PNG 桌宠 comfylies/dsh-png-pet

DSH PNG 桌宠

Windows 10/11 x64 专用的 DeepSeek Harness（DSH）桌宠插件。会话、模型、凭据、智能体和 Web UI 仍然全部由 DSH 拥有；这个插件只做一件事：把真实的 DSH 活动映射成一只透明 PNG 桌宠，并附带一个受限的会话栏。

它不是独立聊天客户端，也没有自己的模型、账号或数据目录。

| 平台 | Windows 10 / 11 x64（仅此一种，不支持 macOS / Linux） |
| 当前版本 | v0.4.0，插件 ↔ Helper 协议 v18 |
| 安装包 | Release v0.4.0 的 dsh-png-pet-0.4.0.tgz（约 151 MiB，内含自包含 Helper） |
| 运行前提 | 面向 DSH 0.2.1-rc.2；接收端不需要 .NET SDK，也不需要编译源码 |
| 安装之后 | 必须重启 DSH：桌面版要完全退出再重新打开 |
| 隐私 | 不读取 API Key、不保存对话、不创建任何监听端口 |

目录

- 功能
- 安装
- 安装后：让 DSH 重新加载
- 第一次使用
- 设置项
- 桌面交互
- 人物形象
- 隐私与边界
- 常见问题
- 从源码构建
- 自定义动画素材
- 项目结构

功能

桌宠与状态

- 透明、无边框、置顶、不占任务栏的 PNG 桌宠；窗口基准 220 × 260 DIP，按 75% / 100% / 125% / 150% 缩放。
- 状态只来自真实的 DSH 会话 / 智能体事件。气泡文案是固定枚举：思考中…、工作中…、输出中…、思考中/工作中、等待你的操作、点击回到 Harness 回答、已完成、发生错误、未连接；idle 不显示气泡。
- 等待批准为橙色气泡、提问为紫色气泡，点击这两类气泡可直接回到 Harness 处理；其它状态气泡不拦截鼠标。
- 位置与缩放保存在 %LOCALAPPDATA%\DshPngPet\window-state.json，下次启动恢复，并会自动夹回最近的显示器工作区。

会话栏（对话）

- 双击桌宠打开或关闭会话栏，IM 式 user / assistant 同屏列表。
- 打开窗口或切换会话时按需加载该会话最近 20 条消息；流式回复按 60 ms 节流刷新，向上滚动后停止自动跟随。
- Enter 发送、Shift+Enter 换行、Esc 停止生成；停止映射到 DSH 的取消能力，回合结束会明确显示「已停止 / 已中断 / 生成失败」，不会留下空白消息。
- 助手回复完成后按 Markdown 渲染（标题、列表、引用、表格、代码块并带复制按钮、链接）；HTML 一律忽略。
- 附件每次最多 4 个：图片支持 PNG / JPG / JPEG / WebP / GIF，单张不超过 2 MB；也可直接 Ctrl+V 粘贴截图。图片走 DSH 的附件能力上传，普通文件只作为受限提示交给模型。
- 会话输入与回复只短暂存在于内存和本地 stdin/stdout 管道，不写入文件、设置或日志。

常驻极简对话

- 右键勾选「对话框常驻」：半透明极简窗口，隐藏发送与附件按钮，只保留输入框。
- 点窗口顶部横线展开 / 收起最近一条助手回复；收起 120 DIP，展开 520 DIP，上限为 min(560 DIP, 屏幕工作区)。
- Enter 发送、Shift+Enter 换行、Esc 停止生成、Ctrl+V 粘贴截图；常驻时发送按钮被隐藏，因此回合进行中按 Enter 无效，请用 Esc 停止。
- 常驻选择只在本次 Helper 运行期间有效，不写入设置；取消勾选即恢复完整会话栏。

请求批准与问卷

在 DSH「设置 → 桌宠 → 请求批准的位置」里选择：

