ISSUE-DRIVEN · BOUNDED · REVIEWABLE

Agent Cycle

把一个 Issue 变成有证据、可审查的 Pull Request

由 GitHub Issue 驱动的有界自循环编码 Agent，并作为中央可复用引擎服务多个目标仓库。

查看 GitHub理解运行机制

人在 Pull Request 边界审查证据，并作最终合并决定。

agent-cycle / issue #42SCROLL
Round 1/ 51 / 13
Issue #42 触发 Listener
  1. 1
    Analystanalysis.json
  2. 2
    Implementerimplementation.json
  3. 3
    Verifierverification.json
  4. 4
    Reviewerreview.json
complete交付 Pull Request
continue进入下一轮
blocked等待维护者
滚动推进 · 向上回退

01 / ORIGIN

思想从哪里来

项目受王巍老师 Let’s Vision 26《AI Agent 的道与术》演讲启发，并在我的整理与个人工程实践中演化为可运行的 GitHub Issue 驱动系统。

01王巍老师演讲稿打开来源 ↗02我的演讲整理打开来源 ↗03项目源码打开来源 ↗

02 / PRINCIPLES

从道，到可运行的术

不是照搬观点，而是把协作原则落实为明确的角色、产物与停止条件。

验收前置

Issue 先明确期望结果，Analyst 写计划，Verifier 独立留下验收证据。

Agent to Agent

四个专门角色顺序协作，后一阶段只接收已校验的结构化产物。

独立 Context

每个角色运行在独立 Claude Code 会话，聊天历史不跨越角色边界。

Memory / Skill

模块化 memory 渐进披露，中央可信 prompt 与角色 skill 通过 system prompt 注入。

有界闭环

Reviewer 通过 continue、complete、blocked 协议控制接力，默认最多五轮。

人的角色上移

人负责定义问题、检查证据，并在 Pull Request 边界作最终合并决定。

03 / MECHANISM

一次运行，四次独立判断

每个角色只完成自己的职责，结构化产物沿固定顺序进入下一阶段。

01read-only

Analyst

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

analysis.json
02write

Implementer

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

implementation.json
03read-only

Verifier

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

verification.json
04read-only

Reviewer

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

review.json
complete交付 Pull Request

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

continue进入下一轮

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

blocked等待维护者

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

04 / CONTEXT

独立思考，结构化交接

角色之间不共享聊天历史，防止未经验证的推断顺着上下文扩散。

独立会话 Context只传递已校验产物
  1. 01Analystread-only
    private contextanalysis.json
  2. 02Implementerwrite
    private contextimplementation.json
  3. 03Verifierread-only
    private contextverification.json
  4. 04Reviewerread-only
    private contextreview.json

聊天历史停留在角色自己的轨道；只有通过契约校验的 JSON 或 Markdown 穿过边界。

05 / CENTRAL ENGINE

一个引擎，服务多个仓库

目标仓库保持轻量，中央工作流和角色契约通过稳定版本统一演进。

Target repositoryiOS AppListener → Issue #18PR 回到本仓库
Target repositoryGo ServiceListener → Issue #19PR 回到本仓库
Target repositoryWeb ClientListener → Issue #20PR 回到本仓库
Central reusable engineAgent Cyclereusable-agent-cycle.yml @ v1

Listener 调用中央引擎，但 Issue、分支、权限、状态与 Pull Request 始终属于各自的目标仓库。

06 / CAPABILITIES

围绕交付建立闭环

中央可复用引擎

目标仓库只安装轻量 Listener，统一调用同一份 reusable workflow。

Issue 事件与信任门控

新建、重开或编辑 Issue 可触发运行，author_association 可显式收窄可信来源。

独立任务分支

每个 Issue 使用 agent/issue-<number> 分支与并发锁，改动不直接进入默认分支。

结构化交接

JSON 产物、state.json 与 handoff.md 持久化每轮证据和紧凑上下文。

Pull Request 交付

包装脚本负责提交、推送和创建 PR，维护者在标准代码审查边界作决定。

Provider Benchmark

用固定 case、provider 与 rubric 对 DeepSeek、MiMo 运行结果做可复现比较。

07 / SECURITY

能力来自明确边界

Agent 执行层与持有 GitHub 权限的包装层分离，状态和只读承诺都接受脚本校验。

PRIVILEGED WRAPPER

特权包装层

  • GitHub Token
  • commit / push
  • Pull Request
  • repository_dispatch
TOKEN stays here
凭据与执行安全边界
AGENT EXECUTION

Agent 执行层

  • 读取代码
  • 实现增量
  • 运行测试
  • 审查证据

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

凭据隔离

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

只读阶段指纹

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

状态目录保护

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

特权静态验证

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

08 / DEPLOY

把 Listener 装进目标仓库

安装器要求本机已有 git、已认证的 gh，以及目标仓库管理员权限。

agent-cycle deploy