@akagilnc/pi-workflow-roles

为 Pi 打包的工作流角色：大理寺（judge）、修内司（fixer）、将作监（coder）、御史台（reviewer）、门下省（collector）、太医署（doctor）、校书郎（merger）。English: README.md。

安装

经 Pi 安装，令 CLI 与运行时同出一份包副本；把 Pi 私有 npm bin 加进 PATH（一次）：

pi install npm:@akagilnc/pi-workflow-roles
export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"

更新用 pi update npm:@akagilnc/pi-workflow-roles——勿另起全局 npm install -g。查看能力：ak-role roles、ak-role help <role>；设席位模型默认：ak-role config set judge openai-codex/gpt-5.6-sol:high；设或清持久劳务引擎（可调用角色）：ak-role config set-engine <seat> <name> / ak-role config unset-engine <seat>。

读结果

ak-role 是唯一受支持的调用方式。每次运行的完整 Terminal 结果写在 stdout——从那里读或正常重定向，不要刮 Pi session 文件：

ak-role judge --attach ./plan.md "Review this plan." > result.txt

退出码报的是生命周期诚实，不是业务成败：一切合法 typed 终态（含 audit_escalation）退出零；无合法终态的失败退出非零，其 Terminal 携带 Error Artifact 引用与原始原因，不伪造回执。

被 Codex/xAI typed HTTP 429 打断且无合法终态的运行，其失败 Terminal 内含完整 ak-role resume <runId> 命令。resume 重开同一 session；临时换模型用全局旗标。包绝不自动换 provider；只有 typed 429 可恢复；未知、已终结、并发重复的 run ID 一律拒绝。门下省、太医署为一次性，无 resume。

全局覆盖前后皆可：ak-role --model xai/grok-4.5:high resume <runId>。

每次运行游奕使自动出席，建议随同一 Terminal 给出。配置：

ak-role config set navigator openai-codex/gpt-5.6-luna:medium
# 持久劳务引擎（可调用角色；不含 navigator）；一次性覆盖仍用 --engine
ak-role config set-engine judge opus
ak-role config unset-engine judge

config set 存席位模型默认；config set-engine / unset-engine 在可调用角色上写入或清除持久劳务引擎名（与 --engine 同轴；拒收 navigator——无独立 activation）。用法与拒绝文案以公开 CLI 的 ak-role config 为准。

回执是 typed 的，调用者不必解析散文即可组合角色；顺序与停止归调用者。编程消费者从 src/package-contracts/ 导出推导契约，不从本文。

当劳务引擎绕行失败、座席回到主路继续劳务时，typed 回执可带机械字段 engineLaborFallback：{ engine, failure, laborBy: "seat" }。仅在真实绕行失败并座席顶班后出现——成功绕行或调用方 cancel 不出现。同一次 activation 内先到先得；无包内 latch 时剥离模型伪造的 engineLaborFallback 键。唯一构造点：src/engine-labor-fallback.ts；决策记录：ADR 0071。本文只投影该契约。

调用百官

公开 option 身份、别名、必填性与 mode 面以生成区 公开 CLI 选项（生成） 与 ak-role help <command> 为准——二者同源。下例只是用法速写，不是第二份旗标合同。指令对大理寺、门下省、太医署可省略，对将作监、修内司、御史台、校书郎必须非空。

# 大理寺——审断所供材料；自行推断举证责任，无 burden 旗标
ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."

# 将作监——营造新作；phase 默认 apply，或显式 plan
ak-role coder plan "Propose the first implementation plan."
ak-role coder apply --attach ./plan.md "Implement the approved slice."
# apply 强制包内 TDD 方法；勿绑 home Skill 顶替

# 御史台——固定目标双轴察举（Standards + Spec）
ak-role reviewer --base main "Review the branch."
# --base 为必填并钉住 fixed point；御史台不接受 --attach
# completed ≠ 准行——findings 在 Terminal 里

# 门下省——GitHub PR 收证；仅 github.com，需 gh 已认证；一次性
ak-role collector --pr 42 --repo owner/repository
ak-role collector --pr 42 --request-manifest ./requests.json
# 无配置时仅观察；可选 request manifest 为 {requests:[{id,body}]}；repo 默认取 origin

