taskboard-workbench 0.3.4 → 0.3.5

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 CHANGED
@@ -6,6 +6,59 @@
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.5] - 2026-11-17
10
+
11
+ > 主题:**把「派给谁、谁在跑、跑完记在哪」这条链在界面上闭合成可读的事实** —— 执行会话从「认得出卡」
12
+ > 进到「认得出它属于哪个项目」,派发从「一律新建」改为「优先复用已绑定空闲会话」,
13
+ > 执行记录从散落字段收成抽屉里的一个聚合段;另修四条团队执行期实测出来的缺陷
14
+ > (撤单不解阻塞 / 诊断不复检 / 零心跳且状态分叉 / 尝试摘要读不到执行方结论)。
15
+ > 版号续走 `0.3.x` patch(`0.4.0` 仍留给计划文档里预留的确认层 `acceptance_state`)。
16
+ > 读数:`node --test` **1375 / 0** · `release-precheck` **EXIT=0** · tarball **89** 文件。
17
+
18
+ ### 新增
19
+
20
+ - **执行会话绑定态(卡 `-263` / 需求 `R187`)** —— 认领 / 启动执行写下的 `tasks.session_id` 此前只进 `tasks`,
21
+ 不进 `project_sessions`,于是执行会话打开工作台被 FR-63 绑定门**整视图挡住**。
22
+ 新增派生绑定:会话被某张在办卡引用 ⇒ `bound=true · role=executor · derived=true`,并**按任务所属项目**解析归属
23
+ (不被会话 cwd 带偏);任务终态后同一会话自动回到 `bound=false`。显式批准仍压过派生。
24
+ `/api/projects/:id/sessions` 的 `executors` 只列派生项,不与主会话 / 已批准重复。
25
+ - **派发目标选取(卡 `-264` / 需求 `R188`)** —— 「启动执行」不再一律新建会话:主会话空闲 ⇒
26
+ `mode=reuse-bound`(**零新建**、任务书明写「不需要再申请关联」、且**不冒充批准**写授权行);
27
+ 全部在跑 ⇒ 新建并同步落 `approved` 授权 + 审计 `authorize-exec-session(execute-click)`。
28
+ 判不准不猜(`live=false` ⇒ 新建并标 `why=liveness-unknown`);跨工作区排除;投递失败**回落**且如实标 `fallbackReason`。
29
+ 预览端点纯只读(`createSession/sendPrompt/openSession` 全 0)。
30
+ - **抽屉「执行记录」聚合段(卡 `-258` / `-268` / 需求 `R184`)** —— `task_evidence` 四节证据、最近一次尝试、
31
+ 产物清单收成一个段,不再散落在抽屉第 7 段与记账文案里。
32
+ - **团队任务 ↔ 看板卡只读映射(卡 `-247` / 需求 `R178` ④)** —— `team_tasks` 与 `.agent-teams` 此前零桥接,
33
+ 两套任务系统只能靠人脑对应;新增只读映射,每张卡可反查团队任务编号。
34
+ - **批量生成任务补全卡片详情(卡 `-273` / 需求 `R189`)** —— 「批量生成任务」此前只产出标题,卡片不可执行。
35
+ 现按规范 07 装配正文(acceptance 透传 + 七段骨架兜底),并配套 `tools/backfill-split-detail.mjs` 回填存量。
36
+
37
+ ### 变更
38
+
39
+ - **`taskboard_update_status` 状态取值统一英文枚举(卡 `-262` / 需求 `R186`)** —— 工具描述写中文
40
+ (待验收 / 受阻 / 取消),实现只认英文枚举,二者对不上时调用方按描述写必然被拒。描述、参数、报错、下发文案四处口径统一。
41
+ - **`README` 的 DSH 版本要求与 `engines` 对齐** —— 旧文案停留在 `0.2.0-rc.2`,`engines.dsh` 已是 `>=0.2.1-rc.3`。
42
+
43
+ ### 修复
44
+
45
+ - **撤单解除依赖阻塞(卡 `-253` / 需求 `R181`)** —— `isTaskReady` 只认 `done`,前置撤单后下游**永久受阻**,
46
+ 且无任何入口能解。现 `canceled` 视为不再阻塞。
47
+ - **诊断复检与假阳性收敛(卡 `-248` / 需求 `R178` ⑤)** —— 诊断只增不减(全库 `review_deadlock` 未解决 25 条,
48
+ 修复后仍 open)、且 heartbeat 为空即判停滞(5 张产物齐全的卡被误报)。现修复后自动重扫并 resolve;
49
+ 停滞判据先查 `changedPaths` / 产物是否存在再报。
50
+ - **执行期心跳与在途 run 闭合(卡 `-260` / `-269` / 需求 `R185`)** —— 实测「22 分 51 秒只有 1 次心跳」,
51
+ 且卡已进待验收而尝试仍显示「进行中 3 分 55 秒」。现周期心跳,进入 `in_review` 即闭合在途 run。
52
+ - **尝试摘要承载执行方结论(卡 `-259` / 需求 `R184`)** —— 摘要此前写死记账文案,读不出执行者说了什么;
53
+ 现承载真实结论,缺省显式标「执行方未回写摘要」。
54
+
55
+ ### 工具
56
+
57
+ - `tools/audit-data-norms.mjs` —— 条目 / 卡片骨架、长度、流程可见性**只读**核查(四个项目通用)。
58
+ - `tools/bench-session-binding.mjs` —— 执行会话绑定态 13 项,临时 dataDir + 随机端口 + 真 HTTP,不起浏览器。
59
+ - `tools/bench-dispatch-target.mjs` —— 派发目标选取 29 项,含记录型假宿主通道与 `TB_BENCH_DISPATCH_REVERSE` 反证入口。
60
+ - `tools/bench-exec-record.mjs` —— 抽屉执行记录聚合段(真 headless Chrome)。
61
+
9
62
  ## [0.3.4] - 2026-11-12
10
63
 
11
64
  > 主题:**把「谁来执行、由谁记账」这条口径钉死** —— CLI 执行者不再由看板自己 spawn,而是把确切的命令、
