Ancienttwo/repo-harness

解决的问题

repo-harness 解决了 AI 编码会话依赖于易失性聊天记忆的问题。当开发人员在不同的 AI 代理（如 Claude 和 Codex）之间切换或开始新会话时，之前的计划、进度和决策的上下文往往会丢失，迫使代理花费 Token 和时间重新发现仓库结构和当前状态。

工作原理

该项目实现了一种基于文件的流水线，其中项目的状态“真相”存在于仓库本身，而不是聊天历史中。它使用 CLI 和一套与宿主适配器（如 ~/.claude/settings.json 和 ~/.codex/hooks.json）集成的钩子系统。

核心机制包括：

• 会话移交 (Session Handoffs)：钩子将上下文、计划和移交内容写回项目文件（例如 .ai/harness/handoff/resume.md），允许新会话从上次中断的地方准确恢复。
• Token 效率：利用预构建的 CodeGraph 索引进行结构化查询，并通过 context-map.json 进行渐进式上下文加载，减少了昂贵的 grep-and-read 循环的需求。
• 护栏 (Guardrails)：进程内变更保护可以在活动计划未标记为“已批准 (Approved)”或“执行中 (Executing)”时阻止实现编辑。
• 结构化产物：将仓库组织成特定的界面，用于规范 (docs/spec.md)、计划 (plans/) 和任务契约 (tasks/contracts/)。

适用对象

专为使用 AI 代理（特别是 Claude 和 Codex）处理复杂、长期编码任务，并希望拥有可重复、可验证且具有 Token 效率的流水线的 AI 工具所有者和开发人员设计。

亮点

• 基于文件的状态：将代理协作从聊天线程转移到仓库本地文件。
• 渐进式上下文加载：使用小型根上下文和能力块来节省 Token。
• 自动化移交：捕获会话状态和 dirty-bit 事件，以促进无缝会话恢复。
• 硬性强制关卡：能够根据活动计划的状态阻止代码编辑。
• MCP 连接器：可选的边车 (sidecar)，用于向 MCP 客户端公开流水线产物。