dsh--prompt--enhance

prompt-enhance（提示词增强 · DSH 通用插件）

💡 觉得好用？去 dsh-plugin.org 查看插件详情并点个 ⭐，支持一下作者～

DSH Web profile 的静态插件：随 harness 启动自动加载，无需每次手动重新加载。任何机器、任何经 DSH 注册的模型/网关均可直接使用；模型能力差异由插件在运行时自动适配，无需修改代码。

文档

• 贡献指南 — 报告问题 / 提交代码 / 开发与测试
• 更新日志
• 安全说明
• 许可证 — Apache-2.0

结构

功能（v1.5.0）

• 通用模型适配（本次核心）：插件不针对任何厂商硬编码，所有能力差异都在运行时自动探测与降级：
  • 按模式发送 reasoningEffort（基础/标准默认 off 关推理、专家默认 high 深思）；模型/网关不支持或拒绝该参数（宿主报 UNSUPPORTED_REASONING_EFFORT、400、developer 角色不被接受等）时，自动在同一候选取掉档位重试一次，不影响可用性。
  • 隐藏推理吃光输出预算导致空输出时（含 0.2.0 宿主把「正常停止但零内容」抛出的 EMPTY_RESPONSE），自动同一候选显式关推理（off）并加大预算重试。注意：0.2.0 起「省略档位参数」不等于关推理——宿主会用模型默认档位补齐（deepseek 默认 high），所以恢复动作必须显式发 'off'。
  • 其它失败（限流、网络等）不重发同一请求：0.2.0 下「去档位」会被宿主补成默认档位，对专家模式等于把同一请求再发一遍、只让计费翻倍。
  • 默认模型失败自动按序回退候选模型（≤3 个），全失败才报错，并逐次记录失败原因。
  • 对“推理档位完全不可用”的网关，可在配置里把对应模式设为 effort: none（= 不带该参数，由宿主按模型默认决定；要真正关推理请用 off）。
• 三种增强模式（✦ 按钮左侧的模式按钮切换，选择记忆在 localStorage）：
  • 基础：纯文本润色，不读取项目上下文，快、省 token（去口头禅/修正错别字/补齐要素）。
  • 标准：结合项目上下文（目录结构 + 依赖配置 + 入口文件）重写，引用具体文件路径。
  • 专家：更深层上下文（4 层目录、更大字符预算）+ 任务分析 + 可验证验收标准。
