sgzxs/dsh-global-task-list

dsh-global-task-list

一个面向 DeepSeek Harness 的全局任务库：五个面向模型的 CRUD 工具、一个持久化浏览器面板、子代理作业状态同步，以及一个生成式 UI surface 渲染器。任务在 storageDomain 单元中跨会话持久化，并可在重启后保留。

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

功能说明

- 全局任务库 —— task_add / task_list / task_update / task_delete 模型工具，基于跨会话的 storageDomain 单元（task_ui）。任务携带标题、状态（pending / running / done / blocked / failed）、描述、parentId、dependsOn、可选的 progress（{ text, percent? }）以及可选的 surface 文档。
- 持久化面板 —— 右下角浮动面板（挂载于会话作用域的 conversation.input.dock 插槽），订阅 Server-Sent Events 通道（/task-ui/events），在每次任务变更时刷新，允许用户更改状态、删除（带确认）并触发生成式拆分循环。使用 --dsw-* 主题令牌样式，并支持中英文本地化。在非对话视图（例如轨迹）中会隐藏。
- 子代理作业同步 —— 通过 task_update(id, { jobId }) 关联到后台作业的任务，会通过 JOB_STATUS_MAP（completed→done、failed→failed、killed→blocked）自动推进其终态。任务由主 agent 显式创建，绝不会从任意后台作业自动注册。
- 生成式 UI surface —— 任务的 surface 字段渲染一棵白名单、递归的组件树：section、metric、statusBadge、progress、table、list、timeline、dag、disclosure。

安装

从 npm 安装是推荐方式 —— 该包附带预构建的 lib/，因此安装时不会运行构建步骤。GitHub 替代方式会拉取源码并在安装时构建（见下文）。

npm（推荐，预构建 —— 安装时无构建步骤）
dsh plugin --profile web add dsh-global-task-list

GitHub（替代方式：源码 + prepare 构建）
dsh plugin --profile web add github:sgzxs/dsh-global-task-list#v0.1.5

该包声明了 dsh.bundle，因此 dsh 会自动将其添加到 profile 的 bundles 中。需要已安装 DSH，并存在 @deepseek-ai/dsh-base 与客户端 surface（dsh-web-app）。

GitHub 安装：allowBuilds
从 GitHub 安装会拉取源码，因此 pnpm 必须运行该包的 prepare 脚本以构建 lib/。pnpm 默认会阻止对 git 托管的包执行此操作，而它的 allowBuilds 键匹配的是确切的提交（仅包含包名的条目不会匹配——参见 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#: true

在安装命令中固定一个标签（例如 #v0.1.5），这样提交哈希——以及因此的 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 验证。
- Host 部分从配置文件的 node_modules 中解析 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-storage-domain 和 zod。
- 客户端 bundle 是预构建的（lib/client.js）并随包一起发布；安装时不会运行构建步骤。

构建（开发）

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

两部分都是 TypeScript：Host 部分（src/index.ts）编译为纯 ESM，客户端部分（TSX）使用 CSS Modules（lightningcss）编译为一个 __ModuleLoader__ 闭包工厂 bundle。

模型体验

请求上下文与条件

该包向 agent 的工具目录贡献了五个面向模型的工具。

模型看到的内容

- taskui_probe — 报告插件的宿主存活状态和当前任务数量。
- task_list — 将每个任务列为 - [status] title (id, job=...)。
- task_add(title, description?, parentId?, dependsOn?, surface?, progress?) — 创建一个任务（初始为 pending）。
- task_update(id, title?/status?/description?/parentId?/dependsOn?/surface?/progress?/jobId?) — 修补一个任务；progress 为 { text, percent? }，surface 接受一个结构化的生成式 UI 文档，jobId 将任务链接到后台作业以进行终态同步。
- task_delete(id) — 删除一个任务。

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

Token 影响

五个工具 schema 及其描述被注入到系统提示的工具目录中。成本固定；不会随任务或数据而增长提示。

KV Cache 影响
独立于 agent 的请求上下文组装。工具 schema 是静态的，因此提示词前缀在多次请求之间保持稳定；任务列表内容不会进入提示词。插件版本变更会替换工具 schema，并使复用失效。

已知限制与延后处理的工作

- 无图布局 —— dag 表面将节点渲染为 chip 加上一个边列表，而不是一个带定位的图。
- 表面是不透明的 —— Host 将 surface 存储为未经验证的 JSON（z.record）；格式错误的 kind 在渲染器中回退为“ignored”，而不是在加载时报错。
- sync-profile.mjs 是本地开发辅助工具 —— 它不会被发布（通过 files 排除）；安装请使用 dsh plugin add。

致谢

灵感来自 HomeRail —— 其生成式 UI（A2UI）理念是“agent 发出一个有界的、白名单化的组件树，由 host 渲染成可一眼浏览的视图”，这一理念塑造了本插件的 surface 文档和组件目录（section / metric / statusBadge / progress / table / list / timeline / dag / disclosure），以及优先使用内置渲染而非直接倾倒原始日志的原则。