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.
- package/CHANGELOG.md +271 -0
- package/README.md +89 -0
- package/package.json +18 -5
- package/scripts/tb-flow.mjs +86 -0
- package/skills/taskboard-flow/SKILL.md +89 -0
- package/skills/taskboard-flow/references/errors.md +61 -0
- package/skills/taskboard-flow/references/injection.md +70 -0
- package/skills/taskboard-flow/references/steps/S0.md +31 -0
- package/skills/taskboard-flow/references/steps/S1.md +28 -0
- package/skills/taskboard-flow/references/steps/S2.md +31 -0
- package/skills/taskboard-flow/references/steps/S3.md +22 -0
- package/skills/taskboard-flow/references/steps/S4.md +25 -0
- package/skills/taskboard-flow/references/steps/S5.md +36 -0
- package/skills/taskboard-flow/references/steps/S6.md +30 -0
- package/skills/taskboard-flow/references/steps/S7.md +23 -0
- package/spec/norms/acceptance.md +36 -0
- package/spec/norms/card-update.md +39 -0
- package/spec/norms/doc-editing.md +30 -0
- package/spec/norms/flow.md +45 -0
- package/spec/norms/manifest.json +41 -0
- package/spec/norms/project-defaults.md +33 -0
- package/src/core/acceptance.mjs +62 -0
- package/src/core/contract.mjs +287 -0
- package/src/core/errors.mjs +3 -0
- package/src/core/evidence.mjs +86 -0
- package/src/core/intake.mjs +87 -24
- package/src/core/requirements.mjs +31 -1
- package/src/core/store.mjs +345 -6
- package/src/core/ticket-stage.mjs +150 -0
- package/src/mcp/flow-block.mjs +173 -0
- package/src/mcp/server.mjs +156 -0
- package/src/mcp/tools.mjs +764 -0
- package/src/server/api.mjs +106 -30
- package/src/server/server.mjs +3 -0
- package/web/app.js +117 -17
- package/web/tokens.css +12 -0
|
@@ -0,0 +1,764 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* tools.mjs —— MCP 只读四工具(P2 · 2026-10-29)
|
|
3
|
+
*
|
|
4
|
+
* 方案依据:`docs/设计/技能化与MCP契约-架构变更方案-2026-10-28.md`
|
|
5
|
+
* §6.1(stdio、同一份 SQLite、零宿主改动)· §6.2(工具清单)· §7.3(workbench_audit 四类漂移)
|
|
6
|
+
*
|
|
7
|
+
* 工具分两批:
|
|
8
|
+
* · **只读四件**(P2):`flow_start` / `project_info` / `norm_get` / `workbench_audit`;
|
|
9
|
+
* · **写四件 + 条目列表**(P3):`requirement_list` / `requirement_upsert` / `requirement_change`
|
|
10
|
+
* / `card_create` / `card_progress`。
|
|
11
|
+
*
|
|
12
|
+
* 只读四条的硬约束:
|
|
13
|
+
* ① **不写库**:这里不调用任何 create/update/delete/record*;`contractSnapshot` 与
|
|
14
|
+
* `listGovernanceAudit` 都是纯读(P1 已钉住「GET /contract 零副作用」);
|
|
15
|
+
* ② **不建目录、不建文档**:`resolveContext()` 会 `ensureRequirementDoc`(写),故这里只用
|
|
16
|
+
* `matchProjectForCwd()` + `getRequirementDoc()`(读);
|
|
17
|
+
* ③ **同一份真源**:数据来自 `openStore({dataDir})` 打开的**同一个** `taskboard.sqlite`,
|
|
18
|
+
* 与 Web/CLI 读写同一库 —— MCP 不是第二份数据。
|
|
19
|
+
*/
|
|
20
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
21
|
+
import path from "node:path";
|
|
22
|
+
import { fileURLToPath } from "node:url";
|
|
23
|
+
|
|
24
|
+
import { evaluateSubmittedContract, loadNorms, NORM_IDS, sha256 } from "../core/contract.mjs";
|
|
25
|
+
import { TbError } from "../core/errors.mjs";
|
|
26
|
+
import { matchProjectForCwd } from "../core/binding.mjs";
|
|
27
|
+
import { markAcceptance, acceptanceFlag } from "../core/acceptance.mjs";
|
|
28
|
+
|
|
29
|
+
/** 包根目录(仓库里 = 仓库根;npm 包里 = package 根)。`spec/norms` 在两处都随包存在。 */
|
|
30
|
+
export const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
|
|
31
|
+
export const NORMS_DIR = path.join(PKG_ROOT, "spec", "norms");
|
|
32
|
+
|
|
33
|
+
const TERMINAL = new Set(["done", "canceled"]);
|
|
34
|
+
const countBy = (rows, key = "status") => rows.reduce((acc, row) => {
|
|
35
|
+
const k = row[key] ?? "unknown";
|
|
36
|
+
acc[k] = (acc[k] ?? 0) + 1;
|
|
37
|
+
return acc;
|
|
38
|
+
}, {});
|
|
39
|
+
|
|
40
|
+
/** 统一错误:MCP 把 `code` 放在返回体里(不是 JSON-RPC error —— 那是协议层错误)。 */
|
|
41
|
+
const fail = (code, message, details = null) => new TbError(code, message, details ?? {});
|
|
42
|
+
|
|
43
|
+
export function resolveProject(store, { project, cwd } = {}) {
|
|
44
|
+
if (typeof project === "string" && project.trim() !== "") return { project: store.requireProject(project.trim()), matchedBy: "explicit" };
|
|
45
|
+
const m = matchProjectForCwd(store, cwd ?? process.cwd());
|
|
46
|
+
if (!m.project) throw fail("PROJECT_NOT_FOUND", "没有任何项目:先建项目,或显式传 project", { cwd: cwd ?? process.cwd() });
|
|
47
|
+
return { project: m.project, matchedBy: m.matched ? "cwd" : "fallback" };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function projectGaps(store, project) {
|
|
51
|
+
const tasks = store.listTasks({ projectId: project.id });
|
|
52
|
+
const live = tasks.filter((t) => !TERMINAL.has(t.status));
|
|
53
|
+
const unattributed = live.filter((t) => !t.requirementId);
|
|
54
|
+
const docs = store.listRequirementDocs({ projectId: project.id });
|
|
55
|
+
const pendingCandidates = docs.reduce((n, doc) => n + store.listRequirementCandidates({ docId: doc.id, status: "pending" }).length, 0);
|
|
56
|
+
const items = store.listRequirementItems({ projectId: project.id });
|
|
57
|
+
const withTasks = new Set(tasks.map((t) => t.requirementId).filter(Boolean));
|
|
58
|
+
return {
|
|
59
|
+
tasks,
|
|
60
|
+
items,
|
|
61
|
+
docs,
|
|
62
|
+
gaps: {
|
|
63
|
+
unattributedTasks: unattributed.length,
|
|
64
|
+
unattributedSamples: unattributed.slice(0, 5).map((t) => t.identifier),
|
|
65
|
+
pendingCandidates,
|
|
66
|
+
unboundSession: !project.initialSessionId,
|
|
67
|
+
requirementsWithoutTasks: items.filter((i) => i.status === "open" && !withTasks.has(i.id)).length,
|
|
68
|
+
tasksInReview: live.filter((t) => t.status === "in_review").length,
|
|
69
|
+
tasksBlocked: live.filter((t) => t.status === "blocked").length,
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 下一步建议(纯推导,不写库)。
|
|
76
|
+
* 顺序对齐 §5.2 的 S1→S7:先把需求说清,再建卡,再由**人**授权,再派发/回填,最后由**人**验收。
|
|
77
|
+
*/
|
|
78
|
+
export function deriveFlowNext({ tasks, items, gaps }) {
|
|
79
|
+
const by = countBy(tasks);
|
|
80
|
+
if (items.length === 0) return { step: "S1", title: "录需求条目", why: "项目还没有需求条目 —— 没有条目就没有可归因的卡", humanAction: null };
|
|
81
|
+
if (gaps.pendingCandidates > 20) return { step: "S1", title: "先清理待确认候选", why: `待确认候选 ${gaps.pendingCandidates} 条(阈值 20)—— 先确认/丢弃,避免候选洪水`, humanAction: null };
|
|
82
|
+
if (gaps.unattributedTasks > 0) return { step: "S2", title: "补归因(先于派发)", why: `${gaps.unattributedTasks} 张未完成卡没有归属需求条目;派发会被归因门拒绝`, humanAction: null };
|
|
83
|
+
if ((by.backlog ?? 0) > 0) return { step: "S3", title: "授权开工(人)", why: `${by.backlog} 张卡在待办池;backlog → todo 只能由人点`, humanAction: "authorize" };
|
|
84
|
+
if ((by.todo ?? 0) > 0) return { step: "S4", title: "派发 / 执行", why: `${by.todo} 张卡已授权待执行`, humanAction: null };
|
|
85
|
+
if ((by.in_progress ?? 0) > 0) return { step: "S5", title: "回填进度 + 证据", why: `${by.in_progress} 张卡在执行中;每条进展要带可核验证据`, humanAction: null };
|
|
86
|
+
if ((by.in_review ?? 0) > 0) return { step: "S7", title: "验收点完成(人)", why: `${by.in_review} 张卡待验收;done 只能由人确认`, humanAction: "accept" };
|
|
87
|
+
return { step: "S1", title: "补需求 / 收口", why: "当前没有待处理的卡;继续拆下一条需求或收口已完成条目", humanAction: null };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** `norm_get` 里 `project` 这一档:读项目自有补充(AGENTS.md),只读、限长、明确"不得覆盖四道门"。 */
|
|
91
|
+
function readProjectNorm(project) {
|
|
92
|
+
const wp = project?.workspacePath;
|
|
93
|
+
if (!wp) return { norm: "project", found: false, file: null, body: "", note: "该项目没有 workspacePath,无法读取项目侧补充规范" };
|
|
94
|
+
const file = path.join(wp, "AGENTS.md");
|
|
95
|
+
if (!existsSync(file)) return { norm: "project", found: false, file, body: "", note: "项目工作区没有 AGENTS.md(无补充约定)" };
|
|
96
|
+
const raw = readFileSync(file, "utf8");
|
|
97
|
+
const MAX = 20000;
|
|
98
|
+
return {
|
|
99
|
+
norm: "project",
|
|
100
|
+
found: true,
|
|
101
|
+
file,
|
|
102
|
+
truncated: raw.length > MAX,
|
|
103
|
+
body: raw.length > MAX ? `${raw.slice(0, MAX)}\n\n…(已截断,原文 ${raw.length} 字符)` : raw,
|
|
104
|
+
note: "项目侧补充:只可「追加 / 参数化」,**不得覆盖**八步顺序与四道门(人工校验 / 归因 / 授权 / 评审);done 只能人置。",
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function buildNormNotice(contract) {
|
|
109
|
+
const flow = (contract?.norms ?? []).find((n) => n.id === "flow");
|
|
110
|
+
const short = flow ? `${flow.digest.slice(0, 8)}…` : "(未取到)";
|
|
111
|
+
return [
|
|
112
|
+
`本流程使用的规范:spec/norms/flow.md @ v${flow?.version ?? "?"}(digest ${short})`,
|
|
113
|
+
"你可以:",
|
|
114
|
+
' · 查看:norm_get { norm: "flow" } ← 一屏读完',
|
|
115
|
+
" · 替换:把自有规范放到 <workspace>/AGENTS.md(由 norm:project 叠加)",
|
|
116
|
+
" · 只改参数:verifyCommand / workspacePath / notApplicable(3 类白名单)",
|
|
117
|
+
"⚠ 八步顺序与四道门(人工校验/归因/授权/评审)不可覆盖;done 只能人点。",
|
|
118
|
+
].join("\n");
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/* ------------------------------------------------------------------ 四个工具 ---- */
|
|
122
|
+
|
|
123
|
+
export function flowStart({ store }, args = {}) {
|
|
124
|
+
const { project, matchedBy } = resolveProject(store, args);
|
|
125
|
+
const { tasks, items, gaps } = projectGaps(store, project);
|
|
126
|
+
const snap = store.contractSnapshot(project.id);
|
|
127
|
+
return {
|
|
128
|
+
project: { id: project.id, name: project.name, workspacePath: project.workspacePath ?? null, initialSessionId: project.initialSessionId ?? null },
|
|
129
|
+
matchedBy,
|
|
130
|
+
contract: {
|
|
131
|
+
version: snap.snapshot.contractVersion,
|
|
132
|
+
docVersion: snap.snapshot.docVersion,
|
|
133
|
+
docDigest: snap.snapshot.docDigest,
|
|
134
|
+
gates: snap.snapshot.gates,
|
|
135
|
+
norms: snap.snapshot.norms,
|
|
136
|
+
baselineStale: snap.stale,
|
|
137
|
+
changed: snap.changed,
|
|
138
|
+
},
|
|
139
|
+
state: { tasks: tasks.length, tasksByStatus: countBy(tasks), requirements: items.length, requirementsByStatus: countBy(items) },
|
|
140
|
+
gaps,
|
|
141
|
+
nextStep: deriveFlowNext({ tasks, items, gaps }),
|
|
142
|
+
normNotice: buildNormNotice(snap.snapshot),
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export function projectInfo({ store }, args = {}) {
|
|
147
|
+
const { project } = resolveProject(store, args);
|
|
148
|
+
const { tasks, items, docs, gaps } = projectGaps(store, project);
|
|
149
|
+
const snap = store.contractSnapshot(project.id);
|
|
150
|
+
return {
|
|
151
|
+
project,
|
|
152
|
+
contract: { version: snap.snapshot.contractVersion, baseline: snap.baseline?.contractVersion ?? null, stale: snap.stale, changed: snap.changed },
|
|
153
|
+
counts: { tasks: tasks.length, tasksByStatus: countBy(tasks), requirements: items.length, requirementsByStatus: countBy(items), requirementDocs: docs.length },
|
|
154
|
+
gaps,
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
export function normGet({ store }, args = {}) {
|
|
159
|
+
const norm = typeof args.norm === "string" ? args.norm.trim() : "";
|
|
160
|
+
if (norm === "project") {
|
|
161
|
+
const { project } = resolveProject(store, args);
|
|
162
|
+
return readProjectNorm(project);
|
|
163
|
+
}
|
|
164
|
+
const allowed = [...NORM_IDS, "project"];
|
|
165
|
+
if (!allowed.includes(norm)) throw fail("NORM_NOT_FOUND", `未知规范:${norm || "(空)"}`, { allowed });
|
|
166
|
+
let norms;
|
|
167
|
+
try { norms = loadNorms(NORMS_DIR); }
|
|
168
|
+
catch (error) { throw fail("NORM_NOT_FOUND", `机器规范目录不可用:${NORMS_DIR}`, { reason: error?.message ?? String(error) }); }
|
|
169
|
+
const hit = norms.find((n) => n.id === norm);
|
|
170
|
+
if (!hit) throw fail("NORM_NOT_FOUND", `机器规范里没有:${norm}`, { allowed: NORM_IDS });
|
|
171
|
+
return { norm: hit.id, version: hit.version, updated: hit.updated, appliesTo: hit.appliesTo, digest: hit.digest, file: hit.relPath, body: hit.body };
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
export function workbenchAudit({ store }, args = {}) {
|
|
175
|
+
const { project } = resolveProject(store, args);
|
|
176
|
+
const sinceHours = Number.isFinite(Number(args.sinceHours)) && Number(args.sinceHours) > 0 ? Number(args.sinceHours) : 168;
|
|
177
|
+
const sinceMs = Date.now() - sinceHours * 3600 * 1000;
|
|
178
|
+
const { tasks, gaps } = projectGaps(store, project);
|
|
179
|
+
|
|
180
|
+
// ① contract-stale:内核 warn 档留下的审计(P1.5)——「有 agent 用旧契约写过东西」
|
|
181
|
+
const warns = store.listGovernanceAudit({ action: "contract-warn" })
|
|
182
|
+
.filter((r) => Date.parse(r.at) >= sinceMs)
|
|
183
|
+
.filter((r) => String(r.target ?? "").startsWith(`${project.id}-`) || r.target === project.id);
|
|
184
|
+
// ② unattributed:未完成且无归因的卡
|
|
185
|
+
const unattributed = tasks.filter((t) => !TERMINAL.has(t.status) && !t.requirementId);
|
|
186
|
+
// ③ unbound-session:项目主会话未绑定
|
|
187
|
+
const unbound = project.initialSessionId ? [] : [project.id];
|
|
188
|
+
// ④ candidate-flood:待确认候选超阈值
|
|
189
|
+
const threshold = 20;
|
|
190
|
+
const flood = gaps.pendingCandidates > threshold;
|
|
191
|
+
|
|
192
|
+
const items = [
|
|
193
|
+
{ type: "contract-stale", count: warns.length, samples: warns.slice(-5).map((r) => ({ at: r.at, actor: r.actor, target: r.target })), remedy: "重取 flow_start,按 changed[] 重读变更部分;新版本随返回体的 contract.version" },
|
|
194
|
+
{ type: "unattributed", count: unattributed.length, samples: unattributed.slice(0, 5).map((t) => t.identifier), remedy: "先补归因(requirement / unattributedReason),再派发 —— 否则归因门会拒" },
|
|
195
|
+
{ type: "unbound-session", count: unbound.length, samples: unbound, remedy: "在任务工作台里为项目「重建/绑定主会话」,否则投递会落空" },
|
|
196
|
+
{ type: "candidate-flood", count: gaps.pendingCandidates, threshold, over: flood, samples: [], remedy: `先确认/丢弃候选再跑条目化(当前 ${gaps.pendingCandidates} 条,阈值 ${threshold})` },
|
|
197
|
+
];
|
|
198
|
+
return {
|
|
199
|
+
project: { id: project.id, name: project.name },
|
|
200
|
+
sinceHours,
|
|
201
|
+
items,
|
|
202
|
+
ok: items.every((i) => i.count === 0 || i.type === "candidate-flood" && !i.over),
|
|
203
|
+
summary: items.filter((i) => i.count > 0).map((i) => `${i.type}=${i.count}${i.type === "candidate-flood" ? `/${i.threshold}` : ""}`),
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/* --------------------------------------------------- P3:写工具 + 条目列表 ---- */
|
|
208
|
+
|
|
209
|
+
const EVIDENCE_KINDS = Object.freeze(["file", "command", "url", "reading"]);
|
|
210
|
+
/** 条目「版本」:`requirement_items` 没有 version 列 ⇒ 用**内容摘要**当乐观锁(纯读、可重算、与行数无关)。 */
|
|
211
|
+
const REQ_VERSION_FIELDS = Object.freeze(["title", "description", "acceptance", "priority", "status"]);
|
|
212
|
+
|
|
213
|
+
function requirementVersion(item) {
|
|
214
|
+
if (!item) return null;
|
|
215
|
+
return sha256(REQ_VERSION_FIELDS.map((k) => String(item[k] ?? "")).join("\u0000")).slice(0, 12);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
function requirementSnapshot(item) {
|
|
219
|
+
const out = { identifier: item.identifier };
|
|
220
|
+
for (const k of REQ_VERSION_FIELDS) out[k] = item[k] ?? "";
|
|
221
|
+
out.version = requirementVersion(item);
|
|
222
|
+
return out;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function readCardUpdateNorm() {
|
|
226
|
+
return loadNorms(NORMS_DIR).find((n) => n.id === "card-update") ?? null;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* 写工具返回体里统一带一份「我这次用的契约 vs 当前契约」的读数。
|
|
231
|
+
*
|
|
232
|
+
* **不阻断**:D2 仍处 `warn` 档(用户拍板 A:先建写工具、契约校验保持 warn,切 `reject` 另行拍板)。
|
|
233
|
+
* 这里只把 verdict 明明白白回给 agent —— 让它自己知道「我拿的是旧规范」;真正的落库留痕在 `store`。
|
|
234
|
+
*/
|
|
235
|
+
function contractReadout(store, projectId, submitted) {
|
|
236
|
+
if (!submitted || typeof submitted !== "object") return { verdict: "skipped", problems: [] };
|
|
237
|
+
const snap = store.contractSnapshot(projectId);
|
|
238
|
+
const verdict = evaluateSubmittedContract(snap.snapshot, submitted);
|
|
239
|
+
return { verdict: verdict.verdict, problems: verdict.problems, current: snap.snapshot.contractVersion };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** 形状即约束:`evidence[]` 非空 + 每项 `{kind∈4, ref 非空}`。 */
|
|
243
|
+
function normalizeEvidence(list) {
|
|
244
|
+
if (!Array.isArray(list) || list.length === 0) {
|
|
245
|
+
throw fail(
|
|
246
|
+
"EVIDENCE_REQUIRED",
|
|
247
|
+
"回填进度必须带 evidence[](非空数组),每项 {kind, ref, note?};只写「已完成」三个字不算证据",
|
|
248
|
+
{ allowedKinds: EVIDENCE_KINDS },
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
return list.map((raw, i) => {
|
|
252
|
+
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
|
|
253
|
+
throw fail("EVIDENCE_INVALID", `evidence[${i}] 必须是对象 {kind, ref, note?}`, { index: i });
|
|
254
|
+
}
|
|
255
|
+
const kind = String(raw.kind ?? "").trim();
|
|
256
|
+
if (!EVIDENCE_KINDS.includes(kind)) {
|
|
257
|
+
throw fail("EVIDENCE_INVALID", `evidence[${i}].kind 必须是 ${EVIDENCE_KINDS.join(" / ")} 之一`, { index: i, received: kind, allowedKinds: EVIDENCE_KINDS });
|
|
258
|
+
}
|
|
259
|
+
const ref = String(raw.ref ?? "").trim();
|
|
260
|
+
if (ref === "") {
|
|
261
|
+
throw fail("EVIDENCE_INVALID", `evidence[${i}].ref 不能为空(命令原文 / 文件路径 / URL / 读数)`, { index: i });
|
|
262
|
+
}
|
|
263
|
+
return { kind, ref, note: raw.note == null ? "" : String(raw.note).trim() };
|
|
264
|
+
});
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** 同一批证据的稳定指纹(顺序敏感;用于「同一次回填重复调用」去重,而不是内容判重)。 */
|
|
268
|
+
function evidenceHash(list) {
|
|
269
|
+
return sha256(JSON.stringify(list.map((e) => [e.kind, e.ref, e.note]))).slice(0, 16);
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/* ---------------- requirement_list(只读) ---------------- */
|
|
273
|
+
|
|
274
|
+
export function requirementList({ store }, args = {}) {
|
|
275
|
+
const { project } = resolveProject(store, args);
|
|
276
|
+
const status = typeof args.status === "string" && args.status.trim() !== "" ? args.status.trim() : undefined;
|
|
277
|
+
const items = store.listRequirementItems({ projectId: project.id, status });
|
|
278
|
+
const byReq = new Map();
|
|
279
|
+
for (const t of store.listTasks({ projectId: project.id })) {
|
|
280
|
+
if (!t.requirementId) continue;
|
|
281
|
+
const arr = byReq.get(t.requirementId) ?? [];
|
|
282
|
+
arr.push(t);
|
|
283
|
+
byReq.set(t.requirementId, arr);
|
|
284
|
+
}
|
|
285
|
+
return {
|
|
286
|
+
project: { id: project.id, name: project.name },
|
|
287
|
+
count: items.length,
|
|
288
|
+
items: items.map((item) => {
|
|
289
|
+
const linked = byReq.get(item.id) ?? [];
|
|
290
|
+
const done = linked.filter((t) => t.status === "done").length;
|
|
291
|
+
return {
|
|
292
|
+
identifier: item.identifier,
|
|
293
|
+
title: item.title,
|
|
294
|
+
status: item.status,
|
|
295
|
+
priority: item.priority,
|
|
296
|
+
version: requirementVersion(item),
|
|
297
|
+
tasks: { total: linked.length, done, open: linked.length - done },
|
|
298
|
+
};
|
|
299
|
+
}),
|
|
300
|
+
};
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/* ---------------- requirement_upsert(写) ---------------- */
|
|
304
|
+
|
|
305
|
+
export function requirementUpsert({ store }, args = {}) {
|
|
306
|
+
const { project } = resolveProject(store, args);
|
|
307
|
+
const contract = contractReadout(store, project.id, args.contract);
|
|
308
|
+
const refCandidate = [args.id, args.requirement].find((x) => typeof x === "string" && x.trim() !== "");
|
|
309
|
+
const ref = refCandidate ? refCandidate.trim() : "";
|
|
310
|
+
|
|
311
|
+
if (ref !== "") {
|
|
312
|
+
const current = store.requireRequirementItemRef(ref);
|
|
313
|
+
if (current.projectId !== project.id) {
|
|
314
|
+
throw fail("DEPENDENCY_CROSS_PROJECT", `条目属于别的项目:${ref}(${current.projectId})`, { requirement: ref, requirementProject: current.projectId, project: project.id });
|
|
315
|
+
}
|
|
316
|
+
const expected = args.expected_version == null ? "" : String(args.expected_version).trim();
|
|
317
|
+
if (expected === "") {
|
|
318
|
+
throw fail("MISSING_VERSION", "改条目必须带 expected_version(= requirement_list 返回的 version)", { identifier: current.identifier, currentVersion: requirementVersion(current) });
|
|
319
|
+
}
|
|
320
|
+
if (expected !== requirementVersion(current)) {
|
|
321
|
+
throw fail("VERSION_CONFLICT", "条目已被他人修改,请重新 requirement_list 后再提交(不静默覆盖)", { identifier: current.identifier, expectedVersion: expected, currentVersion: requirementVersion(current) });
|
|
322
|
+
}
|
|
323
|
+
const patch = {};
|
|
324
|
+
for (const k of REQ_VERSION_FIELDS) if (args[k] !== undefined) patch[k] = args[k];
|
|
325
|
+
if (Object.keys(patch).length === 0) throw fail("USAGE_ERROR", `没有任何可改字段(${REQ_VERSION_FIELDS.join(" / ")})`, {});
|
|
326
|
+
const updated = store.updateRequirementItem(current.identifier, { ...patch, contract: args.contract });
|
|
327
|
+
// 卡 `-176`/`-177`(口径 X):`acceptanceSet` **永远**反映写入后的真实状态;
|
|
328
|
+
// 但只有这次 patch 真带了 `acceptance` 才落审计(否则 99/129 的空验收条目每改一次标题就添一行审计)。
|
|
329
|
+
const acc = patch.acceptance !== undefined
|
|
330
|
+
? markAcceptance(store, { identifier: updated.identifier, acceptance: updated.acceptance, actor: "mcp", entry: "mcp:requirement_upsert:update", detail: { changed: Object.keys(patch) } })
|
|
331
|
+
: acceptanceFlag(updated.acceptance);
|
|
332
|
+
return { created: false, item: requirementSnapshot(updated), changed: Object.keys(patch), contract, acceptanceSet: acc.acceptanceSet };
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
const title = typeof args.title === "string" ? args.title.trim() : "";
|
|
336
|
+
if (title === "") throw fail("INVALID_TITLE", "新建条目需要 title(改已有条目请给 id / requirement + expected_version)", {});
|
|
337
|
+
const created = store.createRequirementItem({
|
|
338
|
+
projectId: project.id,
|
|
339
|
+
title,
|
|
340
|
+
description: args.description,
|
|
341
|
+
acceptance: args.acceptance,
|
|
342
|
+
priority: args.priority,
|
|
343
|
+
status: args.status,
|
|
344
|
+
// 卡 `-176`:MCP 建的条目必须自带来源 `mcp`,否则与「人手建」在库里不可辨(审计也无从按入口统计)。
|
|
345
|
+
source: "mcp",
|
|
346
|
+
contract: args.contract,
|
|
347
|
+
});
|
|
348
|
+
// 卡 `-176`(口径 X):新建时「没给验收」= 显式缺口 —— 回包 `acceptanceSet:false` + 落 `governance_audit`。
|
|
349
|
+
const acc = markAcceptance(store, { identifier: created.identifier, acceptance: created.acceptance, actor: "mcp", entry: "mcp:requirement_upsert" });
|
|
350
|
+
return { created: true, item: requirementSnapshot(created), contract, acceptanceSet: acc.acceptanceSet };
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/* ---------------- requirement_change(写 · 变更影响面确认门) ---------------- */
|
|
354
|
+
|
|
355
|
+
export function requirementChange({ store }, args = {}) {
|
|
356
|
+
const { project } = resolveProject(store, args);
|
|
357
|
+
const ref = [args.requirement, args.id].find((x) => typeof x === "string" && x.trim() !== "");
|
|
358
|
+
if (!ref) throw fail("USAGE_ERROR", "requirement_change 需要 requirement(条目编号或 id)", {});
|
|
359
|
+
const item = store.requireRequirementItemRef(ref.trim());
|
|
360
|
+
if (item.projectId !== project.id) {
|
|
361
|
+
throw fail("DEPENDENCY_CROSS_PROJECT", `条目属于别的项目:${ref}(${item.projectId})`, { requirement: ref, requirementProject: item.projectId, project: project.id });
|
|
362
|
+
}
|
|
363
|
+
const reason = String(args.reason ?? "").trim();
|
|
364
|
+
if (reason === "") {
|
|
365
|
+
throw fail("CHANGE_REASON_REQUIRED", "需求变更必须写 reason(为什么改)—— 没有理由的变更事后无法复盘", { identifier: item.identifier });
|
|
366
|
+
}
|
|
367
|
+
const patchRaw = args.patch && typeof args.patch === "object" && !Array.isArray(args.patch) ? args.patch : {};
|
|
368
|
+
const patch = {};
|
|
369
|
+
for (const k of REQ_VERSION_FIELDS) if (patchRaw[k] !== undefined) patch[k] = patchRaw[k];
|
|
370
|
+
if (Object.keys(patch).length === 0) {
|
|
371
|
+
throw fail("USAGE_ERROR", `patch 至少改一个字段(${REQ_VERSION_FIELDS.join(" / ")})`, {});
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
const before = requirementSnapshot(item);
|
|
375
|
+
const after = { ...before };
|
|
376
|
+
for (const [k, v] of Object.entries(patch)) after[k] = v;
|
|
377
|
+
// 影响面:这条需求下**所有未终态**的卡(改需求时它们可能已经按旧口径做了一半)
|
|
378
|
+
const affectedCards = store.listTasksByRequirement(item.identifier)
|
|
379
|
+
.map((t) => ({ identifier: t.identifier, title: t.title, status: t.status, terminal: TERMINAL.has(t.status) }));
|
|
380
|
+
const affected = affectedCards.filter((c) => !c.terminal);
|
|
381
|
+
|
|
382
|
+
// `change_id` 覆盖「哪条需求 + 改之前是什么样 + 改成什么」⇒ **条目在预览后被改过,id 自动失效**(无状态、无需存表)
|
|
383
|
+
const changeId = sha256(JSON.stringify([item.identifier, before.version, Object.keys(patch).sort().map((k) => [k, String(patch[k])])])).slice(0, 12);
|
|
384
|
+
|
|
385
|
+
if (args.apply !== true) {
|
|
386
|
+
store.recordAudit({ actor: "agent", action: "requirement-change-preview", target: item.identifier, allowed: true, reason: "preview", detail: `${Object.keys(patch).join(",")} change=${changeId}(未落地)` });
|
|
387
|
+
return {
|
|
388
|
+
applied: false,
|
|
389
|
+
needs_approval: true,
|
|
390
|
+
change_id: changeId,
|
|
391
|
+
requirement: item.identifier,
|
|
392
|
+
title: item.title,
|
|
393
|
+
reason,
|
|
394
|
+
changed: Object.keys(patch),
|
|
395
|
+
before,
|
|
396
|
+
after,
|
|
397
|
+
affected_cards: affected,
|
|
398
|
+
affected_total: affectedCards.length,
|
|
399
|
+
how_to_apply: `确认影响面后重发:{ requirement: "${item.identifier}", patch: <同样的 patch>, reason: <同样的 reason>, change_id: "${changeId}", apply: true }`,
|
|
400
|
+
};
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
const given = String(args.change_id ?? "").trim();
|
|
404
|
+
if (given === "") {
|
|
405
|
+
throw fail("CHANGE_NEEDS_APPROVAL", "apply=true 需要先预览拿 change_id(这是变更影响面确认门,不是可跳过的表单)", { identifier: item.identifier, computed: changeId });
|
|
406
|
+
}
|
|
407
|
+
if (given !== changeId) {
|
|
408
|
+
throw fail("CHANGE_ID_MISMATCH", "change_id 与当前条目状态 / 补丁不符(条目在预览后被改过,或补丁换了):请重新预览", { identifier: item.identifier, given, computed: changeId });
|
|
409
|
+
}
|
|
410
|
+
const updated = store.updateRequirementItem(item.identifier, { ...patch, contract: args.contract });
|
|
411
|
+
store.recordAudit({ actor: "agent", action: "requirement-change", target: item.identifier, allowed: true, reason, detail: `${Object.keys(patch).join(",")} change=${changeId}` });
|
|
412
|
+
return {
|
|
413
|
+
applied: true,
|
|
414
|
+
change_id: changeId,
|
|
415
|
+
requirement: item.identifier,
|
|
416
|
+
title: updated.title,
|
|
417
|
+
reason,
|
|
418
|
+
changed: Object.keys(patch),
|
|
419
|
+
before,
|
|
420
|
+
after: requirementSnapshot(updated),
|
|
421
|
+
affected_cards: affected,
|
|
422
|
+
affected_total: affectedCards.length,
|
|
423
|
+
contract: contractReadout(store, project.id, args.contract),
|
|
424
|
+
};
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
/* ---------------- card_create(写 · 归因硬门 D1=A) ---------------- */
|
|
428
|
+
|
|
429
|
+
export function cardCreate({ store }, args = {}) {
|
|
430
|
+
const { project } = resolveProject(store, args);
|
|
431
|
+
const title = typeof args.title === "string" ? args.title.trim() : "";
|
|
432
|
+
if (title === "") throw fail("INVALID_TITLE", "card_create 需要 title", {});
|
|
433
|
+
|
|
434
|
+
// D1=A:**这个工具的入参形状**就是归因硬门。
|
|
435
|
+
// 注意口径边界:这里只收紧 MCP 这一个新入口;内核全局档(TB_STRICT_ATTRIBUTION)保持默认 warn ——
|
|
436
|
+
// 全局翻档会影响 Web / CLI / seed 全部存量调用方,属另一件事,须单独拍板(只登记不擅改)。
|
|
437
|
+
const requirement = typeof args.requirement === "string" ? args.requirement.trim() : "";
|
|
438
|
+
const unattributedReason = [args.unattributed_reason, args.unattributedReason]
|
|
439
|
+
.find((x) => typeof x === "string" && x.trim() !== "")?.trim() ?? "";
|
|
440
|
+
if (requirement === "" && unattributedReason === "") {
|
|
441
|
+
throw fail(
|
|
442
|
+
"REQUIREMENT_REQUIRED",
|
|
443
|
+
"建卡必须归属需求条目:给 requirement <条目编号>;确实不需要归属时用 unattributed_reason <理由> 显式声明(会落审计,可盘点)",
|
|
444
|
+
{ project: project.id, hint: '先 requirement_list { project } 挑一条,或 requirement_upsert 新建' },
|
|
445
|
+
);
|
|
446
|
+
}
|
|
447
|
+
if (requirement !== "" && unattributedReason !== "") {
|
|
448
|
+
throw fail("USAGE_ERROR", "requirement 与 unattributed_reason 只能二选一(要么归属,要么显式不归属)", {});
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
// 新卡只能进待办池:`backlog → todo` 是**人工授权**动作(四道门之一),MCP 不得代点。
|
|
452
|
+
const wantedStatus = typeof args.status === "string" && args.status.trim() !== "" ? args.status.trim() : "backlog";
|
|
453
|
+
if (wantedStatus !== "backlog") {
|
|
454
|
+
throw fail(
|
|
455
|
+
"AUTHORIZATION_REQUIRED",
|
|
456
|
+
`新卡只能建在 backlog(待办池):backlog → todo 是人工授权动作,执行侧不得代点(收到 status=${wantedStatus})`,
|
|
457
|
+
{ received: wantedStatus, allowed: ["backlog"] },
|
|
458
|
+
);
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
// 依赖先解析:失败要发生在建卡**之前**,不留半张没边的卡
|
|
462
|
+
const dependsOn = Array.isArray(args.dependsOn) ? args.dependsOn.map((x) => String(x).trim()).filter(Boolean) : [];
|
|
463
|
+
const blockers = dependsOn.map((dep) => {
|
|
464
|
+
const blocker = store.getTaskRef(dep);
|
|
465
|
+
if (!blocker) throw fail("TASK_NOT_FOUND", `依赖的前置任务不存在:${dep}`, { ref: dep });
|
|
466
|
+
if (blocker.projectId !== project.id) {
|
|
467
|
+
throw fail("DEPENDENCY_CROSS_PROJECT", `前置任务属于别的项目:${dep}(${blocker.projectId})`, { ref: dep, taskProject: blocker.projectId, project: project.id });
|
|
468
|
+
}
|
|
469
|
+
return blocker;
|
|
470
|
+
});
|
|
471
|
+
|
|
472
|
+
const created = store.createTask({
|
|
473
|
+
projectId: project.id,
|
|
474
|
+
title,
|
|
475
|
+
description: args.description,
|
|
476
|
+
acceptance: args.acceptance,
|
|
477
|
+
verifyCommand: args.verifyCommand,
|
|
478
|
+
priority: args.priority,
|
|
479
|
+
owner: args.owner,
|
|
480
|
+
labels: args.labels,
|
|
481
|
+
status: "backlog",
|
|
482
|
+
parentId: args.parent ?? args.parentId,
|
|
483
|
+
requirementId: requirement || undefined,
|
|
484
|
+
unattributedReason: unattributedReason || undefined,
|
|
485
|
+
contract: args.contract,
|
|
486
|
+
});
|
|
487
|
+
|
|
488
|
+
const edges = blockers.map((b) => {
|
|
489
|
+
store.addTaskDependency({ blocker: b.id, blocked: created.id });
|
|
490
|
+
return { blocker: b.identifier, blocked: created.identifier };
|
|
491
|
+
});
|
|
492
|
+
|
|
493
|
+
// 标题去重**只提示不拦截**:「同名但确是另一件事」是合法情形,拦截会逼人改个好名字绕过
|
|
494
|
+
const key = title.toLowerCase();
|
|
495
|
+
const duplicates = store.listTasks({ projectId: project.id })
|
|
496
|
+
.filter((t) => t.id !== created.id && !TERMINAL.has(t.status) && String(t.title).trim().toLowerCase() === key)
|
|
497
|
+
.map((t) => ({ identifier: t.identifier, status: t.status, requirementId: t.requirementId ?? null }));
|
|
498
|
+
|
|
499
|
+
return {
|
|
500
|
+
card: {
|
|
501
|
+
identifier: created.identifier,
|
|
502
|
+
title: created.title,
|
|
503
|
+
status: created.status,
|
|
504
|
+
version: created.version,
|
|
505
|
+
requirementId: created.requirementId ?? null,
|
|
506
|
+
},
|
|
507
|
+
attribution: created.requirementId
|
|
508
|
+
? { kind: "requirement", requirement: requirement }
|
|
509
|
+
: { kind: "explicit-skip", reason: unattributedReason },
|
|
510
|
+
dependsOn: edges,
|
|
511
|
+
duplicates,
|
|
512
|
+
contract: contractReadout(store, project.id, args.contract),
|
|
513
|
+
next: "backlog → todo 需要人工授权;授权后可用 card_progress 回填进度与证据(done 永远只能人点)",
|
|
514
|
+
};
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
/* ---------------- card_progress(写 · 证据必填 + 规范摘要门) ---------------- */
|
|
518
|
+
|
|
519
|
+
export function cardProgress({ store }, args = {}) {
|
|
520
|
+
const ref = [args.card, args.ref, args.task]
|
|
521
|
+
.find((x) => typeof x === "string" && x.trim() !== "")?.trim() ?? "";
|
|
522
|
+
if (ref === "") throw fail("USAGE_ERROR", "card_progress 需要 card(任务编号或 id)", {});
|
|
523
|
+
const task = store.requireTaskRef(ref);
|
|
524
|
+
|
|
525
|
+
const evidence = normalizeEvidence(args.evidence);
|
|
526
|
+
|
|
527
|
+
// `norm_digest` 是**这个工具的必填形状**(不是 D2 的全局档):没读过 card-update 就回填=拿旧规矩干活。
|
|
528
|
+
// 它只影响 MCP 这个新入口,不改任何存量调用方的行为。
|
|
529
|
+
const norm = readCardUpdateNorm();
|
|
530
|
+
const provided = typeof args.norm_digest === "string" ? args.norm_digest.trim() : "";
|
|
531
|
+
if (provided === "") {
|
|
532
|
+
throw fail("NORM_DIGEST_REQUIRED", '回填必须带 norm_digest(card-update 规范的 sha256):先 norm_get { norm: "card-update" } 取 digest', { norm: "card-update", current: norm?.digest ?? null });
|
|
533
|
+
}
|
|
534
|
+
if (!norm || provided !== norm.digest) {
|
|
535
|
+
throw fail("NORM_STALE", "你用的 card-update 规范不是当前版本:按返回的 body 重新回填(digest 见下)", {
|
|
536
|
+
norm: "card-update",
|
|
537
|
+
yours: provided,
|
|
538
|
+
current: norm?.digest ?? null,
|
|
539
|
+
version: norm?.version ?? null,
|
|
540
|
+
body: norm?.body ?? "",
|
|
541
|
+
});
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
const hash = evidenceHash(evidence);
|
|
545
|
+
const marker = `【MCP 证据】hash=${hash}`;
|
|
546
|
+
const existing = store.listComments(task.id).find((c) => String(c.body ?? "").includes(marker)) ?? null;
|
|
547
|
+
let comment = existing;
|
|
548
|
+
let deduped = Boolean(existing);
|
|
549
|
+
if (!existing) {
|
|
550
|
+
const lines = [marker, ...evidence.map((e) => `- ${e.kind}: ${e.ref}${e.note ? ` — ${e.note}` : ""}`)];
|
|
551
|
+
if (typeof args.comment === "string" && args.comment.trim() !== "") lines.push("", args.comment.trim());
|
|
552
|
+
comment = store.addComment(task.identifier, { body: lines.join("\n"), contract: args.contract });
|
|
553
|
+
deduped = false;
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
const statusBefore = task.status;
|
|
557
|
+
let after = task;
|
|
558
|
+
let statusChanged = false;
|
|
559
|
+
const wanted = typeof args.status === "string" && args.status.trim() !== "" ? args.status.trim() : null;
|
|
560
|
+
if (wanted && wanted !== statusBefore) {
|
|
561
|
+
// 走**执行侧状态门**(不是 updateTask):done 只能人点 / 人工校验任务不得改状态 / backlog→todo 属授权
|
|
562
|
+
after = store.teamSetTaskStatus(task.identifier, { status: wanted, actor: "agent" });
|
|
563
|
+
statusChanged = true;
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
return {
|
|
567
|
+
card: {
|
|
568
|
+
identifier: after.identifier,
|
|
569
|
+
statusBefore,
|
|
570
|
+
statusAfter: after.status,
|
|
571
|
+
statusChanged,
|
|
572
|
+
version: after.version,
|
|
573
|
+
requirementId: after.requirementId ?? null,
|
|
574
|
+
},
|
|
575
|
+
evidence: { hash, count: evidence.length, kinds: [...new Set(evidence.map((e) => e.kind))] },
|
|
576
|
+
comment: { id: comment?.id ?? null, deduped },
|
|
577
|
+
norm: { id: "card-update", version: norm.version, digest: norm.digest },
|
|
578
|
+
contract: contractReadout(store, task.projectId, args.contract),
|
|
579
|
+
next: after.status === "in_review" ? "待验收:done 只能由人确认(评审门 + 人工收口)" : null,
|
|
580
|
+
};
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/* ------------------------------------------------------------------ 注册表 ---- */
|
|
584
|
+
|
|
585
|
+
const ok = (schema) => schema;
|
|
586
|
+
|
|
587
|
+
export const TOOLS = Object.freeze([
|
|
588
|
+
{
|
|
589
|
+
name: "flow_start",
|
|
590
|
+
description: "开局第一步(S0,只读):按 cwd / project 解析项目,返回项目身份、contract_version、缺口(未归因卡 / 未绑定主会话 / 待确认候选)与下一步建议。不写任何数据。",
|
|
591
|
+
inputSchema: ok({
|
|
592
|
+
type: "object",
|
|
593
|
+
properties: {
|
|
594
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配,未命中回落默认项目)" },
|
|
595
|
+
cwd: { type: "string", description: "工作目录(默认进程 cwd)" },
|
|
596
|
+
},
|
|
597
|
+
additionalProperties: false,
|
|
598
|
+
}),
|
|
599
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
600
|
+
handler: flowStart,
|
|
601
|
+
},
|
|
602
|
+
{
|
|
603
|
+
name: "project_info",
|
|
604
|
+
description: "项目总览(只读):项目配置 + 任务/需求条目按状态计数 + 契约版本与基线是否漂移。",
|
|
605
|
+
inputSchema: ok({
|
|
606
|
+
type: "object",
|
|
607
|
+
properties: {
|
|
608
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
609
|
+
cwd: { type: "string", description: "工作目录(默认进程 cwd)" },
|
|
610
|
+
},
|
|
611
|
+
additionalProperties: false,
|
|
612
|
+
}),
|
|
613
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
614
|
+
handler: projectInfo,
|
|
615
|
+
},
|
|
616
|
+
{
|
|
617
|
+
name: "norm_get",
|
|
618
|
+
description: "取机器规范正文(只读):flow / card-update / doc-editing / acceptance / project-defaults;norm=\"project\" 取项目自有补充(<workspace>/AGENTS.md)。",
|
|
619
|
+
inputSchema: ok({
|
|
620
|
+
type: "object",
|
|
621
|
+
required: ["norm"],
|
|
622
|
+
properties: {
|
|
623
|
+
norm: { type: "string", description: "规范 id,或 project(项目侧补充)" },
|
|
624
|
+
project: { type: "string", description: "norm=project 时的项目 id(省略按 cwd 匹配)" },
|
|
625
|
+
cwd: { type: "string", description: "工作目录(默认进程 cwd)" },
|
|
626
|
+
},
|
|
627
|
+
additionalProperties: false,
|
|
628
|
+
}),
|
|
629
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
630
|
+
handler: normGet,
|
|
631
|
+
},
|
|
632
|
+
{
|
|
633
|
+
name: "workbench_audit",
|
|
634
|
+
description: "漂移盘点(只读):contract-stale / unattributed / unbound-session / candidate-flood 四类,各带计数、样例与处置建议。",
|
|
635
|
+
inputSchema: ok({
|
|
636
|
+
type: "object",
|
|
637
|
+
properties: {
|
|
638
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
639
|
+
cwd: { type: "string", description: "工作目录(默认进程 cwd)" },
|
|
640
|
+
sinceHours: { type: "number", description: "contract-stale 的回看窗口(小时,默认 168)" },
|
|
641
|
+
},
|
|
642
|
+
additionalProperties: false,
|
|
643
|
+
}),
|
|
644
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
645
|
+
handler: workbenchAudit,
|
|
646
|
+
},
|
|
647
|
+
{
|
|
648
|
+
name: "requirement_list",
|
|
649
|
+
description: "需求条目列表(只读):条目 + 内容版本(乐观锁用)+ 每条下的卡数与完成数。建卡前先用它挑 requirement。",
|
|
650
|
+
inputSchema: ok({
|
|
651
|
+
type: "object",
|
|
652
|
+
properties: {
|
|
653
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
654
|
+
status: { type: "string", description: "按条目状态过滤(open / in_progress / done / canceled 等)" },
|
|
655
|
+
cwd: { type: "string", description: "工作目录(默认进程 cwd)" },
|
|
656
|
+
},
|
|
657
|
+
additionalProperties: false,
|
|
658
|
+
}),
|
|
659
|
+
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
660
|
+
handler: requirementList,
|
|
661
|
+
},
|
|
662
|
+
{
|
|
663
|
+
name: "requirement_upsert",
|
|
664
|
+
description: "新建或修改需求条目(写)。改已有条目必须带 expected_version(= requirement_list 返回的 version),不符 ⇒ VERSION_CONFLICT(不静默覆盖)。",
|
|
665
|
+
inputSchema: ok({
|
|
666
|
+
type: "object",
|
|
667
|
+
properties: {
|
|
668
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
669
|
+
id: { type: "string", description: "要修改的条目(编号或 id);不传则新建" },
|
|
670
|
+
requirement: { type: "string", description: "id 的别名" },
|
|
671
|
+
expected_version: { type: "string", description: "改条目时必填:requirement_list 返回的 version" },
|
|
672
|
+
title: { type: "string" },
|
|
673
|
+
description: { type: "string" },
|
|
674
|
+
acceptance: { type: "string" },
|
|
675
|
+
priority: { type: "string", description: "none / low / medium / high / urgent" },
|
|
676
|
+
status: { type: "string", description: "条目状态(新建默认 open)" },
|
|
677
|
+
contract: { type: "object", description: "调用方用的契约 {version, normDigests}(warn 档:只留痕不阻断)" },
|
|
678
|
+
},
|
|
679
|
+
additionalProperties: false,
|
|
680
|
+
}),
|
|
681
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
|
|
682
|
+
handler: requirementUpsert,
|
|
683
|
+
},
|
|
684
|
+
{
|
|
685
|
+
name: "requirement_change",
|
|
686
|
+
description: "需求变更(写):先返回影响面(affected_cards)+ change_id,带 change_id + apply:true 才落地。条目在预览后被改过 ⇒ change_id 自动失效。",
|
|
687
|
+
inputSchema: ok({
|
|
688
|
+
type: "object",
|
|
689
|
+
properties: {
|
|
690
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
691
|
+
requirement: { type: "string", description: "条目编号或 id" },
|
|
692
|
+
patch: { type: "object", description: "要改的字段:title / description / acceptance / priority / status" },
|
|
693
|
+
reason: { type: "string", description: "为什么改(必填,事后复盘用)" },
|
|
694
|
+
change_id: { type: "string", description: "预览返回的 change_id;apply=true 时必填" },
|
|
695
|
+
apply: { type: "boolean", description: "true 才真正落地(默认 false = 只预览)" },
|
|
696
|
+
contract: { type: "object", description: "调用方用的契约(warn 档)" },
|
|
697
|
+
},
|
|
698
|
+
required: ["requirement", "patch", "reason"],
|
|
699
|
+
additionalProperties: false,
|
|
700
|
+
}),
|
|
701
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
|
|
702
|
+
handler: requirementChange,
|
|
703
|
+
},
|
|
704
|
+
{
|
|
705
|
+
name: "card_create",
|
|
706
|
+
description: "建卡(写)。**归因硬门**:必须给 requirement,或显式 unattributed_reason(落审计)。新卡只能进 backlog(backlog→todo 是人工授权)。",
|
|
707
|
+
inputSchema: ok({
|
|
708
|
+
type: "object",
|
|
709
|
+
properties: {
|
|
710
|
+
project: { type: "string", description: "项目 id(省略则按 cwd 匹配)" },
|
|
711
|
+
title: { type: "string" },
|
|
712
|
+
requirement: { type: "string", description: "归属的需求条目(编号或 id)——与 unattributed_reason 二选一" },
|
|
713
|
+
unattributed_reason: { type: "string", description: "显式声明不归因的理由(会落审计,可盘点)" },
|
|
714
|
+
description: { type: "string" },
|
|
715
|
+
acceptance: { type: "string", description: "完成验收标准(建议必填)" },
|
|
716
|
+
verifyCommand: { type: "string", description: "复核动作(如 npm test)" },
|
|
717
|
+
priority: { type: "string" },
|
|
718
|
+
owner: { type: "string" },
|
|
719
|
+
labels: { type: "array", items: { type: "string" } },
|
|
720
|
+
parent: { type: "string", description: "父任务(编号或 id)" },
|
|
721
|
+
dependsOn: { type: "array", items: { type: "string" }, description: "前置任务(编号或 id),建卡后成依赖边" },
|
|
722
|
+
contract: { type: "object", description: "调用方用的契约(warn 档)" },
|
|
723
|
+
},
|
|
724
|
+
required: ["title"],
|
|
725
|
+
additionalProperties: false,
|
|
726
|
+
}),
|
|
727
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
|
|
728
|
+
handler: cardCreate,
|
|
729
|
+
},
|
|
730
|
+
{
|
|
731
|
+
name: "card_progress",
|
|
732
|
+
description: "回填进度(写)。**证据必填**(evidence[] 非空,每项 {kind:file|command|url|reading, ref, note?})+ **norm_digest 必填**(card-update 规范的 sha256)。状态走执行侧门:done 只能人点。",
|
|
733
|
+
inputSchema: ok({
|
|
734
|
+
type: "object",
|
|
735
|
+
properties: {
|
|
736
|
+
card: { type: "string", description: "任务编号或 id" },
|
|
737
|
+
status: { type: "string", description: "可选:in_progress / in_review / blocked / canceled(done 与会触发授权门的状态一律拒)" },
|
|
738
|
+
evidence: {
|
|
739
|
+
type: "array",
|
|
740
|
+
minItems: 1,
|
|
741
|
+
items: {
|
|
742
|
+
type: "object",
|
|
743
|
+
properties: {
|
|
744
|
+
kind: { type: "string", enum: ["file", "command", "url", "reading"] },
|
|
745
|
+
ref: { type: "string" },
|
|
746
|
+
note: { type: "string" },
|
|
747
|
+
},
|
|
748
|
+
required: ["kind", "ref"],
|
|
749
|
+
additionalProperties: false,
|
|
750
|
+
},
|
|
751
|
+
},
|
|
752
|
+
norm_digest: { type: "string", description: "card-update 规范的 sha256(先 norm_get { norm: \"card-update\" })" },
|
|
753
|
+
comment: { type: "string", description: "附加说明(会拼在证据块之后)" },
|
|
754
|
+
contract: { type: "object", description: "调用方用的契约(warn 档)" },
|
|
755
|
+
},
|
|
756
|
+
required: ["card", "evidence", "norm_digest"],
|
|
757
|
+
additionalProperties: false,
|
|
758
|
+
}),
|
|
759
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
|
|
760
|
+
handler: cardProgress,
|
|
761
|
+
},
|
|
762
|
+
]);
|
|
763
|
+
|
|
764
|
+
export const TOOL_NAMES = Object.freeze(TOOLS.map((t) => t.name));
|