论研发 Agent 的持续交付：iLoop 的设计思路

原文同步自 iLoop DESIGN.md。

一分钟看完

人类程序员也不能一次把代码写对。我们靠项目上下文确定方向，靠编译、日志、UI、截图和崩溃这些真实反馈不断修正。Agent 缺的往往不是再多一点生成能力，而是这套程序员式工作循环。

iLoop 把这套循环做成一层可复用底座：任务先路由到合适的工作流和放权等级，执行后按“要验证什么”选择证据，失败就带着证据再跑一轮；长任务用病例、记账和错题本维持记忆；高风险改动换一个 Agent 独立验收；最终只有时间、范围、机制和反证四道关都闭合，才允许说完成。

它不和 Spec Kit、Codex、Ralph、Superpowers 竞争。那些系统分别擅长把需求想清楚、把任务持续做下去、把能力封装复用；iLoop 补的是下游经常缺失的反馈层：在真实工程和设备里，结果到底对不对，证据在哪里。

iLoop 的目标不是成为一个包办一切的超级 Agent，而是成为一块原子能力：插到任何 AI 研发链路的节点上，把“生成完就结束”改成“拿证据闭环”。

它从哪里来

iLoop 不是先画了一套 Agent 架构，再寻找应用场景。它长自一个很具体的痛点——用 AI 做偏工程化的开发时，反复撞到同一堵墙：

代码规模一大、运行时依赖一强，静态看代码就不够了；
很多判断必须编译、运行、观察真实设备才能下；
任务持续多轮，人不可能盯住 Agent 的每一步；
任意一次误判都可能破坏已有的功能路径。

为了让这类任务能真正跑下去，就得把原来由人完成的检查逐步交给 Agent：补上下文、限制改动范围、编译、抓日志、看 UI、记录失败原因、卡住时升级人。做多了回头看，真正可复用的不是某个具体脚本，而是这套”让 Agent 自己获得反馈并持续修正”的方法。

于是这些能力被抽象出来，变成 iLoop。开源版遵守同一条边界：业务专属逻辑放扩展，只有换一个项目仍成立的判断力和闭环机制才进入核心。

从一个朴素问题开始：程序员为什么能把代码写对

先问一个问题：人类程序员能一次把代码写对吗？

通常不能。

我们写一段就编译一下，跑起来看日志，页面不对就抓 UI 或截图，崩了就看堆栈。新证据推翻了原来的判断，就回去改；修完再跑；影响面大，再补回归。代码并不是被“一次想对”的，而是在一轮轮反馈里逐渐逼近正确。

这个过程里有两类东西：

动手前的方向：需求、接口、项目约束、历史经验、这类任务通常怎么处理。
动手后的反馈：编译结果、日志字段、UI 层级、最终画面、crash report。

前者防止一开始走错，后者负责在执行中纠偏。Agent 如果只有代码生成，没有这两类输入，就像让程序员蒙着眼睛写代码：它当然可以产出很多内容，但不容易知道自己是否真的做对了。

iLoop 做的第一件事，就是把这些“眼睛”和“方向盘”接给 Agent。

理解目标
  ↓
取得最相关的上下文
  ↓
选择方法和放权等级
  ↓
修改 / 执行
  ↓
编译、日志、UI、截图、Crash
  ↓
证据是否支持目标？
  ├─ 否：修正判断，再跑一轮
  └─ 是：验收、收口、沉淀

每一步都可以回到一份别人能重新打开、重新运行的证据，而不是只相信 Agent 说“我验证过了”。

iLoop 是什么

iLoop 是给研发 Agent 补上的程序员式工作循环：把动手前需要的上下文、动手后需要的真实反馈和长期任务所需的制度，组织成一条能持续运行的闭环。

它不是模型，也不替代模型的判断。判断、方案和代码仍然由 Agent 产生。iLoop 提供的是：

任务开始时应该走哪种方法；
当前允许 Agent 做到什么程度；
这一轮最值得验证什么；
应该用哪种证据验证；
哪些结论是看到的，哪些只是推断；
什么条件下可以收敛；
什么时候必须停下问人；
这次踩过的坑如何在下一次被召回。

