Prompt Template Model 扩展

为 Pi 的 prompt 模板增加 model、skill、thinking 等 frontmatter。可用 slash 命令切换到合适模型、设置思考级别、注入 skill 上下文，并在结束后自动恢复会话状态。

/debug-python my code crashes
  → 切换到 Sonnet，加载 tmux skill，agent 开始处理
  → 结束后恢复你之前的模型

为什么需要它？

每个 prompt 模板都变成一个自包含的 agent 模式。/quick-debug 可用轻量模型 + REPL 类 skill；/deep-analysis 可拉起扩展思考与重构专长。命令结束后你仍回到日常默认模型，无需手动切换。

不用再来回切模型，也不用指望 agent 自己选对 skill。配置一次，slash 命令即可复用。

安装

从 npm 安装：

pi install npm:@rotart/pi-prompt-template

从本地检出安装（开发本仓库时常用）：

cd /path/to/pi-prompt-template-model
pi install .
# 之后可用: pi remove .

安装后请重启 pi，或执行 /reload。

若要用委托式 subagent 执行（subagent 与 inheritContext frontmatter），请单独安装 pi-subagents：

pi install npm:pi-subagents

pi-subagents 是可选的——其余功能无需它也能用。在未安装时使用 subagent: true 会快速失败并给出明确错误。

快速开始

1. 创建扩展自有模板目录（不要用 Pi 的 prompts/）：

mkdir -p ~/.pi/agent/prompt-templates
# 或项目级：
# mkdir -p .pi/prompt-templates

2. 在其中放一个带 model（可选 skill）的 markdown 文件：

---
description: Debug Python in tmux REPL
model: claude-sonnet-4-20250514
skill: tmux
---
Start a Python REPL session and help me debug: $@

保存为 ~/.pi/agent/prompt-templates/debug-python.md。

3. 重启 pi，或运行任一扩展命令 / /reload，然后执行 /debug-python some issue。agent 会切到 Sonnet、收到 tmux skill 上下文并开始工作。结束后恢复先前模型。

仍希望由 Pi 默认加载器处理的普通一次性 prompt，请继续放在 ~/.pi/agent/prompts/ 或 .pi/prompts/。

Prompt 发现规则

本扩展与 Pi 共用 slash 命令命名空间，但不共用发现目录。请分开存放，避免同一文件名在自动补全中出现两次：

角色	目录	谁加载
普通 Pi prompt	~/.pi/agent/prompts/、<cwd>/.pi/prompts/，以及 Pi settings.json 的 prompts 条目	仅 Pi 核心
本扩展的增强 / 工作流模板	~/.pi/agent/prompt-templates/、<cwd>/.pi/prompt-templates/	仅本扩展（注册 slash 命令）

不要把扩展模板放在 prompts/ 或其子目录下。Pi 会递归加载 prompts/，若本扩展再注册同名文件，就会再次出现重复 slash 条目。

扩展自有注册路径

• 用户级：~/.pi/agent/prompt-templates/
• 项目级：<cwd>/.pi/prompt-templates/

同名时项目级覆盖用户级。同一层重复会跳过并警告。保留名（含内置命令与 /chain-prompts）也会跳过并警告。

本扩展不会从 Pi 的 settings.json prompts 数组注册命令。该数组仍属于 Pi 的配置面。

Chain 解析

/chain-prompts 与 chain 模板仍可从 Pi 的 prompts/ 树（以及 settings.json 的 prompts 路径）解析普通步骤，以便混合流水线。这些普通步骤不会被注册为扩展命令。

从旧版本迁移

旧版扩展还会扫描 Pi 的 prompts/ 树与 settings.json 的 prompts 条目中的增强模板，导致自动补全出现重复 slash 条目（Pi 一条、本扩展一条）。

若增强模板仍在 prompts/（或列在 Pi settings.json prompts 中）下：

mkdir -p ~/.pi/agent/prompt-templates
mv ~/.pi/agent/prompts/my-workflow.md ~/.pi/agent/prompt-templates/
# 项目级：
# mkdir -p .pi/prompt-templates
# mv .pi/prompts/my-workflow.md .pi/prompt-templates/

