taskboard-workbench 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +101 -2
  2. package/index.js +112 -13
  3. package/package.json +6 -2
  4. package/scripts/tb-flow.mjs +109 -8
  5. package/skills/taskboard-flow/SKILL.md +2 -2
  6. package/skills/taskboard-flow/references/injection.md +76 -29
  7. package/skills/taskboard-flow/references/steps/S5.md +21 -1
  8. package/spec/docs/01-/351/241/271/347/233/256/345/274/200/345/261/200.md +63 -0
  9. package/spec/docs/02-/346/265/201/347/250/213/346/211/247/350/241/214/344/270/216/346/235/241/347/233/256.md +110 -0
  10. package/spec/docs/README.md +36 -0
  11. package/spec/docs/assets//346/235/241/347/233/256/350/257/246/346/203/205/346/250/241/346/235/277.md +105 -0
  12. package/spec/norms/item-detail.md +73 -0
  13. package/spec/norms/manifest.json +7 -0
  14. package/src/core/config.mjs +12 -3
  15. package/src/core/contract.mjs +17 -7
  16. package/src/core/data-dir-hint.mjs +52 -0
  17. package/src/core/docs-assets.mjs +135 -0
  18. package/src/core/errors.mjs +11 -0
  19. package/src/core/evidence.mjs +28 -0
  20. package/src/core/executor.mjs +27 -7
  21. package/src/core/executors.mjs +279 -0
  22. package/src/core/flow-inject.mjs +190 -0
  23. package/src/core/instance-lease.mjs +113 -0
  24. package/src/core/kickoff.mjs +289 -0
  25. package/src/core/norms.mjs +177 -0
  26. package/src/core/requirements.mjs +38 -0
  27. package/src/core/store.mjs +333 -36
  28. package/src/core/verify.mjs +39 -4
  29. package/src/mcp/flow-block.mjs +30 -0
  30. package/src/mcp/server.mjs +19 -6
  31. package/src/mcp/tools.mjs +99 -7
  32. package/src/server/api.mjs +361 -11
  33. package/web/app.js +1077 -82
  34. package/web/tokens.css +166 -28
@@ -1,7 +1,12 @@
1
1
  /**
2
2
  * api.mjs —— 纯路由逻辑(不依赖 node:http)。独立服务与 DSH 宿主插件共用。
3
3
  */
4
+ import path from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+
4
7
  import { PRIORITIES, STATUSES } from "../core/domain.mjs";
8
+ import { materializeProjectNorms, normsView } from "../core/norms.mjs";
9
+ import { docsView, materializeProjectDocs, readDocFile } from "../core/docs-assets.mjs";
5
10
  import { clampElaborateLimit } from "../core/requirements.mjs";
6
11
  import { EXIT, TbError, invalidField } from "../core/errors.mjs";
7
12
  import { resolveContext } from "../core/binding.mjs";
@@ -12,6 +17,7 @@ import { runExecutionLoop, activeEngine } from "../core/loop.mjs";
12
17
  import { assertTeamTemplate, assertQualityGates, planTeamMembers } from "../core/team.mjs";
13
18
  import { assessTaskRef, projectWatchdog } from "../core/watchdog.mjs";
14
19
  import { ticketStage } from "../core/ticket-stage.mjs";
20
+ import { artifactRefKindProblems, EVIDENCE_REF_KINDS } from "../core/evidence.mjs";
15
21
  import { isHumanReviewTask, planHumanReview } from "../core/human-review.mjs";
16
22
  import { deriveNextStep } from "../core/next-step.mjs";
17
23
  /**
@@ -21,12 +27,17 @@ import { deriveNextStep } from "../core/next-step.mjs";
21
27
  * 真实情况:独立进程实例(`node src/server/server.mjs`,没有 DSH 宿主)的 `host.capabilities` 恒为 `null`,
22
28
  * 这类动作在该进程上**做不到**,正确出路是"换到 DSH 内的任务工作台"或"把 prompt 粘到会话里手工投递"。
23
29
  */
30
+ /** 随包机器规范目录(`package.json#files` 含 `spec/norms`);项目副本在 `<工作区>/.taskboard/norms/`。 */
31
+ const PACKAGED_NORMS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../spec/norms");
32
+ /** 随包**人读**文档目录(`package.json#files` 含 `spec/docs`);项目副本默认在 `<工作区>/.taskboard/docs/`。 */
33
+ const PACKAGED_DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../spec/docs");
34
+
24
35
  const HOST_UNAVAILABLE_NEXT = "该实例没有宿主会话通道(独立进程,/api/health 的 host.capabilities 为 null):改到 DSH 内的任务工作台操作,或把返回的 prompt 直接粘到会话里手工投递";
25
36
 
26
37
  import { buildDebugDispatchPrompt } from "../core/debug-dispatch.mjs";
27
38
  import { buildSplitAskPrompt } from "../core/split-ask.mjs";
28
- import { buildReviewEvidence, formatVerifyComment, normalizeVerifyCommand, summarizeVerifyOutput, VERIFY_DEFAULT_COMMAND } from "../core/verify.mjs";
29
- import { evaluateKickoff } from "../core/kickoff.mjs";
39
+ import { buildReviewEvidence, detectUnrunnableVerify, formatVerifyComment, normalizeVerifyCommand, summarizeVerifyOutput, VERIFY_DEFAULT_COMMAND } from "../core/verify.mjs";
40
+ import { buildGapPrompt, buildKickoffTodos, collectGaps, evaluateKickoff } from "../core/kickoff.mjs";
30
41
  import { deriveEmptyState } from "../core/empty-state.mjs";
