taskboard-workbench 0.2.0 → 0.3.1

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.
Files changed (36) hide show
  1. package/CHANGELOG.md +321 -0
  2. package/README.md +95 -0
  3. package/package.json +20 -6
  4. package/scripts/tb-flow.mjs +86 -0
  5. package/skills/taskboard-flow/SKILL.md +89 -0
  6. package/skills/taskboard-flow/references/errors.md +61 -0
  7. package/skills/taskboard-flow/references/injection.md +76 -0
  8. package/skills/taskboard-flow/references/steps/S0.md +31 -0
  9. package/skills/taskboard-flow/references/steps/S1.md +28 -0
  10. package/skills/taskboard-flow/references/steps/S2.md +31 -0
  11. package/skills/taskboard-flow/references/steps/S3.md +22 -0
  12. package/skills/taskboard-flow/references/steps/S4.md +25 -0
  13. package/skills/taskboard-flow/references/steps/S5.md +36 -0
  14. package/skills/taskboard-flow/references/steps/S6.md +30 -0
  15. package/skills/taskboard-flow/references/steps/S7.md +23 -0
  16. package/spec/norms/acceptance.md +36 -0
  17. package/spec/norms/card-update.md +39 -0
  18. package/spec/norms/doc-editing.md +30 -0
  19. package/spec/norms/flow.md +45 -0
  20. package/spec/norms/manifest.json +41 -0
  21. package/spec/norms/project-defaults.md +33 -0
  22. package/src/core/acceptance.mjs +62 -0
  23. package/src/core/contract.mjs +287 -0
  24. package/src/core/errors.mjs +3 -0
  25. package/src/core/evidence.mjs +86 -0
  26. package/src/core/intake.mjs +87 -24
  27. package/src/core/requirements.mjs +31 -1
  28. package/src/core/store.mjs +376 -6
  29. package/src/core/ticket-stage.mjs +162 -0
  30. package/src/mcp/flow-block.mjs +173 -0
  31. package/src/mcp/server.mjs +175 -0
  32. package/src/mcp/tools.mjs +769 -0
  33. package/src/server/api.mjs +128 -30
  34. package/src/server/server.mjs +3 -0
  35. package/web/app.js +162 -34
  36. package/web/tokens.css +12 -0
package/CHANGELOG.md CHANGED
@@ -6,6 +6,327 @@
6
6
  版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
7
7
  每个版本对应一个 annotated tag(`vX.Y.Z`)与一条 GitHub Release;npm dist-tag 与 dsh 兼容区间随版本记录。
8
8
 
