桌面效率助手 wzqvip/dsh-app

DSH 效率助手

让智能体的问题找到你，而不是让你守着网页。

一个效率导向的 DeepSeek Harness 增强项目。
不打开浏览器，也能秒回智能体的提问、随时看到它在干什么。

规划 · 任务清单 · 架构说明 · 调研报告 research/

这个项目解决什么问题

用 DSH 干活时，真实的工作方式是这样的：

智能体在跑一个长任务。你去写代码 / 看文档 / 开会 / 倒杯水。
它遇到一个需要你决策的地方，弹出问题。
而你的浏览器在后台，或者你根本不在电脑前。
于是整个任务停在那里，等你发现 —— 可能十分钟后，可能一个小时后。

这不是自动化不够，这是「你不在场」造成的等待。

DSH 的智能体本身很强，问题在于提问的触达方式：它假设你正盯着那个网页。一旦你离开，它就只能干等。

本项目的目标

把「智能体需要你」这件事，从「你必须回到网页」变成「它主动找到你，你点一下就能回答」。

| | 现状 | 目标 |
| 提问触达 | 需要切到浏览器、找到那个会话 | 桌面上直接弹出/角标提醒 |
| 回答成本 | 打开网页 → 定位会话 → 读题 → 点选 | 点一下选项就能回 |
| 进度感知 | 必须看网页才知道跑到哪 | 一眼看到在做什么 |
| 离开电脑 | 完全错过 | 系统通知 / 稍后回来仍可回答 |

界面预览

截图取自沙箱实例（dsh-efficiency 已并入桌宠能力后的实际界面）。
宠物立绘与表情素材来自 PC2005-cloud/dsh-pet（禁止商用，详见 NOTICE.md）。

① 桌面小窗 + 右键菜单 —— 工具项里有「设置…」，动作分组可点播任意动画

桌面小窗与右键菜单

② 提问面板 —— 提问到达时锚定在宠物下方，点选项 + Submit 即可回答（不用切回网页）

提问面板

③ 设置窗口 —— 8 个分区，内置配置全部字段可编辑（含物理引擎、动画池、表情包池）

设置窗口

设置窗口里到底能改什么（逐分区截图）

设置窗口是可滚动的，一张图看不全。下面是逐分区截的（由 scripts/manual-settings-window.mjs 自动产出，脚本还会校验各图内容不重复）。

宠物 —— 名字、大小、显示方式（web/desktop/both）、停靠角落、水平/垂直边距、三个开关

宠物

提醒与对话 —— 系统通知、碎碎念/对话配表情包、人设提示词（自定义回复内容）、对话记忆轮数、按事件分别设置的刷新间隔

提醒与对话

物理引擎 —— 重力、弹性、地面摩擦、抛掷力度、顶部反弹、宠物互撞

物理引擎

工作状态文案 —— 「思考中 / 执行中 / 出结果 / 等你回复 / 成功 / 出错」六档气泡文案，可自己改

工作状态文案

动画随机链权重 —— 待机 / 转向 / 移动 各自被挑中的权重（设 0 即不再挑）

动画随机链权重

动画池 —— idle/turn/drag/clicks、事件三池、分类（id/权重/不镜像/动作清单）、移动参数（默认值 + 每动作可选覆盖）。内容很多，脚本会自动分段：

动画池 p1

表情包池 —— 27 组「键 = 图片文件名 / 值 = 给模型看的描述」，可增删改

表情包池

诊断信息 —— 排障时把这些贴出来即可定位问题

诊断信息

④ 网页浮层 —— 同一只宠物也能直接活在 DSH 网页里（默认只在桌面小窗；把「显示方式」改成 web/both 即可，见 TESTING.md §5.1）

网页浮层

💡 默认是桌面宠物：内置默认 display=desktop（上游为 both）——桌宠的价值在「不打开网页也能看到提问」，所以默认不占网页。
想在 DSH 网页里也看到它，把设置窗口的「显示方式」改成 两者都要/仅网页浮层 即可（即时生效）。

⚠️ 两套壳的工具项不同（实测确认，不是缺陷）：
- 桌面小窗（Electron）：打开网站 · 查看余额 · 设置… · 回到初始位置
- 网页浮层：打开网站 · 查看余额 · 碎碎念 · 对话

「设置…」只在桌面小窗里 —— 它要经 IPC 通知 Electron 主进程开窗，网页端没有这条通道。
在 DSH 设置页的 Efficiency 分区里也有这条指路提示。

核心能力（按重要性排序）

