项目概览

Clarify 是 DeepSeek Harness 的 Host 插件。它绑定当前真实 Session，读取用户草稿与模型可见上下文，沿当前模型路由生成苏格拉底式问题、上下文相关选项、后续分支和 live Draft preview。用户每回答一个问题，后续状态与预览稿都会吸收已经确认的决定；仍有关键未知时继续追问，预览已经可发送时进入审阅。

澄清完成后，Clarify 冻结当前预览并返回一份待用户确认的 Draft。终端中的 SeekTTY 会把它写回普通输入框，用户可以继续编辑并决定何时发送。其他 Surface 可以通过同一组 Remote 接入；仓库自带的 GET /clarify 提供 Host DIY 页面。

真实推理由同一 Host 进程中的 Auxiliary Runtime 执行并单独计量。Clarify 专注于澄清状态机与 Draft 生成，模型准备、流式输出、限额、取消和辅助用量由 Auxiliary Runtime 统一承接。

[当前 Session + 用户草稿]
              |
              v
     +------------------+      start / answer / refine
     | 消费 Surface     | --------------------------------+
     | SeekTTY 或 DIY   | <-------------------------------+|
     +--------+---------+      问题 / 选项 / live Draft    ||
              |                                           ||
              | accept                                    vv
              |                                  +------------------+
              |                                  | Clarify          |
              |                                  | 决策与预览状态   |
              |                                  +--------+---------+
              |                                           |
              |                                           | 同进程 run
              |                                           v
              |                                  +------------------+
              |                                  | Auxiliary Runtime|
              |                                  | 模型 / 限额 /用量|
              |                                  +------------------+
              v
       [待确认 Draft]
              |
              | 用户审阅并发送
              v
       [正式 Session 消息]
              |
              | 需要实施方案时
              v
       [Harness 原生 /plan]

Clarify 与 Plan

Clarify 和 Plan 接在同一条工作流的前后两段。

Clarify 处理“要做什么还需要问清”的阶段：读取当前 Session 与输入草稿，逐题追问，并把答案写进不断更新的 live Draft preview。采用之后，你得到一份与当前 preview 一致的 Draft，可以在普通输入框里确认和修改。

Plan 处理“需求已经明确、需要决定怎么做”的阶段：Harness 原生 /plan 把已经提交的需求写成实施方案，并进入计划审查。

推荐路径是先用 /clarify 问清需求并采用 Draft，审阅后发送，再在需要时运行 /plan。Clarify 产出用户需求草稿，Plan 产出实施方案，两者共同覆盖从模糊想法到可执行工作的完整过程。

使用体验

在 SeekTTY 中

兼容的 Clarify 六方法 Remote 与 clarify.wire/1 激活后，SeekTTY 会把 /clarify 加入本地命令目录。0.2.2 已发布（tgz + SHA256SUMS），但不是推荐联合基线；已发布回滚工件仍是 0.2.1 / 0.2.0。

• 从命令面板执行：保留整个输入区作为 seed。
• 输入 /clarify some text：以参数文本作为 seed。
• 在现有草稿末尾单独加入 /clarify token 或一行：以前面的草稿作为 seed。

需要继续澄清时，界面通常一次只显示一道基于上下文生成的问题、对应选项和最新 Draft preview；预览已经达到可发送状态时，流程会直接进入审阅。提问次数由当前 Session、草稿和已确认决定共同确定。你可以选择选项、输入自定义答案、直接 refine 当前预览、采用当前 Draft，或结束本次澄清。采用后，完整 Draft 回到普通输入框；发送仍由用户明确完成。

Host DIY 页面

GET /clarify 使用相同的 /api Remote，适合集成验证和其他 Surface 开发。页面要求填入一个已经存在的 sessionId，澄清结束后可以复制 Draft，并在原 Surface 中自行发送。

工作原理

动态问题与逐答预览

问题、选项和 Draft preview 均由模型根据当前 Session、初始草稿、已经接受的决定和上一版预览动态生成。每轮输出都经过结构化校验；新预览需要体现本轮决定，后续问题会沿已经确认的方向继续深入。refine 接收一次性反馈，在保留已确认决定的基础上重写当前预览。

