taskboard-workbench 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +271 -0
  2. package/README.md +89 -0
  3. package/package.json +18 -5
  4. package/scripts/tb-flow.mjs +86 -0
  5. package/skills/taskboard-flow/SKILL.md +89 -0
  6. package/skills/taskboard-flow/references/errors.md +61 -0
  7. package/skills/taskboard-flow/references/injection.md +70 -0
  8. package/skills/taskboard-flow/references/steps/S0.md +31 -0
  9. package/skills/taskboard-flow/references/steps/S1.md +28 -0
  10. package/skills/taskboard-flow/references/steps/S2.md +31 -0
  11. package/skills/taskboard-flow/references/steps/S3.md +22 -0
  12. package/skills/taskboard-flow/references/steps/S4.md +25 -0
  13. package/skills/taskboard-flow/references/steps/S5.md +36 -0
  14. package/skills/taskboard-flow/references/steps/S6.md +30 -0
  15. package/skills/taskboard-flow/references/steps/S7.md +23 -0
  16. package/spec/norms/acceptance.md +36 -0
  17. package/spec/norms/card-update.md +39 -0
  18. package/spec/norms/doc-editing.md +30 -0
  19. package/spec/norms/flow.md +45 -0
  20. package/spec/norms/manifest.json +41 -0
  21. package/spec/norms/project-defaults.md +33 -0
  22. package/src/core/acceptance.mjs +62 -0
  23. package/src/core/contract.mjs +287 -0
  24. package/src/core/errors.mjs +3 -0
  25. package/src/core/evidence.mjs +86 -0
  26. package/src/core/intake.mjs +87 -24
  27. package/src/core/requirements.mjs +31 -1
  28. package/src/core/store.mjs +345 -6
  29. package/src/core/ticket-stage.mjs +150 -0
  30. package/src/mcp/flow-block.mjs +173 -0
  31. package/src/mcp/server.mjs +156 -0
  32. package/src/mcp/tools.mjs +764 -0
  33. package/src/server/api.mjs +106 -30
  34. package/src/server/server.mjs +3 -0
  35. package/web/app.js +117 -17
  36. package/web/tokens.css +12 -0
@@ -2,6 +2,7 @@
2
2
  * api.mjs —— 纯路由逻辑(不依赖 node:http)。独立服务与 DSH 宿主插件共用。
3
3
  */
4
4
  import { PRIORITIES, STATUSES } from "../core/domain.mjs";
5
+ import { clampElaborateLimit } from "../core/requirements.mjs";
5
6
  import { EXIT, TbError, invalidField } from "../core/errors.mjs";
6
7
  import { resolveContext } from "../core/binding.mjs";
7
8
  import { scanProjectMaterials, buildMaterialIndex, collectExternalFiles } from "../core/intake.mjs";
@@ -10,6 +11,7 @@ import { buildTeamDirective } from "../host/team-engine.mjs";
10
11
  import { runExecutionLoop, activeEngine } from "../core/loop.mjs";
11
12
  import { assertTeamTemplate, assertQualityGates, planTeamMembers } from "../core/team.mjs";
12
13
  import { assessTaskRef, projectWatchdog } from "../core/watchdog.mjs";
14
+ import { ticketStage } from "../core/ticket-stage.mjs";
13
15
  import { isHumanReviewTask, planHumanReview } from "../core/human-review.mjs";
14
16
  import { deriveNextStep } from "../core/next-step.mjs";
