loyalchiiina/dsh-todo-float-ball

你的 AI 助手在跑长任务，计划清单却总在眼前消失？把它变成一颗常驻的进度球。 把 AI 干活的任务清单常驻挂在一个悬浮球上 —— DeepSeek Harness（DSH）进度悬浮球插件。

English | 简体中文

---

一句话说明

DSH 里让 AI 干活时，它会用内置的 todo_write 记一份任务清单。官方界面把这份清单渲染成输入框上方的一小条——但那一小条很容易被忽略、会随对话滚走、助手还在干活时它就已经折叠了。你被迫反复翻对话找"现在到底做到哪一步了"。

dsh-todo-float-ball 把这份清单搬到一颗常驻悬浮球上：

你遇到的	这个插件怎么解决
计划条随对话滚走，找不到进度	球常驻窗口角落（默认右下角，可拖拽，位置跨重启记忆）
想知道"几项做完了"，得展开细看	球面直接显示 已完成/总数，进度环同步可视化
不知道助手当前在忙哪一项	球面显示当前进行中任务的名称；胶囊模式只显示这一行
同时跑多个会话，来回切换看进度	固定多个会话，面板并排显示多栏进度，一屏看住所有并行任务
任务做完没做完，颜色分不清	状态色一眼可读：橙脉动=进行中 / 绿=全部完成 / 蓝=只有待办 / 灰=暂无清单
想回看之前排过的任务	历史归档：新计划覆盖旧计划时，旧任务自动折叠进"历史"区，不会凭空消失
球挡住视线	一键隐藏、胶囊化、可拖拽，还能按会话分别记住

它只是一个只读的观察者：插件从不修改官方面板、不改对话内容、不干扰其他插件。

为什么值得装

• 专治"长任务失联" —— DSH 的 AI 会自动续跑很多轮，你可能十几分钟不看屏幕。球上的橙灯和 3/8 让你一眼就知道还在跑、跑到哪了。
• 多会话并行不再瞎猜 —— 固定标签把两栏进度并排摆在同一个面板里，不用左点右点来回切。
• 三球视觉统一 —— 与姊妹插件 dsh-skill-browser、dsh-font-enhancer 共用同一套 120 款皮肤目录，三个球一起换肤、风格一致。
• 双端同一份代码 —— 桌面端（Electron）和网页端行为一致。
• 零侵入零配置 —— 装上即用，不写配置文件也不改官方 UI；Shadow DOM + all:initial 做样式隔离，与你其他主题/皮肤插件互不干扰。
• 数据来源可靠 —— 双通道同步：官方 todo 面板的 DOM 观察 加上 会话投影帧被动解析。官方那一条折叠了，球上依然是完整清单。

效果展示

固定标签 · 双对话任务进度

固定两个会话后，面板同时显示两栏任务进度，并行任务不用来回切换会话就能一起盯着。

胶囊模式

右键球体可收起为细长胶囊，只显示当前进行中的任务和 已完成/总数——屏幕空间紧张时用。

皮肤

内置 120 种皮肤，与姊妹插件 skill-browser / font-enhancer 的球共用同一套皮肤目录，三球外观保持统一。

基本用法

• 悬浮球始终固定在窗口角落（默认右下角）。
• 球面实时显示 已完成/总数，下方显示当前进行中的任务名；外圈进度环同步可视化同一比例。
• 单击展开完整任务面板；再点一下（或按 Esc）收起。
• 右键切换到胶囊模式，只显示当前进行中的任务和进度数字。
• 拖拽到任意位置，按 profile 记忆坐标；拖出屏幕会自动拉回。
• 颜色一眼看状态：橙色脉动 = 正在干活，绿色 = 全部完成，蓝色 = 只有待办，灰色 = 暂无清单。

它是一个纯只读的伴生插件：不修改官方面板、不改对话流、不碰任何其他插件的实现。

功能总览 · At a glance（中英对照 / Bilingual）

