# 提示词优化 · 前后对照实例

> **这些是「本地规则回退」的输出。** 插件默认走模型改写（与 WorkBuddy 的「优化提示词」同一流程），改写结果由模型产出、因模型而异，无法预先固化成文档。本文展示的是规则引擎的输出——它在**模型不可用时自动接管**，也是 `/optimize --offline` 的结果。规则引擎的另一半职责是**诊断**：评分、结构、问题清单在任何时候都由它给出。

本文所有「改写结果」与「评分」都是**引擎真实输出**，不是手工编写的示例。整篇文档由脚本生成，改了引擎后重新生成即可，因此不存在文档与代码漂移：

```powershell
cd E:\plug\dsh-plugin-prompt-optimizer
node tools/gen-examples.mjs      # 重新生成本文档
```

只想看某一条的改写时，可以直接调用引擎：

```powershell
node --input-type=module -e "const m = await import('file:///E:/plug/dsh-plugin-prompt-optimizer/src/engine/index.js'); console.log(m.optimizePrompt('帮我优化一下那个东西，弄得好看点，尽快').optimized)"
```

> 规则引擎是纯本地的，不调用大模型，因此同一输入在任何机器上都会得到同一输出（模型路径不具备这个性质）。

---

## 例 1｜模糊中文口令

没有目标对象、没有约束、没有验收标准，还带催促词。

### 原始提示词

```text
帮我优化一下那个东西，弄得好看点，尽快
```

### 引擎评估

- 工程规范度评分：**21 / 100**（清晰度：低）
- 语言：中文　任务类型：通用任务
- 规模：19 字符 / 1 行 / 1 句　模糊命中 5　冗余命中 0　具体锚点 0
- 维度覆盖：已有 无　缺失 目标、上下文、约束、输出格式、验收标准、示例

问题清单：

| 严重度 | 类别 | 问题 | 原文证据 |
| --- | --- | --- | --- |
| 高 | 缺失要素 | 缺少验收标准 | — |
| 高 | 缺失要素 | 缺少目标 | — |
| 高 | 缺失要素 | 缺少输出格式 | — |
| 高 | 模糊表述 | 没有说明处理对象 | `优化一下那个东西` |
| 高 | 模糊表述 | 质量要求无法验收 | `优化`、`好看` |
| 高 | 模糊表述 | 指代不明确 | `那个` |
| 中 | 缺失要素 | 缺少约束 | — |
| 中 | 缺失要素 | 缺少上下文 | — |
| 中 | 缺失要素 | 缺少示例 | — |
| 中 | 结构 | 缺少结构分节 | — |
| 中 | 结构 | 整段连写（一坨） | `帮我优化一下那个东西`、`弄得好看点`、`尽快` |
| 中 | 风格 | 没说想要什么形式的回答 | — |
| 中 | 模糊表述 | 只有紧迫感，没有时间点 | `尽快` |

### 改写结果

```markdown
# 任务：通用任务

## 目标
- 处理对象：【待补充：明确要处理的具体对象，例如 `src/xxx.js` 里的 `parse()` 函数、某个页面、某段文案】（原文「优化一下那个东西」没有说明对象）
- 指代明确化：【待补充：把「那个」替换成具体名称（文件 / 模块 / 页面 / 章节 / 需求）】
- 质量要求量化：【待补充：把「优化」「好看」换成可验收的指标，例如首屏 < 1s、错误数为 0、对比度 ≥ 4.5:1、函数 ≤ 40 行】
- 时间要求：【待补充：把「尽快」换成具体截止时间或优先级（如今天 18:00 前给出第一版）】
- 交付物：满足目标的可交付结果

## 上下文与约束
- 背景：【待补充：现状 —— 框架与版本、既有实现、相关文件、业务前提】
- 约束：
  - 范围：【待补充：包含哪些部分，明确不做什么】
  - 背景：【待补充：现状、相关材料、既有实现或上文指代的对象】
  - 硬约束：【待补充：必须遵守的规则、不能动的东西、上限】
  - 信息不足时先列出待确认问题，不要自行假设关键需求
  - 保留我给出的所有具体信息（路径、版本、标识符、数字）不要改写
  - 上面任何一项还没确定时，先问我，不要自行假设。

## 输出格式
- 交付结果本身
- 关键决策与取舍说明
- 需要我确认的事项（如有）
- 用 Markdown 输出；不要复述本提示词；不要寒暄与铺垫。

## 验收标准
- [ ] 目标里的每一项都有对应产出
- [ ] 不再出现无法验收的模糊表述
- [ ] 输出形式符合要求
- [ ] 可直接使用，无需返工

## 待确认问题
- 具体处理对象
- 期望的可度量效果
- 交付形式与篇幅
- 验收方式
- 如果这些无法回答，请明确列出你的假设并标注风险。

```

