需求澄清助手DESTINYwang0428/dsh-clarify

dsh-clarify

需求澄清优化插件：把你的自然语言补充、确认，再转化为 agent 可直接执行的指令。

- 输入框旁「澄清」按钮（带 | 分隔符，与权限选择器/导出对话区分），一键分析当前输入
- 本地规则引擎检测 8 类缺失要素（目标/背景/输入材料/约束/输出形式/验收标准/优先级/歧义），逐条反问
- 你逐条回答（可跳过）→ 生成紧凑指令（一行一个要素，token 精简）→ 一键回填输入框，确认后发送
- 可选 LLM 增强：配置 DEEPSEEK_API_KEY（系统凭据或插件设置）后，LLM 补充检测盲区并润色指令语句（同样要求紧凑输出）；不配置时纯本地规则也可用

安装

1. 把 dsh-clarify.mjs 复制到你的 profile 目录：

cp plugin/dsh-clarify.mjs ~/.dsh/profiles/web/

2. 编辑 ~/.dsh/profiles/web/cordis.patch.yml，在 insert 列表追加（参考 examples/cordis.patch.yml）：

- insert:
- id: dsh-clarify-widget
name: ./dsh-clarify.mjs?v=1

3. 重启 dsh web，打开任意会话，在输入栏「访问模式」选择器右侧即可看到「✨ 澄清」按钮。

修改插件源码后，记得把 ?v=1 的版本号 +1（如 ?v=2）再重启，让 loader 重新加载。

使用

1. 在输入框写下你的需求（口语化、模糊都可以）
2. 点击「澄清」打开面板：
- 面板展示原始需求和检测出的反问问题（每项可回答或跳过）
- 勾选「启用 LLM 增强」可让 DeepSeek 补充检测盲区并润色语句（需 API Key）
3. 点击「生成指令」：
- 未开 LLM / LLM 不可用 → 本地模板组装紧凑指令（# 任务 + 一行一个要素 + 一行待确认）
- 开 LLM → DeepSeek 生成优化版指令（同样紧凑，省 token）
4. 「回填输入框」把结果放回输入框（默认自动回填），确认后发送；或点「复制」粘贴到别处

示例

原始输入：

帮我处理一下数据，弄好一点

面板反问（本地规则）：

1. 你希望我具体做什么？请用一句话说清目标（例如：写一个脚本统计项目代码行数）。
2. 这个任务的背景是什么？例如：在哪个项目/目录下进行？为什么需要做这件事？
3. 需要我读取哪些文件、数据或链接作为输入？如果没有，请说「无需输入」。
4. 有什么约束或限制条件吗？例如：时间期限、指定语言/框架、不能动某些文件、范围边界等。
5. 你期望我以什么形式交付结果？例如：可运行的代码、Markdown 文档、JSON 数据、命令清单等。
6. 怎么算完成？有没有验收标准或预期效果（例如：能正常运行、输出正确、测试通过等）？

回答后生成（LLM 增强示例，紧凑格式省 token）：

任务：清洗销售数据 CSV 并输出
- 输入：读取 raw.csv
- 约束：清洗数据
- 输出：输出清洗后 CSV
- 验收：无空值，格式统一

HTTP API

| 路由 | 说明 |
| --- | --- |
| POST /dsh-clarify/api/analyze | 规则引擎检测 { text, maxQuestions } → 要素状态 + 反问问题（LLM 启用时补充） |
| POST /dsh-clarify/api/refine | 生成指令 { text, answers, useLLM, model } → 优化后指令（LLM 失败自动回退本地模板） |
| GET/POST /dsh-clarify/api/settings | 读写设置（存 ~/.dsh/dsh-clarify.json） |
| GET /dsh-clarify/client.js | 注入页面的客户端脚本（插件自动注入，一般无需手动访问） |

设置

设置保存在 ~/.dsh/dsh-clarify.json（首次运行时自动创建），也可在面板中调整：

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| llmEnabled | false | 是否启用 LLM 增强 |
| model | deepseek-chat | DeepSeek 模型（deepseek-chat / deepseek-reasoner） |
| apiKey | '' | 自定义 API Key；留空时回退到系统凭据 DEEPSEEK_API_KEY |
| maxQuestions | 6 | 最多反问条数 |
| autoAnalyze | true | 打开面板时自动分析 |
| fillPlaceholder | true | 生成后自动回填输入框 |

工作原理

- 本地规则引擎：对输入文本做 8 类要素检测（动作词/背景词/输入材料/约束词/输出词/验收词/优先级词/代词歧义），缺失项生成反问问题；回答后按 # 任务 → 一行一个要素 → 一行待确认 的紧凑模板组装，省 token。
- LLM 增强（可选）：调用 https://api.deepseek.com/chat/completions。两处使用——分析时补充反问问题、生成时把「原始需求 + 回答」整合为无歧义的紧凑指令（提示词强制一行一个要素、删除客套/重复/未提供标注）。任何 LLM 失败都会回退本地模板，不影响使用。
- 输入框回填：精确锚定 composer 输入框（textarea[data-phase]，InputBar 特有属性），React 受控组件兼容（原生 value setter + input/change 事件触发 onChange → setDraft）；找不到时回退为手动复制。
- UI 分隔：按钮两侧带 | 分隔符，与「访问模式」「导出对话」等相邻控件区分；右侧无控件时自动隐藏多余分隔符。

测试

node test/smoke.test.mjs        # 纯函数：规则表、要素检测、指令组装、设置存取
node test/integration.test.mjs  # HTTP：模拟 Cordis ctx 启动插件，验证 4 个 API 路由
smoke 覆盖：规则表完整性、要素检测（完整/模糊/空洞/约束/截断/空文本/questions id）、指令组装（全部回答/无回答/部分回答/LLM 回答）、设置读写。
integration 覆盖：设置读写、规则检测、本地模板生成、无 key 时 LLM 回退、client.js 注入、404 兜底。

许可证

MIT