# 修内司——缮修所指 findings；phase 默认 apply，或显式 plan
ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
# --prerequisites 为 {id, requirement} JSON 数组；语法畸形退出 2

# 太医署——单案诊断；一次性
ak-role doctor --issue 115 "Diagnose this retained case."
# --runs 须为项目相对的 .ak-roles/books/<book>/issues/<n>/runs 且匹配 --issue

# 校书郎——雠校一个已在冲突的 merge（先用 Git ort 起动）
ak-role merger --project /path/to/worktree "Reconcile the active merge."
# 遇新意图/权限问题交回调用者，不捏造 authority

班子（唐宋官署命名）

角色按唐宋官署／官职命名，判据与被否方案见 ADR 0051。朝廷对应：皇帝＝陛下，宰相＝调用者，百官＝各角色。 工厂没有政事堂——中枢是陛下。百官各司其职，彼此制衡，共同完成从谋划、建设、审查到收敛的完整流程。

只是名字。 ak-role <name> 的角色标识符以及工具名与 schema 字段一律使用下表席位列的英文名；中文名只是呈现层称谓。

| 名号 | 席位 | 职掌 | | --- | --- | --- | | 将作监 | coder | 营造新作。 承接新的谋划与需求，从一片空白开始设计、建造，直到形成可供使用的新成果。讲究先明其意，再定其形，不妄增枝节，只做当下所需之事。 | | 修内司 | fixer | 缮修旧物。 面对已有问题，不急于表面修补，而是追寻问题根源，找到真正需要修整之处。既要修复眼前缺漏，也要防止同类问题再次出现。 | | 御史台 | reviewer | 察举百弊。 置身事外，以旁观之眼审视成果，寻找其中的不妥、遗漏与隐患。只负责指出问题、陈明依据，不参与修改，也不替人作最终判断。 | | 大理寺 | judge | 审理定谳。 承接各方意见与材料，依照既定规则逐项判断，辨明是非曲直。可以准行、退回或请示更高决定，但自身不参与建设与修改。 | | 审刑院 | judge-auditor／reviewer-auditor（无 CLI，共享内部接缝） | 复核成案。 不重新争论事情本身，而是检查整个办理过程是否合乎规矩。关注是否有人越过职责、是否遗漏必要步骤、是否以错误方式得出正确结果。 | | 门下省 | collector | 承接百议。 位于决策之前，收集各方反馈与意见，确认事情是否已经具备继续推进的条件。它不替人裁决，只负责让信息完整、状态清楚。 | | 校书郎 | merger | 雠校异文。 面对不同来源的修改，负责整理、校合与调和。保留双方有价值的部分，解决彼此冲突；遇到无法自行决定之处，则留待重新裁量。 | | 游奕使 | navigator（无 CLI，自动出席） | 巡行问路。 不掌具体事务，而是观察全局变化，结合当前局面提醒下一步方向。它提供建议与路径参考，但最终选择仍由执掌之人决定。 |

其余席位：

| 席位 | 名 | 职掌 | 状态 | | --- | --- | --- | --- | | doctor | 太医署 | 单案诊断工厂机制，开 keep｜thin｜delete 方 | 已建 | | — | 司天台 | 记候簿——只打点、只指针，不分析不执法 | 一期不是角色（ADR 0047：零 LLM 双面对账）；席位形态属 #67 素材，未定 | | — | 兰台 | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建（#67 两席之一） | | — | 考功司 | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，不属 #67，需要时另立票 | | — | 主簿 | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |

merge 按钮归调用者，没有任何角色握不可逆权限：门下省把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。

上表不规定调用顺序——组合、顺序、重复次数归调用者（ADR 0010）。御史台／大理寺／审刑院是职责分立的类比，不是必经链；审刑院也并非只跟在大理寺之后，大理寺、御史台、太医署各自都有一次。

拾遗补阙 成对留档，待将来出现第二个进言席再启用。

Codex fast 档

