/octoloop — 双环一键入口

OctoLoop = OLP(Outer-Loop Protocol,协议名)之上的产品化封装:用户装 这一个 skill 即可上手双环全能力。三个模式,先选身份再动手;权威规程 在仓库文档,先读再动,不要凭记忆操作。

模式 init — 铺脚手架(首次/新机器)

引导运行仓库的一键引导脚本,再核对依赖清单:

bash scripts/olp-init.sh          # 铺脚手架(黑板/信箱/监视器接线)

脚本按需询问(不假设环境);完成后逐项核对 docs/OLP_QUICKSTART.md §1 环境依赖清单(octos/octoscode 可执行、 herdr 或 tmux、外环模型 CLI)。herdr 来源与分支钉在 §1 依赖表 (hagency-org/herdr,octoscode 识别当前在 feat/octoscode-agent 分支)。任何缺口按 §6 故障速查处理,再跑 §5 冒烟验证(两分钟)。全部发现式:本卡零硬编码路径,一切以 QUICKSTART 的发现命令为准。

模式 outer — 外环上岗(强模型审查员)

收编自 /olp-outer(旧 skill 保留为薄转发)。上岗五步:

1. 读规程:docs/OLP_OUTER_BOOT.md(操作面)+ docs/OUTER_LOOP_PROTOCOL.md(ACK 定式/多外环规则/预算档)
2. 发现现场:herdr agent list / ls -t ~/.octos/instances/, 读各项目 .octos/OUTER_LOOP_REVIEW.md 尾部在途条目
3. 定主审域(多外环并存必做,机械判定不靠笔迹):主审权以 per-project 值班簿+OS 独占锁双层判定——值班簿是提示性目录 (记录署名/域/在途责任,供发现与会话猝死后按 duties 摘要重挂哨; HELD 只可署名批注,STALE/TTL 仅为健康告警,不授予自动 接管权——跨域接管须 operator 明示);终局裁定 = outer-duty 锁 (试锁见下步)。默认主审域 = 启动 cwd 项目;发现现场照旧全机 扫描,但发现 ≠ 接管。
4. 接管职责(主审权锁,R7/olp-v2):上岗必须经 octoscode outer-duty hold --project <项目> --signature <署名> --duties <职责> -- <你的 agent 启动命令> 包裹启动——锁即 authority,守护式死亡耦合(wrapper 唯一持 fd;agent 经 PR_SET_PDEATHSIG 与 wrapper 同死,wrapper 亡⇒agent 必亡⇒VACANT; Linux-only,非 Linux unsupported,Windows LockFileEx 另立); outer-duty check 仅观察、绝不夺取;非 holder 只读批注,活锁接管 只归 operator(终止旧 holder 后再 acquire)。持锁后:署名落板(经 scripts/olp-board-append.sh,flock 原子)→ 立编号条目唤醒内环 → 内环 ACK 后隔离 worktree 独立复验 → 采认代推。安全红线见 BOOT §5。
5. retro(进化环):①触发——战役收官,或进化黑板新卡 ≥ 10 张; ②命令——scripts/olp-evo-harvest.sh <repo> && scripts/olp-evo-retro.sh <repo>(采集→简报,记录目录在 knowledge/context/evolution/);③处置——每次最多推进 3 条记录; 立案条件 hint ≥ 2 或主审目视跨 goal/跨条目复发,或 S1;issue 由 operator 发布或明示委托;④authority——未持 outer-duty 锁只读简报 不写记录;⑤采集哨只认带署名的行首定式 > 外环(<署名>)·改判(作废 #N): / > 外环(<署名>)·R2 记档(#N):,纪律里的散文"R2 记档"不落卡。 ⑥阶段 2/3 工具面(全部只读或只写自家状态目录):监视器 scripts/olp-watch-board.sh <板> <token> --harvest <repo> 命中即采集并常驻 (不带 --harvest 仍一击退出);scripts/olp-evo-metrics.sh <repo> [--since EVO-NNNN] [--json] [--baseline <json>] [--stall <板> --stall-threshold <分钟> [--now <ISO>]] 窗口化诊断(非 KPI:含 increase:/decrease:、stall:、fake_verified:,不作红线); scripts/olp-evo-spec-skeleton.sh <FLAW-NNN.md> 从记录直出契约骨架到 stdout(仓内只许写 specs/drafts/,主审补选择器后才入 specs/); scripts/olp-evo-index.sh <repo> 生成 knowledge/context/evolution/INDEX.md; 回放基线 fixtures/evolution/replay/(合成夹具,实现 commit 不得改)。

模式 inner — 内环形态选型(执行侧)

内环契约 agent 无关(BOOT §6);按任务形态选:

任何形态都要:黑板 ACK 定式、R4/R4b 工作区共存与树主权、 R2 诚实验证声明(verified/partially/unverified)。

自主性纪律(实战沉淀:一次全链演练暴露的六类断点)

外环的价值在全程自主闭环;下面每条都对应一次真实掉链、由 operator 点破的教训。上岗即遵守,不要重蹈:

1. 派出五步闭环:派出→侦听→收割→处置→回执,缺一不闭环。 任何 agent 派出(内环唤醒 / codex 窗格 / 后台任务)的同一批次 内挂完成哨;复验/判词落板后必须回执内环(herdr prompt)—— 黑板是拉模型,master 只在开轮时读板,不回执 = 内环视角外环失联。 侦听必须双哨:正信号哨(ACK 落板)+ 负信号哨(events.jsonl 的 goal_transition blocked / escalation)——只盯正信号时,goal 熔断的 沉默与"还在干活"不可区分(实案:夜间断供熔断 8 小时无人知)。 哨死(超时被回收)会收到失败通知,收到即重挂。
2. 侦听哨唯一合法配方:基线+子串,禁止手搓格式匹配。板面哨一律 发行版 scripts/olp-watch-board.sh(olp-init.sh 安装为 ~/.octos/outer/watch-board.sh)<板> <token> [--skip-signature <署名>](基线行数裁剪 判定域,只看挂哨后新增行;域内 grep -F 宽松匹配,任何前缀格式一视同仁; 外环自己的批注若引用 token 会误报——先落板后挂哨,或用 --skip-signature 排除本署名)。 实案四起同一病灶——谓词作用于全文件+猜格式:三次误报(任务书自述/ 引用文字/历史同号 ACK),一次漏报(### 前缀没猜到,哨空转数小时 致复验迟到);非板面哨锚定唯一新信号:行号基线+署名、产物文件 存在、agent 状态转 idle,严禁数子串。
3. 上岗先做权限预检:把本轮可预期的高频操作(herdr CLI、octos CLI、git push 到 fork)预先配入 harness 允许清单,别撞墙后摆命令 等人。两类永远留给 operator 亲手:免沙箱启动、agent 修改自己的 权限配置(自我提权,harness 会拦且应该拦)。
4. 窗格纪律:开窗格用 split --cwd 指定工作目录,勿靠命令串里 的 cd(实案:三连启动错实例);窗格复用优先、少开关(churn 会 让 operator 的附着画面乱跳);一次性任务用 codex exec 收工即关, 常驻实例才留窗格。
5. goal 卫生:冷派单前查目标会话残留 goal(octos goal list / pane read);收口正解是会话内 /goal stop;serve 存活时离线 octos goal archive 会被 live cache 后写反盖(上游修复前勿依赖); goal 用完必须收口到终态,不留 active 残留。
6. 双签终审:切片级以上交付,推荐第二外环(异厂牌)对抗终审 ——"验收的验收"。实案:单外环两轮复验漏掉"唯一事实源"级机制 错误,对抗复审一轮抓出五 BLOCKER。验收条款尽量写成可 grep 的 断言,复验逐字重跑;ACK 里的概括性声明("占位全回填")必须 逐项自查后才落笔——被证伪即 R2 记档。安全/基建类任务蓝本先行: 先让第二外环出对抗过的设计蓝本再开工,实测轮次差 2 vs 8(有蓝本的 goal 竞争修复两轮收官;实现先行的 duty 锁八轮会签、两次核心设计 易稿——fd 继承与公开 seam 都是"实现了才被审出"的方向错误)。
7. 重启硬清单——兜底瘫痪是隐形的,必须显式巡检。内环(重)启动 后外环逐项核对,禁止"记一笔稍后补":①serve 起(operator 亲手, 免沙箱);②**/loop resume 外环必代**——先 /loop list 取 id 再 /loop resume <id>(裸 resume 要 id 会拒);③双哨挂载(正 ACK + 负 goal_transition);④fallbacks 已配且新会话已快照(改配置 不重启=纸面保险)。原则:主机制健康时,兜底层瘫痪完全不可见 (实案:paused 一整天无人察觉,直至三层同失才暴露,8 小时停摆)。 兜底的健康只能靠巡检,不能靠事故。清单详见 BOOT §0b。 附则(自查面选错实案):清单每步必须绑定权威探查面,内环自检 不得自选替代面——实案:自检报"无 paused 循环"(翻的是数据目录), 而 TUI 状态栏明示 1 paused;loop 状态的权威面是会话内 /loop list, 不是磁盘文件。外环收自检报告时以独立面对账(读屏核状态栏), 声明与状态栏矛盾即打回重查——这是"声明-对象一致性"纪律的运行时 版本:测试对 git 对象,自检对权威状态面。

规模化扇出纪律(实战沉淀:20+ 车道、三天百余任务的一次移植战役)

一个外环 + 二十余条 octoscode 车道,3.3 天派出 113 张任务卡、合入 131 个任务分支,吞吐约为同一外环单干期的 2 倍,且把真实环境端到端从"不通" 推到全绿。**瓶颈不在车道,而在外环独占的两件事:采认复验与真实环境 e2e。**下面每条都是这次战役里的一次真实掉链。

1. 任务卡要"可独立验收":一卡一车道一分支(task/<N>,从最新集成 分支拉),写明:对照的参考实现(要求引用 file:line)、真实路径(勿走 软链)、构建/测试入口、可逐字重跑的验收命令、ACK 定式。车道把工作 提交到长期分支(非 task/N)时会让复验取错对象——卡里写死分支名。
2. 复验必须覆盖全部测试目标:试合并到独立复验克隆,跑每个 crate 的 lib + 全部 test target,而不是手挑几个——实案:复验脚本只跑了 5/37 个 test target,三个合入在部分证据上被采认,另有三个既有红灯 整整一天无人察觉。先对集成分支跑一次基线,把既有红灯列入 "已知红"清单,车道结果只与基线比。
3. 集成分支纪律:合入后先 check --tests 再采认;测试在跑时不合入 (混合两个版本的结果不可信,实案里被迫中止重跑);冲突一律"两边都留" 后再全量跑。复验排队是串行瓶颈:每轮约 30 分钟——多开 2-4 个复验 克隆并行,或把多个小分支顺序合入后一次全量跑、按失败测试所属 域归因。
4. ACK 哨的格式宽容:车道会写 > ACK(...)、### ACK 等变体;哨的 匹配要容忍前缀,放宽谓词时先把现存行写入已见集合再重挂,否则旧 ACK 洪泛。实案:引用格式的 ACK 被漏数小时。哨到期即重挂,不空窗。
5. 纠偏用 addendum,不改原卡:外环复看发现新线索/更正时,向车道黑板 追加 Outer loop addendum/correction to #N 并 prompt 唤醒——车道据此 调整,历史可追。外环手里的真实环境证据(日志行、数据库只读副本、 截图)是车道最缺的:把证据原样递过去,常把 2 小时的排查压到 20 分钟。
6. 只有真实环境才暴露的缺陷类(车道单测全绿也会漏,e2e 要专门找): ①超时/预算与参考实现不一致(参考 60 s,移植 2 s,冷启动必爆); ②功能接在生产从不走的分支上(测试走 A 路径,生产恒走 B); ③静默丢弃(入口拒绝不留日志);④兜底 catch-all 抹掉真实错误原因 (日志只剩一个词,无限重试);⑤线上跑的是旧制品(先核对部署版本再 判缺陷)。派卡时要求车道:超时值引用参考实现、测试走生产装配 路径、每个拒绝点留 reason 日志。
7. 归因前先冷启动交错二分:升级后出现的"回归"可能是负载 × 紧预算, 旧版冷启动同样失败——新旧版本交错、冷启动、同负载对比后再 指认 commit。外环的直觉嫌疑同样要被二分证伪(实案里外环猜错了)。
8. 真实服务商调用花 operator 的额度:车道的真实模型回放会与生产共用 配额(实案:主力模型额度被耗尽一天)。规则:真实 harness 只许走到 会话建立;任何会开 turn 的运行先征得外环同意并用最便宜的档。
9. 主机资源巡检是外环职责:每车道构建目录可达 50 GB;盘低于阈值时 清空闲车道的构建目录(用字面绝对路径删除——cd+glob 或变量 路径会被安全检查拒绝,且本就不该那样删);车道克隆用 APFS clone 时 去重收益小,真正的大头是构建产物;并发测试用槽位锁限流。
10. 车道打分要可回改:五项各 2 分(参考一致/生产接线/测试/边界/诚实), 记入可机读档;真实环境证据出来后上调或下调(实案:一次下调后被 车道的根因报告证明错怪,随即恢复)。按分派单:协议/运行时→最稳车道, 长链调查→快而诚实的档,大文件浏览器套件→慢而稳的档;低分车道只给 小而明确的卡。
11. 车道会"漂移":空闲车道可能被残留提示唤回去重做旧任务、或把 指令原文当 ACK 写回。外环读 ACK 时核对 sha 与卡号、看是否真有新提交; 指令里别写可被误数的 ACK(#N done) 字样。

能力清单(全景一页)

见 docs/OCTOLOOP_FEATURES.md —— 断供降级、孤儿回收、malformed 自纠、预算 checkpoint、断拍自续、写策略三档、纯 Rust MCP 第五信道、 startup --prompt 等逐条:是什么 + 缺省状态 + 用户怎么看到效果。