全局任务库 sgzxs/dsh-global-task-list

dsh-global-task-list

为 DeepSeek Harness 打造的全局任务库：六个面向模型的工具、常驻浏览器面板、子代理作业状态同步，以及生成式 UI 的 surface 渲染器。任务存放在 storageDomain 单元中，跨会话持久化，重启后依然存在。

全局任务列表插件：为 DeepSeek Harness 提供一个跨会话持久化的任务库，附右下角常驻面板（轨迹等非对话界面自动隐藏）。主 agent 用 task_add 创建任务（带描述与进度），spawn 子 agent 后关联 jobId 自动同步终态；面板支持手动改状态、删除、拆分，并实时（SSE）刷新。任务可携带 surface 结构化文档渲染生成式 UI（进度条、时间线、表格、DAG 等）。

它能做什么

- 全局任务库 —— task_add / task_list / task_get / task_update / task_delete 这几个模型工具，操作一个跨会话的 storageDomain 单元（task_ui）。任务包含标题、状态（pending / running / done / blocked / failed）、描述、nextStep、有序的 steps 流程、parentId、dependsOn，以及可选的 progress（{ text, percent? }）和可选的 surface 文档。
- 常驻面板 —— 右下角浮动面板（挂载在会话级的 conversation.input.dock 插槽），订阅 Server-Sent Events 通道（/task-ui/events），任务一有变化就刷新，让你改状态、删除（带确认）、触发生成式拆分循环。点击卡片会在其下方展开一张次级卡片，显示描述、步骤流程、依赖关系和时间戳。样式使用 --dsw- 主题 token，支持中英文。在非对话视图（如轨迹）中自动隐藏。
- 步骤流程 —— 详情卡片用垂直流程而不是进度条来描述进度：已完成和待处理的步骤共用朴素边框，真正重要的两个则画得不一样 —— current 用实心品牌色边框加淡色底，next 用虚线边框。步骤来自所属任务的 steps（done / current / next / todo）；如果任务没写 steps，面板就从 progress 推导出一个节点；列表里没写 next 时，会把 nextStep 继承为一个节点。步骤状态是画出来的，所以也会以文本形式播报给屏幕阅读器。
- 面板动效 —— 新任务升起时，底部锚定的面板会按新增的高度向上滑动，正是这个动作把卡片托了起来；删除的卡片在退场动画期间保留自己的位置，动画结束后面板再收回。展开纯靠 CSS（grid-template-rows: 0fr → 1fr）。在 prefers-reduced-motion 下全部跳过。被移除的卡片会在 layout* effect 中重新收编为幽灵行，因此它不会在任何一个绘制帧里离开 DOM —— 正是这个空档让整个列表闪烁，并让面板在删除时经历一轮收缩/扩张/收缩。
- 可调整大小 —— 拖动面板左边缘（或聚焦后用 ←/→）可在 260px 到 760px 之间设置宽度；宽度记在 localStorage 里。手势沿用 ui-layout 自己的 DragHandle：整个拖动过程使用 pointer capture，每个动画帧只做一次节流更新，宽度从拖动起点计算，而不是每次移动累加。
- 子代理任务同步 —— 通过 task_update(id, { jobId }) 关联到后台作业的任务，会依据 JOB_STATUS_MAP 自动推进其终态（completed→done，failed→failed，killed→blocked）。任务由主智能体显式创建，绝不会从任意后台作业自动注册。
- 生成式 UI 界面 —— 任务的 surface 字段渲染一棵白名单递归组件树：section、metric、statusBadge、progress、table、list、timeline、dag、disclosure。

安装

推荐从 npm 安装 —— 包内已附带预构建的 lib/，安装时不会跑构建步骤。GitHub 方式则拉取源码，并在安装时构建（见下文）。

npm (recommended, prebuilt — no build step at install)
dsh plugin --profile web add dsh-global-task-list

GitHub (alternative: source + prepare build)
dsh plugin --profile web add github:sgzxs/dsh-global-task-list#v0.2.0

