taskboard-workbench 0.3.2 → 0.3.4

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,71 @@
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.4] - 2026-11-12
10
+
11
+ > 主题:**把「谁来执行、由谁记账」这条口径钉死** —— CLI 执行者不再由看板自己 spawn,而是把确切的命令、
12
+ > 回写要求与红线交给**项目主会话**,卡片反馈回到同一个会话里,交付记录不再散落在看板进程;
13
+ > 外加一条 owner 与角色错配的诊断。
14
+ > 版号走 `0.3.x` patch(`0.4.0` 仍留给计划文档里预留的确认层 `acceptance_state`)。
15
+ > 读数:`node --test` **1245 / 0** · `release-precheck` **EXIT=0** · tarball **87** 文件。
16
+
17
+ ### 变更(行为口径)
18
+
19
+ - **CLI 执行改走项目主会话下发并跟踪(卡 `-257` / 需求 `R183`)** —— 除 dsh 宿主会话直接执行外,
20
+ 其他非绑定会话的 agent 执行者(claude / codex / hermes 等)一律交由**项目主会话**下发并跟踪,卡片任务反馈由主会话回写;
21
+ `/exec-cli` **默认不再 spawn**,改为投递一条含「哪张卡 / 确切命令 / 四节回写要求 / 不得置 done 的红线」的指令。
22
+ 三条边界:投递失败**不回落**直跑(如实回 `delivered:false`)· 无宿主回落直跑时**必在卡上留痕**「执行记录不在任何会话里」·
23
+ `direct:true` 保留为显式出口。卡 `session_id` 绑主会话 ⇒ **「打开执行会话」直达记录所在会话**。
24
+
25
+ ### 新增
26
+
27
+ - **owner 与角色错配诊断(卡 `-246` / 需求 `R178` ③)** —— owner 是自由文本,「执行卡被写成审查/规划岗」此前只能人肉发现。
28
+ 新增诊断 `owner-role-mismatch`(**medium**,只诊断不拦截,首选动作=改绑负责人)。
29
+ 判据**实测收窄**:宽口径在真机 4/4 误报 ⇒ 只认带 `kind/work` 标记的卡;真机 301 卡命中 0。
30
+
31
+ ## [0.3.3] - 2026-11-12
32
+
33
+ > 主题:**把「团队执行时缺的那几条路」补齐,并让两个宿主看见同一份库** —— 双宿主对齐(写者租约 + 数据目录自证)、
34
+ > 按卡选执行者、交付证据写入口双通道(含 `agents` 雏形与 WAL)、开局提示词注入当前项目、人工撤单入口,
35
+ > 外加四条团队执行期实测出来的缺陷修复。
36
+ > 版号按本仓既定口径走 **`0.3.x` patch**(`0.3.2` 已声明「`0.3.x` 期 patch 号承载修复 + 可选能力」,
37
+ > `0.4.0` 留给计划文档里预留的确认层 `acceptance_state`)—— 不另起 minor 线。
38
+ > 读数:`npm test` **1225 / 0** · `release-precheck` **EXIT=0** · tarball **86** 文件 · `schemaVersion` **14 → 15**。
39
+
40
+ ### 新增
41
+
42
+ - **双宿主数据对齐(卡 `-236`/`-237` / 需求 `R173`)** —— web 与 desktop **共用同一份库**,且界面能自证「连的是哪个库」:
43
+ 只读跟随者常驻条(`role=follower` 30s 刷新)、写者租约(同时只有一个写者)、`/api/health` 直接给 `dataDir` 与 `dbPath`。
44
+ - **按卡选执行者(卡 `-238` / 需求 `R174`)** —— 任务卡「启动执行」可按卡挑执行者(团队 / 宿主会话 / claude · codex · hermes 等 CLI),
45
+ 前端按注册表渲染图标并按 `id` 派发;**不传执行者 = 原口径**,升级后默认行为不变。
46
+ - **交付证据写入口双通道(卡 `-239`/`-241` / 需求 `R175`)** —— HTTP 与 MCP `card_evidence_submit` **同源**:
47
+ 同一个 store 方法、同一道四字段硬门、同一套错误码;`task_evidence` 增 `evidence_hash` 幂等索引(重复推送不再堆重复行),
48
+ 并落 `agents` / `agent_sessions` 雏形与 WAL(`schemaVersion` **14 → 15**)。
49
+ - **人工撤单入口(卡 `-252` / 需求 `R180`)** —— 抽屉标题栏新增 danger 档「取消任务(撤单)」:原因必填、页内 dialog 二次确认,
50
+ 撤单后把原因写成评论(此前「确认不执行」的卡在界面上根本没有出口,只能挂着)。
51
+
52
+ ### 修复
53
+
54
+ - **内嵌宿主下 `window.prompt` 直接报错(卡 `-240`/`-242` / 需求 `R176`)** —— 新建项目 / 返工说明 / 人工结论 / 需求标题
55
+ 四处取值出口改走**页内 dialog**(`askFields`),取消零副作用;`tests/no-prompt.test.mjs` 守结构门与「三条取消出口统一归 `null`」。
56
+ - **配置页「复制开局提示词」注入当前项目(卡 `-243` / 需求 `R177`)** —— 此前复制的是**默认项目**的开局语,新会话按错误目录开工;
57
+ 现按 `state.projectId` 现算,未设工作目录时**如实提示不猜路径**。
58
+ - **`requestReview` 缺省自动指派评审者(卡 `-244` / 需求 `R178`)** —— 此前只把 `review_state` 置 pending、`reviewer` 留空,
59
+ ⇒ `review_deadlock` 是**必然产物**;现按团队模板缺省指派(真机验证:不传 reviewer ⇒ 回读 `reviewer="reviewer"`)。
60
+ - **同态迁移不再写空转事件(卡 `-245` / 需求 `R178`)** —— `in_review → in_review` 不再追加 `status_changed`,事件流恢复成「状态真的变了」才算。
61
+ - **复核命令不可执行时判「不适用」,不再谎报失败(卡 `-249` / 需求 `R179`)** —— 命令里带未替换占位符(如 `<diff文件>`)时,
62
+ 此前跑出 `sh: syntax error` 并被记成「失败(退出码 2)」;现在 `applicable=false` 且明确说出是哪个占位符没替换。
63
+ - **发布门禁误报(测试夹具)** —— `tests/executors.test.mjs` / `tests/kickoff-prompt-project.test.mjs` 的假家目录写成真机路径形态,
64
+ 命中 L2「mac-home」规则使门禁转红;夹具改中性临时路径,门禁回到 `EXIT=0`。
65
+
66
+ ### 兼容性与升级注意
67
+
68
+ - **npm `latest` 升到 `0.3.3`**;`engines.dsh` 仍为 `>=0.2.1-rc.3`(本机验证形态 `0.2.2-rc.1`)。
69
+ - **`schemaVersion` 14 → 15**:首启自动迁移(`task_evidence` 补 `evidence_hash` 列 + 指纹索引,幂等)。
70
+ 回退到 `0.3.2` 读同一个库**不安全**(旧代码不认识新列),要回退请连同 `.data` 快照一起回。
71
+ - **证据写入变幂等**:同一张卡、同一份产物指纹重复推送只留一行 —— 依赖「每次 push 都新增一行」的外部统计口径需要改。
72
+ - **撤单不会自动解锁下游**:`isTaskReady` 仍只把 `done` 当完成(`canceled` 算未完成),口径待定,见卡 `-253` / 需求 `R181`(backlog)。
73
+
9
74
  ## [0.3.2] - 2026-11-06