| 选项 | 行为 |
| Web（默认） | 全部在 DSH Web 回答，桌宠只保留状态提示 |
| 桌宠 | 当前选中会话的批准与兼容问卷可直接在桌宠处理；批准卡只有「允许本次 / 拒绝」，卡片不含工具名、参数或路径 |
| Web + 桌宠 | 两处同时显示，桌宠卡只读（「前往 DSH Web 处理」），在 Web 作答后结果同步过来 |

- 问卷最多 8 题、每题最多 8 个选项，支持单选 / 多选，每条自定义回答最多 1000 字；一页一题，草稿只保留在内存，提交后等待 Host 确认。
- 下列情况仍留在 Web：题目或选项超限、题目重复、计划审阅类题目（带 detail / intent）、选项带说明、已有另一个待答问卷、目标会话不是当前会话、Helper 未就绪。
- 10 分钟未回答、会话切换或 Helper 关闭都会结束桌宠请求；桌宠模式下 Helper 不可用时不会默认放行，而是按未处理结算。

目标选择

- 右键「选择会话」，或把文件夹直接拖到桌宠上。
- 支持：工作区 → 会话、未分组会话、每个工作区的「＋ 新对话」，以及「＋ 新建工作区」（浏览目录或拖入文件夹注册）。
- 卡片空闲 60 秒自动关闭；这里的选择只是本次运行期间的临时目标，持久化的对话目标只有设置页里的「默认会话」。

待机互动（随机聊聊）

- 默认关闭。只有同时开启「随机聊聊」、勾选「点击话题后允许联网检索」并选择至少一个工作区，桌宠才会在 idle 时偶尔显示本地邀约气泡（内置话题：今日热点、天气、新鲜事，也可写自定义文案）。
- 气泡 30 秒未点击自动消失；点击后才新建一个隔离会话，由 DSH 使用它已配置的网页工具检索，并要求标注来源、不得编造；天气话题会先询问城市。
- 关闭会话栏即结束这次临时目标，回到保存的默认会话。

安装

三种方式都把包装进 DSH profile；包必须来自 Release（原因见下方对照表）。

方式一：一行安装器（推荐）

在 Windows PowerShell 中执行：

& ([scriptblock]::Create((irm 'https://github.com/comfylies/dsh-png-pet/releases/download/v0.4.0/install.ps1'))) -Profile desktop

- 桌面版加 -Profile desktop；不加参数时默认装到 web profile。
- 安装器会复用兼容的 Node（24.x，≥ 24.15.0）、DSH（0.2.1-rc.2）和 pnpm（11.23.0）；本机缺少时在 %LOCALAPPDATA%\DSHPet 准备专用环境，不改机器 PATH。
- 用 release.json 校验下载包的 SHA-256；安装失败会回滚到上一份可用包。命令可重复运行，-Uninstall 用于卸载并保留 DSH、会话与凭据。
- 装完第一次使用：双击桌面的 DSH Pet（web profile），或重新打开 DSH Desktop（desktop profile）。

也可以下载 Release 里的 install.ps1、release.json、dsh-png-pet-0.4.0.tgz 三个文件放在同一目录，然后本地执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Manifest .\release.json -Profile desktop

完整参数、更新与发布流程见 一行安装与发布。

方式二：桌面版 DSH 手动添加 tgz

只想手动把包交给已经装好的 DSH Desktop 时用这个方式。

1. 从 Release v0.4.0 下载 dsh-png-pet-0.4.0.tgz（约 151 MiB）。
2. 放到一个之后不会再移动的目录，例如 C:\dsh-packages\（profile 会用绝对路径记住这个文件）。
3. 打开 DSH Desktop →「插件」页面 →「添加插件」。
4. 在「包名或地址」里粘贴 tgz 的绝对路径：C:\dsh-packages\dsh-png-pet-0.4.0.tgz。
5. 「安装源」保持默认即可：tgz 是本机文件、不经过安装源；但安装过程仍要从 npm 源解析插件的运行时依赖（open），国内网络建议选「中国大陆镜像源」。
6. 点「安装」，等待完成后页面提示「已安装，下次启动后加载」。
7. 完全退出并重新打开 DSH Desktop（关闭窗口只会收进托盘，见 安装后：让 DSH 重新加载）。