包内声明了 dsh.bundle，所以 dsh 会自动把它加进配置档的 bundles。前提是 DSH 安装里已有 @deepseek-ai/dsh-base，并且客户端界面（dsh-web-app）也在。

DSH 运行时是 0.2.x（桌面应用为 0.2.0-rc.2）时，请至少用 0.2.0：更早的版本只声明了 0.1.x 的 DSH peer 范围，运行时会在 pnpm 跑起来之前就拒绝它们，报错为 installation rejected: Plugin dsh-global-task-list@0.1.5 is incompatible with dsh 0.2.0-rc.2。桌面应用还会自行管理配置档 —— 见在桌面应用上安装。

我实际装到的是哪个版本？

不一定是你看到的那个。市场显示的是注册表报告的版本，而安装是一次包管理器运行，解析结果可能不同 —— 配置档 package.json 里的精确锁定、pnpm-lock.yaml 里的条目，或者依次询问的注册表（第一个注册表不可达、或回答没有这个版本时，DSH 的插件管理器会回退到 registry.npmmirror.com，而镜像会滞后于 npm）。没有任何机制会去调和这两者，所以「市场说 2.10，我装到 2.3」是解析结果，不是下载了旧文件。

想看真相，有两个办法：

- 让智能体跑 taskui_probe —— 它会回答 [task-ui] v<version> host alive, tasks=N；启动时宿主日志里的 [task-ui] host plugin loaded v<version> 说的是同一件事；
- 读配置档：<dshHome>/profiles/<profile>/node_modules/dsh-global-task-list/package.json。

想让更新真正落地，就显式写出版本号 —— 精确版本还能让管理器的注册表方案绕过一个尚未同步该版本的镜像：

dsh plugin --profile web add dsh-global-task-list@0.2.11

想持续收到更新，就依赖一个范围而不是精确版本：配置档锁在 0.2.2，无论市场显示什么，它都会一直装 0.2.2。

GitHub 安装：allowBuilds

从 GitHub 安装会拉取源码，所以 pnpm 必须运行包的 prepare 脚本才能构建出 lib/。默认情况下，pnpm 会阻止 git 托管的包执行该脚本，而它的 allowBuilds 键匹配的是确切的 commit（只写包名的条目不会匹配——见 pnpm#12367）。因此第一次 add 会失败，报出 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，消息里会打印出需要放行的确切键。把这个确切的键复制到配置档的 pnpm-workspace.yaml，然后重新运行：

allowBuilds:
dsh-global-task-list@git+https://github.com/sgzxs/dsh-global-task-list.git#<commit>: true

在安装命令里固定一个 tag（例如 #v0.2.0），这样 commit 哈希——也就是 allowBuilds 键——才能保持稳定。

环境要求

- DeepSeek Harness（@deepseek-ai/dsh）版本为 0.1.2-alpha.2 或更高：客户端 bundle 会从 @deepseek-ai/dsh-client-store 导入 defineStore，这是浏览器模块表中的一个条目，更早的宿主上并不存在（在那些宿主上，面板加载失败并报 Failed to load plugins）。已在 0.1.5-rc.2（命令行/web 配置档）和 0.2.0-rc.2（DeepSeek Harness 桌面应用）上验证。
- Host 部分会从配置档的 node_modules 中解析 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-storage-domain 和 zod。
- 客户端 bundle 已预构建（lib/client.js），随包一起发布；安装时不会运行任何构建步骤。

DSH 版本兼容性

Host 部分同时针对两代 DSH 编写，因为 jobs 服务在 0.2 中改变了形态：

| 接口面 | 0.1.x | 0.2.x | 本插件 |
| 任务变更订阅源 | ctx.jobs.onJobsChanged(listener)（listener 收到的是 owner Agent） | ctx.jobs.events.subscribe({ owners: 'all' }, listener)（每次提交都携带任务快照） | 先特性检测 jobs.events.subscribe，回退到 onJobsChanged；两者都不存在时禁用桥接并打印一行日志 |
| ctx.jobs.list(caller) | caller 是 owner Agent | caller 是 owner 的会话 id | 只在 0.1.x 路径上使用，而这条路径正是需要它的那条 |