> 把这份改写再喂回引擎，评分从 **21** 提升到 **80**。

变更说明：

- **重组结构**：把混在一起的整段文字拆成「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，每节只放一类信息，逐条可对齐。
- **明确任务类型与目标**：判定为「通用任务」任务，并把隐含意图改写成「对什么对象做什么、交付什么」的显式表述。
- **消除模糊表述**：把「优化一下那个东西」「那个」「优化」这类不可验收的说法换成可度量指标，无法确定的显式标为【待补充】而不是留给模型猜。
- **补齐缺失维度**：原文缺少目标、上下文、约束、输出格式、验收标准、示例，改写后逐项补上（能推断的写成明确要求，不能推断的标为待补充）。
- **按任务类型补齐工程约束**：按「通用任务」补充该类任务必需的抓手（语言与版本、边界与禁止项、错误处理或受众与深度等），并写死输出格式。
- **写死验收标准**：给出可勾选的验收清单，让「做完了没有」有客观判据，减少来回返工。

总述：原文被判定为「通用任务」任务，工程规范度 21 分（low），其中 5 处表述无法验收，并缺少目标、上下文、约束、输出格式、验收标准、示例。改写后把意图固定为「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，能推断的写成明确要求，不能推断的标为待补充。
---

## 例 2｜冗余重复的中文需求

同一件事反复说、目标重复表述、客套铺垫，信息密度低。

### 原始提示词

```text
麻烦帮我写一个脚本，谢谢！
这个脚本要把 logs 目录下的日志按日期归档。
请写一个脚本，把 logs 目录下的日志按日期归档。
脚本的功能是把 logs 里的日志文件按照日期分组归档。
先看一下目录，然后整理一下，最后归档，差不多就行。
尽量快一点，越快越好，谢谢啦！
```

### 引擎评估

- 工程规范度评分：**25 / 100**（清晰度：低）
- 语言：中文　任务类型：代码实现
- 规模：136 字符 / 6 行 / 6 句　模糊命中 5　冗余命中 2　具体锚点 0
- 维度覆盖：已有 目标　缺失 上下文、约束、输出格式、验收标准、示例

问题清单：

| 严重度 | 类别 | 问题 | 原文证据 |
| --- | --- | --- | --- |
| 高 | 缺失要素 | 缺少验收标准 | — |
| 高 | 缺失要素 | 缺少输出格式 | — |
| 高 | 模糊表述 | 指代不明确 | `这个` |
| 中 | 缺失要素 | 缺少约束 | — |
| 中 | 缺失要素 | 缺少上下文 | — |
| 中 | 缺失要素 | 缺少示例 | — |
| 中 | 结构 | 缺少结构分节 | — |
| 中 | 风格 | 没说想要什么形式的回答 | — |
| 中 | 模糊表述 | 不确定的表述 | `差不多`、`尽量` |
| 中 | 模糊表述 | 只有紧迫感，没有时间点 | `越快越好` |
| 低 | 冗余信息 | 流水账连接词 | `然后`、`最后` |
| 低 | 冗余信息 | 客套铺垫 | `谢谢`、`麻烦`、`请` |
| 低 | 风格 | 客套过多 | `谢谢`、`麻烦`、`请` |
| 低 | 模糊表述 | 数量与范围含糊 | `一点` |

冗余分组：

- **流水账连接词**：`然后`、`最后`
- **客套铺垫**：`谢谢`、`麻烦`、`请`

### 改写结果