悬浮球 · Floating ball

中文	English
常驻可拖拽悬浮球（默认右下角），位置记忆跨重启恢复，越界自动拉回	Persistent draggable ball, position remembered, off-screen clamped back
球面实时 完成数/总数 + 当前进行中任务名（截断）	Live done/total + active task name, updated in real time
状态颜色：橙脉动=进行中 / 绿=完成 / 蓝=待办 / 灰=空清单	Status colours: orange pulse / green / blue / gray
每项带图标与配色：✓ 完成（绿+删除线）、▶ 进行中（橙）、○ 待办（灰虚线）	Per-item icons: ✓ done, ▶ in progress, ○ pending

面板与数据 · Panel & data

中文	English
点球折叠/展开，靠屏幕边缘自动翻侧	Click to fold/expand; flips sides near the edge
双路数据同步：DOM 观察 + 会话投影帧解析——官方面板折叠时也有完整清单	Dual-channel sync: DOM observer + projection frames — full list even when collapsed
Shadow DOM + all:initial 样式隔离	Shadow DOM with all:initial isolation
桌面端 + 网页端双端可用	Works on Desktop and web

历史与固定会话 · History & pinned sessions

中文	English
快照合并而非替换，旧任务进历史归档区	Snapshots merge, older todos become a history archive
行级 ✕ 隐藏、两个折叠行、🧹 批量清理、♻️ 一键恢复、📋 整行复制	Per-row hide, fold rows, batch cleanup, one-click restore, full-text copy
📌 固定会话共用同一渲染器，状态按会话独立	Pinned sessions share the renderer, per-session state
⇄ 上下堆叠 ⇄ 左右并排布局切换	⇄ stacked / side-by-side layout switch

纪律注入 · Discipline injection

中文	English
向每次会话系统提示注入 todo 纪律（order=190）——装插件即生效	Injects todo discipline into every session — works on install
硬门：每轮首个工具调用必须是 todo_write（可用 enforceFirstTodoWrite: false 关闭）	Hard gate: first tool call per turn must be todo_write (toggle)
只有显式布尔 false 才关闭	Only explicit false disables it

皮肤与隐私 · Skins & privacy

中文	English
三球共享 128 款皮肤（含经典旧皮肤）	Shares the 128-skin catalogue across the three balls
零遥测、零上传，仅回环健康路由	Zero telemetry, loopback-only health route

功能清单

功能	说明
常驻悬浮球	始终在视口内可见，可拖到任意位置，位置存 localStorage 重启后恢复（保存了越界旧位置会自动拉回视口内，防"球丢了"）
实时进度	球面显示 完成数/总数 + 当前第一个进行中任务的内容（超长截断），随 todo_write 实时刷新
折叠/展开	点球切换任务面板；面板在球旁边弹出，靠边时自动翻到另一侧
状态颜色	每项带状态图标与配色：✓ 已完成（绿色+删除线）、▶ 进行中（橙色）、○ 待办（灰色虚线圈）；球本身：橙色脉动/绿/蓝/灰
数据双路同步	主路：MutationObserver 监听官方 todo 面板 DOM；辅路：包装 fetch 与 WebSocket.onmessage，被动捕获会话投影帧 {type:"projection", key:"todos", ...}——官方面板折叠时也能拿到完整清单
Shadow DOM 样式隔离	全部 UI 在 open Shadow DOM 内并加 all:initial——样式不进不出，主题/皮肤插件互不干扰
双端可用	DSH Desktop 桌面端（Electron 窗口）与网页端（浏览器）同一份代码通用；UI 挂载在 <html> 根节点，规避 transform 导致的 position:fixed 失效
隐私友好	零遥测、零数据上传。宿主端只注册一个仅限本机回环访问的健康检查路由（/dsh-todo-float-ball/health）
纪律注入（v0.9.0）	宿主端向每次会话的系统提示注入 5 条最硬的 todo 纪律（约 340 字，order=190）——装上插件即生效，无需加载任何技能；可用 injectDiscipline: false 关闭
历史归档与面板管理（v0.10.0）	快照合并不再冲掉旧任务——旧任务进入可折叠的历史归档；行级 ✕ 隐藏、两个独立折叠行、🧹 批量清理、♻️ 一键恢复、📋 整行复制；球面计数只反映最新快照
固定会话同款体验 + 面板布局切换（v0.11.0）	📌 固定会话与当前对话走同一个历史渲染器（两个折叠行、🧹、♻️、按会话独立的开合与操作归属）；面板头部新增 ⇄ 按钮，可在【上下堆叠】与【左右并排】之间切换，并带列标题

