中文 | English

claude-workflow

一个为 Pi 打造的工作流层，在不改动 Pi 核心的前提下，复刻 Claude-Code 式编码代理的实用机制——只读规划、隔离探索、独立验证，以及命令安全门。它完全以 Pi 扩展包的形式交付：一段提示词 overlay、四个命令、一个委派工具、三个内置子代理，以及一个 tool_call 安全门，全部通过 Pi 的公开扩展 API 接入。

本包实现的是这些工作流的行为模式，并不复制 Claude Code 的源码或提示词原文。

安全门是工作流护栏，不是沙箱。 它降低了 agent 发起的命令造成破坏的概率，但并不隔离进程。它不能替代操作系统级或容器级隔离，也不作任何安全保证。参见已知局限。

环境要求

• Pi (@hhyy668/pi-coding-agent) 0.80.x. The extension API contract was verified against pi commit 6d3cc89fdf8854417f1099da003a80ea848907b7 / CLI 0.80.4.
• Node.js >= 22.19.0.
• A configured model provider with a working API key. The commands that spawn subagents (/cw:explore, /cw:verify, /cw:workflow, and the cw_subagent tool) each launch a child pi process that needs a provider; without a key they return a clear configuration error.

安装

Pi 通过读取包 package.json 里的 pi manifest 字段来发现一个包。本包声明：

"pi": {
  "extensions": ["./extensions/claude-workflow/index.ts"],
  "prompts": ["./prompts"]
}

因此无论你以哪种方式让 Pi 感知到本包，它都会从该 manifest 加载扩展入口与提示词模板。有三种方式。

1. 作为已安装的包（npm，推荐）

安装后 Pi 会把它记入你的设置，并在每次运行时加载：

# from npm (once published)
pi install npm:@hhyy668/claude-workflow-for-pi

# project-local instead of user-global: add -l
pi install npm:@hhyy668/claude-workflow-for-pi -l

Pi installs the package, reads its pi manifest, and registers the extension and prompts. Remove it later with pi remove npm:@hhyy668/claude-workflow-for-pi (alias pi uninstall).

2. 从克隆目录，用 -e 直接加载

适合开发，以及在不写入设置的情况下试用本包。克隆仓库、安装开发依赖，再把 Pi 指向扩展入口文件：

git clone https://gitee.com/hhyy668/claude-workflow-for-pi.git
cd claude-workflow-for-pi
npm install
pi -e ./extensions/claude-workflow/index.ts

-e/--extension 只为该会话加载单个扩展，不会持久化到设置。（以这种方式加载入口文件，会注册扩展及其自带的 agents/ 与 prompts/，它们相对自身位置解析。）

3. 软链接到 agent 扩展目录

Pi 会自动发现放在其 agent 配置目录下的扩展。把本包（或仅扩展目录）软链接到 ~/.pi/agent/extensions/，Pi 启动时便会加载：

ln -s "$(pwd)/extensions/claude-workflow" ~/.pi/agent/extensions/claude-workflow

以上任一方式下，可通过确认 /cw:plan、/cw:explore、/cw:verify、/cw:workflow 命令出现在 Pi 的命令列表中，来验证扩展已加载。

命令

/cw:plan —— 只读规划模式

切换只读规划模式。进入时它会快照你当前激活的工具，禁用 edit/write，把 bash 限制为只读命令（安全门切换到更严策略），并注入规划指令，要求模型调查代码并产出单一编号计划。它跨回合监测计划：澄清提问的回合会静默保持规划；包含编号计划的回合会（在 UI 模式下）弹出 执行 / 精炼 / 保持 菜单。

子命令：

| 调用 | 效果 | | ------------------ | ------------------------------------------------- | | /cw:plan | 切换规划模式开/关。计划执行期间，改为显示进度而非切换。 | | /cw:plan execute | 执行最近检测到的计划（恢复工具、离开规划模式、入队实现提示）。在菜单不可用的非 UI 模式下有用。 | | /cw:plan end | 停止执行跟踪。从未被标记 [DONE:n] 的步骤记为 unknown。 | | /cw:plan status | 显示当前规划模式状态与逐步进度。 | | /cw:plan help | 显示内置帮助，含工具快照的注意事项。 |

精炼作为交互式计划菜单里的一个选项提供（它会询问一条可选的修改说明，并在保持规划模式的同时请求修订后的计划）；它是菜单动作，而非 /cw:plan 子命令。

一旦你选择执行，入队的实现提示会要求主 agent 在完成计划步骤 n 后于单独一行打印 [DONE:n]；扩展解析这些标记来跟踪进度。缺失或格式错误的标记只会把对应步骤降级为 unknown——绝不会中断跟踪。

计划状态会被持久化，并在会话 resume/fork 时恢复，因此恢复后的会话回来时，写工具仍处于禁用状态，直到你退出规划模式。

/cw:explore <task>

在子 pi 进程中运行一个隔离的、只读的 explore 子代理，为 <task> 做快速代码库侦察。它向你展示一份简洁报告，并把该报告作为隐藏上下文消息注入对话，这样主模型在后续回合无需你粘贴任何内容即可使用这些发现。子进程只读（read/grep/find/ls 加只读 bash）；命令本身不触发主模型回合。

/cw:verify [scope]

