# prompt-coach

[English](README.md) | 简体中文

在 **Pi** 和 **Oh My Pi（OMP）** 中，把粗略的编码想法整理成清楚、可执行的提示词。先澄清需求、查阅相关证据，再展示完整成稿，由你选择是否在当前会话执行。

## 安装

```bash
# Pi
pi install npm:@sonsong/prompt-coach

# OMP
omp plugin install @sonsong/prompt-coach
```

重启宿主，或使用宿主支持的扩展重载功能。验证版本为 **Pi 0.87.0** 和 **OMP 18.4.2**。两个宿主共用一个 JavaScript 扩展和一份引导规则。引导复用宿主已有模型和上下文，无须单独配置模型账号或 API Key。

## 使用

在空闲会话中启动：

```text
/prompt-coach 登录页偶尔失败，帮我整理一个有用的排错任务。
```

插件优先利用当前对话，必要时读取或搜索相关项目文件。每轮最多追问 1—3 个关键问题，有内置提问工具时优先使用。完整需求直接进入成稿。随时可以说“**直接生成**”“**跳过**”或提出修订；未回答的问题会保留为明确的未知项。

例如，模糊的排错需求会整理为包含复现步骤、预期与实际行为、证据、失败尝试、范围和验收条件的提示词。简单且完整的需求仍保持简短。

## 工具为什么有价值

编码代理只能根据收到的上下文行动。目标、证据、范围或完成标准模糊时，模型就需要猜测，容易反复追问、找错文件、扩大改动范围，结果也更难验收。

`prompt-coach` 会把粗略想法整理成一份可审查的交接提示词：保留相关背景和失败尝试，暴露未知信息，写清约束和验收条件，并让你在执行前确认最终版本。引导阶段保持只读。它尤其适合排错、实现、审查和方案设计等包含多项约束的任务；简单且完整的需求仍保持简短。

| 命令 | 行为 |
| --- | --- |
| `/prompt-coach <想法或提示词>` | 开始引导，或修订当前需求。 |
| `/prompt-coach` | 提示输入想法；已有待确认成稿时，重新打开选择框。 |
| `/prompt-coach cancel` | 结束引导并恢复原工具配置，不启动任务。 |

追问、改进说明和确认界面跟随用户语言，支持英文与简体中文，没有语言上下文时默认英文。可以说“请切换到英文”或“continue in Chinese”切换，也可以单独指定成稿语言。

## 引导会重点完善什么

引导流程落实五条实用原则：

1. **少而准** —— 保留高相关背景和有价值的失败尝试，删除重复信息与无关噪声。
2. **突出重点** —— 按背景、证据、任务、约束和输出组织提示词。背景过长时，限制容易被模型当成普通信息；把关键限制放在任务和完成标准附近，模型更容易在制定方案和检查结果时持续遵守。
3. **先事实后判断** —— 在判断原因或提出方案前，区分已确认事实、猜测和缺失证据。
4. **具体化要求** —— 把“认真分析”这类模糊表达改成具体文件、检查方向、示例、边界和预期结果。
5. **明确完成标准** —— 写清范围、交付物和验收条件，避免任务在执行过程中悄悄扩大。

这五点可以减少噪声、避免无依据的假设、消除歧义并收窄预期输出。引导只追问缺失信息，不要求每个需求都套用固定模板。

## 确认与执行

扩展先展示可复制的完整提示词和最多三条改进说明，再打开宿主原生选择框。

| 选择 | 结果 |
| --- | --- |
| **执行** | 结束引导，恢复原工具配置，把展示的成稿提交到当前会话一次。继续遵守宿主现有权限和计划模式规则。 |
| **继续完善** | 保持只读，等待补充意见。修订后的成稿需要重新确认。这是默认选项。 |
| **仅保留提示词** | 将成稿留在对话中，结束引导，不启动任务。 |
| **关闭弹窗／中断** | 保持只读和待确认状态。用 `/prompt-coach` 重新打开选择框。 |

输入新的消息会使旧成稿的确认失效。内部工具 `prompt_coach_finish` 只能提交成稿，不能授权或启动执行。没有交互界面时，扩展只展示成稿，不会自动执行。

## 只读边界与会话恢复

引导或等待确认期间，只开放经核实的内置读取、搜索、目录浏览、提问工具，以及插件自己的成稿工具。编辑、写入、Shell、脚本、子代理和未知工具调用均被拦截；第三方工具即使使用允许的工具名称也不会放行。直接输入的 Shell 命令和 OMP 的直接 Python 命令也会在引导期间被拦截。

阶段、成稿和原活动工具配置保存在宿主会话记录中。重载、恢复和分支切换按当前分支恢复状态，不重放执行请求。通过 `cancel`、“执行”或“仅保留提示词”退出引导。插件不会在项目中创建成稿文件。

这个限制覆盖扩展已加载时的宿主工具和直接命令入口，不是针对其他进程或其他扩展自身代码的操作系统沙箱。被扩展覆盖的工具不会进入只读白名单。请使用可信扩展，并避免在引导期间切换宿主模式。

## 开发

```bash
npm install
npm run check
npm test
npm pack --dry-run
```

少量测试覆盖禁写、明确执行授权和会话恢复。npm 发布内容由 `files` 白名单控制。用户可见功能发生变化时，必须同步更新本文与 [README.md](README.md)。

官方参考：[OMP 插件文档](https://omp.sh/docs/plugins)、[Pi 包文档](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)、[Pi 包目录](https://pi.dev/packages)。npm 的 `pi-package` 关键词用于目录发现；npm 发布成功与目录实际收录是两个独立状态。

## 许可证

[MIT](LICENSE) © 2026 songsongtao