# 使用指南

## 安装与首次使用

本插件适用于 DSH `>=0.2.1-rc.2 <0.3.0`，已在桌面端 `0.2.1-rc.2` 接入。进度观察针对 DeepSeek Flash；当前实测模型为 DeepSeek V4.1 Flash 1017。其他模型不会自动进入观察范围。

1. 确认 DSH 原生翻译服务可用。两种摘要方式都需要插件依赖正常加载。
2. 在终端执行：

```powershell
dsh plugin --profile desktop add "https://github.com/Han-1413141/dsh-dev-thinkout/releases/download/v0.5.4/dsh-dev-thinkout-0.5.4.tgz"
```

3. 重新打开 DSH 桌面端，在插件列表中找到 `dsh-jev-progress` 并确认启用。
4. 打开插件详情，导入自己的 JeV Key。
5. 在支持的 DeepSeek Flash 会话中开始一项任务。输入框上方会出现进度入口，新的规划与小结会进入聊天正文。

如果 `dsh` 不在 PATH 中，用桌面安装目录里的 `resources/runtime/cli/bin/dsh.cmd` 替换命令中的 `dsh`。使用其他 profile 的用户，将 `desktop` 替换为实际 profile 名称。安装包内的包标识保留为 `dsh-jev-progress`，与仓库名称不同。

## 获取与导入 JeV Key