```markdown
# 任务：代码实现

## 目标
- 帮我写一个脚本
- 写一个脚本，把 logs 目录下的日志按日期归档。
- 指代明确化：【待补充：把「这个」替换成具体名称（文件 / 模块 / 页面 / 章节 / 需求）】
- 要求强度：【待补充：把「差不多」「尽量」改成「必须」或「可选」，并说明判定方式】
- 数量 / 程度：【待补充：把「一点」换成具体数量或区间（如 3 条 / 200 字以内），或可度量的程度（如「延迟降低 30%」）】
- 时间要求：【待补充：把「越快越好」换成具体截止时间或优先级（如今天 18:00 前给出第一版）】
- 交付物：可运行的代码 + 逐文件变更说明

## 上下文与约束
- 背景：【待补充：现状 —— 框架与版本、既有实现、相关文件、业务前提】
- 约束：
  - 语言与版本：【待补充：编程语言与版本，如 Node 20 / Python 3.11 / TypeScript 5.4】
  - 入口与涉及文件：【待补充：入口文件路径，如 src/index.js】
  - 不得改动的接口：【待补充：公共函数签名 / 导出名 / API 契约；没有就写「无」】
  - 错误处理：显式处理参数非法、IO 失败、超时等失败分支，返回可读错误信息，不吞异常、不静默失败
  - 依赖：优先使用标准库与既有依赖；新增第三方依赖必须说明理由与体积影响
  - 兼容性：不破坏既有测试与调用方，不顺手重排无关代码
  - 上面任何一项还没确定时，先问我，不要自行假设。

## 输出格式
- 完整可运行的代码（按文件路径分块，标明新增 / 修改）
- 变更说明：逐个文件说明改了什么、为什么
- 关键取舍：被放弃的方案与原因
- 运行与验证命令
- 用 Markdown 输出；不要复述本提示词；不要寒暄与铺垫。

## 验收标准
- [ ] 代码通过语法检查 / 编译，可直接运行
- [ ] 覆盖正常路径与至少两个边界或错误分支
- [ ] 不改变既有公共接口行为（除非明确要求）
- [ ] 提供可复制的验证命令或新增测试
- [ ] 无无关改动、无调试残留

## 待确认问题
- 目标语言与版本
- 入口文件与涉及范围
- 不允许改动的接口
- 验收命令或测试
- 如果这些无法回答，请明确列出你的假设并标注风险。

```

> 把这份改写再喂回引擎，评分从 **25** 提升到 **62**。

变更说明：

- **重组结构**：把混在一起的整段文字拆成「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，每节只放一类信息，逐条可对齐。
- **明确任务类型与目标**：判定为「代码实现」任务，并把隐含意图改写成「对什么对象做什么、交付什么」的显式表述。
- **消除模糊表述**：把「这个」「差不多」「一点」这类不可验收的说法换成可度量指标，无法确定的显式标为【待补充】而不是留给模型猜。
- **删除冗余与客套**：去掉重复的句子、反复强调的同一动作、流水账连接词与客套铺垫，只保留信息量最高的表述。
- **补齐缺失维度**：原文缺少上下文、约束、输出格式、验收标准、示例，改写后逐项补上（能推断的写成明确要求，不能推断的标为待补充）。
- **按任务类型补齐工程约束**：按「代码实现」补充该类任务必需的抓手（语言与版本、边界与禁止项、错误处理或受众与深度等），并写死输出格式。
- **写死验收标准**：给出可勾选的验收清单，让「做完了没有」有客观判据，减少来回返工。

总述：原文被判定为「代码实现」任务，工程规范度 25 分（low），其中 5 处表述无法验收，并缺少上下文、约束、输出格式、验收标准、示例。改写后把意图固定为「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，能推断的写成明确要求，不能推断的标为待补充。
---

## 例 3｜英文 code 任务（锚点丰富）

带文件路径、版本号与函数名，检查改写是否保住这些锚点。

### 原始提示词

```text
refactor src/hooks/useAuth.ts so it works under React 18.2.0, keep the useAuth signature.
```

### 引擎评估

- 工程规范度评分：**51 / 100**（清晰度：中）
- 语言：英文　任务类型：代码实现
- 规模：89 字符 / 1 行 / 1 句　模糊命中 1　冗余命中 0　具体锚点 2
- 维度覆盖：已有 目标、约束　缺失 上下文、输出格式、验收标准、示例

问题清单：

| 严重度 | 类别 | 问题 | 原文证据 |
| --- | --- | --- | --- |
| 高 | 缺失要素 | 缺少验收标准 | — |
| 高 | 缺失要素 | 缺少输出格式 | — |
| 中 | 缺失要素 | 缺少上下文 | — |
| 中 | 缺失要素 | 缺少示例 | — |
| 中 | 结构 | 缺少结构分节 | — |
| 中 | 结构 | 整段连写（一坨） | `refactor src/hooks/useAuth.ts so it work`、`keep the useAuth signature.` |
| 中 | 风格 | 没说想要什么形式的回答 | — |
| 中 | 模糊表述 | 指代不明确 | `it` |

### 改写结果