9
+ ## [0.3.1] - 2026-11-04
10
+
11
+ > 主题:**7 笔攒批一次发**(`v0.3.0` 后连续攒到 6 项进包变更 + 1 项打包声明),把「卡上收口了、包里还没到」这段补齐。
12
+ > npm `latest` 由 `0.2.0` 直接对齐到本版(跳过从未发布的 `0.3.0`,D7「攒批」口径的兑现)。
13
+ > `npm test` **986 / 0**、`release-precheck` **EXIT=0**、tarball **75** 文件。
14
+
15
+ ### 新增
16
+
17
+ - **`--read-only` 回滚开关(卡 `-208` / 需求 `R153`,`260bdf6`)** —— P3 设计稿承诺的逃生口此前从未实现:
18
+ `--read-only` 下 MCP 工具面 **9 → 5**(只留只读工具),写入类工具不注册而非「注册后报错」——
19
+ 注册了就等于告诉调用方「有这条路」,而它注定失败。反向对照:不带开关时 9 个工具全在。
20
+ - **`engines.dsh` 打包声明(卡 `-212` / 需求 `R156`,`2385e11`)** —— `package.json` 增 `engines.dsh: ">=0.2.1-rc.3"`
21
+ (下限=首个实际验证过的宿主版本)。插件市场卡片的 `DSH <range>` 标签读的就是它,此前 `engines` 只有 `node`
22
+ ⇒ 卡片只能显示「未声明宿主要求」。**生效时序**:本版发布后,还要等上游 `probe-npm` 与一轮 nightly 重建索引才会显形。
23
+
24
+ ### 修复
25
+
26
+ - **「下一步」把半残回包当成「无待办动作」(卡 `-211` / 需求 `R155`,`e8c226b`)** —— 真机事故:宿主未重载时服务端仍回旧形状
27
+ `ticketStage.next = {code,title}`,而前端兜底只判 `next` 是否为 `null` ⇒ 半残回包绕过「旧版服务端」提示,
28
+ 落到 else 分支输出**错误结论**「本卡无待办动作。」(那张卡其实只差人点「完成」,且没有「完成」按钮)。
29
+ 修:判据改为**按形状**——缺 `steps/focus/actions/hint/blocker` 任一即提示「引导不完整(旧版服务端)」;
30
+ `actions: []` 仍是已收口卡的**合法**形态(空数组是真值,齐全必须回 `null`,首版自测即抓到)。
31
+ **守卫**:新增第 15 台 `tools/bench-next-step-shape.mjs`(真 headless Chrome + CDP;前置代理把详情回包降级成旧形状,
32
+ 不必真退回旧进程),A/B/C/D 四组 **11/11 PASS**;反向对照(判据退回 `if (!step)`)**9/11**、A1/A2 双红。
33
+ - **任务抽屉三处判断收敛到单一口径(卡 `-199` / 需求 `R151`,`1c83059`)** —— 「下一步 / 看护 / 诊断」不再各自打
34
+ `/next-step` 与 `/execution`(一次请求算一次、还会落库),统一消费详情里那一份 `ticketStage`;
35
+ 诊断在详情 GET 里**真实求值但零写**(`persist:false`),计数字段从已落库行补回,保住「详情 GET 无写副作用」这条不变量。
36
+
37
+ ### 变更
38
+
39
+ - **契约门切 `reject`(R-A,卡 `-209`,`9bb5fcf`)** —— 调用方带 `contract` 且版本/摘要不符时,由「照常写入 + 一条 `contract-warn` 审计」
40
+ 改为**拒绝写入**;校验整体前移到事务之前(拒绝即零副作用)。不带 `contract` 仍按 `skipped` 向后兼容。
41
+ ⚠ **这是一处行为口径变更**:靠「带错契约也能写」跑通的脚本会开始报错——请先核对调用方是否带对了 `contract`。
42
+ - **`flow_inject_policy` 明标未实现(卡 `-186` / 需求 `R141`,`ad98227`)** —— 技能文档三处(标题 / 顶部警示 / 预埋项表格)
43
+ 写明「未实现(全仓无 reader)」,并加缺口守卫 `tests/flow-inject-policy-gap.test.mjs`:扫 `src/scripts/web/cli/tools/spec`
44
+ 断言该键命中 **0**,将来接线却没更新文档即转红(反向对照:临时探针 ⇒ 2/3 转红)。
45
+
46
+ ### 移出
47
+
48
+ - **`dsh --import` shim 死代码下线(卡 `-207` / 需求 `R152`,`f1e4216`)** —— **13 文件 / +13 −538**:
49
+ 三个 shim 早已被宿主能力位取代,留着只会让人以为还有那条路;残留引用一并清理。
50
+
51
+ ### 兼容性与升级注意
52
+
53
+ - **npm `latest` 由 `0.2.0` 跳到 `0.3.1`**:registry 上**不存在 `0.3.0`**,`changelog` 仍保留其条目(它对应 `v0.3.0` tag 与源码快照)。
54
+ - **`engines.dsh = ">=0.2.1-rc.3"`**:宿主低于此版本不再满足声明(此前未声明,等于默认可装)。本版是本机验证过的形态。
55
+ - **契约门是行为变更**(上条 `-209`):升级后请重新核对 CI/脚本里的 `contract` 版本与摘要。
56
+ - **`schemaVersion` 仍为 13**(本版无表结构变更,`-197` 引入的两表已在 `0.3.0` 就位)。
57
+ - 插件市场卡片出现 `DSH >=0.2.1-rc.3` 标签**不等于**发布当天可见:需上游 `probe-npm` + 一轮 nightly 重建索引。
58
+
59
+ ## [0.3.0] - 2026-11-03
60
+
61
+ > 主题:让「待验收 → 确认」这段**先变得可信** —— 有度量、有事件、有单一口径、有结构化证据。
62
+ > 本版六张卡全部严格走看板全环(`-193` … `-198`,各带证据四节);`npm test` **974 / 0**、`release-precheck` **EXIT=0**。
63
+ > **未做**:npm publish / GitHub Release(另批);生产重载后的快照复评见 `docs/进度/`。
64
+
65
+ ### 新增
66
+
67
+ - **基线度量脚本 `tools/baseline-metrics.mjs`(卡 `-193` / 需求 `R146`)** —— 把「改善了多少」变成可复跑读数:
68
+ 快照 `.data/backup-20261103.sqlite`(sha256 `21182435…`)、**M1 拆两层**(当前在途滞留中位 **148.4h** vs 已完成周期中位 **19.1h**——
69
+ 只报一个会得出「改善 87%」的假结论)、`done` 事件覆盖 **74.2%**(漏 25.8%)、M2 **3.2**;M3/M4 **明标不可测、不写 0**。
70
+ - **阶段推导单一口径 `ticketStage()`(卡 `-196` / `-198` / 需求 `R149`)** —— 新模块 `src/core/ticket-stage.mjs`:
71
+ **不写第五套判断**,直接复用 `deriveNextStep` / `assessTask` / `latestAutoReview` / `evidenceFormatOk` 只做归一;
72
+ 显式区分 `format_ok`(四字段齐、无内容判定)与 `ready`(判定与证据/版本一致),判过又变 ⇒ `stale`。
73
+ `GET /api/tasks/:ref` 新增只读字段 `ticketStage`;任务抽屉显示交付阶段徽标,**`stale` 用警示色**。
74
+ **安全优先级**:`stale` 先于「只差你点完成」——判定过期时不许邀请人确认他没看过的那一版。
75
+ - **交付物证据结构化 + 授权快照(卡 `-197` / 需求 `R150`)** —— `task_evidence`(四字段:判定 / 偏离 / 边界 / 产物 + `artifact_refs` + actor + task_version)
76
+ 与 `task_mandates`(**append-only**:只有 insert,范围变大 = 新行)。**门在事务前**:四字段缺一即 `EVIDENCE_INCOMPLETE` 且零落库;
77
+ `artifact_refs` 一条解不开即整体 `unresolved`,不进 `format_ok`。授权快照覆盖**三条认领入口**
78
+ (`claimTask` / 看板 `PATCH→in_progress` / 团队通道 `teamSetTaskStatus→in_progress`)。
79
+
80
+ ### 修复
81
+
82
+ - **状态事件漏记(卡 `-194` / 需求 `R147`)** —— `teamSetTaskStatus` 与 `applyTeamTaskOutcome`(completed / failed)此前**直接写列不发事件**,
83
+ 实测 175 次完成类变更中 **46 次(26%)无 `status_changed`**;而诊断 / 看护 / 通知 / M1 度量**全部**建在事件流上。
84
+ 现两处落点补齐(同一状态重复写不产生假事件)。
85
+ - **待验收「发起评审」时间缺失(卡 `-195` / 需求 `R148`)** —— 实测 16 张 `in_review` 中 **10 张 `review_requested_at` 为空**,
86
+ M1 因此无从计算。现三条进 `in_review` 的路径(看板 PATCH / 执行侧与团队通道 / 团队回流)都补记,**幂等**(不覆盖首值)、
87
+ **不涨 version**(记账字段不污染乐观锁)。
88
+
89
+ ### 兼容性与升级注意
90
+
91
+ - **`schemaVersion` 12 → 13**:新增 `task_evidence` / `task_mandates` 两表,`create table if not exists` **可重入**;
92
+ 已在真实库副本上验证(连开两次 `schema=13`、217 条任务不变、无报错)。重启宿主即自动迁移。
93
+ - **`review_requested_at` 只对新增生效**:存量 10 张 `in_review` 空值**不自动回填**(属 P0①-b,需人工执行补发)。
94
+ - **`ticketStage` 是新增只读字段**:既有 `task` / `comments` / `reviewEvidence` 语义未变;详情 GET **零写副作用**(新增测试断言)。
95
+ - **`ready` / `stale` 两态暂不可达**:判定层(`decision_log`)属 0-C,未建表前 `decision` 显式 `null`,不伪造判定。
96
+ - 任务抽屉的「下一步 / 看护 / 诊断」三处旧判断**本版未合并**(沙箱内无浏览器验证台,盲删即静默删功能)⇒ 见 `R151`。
97
+
98
+ ## [0.2.3] - 2026-10-30
99
+
100
+ > 本版只有一条修复:**把「只影响人读」的错标改对**(数据一直是对的)。
101
+ > 触发:`-176` 证据评论登记的已知限制 —— `REQUIREMENT_SOURCES` 已含 `mcp`,但前端来源文案只认
102
+ > `intake / elaborated-ai / elaborated-rule`,其余一律回落「手工」。
103
+
104
+ ### 修复
105
+
106
+ - **需求条目来源标签:`mcp` 被错标为「手工」(卡 `-179` / 需求 `R134`)** ——
107
+ MCP 建的条目在**列表胶囊**与**详情「来源」字段**都显示成「手工」,人会以为是自己手工建的,
108
+ 进而误判「谁该补验收」。数据侧(`source="mcp"`)自 0.2.2 起就是对的,**只有人读的那一层在撒谎**。
109
+ 修:`web/app.js` 两处来源文案三元各补 `mcp → "MCP"` 分支(列表 `srcLabel` / 详情 `srcLabel`),
110
+ 其余四档文案(资料索引 / AI / 规则 / 兜底手工)**零改动**。
111
+ **守卫**:新增真渲染验证台 `tools/bench-req-source-label.mjs`(临时 `dataDir` + 随机端口 + 真 headless Chrome + CDP,
112
+ 读渲染后 DOM 的**列表胶囊**与**详情字段**实际文本,A/B/C/D 四条 + `TB_BENCH_WEB_DIR` 反向对照);
113
+ 配套 `tests/bench-req-source-label-coverage.test.mjs`(5 条)进 `npm test`:含**源码守卫**(两处三元都必须有 `mcp` 分支、
114
+ 兜底档必须仍是「手工」)+ 台子不被削薄(隔离形态 / 沙箱自检 / 五档种子 / 反向对照入口 / 退出码契约)。
115
+ **读数**:修复前 A/B 双红(`mcp=手工`、详情`手工`)→ 修复后 **4/4 PASS**(`mcp=MCP`,intake 详情仍「资料索引(引入)」);
116
+ 反向对照(注入旧口径)**2/4**(A/B 转红);源码守卫同样反向验证(删掉 `mcp` 分支 ⇒ 断言失败)。
117
+
118
+ ## [0.2.2] - 2026-10-29
119
+
120
+ > 本版是 **0.2.1 之后的第一个小版本**(未发布 npm / 未出 Release 时为「就绪」状态)。
121
+ > 主题:**把 0.2.1 收口时登记的四张隔离卡清掉**(软链漏扫 / 去重键陈旧 / 两条无约束写入口)。
122
+
123
+ ### 修复
124
+
125
+ - **intake 扫描器的符号链接静默漏扫(卡 `-175`)** —— `Dirent.isFile()` 对符号链接**恒为 false**,
126
+ 故 `walk()` 的 `isFile()/isDirectory()` 双分支把软链文档静默漏掉(本仓 `docs/团队agent.md → ../spec/团队agent.md`
127
+ 从未进索引,`docsTotal` 少 1 且无任何读数提示)。
128
+ 修:软链走 `stat` 跟随判类型 → `realpath` **越界判定**(必须仍在 root 内)→ **祖先链**环路保护;
129
+ 跳过的每一条进 `symlinks.skipped[{relPath,target,reason}]`(九种 reason),跟随的计入 `followed`,`files[]` 带 `symlink:true`。
130
+ 顺带删掉 `tools/audit-intake.mjs` 自带的 `findSymlinks()`(两份实现必然漂移,改读模块记账)。
131
+ **读数更正**:软链修完后 `docsTotal` 是 **391**(不是先前预估的 390)—— 用同版本差集实测钉住:
132
+ HEAD `390` ↔ 新版 `391`、`added=[docs/团队agent.md]`、`removed=[]`;口径漂移的原因是「390」按当时 2 份新文档算的,
133
+ 此后又落了 1 份进度文档。**登记到 0.2.2 发布时,基线应再按当次 docs 数量复算**(本轮收尾时为 392,因又新增 1 份轮次文档)。
134
+ - **改条目标题时 `norm_title` 不同步(卡 `-178`)** —— 标题去重键停在旧值 ⇒ 改名后
135
+ `confirmRequirementCandidates` 把同一条目当「新条目」再插一次。存量 `normTitleMismatch = 0`,属**防新增**。
136
+
137
+ ### 新增
138
+
139
+ - **acceptance 显式缺口标记(卡 `-176` / `-177` · 口径 X)** —— 两条无约束写入口(MCP `requirement_upsert` 与
140
+ HTTP `POST/PATCH /api/requirements/items`)此前「没给验收」与「给了空串」在调用方眼里都是成功。
141
+ 现:`acceptanceSet` 回包字段 **永远**反映写入后状态;缺省时落 `governance_audit`
142
+ (`action = requirement-acceptance-missing`,`reason` 记入口名)⇒「当初给没给验收」可事后 join 审计查出来。
143
+ **刻意不做**:不设必填、不改 schema(129 条里 99 条 `acceptance` 为空,必填会一刀切破「改标题」这类无关操作;
144
+ 审计 join 可查,schema 迁移不可逆)。审计只在**本次写入真碰 `acceptance`** 时落,避免每次改标题都添一行。
145
+ - **`REQUIREMENT_SOURCES` 补 `mcp`** —— MCP 建的条目不再落默认 `manual`,「人手建 / MCP 建」在库里可辨。
146
+
147
+ ### 已知限制(本版未做)
148
+
149
+ - 前端来源标签仍无 `mcp` 分支 ⇒ 列表里 MCP 建的条目会显示成「手工」(**数据正确、标签错标**,2 行改动,待 UI 卡)。
150
+ - MCP 回包不暴露 `source`(`requirementSnapshot` 只回内容字段)。
151
+
152
+ ## [0.2.1] - 2026-10-29
153
+
154
+ > 发版纪律(2026-10-29 起):`0.2.0` 已对外冻结,**此后任何产品代码改动都要走新版本号 + 本文件**,
155
+ > 不得静默混进工作区(否则「registry 上的 0.2.0」与工作区语义漂移)。
156
+ > 发布时把本节改成 `## [0.2.1] - <日期>` 并复查 `docs/发布与收录/02` §5.0 的顺序铁律。
157
+
158
+ ### 变更(口径)
159
+
160
+ - **条目化的失败语义与数量口径(卡 `-169` P4②)** —— 真机上一份「资料索引」类文档走规则拆解,
161
+ 产出 **4213 条**、落库 **100 条** `pending` 候选,其中 **0 条**是真需求(全是文件清单行)。
162
+ 两条根因一起改掉:
163
+
164
+ | 项 | 旧 | 新 |
165
+ | --- | --- | --- |
166
+ | `mode:"auto"` 在 AI 不可用时 | **静默跑规则并落库**,只加 `degraded:true` 标注 | **拒绝 `AI_UNAVAILABLE`、零落库**;要降级必须**显式** `{"mode":"auto","fallback":"rule"}` |
167
+ | `limit` | 默认 **100**,且 **body 传了也不生效** | **从 body 透传**,默认 **20**、硬顶 **200** |
168
+ | `mode:"rule"` | 一点就写,无预览 | 支持 `{"mode":"rule","dryRun":true}` ⇒ **只回预览、零落库**(HTTP 200) |
169
+
170
+ ⚠️ **这是有意的收紧**:宿主没配 LLM 之前,看板的「AI 拆解」会**明确报错**而不是"假装成功"。
171
+ 这正是要的 —— 把「其实没 AI」从「看起来成功」改成「明确失败」。
172
+
173
+ ### 新增
174
+
175
+ - **验证台 `tools/bench-market-install.mjs`(第 14 台,11 项)—— 市场安装形态验收**:
176
+ `npm pack` → 解包 → 装进**隔离 profile**(临时 `DSH_HOME`)→ 真 `dsh` 起宿主 → 真 HTTP。
177
+ 判据是「**插件化 = 拿到宿主会话通道**」:`host.capabilities` 非空 + `create/sessions` 在 +
178
+ **真建出项目主会话** + `scopeFactory=ready`;**反向对照**=同一份打包代码 `node src/server/server.mjs`
179
+ 独立起 ⇒ `capabilities === null`。它补的盲区:以往「插件能用」的证据全来自**仓库软链**,
180
+ `package.json#files[]` 少写一项也照样绿,而市场安装拿的是打包产物。
181
+ - **独立进程启动即声明形态**:`src/server/server.mjs` 多打一行
182
+ `[tb] mode=standalone · 无 DSH 宿主会话通道(投递/建会话/派发团队不可用;需要这些能力请用 DSH 内的 /integrations/taskboard-workbench)`,
183
+ 把「为什么按钮是灰的」提前到启动那一刻。
184
+
185
+ - **规则拆解「先预览再确认」**(前端):「规则拆解(先预览)」→ 页面内预览块(写多少条 / 前 10 条标题 /
186
+ 「规则拆解会把文件清单行也当需求」警示)→「确认写入 / 取消」。
187
+ **不用 `window.confirm`**:IAB 里原生弹窗会被自动拒绝 ⇒ 变成「点了没反应」(见 `docs/发布与收录/06` §E3)。
188
+ - **验证台 `tools/bench-elaborate-guard.mjs`**(第 13 台)—— 真 headless Chrome 读渲染后 DOM,**10 项**:
189
+ 两个按钮在 / 无 AI 点 AI 拆解⇒明确报错且零落库 / 点预览⇒预览块出现且零落库 / 真列 10 条 /
190
+ 「确认写入 20 条」/ 确认后落库 **20** 条 / 页面回报 `候选=20` / 预览块消失。
191
+ 含 `TB_BENCH_WEB_DIR` 反证入口(旧 web ⇒ **7/10 转红**)。
192
+ - **守卫测试 `tests/elaborate-guard.test.mjs`**(11 条):① 零落库 ② 显式 `fallback:"rule"` 才降级
193
+ ③ `dryRun` 零落库且 `preview` 非空 ④ `limit:5` 恰好 5 条 · 默认 20 · 硬顶 200 · 非法值报错
194
+ ⑤ `dryRun` 只对 `rule`、`fallback` 只接受 `rule`、`mode` 只接受三值 ⑥ 反向对照。
195
+
196
+ ### 变更(实现细节)
197
+
198
+ - AI 抛出的错误**保留上游 `code`**(如 `AI_OUTPUT_INVALID`)而不是一律压成 `AI_UNAVAILABLE` ——
199
+ 排障要能区分「没有 AI」和「AI 回了没法解析的东西」。
200
+ - `clampElaborateLimit` 放在 `src/core/requirements.mjs`(纯模块),`store.mjs` 转发 ——
201
+ 这样 `src/server/api.mjs` 取口径时不会把 `node:sqlite` 拽进纯路由层。
202
+
203
+ ### 新增(P1 · 契约快照与机器规范 · 卡 `-170`)
204
+
205
+ - **机器执行规范 `spec/norms/`(运行时唯一真源,随包分发)** —— 五份:
206
+ `flow`(八步 S0–S7 + 四道门 + 错误码处置)/ `card-update`(状态流转 + 回填证据 + 禁止项)/
207
+ `doc-editing`(每轮收尾 + 写入纪律 + 命名)/ `acceptance`(三层判据 + 反向对照 + 合格证据)/
208
+ `project-defaults`(只允许 3 类覆盖:`verifyCommand` / `workspacePath` / `notApplicable`)。
209
+ 每份带 `norm_id / version / updated / applies_to` frontmatter,`manifest.json` 记 `digest = sha256(正文)`。
210
+ `docs/规范/*.md` 仍是**给人读的开发文档**、永不入 git、**不作运行时真源**。
211
+ - **契约快照 `src/core/contract.mjs`(纯计算 + 纯读文件,不写库)** ——
212
+ `contract_version = f(需求文档 digest, 规范 digest×版本, 门配置)`;`diffContract` 能回答「**哪份文件变了**」
213
+ (`changed[]` 指到 `spec/norms/card-update.md` 这一级);`staleError` 固定 `409 CONTRACT_STALE` 形状:
214
+ `your_version` / `current_version` / `changed` / `snapshot` / `remedy`。
215
+ - **两个端点** —— `GET /api/projects/:id/contract`(**零副作用**:现算 + 与基线比对,不落库)·
216
+ `POST /api/projects/:id/contract/recheck`(重算并落基线,`project_contract` 的唯一写入点)。
217
+ - **构建工具 `tools/build-norms.mjs`** —— 生成 manifest;`--check` 供 CI / 守卫。**正文变了但 `version`
218
+ 没 bump ⇒ 硬拒写入(退出码 1,不覆盖 manifest)** —— 否则等于用 manifest 把守卫抹平。
219
+ - **两张表(schema `11 → 12`)** —— `project_contract`(每项目一行契约基线,**只是缓存不是真源**)·
220
+ `flow_injections`(装载块注入审计位;D3 档 C 推迟,默认 `off` 不写)。
221
+
222
+ ### 新增(P1.5 · D2 `warn` 档 · 2026-10-29)
223
+
224
+ - **写路径上的契约校验(内核层,不阻断)** —— `evaluateSubmittedContract()` 纯判据 +
225
+ `store` 在 `createTask` / `updateTask` / `addComment` / `createRequirementItem` / `updateRequirementItem`
226
+ 五条写路径上校验调用方带的 `contract`:
227
+ - **不带** `contract` ⇒ `skipped`(老客户端 / Web 零打扰,向后兼容);
228
+ - 版本或规范摘要不符 ⇒ **照常写入**,另落一条 `contract-warn` 审计
229
+ (`GET /api/governance/audit?action=contract-warn` 可查「谁在用旧规范干活」);
230
+ - 全符 ⇒ `ok`,**不制造审计噪声**。
231
+ - 为什么放内核:MCP / HTTP / CLI / Web / dsh-tool 五个入口都落到 `store`;放门面层就会
232
+ 「六个入口两种语义」(D2 拍板 B)。门面只做一件事:把 `body.contract` 原样透传。
233
+ - 测试 `tests/contract-warn.test.mjs` **4 条**:纯判据 / warn 不阻断且真落库 / 更新+评论两条路径同样受检 /
234
+ HTTP 透传 + 审计可查。
235
+
236
+ > **已知限制(P1.5 边界)**:目前是 **`warn` 档**(D2 拍板:先观测一周再切 `reject`)。
237
+ > 也就是说「用旧规范干活」现在**只留痕、不失败**;`409 CONTRACT_STALE` 的阻断要等切档时才生效。
238
+ > 另外 `project_contract` 目前只在手动 `recheck` 时落基线,需求文档变更时**不会自动 refresh**(随切档一起定)。
239
+
240
+ ### 新增(P2 · MCP 只读四工具 · 卡 `-170` · 2026-10-29)
241
+
242
+ - **MCP 契约层 `src/mcp/`(stdio,零依赖,零宿主改动)** —— `server.mjs` 是 newline-delimited
243
+ JSON-RPC 2.0 的 MCP server(`initialize` / `notifications/*` / `ping` / `tools/list` / `tools/call`),
244
+ `tools.mjs` 注册四个**只读**工具:
245
+ `flow_start`(开局 S0:项目 + `contract_version` + 三类缺口 + 下一步建议)·
246
+ `project_info`(按状态计数 + 契约是否漂移)·
247
+ `norm_get`(`spec/norms/*` 正文 + `sha256` digest;`norm="project"` 读 `<workspace>/AGENTS.md`)·
248
+ `workbench_audit`(`contract-stale` / `unattributed` / `unbound-session` / `candidate-flood` 四类漂移)。
249
+ - **三条实现口径**:① **stdio 而不是 HTTP** —— 不占端口、不碰 `:3080`、不写 `~/.dsh/**`、不需要重载宿主,
250
+ 每个 agent 会话一个进程;② **同一份 `taskboard.sqlite`**(`--data-dir` > `$TB_DATA_DIR` > 默认),
251
+ MCP 不是第二份数据;③ **只读到「连计数都不变」** —— 不调任何 `create/update/record*`,
252
+ 也不走 `resolveContext()`(它会 `ensureRequirementDoc`,属写操作)。
253
+ - **错误分层**:**协议层**用 JSON-RPC error(未知工具 ⇒ `-32602`),**工具层**用 `result.isError` +
254
+ `{code,message}`(如 `NORM_NOT_FOUND`)—— 混用的后果是客户端把「参数写错」当成「服务挂了」。
255
+ - **入口**:`node src/mcp/server.mjs --data-dir <dir>` · `npm run mcp` · `bin: tb-mcp` · `--print-tools`(清单自检)。
256
+ - 守卫测试 `tests/mcp-readonly.test.mjs` **A–H 八组**:握手 / 四工具且全 `readOnlyHint` / `flow_start` 缺口与
257
+ `nextStep` / `project_info` 计数 / `norm_get` 正文+digest+项目档+未知码 / `workbench_audit` 四类齐 /
258
+ **只读**(跑完一轮后 `projects/tasks/comments/ownedTasks/audit` 逐项不变)/ 协议层 `-32602`。
259
+
260
+ > **边界**:写工具(`card_create` / `card_progress` / `requirement_upsert` / `requirement_change`)属 **P3**,
261
+ > 本轮**不含**。也就是说 MCP 现在只能「读事实、报漂移」,**不能替人建卡或改状态**。
262
+
263
+ ### 新增(P3 · MCP 写四工具 + 条目列表 + `mcp-parity` · 卡 `-170` · 2026-10-29)
264
+
265
+ - **五个新工具(MCP 共 9 个)**:
266
+ `requirement_list`(只读:条目 + 内容版本 + 每条卡数)·
267
+ `requirement_upsert`(新建 / 改条目,改必带 `expected_version`)·
268
+ `requirement_change`(**先预览拿 `change_id` + 影响面**,带 `change_id` + `apply:true` 才落地)·
269
+ `card_create`(**归因硬门** + `unattributed_reason` 逃生口)·
270
+ `card_progress`(**`evidence[]` 非空** + **`norm_digest` 必填**)。
271
+ - **形状即约束(这次的四个「不可能」)**:
272
+ | 老毛病 | 现在怎么被挡住 |
273
+ | --- | --- |
274
+ | 建卡忘了归因 | `card_create` 无 `requirement` 且无 `unattributed_reason` ⇒ `REQUIREMENT_REQUIRED`(逃生口落 `attribution_skipped` 事件,可盘点) |
275
+ | 回填写「已完成」三个字 | `evidence[]` 非空且每项 `{kind∈file\|command\|url\|reading, ref}`;空 / 形状错 ⇒ `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` |
276
+ | 拿旧规范回填 | `norm_digest` 必填,与当前 `card-update` 不符 ⇒ `NORM_STALE`(**回带最新正文**,agent 自纠偏) |
277
+ | 改了需求忘了下游 | `requirement_change` 先回 `affected_cards` + `change_id`;条目预览后被改过 ⇒ `CHANGE_ID_MISMATCH` |
278
+ - **四条红线由门守,不由纪律守**:`done` 走执行侧状态门 ⇒ `GOVERNANCE_AGENT_DONE`;`card_create` 只接受
279
+ `backlog`(`backlog → todo` 是人工授权)⇒ `AUTHORIZATION_REQUIRED`;人工校验任务不得被执行侧改状态;
280
+ 同批证据按 `hash` 去重(重复回填不产生第二条评论)。
281
+ - **无状态 `change_id`**:`sha256(条目 + 改前内容版本 + 排序后的补丁)` —— 不建表、不存会话,
282
+ 条目一变 id 自动失效(比「存一张审批表」更难被绕过)。
283
+ - **`mcp-parity` 守卫 `tests/mcp-parity.test.mjs`(4 条)**:同一操作在 **HTTP 与 MCP** 上
284
+ 错误码必须相同(`REQUIREMENT_REQUIRED` / `DEPENDENCY_CROSS_PROJECT` / `GOVERNANCE_AGENT_DONE`),
285
+ 且**副作用同形**(状态 / 优先级 / 验收 / 复核动作 / 归属条目 / 事件序列 `created + attributed` 逐项相等)。
286
+ - 守卫 `tests/mcp-write.test.mjs`(**6 条** A–F):条目版本乐观锁 · 变更影响面门 · 归因/授权门 ·
287
+ 证据与 `norm_digest` 门 · `done` 红线 · **契约仍 `warn` 档**(带旧契约写入成功 + 只留 `contract-warn`)。
288
+
289
+ > **口径边界(有意为之)**:① `card_create` 的归因硬门只收紧 **MCP 这一个新入口**;内核全局档
290
+ > `TB_STRICT_ATTRIBUTION` 仍是默认 `warn`(翻默认会影响 Web / CLI / seed 全部存量调用方,属另一件事,须单独拍板)。
291
+ > ② `contract_version` 仍是 **`warn`** 档(D2 观察期内);写工具返回体带 `contract.verdict`,让 agent 自己知道用了旧规范。
292
+ > ③ `requirement_upsert` 的 `expected_version` 是**内容摘要**(`requirement_items` 没有 version 列),纯读、可重算。
293
+
294
+ ### 新增(P4 · `taskboard-flow` 技能包 + 开局档 A/B · 卡 `-170` · 2026-10-29)
295
+
296
+ - **技能包 `skills/taskboard-flow/`(随包分发,`npm run flow` 即用)** —— `SKILL.md` 是
297
+ **八步 × 六栏**的主流程表(入口 / 前置门 / 判据 / 证据落点 / 失败处置 / 对应 FR),
298
+ 外加「随时可用的两个只读入口」与**五条硬规则**;`references/steps/S0.md … S7.md` 给每步的命令与判据读数,
299
+ `references/errors.md` 是错误码 → 该做什么,`references/injection.md` 是装载细节与档 C 的接口形状。
300
+ **这一层只教顺序、判据与失败处置,不持有任何业务规则副本** —— 数据在 `taskboard.sqlite`,
301
+ 门在 `src/mcp/` 与 `src/core/`,规范在 `spec/norms/`。
302
+ - **装载块唯一生成器 `src/mcp/flow-block.mjs`** —— `readSkill()` / `buildFlowBlock()` / `buildAgentsSnippet()`。
303
+ 八步与硬规则**从 `SKILL.md` 的两个标记区间原样抽取**(`<!-- flow-block:steps -->` / `<!-- flow-block:rules -->`),
304
+ 不复制正文 ⇒ 「技能改了、装载块没跟上」这一类漂移在结构上不存在。
305
+ - **开局档 A(人贴)/ 档 B(外部 agent 约定)**:
306
+ - 档 A:`node scripts/tb-flow.mjs start` 的输出整块贴进 dsh 主会话;或让 MCP 客户端取 prompt **`taskboard.flow`**
307
+ —— **同一生成器、输出逐字节相同**;
308
+ - 档 B:项目根 `AGENTS.md` 写一段「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」,片段由
309
+ `tb-flow snippet` 打印(`--write` 只打印待粘贴内容,**不替人改文件**)。
310
+ - **MCP `prompts` 能力** —— `initialize` 声明 `prompts:{listChanged:false}`,新增 `prompts/list` 与
311
+ `prompts/get`(只认 `taskboard.flow`,未知名字 ⇒ **协议层 `-32602`**);启动日志带 `prompt=taskboard.flow skill=v1`。
312
+ - **CLI `scripts/tb-flow.mjs`(`bin: tb-flow` · `npm run flow`)** ——
313
+ `start [--project --cwd --json --data-dir]`(缺项目时按 `--cwd` / `basename` 猜,猜不到给 `PROJECT_NOT_FOUND` 并
314
+ 打印「怎么指定 `--data-dir`」)· `snippet`(打印档 B 的 `AGENTS.md` 片段)· `check`(自检 frontmatter 与八步完整性)。
315
+ `package.json#files[]` 增加 `skills/` 与 `scripts/tb-flow.mjs` —— 市场安装拿的是打包产物,少写一项就静默缺件。
316
+ - **`deriveFlowNext` / `projectGaps` / `resolveProject` 从 `tools.mjs` 导出**(`export`)—— 让 `flow-block.mjs`
317
+ 复用同一份「下一步」判据,而不是第二份实现。
318
+ - 守卫 `tests/skill-flow.test.mjs`(**6 条** A–F):frontmatter 五项齐全 · 八步连续且每格非空(六栏表头)·
319
+ **双向工具覆盖**(表里提到的工具都在注册表里,注册表里 9 个工具都必须在技能目录被提到)·
320
+ `requires_contract` 与 `CONTRACT_VERSION_PREFIX` 同源 · **档 A/B 同源**(进程内生成 ≡ MCP `prompts/get` ≡ CLI `start`,
321
+ 逐字节)· 真跑 S0→S2(无条目 ⇒ S1;建条目 ⇒ 建卡 ⇒ `nextStep.step === "S3"` 且 `humanAction === "authorize"`)。
322
+
323
+ > **口径边界(有意为之)**:① **档 C(宿主会话创建自动注入)未启用** —— D3 已拍板推迟到「工作台整体封装为插件包」
324
+ > 阶段,本轮只预埋接口(`flow_inject_policy` 配置位默认 `off`、`flow_injections` 审计表、`references/injection.md`),
325
+ > **没有任何代码读这个配置位去注入**;真要接必须先报批改 `~/.dsh/**` 并重载宿主。
326
+ > ② 技能**不进 `docs/规范/`**:后者是本仓库的开发文档、永不入 git,不是运行时真源。
327
+ > ③ 卡 `-170` 仍停在 `in_progress` —— P5 未定,不推 `in_review`。
328
+
329
+
9
330
  ## [0.2.0] - 2026-10-29