15
17
  /**
@@ -36,6 +38,8 @@ import { DIAGNOSTIC_KINDS, evaluateTaskDiagnostics, projectDiagnostics, summariz
36
38
  import { summarizeNotifyDelivery } from "../core/notify.mjs";
37
39
  import { resolveCliExecutor, executeTaskWithCli, buildTaskPrompt, cliArgsFor, claimForCliExecution, DEFAULT_TIMEOUT_MS } from "../core/executor.mjs";
38
40
  import { DEFAULT_FAILURE_LIMIT } from "../core/store.mjs";
41
+ // 卡 `-177`(2026-10-29 · 口径 X):acceptance 缺省口径与 MCP **共用同一份**,不在本文件另写判断。
42
+ import { markAcceptance, acceptanceFlag } from "../core/acceptance.mjs";
39
43
 
40
44
  export const API_SCHEMA_VERSION = 2;
41
45
 
@@ -287,32 +291,26 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
287
291
  if (body.dryRun) {
288
292
  return { status: 200, payload: { project: project.id, root: combined.root, scanned: combined.count, truncated: combined.truncated, files: combined.files.map((f) => ({ relPath: f.relPath, bytes: f.bytes, readable: f.readable, external: !!f.external })), dryRun: true } };
289
293
  }
290
- const mode = body.mode ?? "both";
291
- let doc = null;
292
- if (mode !== "items") {
293
- const ensured = store.ensureRequirementDoc(project.id, { body: "" });
294
- doc = store.updateRequirementDoc(ensured.id, { expectedVersion: ensured.version, body: built.index });
295
- }
296
- let created = [];
297
- if (mode === "items" || mode === "both") {
298
- const existing = new Set(store.listRequirementItems({ projectId: project.id }).map((i) => i.title));
299
- for (const d of built.docs) {
300
- if (existing.has(d.title)) continue;
301
- const item = store.createRequirementItem({
302
- projectId: project.id, title: d.title, docId: doc?.id,
303
- description: `来源:\`${d.relPath}\`\n\n${d.content.slice(0, 2000)}`,
304
- source: "intake", status: body.status ?? "draft",
305
- });
306
- existing.add(d.title);
307
- created.push({ identifier: item.identifier, title: item.title });
294
+ // FR-57(2026-10-29 修订 · A 方案):**引入只建资料索引,不产生需求条目**。
295
+ // 条目只由三条正路产生:人工新建 / elaborate 候选确认 / MCP requirement_upsert。
296
+ // 旧 `items` / `both` 一律**显式拒绝**(不静默降级成 doc-only)——「那条路根本不存在」要在契约层成立,
297
+ // 而不是「前端不点它就没事」。未知 mode 同样收紧为用法错误(仓内无调用方传未知值,见
298
+ // 进度/2026-10-29-intake口径A-FR条款修订草案.md §8.3)。
299
+ const mode = body.mode ?? "doc";
300
+ if (mode !== "doc") {
301
+ if (mode === "items" || mode === "both") {
302
+ throw new TbError("INTAKE_ITEMS_DISABLED",
303
+ "资料引入只生成索引、不产生需求条目;条目请走人工新建 / elaborate 候选确认 / MCP requirement_upsert。历史 source=intake 条目仍可查询、筛选、关闭、删除。");
308
304
  }
305
+ throw new TbError("USAGE_ERROR", `未知 mode:${mode}(intake 仅支持 "doc")`);
309
306
  }
307
+ const ensured = store.ensureRequirementDoc(project.id, { body: "" });
308
+ const doc = store.updateRequirementDoc(ensured.id, { expectedVersion: ensured.version, body: built.index });
310
309
  return {
311
310
  status: 201,
312
311
  payload: {
313
312
  project: project.id, root: combined.root, scanned: combined.count, truncated: combined.truncated, mode,
314
- doc: doc ? { id: doc.id, version: doc.version, bytes: built.index.length } : null,
315
- itemsCreated: created.length, items: created,
313
+ doc: { id: doc.id, version: doc.version, bytes: built.index.length },
316
314
  },
317
315
  };
318
316
  }
@@ -590,6 +588,8 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
590
588
  // 中间任何失败都留一张无归因卡(2026-10-28 修 69 张,其中 56 张来源已不可考)。
591
589
  requirementId: body.requirementId ?? body.requirement,
592
590
  unattributedReason: body.unattributedReason,
591
+ // P1.5:契约校验在**内核**(store)里做,门面只负责把调用方的契约原样带下去。
592
+ contract: body.contract,
593
593
  });
594
594
  // 未归因时必须**可见**:返回体带 `attribution.warning`(CLI 侧走 stderr,Web 侧画黄条)。
595
595
  // 不写成错误是因为严格拒绝要等 P3(见 store.mjs 的 strictAttribution 注释)。
@@ -626,11 +626,23 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
626
626
  // FR-90:详情里直接带上「评审证据包」(自动复核结论 + 最近一条进展评论),
627
627
  // 评审人打开抽屉即可看到机器结论,而不是只看到两个按钮。
628
628
  const comments = store.listComments(task.id);
629
- return { status: 200, payload: { task, comments, reviewEvidence: buildReviewEvidence({ comments }) } };
629
+ // FR-108(卡 `-198`):详情带**阶段推导单一口径**(`ticketStage`,0-A1 的纯函数)。
630
+ // 只读附加字段:不改任何既有字段语义,也不写库。
631
+ // · `decision` 先给 null —— `decision_log` 表属 0-C(FR-109),建表后在这里读行传进来即可;
632
+ // · `diagnostics` 传空数组 —— 详情 GET 不该跑诊断规则(那是 `/diagnostics` 的活),
633
+ // 更不能因为一次读页面就 persist 出诊断行。
634
+ const evidence = typeof store.latestTaskEvidence === "function" ? store.latestTaskEvidence(task.identifier) : null;
635
+ let sessionState = null;
636
+ try { sessionState = store.taskSessionState(task); } catch { sessionState = null; }
637
+ let currentRun = null;
638
+ try { currentRun = typeof store.getCurrentRun === "function" ? store.getCurrentRun(task) : null; } catch { currentRun = null; }
639
+ const stage = ticketStage(task, { evidence, decision: null, comments, sessionState, currentRun, diagnostics: [] });
640
+ return { status: 200, payload: { task, comments, reviewEvidence: buildReviewEvidence({ comments }), ticketStage: stage } };
630
641
  }
631
642
  if (method === "PATCH") {
632
643
  const task = store.updateTask(ref, {
633
644
  expectedVersion: body.version ?? body.expectedVersion,
645
+ contract: body.contract,
634
646
  title: body.title,
635
647
  description: body.description,
636
648
  acceptance: body.acceptance,
@@ -699,23 +711,56 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
699
711
  const ref = decodeURIComponent(reqElaborateRoute[1]);
700
712
  const doc = store.getRequirementDocById(ref) ?? store.getRequirementDoc(ref);
701
713
  if (!doc) throw new TbError("REQUIREMENT_DOC_NOT_FOUND", `需求文档不存在:${ref}`, { ref });
714
+ // ── 条目化契约(卡 `-169` P4② · 2026-10-29 口径变更) ───────────────────────
715
+ // 旧口径(已废):`auto` 在 AI 不可用时**静默跑规则并落库**,只加一个 `degraded:true` 标注。
716
+ // 真机后果:一份「资料索引」文档一次落 100 条 pending 候选,其中 0 条真需求。
717
+ // 新口径:
718
+ // · `mode:"auto"` ≈ **只用 AI**;AI 不可用/失败 ⇒ **拒绝**(`AI_UNAVAILABLE`,**零落库**);
719
+ // · 要规则降级必须**显式** `fallback:"rule"`(旧行为整体退到这条分支,语义不变);
720
+ // · `mode:"rule"` 支持 `dryRun:true` ⇒ 只回预览、零落库(规则模式不再「一点就写」);
721
+ // · `limit` 从 body 透传,默认 20、硬顶 200(旧默认 100 且 body 不生效)。
702
722
  const mode = body.mode ?? "auto";
703
- const runRule = () => ({ ...store.elaborateRequirementDoc(doc.id), mode: "rule" });
723
+ if (mode !== "auto" && mode !== "ai" && mode !== "rule") {
724
+ throw new TbError("USAGE_ERROR", `elaborate mode 必须是 auto/ai/rule,收到:${mode}`);
725
+ }
726
+ const fallback = body.fallback;
727
+ if (fallback !== undefined && fallback !== "rule") {
728
+ throw new TbError("USAGE_ERROR", `elaborate fallback 只能是 rule(显式规则降级),收到:${fallback}`);
729
+ }
730
+ const dryRun = body.dryRun === true;
731
+ if (dryRun && mode !== "rule") {
732
+ throw new TbError("USAGE_ERROR", `dryRun 仅适用于 mode:"rule"(AI 产出量由模型决定,没有"预演"意义),收到 mode:${mode}`);
733
+ }
734
+ const limit = clampElaborateLimit(body.limit);
735
+ const runRule = () => ({ ...store.elaborateRequirementDoc(doc.id, { limit, dryRun }), mode: "rule" });
704
736
  const runAi = async () => {
705
- if (typeof aiElaborator !== "function") throw new TbError("AI_UNAVAILABLE", "AI 条目化不可用(当前环境未提供 LLM 直连)");
706
- const candidates = await aiElaborator(doc);
737
+ if (typeof aiElaborator !== "function") {
738
+ throw new TbError("AI_UNAVAILABLE", `AI 条目化不可用(当前环境未提供 LLM 直连):改传 mode:"rule" 或 {mode:"auto",fallback:"rule"} 走规则拆解;规则模式 limit 默认 20 条`);
739
+ }
740
+ let candidates;
741
+ try {
742
+ candidates = await aiElaborator(doc);
743
+ } catch (error) {
744
+ // AI 自己的失败也统一成可判定的错误码,不再被"降级"吞掉(除非人显式要 fallback)
745
+ if (error instanceof TbError) throw error;
746
+ // 上游已带机器可读 code(如 `AI_OUTPUT_INVALID`)时**保留它** —— 排障要能区分
747
+ // 「没有 AI」与「AI 回了没法解析的东西」;压成同一个码等于丢掉线索。
748
+ const code = typeof error?.code === "string" && error.code ? error.code : "AI_UNAVAILABLE";
749
+ throw new TbError(code, `AI 条目化失败:${error?.message ?? error}(本次未落库)`);
750
+ }
707
751
  return { ...store.addRequirementCandidates(doc.id, candidates, { source: "elaborated-ai" }), mode: "ai" };
708
752
  };
709
- if (mode === "rule") return { status: 201, payload: runRule() };
753
+ if (mode === "rule") return { status: dryRun ? 200 : 201, payload: runRule() };
710
754
  if (mode === "ai") return { status: 201, payload: await runAi() };
711
- if (mode !== "auto") throw new TbError("USAGE_ERROR", `elaborate mode 必须是 auto/ai/rule,收到:${mode}`);
755
+ // mode === "auto"
756
+ if (fallback !== "rule") return { status: 201, payload: await runAi() };
757
+ // 显式 fallback:"rule" ⇒ 保留旧行为:先试 AI,失败则规则降级并标注 degraded
712
758
  if (typeof aiElaborator === "function") {
713
759
  try { return { status: 201, payload: await runAi() }; }
714
760
  catch (error) {
715
761
  return { status: 201, payload: { ...runRule(), degraded: true, aiError: error?.code ?? String(error?.message ?? error) } };
716
762
  }
717
763
  }
718
- // B-1:无 AI 时显式标注降级,避免用户误以为用了 AI
719
764
  return { status: 201, payload: { ...runRule(), degraded: true, aiError: "AI_UNAVAILABLE" } };
720
765
  }
721
766
 
@@ -733,8 +778,15 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
733
778
  const item = store.createRequirementItem({
734
779
  projectId: body.projectId, title: body.title, description: body.description,
735
780
  acceptance: body.acceptance, priority: body.priority, docId: body.docId,
781
+ contract: body.contract,
782
+ });
783
+ // 卡 `-177`(口径 X):人工建条目缺省验收 ⇒ **显式缺口**(回包 `acceptanceSet:false` + `governance_audit`)。
784
+ // 此前只回 `{ item }`,「没给验收」与「给了空串」在调用方眼里都是 201 成功 —— 与 MCP 侧同一个沉默。
785
+ const acc = markAcceptance(store, {
786
+ identifier: item.identifier, acceptance: item.acceptance,
787
+ actor: body.actor ?? "human", entry: "http:POST /api/requirements/items",
736
788
  });
737
- return { status: 201, payload: { item } };
789
+ return { status: 201, payload: { item, acceptanceSet: acc.acceptanceSet } };
738
790
  }
739
791
  throw new TbError("USAGE_ERROR", "/api/requirements/items 仅支持 GET 或 POST");
740
792
  }
@@ -751,12 +803,22 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
751
803
  const item = store.updateRequirementItem(ref, {
752
804
  status: body.status, title: body.title, description: body.description,
753
805
  acceptance: body.acceptance, priority: body.priority, docId: body.docId,
806
+ contract: body.contract,
754
807
  });
808
+ // 卡 `-177`:与 MCP 同一边界 —— `acceptanceSet` 永远反映写入后状态;
809
+ // **只有本次 body 真带 `acceptance` 才落审计**(否则 99/129 空验收条目每改一次标题就添一行审计)。
755
810
  // 需求终态(done/closed)落审计:谁在什么时候把哪条需求收口的(自动只给建议,终态由人定)。
756
811
  if (body.status === "done" || body.status === "closed" || item.status === "done" || item.status === "closed") {
757
812
  try { store.recordAudit({ actor: body.actor ?? "human", action: "requirement-status", target: item.identifier, allowed: true, reason: String(body.status ?? item.status), detail: body.reason ?? null }); } catch { /* ignore */ }
