dsh-dock · 功能坞

DeepSeek Harness 功能坞插件：用一张管理面板，统一注册、开关所有小功能。

模型余额、用量记录、模型设置、图片理解代理……这些散落的小功能，全部收进一个「功能坞」： 每个功能是独立模块，有注册表、有开关、有错误隔离。新功能按模块追加，老功能互不牵连。

---

功能一览

| 功能 | 说明 | |---|---| | 用量记录 | 记录全部 LLM API 调用：秒级时间筛选、Token/费用统计（可配置各模型单价、持久保存并按自填单价计费，支持多段分时价，内置峰谷计价 + 官网价目自动同步作兜底）、分组汇总、明细检索与 CSV 导出 | | 模型设置 | 编辑各 Provider 模型目录：输入类型（文本/图片 + 标注）与思考强度档位；图片能力可由你手动声明，新增 Provider 自动刷新加载，写回官方配置热生效 | | 模型余额 | 展示所有模型 Provider 账户余额（5 分钟自动刷新） | | 任务动画 | 19 种任务运行动画（含星际远征、星云潮汐、曲速航道、量子雷达、星座网络、深海脉动、神经电路等），速度随任务活动联动，配置全部持久化 | | 任务通知 | 任务完成 / 异常 / 需确认通知：页内卡片、6 种提示音、浏览器系统通知、钉钉/飞书群机器人推送（宿主直发，浏览器关着也能推）；与动画互相独立、各自启停 | | 运行状态 | 任务运行状态一览：进行中任务的阶段 / 耗时 / 回合 / 步骤 / 工具 / Token、等待确认提醒（等待的工具与说明）与最近完成记录（只读，与动画/通知共用同一份宿主侧追踪） |

| 趣味游戏 | 任务等待时消磨时间的十款小游戏（五子棋、中国象棋、俄罗斯方块、推箱子、贪吃蛇、打砖块、极速赛车、坦克大战、星际躲避、反应堆解谜）；浮动窗口可拖动/缩放/最小化，不遮挡会话，靠屏幕侧边隐藏 | | 图片理解代理 | 图片识别等（visionproxy）；原图候选默认折叠展示，图片能力以你的声明为准 | | 远程访问 | 账号密码登录的远程入口：网关监听 0.0.0.0 独立端口，手机/平板/局域网设备访问同一实例，会话与任务进度实时一致；主实例保持仅监听 127.0.0.1，结构上不存在绕开登录的直连路径 | | 心跳监视 / 主题信息 | 示例功能（纯 Client） |

会话区随身小控件：启用后，在会话输入区工具行（模型选择器左侧）显示——

• 模型余额：当前选中 Provider 的账户余额（跟随模型切换实时更新），点击打开功能坞并定位到该 Provider 的余额详情；
• 用量记录：当前会话的总 Token 与估算花费（10 秒静默刷新），点击打开功能坞并跳转到该会话的用量记录。

勾选「启用」即显示，点芯片跳转；每个功能可在面板页脚或设置页单独设置「会话页显示/隐藏」。

界面

点击侧栏底部「功能坞」按钮，弹出功能面板：左侧导航 = 首页总揽 + 各功能模块，右侧内容区。

面板支持最大化 / 最小化 / 还原、标题栏拖动、右下角缩放。

---

安装

dsh-dock 是 DeepSeek Harness（dsh）的插件，通过 dsh 插件命令安装：

# 安装 npm 版
dsh plugin --profile web add dsh-dock

# 或安装本地开发版（克隆仓库后）
dsh plugin --profile web add /path/to/dsh-dock

查看 / 卸载：

dsh web --dump-config                     # 查看合成配置（确认 dsh-dock 已加载）
dsh plugin --profile web remove dsh-dock  # 卸载

也可以手动在 cordis.patch.yml 中声明插件后重启 dsh。

要求：DeepSeek Harness 环境（dsh），Node.js 18+。

使用方法

快速上手

1. 启动 dsh：npx @deepseek-ai/dsh web
2. 打开浏览器访问 dsh 的 web 界面
3. 在左侧边栏底部找到 「功能坞」 按钮，点击弹出功能面板
4. 面板左侧是导航：首页总揽 + 各功能模块；右侧是对应内容区

启用 / 停用功能

每个功能有独立开关，两个入口：

• 弹窗页脚：进入某个功能页，页脚显示「已启用（点击停用）/ 已停用（点击启用）」
• 设置页：侧栏底部 → 设置 → 功能坞，每个模块卡片上有开关

停用某功能后，其菜单项、首页卡片、会话区小控件一并隐藏。

会话区随身小控件