• 会话历史上下文（v1.5.0）：标准/专家模式自动把当前会话最近 3 轮的「问题 → 结论」配对压缩后带上（仅人话问答与助手正文，工具结果/插件注入默认过滤），让增强结果贴合刚讨论过的方案；historyTurns: 0 可关闭。
• 智能项目上下文（v1.5.0）：文件读取预算按草稿关键词命中度分配（命中文件优先占 contentChars），项目根存在 AGENTS.md 时自动作为项目事实块读取（单文件上限 4000 字符）；不写任何文件、不新增交互。
• 对比确认：增强完成后弹出「原文 | 增强后」对比面板，点「采用增强结果」才回填输入框，或「放弃」保留原文。
• 可撤回：采用后 9 秒内可点「↩ 撤回」恢复原文。
• 会话内增强历史：每次成功增强/修订的结果自动记入历史（内存，上限 20 条，刷新页面即清空）；对比面板可展开「历史版本」查看并一键采用任一版本（沿用原文变更保护，采用后仍可撤回原文）。
• 忙碌状态卡：等待期间显示「正在增强（模式）… 已用时 N 秒」，带 取消 按钮（真正中断服务端流式调用）。
• 空输入禁用：输入框为空时 ✦ 按钮禁用。
• 待确认段独立展示：模型信息不足时生成的“待确认”清单会被插件从正文中剥离，单独显示在对比面板；采用/发送给大模型的永远是干净正文。
• 待确认问答闭环：模型优先从项目上下文自答（可标注“（假设：…）”），只剩必须由用户决定的事项进入清单；清单在对比面板逐条渲染为「问题 + 输入框」，点「按回答重新增强」把回答连同上一版增强正文发回 Host 做第二轮修订（模型把确认信息修订进正文，仍缺失再问），填过的回答按问题记忆在 localStorage，下次同类问题自动预填；也可以「跳过确认，采用结果」或「放弃」。
• 稳定性：输入态按宿主契约双通道读取（0.1.2-rc.1 起走 session 标准钩子 useInput，≤0.1.1 回退 props.input）；事件处理器只读右槽草稿镜像，不在 overlay 调钩子；提示框/撤回超时优先用宿主 timer 服务、取不到时回退浏览器定时器，提示框还可点击关闭；状态按 sessionId 分桶——切会话或同时挂多个 composer（右侧栏子智能体聊天）时面板/撤回/草稿镜像/在途请求互不串、互不清；写回草稿前校验 phase === 'plain'，被拒时只在面板内提示（不丢增强结果）；publish 定时器失败不阻塞状态推进；忙碌超时 120 秒自动取消；浏览器 JS 错误自动上报 Host 诊断环（GET /api/prompt-enhance/log 可查最近请求与错误）。
• 改写规则：语言与语气跟随草稿（代码/路径/术语逐字保留）；信息不足时列出最少关键待确认项（自动剥离展示，不写入正文），不编造。
• 可配置：模式参数、模型候选链等均可通过组合行 config 覆盖（见下节），部署适配零改码。
• 键盘快捷键：对比面板按 Esc 放弃、Enter 采用（焦点在回答输入框时 Enter 仍为"按回答重新增强"）；任意位置按 Ctrl+Shift+E（macOS Cmd+Shift+E）触发增强。
• 友好错误提示：Host 返回稳定错误码（NO_CONTEXT、ALL_MODELS_FAILED 等），客户端映射为用户可操作提示。

使用场景与最佳实践

典型场景

1. 快速润色需求描述（基础模式）：把一段口语化的需求描述（"帮我做个登录界面，要好看的"）在数秒内整理成含目标、约束、输出格式的完整提示词，不读取项目上下文，适合随手起草。
2. 为已有项目生成组件规格（专家模式）：在 React 项目里写"给商品列表加筛选功能"，专家模式会读取目录结构与关键代码，引用现有组件/接口路径，输出带验收标准的规格。
3. 结合现有 API 编写调用代码的需求（标准模式）：在含 API 定义的项目中写"实现用户注册"，标准模式会提取出入口文件与依赖，让提示词贴合项目真实技术栈。
4. 延续刚才的讨论（标准/专家）：上一轮刚讨论过"用 FastAPI 写登录"，本轮输入"把登录接口加上"，增强会自动带上最近对话结论，输出直接引用刚才的方案。

模式选择建议

故障排查

配置

插件读取组合行 prompt-enhance 的 config（Cordis apply(ctx, config)）。默认行为无需任何配置；需要适配特定模型/网关时，在 $DSH_HOME/cordis.patch.yml（对所有 profile 生效，机器级）或 --patch 覆盖层里写（同一 row id 的 config 会整体替换本行 config，所以请写全）：