普通 Pi prompt 留在 prompts/。移动后执行 /reload 或重启 pi。每个增强命令应只剩一条由本扩展注册的条目。

Frontmatter 参考

所有字段均可选。放在 prompt-templates/ 下、且不含扩展特性（无 model、skill、thinking、loop、subagent、chain、条件块等）的文件默认不会注册为扩展命令；若只需要普通模板展开，请放在 Pi 的 prompts/。

核心字段

字段	默认	作用
model	当前会话模型	使用的模型。可为单个模型、provider/model-id，或逗号分隔的回退列表（见 模型格式）。设置 chain 时忽略。
skill	—	在 agent 处理任务前注入 skill 内容为上下文消息，无需额外往返。见 Skill 解析。
thinking	—	思考级别：off、minimal、low、medium、high、xhigh。
description	—	自动补全旁显示的简短说明。
chain	—	可复用的模板流水线（step -> step）。设置后正文被忽略。见 Chain 模板。
chainContext	—	仅 chain 模板。设为 summary 时，委托步骤会收到先前步骤的紧凑摘要。inheritContext: true 的步骤除外。见 委托步骤的 chain 上下文。

执行控制

字段	默认	作用
restore	true	命令结束后切回之前的模型与思考级别。设为 false 则保持新模型。
loop	—	默认循环次数（1–999、true 或 unlimited）。CLI --loop 可覆盖。见 循环执行。
rotate	false	为 true 且在循环时，按 model 列表轮换模型（非回退语义）。thinking 也可逗号分隔，与模型一一对应。
fresh	false	循环时在迭代之间折叠对话为简要摘要，而不是携带完整上下文，适合长循环省 token。
converge	true	循环时若某轮无文件变更则提前停止。设为 false 则跑满每一轮。
boomerang	false	非 chain prompt 结束后，将执行上下文折叠回分支点并附简要摘要。可与循环（含 fresh）配合，适合 /double-check 一类复查。
worktree	false	为 true 时，并行委托任务在独立 git worktree 中运行。适用于含 parallel() 的 chain、带 parallel: N 的委托 prompt，以及 compare 模板的 bestOfN.worktree。

委托

字段	默认	作用
subagent	—	将执行委托给 subagent，而非当前会话。true 使用默认 delegate agent；字符串如 reviewer 指定具体 agent。需要 pi-subagents。
inheritContext	false	仅在有 subagent 时有意义。为 true 时 subagent 获得当前对话的 fork，而不是从空白开始。
parallel	—	仅委托 prompt。将同一 subagent 并行跑 N 次。每次任务前会加类似 [Parallel subagent 2/3] 的槽位头。须为 ≥ 2 的整数。
bestOfN	—	仅 compare 模板。嵌套的 compare 编写块，含 workers、reviewers、可选 finalApplier 与可选 worktree。模板不支持顶层 compare 字段。
bestOfN.workers	—	worker 阶段有序阵容。每个槽位可含可选 agent/subagent、model、task、taskSuffix、cwd、count。若同时省略 agent 与 subagent，默认 agent 为 delegate。
bestOfN.reviewers	—	聚合 worker 后的 reviewer 阵容。槽位形状与 workers 相同。若同时省略 agent 与 subagent，默认 agent 为 reviewer。
bestOfN.finalApplier	—	可选的单槽最终应用阶段：reviewer 之后在真实分支上编辑。支持可选 agent/subagent、model、task、taskSuffix。若同时省略 agent 与 subagent，默认 agent 为 delegate。不支持 count 与 cwd。运行时要求 bestOfN.worktree: true。
cwd	—	委托 subagent 子进程的工作目录。须为绝对路径（~/... 会展开）。可用于 subagent、chain 模板（作为委托步骤默认 cwd）、compare prompt（默认仓库 cwd）。worker/reviewer 槽位也可在 bestOfN.workers / bestOfN.reviewers 内各自设置 cwd。

模型格式

model: claude-sonnet-4-20250514            # 裸 model ID — 自动选择 provider
model: anthropic/claude-sonnet-4-20250514  # 显式 provider/model

裸 model ID 按 provider 优先级解析：openai-codex → anthropic → github-copilot → openrouter。第一个有有效认证的 provider 胜出。

需要显式控制时：