所以更准确的定位不是“iOS AI 编码助手”，而是验证驱动的研发 Agent 闭环内核。iOS 是第一个官方执行插件，用来把“真实工程、真实设备、真实反馈”这件事跑通。

这么多 Agent 和框架，为什么还需要 iLoop

iLoop 和现有框架解决的是不同层次的问题。

方向	主要解决什么	iLoop 补什么
Codex / 通用 Coding Agent	理解目标、生成代码、调用工具、持续执行	不能只靠执行者判断“已经达标”，要接入外部可复核证据
Spec Kit	把模糊需求整理成规范、计划和任务	规范之后继续在真实工程中落地、运行、验收
Ralph Loop	让目标持续循环推进，直到满足停止条件	每轮该拿什么反馈、反馈可信度如何、停止条件是否真的成立
Superpowers / Skills	把方法和工具封装成可复用能力	把分散能力组织进同一条证据闭环，并约束边界
Harness / Loop Engineering	解释 Agent 为什么需要前馈、反馈、记忆和循环	把这些原则落成能在本机运行的入口协议、内核、工作流和平台插件

可以把它们理解成一条接力链：

Spec / Planning
      ↓
Agent 执行与生成
      ↓
iLoop 取得真实反馈并推动修正
      ↓
独立验收与证据收口

iLoop 不要求别人迁移到一套全新的 Agent 体系。它更像一个下游反馈底座，可以被 Codex、Claude Code、Cursor 或自建 Agent 调用。

说到底，就一句：验过才算数

把编译、取证、病例、错题本、独立验收这些设计收敛成一句话，就是：

AI 说“完成了”不算数，验过才算数。

这套方法叫 VDD，Verification-Driven Development。

为什么不能只让执行者自验

同一个 Agent 完成任务后，再让它检查自己，仍然沿着原来的推理上下文往下走。它天然倾向于确认自己的结论。换一个 prompt 或角色会改善，但两个角色仍可能共享同一套无知。

所以 iLoop 把验证分成两层：

模型外的真实反馈：真编译、真日志、真截图、真 crash。
目标不同的独立验收：高风险任务由没参与执行的 Agent 只看标准和证据。

四道收敛关卡

一个结论要被接受，至少回答四个问题：

时间对得上：证据和现象是同一次发生的。
范围对得上：证据覆盖了问题实际影响的端、版本、入口和条件。
机制说得通：能解释为什么会发生，而不是只看到相关性。
有反证：换一个关键条件，现象应该消失或变化。

缺任何一关，都只能说“仍需证据”，不能把大概率写成确定事实。

对应实现：kernel/evidence.py、kernel/gate.py、kernel/acceptance.py。

真实反馈不是“三件套”，而是按问题选探针

程序员从来不是遇到所有问题都同时跑截图、日志和 UI 树。我们会先问：这一轮到底要验证什么？

要验证的问题	首选证据
字段、状态、执行路径是否正确	定向日志
控件是否存在、隐藏、位置是否正确	UI 层级树
用户最终看到的画面是否正确	截图
动画、滚动、手势是否正确	录屏或逐帧分析
进程是否真的退出、崩在哪里	crash report、启动日志
修改是否破坏构建	编译 success marker + 产物

这条原则有两个目的：

不把轻量问题升级成全量回归；
不用错误的证据替代真实结果，例如用 grep 证明 UI 已经正确。

iLoop 的平台插件负责把这些反馈接进来；内核只关心证据是什么、从哪里来、能否复核。

开源版的 iOS 插件当前支持 build、install、launch、logs、view tree、screenshot、probe 和 crash。模拟器走 simctl，真机走 devicectl 与 Appium WebDriverAgent。

把循环放进长任务，会依次撞上六个问题

“改一下、验一下”适合短任务。任务跑到几十轮后，会出现更难的问题。iLoop 的主要设计不是先画出来再找用途，而是在这些问题中一件件长出来的。