桌面版「添加插件」对话框

对话框各部分说明：

| 位置 | 含义 |
| 标题与说明 | 「添加插件」，说明文字写着「输入插件的包名、GitHub 仓库地址或本地目录路径」——实际的识别范围见下表，比这句话更宽，也包含 .tgz 压缩包 |
| 「包名或地址」输入框 | 唯一的输入项。本机路径必须是绝对路径，相对路径会被拒绝 |
| 「插件安装引导和示例」 | 展开后给出包名示例，可一键「填入示例」 |
| 「安装源」下拉 | 只在需要访问 npm 源时生效：默认安装源 / npm 官方源 / 中国大陆镜像源 / 自定义地址。填 GitHub 地址或 .tgz 直链时不经过它，需要本机能直接访问该地址 |
| 橙色提示 | 提醒插件以你的本机权限运行，来源不明可能损坏 Harness 或泄露数据；并说明插件暂不支持自动更新，升级要先卸载再装新版 |
| 「安装」按钮 | 一次只运行一个安装任务；安装过程与结果都可以在安装详情里查看 |

「包名或地址」能填什么（由对话框自身识别）以及对本项目的结果：

| 填入内容 | 对话框识别为 | 结果 |
| dsh-png-pet | npm 包名 | ❌ 本项目未发布到 npm（package.json 标记 private），会提示「未找到相关插件」 |
| https://github.com/comfylies/dsh-png-pet | Git 仓库 | ❌ 仓库只收录源码，构建产物 lib/ 与 runtime/bin/win32-x64/pet-helper.exe 不入库，装上也加载不了 |
| C:\dsh-packages\dsh-png-pet-0.4.0.tgz | 压缩包 | ✅ 推荐 |
| https://…/dsh-png-pet-0.4.0.tgz | 压缩包直链 | ✅ 可用，本机需要能直接访问该地址 |
| 解压后目录的绝对路径 | 本地目录 | ⚠️ 可行，但会登记为 link: 本机依赖，目录不能移动或删除；目录必须是解压后含 lib/、runtime/ 的完整目录 |

升级与卸载：在插件页对 dsh-png-pet 点「卸载」，再按上面步骤添加新版 tgz——桌面版暂不支持自动更新。
tgz 文件名请带版本号。profile 用绝对 file: 路径记录当前包，正在使用的那个文件不要删除或改名；装好新版之后旧文件才可以删。

方式三：DSH CLI

先完全退出 DSH Desktop，再在 PowerShell 中执行：

dsh plugin --profile desktop add C:\dsh-packages\dsh-png-pet-0.4.0.tgz
dsh plugin --profile desktop list

- dsh 不在 PATH 时用完整路径，例如 & "$env:APPDATA\npm\dsh.cmd"。
- 路径含空格时用引号包住整个路径，例如 add "D:\my packages\dsh-png-pet-0.4.0.tgz"。
- Web profile 把 --profile desktop 换成 --profile web，装完重启该 Host。
- 卸载：dsh plugin --profile desktop remove dsh-png-pet。

安装后：让 DSH 重新加载

插件只在 Host 启动时加载，装完必须重启：

- 桌面版：关闭窗口只是收进托盘（首次会弹一次确认）。请右键托盘图标选「退出 DeepSeek Harness」（与应用菜单同名），然后重新打开。
- Web profile：从 DSH 自己的退出入口结束 Host，再重新启动。
- 同一时间只能运行一个 DSH Host；已经有一个在跑时，第二个会提示「有其他正在运行的 DSH…」。