package/README.md CHANGED
@@ -69,7 +69,7 @@ node cli/tb.mjs project list # 或用 CLI 直接操作
69
69
  | 项 | 值 |
70
70
  | --- | --- |
71
71
  | Node.js | `>= 22.5.0`(依赖 `node:sqlite`) |
72
- | DSH | `0.2.0-rc.2` 线真机验证通过(`0.2.1-alpha.1` 历史走通) |
72
+ | DSH | `>=0.2.1-rc.3`(与 `package.json#engines.dsh` 一致);`0.2.2-rc.3` 真机验证通过 |
73
73
  | 运行时依赖 | 无(`dependencies` 为空) |
74
74
 
75
75
  ## 快速上手(CLI)
package/index.js CHANGED
@@ -669,6 +669,16 @@ export function apply(ctx, config) {
669
669
  } catch (error) {
670
670
  console.error(`[taskboard-workbench] run reconcile error: ${error?.message ?? error}`);
671
671
  }
672
+ // 卡 `-260`(R185):**经主会话下发的执行也打心跳**。
673
+ // `-257` 之后 CLI 执行器默认交项目主会话下发,服务端没有本地进程可挂心跳 —— 真机 `-248`
674
+ // 一条 22 分 51 秒的成功尝试 `heartbeats` 恒为 1。这里每拍(30s)只给「绑定的会话确实在跑
675
+ // (running / 有待消费消息)」的尝试打一拍,会话空闲则一拍都不打(不臆造)。
676
+ try {
677
+ const beat = runtime.store.heartbeatDispatchedRuns();
678
+ if (beat.length) console.log(`[taskboard-workbench] heartbeat ${beat.length} 张在途卡(主会话执行中)`);
679
+ } catch (error) {
680
+ console.error(`[taskboard-workbench] dispatched heartbeat error: ${error?.message ?? error}`);
681
+ }
672
682
  for (const project of listLoopProjects(runtime.store)) {
673
683
  runExecutionLoop({ store: runtime.store, events: runtime.events, projectId: project.id })
674
684
  .then((r) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.3.4",
3
+ "version": "0.3.5",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -155,6 +155,24 @@
155
155
 
156
156
  **分域后仍不变的红线**:无论走哪条路 —— `done` 只能由人确认(执行侧可写 `in_progress` / `in_review` / `blocked` / `canceled`);`backlog` 不得开工;审查未过不解锁下游。
157
157
 
158
+ ### 8.2 团队任务 ↔ 看板卡映射(2026-11-12 · 只增不改 · 卡 `-247`)
159
+
160
+ **两套账本,各自记各自的**(本节只声明关系,不改任何一条既有定义):
161
+
162
+ | 侧 | 真源 | 与看板卡的关联 |
163
+ | --- | --- | --- |
164
+ | 工作台本地 | `team_runs` / `team_members` / `team_tasks` | `team_tasks.task_id → tasks(id)`(**真外键**) |
165
+ | 承载环境 agent-team 插件 | 工作区 `.agent-teams/<team>/team.json` | **无卡号字段**;卡号只以自由文本出现在任务描述/产出里 |
166
+
167
+ **本仓库提供的桥是「只读同步器」**(`src/core/team-bridge.mjs`):请求时现读 `.agent-teams/*/team.json`,用「**项目自有卡号在团队任务文本里全词命中**」推导卡 ↔ `t-id`,并回带**命中字段与片段**(`GET /api/projects/:id/team-bridge`;单卡反查在 `GET /api/tasks/:ref/team` 的 `bridge` 段)。
168
+
169
+ **四条硬口径**:
170
+
171
+ 1. **只读**:不写 `team_tasks`、不改 `.agent-teams/**`、不改 schema、不动历史数据;推导结果**不入库**(没有第二份真源,也就没有漂移)。
172
+ 2. **不写库的理由**:本地侧 `team_tasks` 挂着活跃锁(同一卡只允许一个活跃团队任务)⇒ 把插件团队写进去会把看板侧对**同一张卡**的合法派发挡成 `TASK_LOCKED`;且插件的 `completed` ≠ 看板的 `done`(后者只能人确认)⇒ 状态映射必然带歧义。
173
+ 3. **推导不是登记**:插件任务没有卡号字段 ⇒ 这是**文本反查**,不是真外键。界面与回包都如实标注「只读推导 + 命中字段」,**不冒充真登记**。
174
+ 4. **命中不到就明说**:反查不到 ⇒ 明文声明「**看板只展示、不参与团队状态**」—— 看板侧状态与团队侧状态互不影响,**看板的「完成」仍只能由人确认**。**不写**「没有团队在跑」(那是猜)。
175
+
158
176
  ---
159
177
 
160
178
  ## 九、智能体操作规范(随包)
@@ -14,7 +14,7 @@ import { BLOCK_RECURRENCE_LIMIT, DEFAULT_FAILURE_LIMIT, QUOTA_AUTH_ERROR_RE } fr
14
14
  import { STALL_THRESHOLD_MS, assessTask, latestProgressComment, runInFlight } from "./watchdog.mjs";
15
15
  import { REVIEW_IDLE_MS, detectReviewDeadlock } from "./review.mjs";
16
16
  import { categoryLabel, classifyHumanReview, isHumanReviewTask } from "./human-review.mjs";
17
- import { detectUntakenDelivery } from "./delivery.mjs";
17
+ import { detectUntakenDelivery, isConclusionComment } from "./delivery.mjs";
18
18
 
19
19
  /** 诊断类型(FR-79 验收里逐个点名的八类规则)。 */
20
20
  export const DIAGNOSTIC_KINDS = Object.freeze([
@@ -305,6 +305,98 @@ export function isExecutionClassCard(task) {
305
305
  return true;
306
306
  }
307
307
 
308
+ // ---------------------------------------------------------------------------
309
+ // 交付产物事实(卡 `-248` · 需求 `R178` ⑤ ·「heartbeat 空先查产物」)
310
+ // ---------------------------------------------------------------------------
311
+
312
+ /**
313
+ * 「卡上已有交付产物」的**评论侧标记**(看板自己的交付约定)。
314
+ *
315
+ * 为什么必须有评论这一路:真机(`scada-vibe-1…7`)的活是**宿主 agent team** 干的 ——
316
+ * 它只往卡上贴评论,**不写 `task_evidence`**(FR-106 的结构化证据行是 MCP/HTTP 入口才写的),
317
+ * **也不建 `task_runs` 尝试记录**(那条路不建尝试)。只认结构化证据 + 成功尝试 ⇒ 真机那批卡照样
318
+ * 被判「停滞 / 无人认领」—— 这正是需求条目 `R178` ⑤ 说的「判据只看 heartbeat / reviewer 空,
319
+ * 不看产物是否存在(真机:5 卡 `stalled`+`unclaimed` 高危 10 条,产物齐全)」。
320
+ *
321
+ * 标记只取「**交付动作**」与「**交付声明**」两类,刻意避开两类会误伤的说法:
322
+ * · 不取 `进度` / `反馈` 等**过程**词 —— 过程汇报不代表产物齐全;
323
+ * · 不取裸词 `产出` —— 看板自己的系统留痕「…将产出「评审死锁」诊断。」含这两个字。
324
+ */
325
+ export const ARTIFACT_COMMENT_MARKERS = Object.freeze([
326
+ "请求评审", // 「**请求评审(执行侧)**。产出:`…`」—— 交付动作本身
327
+ "人工验收", // 「请求人工验收」/「请人工验收」
328
+ "复审通过", // 「**复审通过,请求人工验收**」
329
+ "产出:", // 「产出:`路径`」—— 显式声明产物(带全角冒号,避开系统留痕里的「产出「」)
330
+ "证据(四节)", // 本仓四节交付格式
331
+ "证据回流",
332
+ "【证据",
333
+ "## 证据",
334
+ ]);
335
+
336
+ /**
337
+ * 交付产物事实查询(**只读**、纯判定、零写库)。
338
+ *
339
+ * 回答一个问题:**这张卡的活到底干了没有?** 三个来源,任一成立即视为「产物已交」:
340
+ * ① 结构化交付证据(FR-106 `task_evidence`:判定/偏离/边界/产物 四字段齐 + artifact_refs)——最硬;
341
+ * ② 成功尝试记录(`task_runs.outcome === "success"`)—— 执行器交了作业;
342
+ * ③ 交付证据评论(看板自己的交付约定,见 `ARTIFACT_COMMENT_MARKERS`)。
343
+ *
344
+ * **返工作废**:产物之后又出现「返工」事件(`changes_requested`)⇒ 那一版产物已被判不合格,
345
+ * 不再算数 —— 否则「返工之后没人接着干」这种**真停滞**会被吞掉(宁可假阳性不可漏报)。
346
+ *
347
+ * @returns {{delivered: boolean, at: string|null, source: string|null, summary: string, revoked: boolean}}
348
+ */
349
+ export function deliveredArtifacts(store, task, { comments = [], runs = [] } = {}) {
350
+ const empty = { delivered: false, at: null, source: null, summary: "", revoked: false };
351
+ if (!task) return empty;
352
+ const candidates = [];
353
+
354
+ // ① 结构化交付证据(FR-106)
355
+ try {
356
+ const ev = typeof store?.latestTaskEvidence === "function" ? store.latestTaskEvidence(task.identifier) : null;
357
+ if (ev && Array.isArray(ev.artifacts) && ev.artifacts.length > 0) {
358
+ candidates.push({ source: "evidence", at: ev.createdAt ?? null, summary: `结构化交付证据(${ev.artifacts.length} 项产物)` });
359
+ }
360
+ } catch { /* 取不到就当没有 */ }
361
+
362
+ // ② 成功尝试记录(执行器交了作业)
363
+ for (const run of Array.isArray(runs) ? runs : []) {
364
+ if (String(run?.outcome ?? "") !== "success") continue;
365
+ candidates.push({ source: "run-success", at: run.endedAt ?? run.startedAt ?? null, summary: `第 ${run.attempt ?? "?"} 次尝试执行成功` });
366
+ }
367
+
368
+ // ③ 交付证据评论(agent team / 人工贴证据走评论路径)
369
+ for (const c of Array.isArray(comments) ? comments : []) {
370
+ const body = String(c?.body ?? "");
371
+ if (!body) continue;
372
+ if (!isConclusionComment(body)) continue; // 系统留痕不是产物
373
+ if (!ARTIFACT_COMMENT_MARKERS.some((m) => body.includes(m))) continue;
374
+ candidates.push({ source: "delivery-comment", at: c?.createdAt ?? null, summary: "交付证据评论" });
375
+ }
376
+
377
+ if (!candidates.length) return empty;
378
+ const atOf = (c) => { const t = Date.parse(String(c.at ?? "")); return Number.isFinite(t) ? t : -Infinity; };
379
+ // 取**最近**的一份产物(返工判据要跟最新那份对齐)
380
+ const latest = candidates.reduce((a, b) => (atOf(b) > atOf(a) ? b : a));
381
+
382
+ // 返工作废:产物之后出现返工 ⇒ 那一版产物已被判不合格,不再算数
383
+ let reworkAt = -Infinity;
384
+ try {
385
+ const events = typeof store?.listTaskEvents === "function" ? store.listTaskEvents(task, { order: "desc", limit: 200 }) : [];
386
+ for (const e of Array.isArray(events) ? events : []) {
387
+ if (String(e?.type ?? "") !== "changes_requested") continue;
388
+ const t = Date.parse(String(e?.at ?? ""));
389
+ if (Number.isFinite(t) && t > reworkAt) reworkAt = t;
390
+ }
391
+ } catch { /* 取不到就当没返工 */ }
392
+
393
+ // 返工作废:产物之后出现返工 ⇒ 那一版产物已被判不合格,不再算数。
394
+ // 用 `>=` 而不是 `>`:返工与交付**可能落在同一毫秒**(评审 → 打回 → 立刻重投都是进程内连写),
395
+ // 用 `>` 会把「同一毫秒的返工」漏判成「产物仍有效」⇒ 真停滞被吞掉(宁可假阳性不可漏报)。
396
+ const revoked = Number.isFinite(reworkAt) && reworkAt >= atOf(latest);
397
+ return { delivered: !revoked, at: latest.at ?? null, source: latest.source, summary: latest.summary, revoked };
398
+ }
399
+
308
400
  export const DIAGNOSTIC_RULES = Object.freeze([
309
401
  {
310
402
  kind: "block_loop",
@@ -333,6 +425,12 @@ export const DIAGNOSTIC_RULES = Object.freeze([
333
425
  const { task, watchdog, dismissed } = ctx;
334
426
  if (dismissed.has("stalled")) return null;
335
427
  if (watchdog?.state !== "stalled") return null;
428
+ // 卡 `-248`(需求 `R178` ⑤ ·「heartbeat 空先查产物」):
429
+ // 「疑似停滞 N 分钟**无进展回报**」的前提是**没交过活**。若卡上已有交付产物(结构化证据 /
430
+ // 成功尝试 / 交付证据评论),那个前提不成立 ⇒ 不报。
431
+ // 不报还有一层安全理由:本诊断的首选动作是「退回待办(重新派发)」,对一张**已经交过活**的卡
432
+ // 再派一遍 = 让执行侧把做完的活重做一遍,正是 FR-86 说的同文件双写风险。
433
+ if (ctx.artifacts?.delivered) return null;
336
434
  const enc = encodeRef(task.identifier);
337
435
  const offline = watchdog.reason === "session-offline";
338
436
  return {
@@ -362,6 +460,10 @@ export const DIAGNOSTIC_RULES = Object.freeze([
362
460
  if (sessionState?.running) return null;
363
461
  if (!sessionState?.sessionId && runInFlight(currentRun, { now: ctx.now, thresholdMs: ctx.thresholds?.stallMs })) return null;
364
462
  if (claim?.locked && !claim?.expired) return null;
463
+ // 卡 `-248`(需求 `R178` ⑤ ·「heartbeat 空先查产物」):
464
+ // 本诊断的原文是「…**这条任务事实上没人干**」—— 若卡上已有交付产物,这句话**本身就是假的**
465
+ // (有人干了,只是没续认领 / 没改状态)⇒ 不报。真没产物时照报(宁可假阳性不可漏报)。
466
+ if (ctx.artifacts?.delivered) return null;
365
467
  const why = claim?.locked && claim?.expired ? "认领已过期" : claim?.locked ? "认领心跳陈旧" : "未被执行者认领";
366
468
  return {
367
469
  kind: "unclaimed", severity: "high",
@@ -726,6 +828,9 @@ export function collectContext(store, task, { now = Date.now(), thresholds = DEF
726
828
  limitSource: limitOverride != null ? "task" : "default",
727
829
  },
728
830
  runs: attempts,
831
+ // 卡 `-248`:「heartbeat 空先查产物」的**前置事实**(只读、零写库)。
832
+ // `stalled` / `unclaimed` 两条规则先看它,再决定要不要报。
833
+ artifacts: deliveredArtifacts(store, task, { comments, runs: attempts }),
729
834
  // FR-83:评审死锁由**真实判定**给出(调用方可显式覆盖,便于单测/回放)
730
835
  review: review === null
731
836
  ? detectReviewDeadlock(store, task, { now, idleMs: thresholds.reviewIdleMs ?? REVIEW_IDLE_MS })
@@ -753,15 +858,43 @@ export function evaluateTaskDiagnostics(store, ref, { now = Date.now(), threshol
753
858
  return { task, diagnostics: saved.active, summary: summarizeDiagnostics(saved.active), resolved: saved.resolved };
754
859
  }
755
860
 
861
+ /**
862
+ * 复检:终态卡(`done` / `canceled`)的遗留诊断**只收口、不新增**(卡 `-248` · 需求 `R178` ⑤)。
863
+ *
864
+ * 为什么单独一个函数、而不是直接 `evaluateTaskDiagnostics`:
865
+ * · 终态卡**不该**再产出任何诊断(`owner-role-mismatch` 等规则本就排除 done/canceled);
866
+ * · 但库里可能留着上一轮 open 的行 —— 诊断是「只增不减」的,那些行会永远挂着。
867
+ * 真机读数(2026-11-12,只读):`scada-vibe-11`(`canceled`)的 `review_deadlock` 仍 open、
868
+ * `count=19`;本仓 6 张 `done` 卡共 11 行 `stalled`/`unclaimed`/`review_deadlock` 仍 open。
869
+ * · 收口走 `saveTaskDiagnostics(ref, [])` —— 与规则产出的诊断**同一张表、同一套字段**,
870
+ * `resolved_at` 留痕、历史可回溯(不删数据)。
871
+ */
872
+ function closeTerminalDiagnostics(store, task, { now } = {}) {
873
+ let open = [];
874
+ try { open = typeof store.listTaskDiagnostics === "function" ? store.listTaskDiagnostics(task) : []; } catch { open = []; }
875
+ if (!open.length) return [];
876
+ try {
877
+ const saved = store.saveTaskDiagnostics(task.identifier, [], { now });
878
+ return saved?.resolved ?? [];
879
+ } catch { return []; }
880
+ }
881
+
756
882
  /**
757
883
  * 项目级诊断:对"可能需要人介入"的任务逐个评估(进行中 / 受阻 / 待验收),
758
884
  * 返回 { rows, summary }。只读路径也可以调用(会同步落库,保证 count 有意义)。
885
+ *
886
+ * 卡 `-248`:**复检** —— 扫描集之外的终态卡(done/canceled)也走一遍,
887
+ * 把它们身上遗留的诊断**收口**(见 `closeTerminalDiagnostics`);这是「诊断只增不减」的正面修法。
759
888
  */
760
889
  export function projectDiagnostics(store, projectId, { now = Date.now(), thresholds = DEFAULT_THRESHOLDS, persist = true } = {}) {
761
890
  const statuses = new Set(["in_progress", "blocked", "in_review"]);
762
- const tasks = store.listTasks({ projectId }).filter((t) => statuses.has(t.status) || t.triageAt);
891
+ const tasks = store.listTasks({ projectId });
763
892
  const rows = [];
764
893
  for (const task of tasks) {
894
+ if (!(statuses.has(task.status) || task.triageAt)) {
895
+ if (persist) closeTerminalDiagnostics(store, task, { now });
896
+ continue;
897
+ }
765
898
  const r = evaluateTaskDiagnostics(store, task, { now, thresholds, persist });
766
899
  for (const d of r.diagnostics) rows.push({ ...d, identifier: task.identifier, title: task.title, status: task.status });
767
900
  }
@@ -0,0 +1,144 @@
1
+ /**
2
+ * 派发目标解析(卡 `-264` / 需求 `R188`)—— **纯逻辑 + 注入探活**,不碰宿主、不写库。
3
+ *
4
+ * 背景(用户原话,2026-11-13):默认指派 dsh 或其他 agent 授权执行任务卡片时,**应优先选取已绑定本项目的
5
+ * 空闲会话接手**;没有绑定会话时,**要求第一次授权**,或在卡片点「执行」时**把授权指令一并带进去**。
6
+ *
7
+ * 此前行为:`/api/tasks/:ref/execute` 在没显式给 sessionId 时**一律新建会话** ——
8
+ * · 每派一张卡就多一条孤立会话(`project_sessions` 无行),只能靠 `-263` 的派生绑定才不被门挡住;
9
+ * · 项目里明明有空闲的主会话 / 已批准会话,却完全没被利用(主会话闲着也不用)。
10
+ *
11
+ * 判据分层(**只选判得出空闲的**,判不准一律不算 —— 不猜):
12
+ * 1. 主会话(`projects.initial_session_id`)
13
+ * 2. 已批准关联会话(`project_sessions.status='approved'`,最近活跃优先)
14
+ * 3. 派生执行会话(`tasks.session_id`,`-263`)—— **仅当它名下没有 `in_progress` 卡**(干完了待验收的才算空闲)
15
+ * 空闲 = 宿主判得出:`exists !== false && live === true && running === false && pending === 0`。
16
+ */
17
+
18
+ /** 会话是否「此刻空闲」——判不准(live=false / 无宿主通道 / 存在性未知但无 live)一律 false。 */
19
+ export function isIdleLiveness(liveness) {
20
+ if (!liveness || typeof liveness !== "object") return false;
21
+ if (liveness.exists === false) return false; // 确认失效
22
+ if (liveness.live !== true) return false; // 进程内没有 Agent ⇒ 不知道它空不空闲(不猜)
23
+ if (liveness.running === true) return false; // 正在跑
24
+ if (Number(liveness.pending ?? 0) > 0) return false; // inbox 里还有没消费的指令
25
+ return true;
26
+ }
27
+
28
+ /**
29
+ * 候选来源的**验收口径命名** —— `main` / `approved` / `executor`(需求 `R188` 验收①点名的三档)。
30
+ *
31
+ * 为什么另起一档(不直接用 `role`):`role` 是**内部**说法(`associated` = 已批准关联会话),
32
+ * 而验收条款对外说的是「main / approved / executor」—— 对外回包与界面文案用 `kind`,
33
+ * 免得「同一个东西两个名字」在回包里对不上。
34
+ */
35
+ const REUSED_FROM_KINDS = { main: "main", associated: "approved", executor: "executor" };
36
+
37
+ /** 把内部 `role` 映射成验收口径的来源名(认不出来的角色 ⇒ null,不臆断)。 */
38
+ export function reusedFromKind(role) {
39
+ return Object.prototype.hasOwnProperty.call(REUSED_FROM_KINDS, role) ? REUSED_FROM_KINDS[role] : null;
40
+ }
41
+
42
+ /**
43
+ * 枚举「已绑定本项目的会话」候选(**未探活**,纯读库)。
44
+ * 顺序 = 主会话 > 已批准关联 > 派生执行会话;同一会话只出现一次(高优先级的那条胜出)。
45
+ */
46
+ export function listBoundCandidates(store, projectId) {
47
+ const project = store.getProject(projectId) ?? null;
48
+ const out = [];
49
+ const seen = new Set();
50
+ const push = (item) => {
51
+ if (!item?.sessionId || seen.has(item.sessionId)) return;
52
+ seen.add(item.sessionId);
53
+ out.push(item);
54
+ };
55
+ if (project?.initialSessionId) push({ sessionId: project.initialSessionId, role: "main", kind: "main", source: "project-main" });
56
+ const approved = (store.listProjectSessions(projectId) ?? [])
57
+ .filter((row) => row.sessionId && row.status === "approved")
58
+ .sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
59
+ for (const row of approved) push({ sessionId: row.sessionId, role: "associated", kind: "approved", source: "project-approved", updatedAt: row.updatedAt ?? null });
60
+ // 派生执行会话:名下只要还有 in_progress 卡,就说明它正干着别的活 —— 不作为「空闲候选」。
61
+ for (const ex of store.listExecutorSessions(projectId) ?? []) {
62
+ const statuses = Array.isArray(ex.statuses) ? ex.statuses : [];
63
+ if (statuses.includes("in_progress")) continue;
64
+ push({ sessionId: ex.sessionId, role: "executor", kind: "executor", source: "task-derived", updatedAt: ex.lastActivityAt ?? null, tasks: ex.tasks ?? [] });
65
+ }
66
+ return out;
67
+ }
68
+
69
+ /**
70
+ * 选出派发目标。返回:
71
+ * ```
72
+ * { decision: "reuse" | "create-and-authorize",
73
+ * target: { sessionId, role, kind, source, liveness } | null,
74
+ * candidates: [{ sessionId, role, kind, source, idle, why, liveness }],
75
+ * reason }
76
+ * ```
77
+ * `sessionStateOf(sessionId)` / `sessionOriginOf(sessionId, project)` 由调用方注入(api 层已有同一份实现,
78
+ * 这里**不另写第二份探活**)。
79
+ */
80
+ export async function pickDispatchTarget(store, projectId, { sessionStateOf = null, sessionOriginOf = null } = {}) {
81
+ const project = store.getProject(projectId) ?? null;
82
+ const candidates = [];
83
+ for (const c of listBoundCandidates(store, projectId)) {
84
+ // 归属校验:别把**别的项目工作区**的会话派给这张卡(FR-84 的同一把尺子)。
85
+ let origin = null;
86
+ if (typeof sessionOriginOf === "function") {
87
+ try { origin = await sessionOriginOf(c.sessionId, project); } catch { origin = null; }
88
+ }
89
+ let liveness = null;
90
+ if (typeof sessionStateOf === "function") {
91
+ try { liveness = await sessionStateOf(c.sessionId); } catch { liveness = null; }
92
+ }
93
+ let why = null;
94
+ let idle = false;
95
+ if (origin?.mismatch === true) why = "other-workspace";
96
+ else if (!liveness) why = "no-liveness";
97
+ else if (liveness.exists === false) why = "session-gone";
98
+ else if (liveness.live !== true) why = "liveness-unknown";
99
+ else if (liveness.running === true) why = "running";
100
+ else if (Number(liveness.pending ?? 0) > 0) why = "pending-prompts";
101
+ else { idle = true; why = "idle"; }
102
+ candidates.push({ ...c, idle, why, liveness, originCwd: origin?.cwd ?? null });
103
+ }
104
+ const hit = candidates.find((c) => c.idle) ?? null;
105
+ return {
106
+ decision: hit ? "reuse" : "create-and-authorize",
107
+ target: hit ? { sessionId: hit.sessionId, role: hit.role, kind: hit.kind ?? reusedFromKind(hit.role), source: hit.source, liveness: hit.liveness } : null,
108
+ candidates,
109
+ reason: hit ? "bound-idle" : (candidates.length ? "bound-but-busy-or-unknown" : "no-bound-session"),
110
+ };
111
+ }
112
+
113
+ /**
114
+ * 投给**复用会话**的任务书。与 CLI 任务书(`executor.mjs#buildTaskPrompt`)不同:
115
+ * 这是给**宿主会话**的短指令 —— 它本来就在工作区里,不需要 `--add-dir` / `cd` 那一套。
116
+ * 但必须说清三件事:① 已授权(别再申请关联);② 回写口径(四节);③ 红线(不得置 done)。
117
+ */
118
+ export function buildReuseDirective({ task, project, target = null } = {}) {
119
+ const lines = [
120
+ `任务 ${task?.identifier ?? ""}:${task?.title ?? ""}`,
121
+ ``,
122
+ `本会话已绑定项目「${project?.name ?? project?.id ?? ""}」(${project?.id ?? ""})—— 工作台不会挡你;`,
123
+ `这是**已授权**的派发(来源:${target?.role ?? "已绑定会话"}),**不需要再申请关联**。`,
124
+ ];
125
+ if (task?.acceptance) lines.push(`验收:${task.acceptance}`);
126
+ if (task?.verifyCommand) lines.push(`复核动作:${task.verifyCommand}`);
127
+ lines.push("操作指引:执行 → 回写四节证据(判定 / 偏离说明 / 边界自查 / 产物路径)→ 提交「待验收」;**不得置「完成」**(人工确认)。");
128
+ lines.push("若本会话正在处理别的任务:先做完或显式说明冲突,不要静默丢弃本单。");
129
+ return lines.join("\n");
130
+ }
131
+
132
+ /** 投给**新建会话**的授权段(会拼进 `createSession({preset})` 与任务书)。 */
133
+ export function buildAuthorizationDirective({ task, project, sessionId = null } = {}) {
134
+ return [
135
+ `【授权】本会话由看板「启动执行」显式授权,**首次绑定**项目「${project?.name ?? project?.id ?? ""}」(${project?.id ?? ""})。`,
136
+ `你**不得再申请**关联(本会话已被授权),配置页「会话关联」会显示本会话;工作台不会挡你。`,
137
+ task?.identifier ? `本单:任务 ${task.identifier}:${task.title}` : "",
138
+ // 与**复用路径**的任务书对齐:新建出来的会话同样是「空手接单」,不告诉它验收标准与复核动作,
139
+ // 它就只能凭标题猜「做成什么样算做完」。(`R188` 判据锚点:任务书要写明哪张卡 + 回写与红线。)
140
+ task?.acceptance ? `验收:${task.acceptance}` : "",
141
+ task?.verifyCommand ? `复核动作:${task.verifyCommand}` : "",
142
+ `完成后回写四节证据并提交「待验收」;**不得置「完成」**(人工确认)。`,
143
+ ].filter(Boolean).join("\n");
144
+ }
@@ -71,15 +71,58 @@ export function resolveCliExecutor(settings, { role = "engineer" } = {}) {
71
71
  ?? null;
72
72
  }
73
73
 
74
- /** CLI 参数:非交互 + 显式放行工具 + 允许访问项目目录(可被设置里的 `engineer.args` 覆盖)。 */
74
+ /**
75
+ * 派发工作目录(2026-11-13 · 方案 A)。
76
+ *
77
+ * **背景(真机事故)**:本项目 `project.workspacePath` = `00-project-real`,而前端卡片的目标文件在
78
+ * 兄弟目录 `00-project-realdemo/app-vue/`。派单器把 `workspacePath` 同时用作 ① `--add-dir`、
79
+ * ② 任务书 Step 0 的 `cd`、③ 硬边界那句「只允许改 X 内的文件」,于是三处一起指错:
80
+ * CLI 的写权限收敛在 `00-project-real`,目标文件在界外 —— 执行器在 Step 0 就得停(且停得对)。
81
+ *
82
+ * 修法:把「派发目录」与「文档/仓库工作区」解耦。`teamTemplate.engineer.cwd` 一旦配置,
83
+ * 上面三处统一改用它;不配置即**逐字节**维持旧行为(零回归)。
84
+ */
85
+ export function resolveDispatchDir({ project, settings } = {}) {
86
+ const raw = settings?.teamTemplate?.engineer?.cwd;
87
+ const cwd = typeof raw === "string" && raw.trim() ? raw.trim() : null;
88
+ return cwd ?? project?.workspacePath ?? null;
89
+ }
90
+
91
+ /**
92
+ * 硬边界指向的路径(写进任务书那句「只允许改 …… 内的文件」)。
93
+ *
94
+ * `teamTemplate.engineer.writable` 是**相对派发目录**的子路径(如 `app-vue`):
95
+ * 配了就渲染成 `<派发目录>/app-vue`,没配就是整个派发目录。
96
+ * 注意:这是**文字边界**,不是 ACL —— 真正的进程级收敛仍是 `--add-dir`(见 `cliArgsFor`)。
97
+ */
98
+ export function resolveWritableScope({ project, settings } = {}) {
99
+ const dir = resolveDispatchDir({ project, settings });
100
+ // 既有字段优先:`teamTemplate.writeScope`(数组,本项目原本就写着 ["scada-docs/", ".doc-backups/"],
101
+ // 但此前**没有任何代码读它** —— 边界那行一直只渲染整个 workspacePath)。
102
+ // 条目语义:相对派发目录;以 `/` 开头的当绝对路径用(这样不换 cwd 也能放行兄弟目录)。
103
+ const list = settings?.teamTemplate?.writeScope;
104
+ const fromScope = Array.isArray(list) ? list.map(String).map((x) => x.trim()).filter(Boolean) : [];
105
+ const single = settings?.teamTemplate?.engineer?.writable;
106
+ const items = fromScope.length ? fromScope
107
+ : (typeof single === "string" && single.trim() ? [single.trim()] : []);
108
+ if (!items.length) return dir;
109
+ const abs = items.map((x) => (x.startsWith("/") ? x : (dir ? `${dir}/${x.replace(/^\.\//, "")}` : x)));
110
+ return abs.join("、");
111
+ }
112
+
113
+ /** CLI 参数:非交互 + 显式放行工具 + 允许访问派发目录(可被设置里的 `engineer.args` 覆盖)。 */
75
114
  export function cliArgsFor({ executorId, cwd, settings }) {
76
115
  const override = settings?.teamTemplate?.engineer?.args;
77
116
  if (Array.isArray(override) && override.length) return override.map(String);
117
+ const extra = Array.isArray(settings?.teamTemplate?.engineer?.extraDirs)
118
+ ? settings.teamTemplate.engineer.extraDirs.map(String).filter((d) => d.trim())
119
+ : [];
78
120
  return [
79
121
  "-p",
80
122
  "--permission-mode", "acceptEdits",
81
123
  "--allowedTools", String(settings?.teamTemplate?.engineer?.allowedTools ?? DEFAULT_ALLOWED_TOOLS),
82
124
  "--add-dir", cwd,
125
+ ...extra.flatMap((d) => ["--add-dir", d]),
83
126
  ];
84
127
  }
85
128
 
@@ -119,8 +162,8 @@ export function argsAllowEdits(args) {
119
162
  * 本函数产出的就是「要嵌进外层 ``` 围栏」的正文,故正文内**任何代码块一律 4 反引号**。
120
163
  * §一 硬规则 #2:**每个 Step 必须同时给判据与停下情形**,缺一即为不合格模板。
121
164
  */
122
- export function buildTaskPrompt(task, { project, requirementId = null, verifyCommand = null } = {}) {
123
- const cwd = project?.workspacePath ?? null;
165
+ export function buildTaskPrompt(task, { project, settings = null, requirementId = null, verifyCommand = null } = {}) {
166
+ const cwd = resolveDispatchDir({ project, settings });
124
167
  const steps = [
125
168
  `## Step 0 — 预检(只读,不通过就停)`,
126
169
  ``,
@@ -151,7 +194,7 @@ export function buildTaskPrompt(task, { project, requirementId = null, verifyCom
151
194
  `- ❌ 不删任何既有数据(任务 / 看板项目 / 需求条目)。`,
152
195
  `- ❌ 不改本任务范围外的文件;共享文件(core/store、server/api、web/app.js)改动保持最小。`,
153
196
  `- ❌ **不自行置「完成(done)」** —— 完成只能由人确认,你只提交「待验收」。`,
154
- cwd ? `- ✅ 只允许改 ${cwd} 内的文件。` : "",
197
+ resolveWritableScope({ project, settings }) ? `- ✅ 只允许改 ${resolveWritableScope({ project, settings })} 内的文件。` : "",
155
198
  `- ✅ 隔离验证用临时目录 / 临时端口 / 独立进程,跑完即删。`,
156
199
  ``,
157
200
  `## 已知前置`,
@@ -437,14 +480,14 @@ export async function runCliExecutor({
437
480
  argsOverride = null, promptVia = "stdin",
438
481
  } = {}) {
439
482
  if (!executor?.cli) return { started: false, reason: "no-cli-executor" };
440
- const workdir = cwd ?? project?.workspacePath ?? null;
483
+ const workdir = cwd ?? resolveDispatchDir({ project, settings }) ?? null;
441
484
  if (!workdir) return { started: false, reason: "no-workspace", executorId: executor.id };
442
485
  // 测试/离线替身:`TB_CLI_EXECUTOR_BIN` 指定可执行文件时优先使用(不改 executor id 语义)。
443
486
  // `binPath` 优先于裸命令名:宿主由 launchd 拉起时 PATH 常缺 `~/.npm-global/bin`,
444
487
  // 只写命令名会在 `exec-cli` 真跑时报 ENOENT(探测到绝对路径就用它)。
445
488
  // `TB_CLI_EXECUTOR_BIN` 仍是最高优先(测试/离线替身语义不变)。
446
489
  const cli = String(env?.TB_CLI_EXECUTOR_BIN ?? "") || executor.binPath || executor.cli;
447
- const prompt = buildTaskPrompt(task, { project, requirementId, verifyCommand });
490
+ const prompt = buildTaskPrompt(task, { project, settings, requirementId, verifyCommand });
448
491
  const explicitArgs = Array.isArray(argsOverride) && argsOverride.length ? argsOverride.map(String) : null;
449
492
  const args = explicitArgs ?? cliArgsFor({ executorId: executor.id, cwd: workdir, settings });
450
493
  // 参数来源与「能不能写文件」都要如实记进结果(证据与状态都取它,见 isBlindRun)。
package/src/core/loop.mjs CHANGED
@@ -12,7 +12,17 @@ import { normalizeQualityGates } from "./team.mjs";
12
12
  */
13
13
  const cliRuns = new Map();
14
14
  export function activeCliRuns() { return [...cliRuns.keys()]; }
15
- function directiveFor(engine, { teamId, taskRef, requirementId, qualityGates = null }) {
15
+ /**
16
+ * 团队派发指令正文(卡 `-270` · 需求 `R186`)。
17
+ *
18
+ * 状态取值一律**英文枚举在前、中文作括号对照**(与工具描述同形态):
19
+ * 中文只出现在「括号里当列名解释」的位置,**不再出现在「该传什么值」的位置** ——
20
+ * 执行 agent 照抄指令填中文必然被拒(`INVALID_FIELD`),这正是 R186 要消灭的那类系统性误导。
21
+ *
22
+ * 导出供守卫直接断言**真正下发的这份文本**(此前守卫靠 `find` 源码某一行,
23
+ * 锁到的是相邻说明行 ⇒ 真正下发的内容从没人锁过)。
24
+ */
25
+ export function directiveFor(engine, { teamId, taskRef, requirementId, qualityGates = null }) {
16
26
  const head = engine === "official"
17
27
  ? `[派发团队 · DSH官方自带] teamId=${teamId} 请作为 Lead 用 spawn_teammate 召集成员、team_task_create 建任务看板。`
18
28
  : engine === "nanmicoder"
@@ -25,9 +35,9 @@ function directiveFor(engine, { teamId, taskRef, requirementId, qualityGates = n
25
35
  head,
26
36
  `目标:${taskRef}`,
27
37
  requirementId ? `需求:${requirementId}` : "",
28
- `工作台任务标识:${taskRef}(执行/受阻请更新工作台状态:进行中→待验收;失败→受阻)`,
38
+ `工作台任务标识:${taskRef}(状态回写用英文枚举:in_progress(进行中)/ in_review(待验收)/ blocked(受阻)/ canceled(取消);失败→blocked)`,
29
39
  `质量门(${source === "configured" ? "配置" : "默认"}):${gates.join("→")}`,
30
- "操作指引:按依赖就绪认领 → 执行 → 提交\"待验收\";不得置\"完成\"。",
40
+ "操作指引:按依赖就绪认领 → 执行 → 提交 in_review(待验收);不得置 done(完成只能人工确认)。",
31
41
  ].filter(Boolean).join("\n");
32
42
  }
33
43
 
@@ -255,6 +265,27 @@ function inflightOf(store, task) {
255
265
  return null;
256
266
  }
257
267
 
268
+ /**
269
+ * 投给项目**主会话**的汇总指令正文(卡 `-270` · 需求 `R186`)。
270
+ *
271
+ * 抽成独立纯函数有两个理由:
272
+ * ① **守卫必须锁「真正发出去的那份文本」** —— 此前守卫靠 `find` 源码里的某一行,
273
+ * 结果锁到的是相邻的说明行(`工作台任务标识:` 那行),而**真正投进会话的**
274
+ * 「提交"待验收"(失败→受阻)」从来没人锁过 ⇒ 口径错、守卫却绿。
275
+ * ② 口径只改一处:状态取值**英文枚举在前、中文作括号对照**,中文不再出现在
276
+ * 「该传什么值」的位置(`提交 in_review(待验收)`/`失败回写 blocked(受阻)`)。
277
+ *
278
+ * 导出供守卫直接断言真实产出,而不是去源码里捞某一行字符串。
279
+ */
280
+ export function buildDispatchBriefLines(dispatched = []) {
281
+ // 一轮只投递**一条**汇总指令(避免拆解出大量子任务时刷屏目标会话)。
282
+ const lines = [`[任务工作台下发] 本轮派发 ${dispatched.length} 条任务(请作为项目执行团队承接):`];
283
+ for (const d of dispatched) lines.push(`· ${d.task}(teamId=${d.teamId})`);
284
+ lines.push("操作指引:按依赖就绪逐个认领 → 执行 → 提交 in_review(待验收);失败回写 blocked(受阻);不得置 done(完成只能人工确认)。");
285
+ lines.push("状态回写:taskboard_update_status 的 status 取英文枚举 in_progress(进行中)/ in_review(待验收)/ blocked(受阻)/ canceled(取消);中文只是列名,传中文会被拒。完成不得自行置 done(人工确认)。");
286
+ return lines;
287
+ }
288
+
258
289
  /**
259
290
  * 任务下发:把派发指令投递到项目**主会话**(真实闭环)。无绑定会话 / 宿主无 prompt 能力则如实标注降级。
260
291
  */
@@ -266,13 +297,8 @@ async function deliverDispatched(store, project, dispatched) {
266
297
  const reason = boundSessionId ? "prompt-unavailable" : "no-bound-session";
267
298
  for (const d of dispatched) { d.delivered = false; d.deliveryReason = reason; }
268
299
  if (!boundSessionId || typeof port?.sendPrompt !== "function") return result;
269
- // 一轮只投递**一条**汇总指令(避免拆解出大量子任务时刷屏目标会话)。
270
- const lines = [`[任务工作台下发] 本轮派发 ${dispatched.length} 条任务(请作为项目执行团队承接):`];
271
- for (const d of dispatched) lines.push(`· ${d.task}(teamId=${d.teamId})`);
272
- lines.push("操作指引:按依赖就绪逐个认领 → 执行 → 提交\"待验收\"(失败→受阻);不得置\"完成\"(人工确认)。");
273
- lines.push("状态回写:任务看板 taskboard_update_status(进行中/待验收/受阻),完成由人工确认。");
274
300
  let r = null;
275
- try { r = await port.sendPrompt(boundSessionId, lines.join("\n")); } catch { r = null; }
301
+ try { r = await port.sendPrompt(boundSessionId, buildDispatchBriefLines(dispatched).join("\n")); } catch { r = null; }
276
302
  const sent = Boolean(r?.sent);
277
303
  for (const d of dispatched) {
278
304
  d.delivered = sent;