第14章 综合实践：人机协同开发智能信号卡系统

本章导读

第13章中，我们已经把第3章建立的 VS Code + 本地智能体学习环境用于一个物理世界任务：让智能体检查摄像头、生成摄像头访问程序、构建规则模型，并完成三色卡反馈。这个过程说明，AI 不只是聊天框里的文字工具，它可以在人的监督下参与程序开发，帮助我们把现实设备接入学习任务。

第14章是一次综合收束。它不再单独讲一个新概念，而是把前面学过的能力组装起来，完成一个低风险、可演示、可测试、可复核的物理 AI 最小作品。

本章项目是：智能信号卡系统。

它的基本任务是：摄像头捕捉画面，系统判断画面中是否出现红色、黄色、绿色或蓝色信号卡，并给出相应反馈；同时保存日志，记录输入、判断结果、反馈内容、异常情况和人工复核意见。

红色卡片：STOP / 需要关注，请暂停。
黄色卡片：CHECK / 不确定，请人工确认。
绿色卡片：PASS / 状态正常，可以继续。
蓝色卡片：HELP / 请求协助。
无卡片、暗光、摄像头异常：进入 fallback 路径。

这个项目看似简单，但它具备一个完整物理 AI 系统的雏形：摄像头或样例图片提供现实输入，程序完成质量检查和颜色证据提取，规则模型输出候选状态，决策规则把候选状态转换为可控反馈，日志记录过程，人工复核确认是否可信。

因此，第14章真正训练的不是“再识别一次颜色”，而是把一个低风险物理 AI 原型整理成可演示、可测试、可回归、可追溯、可说明边界的综合作品。

本章的重点不是把程序做得多炫，而是训练一种工程能力：把 AI 智能体当作协作开发伙伴，让它帮助你生成、修改、解释和调试程序；你负责需求拆解、边界设定、测试验收和风险控制。

《礼记·学记》说：独学而无友，则孤陋而寡闻。 一个 AI 小作品不是做完就结束。让别人看得懂、跑得起、能复核、能提出改进意见，作品才真正进入协作。

学习目标

• 知识目标：
  1. 能说明物理 AI 最小作品的系统结构：感知层、处理层、推理层、决策层、反馈层、日志层与人工复核层。
  2. 能解释 AI 协同开发中人、智能体、程序、设备四者的职责边界。
  3. 能理解最小可运行原型、需求变更、回归测试、失败样例和 fallback 在物理 AI 工程中的作用。
  4. 能说明为什么物理 AI 作品不能直接把模型输出当作现实动作，而必须经过规则、校验和人工确认。
• 能力目标：
  1. 能在 VS Code 插件中分阶段指挥智能体生成和修改一个物理 AI 小作品。
  2. 能完成从 v1 摄像头自检，到 v2 颜色识别，再到 v3 需求变更和日志记录的迭代过程。
  3. 能构建最小测试集，对红、黄、绿、蓝、无卡、暗光、摄像头异常等情况进行测试。
  4. 能根据测试结果向智能体提出有边界的修改需求，并完成一次回归测试。
  5. 能形成一份作品证据包，包含需求说明、提示词记录、运行日志、测试结果、失败样例和安全边界。
• 素养目标：
  1. 建立 AI 加速开发，但不能替代工程验收的职业意识。
  2. 形成低风险优先、默认安全、可停止、可追溯、人工确认的人机协同习惯。
  3. 理解智能终端、具身智能和物理 AI 的入门逻辑：先做稳定小闭环，再逐步提高复杂度。
  4. 能客观说明作品能力边界，不夸大模型能力，不把课程原型包装成可直接商用系统。

先修要求与环境清单

• 已完成第3章 VS Code + 本地智能体学习环境。
• 已完成第6章提示词结构、第9章视觉理解、第10章工具调用、第11章智能体流程、第12章专业工作流、第13章摄像头识别工程。
• 软件环境：VS Code、VS Code 中的 AI 协同插件、课程统一配置的本地智能体或本地大模型服务、课程预置 Python 环境。
• 硬件与材料：

相关内容见表14-1。

表14-1 设备或材料与必需程度记录表

建议项目目录：

