进程讲解抽屉 Qcsj777/dsh-process-panel

进程（dsh-process-panel）

给 DeepSeek Harness Web 的每条回答加一个 「进程」 入口：点开在右侧滑出一个抽屉，用简体中文、流式地 讲清这一轮智能体在做什么、为什么这么做、结果如何。

- 英文思考过程 → 中文转述（不逐字翻译）
- 工具调用（参数、文件名、命令）→ 中文说明在干什么、为什么
- 报错 → 先说人话含义，再说影响与下一步
- 讲解按回合隔离：一条回答对应一个抽屉、一份讲解记录

English: adds a Process entry to every answer in the DSH web UI. The
drawer streams a Simplified Chinese narration of that turn — what the agent was thinking, which tools it called and why, and what errors meant. One card per agent step; narration only runs while the drawer is open, closing it aborts the in-flight call.

dsh plugin --profile desktop add github:Qcsj777/dsh-process-panel

入口在哪

| 位置 | 什么时候出现 | 点击效果 |
| 回答末尾的操作行（复制 / 好的回答 / 有问题的回答 旁边） | 该回答已经完成 | 打开这一轮的执行讲解 |
| 输入框下方的「这一轮正在生成，可以看 进程」 | 该轮还在生成中 | 同上，可以边跑边看 |

抽屉右上角两个按钮：

- 收起：抽屉滑走但连接保留，讲解继续，随时再点开。
- 关闭：断开连接，立即中止正在跑的讲解调用（不再消耗 token），已有讲解保留；下次点开接着讲，不从头再来。

头部会显示这一轮已消耗的讲解 token（约 1.2k tokens = 模型没回 usage，按字符估算）。

工作原理

主 agent 的一个 step（一次思考 + 这一步的动作） │ ├─ session/event：request/header、user/message、step/start、step/end、 │ assistant/message、tool/call、tool/result、turn/end └─ agent/assistant-stream：reasoning-delta、text-delta、finish（token 级实时流） │ ▼ Host 半：按回合（turn）建租约，把同一个 step 的素材攒成一份 → 结算 → 队列串行调用 LLM「讲解员」 │ ▼ SSE（同源 EventSource，带 session + turn） Client 半：抽屉里逐字渲染中文卡片，一条卡片 = 一个 step

- Host 半（index.js）：两级状态 —— sessions 存 step 素材（思考、回复、工具调用与结果），turns 存讲解记录、观众（SSE 连接）、队列、backlog、token 累计。路由 GET /process-panel/stream?session=<id>&turn=<n>。
- Client 半（client.js）：注册三个槽位 —— conversation.chat.assistant-actions（已完成回答的操作行）、conversation.composer.dock（生成中的入口）、shell.overlay（右侧抽屉，frame 级浮层）。
- 讲解用当前会话自己的模型路由（request/header 的 provider/model），不写进会话日志、不触发新的 assistant-stream，不会打断智能体、不污染对话。

一个 step = 一条讲解（严格一对一）

主智能体一条回答里是 思考 → 工具 → 思考 → 工具 → 回复，抽屉里就是同样条数的卡片，不合并、不拆分，标题写明 第 1 轮 · 第 3 步 · 工具。

- 边界以 step/start / step/end 为准（比从流帧推断可靠）：step/end 之后再等 120ms 让同一提交的 assistant/message、tool/call 落进来；如果这一步还有工具没返回，就等最后一个 tool/result；turn/end 会把本回合剩下的 step 全部结算（边界标成 完成 / 中断 / 失败）。
- 每个 step 只调用一次模型：输入只含本步素材，不会混进别的 step；不会再出现「主智能体三次思考、子代理合成一段」的错位。
- 串行队列：同一回合的讲解按 step 顺序逐条生成，先后不会乱。
- 允许不播报，但不留空卡：讲解员认为没有新增信息时可以输出空内容，此时用一句确定性兜底文案占位（如「调用 web_fetch 已经完成。」），仍然一步一张卡。
- 报错只报本步的：错误原文只取本步的 tool/result.error / 流式 finish.reason.failure / agent/error。
- 截断是显式的：只有程序真的截断长文本时，输入里才出现 …（后面还有内容，已省略）；提示词规定只有看到它才可以说「内容被截断」，避免误报。
- 用哪个模型讲：不另配模型，跟随当前会话本轮的 provider / model（取自 session.requestHeader().config）。没拿到路由就无法开讲，会提示「当前会话还没有可用的模型路由（先发一条消息试试）」。

租约：打开才讲、关闭即停、重开续讲

- 没人看就不调用：某个回合的抽屉没打开时不调用模型，只把结算好的 step 攒进 backlog（上限 400 条）。
- 打开即补播：抽屉打开时先回放已有卡片，再把 backlog 里攒下的环节按顺序讲出来。
- 打开得晚也讲全：如果该回合还没有任何讲解，也没有 backlog，就从会话快照 snapshotEvents() 把这一轮所有 step 补讲一遍（不设条数上限；只有完全没有素材的 step 跳过）。补讲串行执行，环节多时会一条一条往下走。
- 关闭即中止：SSE 断开 → AbortController.abort() 立刻掐掉在跑的讲解调用，未开讲的任务退回 backlog；再次打开接着讲。
- 重连只回放：重新打开抽屉只回放已生成的卡片，不会因为「点进进程」而重算一遍。

可调参数

都在 index.js 顶部：

| 常量 | 默认 | 含义 |
| SETTLE_GRACE_MS | 120 | 流结束后等多久结算，让同一提交的其它事件先落进来 |
| STALE_STEP_MS | 180000 | 一个 step 超过这么久没动静就强制结算 |
| MAX_TOKENS | 1200 | 单条讲解最大输出（含模型思考预算；设 320 时会被思考吃光、正文为空） |
| REASONING_CHARS | 1800 | 思考原文喂给讲解员的截断长度 |
| ANSWER_CHARS | 700 | 模型回复原文的截断长度 |
| REQUEST_CHARS | 260 | 用户请求的截断长度 |
| PREVIEW_CHARS | 700 | 工具参数/结果的截断长度 |
| PREV_ITEMS / PREV_CHARS | 2 / 160 | 带上的前情播报条数与单条截断 |
| MAX_QUEUE / BACKLOG_MAX | 400 / 400 | 讲解队列上限 / 待补播上限 |
| MAX_ITEMS | 400 | 每个回合保留的讲解条数（重连回放用） |
| MAX_TURNS / MAX_SESSIONS | 160 / 32 | 缓存的回合数 / 会话数 |
| JOB_TIMEOUT_MS | 60000 | 单次讲解调用超时 |
| RETRY_DELAY_MS / RETRY_LIMIT | 500 / 2 | 失败重试等待与次数 |

测试

本仓库不带离线冒烟脚本（开发时的脚本依赖本地 DSH 安装目录）。改动后按下面的「安装与更新」重载，再在 DSH Web 里看一条真实回答的「进程」抽屉：生成中打开应逐条出现卡片，关闭应立即停掉讲解，再次打开应从已有卡片继续。

安装与更新

dsh plugin --profile desktop add github:Qcsj777/dsh-process-panel

本地开发时也可以把 profile 的 dependencies 写成 "dsh-process-panel": "link:D:/path/to/process-panel"。

- 改过 index.js：重启 DSH（或 disable → enable 该插件）让 Host 重新加载。
- 改过 client.js / locale/*.json：刷新页面（Ctrl+R）让渲染进程重新注册槽位。