第3章　配置受Git约束的AI协同开发工作台

前两章由学生独立完成了项目克隆、基线运行、手工修改、验证和提交。本章开始引入AI协同开发工具，建立VS Code、Cline、校内Qwen服务和Git仓库之间的基本关系。

本章只允许AI读取限定文件、解释工程和形成修改计划，不实施代码修改。只读阶段用于判断AI取得的上下文是否正确，以及它提出的计划能否验证。

确认Git基线
→ 打开完整工作区
→ 连接校内模型
→ 设定文件和命令权限
→ 限定AI读取范围
→ 让AI解释工程
→ 让AI提出计划
→ 人工审查计划
→ 确认仓库未被修改

完成本章后，应当能够：

用VS Code打开正确的仓库根目录；
根据课程环境卡连接Cline与校内Qwen服务；
说明模型对话成功与AI开发智能体可用之间的区别；
控制AI可以读取、修改和执行的范围；
编写包含目标、上下文、约束和验证方法的任务说明；
依据源代码核查AI对工程的解释；
审查AI提出的文件范围和验证计划；
使用Git确认AI没有超出本章权限修改项目。

3.1 从干净的Git状态开始

3.1.1 检查第2章提交

进入课程仓库，执行：

git branch --show-current
git log -1 --oneline
git status --short

应确认：

当前分支为 lab/ch02-event-policy；
当前提交是第2章的冷却时间修改；
工作区和暂存区没有未提交变化。

AI进入项目前必须先固定基线。若AI工作后出现差异，可以与这一提交比较；若一开始工作区就不干净，后续很难区分哪些变化来自学生、编辑器或AI工具。

3.1.2 建立本章分支

从第2章提交建立新分支：

git switch -c lab/ch03-ai-workbench

本章预计不产生源代码提交，但使用独立分支可以保持章节边界，也为意外变化提供清晰的比较起点。

记录当前提交：

git rev-parse HEAD

3.2 使VS Code工作区与仓库边界一致

3.2.1 打开正确范围

在仓库根目录执行：

code .

不要只打开firmware/sound_event_terminal.ino。AI需要从工作区取得README.md、事件规则、模型清单和项目约束。只打开单个文件，会使它缺少目录关系和Git上下文。

在VS Code集成终端中再次执行：

git rev-parse --show-toplevel
git status --short

第一条命令应输出当前课程仓库根目录。若输出另一个路径，说明终端位于错误仓库。

3.2.2 判断是否信任工作区

VS Code打开新目录时可能要求确认工作区信任。确认前应检查：

仓库地址是否来自课程环境卡；
当前标签或提交是否正确；
README.md和许可证是否存在；
项目脚本准备执行哪些程序；
工作区是否包含来源不明的可执行文件。

工作区信任会影响扩展、任务和调试配置是否可以执行。它不是一个应当机械点击的提示，而是一次代码来源判断。

3.2.3 课程扩展与项目设置

课程环境卡给出当学期测试过的扩展版本。基本扩展包括：

Cline；
C/C++或课程嵌入式开发扩展；
Git历史查看工具；
Markdown预览和格式检查工具。

个人主题、字号和快捷键属于用户设置；换行符、格式化规则和构建任务属于项目设置，应由课程仓库统一提供。不要让扩展在第一次打开项目时自动格式化全部源文件。

安装扩展后，再次执行：

git status --short

如果 .vscode/ 或源代码出现变化，应先检查扩展行为，不要继续配置AI。

3.3 连接`Cline`与校内`Qwen`服务

3.3.1 从环境卡取得参数

校内模型服务的实际参数不写入纸质教材。统一资源定位符（Uniform Resource Locator，URL）用于标识服务地址。应用程序编程接口（Application Programming Interface，API）规定调用方式。

学生从当学期环境卡取得以下参数：

参数	作用
接口类型	`Cline`应选择的服务方式
基础地址（`Base URL`）	校内模型服务入口
模型标识（`Model ID`）	当前课程模型标识
接口密钥（`API Key`）	个人访问凭据
最大上下文	单次任务可使用的上下文范围
并发与配额	课堂服务限制