固定会话与面板布局（v0.11.0）

• 一套渲染器，两种清单——当前对话与每个 📌 固定会话都由同一个 historySectionHtml() 渲染：最新快照平铺，其后是 ▾ 已完成历史（N 条） 与 ▸ 被抛弃的历史任务（M 条），每个折叠行自带 🧹，另有 🧹 一键清理全部历史 与 ♻️ 一键恢复全部隐藏的历史。固定会话面板是从本版本起才拿到后两行的。
• 状态按会话隔离——折叠开合与隐藏记录都以会话 id 为键，在 A 会话里展开或清理不会影响 B 会话；每个操作行都带着它所属会话的 data-ownsid。
• 快照边界稳定——快照/历史的切分先按未过滤的原始列表取 snapLen，再各自过滤隐藏行，隐藏一条快照行不会再把历史行顶进快照区、也不会改变折叠计数。
• ⇄ 布局切换——上下堆叠（当前清单在上、固定会话在下）⇄ 左右并排（左列当前清单、右列固定会话）；偏好写入 localStorage["dsh-todo-float-ball-layout"]，下次打开自动恢复。
• 列标题——左右并排时左列显示当前对话标题（与头部同源同步），右列显示 📌 固定会话；上下堆叠时列标题隐藏，视觉与之前完全一致。

历史归档与面板管理（v0.10.0）

一个长任务里计划会被反复重写。v0.10.0 起面板把最新快照作为当前清单， 更早的条目不再被丢弃，而是归档进历史：

• 合并而非替换——新快照更新会话桶开头 snapLen 行，旧记录里不属于新快照的条目追加在其后，旧任务永不消失。
• 统计口径 = 当前计划——球面 完成数/总数、进度环、头部汇总、「还有 N 项未完成」提示全部只统计最新快照（snapshotList()）；历史是纯档案，不进任何计数。
• 行级隐藏（✕）——悬停历史行点 ✕ 即隐藏。隐藏记录按会话存在 localStorage（dsh-todo-float-ball-hidden-v1），数据层零改动。固定会话（📌）的行独立隐藏——会话 A 的隐藏记录绝不会隐藏会话 B 的行（data-ownsid 归属过滤）。
• 两个折叠行——▾ 已完成历史（N 条） 与 ▸ 被抛弃的历史任务（M 条） 是独立折叠行（默认收起）；最新快照始终完整平铺。
• 批量清理（🧹）——每个折叠行带 🧹 清本区按钮，另有 🧹 一键清理全部历史（X 条） 一行同时清两区。
• 一键恢复（♻️）——♻️ 一键恢复全部隐藏的历史（X 条） 仅在有隐藏条目时出现，一次恢复本会话全部隐藏行。
• 整行复制（📋）——复制完整任务文本（非 80 字显示截断），带真实 ✓/⚠ 反馈。

纪律注入（v0.9.0）

DSH 的技能是按需加载的：一个会话若从未加载 todo-show-discipline 技能，就完全不带 todo 纪律。v0.9.0 起，宿主端会向每次会话的系统提示注入一段稳定的「todo 纪律」段落，因此装上插件就等于纪律常驻——与技能是否加载、用哪个预设、桌面端还是网页端都无关。

