@lidaxi/prompt-enhance

dsh plugin --profile web add @lidaxi/prompt-enhance

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


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

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

文档

• [贡献指南](CONTRIBUTING.md) — 报告问题 / 提交代码 / 开发与测试
• [更新日志](CHANGELOG.md)
• [安全说明](SECURITY.md)
• [许可证](LICENSE) — Apache-2.0

结构

文件 · 内容

lib/index.js · Host 半（ESM 静态 Cordis 插件）：注册 POST /api/prompt-enhance/enhance，按模式读取会话 cwd 与最近对话历史 → 采集项目上下文（目录结构 + 依赖/配置/入口文件，关键词命中优先；根 AGENTS.md 自动作为事实块）→ 调会话默认 LLM 重写提示词（失败自动降级重试 + 回退候选模型链，最多 3 个候选）。

lib/client.js · 浏览器半（window.__ModuleLoader__.load 手写 bundle）：在 conversation.input.right 注册模式选择 + ✦ 按钮、conversation.input.overlay 注册对比面板与浮动提示条；fetch 调 Host 路由（同源）。

cordis.patch.yml · bundle 补丁：向 profile 组合树插入插件行 prompt-enhance（部署可经 $DSH_HOME/cordis.patch.yml 或 --patch 覆盖其 config）。

package.json · main = Host 半、exports["./client"] = 浏览器半、dsh.bundle.patch、dsh.client 声明。

功能（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 写登录"，本轮输入"把登录接口加上"，增强会自动带上最近对话结论，输出直接引用刚才的方案。

模式选择建议

场景 · 推荐模式 · 说明

随手润色、不依赖项目 · 基础 · 快、省 token，纯文本层面清理

需要引用项目结构/依赖/入口 · 标准 · 读取目录树 + 关键配置与代码（3 层预算）

深层任务分析 + 验收标准 · 专家 · 更大上下文预算 + 任务分析 + 可验证验收标准

网关不支持推理档位 · 任意（配 effort: none） · 在 cordis.patch.yml 中为该模式关闭档位发送

故障排查

现象 · 错误码 · 处理建议

"未能读取到项目上下文" · NO_CONTEXT · 确认会话已关联工作目录且目录可读；临时可切换为基础模式

"当前会话未关联工作目录" · NO_CWD · 先打开一个项目工作区，或切换为基础模式

"候选模型均调用失败" · ALL_MODELS_FAILED · 检查网络/网关/模型配置，或切换为基础模式

"未找到可用模型" · NO_CANDIDATES · 在 DSH 设置中配置模型后重试

增强超过 120 秒无结果 · （客户端超时自动取消） · 检查网关延迟；可配置该模式 effort: none 或调大 maxTokens

浏览器控制台报错 · （自动上报诊断环） · GET /api/prompt-enhance/log 查看最近请求与错误详情

配置

插件读取组合行 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: 500

…(truncated)