dsh-png-pet

Identified★ 2

A Windows desktop pet companion for DeepSeek Harness (DSH PNG pet).

DSH PNG 桌宠

Windows 10/11 x64 专用的 DeepSeek Harness（DSH）桌宠插件。DSH 仍然是会话、模型、凭据、Agent 和 Web UI 的唯一拥有者；这个插件只做一件事：把真实的 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、不保存对话、不创建任何监听端口

功能

桌宠与状态

透明、无边框、置顶、不占任务栏的 PNG 桌宠；窗口基准 220 × 260 DIP，按 75% / 100% / 125% / 150% 缩放。
状态只来自真实的 DSH Session / Agent 事件。气泡文案是固定枚举：思考中…、工作中…、输出中…、思考中/工作中、等待你的操作、点击回到 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 时用这个方式。

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

第一次使用

打开 DSH，按界面提示配置自己的模型凭据和工作区（安装器不接触任何密钥）。
打开「设置 → 桌宠」，在「会话」分组里选一个默认会话。
桌宠出现后：双击打开会话栏输入消息，右键调整外观与行为。
想换形象：右键 →「人物形象…」导入自己的 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 时桌宠也会有序关闭。

人物形象

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

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

素材保存在 %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

Comments

Loading…