• 默认开启（不写 config 即为开）。
• 关闭：在 cordis.patch.yml（或 profile 的 patch 层）给本插件加 config: { injectDiscipline: false }，重启 DSH 生效。
• 只有显式布尔 false 才关闭；"false" / 0 / 拼错 / 缺 config 一律保持开启（防误关）。
• 注入文本刻意精简（系统提示每会话都占 token），完整规则仍留在 todo-show-discipline 技能里；该技能在装了本插件后默认不再随会话加载（disable-model-invocation: true）以避免重复占 token，未装本插件时可恢复启用。

安装

本插件是标准 DSH npm 包（自带 dsh.bundle 声明）。两种方式：

从 npm 安装（发布后）

npm install dsh-todo-float-ball

然后在你所用 profile 的 package.json（如 %USERPROFILE%\.dsh\profiles\desktop\package.json）里，把 "dsh-todo-float-ball" 同时加进 dependencies 和 dsh.profile.bundles，重启 DSH 生效。

手动安装

把本包目录整体复制进 profile 的 node_modules（必须是真实目录复制——不要用 link: / file: 依赖，会触发 DSH 安装恢复死循环），按上面同样方式注册后重启。

重启后右下角应出现悬浮球。可用下面的地址验证宿主端已挂载：

http://127.0.0.1:43120/dsh-todo-float-ball/health
→ {"ok":true,"plugin":"dsh-todo-float-ball","version":"<已安装 package.json 里的版本号>"}

实现原理

官方的 todo 数据是一条会话投影（session projection）：

1. @deepseek-ai/dsh-tool-todo 注册 todo_write 工具，并在 sessionProjections 上登记 todos 投影单元；每次调用向会话日志追加一条 todo/write 快照；
2. @deepseek-ai/dsh-client-connection 把当前值以控制帧广播：{type:"projection", sessionId, key:"todos", value:[{content,status}...]}；
3. @deepseek-ai/dsh-client-ui-conversation 把它渲染成输入框上方的任务条（[data-testid="todo-panel"]）。

本插件在两端各挂一个只读探针，不碰任何一端：

• 主路（DOM）：一个带 200ms 防抖的 MutationObserver 盯着 [data-testid="todo-panel"]——面板展开时读 li[data-status] 全量清单；折叠时解析本地化的计数文案（如"1 完成 · 2 进行中"，含中文数字解析）。
• 辅路（传输层）：一次性、防御式的 window.fetch 包装（clone 响应、只处理文本/JSON）与 WebSocket.prototype.onmessage 包装（文本帧），把每个载荷送进严格的提取器——只对形如投影帧、todo/write 事件、{todos:[...]} 快照的对象起反应，其余一律忽略，绝不回写。

所有通道汇入同一个归一化器：过滤出三种合法状态、丢弃空内容、列表无变化时零开销跳过（签名比对）。

常见问题

悬浮球不出现？ 先开上面的 health 地址：能返回说明宿主端正常，是客户端 bundle 没加载（查 DSH 日志有无 loaded without registering，bundle id 必须与包名一致）；不能返回说明插件没进 profile 的 bundles 列表。

能移动悬浮球吗？ 能，拖到哪都行。位置按浏览器/渲染进程分别记忆；万一保存的位置跑到屏幕外，启动时会自动拉回视口内。

官方面板折叠时也能同步吗？ 能。这正是辅路存在的意义：官方面板折叠时只渲染计数文案，而投影帧始终携带完整清单。

会拖慢界面吗？ 不会。观察器 200ms 防抖；传输层窃听先做 "todos" 字符串预筛再解析；兜底看门狗跑约 10 分钟后自动停止。

兼容性

• DSH Desktop 2.x（desktop profile）与 DSH web（web profile）
• 无 peerDependencies——插件自包含，只通过公开 DOM/HTTP 面与 DSH 交互

License

MIT