前言¶
在 DeepSeek Harness（DSH）里让智能体写代码、写文档，常见摩擦不是「模型不懂话」，而是需求里缺几个只有你知道的答案。模型会按默认值猜，成品不对再改一版——来回比开工前问清楚贵得多。社区插件 dsh-clarify（澄清模式）把「问」挪到动手之前：打开开关后，模型先复述要求，再用自带的访谈面板逐题确认，最后给出一张需求卡，你点「确认开工」之后才开始改文件。维护者是 pyc123720，仓库 pyc123720/dsh-clarify，当前版本 0.4.0，许可证 MIT；在 SkillHub 插件目录 中分类为「工作流」。
下面按「它是什么 → 能做什么 → 怎么装 → 怎么用 → 注意边界」介绍，事实均来自项目 README 与 package.json。
这是什么¶
一句话：Ask first, build once——可选的澄清模式，让智能体在开工前访谈你，再按你批准的需求卡执行。
插件通过 Cordis 补丁挂进 DSH，向模型注入「问题优先」的提示词，并提供 clarify_ask、clarify_brief 等工具；Web 客户端在输入框上方渲染访谈面板，状态落在宿主 $DSH_HOME/clarify/state.json，不依赖浏览器本地存储。TUI 或 headless 环境没有面板时，会自动退回内置问答，且一次只问一题，不会把多题塞进一个回答框。
运行环境要求（见 package.json）：Node >= 22.19.0，DSH >= 0.2.0-rc.1 且 < 0.3.0。
核心功能¶
访谈面板（0.2 起由插件自渲染）¶
打开澄清开关后，提问出现在输入框上方的面板里，而不是挤在一个聊天回复框里：
- 每题独立一块：题号、标题、问题、说明；
- 每题 2–4 个具体选项，第一项为推荐值且默认选中；另有独立输入框，手写会覆盖选项；
- 顶部进度可折叠；底部有「全部按推荐」「提交答案」；可「跳过」让模型用默认值继续，或用「×」关掉面板交还对话；
- 面板状态存在宿主，刷新或切换会话再回来，题目与答案仍在；模型在等待时不会自行往下执行。
快问 / 完整：mode=quick 只展示第一题；mode=full 为完整批次（默认）。部署级默认由配置项 interviewMode 决定，工具参数里的 mode 优先。
focus：模型可把 focus: '格式' 等传给 clarify_ask，面板显示「只问：…」标签，供人阅读，不改变过滤逻辑。
需求卡确认与任务边界¶
问完后模型通过 clarify_brief 写出需求卡，同一块面板请你选择：确认开工 / 还要再问 / 我自己改，并可附自由修改说明。批准后卡片写入 state.json，并在后续每轮提示词中作为锚；输入框右侧胶囊在「已确认」状态下可点「卡」查看。
批准后的卡还会落盘为 Markdown（默认路径 <会话 cwd>/.dsh/clarify/card-YYYYMMDD-HHMM-<标题>.md），便于进版本库、换会话或换 agent 时查阅。可通过 cardFile: false 关闭写文件，或用 cardFileDir 指定目录；写文件失败只记 warning，不影响批准本身。
新任务边界：换对象、换交付物或说「下一个」视为新任务，须重新澄清；对上一结果的局部修改（如「第 2 节改成…」）可直接做。面板底部「开始新任务」可清卡。
验收清单¶
clarify_brief 可附带 checklist（最多 6 条，建议 3–5 条），追加在卡片末尾，例如：
**验收清单**
- [ ] PDF 能打开
- [ ] 页数正确
清单在确认面板中先展示；批准后进入状态、提示词锚、cards.json 与落盘 .md。已批准会话的锚会要求模型开工后按清单逐条自查并在回复中说明是否做到。
记忆复查¶
同目录 cards.json 保留最近 8 张已批准卡。新一轮未批准会话的提示词中，除访谈脚本外还会带上最近 3 张卡的标题、批准日期与前 300 字——仅作参考，旧卡不会被当成当前需求；已定事项不必重复问，推荐值可优先沿用。
信息类型与「已开工」过滤¶
每题可声明 kind：goal（目标与成功标准，只在动手前问）、input（默认）、constraint、context。插件通过 session/event 观察写文件类工具调用（如 write、edit、apply_patch 等，见 lib/work-tracker.js）；一旦会话「已开工」，同会话的 goal 题会被丢弃。只读工具不算开工；追踪仅在进程内存中，重启后重新判断。
侧栏待答提示与其它会话¶
若模型在另一个会话里提问，当前会话侧栏底部会出现待答计数（如 ⏳ 1），便于切过去作答。该指示只读聚合接口，不参与面板心跳。
指标（本地）¶
每次访谈与确认会向 $DSH_HOME/clarify/metrics.json 追加记录（最多 500 条）。可用仓库内脚本查看汇总：
node tools/stats.mjs
node tools/stats.mjs --file D:/my/metrics.json
node tools/stats.mjs --json
GET /api/clarify/health 可返回版本、待答数、卡片档案条数、访谈记录条数及各面是否挂载正常。
安装与启用¶
官方安装方式为仓库内的 PowerShell 脚本（不是 dsh plugin add github:… 这类拼接命令）。步骤如下：
- 完全退出 DeepSeek Harness；
- 在插件源码目录执行：
.\install.ps1 -DryRun # 只看会做什么
.\install.ps1 # 拷贝到默认目标并 link 进 profile，补全 dsh.profile.bundles
- 重新打开 DSH，输入框右侧应出现「澄清」胶囊。
常用参数：-Profile 指定 profile；-Target 指定拷贝目标（默认示例为 E:\dsh-env\plugins-local\dsh-clarify）；-Uninstall 从 profile 移除（保留源码）。升级已有安装：重跑 .\install.ps1 覆盖 lib/ 后重启应用。
安装后可在本机自检（端口以实际 DSH 为准）：
Invoke-RestMethod http://127.0.0.1:<端口>/api/clarify/health
期望 JSON 中含 ok: true、version: "0.4.0" 以及 surfaces 等各面状态。
在 profile 的 cordis.patch.yml 中，行 id 为 clarify 的配置示例：
- id: clarify
config:
sectionOrder: 3050
storePath: ''
guidance: true
defaultEnabled: false
interviewTimeoutMs: 1200000
cardFile: true
cardFileDir: ''
interviewMode: full
整行禁用：同一 id 下加 disabled: true。guidance: false 时只保留开关与工具，不注入提示词；defaultEnabled: true 则新会话默认开启澄清。
典型用法¶
界面开关与命令¶
输入框右侧胶囊四种状态：关（「澄清」灰点）、开（「澄清中」）、有待答（「先答 N 个问题」）、已确认（「已确认」+「卡」）。也可在聊天中使用：
/clarify
/clarify on|off|status
模型侧流程（提示词约定）¶
开启后，模型被引导为：
- 先复述「要做 X、用来 Y、交付成 Z」，能自行查的先查；
- 用
clarify_ask提问，默认 1 个最关键题；仅当多件事彼此独立且都卡住下一步时一次给 2–3 个，不超过 3； - 澄清阶段只读不写；用户说「别问了直接做」则停止追问；
- 最多两轮访谈，之后须交需求卡，带着写明的假设开工。
小任务可用快问模式或只问一个点；需求卡须非空且配清单时条目应可勾选、可验收，避免空泛口号。
无面板环境¶
TUI / headless 下宿主检测不到客户端轮询时，退回内置问答且一次一题；子 Agent 中确认需求卡会得到 no_client，不会永久卡住。
适用场景与注意¶
适合：交付物形态、范围、约束、验收标准经常在第一轮描述里说不清的任务；希望需求卡落盘、换 agent 仍能续上的项目；需要在开工前结构化对齐、减少返工的团队或个人工作流。
务必知晓：
- 插件以当前 DSH 进程权限运行；安装前请自行阅读源码与 MIT 许可证，确认信任维护者与代码行为。
- 「澄清阶段只读不写」是提示词与确认门，不是沙箱：插件不会拦截
write/bash等工具。 - API 经宿主连接围栏与本机 loopback 规则保护；同机无 cookie 的
curl等仍可能访问——设计上是方便自检，局域网/公网无有效浏览器会话的请求会被拒绝。 - 面板依赖客户端轮询心跳（约 15 秒内无轮询则视为无面板）；面板 20 分钟无人答（
interviewTimeoutMs）会超时，问题改在聊天正文里继续。 - 状态按 session id 存储；fork 或新 id 不会自动带上澄清状态，需重新点开关。
- SkillHub 目录为社区生态站点，与 DeepSeek / 幻方无官方从属关系；星标等元数据以目录页为准（当前线索为 GitHub 2 stars）。
结尾¶
dsh-clarify 把「返工三次」换成「问三个问题」：访谈面板、需求卡确认与验收清单落在 DSH 工作流里，而不是散落在长对话里。若要进一步了解或提交 issue，见 GitHub 仓库 与 SkillHub 目录页。