界面字段沿用工具名称，正文分别称为“基础地址”和“接口密钥”。若校内服务提供兼容接口，Cline应采用相应协议。这里的“兼容”只描述请求格式，不表示使用某个特定的外部模型服务。

3.3.2 保护个人凭据

接口密钥只填写在课程规定的凭据位置，不写入：

C/C++源文件；
.env或本地脚本；
Cline任务文本；
项目规则文件；
Git提交；
截图、实验报告和群聊。

如果凭据已经出现在仓库或公开截图中，应立即按课程流程撤销并重新签发。只删除文件不能使已经泄露的凭据重新安全。

3.3.3 先测试对话连接

发送一个不读取项目、不调用工具的最小请求：

请只回答“连接正常”，不要读取文件，不要调用工具。

能够得到回答，只证明以下链路可用：

`Cline`界面
→ 校内模型接口
→ `Qwen`模型
→ 文本响应

它还不能证明Cline具有项目文件权限、命令执行能力或稳定的工具调用能力。AI开发智能体还需要接受后续测试。

早期的编程辅助工具主要根据当前文件补全代码。此后，交互式模型能够依据对话生成较长的程序片段。AI开发智能体又增加了读取文件、调用终端和修改工程的能力，因而可以连续完成多步任务。

能力范围扩大后，错误的影响也从“生成一段不合格代码”扩大为“改变真实工程状态”。因此，模型回答正确不等于智能体配置合格。还要检查它取得了哪些上下文、能够调用哪些工具，以及每项调用能否被Git和验证记录追踪。

3.3.4 记录连接但不记录秘密

实验记录可以保存：

`Cline`版本：
接口类型：
模型标识：
连接时间：
连接结果：

不要记录基础地址中的内部路径、个人接口密钥和完整响应头。课程运维需要的敏感信息由教师单独保存。

3.4 设置最小权限

3.4.1 区分四类能力

AI协同开发工具可能具有四类能力：

能力	主要风险	本章设置
读取文件	读取密钥、个人数据或无关大文件	逐项限定
写入文件	产生超范围修改	不允许
执行命令	安装、删除、联网或改变仓库	不允许
访问外部服务	泄露代码或取得不可靠内容	不允许

本章只使用读取能力。即使工具界面提供“自动批准”，也不启用写文件、终端命令、Git提交和网络访问。

3.4.2 规划模式与实施模式

Cline使用规划模式讨论问题、读取上下文和形成方案，使用实施模式修改文件和执行命令。工具界面可能分别使用Plan和Act。界面名称可以变化，两类责任应保持分离：

规划阶段
→ 理解任务
→ 读取限定文件
→ 找出受影响范围
→ 提出实施和验证步骤

实施阶段
→ 按批准计划修改
→ 运行批准命令
→ 展示结果

本章保持在规划阶段。模式名称不是安全保证，真正的控制仍来自文件权限、命令审批、Git差异和人工验证。

3.4.3 不向AI提供的内容

以下文件默认不进入模型上下文：

secrets.local.h等凭据文件；
个人数据和未脱敏日志；
内部服务配置；
大型模型数组；
大型特征权重数组；
与当前任务无关的数据集；
构建产物。

模型文件很大并不是唯一原因。当前任务只需要理解调用关系，把大量无关内容加入上下文会降低任务边界的清晰度。

3.5 用规则文件保存稳定约束

3.5.1 课程仓库中的规则

课程仓库在根目录提供AGENTS.md，并在.clinerules/中提供Cline适配规则。两者记录稳定的项目约束，例如：

# AI协同开发基本规则

- 先说明目标、受影响文件和验证方法，再申请实施。
- 只读取和修改任务明确列出的文件。
- 不读取或输出密钥、个人数据和内部服务地址。
- 不修改模型数据、生成文件和第三方代码，除非任务明确要求。
- 不自行更改验收阈值、接口契约和依赖版本。
- 删除、安装、联网、提交、推送、合并和发布需要单独批准。
- 修改后展示Git差异，由学生执行构建和实机验证。
- 无法从当前文件确认的事实必须标为“待核查”。

规则应简短、可执行，并与课程实际权限一致。规则写得再严格，也不能代替学生检查。

3.5.2 规则优先级和冲突

