/os-workflow

name: os-workflow
description: AI Team OS 里用 CC 内置 Workflow 的两件事：产出回写 OS 的标准模板（§1-2、§4），以及审查分级与派工档位纪律（§3/§3.1）。准备调用 Workflow 编排子 agent 时，或要判定一件事该按 L0/L1/L2 哪一档审查（含「这活要不要开 workflow」）时使用。

OS Workflow — 用 CC 工作流，但让产出回流 OS

背景

调用 Workflow 后，每个内部 agent 会被 hook 自动注册成一个 OS 团队（`workflow-<wf_id>`， 一次 workflow = 一个团队）。追踪是自动的，但**工作内容不会自己入库**——下面两件事必须你做。

1. 总任务上墙（Leader 职责，不变）

调用 Workflow **前**用 `task_create` 把这次工作方向登记上墙并置 running（§2 的回写指令要把它的 id 插进每个 agent 的 prompt，事后补建来不及），完成后 `task_update` 置 completed 并填 result。

2. 在每个 workflow agent 的 prompt 里嵌入「回写指令」

把下面这段**粘进你写的 workflow 脚本里每个 `agent()` 的 prompt 末尾**（已验证 workflow agent 能调 OS 的 MCP 工具 + HTTP API，非沙盒）：

【回写 OS（收尾必做）】
1. ToolSearch 加载：select:mcp__ai-team-os__task_memo_add,mcp__ai-team-os__report_save
2. 完成本职工作后：
   - task_memo_add(task_id="<总任务id>", content="<这步干了啥+关键结论>", memo_type="progress")
   - 重要产出再 report_save(...) 落库，并把 report_id 写进 memo
3. 你在项目目录运行，MCP 自动带项目头，无需关心端口/项目 id。

在脚本里把 `<总任务id>` 用第 1 步 `task_create` 拿到的 id 通过 prompt 字符串插值传进去。

脚本写法示例

// Leader 先 task_create 拿到 taskId（OS MCP），再写 workflow：
const WRITEBACK = `\n【回写 OS（收尾必做）】\n1. ToolSearch: select:mcp__ai-team-os__task_memo_add\n2. 完成后 task_memo_add(task_id="${taskId}", content="...", memo_type="progress")\n3. 项目目录运行，MCP 自动带项目头。`

const r = await agent('你的实际任务……' + WRITEBACK, { schema, label })

3. 模型档位纪律（用户裁定）

两档制：**Fable = 编排层**（统筹/架构裁决/终审），**Opus = 执行层**（一切 worker）。 不传 model 即继承主会话模型，所以在 Fable 会话里裸派会整场按 Fable 价率烧：

• 每个 `agent()` **默认显式带 `model: 'opus'`**（层级别名，浮动到最新 Opus，不写死型号）；
• 仅**终审/对抗裁决/最高难度修复**的 stage 用 `model: 'fable'`（通常配 `effort: 'xhigh'`）。
• 每处 `model: 'fable'` 调用须配一条 `// fable 理由: …` 行注释；Agent 工具派工则在 prompt 首行写 `[fable 理由: …]`。**S6 派工门禁**（PreToolUse 机检）：缺省 model 直接拦，fable 无理由拦。（实录：因 fable 额度溢出临时放宽，被误写成常规方向记忆，直到用户实测才发现——规范口径只在 CLAUDE.md 派工条，此处不重述。）

// 典型分层：执行 stage 全 opus，终审 stage 才 fable
const found = await parallel(ITEMS.map(x => () =>
  agent(findPrompt(x) + WRITEBACK, { model: 'opus', schema: FINDINGS })))
// fable 理由: 终审裁决需最强模型
const verdict = await agent(judgePrompt(found) + WRITEBACK,
  { model: 'fable', effort: 'xhigh', schema: VERDICT })

注：`effort` 由脚本作者按需自选（`agent()` 的 `effort?: 'low'|'medium'|'high'|'xhigh'|'max'`，省略即继承会话档位），治理层不设 effort 制度。**模型档位则是硬约束**：S6 对缺省 model、fable 无理由一律 `exit(2)` 拦下（见上一条）。

3.1 用量七规则（2026-09-05 缔造者裁定）

实证（0905 单日）：133 个 agent 产出 274 万 token 却读了 2.02 亿缓存（74:1）——钱花在重复读同一批全文上，不是花在干活上。