第一次使用

1. 打开 DSH，按界面提示配置自己的模型凭据和工作区（安装器不接触任何密钥）。
2. 打开「设置 → 桌宠」，在「会话」分组里选一个默认会话。
3. 桌宠出现后：双击打开会话栏输入消息，右键调整外观与行为。
4. 想换形象：右键 →「人物形象…」导入自己的 GIF / PNG。

设置项

全部设置都在 DSH「设置 → 桌宠」页面，改完立即同步给桌宠，不需要重启。

| 分组 | 设置项 | 可选值 / 范围 | 默认 |
| 会话 | 默认会话 | 工作区 → 会话（含未分组会话），可选「未选择默认会话」 | 未选择 |
| 权限请求与问卷 | 请求批准的位置 | Web / 桌宠 / Web + 桌宠 | Web |
| 外观 | 默认位置 | 九宫格（屏幕左上 … 屏幕右下） | 屏幕中央 |
| 外观 | 人物与动态：缩放 | 75% / 100% / 125% / 150% | 100% |
| 外观 | 人物与动态：减少动态效果 | 开 / 关（只显示主循环首帧，并暂停物理） | 关 |
| 趣味功能 | 角色物理化 | 开 / 关 | 关 |
| 趣味功能 | 弹力 | 0–100%，物理开启且未开减少动态效果时可调 | 65% |
| 会话栏 | 默认打开位置 | 跟随人物，或九宫格固定位置 | 跟随人物 |
| 会话栏 | 默认大小 | 宽 220–4000 px、高 240–3000 px（最小 220 × 240） | 320 × 420 |
| 会话栏 | 对话字体大小 | 12 / 14 / 16 / 18 px | 14 px |
| 待机互动 | 随机待机动画 | 即将推出（当前不可用） | — |
| 待机互动 | 随机聊聊 | 开关；随机间隔 5–1440 分钟；自定义气泡文案最多 12 条、每条 ≤ 120 字；「点击话题后允许联网检索」；随机聊聊工作区最多 8 个 | 关；8–24 分钟 |

桌面交互

桌宠

| 操作 | 行为 |
| 左键拖动 | 默认桌宠与会话栏一起移动；按住 Ctrl 拖动只移动桌宠 |
| 左键单击 | 显示 5 秒的「峰谷」小卡：按北京时间算出的 DeepSeek API 高峰 / 低谷时段（工作日 09:00–12:00、14:00–18:00 为高峰，其余时间与周末为低谷）；完全本机计算，不联网 |
| 左键双击 | 打开 / 关闭会话栏 |
| 拖入文件夹 | 直接进入目标选择卡，用该目录新建工作区 |
| 右键 | 打开下方菜单 |
| 滚轮 | 桌宠本身不响应滚轮，会话栏内的消息列表可滚动 |

右键菜单（自上而下）：选择会话、人物形象…、对话框常驻（勾选项）、打开 Harness、隐藏、本次缩放（不保存）▸（75% / 100% / 125% / 150%）、分隔线、重置大小与位置、本次关闭桌宠。

- 「本次缩放」只对本次运行有效，不回写 DSH 设置；下次启动仍按设置页的缩放。
- 「打开 Harness」会在默认浏览器里打开本机 DSH Web（http://127.0.0.1:<端口>）；等待批准或提问的气泡也可以直接点击进入。
- 「重置大小与位置」按设置页的默认缩放与默认位置重新归位。
- 「隐藏」后托盘图标出现；托盘菜单为 显示桌宠 / 本次关闭桌宠，双击托盘图标也能恢复。
- 右键「本次关闭桌宠」或托盘「本次关闭桌宠」会结束本次桌宠；从 DSH 退出 Host 时桌宠也会有序关闭。

人物形象

右键桌宠 →「人物形象…」，窗口标题为「人物形象」，副标题「选择一个桌面伙伴，或从本机导入新的形象。」：