758
813
  }
759
- return { status: 200, payload: { item } };
814
+ const acc = body.acceptance !== undefined
815
+ ? markAcceptance(store, {
816
+ identifier: item.identifier, acceptance: item.acceptance,
817
+ actor: body.actor ?? "human", entry: "http:PATCH /api/requirements/items/:ref",
818
+ detail: { changed: Object.keys(body).filter((k) => k !== "actor") },
819
+ })
820
+ : acceptanceFlag(item.acceptance);
821
+ return { status: 200, payload: { item, acceptanceSet: acc.acceptanceSet } };
760
822
  }
761
823
  if (method === "DELETE") {
762
824
  return { status: 200, payload: store.deleteRequirementItem(ref) };
@@ -1477,7 +1539,7 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1477
1539
  if (taskCommentsRoute) {
1478
1540
  const ref = decodeURIComponent(taskCommentsRoute[1]);
1479
1541
  if (method === "GET") { const task = store.requireTaskRef(ref); return { status: 200, payload: { comments: store.listComments(task.id) } }; }
1480
- if (method === "POST") { const task = store.requireTaskRef(ref); const c = store.addComment(task.id, { body: body.body ?? body.comment ?? "" }); emit("task.updated", { taskId: task.id, identifier: task.identifier, status: task.status }); return { status: 201, payload: { comment: c } }; }
1542
+ if (method === "POST") { const task = store.requireTaskRef(ref); const c = store.addComment(task.id, { body: body.body ?? body.comment ?? "", contract: body.contract }); emit("task.updated", { taskId: task.id, identifier: task.identifier, status: task.status }); return { status: 201, payload: { comment: c } }; }
1481
1543
  throw new TbError("USAGE_ERROR", "comments 仅支持 GET 或 POST");
1482
1544
  }
1483
1545
  // FR-17:编辑一条评论(PATCH)。口径见 store.updateComment —— 乐观锁(冲突 → VERSION_CONFLICT/409)
@@ -1741,6 +1803,20 @@ export function createApiRouter({ store, aiElaborator, events } = {}) {
1741
1803
  },
1742
1804
  };
