taskboard-workbench 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +132 -0
- package/LICENSE +21 -0
- package/README.md +121 -2
- package/cli/tb.mjs +314 -0
- package/cordis.patch.yml +5 -0
- package/index.js +633 -0
- package/lib/client.js +522 -0
- package/package.json +83 -4
- package/spec//345/233/242/351/230/237agent.md +171 -0
- package/src/core/advance.mjs +192 -0
- package/src/core/agent-teams.mjs +48 -0
- package/src/core/binding.mjs +44 -0
- package/src/core/config.mjs +22 -0
- package/src/core/debug-dispatch.mjs +94 -0
- package/src/core/delivery.mjs +93 -0
- package/src/core/deps.mjs +53 -0
- package/src/core/diagnostics.mjs +648 -0
- package/src/core/domain.mjs +235 -0
- package/src/core/empty-state.mjs +240 -0
- package/src/core/errors.mjs +139 -0
- package/src/core/executor.mjs +645 -0
- package/src/core/human-review.mjs +773 -0
- package/src/core/intake.mjs +116 -0
- package/src/core/kickoff.mjs +147 -0
- package/src/core/loop.mjs +498 -0
- package/src/core/memory.mjs +193 -0
- package/src/core/next-step.mjs +377 -0
- package/src/core/notify.mjs +183 -0
- package/src/core/owner.mjs +41 -0
- package/src/core/requirements.mjs +262 -0
- package/src/core/review.mjs +82 -0
- package/src/core/session-naming.mjs +64 -0
- package/src/core/split-ask.mjs +107 -0
- package/src/core/store.mjs +3103 -0
- package/src/core/team.mjs +170 -0
- package/src/core/verify.mjs +170 -0
- package/src/core/watchdog.mjs +144 -0
- package/src/host/ai-elaborator.mjs +26 -0
- package/src/host/team-engine.mjs +125 -0
- package/src/host/tool-surface.mjs +205 -0
- package/src/server/api.mjs +1974 -0
- package/src/server/events.mjs +32 -0
- package/src/server/kickoff.mjs +46 -0
- package/src/server/server.mjs +211 -0
- package/src/server/verify.mjs +112 -0
- package/tools/env-check.mjs +35 -0
- package/tools/seed.mjs +67 -0
- package/web/app.js +5237 -0
- package/web/index.html +15 -0
- package/web/tokens.css +1139 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
`taskboard-workbench` 的全部对外版本变更记录。
|
|
4
|
+
|
|
5
|
+
格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
|
|
6
|
+
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
|
|
7
|
+
每个版本对应一个 annotated tag(`vX.Y.Z`)与一条 GitHub Release;npm dist-tag 与 dsh 兼容区间随版本记录。
|
|
8
|
+
|
|
9
|
+
## [0.2.0] - 2026-10-29
|
|
10
|
+
|
|
11
|
+
> **本版是首个发布到 npm 的版本** —— `0.1.0` 只出过 GitHub Release 源码快照,未进 registry。
|
|
12
|
+
> 覆盖 2026-10-23 → 2026-10-29 的全部工作(需求正本 `FR-01…FR-100`,实现缺口 0)。
|
|
13
|
+
|
|
14
|
+
### 新增
|
|
15
|
+
|
|
16
|
+
- **项目推进清单与决策回写(`FR-99`)** —— `GET /api/projects/:id/advance` 把五类待办
|
|
17
|
+
(`decide` / `blocked` / `review` / `accept` / `dispatch`)按「先解锁再推进」合一排序,每条带一句 `why` 与稳定
|
|
18
|
+
`decision_id`;清单是**纯投影**(同状态重复请求字节级一致,`done`/`canceled` 不出现);`?format=block` 产出
|
|
19
|
+
可直接投给项目主会话的指令装载块,`POST …/advance/announce` 投放,`POST …/advance/:decisionId/decide` **幂等**回写。
|
|
20
|
+
- **项目记忆与多 agent 执行记忆归档(`FR-100`)** —— 三张记忆表 + 五个端点:按项目 / 会话 / agent 归档执行记忆,
|
|
21
|
+
支持检索、合成装载与清理。
|
|
22
|
+
- **需求分拆「自动生成 + 按意见重生成」** —— `POST /api/requirements/items/:ref/split-ask` 走项目主会话,
|
|
23
|
+
**只投一条指令、零建卡零改状态**(因此可安全反复点);带修改意见时自动回带上一次草稿。
|
|
24
|
+
生成的卡支持 `kind`(`work` / `review`,未知值报错而非静默丢弃)与**依赖边**(`序号|标题|owner|kind|依赖`)。
|
|
25
|
+
- **评审门** —— `in_review → done` 必须 `review_state === 'approved'`,否则 `REVIEW_NOT_APPROVED`(退出码 5;
|
|
26
|
+
门在写之前 ⇒ 零副作用)。人仍可跳过评审,但须显式 `skipReview === true`(严格布尔),服务端落
|
|
27
|
+
`review_skipped` 事件与审计。
|
|
28
|
+
- **宿主能力位与能力门** —— `GET /api/health` 的 `host` 块补齐 8 个能力位(`createSession` / `sendPrompt` /
|
|
29
|
+
`openSession` / `listSessions` / `sessionExists` / `sessionOrigin` / `renameSession` / `sessionState`);
|
|
30
|
+
前端按能力位置灰宿主依赖按钮并给常驻说明,**能力未知时不擅自禁用**;`host-unavailable` 的错误**同时回带
|
|
31
|
+
`prompt`**,可手工投递。
|
|
32
|
+
- **需求条目「任务 DAG」** —— 稳定拓扑序(Kahn,同层按创建序)+ 每节点 `blockedBy[]` + 依赖边 `reason`
|
|
33
|
+
(为什么卡)+ 节点可点直达该卡(按编号回源 `GET /api/tasks/:ref`,不再"列表里没有就归档了")。
|
|
34
|
+
- **需求条目详情抽屉** —— 按视口分级宽度 + 左缘拖拽 + 一键全屏,独立记忆键 `tb.reqDrawer.width`
|
|
35
|
+
(不与被任务侧共用的 `tb.drawer.width` 串扰),拖动中不落盘、松手才写。
|
|
36
|
+
- **需求条目列表** —— 完成度结论列(`无任务` / `可收口` / `待验收 N` / `受阻 N` / `N/M 收口` 五档,定宽对齐)+
|
|
37
|
+
面板头「可收口 N」+ 点胶囊真滚到详情「关联任务完成情况」段 + 终态显式化(划掉 + 色条 + 降透明)。
|
|
38
|
+
- **自动复核第三态「不适用」** —— 非 Node 工作区不再把「命令不适用」谎报成「失败」(`applicable:false`,
|
|
39
|
+
不跑命令、不改状态)。
|
|
40
|
+
- **发布门禁** —— `node tools/release-precheck.mjs`:tracked tree + `HEAD` 全历史的 L1/L2 敏感信息扫描、
|
|
41
|
+
`npm pack` 内容边界、`docs/`/`.archify/`/`.data/`/`AGENTS.md` 的 ignore 覆盖;配套 `SECURITY.md` 分级口径。
|
|
42
|
+
- **13 个隔离验证台**(`tools/bench-*.mjs`)—— 临时 `dataDir` + 随机端口 + 独立进程,跑真 headless Chrome /
|
|
43
|
+
真 `dsh` / 真 `claude` 取证,**每个都带反向对照**(注入旧口径必须转红)。
|
|
44
|
+
|
|
45
|
+
### 变更
|
|
46
|
+
|
|
47
|
+
- **建卡归因并入建卡事务** —— `createTask` 在同一事务内校验 `requirementId`,跨项目/条目不存在 ⇒ **整笔回滚、
|
|
48
|
+
不占编号**;`POST /api/tasks` 读 `requirementId`;CLI 增 `task create --requirement` 与 `task attribution`。
|
|
49
|
+
默认**软提醒**,`TB_STRICT_ATTRIBUTION=1` 才升级为硬门。归因门(`EXECUTION_NOT_ATTRIBUTED`)保持不变。
|
|
50
|
+
- **需求视图「引入的文件」按文件夹呈现**(`FR-96`)—— 单链合并、目录排在根级文件之前、叶子 `title` 不丢、
|
|
51
|
+
默认折叠。
|
|
52
|
+
- **待验收卡处置入口收敛**(`FR-89`)—— 已通过卡只保留「完成」一处,操作区不再出现裸「下一列」,
|
|
53
|
+
改为「指回下一步」;进行中卡仍保留普通「下一列」(反向对照守住)。
|
|
54
|
+
- **`web/app.js` 支持两种宿主形态** —— 宿主能力未知 / 宿主不可用都按「能力位 + 常驻提示」呈现,
|
|
55
|
+
不再把**能力缺失**呈现为**临时故障**(旧文案「检查宿主会话通道后重试」会让人无限重试一个永不成立的条件)。
|
|
56
|
+
|
|
57
|
+
### 修复
|
|
58
|
+
|
|
59
|
+
- **断线无提示、重连后不重取**(`FR-20`)—— WebSocket 断开给常驻提示并按 `readyState` 分流,
|
|
60
|
+
重连成功后复用 `reload()` 重新取数(验证台 11/11,含反向对照)。
|
|
61
|
+
- **「申报人工校验」点了没反应** —— 抽屉内提示被 `.banner` 遮挡(z-index 40 → 60)。
|
|
62
|
+
- **需求条目详情「太过靠右」** —— `.tb-req-drawer` 死钉 `min(560px, …)`,与 `.tb-drawer` **特异性相同又排在
|
|
63
|
+
后面** ⇒ 盖掉按视口分级与拖拽/全屏(同一个抽屉壳:任务侧有能力、需求侧被一行旧 CSS 钉死)。
|
|
64
|
+
- **建卡可绕过归因** —— Web / CLI / 工具面三个入口原先都拿不到 `requirementId` ⇒ 派生出无归因卡,
|
|
65
|
+
启动执行与派发团队时被 `EXECUTION_NOT_ATTRIBUTED` 拒。
|
|
66
|
+
- **CLI 失败被记成「成功」的相邻问题** —— 失败记账与分类重做:配额/鉴权类(不重试,置受阻 + 审计)与
|
|
67
|
+
瞬时故障(按阈值重试)分流。
|
|
68
|
+
- **需求分拆的两处「界面承诺 ≠ 实现」** —— `kind` 被 `assertSplitTasks` 静默丢弃;按钮写「+ 依赖」而 UI
|
|
69
|
+
根本没有依赖输入(一条边都建不出来)。
|
|
70
|
+
- **DAG 节点点不开** —— 纯展示 `div` 改可点 `button`,并修掉「列表里查不到就提示可能已归档」的死路。
|
|
71
|
+
- **`node --test` 临时目录泄漏** —— 跑完残留临时目录。
|
|
72
|
+
- **优雅重启永远不退出(留孤儿)** —— `server.close(cb)` 只停止接受新连接、要等既有连接全部结束才回调;
|
|
73
|
+
而前端常开 `new EventSource('/api/events')`(SSE 长连接),**回调永不触发** ⇒ SIGTERM 之后进程挂着不退、
|
|
74
|
+
继续持有 `.data/taskboard.sqlite`,下一个实例起来就形成**同库双写者**,再下次重启还要撞 `EADDRINUSE`。
|
|
75
|
+
修:`server.closeAllConnections?.()` 强制断开 SSE / keep-alive + **3 s 兜底 `process.exit(0)`**;
|
|
76
|
+
守卫 `tests/server-graceful-shutdown.test.mjs`(3 条:挂 SSE 必须秒退 / 无连接也要退 / 源码双要素)。
|
|
77
|
+
|
|
78
|
+
### 测试
|
|
79
|
+
|
|
80
|
+
- `npm test`(`node --test`)**853 / 853 · 0 fail · 0 skipped**(`0.1.0` 时为 678)。
|
|
81
|
+
- 13 个浏览器 / 真进程验证台全部带**反向对照**,且全部在 `npm test` 内(不是游离脚本)。
|
|
82
|
+
|
|
83
|
+
### 已知限制
|
|
84
|
+
|
|
85
|
+
- 执行侧外部 CLI(如 `claude`)**没有强制的文件写入边界**:`--add-dir` 只表达授权目录,**不阻止越界写**,
|
|
86
|
+
且 `--allowedTools` 含 `Bash` ⇒ shell 重定向不受目录模型约束。该约束是**指令级**的
|
|
87
|
+
(实证:`tools/bench-cli-write-boundary.mjs`)。
|
|
88
|
+
- **独立进程形态**(`node src/server/server.mjs` 直起、非 DSH 插件)**天生没有宿主会话通道**,
|
|
89
|
+
`/api/health` 的 `host.capabilities` 为 `null`。此时宿主依赖动作按能力位置灰并给出说明,
|
|
90
|
+
`host-unavailable` 会回带 `prompt` 供手工投递。这属**形态差异**,不是缺陷。
|
|
91
|
+
- `docs/` 过程文档不随仓库与包发布,只在本地维护。
|
|
92
|
+
|
|
93
|
+
### 口径裁定
|
|
94
|
+
|
|
95
|
+
- **`FR-52` 验收②** 的「外部 CLI 配额不足 ⇒ 回退为成员自行执行并注明原因」**裁定为以实装为准**
|
|
96
|
+
(命中配额/鉴权类错误 ⇒ 熔断置「受阻」+ 停止自动重试 + 审计 + 明确原因)。理由:key 失效时让每个成员
|
|
97
|
+
各回退一次只会把一次明确故障放大成 N 次,且会掩盖真实故障。条款原文保留,裁决记录见
|
|
98
|
+
`docs/需求文档.md` 文末变更记录 2026-10-29 条。
|
|
99
|
+
|
|
100
|
+
[0.2.0]: https://github.com/SilenZerOrz/taskboard-workbench/releases/tag/v0.2.0
|
|
101
|
+
|
|
102
|
+
## [0.1.0] - 2026-10-23
|
|
103
|
+
|
|
104
|
+
> ⚠️ **本版未发布到 npm。** 它只对应一次 **GitHub Release** 的源码快照(tag 指向初始化提交),
|
|
105
|
+
> registry 上从未出现过 `taskboard-workbench@0.1.0`。**首个 npm 版本是 `0.2.0`。**
|
|
106
|
+
|
|
107
|
+
**对外首个版本(初始版本)**。此前仓库仅内部私有演进(`private: true`),
|
|
108
|
+
所有历史修改不构成对外语义,故对外发布自 `0.1.0` 起算。
|
|
109
|
+
|
|
110
|
+
### 新增
|
|
111
|
+
|
|
112
|
+
- **本地任务工作台核心**:零运行时依赖(`node:sqlite`)的多项目 / 任务 / 需求条目存储,含状态机、
|
|
113
|
+
认领锁与心跳、失败会计与熔断、诊断与尝试记录 / 事件流。
|
|
114
|
+
- **看板与呈现**:列看板(含列内拖拽排序)、关键词搜索、Markdown 呈现与内容安全、
|
|
115
|
+
需求视图「引入的文件」按文件夹树呈现。
|
|
116
|
+
- **执行与编排**:看板侧 CLI 执行器(`cli:claude`)、派发引擎选择(活跃执行者 / 团队模板回落)、
|
|
117
|
+
执行看护与通知订阅 / 唤醒。
|
|
118
|
+
- **DSH 内嵌插件**:`dsh.bundle.patch` + `dsh.client`(web 平台侧栏 / 布局 / 槽位注入),
|
|
119
|
+
会话内「任务工作台」中心标签页。
|
|
120
|
+
- **CLI**:`tb` 命令(`bin` 暴露)与本地 Web 服务(`npm start`)。
|
|
121
|
+
|
|
122
|
+
### 测试
|
|
123
|
+
|
|
124
|
+
- `npm test`(`node --test`)全量单测全绿。
|
|
125
|
+
|
|
126
|
+
### 已知限制
|
|
127
|
+
|
|
128
|
+
- `docs/` 过程文档不随仓库与包发布,只在本地维护。
|
|
129
|
+
- 执行侧外部 CLI(如 `claude`)**没有强制的文件写入边界**:`--add-dir` 只表达授权目录,
|
|
130
|
+
不阻止越界写;该约束是指令级的。
|
|
131
|
+
|
|
132
|
+
[0.1.0]: https://github.com/SilenZerOrz/taskboard-workbench/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 SilenZerOrz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,122 @@
|
|
|
1
|
-
#
|
|
1
|
+
# taskboard-workbench
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Agent Team 任务工作台**:一个本地优先(local-first)的多项目任务看板,
|
|
4
|
+
> 零运行时依赖(`node:sqlite`),既可独立跑成 **CLI + 本地 Web 服务**,也能作为
|
|
5
|
+
> **DSH(DeepSeek Harness)内嵌插件**挂进会话里,派发任务、回流证据、独立复验。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 它解决什么
|
|
10
|
+
|
|
11
|
+
把「需求条目 → 看板派发 → CLI/agent 实际开发 → 证据回流 → 独立复验 → 人工验收」
|
|
12
|
+
这条闭环固化成可查询的数据与可重放的流程,而不是散落在聊天记录里。
|
|
13
|
+
|
|
14
|
+
- **任务不是聊天**:任务卡有状态机(`backlog → todo → in_progress → in_review → done`)、
|
|
15
|
+
乐观锁(`--if-version`)、认领锁与心跳、失败会计与熔断。
|
|
16
|
+
- **证据留在卡上**:评论、事件流、尝试记录、诊断信息都挂在任务上,可回溯。
|
|
17
|
+
- **人工守住最后一道门**:执行侧只能把卡推到「待验收」,`done` 必须由人确认。
|
|
18
|
+
|
|
19
|
+
## 功能概览
|
|
20
|
+
|
|
21
|
+
| 模块 | 内容 |
|
|
22
|
+
| --- | --- |
|
|
23
|
+
| 存储核心 | 零依赖 SQLite(`node:sqlite`);多项目 / 任务 / 需求条目;状态机、父任务、标签、负责人 |
|
|
24
|
+
| 看板 | 列看板(列内拖拽排序)、关键词搜索、Markdown 呈现与内容安全过滤 |
|
|
25
|
+
| 需求视图 | 需求条目列表化展示(行式列表 + 点击右侧抽屉看详情)、引入文件按文件夹树呈现 |
|
|
26
|
+
| 执行编排 | 看板侧 CLI 执行器(如 `cli:claude`)、派发引擎选择、执行看护、通知订阅与唤醒 |
|
|
27
|
+
| CLI | `tb` 命令(项目 / 任务 / 评论的 CRUD,JSON 输出 + 稳定退出码) |
|
|
28
|
+
| DSH 插件 | `dsh.bundle.patch` + `dsh.client`(web 平台侧栏 / 布局 / 槽位注入),会话内「任务工作台」标签页 |
|
|
29
|
+
|
|
30
|
+
## 安装
|
|
31
|
+
|
|
32
|
+
### 作为 DSH 插件
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
dsh plugin --profile web add taskboard-workbench
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
插件通过 `dsh.bundle.patch`(`cordis.patch.yml`)与 `dsh.client` 注入到宿主;
|
|
39
|
+
需要宿主支持的 `@deepseek-ai/dsh-client-ui-{layout,sidebar,slots}`(已声明为**可选 peer**)。
|
|
40
|
+
|
|
41
|
+
### 从源码
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/SilenZerOrz/taskboard-workbench.git
|
|
45
|
+
cd taskboard-workbench
|
|
46
|
+
dsh plugin --profile web add .
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### 独立跑(不用 DSH)
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm start # 启动本地 Web 服务(默认监听本机端口)
|
|
53
|
+
node cli/tb.mjs project list # 或用 CLI 直接操作
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## 要求
|
|
57
|
+
|
|
58
|
+
| 项 | 值 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| Node.js | `>= 22.5.0`(依赖 `node:sqlite`) |
|
|
61
|
+
| DSH | `0.2.0-rc.2` 线真机验证通过(`0.2.1-alpha.1` 历史走通) |
|
|
62
|
+
| 运行时依赖 | 无(`dependencies` 为空) |
|
|
63
|
+
|
|
64
|
+
## 快速上手(CLI)
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# 数据目录:--data-dir > $TB_DATA_DIR > 系统临时目录
|
|
68
|
+
export TB_DATA_DIR="$HOME/.taskboard-data"
|
|
69
|
+
|
|
70
|
+
node cli/tb.mjs project create --name "示例项目" --id demo
|
|
71
|
+
node cli/tb.mjs task create --project demo --title "跑通一次闭环" --description "验证一下"
|
|
72
|
+
node cli/tb.mjs task list --project demo
|
|
73
|
+
node cli/tb.mjs comment add 1 --body "证据:npm test 全绿"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
CLI 约定:成功 `stdout` 输出 JSON(含 `schemaVersion`),退出码 `0`;
|
|
77
|
+
失败 `stderr` 输出 `{schemaVersion, error:{code,message}}`,退出码 `2/3/4/5`。
|
|
78
|
+
并发编辑用 `--if-version`,版本不符返回 `VERSION_CONFLICT`(退出码 5)而不静默覆盖。
|
|
79
|
+
|
|
80
|
+
## 配置
|
|
81
|
+
|
|
82
|
+
| 环境变量 | 作用 | 默认 |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `TB_DATA_DIR` | SQLite 数据目录 | 系统临时目录(仅适合试跑,正式用请显式指定) |
|
|
85
|
+
|
|
86
|
+
项目级配置(工作区路径、审批策略、执行者选择等)在 Web 看板的「项目设置」里维护。
|
|
87
|
+
|
|
88
|
+
## 目录结构
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
index.js DSH 插件入口(cordis patch 注入点)
|
|
92
|
+
lib/client.js 宿主侧客户端桥
|
|
93
|
+
cordis.patch.yml dsh.bundle.patch
|
|
94
|
+
src/core/ 存储、状态机、团队模板、执行编排、看护
|
|
95
|
+
src/server/ HTTP API 与事件流
|
|
96
|
+
src/host/ 团队引擎与工具面
|
|
97
|
+
web/ 本地 Web 看板(app.js / tokens.css / index.html)
|
|
98
|
+
cli/tb.mjs `tb` 命令行
|
|
99
|
+
spec/团队agent.md 团队契约(随包发布,供工作台里的 agent 读取)
|
|
100
|
+
tests/ `node --test` 单测
|
|
101
|
+
tools/ 开发与验证脚本(不进 npm 包,除 seed/env-check)
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## 测试
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
npm test # node --test,全量单测
|
|
108
|
+
node --check index.js # 语法自检(对每个源文件)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## 版本
|
|
112
|
+
|
|
113
|
+
见 [CHANGELOG.md](./CHANGELOG.md)。对外首个版本为 `0.1.0`。
|
|
114
|
+
|
|
115
|
+
## 说明:`docs/` 不随仓库发布
|
|
116
|
+
|
|
117
|
+
本仓库的过程文档(需求 / 计划 / 进度 / 验证 / 规范 / 发布 SOP 等)在本地维护,
|
|
118
|
+
**不进入 git 与 npm 包**(见 `.gitignore`)。仓库只发布可运行的代码与随包契约 `spec/`。
|
|
119
|
+
|
|
120
|
+
## License
|
|
121
|
+
|
|
122
|
+
[MIT](./LICENSE)
|
package/cli/tb.mjs
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* tb —— 命令行接口(零依赖)。成功=stdout JSON(含 schemaVersion),退出码 0;
|
|
4
|
+
* 失败=stderr JSON `{schemaVersion,error:{code,message,details?}}`,退出码 2/3/4/5。
|
|
5
|
+
* 数据目录:--data-dir > TB_DATA_DIR > 系统临时目录。
|
|
6
|
+
*/
|
|
7
|
+
import { readFileSync } from "node:fs";
|
|
8
|
+
import { pathToFileURL } from "node:url";
|
|
9
|
+
|
|
10
|
+
import { EXIT, TbError, toErrorPayload, usageError } from "../src/core/errors.mjs";
|
|
11
|
+
import { openStore } from "../src/core/store.mjs";
|
|
12
|
+
|
|
13
|
+
export const CLI_SCHEMA_VERSION = 2;
|
|
14
|
+
|
|
15
|
+
const GLOBAL_OPTIONS = new Set(["data-dir", "json", "help", "enforce-governance"]);
|
|
16
|
+
const BOOLEAN_OPTIONS = new Set(["json", "help", "enforce-governance", "clear-parent", "clear-labels", "clear-owner", "top-level"]);
|
|
17
|
+
|
|
18
|
+
const COMMAND_OPTIONS = new Map([
|
|
19
|
+
["project create", new Set(["name", "id", "workspace-path"])],
|
|
20
|
+
["project list", new Set()],
|
|
21
|
+
["project get", new Set()],
|
|
22
|
+
["task create", new Set(["project", "title", "description", "description-file", "status", "priority", "labels", "owner", "parent", "actor", "requirement", "unattributed-reason"])],
|
|
23
|
+
["task get", new Set()],
|
|
24
|
+
["task list", new Set(["project", "status", "priority", "label", "labels", "owner", "parent", "top-level", "sort"])],
|
|
25
|
+
["task update", new Set(["if-version", "title", "description", "description-file", "status", "priority", "labels", "add-labels", "remove-labels", "clear-labels", "owner", "clear-owner", "parent", "clear-parent", "actor"])],
|
|
26
|
+
["task delete", new Set(["if-version"])],
|
|
27
|
+
// P0:CLI 原先**完全没有**归因子命令(全文件 0 处 attribution)⇒ 出问题只能手打 HTTP。
|
|
28
|
+
["task attribution", new Set(["requirement"])],
|
|
29
|
+
["comment add", new Set(["body", "body-file"])],
|
|
30
|
+
["comment list", new Set()],
|
|
31
|
+
["comment edit", new Set(["if-version", "body", "body-file", "actor"])],
|
|
32
|
+
["comment history", new Set()],
|
|
33
|
+
]);
|
|
34
|
+
|
|
35
|
+
export const USAGE = `tb —— 多项目任务工作台 CLI
|
|
36
|
+
|
|
37
|
+
用法:tb <资源> <动作> [参数...] [--data-dir <path>]
|
|
38
|
+
|
|
39
|
+
项目
|
|
40
|
+
tb project create --name <名称> [--id <id>] [--workspace-path <路径>]
|
|
41
|
+
tb project list
|
|
42
|
+
tb project get <项目id>
|
|
43
|
+
|
|
44
|
+
任务
|
|
45
|
+
tb task create --project <项目id> --title <标题> [--requirement <条目>|--unattributed-reason <理由>]
|
|
46
|
+
[--description <md>|--description-file <文件>]
|
|
47
|
+
[--status backlog|todo|in_progress|in_review|done|blocked|canceled]
|
|
48
|
+
[--priority none|low|medium|high|urgent]
|
|
49
|
+
[--labels a,b] [--owner <负责人>] [--parent <编号|id>] [--actor human|agent]
|
|
50
|
+
tb task get <编号|id>
|
|
51
|
+
tb task list [--project <id>] [--status <s>] [--priority <p>] [--label <l>]... [--owner <负责人>]
|
|
52
|
+
[--parent <编号|id>] [--top-level] [--sort created|priority]
|
|
53
|
+
tb task update <编号|id> --if-version <N> [--title ...] [--description ...|--description-file ...]
|
|
54
|
+
[--status ...] [--priority ...] [--labels a,b|--add-labels a|--remove-labels b|--clear-labels]
|
|
55
|
+
[--owner <负责人>|--clear-owner] [--parent <编号|id>|--clear-parent] [--actor human|agent]
|
|
56
|
+
tb task delete <编号|id> --if-version <N>
|
|
57
|
+
|
|
58
|
+
评论
|
|
59
|
+
tb comment add <编号|id> --body <md>|--body-file <文件>
|
|
60
|
+
tb comment list <编号|id>
|
|
61
|
+
tb comment edit <编号|id> <评论id> --if-version <N> --body <md>|--body-file <文件> [--actor human|agent]
|
|
62
|
+
(乐观锁:版本不符退出码 5,不静默覆盖;编辑前原正文自动留痕)
|
|
63
|
+
tb comment history <编号|id> <评论id>
|
|
64
|
+
|
|
65
|
+
全局
|
|
66
|
+
--data-dir <path> 数据目录(默认 $TB_DATA_DIR 或系统临时目录)
|
|
67
|
+
--enforce-governance 启用治理约束(禁止智能体置 done / 推进 backlog)
|
|
68
|
+
--json 兼容开关(输出始终为 JSON)
|
|
69
|
+
--help 显示本帮助
|
|
70
|
+
`;
|
|
71
|
+
|
|
72
|
+
export function parseArgv(argv) {
|
|
73
|
+
const operands = [];
|
|
74
|
+
const options = {};
|
|
75
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
76
|
+
const token = argv[index];
|
|
77
|
+
if (typeof token === "string" && token.startsWith("--")) {
|
|
78
|
+
const body = token.slice(2);
|
|
79
|
+
const eq = body.indexOf("=");
|
|
80
|
+
const name = eq === -1 ? body : body.slice(0, eq);
|
|
81
|
+
if (name === "") throw usageError("空选项名不合法");
|
|
82
|
+
if (BOOLEAN_OPTIONS.has(name)) {
|
|
83
|
+
options[name] = eq === -1 ? true : body.slice(eq + 1) !== "false";
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
if (eq !== -1) {
|
|
87
|
+
options[name] = body.slice(eq + 1);
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
const next = argv[index + 1];
|
|
91
|
+
if (next === undefined || next.startsWith("--")) throw usageError(`选项 --${name} 需要一个值`);
|
|
92
|
+
options[name] = next;
|
|
93
|
+
index += 1;
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
operands.push(token);
|
|
97
|
+
}
|
|
98
|
+
return { operands, options };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function assertKnownOptions(command, options) {
|
|
102
|
+
const allowed = COMMAND_OPTIONS.get(command);
|
|
103
|
+
if (!allowed) throw new TbError("UNKNOWN_COMMAND", `未知命令:${command}`);
|
|
104
|
+
for (const name of Object.keys(options)) {
|
|
105
|
+
if (GLOBAL_OPTIONS.has(name)) continue;
|
|
106
|
+
if (!allowed.has(name)) {
|
|
107
|
+
throw new TbError("UNKNOWN_OPTION", `命令 ${command} 不支持选项 --${name}`, { command, allowed: [...allowed] });
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function readTextOption(options, name, fileField) {
|
|
113
|
+
const inline = options[name];
|
|
114
|
+
const file = options[fileField];
|
|
115
|
+
if (inline !== undefined && file !== undefined) throw usageError(`--${name} 与 --${fileField} 只能二选一`);
|
|
116
|
+
if (file !== undefined) {
|
|
117
|
+
try {
|
|
118
|
+
return readFileSync(file, "utf8");
|
|
119
|
+
} catch (error) {
|
|
120
|
+
throw new TbError("INVALID_FIELD", `无法读取文件 ${file}:${error.message}`, { file });
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return inline;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function parseIfVersion(options) {
|
|
127
|
+
const raw = options["if-version"];
|
|
128
|
+
if (raw === undefined) return undefined;
|
|
129
|
+
const value = Number(raw);
|
|
130
|
+
if (!Number.isInteger(value) || value < 1) throw new TbError("MISSING_VERSION", "--if-version 必须是 ≥1 的整数", { value: raw });
|
|
131
|
+
return value;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function collectLabels(options) {
|
|
135
|
+
const values = [];
|
|
136
|
+
for (const key of ["label", "labels"]) {
|
|
137
|
+
if (options[key] !== undefined) values.push(options[key]);
|
|
138
|
+
}
|
|
139
|
+
return values;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
export async function execute(command, operands, options, context) {
|
|
143
|
+
const { store } = context;
|
|
144
|
+
const stderr = context.stderr ?? process.stderr;
|
|
145
|
+
switch (command) {
|
|
146
|
+
case "project create": {
|
|
147
|
+
if (operands.length !== 0) throw usageError("project create 不接受位置参数");
|
|
148
|
+
if (!options.name) throw usageError("缺少必需参数 --name");
|
|
149
|
+
return { project: store.createProject({ name: options.name, id: options.id, workspacePath: options["workspace-path"] }) };
|
|
150
|
+
}
|
|
151
|
+
case "project list": {
|
|
152
|
+
const projects = store.listProjects();
|
|
153
|
+
return { projects, count: projects.length };
|
|
154
|
+
}
|
|
155
|
+
case "project get": {
|
|
156
|
+
if (operands.length !== 1) throw usageError("project get 需要 1 个参数:<项目id>");
|
|
157
|
+
return { project: store.requireProject(operands[0]) };
|
|
158
|
+
}
|
|
159
|
+
case "task create": {
|
|
160
|
+
if (operands.length !== 0) throw usageError("task create 不接受位置参数");
|
|
161
|
+
if (!options.project) throw usageError("缺少必需参数 --project <项目id>");
|
|
162
|
+
if (!options.title) throw usageError("缺少必需参数 --title <标题>");
|
|
163
|
+
const task = store.createTask({
|
|
164
|
+
projectId: options.project,
|
|
165
|
+
title: options.title,
|
|
166
|
+
description: readTextOption(options, "description", "description-file"),
|
|
167
|
+
status: options.status,
|
|
168
|
+
priority: options.priority,
|
|
169
|
+
labels: collectLabels(options),
|
|
170
|
+
owner: options.owner,
|
|
171
|
+
parent: options.parent,
|
|
172
|
+
actor: options.actor,
|
|
173
|
+
// P0:建卡即归因(同一事务)。缺省不报错但**必须可见**——否则又是"建完才发现没归因"。
|
|
174
|
+
requirementId: options.requirement,
|
|
175
|
+
unattributedReason: options["unattributed-reason"],
|
|
176
|
+
});
|
|
177
|
+
if (!task.requirementId && !options["unattributed-reason"]) {
|
|
178
|
+
// 走 stderr ⇒ 不污染 stdout 的 JSON(脚本可继续 `| jq .task.identifier`)
|
|
179
|
+
stderr.write(
|
|
180
|
+
`⚠ 任务 ${task.identifier} 未归属需求条目:启动执行/派发团队会被归因门拒绝(EXECUTION_NOT_ATTRIBUTED)。\n` +
|
|
181
|
+
` 补归因:tb task attribution ${task.identifier} --requirement <条目>\n` +
|
|
182
|
+
` 或下次建卡直接带 --requirement <条目>(确实不需要归属时用 --unattributed-reason <理由>)\n`,
|
|
183
|
+
);
|
|
184
|
+
}
|
|
185
|
+
return { task };
|
|
186
|
+
}
|
|
187
|
+
case "task get": {
|
|
188
|
+
if (operands.length !== 1) throw usageError("task get 需要 1 个参数:<编号|id>");
|
|
189
|
+
const task = store.requireTaskRef(operands[0]);
|
|
190
|
+
return { task, comments: store.listComments(task.id) };
|
|
191
|
+
}
|
|
192
|
+
case "task list": {
|
|
193
|
+
const filter = {
|
|
194
|
+
projectId: options.project,
|
|
195
|
+
status: options.status,
|
|
196
|
+
priority: options.priority,
|
|
197
|
+
owner: options.owner,
|
|
198
|
+
labels: collectLabels(options),
|
|
199
|
+
sort: options.sort ?? "created",
|
|
200
|
+
};
|
|
201
|
+
if (options["top-level"] === true) filter.parentId = null;
|
|
202
|
+
else if (options.parent !== undefined) filter.parentId = store.requireTaskRef(options.parent).id;
|
|
203
|
+
const tasks = store.listTasks(filter);
|
|
204
|
+
return { tasks, count: tasks.length };
|
|
205
|
+
}
|
|
206
|
+
case "task update": {
|
|
207
|
+
if (operands.length !== 1) throw usageError("task update 需要 1 个参数:<编号|id>");
|
|
208
|
+
const changes = { expectedVersion: parseIfVersion(options), actor: options.actor ?? "human" };
|
|
209
|
+
if (options.title !== undefined) changes.title = options.title;
|
|
210
|
+
const description = readTextOption(options, "description", "description-file");
|
|
211
|
+
if (description !== undefined) changes.description = description;
|
|
212
|
+
if (options.status !== undefined) changes.status = options.status;
|
|
213
|
+
if (options.priority !== undefined) changes.priority = options.priority;
|
|
214
|
+
if (options.labels !== undefined) changes.labels = options.labels;
|
|
215
|
+
if (options["add-labels"] !== undefined) changes.addLabels = options["add-labels"];
|
|
216
|
+
if (options["remove-labels"] !== undefined) changes.removeLabels = options["remove-labels"];
|
|
217
|
+
if (options["clear-labels"] === true) changes.labels = [];
|
|
218
|
+
if (options.owner !== undefined) changes.owner = options.owner;
|
|
219
|
+
if (options["clear-owner"] === true) changes.owner = null;
|
|
220
|
+
if (options.parent !== undefined) changes.parentId = options.parent;
|
|
221
|
+
if (options["clear-parent"] === true) changes.clearParent = true;
|
|
222
|
+
return { task: store.updateTask(operands[0], changes) };
|
|
223
|
+
}
|
|
224
|
+
case "task attribution": {
|
|
225
|
+
if (operands.length !== 1) throw usageError("task attribution 需要 1 个参数:<编号|id>");
|
|
226
|
+
if (!options.requirement) throw usageError("缺少必需参数 --requirement <需求条目标识>");
|
|
227
|
+
const task = store.associateRequirementTask(options.requirement, operands[0]);
|
|
228
|
+
return { task };
|
|
229
|
+
}
|
|
230
|
+
case "task delete": {
|
|
231
|
+
if (operands.length !== 1) throw usageError("task delete 需要 1 个参数:<编号|id>");
|
|
232
|
+
return { deleted: store.deleteTask(operands[0], { expectedVersion: parseIfVersion(options) }) };
|
|
233
|
+
}
|
|
234
|
+
case "comment add": {
|
|
235
|
+
if (operands.length !== 1) throw usageError("comment add 需要 1 个参数:<编号|id>");
|
|
236
|
+
const body = readTextOption(options, "body", "body-file");
|
|
237
|
+
if (body === undefined) throw usageError("缺少 --body 或 --body-file");
|
|
238
|
+
return { comment: store.addComment(operands[0], { body }) };
|
|
239
|
+
}
|
|
240
|
+
case "comment list": {
|
|
241
|
+
if (operands.length !== 1) throw usageError("comment list 需要 1 个参数:<编号|id>");
|
|
242
|
+
const comments = store.listComments(operands[0]);
|
|
243
|
+
return { comments, count: comments.length };
|
|
244
|
+
}
|
|
245
|
+
// FR-17:编辑评论(任务引用 + 评论 id 都要给,防误编辑)。`--if-version` 是**必填**的乐观锁。
|
|
246
|
+
case "comment edit": {
|
|
247
|
+
if (operands.length !== 2) throw usageError("comment edit 需要 2 个参数:<编号|id> <评论id>");
|
|
248
|
+
const body = readTextOption(options, "body", "body-file");
|
|
249
|
+
if (body === undefined) throw usageError("缺少 --body 或 --body-file");
|
|
250
|
+
const task = store.requireTaskRef(operands[0]);
|
|
251
|
+
const existing = store.getComment(operands[1]);
|
|
252
|
+
if (!existing || existing.taskId !== task.id) throw new TbError("COMMENT_NOT_FOUND", `评论不存在于任务 ${task.identifier}:${operands[1]}`, { commentId: operands[1], identifier: task.identifier });
|
|
253
|
+
const result = store.updateComment(operands[1], {
|
|
254
|
+
expectedVersion: parseIfVersion(options),
|
|
255
|
+
body,
|
|
256
|
+
actor: options.actor === "agent" ? "agent" : "human",
|
|
257
|
+
});
|
|
258
|
+
return { comment: result.comment, changed: result.changed, revision: result.revision ?? null };
|
|
259
|
+
}
|
|
260
|
+
case "comment history": {
|
|
261
|
+
if (operands.length !== 2) throw usageError("comment history 需要 2 个参数:<编号|id> <评论id>");
|
|
262
|
+
const task = store.requireTaskRef(operands[0]);
|
|
263
|
+
const existing = store.getComment(operands[1]);
|
|
264
|
+
if (!existing || existing.taskId !== task.id) throw new TbError("COMMENT_NOT_FOUND", `评论不存在于任务 ${task.identifier}:${operands[1]}`, { commentId: operands[1], identifier: task.identifier });
|
|
265
|
+
const revisions = store.listCommentRevisions(operands[1]);
|
|
266
|
+
return { comment: existing, revisions, count: revisions.length };
|
|
267
|
+
}
|
|
268
|
+
default:
|
|
269
|
+
throw new TbError("UNKNOWN_COMMAND", `未知命令:${command}`);
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
export async function main(argv = process.argv.slice(2), io = {}) {
|
|
274
|
+
const stdout = io.stdout ?? process.stdout;
|
|
275
|
+
const stderr = io.stderr ?? process.stderr;
|
|
276
|
+
const env = io.env ?? process.env;
|
|
277
|
+
let store = null;
|
|
278
|
+
try {
|
|
279
|
+
const { operands, options } = parseArgv(argv);
|
|
280
|
+
if (options.help === true || operands.length === 0) {
|
|
281
|
+
stderr.write(USAGE);
|
|
282
|
+
return EXIT.USAGE;
|
|
283
|
+
}
|
|
284
|
+
const command = `${operands[0]} ${operands[1] ?? ""}`.trim();
|
|
285
|
+
if (!COMMAND_OPTIONS.has(command)) {
|
|
286
|
+
throw new TbError("UNKNOWN_COMMAND", `未知命令:${command || "(空)"}`, { known: [...COMMAND_OPTIONS.keys()] });
|
|
287
|
+
}
|
|
288
|
+
assertKnownOptions(command, options);
|
|
289
|
+
store = openStore({
|
|
290
|
+
dataDir: options["data-dir"],
|
|
291
|
+
env,
|
|
292
|
+
policy: { enforce: options["enforce-governance"] === true },
|
|
293
|
+
});
|
|
294
|
+
const payload = await execute(command, operands.slice(2), options, { store, env, stderr });
|
|
295
|
+
stdout.write(`${JSON.stringify({ schemaVersion: CLI_SCHEMA_VERSION, ...payload }, null, 2)}\n`);
|
|
296
|
+
return EXIT.OK;
|
|
297
|
+
} catch (error) {
|
|
298
|
+
const { error: errorPayload, exitCode } = toErrorPayload(error);
|
|
299
|
+
stderr.write(`${JSON.stringify({ schemaVersion: CLI_SCHEMA_VERSION, error: errorPayload }, null, 2)}\n`);
|
|
300
|
+
return exitCode;
|
|
301
|
+
} finally {
|
|
302
|
+
try {
|
|
303
|
+
store?.close();
|
|
304
|
+
} catch {
|
|
305
|
+
/* ignore */
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
const entryHref = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
|
|
311
|
+
if (entryHref === import.meta.url) {
|
|
312
|
+
const code = await main();
|
|
313
|
+
process.exitCode = code;
|
|
314
|
+
}
|