Auto_AICoding_Harness：给 AI Coding 套上一层“工程安全壳”

朋友们，最近新弄了一个 Harness 框架工具，有兴趣的朋友可以star 试试哦~
项目地址：https://github.com/yu20120707/Auto_AICoding_Harness

1. 项目一句话介绍

Auto_AICoding_Harness 是一个面向 AI 编程场景的轻量级 Harness 仓库。它不直接参与业务代码运行，也不是某个 C++ 项目的框架库，而是用一组脚本、模板、规则文档和 profile，把一个普通代码仓库接入到“可规划、可验证、可审核、可接力”的 AI Coding 流程中。

更具体一点说，它解决的是这样一个问题：

AI 直接改代码很快，但如果没有任务边界、状态记录、人工审查、验证证据和交接材料，复杂任务很容易变成不可复盘、不可控、不可继续的黑盒操作。

这个仓库的作用就是给 AI Coding 加一层工程控制面：

用户需求
  ↓
任务分级 small / large
  ↓
生成或读取目标项目中的 AGENTS.md、docs/ai、.ai
  ↓
AI 按文档和状态机执行
  ↓
生成 spec / plan / diff / final review
  ↓
人工 approve / reject
  ↓
记录 context-pack / handoff
  ↓
下一个会话继续接力

所以它本质上不是“让 AI 更聪明”的模型层项目，而是“让 AI 更可控”的工程流程项目。

---

2. 为什么需要这个项目

直接让 AI 修改项目代码，短任务通常问题不大，比如修一个 typo、补一个小函数、改一处局部 bug。但当任务变复杂后，问题会迅速暴露：

1. 上下文会丢失
   AI 知道当前对话里的内容，但下一轮会话可能忘记之前做了什么，为什么这么做，哪些地方不能动。

2. 修改范围容易膨胀
   原本只要改一个函数，AI 可能顺手重构一堆文件，造成不可控 diff。

3. 验证证据不稳定
   AI 很容易说“已验证”“应该没问题”，但实际没有记录构建命令、测试命令、失败项和未验证项。

4. 人工审核缺少固定入口
   人想审代码时，需要知道：改了哪些文件？风险在哪里？是否影响 API/ABI？有没有并发问题？有没有性能影响？是否真的跑了测试？

5. 复杂任务难以接力
   一旦任务跨会话、跨 agent、跨子任务，缺少 handoff 和 context-pack 就会导致后续 agent 重新读一遍仓库，甚至重复犯错。

Auto_AICoding_Harness 的设计目标就是把这些“不稳定的人机协作行为”变成“文件化、状态化、可审计的工程流程”。

---

3. 项目的核心定位

这个仓库可以理解为三层结构：