1743
1805
  }
1806
+ // ---------------- 契约快照(P1 · 方案 §6.4 / §8) ----------------
1807
+ // 只读投影:`contractVersion = f(需求文档 digest, spec/norms digest×版本, 门配置)`。
1808
+ // GET 不写库(重算即可);POST …/recheck 才落基线 —— 这样「看一眼契约」永远无副作用。
1809
+ const projectContractRoute = /^\/api\/projects\/([^/]+)\/contract(?:\/(recheck))?$/.exec(pathname);
1810
+ if (projectContractRoute) {
1811
+ const projectId = decodeURIComponent(projectContractRoute[1]);
1812
+ const isRecheck = Boolean(projectContractRoute[2]);
1813
+ if (isRecheck && method !== "POST") throw new TbError("USAGE_ERROR", "contract/recheck 仅支持 POST");
1814
+ if (!isRecheck && method !== "GET") throw new TbError("USAGE_ERROR", "contract 仅支持 GET(重算基线用 POST …/contract/recheck)");
1815
+ const result = isRecheck
1816
+ ? store.refreshProjectContract(projectId, { reason: body.reason ?? null })
1817
+ : store.contractSnapshot(projectId);
1818
+ return { status: 200, payload: result };
1819
+ }
1744
1820
  // ---------------- 项目推进清单(2026-10-28 · 拍板 E1/E3) ----------------
1745
1821
  // E1:**纯投影**,不落表;同状态重复请求字节级一致(不含 now/minutes)。
