# dsh-answer-pet

> 为 DSH Web 桌面宠物插件，实时显示回答进度、多会话状态卡、模型轨迹，支持内置蓝鲸/橘猫/银渐层猫三个可换主题。

## Metadata

- Author: [@Nanki-nn](https://github.com/Nanki-nn)
- Repo: <https://github.com/Nanki-nn/dsh-answer-pet.git>
- GitHub: [Nanki-nn/dsh-answer-pet](https://github.com/Nanki-nn/dsh-answer-pet)
- Stars: 10
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `desktop-pet`, `dsh-plugin`
- Forks: 1
- Open Issues: 1
- Last push: 2026-08-16T15:44:25.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
为 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 Web | 未声明 | 需通过 `dsh plugin --profile web add` 安装；修改 Node half 或 schema 后必须重启 `dsh web` |
| Node.js | 未声明 | 本插件未声明 engines；CONTRIBUTING 提示开发环境使用 Node 20+，本地构建脚本使用 `import.meta.dirname` |
| 操作系统 | 跨平台 | Web 端运行，无原生模块依赖 |
| 原生模块 | 无 | 纯 JS，零 native binding |

## 安装方式
```bash
dsh plugin --profile web add github:Nanki-nn/dsh-answer-pet
```

## 配置项
写在 `<dshHome>/settings.yaml` 的 `answer-pet` section：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `theme` | 字符串 | 宠物主题 id，可选 `blue-whale`（默认蓝鲸）/ `orange-cat`（橘猫）/ `silver-shaded-cat`（银渐层猫），未知值回退到蓝鲸 | `blue-whale` |
| `size` | 数字 | 宠物高度像素（48–200） | `96` |
| `corner` | 字符串 | 停靠角，可选 `br`（右下）/ `bl`（左下）/ `tr`（右上）/ `tl`（左上），拖拽后会脱离停靠角 | `br` |
| `opacity` | 数字 | 宠物常态透明度（0.2–1） | `1` |
| `pollMs` | 数字 | 状态轮询间隔毫秒（200–5000），越小越平滑但流量越大 | `800` |
| `showBar` | 布尔 | 是否显示进度卡片；设为 `false` 时永远不显示展开面板 | `true` |
| `showBubble` | 布尔 | 是否显示宠物头顶的状态气泡 | `true` |

## 常见问题

**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` 开发并内置构建。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-answer-pet](https://deepseek-plugin.org/plugins/Nanki-nn/dsh-answer-pet)
Wiki generated by AI (model: `MiniMax-M3`)