1. Agent 会忘：给它分层记忆

模型上下文会被压缩，早期目标和约束会淡化。把所有东西都塞进 prompt 又会造成 context rot。

iLoop 没有做一个大而全的知识库，而是按用途拆开：

记忆层	保存什么	当前载体
稳定规则	第一性原则、红线、收口口径	`AGENT_PROMPT.md`、`prompts/`
方法记忆	一类任务应该怎么思考、何时升级	`workflow/flows.json`、诊断专家
任务记忆	当前现象、假设、证据、轮次、下一步	`Case`、`Ledger`、证据目录
经验记忆	过去反复出现的工程坑与解法	`LessonBook`、`seed_lessons/`

每轮只加载命中的工作流、相关 lessons 和最小证据缺口。长任务靠外部档案重建上下文，不靠把全部聊天历史顶在窗口里。

对应实现：kernel/case.py、kernel/ledger.py、kernel/lesson.py。

2. Agent 会凭感觉发挥：给它工作流

不同任务的正确起手式不同。排查问题应该先列假设、找区分度最高的证据；新需求应该先对齐验收标准；小文案改动不需要全量回归；环境问题应该先查工具链和错题本。

因此 plan 先把任务路由到一个 flow。flow 会声明：

这类任务的目标；
放权等级；
开工前应读取哪些文档；
优先取什么证据；
什么时候必须升级用户；
收口后可以主动建议什么。

flow 是方向参考，不是机械 checklist。真正执行时仍要根据现场裁剪。

对应实现：kernel/flow.py、workflow/flows.json。

3. 放权过少效率低，放权过多风险高：给它三档自治

iLoop 把权限分成三档：

档位	对外含义	适用场景
L1	只看不改	调查、取证、方案分析
L2	动手改	明确范围内的需求、修复、小迭代
L3	放手干	用户明确授权、有任务清单和验收标准的长任务

越档必须停下确认。小任务不被重流程拖慢，大任务也不会因为一句模糊目标就无限自驱。

4. Agent 会自己给自己打高分：加独立裁判

高风险改动不能只由执行者验收。iLoop 会先用改动范围、文件数和高风险关键词做粗筛，但指标只是线索，不是通过标准。

需要独立验收时，主 Agent 生成一份验收包：

验收标准 + observed 证据 + 明确缺口
                    ↓
              独立验收 Agent
                    ↓
        pass / fail / needs_more

独立裁判不改代码，只逐条判断：

判 fail 必须指出与标准矛盾的具体证据；
缺上下文是 needs_more，不是 fail；
最多补一次证据，不无限往返。

对应实现：kernel/acceptance.py、agents/iloop-acceptance.md。

5. Agent 不知道什么时候停：给它硬收口标准

开工前先把“怎么算完成”写成可验证指标；收口时逐条对照证据，并检查四道关卡。

此外还有反循环闸门：

同一根因失败 3 轮，停手升级；
单任务累计失败 6 轮，停手升级；
环境、账号、权限、签名或缺输入等人类卡口，不反复傻试。

对应实现：kernel/gate.py、kernel/gate_capability.py、kernel/ledger.py。

6. 同一个坑会反复出现：让经验进入下一轮

不是所有问题都值得写入长期记忆。iLoop 只沉淀同时满足三点的经验：

不是一次性业务 bug，而是工程或工具链问题；
跨任务大概率复现；
解法不是一眼就能得到。

下一次遇到相似报错，先查 lessons，再决定是否从零排查。经验从“聊天里说过”变成可召回、可分发的资产。

诊断为什么用“病例”，而不是一串聊天

排查类任务往往一轮结束不了。聊天记录更擅长保存“我们说过什么”，不擅长保存“当前凭什么相信哪个原因”。

iLoop 把一次诊断建成病例：

现象
├── 候选原因 h1
│   ├── 支持证据
│   └── 反对证据
├── 候选原因 h2
├── 下一条最有区分度的检查（TestSpec）
├── 专家会诊结论
└── 四关状态