31
42
  // 2026-10-28 拍板 E1–E3 / D-M1–D-M5:项目推进清单(纯投影 + 幂等回写)与项目记忆(L2 条目 + L3 召回)。
32
43
  import { buildAdvance, renderAdvanceBlock, applyDecision } from "../core/advance.mjs";
@@ -37,9 +48,14 @@ import { runVerifyCommand, probeVerifyApplicability } from "./verify.mjs";
37
48
  import { DIAGNOSTIC_KINDS, evaluateTaskDiagnostics, projectDiagnostics, summarizeDiagnostics, resolveSessionRef, humanReviewProbe, humanReviewAnsweredBy } from "../core/diagnostics.mjs";
38
49
  import { summarizeNotifyDelivery } from "../core/notify.mjs";
39
50
  import { resolveCliExecutor, executeTaskWithCli, buildTaskPrompt, cliArgsFor, claimForCliExecution, DEFAULT_TIMEOUT_MS } from "../core/executor.mjs";
51
+ // 卡 `-238`(R174):执行者注册表 —— 按卡选「团队 / dsh / claude / codex / hermes」的唯一真源。
52
+ // 本文件只用它**解析与校验**,参数与「指令怎么给」都由注册表给,路由不另写第二份。
53
+ import { EXECUTOR_SPECS, EXECUTOR_KINDS, buildExecutorArgs, detectBinary, findExecutorSpec, isExecutorForbidden, listExecutors } from "../core/executors.mjs";
40
54
  import { DEFAULT_FAILURE_LIMIT } from "../core/store.mjs";
41
55
  // 卡 `-177`(2026-10-29 · 口径 X):acceptance 缺省口径与 MCP **共用同一份**,不在本文件另写判断。
42
56
  import { markAcceptance, acceptanceFlag } from "../core/acceptance.mjs";
57
+ // P5 档 C(卡 `-210`):开局注入的唯一实现(内容仍由 `buildFlowBlock()` 生成,本文件不复制正文)。
58
+ import { FLOW_INJECT_MANUAL, FLOW_INJECT_ROLES, injectFlow, normalizeFlowInjectPolicy } from "../core/flow-inject.mjs";
43
59
 
44
60
  export const API_SCHEMA_VERSION = 2;
45
61
 
@@ -50,7 +66,12 @@ export function httpStatusFor(error) {
50
66
  return 400;
51
67
  }
52
68
 