ch14_signal_card_engineering/
├── app/
│   ├── device_probe.py
│   ├── signal_card_v1.py
│   ├── signal_card_v2.py
│   └── signal_card_v3.py
├── samples/
│   ├── red_card.png
│   ├── yellow_card.png
│   ├── green_card.png
│   ├── blue_card.png
│   └── dark_scene.png
├── logs/
│   ├── run_log.md
│   └── change_log.md
├── tests/
│   └── test_matrix.md
├── evidence/
│   └── evidence_pack.md
└── README.md

所有文件必须放在该目录中，不访问工作区外文件。

知识准备：先认识这些词

1. 最小可运行原型（minimum runnable prototype）
   • 一句话说明：功能很小，但能完整跑通输入、处理、输出、记录和复核。
   • 本章要求：不要追求万能识别，先让信号卡系统稳定跑通。
2. 物理 AI 作品
   • 一句话说明：AI 通过摄像头、传感器、屏幕、声音或灯光与现实世界发生关系的作品。
   • 本章边界：只做低风险反馈，不做危险控制。
3. AI 协同开发
   • 一句话说明：人提出目标、边界和验收标准，智能体协助生成方案、程序、测试和说明。
   • 关键原则：智能体负责加速，人负责判断。
4. 版本迭代
   • 一句话说明：把作品分成 v1、v2、v3 逐步完成，每一版都有明确目标和测试。
   • 本章版本：v1 设备探测，v2 三色识别，v3 蓝色求助和 fallback。
5. 需求变更
   • 一句话说明：在原有功能基础上提出新的功能或规则。
   • 本章例子：新增蓝色 HELP；暗光时进入 fallback；日志要记录异常原因。
6. 回归测试
   • 一句话说明：修改新功能后，重新测试旧功能是否被破坏。
   • 本章要求：加入蓝色以后，红、黄、绿仍要重新测试。
7. fallback 路径
   • 一句话说明：系统遇到异常时的备用处理方式。
   • 本章例子：摄像头打不开时使用样例图片；暗光时提示调整光线；无卡时输出 UNKNOWN。
8. 作品证据包
   • 一句话说明：证明作品怎样设计、怎样运行、怎样测试、怎样复核的一组材料。
   • 拓展要求：证据包必须能让别人复现你的作品过程。

14.1 问题与现象：从能跑到像一个作品

14.1.1 为什么第14章不能只是再跑一遍摄像头

第13章已经完成了摄像头识别工程的入门任务。如果第14章只是再识别一次颜色，就没有综合收束的意义。

本章要提高一个层次：从程序能运行走向作品能交付。

作品至少要回答这些问题：

• 它解决什么问题？
• 它的输入是什么？
• 它怎样判断？
• 它怎样反馈？
• 它如何记录？
• 它遇到异常怎么办？
• 它测试过哪些情况？
• 它不能做什么？

这些问题答清楚，才算一个小作品。

14.1.2 为什么选择信号卡系统

信号卡系统适合作为最终综合实践，因为它同时满足三个条件：

相关内容见表14-2。

表14-2 条件与说明记录表

它不是为了替代场景管理，也不是判断人的表现，而是训练你用工程方法做一个最小物理 AI 作品。课程原型的价值在于证据完整、边界清楚，而不是功能看起来炫。

14.1.3 本章要建立的工程意识

本章要训练四种工程意识：

1. 分阶段：不要一次让智能体写完整项目。
2. 有边界：告诉智能体什么不能做。
3. 可测试：每一版都有测试样例。
4. 可追溯：每次修改、运行、失败都有记录。

【思考 1】 为什么程序能识别绿色卡还不能说明作品已经完成？

思考提示：作品还需要测试其他颜色、异常情况、日志、人工复核和安全边界。单个成功样例不能代表作品可靠。

14.2 原理与分析：作品化的七层结构

相关结构如图14-1所示。

14.2.1 七层证据结构

七层结构不是为了把图画得复杂，而是为了让每一层都有证据可查。出错时，才能判断问题来自输入、处理、判断、反馈，还是来自测试和复核不足。

相关内容见表14-3。

表14-3 层次与必须留下的证据记录表

七层结构的价值在于：每一层都能被验收，每一层出错都能被定位。

14.2.2 人、智能体、程序、设备四者分工

相关内容见表14-4。

表14-4 角色与负责什么记录表

如果分工不清，就容易出现“仅依据 AI 输出就提交作品”的问题。

14.2.3 分版本开发