**总原则**：限制的是「把任何问题都按最复杂方式做完」，不是把复杂问题做简单；**审查强度按风险定，不按预算定**——L2 该全文对抗就全文，省的是重复读、多余的镜头与反驳者、多余的轮次。**分级在前，模式在后**：ultracode 常开≠事事开 workflow（缔造者习惯常开；它的字面定义「每个实质任务都开 workflow」照做就是给每件事按最贵的价做），L0/L1 直接做，只有 L2 才开；开了也按下面七条控人数与读量。

1. **机检先行。** 哈希、数字一致性、措辞残留、编号连续、禁用字符、格式，凡能写成命令的检查先跑脚本，零 token 秒出。agent 只处理脚本查不了的：逻辑、措辞立不立得住、设计取舍。 2. **审查分级。** 派出的活按风险分三档，档位决定审不审、怎么审：

• **L0 自测闭环**：改一个函数、调配置、跑工具。执行者自测通过即交付，不触发审查。前提是**自测覆盖了改动路径**；没覆盖的自动升 L1（实锤：自测 61/61 全绿的构建在改动路径上必崩）。
• **L1 摘要审查**：加一个模块功能、修普通 bug。Fable 只读需求、架构基线、执行者 ≤300 字回传，不读执行过程。
• **L2 全文对抗**：跨模块重构、核心接口、安全或性能路径、对外发布物、进签名或哈希台账的产物。全文读，但**一个审稿人读一遍**，不是多镜头加多反驳者。

3. **反驳者配额。** 每条发现 1 个反驳者；它说"是真的"即接受，说"是假的"才加第二个复核（假反驳比假确认贵）。反驳机械类发现（数字、哈希）用 opus，判断类（措辞、逻辑）才用 fable。 4. **审查给定位。** prompt 写"看第 X 节，参照第 Y 行"，禁止默认"读全文加全部参照文档"。多镜头并行时先按镜头切分对象，重叠的发现在派出前合并。 5. **停机规则。** 一轮折入后先跑机检；只有上一轮还剩脚本查不了的判断级 blocker 才开下一轮 agent 审查，否则一个 fable 终审即止。 6. **回传上限。** 执行者只回变更清单、验证结果、决策与风险，≤300 字；工具输出、调试记录、中间上下文用完即弃，不回传。 7. **Leader 不在大上下文里逐条改大文档。** 一份文档超过十处改动，Leader 写成改动清单（定位 + 旧文 + 新文 + 理由）派一个 opus 在小上下文里执行，或整节 Write 一次；Leader 只亲手改一两处。实锤：0905 Leader 70 次 Edit 各在 40 万 token 上下文里重读，1.27 亿缓存读比子 agent 总和还多一半。

// 分级示例：L2 全文对抗 = 一个审稿人 + 每条发现一个反驳者，被反驳才二审
const findings = await agent(reviewPrompt(SECTIONS), { model: 'opus', schema: FINDINGS })   // 定位到章节
const verified = await parallel(findings.map(f => () =>
  // fable 理由: 判断类发现的对抗核验
  agent(refutePrompt(f), { model: f.mechanical ? 'opus' : 'fable', schema: VERDICT })
    .then(async v => v.refuted
      ? { ...f, votes: [v, await agent(refutePrompt(f), { model: 'fable', schema: VERDICT })] }  // fable 理由: 被反驳才二审
      : { ...f, votes: [v] })))

4. 结构化输出体量纪律（两次生产实锤）

给 agent 配 `schema` 时，prompt 里必须写**显式体量硬约束**（每字段字符上限、条目数上限、"宁可精炼不可超限"）——只靠 schema 的 `maxLength` 拦不住：agent 超限会陷入 StructuredOutput 重试循环，耗尽重试上限（5）后整路阵亡返回 `null`。

• schema 的 `maxLength` 给出安全余量；长文本产出改让 agent 直接 Write 文件，结构化输出只返摘要与路径。
• 某一路阵亡后用 resume 修复：只改失败路的 prompt，其余路 `(prompt, opts)` 不动，走缓存零成本重放。

要点

• 回写走 **MCP 工具优先**（自动项目隔离）；HTTP 兜底的端口以 `~/.claude/data/ai-team-os/api_port.txt` 为准（默认 8000，被占用时 autostart 会换端口）。