团队进度面板 ucfjoe/dsh-team-progress

dsh-team-progress

DeepSeek Harness 的 GUI 插件，展示运行中智能体团队的四个视图，数据从持久状态统计得出：谁在做什么、跟踪了哪些缺陷、目标推进到哪一步、现在有什么需要人来处理。读不到的来源会渲染成 unavailable 并附上原因，而不是 0。

宿主侧（lib/index.js）在 webServer 服务上注册一条回环 JSON 路由 POST /api/team-progress/rpc；客户端侧（lib/client.js）向插槽服务注册面板，面板打开期间每 5 秒重新读取该路由。

面板

STALLED task task-5 owner beta is inactive ← 4. act now, FIRST
BLOCKED task task-6 waiting on task-4

3/6 tasks · 2/3 members ← headline ▓▓▓▓▓▓▓░░░▓

MEMBERS 4 ← 1. who is on what
member status claimed task task status
lead running task task-6 pending
alpha running task task-4 in progress
beta inactive task task-5 in progress STALLED
gamma running no claimed task

DEFECTS 10 fixed · 5 in flight · 4 open (19) ← 2. tracked defects #2 Repo→app mapping is dead code. #17 False CRITICAL. +2 more open

GOAL round 7/256 · active · armed ← 3. goal progress Extend dsh-team-progress with the four views

conversation.view id "team-progress", order 30 a "Team progress" session tab
POST /api/team-progress/rpc { method: "state" } the payload

面板是一个 conversation.view 标签页，绑定到打开它时所在的会话。lib/client.js 里 mount() 处的注册代码决定了渲染什么：它只注册这个标签页，别的都不注册。

新增了什么

- MEMBERS —— 每个成员一行：实时状态、它认领的共享任务、该任务的状态。没持有任务的成员渲染为 no claimed task。
- DEFECTS —— 按状态统计各缺陷日志的数量，外加仍未关闭的条目。可识别的状态：open / in flight / fixed / closed as superseded；其他一律计入 other，显示为 unclassified。
- GOAL —— 已开始的轮次与上限、阶段，以及 armed / disarmed。
- STALLED / BLOCKED —— 行动列表，排在最前面渲染，因为停滞是唯一需要人做决定的状态。
- 一条 RPC 路由 —— POST /api/team-progress/rpc，方法 state 和 act。
- 一个可选的操作面 —— 完成 / 重新打开 / 认领 / 释放 / 重新指派、唤醒、中断、派生、自动指派、广播、成员上限，全部走模型自己的工具所调用的同一批领域方法。默认关闭；见 安全。

要求

读取路径针对 DeepSeek Harness 0.2.1-rc.3（2026-10-24）追踪验证，插件最后一次端到端跑通是在 0.2.1-rc.5（2026-11-03）：带 {"method":"state"} 的 POST /api/team-progress/rpc 返回 200 和实时数据。未声明最低版本。
- 客户端部分声明给 web 平台（dsh.client.platform）。它属于浏览器侧代码，所以在 Node 里导入 dsh-team-progress/client 会报 window is not defined —— 这是运行环境决定的，不是缺陷。
- 只有 webServer 是硬注入。agents、agentTeams、sessionProjections、goals、sessionQuery 和 uiWorkspace 都按需解析，所以即使某个配置档禁用了其中某个 bundle，面板仍能加载，并报告来源。

安装

本地未发布的插件包（"private": true）：package.json 声明了 dsh.bundle.patch（./cordis.patch.yml）和客户端 bundle（./lib/client.js，平台 web）。

cordis.patch.yml 只带一行，没有配置：

- insert:
- id: team-progress
name: 'dsh-team-progress'

这个文件不会启用插件。 它是 bundle 自带的补丁，只有在某处启用 bundle 之后才会生效；启用属于配置档变更，会影响每个会话，所以留给配置档所有者决定。

要启用它，分三步。

1. 克隆仓库，让配置档能解析到这个包。 配置档从自己的 package.json 解析插件包，所以把检出目录加为 link: 依赖，再跑配置档的安装（配置档目录自带 pnpm-workspace.yaml）：

git clone https://github.com/ucfjoe/dsh-team-progress.git ~/dsh-team-progress

PROFILE=~/.dsh/profiles/desktop # the profile you run
in "$PROFILE/package.json":
"dependencies": { …, "dsh-team-progress": "link:$HOME/dsh-team-progress" }
cd "$PROFILE" && pnpm install
ls -l node_modules/dsh-team-progress # expect a symlink to the checkout