# $DSH_HOME/cordis.patch.yml
- id: prompt-enhance
  config:
    maxAttempts: 3            # 候选模型链长度上限（1-6，默认 3）
    autoFill: true            # 是否自动从已注册 provider 补足候选（默认 true）
    candidates:               # 固定候选链（可选，优先于会话默认模型）
      - { provider: my-provider, model: my-model }
    system: ""                # 可选：完整替换内置系统提示词；留空字符串表示使用默认内置提示词
    modes:
      basic:
        effort: off           # 'off'|'low'|'high'|'max'（按模型支持发送）
                              # 或 'none'：不带该参数（宿主按模型默认补齐，不是关推理）
        maxTokens: 2000
        temperature: 0.4
      standard:
        effort: off
        maxTokens: 3000
        temperature: 0.3
        depth: 3              # 上下文采集：目录递归层数
        treeLines: 160        # 目录树行数上限
        treeChars: 7000       # 目录树字符上限
        fileChars: 6000       # 单个配置文件内容上限
        contentChars: 11000   # 文件内容合计上限
        historyTurns: 3        # 会话历史：最近 N 轮（0 = 不带）
        historyChars: 6000     # 会话历史字符上限
        extra: ""             # 追加到系统提示词的模式说明
      expert:
        effort: high
        maxTokens: 5000
        temperature: 0.2
        depth: 4
        treeLines: 260
        treeChars: 12000
        fileChars: 9000
        contentChars: 18000
        historyTurns: 3
        historyChars: 9000

安装（其他机器）

前提：已安装 DeepSeek Harness 并启用 web profile（dsh web）。

宿主版本兼容

插件两种契约都读（readInputState()），所以 web profile 与桌面版客户端通用。若在旧宿主上看到 ✦ 按钮恒为禁用，说明宿主给槽位传的值既不是 input 也不是 useInput——请附上宿主版本反馈。

方式一（推荐）：npm 一键安装

插件已发布到 npm registry，使用 DSH 官方插件命令安装：

# 安装
dsh plugin --profile web add @lidaxi/prompt-enhance

# 升级
dsh plugin --profile web update @lidaxi/prompt-enhance

# 卸载
dsh plugin --profile web remove @lidaxi/prompt-enhance

安装后重启 dsh web 并刷新页面即可。dsh plugin 会自动把本包加入 dsh.profile.bundles（包内 dsh.bundle.patch 组合补丁与 dsh.client.inject 浏览器半声明随 bundle 自动生效），无需手工编辑任何文件。

路由安全（v1.5.2 加固）