1. 打开 [JeV 官网](https://decision.vllm-sr.ai/)，点击 **Get API key**，阅读并确认服务条款。
2. 复制生成的 Key，并自行保存。官网只显示一次。
3. 在 DSH 本插件详情页，或输入框上方的「进度设置」中，展开「获取并导入免费 JeV Key」。
4. 粘贴 Key，点击「验证并导入」。显示「已配置」后完成连接；后续可用「检查连接」查看状态。

截至 2026-10-21，官方文档将 Decision API 标为免费服务，同时设置请求与 Token 额度。额度和服务状态以[官方说明](https://decision.vllm-sr.ai/docs)为准。

Key 优先保存在 DSH 本机凭据服务。Windows 缺少该服务时使用 DPAPI 加密文件；输入框不回显已有 Key，导入完成后清空。其他系统若不支持凭据写入，可在启动 DSH 前配置 `JEV_API_KEY` 环境变量。不要把真实 Key 放进会话、问题反馈或仓库。

## 选择摘要方式

| 方式 | 作用 | 费用说明 |
| --- | --- | --- |
| 轻量摘要 | JeV 筛选任务信息，独立调用 DeepSeek Flash 整理为自然中文 | 会增加轻量模型调用；金额按所用渠道和可用价格目录记录 |
| 原生翻译 | JeV 选择完整规划、阶段小结或明确进展，交给 DSH 原生翻译 | 不调用轻量摘要模型 |

在「进度设置 → 摘要方式」切换。设置只影响后续进展；旧记录保留，尚未返回的旧方式结果会被取消。原生翻译使用 DSH 的 Bing/Google 服务；若全局翻译方式需要写入主会话，本插件的独立翻译调用使用 Bing，不修改全局设置。

JeV 负责判断，不负责生成摘要正文。两种方式都过滤重复计划、代码、坐标和计算细节，保留具体任务推进、阶段结果、方案变化及阻碍。

## 调整输出多少

先调整「输出频率」和「筛选严格程度」：

| 选项 | 用途 |
| --- | --- |
| 较少 | 合并较小的进展，适合安静地查看任务 |
| 适中 | 默认选择，保留明确的新信息 |
| 较多 | 保留更多具体环节的推进 |
| 宽松 | 允许较轻的任务进展进入候选 |
| 均衡 | 默认筛选，兼顾连贯性与信息量 |
| 严格 | 优先显示重要结果和变化 |

需要细调时，展开「调整具体阈值」：

| 阈值 | 范围 | 默认值 | 调整效果 |
| --- | --- | --- | --- |
| 新信息置信阈值 | 0.50–0.95 | 0.70 | 越高越少接受相近的新内容 |
| 进展置信阈值 | 0.30–0.95 | 0.50 | 越高越要求内容确实属于任务进展 |
| 信息重要程度 | 0–4 | 0.50 | 越高越偏向阶段成果、变化和阻碍 |

这些选项按内容筛选，不是定时器。不会固定每隔若干秒生成一条摘要；长时间没有新的任务信息时，保持安静是正常行为。频率调高后仍会过滤重复句子和无关细节。

## 聊天中的显示

- **任务摘要**：概括本轮要做什么，单独显示。
- **方案与阶段小结**：穿插在对应思考或工具步骤附近。原始思考展开后，摘要跟随对应段落；步骤组收起时，摘要放在可见的组后。
- **当前进度**：输入框上方集中显示一条状态，点击可展开同一任务的进度历史。

DSH 使用「标准」工作步骤显示时，同组摘要按连续正文排列；超过四条默认显示最近三条，可展开此前记录。该折叠只影响显示，不限制摘要的生成。

「摘要显示」可以选择「原生正文 · 无标识」或「带小标识」。进度外观可以选择蓝色动态鲸尾、动态思考、原生思考标签或纯文字。动画在执行时播放，结束后停止，并遵循系统的减少动画设置。

关闭「显示底部进度」后，状态文字及历史入口隐藏，流程和设置的小入口保留。

## 阅读流程图

点击输入框上方的「流程」。

- 父框表示任务或阶段，里面是所属工作项。点击父框标题折叠或展开。
- 横向从左往右推进；竖向从上往下推进。在窗口顶部，或「进度设置 → 流程方向」切换，按会话保存。
- 明确的并行工作放在同一层，串行箭头表示已记录的递进关系。多个前后依赖可以形成分叉和汇合。
- 跨父任务的局部依赖标为「子任务串行」，具体涉及哪项工作可以在详情中查看。
- 实线表示记录中明确的关系，虚线表示模型判断的关系。缺少关系的记录单独归组，不因出现时间相邻而补造依赖。
- 点击工作项打开历史详情。大量历史保存在节点中，工作项超过八项的父任务首次默认折叠。

「定位当前」聚焦正在推进的工作；「展开全部」打开父任务；「适应宽度」调整缩放，最低保持 65% 阅读比例，超出部分可以滚动或拖动。顶部还可选择轮次和功能分支。

「已报告完成」表示存在明确的完成陈述，不等于独立验证通过。插件不改写主模型的任务清单，也不会因为普通工具返回成功就宣布整项任务完成。

## 查看用量与费用

「进度设置」显示当前会话的 JeV 和轻量调用；插件详情汇总本机保留的会话缓存。展示次数、输入/缓存/输出 Token、成功/失败/取消及费用估算。

JeV 按当前官方免费服务记录费用为 0。轻量调用使用可用价格目录估算；目录估算不是账户实际扣款。没有返回用量或没有价格时显示未知，不补成 0。

安装支持辅助调用接口的 dsh-cost-meter 后，插件会显示「已接入」，新调用归入对应会话的「插件辅助调用」。断线时进入本地队列，恢复后按请求 ID 去重同步。现行安装若缺少接口，独立用量显示继续工作；可选适配补丁及指定基线见 [cost-meter 兼容说明](../integrations/dsh-cost-meter/README.md)。

## 数据去向

工作摘要来自模型的思考流和任务事件。插件不会把它们作为新消息送回主模型，也不向主模型上下文注入提示词。

JeV 会收到筛选所需的受限段落和任务上下文；轻量模式还会向当前 DeepSeek 渠道发送独立摘要请求，原生翻译模式会调用翻译服务。JeV 官方说明请求与响应可能被记录用于改进模型，详见[服务条款](https://decision.vllm-sr.ai/terms)。常见凭据会先过滤，但自动过滤不等于对任意敏感内容的完整识别。

展示缓存位于 `~/.dsh/plugin-data/jev-progress`；不写入主会话日志。卸载插件不会自动删除缓存、已有凭据或 cost-meter 中已记录的账目。

## 常见问题

| 情况 | 处理方法 |
| --- | --- |
| 没有进度入口 | 确认插件在正确的 profile 中启用、DSH 版本匹配、翻译依赖正常，再重新打开桌面端 |
| 显示「请配置 JeV 密钥」 | 在插件详情导入自己的 Key，并检查连接 |
| Key 验证失败 | 重新复制完整 Key；401/403 通常表示无效，429 表示限流，连接失败时检查网络和官方状态 |
| 有思考但没有新摘要 | 确认使用支持的 Flash 模型；重复计划、实现细节和缺少新信息的段落会被过滤，可将频率调高或降低筛选严格程度 |
| 只有开头摘要 | 查看后续内容是否包含具体新进展；降低新信息阈值后观察新任务，旧记录不会重新整理 |
| 摘要集中在步骤组后面 | DSH 正收起该过程组；展开工作步骤后，摘要回到来源位置 |
| 流程中没有并行连线 | 只有明确记录或模型判断出的并行关系才会显示；旧记录可能缺少关系与任务归属 |
| 费用显示待定价 | 当前调用没有可用价格；保留实际 Token，金额等待确认 |
| cost-meter 没有辅助调用 | 检查插件是否显示「已接入」，并按兼容说明确认接口；不能只根据版本号判断 |

反馈问题时提供 DSH 版本、插件版本、摘要方式、错误码和复现步骤。涉及截图时，遮住 Key 与私人会话内容。

## 更新与卸载

更新：下载新 Release 的安装包，使用同一条 `dsh plugin --profile desktop add` 命令安装新包，再重新打开桌面端。

卸载：

```powershell
dsh plugin --profile desktop remove dsh-jev-progress
```