1. 点「添加 GIF / PNG」选单张图片，或点「添加角色目录」选含 character.json 的多状态目录。
2. 在预览里逐状态检查动作（待机、思考、工作、思考与工作、回复、等待操作、提问、成功、错误、未连接）。
3. 调整「人物名称」、「头顶位置（蓝点）」和「脚底基线（橙线）」——蓝点是气泡的落点，橙线是脚底基准。
4. 点「导入并使用」；导入过程中当前桌宠继续工作，也可以「取消导入」。
5. 之后可在人物列表中即时切换、「恢复默认」，或用「移除人物」删掉本机副本（原始素材文件保留）。

素材保存在 %LOCALAPPDATA%\DshPngPet\Characters，不进插件包也不进 EXE：删掉原图、升级插件都不影响已导入的人物。限制与规则：
- 单文件 ≤ 20 MiB，单个角色输入合计 ≤ 100 MiB；原图每边 ≤ 2048 px。
- 单动作 ≤ 240 帧，单角色 ≤ 1024 帧；导入时等比缩到最长边 512 px、底部对齐补齐方形画布，小图不放大，背景原样保留（不自动抠图）。
- GIF 保留逐帧时长（零延迟按 100 ms，极短帧至少 20 ms）；缺少某个状态时回退该人物自己的待机动画，真实状态仍由气泡显示。
- 人物库最多 50 个、合计 ≤ 1 GiB；达到上限需自己移除不再需要的人物。

角色目录清单（character.json）、动作类型和完整限制见 外置人物使用说明。

隐私与边界

- 不读取、保存、记录或转发 API Key、授权头、提示词、工具参数、工具结果、文件路径或 DSH 凭据。
- 不直接请求模型服务，也不创建 HTTP、WebSocket、命名管道或任何监听端口：TypeScript 插件与 C# Helper 之间只通过父子进程 stdin/stdout 的 JSON Lines 通信。
- 会话输入、助手回复、历史投影和流式预览只短暂存在于内存和这条管道中，不写入文件、设置或日志。
- 不显示 reasoning；历史只投影用户文本、助手可见文本，以及经限长处理的图片 / 工具占位。
- 协议字段严格白名单校验（版本、类型、长度），未知输入安全失败，不会影响 DSH Host。
- 人物导入是唯一的本地文件读取例外：只读取你主动选择的 PNG / GIF 或角色目录，来源路径只在 Helper 内存中短暂存在；人物库只保存规范化 PNG、动画元数据、名称与选择 ID。
- 网页内容、DSH 事件与 Helper 输入都当作不可信数据；随机聊聊也只在你点击气泡后才联网。
- 已知兼容性限制：部分标准 DSH Web profile 不向第三方开放设置命名空间，此时设置页会显示固定的不可用提示——本项目不会用自建 HTTP 端点绕过它。

完整的产品定位与安全边界见 项目需求书。

常见问题

装完桌宠没出现？ Host 必须重启才会加载插件。桌面版要完全退出（右键托盘图标 →「退出 DeepSeek Harness」）再打开；同时确认「插件」页里 dsh-png-pet 处于启用状态。

为什么安装包这么大？ 包里含 .NET 10 自包含单文件 Helper（解包约 248 MiB），因此接收端不需要 .NET SDK，也不需要编译。

会自动更新吗？ 不会。桌面版请先「卸载」再添加新版 tgz；一行安装器可以重复运行来更新。

桌宠会读取我的对话或密钥吗？
不会，见 隐私与边界。

支持 macOS / Linux 吗？ 不支持。Helper 是 WPF / .NET 10 的 Windows 可执行文件，只发布 win-x64。

能同时开桌面版和 dsh web 吗？ 不能，同一时间只能有一个 DSH Host，桌宠跟随当前运行的那个。

