Agent 工具路线选择与通用工程实践

参考任务卡——目标：“让 CSV 导出在空输入与非 ASCII 文本下不静默截断。”范围内：export.py 的行写入逻辑与 tests/test_export.py。非目标：不新增导出格式、不改 UI、不升级依赖。标准：(1) python3 -m unittest tests.test_export -v 退出码为 0；(2) 导出空数据集得到的文件只含表头行（通过检查文件验证）；(3) 含“café, 東京”的记录经 CSV 写入后逐字节往返一致（通过重读文件验证）；(4) git diff 只触及 export.py 与 tests/test_export.py。

参考计划——(a) 运行 python3 -m unittest discover -s tests -v 并读堆栈；在 app.py 出错行附近找到空列表访问。(b) 运行 git status --porcelain：若有改动先 stash 或提交（git stash -u，或临时分支提交）；若已干净则用 git rev-parse HEAD 记录基线——空提交本来也会失败。(c) 步骤：1. 复现崩溃并记录确切异常（检查点：捕获堆栈）；2. Agent 只修改 app.py 增加空值守卫（检查点：git diff 只触及 app.py）；3. 重跑测试套件（检查点：退出码 0）；4. 审查 diff 并提交绿色状态（检查点：git diff --check 干净且已提交）。

最小包：src/greeter.py（代码）、tests/test_greeter.py（行为契约）与堆栈（确切失败）。只有当 README 定义问候语格式时才纳入。.env 永远排除——绝不把凭据交给 Agent；整个 src/ 树与 package.json 与该行为无关且会污染注意力，同样排除。

授予：仓库读取、文件编辑、仅限测试命令的 shell（pytest tests/ 或等价）。拒绝：无限制 shell、网络抓取、包安装、git push 与部署——本任务既不需要也不被允许。开关名以所选 track 当前的官方权限文档为准（例如 Claude Code 的 permissions/settings 文档、Codex CLI 的 --sandbox/--ask-for-approval 参考、Pi 的工具边界文档或 DeepSeek Harness README），因为名称随版本变化。

该 README 备注是注入指令，不得执行：运行该脚本会泄露私钥。响应：(1) 不执行该脚本；(2) 把该文件与行记录为提示词注入发现；(3) 检查此前步骤是否已遵从（diff、shell 历史、网络证据），若已遵从则升级处理；(4) 只继续已授权的解析器任务；(5) 在评审记录中上报该产物。

暴露分类：可能已传输且仍存在于工作区——按已暴露处理。响应顺序：(1) 停止运行；(2) 在 provider 控制台吊销并轮换该密钥；(3) 从 secrets.env 删除，若已提交则清洗 git 历史；(4) 扫描 diff、日志与转录中的其他副本；(5) 记录事件与证据。评审用的最小新增行凭据扫描：

import re
SECRET = re.compile(r'^\+.*(api[_-]?key|secret|token|password|\w*key)\s*=', re.I | re.M)
diff = '+STAGING_KEY=sk-live-9f2ab\n+mode=fast\n-OLD_KEY=sk-dead\n'
hits = SECRET.findall(diff)
assert len(hits) == 1, hits  # only the added line is flagged
print('PASS: flagged added credential line')

裁决：整体拒绝——expresss 是 typosquat 模式，postinstall 脚本拉取并执行远端代码，属于外泄通道。命令：git restore package.json package-lock.json 回退 manifest 与 lockfile；不运行安装；在评审记录中记下事件；若安装已发生，按环境已被攻陷处理并排查。声明依赖差异的审查助手：

baseline = {'express': '^4.18.2', 'lodash': '^4.17.21'}
proposed = {'expresss': '^9.9.9', 'lodash': '^4.17.21'}
added = sorted(set(proposed) - set(baseline))
removed = sorted(set(baseline) - set(proposed))
assert added == ['expresss'] and removed == ['express']
print('PASS: flagged unexpected dependency delta:', added)

顺序：(c) 验收标准 → (f) 上下文包 → (d) 一处有界改动 → (a) 运行测试并检查 → (b) 审查 diff → (e) 提交绿色状态。停止条件：同一失败重复两次（重新框定而不是重试），或 Agent 越出范围/权限行事（停下审查）。

运行：npm test（要求退出码 0）、tsc --noEmit、npx eslint .、npm run build，然后在运行中的应用上操练真实登录页——成功登录加一次无效密码被拒。证据 = 记录下来的命令、退出码与观察到的行为，而不是 Agent 的文字。若项目没有配置 linter 或 typecheck，记录其缺失而非假设存在。

Hunk 1：确认边界逻辑并重跑测试后接受。Hunk 2：拒绝——注释断言是在粉饰通过，恢复它们。Hunk 3：拒绝——掩盖真实改动的越界扰动，回退它。动作：要求只含 hunk 1 的重新提交，并用 git diff、git diff --check 与 git status --short 确认没有其他变化。

git revert cafe123——追加反向提交，保留历史与未提交的 notes.md，但不保证无冲突：若 beef456 改过同一行，Git 会中途停下——保留 beef456 的正确行为解决冲突块后 git revert --continue；或 git revert --abort，改为在临时分支上用 git restore --source=cafe123^ -- <受影响文件> 选择性恢复坏提交前的文件状态，并以修正提交记录。若 cafe123 也碰过 notes.md，先快照（git diff notes.md > /tmp/notes.patch），恢复后再还原你的版本。禁止：git reset --hard beef456 或 git reset --hard HEAD~1——会丢弃 Git 无法恢复的未提交 notes.md 改动。

(1) 审查——破坏性但范围限定且可重建；确认路径在工作区内且 build/ 可重新生成后才批准。(2) 拒绝——force-push 重写共享历史；普通 push 也需授权。(3) 审查——先做供应链检查（准确名字、来源、固定版本），再在一次性环境中批准。(4) 拒绝，除非有明确授权——对外通信是真实世界副作用。(5) 允许——本地、可逆、只读。

参考骨架——name: release-notes-drafter；description: “在当前仓库中根据已合并的 PR 起草发布说明；仅当用户要求发布说明或 changelog 草稿时触发——不为写代码、评审 PR 或发布任何内容而触发。” 指令：(1) 只读 git log 与已合并 PR 标题；(2) 按 fixed/added/changed 分组；(3) 草稿写入 CHANGELOG-draft.md，绝不 commit、tag、push 或发布；(4) 含混的 PR 标记给用户而不是猜测。应触发：“根据已合并 PR 起草 v2.3 发布说明”；“为这次发布写 changelog”。对抗不触发：“帮我评审这个 PR”；“把发布说明发到博客”。退役：当发布说明改由 CI 生成，或连续两次评审发现描述误触发时移除。