这一步在全新克隆上跑过，环境是 pnpm 11.22.0 / Node v26.7.0：符号链接出现，import('dsh-team-progress') 能解析到宿主部分（apply、inject、name），克隆目录里 npm test 通过。

2. 把这一行加到配置档的 cordis.patch.yml。

- id: team-progress
name: 'dsh-team-progress'
config:
defectLogs:
- ~/repos/your-project/docs/defects.md
allowMutations: false

上面那种 - insert: 包裹写法也接受。defectLogs 条目里的 ~ 会展开，空条目忽略。

3. 重新加载。 改完宿主部分后，只改文件不够 —— 模块是应用进程内的 ESM，要重新加载插件（先禁用再启用）才能重新导入并重建客户端 bundle。记录在开发日志里。

配置

每个键都可选；下面的默认值就是 lib/index.js 实际采用的。

| 键 | 默认值 | 作用 |
| defectLogs | [] | markdown 缺陷日志的路径，绝对路径或 ~/…。空是出厂默认，此时缺陷视图报告 unavailable: no defect-log paths are configured。只从配置读取，绝不从请求体读取。 |
| allowMutations | false | 启用 act 方法。关闭时 act 返回 403 TEAM_PROGRESS_ACTIONS_DISABLED；所有视图照常工作。 |
| actionPolicy | 'all' | 在 allowMutations 打开后，收窄可触达的操作范围。'read-write' 会扣下两个在点击之后仍有后续影响的操作 —— spawn（创建智能体）和 member-limit（改写磁盘上的配置文件）—— 返回 403 TEAM_PROGRESS_ACTION_WITHHELD，且不触达任何领域方法。面板上的操作仍全部可执行。值缺失或无法识别时按 'all' 处理，因此已有配置档保持不变；响应负载的 actions.policy 始终给出实际生效的值。 |
| spawnFreshProvider | 'spawn' | fresh 上下文派生时传给 spawnTeammate 的服务商名。 |
| spawnForkProvider | 'fork' | fork 上下文派生时传给 spawnTeammate 的服务商名。 |
| aliasFile | ~/.dsh/team-progress/aliases.json | 面板自有的显示别名、一句话用途和隐藏标记的 JSON 存储，每个成员一条，键为 leadId\|memberId。 |
| homePatchFile | ~/.dsh/cordis.patch.yml | member-limit 操作改写的补丁层，改写时会在旁边写一份带时间戳的备份。 |

缺陷日志格式

解析器读取 markdown 表格。表头行含 Status 列，且另有一列匹配 Defect / Issue / Problem / Bug，紧接着是分隔行，这样的表格才算数：

| # | Defect | Evidence | Status |
| 2 | Repo→app mapping is dead code. | investigate.py:319-321 | open |
| 17 | False CRITICAL. | run.log | fixed #222 — merged |