对给定范围（默认：你当前未提交的改动）运行一个隔离的、只读的 verifier 子代理。verifier 在只读写策略下采集命令证据并返回一个 verdict：

• PASS —— 它能运行的只读检查（如 tsc --noEmit、不带 --fix 的 eslint、git diff/status/log）足以证明工作成立。
• FAIL —— 某项检查证明了具体缺陷，并附失败的命令与输出。
• PARTIAL —— 某项有意义的检查被写策略阻塞或工具缺失；被阻塞/缺失的检查会列出，供你自行运行。

在本 MVP 中，PARTIAL 是预期的、正常的结果。 verifier 不可写入你的项目树，因此写类检查（npm test、构建、装包、快照更新）在项目树内被阻塞并报告为被阻塞。/cw:verify help 会完整打印这些说明。确需临时脚本时，它们被限定在操作系统临时目录内。

/cw:workflow <task>

在子进程中运行 MVP 链 explore → planner：一个探索代理勘察代码，一个规划代理把发现转成有序的实现计划。在 UI 模式下，它随后会为主 agent 入队一条包含该计划的实现提示作为 follow-up——MVP 中子进程从不编辑文件，因此实现发生在你的主会话里，之后你用 /cw:verify 验证。在不支持 follow-up 投递的模式下，它展示计划并把后续交给你。

cw_subagent 工具

一个由主 agent 调用的工具（不是命令），用于把工作委派给同样隔离的只读子代理。三种模式，每次调用恰好用一种：

• single —— { agent, task }：一个代理，一个任务。
• parallel —— { tasks: [{ agent, task }, ...] }：独立任务并发运行（并发上限 4）。
• chain —— { chain: [{ agent, task }, ...] }：顺序步骤，每个任务可通过 {previous} 占位符引用上一步的输出（若无占位符，则自动追加）。

子代理不能修改文件，也不能再委派（最大委派深度为 1），它们返回文本报告。可用代理为下面的内置代理。

内置代理

代理定义是带 YAML frontmatter 的 Markdown 文件，随包置于 agents/，并相对本包解析（用户/项目级代理发现不在 MVP 范围内）。

| 代理 | 角色 | 工具 | | ---------- | ----------------------------------------------- | ------------------------------- | | explore | 快速只读侦察；报告文件、符号、发现。 | read, grep, find, ls, 只读 bash | | planner | 把任务 + 发现转成带风险与关键文件清单的有序计划。 | read, grep, find, ls（有意不含 bash） | | verifier | 通过运行只读检查独立验证工作；报告证据与 PASS/FAIL/PARTIAL verdict。 | read, grep, find, ls, 只读 bash | | worker | 全能力实现代理。随包禁用——MVP 绝不让子进程编辑文件。 | （禁用） |

安全门

扩展安装一个 tool_call 处理器，把 agent 发起的 bash、edit、write 调用分成三档：

• allow —— 放行。
• confirm —— UI 模式下弹确认；非 UI 模式 fail closed（带原因阻塞，而非静默放行或挂起等待）。
• block —— 直接拒绝，并附一条消息告诉你：若确实想执行，可自己在 shell 里手动运行。

它覆盖递归/宽泛删除、丢弃未提交工作或改写 git 状态、外发（push、PR/issue 活动）、写入受保护文件（.env、凭据文件、.git/、node_modules/、lockfile），以及装包。规划模式应用更严策略（重定向、heredoc、文件创建、装包、git 写、杀进程均被阻塞）。子代理在角色专属策略下运行：verifier 子代理只能在操作系统临时目录里写临时脚本；explore/planner/未知角色严格只读。

已知局限

• PARTIAL 是 /cw:verify 的正常 verdict。 由于写类检查（测试、构建、装包）在项目树内被阻塞，只读的 verifier 通常无法给出 PASS。列出被阻塞检查的 PARTIAL 是诚实的，而非失败。PASS 仅保留给白名单只读检查本身即构成充分证据的情形。
• 规划模式期间的工具变更在退出时被覆盖。 规划模式在进入时快照你激活的工具，退出时原样恢复该快照。你在规划模式激活期间对工具集所做的任何更改，都会在离开时丢失。（会话 resume 时，快照会与当前已注册的工具求交集，因此不再存在的名称会被丢弃。）
• 安全门是工作流护栏，不是沙箱。 它仅约束 agent 发起的工具调用；它不隔离进程、不覆盖一切，也不作任何安全保证。请把它当作护栏，而非围栏。
• 非 UI 模式 fail closed。 在 print/JSON（非交互）模式下无人应答确认提示，因此任何 confirm 档动作都会被阻塞而非执行。某些交互能力（计划动作菜单）也会降级为一条纯提示。
• 子代理需要 provider API key。 /cw:explore、/cw:verify、/cw:workflow 与 cw_subagent 都会派生子 pi 进程；没有配置好的模型/API key 时，它们会返回清晰的配置错误。

开发

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest

纯逻辑（安全分类、计划步骤与 [DONE:n] 解析、状态恢复、verdict 解析）由单元测试覆盖。手动冒烟使用 fixtures/demo-project/ 夹具——四个命令的走查见 examples/demo.md，端到端回归清单见 docs/phase5-regression.md。完整规格见 docs/spec.md，分阶段计划见 docs/plan.md。提示词全景可视化见 docs/prompt-map.html，与 Claude Code 的机制对照见 docs/cc-prompt-comparison.md。