用 pi 提示词模板沉淀 GitHub Issue 分析流程：`.pi/prompts/is.md` 逐行拆解与复用指南

本篇技术指南以 pi 仓库中真实存在的提示词模板 .pi/prompts/is.md 为核心，讲解如何把"分析 GitHub Issue（缺陷与功能请求）"这一高频工程任务固化为一条可复用、可带参调用的斜杠命令 /is <issue>。读完你将掌握 pi 提示词模板的前置机制（目录发现、frontmatter 解析、参数替换），理解模板中每条指令背后的工程意图，并能基于同一套写法快速沉淀你自己的 Issue/PR 分析流程。

模板概览：一个 28 行的"任务说明书"

.pi/prompts/is.md 是 pi 编码代理项目自用的提示词模板文件，全文极短却定义了一套完整的 GitHub Issue 分析 SOP（标准作业流程）。它在交互编辑器中表现为一条命令：输入 /is <issue> 即可把模板内容展开成正式指令，要求模型对指定的 Issue 进行分析并提出修复/实现方案。

模板由两部分组成：

• YAML frontmatter：声明模板的 description 与 argument-hint，供自动补全下拉框展示；
• 正文指令：依次约束 CI 环境下的标签/指派行为、Issue 全量读取方式、独立验证要求、Bug 分析与功能请求分析的分支处理，以及"只分析、不实现"的边界。

这份模板之所以值得拆解，是因为它示范了提示词工程中几个关键手法：可预测的副作用控制、强制"一手信息"获取、按任务类型分支的推理路径、明确的行动边界。下面先看它在 pi 中的加载机制，再逐行回到模板本身。

前置机制：pi 如何发现并展开 .pi/prompts/ 中的模板

is.md 之所以能被当作 /is 命令使用，靠的是 pi 的提示词模板（Prompt Templates）能力。官方文档 packages/coding-agent/docs/prompt-templates.md 说明：

