taskboard-workbench 0.0.0-stage → 0.3.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 +403 -0
- package/LICENSE +21 -0
- package/README.md +210 -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 +96 -4
- package/scripts/tb-flow.mjs +86 -0
- package/skills/taskboard-flow/SKILL.md +89 -0
- package/skills/taskboard-flow/references/errors.md +61 -0
- package/skills/taskboard-flow/references/injection.md +70 -0
- package/skills/taskboard-flow/references/steps/S0.md +31 -0
- package/skills/taskboard-flow/references/steps/S1.md +28 -0
- package/skills/taskboard-flow/references/steps/S2.md +31 -0
- package/skills/taskboard-flow/references/steps/S3.md +22 -0
- package/skills/taskboard-flow/references/steps/S4.md +25 -0
- package/skills/taskboard-flow/references/steps/S5.md +36 -0
- package/skills/taskboard-flow/references/steps/S6.md +30 -0
- package/skills/taskboard-flow/references/steps/S7.md +23 -0
- package/spec/norms/acceptance.md +36 -0
- package/spec/norms/card-update.md +39 -0
- package/spec/norms/doc-editing.md +30 -0
- package/spec/norms/flow.md +45 -0
- package/spec/norms/manifest.json +41 -0
- package/spec/norms/project-defaults.md +33 -0
- package/spec//345/233/242/351/230/237agent.md +171 -0
- package/src/core/acceptance.mjs +62 -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/contract.mjs +287 -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 +142 -0
- package/src/core/evidence.mjs +86 -0
- package/src/core/executor.mjs +645 -0
- package/src/core/human-review.mjs +773 -0
- package/src/core/intake.mjs +179 -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 +292 -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 +3442 -0
- package/src/core/team.mjs +170 -0
- package/src/core/ticket-stage.mjs +150 -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/mcp/flow-block.mjs +173 -0
- package/src/mcp/server.mjs +156 -0
- package/src/mcp/tools.mjs +764 -0
- package/src/server/api.mjs +2050 -0
- package/src/server/events.mjs +32 -0
- package/src/server/kickoff.mjs +46 -0
- package/src/server/server.mjs +214 -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 +5337 -0
- package/web/index.html +15 -0
- package/web/tokens.css +1151 -0
package/README.md
CHANGED
|
@@ -1,3 +1,211 @@
|
|
|
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
|
+
装好后在 DSH 里打开「任务工作台」面板(地址以 `/integrations/taskboard-workbench` 结尾)。
|
|
42
|
+
**只有这个形态拿得到宿主会话通道**:`GET /api/health` 的 `host.capabilities` 非空,
|
|
43
|
+
「投给主会话 / 打开会话 / 派发团队」才可用。
|
|
44
|
+
|
|
45
|
+
> 验收这条链路(从 `npm pack` 产物装进全新隔离 profile,真宿主起会话):
|
|
46
|
+
> `node tools/bench-market-install.mjs` —— 11 项,含「独立进程无宿主通道」的反向对照。
|
|
47
|
+
|
|
48
|
+
### 从源码
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
git clone https://github.com/SilenZerOrz/taskboard-workbench.git
|
|
52
|
+
cd taskboard-workbench
|
|
53
|
+
dsh plugin --profile web add .
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 独立跑(不用 DSH)
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npm start # 启动本地 Web 服务(默认监听本机端口)
|
|
60
|
+
node cli/tb.mjs project list # 或用 CLI 直接操作
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
> ⚠️ 独立进程**没有** DSH 宿主会话通道:`/api/health` 的 `host.capabilities` 恒为 `null`,
|
|
64
|
+
> 「投给主会话 / 打开会话 / 派发团队」不可用(界面按能力位置灰并常驻提示)。
|
|
65
|
+
> 看板、建卡、改状态、评审、人工收口照常可用。要投递或派发,请用上面的**插件形态**。
|
|
66
|
+
|
|
67
|
+
## 要求
|
|
68
|
+
|
|
69
|
+
| 项 | 值 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| Node.js | `>= 22.5.0`(依赖 `node:sqlite`) |
|
|
72
|
+
| DSH | `0.2.0-rc.2` 线真机验证通过(`0.2.1-alpha.1` 历史走通) |
|
|
73
|
+
| 运行时依赖 | 无(`dependencies` 为空) |
|
|
74
|
+
|
|
75
|
+
## 快速上手(CLI)
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# 数据目录:--data-dir > $TB_DATA_DIR > 系统临时目录
|
|
79
|
+
export TB_DATA_DIR="$HOME/.taskboard-data"
|
|
80
|
+
|
|
81
|
+
node cli/tb.mjs project create --name "示例项目" --id demo
|
|
82
|
+
node cli/tb.mjs task create --project demo --title "跑通一次闭环" --description "验证一下"
|
|
83
|
+
node cli/tb.mjs task list --project demo
|
|
84
|
+
node cli/tb.mjs comment add 1 --body "证据:npm test 全绿"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
CLI 约定:成功 `stdout` 输出 JSON(含 `schemaVersion`),退出码 `0`;
|
|
88
|
+
失败 `stderr` 输出 `{schemaVersion, error:{code,message}}`,退出码 `2/3/4/5`。
|
|
89
|
+
并发编辑用 `--if-version`,版本不符返回 `VERSION_CONFLICT`(退出码 5)而不静默覆盖。
|
|
90
|
+
|
|
91
|
+
## MCP 契约层(九个工具)
|
|
92
|
+
|
|
93
|
+
把「开局要读什么、规范长什么样、哪里有漂移、卡怎么建、进度怎么回填」做成 agent 可直接调用的接口,
|
|
94
|
+
让 Claude Code / Codex / Hermes 等外部 agent 不必靠人肉复制粘贴就能对齐同一份项目事实。
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
node src/mcp/server.mjs --data-dir "$TB_DATA_DIR" # MCP 客户端作为子进程拉起(stdio)
|
|
98
|
+
node src/mcp/server.mjs --print-tools # 只打印工具清单(调试用)
|
|
99
|
+
npm run mcp -- --data-dir "$TB_DATA_DIR" # 同上,走 npm script
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
传输是 **stdio + newline-delimited JSON-RPC 2.0**(MCP stdio transport):
|
|
103
|
+
**不占端口、不碰 `:3080`、不写 `~/.dsh/**`、不需要重载宿主**,每个 agent 会话一个进程。
|
|
104
|
+
|
|
105
|
+
### 只读五件
|
|
106
|
+
|
|
107
|
+
| 工具 | 用途 |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| `flow_start` | 开局第一步(S0):项目身份 + `contract_version` + 缺口(未归因卡 / 未绑定主会话 / 待确认候选)+ 下一步建议 |
|
|
110
|
+
| `project_info` | 项目总览:任务与需求条目按状态计数 + 契约版本与基线是否漂移 |
|
|
111
|
+
| `norm_get` | 取机器规范正文(`flow` / `card-update` / `doc-editing` / `acceptance` / `project-defaults`;`norm="project"` 读项目自有 `<workspace>/AGENTS.md`)+ `digest` |
|
|
112
|
+
| `requirement_list` | 需求条目列表:条目 + 内容版本(乐观锁用)+ 每条下的卡数与完成数 |
|
|
113
|
+
| `workbench_audit` | 漂移盘点:`contract-stale` / `unattributed` / `unbound-session` / `candidate-flood` 四类,各带计数、样例与处置建议 |
|
|
114
|
+
|
|
115
|
+
### 写四件(形状即约束)
|
|
116
|
+
|
|
117
|
+
| 工具 | 强制的形状 | 被拒的样子 |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| `card_create` | **归因硬门**:`requirement` 或显式 `unattributed_reason`(落审计)。新卡只能进 `backlog` | `REQUIREMENT_REQUIRED` / `AUTHORIZATION_REQUIRED`(`backlog → todo` 是人工授权) |
|
|
120
|
+
| `card_progress` | `evidence[]` **非空**(每项 `{kind: file\|command\|url\|reading, ref, note?}`)+ **`norm_digest` 必填**(`card-update` 的 sha256) | `EVIDENCE_REQUIRED` / `NORM_DIGEST_REQUIRED` / `NORM_STALE`(回带最新正文)/ `GOVERNANCE_AGENT_DONE` |
|
|
121
|
+
| `requirement_upsert` | 改条目必须带 `expected_version`(`requirement_list` 返回的 `version`) | `MISSING_VERSION` / `VERSION_CONFLICT` |
|
|
122
|
+
| `requirement_change` | 先预览拿 `change_id` + 影响面 `affected_cards`,带 `change_id` + `apply:true` 才落地 | `CHANGE_NEEDS_APPROVAL` / `CHANGE_ID_MISMATCH`(预览后条目被改过即失效) |
|
|
123
|
+
|
|
124
|
+
**四条红线仍然由门守,不是由纪律守**:
|
|
125
|
+
|
|
126
|
+
1. `done` 只能人点 —— `card_progress` 走执行侧状态门,写 `done` 直接 `GOVERNANCE_AGENT_DONE`;
|
|
127
|
+
2. `backlog → todo` 是人工授权 —— `card_create` 只接受 `backlog`;
|
|
128
|
+
3. 人工校验任务不得被执行侧改状态;
|
|
129
|
+
4. 证据不能是「已完成」三个字 —— `evidence[]` 的形状就是判据;同一批证据重复回填会按 `hash` 去重。
|
|
130
|
+
|
|
131
|
+
**契约档位**:`contract_version` 目前仍是 **`warn`** 档(不符只落 `contract-warn` 审计、不阻断),
|
|
132
|
+
切 `reject` 要等观察期到点单独拍板;写工具的返回体里带 `contract.verdict` 让 agent 自己知道用没用旧规范。
|
|
133
|
+
|
|
134
|
+
数据源是**同一个** `taskboard.sqlite`(`--data-dir` > `$TB_DATA_DIR` > 默认),
|
|
135
|
+
MCP 不是第二份数据 —— 看板里看到的、CLI 改的、MCP 读的,是同一行记录。
|
|
136
|
+
`tests/mcp-parity.test.mjs` 守的就是这条:同一操作在 HTTP 与 MCP 上**错误码与副作用必须同形**。
|
|
137
|
+
|
|
138
|
+
同一个 server 还提供一个 **MCP prompt `taskboard.flow`**(`prompts/list` / `prompts/get`):
|
|
139
|
+
内容是当前项目的「开局装载块」—— 契约版本、门档、六类缺口、下一步该做什么、八步表与五条硬规则。
|
|
140
|
+
它与 CLI 的 `tb-flow start` **共用一个生成器**,输出逐字节相同(`tests/skill-flow.test.mjs` 守这条)。
|
|
141
|
+
|
|
142
|
+
## 技能包(开局装载)
|
|
143
|
+
|
|
144
|
+
`skills/taskboard-flow/` 是给 agent 读的**主流程技能**(八步 S0–S7 × 六栏:入口 / 前置门 / 判据 /
|
|
145
|
+
证据落点 / 失败处置 / 对应 FR),随包分发。它**只教顺序与判据,不持有业务规则副本** ——
|
|
146
|
+
数据在 `taskboard.sqlite`,门在 `src/mcp/` 与 `src/core/`,机器规范在 `spec/norms/`。
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
npm run flow -- start --data-dir "$TB_DATA_DIR" --project demo # 打印开局装载块(档 A:整块贴进会话)
|
|
150
|
+
npm run flow -- start --json # 同上,结构化输出
|
|
151
|
+
npm run flow -- snippet # 打印档 B 的 AGENTS.md 片段
|
|
152
|
+
npm run flow -- check # 自检 frontmatter 与八步完整性
|
|
153
|
+
node scripts/tb-flow.mjs start --cwd /path/to/repo # 缺项目时按 cwd / 目录名猜
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
三种开局方式,按侵入性排序:
|
|
157
|
+
|
|
158
|
+
| 档 | 谁用 | 怎么做 | 要不要改宿主 |
|
|
159
|
+
| --- | --- | --- | --- |
|
|
160
|
+
| **A 开局提示词** | 人在 dsh 主会话里新开一轮 | 贴 `tb-flow start` 输出;或 MCP 客户端取 prompt `taskboard.flow` | 不用 |
|
|
161
|
+
| **B 外部 agent 约定** | Claude Code / Codex 在项目仓库里开工 | 项目根 `AGENTS.md` 写「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」,片段用 `tb-flow snippet` 打印 | 不用 |
|
|
162
|
+
| **C 宿主自动注入** | dsh 会话创建即注入 | **未启用**(须报批改 `~/.dsh/**` 并重载宿主);接口形状见 `skills/taskboard-flow/references/injection.md` | 须报批 |
|
|
163
|
+
|
|
164
|
+
## 配置
|
|
165
|
+
|
|
166
|
+
| 环境变量 | 作用 | 默认 |
|
|
167
|
+
| --- | --- | --- |
|
|
168
|
+
| `TB_DATA_DIR` | SQLite 数据目录 | 系统临时目录(仅适合试跑,正式用请显式指定) |
|
|
169
|
+
|
|
170
|
+
项目级配置(工作区路径、审批策略、执行者选择等)在 Web 看板的「项目设置」里维护。
|
|
171
|
+
|
|
172
|
+
## 目录结构
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
index.js DSH 插件入口(cordis patch 注入点)
|
|
176
|
+
lib/client.js 宿主侧客户端桥
|
|
177
|
+
cordis.patch.yml dsh.bundle.patch
|
|
178
|
+
src/core/ 存储、状态机、团队模板、执行编排、看护
|
|
179
|
+
src/server/ HTTP API 与事件流
|
|
180
|
+
src/host/ 团队引擎与工具面
|
|
181
|
+
src/mcp/ MCP 契约层(stdio server + 九个工具:只读五 / 写四 + prompt taskboard.flow)
|
|
182
|
+
skills/taskboard-flow/ 主流程技能包(八步 × 六栏 + 每步 references + 错误码 + 装载说明)
|
|
183
|
+
scripts/tb-flow.mjs `tb-flow` 开局装载块 CLI(start / snippet / check)
|
|
184
|
+
web/ 本地 Web 看板(app.js / tokens.css / index.html)
|
|
185
|
+
cli/tb.mjs `tb` 命令行
|
|
186
|
+
spec/团队agent.md 团队契约(随包发布,供工作台里的 agent 读取)
|
|
187
|
+
spec/norms/ 机器执行规范(运行时唯一真源,随包;manifest.json 带 sha256 digest)
|
|
188
|
+
tests/ `node --test` 单测
|
|
189
|
+
tools/ 开发与验证脚本(不进 npm 包,除 seed/env-check)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## 测试
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm test # node --test,全量单测
|
|
196
|
+
node --check index.js # 语法自检(对每个源文件)
|
|
197
|
+
node src/mcp/server.mjs --print-tools # MCP 工具清单自检
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## 版本
|
|
201
|
+
|
|
202
|
+
见 [CHANGELOG.md](./CHANGELOG.md)。对外首个版本为 `0.1.0`。
|
|
203
|
+
|
|
204
|
+
## 说明:`docs/` 不随仓库发布
|
|
205
|
+
|
|
206
|
+
本仓库的过程文档(需求 / 计划 / 进度 / 验证 / 规范 / 发布 SOP 等)在本地维护,
|
|
207
|
+
**不进入 git 与 npm 包**(见 `.gitignore`)。仓库只发布可运行的代码与随包契约 `spec/`。
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
[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
|
+
}
|