能换成自己的角色吗？ 可以。普通需求用「人物形象…」导入 GIF / PNG；要改动画结构则替换仓库里的动画素材后重新打包，见下方两节。

卸载会删掉什么？ 只移除插件和安装器创建的快捷方式。DSH 会话、凭据、人物库（%LOCALAPPDATA%\DshPngPet\Characters）都会保留，需要时手动删除该目录。

从源码构建

需要 Node.js ≥ 22.19 与 .NET 10 SDK：

npm install
npm test
dotnet test pet-helper.Tests\PetHelper.Tests.csproj --no-restore
npm run build:helper # 发布自包含 Helper 到 runtime\bin\win32-x64\pet-helper.exe
npm run test:package
npm run package:release # 生成 dist\packages 下的 install.ps1、release.json、版本化 .tgz

pet-helper.exe 以 .NET 10 自包含单文件发布（保留 IncludeNativeLibrariesForSelfExtract）；打包时若桌宠正在运行，需先从右键菜单关闭它再打包。

自定义动画素材

- 根清单 pet-helper/Assets/pet-animations.json（formatVersion: 5）为 10 个状态各声明一份清单和回退链；每份清单位于 pet-helper/Assets/Animations/<状态键>/animation.json，声明片段（clips）、程序（program.enter / program.loop）、状态切换（transitions）和附加动作（extras）。
- 帧放在 Animations/<状态键>/<片段键>/NNN.png：透明 PNG、同一画布大小、脚底基线一致；片段键限 [a-z0-9-]，单片段 1–240 帧，单清单累计 ≤ 1024 帧，单状态 ≤ 8 个片段，frameDurationMs 为 16–1000 ms。
- 每个片段必须声明 statusAnchor（0–1 归一化坐标，指向该片段画布里角色头顶的中点），状态气泡以它为基准，并在整段动画中固定不动。
- 缺失状态按根清单的 fallback 逐级回退，最终回到 idle；全部不可用时显示静态 placeholder-a.png。
- 仓库内置形象共 8 段动作、318 帧：呼吸（idle）、思考（thinking）、搬运（working）、打字（responding）、举手 / 持卡 / 收卡（question）、完成（success）；waiting、error、thinking-working、disconnected 通过回退复用。
- 改完素材要重新 npm run build:helper 并重新打包安装；源资源不会热部署到正在运行的 Harness。只想换外观而不动仓库，直接用「人物形象」导入更快。

项目结构

| 目标 | 位置 |
| 插件装配、Helper 启动 | src/index.ts、src/helper-process.ts |
| 协议类型与校验 | src/protocol.ts、pet-helper/ProtocolMessage.cs、pet-helper/ProtocolReader.cs |
| DSH 事件 → 桌宠状态 | src/dsh-event-adapter.ts、src/companion-reducer.ts、src/companion-bridge.ts |
| 会话栏、历史、批准、问卷、目标选择 | src/dialogue-controller.ts、src/dialogue-history.ts、src/approval-controller.ts、src/questionnaire-controller.ts、src/target-controller.ts |
| DSH 设置与 Web 设置页 | src/dialogue-settings.ts、src/client.tsx |
| WPF 桌宠窗口与托盘 | pet-helper/MainWindow.xaml(.cs)、pet-helper/PetTrayIcon.cs |
| 会话栏、目标选择、人物窗口 | pet-helper/DialogueWindow.xaml(.cs)、pet-helper/TargetWindow.xaml(.cs)、pet-helper/CharacterWindow.xaml(.cs) |
| 动画素材与清单 | pet-helper/Assets/pet-animations.json、pet-helper/Assets/Animations/ |
| 安装器与打包 | scripts/install.ps1、scripts/package-release.ps1、scripts/build-helper.ps1 |

许可与社区

- MIT License，见 LICENSE。
- 仓库：<https://github.com/comfylies/dsh-png-pet>
- DSH 插件社区：<https://github.com/topics/dsh-plugin>