① 问题提醒 —— 本项目存在的主要理由

智能体提问时，在桌面常驻层立刻呈现：

- 一眼看到问题：题干 + 选项，不需要打开网页
- 一键回答：点选项即回，支持多选与"其他"自由文本
- 不丢：即使你当时不在，问题不会消失，回来仍可回答（见 架构说明）
- 系统通知：窗口失焦时也能提醒到

这是"生产力"的直接来源：它把一次上下文切换，压缩成一次点击。

② 进度可视 —— 随时知道它在干什么

- 常驻状态：思考 / 工作 / 整理 / 等待 / 成功 / 出错
- 待办推进、当前工具、运行时长
- 多个会话并行时的角标与汇总

③ 进度气泡（可选，会消耗额外 token）

用一个独立的轻量会话去观察主智能体的进度，偶尔生成一句人类可读的总结或提问，以气泡对话的形式呈现（"它已经改完 3 个文件，正在跑测试"）。

- ⚠️ 默认关闭。它需要额外调用模型，按周期计费。
- 三种档位见下方「进度显示档位」。
- 主力始终是 ①② 的零成本方案，③ 只是给"想要更自然表达"的人一个选项。

④ 局域网 / 手机访问（纯 Web 能力，与桌宠无关）

手机、平板通过浏览器访问响应式网页 —— 这不是桌宠功能，桌宠设置面板只是放这个开关的地方。

因此它和桌宠彻底解耦：桌宠没装或装不上，这个能力也必须可用。

⚠️ 但"一键开局域网"不是即时生效的开关：DSH 的命令行硬拒绝绑定 0.0.0.0（理由原文是"会把远程代码执行暴露到网络"），且运行中的服务器无法改绑定地址。实际形态是改配置 → 提示需重启 → 一键重启，并必须带安全门槛（暴露面 = 同网段可执行任意命令）。详见 plan.md §5。

⑤ 互动模块（非主线，可选）

这些是锦上添花，不是项目重点。它们让常驻的那一小块区域更耐看、更好用，但去掉它们，效率功能依然成立：

- 桌宠形象：桌面上的一只小动物，承载状态与气泡，让提醒不突兀
- galgame 模式：把智能体的长回答变成"点一下下一句"的逐句呈现，适合阅读长文

⑥ 启动器（解压即用）

DSH 目前需要手动装环境 + 敲命令才能用：

npm install -g @deepseek-ai/dsh # 1. 自己装
dsh web # 2. 自己在终端敲
3. 等打印出带 ?token= 的 URL，浏览器自动打开
4. 终端不能关，关了服务就停

启动器把这一串压缩成"双击一个图标"：

- 自动检测环境（Node / npm / dsh / 端口），缺失则用人话引导并给官方下载链接
- 自动拉起 dsh web、抓取 token、载入界面
- 托盘常驻、退出时优雅关闭子进程
- GitHub Release 发布，解压即用，无需自己搭建

⚠️ 启动器不是 MVP 的一部分，优先级低于 R0/R0b（它是分发层，不是核心效率层）。
它还不是"另一个 DSH 客户端" —— 不重写会话 UI，只做引导 + 承载。
完整设计（启动时序、环境检测、跨平台要点、失败处理）见 LAUNCHER.md。

进度显示档位（token 成本递进）

| 档位 | 做法 | 额外 token | 建议 |
| A. 零成本（默认） | 直接读 DSH 已有的会话状态与投影：状态、待办、工具调用、运行时长、待答问题 | 0 | 默认开启，这就是主力 |
| B. 本地聚合 | 本地把这些信号归纳成一句话（规则/模板，不过模型） | 0 | 想要更"人话"又不想花钱 |
| C. 独立观察会话 | 另起一个轻量会话读进度 → 生成自然语言总结 + 气泡 | 按周期消耗 | 可选，需显式开启；可设周期与预算上限 |

档位 C 正是"新开一个 chat 窗口看进度"的想法，会在计划里作为可选项实现（见 plan.md）。
设计上保证：关掉 C，A/B 仍然完整可用。

架构一分钟

