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.
Files changed (75) hide show
  1. package/CHANGELOG.md +403 -0
  2. package/LICENSE +21 -0
  3. package/README.md +210 -2
  4. package/cli/tb.mjs +314 -0
  5. package/cordis.patch.yml +5 -0
  6. package/index.js +633 -0
  7. package/lib/client.js +522 -0
  8. package/package.json +96 -4
  9. package/scripts/tb-flow.mjs +86 -0
  10. package/skills/taskboard-flow/SKILL.md +89 -0
  11. package/skills/taskboard-flow/references/errors.md +61 -0
  12. package/skills/taskboard-flow/references/injection.md +70 -0
  13. package/skills/taskboard-flow/references/steps/S0.md +31 -0
  14. package/skills/taskboard-flow/references/steps/S1.md +28 -0
  15. package/skills/taskboard-flow/references/steps/S2.md +31 -0
  16. package/skills/taskboard-flow/references/steps/S3.md +22 -0
  17. package/skills/taskboard-flow/references/steps/S4.md +25 -0
  18. package/skills/taskboard-flow/references/steps/S5.md +36 -0
  19. package/skills/taskboard-flow/references/steps/S6.md +30 -0
  20. package/skills/taskboard-flow/references/steps/S7.md +23 -0
  21. package/spec/norms/acceptance.md +36 -0
  22. package/spec/norms/card-update.md +39 -0
  23. package/spec/norms/doc-editing.md +30 -0
  24. package/spec/norms/flow.md +45 -0
  25. package/spec/norms/manifest.json +41 -0
  26. package/spec/norms/project-defaults.md +33 -0
  27. package/spec//345/233/242/351/230/237agent.md +171 -0
  28. package/src/core/acceptance.mjs +62 -0
  29. package/src/core/advance.mjs +192 -0
  30. package/src/core/agent-teams.mjs +48 -0
  31. package/src/core/binding.mjs +44 -0
  32. package/src/core/config.mjs +22 -0
  33. package/src/core/contract.mjs +287 -0
  34. package/src/core/debug-dispatch.mjs +94 -0
  35. package/src/core/delivery.mjs +93 -0
  36. package/src/core/deps.mjs +53 -0
  37. package/src/core/diagnostics.mjs +648 -0
  38. package/src/core/domain.mjs +235 -0
  39. package/src/core/empty-state.mjs +240 -0
  40. package/src/core/errors.mjs +142 -0
  41. package/src/core/evidence.mjs +86 -0
  42. package/src/core/executor.mjs +645 -0
  43. package/src/core/human-review.mjs +773 -0
  44. package/src/core/intake.mjs +179 -0
  45. package/src/core/kickoff.mjs +147 -0
  46. package/src/core/loop.mjs +498 -0
  47. package/src/core/memory.mjs +193 -0
  48. package/src/core/next-step.mjs +377 -0
  49. package/src/core/notify.mjs +183 -0
  50. package/src/core/owner.mjs +41 -0
  51. package/src/core/requirements.mjs +292 -0
  52. package/src/core/review.mjs +82 -0
  53. package/src/core/session-naming.mjs +64 -0
  54. package/src/core/split-ask.mjs +107 -0
  55. package/src/core/store.mjs +3442 -0
  56. package/src/core/team.mjs +170 -0
  57. package/src/core/ticket-stage.mjs +150 -0
  58. package/src/core/verify.mjs +170 -0
  59. package/src/core/watchdog.mjs +144 -0
  60. package/src/host/ai-elaborator.mjs +26 -0
  61. package/src/host/team-engine.mjs +125 -0
  62. package/src/host/tool-surface.mjs +205 -0
  63. package/src/mcp/flow-block.mjs +173 -0
  64. package/src/mcp/server.mjs +156 -0
  65. package/src/mcp/tools.mjs +764 -0
  66. package/src/server/api.mjs +2050 -0
  67. package/src/server/events.mjs +32 -0
  68. package/src/server/kickoff.mjs +46 -0
  69. package/src/server/server.mjs +214 -0
  70. package/src/server/verify.mjs +112 -0
  71. package/tools/env-check.mjs +35 -0
  72. package/tools/seed.mjs +67 -0
  73. package/web/app.js +5337 -0
  74. package/web/index.html +15 -0
  75. package/web/tokens.css +1151 -0