1746
1822
  const projectAdvanceRoute = /^\/api\/projects\/([^/]+)\/advance$/.exec(pathname);
@@ -177,6 +177,9 @@ export function startServer({ dataDir, port, host = "127.0.0.1", env = process.e
177
177
  server.listen(resolvedPort, host, () => {
178
178
  const address = server.address();
179
179
  console.log(`[tb] listening on http://${host}:${address.port}${basePath}/`);
180
+ // 2026-10-29:把「本实例没有宿主通道」在**启动那一刻**就说清,而不是等用户点投递才撞墙。
181
+ // 独立进程里没有 DSH 的 ctx.sessions ⇒ /api/health 的 host.capabilities 恒为 null。
182
+ console.log("[tb] mode=standalone · 无 DSH 宿主会话通道(投递/建会话/派发团队不可用;需要这些能力请用 DSH 内的 /integrations/taskboard-workbench)");
180
183
  console.log(`[tb] dataDir=${store.dataDir}`);
181
184
  console.log(`[tb] db=${store.dbPath}`);
182
185
  console.log(`[tb] projects=${ensured.projects.length}${ensured.created ? " (auto-created default project)" : ""}`);
package/web/app.js CHANGED
@@ -717,7 +717,11 @@
717
717
  const drawerHeadMain = mk("div");
718
718
  const drawerTitle = mk("h2", null, "");
719
719
  const drawerId = mk("div", "tb-drawer-id", "");
720
- drawerHeadMain.append(drawerId, drawerTitle);
720
+ // FR-108(卡 `-198`):交付阶段徽标 —— 服务端 `ticketStage` 的单一口径,只读展示。
721
+ // `stale` 单独给警示样式:判定过期时**不许**看起来像"可以确认"。
722
+ const drawerStage = mk("span", "tb-stage-badge", "");
723
+ drawerStage.hidden = true;
724
+ drawerHeadMain.append(drawerId, drawerStage, drawerTitle);
721
725
  const drawerClose = mk("button", "ghost", "✕");
722
726
  drawerClose.type = "button";
723
727
  drawerClose.title = "关闭";
@@ -2539,13 +2543,12 @@
2539
2543
  try { await api("POST", "/api/requirements/items", { projectId: state.projectId, title }); showBanner("已新建需求条目", "info"); await renderConfig(); }
2540
2544
  catch (e) { showBanner(`新建失败:${e.message}`, "error"); }
2541
2545
  })));