启用「模型余额」「用量记录」后，会话输入区工具行（模型选择器左侧）会出现两个小芯片：

• ⛁ 会话用量：显示当前会话的 Token 数与估算费用（10 秒自动刷新）
• 余额：显示当前选中模型的 Provider 账户余额（跟随模型切换实时更新）

点击芯片直接跳转功能坞对应页（「会话用量」打开后即按当前会话筛选出结果，无需再点查询）。每个功能可在面板页脚或设置页单独设置「会话页显示 / 隐藏」。

各功能使用

用量记录

1. 打开功能坞 → 用量记录
2. 使用顶部筛选：时间范围（秒级）、会话、提供商、模型（与提供商联动）、状态、推理强度
3. 点「查询」有等待动画：数据量大时要等几秒，这段时间不再只有一行「加载中…」——状态行变成 ⟳ 加载中...（转圈 + 省略号一个个蹦出来），按钮转成「查询中…」（转圈 + 流光扫过，期间禁用不会重复提交），数据区顶部浮出「记账小队」banner（🧮📒🔍 轮流蹦跳 + ✦ 闪星 + 扫光进度条，每 1.3 秒换一句俏皮文案，等超过 5 秒会换成安抚语气），加载期间旧数据整体压暗且不可点；结果到位时闪一次「✓ 数据已更新」、KPI 卡错峰回弹
4. 查看 9 张 KPI 卡（调用次数 / Token / 输入 / 缓存命中 / 命中率 / 输出 / 金额 USD / 金额 CNY / 累计耗时）
5. 「分组汇总」按 无 / 提供商 / 模型 / 状态 / 强度 维度切换
6. 明细表 15 列可排序，100 行/页，点击「会话 ID」即筛选该会话；行右侧「详情」看单次调用信息
7. 「CSV 导出」下载当前筛选结果
8. 费用不准？点「单价设置」按模型填真实单价：官网刊例价是抓来的，与实际计费（第三方中转、折扣、自建端点）常有出入。点开独立的「单价设置」子弹窗（可最大化、拖动、缩放），可按模型逐条配置单价（人民币元 / 百万 tokens，匹配模型名子串即可），并设置兜底单价、USD→CNY 汇率、是否继续自动同步官网价。每个模型还可配置多段分时价（如 DeepSeek 的高峰/优惠时段），命中哪段用哪段、时段外回落基准价，支持跨零点（如 23~7）与半点边界（如 8.5 = 08:30）。保存后写入宿主配置持久保存，费用立即按自填单价重算（无需重扫历史）；计价优先级：自定义单价 > 官网同步价 > 内置价 > 兜底价。明细表里走兜底价的金额会标「兜底」，方便你补配。

模型余额

1. 打开功能坞 → 模型余额
2. 列表展示全部已配置 Provider 的余额/配额状态（每 5 分钟自动刷新，可手动「刷新」）

任务动画

1. 打开功能坞 → 任务动画（与「任务通知」「运行状态」互相独立，可只开其一）：
   • 运行动画：任务进行中才出现，19 种氛围模式任选（默认「流光细线」），速度随任务吞吐自动加快（Token 速率驱动）：
     • 流光细线 / 呼吸光点 / 轨道光环 / 环屏巡航 / 代码雨 / 星野 / 极光：顶部流光、徽标呼吸、轨道光环、边缘巡航、字符缓落、星点闪烁、柔光带等克制动效
     • 桌面伙伴：CSS 3D 立体的具象人物坐在紧凑双工位前，任务活动越密集动作越快；流级实时同步任务阶段——模型思考时微抬头、单手托下巴，正文输出/写代码时低头键入右侧工位，查资料时转头扫视左侧屏幕；整卡可拖到屏幕任意位置（位置持久化），右下角手柄 / 面板滑块可缩放大小（85%~220%，自动保存）
     • 星际远征 / 星云潮汐 / 曲速航道 / 量子雷达 / 星座网络 / 数据萤火 / 深海脉动 / 棱镜光谱 / 神经电路 / 引力涟漪 / 灵感天灯：从星系远征到电路脉冲的十一种氛围场景（星际远征完成时货运舰会归航停泊在输入框上方）
2. 任务结束动效自动消失，完成瞬间一缕流光掠过；功能坞面板打开时环境动效自动隐藏避免重叠
3. 任务运行状态（进行中 / 等待确认 / 最近完成）见左侧「运行状态」菜单，结束与需确认提醒见「任务通知」
4. 配置（动画开关 / 动画模式 / 桌面伙伴大小）经宿主 settings 持久化，重启 dsh 后自动恢复

任务通知（从「任务动画」拆出，独立菜单项与开关）