插件触及的其他一切在两代之间都没有变化：defineTool / tools.register、createUserMessage、defineDomain / domainTable / storageDomain.open、webServer.register({ kind, path, handler })、agents.list() / agent.followup / session.header.origin，以及 domain/changed 事件。客户端部分完全不需要版本分支——浏览器平台模块表（react、react/jsx-runtime、react-dom、react-dom/client、@deepseek-ai/cordis、dsh-client-store、dsh-client-ui-slots、dsh-client-ui-primitives、dsh-client-ui-dockkit）和 conversation.input.dock 插槽契约在两代中完全相同。
peerDependencies 因此同时接受两条版本线（^0.1.5-rc.2 || ^0.2.0-rc.2）。DSH 会在安装时、以及再次组装配置档时，拿每个 @deepseek-ai/dsh 的 peer 范围去校验正在运行的运行时，所以范围一旦排除了当前版本，插件会被拦下，而不是降级运行。

在桌面应用上安装

桌面应用自己管着它的配置档：在 Electron 应用之外执行 dsh --profile desktop 会被拒绝，而 dsh plugin --profile desktop <args> 要求先把应用完全退出。你可以走应用自带的 Plugins 页面安装，也可以手动放置包并声明：

// $DSH_HOME/profiles/desktop/package.json
{
"dependencies": { "dsh-global-task-list": "link:../../plugins/dsh-global-task-list" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-global-task-list"] } }
}

配置档默认会重新加载配置（dsh-hmr），所以正在运行的桌面应用会在下次重新组装时挂载插件——不用重启。

构建（开发）

npm install
npm run build:host # tsdown bundles src/index.ts → lib/index.js
npm run build:client # tsdown bundles src/client → lib/client.js
npm run typecheck # tsc --noEmit, against the real DSH 0.2.0-rc.2 types
npm test # builds, then typecheck + smoke + render + CSS-classes
npm run sync web # copy the build into a profile's node_modules (dev helper)

两半都是 TypeScript：Host 那一半（src/index.ts）编译成纯 ESM，客户端那一半（TSX）连同 CSS Modules（lightningcss）一起编译成 __ModuleLoader__ 闭包工厂包。

为什么要有测试套件

构建只做转译——tsdown 跑的时候 dts: false，从不做类型检查——所以构建路径上没有任何东西能抓住写错的标识符。npm test 用六层来补上这个缺口，每一层都抓到过其他层漏掉的问题：

| 层 | 能抓到 |
| tsc --noEmit | 未定义的标识符、参数类型错误、过期的语言键（字典才是键集合的权威来源） |
| test/host-smoke.mjs | Host 那一半实际贡献了什么：六个工具、它们转换后的 JSON Schema（包括对象类型的 steps 项）、两条 HTTP 路由、job-bridge 订阅，以及 system-prompt 段落。它还会跑一遍存储生命周期：临时的 already-open 会重试，销毁插件会关掉它自己持有的句柄。 |
| test/client-smoke.mjs | 模块求值和 apply() 抛错——浏览器会把它报成「Failed to load plugins」 |
| test/render-check.mjs | 各种任务状态下的渲染路径抛错。DSH 会隔离每个 slot 条目，所以抛错的组件什么都渲染不出来：面板消失了，UI 其余部分却安然无恙。测试装置会让真实组件跑过一套最小钩子运行时，子组件也一并渲染。 |
| test/class-check.mjs | css.foo 没有对应的 .foo 规则（反过来也一样）——类映射就是个普通对象，两边都没有类型 |
| test/bundle-css-check.mjs | 在构建产物里做同样的拆分：bundle 导出的映射里每个 class，都必须在 bundle 注入的 CSS 文本里有对应规则。源码和构建结果可能对不上。 |

类型检查需要把 DSH 各包作为 devDependencies；它们精确锁定到插件所针对的运行时版本线，并且永不发布（files 只列出 lib/ 和补丁）。

模型体验

请求上下文与条件

这个包向智能体的工具目录贡献六个面向模型的工具。

模型看到什么

- taskui_probe — 报告插件的宿主存活状态和当前任务数。
- task_list — 每个任务一行分诊信息：- [status] title (id[, job=...]) — next: ...。
- task_get(id) — 一个任务的完整记录，排序方式贴合会话接手别人工作时的需要：状态和标题、progress（带百分比）、next、完整的 steps 流程及其状态、依赖、父任务、job、描述和时间戳。
- task_add(title, description?, nextStep?, steps?, parentId?, dependsOn?, surface?, progress?) — 创建任务（初始为 pending）。
- task_update(id, title?/status?/description?/nextStep?/steps?/parentId?/dependsOn?/surface?/progress?/jobId?) — 给单个任务打补丁；progress 是 { text, percent? }，nextStep 是一行「接下来做什么」，steps 是详情卡片绘制的有序 [{ text, state }] 流程，surface 接受结构化生成式 UI 文档，jobId 把任务关联到后台 job，用于终态同步。
- task_delete(id) — 删除单个任务。

列表刻意做短，细节都放在 task_get 里，所以模型的读取路径是「先用 task_list 过滤，再读你即将动手的那一个任务」。持久记录承载的信息远超任何一行能容纳的量，而后来的会话没有别的途径拿到它。

nextStep 和 steps 晚于最初的记录 schema。两者都可选且有默认值，而且该领域的后端描述符由领域名、版本和表名推导，而非来自 zod schema —— 所以加一列不需要升版本，在该列存在之前写入的记录也仍能加载。steps 的条目在写入时由持久化 zod 边界校验，因此工具参数把它们声明为宽松对象（additionalProperties: true），而不是在 JSON Schema 里重复那份枚举。

surface 文档是一棵递归的白名单组件树（section / metric / statusBadge / progress / table / list / timeline / dag / disclosure），由浏览器面板渲染。渲染器会忽略未知类型；Host 把文档当作不透明 JSON 存储。

如何让智能体用上它

技能是由模型调用的：模型看到的目录里只有每个技能的名称和描述，所以 task-ui 只在模型判断描述匹配时才加载——而不是普通工作一开始就加载。对于必须主动发生的行为，这个杠杆用错了，所以插件改用始终在场的杠杆：

1. 工具描述——这些 schema 每次请求都待在系统提示词的工具目录里。每个描述都写明用途、该动手的时机、以及边界（harness 给自己的 todo_write 用的也是这个形状，正是出于这个原因才做成主动式）。task_add 说要记录多步工作，在开始之前，并且始终在委派之前——还说要记录得晚一点，而不是干脆不记；task_update 说要让条目持续更新，要关联委派出去的任务，以及如何正确收尾（清空 nextStep，让 steps 全部为 done，把结果写进 description）。

跳过边界刻意做成形状测试，而不是长度测试。它最初写的是「跳过琐碎的单步请求 / 一次性回答」，结果一次仓库分析直接穿了过去：「analyze X」是一次交互、一个交付物，模型完全可以合理地把它归进「一次性」。现在它点名了算数的形状——analyze / investigate / compare / implement / review，以及用户称为任务的一切——并且只保留一条豁免：不用查任何东西就能给出的回复。
2. 一个系统提示词小节（task-ui:library，排在子代理工具自己的顺序上）——一句话，用 harness 自己的语体，这样即便模型从不伸手去拿工具，也知道这个库存在。它覆盖的是全部义务，不只是写的那一半：开始前记录，工作中保持最新，在继续早先会话启动的事情之前把记录读回来，点名哪些形状算多步，以及记录得晚一点也好过不记。它渲染两个变体：拥有这项工作的会话拿到全部内容，而子代理（从 AssembleContext.agent.session.header.origin 读取）只被告知要让它自己任务的记录保持真实——它不规划、不委派，也不创建它的生成者看不见的平行条目。在任何 task_add 不可调用的作用域里，它渲染为空；config.promptSection: false 会把它去掉，供更愿意只靠描述来做的部署使用。
3. 工具结果里的即时提示 —— 写入类工具只在自己的结果里报告推导出的不一致，其余情况什么都不说。task_add 会点名只有标题的条目缺了哪些字段；task_update 作用于一个刚变成 done 的任务时，会点名具体缺口（nextStep 还留着、步骤没标成 done、description 为空）。这些提示不复述任何规则，也不重复任何指引 —— 它们读刚写下的记录，报告这一条哪里不对 —— 所以只要没真出问题就不花任何代价，而且出现时机正好还来得及修。工具结果会追加到会话里，所以它和章节不同，永远不碰缓存的提示词前缀。

4. 操作手册搭上会话里第一次库调用 —— 内置技能的主体挂到第一次 task_ 调用的结果上，每个会话一次，这样即使模型从不调用 skill 工具，也会在决定使用这个库的那一刻读到手册。放在工具结果里投递有三个原因：它落在同一轮（章节或上下文只能在下一次请求生效），在从不碰这个库的会话里不花任何代价，而且它是追加到会话而不是注入提示词，所以缓存的提示词前缀不受影响。主体从本包自带的副本读取，而不是走 ctx.skills，因为宿主平面插件不能指望看到某个智能体预设挂在自己作用域里的服务商；front matter 会被剥掉，文本长度保持在工具结果裁剪器的阈值以下。

5. 编排钩子更早投递 —— 一个 tools/post-execute 监听器盯着那些暴露模型正在组织多步工作的调用：todo_write（它决定跟踪步骤了）、任何 subagent 派生（它在委派了）、workflow / ralph。会话里第一个出现的调用会通过 additionalContexts 把手册挂到那次调用上 —— 这是 harness 自己的通道，用于「为下一次请求附加上下文」—— 所以被调用工具的结果保持其所有者写下的原样。这就是区别所在：是在模型已经记下东西之后才解释这个库，还是在模型刚开始安排工作时就解释。消息用本插件自己的 MessageSourceMap kind 归属，并声明 form: 'instructions'（语义词汇表里对「从文件读出的指令」的叫法），遵循 harness 的规则：每个生产者声明自己的 kind，而不是共用一个兜底 kind。

两条投递通道都走同一个每会话一次的集合，所以恰好只有一条胜出，手册绝不会发两次。

章节按名称合并，所以这一节 —— 一个没有 DSH 包或预设使用的唯一名称 —— 既不会被部署的 persona 遮蔽，也不会遮蔽它：它们全都按 order 顺序渲染（deployment:persona-prefix 在 0，本节在子代理工具的 order，deployment:persona-suffix 在 10200）。
捆绑技能仍然是详细工作流的所在之处（子代理监督循环、流程编写规则、跨会话交接读取顺序、surface 组件目录）。它不会注入提示词——模型得先决定使用这个库，那些细节才值得花 token，而常驻的杠杆正是让它做出决定的东西——但杠杆 4 和 5 会在会话真正开始安排工作时，把正文摆到它面前，这正是「决定要用」和「知道怎么用好」之间的缺口。

Token 影响

六个工具 schema 连同描述一起注入系统提示词的工具目录，另外——除非 config.promptSection 为 false——一句固定的话注入系统提示词。成本固定；不会随任务或数据增长。

KV Cache 影响

与智能体的请求上下文组装无关。工具 schema 和提示词段落都是静态的，所以提示词前缀在多次请求之间保持稳定；任务列表内容不会进入提示词。插件版本变化（或切换 promptSection）会替换该段落或工具 schema，使复用失效。

设计说明

任务在设计上与会话无关。 记录刻意不写明创建它或最后改动它的是哪个会话，也没有任何字段把条目绑到某次对话。这个库存在的意义就是让工作无缝交接：任何会话——之后的会话、不同的预设、子代理——都能拾起条目继续做，它需要的是现在什么是真的和接下来做什么，而这两样记录都带着（progress、steps、nextStep）。记录来源会让每个条目都变成产生它的那次对话的产物，这与初衷恰恰相反；还会诱使后续会话去听从一个已不存在的归属者。这就是为什么 task_get 先给状态而不是历史，也是为什么任务活得比它起始的会话更久时，什么都不用重写。

已知限制与待办工作

- 没有图布局 —— dag surface 把节点渲染成 chip 加一个边列表，而不是定位好的图。
- Surface 不透明 —— Host 把 surface 当作未校验的 JSON 存储（z.record）；格式不对的 kind 在渲染器里回退为「忽略」，而不是在加载时报错。
- sync-profile.mjs 是本地开发辅助脚本 —— 它把构建好的包复制到 $DSH_HOME/profiles/<profile>/node_modules（profile 默认是 web），并在该 profile 的 dsh.profile.bundles 没有列出插件时发出警告。它不发布（通过 files 排除）；安装请用 dsh plugin add。
- 任务状态同步会降级，绝不阻塞 —— 运行时既不提供 jobs.events.subscribe 也不提供 jobs.onJobsChanged 时，工具、面板和 HTTP API 都保留，并记录 jobs service exposes no change feed; job status sync disabled。
- 提示词部分无法强制行为 —— 描述和一句话只能提高模型记录工作的概率；harness 里没有任何东西能强迫它。需要保证的部署应该在自己的 persona 或预设指令里说明，它们的优先级高于插件的贡献。
- 技能更新是播种式的，也可能被遮蔽 —— Host 那一半会把 skills/task-ui/SKILL.md 写入 <dshHome>/skills/task-ui/ 并保持更新，但它不会覆盖用户编辑过的副本：编辑过的副本原样保留，这一版的文本写在它旁边，名为 SKILL.md.new。更重要的是，播种的副本只是几个可能的根之一，dsh-skill-filesystem 会给它们排序（最低者胜）：项目 .dsh 100、项目 .agents 200、customSkillDirs 300、$DSH_HOME/skills 400、用户 .agents 500，包自带的副本排在最后，600。因此，如果某个部署的 customSkillDirs 里有自己的 task-ui 副本，就会遮蔽播种的那份 —— 从另一台机器复制来的智能体预设，可能悄悄钉住一份几个月前的手册，而插件的副本才是最新的。插件看不到也修不了被遮蔽的副本；如果加载的技能看起来过时，先检查这些根。
- 阻塞原因没有自己的字段 —— dependsOn 覆盖任务到任务的阻塞；不是另一个任务的原因（「等待外部服务」）只能放在 nextStep 里。
- 链接到 job 的 running 任务会被标记，而不是被纠正 —— job 注册表是进程内的，所以在运行中的 Host 启动之前写入的 jobId 不可能指向任何活着的东西。两条读取路径都会说明：task_list 追加 [expired]，task_get 以 warning: 行开头，面板用 --dsw-alias-state-warn-primary 给 job 行上色。记录是被标注*而不是被重写，因为插件无法知道工作是完成了、被放弃了，还是根本没记录。信号来自任务自己的 updatedAt 与 Host 启动时间的比较（jobs 没有暴露任何能枚举每个 owner 的 job 的调用），所以启动之后的写入会清除标记 —— 如果某个会话手动给一个仍带着旧 jobId 的任务设置 running，就会出现假阴性。

- 客户端 bundle 不是字节可复现的 —— npm run build:client 每次运行都会以不同的键顺序输出 CSS-module 类映射，所以即使源码完全相同，bundle 哈希也会变。键→哈希对本身是稳定的，运行时也没有任何东西观察这个顺序；唯一的代价是无法用哈希把本地构建和已发布的 tarball 对比，这就是为什么 lib/client.js 永远无法与它已发布的副本逐字节匹配。

致谢

灵感来自 HomeRail —— 它的生成式 UI（A2UI）思路是「智能体输出一棵有边界、带白名单的组件树，由宿主渲染成一眼能看懂的视图」。这个思路塑造了本插件的 surface 文档与组件目录（section / metric / statusBadge / progress / table / list / timeline / dag / disclosure），也塑造了「优先用内置渲染，而不是直接倒原始日志」这一原则。