dsh-answer-pet

一句话定位

为 DSH Web 添加一只可换外观的桌面宠物，实时显示模型回答进度、token/速率、工具调用和多会话并发状态。

核心能力

• 实时显示回答进度：开始处理、思考、输出、工具调用、完成五个阶段，状态条在同一回合内单调填充。
• 多会话并发显示：每个运行中的会话展示一张独立的进度卡，纵向排列，互不干扰。
• 模型轨迹时间线：每张卡片内展示最近 4 条动作（分析任务、推理规划、组织回答、工具调用及结果），工具失败在时间线标红。
• 可换宠物主题：内置蓝鲸、橘猫、银渐层猫三套主题（基于声明式 PetTheme v1 契约），未知主题自动回退到默认蓝鲸。
• 工具调用隐私摘要：仅从 description / query / pattern / file_path / path / url 白名单字段提取短描述，不暴露完整命令或参数。
• 交互体验：宠物可拖拽，位置保存在浏览器本地；单击宠物触发主题眨眼；状态卡可折叠为数量按钮。
• 轮询 + SSE 双通道：流式 token 平滑靠 800ms 轮询更新，阶段切换通过 SSE 即时推送，避免 EventSource 被打爆。

技术实现

• 语言: JavaScript (ESM Node half + CommonJS client bundle)
• 关键依赖: schemastery（配置 schema 校验）、DSH 宿主 services（session/event 事件源、webServer HTTP 路由、settings 配置接入）
• 架构模式: 官方 bundle 插件双半体——Node half 监听 session/event 折叠进度/轨迹并通过 webServer.register 暴露 3 个 HTTP 端点；Client half 自渲染 DOM 与主题，零平台模块依赖，通过 fetch 轮询 + EventSource 订阅数据
• 入口文件: Node half .dsh-plugin/index.mjs / Client half .dsh-plugin/client.js（由 scripts/build-client.mjs 按运行时 → 主题 → 核心顺序拼接生成）

适用场景

日常和 DSH Web 交互时，希望直观看到模型当前是否在思考、输出多快、卡在哪一步工具调用，而不是盯着控制台日志。多会话并行开发或批量任务时，多张独立进度卡能帮你一眼分清哪个会话跑到了哪一步。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Nanki-nn/dsh-answer-pet

配置项

写在 <dshHome>/settings.yaml 的 answer-pet section：

常见问题

Q: 安装后看不到宠物怎么办？

A: 先确认用 --profile web 安装；然后停止并重新启动当前的 dsh web 进程，再刷新原来的 Web 页面。单独启动另一个 Web 服务不会更新当前页面。

Q: 升级插件后主题或配置不生效怎么办？

A: 插件的 Node half 监听宿主事件、配置 schema 由服务端注入；升级后必须重启 dsh web，仅刷新浏览器只会更新客户端样式。

Q: 设置了主题但仍显示蓝鲸？

A: 检查 answer-pet.theme 是否是 blue-whale / orange-cat / silver-shaded-cat 之一；未知或拼写错误的 id 会安全回退到默认蓝鲸，并不会报错。

Q: 进度为什么不是模型给出的精确百分比？

A: 大多数模型接口不会回报回答完成百分比。插件结合阶段权重、token 计数、maxTokens 与饱和曲线（1-exp(-out/600)）估算，真实 token usage 到达后会覆盖流式估算值。

Q: 工具调用面板会泄露命令或参数吗？

A: 不会。轨迹摘要只从 description / query / pattern / file_path / path / url 这几个白名单字段提取短描述，压缩空白并限制长度，不展示完整命令或原始 JSON。

Q: 如何恢复宠物的默认停靠角位置？

A: 在浏览器开发者工具执行 localStorage.removeItem('answer-pet:pos'); location.reload()；同时还想恢复进度条展开状态，再加一行 localStorage.removeItem('answer-pet:bar')。

Q: 空闲时为什么不显示数字 0？

A: 这是预期行为。数量按钮只在状态卡已收起且至少有一个运行中的会话时出现，空闲时保持界面简洁。

上手难度

入门 — 安装命令一行、配置 schema 字段直观可调；不需要写代码或修改源码就能用上，遇到问题通常重启 dsh web 即可。

已知问题与限制