执行任务前应确认：

本章任务说明；
课程仓库规则；
当前文件中的接口和注释；
教师给出的环境卡；
AI工具自身的默认行为。

如果这些内容冲突，应暂停任务并请求教师确认。AI不能自行选择一个“看起来合理”的规则继续实施。

3.5.3 用Git检查规则是否改变仓库

打开规则文件后执行：

git status --short
git diff

规则由课程仓库提供，本章只读取，不修改。若编辑器改变了换行或空白，应恢复后再继续。

3.6 第一次让AI读取真实工程

3.6.1 任务说明的四个组成部分

一个适合AI协同的任务说明至少包含：

目标：需要回答什么工程问题；
上下文：允许读取哪些文件；
约束：不得读取、修改和假设什么；
输出：回答应采用什么结构。

本章第一次任务如下：

目标：
解释智能声音识别通知器从声音输入到事件通知的程序路径。

只允许读取：
1. README.md
2. firmware/sound_event_terminal.ino
3. firmware/event_policy.h
4. models/model-manifest.json

不得执行：
- 不读取其他文件；
- 不修改任何文件；
- 不运行命令；
- 不推测未在文件中出现的板卡参数、模型指标和服务配置。

请按以下结构回答：
1. 声音输入从哪个调用进入；
2. 特征和模型推理由哪些对象完成；
3. 模型输出怎样进入事件规则；
4. 阈值和冷却分别控制什么；
5. 哪些事实无法从这四个文件确认。

最后一项要求AI列出无法确认的事实，可以检查它是否区分源码证据和推测。

3.6.2 核查AI的回答

不要只根据语言是否流畅判断。逐项回到源文件：

核查项	证据位置
音频输入调用	主程序实际函数调用
特征处理对象	主程序对象和头文件引用
模型版本与类别	`model-manifest.json`
阈值和冷却	`event_policy.h`
通知接口	主程序调用位置

合格回答应当：

使用文件中的实际名称；
能把调用顺序与职责对应起来；
不把单次输出分数写成模型准确率；
不虚构本次运行结果；
明确指出通知协议细节不在当前四个文件内。

若回答出现错误，不要立即要求AI“再认真一点”。应指出具体证据：

你把trigger_threshold解释为模型准确率。
请重新阅读event_policy.h，并区分单次模型输出、触发阈值和数据集评价指标。
仍然只读取原来的四个文件。

这种修正方式把反馈绑定到项目事实，而不是使用模糊评价。

3.7 让AI为下一项修改提出计划

3.7.1 选择一个小而可验证的任务

第4章将把事件策略修改纳入议题、任务分支和合并请求。本章先让AI为一项小修改提出计划：

当事件被冷却规则阻止时，在串口日志中输出剩余冷却时间，便于区分“模型没有识别”与“事件处于冷却期”。

这个任务具有明确输入、输出和验证方法：

输入：冷却期内再次满足触发条件；
输出：串口显示剩余冷却毫秒数；
不改变：模型、阈值、冷却总时长和通知协议。

3.7.2 提交规划请求

继续保持规划模式：

目标：
为“冷却期内输出剩余冷却时间”制定实施计划。

允许读取：
- firmware/sound_event_terminal.ino
- firmware/event_policy.h

允许在计划中涉及：
- firmware/sound_event_terminal.ino
- firmware/event_policy.h

不得涉及：
- audio_frontend.h
- model_runner.h
- model_data.h
- notification_client.h
- secrets.local.h
- 模型清单和模型类别

约束：
- 不改变trigger_threshold；
- 不改变cooldown_ms；
- 不改变事件是否触发的现有行为；
- 不增加第三方依赖；
- 不在本章实施修改。

计划必须包含：
1. 当前接口怎样传递冷却状态；
2. 需要修改的函数或数据结构；
3. 每一步预期产生的Git差异；
4. 构建验证；
5. 正例、冷却期和冷却结束三种实机验证；
6. 可能影响现有接口的风险。

3.7.3 审查计划

按下面六项审查：