@@ -0,0 +1,30 @@
1
+ ---
2
+ norm_id: doc-editing
3
+ version: 1
4
+ updated: 2026-10-29
5
+ applies_to: ["*"]
6
+ ---
7
+ # doc-editing · 文档更新规范(机器版)
8
+
9
+ ## 每轮收尾(缺一即该轮未完成)
10
+
11
+ 1. 更新 `docs/进度/当前状态.md`(唯一进度快照)。
12
+ 2. 追加轮次记录 `docs/进度/YYYY-MM-DD-<主题>.md`:现象 / 根因 / 修复 / 验证 / 遗留。
13
+ 3. 同步 `docs/README.md` 与相关 `README.md` 索引。
14
+ 4. 回报里给出「文档更新清单」(改了哪几份 + 路径)。
15
+
16
+ ## 写入纪律
17
+
18
+ - **先落文档,再动手**:口径/方案类先写进 `docs/设计/`,代码跟着文档走。
19
+ - **不改历史决策**:`docs/历史归档/`、已定稿条款不动;要改就加「变更记录」并写理由。
20
+ - **一条事实只写一处**:同一结论不重复散落;引用用相对链接。
21
+ - **敏感信息先脱敏**:`sk-*` / `*_token` / 密码 / 私钥 / 含凭据连接串 ⇒ 占位符(`sk-REDACTED`)。
22
+ - **读数必须可复跑**:写进文档的每个数字后面要有能重跑的命令。
23
+
24
+ ## 命名
25
+
26
+ | 类型 | 规则 |
27
+ |---|---|
28
+ | 轮次记录 | `YYYY-MM-DD-<主题>.md`(同日同主题追加,不新建) |
29
+ | 设计方案 | `<主题>-方案-YYYY-MM-DD.md` |
30
+ | 踩坑 / 复盘 | 归 `个人笔记/踩坑经验/<主题>/`,**不写进本仓 `docs/`** |
@@ -0,0 +1,45 @@
1
+ ---
2
+ norm_id: flow
3
+ version: 1
4
+ updated: 2026-10-29
5
+ applies_to: ["*"]
6
+ ---
7
+ # flow · 主流程八步(机器版)
8
+
9
+ > 这是**给 agent 执行**的契约,不是给人读的文档。人读正本在 `docs/`(不入 git)。
10
+ > 顺序与四道门**不可覆盖**;项目只允许在 `project-defaults` 的 3 类白名单内参数化。
11
+
12
+ | 步 | 名称 | 该做什么 | 前置门 | 允许的写 |
13
+ |---|---|---|---|---|
14
+ | S0 | 绑定与对照 | 认项目、认会话归属;先看 `gaps`(未归因卡 / 未绑定会话 / 待确认候选) | 会话归属(主会话或已批准关联) | 无 |
15
+ | S1 | 需求文档与条目 | 文档 → 条目,**一条一件事**;`draft` 未确认不得建卡 | 文档 digest 一致 | 需求条目 |
16
+ | S2 | 分拆成卡 | 建卡**必带 `requirement`**;一事务内完成归因 | 条目存在 + 同项目 | 卡片 |
17
+ | S3 | 授权开工 | `backlog → todo`;**人点**,执行侧不得自我授权 | 归因门 → 授权门 | 卡片状态 |
18
+ | S4 | 派发/执行 | 派团队或 CLI;持锁 + 心跳 | 归因 + 授权 + 人工校验门 | 执行记录 |
19
+ | S5 | 回填进度 | 每条进展**带可核验证据**(文件 / 命令 / 读数),不是「已完成」三个字 | 契约版本一致 + `norm_digest` 匹配 | 评论 + 事件 |
20
+ | S6 | 需求变更 | 先算**影响面**再改;`done` 卡不自动重开,标 `needs_recheck` | 影响面已确认 | 变更集 |
21
+ | S7 | 验收收口 | `in_review → done`,**只由人** | 评审门 `review_state==='approved'` 或显式 `skipReview` | 卡片状态 |
22
+
23
+ ## 四道门(不可覆盖)
24
+
25
+ 1. **人工校验**(人在环):`human_review` 卡两出口都 409 `HUMAN_REVIEW_NOT_EXECUTABLE`。
26
+ 2. **归因**:未归因卡不得派发 ⇒ `EXECUTION_NOT_ATTRIBUTED`;逃生口 `unattributed_reason` 必须落审计。
27
+ 3. **授权**:`backlog → todo` 只由人(`GOVERNANCE_ACTOR`)。
28
+ 4. **评审**:`in_review → done` 需 `approved`;人可 `skipReview:true` 跳过,但服务端落 `review_skipped` 审计。
29
+
30
+ ## 错误码处置(agent 自纠偏,不要问人)
31
+
32
+ | 错误码 | 含义 | 处置 |
33
+ |---|---|---|
34
+ | `EXECUTION_NOT_ATTRIBUTED` | 卡未挂需求条目 | 先补归因(`requirement` 参数 / `tb task attribution`),再派发 |
35
+ | `CONTRACT_STALE` | 契约版本过期 | 用返回体里的 `snapshot` 重试(**别问人**) |
36
+ | `NORM_STALE` | 用了旧规范 | 重取 `norm_get`,按新正文改完再写 |
37
+ | `REVIEW_NOT_APPROVED` | 未评审就想 done | 先 `review approve`;跳过须人显式 `skipReview` |
38
+ | `HUMAN_REVIEW_NOT_EXECUTABLE` | 人工校验卡被派发 | 停手,转人处理 |
39
+ | `GOVERNANCE_AGENT_DONE` | 执行侧想点完成 | 停手,交人点 |
40
+
41
+ ## 红线
42
+
43
+ - **`done` 只能由人置**;执行侧与评审都不得代点。
44
+ - 需求变更**不自动重开**已完成卡。
45
+ - 派生动作(建卡 / 派发 / 收口)必须能被审计追到「谁、用哪版契约、什么证据」。
@@ -0,0 +1,41 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "note": "由 node tools/build-norms.mjs 生成;正文变了必须 bump version(否则 tests/norms-parity.test.mjs 报红)",
4
+ "norms": [
5
+ {
6
+ "norm_id": "acceptance",
7
+ "version": 2,
8
+ "updated": "2026-10-29",
9
+ "digest": "1d91f555c46ecfb122f85e20c3a5ca9c0f37c7f8d2422ed08ce071b25fd98613",
10
+ "file": "spec/norms/acceptance.md"
11
+ },
12
+ {
13
+ "norm_id": "card-update",
14
+ "version": 1,
15
+ "updated": "2026-10-29",
16
+ "digest": "1d590cbacca29765f129f742a7137c0bdc80e916b8fca69fdb05a5289b5e1f24",
17
+ "file": "spec/norms/card-update.md"
18
+ },
19
+ {
20
+ "norm_id": "doc-editing",
21
+ "version": 1,
22
+ "updated": "2026-10-29",
23
+ "digest": "4e3ca702e45f3dc3f1072be2f4685ca5490dea0dd9a1d753e75ae609c8beaf5f",
24
+ "file": "spec/norms/doc-editing.md"
25
+ },
26
+ {
27
+ "norm_id": "flow",
28
+ "version": 1,
29
+ "updated": "2026-10-29",
30
+ "digest": "3b7596bf7bd8c21367e80bc08da6fe332d35ff4faf73f570ae8982c6fdb76371",
31
+ "file": "spec/norms/flow.md"
32
+ },
33
+ {
34
+ "norm_id": "project-defaults",
35
+ "version": 1,
36
+ "updated": "2026-10-29",
37
+ "digest": "0afa06d35abda598cb1ef5d94d1d6cfbc061620b664e6adb279f78829ba1d1ad",
38
+ "file": "spec/norms/project-defaults.md"
39
+ }
40
+ ]
41
+ }
@@ -0,0 +1,33 @@
1
+ ---
2
+ norm_id: project-defaults
3
+ version: 1
4
+ updated: 2026-10-29
5
+ applies_to: ["*"]
6
+ ---
7
+ # project-defaults · 项目可覆盖项(机器版)
8
+
9
+ ## 只允许这 3 类覆盖(其余键一律 `NORM_OVERRIDE_FORBIDDEN`)
10
+
11
+ | 键 | 例 | 为什么允许 |
12
+ |---|---|---|
13
+ | `verifyCommand` | `mvn -q test` / `pytest -q` | 技术栈不同,这是**事实**不是标准 |
14
+ | `workspacePath` | `/path/to/repo` | 同上 |
15
+ | `notApplicable` | `["S4"]` + **必填理由** | 有些项目不派发团队;须写理由并落审计 |
16
+
17
+ ## 禁止覆盖(硬拒)
18
+
19
+ - 八步的**顺序**;
20
+ - 四道门:人工校验 / 归因 / 授权 / 评审;
21
+ - `done` 只能由人置;
22
+ - 「回填必须带证据」。
23
+
24
+ ## 项目自有规范怎么叠加
25
+
26
+ 项目可以在 `<workspace>/AGENTS.md` 写**自己的约定**,加载顺序是:
27
+
28
+ ```
29
+ spec/norms/*.md(随包,唯一真源) → <workspace>/AGENTS.md(只能追加/参数化)
30
+ ```
31
+
32
+ - 追加的条目**不得**与上面的禁止项冲突;冲突即 `NORM_CONFLICT`(开发期红,不是运行期出事)。
33
+ - 加载块里固定带 `norm_notice`:告诉人「当前用的哪份规范、什么版本、怎么查看/替换」。
@@ -0,0 +1,171 @@
1
+ # 团队 agent.md · Agent Team 任务工作台
2
+
3
+ > **用途**:约束本项目「Agent Team 任务工作台」下的**多智能体团队**如何创建、派发、执行与回写。
4
+ > **适用范围**:所有经工作台/承载环境(DSH)创建的团队与其成员;也作为本仓库后续"自举开发"的团队契约。
5
+ > **上位依据**:[`需求文档.md`](./需求文档.md)(§二 K/L,FR-34…FR-48)、[`规范/04-决策与复盘.md`](./规范/04-决策与复盘.md)(外部 CLI 执行器)。
6
+ > **状态**:v1.1(2026-10-14 首版;2026-10-23 增补 §8.1 分域声明 —— **只增不改,角色定义未动**)。技术实现随后续切片推进;本文先锁**契约与红线**。
7
+ > **测试/开发环境指定的引擎插件**:**`@nanmicoder/dsh-agent-teams`(v0.1.22)**——队长派发/成员执行经该插件(T-5 兼容性见 [`计划文档.md`](./计划文档.md))。
8
+
9
+ ---
10
+
11
+ ## 一、角色(成员集合)
12
+
13
+ | 角色 | id | 职责 | 写权限 |
14
+ | --- | --- | --- | --- |
15
+ | 队长 | `lead` | 领取目标任务 → 按模板派发 → 汇总回流 → 不解锁下游直到审查通过 | 派发、汇总;**不得置 done** |
16
+ | 规划 | `planner` | 需求拆解、可行性、技术任务与依赖 | 产出需求/任务;不改实现代码 |
17
+ | 开发 | `engineer` | 实现代码(可调外部 code CLI) | 指定文件;**不得 commit/push**(commit 归队长/人) |
18
+ | 测试 | `tester` | 验证、回归、缺陷复现 | 测试与报告;**不得写实现代码** |
19
+ | 评审 | `reviewer` | 质量门审查;审查未过不得解锁下游 | 审查结论 |
20
+ | 归档 | `archivist` | 文档、索引、交付 | 文档区 |
21
+
22
+ > 最小团队 = `lead` + `engineer` + `tester`;含质量门时加 `reviewer`。
23
+
24
+ ---
25
+
26
+ ## 二、团队创建要求(模板字段)
27
+
28
+ 创建团队前**须给定模板**(缺一不可):
29
+
30
+ 1. **roles**:角色集合与数量(默认 `lead×1, engineer≥1, tester≥1[, reviewer]`)。
31
+ 2. **per-role model**:每个角色的模型(可留空=默认)。
32
+ 3. **per-role executor**:每角色的执行器——`hosted`(承载环境内智能体)/ `cli:codex` / `cli:claude` / 其他外部 code CLI。
33
+ 4. **quality gates**:质量门顺序(默认 `需求→实现→验证→审查→集成`)。
34
+ 5. **target**:目标任务或需求条目(**必须已归因**;否则拒建)。
35
+
36
+ **硬性校验**:目标未归因 → 拒绝;角色缺失或数量为 0 → 拒绝;同一任务已有活跃执行单元 → 拒绝(任务级锁)。
37
+
38
+ ### 附:项目环境与约束(随团队一起约定)
39
+
40
+ 创建团队时**同时约定项目环境与约束**(存于项目设置,见 FR-56):工作区路径、语言/时区、构建与测试命令、编码约定、红线(不得 commit/push、不得写 done 等)。团队执行时**以该约束为项目上下文**。
41
+
42
+ ---
43
+
44
+ ## 二·序、团队先于任务(项目入口)
45
+
46
+ > 顺序权威:`需求文档.md` §三 场景六「项目从零到执行(团队先行)」;需求 §二 N(FR-55…FR-59)。
47
+
48
+ - 工作台页 = 项目团队的**项目入口**;**项目文档可以尚未完善**时即进入。
49
+ - **入口是"会话优先"**:先在一个会话里打开工作台(该会话即项目的**初始会话**,FR-60),再在该会话内做项目配置;开局用[`规范/项目开局提示词`](./规范/02-流程与开局规范.md)提醒"创建会话时加载工作台插件 + 指定 agent team 插件"(FR-61)。
50
+ - **两种入口**(FR-62/63):① 从 DSH 列表的「任务工作台」按钮进入 = **全局入口**,默认进"近期执行"项目,可用顶部下拉切换;② 从**会话区**进入 = **会话入口**,默认加载该会话已绑定的项目;**未绑定会话不显示工作台数据**,可经对话申请关联、由**项目主会话批准**后生效。
51
+ - **团队的第一使命不是执行,而是"把空项目变成需求与任务"**:
52
+ 1. 引入项目资料(md/doc);
53
+ 2. **需求梳理 → 优化 → 落盘需求文档**(FR-58);
54
+ 3. 定稿后**拆解成看板任务**并归因(FR-59)。
55
+ - **只有走到"已归因任务"之后,才进入执行**(队长派发 → 成员执行 → 反馈,FR-49/51)。
56
+ - 因此:**未归因任务被归因门拦截是预期**,不是"缺 todo"。
57
+
58
+ ---
59
+
60
+ ## 三、派发协议(入口 = 队长)
61
+
62
+ - **入口固定为承载环境(DSH)创建的 agent team 队长**:由队长领取目标任务并向下派发;不由人逐条手点。
63
+ - 派发顺序:按依赖就绪逐个认领;上游未就绪的任务**不得开工**。
64
+ - 队长可**反向调用**成员:为成员生成子任务(`team_tasks`)并指向成员角色/执行器。
65
+ - 目标未归因 / 任务在 `backlog` → **拦截**(未授权不开工)。
66
+
67
+ ### 反向调用链(示意)
68
+
69
+ ```
70
+ 人/工作台 ──派发──▶ 队长(lead)
71
+ │ 按模板 + 依赖
72
+ ▼
73
+ 成员(engineer/tester/reviewer/archivist)
74
+ │ 执行(hosted 或 cli:codex/cli:claude)
75
+ ▼
76
+ 反馈回写 ──▶ 工作台(任务/团队状态 + 审计)
77
+ ```
78
+
79
+ ---
80
+
81
+ ## 四、执行器规范(可配置外部 code CLI)
82
+
83
+ - **执行器可配置**:代码执行成员(`engineer`,必要时 `tester` 的复现脚本)可配置为外部 code CLI,如 `codex`、`claude`。
84
+ - **必须非交互**:显式非交互模式(如 `claude -p` / `codex exec`),**不得进入交互式会话**(会挂住)。
85
+ - **显式授权目录**:必须使用绝对路径;跨目录需显式授权(如 `--add-dir`)。
86
+ - **配额回退**:调用前做极短探测;配额不足 → **回退为成员自行执行**,并注明"因配额回退",**不降低验收标准**。
87
+ - **不采信未复核输出**:外部 CLI 的产出必须经成员复核 + 自测(`node --check` + `node --test`)。
88
+ - 细节与边界见 [`规范/04-决策与复盘.md`](./规范/04-决策与复盘.md)。
89
+
90
+ ---
91
+
92
+ ## 五、反馈回写契约(成员 → 工作台)
93
+
94
+ 成员每次执行**必须回写**以下最小集:
95
+
96
+ | 字段 | 含义 |
97
+ | --- | --- |
98
+ | `teamTask.status` | `open` / `running` / `completed` / `failed` / `cancelled` |
99
+ | `attempt.result` | 本次尝试结果(`passed` / `failed` / `blocked` + 简述) |
100
+ | `evidence` | 产出证据:diff 摘要 / 退出码 / 测试结果 / 复现步骤 |
101
+ | `actor` | 成员标识(角色 + 实例) |
102
+
103
+ - 回写经**工作台 API**(不是直接改库):`/api/teams/:id/tasks/:tt/outcome`、`/api/teams/:id/progress`、`/api/tasks/:ref/team-status`。
104
+ - **完成 ≠ done**:成员跑完 → 任务转 `in_review`(待验收);`done` 只能由人确认。
105
+ - 部分完成:完成项 `in_review`、失败项 `blocked`;**下游不解锁**。
106
+ - 全队失败 → 团队整体 `failed` + 可重试。
107
+
108
+ ---
109
+
110
+ ## 六、治理红线(固定,不可配)
111
+
112
+ 1. **执行侧不得写 `done`**:任何来自团队/成员/尝试的写请求,若目标状态 = `done` → 拒绝 + 审计。
113
+ 2. **未授权不开工**:`backlog` 任务不得被团队认领。
114
+ 3. **审查未过不解锁下游**:`kind=review` 未 pass → 下游保持 `blocked`。
115
+
116
+ 执行侧可写:`in_progress` / `in_review` / `blocked` / `canceled`。
117
+ **"两个 done 不相等"**:本项目库的 `done`(人工确认)≠ 承载环境 agent team 的 `completed`(成员跑完);红线只作用于"执行侧回流到本项目库的写路径"。
118
+
119
+ ---
120
+
121
+ ## 七、边界与严禁
122
+
123
+ - 不 commit / 不 push / 不 publish(commit 归队长/人;push/publish 需用户显式授权)。
124
+ - 不改范围外文件;同一文件串行修改(不并行改同一文件)。
125
+ - 不隐藏失败:失败原样上报,禁止"重试到成功再报"。
126
+ - 不进入交互式会话;不在无授权目录落盘。
127
+ - 不绕开工作台 API 直接改库。
128
+
129
+ ---
130
+
131
+ ## 八、与其它文档的关系
132
+
133
+ - 需求:[`需求文档.md`](./需求文档.md) §二 M(FR-49…FR-54,自主开发闭环)。
134
+ - 计划:[`计划文档.md`](./计划文档.md) §二C(P8)。
135
+ - 外部 CLI 授权:[`规范/04-决策与复盘.md`](./规范/04-决策与复盘.md)。
136
+
137
+ ### 8.1 分域声明(2026-10-23 · 只增不改)
138
+
139
+ **本文件约束的是「工作台派发路径」**:经工作台/承载环境(DSH)创建的团队,怎样建、怎样派、怎样回写、红线是什么。**编制单位=角色(executor)**。
140
+
141
+ **被派发项目自有的「会话团队」设定不在本文件作用范围内。** 典型例子:`项目-dsh-acp/docs/项目团队.md` 的 A/B/C 会话拓扑(Planner 独立 · Executor/Coder 共用同一会话 · Verifier 独立)。本文件**不改写、不降级、不覆盖**它们 —— 它们约束的是「人 ⇄ 会话」手转时的协作方式,**编制单位=会话**。
142
+
143
+ **路由规则(何时走哪条)**:
144
+
145
+ | 触发场景 | 走哪条路径 | 权威文档 |
146
+ | --- | --- | --- |
147
+ | 经工作台/DSH 把任务派发给 agent team(队友领取、证据回流看板、评审门把关) | 工作台派发路径 | **本文件** |
148
+ | 人直接开 A/B/C 类会话、人工转发指令(不经看板派发、不经评审门) | 项目自有会话团队 | **该项目自己的团队文档** |
149
+
150
+ **同名不同义(勿混用)**:工作台的 `planner` / `engineer` / `tester` / `reviewer` 是**派发单元(角色)**;项目的 `Planner` / `Executor` / `Coder` / `Verifier` 是**会话身份**。二者**语义可叠加**:同一件事可以是「会话 A 里的 Planner 同时作为工作台 `planner` 角色被派发」。读到时先问两件事 —— **这份文档是谁的**、**这个名字指的是角色还是会话**。
151
+
152
+ **若项目希望在工作台团队页看到自己的会话分工**:请在**项目侧**文档里写一份「角色 → 会话」映射(例如 `planner→A`、`engineer→B(Coder)`、`tester/reviewer→C`),**不要**为此改写本文件的角色定义。工作台团队页展示的是**派发角色**,不承担会话拓扑的表达。
153
+
154
+ **跨仓库不做的事**:本文件随包交付(见 `package.json#files`),被派发项目**无需自带**;**不在被派发项目里新建第二份 `团队agent.md`**(另建即制造重复与漂移)。
155
+
156
+ **分域后仍不变的红线**:无论走哪条路 —— `done` 只能由人确认(执行侧可写 `in_progress` / `in_review` / `blocked` / `canceled`);`backlog` 不得开工;审查未过不解锁下游。
157
+
158
+ ---
159
+
160
+ ## 九、智能体操作规范(随包)
161
+
162
+ > **本条与 FR-07 同源,不得另立第二份规范**:本节是 FR-22 所要求的「智能体操作规范」正本清单,随包交付(见 `package.json#files`),并与 [`需求文档.md`](./需求文档.md) 的 FR-07 边界一致(**先读 → 认领 → 执行 → 提交待验收 → 人确认**)。本节可独立阅读,不与本文件其它条款矛盾;若与 FR-07 出现表述分歧,**以 FR-07 为准**。
163
+
164
+ **一份自洽清单(六条,按操作顺序)**:
165
+
166
+ 1. **先读任务与评论再动手**。接单前先读该任务的状态、描述、**全部评论**与 `acceptance`(验收口径/复核动作);未读过就动手视为违规。读到的信息与预期不符(例如目标未归因),先停手确认,不要"边猜边干"。
167
+ 2. **`backlog` 不得执行**。处于 `backlog` 的任务,智能体**不得认领、不得推进**;只有人把它移出 `backlog`(到 `todo` 等可开工状态)后才可认领。被拦截是**预期**,不是"缺 todo"(互链:§三 派发协议、§六 红线 2)。
168
+ 3. **认领需声明身份**。认领(进入进行中)="由我负责",必须**显式声明身份**:角色 + 实例(如 `engineer@<实例>`)以及所在会话;系统会记录认领者/会话身份。匿名认领视为无效。
169
+ 4. **完成后提交待验收并附证据**。跑完只能把任务提交为 `in_review`(**待验收**),并附上"做了什么、怎么验证的"证据:diff 摘要 / 退出码 / 测试结果(`node --check` + `node --test`)/ 复现步骤。部分完成:完成项 `in_review`、失败项 `blocked`,下游不解锁(互链:§五 反馈回写契约)。
170
+ 5. **`done` 必须由人确认**。智能体**没有任何手段**把任务置为 `done`;`done` 只能由人在界面或命令行显式确认。执行侧可写状态仅 `in_progress` / `in_review` / `blocked` / `canceled`(互链:§六 红线 1、§五"完成 ≠ done")。
171
+ 6. **与他人冲突需重读再改**。发现目标已被他人改动(他人认领、评论新增、状态变化)时,**重读**最新版本再改,不得凭旧快照覆写;版本冲突按 `VERSION_CONFLICT`(退出码 5)处理 —— 重新读取 → 以最新版本重做改动 → 再提交,**不要**盲目重试同一份旧载荷。
@@ -0,0 +1,62 @@
1
+ /**
2
+ * acceptance.mjs —— 「验收标准缺省」的**唯一**口径入口(卡 `-176` / `-177`,2026-10-29)。
3
+ *
4
+ * 背景(口径 **X**,人拍板于 2026-10-29):`requirement_items.acceptance` **不做必填、不改 schema**。
5
+ * 实测 129 条里 **99 条 acceptance 为空**,而「空」与「当初没收集」不可辨 —— 强制必填会一刀切破
6
+ * 「改标题」这类无关操作;schema 迁移不可逆,审计 join 可查。故取**显式缺口标记**:
7
+ *
8
+ * · 回包 `acceptanceSet:false` —— 调用方一眼看出「这条没有验收口径」,而不是拿到一个看似成功的 201;
9
+ * · 缺省落一条 `governance_audit`(`action = requirement-acceptance-missing`)
10
+ * —— 「当初给没给验收」可事后按 `target = 条目编号` 查审计,不必加列。
11
+ *
12
+ * 纪律来源(产品内既有先例):`-172` 把「失败被包装成成功」改成显式
13
+ * (`AI_UNAVAILABLE` / `fallback:"rule"` / `dryRun`)—— 同一纪律套到 acceptance 上就是「显式缺口」。
14
+ *
15
+ * **HTTP 与 MCP 必须共用本文件**:两条写入口各写一份判断必然漂移 —— `-176` / `-177` 本来就是
16
+ * 「同一个缺口的两半」,各修各的就会长出两个口径。
17
+ *
18
+ * 落审计的**边界**(刻意如此,防审计洪水):只有**这次写入碰了 `acceptance`** 才落审计
19
+ * (新建条目 = 每次;改条目 = 仅当 patch 里带 `acceptance`)。`acceptanceSet` 则**永远**反映写入后的
20
+ * 真实状态 —— 于是一条 99/129 的空验收条目改标题时,回包照样会诚实告诉你 `acceptanceSet:false`,
21
+ * 但不会给审计表再添一行。
22
+ */
23
+
24
+ export const ACCEPTANCE_MISSING_ACTION = "requirement-acceptance-missing";
25
+
26
+ /** 「没给验收」的判定:`null` / `undefined` / 纯空白都算缺省(与 store 侧清空语义一致)。 */
27
+ export function isAcceptanceMissing(value) {
28
+ return value == null || String(value).trim() === "";
29
+ }
30
+
31
+ /**
32
+ * 给一次需求条目写入打「验收缺口」标记。
33
+ *
34
+ * @param {{recordAudit:Function}} store
35
+ * @param {{identifier?:string|null, acceptance?:any, actor?:string, entry?:string, detail?:object|null}} opts
36
+ * `entry` 必填语义上是「哪条写路径」(如 `mcp:requirement_upsert` / `http:POST /api/requirements/items`),
37
+ * 进 `governance_audit.reason`,便于按入口统计缺口。
38
+ * @returns {{acceptanceSet:boolean, auditId:string|null}}
39
+ */
40
+ export function markAcceptance(store, { identifier = null, acceptance = null, actor = "human", entry = "unknown", detail = null } = {}) {
41
+ if (!isAcceptanceMissing(acceptance)) return { acceptanceSet: true, auditId: null };
42
+ let auditId = null;
43
+ try {
44
+ auditId = store.recordAudit({
45
+ actor,
46
+ action: ACCEPTANCE_MISSING_ACTION,
47
+ target: identifier,
48
+ allowed: true,
49
+ reason: entry,
50
+ detail: JSON.stringify({ entry, identifier, ...(detail && typeof detail === "object" ? detail : {}) }),
51
+ });
52
+ } catch { auditId = null; } // 审计是旁证不是阻断:写审计失败不得让业务写入失败(与 contract-warn 同口径)
53
+ return { acceptanceSet: false, auditId };
54
+ }
55
+
56
+ /**
57
+ * 只读版:给「这次写入没碰 acceptance」的路径算回包标记(**不落审计**)。
58
+ * @returns {{acceptanceSet:boolean, auditId:null}}
59
+ */
60
+ export function acceptanceFlag(acceptance) {
61
+ return { acceptanceSet: !isAcceptanceMissing(acceptance), auditId: null };
62
+ }
@@ -0,0 +1,192 @@
1
+ /**
2
+ * advance.mjs —— 项目级「推进清单」与「决定回写」(2026-10-28 拍板 E1–E3)。
3
+ *
4
+ * 为什么需要它:工作台已有三份**按状态切片**的只读视图
5
+ * `projectWatchdog`(只扫 in_progress)· `projectDiagnostics`(in_progress/blocked/in_review)·
6
+ * `GET /reviews`(评审态)。三者都**不含 `todo`(可派发)卡**,也都不产出 `action` / `decision_id`
7
+ * ⇒ 人只能逐卡点开才知道"现在该干什么"。
8
+ *
9
+ * 本模块只做两件事:
10
+ * ① `buildAdvance` —— 五类合一、按"先解锁再推进"排序的**纯投影**(不写库、可复算、同状态字节级一致);
11
+ * ② `applyDecision` —— 把主会话里人的一句结论**幂等**落回卡(同 `decisionId` 只产生一次副作用)。
12
+ *
13
+ * 铁律(E3):**`done` 仍只由人点** —— `accept/complete` 必须 `actor === "human"`,否则 409。
14
+ */
15
+ import { createHash } from "node:crypto";
16
+
17
+ import { TbError } from "./errors.mjs";
18
+ import { projectWatchdog } from "./watchdog.mjs";
19
+
20
+ /** 五类待办;排序=先解锁(等人定)再推进(可开工)。 */
21
+ export const ADVANCE_KINDS = Object.freeze(["decide", "blocked", "review", "accept", "dispatch"]);
22
+ const KIND_RANK = Object.freeze({ decide: 0, blocked: 1, review: 2, accept: 3, dispatch: 4 });
23
+
24
+ /**
25
+ * 稳定的 `decision_id`:**不含时间戳、不含序号** ⇒ 同一待办在两次请求里 id 相同,
26
+ * 重复提交才能幂等;待办消失(卡进 done)后 id 自然不再出现。
27
+ */
28
+ export function advanceItemId(projectId, kind, taskRef, discriminator = "") {
29
+ return `adv-${createHash("sha1").update(`${projectId}|${kind}|${taskRef}|${discriminator}`).digest("hex").slice(0, 12)}`;
30
+ }
31
+
32
+ const refSortValue = (identifier) => {
33
+ const n = Number(String(identifier ?? "").replace(/^[^0-9]*/, ""));
34
+ return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER;
35
+ };
36
+
37
+ /** 分类一条卡(返回 null=不进清单,例如正常跑着的 in_progress / backlog)。 */
38
+ function classify(task, watchdog) {
39
+ const state = watchdog?.state ?? null;
40
+ const unattributed = !task.requirementId;
41
+ if (task.humanReviewState === "pending" || state === "awaiting-decision") {
42
+ return {
43
+ kind: "decide",
44
+ why: task.humanReviewState === "pending" ? "人工校验待结论" : "执行侧在提问,等人给结论",
45
+ actions: [{ code: "choose", label: "给结论" }],
46
+ };
47
+ }
48
+ if (task.status === "blocked" || state === "stalled") {
49
+ if (task.status === "blocked" && unattributed) {
50
+ return {
51
+ kind: "blocked",
52
+ why: "卡住了 + 未归因:补上需求条目前派发会被拒(EXECUTION_NOT_ATTRIBUTED)",
53
+ actions: [{ code: "attribute", label: "补归因" }, { code: "retry", label: "重试" }],
54
+ };
55
+ }
56
+ if (task.status === "blocked") {
57
+ return { kind: "blocked", why: `卡住了:${task.blockKind ?? "未分类"}`, actions: [{ code: "retry", label: "重试" }] };
58
+ }
59
+ return { kind: "blocked", why: "停滞:长时间无进展", actions: [{ code: "retry", label: "重试" }] };
60
+ }
61
+ if (task.status === "in_review") {
62
+ if (task.reviewState === "approved") {
63
+ return { kind: "accept", why: "评审已通过,等你点「完成」", actions: [{ code: "complete", label: "完成(只人)" }] };
64
+ }
65
+ return { kind: "review", why: "等评审", actions: [{ code: "approve", label: "评审通过" }, { code: "changes", label: "返工" }] };
66
+ }
67
+ if (task.status === "todo") {
68
+ if (unattributed) {
69
+ return {
70
+ kind: "blocked",
71
+ why: "未归因:派发会被拒(EXECUTION_NOT_ATTRIBUTED),先补需求条目",
72
+ actions: [{ code: "attribute", label: "补归因" }],
73
+ };
74
+ }
75
+ return { kind: "dispatch", why: "可开工(已归因),等你派发", actions: [{ code: "dispatch", label: "派发" }] };
76
+ }
77
+ return null;
78
+ }
79
+
80
+ /**
81
+ * 纯投影:同一状态重复调用**字节级一致**(不含 `now`/`minutes` 等随时间变化的字段)。
82
+ * `done` / `canceled` 一律不出现。
83
+ */
84
+ export function buildAdvance(store, projectId, { now = null } = {}) {
85
+ const project = store.requireProject(projectId);
86
+ const tasks = store.listTasks({ projectId })
87
+ .filter((t) => t.status !== "done" && t.status !== "canceled");
88
+ const watched = new Map((projectWatchdog(store, projectId, { now: now ?? Date.now() }) ?? []).map((r) => [r.identifier, r]));
89
+ const items = [];
90
+ for (const task of tasks) {
91
+ const verdict = classify(task, watched.get(task.identifier) ?? null);
92
+ if (!verdict) continue;
93
+ items.push({
94
+ id: advanceItemId(projectId, verdict.kind, task.identifier, verdict.why.includes("未归因") ? "unattributed" : ""),
95
+ kind: verdict.kind,
96
+ taskId: task.id,
97
+ taskRef: task.identifier,
98
+ title: task.title,
99
+ status: task.status,
100
+ requirementId: task.requirementId ?? null,
101
+ why: verdict.why,
102
+ actions: verdict.actions,
103
+ });
104
+ }
105
+ items.sort((a, b) => (KIND_RANK[a.kind] - KIND_RANK[b.kind]) || (refSortValue(a.taskRef) - refSortValue(b.taskRef)) || String(a.taskRef).localeCompare(String(b.taskRef)));
106
+ const counts = Object.fromEntries(ADVANCE_KINDS.map((k) => [k, 0]));
107
+ for (const item of items) counts[item.kind] += 1;
108
+ return { project: project.id, projectName: project.name ?? null, count: items.length, counts, items };
109
+ }
110
+
111
+ /** 把清单渲染成**可直接投给主会话**的指令装载块(P-B)。 */
112
+ export function renderAdvanceBlock(list) {
113
+ const head = `【项目推进清单 · ${list.projectName ?? list.project}】`;
114
+ if (list.count === 0) return `${head}\n当前无待办(0 项)。不需要写 todo。`;
115
+ const tally = ADVANCE_KINDS.map((k) => `${k} ${list.counts[k]}`).join(" / ");
116
+ const lines = list.items.map((item, i) => (
117
+ `${i + 1}. [${item.kind}] #${item.taskRef} ${item.title} —— ${item.why} decision_id=${item.id}`
118
+ ));
119
+ return [
120
+ head,
121
+ `共 ${list.count} 项待办(${tally})。请用 todo_write 把它们写成你的 todo,然后逐项推进:`,
122
+ ...lines,
123
+ "规则:① 卡片的「完成」**不是你勾 todo**,只能由人点(accept 类必须人工确认);",
124
+ ` ② 需要人定的事项**停下来等人回复**,拿到结论后调用 POST /api/projects/${list.project}/advance/<decision_id>/decide;`,
125
+ " ③ dispatch 类请走既有派发入口(派发团队 / 交主会话执行),不要自己改卡状态。",
126
+ ].join("\n");
127
+ }
128
+
129
+ /** 在主会话里找这条决定是否已经执行过(幂等重放判据)。 */
130
+ function findAppliedDecision(store, projectId, decisionId) {
131
+ const events = store.listProjectEvents(projectId, { limit: 500, order: "desc" }) ?? [];
132
+ for (const ev of events) {
133
+ if (ev.type !== "decision" || !ev.detail) continue;
134
+ try {
135
+ const parsed = JSON.parse(ev.detail);
136
+ if (parsed?.decisionId === decisionId) return { ...parsed, cursor: ev.cursor, taskRef: parsed.taskRef ?? null, at: ev.at };
137
+ } catch { /* 非 JSON 的历史 detail 忽略 */ }
138
+ }
139
+ return null;
140
+ }
141
+
142
+ /**
143
+ * 把一句决定落回卡:**幂等**(同 `decisionId` 第二次只返回首次结果,不再产生副作用)。
144
+ * 支持 choice:accept/complete(**仅人**)· review/approve · review/changes · blocked/retry · decide/&lt;任意结论&gt;
145
+ */
146
+ export function applyDecision(store, projectId, decisionId, { choice, note = null, actor = "human" } = {}) {
147
+ store.requireProject(projectId);
148
+ if (!choice) throw new TbError("USAGE_ERROR", "decide 必须带 choice(如 complete / approve / changes / retry,或一句结论)", { decisionId });
149
+ const applied = findAppliedDecision(store, projectId, decisionId);
150
+ if (applied) return { replay: true, decisionId, applied };
151
+
152
+ const list = buildAdvance(store, projectId);
153
+ const item = list.items.find((i) => i.id === decisionId);
154
+ if (!item) throw new TbError("ADVANCE_ITEM_NOT_FOUND", "该待办已不存在(可能已收口或状态已变),请重新拉取清单", { decisionId, projectId });
155
+
156
+ const task = store.getTaskById(item.taskId);
157
+ const wanted = String(choice);
158
+ let task2 = task;
159
+ if (item.kind === "accept") {
160
+ if (wanted !== "complete") throw new TbError("USAGE_ERROR", `accept 类只接受 choice=complete,收到 ${wanted}`, { decisionId });
161
+ // E3 红线:完成只能由人确认,执行侧/评审都不代点
162
+ if (String(actor) !== "human") throw new TbError("HUMAN_CONFIRM_REQUIRED", "「完成」只能由人确认(actor 必须是 human)", { decisionId, actor });
163
+ task2 = store.updateTask(task.identifier, { status: "done", expectedVersion: task.version, actor });
164
+ } else if (item.kind === "review") {
165
+ if (wanted === "approve") task2 = store.approveReview(task.identifier, { actor, comment: note ?? "" });
166
+ else if (wanted === "changes") task2 = store.requestChanges(task.identifier, { actor, comment: note ?? "" });
167
+ else throw new TbError("USAGE_ERROR", `review 类只接受 approve / changes,收到 ${wanted}`, { decisionId });
168
+ } else if (item.kind === "blocked") {
169
+ if (wanted === "retry") task2 = store.retryTaskExecution(task.identifier);
170
+ else if (wanted === "attribute") {
171
+ throw new TbError("ADVANCE_CHOICE_UNSUPPORTED", "补归因请走 POST /api/tasks/<ref>/attribution(本条决定不代做)", { decisionId, remedy: `POST /api/tasks/${task.identifier}/attribution {"requirement":"<条目>"}` });
172
+ } else throw new TbError("USAGE_ERROR", `blocked 类只接受 retry,收到 ${wanted}`, { decisionId });
173
+ } else if (item.kind === "dispatch") {
174
+ throw new TbError("ADVANCE_CHOICE_UNSUPPORTED", "派发请走既有派发入口,decide 不做派发", { decisionId, remedy: "POST /api/tasks/<ref>/execution/start 或团队派发端点" });
175
+ }
176
+
177
+ const detail = JSON.stringify({ decisionId, kind: item.kind, choice: wanted, note, actor, taskRef: item.taskRef });
178
+ const ev = store.recordTaskEvent(task.id, { type: "decision", to: wanted, actor: String(actor), detail });
179
+ const after = buildAdvance(store, projectId);
180
+ const stillThere = after.items.some((i) => i.id === decisionId);
181
+ return {
182
+ replay: false,
183
+ decisionId,
184
+ kind: item.kind,
185
+ choice: wanted,
186
+ taskRef: item.taskRef,
187
+ taskStatus: (task2 && task2.status) || task.status,
188
+ eventCursor: ev?.cursor ?? null,
189
+ remaining: after.count,
190
+ stillListed: stillThere,
191
+ };
192
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * agent-teams.mjs —— 列出"可用于执行的团队"(供工作台配置页做"任务执行团队选择")。
3
+ *
4
+ * 来源:
5
+ * - official : DSH 官方自带「智能体团队」(spawn_teammate / team_task_*) —— 不落本项目文件,作为常驻选项。
6
+ * - third-party: 工作区 `.agent-teams/<teamId>/team.json`(如 @nanmicoder/dsh-agent-teams)。
7
+ * (工作台本地 team_runs 由 store 侧提供。)
8
+ */
9
+ import { readdir, readFile } from "node:fs/promises";
10
+ import { join } from "node:path";
11
+
12
+ export const OFFICIAL_TEAM = {
13
+ id: "official",
14
+ name: "DSH 官方自带 · 智能体团队(编队)",
15
+ source: "official",
16
+ phase: "dsd-side",
17
+ memberCount: null,
18
+ members: [],
19
+ taskCount: null,
20
+ note: "由队长用 spawn_teammate 召集;编队页可见;不落项目文件",
21
+ };
22
+
23
+ /**
24
+ * 扫描工作区 `.agent-teams/*`(第三方引擎)。
25
+ * 只保留"由本项目主会话创建"的团队:`captainSessionId === mainSessionId`(未提供则全量)。
26
+ */
27
+ export async function scanAgentTeams(workspacePath, { mainSessionId = null } = {}) {
28
+ if (!workspacePath) return [];
29
+ const root = join(workspacePath, ".agent-teams");
30
+ let entries = [];
31
+ try { entries = await readdir(root, { withFileTypes: true }); } catch { return []; }
32
+ const out = [];
33
+ for (const entry of entries) {
34
+ if (!entry.isDirectory() || entry.name === "archive") continue;
35
+ try {
36
+ const j = JSON.parse(await readFile(join(root, entry.name, "team.json"), "utf8"));
37
+ const captainSessionId = j.captainSessionId ?? null;
38
+ if (mainSessionId && captainSessionId && captainSessionId !== mainSessionId) continue; // 非主会话创建 → 不列
39
+ out.push({
40
+ id: j.id ?? entry.name, name: j.name ?? entry.name, source: "third-party",
41
+ phase: j.phase ?? null, memberCount: (j.members || []).length,
42
+ members: (j.members || []).map((m) => m.name), taskCount: (j.tasks || []).length,
43
+ captainSessionId,
44
+ });
45
+ } catch { /* 跳过非法 */ }
46
+ }
47
+ return out;
48
+ }