dsh-explain-selection

Readme

# 选中解释 / dsh-explain-selection

在 DSH 里读回答时遇到不懂的词：**选中它 → 右键「解释」→ 贴着选区弹出一张讲解卡片**。
卡片里的文字照样可以选中再解释，**可以一层层追下去**——而全程**不会往你的对话里多写一个字**。

解释由宿主直接调用 `ctx.llm` 流式生成，**不写进会话日志、不进入主对话上下文**。
所以"追问把上下文刷爆、还得往上翻"这件事从根上不会发生。

## 演示

<!-- 维护提示：换 GIF 后必须把下面地址里的 v= 递增。
     注意必须直接用 raw.githubusercontent.com 这个地址。写成 blob/<分支>/<文件>?raw=true 的话，
     那一跳是 302 跳转，跳转目标会把查询串丢掉 —— 版本参数根本到不了真正被缓存的那个地址，
     于是换了图也没用。 -->
![选中术语就地解释，第二层带着父术语继续追问](https://raw.githubusercontent.com/KLAX54ix/dsh-explain-selection/assets/demo.gif?v=2)

完整录制，**1 分 15 秒未剪辑**。值得留意的三处：

1. 选中「临界指数」→ 右键 → **解释**。卡片贴着选区弹出，底部一行小字标着 **已带上下文（上下文 172 字）**。
2. 在卡片正文里继续选词：「磁化率」→「幂律」→「相变」……**一层层往下追**，每张卡片都标着它继承的**父术语**，例如 `已带上下文（父术语「磁化率」+ 上下文 68 字）`。层数不限。
3. 中途能看到一张卡片的 **`正在解释…`** 流式状态；而当父术语是**一整条公式**时，它照样接得住。

全程**对话里没有多出任何消息**：卡片不是消息，它只是浮在回答上方。

## 安装

```bash
dsh plugin add github:KLAX54ix/dsh-explain-selection
```

**DSH Desktop（桌面端）**：`desktop` profile 由 Electron 应用独占管理，命令行添加会被拒绝。
请在应用内 **设置 → 插件 → 添加插件**，填同一个地址：

```
github:KLAX54ix/dsh-explain-selection
```

安装后**重启一次应用**：`index.js` 是宿主半体，只在启动时加载；`client.js` 会自动热加载。

## 怎么用

| 动作 | 操作 |
|---|---|
| **解释** | 选中回答里的文字 → 右键 → **解释** |
| **复制** | 同一个菜单里的 **复制** |
| **继续追问 · 点术语** | 解释里带虚线下划线的词可直接点击，在它旁边开一张新卡片 |
| **继续追问 · 再选中** | 卡片正文里任意文字都能选中再解释，**层数不限** |
| **移动卡片** | 抓住头部左侧的 `⣿` 手柄拖动，松手即停在那里 |
| **归位** | 拖走后的卡片头部会出现 `⤺`；也可以双击手柄 |
| **拖拽时看归属** | 拖动过程中有一条淡虚线，从卡片指回它所解释的那几个字 |
| **拖拽时滚页面** | 按住卡片不放，滚轮照样滚动对话，方便把它放到当前屏幕外的位置 |
| **收起 / 展开** | 头部 `–` 收成贴着原文的小胶囊；点胶囊展开 |
| **关闭** | 头部 `×` |
| **关闭右键菜单** | `Esc`、点击别处、滚动、缩放窗口 |

## 它会怎么跟你说话

- **会联系上下文**：解释顶层选区时带**前后各 120 字**；在卡片里追问时带**父卡片那段解释 + 父术语**。
- **不是词就直说**：选中跨词边界的片段（例如从「浮动工具条」里只选到「动工」），它会告诉你这不是一个词、原本属于哪个词，**不会替你编一个含义**。
- **答案短**：两句话以内、最多 80 字，宁短勿长。
- **线索不足会承认**，不假装确定。
- **重复解释瞬时**：同一句话里的同一个词再解释一次，不发请求、不耗 token、立刻显示。

卡片底部有一行浅灰小字，例如 `已带上下文（上下文 240 字）`——它表示这次解释**实际带上了多少消歧信息**。没有这一行，说明本次切词没有可用上下文。

## 卡片跟着谁动

| 情况 | 结果 |
|---|---|
| 页面滚动 / 缩放 | 卡片跟着原文走 |
| 锚定中的卡片，父卡片移动 | **跟着动** |
| 被拖走（停靠）的卡片 | **不跟**，停在你自己放的位置 |
| 收起父卡片 | 它的子卡片**一起隐藏**（锚点在一个看不见的卡片里）；展开父卡片后回到原位 |
| 关闭父卡片 | 子卡片**一起关闭** |

## 与主对话上下文的关系

这是这个插件存在的理由，单独说明：

- **解释不进会话日志。** 宿主半体在自己的路由里直接调用模型，不经过 agent loop，所以这段问答**不是消息**。
- **卡片按会话销毁。** 切换项目或会话，卡片、原文标记、进行中的请求一起消失——不做归档、不做保留。
- **答案缓存只在内存里。** 不落盘、不进日志，刷新页面或重启即失效。

## 为什么答案又快又短

- **主动压低推理。** DeepSeek 适配器默认推理强度是 `high`，而 `max_tokens` 同时覆盖推理与答案——不压低的话预算会被推理吃光，卡片会被截断，而且又慢又贵。插件会**先查这个模型支持哪些档位，取最便宜的一个**（通常就是 `off`）。**不硬写 `off`**：DSH 会在发请求前拿它跟模型能力比对，模型没有这个档位就会直接失败——这正是 0.1.1 修掉的问题。
- **输入输出双向收紧。** 选中文本上限 400 字，输出上限 256 token，提示词硬约束 80 字。
- **内存答案缓存。** 重复查询 0 请求、0 token。

一次短术语查询是几百输入 token 的量级。

## 已知限制

- 客户端文案硬编码中文，未接 `ctx.locale`。
- 使用当前**默认模型**，不跟随单会话的模型切换。
- 术语是否可点，取决于模型有没有按约定输出 `[[术语]]` 标记；没有标记时用"选中 + 右键"嵌套。
- 缓存不持久化，重启即空。
- 未做整段批量解释。
- 本插件在 DSH 的 **developer preview** 期间开发（0.2.0-rc.2）。DSH 官方明确表示会有破坏性变更，升级后若失效请提 issue。

## 开发

设计推演、根因分析、踩坑记录与验证状态都在 **[NOTES.md](./NOTES.md)**。
源码只有四个文件，**没有构建步骤**。

## License

[MIT](./LICENSE)