wuhua2026/dsh-prompt-enhance

description: "将粗略草稿转化为完整、可发送的请求（enrich）或执行器规范（spec），并带有程序化质量门禁。一个用于 DeepSeek Harness 的 Cordis 插件。"
kind: "package-reference"

dsh-prompt-enhance

摘要

dsh-prompt-enhance 将简短、描述不充分的请求改写为能够准确表达其真实意图的请求。它提供两种输出形态，因为正确的形态取决于谁来阅读该产物：enrich 返回以完整方式书写的同一请求，作为一句可直接发送的话；而 spec 将其包装为 Role/Task/Context/Constraints/Output format/Acceptance criteria 格式的简报，供另一个执行器使用。

三个界面共享同一条流水线：一个 /enhance 命令、一个模型可调用的 enhance_prompt 工具，以及输入框中的一个 ✨ 按钮，可在不发送的情况下就地改写。每个结果都由程序化守卫检查——实体保留、自适应长度守卫、引用依赖、工具名称规范——并且每次调用都会被记录，以便衡量采用情况而非凭猜测。

状态：原型，已在 DSH 0.1.5-rc.1 上作为动态 Cordis 插件完成端到端验证。 以下行为是经过实测的，而非假设的；标记为未验证的部分则确实未经验证，并已如实说明。

目录

- 它的功能
- 使用此包
- 守卫，以及它们过去产生的误报
- 实测行为
- 未验证
- 设计决策
- 仓库布局

它的功能

给定：

全面理解当前工作区

enrich 模式返回：

全面理解当前工作区，包括工作区的目录结构与文件组织方式、每个文件的用途与内容要点、文件之间的依赖与引用关系、
项目所用的技术栈与配置、构建与运行方式、代码风格与命名约定、已有的文档与注释、以及当前存在的待办事项、
未完成部分和潜在问题，对于无法从工作区中确认的信息不要臆测，应标注为待确认。

一段 9 个字符的草稿变成了一句 143 个字符的话，列举了此类请求实际涵盖的各个方面。你按下 Enter 并发送它。这就是该插件的全部意义所在：增强后的文本就是用户自己的请求，被补全了——而不是关于该请求的文档。

对同一输入使用 spec 模式则返回一份六段式简报：

角色：工作区分析助手。
任务：全面理解当前工作区，并输出一份结构化的理解报告。
上下文：…
约束：…
输出格式：…
验收标准：…

两者都是正确的。它们是面向不同读者的不同产物，而选错默认值会让该功能无法使用——一个想发送一句话的人不会手动删除六个段落标题。

使用此包

上下文策略：S0+

默认调用完全不发送任何对话历史——只有系统提示、一个固定信封和草稿。这保持了前缀稳定、调用成本低廉，并且意味着增强器永远不会写回已提交的历史记录。
零上下文的代价是一种新的失败模式：像 改一下上面那个（“change that thing above”）这样的草稿没有指代对象。一个靠猜测的增强器会生成格式良好的结果，却指向错误的对象，而用户不太可能注意到。因此：

1. 输出契约携带一个 needs_context 布尔值，并且提示词禁止猜测指代对象。
2. 当它为 true 且存在上一轮用户发言时，调用会附带该轮发言重试一次（S1）。
3. 如果仍然无法解析，守卫会抛出 FLAG needs-context，而不是悄悄返回某个看似合理的东西。

每次尝试都有自己的超时预算。在一对尝试之间共享一个预算，正是把一次有效的升级上报为失败的原因。

模式

| 模式 | 产物 | 默认 | 使用场景 |
|---|---|---|---|
| enrich | 同一个请求，完整写出；单行散文 | ✅ | 你想把自己的一句话补完整，然后发送 |
| spec | 角色/任务/上下文/约束/输出格式/验收标准 | | 结果要交给另一个执行器 |

界面

- /enhance  —— 命令界面。返回一条简短回执；命令渲染在模型历史之外，所以长文本不适合放在这里。
- enhance_prompt —— 可被模型调用的工具，带一个 mode 参数。返回完整报告。
- composer 的 ✨ 按钮 —— 读取草稿，通过包私有通道调用宿主，并把结果写回，但不发送。包含 ↩ 撤销（恢复增强前的草稿）和一个模式切换。

最小配置

cordis.yml（动态包形式）
- name: ./prompt-enhance.js

增强器通过 ctx.agentDefaultModel.currentSelection() 解析其路由，回退到第一个已注册的提供方。它从不硬编码模型名称。

守卫，以及它们过去产生的误报

每个结果都携带一张守卫表。每一行是 PASS、WARN、FAIL、FLAG 或 n/a —— 而 n/a 有意与 PASS 区分开，因为“守卫没有可检查的内容”不等于“守卫检查过并批准了”。把两者混为一谈，正是让一个失效的检查保持不可见的原因。