53
- export function createApiRouter({ store, aiElaborator, events } = {}) {
69
+ /**
70
+ * @param executorProbe 执行者探测(默认 `detectBinary`)。**可注入**是为了让「未安装」这条分支
71
+ * 能被测试真实走一遍 —— 否则本机四个 CLI 全装着,`EXECUTOR_NOT_INSTALLED` 永远测不到。
72
+ * 与 `TB_CLI_EXECUTOR_BIN` 同属「测试/宿主替身」这一层,不改变生产默认行为。
73
+ */
74
+ export function createApiRouter({ store, aiElaborator, events, executorProbe = detectBinary } = {}) {
54
75
  const emit = (type, payload) => { try { events?.publish?.(type, payload); } catch { /* ignore */ } };
55
76
  /**
56
77
  * 已有执行会话仍在执行(未返回结论)→ 不得再次下发。
@@ -183,6 +204,19 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
183
204
  ].join("\n");
184
205
  }
185
206
  async function route({ method, pathname, searchParams, body = {} }) {
207
+ // 卡 `-237`(需求 `R173`):同一个库同一时刻只允许一个写者。
208
+ // follower 一律只读 —— **所有非 GET 直接 409**,不做「部分放行」:
209
+ // 放行一半比全拒更难解释,也更容易踩到对端正跑着的执行。
210
+ // **现读**(fresh)而不是吃本地缓存:缓存最多滞后一个心跳周期,那 15s 就是真实双写窗口。
211
+ if (method !== "GET" && method !== "HEAD" && method !== "OPTIONS"
212
+ && (typeof store.instanceRoleFresh === "function" ? store.instanceRoleFresh() : "writer") === "follower") {
213
+ const leaseOwner = typeof store.instanceLeaseOwnerFresh === "function" ? store.instanceLeaseOwnerFresh() : null;
214
+ throw new TbError(
215
+ "FOLLOWER_READ_ONLY",
216
+ `本实例是只读跟随者:另一个工作台实例正在写同一个库(${leaseOwner ? `${leaseOwner.host} · pid ${leaseOwner.pid}` : "对端实例"})。请到那个窗口操作,或等它退出后本窗口会自动接管。`,
217
+ { role: "follower", leaseOwner, dataDir: store.dataDir },
218
+ );
219
+ }
186
220
  if (pathname === "/api/health" && method === "GET") {
187
221
  // 宿主能力可见性(诊断):投递指令 / 建会话 / 打开会话 各依赖的宿主服务是否已就绪。
188
222
  const has = (fn) => { try { return typeof fn === "function"; } catch { return false; } };
@@ -217,6 +251,49 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
217
251
  payload: { statuses: STATUSES, priorities: PRIORITIES, dataDir: store.dataDir, dbPath: store.dbPath },
218
252
  };
219
253
  }
254
+ if (pathname === "/api/executors" && method === "GET") {
255
+ // 卡 `-238`(R174):把「这张卡能交给谁跑」变成**可读数据**,前端照它渲染图标、按它的 id 派发。
256
+ // 只读:不 spawn 干活(仅 `--version` 探测,失败即 null)、不写库、不碰宿主会话。
257
+ // 项目维度的两处判据必须带 `projectId`:`forbiddenExecutors` 与 `executionTeam` 都是**项目设置**。
258
+ const projectId = searchParams.get("projectId") ?? searchParams.get("project") ?? null;
259
+ const settings = projectId ? store.getProjectSettings(projectId) : null;
260
+ const port = store.hostSessionPort;
261
+ // 与 `/api/health` 同口径(`createSession: Boolean(port?.available)`):宿主会话通道成不成立看它。
262
+ const hostSessionAvailable = Boolean(port && port.available);
263
+ // `executionTeam` 为空 ⇒ 团队派发没有落点。没带 projectId 时**判不准** ⇒ 传 null(按可用处理,不冒充不可用)。
264
+ const teamAvailable = projectId ? Boolean(settings?.teamTemplate?.executionTeam) : null;
265
+ const executors = await listExecutors({
266
+ settings,
267
+ hostSessionAvailable,
268
+ teamAvailable,
269
+ detect: executorProbe,
270
+ // 版本探测**默认关**:真机实测 `hermes --version` 不退出(>10s 才被杀),为它牺牲首屏
271
+ // 不划算(这个字段只用于展示)。要就显式 `?version=1`,那是诊断/人查的动作,不是页面必经之路。
272
+ withVersion: searchParams.get("version") === "1",
273
+ });
274
+ // `defaultId`=「**不换执行者**时这张卡本来会走谁」:优先项目 `roles[].executor`(走既有
275
+ // `resolveCliExecutor` 同一套解析,含 forbidden 过滤),解析不到就退宿主会话。
276
+ // 为什么由服务端给:前端不该知道 `teamTemplate.roles[].executor` 这种配置细节,
277
+ // 否则「默认选中项」会与真实派发口径各说一套。
278
+ const configured = (() => {
279
+ try { return resolveCliExecutor(settings, { role: "engineer" }); } catch { return null; }
280
+ })();
281
+ const configuredId = configured?.id ?? null;
282
+ const defaultId = (configuredId && executors.some((item) => item.id === configuredId && item.usable))
283
+ ? configuredId
284
+ : (executors.some((item) => item.id === "host:dsh" && item.usable) ? "host:dsh" : executors.find((item) => item.usable)?.id ?? null);
285
+ return {
286
+ status: 200,
287
+ payload: {
288
+ schemaVersion: 2,
289
+ projectId,
290
+ executors,
291
+ defaultId,
292
+ hostSessionAvailable,
293
+ hostCapabilities: (() => { try { return port?.capabilities?.() ?? null; } catch { return null; } })(),
294
+ },
295
+ };
296
+ }
220
297
  if (pathname === "/api/context" && method === "GET") {
221
298
  // 工作区(cwd) → 项目 → 需求文档 的初始绑定;session= 时绑定/校验"主会话与关联"(FR-60/FR-62/FR-63)
222
299
  const cwd = searchParams.get("cwd") ?? undefined;
@@ -330,6 +407,59 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
330
407
  });
331
408
  return { status: 200, payload: { project: project.id, workspacePath: project.workspacePath ?? null, readable: facts.readable, ...report } };
332
409
  }
410
+ // 卡 `-229`(需求 R170):配置页「引入主对话」—— 把**当前实时缺口**投给项目主会话。
411
+ // 与上方 GET /kickoff 严格分离:GET 只读(注释见上,绝不写任何数据);本路由只做「现算缺口 + 投递 + 审计」,
412
+ // 同样**不改任何完成度数据**。缺口由 collectGaps(evaluateKickoff(...)) 投影 ⇒ 完成度真源仍只有 evaluateKickoff。
413
+ const projectKickoffAnnounceRoute = /^\/api\/projects\/([^/]+)\/kickoff\/announce$/.exec(pathname);
414
+ if (projectKickoffAnnounceRoute) {
415
+ if (method !== "POST") throw new TbError("USAGE_ERROR", "kickoff/announce 仅支持 POST");
416
+ const project = store.requireProject(decodeURIComponent(projectKickoffAnnounceRoute[1]));
417
+ // 每次现算(与 GET /kickoff 同一份自检数据源),保证「投出去的条目数 = 配置页未完成项数」。
418
+ const settings = store.getProjectSettings(project.id);
419
+ const facts = collectKickoffFacts(project.workspacePath ?? null);
420
+ const report = evaluateKickoff({
421
+ files: facts.files,
422
+ settings,
423
+ custom: { reviewerRole: hasReviewerRole(settings?.teamTemplate), engineerExecutor: hasEngineerExecutor(settings?.teamTemplate) },
424
+ });
425
+ const gaps = collectGaps(report);
426
+ // 卡 `-230`:同一次聚合出**结构化 todolist**(一步一条、依赖顺序、每条带可执行判据)。
427
+ const todos = buildKickoffTodos({ project, gaps });
428
+ // 卡 `t20`(需求 `R170`):缺口注入必须带「关联需求」—— 否则执行侧建的卡会被归因门拒(EXECUTION_NOT_ATTRIBUTED)。
429
+ // 候选只取**本项目未关闭**的条目:已关闭的条目建出来的卡同样过不了归因门(等价于未归属)。
430
+ const requirements = store
431
+ .listRequirementItems({ projectId: project.id })
432
+ .filter((it) => it.status !== "closed")
433
+ .map((it) => ({ identifier: it.identifier, title: it.title }));
434
+ // 显式指定的那条要**先校验再拼正文**:不存在的引用不得静默降级成「未指定」(那会建出一堆无归属的卡)。
435
+ let requirement = null;
436
+ const requirementRef = body.requirement == null ? "" : String(body.requirement).trim();
437
+ if (requirementRef !== "") {
438
+ // 卡 `-234`:本路由一定知道项目 ⇒ 简写 `R170` 按本项目解析。
439
+ const item = store.requireRequirementItemRef(requirementRef, { projectId: project.id }); // 不存在 ⇒ REQUIREMENT_NOT_FOUND
440
+ if (item.projectId !== project.id) {
441
+ throw new TbError("REQUIREMENT_NOT_FOUND", `需求条目不属于本项目:${requirementRef}`, { ref: requirementRef, projectId: project.id });
442
+ }
443
+ requirement = { identifier: item.identifier, title: item.title };
444
+ }
445
+ const prompt = buildGapPrompt({ project, gaps, todos, requirement, requirements });
446
+ const summary = { step: gaps.step, done: gaps.done, total: gaps.total, count: gaps.items.length, todos: todos.length };
447
+ const sid = body.sessionId ? String(body.sessionId) : (project.initialSessionId ?? null);
448
+ if (!sid) throw new TbError("NO_MAIN_SESSION", "该项目还没有主会话:先在开局流程绑主会话,或用 body.sessionId 指定", { projectId: project.id, gaps: summary, todos, prompt, requirement, requirements });
449
+ const hostPort = store.hostSessionPort;
450
+ if (!hostPort || typeof hostPort.sendPrompt !== "function") {
451
+ // 与本文件 split-ask 同口径:投不进去也要给人能做的事 —— 正文原样回带(前端据此降级,不得谎称已投递)。
452
+ // 新增 host-unavailable 投递点须同步校准 `tests/host-gate.test.mjs` 的计数(守卫按该字面量出现次数钉住)。
453
+ return { status: 200, payload: { project: project.id, sessionId: sid, delivered: false, reason: "host-unavailable", hostCapabilities: null, nextAction: HOST_UNAVAILABLE_NEXT, gaps: summary, todos, prompt, requirement, requirements, block: prompt } };
454
+ }
455
+ let sent = null;
456
+ try { sent = await hostPort.sendPrompt(sid, prompt); } catch (e) { sent = { sent: false, reason: e?.message ?? "error" }; }
457
+ const delivered = Boolean(sent?.sent ?? sent?.delivered);
458
+ try {
459
+ store.recordAudit({ actor: body.actor ?? "board", action: "kickoff-announce", target: project.id, allowed: delivered, reason: delivered ? "delivered" : (sent?.reason ?? "delivery-failed"), detail: `session=${sid} gaps=${gaps.items.length} checks=${gaps.done}/${gaps.total} steps=${gaps.step}` });
460
+ } catch { /* 审计失败不阻断投递结论(投递已生效时谎报失败会诱发重复注入) */ }
461
+ return { status: 200, payload: { project: project.id, sessionId: sid, delivered, reason: delivered ? null : (sent?.reason ?? "delivery-failed"), gaps: summary, todos, prompt, requirement, requirements, block: prompt } };
462
+ }
333
463
  // 项目设置(FR-56):项目环境约束 + agent 执行团队模板