2542
- req.appendChild(row("AI 拆解(auto)", btn("拆解", async () => {
2546
+ req.appendChild(row("AI 拆解(auto · 不可用即报错)", btn("拆解", async () => {
2543
2547
  try {
2544
2548
  const docs = await api("GET", `/api/requirements/docs?project=${encodeURIComponent(state.projectId)}`);
2545
2549
  const doc = docs.docs[0];
2546
2550
  if (!doc) { showBanner("请先新建/编辑需求文档", "error"); return; }
2547
- const r = await api("POST", `/api/requirements/docs/${encodeURIComponent(doc.id)}/elaborate`, { mode: "auto" });
2548
- showBanner(`拆解:mode=${r.mode}${r.degraded ? "(降级:" + (r.aiError ?? "无AI") + ")" : ""} 候选=${r.candidates ? r.candidates.length : 0}${r.totalFound && r.totalFound > (r.candidates ? r.candidates.length : 0) ? `(共 ${r.totalFound},已截断)` : ""}`, r.degraded ? "error" : "info");
2551
+ await runElaborateAi(doc, { render: false });
2549
2552
  } catch (e) { showBanner(`拆解失败:${e.message}`, "error"); }
2550
2553
  })));
2551
2554
 
@@ -2669,10 +2672,11 @@
2669
2672
  init.appendChild(alignBox);
2670
2673
  void refreshAlign();
2671
2674
 
2672
- init.appendChild(row("引入项目资料(md/doc)", btn("从工作区引入", async () => {
2675
+ init.appendChild(row("引入项目资料(md/doc)", btn("引入资料(仅索引)", async () => {
2673
2676
  try {
2674
- const r = await api("POST", `/api/projects/${encodeURIComponent(state.projectId)}/intake`, {});
2675
- showBanner(`已引入 ${r.scanned} 个文档,生成条目 ${r.itemsCreated};需求文档 v${r.doc?.version ?? "?"}`, "info");
2677
+ // FR-57(2026-10-29 A):引入**只写资料索引**,不产生需求条目 —— 文案必须说清副作用。
2678
+ const r = await api("POST", `/api/projects/${encodeURIComponent(state.projectId)}/intake`, { mode: "doc" });
2679
+ showBanner(`已同步资料索引:扫描 ${r.scanned} 个文档,需求文档 v${r.doc?.version ?? "?"}(${r.doc?.bytes ?? 0} 字节);本次不生成需求条目`, "info");
2676
2680
  await renderConfig();
2677
2681
  } catch (e) { showBanner(`引入失败:${e.message}`, "error"); }
2678
2682
  }, "primary")));
@@ -2902,6 +2906,9 @@
2902
2906
  // ------------------------------------------------------------ 需求视图(文档 + 条目 + 详情)
2903
2907
  const reqState = {
2904
2908
  docId: null, itemId: null, editingDoc: false, candidates: [], filter: "all", q: "", selected: new Set(),
2909
+ // 卡 `-169` P4②(2026-10-29):规则拆解的**预览态**(零落库)。非 null 时文档面板里渲染
2910
+ // 一块「预览 + 确认写入 / 取消」——规则模式不再「一点就写 100 条」。
2911
+ rulePreview: null,
2905
2912
  // 卡 `-160` 收尾(2026-10-27):列表内「完成度结论」的懒取缓存 —— identifier → { at, payload }。
2906
2913
  // `completionInflight` 去重在途请求(同一行不重复打),`focusCompletion` 是「点胶囊 ⇒ 抽屉滚到完成度段」的一次性定位标记。
2907
2914
  completion: new Map(), completionInflight: new Set(), focusCompletion: false,
@@ -3095,6 +3102,76 @@
3095
3102
  await Promise.all(Array.from({ length: Math.min(REQ_COMPLETION_CONCURRENCY, queue.length) }, () => worker()));
3096
3103
  }
3097
3104
 
3105
+ // ── 需求条目化:三个入口统一走这里(卡 `-169` P4② · 2026-10-29 口径变更)────────────
3106
+ // 服务端新契约:`auto` 只用 AI,AI 不可用 ⇒ `AI_UNAVAILABLE` + **零落库**;
3107
+ // 规则降级必须显式 `fallback:"rule"`;规则模式支持 `dryRun` 预览。
3108
+ // 前端因此必须做两件事:① 把 `AI_UNAVAILABLE` 说成人话(不再"假装成功");
3109
+ // ② 规则拆解**先预览再二次确认**(`window.confirm` 在 IAB 里会被自动拒绝 ⇒ 一律用页面内按钮,
3110
+ // 见 06 §E3 —— 用原生弹窗会变成"点了没反应")。
3111
+ const elaborateUrl = (doc) => `/api/requirements/docs/${encodeURIComponent(doc.id)}/elaborate`;
3112
+ const elaborateSummary = (r) => {
3113
+ const n = (r.candidates ?? []).length;
3114
+ const trunc = r.totalFound != null && r.totalFound > n ? `(共 ${r.totalFound},本次写 ${n})` : "";
3115
+ const deg = r.degraded ? `(规则降级:${r.aiError ?? "无AI"})` : "";
3116
+ return `拆解:mode=${r.mode}${deg} 候选=${n}${trunc}`;
3117
+ };
3118
+ async function runElaborateAi(doc, { render = true } = {}) {
3119
+ try {
3120
+ const r = await api("POST", elaborateUrl(doc), { mode: "auto" });
3121
+ reqState.candidates = r.candidates ?? [];
3122
+ showBanner(elaborateSummary(r), "info");
3123
+ if (render) await renderRequirements();
3124
+ } catch (e) {
3125
+ if (e && e.code === "AI_UNAVAILABLE") {
3126
+ showBanner(`AI 拆解不可用:${e.message}。这次没有任何落库;要规则拆解请点「规则拆解(先预览)」。`, "error");
3127
+ } else {
3128
+ showBanner(`拆解失败:${e.message}`, "error");
3129
+ }
3130
+ }
3131
+ }
3132
+ async function startElaborateRulePreview(doc) {
3133
+ try {
3134
+ const pre = await api("POST", elaborateUrl(doc), { mode: "rule", dryRun: true });
3135
+ reqState.rulePreview = { ...pre, docId: doc.id };
3136
+ await renderRequirements();
3137
+ } catch (e) { showBanner(`规则拆解预览失败:${e.message}`, "error"); }
3138
+ }
3139
+ async function commitElaborateRule(doc) {
3140
+ const pv = reqState.rulePreview;
3141
+ try {
3142
+ const r = await api("POST", elaborateUrl(doc), { mode: "rule", limit: pv?.limit });
3143
+ reqState.candidates = r.candidates ?? [];
3144
+ reqState.rulePreview = null;
3145
+ showBanner(elaborateSummary(r), "info");
3146
+ await renderRequirements();
3147
+ } catch (e) { showBanner(`规则拆解失败:${e.message}`, "error"); }
3148
+ }
3149
+ /** 预览块:把「会写多少条 / 规则会把文件清单行也当需求 / 前 10 条长什么样」摆在人眼前。 */
3150
+ function appendElaborateRulePreview(host, doc) {
3151
+ const pv = reqState.rulePreview;
3152
+ if (!pv || pv.docId !== doc.id) return;
3153
+ const box = mk("div", "req-warn");
3154
+ box.appendChild(mk("div", null,
3155
+ `⚠ 规则拆解预览(未落库):共找到 ${pv.totalFound} 条`
3156
+ + (pv.truncated ? `,本次最多写 ${pv.limit} 条(已截断)` : `,将全部写为候选(${pv.limit} 条以内)`)));
3157
+ box.appendChild(mk("div", null,
3158
+ "⚠ 规则拆解会把「文件清单行」也当需求 —— 一份资料索引类文档曾产出 4213 条、其中 0 条是真需求。请先扫一眼下面这些标题。"));
3159
+ if ((pv.preview ?? []).length) {
3160
+ const ol = mk("ol", "req-rule-preview");
3161
+ for (const c of pv.preview) ol.appendChild(mk("li", null, c.title));
3162
+ box.appendChild(ol);
3163
+ } else {
3164
+ box.appendChild(mk("div", null, "(这份文档没解析出任何候选 —— 点「取消」即可)"));
3165
+ }
3166
+ const bar = mk("div", "btn-row");
3167
+ bar.append(
3168
+ btn(`确认写入 ${pv.truncated ? pv.limit + " 条" : "全部候选"}`, () => void commitElaborateRule(doc), "primary"),
3169
+ btn("取消", () => { reqState.rulePreview = null; void renderRequirements(); }),
3170
+ );
3171
+ box.appendChild(bar);
3172
+ host.appendChild(box);
3173
+ }
3174
+
3098
3175
  async function renderRequirements() {
3099
3176
  reqRoot.replaceChildren(mk("p", "hint", "加载需求…"));
3100
3177
  try {
@@ -3136,10 +3213,9 @@
3136
3213
  catch (e) { showBanner(`保存失败:${e.message}`, "error"); }
3137
3214
  }, "primary"),
3138
3215
  btn("取消", () => { reqState.editingDoc = false; void renderRequirements(); }),
3139
- btn("AI 拆解", async () => {
3140
- try { const r = await api("POST", `/api/requirements/docs/${encodeURIComponent(doc.id)}/elaborate`, { mode: "auto" }); reqState.candidates = r.candidates ?? []; showBanner(`拆解:mode=${r.mode}${r.degraded ? "(降级:" + (r.aiError ?? "无AI") + ")" : ""} 候选=${reqState.candidates.length}`, r.degraded ? "error" : "info"); await renderRequirements(); }
3141
- catch (e) { showBanner(`拆解失败:${e.message}`, "error"); }
3142
- }),
3216
+ btn("AI 拆解", () => void runElaborateAi(doc)),
3217
+ // 编辑态下正文未保存:规则拆解基于**已保存**正文,直接切走会让人以为用的是眼前这段 ⇒ 明确拒绝
3218
+ btn("规则拆解(先预览)", () => showBanner("请先「保存」或「取消」编辑,再用规则拆解(它读的是已保存的正文)", "error")),
3143
3219
  );
3144
3220
  docBody.append(ta, bar);
3145
3221
  } else {
@@ -3192,12 +3268,11 @@
3192
3268
  const bar = mk("div", "btn-row");
3193
3269
  bar.append(
3194
3270
  btn("编辑", () => { reqState.editingDoc = true; void renderRequirements(); }, "primary"),
3195
- btn("AI 拆解(auto)", async () => {
3196
- try { const r = await api("POST", `/api/requirements/docs/${encodeURIComponent(doc.id)}/elaborate`, { mode: "auto" }); reqState.candidates = r.candidates ?? []; showBanner(`拆解:mode=${r.mode}${r.degraded ? "(降级:" + (r.aiError ?? "无AI") + ")" : ""} 候选=${reqState.candidates.length}`, r.degraded ? "error" : "info"); await renderRequirements(); }
3197
- catch (e) { showBanner(`拆解失败:${e.message}`, "error"); }
3198
- }),
3271
+ btn("AI 拆解(auto)", () => void runElaborateAi(doc)),
3272
+ btn("规则拆解(先预览)", () => void startElaborateRulePreview(doc)),
3199
3273
  );
3200
3274
  docBody.appendChild(bar);
3275
+ appendElaborateRulePreview(docBody, doc);
3201
3276
  }
3202
3277
 
3203
3278
  // —— 条目面板(新建 + 筛选 + 确认/删除;FR-64/65 便于人工查阅确认)
@@ -3352,7 +3427,7 @@
3352
3427
  li.dataset.status = it.status;
3353
3428
  const statusTxt = reqStatusLabel(it.status);
3354
3429
  li.title = `状态:${statusTxt}`;
3355
- const srcLabel = it.source === "intake" ? "资料索引" : it.source === "elaborated-ai" ? "AI" : it.source === "elaborated-rule" ? "规则" : "手工";
3430
+ const srcLabel = it.source === "intake" ? "资料索引" : it.source === "elaborated-ai" ? "AI" : it.source === "elaborated-rule" ? "规则" : it.source === "mcp" ? "MCP" : "手工";
3356
3431
  const main = mk("div", "req-item-main");
3357
3432
  const cb = mk("input"); cb.type = "checkbox"; cb.checked = reqState.selected.has(it.identifier); cb.title = "选择";
3358
3433
  cb.addEventListener("click", (e) => { e.stopPropagation(); if (cb.checked) reqState.selected.add(it.identifier); else reqState.selected.delete(it.identifier); void renderRequirements(); });
@@ -3506,7 +3581,7 @@
3506
3581
  head.appendChild(mk("p", "req-meta", item.identifier));
3507
3582
  head.appendChild(mk("h2", null, item.title));
3508
3583
  host.appendChild(head);
3509
- const srcLabel = item.source === "intake" ? "资料索引(引入)" : item.source === "elaborated-ai" ? "AI 拆解" : item.source === "elaborated-rule" ? "规则拆解" : "手工";
3584
+ const srcLabel = item.source === "intake" ? "资料索引(引入)" : item.source === "elaborated-ai" ? "AI 拆解" : item.source === "elaborated-rule" ? "规则拆解" : item.source === "mcp" ? "MCP" : "手工";
3510
3585
  const statusTxt = reqStatusLabel(item.status);
3511
3586
  const dl = mk("dl", "req-fields");
3512
3587
  const addF = (k, v, cls) => { dl.appendChild(mk("dt", null, k)); const dd = mk("dd", null, v); if (cls) dd.className = cls; dl.appendChild(dd); };
@@ -3828,11 +3903,35 @@
3828
3903
  showBanner(`派发失败(${identifier}):${error.message}${error.code ? `(${error.code})` : ""}`, "error");
3829
3904
  }
3830
3905
  }
3906
+ /**
3907
+ * FR-108(卡 `-198`):交付阶段徽标的**唯一**渲染点。
3908
+ * 文案只描述"交付物到哪一步",不替代"下一步点哪里"(那是 `next` 的活)。
3909
+ * `stale` 必须显式告警 —— 判定绑定的证据/版本已经变了,人看到的不是被确认的那一版。
3910
+ */
3911
+ function renderStageBadge(stageInfo) {
3912
+ const stage = stageInfo?.stage ?? null;
3913
+ const LABELS = {
3914
+ format_ok: "交付物格式合格(未判)",
3915
+ ready: "交付物已判可收",
3916
+ stale: "证据/版本已变,判定作废",
3917
+ refs_unresolved: "产物引用解不开",
3918
+ };
3919
+ const label = LABELS[stage] ?? null;
3920
+ if (!label) { drawerStage.hidden = true; drawerStage.textContent = ""; drawerStage.removeAttribute("data-stage"); return; }
3921
+ drawerStage.hidden = false;
3922
+ drawerStage.textContent = label;
3923
+ drawerStage.dataset.stage = stage;
3924
+ drawerStage.title = stageInfo?.reason ? `${label}:${stageInfo.reason}` : label;
3925
+ }
3926
+
3831
3927
  async function openTaskDetail(task) {
3832
3928
  const renderSeq = ++detailRenderSeq; // 本代编号(并发渲染时只有最新一代允许落地)
3833
3929
  detailTask = task;
3834
3930
  drawerId.textContent = task.identifier;
3835
3931
  drawerTitle.textContent = task.title;
3932
+ drawerStage.hidden = true;
3933
+ drawerStage.textContent = "";
3934
+ drawerStage.removeAttribute("data-stage");
3836
3935
  drawerActions.replaceChildren(); // 换卡先清空标题栏动作区,避免上一张卡的按钮残留
3837
3936
  drawerBody.replaceChildren(mk("p", "hint", "加载详情…"));
3838
3937
  drawerBackdrop.classList.add("show");
@@ -3850,6 +3949,7 @@
3850
3949
  api("GET", `/api/requirements/items?project=${encodeURIComponent(task.projectId)}`).catch(() => ({ items: [] })),
3851
3950
  ]);
3852
3951
  if (renderSeq !== detailRenderSeq) return; // 取数期间已被更新的一代取代 ⇒ 本次渲染作废
3952
+ renderStageBadge(detail.ticketStage ?? null);
3853
3953
  const t = detail.task ?? task;
3854
3954
  // 需求条目 id → 可读「identifier · title」。真机报障(2026-10-22):概览只打裸 UUID,
3855
3955
  // 用户「不知道这个关联的是哪个需求」—— 归属成了没人看得懂的字段。
package/web/tokens.css CHANGED
@@ -645,6 +645,18 @@ dialog h2 { margin: 0 0 var(--space-3); font-size: 15px; }
645
645
  .tb-drawer-head .tb-drawer-id { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; color: var(--text-tertiary); }
646
646
  .tb-drawer-head h2 { margin: 0; font-size: 15px; line-height: 1.35; }
647
647
  .tb-drawer-head .spacer { flex: 1 1 auto; }
648
+ /* FR-108(卡 `-198`):交付阶段徽标。只显示"交付物到哪一步"(format_ok / ready / stale / refs_unresolved),
649
+ 不替代"下一步点哪里"。`stale` 用警示色:判定绑定的证据或版本已变,人看到的不是被确认的那一版。 */
650
+ .tb-stage-badge {
651
+ display: inline-flex; align-items: center; gap: 4px;
652
+ padding: 1px 8px; border-radius: 999px;
653
+ font-size: 11px; line-height: 1.6; white-space: nowrap;
654
+ border: var(--border-hairline) solid var(--border);
655
+ color: var(--text-secondary); background: transparent;
656
+ }
657
+ .tb-stage-badge[data-stage="ready"] { color: var(--success); border-color: currentColor; }
658
+ .tb-stage-badge[data-stage="stale"],
659
+ .tb-stage-badge[data-stage="refs_unresolved"] { color: var(--danger); border-color: var(--danger); background: var(--danger-soft); font-weight: 600; }
648
660
  /* 2026-10-23(用户真机批注):整卡动作区(原正文底部「操作」区块)上移到标题栏,与「全部收起 / 还原 / ✕」同排。
649
661
  动作多时**只在动作区内部换行**,不挤掉标题、也不撑破标题栏;没有任何动作时整块不占位。 */
650
662
  .tb-drawer-actions { display: flex; flex-wrap: wrap; gap: var(--space-2); justify-content: flex-end; align-items: center; flex: 0 1 auto; max-width: min(72%, 900px); }