1. 打开功能坞 → 任务通知：
   • 通知事件：完成通知 / 异常通知 / 需确认提醒（工具等待你批准，如沙箱越界执行命令时弹常驻卡片 + 确认音）各自独立开关
   • 提醒方式：卡片停留时长（4 / 8 / 15 / 30 秒或常驻）、浏览器系统通知（仅页面后台时推送，首次开启会请求授权）、提示音 6 种 WebAudio 合成音效可选（完成 / 异常 / 确认各配一音，可单独试听）
   • 钉钉推送（可选）：任务结束由宿主直发 markdown 消息到钉钉群机器人（浏览器关着也能推）——填入 Webhook 地址保存，「发送测试消息」验证连通；机器人安全设置选「自定义关键词」填「任务」或「dsh」
   • 飞书推送（可选）：与钉钉同款消息以卡片形式推送到飞书群机器人——填入 Webhook 地址（https://open.feishu.cn/open-apis/bot/v2/hook/…）保存，「发送测试消息」验证连通；可与钉钉同时开启
2. 通知与动画互不依赖：停用「任务动画」后通知照常工作，反之亦然（动画 / 通知 / 运行状态共用同一份宿主侧任务追踪，只有一份开销）
3. 群机器人推送的事件筛选跟随「完成 / 异常通知」开关；通知配置经宿主 settings 持久化，重启后恢复；升级会自动把旧版存在「任务动画」里的通知配置迁移过来

运行状态（从「任务动画」拆出，独立菜单项与开关；只读）

1. 打开功能坞 → 运行状态：
   • 进行中任务：任务标题 + 阶段标签（思考中 / 输出中 / 编写代码 / 查资料）、模型（Provider）、已运行时长、回合 / 步骤 / 工具次数、输入↧输出↥ Token
   • 等待确认：顶部横幅提示「N 项等待确认」，对应任务打「等待确认」标签并列出等待的工具与说明（工具等待你批准时任务会停在原地）
   • 最近完成：最多 10 条，含结束原因（完成 / 出错 / 已中止 / 受阻 / 达输出上限 / 中断）、耗时、Token 与结束时间
2. 面板打开时自动刷新（有任务 2 秒、空闲 8 秒、出错 15 秒），也可手动「刷新」；本模块没有常驻浮层，关掉面板即零开销
3. 本页只读、不写任何配置：数据来自宿主侧会话级任务追踪（与动画 / 通知共用一份）；动效在「任务动画」，结束 / 需确认提醒在「任务通知」

模型设置

1. 打开功能坞 → 模型设置
2. 编辑各 Provider 的模型目录：输入类型（文本 / 图片）、思考强度档位；新建 Provider 后进入页面会自动重读目录，顶部和底部都可手动刷新
3. 是否可直接识图以你勾选的「图片」能力为准；运行时候选仅作辅助提示
4. 保存后写回官方配置，即时生效（无需重启）

图片理解代理（visionproxy）

• 用于图片内容识别等场景。原图直发候选默认折叠，模型设置中勾选「图片」输入类型的模型即可走该通道；请按实际 Provider 能力选择，端点不支持时取消该标记即可恢复代理识别。

远程访问

主 DSH 默认只监听 127.0.0.1（官方 CLI 拒绝 --host 0.0.0.0，因为浏览器表层没有登录认证）。「远程访问」提供账号密码登录的网关作为唯一远程入口，主实例保持仅本机：

1. 账号密码登录网关（唯一远程入口）：在功能坞「远程访问」页设置账号密码并点开启，网关监听 0.0.0.0 的独立端口（默认主端口+1，如 3080 → 3081，可改）。所有设备（电脑/手机/平板）访问 http://<电脑IP>:<网关端口>，未登录自动跳转登录页，登录后进入的是同一个 DSH 进程——历史会话、工作区（含浏览式选目录）、正在进行的任务进度、设置实时一致；登录会话 Cookie 7 天滑动过期，点「退出登录」随时注销。网关与主服务是同一台机器上的两个监听，不能共用一个端口。工作区目录选择钉为浏览器浏览模式（远程设备不能弹本机对话框）；远程页面的兼容兜底（crypto.randomUUID）由网关注入。
   • 密码只存加盐哈希；登录失败按来源 IP 限速（10 分钟 10 次）；修改密码后所有设备立即下线；关闭远程访问即停止网关并注销所有会话。
   • 异地组网：Tailscale/ZeroTier 等虚拟组网内直接用组网 IP 访问同一入口，效果与局域网相同。
   • 旧版「服务器模式（0.0.0.0）」与「扫码令牌接力」已被此方案取代：前者把无认证的 DSH 裸露给局域网，后者双实例任务状态不同步。开启远程访问时会自动清理旧的 0.0.0.0 webserver 补丁行（提示重启后回到仅本机）。