334
464
  const projectSettingsRoute = /^\/api\/projects\/([^/]+)\/settings$/.exec(pathname);
335
465
  if (projectSettingsRoute) {
@@ -346,11 +476,146 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
346
476
  if (roles.length) assertTeamTemplate({ roles, qualityGates: tpl?.qualityGates });
347
477
  else assertQualityGates({ qualityGates: tpl?.qualityGates });
348
478
  }
349
- const saved = store.saveProjectSettings(project.id, { envConfig: body.envConfig, teamTemplate: body.teamTemplate, loop: body.loop });
479
+ // P5 档 C(卡 `-210`):`flowInjectPolicy` 是**切换注入行为**的配置 ⇒ 写前校验(非法值不落库)。
480
+ // 未传 = 保持不变(老前端 / 只改 envConfig 的调用方零影响)。
481
+ let flowInjectPolicy;
482
+ if (body.flowInjectPolicy !== undefined) flowInjectPolicy = normalizeFlowInjectPolicy(body.flowInjectPolicy, { strict: true });
483
+ const saved = store.saveProjectSettings(project.id, { envConfig: body.envConfig, teamTemplate: body.teamTemplate, loop: body.loop, flowInjectPolicy });
350
484
  return { status: 200, payload: saved };
351
485
  }
352
486
  throw new TbError("USAGE_ERROR", "settings 仅支持 GET 或 PUT");
353
487
  }