每次 tick 只给出下一条最有区分度的检查；专家只能回答自己边界内的问题；新证据互相矛盾时 reroute 重分诊，而不是硬把旧结论圆回来。

这使诊断可以跨轮次、跨会话，甚至被新的事件继续唤醒。

对应实现：kernel/case.py、kernel/experts.py。

凭什么能换任务、换业务、换平台

通用性不是把所有能力都塞进核心，而是把边界切干净。

┌─────────────────────────────────────────────┐
│ 判断力：VDD / 工作流 / 病例 / 验收 / 错题本 │
├─────────────────────────────────────────────┤
│ 业务层：领域材料 / 业务 flow / 专项脚本 / 角色│
├─────────────────────────────────────────────┤
│ 平台层：iOS / 日志 / 监控 / CI / IM / 设备   │
└─────────────────────────────────────────────┘

判断力回答“应该怎么想、怎样才算完成”；
业务层回答“这个领域是什么、目标和边界是什么”；
平台层回答“具体怎么编、怎么跑、怎么拿证据”。

换业务只替换业务层，换平台只替换执行插件，核心循环不需要重写。

判断一段逻辑是否应进入核心，可以只问一句：

换一家公司、换一套工具链，这段逻辑还成立吗？

成立，进入核心；不成立，做成插件或扩展。

“内核协议”到底是什么

普通使用者不需要先学习 SPEC.md。

内核协议不是一套要背的理论，而是 Agent 与插件之间的插座标准。它只规定四类东西应该长什么样：

证据：从哪里来，是观测还是推断，产物在哪里；
能力：插件支持 build、logs、screenshot 还是 crash，调用结果如何统一返回；
工作流：一类任务何时命中、用哪档权限、读哪些文档、何时升级；
经验：一条 lesson 如何保存和检索。

这样监控、日志、CI、IM、Android 或其他平台可以各自实现插件，而病例、验收、错题本和收口逻辑不需要认识任何具体平台。

SPEC.md 主要服务插件作者和 Agent 自动二次开发，不是普通用户的使用门槛。

为什么能跨 Agent 宿主

iLoop 不把自己的生命线绑在某个 IDE 或模型上。它分成三部分一起随仓库分发：

AGENT_PROMPT.md：告诉 Agent 第一性原则、运行顺序、红线和如何按需加载文档；
CLI 与内核：执行 plan、取证、病例、验收、记忆和扩展校验；
平台插件：把具体工程和设备反馈转换成统一证据。

支持项目规则或系统提示的宿主，都可以加载入口文档；支持 shell/进程调用的宿主，都可以运行同一套 CLI。Claude Code、Codex、Cursor 或自建 Agent 的差异由宿主适配承担，VDD、flow、证据和病例不会跟着重写。

开源版选择把提示词与代码放进同一个 GitHub 仓：

clone 一次就拿到匹配版本的入口、分片文档、内核和插件；
git pull 同时更新协议和实现；
不存在提示词已经升级、工具链却没拉下来或版本不匹配的问题。

这不等于“文件在本地就算接入完成”。真正的宿主接入仍要验证：Agent 是否读到了入口、能否调用 CLI、需要的子 Agent 或设备能力是否可用。缺能力时明确降级，不能冒充完整闭环。

二次开发：把开发接口交给 Agent，而不是交给人

传统插件系统常要求人先读 SDK、写 manifest、研究目录结构。iLoop 的二次开发首先是一份Agent 可执行的开发协议。

用户只需要表达业务目标：

基于 iLoop 做一个代码排查 Agent。基于 iLoop 做一个智能 oncall Agent。给团队增加一个发布回归工作流。

加载了 iLoop 入口协议的 Agent 会自行完成：

判断归属：服务所有用户的能力进公共核心；只服务某个团队或业务的能力进独立扩展。归属不清先让用户选择。
读取扩展契约：加载 EXTENDING.md，而不是凭入口提示词猜目录。
创建隔离空间：运行 extension-init <team.extension>。
只改扩展目录：核心整体只读，业务能力不 fork、不魔改入口。
实现业务层：按需添加 flow、平台插件、事件源、通知渠道或方法专家。
执行边界校验：运行 extension-validate，检查命名空间、核心覆盖和格式。
拿真实任务验收：再次运行 plan，确认真实业务请求能命中新 flow，再按该 flow 跑一次闭环。