model: anthropic/claude-opus-4-5        # 直连 Anthropic API
model: openai-codex/gpt-5.2             # 经 Codex 订阅（OAuth）
model: github-copilot/claude-opus-4-5   # 经 Copilot 订阅
model: openrouter/claude-opus-4-5       # 经 OpenRouter
model: openai/gpt-5.2                   # 直连 OpenAI API

模型回退

逗号分隔列表按顺序尝试：

model: claude-haiku-4-5, claude-sonnet-4-20250514

先试 Haiku；找不到或无 API key 则用 Sonnet。若当前会话已在列表中某一模型上，则保持不切换。全部候选失败时会返回一次错误，列出尝试结果。

可混用裸 ID 与显式 provider 规格：

model: anthropic/claude-haiku-4-5, openrouter/claude-haiku-4-5, claude-sonnet-4-20250514

Skills

通常 Pi 会在系统提示中列出可用 skill，agent 读完任务后决定加载哪个，再用 read 工具加载——多一轮往返，还可能选错。

skill 字段声明本模板要绑定的 skill（产品承诺是绑定成功，而不是子代理一定已把全文记进上下文）。支持多个 skill：

---
description: Browser testing mode
model: claude-sonnet-4-20250514
skill: surf
# 或多 skill：
# skill: grilling, research, codebase-design
# skill:
#   - grilling
#   - skill:research
---
$@

双模式（同一 skill 字段）

路径	行为
本会话（无 subagent）	全文注入：每个 skill 的正文以 <skill name="…"> 进入本轮上下文，无需 tool call
子代理（subagent / 委托 / parallel）	按需绑定：先校验 skill 存在且可读；把 available_skills 元数据（name + description + path，不含正文）交给子代理；子代理可据此判断何时使用哪个 skill 并按需 read。父会话仅 info 通知绑定名单，不发全文 skill-loaded 卡片

任一声明的 skill 找不到或不可读会全有或全无快速失败（禁止“裸跑”）。委托解析目录为模板 cwd（若有），否则为当前会话 cwd。

Skill 解析

skill 接受裸名称、skill: 前缀、逗号列表或 YAML 字符串数组；会 trim、去掉一层 skill: 前缀、去空、去重且保序。

skill: tmux
skill: skill:tmux    # 等价
skill: grilling, research

解析顺序（对每个名称）：

1. pi.getCommands() 中已注册、source 为 "skill" 的 skill 命令
2. <resolveCwd>/.pi/skills/<name>/SKILL.md 或 <name>.md
3. 当前目录及祖先中的 .agents/skills（上至 git 根）
4. ~/.pi/agent/skills/<name>/SKILL.md 或 ~/.pi/agent/skills/<name>.md
5. ~/.agents/skills/<name>/SKILL.md 或 ~/.agents/skills/<name>.md

内联模型条件

正文可包含仅对特定模型渲染的段落：

---
description: Cross-model code review
model: claude-haiku-4-5, claude-sonnet-4-20250514
---
Summarize the change first.

<if-model is="claude-haiku-4-5">
Keep the answer brief and cost-conscious.
<else>
Do a deeper pass and call out subtle risks.
</if-model>

条件针对实际运行的模型求值——多模型模板在回退解析之后，或未写 model 时针对会话模型。