临时澄清状态

每个进程绑定已有 sessionId，状态为 running、cancelled、stale 或 complete。默认 15 分钟无交互后进入 stale，并返回 staleReason=ttl-expired。Session、模型路由或上下文发生影响一致性的变化时，进程也会以明确原因进入 stale。终态 Draft 通过单独的 fetchDraft 返回。

主 Session 对话记录

问题、选项、live Draft preview 和 refine 反馈保留在 Host 内存中的临时进程里。主 Session transcript 继续保存正式对话：用户审阅并发送后的消息、助手回复、工具记录，以及随后 /plan 产生的计划审查。澄清状态与 input queue、pending、Plan、Goal、Profile 和本地文件相互分离。

辅助模型用量

每一次模型调用都经同进程 auxiliaryRuntime 执行，用量写入官方 storageDomain 的 auxiliary_runtime 域。官方 tokenUsage 继续表示 Agent 循环。SeekTTY /status 在快照健康时分栏展示 Official、Auxiliary 和读取时派生的 Combined。配对规则只写在文档里：Host 0.1.1-rc.2 配 Auxiliary Runtime 0.1.1，Host 0.1.0-rc.8 配 0.1.0（0.1.1 仍承认 rc.8）。Clarify 不把这对规则做成 wire 或公共 API 检查。

辅助账本保存调用标识、purpose、状态、Token 桶、规范化失败和时间戳。prompt、消息正文、模型输出、自定义回答、凭据和文件路径保留在账本之外。

快速开始

已发布旧栈（回滚）

最近一次联合验收仍是官方 @deepseek-ai/dsh@0.1.0-rc.8 + Clarify 0.2.1 + Auxiliary Runtime 0.1.0 + SeekTTY 1.2.0。从 GitHub Releases 安装已经构建好的 tarball。

在终端体验 /clarify 时，把三包安装进同一个 tui Profile：

pnpm add --global @deepseek-ai/dsh@0.1.0-rc.8

dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/seektty/releases/download/v1.2.0/seektty-1.2.0.tgz
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/dsh-plugin-auxiliary-runtime/releases/download/v0.1.0/dsh-plugin-auxiliary-runtime-0.1.0.tgz
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/dsh-plugin-clarify/releases/download/v0.2.1/dsh-plugin-clarify-0.2.1.tgz
dsh --profile tui

Host DIY 页面使用独立的 web Profile：

dsh plugin --profile web add https://github.com/Hilbert-beinghappy/dsh-plugin-auxiliary-runtime/releases/download/v0.1.0/dsh-plugin-auxiliary-runtime-0.1.0.tgz
dsh plugin --profile web add https://github.com/Hilbert-beinghappy/dsh-plugin-clarify/releases/download/v0.2.1/dsh-plugin-clarify-0.2.1.tgz
dsh --profile web

卸载和重装继续使用官方原生命令：

dsh plugin --profile tui remove dsh-plugin-clarify
dsh plugin --profile tui add https://github.com/Hilbert-beinghappy/dsh-plugin-clarify/releases/download/v0.2.1/dsh-plugin-clarify-0.2.1.tgz

已发布 0.2.2（非推荐联合基线）

Clarify 0.2.2 已发布 GitHub Release（tgz + SHA256SUMS），并在精确 stock @deepseek-ai/dsh@0.1.1-rc.2、无 SeekTTY 下做过校验和核验。Web-only T7 见 docs/t7-evidence/0.1.1-rc.2/t7-full.json 与 t7-full-report.md；入库 G0 仍见同目录 t7.json。Auxiliary Runtime 0.1.1 也已发布。这不是新的推荐联合基线，也不是完整联合验收；推荐回滚仍见上一节。

Host DIY / Web-only 安装只添加已发布 Clarify（及如需推理的已发布 Auxiliary），不要把 SeekTTY 写进新推荐组合：

