taskboard-workbench 0.3.0 → 0.3.2
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 +106 -0
- package/README.md +6 -0
- package/index.js +39 -6
- package/package.json +8 -3
- package/scripts/tb-flow.mjs +109 -8
- package/skills/taskboard-flow/SKILL.md +1 -1
- package/skills/taskboard-flow/references/injection.md +77 -24
- package/spec/docs/01-/351/241/271/347/233/256/345/274/200/345/261/200.md +63 -0
- package/spec/docs/02-/346/265/201/347/250/213/346/211/247/350/241/214/344/270/216/346/235/241/347/233/256.md +110 -0
- package/spec/docs/README.md +36 -0
- package/spec/docs/assets//346/235/241/347/233/256/350/257/246/346/203/205/346/250/241/346/235/277.md +105 -0
- package/spec/norms/item-detail.md +73 -0
- package/spec/norms/manifest.json +7 -0
- package/src/core/contract.mjs +17 -7
- package/src/core/docs-assets.mjs +135 -0
- package/src/core/errors.mjs +2 -0
- package/src/core/flow-inject.mjs +190 -0
- package/src/core/kickoff.mjs +289 -0
- package/src/core/norms.mjs +177 -0
- package/src/core/requirements.mjs +38 -0
- package/src/core/store.mjs +196 -35
- package/src/core/ticket-stage.mjs +13 -1
- package/src/core/verify.mjs +12 -4
- package/src/mcp/flow-block.mjs +30 -0
- package/src/mcp/server.mjs +26 -7
- package/src/mcp/tools.mjs +9 -3
- package/src/server/api.mjs +234 -6
- package/web/app.js +656 -78
- package/web/tokens.css +137 -28
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# 01 · 项目开局(六步 + 自检表)
|
|
2
|
+
|
|
3
|
+
> 目的:把「打开工作台之后先干什么」这件事定死,避免项目一建就堆卡、卡一开就没人认得边界。
|
|
4
|
+
|
|
5
|
+
## 六步
|
|
6
|
+
|
|
7
|
+
### 1. 绑定工作区
|
|
8
|
+
|
|
9
|
+
项目必须有 **workspacePath**(你的代码仓库目录)。它是三件事的锚点:
|
|
10
|
+
|
|
11
|
+
- 项目副本写在哪:`<工作区>/.taskboard/`(文档、机器规范);
|
|
12
|
+
- 执行单元的工作目录(`cwd`);
|
|
13
|
+
- 开局自检、契约、证据里所有「相对路径」的基准。
|
|
14
|
+
|
|
15
|
+
> 没填工作区 ⇒ 副本生成会直接拒绝(`WORKSPACE_MISSING`),这不是 bug,是防止「静默写到不知道哪里」。
|
|
16
|
+
|
|
17
|
+
### 2. 建需求文档 + 第一条需求条目
|
|
18
|
+
|
|
19
|
+
需求条目是**可评估单元**,一张卡是**可执行单元**。先有需求,再拆卡 —— 反过来做,卡会没有归属,
|
|
20
|
+
后面既统计不了完成度,也没法回答「这件事为什么要做」。
|
|
21
|
+
|
|
22
|
+
条目骨架见 [`02-流程执行与条目.md`](./02-流程执行与条目.md) §三,模板见 [`assets/条目详情模板.md`](./assets/条目详情模板.md)。
|
|
23
|
+
|
|
24
|
+
### 3. 拆首卡:一张,带可判真假的验收
|
|
25
|
+
|
|
26
|
+
开局第一张卡不要贪大。判据:**做完之后,能用一条命令或一次点击判定真假**。
|
|
27
|
+
|
|
28
|
+
反例:「完善初始化流程」(不可判)→ 正例:「`POST /api/projects` 建项目后 `GET /api/projects/:id` 回读 `workspacePath` 一致」(可判)。
|
|
29
|
+
|
|
30
|
+
### 4. 确认执行能力(**必须标宿主版本 + pid**)
|
|
31
|
+
|
|
32
|
+
工作台能不能派发,取决于宿主能力位(会话创建 / 会话存在 / 归属查询…)。这些是**外部环境事实**,
|
|
33
|
+
不是本仓库常量 —— 所以任何「能力可用/不可用」的结论都要写清当时的 **宿主版本 + 进程号**,
|
|
34
|
+
否则升级之后旧读数会变成假事实(本项目实测过:宿主小版本升级就把三个能力位从 `false` 全翻成 `true`)。
|
|
35
|
+
|
|
36
|
+
### 5. 跑通第一条闭环
|
|
37
|
+
|
|
38
|
+
认领(`in_progress` + owner)→ 执行 → 证据四节 → `done`。第一张卡走完,才说明「看板不是摆设」。
|
|
39
|
+
|
|
40
|
+
### 6. 定验收口径再放量
|
|
41
|
+
|
|
42
|
+
放量之前确认三件事:验收写在哪(字段还是正文)、`done` 谁点、审查过不过谁来判。
|
|
43
|
+
这三条不定,卡越多越乱。
|
|
44
|
+
|
|
45
|
+
## 自检表(逐条能回答「是」才算开局完成)
|
|
46
|
+
|
|
47
|
+
| # | 检查 | 判据 |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| 1 | 工作区已绑定 | `GET /api/projects/:id` 的 `workspacePath` 非空 |
|
|
50
|
+
| 2 | 有需求条目 | 需求视图里至少 1 条 `open` |
|
|
51
|
+
| 3 | 首卡有验收 | 卡的 `acceptance` 非空且每条可判真假 |
|
|
52
|
+
| 4 | 卡归因到需求 | 卡上 `requirement_ref` 指向第 2 步的条目 |
|
|
53
|
+
| 5 | 执行能力已核实 | 能力读数带 **宿主版本 + pid** |
|
|
54
|
+
| 6 | 首条闭环走完 | 该卡 `done` 且证据四节齐全 |
|
|
55
|
+
|
|
56
|
+
## 反模式(开局阶段最常见的四个)
|
|
57
|
+
|
|
58
|
+
| 反模式 | 后果 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| 先堆 20 张卡,没有需求条目 | 完成度无从统计;卡与卡之间的边界靠记忆 |
|
|
61
|
+
| 验收写在描述正文、`acceptance` 留空 | 服务端只认字段 ⇒ 等于「没有验收」 |
|
|
62
|
+
| 把整份需求文档粘进条目 | 早期导入就是这么截断的:2000 字符处断在半个词上 |
|
|
63
|
+
| 把「宿主能力」当常量写进文档 | 宿主一升级,文档与事实分叉,且没人会回头改 |
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# 02 · 流程执行与条目写法
|
|
2
|
+
|
|
3
|
+
> 这一份管两件事:**活怎么走**(全环 + 指令 + 证据)与**条怎么写**(骨架 + 预算 + 反模式)。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 一、全环(缺任一环,这轮就不算完成)
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
需求条目 → 任务卡(带 requirement_ref) → 认领(in_progress + owner)
|
|
11
|
+
→ 执行 → 证据评论(四节) → done → 需求关闭(先回读 ready)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
四条硬规矩:
|
|
15
|
+
|
|
16
|
+
1. **卡必须挂需求**。没有 `requirement_ref` 的卡不允许开工;若确实不属于任何需求,先补建条目再开卡。
|
|
17
|
+
2. **认领先于动手**。`in_progress` + owner 是先写库、再干活;反过来做,看板上就永远看不出谁在干。
|
|
18
|
+
3. **证据评论不是汇报**。它是**下次复跑的说明书**:判定 / 偏离说明 / 边界自查 / 产物路径。
|
|
19
|
+
4. **关闭需求前先回读**。`completion` 里 `ready=false` 就说明还有卡没收口 —— 这时候关,等于把未完成记成完成。
|
|
20
|
+
|
|
21
|
+
> 计划外/新增需求同样走这条环:先建条目拿 ref → 建关联卡 → 可做则认领、不可做留 backlog。**不许停在口头。**
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 二、指令骨架(下发给执行 agent 时)
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
<编号>|<一句话标题>
|
|
29
|
+
|
|
30
|
+
范围:<文件:行 / 条目编号 / 章节>;包含:…;移出:…
|
|
31
|
+
禁止:<项目硬禁令> + 本轮特禁
|
|
32
|
+
做法:分步;涉及改代码时写「先贴原文 → 改 → 再贴原文」
|
|
33
|
+
报告:证据四节 + 本类额外要什么读数
|
|
34
|
+
停下:<什么情况必须停、不停会怎样>
|
|
35
|
+
验收:<可复跑读数,一条一行,能判真假>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
两条容易漏的:
|
|
39
|
+
|
|
40
|
+
- **「范围」必须同时写「包含」和「移出」**。只写包含 = 边界没定,执行侧会顺手扩。
|
|
41
|
+
- **「停下」不是客套**。写清「什么情况下停」,比写十遍「不要越界」有用。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 三、条目骨架
|
|
46
|
+
|
|
47
|
+
### 任务卡(可执行单元 · 七块全填)
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
<编号>|<动词开头:做完什么>
|
|
51
|
+
|
|
52
|
+
目标:这张卡做完,解决谁的什么问题(不写做法)
|
|
53
|
+
范围:<位置>;包含:…;移出:…
|
|
54
|
+
禁止:<相关硬禁令> + 本轮特禁
|
|
55
|
+
做法:分步
|
|
56
|
+
报告:四节证据 + 额外读数
|
|
57
|
+
停下:<停的条件>
|
|
58
|
+
验收:<可复跑读数>
|
|
59
|
+
关联:<需求 ref / 依赖卡 / 规范 §>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### 需求条目(可评估单元 · 五块必填)
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
<编号>|<一句话标题>
|
|
66
|
+
|
|
67
|
+
目标:要解决什么(一句话)
|
|
68
|
+
范围:包含:…;移出:…
|
|
69
|
+
约束:口径、边界、红线
|
|
70
|
+
验收:3–6 条,可判真假
|
|
71
|
+
关联:条目 / 卡 / 文档 §
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
需求条目**可以省**「做法 / 报告 / 停下」—— 它说的是**要什么**,不是**怎么做**。
|
|
75
|
+
|
|
76
|
+
### 长度预算
|
|
77
|
+
|
|
78
|
+
| 对象 | 上限 | 超了怎么办 |
|
|
79
|
+
|---|---:|---|
|
|
80
|
+
| 需求条目描述 | 1200 字符 | 细节挪进卡或文档,正文只留指针 |
|
|
81
|
+
| 任务卡描述 | 800 字符 | 同上 |
|
|
82
|
+
| `acceptance` | 3–6 条 | 超过 6 条说明这件事该拆成两张卡 |
|
|
83
|
+
|
|
84
|
+
**禁止整段粘源文档**:写「见 `<路径>` §x」。整段粘贴就是 2000 字符截断的直接来源。
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 四、证据四节(每条都要能独立复跑)
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
① 判定 —— 逐条对验收给读数(命令 + 输出摘要),PASS/FAIL 明确
|
|
92
|
+
② 偏离说明 —— 计划外做了什么、为什么;没做的说明
|
|
93
|
+
③ 边界自查 —— 没碰什么(进程 / 数据 / 历史文档 / 未授权对外动作)
|
|
94
|
+
④ 产物路径 —— 改了哪些文件、文档落在哪、归档在哪
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
判据:**换个人只看这条评论,能不能不问你一句就把这轮复跑出来**。不能,就是没写完。
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 五、反模式(都真实出现过)
|
|
102
|
+
|
|
103
|
+
| 反模式 | 为什么坏 |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `acceptance` 留空,验收写在正文 | 服务端只认字段;正文写了等于没写 |
|
|
106
|
+
| 正文一遍验收、字段再一遍且措辞不同 | 两个源必然走样;同一件事只准一个源 |
|
|
107
|
+
| 描述正好 2000 字符、结尾断在半个词上 | 早期导入的截断残片;界面标「残片」就别当完整依据 |
|
|
108
|
+
| 「验证通过」但不给读数 | 无法证伪,也无法复跑 |
|
|
109
|
+
| 用「上一轮说过要做」代替本轮批准 | 授权有有效期;破坏性动作必须当轮明确批准 |
|
|
110
|
+
| 只报「已完成」不报「没做什么」 | 边界是结论的一部分,缺失会被下次误读成「已覆盖」 |
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# 随包文档 · 开局与流程约束(人读版)
|
|
2
|
+
|
|
3
|
+
这个目录是**任务工作台随包分发的人读文档**:装完插件就能看到「项目怎么开局、流程怎么走、条目怎么写」,
|
|
4
|
+
不必依赖作者机器上的 `docs/`。
|
|
5
|
+
|
|
6
|
+
它是**通用版**:写给任何项目,不含作者本仓的历史读数与内部路径。
|
|
7
|
+
|
|
8
|
+
## 两份文档,各管一层
|
|
9
|
+
|
|
10
|
+
| 层 | 位置 | 管什么 |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| **人读版**(本目录) | `spec/docs/` | **为什么**这么定:开局清单、流程全环、反例与代价 |
|
|
13
|
+
| **机器版** | `spec/norms/` | **判据**:骨架、长度预算、门禁口径;写操作时按它校验契约 |
|
|
14
|
+
|
|
15
|
+
改人读文档**不影响**契约;只有改 `spec/norms/` 里的规范正文才会改契约版本(且必须 bump `version`)。
|
|
16
|
+
|
|
17
|
+
## 目录
|
|
18
|
+
|
|
19
|
+
- [`01-项目开局.md`](./01-项目开局.md) —— 新项目从零到「第一条闭环」的六步清单与自检表
|
|
20
|
+
- [`02-流程执行与条目.md`](./02-流程执行与条目.md) —— 需求 → 卡 → 认领 → 执行 → 证据 → done 全环;条目骨架与预算
|
|
21
|
+
- [`assets/条目详情模板.md`](./assets/条目详情模板.md) —— 可直接复制的卡 / 需求骨架
|
|
22
|
+
|
|
23
|
+
## 这些文档放在哪(三处)
|
|
24
|
+
|
|
25
|
+
1. **包内默认位置**:安装后随包就在(插件的 `spec/docs/`),**只读**,升级会被覆盖;
|
|
26
|
+
2. **项目存放位置**:默认 `<你的工作区>/.taskboard/docs/`,由配置页「生成默认副本」写入,**可改**;
|
|
27
|
+
3. **生效来源**:看板读文档时优先项目副本,缺的回落包内 —— 配置页会显示当前是哪一种。
|
|
28
|
+
|
|
29
|
+
## 想改成自己的规矩
|
|
30
|
+
|
|
31
|
+
1. 配置页 →「文档与规范位置」→ **生成默认副本**;
|
|
32
|
+
2. 直接编辑项目副本里的 `.md`;
|
|
33
|
+
3. 只在本机生效就不管它;想团队共享就把该目录 `git add` 进你的仓库(要不要入库由你定)。
|
|
34
|
+
|
|
35
|
+
> 若你要改的是**会被看板强制校验**的规则(骨架 / 预算 / 验收条数),那是 `spec/norms/` 的事 ——
|
|
36
|
+
> 项目副本里的规范正文改了**必须同时把 `version` 加 1**,否则会被判「规范被偷偷改了」并拦写。
|
package/spec/docs/assets//346/235/241/347/233/256/350/257/246/346/203/205/346/250/241/346/235/277.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# 条目详情模板(可直接复制)
|
|
2
|
+
|
|
3
|
+
> 配套文档:[`../02-流程执行与条目.md`](../02-流程执行与条目.md) §三(骨架与预算)。
|
|
4
|
+
> 用法:复制 A 或 B 的空骨架,把 `<>` 填掉。写完过一遍下面的「五问自检」。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## A. 任务卡(空骨架 · 七块全填)
|
|
9
|
+
|
|
10
|
+
```markdown
|
|
11
|
+
<编号>|<动词开头的一句话:做完什么>
|
|
12
|
+
|
|
13
|
+
目标:<这张卡做完解决谁的什么问题;一句话,不写做法>
|
|
14
|
+
范围:<文件:行 / 条目编号 / 章节>;包含:<…>;移出:<…>
|
|
15
|
+
禁止:<项目硬禁令中与本卡相关的几条> + 本轮特禁:<…>
|
|
16
|
+
做法:
|
|
17
|
+
1. <先贴原文(文件:行)>
|
|
18
|
+
2. <改什么>
|
|
19
|
+
3. <再贴原文 + 跑哪条命令>
|
|
20
|
+
报告:四节证据(判定 / 偏离说明 / 边界自查 / 产物路径)+ <本类额外读数:如 dist-tags / 渲染后 DOM / 台架 n/n>
|
|
21
|
+
停下:报错 / 超范围 / 验收不满足 / 需要新变量 ⇒ 停,不重试;<本卡特有停机条件>
|
|
22
|
+
验收:
|
|
23
|
+
① <读数 1>
|
|
24
|
+
② <读数 2>
|
|
25
|
+
③ <读数 3>
|
|
26
|
+
关联:<需求 ref> · <依赖卡> · <文档 §> · <上游 PR>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## B. 需求条目(空骨架 · 五块必填)
|
|
32
|
+
|
|
33
|
+
```markdown
|
|
34
|
+
<编号>|<一句话:这条需求要达成什么>
|
|
35
|
+
|
|
36
|
+
目标:<对外可感知的结果,不是实现手段>
|
|
37
|
+
范围:包含:<…>;移出:<**必填**,否则范围无边界>
|
|
38
|
+
约束:<硬禁令引用 + 口径约束:不改 schema / 不动生产进程 / 须人拍…>
|
|
39
|
+
验收:
|
|
40
|
+
① <能判真假的读数 1>
|
|
41
|
+
② <读数 2>
|
|
42
|
+
③ <读数 3>
|
|
43
|
+
关联:<设计稿 / 上游仓库 / 关联卡 / 其它需求>(没有就写「无」)
|
|
44
|
+
背景:<可选,≤5 行,只写「为什么现在做」>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## C. 填好的卡(示例)
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
<你的项目>-999|把「来源」列的 mcp 条目正确显示为 MCP
|
|
53
|
+
|
|
54
|
+
目标:MCP 建的需求条目在界面上不再被标成「手工」,人能一眼看出是谁建的。
|
|
55
|
+
范围:`web/app.js` 的两处来源三元链;包含:列表胶囊 + 详情字段;移出:数据层 source 值、其它来源档位。
|
|
56
|
+
禁止:不整文件重写;不动 `:3080`。
|
|
57
|
+
做法:
|
|
58
|
+
1. 先贴两处三元链原文
|
|
59
|
+
2. 各加一个 `mcp` 分支
|
|
60
|
+
3. 再贴原文 + 跑渲染验证台
|
|
61
|
+
报告:四节证据 + 验证台 n/n + 旧前端反证读数。
|
|
62
|
+
停下:反证不转红(说明守卫没守住)⇒ 停,先修守卫。
|
|
63
|
+
验收:
|
|
64
|
+
① 列表里 `source="mcp"` 显示「MCP」
|
|
65
|
+
② 详情「来源」字段=「MCP」
|
|
66
|
+
③ `intake` 条目仍显示「资料索引(引入)」
|
|
67
|
+
关联:R-xxx · 文档 §三
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## D. 证据四节(空骨架)
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
【证据 · 四节】<卡号> · <日期>
|
|
76
|
+
|
|
77
|
+
## ① 判定
|
|
78
|
+
| # | 验收 | 读数 | 结论 |
|
|
79
|
+
|---|---|---|---|
|
|
80
|
+
| ① | <验收原句> | <命令 + 输出摘要> | PASS/FAIL |
|
|
81
|
+
|
|
82
|
+
## ② 偏离说明
|
|
83
|
+
- <偏离 1:计划是什么 / 实际是什么 / 为什么>
|
|
84
|
+
- <没做的:哪些移出项、留给谁>
|
|
85
|
+
|
|
86
|
+
## ③ 边界自查
|
|
87
|
+
- 未 <改动项:版本 / tag / 历史文档 / 生产进程>
|
|
88
|
+
- <未碰的进程与数据>
|
|
89
|
+
|
|
90
|
+
## ④ 产物路径
|
|
91
|
+
- 新:<路径>
|
|
92
|
+
- 改:<路径>
|
|
93
|
+
- 文档:<路径>
|
|
94
|
+
- 归档:<路径>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 五问自检(写完逐条过)
|
|
100
|
+
|
|
101
|
+
1. 第一行是不是「`<编号>|一句话`」?
|
|
102
|
+
2. 「范围」有没有**同时**写「包含」与「移出」?
|
|
103
|
+
3. 验收的每一条,别人拿过去能不能**判真假**?
|
|
104
|
+
4. 有没有整段粘文档?有就改成指针。
|
|
105
|
+
5. 字符数在预算内吗(需求 ≤1200 / 卡 ≤800 / 验收 3–6 条)?
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
---
|
|
2
|
+
norm_id: item-detail
|
|
3
|
+
version: 1
|
|
4
|
+
updated: 2026-11-04
|
|
5
|
+
applies_to: ["*"]
|
|
6
|
+
---
|
|
7
|
+
# item-detail · 条目详情规范(机器版)
|
|
8
|
+
|
|
9
|
+
> 这是 `docs/规范/07-条目详情规范.md` 的**随包机器版**:只留「骨架 + 预算 + 判据」,不带本仓的实测读数与存量清单。
|
|
10
|
+
> `docs/` 不入 git、不进包;**本文件才是装机后真正生效的那份**,也是 `contract_version` 里被 digest 化的那份。
|
|
11
|
+
|
|
12
|
+
## 两轨骨架
|
|
13
|
+
|
|
14
|
+
### 任务卡(可执行单元 · 7 块全填)
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
<编号>|<一句话标题:动词开头,说清"做完什么">
|
|
18
|
+
|
|
19
|
+
目标:这张卡做完,解决谁的什么问题(一句话,不写做法)
|
|
20
|
+
范围:<文件:行 / 条目编号 / 章节>;包含:…;移出:…
|
|
21
|
+
禁止:<硬禁令里与本卡相关的那几条> + 本轮特禁
|
|
22
|
+
做法:分步;涉及改代码时写「先贴原文 → 改 → 再贴原文」
|
|
23
|
+
报告:四节证据(判定 / 偏离说明 / 边界自查 / 产物路径)+ 本类额外读数
|
|
24
|
+
停下:<什么情况必须停、不停会怎样>
|
|
25
|
+
验收:<可复跑读数,一条一行,能判真假>
|
|
26
|
+
关联:<需求 ref / 依赖卡 / 上游 PR / 规范 §>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### 需求条目(可评估单元 · 5 块必填)
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
<编号>|<一句话标题>
|
|
33
|
+
|
|
34
|
+
目标:要解决什么(一句话)
|
|
35
|
+
范围:包含:…;移出:…
|
|
36
|
+
约束:口径、边界、必须守的红线
|
|
37
|
+
验收:3–6 条,可判真假
|
|
38
|
+
关联:条目/卡/文档 §
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
> 需求条目可省「做法 / 报告 / 停下」——它是**要什么**,不是**怎么做**。
|
|
42
|
+
|
|
43
|
+
## 长度预算
|
|
44
|
+
|
|
45
|
+
| 对象 | 上限 | 超了怎么办 |
|
|
46
|
+
|---|---:|---|
|
|
47
|
+
| 需求条目 `description` | 1200 字符 | 把细节挪进条目级的卡或文档,正文只留指针 |
|
|
48
|
+
| 任务卡 `description` | 800 字符 | 同上 |
|
|
49
|
+
| `acceptance` | 3–6 条 | 超过 6 条说明这件事该拆成两张卡 |
|
|
50
|
+
|
|
51
|
+
**禁止整段粘源文档**:写 `见 <path> §x`,不要复制正文。整段粘贴是 2000 字符截断的直接来源。
|
|
52
|
+
|
|
53
|
+
## 反例(真出现过)
|
|
54
|
+
|
|
55
|
+
| 反例 | 为什么坏 |
|
|
56
|
+
|---|---|
|
|
57
|
+
| 一段散文讲背景、方案、验收混在一起 | 读者要从散文里抠「范围」和「验收」,抠出来还不一致 |
|
|
58
|
+
| `acceptance` 留空,验收写在正文里 | 服务端只认字段;空字段=「没有验收」,正文写了不算 |
|
|
59
|
+
| 正文写一遍验收、`acceptance` 字段又写一遍且措辞不同 | 两个源,必然走样(同一件事只准一个源) |
|
|
60
|
+
| 描述正好 2000 字符、结尾断在半个词上 | 早期导入的截断残片;界面会标「残片」,别当完整描述引用 |
|
|
61
|
+
|
|
62
|
+
## 自检(写完逐条过)
|
|
63
|
+
|
|
64
|
+
1. 第一行是不是 `<编号>|一句话`?没有编号就先分配再写。
|
|
65
|
+
2. 「范围」是否**同时**写了「包含」与「移出」?只写包含=边界没定。
|
|
66
|
+
3. 「验收」的每一条,拿给别人能不能**判真假**?不能就是没写完。
|
|
67
|
+
4. 有没有整段粘文档?有就改成指针。
|
|
68
|
+
5. 字符数是否在预算内(需求 ≤1200 / 卡 ≤800)?
|
|
69
|
+
|
|
70
|
+
## 这条规范自己怎么改
|
|
71
|
+
|
|
72
|
+
默认副本随包分发;项目里可复制一份到 `<工作区>/.taskboard/norms/` 自行修改。
|
|
73
|
+
**改正文必须同时 bump `version`**,否则 digest 校验会判定「规范被偷偷改了」,写操作会被按过期契约拦下。
|
package/spec/norms/manifest.json
CHANGED
|
@@ -30,6 +30,13 @@
|
|
|
30
30
|
"digest": "3b7596bf7bd8c21367e80bc08da6fe332d35ff4faf73f570ae8982c6fdb76371",
|
|
31
31
|
"file": "spec/norms/flow.md"
|
|
32
32
|
},
|
|
33
|
+
{
|
|
34
|
+
"norm_id": "item-detail",
|
|
35
|
+
"version": 1,
|
|
36
|
+
"updated": "2026-11-04",
|
|
37
|
+
"digest": "d499289758145cd2e5e411f94579786c00a7332349429e4d252536de26d7963f",
|
|
38
|
+
"file": "spec/norms/item-detail.md"
|
|
39
|
+
},
|
|
33
40
|
{
|
|
34
41
|
"norm_id": "project-defaults",
|
|
35
42
|
"version": 1,
|
package/src/core/contract.mjs
CHANGED
|
@@ -22,8 +22,14 @@ import path from "node:path";
|
|
|
22
22
|
|
|
23
23
|
import { TbError } from "./errors.mjs";
|
|
24
24
|
|
|
25
|
-
/**
|
|
26
|
-
|
|
25
|
+
/**
|
|
26
|
+
* 随包分发的机器规范(缺一份即 `NORM_NOT_FOUND`)。
|
|
27
|
+
*
|
|
28
|
+
* `item-detail`(卡 `-216` / 需求 `R160`,2026-11-04):`docs/规范/07-条目详情规范.md` 的随包机器版 ——
|
|
29
|
+
* `docs/` 被 gitignore ⇒ 没有 git 历史、不进包、没有 version/digest,`NORM_STALE` 护不到它;
|
|
30
|
+
* 收进这里之后它才真正参与 `contract_version`。
|
|
31
|
+
*/
|
|
32
|
+
export const NORM_IDS = Object.freeze(["flow", "card-update", "doc-editing", "acceptance", "project-defaults", "item-detail"]);
|
|
27
33
|
|
|
28
34
|
/** 参与 contract_version 的门配置项(顺序固定 ⇒ 可复现)。 */
|
|
29
35
|
export const GATE_NAMES = Object.freeze(["attribution", "authorization", "review", "humanReview"]);
|
|
@@ -40,9 +46,12 @@ export function sha256(text) {
|
|
|
40
46
|
* 只认最小 YAML 子集(`key: value` / `key: [a, b]` / 数字 / 引号串)——本仓规范就是这么写的,
|
|
41
47
|
* 引完整 YAML 解析器会把「机器规范的形状」变成第三方依赖的版本风险。
|
|
42
48
|
*
|
|
49
|
+
* `allowUnknown`:只给**项目副本**用 —— 用户在自己目录里多放一份 `notes.md` 不该把整个看板炸掉
|
|
50
|
+
* (卡 `-216`:宁可忽略陌生文件,也不要 `NORM_INVALID` 把读写全挡了)。
|
|
51
|
+
*
|
|
43
52
|
* @returns {{meta:{norm_id:string,version:number,updated:string,applies_to:string[]}, body:string, digest:string}}
|
|
44
53
|
*/
|
|
45
|
-
export function parseNormDoc(text, file = "<norm>") {
|
|
54
|
+
export function parseNormDoc(text, file = "<norm>", { allowUnknown = false } = {}) {
|
|
46
55
|
const raw = String(text ?? "").replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
|
|
47
56
|
if (!raw.startsWith("---\n")) throw new TbError("NORM_INVALID", `规范缺 frontmatter:${file}`, { file });
|
|
48
57
|
const end = raw.indexOf("\n---\n", 4);
|
|
@@ -58,7 +67,7 @@ export function parseNormDoc(text, file = "<norm>") {
|
|
|
58
67
|
meta[key] = parseScalar(line.slice(idx + 1).trim());
|
|
59
68
|
}
|
|
60
69
|
const normId = String(meta.norm_id ?? "");
|
|
61
|
-
if (!NORM_IDS.includes(normId)) {
|
|
70
|
+
if (!NORM_IDS.includes(normId) && !allowUnknown) {
|
|
62
71
|
throw new TbError("NORM_INVALID", `规范 norm_id 非法:${file} · ${JSON.stringify(meta.norm_id)}`, { file, allowed: NORM_IDS });
|
|
63
72
|
}
|
|
64
73
|
if (!Number.isInteger(meta.version) || meta.version < 1) {
|
|
@@ -93,16 +102,17 @@ function stripQuotes(s) {
|
|
|
93
102
|
* 读一个规范目录(`spec/norms/*.md`)。
|
|
94
103
|
*
|
|
95
104
|
* @param {string} dir
|
|
96
|
-
* @param {{requireAll?: boolean}} [opts] `requireAll`(默认 true
|
|
105
|
+
* @param {{requireAll?: boolean}} [opts] `requireAll`(默认 true)=`NORM_IDS` 必须齐;单测造夹具与
|
|
106
|
+
* **读项目副本**(缺项要逐份回落包内)时必须传 `false`。
|
|
97
107
|
*/
|
|
98
|
-
export function loadNorms(dir, { requireAll = true } = {}) {
|
|
108
|
+
export function loadNorms(dir, { requireAll = true, allowUnknown = false } = {}) {
|
|
99
109
|
if (!dir || !existsSync(dir)) throw new TbError("NORM_NOT_FOUND", `机器规范目录不存在:${dir}`, { dir });
|
|
100
110
|
const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
|
|
101
111
|
const norms = [];
|
|
102
112
|
const seen = new Map();
|
|
103
113
|
for (const file of files) {
|
|
104
114
|
const abs = path.join(dir, file);
|
|
105
|
-
const parsed = parseNormDoc(readFileSync(abs, "utf8"), abs);
|
|
115
|
+
const parsed = parseNormDoc(readFileSync(abs, "utf8"), abs, { allowUnknown });
|
|
106
116
|
const prev = seen.get(parsed.meta.norm_id);
|
|
107
117
|
if (prev) throw new TbError("NORM_INVALID", `norm_id 重复:${parsed.meta.norm_id}(${prev} / ${abs})`, { normId: parsed.meta.norm_id });
|
|
108
118
|
seen.set(parsed.meta.norm_id, abs);
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 随包人读文档(`spec/docs/`)与**项目副本**的位置解析 / 物化 —— 卡 `-220` / 需求 `R161`
|
|
3
|
+
*
|
|
4
|
+
* ## 与 `norms.mjs` 的分工(别合并)
|
|
5
|
+
* - `norms.mjs`:**机器规范**(`spec/norms/`)。它的正文被 digest 进契约 ⇒ 改正文必须 bump
|
|
6
|
+
* `version`,否则写操作按旧契约被拦。它是**会改变系统行为**的那一份。
|
|
7
|
+
* - 本文件:**人读文档**(`spec/docs/`,开局 / 流程 / 条目 + 模板)。改了**不影响契约、不影响门禁**,
|
|
8
|
+
* 只是「照着做」的说明书。两者放同一张配置卡会让人以为改文档会改行为,所以刻意分开。
|
|
9
|
+
*
|
|
10
|
+
* ## 三处位置(用户要的「可查可看可改」)
|
|
11
|
+
* 1. **包内默认**:随包(`<安装目录>/spec/docs`)—— 只读,升级即被覆盖;
|
|
12
|
+
* 2. **项目存放**:默认 `<工作区>/.taskboard/docs`,**可改**(项目设置 `envConfig.docsDir`);
|
|
13
|
+
* 3. **生效来源**:项目副本存在时以它为准;否则回落包内(逐文件比对,缺的从包内列出来)。
|
|
14
|
+
*
|
|
15
|
+
* ## 纪律
|
|
16
|
+
* - 物化**只在显式调用时**发生(`materializeProjectDocs`),建项目不静默写用户工作区;
|
|
17
|
+
* - 已存在的文件默认**不覆盖**(`kept`),要覆盖必须显式 `overwrite: true`(「恢复默认」按钮);
|
|
18
|
+
* - 目录可不存在:视图层如实回 `exists: false`,不替用户创建。
|
|
19
|
+
*/
|
|
20
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
|
|
21
|
+
import path from "node:path";
|
|
22
|
+
|
|
23
|
+
import { TbError } from "./errors.mjs";
|
|
24
|
+
|
|
25
|
+
/** 项目副本相对工作区的默认位置。 */
|
|
26
|
+
export const PROJECT_DOCS_SUBDIR = path.join(".taskboard", "docs");
|
|
27
|
+
|
|
28
|
+
/** 副本目录里用的 README(**新增**于副本,不进包内默认目录,避免包内多一份自述)。 */
|
|
29
|
+
const PROJECT_README = `# 本项目的开局与流程文档(可改)
|
|
30
|
+
|
|
31
|
+
这里是**本项目的副本**,来源是任务工作台随包分发的默认文档(开局 / 流程 / 条目 + 模板)。
|
|
32
|
+
看板「文档与规范位置」优先读这里;缺哪份就回落用安装包里那份(不会报错)。
|
|
33
|
+
|
|
34
|
+
- 改这里的 \`.md\` **不会**改变看板行为(门禁与契约只吃 \`spec/norms/\` 的机器规范);
|
|
35
|
+
- 这些文档是写给人看的:可以直接按自己项目的习惯改,删到只剩需要的几份也行;
|
|
36
|
+
- 要不要把本目录 \`git add\` 进仓库由你定:想团队共享就入库,只想本机生效就加进 \`.gitignore\`。
|
|
37
|
+
`;
|
|
38
|
+
|
|
39
|
+
/** @param {string|null|undefined} workspacePath */
|
|
40
|
+
export function projectDocsDir(workspacePath) {
|
|
41
|
+
const ws = typeof workspacePath === "string" ? workspacePath.trim() : "";
|
|
42
|
+
if (!ws) return null;
|
|
43
|
+
return path.join(ws, PROJECT_DOCS_SUBDIR);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* 覆盖目录解析:绝对路径直接用;相对路径按工作区解析(空 ⇒ null = 用默认)。
|
|
48
|
+
* 之所以允许相对:项目里常想写 `.taskboard/docs` 这种可入库的路径,而不是钉死本机绝对路径。
|
|
49
|
+
*/
|
|
50
|
+
export function resolveOverrideDir(overrideDir, workspacePath) {
|
|
51
|
+
const raw = typeof overrideDir === "string" ? overrideDir.trim() : "";
|
|
52
|
+
if (!raw) return null;
|
|
53
|
+
if (path.isAbsolute(raw)) return path.normalize(raw);
|
|
54
|
+
const ws = typeof workspacePath === "string" ? workspacePath.trim() : "";
|
|
55
|
+
if (!ws) throw new TbError("WORKSPACE_MISSING", "存放位置写的是相对路径,但项目未配置工作区目录 ⇒ 无法解析");
|
|
56
|
+
return path.normalize(path.join(ws, raw));
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** 递归列 md(副本里可能有 assets/ 子目录)。 */
|
|
60
|
+
export function listDocs(dir) {
|
|
61
|
+
if (!dir || !existsSync(dir)) return [];
|
|
62
|
+
const out = [];
|
|
63
|
+
const walk = (d, base) => {
|
|
64
|
+
for (const name of readdirSync(d).sort()) {
|
|
65
|
+
const abs = path.join(d, name);
|
|
66
|
+
if (statSync(abs).isDirectory()) walk(abs, base);
|
|
67
|
+
else if (name.endsWith(".md")) out.push(path.relative(base, abs));
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
walk(dir, dir);
|
|
71
|
+
return out.sort();
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 只读视图:包内默认 / 项目存放 / 生效来源。
|
|
76
|
+
* @param {{packagedDir:string, workspacePath?:string|null, overrideDir?:string|null}} input
|
|
77
|
+
*/
|
|
78
|
+
export function docsView({ packagedDir, workspacePath = null, overrideDir = null }) {
|
|
79
|
+
const defaultDir = projectDocsDir(workspacePath);
|
|
80
|
+
const resolvedOverride = resolveOverrideDir(overrideDir, workspacePath);
|
|
81
|
+
const projectDir = resolvedOverride ?? defaultDir;
|
|
82
|
+
const packagedFiles = listDocs(packagedDir);
|
|
83
|
+
const projectFiles = listDocs(projectDir);
|
|
84
|
+
const hasProjectCopy = projectFiles.length > 0;
|
|
85
|
+
return {
|
|
86
|
+
packaged: { dir: packagedDir, files: packagedFiles },
|
|
87
|
+
project: {
|
|
88
|
+
dir: projectDir,
|
|
89
|
+
dirIsOverride: Boolean(resolvedOverride),
|
|
90
|
+
exists: Boolean(projectDir && existsSync(projectDir)),
|
|
91
|
+
files: projectFiles,
|
|
92
|
+
},
|
|
93
|
+
effective: hasProjectCopy ? { source: "project", dir: projectDir } : { source: "packaged", dir: packagedDir },
|
|
94
|
+
missingInProject: hasProjectCopy ? packagedFiles.filter((f) => !projectFiles.includes(f)) : [],
|
|
95
|
+
workspacePath: workspacePath ?? null,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* 把包内默认文档复制成项目副本(显式动作)。
|
|
101
|
+
* @param {{packagedDir:string, workspacePath?:string|null, overrideDir?:string|null, overwrite?:boolean}} input
|
|
102
|
+
*/
|
|
103
|
+
export function materializeProjectDocs({ packagedDir, workspacePath = null, overrideDir = null, overwrite = false }) {
|
|
104
|
+
const resolvedOverride = resolveOverrideDir(overrideDir, workspacePath);
|
|
105
|
+
const dir = resolvedOverride ?? projectDocsDir(workspacePath);
|
|
106
|
+
if (!dir) throw new TbError("WORKSPACE_MISSING", "项目未配置工作区目录 ⇒ 无法生成文档副本;请先在「配置 → 当前绑定」填工作区");
|
|
107
|
+
if (!existsSync(packagedDir)) throw new TbError("DOCS_NOT_FOUND", `随包文档目录不存在:${packagedDir}`);
|
|
108
|
+
mkdirSync(dir, { recursive: true });
|
|
109
|
+
const written = []; const kept = [];
|
|
110
|
+
for (const rel of listDocs(packagedDir)) {
|
|
111
|
+
const target = path.join(dir, rel);
|
|
112
|
+
if (existsSync(target) && !overwrite) { kept.push(rel); continue; }
|
|
113
|
+
mkdirSync(path.dirname(target), { recursive: true });
|
|
114
|
+
copyFileSync(path.join(packagedDir, rel), target);
|
|
115
|
+
written.push(rel);
|
|
116
|
+
}
|
|
117
|
+
const readme = path.join(dir, "README.md");
|
|
118
|
+
// 包内也有 README:上面已复制成包内版本;这里只在「包内没有 README」时补项目自述,避免互相覆盖。
|
|
119
|
+
if (!existsSync(readme)) { writeText(readme, PROJECT_README); written.push("README.md"); }
|
|
120
|
+
return { dir, written, kept, count: listDocs(dir).length };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function writeText(abs, text) {
|
|
124
|
+
mkdirSync(path.dirname(abs), { recursive: true });
|
|
125
|
+
writeFileSync(abs, text, "utf8");
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** 读一份文档正文(配置页「看一眼」用,只读)。 */
|
|
129
|
+
export function readDocFile(dir, rel) {
|
|
130
|
+
const safe = String(rel ?? "").replace(/^[/\\]+/, "");
|
|
131
|
+
if (!safe || safe.includes("..")) throw new TbError("USAGE_ERROR", "非法文档路径");
|
|
132
|
+
const abs = path.join(dir, safe);
|
|
133
|
+
if (!existsSync(abs)) throw new TbError("DOCS_NOT_FOUND", `文档不存在:${safe}`);
|
|
134
|
+
return { file: safe, text: readFileSync(abs, "utf8") };
|
|
135
|
+
}
|
package/src/core/errors.mjs
CHANGED
|
@@ -88,6 +88,8 @@ export const ERROR_CATEGORY = Object.freeze({
|
|
|
88
88
|
AGENT_CANNOT_FINALIZE: EXIT.DATA,
|
|
89
89
|
|
|
90
90
|
// 冲突
|
|
91
|
+
// 卡 `-229`(R170):开局缺口投递时项目还没绑主会话 ⇒ 冲突类(先绑/重建主会话再重试;非数据错误)
|
|
92
|
+
NO_MAIN_SESSION: EXIT.CONFLICT,
|
|
91
93
|
VERSION_CONFLICT: EXIT.CONFLICT,
|
|
92
94
|
PROJECT_EXISTS: EXIT.CONFLICT,
|
|
93
95
|
// FR-03:非空项目不得删除(仍有任务/需求条目/需求文档正文)⇒ 冲突,须先清空
|