| 守卫 | 检查内容 | 它在开发中捕获的真实失败 |
|---|---|---|
| parseable | 回复是一个带 rewritten 的 JSON 对象 | 纯文本回复被挽救为 kind: 'bare'，而不是被丢弃 |
| entity-preserve | 文件名和多位数数字完全一致；时长和序数按数字值 | 报告为通过，但实际上什么都没检查，因为 length >= 2 过滤器丢掉了 5秒 和 第3个分支 |
| length-guard | 自适应：短草稿用绝对上限，长草稿用比例区间 | 在一个 9 字符草稿上触发了 WARN 9.44x —— 对 9 字符输入设比例上限在原理上就无法满足 |
| no-tool-names | 结果不提及任何类似工具标识符的名称 | 增强器被喂入了 AVAILABLE TOOLS (1) —— 一个只包含它自己的能力列表 |
| no-invention（spec） | 没有范围限制或预检查，而草稿从未要求过 | 将 不得编造（“不得编造”）报告为一项发明——一种元护栏，即正是提示词所要求的内容 |
| no-skeleton（enrich） | 单行散文，没有带标签的章节，没有列表形态 | 规范形态的输出泄漏进了一个其全部意义就在于不呈现规范形态的模式 |

这个教训可以推广：一个总是喊狼来了的护栏比没有护栏更糟，因为它破坏了读者信任绿色行的能力。当护栏触发时，先怀疑护栏，再怀疑产物。上述六个护栏中有三个在发布时带有误报缺陷，只有在针对真实草稿运行后才得到修复。

实测行为

所有数据均来自 DSH 0.1.5-rc.1 上部署的动态插件，模型为 deepseek-official/deepseek-flash，增强器使用 reasoningEffort: off（会话自身的选择是 max；继承它会把输出预算烧在思考上）。

| 指标 | 结果 |
|---|---|
| 延迟，enrich | 1.4–2.6 秒 |
| 延迟，spec | 2.4–3.5 秒 |
| 延迟，S0→S1 升级 | 4.7–5.0 秒（两次尝试，独立预算） |
| 输入 token | 150–860 |
| 输出 token | 110–740 |
| 指纹草稿上的实体保留 | 2/2 文件名完全一致，3/3 数量值均存在 |
| 引用处理 | 升级正确触发；未解析的引用被标记，从不猜测 |
| 采用情况 | 在加入 enrich 模式后，其作者报告在真实草稿上可被采用 |

延迟和 token 数据均为每次调用，读取自插件自身的 Facts 块，而非估算。

未验证

直言不讳，因为另一种选择是写一份夸大其词的 README：

1. 静态包组装。 此处所有内容均作为动态 Cordis 包验证。它从未作为静态包挂载到这台机器上，且此前两次静态插件尝试均在此失败（profile 路由上的 404，以及一个未收到任何 agent 事件的加载器上下文）。src/index.js 中的 harness. 调用是沙箱内置函数；静态移植会用 ctx.tools.register 和 Remote 服务替换它们。该移植尚未完成。
2. 能力对齐。 动态包的 ctx.tools 外观通过包自身的作用域解析读取，并丢弃其参数（dsh-cordis-host-runner/lib/types/guard.js），因此 agent 的真实注册表在那里不可读——实测为 1 个可见工具，而实际请求头中有 35 个。因此该功能被移除而非伪造，并由 no-tool-names 替代。静态包可以读取完整注册表，并可以实现原始检查。
3. 冷页面上的 Composer 按钮。 该按钮依赖 conversation.input.right 和 inputActions.setDraft；两者均已确认可用，且读取草稿必须在渲染期间进行，因为 useInput 是一个 React hook。已交互式验证，但未在冷启动客户端下验证。
4. 跨模型行为。 仅使用了 deepseek-flash。表单约束在其他模型上是否成立尚未测试。

设计决策

完整记录见 docs/design-decisions.md：十项决策及其各自的定案证据，包括那些最初判断错误的决策。要点如下：

- 输出形态由读者决定，而非由引擎决定（D1）。这正是“参考资料”与“可直接交付”之间的差别。
- 辅助模型调用不得继承操作者的推理预算（D2）。传入 reasoningEffort: 'max' 会返回 finish=max-tokens 且无正文。
- 比例上限不适用于短输入（D3）。这一点被学习了两次。
- 宁可告诉模型“没有能力列表”，也不要给它一个只有一项的列表（D5）。错误的列表可测量地降低了输出质量。
- 守卫必须针对其自身的失败模式进行验证，而不仅仅是其通过用例（D4）。

docs/verification.md 保存了原始迭代日志：测量了什么、数值是多少，以及因此发生了什么变化。

测试

npm test              # node --test test/            (25 tests)
npm run typecheck     # tsc --noEmit                 (needs npm install first)

在沙箱拒绝管道式子进程 stdio 的机器上（构建该插件的 Windows 主机就是这种情况），node --test 会在运行任何内容之前以 EPERM 失败。请使用：

npm run test:sandbox  # node --test --test-isolation=none test/guards.test.js

该测试套件针对六个守卫，既覆盖了旨在触发它们的输入，也*覆盖了旨在不触发它们的输入，包括 D4 中记录的三例误报，以及一个 KNOWN LIMITATION 测试，用于固定剩余的唯一缺口（被非英文散文替换的数字仍会被报告为丢失）。

仓库布局

src/
prompts.js     system prompts and tuned constants (extracted verbatim from the verified package)
guards.js      the six guards, each with the failure it exists to catch
llm-call.js    bounded streaming call, per-attempt budget, S0+ context assembly
index.js       Cordis plugin: command, tool, package-private RPC, adoption records
client.js      composer button (render-time draft read, write-back, undo)
test/
guards.test.js 25 tests, including the documented known limitation
docs/
design-decisions.md   ten decisions + evidence + the wrong first attempts
verification.md       iteration log: measurement -> change
examples/
dynamic-plugin.md     how to run this as a throwaway dynamic plugin, no build

许可证

MIT。见 LICENSE。