• 进度是估算值：模型接口通常不返回精确的完成百分比，进度按 token 计数和饱和曲线计算，与真实剩余时间可能存在偏差。
• 升级需重启：修改 Node half 或配置 schema 后必须重启 dsh web 进程，仅刷新浏览器不会加载新的宿主逻辑和 schema。
• 拖拽后脱离停靠角：手动拖动过宠物后，corner 配置不再生效，新位置保存在浏览器 localStorage，删除 answer-pet:pos 才恢复默认角。
• 主题固定三选一：当前仅加载随插件构建、通过 PetTheme v1 契约校验的内置主题，不执行第三方任意 JavaScript 也不注入外部 SVG；如需自定义主题需按 docs/PET_THEME.md 开发并内置构建。

DSH Web 可扩展回答状态宠物框架：宠物主题、多会话进度与模型执行轨迹。

dsh-answer-pet 是一个 DeepSeek Harness Web bundle 插件和可扩展回答状态宠物框架。核心负责会话进度、模型轨迹和状态卡；声明式 PetTheme v1 负责宠物 SVG、动画、宽高比和阶段文案。默认使用蓝鲸，也内置橘猫示例主题和高相似度银渐层猫主题。

功能

• 可扩展 PetTheme v1：宠物外观与回答进度核心解耦。
• 内置蓝鲸、橘猫和银渐层猫三个主题；银渐层猫使用构建时注入的可信内嵌 PNG，不加载外部图片资源。
• 实时显示开始处理、思考、输出、工具调用和完成状态；工具失败会在轨迹中标红。
• 显示输出 token、token/s、耗时、进度百分比和文本片段。
• 多会话并发时，每个运行中的会话显示一张独立进度卡。
• 卡片内展示最近模型轨迹：分析任务、推理与规划、组织回答、调用工具及运行结果。
• 工具轨迹显示工具名、安全短描述、运行/完成/失败状态和耗时，不展示完整命令或原始参数。
• 状态卡可折叠；折叠后仅在有运行会话时显示会话数量。
• 拖拽位置持久化；单击宠物只触发主题定义的眨眼表现。
• 轮询与 SSE 结合：流式数据平滑更新，阶段切换即时刷新。
• 支持主题、尺寸、停靠角、透明度、轮询间隔、进度卡和气泡配置。

宠物主题

在配置中切换：

answer-pet:
  theme: silver-shaded-cat # blue-whale / orange-cat / silver-shaded-cat

主题更新会在下一次配置刷新时挂载。未知主题会安全回退到 blue-whale。

希望开发自己的宠物，请查看 PetTheme v1 开发指南。当前版本只加载随插件构建、通过契约校验的可信内置主题，不执行第三方任意 JavaScript，也不注入未经清理的外部 SVG。

安装

dsh plugin --profile web add github:Nanki-nn/dsh-answer-pet

安装后重启 dsh web，再刷新页面。升级插件时重复执行同一条安装命令即可。

模型轨迹和主题配置都由插件的 Node half 提供；从旧版本升级到 0.6.0 后必须重启 dsh web，仅刷新浏览器不会加载新的配置 schema。

回答进度

进度计算规则：

• 优先使用 assistant/chunk 的 usage 数据；流式期间按文本长度估算。
• 有 maxTokens 时按 outputTokens / maxTokens 填充。
• 没有 maxTokens 时使用饱和曲线估算，避免进度长期停滞。
• 同一回合内进度单调不减。
• 输出速率使用 EMA 平滑估算。

状态卡结构

每个运行会话对应一张状态卡，包含：

1. 标题行：运行状态圆点、会话标题、进度百分比。
2. 统计行：当前阶段、输出 token、token/s 和已运行时间。
3. 轨迹时间线：最近的模型动作、工具调用、状态和耗时。
4. 进度条：同一回合内平滑、单调填充；模型输出时显示流动效果。

多个会话同时运行时，卡片按会话独立更新并纵向排列。没有运行会话时不显示状态卡，也不显示数量按钮。

模型执行轨迹

每张运行会话卡都会展示最近的模型动作，例如：

分析任务 · 步骤 1                  1s
推理与规划                         3s
调用 grep · SessionEvent           2s
组织回答                           5s

轨迹状态通过时间线圆点区分：

• 蓝色呼吸圆点：当前正在执行。
• 绿色圆点：动作或工具调用已完成。
• 红色圆点：工具调用失败。

可识别的轨迹包括：

• 开始处理请求。
• 进入模型步骤并分析任务。
• 生成 reasoning 内容时显示“推理与规划”。
• 生成正文时显示“组织回答”。
• 原生 tool/call / tool/result 工具调用及结果。
• run_code 内部的 tool/code-dispatch-start / tool/code-dispatch 嵌套工具调用。

为避免轨迹区域过高，宿主最多保存最近 6 条，卡片显示最近 4 条。每个运行会话独立维护自己的轨迹。

