taskboard-workbench 0.0.0-stage → 0.2.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 (50) hide show
  1. package/CHANGELOG.md +132 -0
  2. package/LICENSE +21 -0
  3. package/README.md +121 -2
  4. package/cli/tb.mjs +314 -0
  5. package/cordis.patch.yml +5 -0
  6. package/index.js +633 -0
  7. package/lib/client.js +522 -0
  8. package/package.json +83 -4
  9. package/spec//345/233/242/351/230/237agent.md +171 -0
  10. package/src/core/advance.mjs +192 -0
  11. package/src/core/agent-teams.mjs +48 -0
  12. package/src/core/binding.mjs +44 -0
  13. package/src/core/config.mjs +22 -0
  14. package/src/core/debug-dispatch.mjs +94 -0
  15. package/src/core/delivery.mjs +93 -0
  16. package/src/core/deps.mjs +53 -0
  17. package/src/core/diagnostics.mjs +648 -0
  18. package/src/core/domain.mjs +235 -0
  19. package/src/core/empty-state.mjs +240 -0
  20. package/src/core/errors.mjs +139 -0
  21. package/src/core/executor.mjs +645 -0
  22. package/src/core/human-review.mjs +773 -0
  23. package/src/core/intake.mjs +116 -0
  24. package/src/core/kickoff.mjs +147 -0
  25. package/src/core/loop.mjs +498 -0
  26. package/src/core/memory.mjs +193 -0
  27. package/src/core/next-step.mjs +377 -0
  28. package/src/core/notify.mjs +183 -0
  29. package/src/core/owner.mjs +41 -0
  30. package/src/core/requirements.mjs +262 -0
  31. package/src/core/review.mjs +82 -0
  32. package/src/core/session-naming.mjs +64 -0
  33. package/src/core/split-ask.mjs +107 -0
  34. package/src/core/store.mjs +3103 -0
  35. package/src/core/team.mjs +170 -0
  36. package/src/core/verify.mjs +170 -0
  37. package/src/core/watchdog.mjs +144 -0
  38. package/src/host/ai-elaborator.mjs +26 -0
  39. package/src/host/team-engine.mjs +125 -0
  40. package/src/host/tool-surface.mjs +205 -0
  41. package/src/server/api.mjs +1974 -0
  42. package/src/server/events.mjs +32 -0
  43. package/src/server/kickoff.mjs +46 -0
  44. package/src/server/server.mjs +211 -0
  45. package/src/server/verify.mjs +112 -0
  46. package/tools/env-check.mjs +35 -0
  47. package/tools/seed.mjs +67 -0
  48. package/web/app.js +5237 -0
  49. package/web/index.html +15 -0
  50. package/web/tokens.css +1139 -0
