ENGINEERING NOTES · V1

中央引擎如何保持
有界、可查、可停

由 GitHub Issue 驱动的有界自循环编码 Agent，并作为中央可复用引擎服务多个目标仓库。 这里展开它在 GitHub Actions、Agent 运行时与目标仓库之间的真实工程边界。

查看源代码 ↗← 返回产品页

01 / ARCHITECTURE

中央引擎与调用仓库

工作流实现集中复用，运行产生的一切仍归目标仓库。
目标仓库

Issue、Listener、独立任务分支、状态文件与 Pull Request 都留在调用仓库。

中央引擎

reusable workflow、可信 prompt、角色 skills 与包装脚本通过稳定版本复用。

特权包装层

快照、提交、推送、PR 与 repository_dispatch 接力由受信任脚本负责。

Agent 执行层

角色只在自身权限内读取、实现、测试或审查，不持有 GitHub 凭据。

Issue event
  → target Listener
  → reusable-agent-cycle.yml @ v1
  → agent/issue-<number>
  → Pull Request in target repository

事件与信任

新建、重开、编辑 Issue 均可触发；author_association 通过 AGENT_TRUSTED_ASSOCIATIONS 显式收窄。

分支与并发

每个 Issue 固定到 agent/issue-<number> 分支和对应并发锁，同一任务不会并行互相覆盖。

02 / ROLE CONTRACTS

四个角色，四份可校验产物

角色权限、输入和输出由包装层固定，而不是靠一次长会话自行切换身份。
01

Analyst

read-only
INPUT
Issue 快照与当前 handoff
OUTPUT
analysis.json

读取问题证据，定位根因或变更理由，形成实施与验证计划。

02

Implementer

write
INPUT
已校验的 analysis.json
OUTPUT
implementation.json

以测试驱动方式完成一个有界增量，并记录改动、验证与计划偏差。

03

Verifier

read-only
INPUT
真实 diff 与 implementation.json
OUTPUT
verification.json

独立运行回归与验收检查，只记录证据，不修改目标代码。

04

Reviewer

read-only
INPUT
真实 diff 与前三阶段产物
OUTPUT
review.json

依据验证证据给出最终 findings，并决定本轮状态。

只读并非提示词承诺

Analyst、Verifier、Reviewer 执行前后都会计算工作树指纹；出现可提交变更时，本轮直接停止。

03 / STATE PROTOCOL

状态留在任务分支里

跨角色、跨轮的事实都写入 .agent_state/issues/<number>/，让恢复与审查有稳定依据。
FILEOWNERPURPOSE
issue.mdWrapper

保存最新 Issue 快照。

state.jsonWrapper

记录轮数、Provider 与生命周期。

handoff.mdWrapper

保存由最终审查派生的下一轮紧凑上下文。

result.jsonReviewer / Wrapper

保存已校验的本轮最终状态。

analysis.jsonAnalyst

记录证据、根因、实施与验证计划。

implementation.jsonImplementer

记录实际改动、测试结果和计划偏差。

verification.jsonVerifier

记录独立测试与验收证据。

review.jsonReviewer

记录审查结论与具体 findings。

complete交付 Pull Request

停止接力，等待维护者审查与合并。

continue进入下一轮

包装层生成 handoff.md，携带紧凑上下文继续。

blocked等待维护者

停止执行，保留证据并交由维护者处理。

默认硬上限：Round N / 5。到达上限后停止，不再发起下一次 repository_dispatch。

04 / SECURITY MODEL

Token 只存在于特权包装层

目标代码运行与 GitHub 权限操作在不同阶段发生，缩小凭据暴露和供应链执行面。

凭据隔离

Claude Code 不接收 GitHub Token、PAT 或 Actions 运行时凭据。

只读阶段指纹

包装脚本比较只读角色执行前后的工作树指纹，发现可提交改动即停止本轮。

状态目录保护

Implementer 可改目标代码，但不能篡改 wrapper 管理的生命周期状态和前序产物。

特权静态验证

持有 Token 的 finalize 只解析工作流 YAML，不执行目标仓库可控代码。

Privileged finalize
  GitHub Token → commit / push / PR / dispatch
  validate-target.sh → static YAML parsing only