参数与隐私

工具轨迹始终显示实际工具名，例如 read、grep、pwsh、web_search。参数区域只从以下白名单字段提取简短摘要：

• description
• query
• pattern
• file_path
• path
• url

插件不会在轨迹面板中显示完整 Shell 命令、完整工具参数或原始 JSON；摘要会压缩空白并限制长度。

交互

• 拖拽宠物：移动宠物，位置保存在 localStorage。
• 单击宠物：触发主题的单次眨眼，不移动、不切换位置。
• 展开状态：运行中的会话在宠物上方显示为多张独立卡片。
• 收起状态：卡片隐藏；有运行会话时，宠物下方显示数量按钮。
• 点击数量按钮：重新展开会话卡片。

配置

在 <dshHome>/settings.yaml 的 answer-pet section 中配置：

answer-pet:
  theme: blue-whale # blue-whale / orange-cat / silver-shaded-cat
  size: 96          # 宠物高度 px（48–200）
  corner: br        # 停靠角：br / bl / tr / tl
  opacity: 1        # 透明度（0.2–1）
  pollMs: 800       # /state 轮询间隔
  showBar: true     # 显示会话进度卡
  showBubble: true  # 显示状态气泡

常见问题

安装后没有看到宠物

确认插件安装到了 Web profile：

dsh plugin --profile web add github:Nanki-nn/dsh-answer-pet

然后停止并重新启动当前的 dsh web 进程，再刷新原来的 Web GUI 页面。单独启动另一个 Web 服务不会更新当前页面。

能看到宠物，但没有模型轨迹

轨迹依赖 Node half 监听 session/event。更新插件后必须重启 dsh web；仅刷新页面只能更新浏览器端样式，无法加载新的宿主逻辑。

为什么设置主题后仍显示蓝鲸

确认 theme 是已安装的主题 id。当前内置 blue-whale、orange-cat 和 silver-shaded-cat；未知或无效 id 会回退到蓝鲸。升级后还需要重启 dsh web，让新的 settings schema 生效。

为什么空闲时不显示数字 0

这是预期行为。数量按钮只在状态卡已收起且至少有一个运行会话时显示；空闲时保持界面简洁。

如何恢复被拖动的默认位置

在当前 DSH Web 页面打开浏览器开发者工具并执行：

localStorage.removeItem('answer-pet:pos')
location.reload()

如需同时恢复状态卡的展开状态：

localStorage.removeItem('answer-pet:bar')
location.reload()

为什么进度不是模型提供的精确百分比

多数模型接口不会报告“回答完成百分比”。插件根据阶段、token、maxTokens 和饱和曲线估算进度；真实 token usage 到达后会覆盖流式估算值。

架构

• .dsh-plugin/index.mjs：监听 session/event，按会话维护进度与 title/running 元数据，提供 /answer-pet/state、/answer-pet/events 和 /answer-pet/config。
• .dsh-plugin/src/progress.mjs：进度阶段机、token 填充和速率 EMA。
• .dsh-plugin/src/session-meta.mjs：从事件折叠会话标题和运行状态。
• .dsh-plugin/src/trace.mjs：折叠阶段与工具事件，生成有限长度、安全摘要的模型轨迹（宿主保留 6 条，客户端展示 4 条）。
• .dsh-plugin/client/themes/runtime.mjs：PetTheme v1 校验、注册、解析和蓝鲸回退。
• .dsh-plugin/client/themes/blue-whale.mjs：默认蓝鲸主题。
• .dsh-plugin/client/themes/orange-cat.mjs：橘猫示例主题和开发模板。
• .dsh-plugin/client/themes/silver-shaded-cat.mjs：去背景紧裁切原画与 SVG 状态动画覆盖层组成的银渐层猫主题。
• .dsh-plugin/client/index.mjs：主题无关的浏览器 DOM、状态卡、轨迹时间线和交互核心。
• .dsh-plugin/client.js：由构建脚本按运行时 → 主题 → 核心顺序生成的 DSH client bundle。
• docs/PET_THEME.md：主题契约、安全约束和开发流程。

本地开发

npm install
npm test
node scripts/build-client.mjs
node scripts/build-client.mjs --check

本地安装：

dsh plugin --profile web add "D:\AI\dsh\dsh-answer-pet"

客户端 bundle 修改后刷新页面生效；Node half 修改后需要重启 dsh web。

想报告问题、提交代码或新增宠物主题，请阅读 贡献指南。

License

MIT © Nanki-nn