问题是否准确？ 计划解决的是日志可观察性，不是重新设计事件策略。
文件是否越界？ 只能涉及两个批准文件。
现有行为是否保持？ 阈值、冷却时间和通知条件不得改变。
接口变化是否必要？ 如果需要扩大公开接口，应解释理由和调用方影响。
验证是否完整？ 不能只写“编译通过”，必须包含实机时间边界。
计划能否分步检查？ 每一步应产生有限而清楚的差异。

若AI建议顺便重构整个事件模块、添加日志框架或更换依赖，应删除这些内容。当前任务不需要的“改进”会扩大评审和验证成本。

3.8 保存人工审查结论

本章不要求保存完整对话截图。实验记录只保留有助于复查的内容：

# 第3章AI规划审查

## 任务
冷却期内输出剩余冷却时间。

## 允许范围
- 读取：
- 计划修改：
- 禁止修改：

## AI计划摘要
1.
2.
3.

## 人工审查
- 接受：
- 修改：
- 拒绝：

## 验证要求
- 构建：
- 实机：
- Git差异：

## 待确认事项
-

记录重点是人工判断，不是对话长度。接口密钥、内部地址、个人数据和不必要的完整提示上下文不得进入公开仓库。

第4章建立GitLab协作后，这类计划摘要可以进入议题讨论或合并请求说明，由团队共同审查。

3.9 确认AI没有修改项目

本章结束前执行：

git status --short
git diff
git diff --staged

三条命令都应没有输出。再检查当前提交：

git log -1 --oneline

它仍应是第2章提交。模型对话和计划文本不等于项目变化；只有文件进入工作区，Git才会显示差异。

如果出现意外变化：

记录 git status --short；
使用 git diff -- <文件>查看具体内容；
判断变化来自AI、扩展还是人工操作；
保存必要证据；
对确认不需要的未暂存变化使用 git restore <文件>恢复；
检查工具权限设置后再继续。

不要在不查看差异的情况下直接批量恢复。

3.10 常见问题

模型对话正常，但不能读取文件

检查VS Code是否打开仓库根目录。确认工作区是否受信任，Cline是否取得文件读取权限。还要核对任务中的路径。

AI回答了许多文件中不存在的参数

要求它逐项给出文件和代码位置；无法定位的内容标记为待核查。减少上下文不会自动保证正确，仍需要人工查证。

AI要求读取整个仓库

根据当前问题补充最小必要文件。模型数据、凭据和无关模块不应因为“可能有用”而全部加入。

AI在规划阶段提出修改多个模块

重新明确目标和禁止范围。若任务确实需要扩大范围，应由学生和教师先改变任务定义，而不是由AI自行扩大。

`Cline`准备执行命令

拒绝执行，并检查当前模式和自动批准设置。本章只读取和规划。

安装扩展后Git出现大量变化

检查换行符、格式化和 .vscode/设置。先恢复课程基线，再关闭自动格式化或使用仓库规定的配置。

3.11 本章小结

本章建立了第一次受控AI协同，但没有让AI直接修改代码。学生完成了四项基础工作：

从干净Git提交建立AI协同基线；
使用课程环境卡连接Cline和校内Qwen服务；
控制AI的文件、命令和敏感信息边界；
依据源代码审查AI的工程解释和修改计划。

AI协同的起点不是生成代码，而是把任务、上下文、约束和验证写清楚。Git则提供前后状态的客观比较，使学生能够确认工具是否越界。

第4章将把本章计划转化为一个GitLab议题。学生从议题建立任务分支，允许AI按批准计划实施修改。随后通过Git差异、构建、实机验证、合并请求和同伴评审，完成第一次团队协作闭环。

3.12 综合实践

从课程仓库选择一个尚未学习的组件，为它编写只读分析任务。任务限定文件范围，要求AI引用代码位置，并列出无法确认的事项。
设计一张最小权限表，分别规定读取、写入、执行命令和访问网络的条件。每项权限写出一个风险和一个人工确认点。
使用两组不同上下文分析同一工程问题。其中一组缺少关键文件。比较两份回答中的依据、推测和遗漏，形成审查结论。
选择一份AI修改计划，标出“接受”“退回修改”和“缺少证据”3类内容。修订计划，使每项变化都对应文件、约束和验证方法。

第3章 配置受Git约束的AI协同开发工作台