488
+ // 开局注入(P5 档 C · 卡 `-210`):档 C 的**人工出口**(`tb-flow inject --session`)+ 审计查询。
489
+ // 内容与自动注入**共用** `src/core/flow-inject.mjs`(同一个 `buildFlowBlock()`)—— 本文件不复制正文。
490
+ const projectFlowRoute = /^\/api\/projects\/([^/]+)\/flow\/(inject|injections)$/.exec(pathname);
491
+ if (projectFlowRoute) {
492
+ const project = store.requireProject(decodeURIComponent(projectFlowRoute[1]));
493
+ const action = projectFlowRoute[2];
494
+ const configuredPolicy = store.getProjectSettings(project.id).flowInjectPolicy ?? "off";
495
+ if (action === "injections") {
496
+ if (method !== "GET") throw new TbError("USAGE_ERROR", "flow/injections 仅支持 GET");
497
+ const rows = store.listFlowInjections({ projectId: project.id, sessionId: searchParams.get("sessionId") ?? undefined });
498
+ return { status: 200, payload: { projectId: project.id, policy: configuredPolicy, injections: rows } };
499
+ }
500
+ if (method !== "POST") throw new TbError("USAGE_ERROR", "flow/inject 仅支持 POST");
501
+ const sessionId = String(body.sessionId ?? "").trim();
502
+ if (!sessionId) throw new TbError("USAGE_ERROR", "缺 sessionId:要投进哪个会话(tb-flow inject --session <id>)");
503
+ // 角色:显式优先;不传就按「是不是项目主会话」推(推错只会少注,不会把完整版塞进执行会话)。
504
+ const role = body.role === undefined || body.role === null || String(body.role).trim() === ""
505
+ ? (sessionId === project.initialSessionId ? "main" : "exec")
506
+ : String(body.role).trim();
507
+ if (!FLOW_INJECT_ROLES.includes(role)) {
508
+ throw new TbError("USAGE_ERROR", `role 只能是 ${FLOW_INJECT_ROLES.join(" / ")}`, { role });
509
+ }
510
+ const port = store.hostSessionPort;
511
+ // 人工一次性投递:审计记 `manual`(显式绕过 `off`,但**子 agent 仍不注入** —— 硬规则不因人工放开)。
512
+ const result = await injectFlow({
513
+ store,
514
+ deliver: (sid, text) => (port && typeof port.sendPrompt === "function"
515
+ ? port.sendPrompt(sid, text)
516
+ : Promise.resolve({ sent: false, reason: "host-unavailable" })),
517
+ projectId: project.id,
518
+ sessionId,
519
+ role,
520
+ policy: FLOW_INJECT_MANUAL,
521
+ source: body.source ?? "api",
522
+ });
523
+ if (!result.injected) {
524
+ return { status: 200, payload: {
525
+ delivered: false, sessionId, role, policy: result.policy, reason: result.reason,
526
+ nextAction: result.reason === "host-unavailable" ? HOST_UNAVAILABLE_NEXT : null,
527
+ // 投不进去也要给出人能做的事:正文原样回带,手工粘贴即可(与本文件 split-ask 同口径)。
528
+ prompt: result.text ?? null, digest: result.digest ?? null, chars: result.chars ?? 0,
529
+ } };
530
+ }
531
+ try {
532
+ store.recordAudit({
533
+ actor: "board", action: "flow-inject", target: project.id, allowed: true, reason: role,
534
+ detail: JSON.stringify({ sessionId, policy: result.policy, version: result.version, digest: result.digest, chars: result.chars, source: result.source }),
535
+ });
536
+ } catch { /* 审计失败不影响投递结论(投递已生效,谎报失败会诱发重复注入) */ }
537
+ return { status: 200, payload: {
538
+ delivered: true, sessionId, role, policy: result.policy, version: result.version,
539
+ contractVersion: result.contractVersion, digest: result.digest, chars: result.chars,
540
+ injection: {
541
+ id: result.injectionId, projectId: project.id, sessionId, policy: result.policy,
542
+ contractVersion: result.contractVersion, digest: result.digest, injectedAt: result.injectedAt,
543
+ },
544
+ auditRecorded: result.auditRecorded, source: result.source,
545
+ } };
546
+ }
547
+ // 项目级机器规范(卡 `-216` / 需求 `R160`):看板到底读的是哪份、要不要生成 / 恢复副本。
548
+ const projectNormsRoute = /^\/api\/projects\/([^/]+)\/norms$/.exec(pathname);
549
+ if (projectNormsRoute) {
550
+ const project = store.requireProject(decodeURIComponent(projectNormsRoute[1]));
551
+ const workspacePath = project.workspacePath ?? null;
552
+ if (method === "GET") {
553
+ return { status: 200, payload: normsView({ packagedDir: PACKAGED_NORMS_DIR, workspacePath }) };
554
+ }
555
+ if (method === "POST") {
556
+ const action = String(body.action ?? "materialize");
557
+ if (action !== "materialize" && action !== "reset") throw new TbError("USAGE_ERROR", "action 只支持 materialize / reset");
558
+ const out = materializeProjectNorms({ packagedDir: PACKAGED_NORMS_DIR, workspacePath, overwrite: action === "reset" });
559
+ try {
560
+ store.recordAudit({
561
+ actor: body.actor ?? "human", action: `norms-${action}`, target: project.id, allowed: true,
562
+ reason: out.dir, detail: JSON.stringify({ written: out.written, kept: out.kept }),
563
+ });
564
+ } catch { /* 审计失败不影响复制结果 */ }
565
+ return { status: 200, payload: { ...out, view: normsView({ packagedDir: PACKAGED_NORMS_DIR, workspacePath }) } };
566
+ }
567
+ throw new TbError("USAGE_ERROR", "norms 仅支持 GET 或 POST(POST body.action = materialize | reset)");
568
+ }
569
+ // 项目级**人读**文档位置(卡 `-220` / 需求 `R161`):包内默认 / 项目存放 / 生效来源 —— 可查、可看、可改。
570
+ // 与 `norms` 分开:这里改文档**不影响契约**(契约只吃 `spec/norms/`),所以别做成同一张卡。
571
+ const projectDocsRoute = /^\/api\/projects\/([^/]+)\/docs$/.exec(pathname);
572
+ if (projectDocsRoute) {
573
+ const project = store.requireProject(decodeURIComponent(projectDocsRoute[1]));
574
+ const workspacePath = project.workspacePath ?? null;
575
+ const overrideDir = store.getProjectSettings(project.id)?.envConfig?.docsDir ?? null;
576
+ const view = () => docsView({ packagedDir: PACKAGED_DOCS_DIR, workspacePath, overrideDir });
577
+ if (method === "GET") {
578
+ const file = searchParams.get("file");
579
+ // ?file= 只读「看一眼」:路径按**生效目录**解析(有副本读副本,没有读包内)。
580
+ if (file) {
581
+ const cur = view();
582
+ return { status: 200, payload: { ...readDocFile(cur.effective.dir, file), source: cur.effective.source, dir: cur.effective.dir } };
583
+ }
584
+ return { status: 200, payload: view() };
585
+ }
586
+ if (method === "POST") {
587
+ const action = String(body.action ?? "materialize");
588
+ if (action !== "materialize" && action !== "reset") throw new TbError("USAGE_ERROR", "action 只支持 materialize / reset");
589
+ const out = materializeProjectDocs({ packagedDir: PACKAGED_DOCS_DIR, workspacePath, overrideDir, overwrite: action === "reset" });
590
+ try {
591
+ store.recordAudit({
592
+ actor: body.actor ?? "human", action: `docs-${action}`, target: project.id, allowed: true,
593
+ reason: out.dir, detail: JSON.stringify({ written: out.written, kept: out.kept }),
594
+ });
595
+ } catch { /* 审计失败不影响复制结果 */ }
596
+ return { status: 200, payload: { ...out, view: view() } };
597
+ }
598
+ if (method === "PUT") {
599
+ // 改存放位置:空 / null ⇒ 恢复默认(删 docsDir 键,不留空串歧义)。
600
+ const next = body.dir;
601
+ if (next !== undefined && next !== null && typeof next !== "string") throw new TbError("USAGE_ERROR", "dir 必须是字符串或 null");
602
+ const current = store.getProjectSettings(project.id).envConfig ?? {};
603
+ const envConfig = { ...current };
604
+ if (next === undefined || next === null || String(next).trim() === "") delete envConfig.docsDir;
605
+ else envConfig.docsDir = String(next).trim();
606
+ // 写前先解析一遍:相对路径无工作区时会抛 WORKSPACE_MISSING —— 在写库**之前**拦,避免存进一个用不了的配置。
607
+ const after = docsView({ packagedDir: PACKAGED_DOCS_DIR, workspacePath, overrideDir: envConfig.docsDir ?? null });
608
+ store.saveProjectSettings(project.id, { envConfig });
609
+ try {
610
+ store.recordAudit({
611
+ actor: body.actor ?? "human", action: "docs-set-dir", target: project.id, allowed: true,
612
+ reason: after.project.dir, detail: JSON.stringify({ override: envConfig.docsDir ?? null, isDefault: !envConfig.docsDir }),
613
+ });
614
+ } catch { /* 审计失败不影响保存 */ }
615
+ return { status: 200, payload: docsView({ packagedDir: PACKAGED_DOCS_DIR, workspacePath, overrideDir: envConfig.docsDir ?? null }) };
616
+ }
617
+ throw new TbError("USAGE_ERROR", "docs 仅支持 GET / POST(materialize|reset) / PUT(dir)");
618
+ }
354
619
  // 会话 ↔ 项目关联(FR-63):列出 / 申请 / 批准