所以二次开发的交互面不是“请人类手写一个 flows.json”，而是“告诉 Agent 目标、输入、输出和验收口径”。协议和脚手架是 Agent 的工具。

对应实现：AGENT_PROMPT.md、EXTENDING.md、kernel/extension.py。

oncall 只是其中一个例子

把具体 IM 和告警平台拿掉，智能 oncall 的通用骨架是：

事件源
病例建档
证据驱动诊断
按风险决定自动处置或升级
通知结论

事件源和通知渠道是接口，病例、专家、四关、错题本和验收是内核。

因此同一套内核既可以驱动交互式代码修复，也可以驱动一个事件唤醒的诊断 Agent。区别只是入口和平台插件，不是重新造一套 Agent。

开源版提供 EventSource、Notifier、stdout/webhook 参考实现和 oncall-demo。

看板不证明“AI 很忙”，只证明交付发生了什么

步骤多不等于价值高。iLoop 的看板不应该把历史 trace 包装成“替你做了多少动作”，而是分三本账：

账本	回答的问题
结果账	完成多少任务、哪些轮次成功或失败、产出了多少 observed 证据
机制账	工作流、取证、止损、独立验收是否参与了交付
审计账	证据、病例、错题本和时间线能否回到原始依据

指标只用于发现问题和展示过程，不能替代真实验收。这与 VDD 的原则一致：覆盖率、步骤数、自动化次数都不是“完成”的门槛。

对应实现：kernel/ledger.py、kernel/dashboard.py。

开源版当前落到了哪里

已实现

平台无关内核，纯 Python 标准库；
入口提示词与按需分片提示词；
10 个内置 flow 和 L1/L2/L3 放权；
证据分级、四道关卡、病例、诊断专家；
tick / consult / reroute 持续诊断；
独立验收与改动风险粗筛；
错题本、反循环、能力 Gate、红线守卫；
提效看板；
Agent 驱动的扩展脚手架和校验器；
iOS 官方插件：build、install、launch、logs、view tree、screenshot、probe、crash；
模拟器与真机执行路径，真机 UI 基于 Appium WebDriverAgent；
83 条 selftest 断言。

已真实验证

内核和 iOS 插件 selftest 全绿；
Xcode 自动发现；
模拟器 probe 与 screenshot 端到端运行，截图产物可复核；
oncall demo 从事件到病例、证据、四关、通知完整运行；
扩展创建、校验和防覆盖核心 flow。

仍需继续验证

更多真实 iOS 工程上的 build / install / launch 组合；
更多真机与系统版本覆盖；
真机 UI batch 目前只支持 tap；
Android、Web、Lynx 等新平台应以插件方式逐个接入并真实验证，不能仅凭架构推断已经通用。

这也是 iLoop 对自己的要求：可以说架构为跨平台准备好了，但在某个平台真跑通之前，不能把“可以扩展”说成“已经支持”。

最后：iLoop 的价值不在“又多一个 Agent”

现在很多 AI 研发链路已经能从需求生成代码、生成测试，甚至触发发布。但这些链路很容易停在开环：

代码生成了，能不能编过；
测试说通过，是否覆盖了真实用户路径；
页面改了，用户实际看到的是否正确；
修复上线，是否影响了其他入口。

如果这些问题仍然依赖人到处搬运信息、再转述给 Agent，反馈链就既慢又有损。

iLoop 想沉淀的是一层可复用的反馈能力：把 Agent 原来够不到的编译、设备、日志、UI、崩溃和平台证据接回来，再用病例、工作流、验收和记忆组织起来。

补一条断掉的反馈链，Agent 就少猜一点；证据越完整、越一手，循环越可靠。

所以 iLoop 最终想成为的，不是一个更聪明的 Agent，而是整个 AI 研发链路可以复用的反馈底座。