• 项目级模板放在 .pi/prompts/*.md（仅当项目被信任后加载）；is.md 正落在此目录，因此当前仓库中即可直接生效。
• 全局模板放在 ~/.pi/agent/prompts/*.md，另可通过 packages 的 prompts/ 目录、settings 中的 prompts 数组，或 CLI 的 --prompt-template <path> 追加加载；可用 --no-prompt-templates 关闭发现。

与"技能"（Skills）不同，提示词模板不做渐进式披露，展开即完整注入对话；模板加载在 prompts/ 目录内是非递归的，子目录模板需显式配置。

目录名 .pi 从哪来

仓库配置层定义了配置目录名常量：在 packages/coding-agent/src/config.ts 中可见 CONFIG_DIR_NAME 默认取值为 .pi，且可由包清单中的 piConfig.configDir 覆盖。也就是说 .pi/prompts/ 是项目级配置目录 {cwd}/{CONFIG_DIR_NAME}/prompts 的默认落点。

文件名即命令名

模板加载器在 packages/coding-agent/src/core/prompt-templates.ts 中实现：

• loadTemplateFromFile 以文件名去掉 .md 作为模板名，故 is.md → 命令 /is（见 prompt-templates.ts 中 name = basename(filePath).replace(/\.md$/, "")）；
• description 缺失时回退取正文首个非空行并截断至 60 字符；
• frontmatter 中 argument-hint 字段被映射为模板的 argumentHint，用于自动补全提示。

文档 prompt-templates.md 展示的补全渲染效果里，恰好能看到本仓库 is.md 注册后的样子：

→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  is   <issue>        — Analyze GitHub issues (bugs or feature requests)
  wr   [instructions] — Finish the current task end-to-end

注意角括号 <issue> 表示必填参数，方括号 [...] 表示可选——这正对应 is.md 中的 argument-hint: "<issue>"。

参数如何注入正文

模板正文首行为 Analyze GitHub issue(s): $ARGUMENTS。展开 /is #123 --json 这类调用时，expandPromptTemplate 会先经 parseCommandArgs 按 bash 风格切分参数（支持单双引号包裹的空格参数），再由 substituteArgs 完成占位符替换：

• $1、$2…：位置参数；$@ / $ARGUMENTS：全部参数拼接；
• ${1:-default}、${@:-default}：参数缺失/为空时回退默认值；
• ${@:N}、${@:N:L}：自第 N 个参数起切片（1 起始、bash 风格）。

因此 /is 42 展开后首行即为 Analyze GitHub issue(s): 42，后续所有步骤都围绕该 Issue 展开（实现见 prompt-templates.ts）。

逐步拆解 is.md：每条指令都在解决什么问题

回到模板正文。它开篇声明目标后即进入编号流程，我们将逐一还原每条指令的作用与设计动机。

第 1 步：CI 感知的标签与指派（副作用控制）

1. If running under CI (CI=true), do not add the inprogress label and do not assign the issue. Otherwise, add the inprogress label … and assign the issue to the local gh user …

这条约束回答了一个实操痛点：分析是异步的长任务。在交互式终端里，把 Issue 标记为 inprogress 并指派给当前 gh 登录用户，能防止他人重复认领；但在 CI 流水线里，这类标签/指派既无意义又可能污染真实协作状态。因此模板要求模型先探测 CI=true，环境不同行为不同；且若任一步骤失败，必须显式报告后继续——失败不能被吞掉，也不能阻断主流程。

从工程视角看，这示范了一条通用经验：凡对远端资源有副作用的 Agent 任务，都要先问"我现在运行在哪类环境"，并在失败时保留可见性。

第 2 步：强制全量、结构化读取 Issue

2. Read the issue in full, including all comments and linked issues/PRs. Use fields supported by GitHub CLI, for example: gh issue view <issue> --json title,body,comments,labels,assignees,state,url,author,createdAt,updatedAt,closedByPullRequestsReferences

命令指明"包括所有评论与关联 Issue/PR"——缺陷的真正线索往往散落在讨论串与相关联的 PR（如 closedByPullRequestsReferences 能揭示哪些提交"修复"了它）。通过 --json 一次拉取结构化字段，而不是让模型从终端渲染的摘要里猜，可保证输入完整、字段名确定。

值得指出的是 <issue> 在模板里以角括号占位，说明它应由调用者在输入 /is <issue> 时替换为真实的 Issue 编号或 URL（gh issue view 同时支持数字与 URL）。

第 3 步：不信任 Issue 内已有的分析（一手信息原则）

3. Do not trust analysis written in the issue. Independently verify behavior and derive your own analysis from the code and execution path.

这是模板最核心的方法论之一：Issue 中的"根因分析"、"修复建议"是用户/上报者的二手结论，常与实际不符。模型被要求放弃二手论断，转向一手证据——代码与执行路径。这条指令直接塑造了后续第 4、5 步的分支逻辑：凡是"他人结论"一律需要复核，凡是"代码事实"才可作为推理基础。

第 4 步：Bug 分支——先忽略结论，再全量读代码

对于缺陷类 Issue，模板给出严格的推理纪律：

1. 忽略 Issue 中的根因分析（"likely wrong"）；
2. 全量阅读相关代码文件，不得截断——防止模型基于不完整的上下文草率归因；
3. 追踪代码路径，定位真实根因；
4. 提出修复方案。

这里"Read all related code files in full (no truncation)"是一条重要的上下文管理指令：它要求模型在推理前先完整加载证据，避免被上下文窗口裁剪出的"局部事实"误导。结合 pi 的编码代理定位（具备 bash、读写文件等工具，见 packages/coding-agent/docs/index.md），这条指令可落地的含义是：必要时先用工具读完整个相关模块，再下结论。

第 5 步：功能请求分支——追求最小实现

对于新功能类 Issue：

1. 未经验证不采信 Issue 中的实现方案；
2. 全量阅读相关代码文件；
3. 提出最精简的实现路径；
4. 列出受影响文件清单与所需改动。

与 Bug 分支相比，功能分支的产出不是"修复"而是"变更提案"：明确指出波及哪些文件、需要什么改动，为后续人工评审提供抓手，也为可能的落地实现铺路。

终局红线：默认不实现

Do NOT implement unless explicitly asked. Analyze and propose only.

模板在最末写死行动边界：模型默认输出分析与方案，绝不越界动手改代码，除非用户显式要求。这是把"分析型模板"与"执行型模板"区分开来的关键设计，避免一次 /is 意外触发大规模代码改动。

分支结构一图读懂

可以把模板正文的推理流程归纳为如下控制流：

/is <issue>（+ CI 环境探测）
        │
        ├─ CI=true ────────────────► 跳过标签/指派（失败仍显式报告）
        └─ 非 CI ──────────────────► 加 inprogress 标签 + 指派给本地 gh 用户
        │
        全量读取 Issue（含评论与关联 Issue/PR，gh issue view --json …）
        │
        独立验证：不信任 Issue 内已有分析，回到代码与执行路径
        │
        ├─ 缺陷类：忽略其根因 → 全量读代码 → 追踪路径 → 真实根因 → 修复方案
        ├─ 功能类：核验方案 → 全量读代码 → 最小实现思路 → 受影响文件 + 改动清单
        │
        默认只分析与提议，未经明示不实现

这张图概括了 is.md 全部逻辑，任何一条斜杠命令的展开执行都遵循此路径。

在仓库中验证：模板如何进入运行时

若想确认该模板真的会被 pi 加载，可在 packages/coding-agent/src/core/resource-loader.ts 中看到：项目级模板路径由 join(this.cwd, CONFIG_DIR_NAME, "prompts") 计算（对应当前仓库 .pi/prompts），全局模板由 join(this.agentDir, "prompts") 计算（对应 ~/.pi/agent/prompts）；随后路径进入 loadPromptTemplates，经由 prompt-templates.ts 的 frontmatter 解析与占位符替换后注册为可展开模板。这意味着：你只要把一份合规的 .md（含 --- frontmatter）放入 .pi/prompts/，pi 下次启动就会把它变成一条新的斜杠命令。

复用这套写法：沉淀你自己的分析模板

is.md 的价值不仅在于它本身，更在于它是一份可照抄的模板范式。总结可迁移的写法清单：

1. 用 frontmatter 说清楚"何时用"：description 写清适用场景（如"bugs or feature requests"），argument-hint 用 <必填> / [可选] 标出参数，二者共同决定自动补全的可用性；
2. 正文首行声明任务并携带 $ARGUMENTS：保证展开后参数自然流入指令；
3. 环境感知副作用：凡是打标签、指派、推送等外部副作用，先判断 CI=true 等环境变量并给出分支行为；
4. 强制一手证据：明确要求"不信任现有结论、全量读文件、沿代码路径独立推导"；
5. 按任务类型分支出不同推理模板：Bug 走"追根因→提修复"，Feature 走"最小实现→列受影响文件"；
6. 写清行动边界：默认只分析不实现，把"是否动手"的决定权交还用户。

例如，把文中 gh issue view 换成 gh pr view、将分支逻辑改为"审查 PR diff"，即可得到一条 /pr 分析命令（文档 prompt-templates.md 中出现的 pr 模板正是同构产物）；同理可衍生出 commit 审计、changelog 检查等只读分析模板。

小结

.pi/prompts/is.md 是 pi 仓库中提示词模板机制与真实工程 SOP 结合的一个缩影：它用约 20 行指令封装了"GitHub Issue 分析"这一任务的完整推理纪律——从 CI 环境下的副作用控制，到全量读取、独立验证、按 Bug/Feature 分支处理，再到默认不实现的边界。理解这份模板的机制（prompt-templates.ts、resource-loader.ts、config.ts）与写法范式后，你完全可以为团队的代码评审、缺陷复现、版本审计等场景沉淀出同样高质量的斜杠命令，让 Agent 每次出手都遵循经过验证的分析流程。