# @akagilnc/pi-workflow-roles 中文文档

规范地址：https://npmcn.com/package/%40akagilnc/pi-workflow-roles/

版本：0\.1\.6100
npm 元数据更新时间：2026-11-02T00:35:07.138Z
中文译文更新时间：2026-11-05T21:23:07.729Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40akagilnc/pi-workflow-roles
原文对照：https://npmcn.com/package/%40akagilnc/pi-workflow-roles/?lang=original
项目主页：https://github.com/Akagilnc/ak-pi-workflow-roles#readme
源码仓库：https://github.com/Akagilnc/ak-pi-workflow-roles

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.6 MB，431 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：1 个
- peer 依赖：@earendil-works/pi-ai \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-08-12T00:50:56.545Z
- 最新版本发布：2026-11-02T00:35:06.837Z
- 近 30 天下载量：18568（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：529（近 12 个月 529 个）

## 中文简介

Pi 的自定义工作流程角色

## 安装

```sh
npm install @akagilnc/pi-workflow-roles
```

也可以使用：`pnpm add @akagilnc/pi-workflow-roles`、`yarn add @akagilnc/pi-workflow-roles`、`bun add @akagilnc/pi-workflow-roles`

## README

# @akagilnc/pi-workflow-roles

为 [Pi](https://pi.dev/) 打包的工作流角色：大理寺（judge）、给事中（countersign）、中书省（secretariat）、左拾遗（gleaner-left）、修内司（fixer）、将作监（coder）、御史台（reviewer）、通进司（collector）、太医署（doctor）、校书郎（merger）、符宝郎（notary）、台院（inspector）、太史（analyst）。English: [README.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.md)。

## 安装

安装约定见 [ADR 0052](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0052-public-cli-is-the-only-supported-external-role-interface.md)。操作示例：

```bash
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](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/.github/workflows/publish-registry.yml)。

## 读结果

公开入口与结果交付见 [ADR 0052](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0052-public-cli-is-the-only-supported-external-role-interface.md)。重定向示例：

```bash
ak-role judge --model <provider/model[:thinking]> --attach ./plan.md "Review this plan." > result.txt
```

`--attach`、修内司 `--prerequisites` 与通进司 `--request-manifest` 把调用方路径原样写进衙门第一句话。包不读、不复制、不校验；调用方当前目录与 `--project` 不同时请给绝对路径（[ADR 0087](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/docs/adr/0087-package-routes-and-passes-through-code-hands-no-paths.md)）。

退出码与 Terminal 语义见 [ADR 0052](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0052-public-cli-is-the-only-supported-external-role-interface.md)、[Terminal 实现](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/terminal.ts)。

手动续跑用法与旗位见 `ak-role help resume`；model / host 解析见 `ak-role help`，engine 配置见 `ak-role help config`。审核续跑归属见 [ADR 0003](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0003-per-role-submission-tools.md)。换宿主与先前记录递送见 [ADR 0086](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0086-host-dossier-is-native-file-copy-sitian-append-only.md)。续跑失败处置见 [公开执行接缝](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/post-admission.ts)。headless 回合启动材料目录在宿主终局之后（或 setup 失败已抛出之旁）清理失败时，经 package-fault 保留真因后继续，不另造宿主失败、也不改写已形成的终局（见 [headless 宿主](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/headless-host/role-turn-host.ts)）。

自动续跑行为见 [auto-resume 实现](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/auto-resume.ts)；配置用法见 `ak-role help config`，有效上限用 `ak-role config show` 查看。

催交与实发次数记账（#1132）见 [角色运行时](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/role-runtime.ts)、[回执递送策略](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/receipt-delivery-policy.ts)、[外部宿主循环](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/external-host-turn-loop.ts)。unfinished 缺理由处置见 [ADR 0050](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0050-unfinished-terminal-state-reports-fact-not-diagnosis.md)。

**收卷与票号：** 所有宿主都不另开补报票号轮。pi、grok-build、hermes 的未绑定腿收卷后，工具回话会问票号；卷已收下，不必重交，知道就调 `ak_report_ticket`，不知道就结束本轮。已绑定或交卷自带 `ticketNumber` 时照旧收卷即结束。同轮再次交卷照收，最新一份成为结论。claude（`--json-schema`）、codex（`--output-schema`）的原生结构化输出交卷即结束，无法插入收卷回话；只靠交卷 `ticketNumber` 字段与随时可调的 `ak_report_ticket`，漏报留在 unbound，不补适配层。

席位与官席配置：

```bash
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](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0082-three-layer-runtime-role-host-face.md)。宿主推荐与原生压缩配置见 [#971](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/971)。

**宿主 provider：** 见 `ak-role help` 与 [provider 解析](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/host-providers.ts)；表内容用 `ak-role config show` 查看。

**机器方法 Skill：** 运行 `ak-role setup`；安装行为见 [机器 Skill setup](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/machine-method-skills.ts)、[ADR 0052](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0052-public-cli-is-the-only-supported-external-role-interface.md)；宿主能力见 [Pi Skill 递送](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/pi/role-turn-host.ts)、[外部 host 描述](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/host-descriptions.ts)。

**官席解析：** 见 [机构解析](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/institutional-resolution.ts)；配置用法见 `ak-role help config`，持久文件读取见 [config 实现](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/public-cli/config.ts)。

**回执：** 见 [导出契约](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/package-contracts/)；游奕使不调模型，建议取自 [路线表](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/navigator-route-table.ts)；调用面见 `ak-role help navigator`。组合与停止见 [ADR 0010](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0010-callers-own-role-composition-and-repetition.md)。

**交卷闸：** 见 [ADR 0079](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0079-direct-officer-summons-ticket-memory-pointer-input.md)、[交卷闸实现](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/submission-gate.ts)、[worker 审核组合](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/worker-role.ts)、[judge 审核组合](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/judge-role.ts)。劳务引擎失败处置见 [ADR 0071](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0071-engine-detour-failure-seat-fallback-declaration.md)，使用量观测见 [usage fact 真源](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/engine-detour-usage.ts)。

## 调用百官

下例只是用法速写；option 身份、别名、必填性与 mode 面以 `ak-role help <command>` 为准，不另立第二份旗标合同。

```bash
# 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](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/README.md#tests)。

## 班子（唐宋官署命名）

名号与本厂术语的正名见 [GLOSSARY.md](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/GLOSSARY.md)；名号判据、朝廷对应与机器键边界见 [ADR 0051](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0051-roles-are-named-after-tang-song-offices.md)。下表为名号索引。

| 名号 | 席位 | 职掌 |
| --- | --- | --- |
| **将作监** | coder | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/coder.md)。 |
| **修内司** | fixer | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/fixer.md)。 |
| **御史台** | reviewer | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/reviewer.md)；调用面见 `ak-role help reviewer`。 |
| **大理寺** | judge | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/judge.md)。 |
| **审刑院** | auditor（调用面见 `ak-role help auditor`） | 依受审对象读取 [大理寺审计 Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/judge-auditor.md)／[太医署审计 Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/doctor-auditor.md)。 |
| **门下省** | gatekeeper | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/gatekeeper.md)；独立调用见 `ak-role help gatekeeper`，交卷闸关系见 [ADR 0079](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0079-direct-officer-summons-ticket-memory-pointer-input.md)。 |
| **中书省** | secretariat | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/secretariat.md)；调用面见 `ak-role help secretariat`。 |
| **给事中** | countersign | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/countersign.md)；调用面见 `ak-role help countersign`。 |
| **左拾遗** | gleaner-left | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/gleaner-left.md)；调用面见 `ak-role help gleaner-left`。 |
| **台院** | inspector | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/inspector.md)；调用面见 `ak-role help inspector`，名号沿革见 [ADR 0074](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0074-gate-province-reorg-jishizhong-chaiyuan-split.md) 与 [#584](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/584)。 |
| **符宝郎** | notary | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/notary.md)；调用面见 `ak-role help notary`。 |
| **通进司** | collector | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/collector.md)。 |
| **校书郎** | merger | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/merger.md)。 |
| **游奕使** | navigator | 非模型查表席位：按衙门结局给一句建议，表见 [路线表](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/src/navigator-route-table.ts)；调用面见 `ak-role help navigator`。 |
| **起居郎** | diarist | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/diarist.md)；调用面见 `ak-role help diarist`。 |

其余席位：

| 席位 | 名 | 职掌 | 状态 |
| --- | --- | --- | --- |
| doctor | **太医署** | 职掌见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/doctor.md)；调用面见 `ak-role help doctor`。 | 待设计（2026-10-08 陛下：留着、以后重新设计；现行卷宗改造不为它保读者） |
| analyst | **太史** | 职掌见 [ADR 0068](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0068-taishi-analysis-seat-reads-records-writes-sibling-home.md)；调用面见 `ak-role help analyst`。 | 待设计（留着、以后重新设计；现行卷宗改造不为它保读者。原已建：[ADR 0068](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0068-taishi-analysis-seat-reads-records-writes-sibling-home.md)；机器面键 `analyst`，[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445) 拼音清零） |
| — | **司天台** | 职掌见 [ADR 0047](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0047-sitian-phase-one-mechanism-not-role.md)、[ADR 0065](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0065-sitian-phase-two-records-have-one-entry.md)。 | **一期不是角色**（[ADR 0047](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0047-sitian-phase-one-mechanism-not-role.md)：确定性机制；两面对账已删 [#855](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/855)）；分析席已由太史承担；起居录见 [ADR 0075](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0075-ticket-provenance-diarist-pipeline.md)；机器面键 `archivist`（[#445](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/445)） |
| marshal | **尚书省** | 审→判→修 质量收敛环的省部级驱动角色：调用方递票号与 baseline，尚书省驱动御史台/大理寺/修内司滚到收敛（converged 唯庭可判）或 escalate 上呈，交回 typed 报告；不弹、不判、不修，只让链条转到收敛 | 已定名（#145）；席位待落地（#146） |
| — | **殿院** | [#560](https://github.com/Akagilnc/ak-pi-workflow-roles/issues/560) 机械定点测试巡查件（产物 kind `test-report`） | 在建/待落地，非席位，不占机器键 |
| — | **察院** | 巡按层名号占位 | 悬置，仅保留名号，巡按机制未建 |
| — | **兰台** | 读档议制——耗时／缺口／冗余三条，上奏不执法 | 未建 |
| — | **考功司** | 考具体效率——角色与档位的升档率、一次通过率、每票成本 | 留档，需要时另立票 |
| — | **主簿** | 合并后勾稽销案：核实确已合上、清理残留、报到达 | 未建 |

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

角色组合、调用顺序、停止与内审关联见 [ADR 0010](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/docs/adr/0010-callers-own-role-composition-and-repetition.md)；通进司职责见 [Soul](https://npmcn.com/package/%40akagilnc/pi-workflow-roles/souls/collector.md)。

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

## 规范指针

-   命令用法、解析与拒绝文案：`ak-role help`、`ak-role help <command>`、`ak-role help config`（唯一权威）。
-   决策与法理：[docs/adr/](https://github.com/Akagilnc/ak-pi-workflow-roles/tree/main/docs/adr)（组合与顺序 ADR 0010、公开 CLI 面 ADR 0052、交卷闸 ADR 0066/0067/0070/0072、劳务引擎 ADR 0069/0071、起居录 ADR 0075 等，未尽举）。
-   术语表：[CONTEXT.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/CONTEXT.md)。编程契约：`src/package-contracts/` 导出。

## 常见问题

### @akagilnc/pi-workflow-roles 是什么？

Pi 的自定义工作流程角色

### 如何安装 @akagilnc/pi-workflow-roles？

在项目目录运行 npm install @akagilnc/pi-workflow-roles，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ak-role，可以用 npx ak-role 直接运行。

### @akagilnc/pi-workflow-roles 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/akagilnc\_\_pi-workflow-roles 是否存在。

### @akagilnc/pi-workflow-roles 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @akagilnc/pi-workflow-roles 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @akagilnc/pi-workflow-roles 可以商用吗？

@akagilnc/pi-workflow-roles 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @akagilnc/pi-workflow-roles 的下载量有多少？

根据 npm 官方下载统计，@akagilnc/pi-workflow-roles 在 2026/10/05 – 2026/11/03 这 30 天内被下载 18,568 次，日均约 619 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @akagilnc/pi-workflow-roles 还在维护吗？

最新版本 0\.1\.6100 发布于 2026/11/02（4 天前）；至今共发布 529 个版本，其中过去 12 个月发布了 529 个；首次发布于 2026/08/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。