taskboard-workbench 0.3.1 → 0.3.3
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 +101 -2
- package/index.js +112 -13
- package/package.json +6 -2
- package/scripts/tb-flow.mjs +109 -8
- package/skills/taskboard-flow/SKILL.md +2 -2
- package/skills/taskboard-flow/references/injection.md +76 -29
- package/skills/taskboard-flow/references/steps/S5.md +21 -1
- 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/config.mjs +12 -3
- package/src/core/contract.mjs +17 -7
- package/src/core/data-dir-hint.mjs +52 -0
- package/src/core/docs-assets.mjs +135 -0
- package/src/core/errors.mjs +11 -0
- package/src/core/evidence.mjs +28 -0
- package/src/core/executor.mjs +27 -7
- package/src/core/executors.mjs +279 -0
- package/src/core/flow-inject.mjs +190 -0
- package/src/core/instance-lease.mjs +113 -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 +333 -36
- package/src/core/verify.mjs +39 -4
- package/src/mcp/flow-block.mjs +30 -0
- package/src/mcp/server.mjs +19 -6
- package/src/mcp/tools.mjs +99 -7
- package/src/server/api.mjs +361 -11
- package/web/app.js +1077 -82
- package/web/tokens.css +166 -28
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
# 三档装载 + 分层注入策略(档 C
|
|
1
|
+
# 三档装载 + 分层注入策略(档 C **已实现** · 默认 `off`)
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
> `
|
|
5
|
-
>
|
|
6
|
-
>
|
|
7
|
-
>
|
|
3
|
+
> ✅ **已实现(卡 `-210` / 需求 `R128`)** —— `flow_inject_policy` 现在**真有 reader**了:
|
|
4
|
+
> 判定与投递在 `src/core/flow-inject.mjs`,宿主出口在 `index.js` 的 `createSession()`,
|
|
5
|
+
> 人工出口是 `node scripts/tb-flow.mjs inject --session <id>`。
|
|
6
|
+
> **默认 `off` ⇒ 不打开开关时行为与接线前完全一致**(不构建、不投递、不写审计行)。
|
|
7
|
+
> **自证**:`node --test tests/flow-inject-policy-gap.test.mjs`(结构 + 文档口径)
|
|
8
|
+
> 与 `node --test tests/flow-inject.test.mjs` / `tests/flow-inject-wiring.test.mjs`(四档分流与三处接线)。
|
|
8
9
|
|
|
9
10
|
## 一、三档从侵入性低到高
|
|
10
11
|
|
|
@@ -12,7 +13,7 @@
|
|
|
12
13
|
| --- | --- | --- | --- |
|
|
13
14
|
| **A 开局提示词** | 人在 dsh 主会话新开一轮 | 贴 `node scripts/tb-flow.mjs start` 的输出(或 MCP prompt `taskboard.flow`,同一生成器) | ✅ 已可用 |
|
|
14
15
|
| **B 外部 agent 约定开局** | Claude Code / Codex 在**项目仓库**里开工 | 项目 `AGENTS.md` 一段「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」;片段用 `tb-flow snippet` 打印 | ✅ 已可用 |
|
|
15
|
-
| **C 宿主自动注入** | dsh 会话一创建就注入流程 | 宿主插件在 `
|
|
16
|
+
| **C 宿主自动注入** | dsh 会话一创建就注入流程 | 宿主插件在 `createSession()` 建完会话后按项目 `flow_inject_policy` 注入(`main`=完整版 / 执行·关联=摘要版 / 子 agent=不注入) | ✅ **已实现·默认 `off`**(打开方式见 §二;生效需一次宿主重载窗口) |
|
|
16
17
|
|
|
17
18
|
### 档 B 的 `AGENTS.md` 片段(`tb-flow snippet` 的输出)
|
|
18
19
|
|
|
@@ -31,46 +32,92 @@
|
|
|
31
32
|
> 三条边界:① 片段**只指路**,不复制八步正文(避免第二真源);② 路径写成占位符 —— 每个项目装在哪不一样;
|
|
32
33
|
> ③ 这段**不覆盖**项目自己的 `AGENTS.md` 规矩,只是「开工第一步」。
|
|
33
34
|
|
|
34
|
-
## 二、档 C
|
|
35
|
+
## 二、档 C 的接线形状(已生效)
|
|
35
36
|
|
|
36
|
-
|
|
|
37
|
+
| 项 | 内容 | 现在生效吗 |
|
|
37
38
|
| --- | --- | --- |
|
|
38
|
-
| `flow_inject_policy` | `off` / `main-only` / `main+exec` / `all`(**默认 `off`**) |
|
|
39
|
-
| 审计表 | `flow_injections(session_id, project_id, policy, contract_version, digest, injected_at)` | ✅
|
|
40
|
-
|
|
|
39
|
+
| `flow_inject_policy` | `off` / `main-only` / `main+exec` / `all`(**默认 `off`**) | ✅ 生效。落在 `project_settings.flow_inject_policy`(API 字段 `flowInjectPolicy`),读点=`src/core/flow-inject.mjs` |
|
|
40
|
+
| 审计表 | `flow_injections(session_id, project_id, policy, contract_version, digest, injected_at)` | ✅ 每次**投递成功**落一行;`digest = sha256(实际投出的正文)`,可事后核「投的是哪一版」 |
|
|
41
|
+
| 宿主接入位 | `index.js` 的 `createSession()` 出口(建会话 → 预置任务指令 → **注入装载块**) | ✅ 已接;`role` 由调用方声明(主会话 `main` / 任务执行会话 `exec`),**没声明就不注入** |
|
|
42
|
+
| 人工出口 | `node scripts/tb-flow.mjs inject --session <id> [--role …] [--host <url>]` | ✅ 已接(`POST /api/projects/:id/flow/inject`);审计记 `policy=manual` |
|
|
43
|
+
|
|
44
|
+
### 怎么打开 / 怎么关掉(不需要改代码)
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# 打开(只给项目主会话注入)
|
|
48
|
+
curl -X PUT http://127.0.0.1:3080/integrations/taskboard-workbench/api/projects/<项目id>/settings \
|
|
49
|
+
-H 'content-type: application/json' -d '{"flowInjectPolicy":"main-only"}'
|
|
50
|
+
# 关掉(回滚:写回 off,或删掉该字段)
|
|
51
|
+
curl -X PUT ... -d '{"flowInjectPolicy":"off"}'
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
> 非法值在**写库之前**被拒(`flow_inject_policy 只能是 …`);`flowInjectPolicy` 未传 ⇒ 保持不变。
|
|
55
|
+
> Web 配置页暂无该控件(配置页只管 `envConfig` / `teamTemplate`)—— 当前入口是上面的 API。
|
|
41
56
|
|
|
42
|
-
###
|
|
57
|
+
### 接入位长什么样(真实代码路径)
|
|
43
58
|
|
|
44
59
|
```
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
├─
|
|
49
|
-
└─
|
|
60
|
+
api.mjs POST /api/requirement…/sessions/rebind (mode=create) → port.createSession({role:"main"})
|
|
61
|
+
api.mjs POST /api/tasks/:ref/execute → port.createSession({role:"exec"})
|
|
62
|
+
└─ index.js createSession()
|
|
63
|
+
├─ sc.create({cwd}) → rename({sessionId,title}) → deliver(preset) // 原有行为,未改
|
|
64
|
+
└─ injectOpeningFlow() → src/core/flow-inject.mjs
|
|
65
|
+
├─ 读 project_settings.flow_inject_policy(缺省 off ⇒ 直接返回 policy-off)
|
|
66
|
+
├─ decideFlowInjection({policy, role}) // 纯函数:策略 × 角色矩阵
|
|
67
|
+
├─ 完整版 = buildFlowBlock().text // ★ 与 tb-flow start / MCP prompts/get 同一生成器
|
|
68
|
+
│ 摘要版 = buildFlowSummary(block) // 由同一个 block 剪裁,不另写规则
|
|
69
|
+
├─ deliver(sessionId, text) // sessionController.prompt(mode:"queue")
|
|
70
|
+
└─ store.recordFlowInjection({…六字段})
|
|
50
71
|
```
|
|
51
72
|
|
|
52
73
|
**关键:注入内容必须由同一个生成器产出** —— 否则宿主注入的、人贴的、agent 自己拉的会是三份不同的说明书。
|
|
74
|
+
守卫:`tests/flow-inject-wiring.test.mjs` 的 C1 用**独立进程**跑 `tb-flow inject`,
|
|
75
|
+
把 `tb-flow start` 的 stdout 与宿主实际投出的正文**逐字节对拍**(并核 `sha256`)。
|
|
53
76
|
|
|
54
77
|
## 三、分层注入策略(按会话角色给不同长度)
|
|
55
78
|
|
|
56
|
-
|
|
|
79
|
+
| 会话类型(`role`) | 注入什么 | 为什么 |
|
|
57
80
|
| --- | --- | --- |
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
81
|
+
| **项目主会话**(`main`) | 完整版:八步全文 + 五条硬规则 + 错误码索引 | 它要做判断、要拆卡、要回填 |
|
|
82
|
+
| **执行会话**(`exec`) | **摘要版(≤ 300 tokens)**:当前步 + 两道门 + 常见错误码处置 | 它只需要"别把 done 写了"这类护栏 |
|
|
83
|
+
| **关联会话**(`related`) | 摘要版(同 `exec`) | 同上;只在 `all` / `manual` 下注入 |
|
|
84
|
+
| **子 agent 会话**(`subagent`) | **不注入**(**硬规则**,`manual` 也不放开) | 子 agent 由父会话派活,注入只会稀释它自己的任务上下文 |
|
|
85
|
+
|
|
86
|
+
策略 × 角色(✓=注入):
|
|
61
87
|
|
|
62
|
-
|
|
88
|
+
| 角色 \ 策略 | `off` | `main-only` | `main+exec` | `all` | `manual` |
|
|
89
|
+
| --- | --- | --- | --- | --- | --- |
|
|
90
|
+
| `main` | — | ✓ 完整版 | ✓ 完整版 | ✓ 完整版 | ✓ 完整版 |
|
|
91
|
+
| `exec` | — | — | ✓ 摘要版 | ✓ 摘要版 | ✓ 摘要版 |
|
|
92
|
+
| `related` | — | — | — | ✓ 摘要版 | ✓ 摘要版 |
|
|
93
|
+
| `subagent` | — | — | — | — | — |
|
|
94
|
+
|
|
95
|
+
`manual` 只给人工一次性投递用(显式绕过 `off`,所以审计必须能把它与自动注入区分开)。
|
|
96
|
+
角色未知(调用方没声明)⇒ **不注入**(`role-unknown`):宁可少注,不可把完整版塞进执行会话。
|
|
97
|
+
|
|
98
|
+
摘要版的真实形状(由 `buildFlowSummary(block)` 生成,长度实测 ≈164 tokens / 374 字符):
|
|
63
99
|
|
|
64
100
|
```
|
|
65
101
|
任务看板主流程(摘要)
|
|
66
|
-
当前步:<S?,来自
|
|
67
|
-
|
|
102
|
+
当前步:<S?,来自 buildFlowBlock().nextStep>
|
|
103
|
+
两道门:done 只能人点(GOVERNANCE_AGENT_DONE)· backlog→todo 是人工授权(EXECUTION_NOT_AUTHORIZED)
|
|
68
104
|
回填要带:evidence[](file/command/url/reading)+ norm_digest(norm_get "card-update")
|
|
69
105
|
契约:<contract_version>(用旧版本会落 contract-warn)
|
|
106
|
+
常见错误码:EXECUTION_NOT_ATTRIBUTED(先补归因)· CONTRACT_STALE / NORM_STALE(重取规范)· REVIEW_NOT_APPROVED(等人复核)
|
|
107
|
+
全文:`node scripts/tb-flow.mjs start`(与宿主注入同源)
|
|
70
108
|
```
|
|
71
109
|
|
|
72
|
-
|
|
110
|
+
> ⚠ 上一版本文里写的是 `AUTHORIZATION_REQUIRED` —— **本仓没有这个错误码**(真码是 `EXECUTION_NOT_AUTHORIZED`)。
|
|
111
|
+
> 摘要版要塞给人/agent 直接照做的错误码,写错等于指路指到墙上;`tests/flow-inject.test.mjs` 的 C 条把它钉住。
|
|
112
|
+
|
|
113
|
+
## 四、失败与运维边界
|
|
73
114
|
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
-
|
|
115
|
+
- **注入异常不阻断会话创建**(验收 ⑤):`injectFlow()` **从不抛错**,一律回 `{injected:false, reason}`;
|
|
116
|
+
宿主 `createSession()` 把结果塞进 `injection` 字段如实回包,会话照旧建出来。
|
|
117
|
+
- **投递成功但审计写失败** ⇒ 回 `injected:true` + `reason:"injected-audit-failed"`(**不谎报没投**,否则调用方会重复注入)。
|
|
118
|
+
- **无宿主通道**(独立进程实例):`POST /flow/inject` 回 `{delivered:false, reason:"host-unavailable", prompt:"<正文>"}`
|
|
119
|
+
—— 正文原样回带,人可以直接粘贴;CLI 同理(退出码 5,正文打到 stdout)。
|
|
120
|
+
- **生产生效仍需一次宿主重载窗口**:本轮的代码改动在仓库内(`index.js` / `api.mjs` / `store.mjs`),
|
|
121
|
+
要让**当前运行中的** `:3080` 实例用上,必须重载宿主 —— 属 AGENTS.md §3 须先报批的动作,本轮未做。
|
|
122
|
+
- **不做的事**:不碰 `~/.dsh/**`、不改任何会话创建路径(只在本插件自己的 `createSession()` 出口加一层)、
|
|
123
|
+
不把注入做成「第二真源」(正文只能来自 `buildFlowBlock()` / `buildFlowSummary(block)`)。
|
|
@@ -17,8 +17,28 @@ card_progress {
|
|
|
17
17
|
}
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
## 交付证据(另一种写入口 · 不是"进度")
|
|
21
|
+
|
|
22
|
+
`card_progress` 写的是**过程性证据**(command / url / reading)。要把**交付证据**(判定 / 偏离 / 边界 / 产物)
|
|
23
|
+
落到 `task_evidence` 表,用 `card_evidence_submit`(HTTP 侧对应 `POST /api/tasks/:ref/evidence`,同源同门):
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
card_evidence_submit {
|
|
27
|
+
card,
|
|
28
|
+
verdict: "做了什么、结论是什么",
|
|
29
|
+
deviation: "没按原计划做的部分(不写 = 隐藏信息)",
|
|
30
|
+
boundary: "未取得 / 无法判定的读数必须明说",
|
|
31
|
+
artifacts: ["docs/进度/xxx.md", "npm test 1186/1186"],
|
|
32
|
+
artifact_refs: [ { kind: "commit", ref: "57e97f9" }, { kind: "file", ref: "src/core/store.mjs" } ]
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- 四字段**缺一即拒**(`EVIDENCE_INCOMPLETE`),不会落半条;
|
|
37
|
+
- `artifact_refs` 只接受 `commit` / `file`(其余 ⇒ `INVALID_ARTIFACT_REF`);过程性证据走 `evidence[]` 那一侧;
|
|
38
|
+
- 同指纹重复提交**幂等**(`deduped: true`,不增行)。
|
|
39
|
+
|
|
20
40
|
## 判据
|
|
21
|
-
- `evidence[].kind` ∈ `file` / `command` / `url` / `reading
|
|
41
|
+
- `evidence[].kind` ∈ `file` / `command` / `url` / `reading`(`commit` 属交付证据侧),`ref` 非空;
|
|
22
42
|
- 返回 `comment.deduped === false`(第二次同样证据会是 `true`,不会刷重复评论);
|
|
23
43
|
- `card.statusAfter` 与你期望的一致;
|
|
24
44
|
- 评论正文里有 `【MCP 证据】hash=…` —— 这就是事后复核的锚点。
|
|
@@ -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/config.mjs
CHANGED
|
@@ -1,12 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* 运行期配置:数据目录解析(FR-31/FR-33)。
|
|
3
|
-
* 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR >
|
|
4
|
-
*
|
|
3
|
+
* 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR > 默认目录。
|
|
4
|
+
*
|
|
5
|
+
* 默认目录(2026-11-10 · 卡 `-236` / 需求 `R173` 改):
|
|
6
|
+
* `~/.dsh/data/taskboard-workbench`
|
|
7
|
+
* 原默认是 `os.tmpdir()/tb-workbench-mvp-a` —— 两个问题:
|
|
8
|
+
* ① **临时目录会被 macOS 定期清理** ⇒ 看板数据随时静默消失;
|
|
9
|
+
* ② dsh web 与 dsh desktop 是**两个宿主**,只要有一边没显式配 `dataDir`,就会落到
|
|
10
|
+
* 自己解析的默认位置,于是「两边看到两份库」(真机:web 264 张卡 / desktop 0 张)。
|
|
11
|
+
* 改成用户目录下的固定路径后,**两个宿主不配置也是同一份库**。
|
|
5
12
|
*/
|
|
6
13
|
import os from "node:os";
|
|
7
14
|
import path from "node:path";
|
|
8
15
|
|
|
9
|
-
export const DEFAULT_DATA_DIR = path.join(os.
|
|
16
|
+
export const DEFAULT_DATA_DIR = path.join(os.homedir(), ".dsh", "data", "taskboard-workbench");
|
|
17
|
+
/** 旧默认目录:**只用于「空库检测 / 迁移提示」**,不再作为任何写入目标。 */
|
|
18
|
+
export const LEGACY_DATA_DIR = path.join(os.tmpdir(), "tb-workbench-mvp-a");
|
|
10
19
|
export const DB_FILENAME = "taskboard.sqlite";
|
|
11
20
|
|
|
12
21
|
export function resolveDataDir({ dataDir, env = process.env } = {}) {
|