```markdown
# Task: Implement Code

## Goal
- refactor src/hooks/useAuth.ts so it works under React 18.2.0, keep the useAuth signature.
- Deixis: [TODO: replace "it" with a concrete name (file / module / page / requirement)].
- Deliverable: Runnable code + per-file change notes

## Context & Constraints
- Background: [TODO: current state — frameworks and versions, existing implementation, related files, business premise]
- Fixed anchors (do not rewrite): `src/hooks/useAuth.ts`, `React 18.2.0`
- Constraints:
  - Language & version: [TODO: e.g. Node 20 / Python 3.11 / TypeScript 5.4]
  - Entry point & files involved: [TODO: e.g. src/index.js]
  - Public interfaces that must not change: [TODO: exported names / signatures / API contract; write "none" if N/A]
  - Error handling: handle invalid input, IO failures and timeouts explicitly; return readable errors; never swallow exceptions
  - Dependencies: prefer the standard library and existing deps; justify any new dependency
  - Compatibility: do not break existing tests or callers; no unrelated rewrites
  - If any item above is not yet decided, ask me before starting instead of assuming.

## Output Format
- Complete runnable code, split by file path, marked new/modified
- Change notes: what changed per file and why
- Key trade-offs and rejected alternatives
- Run / verification commands
- Output in Markdown; do not restate this prompt; no greetings or filler.

## Acceptance Criteria
- [ ] Code parses or compiles and runs as delivered
- [ ] Covers the happy path plus at least two boundary or error cases
- [ ] No existing public behaviour changed (unless requested)
- [ ] A copy-pasteable verification command or new test is provided
- [ ] No unrelated changes, no debug leftovers

```

> 把这份改写再喂回引擎，评分从 **51** 提升到 **83**。

变更说明：

- **重组结构**：把混在一起的整段文字拆成「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，每节只放一类信息，逐条可对齐。
- **明确任务类型与目标**：判定为「代码实现」任务，并把隐含意图改写成「对什么对象做什么、交付什么」的显式表述。
- **消除模糊表述**：把「it」这类不可验收的说法换成可度量指标，无法确定的显式标为【待补充】而不是留给模型猜。
- **补齐缺失维度**：原文缺少上下文、输出格式、验收标准、示例，改写后逐项补上（能推断的写成明确要求，不能推断的标为待补充）。
- **保留具体锚点**：原文里的路径 / 版本 / 标识符 / 数字（「src/hooks/useAuth.ts」「React 18.2.0」 等 2 处）全部保留，避免改写时丢信息。
- **按任务类型补齐工程约束**：按「代码实现」补充该类任务必需的抓手（语言与版本、边界与禁止项、错误处理或受众与深度等），并写死输出格式。
- **写死验收标准**：给出可勾选的验收清单，让「做完了没有」有客观判据，减少来回返工。

总述：原文被判定为「代码实现」任务，工程规范度 51 分（medium），其中 1 处表述无法验收，并缺少上下文、输出格式、验收标准、示例。改写后把意图固定为「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，原文的 2 处具体锚点原样保留，能推断的写成明确要求，不能推断的标为待补充。
---

## 例 4｜bugfix 任务

描述了现象但没有复现步骤、期望/实际与回归验证方式。

### 原始提示词

```text
登录的时候报错，refreshToken 那个函数好像有问题，Node 20 下面就会崩溃，帮我修一下
```

### 引擎评估

- 工程规范度评分：**34 / 100**（清晰度：低）
- 语言：中英混合　任务类型：缺陷修复
- 规模：51 字符 / 1 行 / 1 句　模糊命中 2　冗余命中 0　具体锚点 2
- 维度覆盖：已有 无　缺失 目标、上下文、约束、输出格式、验收标准、示例

问题清单：

| 严重度 | 类别 | 问题 | 原文证据 |
| --- | --- | --- | --- |
| 高 | 缺失要素 | 缺少验收标准 | — |
| 高 | 缺失要素 | 缺少目标 | — |
| 高 | 缺失要素 | 缺少输出格式 | — |
| 中 | 缺失要素 | 缺少约束 | — |
| 中 | 缺失要素 | 缺少上下文 | — |
| 中 | 缺失要素 | 缺少示例 | — |
| 中 | 结构 | 缺少结构分节 | — |
| 中 | 结构 | 整段连写（一坨） | `登录的时候报错`、`refreshToken 那个函数好像有问题`、`帮我修一下` |
| 中 | 风格 | 没说想要什么形式的回答 | — |
| 中 | 模糊表述 | 不确定的表述 | `好像` |
| 中 | 模糊表述 | 指代不明确 | `那个` |

### 改写结果