10
331
 
11
332
  > **本版是首个发布到 npm 的版本** —— `0.1.0` 只出过 GitHub Release 源码快照,未进 registry。
package/README.md CHANGED
@@ -38,6 +38,13 @@ dsh plugin --profile web add taskboard-workbench
38
38
  插件通过 `dsh.bundle.patch`(`cordis.patch.yml`)与 `dsh.client` 注入到宿主;
39
39
  需要宿主支持的 `@deepseek-ai/dsh-client-ui-{layout,sidebar,slots}`(已声明为**可选 peer**)。
40
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
+
41
48
  ### 从源码
42
49
 
43
50
  ```bash
@@ -53,6 +60,10 @@ npm start # 启动本地 Web 服务(默认监听本机端
53
60
  node cli/tb.mjs project list # 或用 CLI 直接操作
54
61
  ```
55
62
 
63
+ > ⚠️ 独立进程**没有** DSH 宿主会话通道:`/api/health` 的 `host.capabilities` 恒为 `null`,
64
+ > 「投给主会话 / 打开会话 / 派发团队」不可用(界面按能力位置灰并常驻提示)。
65
+ > 看板、建卡、改状态、评审、人工收口照常可用。要投递或派发,请用上面的**插件形态**。
66
+
56
67
  ## 要求