is 支持精确 model ID、provider/model-id、provider 通配如 anthropic/*，以及逗号组合：

<if-model is="anthropic/*">Anthropic-specific instructions</if-model>
<if-model is="openai/gpt-5.2, anthropic/*">Either OpenAI or Anthropic</if-model>

<else> 为回退分支。支持嵌套 <if-model>。

参数替换

正文中的占位符会展开为命令名后的参数：

占位符	展开为
$1、$2、...	第 N 个参数（从 1 起）
$@ 或 @$ 或 $ARGUMENTS	全部参数，空格拼接
${@:N}	从位置 N 起的全部参数
${@:N:L}	从位置 N 起的 L 个参数

---
model: claude-sonnet-4-20250514
---
Analyze $1 focusing on $2. Additional context: ${@:3}

/analyze src/main.ts performance edge cases error handling 会把 $1 展开为 src/main.ts，$2 为 performance，${@:3} 为 edge cases error handling。

委托 Subagent 执行

可将 prompt 交给 subagent，而不是在当前会话运行：

---
model: anthropic/claude-sonnet-4-20250514
subagent: true
---
Review and simplify this code: $@

subagent: true 委托给默认 delegate agent。指定具体 agent：

---
model: anthropic/claude-sonnet-4-20250514
subagent: reviewer
inheritContext: true
---
Audit this diff for correctness and edge cases: $@

inheritContext: true 会 fork 当前对话，使 subagent 拥有完整上下文；否则从空白开始。

强制指定工作目录时加 cwd：

---
model: claude-sonnet-4-20250514
subagent: browser-screenshoter
cwd: /tmp/screenshots
---
Use url in the prompt to take screenshot: $@

subagent 进程以 /tmp/screenshots 为工作目录。路径须绝对（~/... 会展开）。目录在执行时校验。

把同一委托 prompt 扇出为多份并行，加 parallel: N：

---
model: anthropic/claude-sonnet-4-20250514
subagent: simplifier
inheritContext: true
parallel: 3
worktree: true
---
Review changed code and fix any issues found.

这会展开为三个并行的 pi-subagents 任务，目标同一 agent。每个收到相同渲染后的 prompt，并自动加上 [Parallel subagent 1/3] 等槽位头，便于正文给副本分配不同角色。此处 worktree: true 可选，用于给每次并行运行独立 git worktree。

执行期间，编辑器上方会出现实时进度组件（耗时、tool 次数、token、当前 tool）。结束后替换为完成卡片（任务预览、tool 历史、输出、用量）。

运行时可用 --subagent、--subagent=<name>、--subagent:<name> 或 --cwd=<path> 覆盖委托行为。--cwd=<path> 在可选 ~/... 展开后须为绝对路径。运行时标志仅对当次调用生效。

另有两个适用于任意 prompt（不仅委托）的运行时标志：

• --model=provider/model-id — 覆盖模板的 model。适用于单次执行、循环与委托。
• --fork — 以 inheritContext（fork 上下文）运行。若未设则隐含 --subagent。

/double-check --model=anthropic/claude-opus-4-6
/double-check --fork --subagent:worker
/deslop --model=openai/gpt-5.4 --loop 3

Compare 模板还支持运行时阵容覆盖：

编写时用 frontmatter 的 bestOfN:。运行时覆盖使用下方低层标志。

• --workers=<json-array> / --reviewers=<json-array> 替换对应 frontmatter 阵容。
• --workers-append=<json-array> / --reviewers-append=<json-array> 追加到对应阵容。
• --final-applier=<json-object-or-one-element-array> 替换可选的最终应用槽。

每个 worker/reviewer JSON 数组元素须为对象，含 subagent 或 agent，以及可选 model、task、taskSuffix、cwd、count。worker 槽中 "subagent": true 映射为 delegate；reviewer 槽中映射为 reviewer。--final-applier= 接受一个槽位对象（或单元素数组），含 subagent/agent 与可选 model、task、taskSuffix；该最终槽中 "subagent": true 映射为 delegate，且不支持 count 与 cwd。

Best-of-N Compare Prompt

本仓库在 examples/ 下提供一个 compare 示例：

• examples/best-of-n.md 安装后为 /best-of-n，在当前仓库运行，展示混合 workers、混合 reviewers 与可选最终应用阶段。
• 冒烟测试：/best-of-n smoke test。

从本仓库检出（或已安装的包目录）手动安装：

PTM_DIR=/path/to/pi-prompt-template-model
mkdir -p ~/.pi/agent/prompt-templates
cp "$PTM_DIR/examples/best-of-n.md" ~/.pi/agent/prompt-templates/best-of-n.md

复制后若 pi 已在运行请重启。该 prompt 会执行明确的 compare 流程：

Compare 模板用 bestOfN: 编写。顶层 workers、reviewers、finalApplier frontmatter 会被拒绝并给出迁移诊断。

1. Worker 阶段：并行运行 worker 阵容（context: fork），在临时 worktree 中生成候选实现。
2. 只要至少一名 worker 成功就继续。Reviewer 槽收到成功 worker 输出与 worker/worktree 摘要，只产出 findings。
3. 可选最终应用：若配置了 finalApplier，在真实 compare 仓库（compareCwd）上跑一次委托应用，挑选胜者或综合/拣选并应用最终补丁。
4. 若全部 reviewer 失败但存在 finalApplier，最终应用仍会运行，上下文来自 worker 与 reviewer 失败摘要。

worker/reviewer 阵容完全可由 bestOfN frontmatter 或运行时覆盖配置，没有固定的“三模型 worker”假设。若省略 bestOfN.workers，回退为一个使用当前/主模型的 delegate worker。若省略 bestOfN.reviewers，回退为一个 reviewer 槽。bestOfN.finalApplier 可选；有效 final applier 存在时要求 bestOfN.worktree: true。

同模型 best-of-N 可在单个 worker 槽上使用 count: N：

bestOfN:
  workers:
    - model: openai-codex/gpt-5.4:low
      count: 4

也可混用模型并为各槽设不同 count：

bestOfN:
  workers:
    - model: openai-codex/gpt-5.4:low
      count: 3
    - model: google/gemini-2.5-pro:medium
      count: 2
    - model: anthropic/claude-sonnet-4-20250514:high

reviewer 槽形状相同；bestOfN.finalApplier 为可选单槽最终应用：

bestOfN:
  reviewers:
    - model: openai-codex/gpt-5.4:low
      count: 2
    - model: google/gemini-2.5-pro:medium
      taskSuffix: Focus on regression risk.
  finalApplier:
    model: anthropic/claude-sonnet-4-20250514:high
    taskSuffix: Apply the final patch on the current branch and report verification.

在 compare 阵容中，同时省略 agent 与 subagent 时使用阶段默认：workers 为 delegate，reviewers 为 reviewer，finalApplier 为 delegate。需要时仍可显式设置 agent 或 subagent。

重复写相同槽位仍然可用，但槽位完全相同时 count: N 更简洁。

阵容内用 task 做整段 per-slot 覆盖，用 taskSuffix 做小段追加。taskSuffix 接在共享 worker 任务之后（若写了槽位 task 则在其后），适合例如 per-model 输出文件名。

当 compare prompt 使用 bestOfN.worktree: true 时，所有 worker 槽必须解析到同一 cwd。仅在关闭 worktree 隔离时才允许混用 worker cwd。Worktree 隔离只作用于 worker 阶段；bestOfN.finalApplier 始终在真实分支（compareCwd）上应用。

确定性步骤（Deterministic Steps）

Prompt 模板可在可选的 LLM 回合之前运行一条确定性命令或脚本。适合第一步应是直接代码、而不是模型延迟的场景。

流程：

1. 运行一条命令或脚本。
2. 始终渲染可见的确定性结果卡片（命令、退出码、耗时、stdout/stderr 预览）。
3. 可选地将结构化结果作为 [Deterministic step] 前言交给模型，再接 prompt 正文。
4. 若 handoff: never，在结果卡片与可见完成标记后结束——不进入 LLM 回合。

handoff 前言字段名稳定，例如：status、executionKind、command、cwd、exitCode、signal、durationMs、timedOut、lineCount、charCount、truncated、omittedChars、preview。

V1 范围刻意收窄：确定性执行仅适用于单个 prompt 模板，不与 chain、委托/subagent、parallel 或循环组合。运行时对确定性 prompt 会显式拒绝 --loop、--subagent、--fork。

编写形式

可使用顶层简写或嵌套在 deterministic: 下。二者等价。简写更短；需要集中在一组键下时用嵌套。

顶层简写 — 直接在 frontmatter 放 run、script、handoff、timeout、cwd、env、nonInteractive：

---
run: git push origin HEAD:main
handoff: on-failure
timeout: 30000
---
If the push failed, explain why and suggest the next step.

也可用 script: 简写：

---
script: ./scripts/ship.sh
handoff: always
timeout: 15000
---
Summarize the script result.

嵌套形式 — 全部放在 deterministic: 下：

---
model: claude-sonnet-4-20250514
deterministic:
  script:
    path: ./scripts/ship.sh
    args:
      - --fast
  handoff: always
  timeout: 15000
  cwd: ~/src/my-repo
---
Summarize the script result and call out anything risky.

结构化命令 — 需要显式 args 而不是单条 shell 字符串时，用 deterministic.run.command + args：

---
model: claude-sonnet-4-20250514
deterministic:
  run:
    command: git
    args: [status, --short]
  handoff: always
---
Interpret the repo state.

不要在同一 prompt 中混用顶层简写与嵌套 deterministic:，二选一。

对模型的要求

会 handoff 到模型的确定性 prompt（handoff: always、on-success 或 on-failure）需要有模型可继续：

• 显式写 model:，或
• 省略 model:，继承当前活跃模型

handoff: never 不需要 model 字段，因为不会进入 LLM。

Handoff 取值

• always — 确定性卡片发出后始终进入 LLM。
• never — 卡片与完成标记后停止。
• on-success — 仅退出码为 0 时继续。
• on-failure — 仅非零退出时继续。

slash 命令选择器中的描述会显示为 deterministic-step:<handoff>。

超时

timeout 单位为毫秒。超时后 runner 先发 SIGTERM；宽限期后仍未退出则升级为 SIGKILL。

脚本路径解析

相对脚本路径先相对 prompt 文件所在目录解析，再回退到命令调用时的 cwd。绝对路径亦可。

环境与非交互模式

可提供显式环境变量，并控制 runner 的非交互防护：

---
deterministic:
  run: ./deploy.sh
  handoff: never
  nonInteractive: false
  env:
    SPECIAL_TOKEN: abc123
    RETRIES: 2
---

nonInteractive 默认为 true。该模式下 stdin 被忽略，并设置若干防护默认环境，例如 CI=1、GIT_TERMINAL_PROMPT=0、PAGER=cat、GIT_PAGER=cat。当命令需要更接近常规的进程环境、并明确退出这些默认时，设 nonInteractive: false。显式 env 会覆盖内置默认。

输出截断

过大的 stdout/stderr 在写入对话卡片载荷前会被截断。卡片与 LLM handoff 块都会显示总字符/行数，以及截断元数据。

循环执行

用 --loop 多次运行同一模板：

/deslop --loop 5
/deslop --loop=5
/deslop --loop          # 无限 — 直到收敛或上限（999）

也可在 frontmatter 设默认；CLI --loop 始终优先：

---
loop: 5
---

loop: unlimited（或 loop: true）用于开放式循环，直到收敛、用户中断或安全上限 999 轮：

---
loop: unlimited
converge: false
fresh: true
subagent: true
---

循环如何工作

每轮运行同一 prompt。默认上下文会累积——第 3 轮能看到第 1、2 轮的完整对话并在其上继续。

收敛：若某轮无文件变更（无 write 或 edit tool 调用），循环提前结束。默认开启。用 --no-converge 或 converge: false 可强制跑满。

新鲜上下文：加 --fresh（或 frontmatter fresh: true）会在迭代之间折叠对话。每轮只有先前迭代的简要摘要，适合长循环避免 token 爆炸。

状态：TUI 状态栏显示 loop 2/5。

全程保持 model、thinking、skill。若 restore: true（默认），最终一轮后全部恢复。

模型轮换

rotate: true 把逗号分隔的 model 列表从回退链变成轮换列表。每一循环轮次使用列表中的下一个模型，并绕回：

---
model: claude-opus-4-6, gpt-5.4, gpt-5.3-codex
thinking: high, xhigh, off
loop: 9
rotate: true
fresh: true
---
Review and fix issues in this codebase.

第 1 轮 Opus + high，第 2 轮 GPT-5.4 + xhigh，第 3 轮 Codex + off，再回到 Opus。状态栏会显示当前模型：loop 2/9 · gpt-5.4 xhigh。

特别适合不同模型互相补漏的 ralph 风格循环。下列 subagent 示例需要 pi-subagents。单模型、每轮委托且新鲜上下文：

---
model: claude-sonnet-4-20250514
subagent: true
inheritContext: true
loop: 5
fresh: true
---
Simplify this code: $@

加上 rotate 与多模型，每轮切换视角：

---
model: claude-opus-4-6, gpt-5.4, gpt-5.3-codex
thinking: xhigh, high, high
loop: 9
rotate: true
fresh: true
subagent: true
---
Review and fix issues in this codebase.

每轮新鲜上下文、不同模型与各自思考级别。某轮无文件变更时收敛停止——用 converge: false 可保证每个模型至少跑一轮。

thinking 与 rotate: true 的配对：

• 单值（thinking: high）— 应用于每个模型。
• 逗号分隔（thinking: high, xhigh, off）— 按位置对应，数量须与模型一致。
• 省略 — 每轮继承会话默认。

没有 loop 时 rotate 无效，逗号分隔 model 仍为普通回退语义。

串联模板（Chaining）

/chain-prompts 按顺序运行多个模板。每步使用各自的 model、skill、thinking，对话上下文在步骤间流动：

/chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts

先跑 analyze-code，再 fix-plan（能看到分析），再 summarize。-- 分隔共享参数——其后内容作为每步的 $@，除非某步自带内联参数：

/chain-prompts analyze-code "error handling" -> fix-plan -> summarize -- src/main.ts

第 1 步得到 "error handling"；第 2、3 步回退到共享的 "src/main.ts"。

chain 在开始前捕获你的 model 与 thinking，并在结束或任一步失败时恢复。

Chain 模板

可复用流水线写在 frontmatter：

---
description: Review then clean up
chain: double-check --loop 2 -> deslop --loop 2
---

这会把文件名注册为命令：先对 double-check 循环两次，再对 deslop 循环两次。每步的 --loop N 在进入下一步前重复该步，并带每步收敛（无变更则提前停，除非该步模板 converge: false）。

chain 声明还支持 parallel(...) 并行组：

---
chain: parallel(scan-frontend, scan-backend) -> consolidate
---

parallel(...) 内每一项作为委托 subagent 任务并发运行。并行项可带 per-step 参数（如 parallel(scan-frontend, scan-backend "auth")），但不支持组内 per-step --loop。嵌套 parallel(...) 会被拒绝。并行项必须是委托模板（subagent: ... 或运行时 --subagent）。同一并行组内所有项须解析到相同的 inheritContext 模式。通常允许混用 cwd；启用 worktree: true 时必须解析到同一 cwd。

加 worktree: true（或运行时 --worktree）可让每个并行 subagent 使用独立 git worktree，避免并发编辑冲突：

---
chain: parallel(scan-frontend, scan-backend) -> consolidate
worktree: true
---

worktree 要求 chain 至少含一个 parallel() 步骤。标志会传给 pi-subagents，由其创建与清理 worktree。

带 model 的步骤使用自己的模型；不带的步骤继承 chain 开始时 的模型快照，而不是上一步的模型，以保证行为确定。

Chain 模板 frontmatter 可含 loop、fresh、converge、restore、worktree、cwd 以控制整体执行：

---
chain: analyze -> fix
loop: 3
fresh: true
converge: false
---

这会完整跑 analyze → fix 三次，迭代间新鲜上下文且不提前停。不支持 chain 嵌套——步骤不能引用其他 chain 模板。

Chain 模板设置 cwd 时，会成为该 chain 中所有委托步骤的默认委托子进程工作目录。运行时 --cwd=<path> 可覆盖。

委托步骤的 Chain 上下文

委托 chain 步骤默认从空白开始，看不到先前步骤。Chain 上下文会把先前步骤的紧凑摘要前置到每个委托任务，便于后续步骤衔接。

整链启用：frontmatter 写 chainContext: summary，或 CLI 加 --chain-context：

---
chain: analyze -> fix
chainContext: summary
---

/chain-prompts analyze -> fix --chain-context

仅对某一步启用时，在该步名后加 --with-context：

/chain-prompts analyze -> reviewer --with-context -> summarize

此处只有 reviewer 收到 analyze 的摘要；summarize 不会。

使用 inheritContext: true 的步骤已 fork 完整父对话，会跳过摘要前言。parallel(...) 组内不支持 --with-context。chain 使用 loop 时，摘要在每轮迭代重置。

从 CLI 并行与循环

/chain-prompts 也支持并行组：

/chain-prompts parallel(scan-fe, scan-be) -> review
/chain-prompts parallel(scan-fe, scan-be) -> review --worktree

循环作用于整条 chain：

/chain-prompts analyze -> fix --loop 3
/chain-prompts analyze -> fix --loop 3 --fresh
/chain-prompts analyze -> fix --loop 3 --no-converge
/chain-prompts analyze -> fix --loop

收敛按每轮迭代内所有步骤计——若无任何步骤产生文件变更则停止。模板会在迭代之间从磁盘重读，因此中途编辑可即时生效。

Agent Tool

Agent 可通过 run-prompt 工具自己调用 prompt 模板。默认关闭：

/prompt-tool on

启用后，agent 的工具列表中会出现 run-prompt：

run-prompt({ command: "deslop --loop 5 --fresh" })
run-prompt({ command: "chain-prompts analyze -> fix --chain-context" })
run-prompt({ command: "chain-prompts analyze -> fix --loop 3" })
run-prompt({ command: "deslop --subagent" })

工具会在 agent 当前回合结束后排队执行该命令。循环、chain、收敛等行为与 slash 命令一致。

可附加引导语，约束 agent 何时使用：

/prompt-tool on Use run-prompt for iterative code improvement tasks
/prompt-tool guidance Use sparingly, only for multi-pass refinement
/prompt-tool guidance clear
/prompt-tool off
/prompt-tool                   # 显示当前状态

配置持久化在 ~/.pi/agent/prompt-template-model.json。

自动补全

命令会在补全描述中显示配置：

/debug-python    Debug Python session [sonnet +tmux] (user)
/deep-analysis   Deep code analysis [sonnet high] (user)
/save-progress   Save progress doc [haiku|sonnet] (user)
/component       Create React component [sonnet] (user:frontend)

子目录

可用子目录组织扩展自有模板并做命名空间：

~/.pi/agent/prompt-templates/
├── quick.md                    → /quick (user)
├── debug-python.md             → /debug-python (user)
└── frontend/
    ├── component.md            → /component (user:frontend)
    └── hook.md                 → /hook (user:frontend)

子目录会作为自动补全中的 source 标签。命令名仅基于文件名。同一 source 层内的重复会跳过并警告；保留名如 model、reload、chain-prompts 同样处理。

Print 模式

这些命令在 pi -p 中同样可用：

pi -p "/debug-python my code crashes on line 42"

会切换模型、注入 skill、agent 回复，输出到 stdout。适合脚本或管道。

示例

思考级别 — 棘手分析用高思考：

---
description: Deep code analysis with extended thinking
model: claude-sonnet-4-20250514
thinking: high
---
Analyze this code thoroughly, considering edge cases and potential issues: $@

粘性模式切换 — 在本会话剩余时间保持新模型：

---
description: Switch to Haiku for this session
model: claude-haiku-4-5
restore: false
---
Switched to Haiku. How can I help?

跨 provider 回退 — 同一模型在不同 provider 上尝试：

---
description: Quick analysis
model: anthropic/claude-haiku-4-5, openrouter/claude-haiku-4-5
---
$@

限制

• 增强模板必须放在 prompt-templates/。仅存在于 Pi prompts/ 或 settings.json prompts 路径下的文件不会被本扩展注册（仍可能作为普通 Pi prompt 出现）。
• Prompt 文件在会话开始时、以及每当运行扩展自有命令时重新加载。会话中途新增文件时，请运行任一扩展命令（如 /chain-prompts）、开新会话，或 reload pi。
• 模型恢复状态在内存中。响应中途关闭 pi 会丢失。
• Chain 中无 model 的步骤继承 chain 开始时的模型快照，而不是上一步的模型。这是为确定性故意设计的。
• 委托 subagent prompt 需要 pi-subagents。
• run-prompt 须用 /prompt-tool on 显式启用。
• 确定性 run 在 Unix 上使用 /bin/bash，在 Windows 上使用 PATH 中的 bash（例如 Git Bash）。跨 OS 共享模板时请优先写可移植命令。

附带 Skill

包内含 prompt-template-authoring skill（见 skills/），用于编写与维护本扩展的 prompt 模板。安装扩展后由 Pi 按 package.json 的 pi.skills 发现。

开发

npm test

开发依赖为 @earendil-works/pi-* 等 peer 对应版本；详见 package.json。

许可证

MIT。详见 LICENSE。