```markdown
# 任务：缺陷修复

## 目标
- 指代明确化：【待补充：把「那个」替换成具体名称（文件 / 模块 / 页面 / 章节 / 需求）】
- 要求强度：【待补充：把「好像」改成「必须」或「可选」，并说明判定方式】
- 交付物：根因说明 + 最小修复 + 回归测试

## 上下文与约束
- 背景：【待补充：现状 —— 框架与版本、既有实现、相关文件、业务前提】
- 固定锚点（不得改写）：`refreshToken`、`Node 20`
- 约束：
  - 复现步骤：【待补充：操作步骤 / 输入数据 / 环境（版本、平台）】
  - 期望行为 vs 实际行为：【待补充：分别写清，例如「期望跳转首页 / 实际返回 500」】
  - 根因要求：说明为什么会发生（触发条件、相关代码路径），不要只描述改了什么
  - 修复范围：最小改动，不做无关重构、不顺手改风格
  - 回归测试：新增或更新一个「修复前失败、修复后通过」的用例
  - 证据：涉及日志、堆栈、报错码时原样引用，不要改写
  - 上面任何一项还没确定时，先问我，不要自行假设。

## 输出格式
- 根因（一句话）
- 最小修复（diff 或完整文件）
- 复现与验证步骤（命令 / 操作序列）
- 新增的回归测试
- 影响面与回滚方式
- 用 Markdown 输出；不要复述本提示词；不要寒暄与铺垫。

## 验收标准
- [ ] 按复现步骤不再触发问题
- [ ] 新增回归测试修复前失败、修复后通过
- [ ] 根因有证据支撑（日志 / 堆栈 / 代码行）
- [ ] 没有改变无关行为

## 待确认问题
- 稳定的复现步骤
- 期望行为与实际行为
- 环境与版本
- 相关日志或错误码
- 如果这些无法回答，请明确列出你的假设并标注风险。

```

> 把这份改写再喂回引擎，评分从 **34** 提升到 **68**。

变更说明：

- **重组结构**：把混在一起的整段文字拆成「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，每节只放一类信息，逐条可对齐。
- **明确任务类型与目标**：判定为「缺陷修复」任务，并把隐含意图改写成「对什么对象做什么、交付什么」的显式表述。
- **消除模糊表述**：把「那个」「好像」这类不可验收的说法换成可度量指标，无法确定的显式标为【待补充】而不是留给模型猜。
- **补齐缺失维度**：原文缺少目标、上下文、约束、输出格式、验收标准、示例，改写后逐项补上（能推断的写成明确要求，不能推断的标为待补充）。
- **保留具体锚点**：原文里的路径 / 版本 / 标识符 / 数字（「refreshToken」「Node 20」 等 2 处）全部保留，避免改写时丢信息。
- **按任务类型补齐工程约束**：按「缺陷修复」补充该类任务必需的抓手（语言与版本、边界与禁止项、错误处理或受众与深度等），并写死输出格式。
- **写死验收标准**：给出可勾选的验收清单，让「做完了没有」有客观判据，减少来回返工。

总述：原文被判定为「缺陷修复」任务，工程规范度 34 分（low），其中 2 处表述无法验收，并缺少目标、上下文、约束、输出格式、验收标准、示例。改写后把意图固定为「目标 / 上下文与约束 / 输出格式 / 验收标准」四节，原文的 2 处具体锚点原样保留，能推断的写成明确要求，不能推断的标为待补充。

---

## 截断行为

直接调用引擎时，输入超过 `MAX_INPUT`（20000 字符）会被截断，并产生一条 `severity: high` 的 `style.truncated`。

| 项 | 值 |
| --- | --- |
| 原始输入长度 | 24000 字符 |
| 实际参与分析的文本 | 20000 字符 |
| 上限 | MAX_INPUT = 20000 |

产生的 finding：

```text
[高] style.truncated — 输入超长已截断
原始输入 24000 字符，超过上限 20000，只分析了前 20000 字符。
```

经过插件调用时，Host 会在更早的位置截断并补写同样 id 的 finding，且生效上限被夹取到 `MAX_INPUT`；两层的行为与合并规则见 [README 第 6.2 节](../README.md#62-超长输入的截断行为)。

---

## 复现全部实例

```powershell
cd E:\plug\dsh-plugin-prompt-optimizer
node --test "tests/*.test.mjs"     # 56 个测试
node tools/build-host.mjs          # 重新生成 lib/index.js
node tools/build-client.mjs        # 重新生成 lib/client.js（内联引擎）
node tools/gen-examples.mjs        # 重新生成本文档
```