开启：echo "fast_mode = on" > ~/.pi-codex-fast；关闭：echo "fast_mode = off" > ~/.pi-codex-fast（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。

公开 CLI 选项（生成）

本表由 src/public-cli/option-definitions.ts 生成；以 ak-role help <command> 为准。勿手改本区。

global

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --model | — | provider/model | 否 | 否 | option | — | 覆盖本调用有效席位模型（可置于子命令前或后）。 | | --thinking | — | level | 否 | 否 | option | — | 覆盖 thinking 档位：off|minimal|low|medium|high|xhigh|max。 | | --engine | — | name | 否 | 否 | option | — | 本调用可选劳动引擎（池令名字；有包内调法笔记则附卷；全部角色可用）。 | | --help | -h | — | 否 | 否 | option | — | 显示公开 CLI 帮助并退出。 |

judge

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |

coder

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | plan\|apply | plan, apply | — | 否 | 否 | positional | phases=plan|apply; default=apply | 指令前可选 phase 词元；默认 apply。 | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |

fixer

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | plan\|apply | plan, apply | — | 否 | 否 | positional | phases=plan|apply; default=apply | 指令前可选 phase 词元；默认 apply。 | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 | | --prerequisites | — | path | 否 | 否 | option | — | {id, requirement} 前置条件 JSON 数组路径。 |

reviewer

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --base | — | revision | 是 | 否 | option | — | 必填；钉住审查目标的 fixed-point revision。 | | --authority-ref | — | ref | 否 | 是 | option | — | 持久 authority 引用/URL（可重复；仅 ref，非内联散文）。 |

collector

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 | | --pr | — | number | 是 | 否 | option | — | 必填；正整数 GitHub PR 号。 | | --repo | — | owner/repo | 否 | 否 | option | — | GitHub owner/repo 覆盖（默认取 github.com origin）。 | | --request-manifest | — | path | 否 | 否 | option | — | 可选 request manifest JSON 路径（{requests:[{id,body}]}）。 |

doctor

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --project | — | path | 否 | 否 | option | — | 卷宗身份用的项目根（默认进程 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 | | --issue | — | number | 是 | 否 | option | — | 必填；留存病例的正整数 issue 号。 | | --runs | — | path | 否 | 否 | option | — | 可选项目相对 .ak-roles/books//issues//runs 覆盖，且须匹配 --issue。 |

merger

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | --project | — | path | 否 | 否 | option | — | 已有进行中 ordinary merge 的项目根（默认 cwd）。 | | --attach | — | path | 否 | 是 | option | — | 附加普通文件；受理即冻结（可重复）。 |

taishi

| 拼写 | 别名 | 值 | 必填 | 可重复 | 形式 | 模式/阶段 | 说明 | | --- | --- | --- | --- | --- | --- | --- | --- | | sweep | — | — | 否 | 否 | positional | modes=sweep | 可选 sweep 模式词元（至多一次；不得夹带其他 positional）。 | | --ticket | — | number | 否 | 否 | option | modes=issue | 票号；在 cwd 候簿（git common-dir）内按 invocation.ticketNumber 现取现算。裸调用=整簿。不依赖 library-index 自举。 | | --attach | — | path | 条件:sweep | 是 | option | modes=sweep; max=sweep:1 | sweep 模式附件路径；sweep 必填且恰一次；载荷为附件正文。 | | --cohort | — | — | 否 | 否 | option | modes=cohort | 选择 cohort 模式。 | | --group-a-label | — | label | 条件:cohort | 否 | option | modes=cohort | cohort A 组标签（cohort 模式必填）。 | | --group-a-issues | — | N[,N...] | 条件:cohort | 否 | option | modes=cohort | cohort A 组逗号分隔正整数 issue 列表（cohort 模式必填）。 | | --group-b-label | — | label | 条件:cohort | 否 | option | modes=cohort | cohort B 组标签（cohort 模式必填）。 | | --group-b-issues | — | N[,N...] | 条件:cohort | 否 | option | modes=cohort | cohort B 组逗号分隔正整数 issue 列表（cohort 模式必填）。 |