三条 /api/prompt-enhance/* 路由是 webServer 上的 exact 注册，而 DSH 的 /api 围栏是 prefix 路由——exact 命中即返回，围栏看不到它们（实测 0.2.0-rc.2：带 Origin: https://evil.example + Sec-Fetch-Site: cross-site 的 POST 能直接打到 enhance；同样头的 /api/gateway/* 是 403）。v1.5.2 起插件自己套上宿主的门禁：

另外：POST 若带非 JSON 的 content-type 直接 415（挡表单型跨站简单请求）；请求体 >1MB 返回 413 结构化错误（不再断连）；草稿上限 20000 字符；单条路由注册冲突只放弃该条（不再三条一起失效）；响应带 cache-control: no-store。

方式二：从源码安装（本地开发 / 贡献者）

仓库自带 install.ps1 / install.sh，clone 后在仓库目录直接执行：

.\install.ps1

chmod +x install.sh
./install.sh

脚本会自动：创建源码联接 → 同步安装副本（含语法与一致性校验）→ 注册依赖与 bundle（file: 依赖）。改完代码只需重新执行脚本 + 重启 dsh web。卸载用 .\uninstall.ps1 / ./uninstall.sh（安全：只删联接/副本/注册，保留本仓库源码）。

方式三：手动

# 1) 把插件源码放到 DSH 插件目录（<repo> = 本仓库 clone 路径）
Copy-Item -Recurse <repo> "$HOME\.dsh\plugins\prompt-enhance"

# 2) 注册依赖与 bundle（编辑 $HOME\.dsh\profiles\web\package.json）：
#    dependencies 增加：
#      "@lidaxi/prompt-enhance": "file:../../plugins/prompt-enhance"
#    dsh.profile.bundles 数组增加：
#      "@lidaxi/prompt-enhance"
#    （插件的 cordis.patch.yml 组合补丁与 dsh.client.inject 声明会随 bundle 自动生效）

# 3) 重启 dsh web，刷新页面

重启后：composer 发送按钮左侧出现 [模式 ▾] [✦]（✦ 为增强按钮）。

开发与调试

• 本地源码开发：改完源码后重跑 install.sh / install.ps1 同步到安装副本，再重启 harness 生效：

Copy-Item "$HOME\.dsh\plugins\prompt-enhance\lib\index.js", "$HOME\.dsh\plugins\prompt-enhance\lib\client.js" "$HOME\.dsh\profiles\web\node_modules\@lidaxi\prompt-enhance\lib\" -Force

# macOS / Linux
cp lib/index.js lib/client.js "$HOME/.dsh/profiles/web/node_modules/@lidaxi/prompt-enhance/lib/"

• 诊断：GET /api/prompt-enhance/log 返回最近请求记录（状态 / 耗时 / 所用模型 / 浏览器错误上报）。

工作原理

• Host 半（lib/index.js）注册 POST /api/prompt-enhance/enhance：按模式读取会话工作目录与最近对话历史 → 采集项目上下文（目录树 + 依赖/配置/入口文件，按草稿关键词命中优先；根 AGENTS.md 自动作为事实块）→ 用会话默认 LLM 流式重写提示词（失败自动降级重试：去档位 / 关推理加大预算，再回退候选模型链 ≤3 个，支持取消中断）。
• 浏览器半（lib/client.js）在 conversation.input.right 注册模式选择 + ✦ 按钮，在 conversation.input.overlay 注册对比面板 / 忙碌状态卡 / 提示条；采用增强结果前先对比原文与增强后，采用后 9 秒内可撤回。
• 模型能力适配：插件始终先按模式档位调用；任一失败（网关拒绝档位参数、适配器不支持、空输出、限流等）都会在同一候选上自动降级——先去掉档位参数重试，空输出（输出预算耗尽）则关推理并加大预算重试，仍失败再按序回退下一个候选。整个流程不依赖任何厂商特有的错误码或模型名单。
• 待确认清单：模型信息不足时生成的"待确认"段会被插件从正文剥离，不随正文发送给下游模型；用户可在对比面板逐条回答，插件带答案做第二轮“修订增强正文”调用（answers + baseEnhanced），返回修订后的正文与新清单。

通用兼容性说明

• 官方 DeepSeek API：完整支持（off / low / high / max 推理档位，基础/标准默认 off 实测 6-10s 出全量正文）。
• 任意 OpenAI 兼容网关 / 私有代理 / 内部模型：开箱即用。推理档位参数被网关拒绝（含 400、developer 角色不被接受、thinking 等参数不识别）时自动去掉档位重试；参数彻底不可用时把对应模式配置为 effort: none 即可跳过。插件不针对任何特定厂商做硬编码，新增模型无需改动。
• 推理模型：隐藏推理吃光输出预算导致空输出时自动关推理并加大预算重试；预算仍不足可在配置中调大该模式 maxTokens。

已知约束

• 增强模型默认 = 会话默认模型（agentDefaultModel.currentSelection()），失败回退候选模型链（默认 ≤3 个；可用 config.candidates 固定候选链、config.maxAttempts 调整长度）。
• 上下文采集上限（标准模式默认）：目录 3 层、树 160 行 / 7000 字符、文件内容合计 11000 字符、单文件 6000 字符；专家模式预算更大（4 层 / 260 行 / 12000 字符树 / 18000 字符内容）。均可按模式配置覆盖。
• 会话历史上下文（标准/专家，默认最近 3 轮）：仅当前会话、仅人话问答与助手正文（工具结果/插件注入默认过滤），historyTurns: 0 可关闭；历史随增强请求进入所用 LLM 网关（与项目上下文同级别，外部网关下历史内容会出本机）。
• 基础模式不依赖会话工作目录；标准/专家模式需要会话关联工作目录。
• 增强期间用户修改输入框则不覆盖，提示重试。

许可证

本仓库采用 Apache-2.0 许可证，贡献即代表您同意该许可证。