10
75
 
11
76
  > 主题:**把三轮「卡上已收口、包里还没有」的改动一次补齐** —— `0.3.1` 之后又攒了开局长注入(P5 档 C)、
package/index.js CHANGED
@@ -5,8 +5,8 @@
5
5
  * 挂到独立命名空间 /integrations/taskboard-workbench 下,并同时托管 web/ 静态资源
6
6
  * (客户端面板通过同源脚本加载复用 web/app.js 的看板渲染)。
7
7
  *
8
- * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > 系统临时目录
9
- * (默认不写代码仓库)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
8
+ * 数据目录:插件配置 dataDir > 宿主 `ctx.get("config").dataDir` > TB_DATA_DIR > `~/.dsh/data/taskboard-workbench`
9
+ * (默认不写代码仓库;2026-11-10 起不再落系统临时目录 —— 见 `src/core/config.mjs`)。**不得直接读 `ctx.config`**:本插件 `inject` 只声明了 `webServer`,
10
10
  * cordis 会对未声明属性抛「cannot get property "config" without inject」⇒ 装载期整条 entry
11
11
  * 不激活(2026-10-26 用隔离真宿主 `--from-default-profile` 复现;真实 profile 因为用户层
12
12
  * patch 显式给了 `config.dataDir`,把 `??` 右边短路掉,才一直没暴露)。
@@ -15,9 +15,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
15
15
  import { createRequire } from "node:module";
16
16
  import { existsSync, realpathSync } from "node:fs";
17
17
  import path from "node:path";
18
+ import os from "node:os";
18
19
 
19
20
  import { resolveDataDir } from "./src/core/config.mjs";
21
+ import { detectLegacyDataHint } from "./src/core/data-dir-hint.mjs";
20
22
  import { openStore } from "./src/core/store.mjs";
23
+ import { LEASE_HEARTBEAT_MS } from "./src/core/instance-lease.mjs";
21
24
  import { createRequestHandler, ensureDefaultProject, WEB_DIR } from "./src/server/server.mjs";
22
25
  import { createEventHub } from "./src/server/events.mjs";
23
26
  import { runExecutionLoop, listLoopProjects } from "./src/core/loop.mjs";