┌──────────────────────────────────────────────────────────┐
│ dsh-efficiency ← 本仓库，一个插件包 │ │ · 问题提醒与一键回答 ← 核心 │ │ · 进度采集与状态联动 ← 核心（零 token） │ │ · 桌宠本体（网页浮层 + 桌面小窗 + 气泡 + 通知） │ │ · 设置 GUI │ │ │ │ ⚠️ 其中「桌宠本体」的代码 vendor 自 PC2005-cloud/dsh-pet │ │ （MIT），我们做了改造。详见下方「许可与致谢」。 │ └──────────────────────────────────────────────────────────┘ │ 素材（已随本包分发） ┌──────────────────────────────────────────────────────────┐ │ 本包自带 vendor/dsh-pet/assets/ │ │ · 立绘动画 / 表情包 / 字体 / 内置默认配置 │ │ · 上游声明：允许开源使用、禁止商用（详见 NOTICE.md） │ └──────────────────────────────────────────────────────────┘ │ 运行于 ┌──────────────────────────────────────────────────────────┐ │ DSH 宿主 0.2.0-rc.2 │ │ · userQuestions（提问/回答/超时继续） ← 效率功能的基础 │ │ · session 投影、tool-call、待办、审批 │ └──────────────────────────────────────────────────────────┘

详细设计（含事件名、数据流、为什么问题不会丢）见 ARCHITECTURE.md。

与 DSH 的关系

本项目完全基于 DSH 的插件机制，不 fork、不改 DSH 源码：

- 宿主侧：cordis 插件（apply(ctx) + 服务注入）
- 客户端侧：注册到 shell.overlay / conversation.view / settings 等官方槽位
- 提问能力直接复用官方 ctx.userQuestions，不自己造问答协议

因此 DSH 升级时，本项目只需要跟进插件接口，而不是维护一个分叉。

快速开始

想亲手试一下？ 完整的沙箱实测步骤（含前置、启动、该看到什么、排查）见 TESTING.md —— 那份是照着做就能跑通的版本，本节只是摘要。

本项目只发布在 GitHub，不发布 npm。lib/ 构建产物不入库，因此安装分两步：先构建，再 add file:。

① 依赖：已内置，无需另装

本包自带 dsh-pet 的代码与素材（vendor/dsh-pet/，含 60.7 MB 素材），所以装本包一个命令就完整可用 —— 立绘、动画、表情包、字体都在包里。

上游素材的声明是「允许开源使用、禁止商用」，本项目开源且非商用，且已在 NOTICE.md 与 THIRD-PARTY-NOTICES.md 完整署名与说明。

早先的版本要求另装一份 dsh-pet 取素材（因其"禁商用"被我理解为"不能进仓库"）；维护者 2026-09-30 决定改为随包分发以简化安装 —— 现不再需要这一步。

② 本项目

git clone https://github.com/wzqvip/dsh-app.git
cd dsh-app/packages/dsh-efficiency
npm install
npm run deploy # 五道门禁全绿才产出 release/
dsh plugin --profile web add file:<上一步所在目录>/release

装的路径是 packages/dsh-efficiency/release（门禁把关后的成品），不是仓库根目录。开发时也可以直接装包根 packages/dsh-efficiency —— 两者 lib/ 内容一致。

③ 校验（不启动服务器）

node packages/dsh-efficiency/scripts/preflight.mjs # 只读，34 项，约 1.3 秒

版本兼容

DSH 会校验插件的 @deepseek-ai/dsh peer 范围，不匹配则拒绝加载。处理方式：

查看当前运行时版本与已有豁免
dsh plugin --profile web version-exemptions

对某个不匹配的包授予精确版本豁免（需明确接受风险）
dsh plugin --profile web allow-version <包名>@<版本> --dsh-version <运行时版本> --accept-risk

💡 本项目的插件刻意不声明 @deepseek-ai/dsh peer，因此不受此闸门约束；只有第三方插件（如 dsh-pet）需要豁免。豁免不随插件/DSH 升级继承。

项目决策记录

已确认的方向性决策，避免后续反复：