本章采用四个版本推进：

相关内容见表14-5。

表14-5 版本与目标记录表

分版本不是为了麻烦，而是为了让问题变小、可检查。

14.2.4 测试矩阵

最终作品必须包含最小测试矩阵：

相关内容见表14-6。

表14-6 编号与输入记录表

测试矩阵是作品可信度的核心证据。完成测试矩阵后，还要把演示流程串成可以复核的闭环，相关结构如图14-2所示。

14.2.5 为什么不能把模型输出直接当动作

模型输出可能错。即使规则模型也可能受光线、背景、距离影响；如果加入轻量视觉模型，也仍然可能受到训练数据、画面质量和提示方式影响。

所以本章所有反馈都必须经过决策层。决策层要回答三个问题：

• 画面质量是否合格？
• 颜色证据是否足够明确？
• 这个反馈是否需要人工确认？

例如，模型输出“可能是红色”并不等于系统一定输出 STOP。若画面暗、颜色区域小或背景干扰明显，就应降级为 CHECK、UNKNOWN 或 FALLBACK。

这就是物理 AI 比普通聊天更需要工程护栏的原因。

AI 协同实践：分阶段开发智能信号卡系统

第 1 步：让智能体生成 v0 方案

在 VS Code 插件中输入：

请帮我完成第14章智能信号卡系统。
注意：第13章已经完成摄像头识别工程基础，本章重点是形成可演示、可测试、可回归、可追溯、可说明边界的综合作品。

总目标：
1. 使用摄像头或样例图片识别红、黄、绿、蓝四种信号卡；
2. 输出 STOP / CHECK / PASS / HELP / UNKNOWN；
3. 暗光或摄像头异常时进入 fallback；
4. 保存运行日志和变更日志；
5. 生成作品证据包；
6. 不拍摄人脸，不上传图片，不控制外部设备；
7. 程序不主动保存摄像头画面，只保存运行日志、变更日志和人工复核记录。

请先不要创建文件。
请先列出项目目录、文件作用、版本计划、测试矩阵、安全风险和验收标准，等待我确认。

确认智能体计划时，检查它是否包含 v0、v1、v2、v3 的阶段划分。

第 2 步：完成 v1 摄像头与样例图片输入

确认后输入：

我确认 v0 方案。
请先实现 v1：摄像头或样例图片输入。
要求：
1. 先探测摄像头；
2. 摄像头可用时读取摄像头画面；
3. 摄像头不可用时读取 samples 中的样例图片；
4. 测试前确认画面不含人脸，程序不主动保存摄像头画面；
5. 运行结果写入 logs/run_log.md；
6. 完成后不要继续做颜色识别，先等待我验收 v1。

v1 验收表：

相关内容见表14-7。

表14-7 项目与是否通过记录表

第 3 步：完成 v2 三色识别

v1 通过后输入：

v1 已验收。
请实现 v2：红、黄、绿三色识别。
要求：
1. 绿色输出 PASS / 状态正常；
2. 黄色输出 CHECK / 请人工确认；
3. 红色输出 STOP / 需要关注；
4. 无明显颜色输出 UNKNOWN；
5. 更新 tests/test_matrix.md；
6. 运行 T1、T2、T3、T5 测试；
7. 把结果写入 run_log.md。

v2 测试表：

相关内容见表14-8。

表14-8 编号与输入记录表

第 4 步：提出 v3 需求变更

现在提出需求变更：

现在提出 v3 需求变更：
1. 新增蓝色卡；
2. 蓝色输出 HELP / 请求协助；
3. 加入暗光检测，暗光时输出 FALLBACK / 请调整光线；
4. 原有红、黄、绿、UNKNOWN 功能不能被破坏；
5. 请先说明要修改哪些文件和测试用例，等待我确认。

确认后再让智能体执行修改。

第 5 步：执行 v3 并做回归测试

我确认 v3 修改计划。
请执行修改，并完成完整回归测试：
T1 绿色 → PASS
T2 黄色 → CHECK
T3 红色 → STOP
T4 蓝色 → HELP
T5 无卡片 → UNKNOWN
T6 暗光 → FALLBACK
T7 摄像头不可用 → SAMPLE_MODE
请生成 logs/change_log.md，并更新 evidence/evidence_pack.md。

