任务甘特图 xx529/dsh-task-gantt

dsh-task-gantt

DeepSeek Harness 侧边栏的 agent team 任务甘特图 —— 纵轴每个 teammate 一条泳道，横轴是真实的会话时间，每个共享任务都画出标题与简介。

下面的截图是真实面板 + 合成 fixture 数据（5 条泳道、5 种不同的 agent 颜色、时长差异明显的任务、一个仍在进行的任务、双向消息箭头），由真实浏览器以 2 倍分辨率拍摄并裁到面板本体，存于 docs/screenshots/panel-v4.png。之所以标注清楚：画面是出厂组件画的，但数据是 fixture，所以它不是真机团队数据截图。图里页脚带着构建标识（v0.2.11 · label-in-box），读者据此可以判断是哪个构建画的。
其余截图（真机团队数据的面板全貌、任务卡详情、降级态）仍待补；清单见 docs/SCREENSHOTS.md。不会用示意图冒充实拍。

暗色皮肤下的任务甘特图面板：五条不同 agent 颜色的泳道、消息箭头分发出与收到、任务条长度即真实时长，标题画在条内

dsh-task-gantt 是 dsh-better-sidebar 的插件：它注册一个额外的侧边栏页签。插件是只读的 —— 它不会创建、认领或完成任何任务。

项目状态