| 决策 | 结论 | 理由 |
| 定位 | 效率工具，桌宠/ galgame 是可选载体 | 真正痛点是提问触达，不是桌宠 |
| 局域网 / 手机适配 | 纯 Web 能力，与桌宠无关 | 手机/平板用浏览器访问响应式网页；桌宠面板只是放开关的地方 |
| 与 dsh-pet 的关系 | vendor 其代码并改造（2026-09-29 拍板，取代早期的"只依赖不 fork"） | 需要加右键「设置…」入口与完整设置 GUI，必须改代码；上游为 MIT 明确允许 |
| 代码引入方式 | 直接复制进仓库（packages/dsh-efficiency/vendor/dsh-pet/），不用 submodule | 我们要深改而非轻补丁，submodule 的"干净 merge"价值丧失，反而多出「空目录陷阱」与「打包漏文件」两个风险 |
| 素材 | 随包分发（vendor/dsh-pet/assets/，60.7 MB） | 上游声明「允许开源使用、禁止商用」；本项目开源且非商用，已完整署名 |
| 优先级 | 先做 R0（提问触达），进度先用零成本方式 | 痛点是"任务干等"，不是"看不懂状态" |
| 分发 | 只发 GitHub，用户自行构建 | 避免过早处理 npm 发布；构建流程见上 |
| 启动器 | 做成 exe，Release 发布，解压即用 | 消除"装环境 + 敲命令"的摩擦；它不是 MVP 的一部分 |
| 启动器技术栈 | Electron | 复用与桌宠同一运行时与经验，避免引入第二套桌面技术栈 |
| 上架插件市场 | 等 MVP 跑通再上架 | 避免为未验证的功能写英文 README 与元信息 |
| 许可 | 本项目代码 MIT；完全免费开源，不做商业用途 | 与依赖生态一致；上游素材的非商用限制我们也一并遵守 |

明确的非目标

为了不跑偏，以下不是本项目的目标：

- ❌ 不做另一个 DSH 桌面客户端
- ❌ 不做天气、监控、看板这类功能，它们和「让智能体的问题触达你」无关
- ❌ 不 fork DSH，不修改其 @deepseek-ai/ 源码
- ✅ 素材随包分发 —— 用户装本包一个命令即可用，不必另装 dsh-pet（上游声明允许开源使用、禁止商用）
- ❌ 不追求桌宠的「养成/收集」玩法 —— 桌宠是载体，不是目的
- ❌ 不默认开启任何消耗额外 token 的功能
- ❌ 暂不发布 npm 包

设计原则

1. 效率优先：每一处设计都问「这能不能减少一次上下文切换？」
2. 零成本默认：默认路径不额外调用模型；花钱的能力必须显式开启
3. 降级可用：关掉桌宠、关掉 galgame、关掉档位 C，核心提醒功能依然工作
4. 复用而非重造：提问用官方 userQuestions，载体用 dsh-pet，导出用内置 /export
5. 不丢信息：错过的提问必须还能回答，而不是变成一次失败
6. 依赖而非吞并：第三方能力保持上游可升级，通过适配层隔离风险

文档

放在仓库根目录的（门面与主计划）：

| 文档 | 内容 |
| README.md | 就是你正在读的这份：是什么、能干什么、怎么装 |
| plan.md | 完整规划：需求拆解、调研结论、架构、分阶段路线图、风险登记 |
| todo.md | 可执行任务清单（含工时、门禁、待验证项） |
| STATUS.md | 交付状态：逐项验证证据、已知取舍、部署前核对表 |
| NOTICE.md | 第三方许可与强制署名义务 |
| AGENTS.md | 给协作者/AI 的跨会话约定（工作流、代码约定、许可硬约束） |

放在 docs/ 的（专题与流程）：

| 文档 | 内容 |
| TESTING.md | 沙箱实测指南：前置、构建安装、启动、该看到什么、排查 —— 照着做就能跑通 |
| DEPLOY-CHECKLIST.md | 部署到生产的步骤与注意事项（含最容易搞错的一点） |
| ARCHITECTURE.md | 技术设计：提问-回答管线、进度数据来源、token 成本控制 |
| LAUNCHER.md | 启动器设计：启动时序、环境检测、跨平台要点、失败处理 |
| SECURITY.md | 安全说明：局域网暴露 = RCE 风险 |
| LAN-ACCESS.md | 局域网访问：当前 DSH 不支持直连，三条可行替代路径（实测） |
| COMMIT-IDENTITY.md | 提交署名与头像的来龙去脉（含历史重写记录） |
| EXECUTION.md | 实施顺序与阶段拆分 |
| CHANGELOG.md | 面向发布的变化记录 |
| CONTRIBUTING.md | 贡献指南与许可/署名必读 |
| research/ | 源码级调研报告：插件架构、嵌入方案、局域网安全、响应式、显示模式 |
| .github/REPO-METADATA.md | 仓库 Description / Topics / Social preview 文案（需手动填到 GitHub 设置） |

相对链接由 scripts/check-doc-links.mjs 校验（当前 148 个链接全绿）——搬动文档后跑一次，避免 404。

开发过程与成本

本项目由 AI（DeepSeek-V4.1-Flash）在 DSH（DeepSeek Harness）里实现，维护者负责方向决策、验收与部署。这里如实记录产出与消耗，便于评估这类工作方式。

提交历史

提交历史