355
620
  const projectAgentTeamsRoute = /^\/api\/projects\/([^/]+)\/agent-teams$/.exec(pathname);
356
621
  if (projectAgentTeamsRoute) {
@@ -466,6 +731,9 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
466
731
  const created = await port.createSession({
467
732
  cwd: project.workspacePath ?? undefined,
468
733
  title: mainSessionName,
734
+ // P5 档 C(卡 `-210`):声明角色 —— 只有 `main` 才吃「完整版装载块」。
735
+ role: "main",
736
+ projectId: project.id,
469
737
  });
470
738
  const sessionId = created?.sessionId ?? null;
471
739
  if (!sessionId) throw new TbError("SESSION_CREATE_FAILED", "宿主未能创建会话", { reason: created?.reason ?? null });
@@ -695,6 +963,38 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
695
963
  }
696
964
 
697
965
 
966
+ // ---- FR-106(0-B-b · 卡 -239)· 交付证据写入口(HTTP 侧)----
967
+ // 与 MCP `card_evidence_submit` **同源**:同一个 store 方法、同一道四字段硬门、同一套错误码。
968
+ // 本层只多做一件规则层不做的事:**入口层 kind 白名单**(非 {commit,file} 显式拒,而不是静默丢)。
969
+ const taskEvidenceRoute = /^\/api\/tasks\/([^/]+)\/evidence$/.exec(pathname);
970
+ if (taskEvidenceRoute) {
971
+ if (method !== "POST") throw new TbError("USAGE_ERROR", "交付证据入口仅支持 POST");
972
+ const ref = decodeURIComponent(taskEvidenceRoute[1]);
973
+ const submittedRefs = body.artifact_refs ?? body.artifactRefs;
974
+ const badKinds = artifactRefKindProblems(submittedRefs);
975
+ if (badKinds.length) {
976
+ throw new TbError(
977
+ "INVALID_ARTIFACT_REF",
978
+ `artifact_refs 只接受 ${EVIDENCE_REF_KINDS.join(" / ")}(非法项:第 ${badKinds.map((b) => b.index + 1).join("、")} 项)`,
979
+ { problems: badKinds },
980
+ );
981
+ }
982
+ const evidence = store.addTaskEvidence(ref, {
983
+ verdict: body.verdict,
984
+ deviation: body.deviation,
985
+ boundary: body.boundary,
986
+ artifacts: body.artifacts,
987
+ artifactRefs: submittedRefs,
988
+ actor: body.actor ?? "agent",
989
+ });
990
+ const task = store.requireTaskRef(ref);
991
+ const stage = ticketStage(task, { evidence, comments: store.listComments(task.id) });
992
+ try {
993
+ store.recordAudit({ actor: String(body.actor ?? "agent"), action: "evidence-submit", target: task.identifier, allowed: true, reason: evidence.deduped ? "deduped" : "created", detail: `http · kind=${evidence.refsState} · hash=${evidence.evidenceHash ?? "null"}` });
994
+ } catch { /* 审计失败不影响业务写入 */ }
995
+ return { status: 201, payload: { evidence, ticketStage: stage } };
996
+ }
997
+
698
998
  // ---- 需求文档(FR-34) ----