如果智能体只测试蓝色，而没有重新测试红、黄、绿，应要求它补做回归测试。

第 6 步：生成作品证据包

请根据项目文件、运行日志和测试结果，生成 evidence/evidence_pack.md。

证据包必须包含：
1. 作品目标；
2. 系统七层结构；
3. 人、智能体、程序、设备四者分工；
4. v1/v2/v3 版本变化；
5. 测试矩阵和测试结果；
6. 失败样例或 fallback 记录；
7. 安全边界；
8. 仍需改进的问题。

第 7 步：准备展示与答辩

让智能体生成展示草稿：

请帮我生成一份 5 分钟作品展示说明。
要求：
1. 不夸大作品能力；
2. 说明本作品只是课程原型；
3. 展示 v1/v2/v3 的迭代过程；
4. 说明我如何验收智能体生成的程序；
5. 说明失败样例和安全边界；
6. 最后提出下一步改进方向。

展示稿必须由你修改，并加入真实测试结果。

验证与证据：怎样证明作品可靠

作品证据包

相关内容见表14-9。

表14-9 材料与必须包含记录表

作品验收建议

相关内容见表14-10。

表14-10 维度与权重记录表

不合格情况

出现以下情况之一，应要求重做或补证据：

• 没有日志；
• 没有测试失败样例；
• 只展示成功，不说明限制；
• 智能体创建文件路径不清楚；
• 摄像头拍到隐私画面；
• 需求变更后没有回归测试；
• 声称作品可以直接用于真实管理场景。

伦理、安全与边界

摄像头数据属于敏感数据

摄像头会采集现实环境。即使本章只识别色卡，也必须默认谨慎：

• 不拍摄人脸；
• 不保存他人画面；
• 不上传未经允许的图片；
• 不使用真实监控画面；
• 不把测试图片用于其他用途。

低风险反馈优先

本章只做屏幕文字、颜色块、可选蜂鸣器或低压 LED 提示。

禁止接入：

• 门锁；
• 高压电器；
• 大功率电机；
• 车辆；
• 机械臂；
• 真实生产设备。

模型判断不能直接成为现实动作

即使识别结果看起来正确，也必须经过决策规则和人工确认。特别是红色、求助、异常等状态，不能让系统自动做高风险动作。

AI 协同开发必须留痕

作品中必须保留：

• 关键提示词；
• 智能体修改建议；
• 人工确认记录；
• 测试结果；
• 失败案例；
• 安全说明。

没有留痕，就无法证明你真正参与了设计和验收。

总结与思考

本章核心判断

1. 第14章的目标不是再学一个工具，而是完成一个可演示、可测试、可复核的物理 AI 最小作品。
2. 智能体可以协助开发，但人必须负责需求、边界、验收和安全。
3. 分版本开发能降低复杂度，让问题可定位、可修复。
4. 需求变更必须配合回归测试。
5. 能说明失败边界的作品，比只展示成功的作品更可信。

基础题

1. v1、v2、v3 分别解决什么问题？
2. 什么是 fallback？本章有哪些 fallback 场景？
3. 为什么作品证据包比单个运行截图更重要？

迁移题

请选择一个专业场景，将智能信号卡系统迁移为一个低风险提示作品：

• 汽修实训：设备状态信号卡；
• 烹饪实训：后厨流程提示卡；
• 电商仓储：分拣状态提示卡；
• 护理实训：耗材整理提示卡；
• 机电实训：巡检状态提示卡。

请说明输入、判断、反馈、日志和人工复核点。

风险题

如果有人建议把本章作品改成自动判断学习者是否需要帮助，你会如何修改这个需求，使它保持低风险、可复核、尊重隐私？

补充题

请判断下列说法是否正确，并说明理由：

1. 智能体生成的项目能运行，就可以直接展示为成熟产品。
2. 需求变更后，只测试新增功能即可。
3. 物理 AI 小作品必须说明不能做什么。

本章交付物

完成本章后，你应提交以下材料：

1. 项目目录结构说明 1 份；
2. v0/v1/v2/v3 关键提示词记录 1 份；
3. 运行日志 run_log.md；
4. 变更日志 change_log.md；
5. 测试矩阵 test_matrix.md；
6. 作品证据包 evidence_pack.md；
7. 5 分钟展示说明 1 份；
8. 安全边界说明 1 份。