前言¶
在 DeepSeek Harness（DSH）里看 agent 跑工具时，工具卡里往往是一整段命令、脚本或 API 调用。懂开发的人能顺着读，不熟悉编程的人只能猜「它在改什么」。会话里若再叠一层说明面板，又会和代码块抢版面、重复解释同一件事。
下面介绍的 dsh-code-explainer 走另一条路：在工具卡的输入代码和输出区上，用行尾注释把「这行在做什么」和必要的「为什么这么写」写进同一句中文，不单独占一块教学区域。复制代码时拿到的仍是原始文本，注释不参与 DOM 正文。
这是什么¶
dsh-code-explainer 是 DSH 的客户端插件，维护者为 xiaoluoli45。它针对 agent 实际执行的代码、命令和工具输出做逐行（或按输出类型分级）的中文解释，面向「不想先学语法也想跟上 agent 在干什么」的读者。
插件分两半：浏览器端（client.js）负责在会话 DOM 里挂注释、处理输出区版式；宿主端（index.js）用本地规则先给说明，规则覆盖不了的行再通过可配置的 LLM 补一句。说明通过 POST /line-notes 等本地 HTTP 接口下发，前缀为 /dsh-code-explainer/api，仅接受回环地址。
当前仓库版本为 0.4.1（见 package.json），许可证 MIT。
核心功能¶
输入代码块：灰色行尾 // 注释¶
工具卡里的输入代码按行解析（依赖 DSH 代码块 DOM：pre > code > span.line）。每一行末尾用 CSS 伪元素挂上中文说明，样式比代码略淡，与语法高亮并存。
- 空行、纯括号行、纯注释行不强行加说明。
- 同一种写法在同一代码块内只在第一次出现时完整解释，后续可标「（同上）」。
- 术语首次出现可带简短中文对照（例如
await（等待异步完成））。 - 代码块标题栏有 「注释：开 / 注释：关」 总开关，状态记在浏览器
localStorage；关掉后恢复纯代码视图。
注释写在伪元素里，不会进入 textContent，因此复制按钮和手动选中都不会带上说明。
输出区：按类型区分¶
| 输出类型 | 处理方式 |
|---|---|
| 代码（源码、脚本片段、diff） | 逐行行尾说明，前缀用蓝色 →，与输入区的灰色 // 区分 |
| 普通文本（目录清单、日志、纯数据） | 块首加一句总述（「这段输出是……」），仅对关键行（报错、退出码、找不到文件等）加说明，不逐行硬凑 |
输出若为代码，会先去掉类似 1: 的行号再按行说明。总述节点插在宿主 ioSection 外侧，避免破坏其两列 grid 布局（插件内用 test/output-card.mjs 回归这一条）。
解释覆盖面¶
本地规则覆盖命令行、常见工具调用（如 tools.ops_bash）、参数行、赋值与 await、console.log、import / require、fs、path、process.env 等。规则表列不出的复杂行，在 llm 为 auto 时由模型按行号补一句；llm: off 则只用规则，不调模型。
工具卡仍在 data-state="running" 时，前端只展示规则结果，状态结束后再异步请求模型补充，避免半截代码反复触发 LLM。
隐私、成本与降级¶
展示、落盘和发给模型前，会对 sk-...、ghp_...、Bearer ... 等凭据样式做掩码。模型请求按代码内容哈希缓存，同一段代码不重复调用。模型不可用、超时或 JSON 解析失败时，页面保留规则说明，不阻塞工具执行，也不改写用户当前会话的模型选择。辅助调用不向会话日志追加事件。
安装与启用¶
环境要求：DSH >= 0.2.0，Node >= 20。
在本地已有仓库目录的前提下，用 link 方式装进 desktop profile（路径换成你机器上的绝对路径）：
dsh plugin --profile desktop add "link:<本仓库目录的绝对路径>"
安装后刷新 DSH 页面（Ctrl+R）或重启宿主。package.json 声明了 dsh.bundle.patch，宿主会把 cordis.patch.yml 挂到 profile 层，一般不需要改 DSH 安装目录本身。
卸载：
dsh plugin --profile desktop remove dsh-code-explainer
配置（cordis.patch.yml）¶
安装时也可由 profile 传入等价片段：
- insert:
- id: dsh-code-explainer
name: './index.js'
config:
llm: auto
# provider: deepseek-official
# model: deepseek-chat
常用配置项：
| 键 | 默认 | 含义 |
|---|---|---|
enabled |
true |
插件总开关；false 时完全不工作 |
llm |
auto |
规则不足时是否请模型补；off 仅本地规则 |
provider / model |
空 | 显式指定补充用模型；留空则尽量复用当前会话最近一次请求的模型路由 |
maxInputChars |
8000 |
发给模型的输入上限 |
maxOutputTokens |
900 |
模型输出 token 上限 |
timeoutMs |
25000 |
单次模型调用超时 |
concurrency |
2 |
模型补充并发上限 |
页面上的「注释：开/关」管展示；enabled 管插件是否启动，两者不是同一层开关。
典型用法与界面行为¶
安装并启用后，在 DSH 会话里让 agent 执行带代码的工具卡即可，无需额外命令。插件通过 MutationObserver 跟踪会话 DOM，React 重渲染后会补回行尾属性，并每 3 秒兜底扫描一次。
README 中的效果示意：输入区类似下面结构时，每行行尾会出现中文说明（此处仅作格式参考，实际注释由插件生成）：
const r = await tools.ops_bash({
command: "Get-ChildItem -LiteralPath 'D:\\project'",
description: "List directory contents",
timeoutMs: 60000
});
console.log(JSON.stringify(r, null, 2));
维护者在 DSH 0.2.1-rc.5 上对 run_code 等路径做过实测（插件 0.4.0 时段），验证了动态 import("node:fs") 的解释、try/catch 表述、长注释换行不挤代码、复制不含注释等行为。离线冒烟测试见仓库 node test/smoke.mjs、node test/output-card.mjs。
需要只看规则、零模型成本时，把配置里的 llm 设为 off。需要排查插件状态时，可调用本地 API，例如 GET /dsh-code-explainer/api/health、GET /state。
适用场景与注意¶
适合谁
- 需要向非技术同事演示或共读 DSH 会话、又不愿在代码外再维护一套说明的人。
- 自己读 agent 日志时，希望命令行和常见 Node/API 写法有即时中文对照的开发者。
边界与依赖（摘自仓库「已知边界」）
- 只处理会话里工具卡内的代码块，不处理 Markdown 正文里的围栏代码。
- 依赖宿主代码块 DOM 契约；DSH 前端大改时需同步改选择器。
- 复杂嵌套表达式、链式调用、模板字符串等可能只得到一句通用说明或未识别标记。
- 「注释：开/关」存在浏览器本地，不随账号同步。
权限与安全
插件随当前 DSH 进程运行，宿主端可调用你配置的 LLM 路由处理规则未覆盖的代码片段。安装前应阅读仓库源码与 MIT 许可；社区目录 SkillHub 插件页 与 GitHub 仓库相互独立，均不等同于 DeepSeek 或幻方的官方应用商店。
结尾¶
dsh-code-explainer 把「agent 写了什么」收成工具卡上的行尾中文：规则先出结果，必要时再由模型补洞，并可一键关掉注释或关掉 LLM。若你在 DSH desktop 场景里需要这种读代码方式，可按 link 安装并在 cordis.patch.yml 里调 llm 与限额。