57
68
 
58
69
  | 项 | 值 |
@@ -77,6 +88,85 @@ CLI 约定:成功 `stdout` 输出 JSON(含 `schemaVersion`),退出码 `0
77
88
  失败 `stderr` 输出 `{schemaVersion, error:{code,message}}`,退出码 `2/3/4/5`。
78
89
  并发编辑用 `--if-version`,版本不符返回 `VERSION_CONFLICT`(退出码 5)而不静默覆盖。
79
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
+ node src/mcp/server.mjs --read-only # **只读模式**:只暴露五件只读工具,写四件调用即 READ_ONLY_MODE
100
+ npm run mcp -- --data-dir "$TB_DATA_DIR" # 同上,走 npm script
101
+ ```
102
+
103
+ `--read-only` 是写工具的**回滚开关**(写路径出问题时的逃生口):`tools/list` 里不再出现
104
+ `card_create` / `card_progress` / `requirement_upsert` / `requirement_change`,直接调用返回
105
+ `isError:true` + `code=READ_ONLY_MODE`(**不是**「未知工具」,便于区分「开关生效」与「名字拼错」)。
106
+ 不带该参数时行为不变(9 个工具)。
107
+
108
+ 传输是 **stdio + newline-delimited JSON-RPC 2.0**(MCP stdio transport):
109
+ **不占端口、不碰 `:3080`、不写 `~/.dsh/**`、不需要重载宿主**,每个 agent 会话一个进程。
110
+
111
+ ### 只读五件
112
+
113
+ | 工具 | 用途 |
114
+ | --- | --- |
115
+ | `flow_start` | 开局第一步(S0):项目身份 + `contract_version` + 缺口(未归因卡 / 未绑定主会话 / 待确认候选)+ 下一步建议 |
116
+ | `project_info` | 项目总览:任务与需求条目按状态计数 + 契约版本与基线是否漂移 |
117
+ | `norm_get` | 取机器规范正文(`flow` / `card-update` / `doc-editing` / `acceptance` / `project-defaults`;`norm="project"` 读项目自有 `<workspace>/AGENTS.md`)+ `digest` |
118
+ | `requirement_list` | 需求条目列表:条目 + 内容版本(乐观锁用)+ 每条下的卡数与完成数 |
119
+ | `workbench_audit` | 漂移盘点:`contract-stale` / `unattributed` / `unbound-session` / `candidate-flood` 四类,各带计数、样例与处置建议 |
120
+
121
+ ### 写四件(形状即约束)
122
+
123
+ | 工具 | 强制的形状 | 被拒的样子 |
124
+ | --- | --- | --- |
125
+ | `card_create` | **归因硬门**:`requirement` 或显式 `unattributed_reason`(落审计)。新卡只能进 `backlog` | `REQUIREMENT_REQUIRED` / `AUTHORIZATION_REQUIRED`(`backlog → todo` 是人工授权) |
126
+ | `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` |
127
+ | `requirement_upsert` | 改条目必须带 `expected_version`(`requirement_list` 返回的 `version`) | `MISSING_VERSION` / `VERSION_CONFLICT` |
128
+ | `requirement_change` | 先预览拿 `change_id` + 影响面 `affected_cards`,带 `change_id` + `apply:true` 才落地 | `CHANGE_NEEDS_APPROVAL` / `CHANGE_ID_MISMATCH`(预览后条目被改过即失效) |
129
+
130
+ **四条红线仍然由门守,不是由纪律守**:
131
+
132
+ 1. `done` 只能人点 —— `card_progress` 走执行侧状态门,写 `done` 直接 `GOVERNANCE_AGENT_DONE`;
133
+ 2. `backlog → todo` 是人工授权 —— `card_create` 只接受 `backlog`;
134
+ 3. 人工校验任务不得被执行侧改状态;
135
+ 4. 证据不能是「已完成」三个字 —— `evidence[]` 的形状就是判据;同一批证据重复回填会按 `hash` 去重。
136
+
137
+ **契约档位**:`contract_version` 目前仍是 **`warn`** 档(不符只落 `contract-warn` 审计、不阻断),
138
+ 切 `reject` 要等观察期到点单独拍板;写工具的返回体里带 `contract.verdict` 让 agent 自己知道用没用旧规范。
139
+
140
+ 数据源是**同一个** `taskboard.sqlite`(`--data-dir` > `$TB_DATA_DIR` > 默认),
141
+ MCP 不是第二份数据 —— 看板里看到的、CLI 改的、MCP 读的,是同一行记录。
142
+ `tests/mcp-parity.test.mjs` 守的就是这条:同一操作在 HTTP 与 MCP 上**错误码与副作用必须同形**。
143
+
144
+ 同一个 server 还提供一个 **MCP prompt `taskboard.flow`**(`prompts/list` / `prompts/get`):
145
+ 内容是当前项目的「开局装载块」—— 契约版本、门档、六类缺口、下一步该做什么、八步表与五条硬规则。
146
+ 它与 CLI 的 `tb-flow start` **共用一个生成器**,输出逐字节相同(`tests/skill-flow.test.mjs` 守这条)。
147
+
148
+ ## 技能包(开局装载)
149
+
150
+ `skills/taskboard-flow/` 是给 agent 读的**主流程技能**(八步 S0–S7 × 六栏:入口 / 前置门 / 判据 /
151
+ 证据落点 / 失败处置 / 对应 FR),随包分发。它**只教顺序与判据,不持有业务规则副本** ——
152
+ 数据在 `taskboard.sqlite`,门在 `src/mcp/` 与 `src/core/`,机器规范在 `spec/norms/`。
153
+
154
+ ```bash
155
+ npm run flow -- start --data-dir "$TB_DATA_DIR" --project demo # 打印开局装载块(档 A:整块贴进会话)
156
+ npm run flow -- start --json # 同上,结构化输出
157
+ npm run flow -- snippet # 打印档 B 的 AGENTS.md 片段
158
+ npm run flow -- check # 自检 frontmatter 与八步完整性
159
+ node scripts/tb-flow.mjs start --cwd /path/to/repo # 缺项目时按 cwd / 目录名猜
160
+ ```
161
+
162
+ 三种开局方式,按侵入性排序:
163
+
164
+ | 档 | 谁用 | 怎么做 | 要不要改宿主 |
165
+ | --- | --- | --- | --- |
166
+ | **A 开局提示词** | 人在 dsh 主会话里新开一轮 | 贴 `tb-flow start` 输出;或 MCP 客户端取 prompt `taskboard.flow` | 不用 |
167
+ | **B 外部 agent 约定** | Claude Code / Codex 在项目仓库里开工 | 项目根 `AGENTS.md` 写「开工先跑 `<taskboard>/scripts/tb-flow.mjs start`」,片段用 `tb-flow snippet` 打印 | 不用 |
168
+ | **C 宿主自动注入** | dsh 会话创建即注入 | **未启用**(须报批改 `~/.dsh/**` 并重载宿主);接口形状见 `skills/taskboard-flow/references/injection.md` | 须报批 |
169
+
80
170
  ## 配置