699
999
  if (pathname === "/api/requirements/docs") {
700
1000
  if (method === "GET") {
@@ -1006,6 +1306,9 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1006
1306
  preset,
1007
1307
  cwd: store.getProject(execTask.projectId)?.workspacePath ?? undefined,
1008
1308
  title: sessionName,
1309
+ // P5 档 C(卡 `-210`):执行会话 ⇒ 只吃「摘要版」(`main-only` 下**不注入**)。
1310
+ role: "exec",
1311
+ projectId: execTask.projectId,
1009
1312
  });
1010
1313
  if (created?.sessionId) {
1011
1314
  sessionId = created.sessionId;
@@ -1187,13 +1490,44 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1187
1490
  const project = store.getProject(task.projectId);
1188
1491
  const settings = store.getProjectSettings(task.projectId);
1189
1492
  const role = String(body.role ?? "engineer");
1190
- const executor = resolveCliExecutor(settings, { role });
1493
+ // 卡 `-238`(R174):**按卡选执行者**(可选)。不传 = 逐字节走原口径(项目 `roles[].executor` 决定),
1494
+ // 传了 = 只对这一张卡生效,且**不绕过任何既有门**(人工校验 / 归因 / 授权 / 评审一个不落,见下)。
1495
+ const requestedExecutor = body.executor ?? searchParams.get("executor") ?? null;
1496
+ let chosenSpec = null;
1497
+ let executor = null;
1498
+ let binPath = null;
1499
+ if (requestedExecutor !== null && String(requestedExecutor).trim() !== "") {
1500
+ chosenSpec = findExecutorSpec(requestedExecutor);
1501
+ const known = EXECUTOR_SPECS.map((spec) => spec.id).join(" / ");
1502
+ if (!chosenSpec) {
1503
+ throw new TbError("EXECUTOR_UNKNOWN", `未知执行者「${String(requestedExecutor)}」:可用 ${known}`, { requested: String(requestedExecutor), known: EXECUTOR_SPECS.map((spec) => spec.id) });
1504
+ }
1505
+ // 三条「选不了」**分开报**:人要据此决定去装 CLI、去改项目设置、还是换入口。
1506
+ if (chosenSpec.kind !== EXECUTOR_KINDS.CLI) {
1507
+ throw new TbError("EXECUTOR_NOT_CLI", `执行者 ${chosenSpec.id}(kind=${chosenSpec.kind})不是 CLI 通道:${chosenSpec.kind === EXECUTOR_KINDS.TEAM ? "团队派发请用 POST /api/teams" : "宿主会话请用 POST /api/tasks/:ref/execute"}`, { executor: chosenSpec.id, kind: chosenSpec.kind });
1508
+ }
1509
+ if (isExecutorForbidden(chosenSpec, settings)) {
1510
+ throw new TbError("EXECUTOR_FORBIDDEN", `执行者 ${chosenSpec.id} 在项目 forbiddenExecutors 中:项目禁用的执行者不得按卡选择(改项目设置后才可选)`, { executor: chosenSpec.id });
1511
+ }
1512
+ const probe = executorProbe(chosenSpec.command);
1513
+ if (!probe.installed) {
1514
+ throw new TbError("EXECUTOR_NOT_INSTALLED", `执行者 ${chosenSpec.id} 未安装:已查 PATH · ~/.npm-global/bin · ~/.local/bin · /opt/homebrew/bin,未找到 ${chosenSpec.command}`, { executor: chosenSpec.id, command: chosenSpec.command, searched: probe.searched });
1515
+ }
1516
+ binPath = probe.binPath;
1517
+ executor = { id: chosenSpec.id, cli: chosenSpec.command, binPath, role };
1518
+ } else {
1519
+ executor = resolveCliExecutor(settings, { role });
1520
+ }
1191
1521
  if (!executor) throw new TbError("NO_CLI_EXECUTOR", `项目 ${task.projectId} 没有可用的 CLI 执行器(teamTemplate.roles[].executor 需为 cli:*,且不在 forbiddenExecutors 中)`);
1192
1522
  const cwd = project?.workspacePath ?? null;
1523
+ const prompt = buildTaskPrompt(task, { project, requirementId: task.requirementId ?? null, verifyCommand: settings?.teamTemplate?.engineer?.verifyCommand ?? null });
1524
+ // 参数:显式选了执行者 ⇒ 由注册表给(claude 仍复用 `cliArgsFor`,含 engineer.args 覆盖语义);
1525
+ // 否则原样 `cliArgsFor`(老路径的 plan 一字不差)。
1193
1526
  const plan = {
1194
- executor: executor.id, cli: executor.cli, role: executor.role, cwd,
1195
- args: cliArgsFor({ executorId: executor.id, cwd, settings }),
1196
- prompt: buildTaskPrompt(task, { project, requirementId: task.requirementId ?? null, verifyCommand: settings?.teamTemplate?.engineer?.verifyCommand ?? null }),
1527
+ executor: executor.id, cli: binPath ?? executor.cli, role: executor.role ?? role, cwd,
1528
+ args: chosenSpec ? (buildExecutorArgs(chosenSpec, { cwd, settings, prompt }) ?? cliArgsFor({ executorId: executor.id, cwd, settings })) : cliArgsFor({ executorId: executor.id, cwd, settings }),
1529
+ promptVia: chosenSpec?.promptVia ?? "stdin",
1530
+ prompt,
1197
1531
  };
1198
1532
  if (body.dryRun === true || searchParams.get("dryRun") === "1") return { status: 200, payload: { ran: false, dryRun: true, plan } };
1199
1533
  const timeoutMs = Number(body.timeoutMs ?? 0) > 0 ? Number(body.timeoutMs) : DEFAULT_TIMEOUT_MS;
@@ -1212,7 +1546,12 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1212
1546
  // 进入「进行中」**,否则整个执行期看板显示错误的列(2026-10-18 实测 -73 停在「待办池」14 分钟)。
1213
1547
  const claim = claimForCliExecution(store, task.identifier, { actor: "cli-executor" });
1214
1548
  emit("task.updated", { taskId: task.id, identifier: task.identifier, status: store.requireTaskRef(task.identifier).status });
1215
- const fire = () => executeTaskWithCli({ store, task, project, settings, role, timeoutMs }).catch((error) => ({ ran: false, reason: String(error?.message ?? error) }));
1549
+ const fire = () => executeTaskWithCli({
1550
+ store, task, project, settings, role, timeoutMs,
1551
+ resolvedExecutor: executor,
1552
+ argsOverride: chosenSpec ? plan.args : null,
1553
+ promptVia: plan.promptVia,
1554
+ }).catch((error) => ({ ran: false, reason: String(error?.message ?? error) }));
1216
1555
  if (body.async === true || searchParams.get("async") === "1") {
1217
1556
  fire();
1218
1557
  emit("task.updated", { taskId: task.id, identifier: task.identifier, status: task.status });
@@ -1636,10 +1975,21 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1636
1975
  // 而该工作区是 Java 工程 ⇒ `ENOENT package.json` ⇒ 退出码 254 ⇒ 结论「失败」。
1637
1976
  // 这是「命令不适用」,不是「测试失败」:不跑这条注定报错的命令,落一个**第三态**(不适用)+
1638
1977
  // 一条明路(去填本卡复核动作)。人配过的命令(`configured` 非空)一律照跑,不替他判断。
1978
+ // 卡 `-249`(R179):**先判「这条命令能不能跑」再跑**。占位符没有替换时(`... <diff文件>`),
1979
+ // shell 会把它解析成重定向 ⇒ 语法错误 ⇒ 退出码 2,结论被写成「失败(退出码 2)」——
1980
+ // 把「配置写成了模板」谎报成「复核没过」。与 FR-94 同构:判「不适用」,不跑。
1981
+ const unrunnable = detectUnrunnableVerify(command);
1639
1982
  const probe = configured ? { applicable: true, reason: null } : await probeVerifyApplicability({ command, cwd });
1640
- const skipReason = probe.applicable ? null : probe.reason;
1983
+ const skipReason = unrunnable ? unrunnable.reason : (probe.applicable ? null : probe.reason);
1641
1984
  const result = skipReason
1642
- ? { exitCode: null, timedOut: false, durationMs: 0, tail: `未执行:${skipReason}。\n请在任务「编辑 → 复核动作」(或项目设置 envConfig.verifyCommand)里填本项目的复核命令后重跑,例如 Java 工程填 \`mvn -q test\`。` }
1985
+ ? {
1986
+ exitCode: null, timedOut: false, durationMs: 0,
1987
+ tail: `未执行:${skipReason}。\n${
1988
+ unrunnable
1989
+ ? `请把占位符换成**真实文件路径**后重跑。注意:自动复核的工作目录 = 本项目的 workspacePath(${cwd}),相对路径要相对它写。`
1990
+ : "请在任务「编辑 → 复核动作」(或项目设置 envConfig.verifyCommand)里填本项目的复核命令后重跑,例如 Java 工程填 `mvn -q test`。"
1991
+ }`,
1992
+ }
1643
1993
  : await runVerifyCommand({ command, cwd });
1644
1994
  // FR-90 强化(真机反馈 2026-10-22:「执行结果只返回一个结果,应该在自动复核证据内自动填入
1645
1995
  // 复核总结证据及结论」):除机器头外,再把**总结 / 失败点**一并落成证据,并回传前端供自动填入。