图由 scripts/make-commit-history-svg.mjs 从真实 git log 渲染（不是截图），可随时重跑核对。

Token 消耗（本会话实测）

数据来源：DSH 的会话用量快照（~/.dsh/storages/session_projcache/），按该会话的 goal id 核对确认。

| 指标 | 数值 |
| 未缓存输入 | 2,961,374 |
| 输出 | 1,263,103 |
| 缓存读取 | 887,106,688 |
| 缓存写入 | 0 |
| 上下文水位（快照时） | 304,814 / 1,000,000（约 30%） |
| 快照位置 | turn 76 · step 19 |

⚠️ 缓存读取近 8.87 亿是这类长会话的典型特征：每一步都要重新提交整段上下文，大部分由 prompt cache 命中（单价远低于未缓存输入）。不要把它当「新增消耗」看 ——真正的「新读入」是那 2.96M 未缓存输入。
表中数字是实测值；费用请按你自己的账单与当期价目计算，这里不猜价格。

许可与致谢

本项目

- 代码：MIT（见 LICENSE）
- 完全免费开源，不做任何商业用途 —— 不设付费项、不做商业授权、不接商业分发
- 第三方依赖与内联复用的代码各自遵循其条款，详见 NOTICE.md
- 实现方：DeepSeek-V4.1-Flash（在 DSH / DeepSeek Harness 中完成编码与验证）；方向决策、验收与部署由维护者负责

⚠️ 我们使用了 dsh-pet 的代码（请务必阅读）

本项目的「桌宠本体」不是我们原创，而是 vendor（内联复用）自 PC2005-cloud/dsh-pet 的代码*，在其基础上改造而来。按上游的 MIT 许可与二创约定，这里如实说明：

| 项 | 说明 |
| 上游 | PC2005-cloud/dsh-pet |
| 上游版本 | 0.2.12 · commit 6bb68c0f30abaf9e75330f55f639dff0817c9230 |
| 上游许可 | MIT · Copyright (c) 2026 PC2005-cloud（原文见 vendor/dsh-pet/LICENSE） |
| 我们 vendor 了什么 | 仅代码：src/（TypeScript 源码）、runtime/（桌面 Electron helper）、构建脚本 |
| 我们带上了什么 | 素材也随包分发（vendor/dsh-pet/assets/：立绘动画 / 表情包 / 字体 / 内置默认配置）—— 上游声明允许开源使用，本项目开源且非商用 |
| 我们做的改动 | 合并为单一插件包、加"同一档位不打断动画"修复、素材路径改指已安装包、后续还将加设置 GUI 与右键「设置…」入口。改动由 scripts/patch-vendor.mjs 幂等施加，代码中带 [dsh-app] 标记 |
| 本仓库中的位置 | packages/dsh-efficiency/vendor/dsh-pet/（含 出处说明） |

署名义务（强制）

上游的二创约定要求：任何介绍、展示、分发本项目的场合，都必须附上原作者地址。

<https://github.com/PC2005-cloud/dsh-pet>

如果你 fork、改版、换皮或分发本项目，请一并保留上面这个地址。

素材的额外限制

上游素材（动画 / 提示词 / 源视频 / 表情包 / 字体）允许开源使用、禁止商用。

本项目随包分发这些素材（vendor/dsh-pet/assets/，60.7 MB），以便用户装一个包即可用。
依据是上游「允许开源使用」的声明 —— 而本项目整体开源且明确不用于任何商业用途（硬约束见 NOTICE.md）。上游的强制署名要求已在上文与 THIRD-PARTY-NOTICES.md 中满足。

⚠️ 如实说明一处法律上的分寸：上游声明写的是「允许使用」，而"复制进另一个仓库并随之分发"属再分发；MIT 明确授予再分发（sublicense, and/or sell），但素材不在 MIT 范围内。
维护者已知悉该区别并决定按此分发。
若上游作者提出异议，删掉 vendor/dsh-pet/assets/ 即可回到"仅代码"形态—— 解析器保留了回退到已安装 dsh-pet 的路径（见 scripts/patch-vendor.mjs）。

字体

assets/fonts/上首软糖体.ttf 是第三方字体，其著作权与许可独立于上游项目。
本项目按上游的分发方式一并携带；若要再分发，请自行核实该字体的授权范围。

其他致谢

- DeepSeek Harness —— 本项目的宿主平台与全部能力基础（MIT）
- awesome-dsh-plugin —— 插件生态目录（4382 个插件）是选型的主要依据

一句话：不是让桌宠更可爱，而是让 agent 的问题再也等不到你。