@@ -383,7 +386,12 @@ export function createHostSessionPort({ getService, getCtx, getStore } = {}) {
383
386
  const q = getService?.("sessionQuery");
384
387
  if (!q) return { sessionId, cwd: null, source: "unavailable" };
385
388
  try {
386
- const index = await sessionIndex();
389
+ // 卡 `-235`(需求 `R172`)· lint `no-undef` 抓到的真缺陷:原写 `await sessionIndex()`,
390
+ // 而那是**同一对象的方法**、不在当前作用域 ⇒ ReferenceError ⇒ 被下面的 `catch` 静默吞掉 ⇒
391
+ // 「先查持久化索引(带 TTL 缓存)」这条路径**从未生效**,每次都退到 readSession。
392
+ // 改为直接调上面那个闭包(`sessionIndex()` 方法体也是它),同源、同缓存,语义不变。
393
+ const built = await buildSessionIndex();
394
+ const index = built?.map ?? null;
387
395
  if (index?.has(sessionId)) {
388
396
  return { sessionId, cwd: index.get(sessionId)?.cwd ?? null, source: "sessionQuery.listSessions" };
389
397
  }
@@ -599,17 +607,51 @@ export function apply(ctx, config) {
599
607
  disposed = false;
600
608
  registerRoutes(getWebServer());
601
609
  registerTools(ctx?.get?.("tools") ?? ctx?.tools);
610
+ // 卡 `-237`(需求 `R173`):**多实例单写者租约**。dsh web 与 dsh desktop 可以同时打开同一个库,
611
+ // 谁先抢到谁写;后起者降级为 follower(只读 + 不起执行循环 + 不做 boot 收口)。
612
+ let leaseRole = "writer";
613
+ let leaseOwner = null;
614
+ try {
615
+ const lease = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
616
+ leaseRole = lease.role;
617
+ leaseOwner = lease.owner;
618
+ if (leaseRole !== "writer") {
619
+ console.log(`[taskboard-workbench] 只读跟随:另一实例正在写同一个库(${lease.owner?.host} · pid ${lease.owner?.pid} · ${runtime.store.dbPath})`);
620
+ } else if (lease.tookOver) {
621
+ console.log(`[taskboard-workbench] 写者租约接管:上一实例 ${lease.previous?.host} · pid ${lease.previous?.pid} 已过期`);
622
+ }
623
+ } catch (error) {
624
+ console.error(`[taskboard-workbench] 写者租约获取失败(按 writer 继续):${error?.message ?? error}`);
625
+ }
602
626
  // FR-82 收口(启动口径):上一进程留下的「进行中」尝试不会有人闭合 —— 启动时一次结清(**不看时长**)。
627
+ // **只有 writer 才做 boot 收口** —— 它分不清「上一进程」与「另一个还活着的进程」,
628
+ // follower 跑一次就会把对端正跑着的执行当孤儿结清(这正是 R173 的真机风险)。
629
+ if (leaseRole === "writer") {
630
+ try {
631
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
632
+ if (rec.ended.length || rec.ghostClaims.length) {
633
+ console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
634
+ }
635
+ } catch (error) {
636
+ console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
637
+ }
638
+ }
639
+ // 卡 `-236`(需求 `R173`):默认目录从系统临时目录搬到 `~/.dsh/data/taskboard-workbench` 之后,
640
+ // 老用户的卡还在旧目录 —— 只读对照一次,把「升级后看板全空」变成一条能看懂的提示。
641
+ // **不搬库、不删旧库**:搬数据属破坏性动作,交用户决定(提示里给两条明路)。
603
642
  try {
604
- const rec = runtime.store.reconcileOrphanRuns({ boot: true });
605
- if (rec.ended.length || rec.ghostClaims.length) {
606
- console.log(`[taskboard-workbench] boot reconcile: 收口孤儿尝试 ${rec.ended.length} 条(${rec.ended.map((r) => `${r.identifier}#${r.attempt}→${r.outcome}`).join(", ")});清幽灵认领 ${rec.ghostClaims.length} 条`);
643
+ const hint = detectLegacyDataHint({ dataDir: runtime.dataDir, activeTaskCount: runtime.store.stats().tasks });
644
+ if (hint) {
645
+ runtime.store.dataDirHint = hint;
646
+ console.warn(`[taskboard-workbench] 数据目录迁移提示:${hint.hint}`);
607
647
  }
608
648
  } catch (error) {
609
- console.error(`[taskboard-workbench] boot reconcile failed: ${error?.message ?? error}`);
649
+ console.error(`[taskboard-workbench] 迁移提示探测失败(忽略):${error?.message ?? error}`);
610
650
  }
611
651
  // 看板执行循环定时器(FR-70):仅对"已开启循环"的项目按活跃引擎自动派发待执行任务
612
652
  const loopTimer = setInterval(() => {
653
+ // 卡 `-237`:follower 不跑执行循环(否则同一张卡会被两个宿主同时派发)。
654
+ if (leaseRole !== "writer") return;
613
655
  // FR-77:回收失效认领(认领过期 / 心跳陈旧)——执行侧仍存活则延后,避免重复派发。
614
656
  try {
615
657
  const reclaimed = runtime.store.reclaimStaleClaims();
@@ -636,6 +678,28 @@ export function apply(ctx, config) {
636
678
  }
637
679
  }, 30000);
638
680
  loopTimer.unref?.();
681
+ // 卡 `-237`:心跳 15s。**follower 也每拍一次 acquire** —— 对端一退出(租约过期 45s)就能接管。
682
+ const leaseTimer = setInterval(() => {
683
+ try {
684
+ const next = runtime.store.acquireInstanceLease({ host: os.hostname(), pid: process.pid });
685
+ if (next.role === "writer" && leaseRole !== "writer") {
686
+ leaseRole = "writer";
687
+ leaseOwner = null;
688
+ console.log("[taskboard-workbench] 已接管写者租约(对端已过期),本窗口恢复读写");
689
+ try {
690
+ const rec = runtime.store.reconcileOrphanRuns({ boot: true });
691
+ if (rec.ended.length || rec.ghostClaims.length) console.log(`[taskboard-workbench] 接管收口:孤儿 ${rec.ended.length} 条 / 幽灵认领 ${rec.ghostClaims.length} 条`);
692
+ } catch (error) { console.error(`[taskboard-workbench] 接管收口失败:${error?.message ?? error}`); }
693
+ } else if (next.role !== "writer" && leaseRole === "writer") {
694
+ leaseRole = "follower";
695
+ leaseOwner = next.owner;
696
+ console.log(`[taskboard-workbench] 失去写者租约 → 只读跟随(${next.owner?.host} · pid ${next.owner?.pid})`);
697
+ }
698
+ } catch (error) {
699
+ console.error(`[taskboard-workbench] 租约心跳失败:${error?.message ?? error}`);
700
+ }
701
+ }, LEASE_HEARTBEAT_MS);
702
+ leaseTimer.unref?.();
639
703
  // 服务在插件 apply 之后才出现/被替换时,重新注册(agent-teams 同款做法)。
640
704
  const onService = (name) => {
641
705
  if (name === "webServer" || name === "httpServer") registerRoutes(getWebServer());
@@ -645,6 +709,8 @@ export function apply(ctx, config) {
645
709
  return () => {
646
710
  disposed = true;
647
711
  try { clearInterval(loopTimer); } catch (_) {}
712
+ try { clearInterval(leaseTimer); } catch (_) {}
713
+ try { runtime.store.releaseInstanceLease(); } catch (_) {}
648
714
  try {
649
715
  off?.();
650
716
  } catch (_) {}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taskboard-workbench",
3
- "version": "0.3.2",
3
+ "version": "0.3.4",
4
4
  "type": "module",
5
5
  "description": "agent team 任务工作台:零依赖核心(node:sqlite)+ CLI + 本地 Web 看板 + DSH 内嵌插件",
6
6
  "license": "MIT",
@@ -34,7 +34,7 @@ requires_contract: v1
34
34
  | **S2** | 分拆成卡 | `card_create` | 条目存在 + 同项目 + 归因硬门 | 返回 `attribution.kind="requirement"`;卡在 `backlog`;依赖真成边 | `tasks` + `task_events`(`created` / `attributed`) | `REQUIREMENT_REQUIRED` ⇒ 补 `requirement`,或显式 `unattributed_reason`(会落审计);`DEPENDENCY_CROSS_PROJECT` ⇒ 前置卡挂错项目;`AUTHORIZATION_REQUIRED` ⇒ 新卡只能进 `backlog` | FR-29 / FR-38 |
35
35
  | **S3** | 授权开工(人) | 看板「启动执行」/ 人点 | 归因门 → 授权门 | `backlog → todo` 由**人**点;执行侧不得自我授权 | `task_events`(`set-status`,`actor=human`) | 执行侧想推 ⇒ `AUTHORIZATION_REQUIRED`;卡还没归因 ⇒ 先回 S2 | FR-40 / FR-84 |
36
36
  | **S4** | 派发 / 执行 | 看板派发 · 宿主团队工具 · MCP `card_progress` 推进状态 | 归因 + 授权 + **人工校验门** | 卡进 `in_progress` 且带认领心跳;人工校验任务不得被执行侧改状态 | `team_runs` / claims / `task_events` | `HUMAN_REVIEW_NOT_EXECUTABLE` ⇒ 这是人在环任务,走人工结论入口;`EXECUTION_NOT_ATTRIBUTED` ⇒ 回 S2 补归因 | FR-41 / FR-42 / FR-85 |
37
- | **S5** | 回填进度 + 证据 | `card_progress` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
37
+ | **S5** | 回填进度 + 证据 | `card_progress` · `card_evidence_submit` | `contract_version` 一致 + `norm_digest` 一致 | 每条进展带**可核验证据**(`file` / `command` / `url` / `reading`),不是「已完成」三个字;`in_review` 前必须有证据 | 评论(`【MCP 证据】hash=…`)+ 审计 | `EVIDENCE_REQUIRED` / `EVIDENCE_INVALID` ⇒ 按形状补;`NORM_DIGEST_REQUIRED` / `NORM_STALE` ⇒ 先 `norm_get {norm:"card-update"}` 再回填 | FR-94 / FR-50 |
38
38
  | **S6** | 需求变更 | `requirement_change` | 影响面已计算(`affected_cards`) | 先预览拿 `change_id`,确认影响面后带 `change_id` + `apply:true` 才落地;`done` 卡**不自动重开** | `governance_audit`(`requirement-change`,带 `reason`) | `CHANGE_NEEDS_APPROVAL` ⇒ 忘了先预览;`CHANGE_ID_MISMATCH` ⇒ 条目在预览后被改过,重新预览;`CHANGE_REASON_REQUIRED` ⇒ 补理由 | FR-39 / FR-100 |
39
39
  | **S7** | 验收收口(人) | 看板「完成」/ 人点 | 评审门 `review_state==='approved'`(或显式 `skipReview`) | `in_review → done` **只由人**;执行侧写 `done` 一律被拒 | `governance_audit`(`actor=human`) | `REVIEW_NOT_APPROVED` ⇒ 先评审通过;`GOVERNANCE_AGENT_DONE` ⇒ 这不是执行侧该做的事 | FR-83 / FR-99 |
40
40
  <!-- /flow-block:steps -->
@@ -17,8 +17,28 @@ card_progress {
17
17
  }
18
18
  ```
19
19
 
20
+ ## 交付证据(另一种写入口 · 不是"进度")
21
+
22
+ `card_progress` 写的是**过程性证据**(command / url / reading)。要把**交付证据**(判定 / 偏离 / 边界 / 产物)
23
+ 落到 `task_evidence` 表,用 `card_evidence_submit`(HTTP 侧对应 `POST /api/tasks/:ref/evidence`,同源同门):
24
+
25
+ ```
26
+ card_evidence_submit {
27
+ card,
28
+ verdict: "做了什么、结论是什么",
29
+ deviation: "没按原计划做的部分(不写 = 隐藏信息)",
30
+ boundary: "未取得 / 无法判定的读数必须明说",
31
+ artifacts: ["docs/进度/xxx.md", "npm test 1186/1186"],
32
+ artifact_refs: [ { kind: "commit", ref: "57e97f9" }, { kind: "file", ref: "src/core/store.mjs" } ]
33
+ }
34
+ ```
35
+
36
+ - 四字段**缺一即拒**(`EVIDENCE_INCOMPLETE`),不会落半条;
37
+ - `artifact_refs` 只接受 `commit` / `file`(其余 ⇒ `INVALID_ARTIFACT_REF`);过程性证据走 `evidence[]` 那一侧;
38
+ - 同指纹重复提交**幂等**(`deduped: true`,不增行)。
39
+
20
40
  ## 判据
21
- - `evidence[].kind` ∈ `file` / `command` / `url` / `reading`,`ref` 非空;
41
+ - `evidence[].kind` ∈ `file` / `command` / `url` / `reading`(`commit` 属交付证据侧),`ref` 非空;
22
42
  - 返回 `comment.deduped === false`(第二次同样证据会是 `true`,不会刷重复评论);
23
43
  - `card.statusAfter` 与你期望的一致;
24
44
  - 评论正文里有 `【MCP 证据】hash=…` —— 这就是事后复核的锚点。
@@ -0,0 +1,90 @@
1
+ /**
2
+ * CLI 执行器 · **经项目主会话下发**的指令构造(需求 `R183` / 卡 `-257`)。
3
+ *
4
+ * 背景(2026-11-12 真机 `-246`):服务端直接 `spawn claude -p` 时,执行过程与该会话无关 ——
5
+ * 人点「打开执行会话」只看得到项目主会话、里面一条记录都没有,`task_runs` 也只有
6
+ * `actor=cli-executor`、磁盘上更没有任何输出。用户拍板的口径由此而来:
7
+ *
8
+ * **除「DSH 宿主会话」直接执行外,其他 agent 执行者一律交给项目主会话下发并跟踪,
9
+ * 卡片的任务执行反馈也由主会话回写。**
10
+ *
11
+ * 所以这里生成的不是"给 CLI 的任务书"(那个是 `buildTaskPrompt`),而是**给主会话的派单指令**:
12
+ * 确切命令 + 回写要求 + 红线,三样都得写在正文里,否则主会话要么自己重写任务书(漂移),
13
+ * 要么跑完不写卡(看板又变成黑盒)。
14
+ */
15
+
16
+ /** 看板 API 基址(与 `kickoff.mjs` 的 `SETTINGS_BASE` 同一口径:DSH 内嵌命名空间)。 */
17
+ export const TB_API_BASE = "http://127.0.0.1:3080/integrations/taskboard-workbench";
18
+
19
+ /** 单引号包裹并转义 —— 命令里出现中文/空格/特殊符号时也能安全粘进 shell。 */
20
+ function shq(value) {
21
+ const s = String(value ?? "");
22
+ return `'${s.replaceAll("'", `'\\''`)}'`;
23
+ }
24
+
25
+ /**
26
+ * 拼出主会话要执行的那条 shell 命令。
27
+ *
28
+ * 两种投递形态(与 `executors.mjs` 的 `promptVia` 一一对应):
29
+ * - `stdin`(claude / codex):任务书走 heredoc,避免超长命令行;
30
+ * - `argv`(hermes `-z <prompt>`):任务书已经在参数里(`buildExecutorArgs` 拼好的),不再重复投递。
31
+ */
32
+ export function buildCliCommand({ plan }) {
33
+ const cli = plan?.cli ?? "";
34
+ const args = Array.isArray(plan?.args) ? plan.args : [];
35
+ const base = [cli, ...args].join(" ");
36
+ if (plan?.promptVia === "argv") return base;
37
+ const delim = `TB_PROMPT_${Math.random().toString(36).slice(2, 8).toUpperCase()}`;
38
+ return `${base} <<'${delim}'\n${plan?.prompt ?? ""}\n${delim}`;
39
+ }
40
+
41
+ /**
42
+ * 给项目主会话的派单指令。
43
+ *
44
+ * @param {object} input
45
+ * @param {object} input.task 任务卡(`identifier` / `title` / `acceptance` / `verifyCommand`)
46
+ * @param {object|null} input.project 项目(`workspacePath` 用作工作目录)
47
+ * @param {object} input.executor 执行者(`id` / `role`)
48
+ * @param {object} input.plan 执行计划(`cli` / `args` / `cwd` / `promptVia` / `prompt`)
49
+ * @param {string} input.apiBase 看板 API 基址(回写用)
50
+ */
51
+ export function buildMainSessionCliPrompt({ task, project, executor, plan, apiBase = TB_API_BASE }) {
52
+ const cwd = plan?.cwd ?? project?.workspacePath ?? "(未设置工作目录)";
53
+ const command = buildCliCommand({ plan });
54
+ const ref = task?.identifier ?? "";
55
+ const acceptance = String(task?.acceptance ?? "").trim();
56
+ const verify = String(task?.verifyCommand ?? "").trim();
57
+ return [
58
+ `# 派单:${ref} 由你(项目主会话)用 ${executor?.id ?? "CLI"} 执行并回写`,
59
+ ``,
60
+ `看板把这张卡交给**本会话**下发跟踪 —— 请**在这里**跑下面的命令,让执行记录留在本会话里,`,
61
+ `不要转手丢到别处静默跑完。`,
62
+ ``,
63
+ `## 这是哪张卡`,
64
+ `- 编号:${ref}`,
65
+ `- 标题:${task?.title ?? "(无标题)"}`,
66
+ acceptance ? `- 验收:${acceptance}` : `- 验收:(该卡未写验收标准 —— 跑完在证据里如实说明)`,
67
+ verify ? `- 复核动作:${verify}` : `- 复核动作:(沿用项目设置)`,
68
+ ``,
69
+ `## 执行命令(工作目录 ${cwd})`,
70
+ "```bash",
71
+ command,
72
+ "```",
73
+ ``,
74
+ `## 跑完之后(三件都做,缺一不合格)`,
75
+ `1. 把**四节证据**写进卡片(判定 / 偏离说明 / 边界自查 / 产物路径):`,
76
+ ` \`POST ${apiBase}/api/tasks/${ref}/evidence\``,
77
+ ` body 至少含 \`verdict\` \`deviation\` \`boundary\` \`artifacts\` 四个字段,\`actor\` 写 \`agent\`。`,
78
+ ` 若你有任务工作台的 MCP 工具,用 \`card_evidence_submit\`(同一道门、同一套错误码)。`,
79
+ `2. 把卡提交「待验收」:\`POST ${apiBase}/api/tasks/${ref}/execution/review\``,
80
+ `3. 失败就 \`POST ${apiBase}/api/tasks/${ref}/execution/fail\`,并在 body 里写清原因与错误尾段。`,
81
+ ``,
82
+ `## 红线`,
83
+ `- **不得置 done**(完成只能人点);`,
84
+ `- 不 commit、不 push、不改历史决策文档、不删既有数据;`,
85
+ `- 命令退出码非 0 或零改动时,照实写进证据,不要美化成"完成"。`,
86
+ ``,
87
+ `## 回报`,
88
+ `做完在本会话回一句:退出码 / 改了哪些文件 / 卡片当前状态。`,
89
+ ].join("\n");
90
+ }
@@ -1,12 +1,21 @@
1
1
  /**
2
2
  * 运行期配置:数据目录解析(FR-31/FR-33)。
3
- * 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR > 默认临时目录。
4
- * 默认放临时目录,保证"运行不写仓库"(本机仓库目录只读)。
3
+ * 优先级:显式参数 --data-dir > 环境变量 TB_DATA_DIR > 默认目录。
4
+ *
5
+ * 默认目录(2026-11-10 · 卡 `-236` / 需求 `R173` 改):
6
+ * `~/.dsh/data/taskboard-workbench`
7
+ * 原默认是 `os.tmpdir()/tb-workbench-mvp-a` —— 两个问题:
8
+ * ① **临时目录会被 macOS 定期清理** ⇒ 看板数据随时静默消失;
9
+ * ② dsh web 与 dsh desktop 是**两个宿主**,只要有一边没显式配 `dataDir`,就会落到
10
+ * 自己解析的默认位置,于是「两边看到两份库」(真机:web 264 张卡 / desktop 0 张)。
11
+ * 改成用户目录下的固定路径后,**两个宿主不配置也是同一份库**。
5
12
  */
6
13
  import os from "node:os";
7
14
  import path from "node:path";
8
15
 
9
- export const DEFAULT_DATA_DIR = path.join(os.tmpdir(), "tb-workbench-mvp-a");
16
+ export const DEFAULT_DATA_DIR = path.join(os.homedir(), ".dsh", "data", "taskboard-workbench");
17
+ /** 旧默认目录:**只用于「空库检测 / 迁移提示」**,不再作为任何写入目标。 */
18
+ export const LEGACY_DATA_DIR = path.join(os.tmpdir(), "tb-workbench-mvp-a");
10
19
  export const DB_FILENAME = "taskboard.sqlite";
11
20
 
12
21
  export function resolveDataDir({ dataDir, env = process.env } = {}) {
@@ -0,0 +1,52 @@
1
+ /**
2
+ * data-dir-hint.mjs —— 「你这个库是空的,但旧默认目录里还有数据」的**只读**检测(卡 `-236` / 需求 `R173`)。
3
+ *
4
+ * 为什么需要它:默认目录从 `os.tmpdir()/tb-workbench-mvp-a` 改到 `~/.dsh/data/taskboard-workbench` 之后,
5
+ * 老用户的卡还在旧目录里。如果只是静默换目录,用户看到的就是「升级后看板全空」——比原来的 bug 更吓人。
6
+ * 所以启动时做一次**只读**对照:新库 0 张卡 + 旧库有卡 ⇒ 打一条明确的迁移提示(并在 /api/health 里带出来)。
7
+ *
8
+ * 边界(都很硬):
9
+ * - **不复制、不删除、不写入**旧库;只读打开 + 一条 count。旧库打开失败一律当"没有提示",绝不打断启动。
10
+ * - 新库已经有卡 ⇒ 不提示(用户显然已在用新目录)。
11
+ * - 两个目录相同(用户显式把 dataDir 指回旧目录)⇒ 不提示。
12
+ */
13
+ import { existsSync } from "node:fs";
14
+ import path from "node:path";
15
+ import { DatabaseSync } from "node:sqlite";
16
+
17
+ import { DB_FILENAME, LEGACY_DATA_DIR } from "./config.mjs";
18
+
19
+ export function detectLegacyDataHint({
20
+ dataDir,
21
+ activeTaskCount = 0,
22
+ legacyDir = LEGACY_DATA_DIR,
23
+ dbFilename = DB_FILENAME,
24
+ } = {}) {
25
+ if (!dataDir || !legacyDir) return null;
26
+ if (path.resolve(String(dataDir)) === path.resolve(String(legacyDir))) return null;
27
+ if (Number(activeTaskCount) > 0) return null;
28
+
29
+ const legacyDbPath = path.join(legacyDir, dbFilename);
30
+ if (!existsSync(legacyDbPath)) return null;
31
+
32
+ let legacyTaskCount = 0;
33
+ try {
34
+ const db = new DatabaseSync(legacyDbPath, { readOnly: true });
35
+ try {
36
+ const row = db.prepare("select count(*) as n from tasks").get();
37
+ legacyTaskCount = Number(row?.n ?? 0);
38
+ } finally { db.close(); }
39
+ } catch {
40
+ return null; // 旧库读不开(权限 / 损坏 / 不是本插件库)⇒ 不当提示,更不当错误
41
+ }
42
+ if (legacyTaskCount <= 0) return null;
43
+
44
+ return {
45
+ reason: "EMPTY_ACTIVE_WITH_LEGACY_DATA",
46
+ dataDir: path.resolve(String(dataDir)),
47
+ legacyDir: path.resolve(String(legacyDir)),
48
+ legacyDbPath,
49
+ legacyTaskCount,
50
+ hint: `当前数据目录(${path.resolve(String(dataDir))})没有任务,但旧默认目录 ${legacyDir} 里有 ${legacyTaskCount} 张卡。要看旧数据:把 dataDir 指回旧目录(TB_DATA_DIR=… 或插件配置 dataDir),或自行把 ${dbFilename} 复制过来后重启。本插件不会自动搬库。`,
51
+ };
52
+ }
@@ -23,6 +23,8 @@ export const DIAGNOSTIC_KINDS = Object.freeze([
23
23
  "human_review_required",
24
24
  // 2026-10-22 补口:把「投递到会话但没交作业」从**静默回收**变成**可见 + 有恢复动作**。
25
25
  "delivery_untaken",
26
+ // 卡 `-246`(需求 `R178` ③):owner 是自由文本 ⇒「执行卡被写成审查/规划岗」这类越位只能人肉发现。
27
+ "owner-role-mismatch",
26
28
  ]);
27
29
 
28
30
  /** 严重度取值;high 最重(UI 用它排序与着色)。 */
@@ -185,8 +187,14 @@ function commonActions(ctx, { retryLabel = "退回待办(重新派发)", ret
185
187
  ];
186
188
  }
187
189
 
188
- /** 人工忽略留痕标记:`已忽略诊断「<kind>」…`(FR-79「忽略即消解且保留原文可回溯」)。 */
189
- const DISMISS_RE = /已忽略诊断[「"]?([a-zA-Z_]+)/;
190
+ /**
191
+ * 人工忽略留痕标记:`已忽略诊断「<kind>」…`(FR-79「忽略即消解且保留原文可回溯」)。
192
+ *
193
+ * 2026-11-12(卡 `-246`):字符类补上 `-` —— 新诊断 kind `owner-role-mismatch` **带连字符**,
194
+ * 原 `([a-zA-Z_]+)` 只会截到 `owner`,于是「忽略此项」写了留痕却压不住这条诊断(静默失效)。
195
+ * 既有 kind 全是 `[a-z_]+`,补 `-` 不改变它们的行为。
196
+ */
197
+ const DISMISS_RE = /已忽略诊断[「"]?([a-zA-Z_-]+)/;
190
198
 
191
199
  /**
192
200
  * 已被人工忽略的诊断类型(且忽略发生在最近一次进展之后)。
@@ -228,6 +236,75 @@ function evidenceText(e) {
228
236
  try { return JSON.stringify(e); } catch { return String(e); }
229
237
  }
230
238
 
239
+ // ---------------------------------------------------------------------------
240
+ // owner 与角色错配(卡 `-246` · 需求 `R178` ③)
241
+ // ---------------------------------------------------------------------------
242
+
243
+ /**
244
+ * owner 的角色词表(沿用团队编制口径:`src/core/team.mjs#TEAM_ROLES` 与 `web/app.js#OWNER_LABELS`)。
245
+ *
246
+ * owner 是**自由文本**(早期靠 `owner:<role>` 标签承载,见 `core/owner.mjs`),所以归一必须容忍
247
+ * 「开发 engineer」这类「中文 + 英文」写法,也不能把 `codex` / `agent-team:claude-cli` 当成角色。
248
+ */
249
+ export const OWNER_ROLE_TOKENS = Object.freeze([
250
+ "lead", "planner", "engineer", "tester", "reviewer", "archivist",
251
+ ]);
252
+
253
+ /**
254
+ * **不执行**的角色(卡 `-246` 任务书点名):规划 / 审查 / 归档。
255
+ * 执行岗是 `engineer`(开发)与 `tester`(测试)。
256
+ */
257
+ export const NON_EXECUTING_OWNER_ROLES = Object.freeze(["planner", "reviewer", "archivist"]);
258
+
259
+ /** 角色词 → 人读标签(与前端 `OWNER_LABELS` 同口径;core 不能引 web,故各存一份)。 */
260
+ export const OWNER_ROLE_LABELS = Object.freeze({
261
+ lead: "队长 lead", planner: "规划 planner", engineer: "开发 engineer",
262
+ tester: "测试 tester", reviewer: "评审 reviewer", archivist: "归档 archivist",
263
+ });
264
+
265
+ /**
266
+ * 看板自己的**卡类型标记**(`tasks` 表没有 kind 列,落在 labels 上 —— 见 store.mjs 分拆落库处):
267
+ * · `kind/work` = 工作项(要派出去执行/落地)
268
+ * · `kind/review` = 审查项(审别人的活)
269
+ */
270
+ export const CARD_KIND_WORK_LABEL = "kind/work";
271
+ export const CARD_KIND_REVIEW_LABEL = "kind/review";
272
+
273
+ /**
274
+ * owner → 角色词(纯函数)。取**首个命中**的角色词;命不中返回 `null`(自由文本不判角色)。
275
+ *
276
+ * 词边界匹配(而非子串):`reviewer` 不能被 `review` 命中、`codex` 不能被 `code` 命中。
277
+ * 「首个命中」按 `OWNER_ROLE_TOKENS` 的顺序(与团队编制表一致),含多个词时**保守取先出现的**。
278
+ */
279
+ export function ownerRole(owner) {
280
+ const text = String(owner ?? "").trim().toLowerCase();
281
+ if (text === "") return null;
282
+ for (const token of OWNER_ROLE_TOKENS) {
283
+ if (new RegExp(`(?:^|[^a-z])${token}(?:[^a-z]|$)`).test(text)) return token;
284
+ }
285
+ return null;
286
+ }
287
+
288
+ /**
289
+ * 这张卡**是不是执行类**(纯函数)。
290
+ *
291
+ * 判据:卡带看板自己的卡类型标记 `kind/work`,且没有 `kind/review`(两者同时出现=数据自相矛盾,不判)。
292
+ *
293
+ * **为什么不靠标题/描述猜**:看板没有别的字段能区分「要落地的执行卡」与「规划/文档卡」——
294
+ * 两者在 owner 上都可能是 planner。2026-11-12 真机库实测(`.data/taskboard.sqlite`,299 张卡):
295
+ * 宽判据「在途 + owner∈{planner,reviewer,archivist}」命中 4 张,**4/4 全是误报**
296
+ * (`scada-vibe-3/4/6/12` 全是 planner 的正经规划卡:需求条款化 / 条款迁移 / 决策单 / 需求补条)。
297
+ * ⇒ 按卡 `-246`「历史卡大面积误报 ⇒ 停,改判据」的处置,判据收窄到**看板自己有类型标记**的卡。
298
+ */
299
+ export function isExecutionClassCard(task) {
300
+ const labels = Array.isArray(task?.labels)
301
+ ? task.labels.map((l) => String(l ?? "").trim().toLowerCase())
302
+ : [];
303
+ if (!labels.includes(CARD_KIND_WORK_LABEL)) return false;
304
+ if (labels.includes(CARD_KIND_REVIEW_LABEL)) return false;
305
+ return true;
306
+ }
307
+
231
308
  export const DIAGNOSTIC_RULES = Object.freeze([
232
309
  {
233
310
  kind: "block_loop",
@@ -468,6 +545,52 @@ export const DIAGNOSTIC_RULES = Object.freeze([
468
545
  };
469
546
  },
470
547
  },
548
+ {
549
+ /**
550
+ * 卡 `-246`(需求 `R178` ③):**owner 与角色错配** —— owner 是自由文本,不校验角色,
551
+ * 于是「这张执行卡的 owner 是 review/plan 岗」这类越位只能靠人肉发现。
552
+ *
553
+ * 判据(三条**全部**满足才报):
554
+ * ① **owner 越位**:owner 归一后命中不执行的角色 {planner, reviewer, archivist}
555
+ * (自由文本如 `codex` 不判 —— 判不准就不升级,FR-85 红线)。
556
+ * ② **卡是执行类**:卡带看板自己的卡类型标记 `kind/work`(`kind/review` 的审查卡不判)。
557
+ * ③ **卡在途**:`done` / `canceled` 不再提示 —— 收口卡的历史错配不影响当下。
558
+ *
559
+ * **只诊断、不拦截**(任务书「移出:硬拦截(会误伤历史卡)」):本规则不写库、不改状态、
560
+ * 不阻断建卡与派发,只产出一条 medium 提示 + 两个恢复动作(人工改绑 / 人工忽略)。
561
+ */
562
+ kind: "owner-role-mismatch",
563
+ evaluate(ctx) {
564
+ const { task, dismissed } = ctx;
565
+ if (dismissed.has("owner-role-mismatch")) return null;
566
+ const role = ownerRole(task.owner);
567
+ if (!role || !NON_EXECUTING_OWNER_ROLES.includes(role)) return null;
568
+ if (!isExecutionClassCard(task)) return null;
569
+ if (task.status === "done" || task.status === "canceled") return null;
570
+ const enc = encodeRef(task.identifier);
571
+ const roleLabel = OWNER_ROLE_LABELS[role] ?? role;
572
+ return {
573
+ kind: "owner-role-mismatch", severity: "medium",
574
+ title: `负责人与卡的类型错配:工作项的负责人是「${roleLabel}」`,
575
+ detail: `这张卡标着「工作项(${CARD_KIND_WORK_LABEL})」—— 是要派出去执行/落地的活;`
576
+ + `但负责人(owner)写的是「${roleLabel}」,那是**不执行**的角色(执行岗是 开发 engineer / 测试 tester)。\n`
577
+ + `越位的后果:这条活要么没人认领(owner 指向错岗),要么被当成审查/规划/归档处理。\n`
578
+ + `请人工确认:若确实由执行岗做 → 改绑负责人;若这张卡本来就是审查/规划/归档卡 → 忽略此项(不是缺陷)。`,
579
+ suggested: "reassign_owner",
580
+ actions: [
581
+ action("reassign_owner", "改绑负责人(执行岗 engineer)", {
582
+ kind: "primary", method: "PATCH", path: `/api/tasks/${enc}`,
583
+ body: { owner: "engineer", version: task.version },
584
+ hint: "按项目实际编制改(测试活填 tester);若这张卡本就是审查/规划/归档卡,请改用「忽略此项」。",
585
+ }),
586
+ action("dismiss", "忽略此项(owner 正确 / 卡不是执行卡)", {
587
+ path: `/api/tasks/${enc}/diagnostics/dismiss`, body: { kind: "owner-role-mismatch" },
588
+ hint: "写一条忽略留痕,原文可回溯",
589
+ }),
590
+ ],
591
+ };
592
+ },
593
+ },
471
594
  ]);
472
595
 
473
596
  /** 纯函数:按规则集产出诊断列表(按严重度 → kind 稳定排序)。 */
@@ -98,6 +98,15 @@ export const ERROR_CATEGORY = Object.freeze({
98
98
  REQ_IDENTIFIER_CONFLICT: EXIT.CONFLICT,
99
99
  DEPENDENCY_EXISTS: EXIT.CONFLICT,
100
100
  DOC_EXISTS: EXIT.CONFLICT,
101
+ // 卡 `-238`(R174):执行者按卡选择 —— 三种「选不了」必须**分开报**,否则人分不清该去装 CLI、
102
+ // 还是去改项目设置(forbiddenExecutors 优先级最高)。
103
+ EXECUTOR_UNKNOWN: EXIT.USAGE,
104
+ EXECUTOR_NOT_INSTALLED: EXIT.USAGE,
105
+ EXECUTOR_FORBIDDEN: EXIT.USAGE,
106
+ // 选了一个「不是 CLI 形态」的执行者(team / host-session)却打到 exec-cli 上 ⇒ 用法错误,并指路正确入口
107
+ EXECUTOR_NOT_CLI: EXIT.USAGE,
108
+ // 卡 `-237`(R173):同一个库同一时刻只允许一个写者;follower 的所有写操作一律 409。
109
+ FOLLOWER_READ_ONLY: EXIT.CONFLICT,
101
110
  });
102
111
 
103
112
  /** 领域错误:带 code / 退出码 / 可选细节。 */
@@ -10,6 +10,16 @@ import path from "node:path";
10
10
  import { execFileSync } from "node:child_process";
11
11
 
12
12
  export const EVIDENCE_FIELDS = Object.freeze(["verdict", "deviation", "boundary", "artifacts"]);
13
+
14
+ /**
15
+ * `kind` 的**唯一枚举**(FR-106 · 0-B-b):证据条目可用的五类。
16
+ * 为什么要收在一处:MCP 的 `card_progress.evidence[]`、MCP 的 `card_evidence_submit`、
17
+ * HTTP 的 `POST /api/tasks/:ref/evidence` 三个入口都要判同一套值 ——
18
+ * 各写一份必然漂移(此前 tools.mjs 里就有一份只到 `reading` 的副本)。
19
+ */
20
+ export const EVIDENCE_KINDS = Object.freeze(["file", "command", "url", "reading", "commit"]);
21
+
22
+ /** 真正参与 `artifact_refs` 核验的 kind(其余**逐条不进** `artifact_refs` ⇒ 行级 `unchecked`)。 */
13
23
  export const EVIDENCE_REF_KINDS = Object.freeze(["commit", "file"]);
14
24
 
15
25
  const text = (v) => (typeof v === "string" ? v.trim() : "");
@@ -39,6 +49,24 @@ export function normalizeArtifactRefs(refs) {
39
49
  return out;
40
50
  }
41
51
 
52
+ /**
53
+ * **入口层**白名单校验(FR-106 第 3 条):`artifact_refs[].kind` 不在 `{commit,file}` 内就**显式报错**。
54
+ *
55
+ * 与 `normalizeArtifactRefs` 的分工必须区分清楚:
56
+ * · **规则层**(`normalizeArtifactRefs`)继续**静默丢弃**非法项 —— 契约不变,`tests/task-evidence.test.mjs` D 组钉着;
57
+ * · **入口层**(MCP / HTTP 的写入口)先跑这里,非法即整笔拒(`INVALID_ARTIFACT_REF`)⇒ 调用方拿得到真原因。
58
+ * 只在入口层做,是为了不改动任何既有规则层行为。
59
+ */
60
+ export function artifactRefKindProblems(refs) {
61
+ if (!Array.isArray(refs)) return [];
62
+ const bad = [];
63
+ refs.forEach((r, index) => {
64
+ const kind = text(r?.kind);
65
+ if (!EVIDENCE_REF_KINDS.includes(kind)) bad.push({ index, kind: kind || null, allowedKinds: [...EVIDENCE_REF_KINDS] });
66
+ });
67
+ return bad;
68
+ }
69
+
42
70
  /**
43
71
  * 核验 `artifact_refs`:任一解不开即整体 `unresolved`(不"部分通过")。
44
72
  * `resolve({kind, ref})` 由调用方注入 —— 默认实现见 `makeResolver`。