pnpm add --global @deepseek-ai/dsh@0.1.1-rc.2
dsh plugin --profile web add https://github.com/Hilbert-beinghappy/dsh-plugin-auxiliary-runtime/releases/download/v0.1.1/dsh-plugin-auxiliary-runtime-0.1.1.tgz
dsh plugin --profile web add https://github.com/Hilbert-beinghappy/dsh-plugin-clarify/releases/download/v0.2.2/dsh-plugin-clarify-0.2.2.tgz

安装会按 package.json#dsh.bundle.patch 中的 cordis.patch.yml 更新目标 Profile。Cordis 子上下文让 Clarify 等待 auxiliaryRuntime，Auxiliary Runtime 等待官方 storageDomain；服务激活由依赖可用性决定，与添加命令的先后顺序解耦。docs/t0-evidence/0.1.1-rc.1/ 仍是同日被替换版本的历史观察，不能代替 0.1.1-rc.2。

接口与兼容

Typert Remote 命名空间 clarify 提供六个方法：

消费者使用 stock Connection 信封，例如：

POST /api/clarify/start
Content-Type: application/json

{
  "type": "client-request",
  "rpcId": "<id>",
  "method": "clarify/start",
  "payload": { "args": { "sessionId": "<id>", "seedText": "optional" } }
}

公开兼容与验证声明分两层：

• 0.2.1 继承 0.2.0 的六方法 Remote、clarify.wire/1 和精确 rc.8 兼容边界。0.2.0 live-provider 联合验收覆盖动态问题／选项／preview、多轮演进、采用后只写回输入框、中断恢复、用量来源和隐私。0.2.1 未重跑 live-provider 动态多轮，也没有 cache／cost A/B。
• rc.6 / rc.7 只保留历史探针车道，不是 0.2.2 生产组合。

精确兼容矩阵与 T0 证据见 docs/compatibility.md 和 docs/t0-evidence/。pnpm t3 提供进程内 Remote 冒烟，真实 Host/TUI 验收使用联合轨道。

T0 探针由 CLARIFY_PROBE=1 或隔离 DSH_HOME/.clarify-probe 标记启用，并提供 GET /clarify/probe。这一入口服务于隔离测试夹具；日常 Profile 保持探针关闭。

开发

pnpm install
pnpm test
pnpm build
pnpm pack:check
pnpm t3
pnpm t0:dsh011rc2
pnpm t1:dsh011rc2
pnpm t0:dsh011rc1
pnpm t1:dsh011rc1
pnpm t0:matrix
pnpm t1:matrix
pnpm t7:validate
pnpm t7:from-pack
pnpm t7:from-release

pnpm t0:dsh011rc2 / pnpm t1:dsh011rc2 是当前生产精确 lane。pnpm t0:dsh011rc1 / pnpm t1:dsh011rc1 只复现同日被替换的 0.1.1-rc.1，不能代替 rc.2。pnpm t7:validate 核验已入库 t7/1 的结构与声明一致性，并报告实际分类；当前入库 G0 通过，但不是完整 T7。G0 是无 key 安全/遏制闸门：要求 INFERENCE_UNAVAILABLE 加上稳定的 provider-neutral providerFailureCode（本 lane 实跑为 ENOTSUP，不是 MISSING_CREDENTIAL）、未变的公开快照、已证明无 SeekTTY，以及 /clarify 六方法控件。--from-pack 不是用户价值证据。pnpm t7:from-release 是显式本地资产命令，必须同时提供已发布 dsh-plugin-clarify-0.2.2.tgz 与 dsh-plugin-auxiliary-runtime-0.1.1.tgz 及对应 SHA256SUMS；版本来自已知输入，文件名必须精确匹配。无 key / mock 不等于完整 T7。Web-only 完整 T7 另见 t7-full.json / t7-full-report.md，不由 t7:validate 核验。

CI verify 运行测试、干净构建、打包检查和进程内冒烟。Release 前还会在三个项目的联合轨道中执行官方 Host、真实 PTY、安装、卸载和重装门禁。

许可

MIT