81
171
 
82
172
  | 环境变量 | 作用 | 默认 |
@@ -94,9 +184,13 @@ cordis.patch.yml dsh.bundle.patch
94
184
  src/core/ 存储、状态机、团队模板、执行编排、看护
95
185
  src/server/ HTTP API 与事件流
96
186
  src/host/ 团队引擎与工具面
187
+ src/mcp/ MCP 契约层(stdio server + 九个工具:只读五 / 写四 + prompt taskboard.flow)
188
+ skills/taskboard-flow/ 主流程技能包(八步 × 六栏 + 每步 references + 错误码 + 装载说明)
189
+ scripts/tb-flow.mjs `tb-flow` 开局装载块 CLI(start / snippet / check)
97
190
  web/ 本地 Web 看板(app.js / tokens.css / index.html)
98
191
  cli/tb.mjs `tb` 命令行
99
192
  spec/团队agent.md 团队契约(随包发布,供工作台里的 agent 读取)
193
+ spec/norms/ 机器执行规范(运行时唯一真源,随包;manifest.json 带 sha256 digest)
100
194
  tests/ `node --test` 单测
101
195
  tools/ 开发与验证脚本(不进 npm 包,除 seed/env-check)
102
196
  ```
@@ -106,6 +200,7 @@ tools/ 开发与验证脚本(不进 npm 包,除 seed/env-chec
106
200
  ```bash