──────────────── security boundary ────────────────
Agent execution
  source code → implement / test / review
  GitHub credentials → unavailable

05 / INSTALLATION

稳定引用，而不是跟随 main

私有中央引擎通过安装器完成 Listener、仓库设置和 Secret 前置检查。
./agent-cycle setup
cd /path/to/private-target
agent-cycle deploy

# choose MiMo and narrow trusted associations
agent-cycle deploy --provider mimo \
  --trusted-associations OWNER,MEMBER

生产 Listener 固定到稳定 v1 或 commit SHA。私有目标仓库调用私有 reusable workflow 时，还需 ENGINE_TOKEN 和中央引擎的 Actions 访问授权；public 目标仓库不能直接调用 private reusable workflow。

06 / BENCHMARK

相同 Case、快照与 Rubric

Benchmark 在专用目标仓库中对固定代码快照创建任务，收集 PR 与状态产物，再按 rubric 生成报告。
01validate-config
02create-issues
03run
04collect
05report
agent-cycle benchmark validate-config
agent-cycle benchmark create-issues --target-repo OWNER/REPO
agent-cycle benchmark run --target-repo OWNER/REPO
agent-cycle benchmark collect --target-repo OWNER/REPO --out results.jsonl
agent-cycle benchmark report --input results.jsonl --out report.md

当前配置覆盖 DeepSeek 与 MiMo。报告只呈现相同输入和评分规则下的观测结果，不把一次运行解释为 Provider 的绝对排名。

07 / ENGINEERING CHALLENGES

真正困难的是边界与证据

六个问题都来自当前实现的工作流、包装脚本与测试，而不是概念性架构图。
01

跨仓库上下文归属

问题

可复用工作流来自中央引擎，但 Issue、分支、权限和 PR 必须始终作用于发起调用的目标仓库。

解法

让 reusable workflow 在调用仓库的 github 上下文中运行，并显式区分 ENGINE_ROOT 与 TARGET_ROOT。

  • GitHub Actions
  • Reusable Workflow
02

Agent 与凭据的权限分离

问题

代码执行环境需要读写目标仓库，却不应该接触可创建分支、PR 或接力运行的高权限凭据。

解法

Claude Code 运行时移除 GitHub 凭据，把提交、推送、PR 与 dispatch 收口到快照化包装脚本。

  • Security
  • Least Privilege
03

只读角色的可验证约束

问题

提示词中的只读承诺无法单独证明 Analyst、Verifier、Reviewer 没有在工作树留下副作用。

解法

在每个只读阶段前后计算工作树指纹，发现可提交变更就停止本轮并拒绝发布 Agent 修改。

  • Fingerprint
  • Fail Closed
04

跨轮上下文压缩

问题

完整会话历史会持续膨胀，也会把噪声和未经验证的推断带入下一角色或下一轮。

解法

会话彼此独立，只传递经过模式校验的 JSON 产物，并由 Wrapper 从审查结果派生 handoff.md。

  • Context
  • Schema
05

循环必须可证明终止

问题

Reviewer 可能连续要求继续，若没有统一状态协议与硬上限，自动接力可能长期占用 Actions。

解法

把状态限制为 continue、complete、blocked，并由 Wrapper 执行默认五轮上限和最终停止逻辑。

  • State Machine
  • Bounded Loop
06

Provider 比较的可复现性

问题

不同 Provider 若面对不同代码版本、Issue 或评分规则，最终报告无法支持可靠比较。

解法

Cases 固定上游仓库与 commit，run 记录 base SHA，collect 汇总产物，再用同一 rubric 计算报告。

  • Benchmark
  • Reproducibility

08 / RELIABILITY

同一路径 Dogfooding

中央仓库也调用同一份可复用引擎；可靠性约束由脚本测试和 CI 持续检查。
  • 中央引擎与目标 Listener 走同一条 reusable workflow 生产路径完成 dogfooding。
  • validate-engine.sh 在本地与 CI 检查工作流、脚本、模板和状态契约。
  • Shell 测试覆盖准备轮次、finalize、跨仓库调用、只读变更检测与 Benchmark 流程。
  • 生产 Listener 固定稳定 tag 或 commit SHA，避免目标仓库静默跟随开发分支。