| 版本 | 0.3.2 |
| 冻结契约（src/shared/contract.ts） | 已完成 |
| host 数据层（src/host/*） | 进行中 |
| 页签注册（src/client/index.ts） | 已完成 |
| 甘特图渲染（src/client/ui/） | 进行中 |
| 真机挂载冒烟 | 尚未执行 |

下面描述的是冻结契约规定的行为；实际跑过什么、观察到什么，看 docs/VALIDATION.md（由验证同学维护）—— 本 README 不会把没跑过的事写成结论。

功能

- 泳道 = 名单。 先是 Lead，再按名单顺序排 teammate，最后是 unassigned 行（任务还没指派给任何人时落在这里）。
- 真实时间轴。 每条活动区间、每次任务状态迁移，时间都取自持久化会话事件日志 （epoch 毫秒），不是「面板打开的那一刻」。
- turn 带 + 内嵌 step 条。 一整个 prompt/response 回合是浅色带，回合内的每个 model step 是深色条；还没闭合的区间画成开口并延伸到当前时刻。
- 任务卡承载信息，不只是颜色。 卡上是 subject 加一行 description；详情里有状态、负责人、blockedBy、writeScopes 与 ready。
- 如实降级。 拿不到时间的泳道会明说，并把任务标成实时态，而不是编一个区间出来。
- 令牌驱动主题 + 中英双语。 所有颜色只来自 DSH 的 --dsw-alias- / --dsw-font- / --ds- 令牌，因此任何皮肤都能用；界面语言跟随页面语言自动切换中/英。

运行要求

| 要求 | 值 |
| DSH | 0.2.0-rc.2（本插件的开发基准版本） |
| dsh-better-sidebar | >= 0.4.0（引入 ctx.betterSidebar 注册表服务的版本） |
| Node | >= 20 |
| Profile | 任意带浏览器的 DSH Web profile |

插件只声明一个 peer：@deepseek-ai/cordis@^4.0.0，且标为 optional。它故意不声明 任何 @deepseek-ai/dsh- peer —— 宿主启动预检会评估这些范围，不满足时会静默禁掉整个 profile 行。详见 docs/DESIGN.md §8。

如果没装 dsh-better-sidebar，插件照样加载，只打一条 warn 日志，没有页签可注册而已。

安装

下面的命令逐字引用自 docs/INSTALL.md（owner：packaging）—— 那是这些命令唯一被写下来的地方，每条命令的完整依据也在那里。

cd ~/.dsh && dsh plugin --profile web add "github:xx529/dsh-task-gantt"

然后重启 dsh web，并硬刷新浏览器页面（Cmd+Shift+R）。

状态：[not run]。 xx529/dsh-task-gantt 目前还不存在于 GitHub
（gh repo view xx529/dsh-task-gantt → "Could not resolve to a Repository"），所以这条命令今天无法端到端跑通。它是照一手依据写的，不是凭印象：dsh plugin 把参数原样转发给 pnpm （~/.nvm/versions/node/v22.22.2/lib/node_modules/@deepseek-ai/dsh/lib/bin.js:96），而 github:owner/repo 正是官方文档给 bundle 插件印的形式（docs/INSTALL.md §1.1，同形式已对真实包验证过）。

⚠️ 不要用别名形式安装

… add "dsh-task-gantt@github:xx529/dsh-task-gantt" 也能解析，但包会落在 node_modules/<别名>，而它内部 package.json 的 "name" 仍是 dsh-task-gantt。
profile 的 dsh.profile.bundles 与 Loader row 是按包名记账的，两者不一致会退化成「warn, then skip」。请使用上面的无别名形式（docs/INSTALL.md §1.1）。

可选前置：面板需要有 dsh-better-sidebar 才能注册进去。它被有意地不作为本包的依赖。

cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar

卸载

cd ~/.dsh && dsh plugin --profile web remove dsh-task-gantt

之后重启 dsh web。

⚠️ remove 不会改 patch 层。 卸载只删依赖，不会移除 cordis.patch.yml 里手工添加的 insert 行。本插件的 row 来自它自己的 bundle patch（dsh.bundle.patch → cordis.patch.yml），随包一起走，所以理论上不留残渣 —— 但如果你曾手工往 ~/.dsh/profiles/web/cordis.patch.yml 加过 - insert: - id: dsh-task-gantt，那一行也要删掉（docs/INSTALL.md §5）。

使用

打开面板

1. 打开一个存在 agent team 的会话（有 teammate，或至少有一个共享任务）。
2. 打开右侧栏，点 +。
3. 选择页签：
- 中文界面：任务甘特图
- 英文界面：Task Gantt

页签声明为 single: true —— 官方文档里的单实例语法糖（single: true ≡
dedupeKey: () => id）：再次打开会聚焦已有页签，而不是叠出第二个。如果你在菜单里看不到
说明文字，那是宿主侧的规则，不是插件的问题 —— 宿主只在新页签列表不超过 4 条时才渲染说明。

怎么看这张图

| 元素 | 含义 |
| 泳道头 | 一位名单成员：名字、角色、状态点 |
| 浅色带 | 一整个 turn（turn/start … 结算） |
| 深色条 | turn 内的一个 model step（step/start … step/end） |
| 开口条 | 该区间尚未闭合，右端延伸到「现在」 |
| 竖线 | 当前真实时间 |
| 任务卡 | 一个共享任务，按它被记录下来的时间定位 |
| 带实时标记的任务卡 | 该任务没有可考的时间记录，位置是当前状态，不是历史区间 |

悬停或键盘聚焦任务卡可以看到完整 subject、description、blockedBy、 writeScopes，以及是否 ready。整张图由真实 DOM 元素构成（不用 canvas），文字可选、读屏可达。

降级态

面板永远会告诉你这张时间轴是怎么拼出来的。响应里的 source 只有三种取值：

| source | 含义 | 你会看到 |
| log | 区间来自可读的持久化会话日志 —— 权威 | 完整时间轴 |
| partial | 部分泳道的日志读不到 | 能读的泳道照画，读不到的降级，并给出说明 |
| live | 没有任何日志可读，只有投影 | 只画当前状态，明确标注，并给出说明 |

另外两种状态也值得知道：

- 当前会话没有 agent team —— 空态，暂时没有东西可画。
- 任务板提前中止 —— 显示 Lead 的持久化失败原因（banner）。

任何降级态下，插件都不会发明时间戳。没有历史记录的任务画在当前位置并标为实时态，这是有意为之。

工作原理

这张图由两个数据源拼成，缺任何一个都画不出来：

1. agentTeam 会话投影（浏览器侧）权威地回答「有什么、现在是什么状态」——名单、phase，以及共享任务的 status、owner、依赖与写入范围。它完全没有时间戳：成员记录和任务记录里都没有 createdAt / startedAt / completedAt。它能告诉你某个任务 completed，但永远无法告诉你什么时候完成的。
2. 持久化会话事件日志（host 侧，Lead 与每个 teammate 各一份）是唯一权威的时钟。
每条事件带 time（epoch 毫秒）与 seq。host 半读取日志，把它们折叠成活动区间与带时间的任务迁移。

host 半把折叠结果通过一个很小的只读 JSON API 暴露出来（POST /dsh-task-gantt/api/timeline），浏览器半负责渲染。浏览器自己读不了会话日志，这就是这个拆分存在的原因。

任务时间从哪里来

任务状态迁移原则上可能不在日志里留痕，所以插件按顺序尝试三级，取到就停：

1. 日志里有任务相关事件（team/task）→ 直接用它的 time；
2. 否则扫 tool/call，命中共享任务板工具（team_task_create / team_task_update） → 用该次调用的 time，并用它的 expected_revision 把这次变更归属到真正动手的 teammate；
3. 都没有 → history 保持为空，任务按实时态绘制。

第 1 级是常态，而且是实测过的。 team/task 事件写进 Lead 自己的会话日志并立即 flush，所以看板刚动过就能读到；六个 teammate 的日志里这类事件是 0 条（docs/FINDINGS-host.md §1、§4.1–4.2）。第 2 级保留作兜底与归属通道，因为 team/task 只带完整任务快照、没有 action 字段 —— action 必须由 revision 连续性与 status 迁移推导（docs/FINDINGS-host.md §4.4）。

第 3 级是真实存在的结果，不是 bug。详见 docs/DESIGN.md §3。

配置项

没有。插件只注册一个页签和一个 HTTP 路由前缀，没有设置界面、没有配置文件、没有环境变量。

常见问题

它会改我的任务吗？ 不会。插件只读，从不调用任务的创建/更新服务。它注册的 HTTP 路由只有同源的 POST …/timeline 与 POST …/ping。

某个显然跑过的任务为什么没有条？ 因为它的状态迁移没有被任何可读的会话日志记录下来（上面的第 3 级）。任务仍会画在当前位置并标为实时态，而不是被放到一个猜出来的时间点上。

为什么页签没出现？ 要么这个 profile 没有挂载 dsh-better-sidebar，要么插件行没有生效。确认插件出现在 profile 的 dsh.profile.bundles 里，然后重启 dsh web。

没有 agent team 的 profile 能用吗？ 能，会显示空态。插件用 ctx.get(...) 探测它需要的每个服务，不依赖 agent-team 层即可激活。

换皮肤还能用吗？ 应该能。面板只消费 DSH 主题令牌（--dsw-alias-、--dsw-font-、--ds-），零颜色字面量，并且有测试守着。

开发

pnpm install
pnpm run typecheck # tsc --noEmit，必须 0 error
pnpm run test # vitest
pnpm run build # 产出 lib/index.js（host 半）+ lib/client.js（浏览器半）

lib/ 是故意提交进仓库的：插件从 GitHub 直装、没有构建步骤，所以发布产物必须在仓库里 —— CI 也会检查它是否是最新的。

想用本地检出直接挂到 profile（而不是装一份拷贝），逐字引用自 docs/INSTALL.md §1.2：

cd ~/.dsh && dsh plugin --profile web add "link:/Users/lzx/Documents/GitHub/dsh-task-gantt"

设计文档与数据源取舍：docs/DESIGN.md。
上架材料：docs/MARKET.md。
已经实际验证过的内容：docs/VALIDATION.md。

许可

MIT —— 见 LICENSE。