@akagilnc/pi-workflow-roles
为 Pi 打包的工作流角色：大理寺（judge）、给事中（countersign）、中书省（secretariat）、左拾遗（gleaner-left）、修内司（fixer）、将作监（coder）、御史台（reviewer）、通进司（collector）、太医署（doctor）、校书郎（merger）、符宝郎（notary）、台院（inspector）、太史（analyst）。English: README.md。
安装
安装约定见 ADR 0052。操作示例：
pi install npm:@akagilnc/pi-workflow-roles
export PATH="$HOME/.pi/agent/npm/node_modules/.bin:$PATH"
更新示例：pi update npm:@akagilnc/pi-workflow-roles。查看能力：ak-role roles、ak-role help <role>；席位与官席配置见下方「读结果」。
发布路由见 registry workflow。
读结果
公开入口与结果交付见 ADR 0052。重定向示例：
ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review this plan." > result.txt
--attach、修内司 --prerequisites 与通进司 --request-manifest 把调用方路径原样写进衙门第一句话。包不读、不复制、不校验；调用方当前目录与 --project 不同时请给绝对路径（ADR 0087）。
退出码与 Terminal 语义见 ADR 0052、Terminal 实现。
手动续跑用法与旗位见 ak-role help resume；model / host 解析见 ak-role help，engine 配置见 ak-role help config。审核续跑归属见 ADR 0003。换宿主与先前记录递送见 ADR 0086。续跑失败处置见 公开执行接缝。headless 回合启动材料目录在宿主终局之后（或 setup 失败已抛出之旁）清理失败时，经 package-fault 保留真因后继续，不另造宿主失败、也不改写已形成的终局（见 headless 宿主）。
自动续跑行为见 auto-resume 实现；配置用法见 ak-role help config，有效上限用 ak-role config show 查看。
催交与实发次数记账（#1132）见 角色运行时、回执递送策略、外部宿主循环。unfinished 缺理由处置见 ADR 0050。
收卷与票号： 所有宿主都不另开补报票号轮。pi、grok-build、hermes 的未绑定腿收卷后，工具回话会问票号；卷已收下，不必重交，知道就调 ak_report_ticket，不知道就结束本轮。已绑定或交卷自带 ticketNumber 时照旧收卷即结束。同轮再次交卷照收，最新一份成为结论。claude（--json-schema）、codex（--output-schema）的原生结构化输出交卷即结束，无法插入收卷回话；只靠交卷 ticketNumber 字段与随时可调的 ak_report_ticket，漏报留在 unbound，不补适配层。
席位与官席配置：
ak-role config set judge <provider/model[:thinking]>
# 官席配置示例
ak-role config set gatekeeper <provider/model[:thinking]>
ak-role config set inspector <provider/model[:thinking]>
ak-role config set notary <provider/model[:thinking]>
ak-role config unset gatekeeper
# 引擎配置示例
ak-role config set-engine judge claude-code
ak-role config set-engine coder cursor cursor-grok-4.6-high
ak-role config set-engine-model coder cursor-grok-4.6-high
ak-role config unset-engine-model coder
ak-role config unset-engine judge
# 宿主配置示例
ak-role config set-host judge grok-build
ak-role config unset-host judge
ak-role config set-auto-resume-limit 3
宿主轴： 用法与解析见 ak-role help；机构边界见 ADR 0082。宿主推荐与原生压缩配置见 #971。
宿主 provider： 见 ak-role help 与 provider 解析；表内容用 ak-role config show 查看。
机器方法 Skill： 运行 ak-role setup；安装行为见 机器 Skill setup、ADR 0052；宿主能力见 Pi Skill 递送、外部 host 描述。
官席解析： 见 机构解析；配置用法见 ak-role help config，持久文件读取见 config 实现。
回执： 见 导出契约；游奕使不调模型，建议取自 路线表；调用面见 ak-role help navigator。组合与停止见 ADR 0010。
交卷闸： 见 ADR 0079、交卷闸实现、worker 审核组合、judge 审核组合。劳务引擎失败处置见 ADR 0071，使用量观测见 usage fact 真源。
调用百官
下例只是用法速写；option 身份、别名、必填性与 mode 面以 ak-role help <command> 为准，不另立第二份旗标合同。
# model 用法见 ak-role help
# 大理寺
ak-role judge --model <provider/model[:thinking]> --attach ./findings.md --attach ./adr.md "Adjudicate every finding."
# 将作监
ak-role coder --model <provider/model[:thinking]> plan "Propose the first implementation plan."
ak-role coder --model <provider/model[:thinking]> apply --attach ./plan.md "Implement the approved slice."
# 御史台
ak-role reviewer --model <provider/model[:thinking]> --base main --authority-ref docs/adr/0001-roles-grow-by-demand.md "Review the branch."
# 可选单 lens 覆盖
ak-role reviewer --model <provider/model[:thinking]> --base main --lens correctness --authority-ref CLAUDE.md
# 通进司
ak-role collector --model <provider/model[:thinking]> --pr 42 --repo owner/repository "为所指 issue 收证。"
ak-role collector --model <provider/model[:thinking]> --repo owner/repository "为 #42 收证。"
ak-role collector --model <provider/model[:thinking]> --pr 42 --request-manifest ./requests.json "带具名请求正文收证。"
# 修内司
ak-role fixer --model <provider/model[:thinking]> --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."
# 太医署
ak-role doctor --model <provider/model[:thinking]> --issue 115 "Diagnose this retained case."
# 校书郎
ak-role merger --model <provider/model[:thinking]> --project /path/to/worktree "Reconcile the merge."
# 符宝郎——以 source-run locator 直调；职掌见 souls/notary.md
ak-role notary --model <provider/model[:thinking]> --source-run <runId@role|path>
# 台院
ak-role inspector --model <provider/model[:thinking]> --attach ./change.patch "Review this material."
# 门下省
ak-role gatekeeper --model <provider/model[:thinking]> --attach ./submission.json "审：这批材料该谁审？"
# 游奕使
ak-role navigator # 整张路线表（不调模型）
ak-role navigator --role coder # 只看某衙门的几行
# 起居郎请求示例；方法见 resources/diarist-collect.md
ak-role diarist --model <provider/model[:thinking]> "整理 #582 自上次成录以来的御话。"
# 多票请求示例
ak-role diarist --model <provider/model[:thinking]> "整理 #582、#583 自上次成录以来的御话，分别成录。"
# 给事中
ak-role countersign --model <provider/model[:thinking]> --attach ./ticket.md "裁：本票 #582 是否足以开工。"
# 中书省
ak-role secretariat --model <provider/model[:thinking]> "审 #924 票面的设计。"
# 左拾遗
ak-role gleaner-left --model <provider/model[:thinking]> --base main
# 太史
ak-role analyst
# 续跑请求示例；审核续跑归属见 ADR 0003
ak-role --model <provider/model[:thinking]> resume <runId> "<裁定>"
测试
聚焦命令与报告位置见 Tests。
班子（唐宋官署命名）
名号与本厂术语的正名见 GLOSSARY.md；名号判据、朝廷对应与机器键边界见 ADR 0051。下表为名号索引。
| 名号 | 席位 | 职掌 |
|---|---|---|
| 将作监 | coder | 职掌见 Soul。 |
| 修内司 | fixer | 职掌见 Soul。 |
| 御史台 | reviewer | 职掌见 Soul；调用面见 ak-role help reviewer。 |
| 大理寺 | judge | 职掌见 Soul。 |
| 审刑院 | auditor（调用面见 ak-role help auditor） | 依受审对象读取 大理寺审计 Soul／太医署审计 Soul。 |
| 门下省 | gatekeeper | 职掌见 Soul；独立调用见 ak-role help gatekeeper，交卷闸关系见 ADR 0079。 |
| 中书省 | secretariat | 职掌见 Soul；调用面见 ak-role help secretariat。 |
| 给事中 | countersign | 职掌见 Soul；调用面见 ak-role help countersign。 |
| 左拾遗 | gleaner-left | 职掌见 Soul；调用面见 ak-role help gleaner-left。 |
| 台院 | inspector | 职掌见 Soul；调用面见 ak-role help inspector，名号沿革见 ADR 0074 与 #584。 |
| 符宝郎 | notary | 职掌见 Soul；调用面见 ak-role help notary。 |
| 通进司 | collector | 职掌见 Soul。 |
| 校书郎 | merger | 职掌见 Soul。 |
| 游奕使 | navigator | 非模型查表席位：按衙门结局给一句建议，表见 路线表；调用面见 ak-role help navigator。 |
| 起居郎 | diarist | 职掌见 Soul；调用面见 ak-role help diarist。 |
其余席位：
| 席位 | 名 | 职掌 | 状态 |
|---|---|---|---|
| doctor | 太医署 | 职掌见 Soul；调用面见 ak-role help doctor。 | 待设计（2026-10-08 陛下：留着、以后重新设计；现行卷宗改造不为它保读者） |
| analyst | 太史 | 职掌见 ADR 0068；调用面见 ak-role help analyst。 | 待设计（留着、以后重新设计；现行卷宗改造不为它保读者。原已建：ADR 0068；机器面键 analyst，#445 拼音清零） |
| — | 司天台 | 职掌见 ADR 0047、ADR 0065。 | 一期不是角色（ADR 0047：确定性机制；两面对账已删 #855）；分析席已由太史承担；起居录见 ADR 0075；机器面键 archivist（#445） |
| marshal | 尚书省 | 审→判→修 质量收敛环的省部级驱动角色：调用方递票号与 baseline，尚书省驱动御史台/大理寺/修内司滚到收敛（converged 唯庭可判）或 escalate 上呈，交回 typed 报告；不弹、不判、不修，只让链条转到收敛 | 已定名（#145）；席位待落地（#146） |
| — | 殿院 | #560 机械定点测试巡查件（产物 kind test-report） | 在建/待落地，非席位，不占机器键 |
| — | 察院 | 巡按层名号占位 | 悬置，仅保留名号，巡按机制未建 |
| — | 兰台 | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建 |
| — | 考功司 | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，需要时另立票 |
| — | 主簿 | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |
merge 按钮归调用者，没有任何角色握不可逆权限：通进司把收证这件苦活做完并报收集终态，人（或 AI）自己判断、自己点，点完想调主簿就调、不调也可以。
角色组合、调用顺序、停止与内审关联见 ADR 0010；通进司职责见 Soul。
拾遗补阙 成对留档，待将来出现第二个进言席再启用。
规范指针
- 命令用法、解析与拒绝文案：
ak-role help、ak-role help <command>、ak-role help config（唯一权威）。 - 决策与法理：docs/adr/（组合与顺序 ADR 0010、公开 CLI 面 ADR 0052、交卷闸 ADR 0066/0067/0070/0072、劳务引擎 ADR 0069/0071、起居录 ADR 0075 等，未尽举）。
- 术语表：CONTEXT.md。编程契约：
src/package-contracts/导出。