趣味游戏

• 任务在后台继续执行时，游戏在局部浮动窗口里运行（可拖动、可调大小、可最大化/最小化、不遮挡会话内容）。
• 屏幕侧边的「趣味游戏」磁吸入口贴在左边栏右缘（不挡工作区目录），可换上下部位、左右换边，位置会被记住。
• 十款小游戏：五子棋、中国象棋（你 vs AI）、俄罗斯方块、推箱子、贪吃蛇、打砖块、极速赛车、坦克大战、星际躲避、反应堆解谜；都支持键盘（配套的也配了按钮）操作。

心跳监视 / 主题信息

• 示例功能，展示纯 Client 功能模块的写法

常见问题

• 插件会消耗 token 吗：默认不会。用量记录/模型余额/任务动画/任务通知/运行状态/模型设置都是被动监听或本地查询，不调用 AI。唯一主动调 AI 的是「图片理解代理」（用视觉模型识图），它默认关闭，需你在模型设置里手动开启才生效；开启后每次识图按所选视觉模型计费。
• 功能开关刷新后重置：v0.5.0 起功能开关已持久化（浏览器本地存储），刷新/重启后保持。
• 任务动画/任务通知/运行状态不生效：三者的路由都在宿主进程内（动画/通知的配置持久化也在宿主），旧宿主需重启 dsh web 加载（面板页会提示「宿主进程是旧版本」）。另注意通知与运行状态已各自独立成菜单项，需在功能坞里分别开启「任务通知」「运行状态」。
• 用量记录空白：确认 dsh 是较新版本且插件宿主已加载（查看启动日志含 [dsh-dock] host half loaded）；旧宿主进程需重启 dsh web 加载新路由。
• 费用不准 / 与实际账单对不上：金额是按单价估算的，官网抓取来的刊例价不代表你的实际计费。在用量记录页点「单价设置」（独立子弹窗，可最大化/拖动/缩放），按模型填真实单价并保存（持久化到宿主配置），费用会立即按自填单价重算；每个模型还支持多段分时价（跨零点 / 半点边界）。计价优先级为「自定义单价 > 官网同步价 > 内置价 > 兜底价」，明细里走兜底价的金额会标「兜底」。
• 余额显示「需登录 / 无密钥」：对应 Provider 未在 dsh 凭据中配置可查询余额的密钥，属正常状态提示。
• 切模型 / 打开历史会话卡住，报 preset "…" failed to mount：这是该 agent 预设与 dsh 版本 的 schema 漂移，不是本插件的问题。预设目录在 ~/.dsh/.agent-presets/<id>/，dsh 升级后预设里的 行可能不再合法（例如 @deepseek-ai/dsh-persona 在 0.1.5-rc.1 把 config.text 改为必填的 config.prefix + config.suffix），导致绑定了它的会话无法 resume。修法：把该预设与 dsh 自带的 standard 预设对齐（照抄新字段，保留自己的 persona 正文）；细节见 docs/workflow.md §6「升级核对」。

开发：新增一个功能模块

开发流程、提交/推送约定与发版流程见 docs/workflow.md（唯一真源）； 配套 agent 预设为 dsh-dock 插件开发。改动历史见 docs/session-notes.md。

每个功能是一个 features/<id>/ 目录，由两部分组成：

features/<id>/
  host.js        # 宿主半部：注册 RPC 路由 / 定时任务（纯 ESM，零构建）
  view.js(x)     # 客户端视图：渲染面板内容（自带样式，CSS 类名带前缀隔离）

在视图模块导出功能描述符：

export const feature = {
  id: "my-feature",
  name: "我的功能",
  order: 160,              // 菜单排序（首页固定第一，数值越大越靠后）
  accent: "#22c55e",       // 品牌色
  description: "…",
  css: "…",
  View: MyView,            // 面板内容组件，收到 { ctx, feature, params }
  HomeStat: MyStat,        // 可选：首页总揽卡片统计
  Chip: MyChip,            // 可选：会话输入区小控件
  Overlay: MyOverlay,      // 可选：功能全局浮层（功能启用即常驻整页挂载，如任务动效/通知）
};

外壳只做组装：宿主半部在 index.js 注册，客户端在外壳 src/client.jsx 装配。 每个模块可整体拎出单独打包发布（scripts/extract-feature.mjs 生成独立包骨架， 独立包装回后经 dockBridge 注册回功能坞菜单）。

许可

MIT