107
201
  npm test # node --test,全量单测
108
202
  node --check index.js # 语法自检(对每个源文件)
203
+ node src/mcp/server.mjs --print-tools # MCP 工具清单自检
109
204
  ```
110
205
 
111
206
  ## 版本
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -29,7 +29,8 @@
29
29
  "access": "public"
30
30
  },
31
31
  "engines": {
32
- "node": ">=22.5.0"
32
+ "node": ">=22.5.0",
33
+ "dsh": ">=0.2.1-rc.3"
33
34
  },
34
35
  "main": "./index.js",
35
36
  "exports": {
@@ -43,18 +44,25 @@
43
44
  "index.js",
44
45
  "lib/client.js",
45
46
  "cordis.patch.yml",
47
+ "skills",
46
48
  "src",
47
49
  "web",
48
50
  "cli",
49
51
  "spec/团队agent.md",
52
+ "spec/norms",
53
+ "scripts/tb-flow.mjs",
50
54
  "tools/seed.mjs",
51
55
  "tools/env-check.mjs"
52
56
  ],
53
57
  "bin": {
54
- "tb": "./cli/tb.mjs"
58
+ "tb": "./cli/tb.mjs",
59
+ "tb-mcp": "./src/mcp/server.mjs",
60
+ "tb-flow": "./scripts/tb-flow.mjs"
55
61
  },
56
62
  "scripts": {
57
63
  "start": "node src/server/server.mjs",
64
+ "mcp": "node src/mcp/server.mjs",
65
+ "flow": "node scripts/tb-flow.mjs",
58
66
  "seed": "node tools/seed.mjs",
59
67
  "test": "node --test",
60
68
  "env-check": "node tools/env-check.mjs"
@@ -65,9 +73,15 @@
65
73
  "@deepseek-ai/dsh-client-ui-slots": "*"
66
74
  },
67
75
  "peerDependenciesMeta": {
68
- "@deepseek-ai/dsh-client-ui-layout": { "optional": true },
69
- "@deepseek-ai/dsh-client-ui-sidebar": { "optional": true },
70
- "@deepseek-ai/dsh-client-ui-slots": { "optional": true }
76
+ "@deepseek-ai/dsh-client-ui-layout": {
77
+ "optional": true
78
+ },
79
+ "@deepseek-ai/dsh-client-ui-sidebar": {
80
+ "optional": true
81
+ },
82
+ "@deepseek-ai/dsh-client-ui-slots": {
83
+ "optional": true
84
+ }
71
85
  },
72
86
  "dsh": {
73
87
  "bundle": {
@@ -0,0 +1,86 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * tb-flow.mjs —— 开局装载块(P4 · 档 A / 档 B 的同一个入口)
4
+ *
5
+ * 用法:
6
+ * node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json]
7
+ * node scripts/tb-flow.mjs snippet [--project <id>] # 打给项目 AGENTS.md 用的片段
8
+ * node scripts/tb-flow.mjs check # 只自检(不读写库)
9
+ *
10
+ * 数据源:`--data-dir` > `$TB_DATA_DIR` > 默认(与 Web / CLI / MCP 同一份 `taskboard.sqlite`)。
11
+ *
12
+ * **只读**:本脚本不建卡、不改状态、不写评论、不写审计 —— 它只把"现在该干什么"打印出来。
13
+ * 与 MCP prompt `taskboard.flow` 共用 `src/mcp/flow-block.mjs`,输出**逐字节相同**。
14
+ */
15
+ import path from "node:path";
16
+ import { fileURLToPath } from "node:url";
17
+
18
+ import { buildAgentsSnippet, buildFlowBlock, readSkill, SKILL_PATH } from "../src/mcp/flow-block.mjs";
19
+ import { openStore } from "../src/core/store.mjs";
20
+ import { resolveDataDir } from "../src/core/config.mjs";
21
+
22
+ const argv = process.argv.slice(2);
23
+ const has = (name) => argv.includes(name);
24
+ const argOf = (name) => {
25
+ const i = argv.indexOf(name);
26
+ return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
27
+ };
28
+ const command = argv.find((a) => !a.startsWith("-") && argv[argv.indexOf(a) - 1] !== "--project" && argv[argv.indexOf(a) - 1] !== "--cwd" && argv[argv.indexOf(a) - 1] !== "--data-dir") ?? "start";
29
+
30
+ if (has("--help") || has("-h")) {
31
+ process.stdout.write(`tb-flow · 任务看板开局装载块
32
+ 用法:
33
+ node scripts/tb-flow.mjs start [--project <id>] [--cwd <dir>] [--json] [--data-dir <dir>]
34
+ node scripts/tb-flow.mjs snippet [--project <id>]
35
+ node scripts/tb-flow.mjs check
36
+ 只读脚本:不建卡 / 不改状态 / 不写评论。数据源同 Web/CLI(--data-dir > $TB_DATA_DIR > 默认)。
37
+ `);
38
+ process.exit(0);
39
+ }
40
+
41
+ if (command === "check") {
42
+ const skill = readSkill();
43
+ process.stdout.write(`skill: ${skill.relPath} · name=${skill.meta.name} · version=${skill.meta.version} · requires_contract=${skill.meta.requires_contract}\n`);
44
+ process.stdout.write(`八步段落: ${skill.steps.split("\n").filter((l) => l.startsWith("| **S")).length} 行 · 硬规则: ${skill.rules.split("\n").filter((l) => /^\d+\./.test(l)).length} 条\n`);
45
+ process.exit(0);
46
+ }
47
+
48
+ if (command === "snippet") {
49
+ process.stdout.write(`${buildAgentsSnippet({ project: argOf("--project"), pkgPath: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..") })}\n`);
50
+ process.exit(0);
51
+ }
52
+
53
+ if (command !== "start") {
54
+ process.stderr.write(`未知子命令:${command}(可用:start / snippet / check)\n`);
55
+ process.exit(2);
56
+ }
57
+
58
+ const dataDir = argOf("--data-dir") ?? resolveDataDir({ env: process.env });
59
+ const store = openStore({ dataDir, env: process.env });
60
+ try {
61
+ const block = buildFlowBlock({ store, project: argOf("--project"), cwd: argOf("--cwd") ?? process.cwd() });
62
+ if (has("--json")) {
63
+ process.stdout.write(`${JSON.stringify({
64
+ project: block.project,
65
+ contract: block.contract,
66
+ gaps: block.gaps,
67
+ nextStep: block.nextStep,
68
+ skill: { ...block.skill, path: SKILL_PATH },
69
+ dataDir: store.dataDir,
70
+ block: block.text,
71
+ }, null, 2)}\n`);
72
+ } else {
73
+ process.stdout.write(block.text);
74
+ process.stderr.write(`[tb-flow] dataDir=${store.dataDir} · 只读 · 与 MCP prompt taskboard.flow 同源\n`);
75
+ }
76
+ } catch (error) {
77
+ process.stderr.write(`${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}\n`);
78
+ if (error?.code === "PROJECT_NOT_FOUND") {
79
+ // 默认数据目录是临时目录 ⇒ 用户几乎总会撞这一下。把「怎么指到真库」直接写出来。
80
+ process.stderr.write(`提示:当前数据目录是 ${store.dataDir}(不含该项目)。看板在别的目录时显式带 --data-dir,例如:\n`);
81
+ process.stderr.write(` node scripts/tb-flow.mjs start --project <id> --data-dir .data\n`);
82
+ }
83
+ process.exit(error?.code === "PROJECT_NOT_FOUND" ? 3 : 1);
84
+ } finally {
85
+ try { store.close(); } catch { /* ignore */ }
86
+ }