层级	作用	典型内容
core	控制流程，不关心具体语言	状态机、安全写入、review gate、handoff、context-pack
profile	定义工程策略	C++ / Linux / 后端 / 系统工程检查项
templates	生成目标项目文件	AGENTS.md、docs/ai/*、.ai/*、脚本模板

最重要的边界是：

core 管流程
profile 管工程规范
templates 管生成物
.ai 管任务运行时
docs/ai 管长期项目知识

这个边界非常关键。因为如果把 CMake、ctest、clang-tidy 这类 C++ 项目策略硬编码进 core，那么这个 harness 很快就会变成一个不可复用、难迁移的专用脚本堆。现在的设计是：core 只负责“什么时候进入哪个状态、什么时候需要人工 gate、什么时候允许覆盖文件”，具体工程判断交给 profile。

---

4. 仓库结构拆解

仓库大致可以拆成这些部分：

Auto_AICoding_Harness/
├── bin/                         # 用户直接调用的命令入口
├── core/                        # 命令背后的通用逻辑
├── docs/
│   ├── design/                  # 设计契约、状态机、边界文档
│   ├── usage/                   # 使用说明和生成结构说明
│   └── release/                 # release checklist
├── templates/                   # base 模板源
├── profiles/
│   └── cpp-linux-backend-system # C++/Linux/后端/系统工程 profile
├── prompts/                     # bootstrap/local agent prompt
├── scripts/                     # 脚本说明，不是 CLI 实现
├── skills/                      # 可安装到 Codex/global skills 的技能源
├── examples/                    # small/large 生成结果示例
└── tests/                       # Python 回归测试

这里有几个设计点值得注意。

第一，bin/ 是命令入口，但真正的实现不应塞在命令文件里。命令入口只是解析参数、调用 core、打印结果。

第二，core/ 是这个项目的稳定内核。比如状态读写在 state.py，安全写入在 safe_write.py，模板物化在 template.py，review 生成在 review.py，审批 gate 在 approval.py，上下文打包和 handoff 在 context.py。

第三，templates/ 是目标项目生成文件的唯一事实源。也就是说，目标项目里生成出来的 AGENTS.md、docs/ai/workflow.md、.github/copilot-instructions.md、scripts/ai_check.sh 等文件，不应该在仓库其他地方再维护一份副本，否则会出现“模板 A 说一套，文档 B 说一套”的漂移。

第四，profiles/cpp-linux-backend-system 是当前首发 profile，里面主要约束 C++ 系统工程问题，例如生命周期、并发、网络、Linux 调试、性能、API/ABI、构建和测试。

---

5. small 和 large：不是两个系统，而是两种控制强度

这个项目把任务分为不同控制强度，其中最核心的是 small 和 large。

small 模式

small 是轻量模式，适合低风险、局部、容易回滚、容易验证的任务。

典型命令：

python3 bin/ai-init small

执行后，目标项目会被写入基础 AI 协作结构，例如：

target-repo/
├── AGENTS.md
├── docs/ai/
│   ├── README.md
│   └── workflow.md
├── scripts/
│   ├── ai_build.sh
│   ├── ai_test.sh
│   └── ai_check.sh
└── .ai/
    ├── state.json
    └── templates/

small 模式强调的是：

先建立最小协作协议
再让 AI 在明确边界内工作
最后通过 diff review / final review 收口

它不要求一开始就写完整 spec 和 plan，适合简单修复、局部文档调整、小范围功能补丁。

large 模式

large 是强控制模式，适合复杂任务，比如跨模块改动、架构调整、公共接口变更、构建系统变更、并发/网络/性能相关修改。

典型命令：

python3 bin/ai-upgrade large

large 模式会增加更完整的运行时结构：

.ai/
├── spec.md
├── scope.md
├── implementation-plan.md
├── affected-files.md
├── run-trace.md
├── verification.md
├── evaluation.md
├── context-pack.md
├── handoff.md
├── reviews/
├── approvals/
├── backups/
└── subagent-packets/

large 模式不是换了一套系统，而是在同一个 workflow 上加更强的 gate：

spec gate
  ↓
plan gate
  ↓
diff gate
  ↓
final gate

每个 gate 都可以被人工 approve 或 reject。这样可以避免 AI 一路自动冲到底，把复杂任务做成不可控的黑盒。

---

6. 状态机：把 AI 任务变成可恢复的流程

项目的核心状态文件是：

.ai/state.json

它是目标项目的任务状态源。典型结构类似：

{
  "schema_version": 1,
  "mode": "large",
  "profile": "cpp-linux-backend-system",
  "status": "PLAN_APPROVED",
  "current_gate": null,
  "approved_gates": ["spec", "plan"],
  "created_by": "Auto_AICoding_Harness",
  "task_id": "init-small",
  "task_title": "Initialize harness in small mode",
  "updated_at": "2026-06-08T12:00:00+08:00"
}

这个状态机有几个关键状态：

状态	含义
INIT	已初始化
WAITING_HUMAN_SPEC_APPROVAL	等待人工审核需求规格
SPEC_APPROVED	spec 已批准
WAITING_HUMAN_PLAN_APPROVAL	等待人工审核实现计划
PLAN_APPROVED	plan 已批准
WAITING_HUMAN_DIFF_APPROVAL	等待人工审核 diff
DIFF_APPROVED	diff 已批准
WAITING_HUMAN_FINAL_APPROVAL	等待最终验收
DONE	任务完成
NEEDS_REPLAN	需求或计划被打回
NEEDS_FIX	diff 被打回，需要修复
NEEDS_MORE_TESTS	最终验收缺少验证证据

状态机的价值不是“复杂”，而是把 AI 任务的每个关键转折点固定下来。否则复杂任务跑到一半，下一个会话只看到一堆改动，却不知道当前到底是“计划已批准但还没实现”，还是“实现已完成但还没测试”，还是“diff 已被打回”。

---

7. Review Gate：AI 生成材料，人做最终决策

这个项目的 review 设计很直接：

ai-review 生成审查材料
ai-approve / ai-reject 改变状态

例如 diff 审查：

python3 bin/ai-review diff

这个命令会要求目标仓库必须是 git repo，并且必须存在真实 working-tree diff。然后它会收集：

git status --short
git diff --stat
git diff --name-only
git diff

生成：

.ai/reviews/diff-review.md

这个 review 文档不只是把 diff 贴出来，还会带上检查清单，例如：

Scope Check:
- 只改了预期文件吗？
- 有没有无关格式化？
- 有没有误提交运行时文件？
- 有没有未经批准的 public API 变更？
- 有没有隐藏的大重构？

C++ / System Risk Check:
- ownership/lifetime 安全吗？
- error handling 完整吗？
- 有没有引入 data race？
- API/ABI 兼容性检查了吗？
- timeout/retry 语义有没有变化？
- 测试是否更新？

然后人工可以执行：

python3 bin/ai-approve diff

或：

python3 bin/ai-reject diff

这两个命令才会真正推进状态。

这种设计的重点是：AI 可以生成审查材料，但不能替代人工 gate。

---

8. 安全写入：默认不覆盖，覆盖必须备份

Auto_AICoding_Harness 的文件写入策略很保守：

文件不存在：CREATED
文件已存在且无 --force：SKIPPED
文件已存在且有 --force：OVERWRITTEN，并备份旧文件

备份路径一般在：

.ai/backups/<timestamp>/

这个策略解决了一个很现实的问题：AI 工具经常会“初始化一下”就把已有配置覆盖掉。对于真实项目来说，这非常危险，因为 AGENTS.md、.github/copilot-instructions.md、docs/ai/* 可能已经被团队手动维护过。

所以这个项目默认不覆盖已有文件。你必须显式传入：

python3 bin/ai-init small --force

或：

python3 bin/ai-upgrade large --force

才会覆盖，并且覆盖前会备份。
这就是工程里常见的“默认安全，显式破坏性操作”的设计。

另外，safe_write.py 还禁止写入一些业务源目录，例如 src、include、tests。这说明 harness 命令默认只应该管理 AI 协作文件，而不是直接修改业务代码。

---

9. context-pack 和 handoff：解决长任务接力问题

AI Coding 最大的问题之一是长上下文污染。一个任务跑久了以后，对话里会混入大量历史讨论、失败尝试、过期假设和无关信息。继续在原上下文里做，容易导致判断质量下降。

这个项目用两个文件解决接力问题：

.ai/context-pack.md
.ai/handoff.md

context-pack

context-pack 是紧凑上下文包，适合“下一轮继续干”。它会总结：

当前 mode
当前 profile
当前 status
当前 gate
已批准 gate
关键文件是否存在
git status
diff stat
changed files
最近 review
最近 approval
spec / plan / affected-files 摘要
verification 摘要
下一步建议

命令：

python3 bin/ai-context-pack

这个命令只生成上下文材料，不推进状态。

handoff

handoff 更偏交接文档，适合“换一个 agent 或换一个干净会话继续”。它会记录：

当前状态
已经完成了什么
修改过哪些文件
验证和 review 证据在哪里
当前 blocker / gate
下一步动作
禁止做什么

命令：

python3 bin/ai-handoff

它也不推进状态。

这两个命令的意义是：把会话记忆从聊天窗口里抽出来，落到项目文件里。

---

10. C++ / Linux / 后端 / 系统工程 profile

当前默认 profile 是：

cpp-linux-backend-system

这个 profile 对目标项目生成一组 docs/ai/* 长期工程知识文档，例如：

docs/ai/cpp-system.md
docs/ai/linux-debug.md
docs/ai/network.md
docs/ai/concurrency.md
docs/ai/api-abi.md
docs/ai/performance.md
docs/ai/observability.md
docs/ai/cmake.md
docs/ai/build.md
docs/ai/testing.md
docs/ai/verification-matrix.md

这套 profile 的设计明显偏系统工程，而不是普通 CRUD 后端。它关注的问题包括：

方向	关注点
C++ 对象模型	ownership、lifetime、RAII、异常安全
并发	lock scope、data race、atomic、线程生命周期
网络	socket、epoll、timeout、retry、backpressure
Linux 调试	process、signal、fd、strace、core dump、perf
API/ABI	public header、协议兼容、二进制兼容
性能	profile 证据、热点路径、benchmark
可观测性	log、metric、diagnostic、failure evidence
构建测试	CMake、compile_commands、unit/integration/regression

这对 C++ 后端/基础架构项目很重要。因为这类项目的风险通常不在“代码能不能编译”，而在：

生命周期是否安全
并发路径是否竞态
网络异常是否覆盖
超时重试是否改变语义
ABI 是否破坏
性能是否退化
日志指标是否足够排障

把这些检查项写进 profile，本质上是在给 AI 添加“工程审查视角”。

---

11. subagent：目前是协议，不是自动执行框架

项目里有 large-mode subagent role templates，例如：

.codex/agents/planner.md
.codex/agents/explorer.md
.codex/agents/implementer.md
.codex/agents/reviewer.md
.codex/agents/evaluator.md

还有：

.ai/subagent-packets/

角色大致分工是：

角色	职责
planner	规划范围、步骤、gate 和验证策略
explorer	只读扫描代码和证据，不编辑
implementer	按 scope 做实现
reviewer	审 diff、契约、回归风险
evaluator	验证命令、证据和残余风险

但这里有一个重要边界：
subagent 不是 correctness dependency，也不是自动调度系统。

换句话说，项目提供的是 role template 和 dispatch record，不是一个真正的多 agent runtime。
如果当前 AI 编程工具支持 subagent，可以把 packet 作为上下文交给子 agent。
如果不支持，主 agent 就按同样的角色契约顺序执行。

这其实是一个比较稳的设计。因为不同 AI Coding 工具对 subagent 的支持差异很大。如果项目强依赖某个平台的自动 subagent 调度，迁移成本会非常高。而现在的做法是把 subagent 抽象成“可选加速层”。

---

12. skills：可安装，但不能成为正确性依赖

仓库还提供 skills 体系，用来沉淀可复用方法论。例如：

methodology/design-before-code
methodology/systematic-debugging
methodology/verification-before-completion
methodology/human-in-loop-development
system/cpp-system-dev
system/linux-debug
system/network-programming
system/concurrency-review
system/performance-analysis
system/cpp-api-abi-review

ai-install-skills 可以把这些 skills 安装到 Codex 的全局 skills 目录：

python3 bin/ai-install-skills --dry-run
python3 bin/ai-install-skills
python3 bin/ai-install-skills --force

它的默认目标大致是：

$CODEX_HOME/skills
或
~/.codex/skills

设计上也保留了安全策略：

dry-run 只预览，不写入
默认存在则跳过
--force 才覆盖
覆盖前备份

不过 skills 仍然不是正确性依赖。没有 skills 时，AI 应该直接读 AGENTS.md 和 docs/ai/*。skills 的角色是提升执行质量，而不是让流程成立的必要条件。

---

13. 典型使用流程

一个完整 large-mode 任务可以这样走：

# 1. 查看状态
python3 bin/ai-status

# 2. 初始化目标项目
python3 bin/ai-init small

# 3. 升级到 large 模式
python3 bin/ai-upgrade large

# 4. 填写或修改 .ai/spec.md
python3 bin/ai-review spec
python3 bin/ai-approve spec

# 5. 填写或修改 .ai/implementation-plan.md
python3 bin/ai-review plan
python3 bin/ai-approve plan

# 6. 实际修改业务代码
# ...

# 7. 生成 diff review
python3 bin/ai-review diff
python3 bin/ai-approve diff

# 8. 生成上下文包和交接文档
python3 bin/ai-context-pack
python3 bin/ai-handoff

# 9. 最终验收
python3 bin/ai-review final
python3 bin/ai-approve final

# 10. 查看最终状态
python3 bin/ai-status

最后目标状态应该进入：

DONE

并且 .ai/state.json 中应该能看到：

"approved_gates": ["spec", "plan", "diff", "final"]

这就把一次 AI Coding 任务从“聊天式执行”变成了“有状态、有证据、有审查、有交接”的工程流程。

---

14. 这个项目的工程亮点

亮点一：边界清晰

它没有把所有东西混成一个大 prompt，而是明确区分：

全局行为
项目行为
项目事实
任务运行时
复用方法
平台适配

对应文件路径是：

global/AGENTS.md.template     # 全局行为基线
AGENTS.md                     # 项目入口规则
docs/ai/*                     # 项目长期知识
.ai/*                         # 当前任务运行态
skills/*                      # 可复用技能
prompts/*                     # 一次性 setup prompt

这种分层能显著降低上下文污染。

亮点二：状态机足够小

状态机没有做成复杂工作流引擎，而是只控制关键 gate：

spec
plan
diff
final

状态数量不多，但覆盖了复杂任务最关键的风险点。
这符合工程工具设计原则：流程控制应该足够强，但不能重到没人愿意用。

亮点三：默认安全写入

默认 SKIPPED，显式 --force 才覆盖，而且覆盖前备份。
这对真实项目很重要，尤其是 .github、AGENTS.md、docs/ai 这类容易被人手动维护的文件。

亮点四：适合 C++ 系统方向

默认 profile 不是泛泛的“代码质量检查”，而是围绕 C++ / Linux / 后端 / 系统工程展开。
这让它比普通 AI Coding prompt 更接近真实基础架构开发场景。

亮点五：可接力

context-pack 和 handoff 解决的是长任务续跑问题。
这点在 AI Coding 里非常关键，因为真实复杂任务经常不是一轮对话能做完的。

---

15. 当前不足和风险

这个项目当前也有明显不足。

1. 文档和实现有漂移风险

部分文档中提到的命令面、版本 baseline、release phase 并不完全一致。
例如 README 中强调 phase10，而 release/checklist 和部分测试又出现更靠后的能力描述。
这说明项目处于快速演进阶段，需要一个更严格的能力清单生成机制。

建议后续把命令清单变成机器生成，例如：

bin/* 自动扫描
↓
生成 docs/design/current-capabilities.md
↓
测试校验 README 是否同步

2. 目前还不是完整 AI Agent Runtime

它不负责真正调用模型，也不负责执行 subagent。
它更像是 workflow harness，而不是 agent framework。
这不是缺点，但对外介绍时要讲清楚，否则别人可能误以为它是类似 Devin/Codex CLI 的自动编程执行器。

3. scripts 还是 placeholder

ai_build.sh、ai_test.sh、ai_check.sh 当前是安全占位模板，需要目标项目自己替换。
这意味着它能建立流程，但不能自动理解每个项目的真实构建链路。

4. profile 目前单一

当前默认 profile 是 cpp-linux-backend-system。
如果要扩展到 Java 后端、前端、数据工程、嵌入式、Android、Rust 系统开发，就需要新增 profile overlay。

5. .ai 的 git 策略需要更细

.ai/state.json、reviews、approvals、backups 大多属于运行时，不一定应该提交。
但 .ai/templates、.ai/.gitkeep 又可能需要保留。
对真实团队使用来说，最好生成一份更精细的 .gitignore 建议。

---

16. 可以怎么继续升级

如果继续迭代，我认为优先级可以这样排：

P0：统一版本和命令面

把 README、current-capabilities、release checklist、tests 中的命令面彻底对齐。
当前最重要的是避免使用者看到不同文档得出不同结论。

P1：补一个 ai doctor

增加：

python3 bin/ai-doctor

检查目标项目是否满足 harness 运行条件：

是否 git repo
是否存在 .ai/state.json
AGENTS.md 是否存在
docs/ai 是否存在
scripts/ai_check.sh 是否已替换 placeholder
当前 state 是否和文件结构一致
是否存在未批准 gate
是否存在 stale review

P2：让 verification 更结构化

当前 .ai/verification.md 是 markdown 证据。可以进一步增加：

.ai/verification.json

让机器能可靠读取：

{
  "commands": [
    {
      "cmd": "cmake --build build",
      "exit_code": 0,
      "duration_ms": 12345,
      "log": ".ai/logs/build.log"
    }
  ],
  "not_run": [
    {
      "item": "benchmark",
      "reason": "no benchmark target"
    }
  ]
}

这样 final gate 就能更严格地判断“是否真的验证过”。

P3：增加 profile marketplace 但不急

可以新增：

profiles/java-backend
profiles/rust-system
profiles/android-aosp
profiles/python-agent

但不建议太早做成 marketplace。
当前项目的最大价值是自用稳定流程，而不是泛化成大而全平台。

P4：接入真实项目 examples

examples 目前更像生成结构样例。后续可以提供几个真实任务样例：

example-task-fix-build/
example-task-refactor-api/
example-task-performance-regression/
example-task-network-timeout-bug/

每个样例包含：

spec
plan
diff-review
approval
verification
handoff

这比单纯文档更能说明 harness 的价值。

---

17. 总结

Auto_AICoding_Harness 的核心价值不是“自动写代码”，而是“把 AI 写代码这件事变成可控工程流程”。

它用很轻的 Python 命令和 markdown 模板，建立了几条关键约束：

任务要分级
上下文要落盘
长期知识和运行态要分离
复杂任务要有 spec / plan / diff / final gate
人工审批不能被 AI 绕过
验证必须有证据
handoff 必须可接力
覆盖文件必须显式且可回滚

如果用一句工程化的话概括：

这个项目不是 AI Coding 的发动机，而是 AI Coding 的刹车、仪表盘、行车记录仪和交接单。