- 状态单元格解析为 open、in flight（或 in-flight）、fixed 或 closed as superseded。单元格在第一个 , ; : — – ( # 或 - 处截断，所以尾部的引用（fixed #222 — merged）不改变状态；bold 短语从强调标记内部读取。
- 这四种之外的状态计为 other，不丢弃也不猜测，因此新写法会以 unclassified 出现，而不是消失。
- 转义的 \| 不拆分单元格。空行不结束表格，只要下一个非空行仍是数据行；标题、分隔行、新表头或正文才会结束表格。章节标题会带到每一行上。
- 计数为 fixed / inFlight / open / superseded / other / total。open 行最多 50 条，余数放在 openTruncated 里；超过 4 MiB 的文件拒绝读取，单张表最多 5000 行。

安全：操作面

POST /api/team-progress/rpc 直接注册在 web 服务器上，绕过了应用自身的鉴权中间件。 一旦 allowMutations: true，任何本地进程 —— 机器上的任何脚本、任何工具、任何智能体 —— 都能通过这条路由驱动团队面板：完成、重开、认领或改派共享任务，唤醒不活跃成员，打断运行中的智能体，派生队友，向整个团队广播。
- 出厂默认是关闭（allowMutations: false）。
- 关闭时，act 返回 403 TEAM_PROGRESS_ACTIONS_DISABLED，不会触达任何领域方法。读视图、计数和读路径照常工作，不受影响。
- 要在单用户机器上主动开启，并把这条路由当作本地控制套接字，而不是带认证的 API。
- actionPolicy: 'read-write' 能在不关闭的前提下进一步收窄：spawn 和 member-limit 返回 403 TEAM_PROGRESS_ACTION_WITHHELD，而所有看板操作照常工作。这两个动作的影响会超出点击本身——一个会创建带模型预算的活跃智能体，另一个会改写磁盘上的配置文件。收窄是可选开启的，所以现有配置档已有的取值（'all'）仍是默认，不会被重新解释。

defectLogs 里的路径只来自配置，绝不来自请求，因此这条路由无法变成任意文件读取器。请求体上限 64 KiB。

载荷 / RPC 契约

路径固定，no-store。

两个方法：state 接收 { sessionId? }，返回下面的快照；act 接收 { leadId, action, … }，返回回执，或带领域 code 的拒绝。

输入处理：非 POST → 405；请求体超过 64 KiB → 413；JSON 无效、JSON 不是对象，或 method 缺失 / 为空 / 不是字符串 → 400；方法未注册（包括 constructor、__proto__、toString）→ 404；变更关闭时调用 act → 403 TEAM_PROGRESS_ACTIONS_DISABLED。

{
"ok": true,
"generatedAt": "2026-10-30T11:02:50.000Z", // ISO, host clock at read time
"summary": { "total": 6, "completed": 3, "inProgress": 2, "pendingReady": 0,
"blocked": 1, "stalled": 1, "members": { "live": 2, "total": 3 } },
"teams": [ /* one card per lead: label, summary, roster, lanes, goal, lineage / ],
"roster": { "state": "ok", "leads": 1, "stalled": 1, "members": [ / rows / ] },
"defects": {
"state": "ok", // ok | partial | unavailable
"files": [{ "path": "…", "state": "ok", "rows": 19 }],
"counts": { "fixed": 10, "inFlight": 5, "open": 4, "superseded": 0,
"other": 0, "total": 19 },
"open": [ / rows / ], "openShown": 1, "openTruncated": 3
},
"goal": { "state": "ok", "goals": [ / roundsStarted, maxGoalRounds, phase */ ] },
"waitingOnYou": { "state": "ok", "total": 3, "stalled": 1, "unassigned": 2, "idle": 0 },
"attention": [ { "kind": "stalled", "label": "task-5", "detail": "owner beta is inactive" } ],
"actions": { "enabled": false, "policy": "all" },
"degraded": { "any": false, "reasons": [] }
}

诚实规则

- null 永远不是 0。 读不到的计数是 null，视图会说明原因。每个可读快照都满足 completed + inProgress + pendingReady + blocked === total。
- 数据源缺失不等于零。 每个视图都带自己的 state（ok / partial / none / unavailable），状态不是 ok 时还会给出原因。缺陷日志缺失时是 unavailable，counts: null；一份日志可读、另一份缺失时是 partial，给出真实计数并点名缺失的文件。none（「没有目标」）和 unavailable（「我没能查看」）是两种不同的回答，渲染方式也不同。
- 故意做成三值。 读不到实时状态时，stalled 取 true、false 或 null；null 不画徽标，而不是声称「未停滞」。
- degraded 的范围很窄。 它只覆盖看板和团队的读取，所以缺陷文件缺失时在原位说明自己，不会让可读的任务看板显得降级。
- 不做任何估算。 没有 ETA，没有百分比，没有已用时长。

测试

运行 npm test。两套测试都通过；它们是在 Node v26.7.0 上跑的。

- test/verify.mjs —— 通过 React shim 渲染真实的客户端 bundle，断言每个视图，包括每一种缺失：关注项按文档顺序排在最前，STALLED 徽标只出现在状态已知的地方，任何地方都没有凭空编造的 0。
- test/verify-host.mjs —— 用 fixture 看板驱动宿主端，断言 payload、读取路径（每个 lead 调用一次 tryMembership，零次 agents.get() 调用）、RPC 状态码，以及请求无法重定向缺陷日志路径。

设计说明

- 成员自己持有的任务优先于它被创建时的描述。 描述在创建时就固定了，会随工作推进而失真；成员持有的任务才是「它在做什么」的可靠答案。
- provisioning 不是停滞。 组建队友是正常的启动状态。只有持有进行中工作时处于 inactive 或 failed 才算，状态未知时给出 null 而不是 false。
- 读取器抛错时必须渲染 unavailable，绝不能渲染成「没有目标」。 目标服务的 get() 对不是注册表实时实例的智能体会抛错，所以每次调用都包了一层：把「没能查看」和「没有」混为一谈，会在读取失败时报成功。
- 读不到的数据源不是零。 缺失的文件、未注册的服务、读不了的看板，各自在自己的字段里说明，因为编造的 0 读起来像事实。
- 让面板能动手的开关默认关闭。 只读面板在任何配置档上都安全；能唤醒智能体、移动共享看板的路由，得由所有者明确决定。

许可证

MIT —— 见 LICENSE 和 package.json 里的 license 字段。