@@ -0,0 +1,235 @@
1
+ /**
2
+ * 领域模型:七状态、五优先级、标签、可读编号、父子与版本语义(FR-04/06/08/09/10/18)。
3
+ * 本模块是纯函数层:不触碰文件系统与数据库,可单独测试(核心层不依赖 DSH)。
4
+ */
5
+ import { invalidField, TbError } from "./errors.mjs";
6
+
7
+ /** 七状态(顺序即看板列顺序)。核心层不限制转移,任意互转都允许。 */
8
+ export const STATUSES = Object.freeze([
9
+ "backlog",
10
+ "todo",
11
+ "in_progress",
12
+ "in_review",
13
+ "done",
14
+ "blocked",
15
+ "canceled",
16
+ ]);
17
+
18
+ /** 五优先级;rank 越小越紧急,用于排序(FR-08:紧急在前)。 */
19
+ export const PRIORITIES = Object.freeze(["none", "low", "medium", "high", "urgent"]);
20
+ export const PRIORITY_RANK = Object.freeze({
21
+ urgent: 0,
22
+ high: 1,
23
+ medium: 2,
24
+ low: 3,
25
+ none: 4,
26
+ });
27
+
28
+ /** 默认值 */
29
+ export const DEFAULT_STATUS = "backlog";
30
+ export const DEFAULT_PRIORITY = "none";
31
+
32
+ /** 治理能力位(FR-07):默认不强制;上层可打开 enforcement。 */
33
+ export const GOVERNANCE_DEFAULTS = Object.freeze({
34
+ /** 是否禁止智能体把任务置为 done(默认关闭 = 核心层不拦截任意转移)。 */
35
+ enforce: false,
36
+ /** 打开 enforcement 时同时禁止智能体把 backlog 任务推进到其它状态。 */
37
+ blockAgentClaimFromBacklog: true,
38
+ });
39
+
40
+ export const ACTORS = Object.freeze(["human", "agent"]);
41
+
42
+ export function isStatus(value) {
43
+ return STATUSES.includes(value);
44
+ }
45
+
46
+ export function isPriority(value) {
47
+ return PRIORITIES.includes(value);
48
+ }
49
+
50
+ export function assertStatus(value, field = "status") {
51
+ if (!isStatus(value)) {
52
+ throw new TbError(
53
+ "INVALID_STATUS",
54
+ `${field} 必须是 ${STATUSES.join(" / ")} 之一,收到:${JSON.stringify(value)}`,
55
+ { allowed: STATUSES.slice() },
56
+ );
57
+ }
58
+ return value;
59
+ }
60
+
61
+ export function assertPriority(value, field = "priority") {
62
+ if (!isPriority(value)) {
63
+ throw new TbError(
64
+ "INVALID_PRIORITY",
65
+ `${field} 必须是 ${PRIORITIES.join(" / ")} 之一,收到:${JSON.stringify(value)}`,
66
+ { allowed: PRIORITIES.slice() },
67
+ );
68
+ }
69
+ return value;
70
+ }
71
+
72
+ export function assertActor(value, field = "actor") {
73
+ if (!ACTORS.includes(value)) {
74
+ throw invalidField(field, `${field} 必须是 human 或 agent,收到:${JSON.stringify(value)}`);
75
+ }
76
+ return value;
77
+ }
78
+
79
+ /** 项目 id:小写字母开头,允许小写字母/数字/连字符,2–32 字符;同时作为可读编号前缀。 */
80
+ export const PROJECT_ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
81
+
82
+ export function assertProjectId(value, field = "id") {
83
+ if (typeof value !== "string" || !PROJECT_ID_PATTERN.test(value)) {
84
+ throw new TbError(
85
+ "INVALID_ID",
86
+ `${field} 必须匹配 ${PROJECT_ID_PATTERN}(小写字母开头,仅含小写字母/数字/连字符,2–32 字符),收到:${JSON.stringify(value)}`,
87
+ );
88
+ }
89
+ return value;
90
+ }
91
+
92
+ /** 由项目名派生 id/前缀:中文等非 ASCII 会得到空串,需要调用方显式给 --id。 */
93
+ export function slugify(name) {
94
+ return String(name ?? "")
95
+ .toLowerCase()
96
+ .replace(/[^a-z0-9]+/g, "-")
97
+ .replace(/^-+|-+$/g, "")
98
+ .slice(0, 32);
99
+ }
100
+
101
+ /** 可读编号:`<前缀>-<序号>`,序号项目内单调递增(FR-04)。 */
102
+ export function formatIdentifier(prefix, sequence) {
103
+ if (!Number.isInteger(sequence) || sequence < 1) {
104
+ throw invalidField("sequence", `序号必须是 ≥1 的整数,收到:${JSON.stringify(sequence)}`);
105
+ }
106
+ return `${prefix}-${sequence}`;
107
+ }
108
+
109
+ /** 解析 `demo-12` → { prefix: "demo", sequence: 12 };不匹配返回 null。 */
110
+ export function parseIdentifier(value) {
111
+ const match = /^([a-z][a-z0-9-]*)-(\d+)$/.exec(String(value ?? ""));
112
+ if (!match) return null;
113
+ const sequence = Number(match[2]);
114
+ if (!Number.isSafeInteger(sequence) || sequence < 1) return null;
115
+ return { prefix: match[1], sequence };
116
+ }
117
+
118
+ export const LABEL_MAX_LENGTH = 40;
119
+ export const LABEL_MAX_COUNT = 20;
120
+
121
+ /**
122
+ * 标签规范化:支持 `["a,b"]`、`["a","b"]`、`"a,b"` 三种输入形态;
123
+ * 每个元素再按逗号拆分,去首尾空白、压缩内部空白、去重;拒绝空标签与超长标签(FR-09)。
124
+ */
125
+ export function normalizeLabels(input) {
126
+ const raw = Array.isArray(input) ? input : input === undefined || input === null ? [] : [input];
127
+ const out = [];
128
+ for (const item of raw) {
129
+ for (const piece of String(item ?? "").split(",")) {
130
+ const label = piece.trim().replace(/\s+/g, " ");
131
+ if (label === "") continue;
132
+ if (label.length > LABEL_MAX_LENGTH) {
133
+ throw new TbError("INVALID_LABEL", `标签过长(上限 ${LABEL_MAX_LENGTH}):${label}`);
134
+ }
135
+ if (!out.includes(label)) out.push(label);
136
+ }
137
+ }
138
+ if (out.length > LABEL_MAX_COUNT) {
139
+ throw new TbError("INVALID_LABEL", `标签过多(上限 ${LABEL_MAX_COUNT}):${out.length}`);
140
+ }
141
+ return out;
142
+ }
143
+
144
+ export function assertTitle(value, field = "title") {
145
+ const title = String(value ?? "").trim();
146
+ if (title === "") throw invalidField(field, "title 不能为空(标题必填)");
147
+ if (title.length > 200) throw invalidField(field, `title 过长(上限 200):${title.length}`);
148
+ return title;
149
+ }
150
+
151
+ export function normalizeDescription(value) {
152
+ if (value === undefined || value === null) return "";
153
+ return String(value);
154
+ }
155
+
156
+ /**
157
+ * 父子关系校验(FR-10):单父、同项目、禁止成环。
158
+ * @param {{ id: string, projectId: string, parentId: string|null }} child
159
+ * @param {{ id: string, projectId: string, parentId: string|null }} parent
160
+ */
161
+ export function assertParentLink(child, parent) {
162
+ if (child.id === parent.id) {
163
+ throw new TbError("PARENT_CYCLE", "父子关系不能指向自己(会形成环)", { taskId: child.id });
164
+ }
165
+ if (child.parentId && child.parentId !== parent.id) {
166
+ throw new TbError(
167
+ "PARENT_ALREADY_SET",
168
+ `任务已存在父任务(${child.parentId});如需更换请先清除父任务(FR-10:最多一个父任务)`,
169
+ { taskId: child.id, currentParentId: child.parentId, requestedParentId: parent.id },
170
+ );
171
+ }
172
+ if (child.projectId !== parent.projectId) {
173
+ throw new TbError(
174
+ "PARENT_CROSS_PROJECT",
175
+ `父子关系不能跨项目(子任务项目 ${child.projectId},父任务项目 ${parent.projectId})`,
176
+ { childProjectId: child.projectId, parentProjectId: parent.projectId },
177
+ );
178
+ }
179
+ }
180
+
181
+ /**
182
+ * 成环检测:沿 parent 链向上走,若遇到 childId 即成环。
183
+ * @param {string} childId
184
+ * @param {string} parentId
185
+ * @param {(id: string) => ({ id: string, parentId: string|null } | undefined)} getTask
186
+ */
187
+ export function assertNoCycle(childId, parentId, getTask) {
188
+ const seen = new Set([childId]);
189
+ let cursor = parentId;
190
+ while (cursor) {
191
+ if (seen.has(cursor)) {
192
+ throw new TbError("PARENT_CYCLE", "父子关系会形成环,已拒绝", {
193
+ childId,
194
+ parentId,
195
+ at: cursor,
196
+ });
197
+ }
198
+ seen.add(cursor);
199
+ const node = getTask(cursor);
200
+ if (!node) break;
201
+ cursor = node.parentId ?? null;
202
+ }
203
+ }
204
+
205
+ /**
206
+ * 治理校验(FR-07):能力位默认关闭(核心层不拦截);打开后按约定拒绝智能体的越权动作。
207
+ * @param {{ actor: string, from: string|null, to: string }} change
208
+ * @param {{ enforce: boolean, blockAgentClaimFromBacklog: boolean }} policy
209
+ */
210
+ export function checkGovernance(change, policy = GOVERNANCE_DEFAULTS) {
211
+ if (!policy?.enforce) return null;
212
+ const actor = change.actor ?? "human";
213
+ if (actor !== "agent") return null;
214
+ if (change.to === "done") {
215
+ return new TbError("AGENT_CANNOT_SET_DONE", "智能体不能把任务置为 done(FR-07:完成必须由人确认)", {
216
+ from: change.from,
217
+ to: change.to,
218
+ });
219
+ }
220
+ if (policy.blockAgentClaimFromBacklog && change.from === "backlog" && change.to !== "backlog") {
221
+ return new TbError(
222
+ "AGENT_CANNOT_CLAIM_BACKLOG",
223
+ "智能体不能推进 backlog 任务(FR-07:未授权不得开工)",
224
+ { from: change.from, to: change.to },
225
+ );
226
+ }
227
+ return null;
228
+ }
229
+
230
+ /** 按优先级排序(紧急在前),同优先级按 created_at 升序 → 稳定可预期(FR-08/FR-15)。 */
231
+ export function compareByPriority(a, b) {
232
+ const rankDiff = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
233
+ if (rankDiff !== 0) return rankDiff;
234
+ return String(a.createdAt ?? "").localeCompare(String(b.createdAt ?? ""));
235
+ }
@@ -0,0 +1,240 @@
1
+ /**
2
+ * FR-93 · 看板空态引导(缺陷 F-05:次状态议题空态无引导)。
3
+ *
4
+ * ## 要解决的问题(缺陷 F-05)
5
+ *
6
+ * 缺陷原文(`docs/测试/缺陷清单-2026-10-10.md` F-05,讲的是旧 `web/src/App.tsx` 实现):
7
+ * 单项目视图下若议题全部处于次要状态(`backlog`/`done`/`canceled`),主看板三列均显示
8
+ * 「暂无议题」,**空状态不引导**到「其他任务」面板,使用者会误判"这个项目没有议题"。
9
+ *
10
+ * ## 本仓的对应形态(口径对齐,2026-10-22)
11
+ *
12
+ * 本仓已把 7 个状态全部提升为主列(`domain.mjs` 的 `STATUSES` 含 `backlog`),没有「其他任务」
13
+ * 面板,因此 F-05 的**同一类**可发现性缺口换了个位置出现:
14
+ *
15
+ * 1. **折叠隐藏**(FR-88):全部卡片被打 `archived` 标签 ⇒ `visible` 为空 ⇒ 七列全是「暂无任务」,
16
+ * 而折叠计数只在工具栏(`已折叠 N`)与摘要行出现,**列内零解释**。
17
+ * 2. **筛选命中不到**(FR-63 优先级/标签筛选):筛选后为空 ⇒ 同样是七列「暂无任务」,
18
+ * 用户分不清是"真没有任务"还是"被筛掉了"。
19
+ *
20
+ * 两种情形的共同点是:**数据在库里,只是没显示,而界面不解释为什么**。
21
+ * 本模块只负责**如实说明**"还有多少张卡不在默认视图里、为什么",不代替人做判断,
22
+ * 也**不自动改筛选条件**(避免"自动帮你清掉筛选"这种惊喜行为)。
23
+ *
24
+ * ## 设计约束(红线)
25
+ *
26
+ * - **纯函数、无 I/O**:不读库、不写库、不发请求,便于单测穷举。
27
+ * - **不臆断**:只有真的存在被隐藏的卡片时才给引导;真的一个任务都没有时,如实说"暂无任务",
28
+ * **绝不编造数量**(与 `verify.mjs`「认不出就如实写,绝不编造」同一条纪律)。
29
+ * - **区分两类隐藏原因**:`archived`(折叠,需用户主动开)与筛选(需用户主动清),
30
+ * 引导文案与出口分别指向对应的既有控件,不新增状态、不新增面板。
31
+ */
32
+
33
+ /** 折叠标签(与 `web/app.js` 的 `ARCHIVE_LABEL` 保持一致)。 */
34
+ export const ARCHIVE_LABEL = "archived";
35
+
36
+ /**
37
+ * 判定一张卡是否处于折叠(软归档)状态。
38
+ *
39
+ * @param {{labels?: string[]}} task
40
+ * @returns {boolean}
41
+ */
42
+ export function isArchived(task) {
43
+ return Array.isArray(task?.labels) && task.labels.includes(ARCHIVE_LABEL);
44
+ }
45
+
46
+ /**
47
+ * 当前是否处于"筛选生效"状态。
48
+ *
49
+ * 口径与 `web/app.js` 的 `state` 对齐:`priority` / `label` / `sessionScope` / `keyword` 任一非空即为筛选中。
50
+ * `label` 需排除折叠开关载体 `archived`(它由 `showArchived` 表达,不算筛选条件);
51
+ * `sessionScope`(FR-26 会话归属:`linked` / `unlinked`)空串=「全部」,不算筛选。
52
+ * `keyword`(FR-14 搜索)空串 / 纯空白=没在搜索,不算筛选。
53
+ *
54
+ * @param {{priority?: string, label?: string, sessionScope?: string, keyword?: string}} filters
55
+ * @returns {boolean}
56
+ */
57
+ export function hasActiveFilter(filters) {
58
+ const priority = typeof filters?.priority === "string" ? filters.priority.trim() : "";
59
+ const label = typeof filters?.label === "string" ? filters.label.trim() : "";
60
+ const sessionScope = typeof filters?.sessionScope === "string" ? filters.sessionScope.trim() : "";
61
+ const keyword = typeof filters?.keyword === "string" ? filters.keyword.trim() : "";
62
+ return priority !== "" || (label !== "" && label !== ARCHIVE_LABEL) || sessionScope !== "" || keyword !== "";
63
+ }
64
+
65
+ /** FR-26:会话归属筛选值的可读文案(与 `web/app.js` 的下拉标签逐字一致)。 */
66
+ export const SESSION_SCOPE_LABELS = Object.freeze({ linked: "已关联会话", unlinked: "未关联会话" });
67
+
68
+ /**
69
+ * FR-28:会话归属的第三/四档「仅本会话」——取值为 `session:<会话标识>`。
70
+ * 与 FR-26 的 `linked` / `unlinked` 并列(语义不同:那两档问"有没有关联会话",
71
+ * 本档问"关联的是不是**这一个**会话")。
72
+ */
73
+ export const SESSION_SCOPE_CURRENT_PREFIX = "session:";
74
+
75
+ /** 会话标识在文案里只显示短前缀(与卡面 `session-chip` 同口径,真值不丢:完整标识在 title / 配置页可读)。 */
76
+ export const SESSION_SCOPE_ID_SHORT = 14;
77
+
78
+ /**
79
+ * FR-28:把会话归属档位值格式化成可读文案。
80
+ * `linked` / `unlinked` → 各自标签;`session:<id>` → `仅本会话(<短标识>…)`;空 → 空串。
81
+ *
82
+ * @param {string} scope
83
+ * @returns {string}
84
+ */
85
+ export function formatSessionScope(scope) {
86
+ const value = typeof scope === "string" ? scope.trim() : "";
87
+ if (value === "") return "";
88
+ if (value.startsWith(SESSION_SCOPE_CURRENT_PREFIX)) {
89
+ const id = value.slice(SESSION_SCOPE_CURRENT_PREFIX.length).trim();
90
+ if (id === "") return "仅本会话";
91
+ const short = id.length > SESSION_SCOPE_ID_SHORT ? `${id.slice(0, SESSION_SCOPE_ID_SHORT)}…` : id;
92
+ return `仅本会话(${short})`;
93
+ }
94
+ return SESSION_SCOPE_LABELS[value] ?? value;
95
+ }
96
+
97
+ /**
98
+ * 推导看板空态的引导口径。
99
+ *
100
+ * **只在 `visibleTasks` 为空时被使用**(即整个看板空)。此时把 `allTasks` 按"为什么不显示"
101
+ * 分桶,给出可核验的引导文案。
102
+ *
103
+ * @param {object} params
104
+ * @param {Array<{status?: string, labels?: string[]}>} params.allTasks 当前项目 / 当前筛选口径下的全部卡(服务端已按筛选返回)
105
+ * @param {Array<object>} [params.visibleTasks] 折叠过滤后的实际入列卡
106
+ * @param {{priority?: string, label?: string, sessionScope?: string, keyword?: string}} [params.filters] 当前生效的筛选/搜索条件
107
+ * @param {boolean} [params.showArchived] 是否打开了「显示已折叠」
108
+ * @returns {{
109
+ * empty: boolean,
110
+ * kind: "no-tasks" | "filtered-out" | "archived" | "filtered-and-archived",
111
+ * hiddenTotal: number,
112
+ * archivedCount: number,
113
+ * filteredCount: number,
114
+ * message: string,
115
+ * hints: string[],
116
+ * reasons: Array<{ reason: "archived" | "filtered", count: number, hint: string }>,
117
+ * }}
118
+ */
119
+ export function deriveEmptyState({ allTasks, visibleTasks, filters = {}, showArchived = false } = {}) {
120
+ const all = Array.isArray(allTasks) ? allTasks : [];
121
+ const visible = Array.isArray(visibleTasks) ? visibleTasks : all;
122
+ const filtering = hasActiveFilter(filters);
123
+ // FR-14:搜索关键词(已 trim;空串=没在搜索)。**原样**用于文案回显,不在此大小写化。
124
+ const keyword = typeof filters?.keyword === "string" ? filters.keyword.trim() : "";
125
+
126
+ // 看板整体是否真的空 —— 只有"一列都没卡"才算空态。
127
+ const empty = visible.length === 0;
128
+
129
+ // 分桶:折叠隐藏 vs 其它原因(筛选命中不到 / 状态不在可见口径内)。
130
+ // 注意 showArchived=true 时折叠卡本来就会入列,此时不该再把它算成"被隐藏"。
131
+ const archivedHidden = showArchived ? [] : all.filter(isArchived);
132
+ const archivedIds = new Set(archivedHidden.map((task) => task?.identifier ?? task?.id));
133
+ const filteredHidden = all.filter((task) => {
134
+ if (archivedIds.has(task?.identifier ?? task?.id)) return false;
135
+ return !visible.includes(task);
136
+ });
137
+
138
+ const archivedCount = archivedHidden.length;
139
+ const filteredCount = filteredHidden.length;
140
+ const hiddenTotal = archivedCount + filteredCount;
141
+
142
+ if (!empty) {
143
+ return {
144
+ empty: false,
145
+ kind: "no-tasks",
146
+ hiddenTotal: 0,
147
+ archivedCount: 0,
148
+ filteredCount: 0,
149
+ message: "",
150
+ hints: [],
151
+ reasons: [],
152
+ };
153
+ }
154
+
155
+ // 真的一个任务都没有:如实说"暂无任务",**不编造数量、不给无的放矢的引导**。
156
+ if (all.length === 0) {
157
+ // FR-14 / FR-16:搜索无命中必须给出**明确指出关键词**的空态,不能与「本项目暂无任务」混为一谈
158
+ // (前者是"词没对上",后者是"真的没卡" —— 引导动作也不同:换词 vs 新建任务)。
159
+ if (keyword !== "") {
160
+ return {
161
+ empty: true,
162
+ kind: "no-tasks",
163
+ hiddenTotal: 0,
164
+ archivedCount: 0,
165
+ filteredCount: 0,
166
+ message: `没有匹配「${keyword}」的任务`,
167
+ hints: ["换个关键词,或清空搜索后重试"],
168
+ reasons: [],
169
+ };
170
+ }
171
+ return {
172
+ empty: true,
173
+ kind: "no-tasks",
174
+ hiddenTotal: 0,
175
+ archivedCount: 0,
176
+ filteredCount: 0,
177
+ message: filtering ? "当前筛选下没有任务" : "本项目暂无任务",
178
+ hints: filtering ? ["清空筛选条件后重试"] : [],
179
+ reasons: [],
180
+ };
181
+ }
182
+
183
+ // 有任务但一列都没卡 —— 这就是 F-05 的场景,必须解释「它们在哪」。
184
+ const reasons = [];
185
+ if (archivedCount > 0) {
186
+ reasons.push({
187
+ reason: "archived",
188
+ count: archivedCount,
189
+ hint: `${archivedCount} 个已折叠(软归档)· 点工具栏「显示已折叠(${archivedCount})」展开;数据与历史都在,可随时取消`,
190
+ });
191
+ }
192
+ if (filteredCount > 0) {
193
+ const parts = [];
194
+ if (typeof filters?.priority === "string" && filters.priority.trim()) parts.push(`优先级=${filters.priority.trim()}`);
195
+ if (typeof filters?.label === "string" && filters.label.trim() && filters.label.trim() !== ARCHIVE_LABEL) {
196
+ parts.push(`标签=${filters.label.trim()}`);
197
+ }
198
+ if (typeof filters?.sessionScope === "string" && filters.sessionScope.trim()) {
199
+ parts.push(`会话归属=${formatSessionScope(filters.sessionScope)}`);
200
+ }
201
+ // FR-14:搜索关键词也如实回显(否则用户只看到"筛掉了 N 个"却不知道是哪一个条件所致)
202
+ if (keyword !== "") parts.push(`关键词=${keyword}`);
203
+ const cond = parts.length > 0 ? parts.join(" · ") : "当前筛选";
204
+ reasons.push({
205
+ reason: "filtered",
206
+ count: filteredCount,
207
+ hint: `${filteredCount} 个不在当前筛选/口径内(${cond})· 清空筛选条件即可看到`,
208
+ });
209
+ }
210
+
211
+ const kind =
212
+ archivedCount > 0 && filteredCount > 0
213
+ ? "filtered-and-archived"
214
+ : archivedCount > 0
215
+ ? "archived"
216
+ : "filtered-out";
217
+
218
+ return {
219
+ empty: true,
220
+ kind,
221
+ hiddenTotal,
222
+ archivedCount,
223
+ filteredCount,
224
+ message: `看板为空:本项目还有 ${hiddenTotal} 个任务未显示在此`,
225
+ hints: reasons.map((item) => item.hint),
226
+ reasons,
227
+ };
228
+ }
229
+
230
+ /**
231
+ * 把空态口径渲染成**纯文本**一行(用于摘要行 / 无障碍标签 / 单测断言)。
232
+ *
233
+ * @param {ReturnType<typeof deriveEmptyState>} state
234
+ * @returns {string}
235
+ */
236
+ export function formatEmptyState(state) {
237
+ if (!state?.empty) return "";
238
+ if (state.hiddenTotal === 0) return state.message;
239
+ return `${state.message}:${state.hints.join(";")}`;
240
+ }
@@ -0,0 +1,139 @@
1
+ /**
2
+ * 统一错误与退出码(FR-21 / FR-33 契约)。
3
+ *
4
+ * 退出码:0 成功 · 2 输入错误 · 3 服务或存储不可用 · 4 数据或响应错误 · 5 冲突
5
+ * 所有错误都带机器可读的 `code`,CLI 以 JSON 形式写到 stderr。
6
+ */
7
+
8
+ export const EXIT = Object.freeze({
9
+ OK: 0,
10
+ USAGE: 2,
11
+ SERVICE: 3,
12
+ DATA: 4,
13
+ CONFLICT: 5,
14
+ });
15
+
16
+ /** 类别 → 退出码的权威映射(新增错误码时必须在此登记类别)。 */
17
+ export const ERROR_CATEGORY = Object.freeze({
18
+ // 输入/用法
19
+ USAGE_ERROR: EXIT.USAGE,
20
+ MISSING_FIELD: EXIT.USAGE,
21
+ INVALID_FIELD: EXIT.USAGE,
22
+ INVALID_ID: EXIT.USAGE,
23
+ INVALID_STATUS: EXIT.USAGE,
24
+ INVALID_PRIORITY: EXIT.USAGE,
25
+ INVALID_LABEL: EXIT.USAGE,
26
+ MISSING_VERSION: EXIT.USAGE,
27
+ UNKNOWN_COMMAND: EXIT.USAGE,
28
+ UNKNOWN_OPTION: EXIT.USAGE,
29
+ // FR-03:删除项目必须先显式确认(缺确认 ⇒ 用法错误,避免误触删掉项目)
30
+ PROJECT_DELETE_UNCONFIRMED: EXIT.USAGE,
31
+
32
+ // 存储不可用
33
+ STORE_UNAVAILABLE: EXIT.SERVICE,
34
+ DB_OPEN_FAILED: EXIT.SERVICE,
35
+
36
+ // 数据/响应错误
37
+ DATA_ERROR: EXIT.DATA,
38
+ NOT_FOUND: EXIT.DATA,
39
+ PROJECT_NOT_FOUND: EXIT.DATA,
40
+ TASK_NOT_FOUND: EXIT.DATA,
41
+ COMMENT_NOT_FOUND: EXIT.DATA,
42
+ // FR-17 红线④:机器证据评论(【自动复核】…)一旦可能被评审引用,编辑即"改写证据"的旁路 ⇒ 拒绝编辑
43
+ COMMENT_NOT_EDITABLE: EXIT.DATA,
44
+ PARENT_NOT_FOUND: EXIT.DATA,
45
+ PARENT_CROSS_PROJECT: EXIT.DATA,
46
+ PARENT_ALREADY_SET: EXIT.DATA,
47
+ PARENT_CYCLE: EXIT.DATA,
48
+ REQUIREMENT_NOT_FOUND: EXIT.DATA,
49
+ REQUIREMENT_DOC_NOT_FOUND: EXIT.DATA,
50
+ CANDIDATE_NOT_FOUND: EXIT.DATA,
51
+ DEPENDENCY_SELF: EXIT.USAGE,
52
+ DEPENDENCY_CROSS_PROJECT: EXIT.DATA,
53
+ DEPENDENCY_CYCLE: EXIT.DATA,
54
+ SPLIT_EMPTY: EXIT.DATA,
55
+ AI_OUTPUT_INVALID: EXIT.DATA,
56
+ AI_UNAVAILABLE: EXIT.SERVICE,
57
+ EXECUTION_NOT_AUTHORIZED: EXIT.DATA,
58
+ EXECUTION_NOT_ATTRIBUTED: EXIT.DATA,
59
+ EXECUTION_ALREADY_RUNNING: EXIT.CONFLICT,
60
+ EXECUTION_CIRCUIT_OPEN: EXIT.CONFLICT,
61
+ TASK_LOCKED: EXIT.CONFLICT,
62
+ // 人工校验任务(FR-85b):人在环升级门的拒绝类错误
63
+ HUMAN_REVIEW_NOT_CLAIMABLE: EXIT.CONFLICT,
64
+ HUMAN_REVIEW_NOT_EXECUTABLE: EXIT.CONFLICT,
65
+ // 评审门(FR-83 补口 · 卡 `-162`):待验收卡未评审通过就想收口 ⇒ 冲突类(可重试的同类语义:
66
+ // "先评审"是可走通的另一条路),显式 skipReview=true 才是合法逃生口
67
+ REVIEW_NOT_APPROVED: EXIT.CONFLICT,
68
+ // 自动复核(FR-90):项目没配工作区目录,没地方跑验证命令
69
+ PROJECT_WORKSPACE_MISSING: EXIT.USAGE,
70
+ HUMAN_REVIEW_ALREADY_EXISTS: EXIT.CONFLICT,
71
+ HUMAN_REVIEW_ALREADY_CONCLUDED: EXIT.CONFLICT,
72
+ HUMAN_REVIEW_PENDING: EXIT.CONFLICT,
73
+ HUMAN_REVIEW_NOT_CONFIDENT: EXIT.DATA,
74
+ HUMAN_REVIEW_CANNOT_DONE: EXIT.DATA,
75
+ HUMAN_REVIEW_NOT_KIND: EXIT.DATA,
76
+ HUMAN_REVIEW_DRAFT_INVALID: EXIT.DATA,
77
+ GOVERNANCE_AGENT_DONE: EXIT.DATA,
78
+ GOVERNANCE_REVIEW_BLOCKED: EXIT.DATA,
79
+ TEAM_NOT_FOUND: EXIT.DATA,
80
+ TEAM_TASK_NOT_FOUND: EXIT.DATA,
81
+ // FR-50:团队模板非法(角色缺失 / 数量为 0 / 角色名不在契约集合内)⇒ 拒绝建队
82
+ INVALID_TEAM_TEMPLATE: EXIT.USAGE,
83
+ AGENT_CANNOT_CLAIM_BACKLOG: EXIT.DATA,
84
+ AGENT_CANNOT_SET_DONE: EXIT.DATA,
85
+ AGENT_CANNOT_FINALIZE: EXIT.DATA,
86
+
87
+ // 冲突
88
+ VERSION_CONFLICT: EXIT.CONFLICT,
89
+ PROJECT_EXISTS: EXIT.CONFLICT,
90
+ // FR-03:非空项目不得删除(仍有任务/需求条目/需求文档正文)⇒ 冲突,须先清空
91
+ PROJECT_NOT_EMPTY: EXIT.CONFLICT,
92
+ IDENTIFIER_CONFLICT: EXIT.CONFLICT,
93
+ REQ_IDENTIFIER_CONFLICT: EXIT.CONFLICT,
94
+ DEPENDENCY_EXISTS: EXIT.CONFLICT,
95
+ DOC_EXISTS: EXIT.CONFLICT,
96
+ });
97
+
98
+ /** 领域错误:带 code / 退出码 / 可选细节。 */
99
+ export class TbError extends Error {
100
+ constructor(code, message, details = undefined) {
101
+ super(message);
102
+ this.name = "TbError";
103
+ this.code = code;
104
+ this.details = details;
105
+ this.exitCode = ERROR_CATEGORY[code] ?? EXIT.DATA;
106
+ }
107
+
108
+ toJSON() {
109
+ return {
110
+ code: this.code,
111
+ message: this.message,
112
+ ...(this.details === undefined ? {} : { details: this.details }),
113
+ };
114
+ }
115
+ }
116
+
117
+ export function usageError(message, details) {
118
+ return new TbError("USAGE_ERROR", message, details);
119
+ }
120
+
121
+ export function invalidField(field, message, details) {
122
+ return new TbError("INVALID_FIELD", message ?? `字段 ${field} 非法`, details);
123
+ }
124
+
125
+ export function notFound(kind, key) {
126
+ return new TbError(kind, `未找到:${key}`, { key });
127
+ }
128
+
129
+ /** 对外统一出口:任何异常都转成 { error, exitCode }。 */
130
+ export function toErrorPayload(error) {
131
+ if (error instanceof TbError) {
132
+ return { error: error.toJSON(), exitCode: error.exitCode };
133
+ }
134
+ const message = error instanceof Error ? error.message : String(error);
135
+ return {
136
+ error: { code: "DATA_ERROR", message },
137
+ exitCode: EXIT.DATA,
138
+ };
139
+ }