taskboard-workbench 0.3.1 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +101 -2
- package/index.js +112 -13
- package/package.json +6 -2
- package/scripts/tb-flow.mjs +109 -8
- package/skills/taskboard-flow/SKILL.md +2 -2
- package/skills/taskboard-flow/references/injection.md +76 -29
- package/skills/taskboard-flow/references/steps/S5.md +21 -1
- package/spec/docs/01-/351/241/271/347/233/256/345/274/200/345/261/200.md +63 -0
- package/spec/docs/02-/346/265/201/347/250/213/346/211/247/350/241/214/344/270/216/346/235/241/347/233/256.md +110 -0
- package/spec/docs/README.md +36 -0
- package/spec/docs/assets//346/235/241/347/233/256/350/257/246/346/203/205/346/250/241/346/235/277.md +105 -0
- package/spec/norms/item-detail.md +73 -0
- package/spec/norms/manifest.json +7 -0
- package/src/core/config.mjs +12 -3
- package/src/core/contract.mjs +17 -7
- package/src/core/data-dir-hint.mjs +52 -0
- package/src/core/docs-assets.mjs +135 -0
- package/src/core/errors.mjs +11 -0
- package/src/core/evidence.mjs +28 -0
- package/src/core/executor.mjs +27 -7
- package/src/core/executors.mjs +279 -0
- package/src/core/flow-inject.mjs +190 -0
- package/src/core/instance-lease.mjs +113 -0
- package/src/core/kickoff.mjs +289 -0
- package/src/core/norms.mjs +177 -0
- package/src/core/requirements.mjs +38 -0
- package/src/core/store.mjs +333 -36
- package/src/core/verify.mjs +39 -4
- package/src/mcp/flow-block.mjs +30 -0
- package/src/mcp/server.mjs +19 -6
- package/src/mcp/tools.mjs +99 -7
- package/src/server/api.mjs +361 -11
- package/web/app.js +1077 -82
- package/web/tokens.css +166 -28
package/src/core/kickoff.mjs
CHANGED
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
* 红线(与 FR-85 同口径):**自检只给结论,不改任何数据**;缺什么由人(或用既有入口)去补。
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
+
import { TbError } from "./errors.mjs";
|
|
17
|
+
|
|
16
18
|
/** 出处(写进报告,便于追溯;引用不复制原文)。 */
|
|
17
19
|
export const KICKOFF_SOURCE = Object.freeze({
|
|
18
20
|
title: "Vibe Coding 团队协作技巧(鱼皮 / ai-guide)",
|
|
@@ -145,3 +147,290 @@ export function evaluateKickoff({ files = {}, settings = {}, custom = {} } = {})
|
|
|
145
147
|
: `开局对齐未完成(${doneCount}/${steps.length}):未对齐项 ${missing.map((s) => s.title).join("、")};建议先补齐再派发执行。`,
|
|
146
148
|
};
|
|
147
149
|
}
|
|
150
|
+
|
|
151
|
+
/** 回查:report 的步骤只有 id/title/status/done/total/checks,判据来源(paths/setting/custom)
|
|
152
|
+
* 必须回 `KICKOFF_ALIGNMENT_STEPS` 这**唯一一份**定义里取 —— 不复制第二份步骤定义。 */
|
|
153
|
+
const stepDefOf = (stepId) => KICKOFF_ALIGNMENT_STEPS.find((s) => s.id === stepId) ?? null;
|
|
154
|
+
const checkDefOf = (stepDef, checkId) => (stepDef?.checks ?? []).find((c) => c.id === checkId) ?? null;
|
|
155
|
+
/** 步骤在规范序里的下标(未知 stepId 排最后)。 */
|
|
156
|
+
const canonicalStepIndex = (stepId) => {
|
|
157
|
+
const i = KICKOFF_ALIGNMENT_STEPS.findIndex((s) => s.id === stepId);
|
|
158
|
+
return i < 0 ? KICKOFF_ALIGNMENT_STEPS.length : i;
|
|
159
|
+
};
|
|
160
|
+
/**
|
|
161
|
+
* 判据的「可核验信号」——**结构化**描述(不解析自然语言):
|
|
162
|
+
* { kind:"paths", any:[文件候选] } / { kind:"setting", keys:[点路径] } / { kind:"custom", id }
|
|
163
|
+
* todolist 生成器据此拼**可执行命令**(见 buildKickoffTodos)。
|
|
164
|
+
*/
|
|
165
|
+
function signalOf(def) {
|
|
166
|
+
if (Array.isArray(def?.paths) && def.paths.length) return { kind: "paths", any: def.paths.map(String) };
|
|
167
|
+
if (def?.setting) return { kind: "setting", keys: (Array.isArray(def.setting) ? def.setting : [def.setting]).map(String) };
|
|
168
|
+
if (def?.custom) return { kind: "custom", id: String(def.custom) };
|
|
169
|
+
return { kind: "unknown" };
|
|
170
|
+
}
|
|
171
|
+
/** 信号 → 人能读的「动作 / 判据」文案(必须点名具体文件或设置项,禁止泛化措辞)。 */
|
|
172
|
+
function describeSignal(signal, fallbackId) {
|
|
173
|
+
if (signal.kind === "paths") return { action: `新增/补齐文件(任一即可):${signal.any.join(" / ")}`, criterion: `工作区存在文件(任一):${signal.any.join(" / ")}` };
|
|
174
|
+
if (signal.kind === "setting") return { action: `在项目设置里填写 ${signal.keys.join(" 或 ")} 的值`, criterion: `项目设置 ${signal.keys.join(" 或 ")} 非空` };
|
|
175
|
+
if (signal.kind === "custom") return { action: `按团队模板补齐自检项 ${signal.id}`, criterion: `团队模板自检项 ${signal.id} 为真` };
|
|
176
|
+
return { action: `补齐自检项 ${fallbackId}`, criterion: `自检项 ${fallbackId} 为真` };
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* 卡 `-229`(需求 `R170`):把自检结论**投影**成「缺口清单」。
|
|
181
|
+
*
|
|
182
|
+
* 入参就是 `evaluateKickoff()` 的返回值 —— **本函数不重新判定任何判据、不新增完成度真源**,
|
|
183
|
+
* 只是把已经算好的 `steps[].done/total` 与 `checks[].ok` 换个形状摆出来。
|
|
184
|
+
* 形状:`{ step, done, total, items:[{label, action, criterion, step}] }`
|
|
185
|
+
* · `step` = 步骤总数(= report.steps.length,本项目 6)
|
|
186
|
+
* · `done`/`total` = **判据**级计数(逐步骤累加 report.steps[].done/total,不重算)
|
|
187
|
+
* · `items` = 未通过的判据(`items.length === 0` ⟺ `done === total` ⟺ `report.ready === true`)
|
|
188
|
+
* · `items[].step` 是**步骤归属**(渲染表格用),同样直接取自 report,不是第二份完成度。
|
|
189
|
+
*/
|
|
190
|
+
export function collectGaps(report) {
|
|
191
|
+
// F3(评审):非法入参**显式抛错**。曾经静默返回全零 ⇒ 前端读成「零缺口=已对齐」并置灰(假绿)。
|
|
192
|
+
if (!report || typeof report !== "object" || Array.isArray(report) || !Array.isArray(report.steps)) {
|
|
193
|
+
throw new TbError(
|
|
194
|
+
"INVALID_FIELD",
|
|
195
|
+
"collectGaps(report) 只接受 evaluateKickoff() 的返回值(对象且含 steps 数组);传 projectId 字符串之类是误用 —— 缺口必须来自自检结果,不能凭空算",
|
|
196
|
+
{ got: Array.isArray(report) ? "array" : typeof report },
|
|
197
|
+
);
|
|
198
|
+
}
|
|
199
|
+
const steps = report.steps;
|
|
200
|
+
const items = [];
|
|
201
|
+
for (const step of steps) {
|
|
202
|
+
if (step?.status === "done") continue; // 已完成步骤:整步跳过(只统计未完成)
|
|
203
|
+
const stepDef = stepDefOf(step?.id);
|
|
204
|
+
const title = String(step?.title ?? stepDef?.title ?? "");
|
|
205
|
+
for (const check of step?.checks ?? []) {
|
|
206
|
+
if (check?.ok === true) continue; // 已通过判据:跳过(只统计未完成)
|
|
207
|
+
const def = checkDefOf(stepDef, check?.id); // F1:回查唯一一份步骤定义拿来源
|
|
208
|
+
const signal = signalOf(def);
|
|
209
|
+
const { action, criterion } = describeSignal(signal, String(check?.id ?? "?"));
|
|
210
|
+
items.push({
|
|
211
|
+
label: String(check?.label ?? def?.label ?? ""),
|
|
212
|
+
action,
|
|
213
|
+
criterion,
|
|
214
|
+
step: title,
|
|
215
|
+
stepId: String(step?.id ?? ""),
|
|
216
|
+
checkId: String(check?.id ?? ""),
|
|
217
|
+
signal,
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
const done = steps.reduce((n, s) => n + (Number(s?.done) || 0), 0);
|
|
222
|
+
const total = steps.reduce((n, s) => n + (Number(s?.total) || 0), 0);
|
|
223
|
+
return { step: steps.length, done, total, items };
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** 卡 `-230`(需求 R170):每条 todo 的「完成后提示」——正文与结构体共用这一份文案。 */
|
|
227
|
+
export const KICKOFF_TODO_HINT = "完成后回配置页「项目开局对齐」重跑配置页自检(点「重新自检」;✅ 与计数随真实判据变化)";
|
|
228
|
+
|
|
229
|
+
/** 六步顺序的**唯一**短文案(注入正文与守卫都用它,别另抄一份)。 */
|
|
230
|
+
export const KICKOFF_ORDER_TEXT = "规范 → 文档 → Git → 审查 → 协作 → 分工";
|
|
231
|
+
|
|
232
|
+
/** 设置类判据的兜底基址:与 `scripts/tb-flow.mjs` 的 `--host` 约定同源,可用 TB_BASE 覆盖。 */
|
|
233
|
+
const SETTINGS_BASE = "http://127.0.0.1:3080/integrations/taskboard-workbench";
|
|
234
|
+
|
|
235
|
+
/** 单引号安全包裹(命令里会拼整段 node 脚本;脚本内只用双引号,不出现单引号)。 */
|
|
236
|
+
const shellQuote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* `node -e` 脚本壳(Node 18+ 自带 fetch):基址读 `TB_BASE`,缺省 `SETTINGS_BASE`。
|
|
240
|
+
* 非 2xx / 解析失败 / 任何异常一律 `process.exit(1)` —— 拿不到数据=判不通过,绝不假绿。
|
|
241
|
+
*/
|
|
242
|
+
const settingsFetchScript = (pid, body) =>
|
|
243
|
+
`const base=process.env.TB_BASE||"${SETTINGS_BASE}";fetch(base+"/api/projects/${pid}/settings").then((r)=>{if(!r.ok)process.exit(1);return r.json();}).then((j)=>{${body}}).catch(()=>process.exit(1));`;
|
|
244
|
+
|
|
245
|
+
/** `setting` 判据的判定体:与 `isFilled()` 同口径(undefined/null/""/[]/{} 都算没填)。 */
|
|
246
|
+
const settingCheckBody = (keys) =>
|
|
247
|
+
`const pick=(o,p)=>String(p).split(".").reduce((a,k)=>(a==null?a:a[k]),o);const filled=(v)=>v!==undefined&&v!==null&&(typeof v==="string"?v.trim()!=="":Array.isArray(v)?v.length>0:typeof v==="object"?Object.keys(v).length>0:true);process.exit(${JSON.stringify(keys)}.some((k)=>filled(pick(j,k)))?0:1);`;
|
|
248
|
+
|
|
249
|
+
/** `reviewerRole` 判定体:只在 `teamTemplate.roles` 段内看角色名是否含 `review`(不扫全 JSON)。 */
|
|
250
|
+
const REVIEWER_CHECK_BODY =
|
|
251
|
+
`const r=j&&j.teamTemplate&&j.teamTemplate.roles;const names=Array.isArray(r)?r.map((x)=>String((x&&x.role)!==undefined?x.role:x).toLowerCase()):(r&&typeof r==="object"?Object.keys(r).map((k)=>k.toLowerCase()):[]);process.exit(names.some((n)=>n.includes("review"))?0:1);`;
|
|
252
|
+
|
|
253
|
+
/** `engineerExecutor` 判定体:与 `hasEngineerExecutor()` 同口径(roles[engineer].executor / roles.engineer / teamTemplate.engineer.verifyCommand)。 */
|
|
254
|
+
const ENGINEER_CHECK_BODY =
|
|
255
|
+
`const t=j&&j.teamTemplate;const r=t&&t.roles;let ok=false;if(Array.isArray(r))ok=r.some((x)=>String((x&&x.role)!==undefined?x.role:"").toLowerCase()==="engineer"&&String((x&&x.executor)||"").trim()!=="");else if(r&&typeof r==="object"&&r.engineer)ok=true;if(!ok)ok=String((t&&t.engineer&&t.engineer.verifyCommand)||"").trim()!=="";process.exit(ok?0:1);`;
|
|
256
|
+
|
|
257
|
+
/** 候选路径 → 紧凑形态:无目录且有扩展名的,按「最后一个点之前」归并成 glob
|
|
258
|
+
* (`.eslintrc.json` / `.eslintrc.cjs` ⇒ `.eslintrc*`);带目录或无扩展名的原样保留。
|
|
259
|
+
* 只为把命令压短,**不新增判据真源**;语义仍是「任一存在即通过」。 */
|
|
260
|
+
const compactPathGlobs = (any) => {
|
|
261
|
+
const groups = new Map();
|
|
262
|
+
const order = [];
|
|
263
|
+
for (const raw of any) {
|
|
264
|
+
const base = String(raw);
|
|
265
|
+
const dot = base.lastIndexOf(".");
|
|
266
|
+
const stem = base.includes("/") || dot <= 0 ? base : base.slice(0, dot);
|
|
267
|
+
if (!groups.has(stem)) { groups.set(stem, []); order.push(stem); }
|
|
268
|
+
groups.get(stem).push(base);
|
|
269
|
+
}
|
|
270
|
+
return order.map((stem) => (groups.get(stem).length > 1 ? `${stem}*` : groups.get(stem)[0]));
|
|
271
|
+
};
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* 判据信号 → **可执行命令**(POSIX sh;在项目工作区根目录执行):
|
|
275
|
+
* · paths ⇒ `e=$(ls -d …|head -1); [ -n "$e" ]`(文件存在性,任一即可;紧凑形态)
|
|
276
|
+
* · setting ⇒ `node -e '…fetch …/api/projects/<id>/settings…'`,按 `isFilled()` 口径判**值非空**
|
|
277
|
+
* · custom ⇒ 同上,但按角色名/执行器判(`reviewerRole` 只看 `teamTemplate.roles`)
|
|
278
|
+
* 旧写法用 `grep '"gitFlow"'` 只匹配**键名**、`grep -i 'reviewer'` 是全 JSON 子串匹配,
|
|
279
|
+
* 与「值非空 / 为该角色」不等价 ⇒ 键在值空、或无关文本里提到 reviewer 都会假绿。
|
|
280
|
+
*
|
|
281
|
+
* paths 分支的紧凑形态(卡 `t22`):原 `[ -e "A" ] || [ -e "B" ] …` 全展开会随候选数线性变长
|
|
282
|
+
* (code-style 一步 15 个候选),叠加多判据后超过 `VERIFY_MAX_COMMAND`。改为归并 glob + 一次 `ls -d`,
|
|
283
|
+
* 判据语义不变(任一存在 ⇒ `$e` 非空 ⇒ 0);glob 部分**不能加引号**(加引号就不展开)。
|
|
284
|
+
*/
|
|
285
|
+
export function gapVerifyCommand(signal, projectId) {
|
|
286
|
+
const kind = signal?.kind ?? "unknown";
|
|
287
|
+
if (kind === "paths") {
|
|
288
|
+
const any = Array.isArray(signal.any) ? signal.any : [];
|
|
289
|
+
if (any.length === 0) return "false";
|
|
290
|
+
const items = compactPathGlobs(any).map((p) => (p.endsWith("*") ? p : shellQuote(p)));
|
|
291
|
+
return `e=$(ls -d ${items.join(" ")} 2>/dev/null|head -1); [ -n "$e" ]`;
|
|
292
|
+
}
|
|
293
|
+
const pid = encodeURIComponent(String(projectId ?? "?"));
|
|
294
|
+
if (kind === "setting") {
|
|
295
|
+
const keys = (Array.isArray(signal.keys) ? signal.keys : []).map(String);
|
|
296
|
+
return `node -e ${shellQuote(settingsFetchScript(pid, settingCheckBody(keys)))}`;
|
|
297
|
+
}
|
|
298
|
+
if (kind === "custom") {
|
|
299
|
+
const id = String(signal.id ?? "");
|
|
300
|
+
if (id === "reviewerRole") return `node -e ${shellQuote(settingsFetchScript(pid, REVIEWER_CHECK_BODY))}`;
|
|
301
|
+
if (id === "engineerExecutor") return `node -e ${shellQuote(settingsFetchScript(pid, ENGINEER_CHECK_BODY))}`;
|
|
302
|
+
// 未知 custom 项:保守不通过(宁可让人手工核,也不假绿)。
|
|
303
|
+
return `echo ${shellQuote(`no machine check for custom:${id}`)} >&2; false`;
|
|
304
|
+
}
|
|
305
|
+
return `echo "no machine check for ${kind}" >&2; false`;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** 卡 `-230`:缺口清单 → **分步 todolist**(一步一条,顺序固定 = 依赖顺序)。
|
|
309
|
+
* **不解析自然语言**:全部字段由 `collectGaps().items[]` 的 `signal`/`action`/`criterion` 机械拼装。
|
|
310
|
+
* 每条的 `hint` 固定为 `KICKOFF_TODO_HINT`(完成后回配置页重跑自检)。
|
|
311
|
+
*/
|
|
312
|
+
export function buildKickoffTodos({ project, gaps } = {}) {
|
|
313
|
+
if (!gaps || typeof gaps !== "object" || !Array.isArray(gaps.items)) {
|
|
314
|
+
throw new TbError("INVALID_FIELD", "buildKickoffTodos({project, gaps}) 需要 collectGaps() 的输出(含 items 数组)", { got: typeof gaps });
|
|
315
|
+
}
|
|
316
|
+
const pid = project?.id ?? null;
|
|
317
|
+
const order = [];
|
|
318
|
+
const buckets = new Map();
|
|
319
|
+
for (const item of gaps.items) {
|
|
320
|
+
const key = String(item?.stepId ?? item?.step ?? "");
|
|
321
|
+
if (!buckets.has(key)) {
|
|
322
|
+
buckets.set(key, { stepId: key, step: String(item?.step ?? ""), items: [] });
|
|
323
|
+
order.push(key);
|
|
324
|
+
}
|
|
325
|
+
buckets.get(key).items.push(item);
|
|
326
|
+
}
|
|
327
|
+
// 顺序**按规范序**(不是入参出现顺序):逆序喂进来也要输出 规范 → 文档 → Git → 审查 → 协作 → 分工。
|
|
328
|
+
// 未知 stepId 排最后,相互间保持原顺序(稳定排序;Array#sort 自 ES2019 起保证稳定)。
|
|
329
|
+
order.sort((a, b) => canonicalStepIndex(a) - canonicalStepIndex(b));
|
|
330
|
+
return order.map((key, i) => {
|
|
331
|
+
const bucket = buckets.get(key);
|
|
332
|
+
const items = bucket.items;
|
|
333
|
+
return {
|
|
334
|
+
index: i + 1,
|
|
335
|
+
stepId: bucket.stepId,
|
|
336
|
+
step: bucket.step,
|
|
337
|
+
action: items.map((it) => String(it?.action ?? "")).filter(Boolean).join(";"),
|
|
338
|
+
criterion: items.map((it) => String(it?.criterion ?? "")).filter(Boolean).join(";"),
|
|
339
|
+
verifyCommand: items.map((it) => `( ${gapVerifyCommand(it?.signal, pid)} )`).join(" && "),
|
|
340
|
+
hint: KICKOFF_TODO_HINT,
|
|
341
|
+
labels: items.map((it) => String(it?.label ?? "")).filter(Boolean),
|
|
342
|
+
};
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* 卡 `t20`(需求 `R170`):缺口注入的「建卡要求(关联需求)」段 —— **纯字符串拼接,不解析自然语言**。
|
|
348
|
+
*
|
|
349
|
+
* 为什么必须有这一段:执行侧收到缺口后是照正文建卡的,而 `store.createTask` 认完整 identifier
|
|
350
|
+
* (形如 `taskboard-workbench-R170`)与简写 `R170`(卡 `-234` 起按本项目解析),且没归属的卡执行时
|
|
351
|
+
* 会被归因门拒(`EXECUTION_NOT_ATTRIBUTED`)。正文里一个字不提「关联需求」⇒ 建出来的卡必然无归属 ⇒ 建了也跑不动。
|
|
352
|
+
*
|
|
353
|
+
* 三态(三选一,互斥):
|
|
354
|
+
* · 给了 `requirement`(本次指定)⇒ 只写这一条,**不再**列候选(候选是噪音,还会引诱执行侧另选);
|
|
355
|
+
* · 没给但有候选 ⇒ 列出来让人/执行侧选一条(完整标识 + 标题,两者都要,否则对不上号);
|
|
356
|
+
* · 没给且无候选 ⇒ 明说「本项目暂无未关闭需求」,并给显式逃生口 `unattributedReason`。
|
|
357
|
+
*/
|
|
358
|
+
function buildRequirementSection(requirement, requirements) {
|
|
359
|
+
const lines = [
|
|
360
|
+
"## 建卡要求(关联需求)",
|
|
361
|
+
"",
|
|
362
|
+
"- 每张卡必须带 `requirement` 字段;写**完整标识**最稳(形如 `taskboard-workbench-R170`),简写 `R170` 也认(按本项目解析)。",
|
|
363
|
+
"- 未归属的卡执行时会被归因门拒绝(`EXECUTION_NOT_ATTRIBUTED`)—— 建出来也跑不动。",
|
|
364
|
+
];
|
|
365
|
+
const picked = requirement && typeof requirement === "object" ? String(requirement.identifier ?? "").trim() : "";
|
|
366
|
+
if (picked !== "") {
|
|
367
|
+
const title = String(requirement.title ?? "").trim();
|
|
368
|
+
lines.push(`- 本次指定关联需求:\`${picked}\`${title ? `(${title})` : ""}。`);
|
|
369
|
+
} else {
|
|
370
|
+
const candidates = (Array.isArray(requirements) ? requirements : [])
|
|
371
|
+
.map((it) => ({ identifier: String(it?.identifier ?? "").trim(), title: String(it?.title ?? "").trim() }))
|
|
372
|
+
.filter((it) => it.identifier !== "");
|
|
373
|
+
if (candidates.length > 0) {
|
|
374
|
+
lines.push("- 本次未指定:从下列候选里选一条填进 `requirement`(完整标识 + 标题):");
|
|
375
|
+
for (const it of candidates) lines.push(` - \`${it.identifier}\`${it.title ? ` ${it.title}` : ""}`);
|
|
376
|
+
} else {
|
|
377
|
+
lines.push("- 本项目暂无未关闭需求,需先建需求条目或用 `unattributedReason` 显式声明(写明不归属的原因)。");
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
lines.push("");
|
|
381
|
+
return lines;
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* 卡 `-229`:把缺口清单拼成**可直接投进主会话**的一段正文(纯函数,便于单测/复用)。
|
|
386
|
+
* 表格四列与需求一致:步骤 / 缺什么 / 建议动作 / 判据;并按 report 的步骤顺序(即依赖顺序)排列。
|
|
387
|
+
*/
|
|
388
|
+
export function buildGapPrompt({ project, gaps, todos, requirement = null, requirements = [] } = {}) {
|
|
389
|
+
const p = project ?? {};
|
|
390
|
+
const g = gaps ?? { step: 0, done: 0, total: 0, items: [] };
|
|
391
|
+
const items = Array.isArray(g.items) ? g.items : [];
|
|
392
|
+
const todoList = Array.isArray(todos) ? todos : buildKickoffTodos({ project, gaps: g });
|
|
393
|
+
const requirementSection = buildRequirementSection(requirement, requirements);
|
|
394
|
+
const name = String(p.name ?? "").trim() || "(未命名项目)";
|
|
395
|
+
const id = String(p.id ?? "").trim() || "?";
|
|
396
|
+
const cell = (value) => String(value ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
|
|
397
|
+
const lines = [
|
|
398
|
+
`[任务工作台 · 开局对齐缺口] 项目:${name}(${id})`,
|
|
399
|
+
"",
|
|
400
|
+
`当前缺口 ${items.length} 项(共 ${Number(g.step) || 0} 步;判据自检 ${Number(g.done) || 0}/${Number(g.total) || 0} 已通过)。`,
|
|
401
|
+
`请把下列缺口建成待办清单(todolist),**按依赖顺序推进**(${KICKOFF_ORDER_TEXT})。`,
|
|
402
|
+
"",
|
|
403
|
+
"| # | 步骤 | 缺什么 | 建议动作 | 判据 |",
|
|
404
|
+
"|---|---|---|---|---|",
|
|
405
|
+
];
|
|
406
|
+
if (items.length === 0) {
|
|
407
|
+
lines.push("| — | — | (无缺口:开局已对齐) | — | — |");
|
|
408
|
+
} else {
|
|
409
|
+
items.forEach((item, i) => {
|
|
410
|
+
lines.push(`| ${i + 1} | ${cell(item?.step)} | ${cell(item?.label)} | ${cell(item?.action)} | ${cell(item?.criterion)} |`);
|
|
411
|
+
});
|
|
412
|
+
}
|
|
413
|
+
lines.push("", `## 待办清单(todolist · 按依赖顺序推进 · 共 ${todoList.length} 条)`, "");
|
|
414
|
+
if (todoList.length === 0) {
|
|
415
|
+
lines.push("- (无缺口:开局对齐已完成,不需要待办)");
|
|
416
|
+
} else {
|
|
417
|
+
for (const todo of todoList) {
|
|
418
|
+
lines.push(`${todo.index}. [ ] ${todo.step}`);
|
|
419
|
+
lines.push(` - 动作:${todo.action}`);
|
|
420
|
+
lines.push(` - 判据:${todo.criterion}`);
|
|
421
|
+
lines.push(` - 命令:${todo.verifyCommand}`);
|
|
422
|
+
lines.push(` - 完成:${todo.hint}`);
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
lines.push(
|
|
426
|
+
"",
|
|
427
|
+
// 卡 `t20`:紧跟在待办清单之后 —— 执行侧读到这里正是「准备建卡」的那一刻,要求要摆在手边。
|
|
428
|
+
...requirementSection,
|
|
429
|
+
"> 本清单与「开工语」(新会话首条 `KICKOFF_PROMPT` ①–⑧ 的第 ① 项)是**同一套六步**,不另立流程。",
|
|
430
|
+
"",
|
|
431
|
+
"## 推进纪律",
|
|
432
|
+
"- 每完成一项,回配置页「项目开局对齐」点「重新自检」:✅ 与计数随真实判据变化(判据只此一份,不另立真源)。",
|
|
433
|
+
"- 缺什么以自检读数为准:本清单由 evaluateKickoff() 的当前结果投影,不缓存、不臆断。",
|
|
434
|
+
);
|
|
435
|
+
return lines.join("\n");
|
|
436
|
+
}
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 项目级机器规范(卡 `-216` / 需求 `R160`,2026-11-04 人拍)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么需要:`spec/norms/*.md` 是随包分发的**默认**规范,但它躺在 `node_modules` 里 ——
|
|
5
|
+
* 用户要按自己团队的口径改,只能改安装目录(升级即丢),或者改 `docs/`(不入 git、不进包)。
|
|
6
|
+
* 所以给每个项目一份**可改副本**:`<项目工作区>/.taskboard/norms/`。
|
|
7
|
+
*
|
|
8
|
+
* 三条设计口径(对应决策点):
|
|
9
|
+
* · **D-A 位置**:`.taskboard/norms/` —— 不与用户自己的 `spec/` 撞名,且一眼看出是工具产物;
|
|
10
|
+
* · **D-B 时机**:只在**显式动作**(配置页按钮 / API)时复制,**建项目不静默写用户目录**;
|
|
11
|
+
* · **D-C 改动**:改正文必须 bump `version`,否则 `build-norms --check` / digest 校验红。
|
|
12
|
+
*
|
|
13
|
+
* 读优先级:项目副本存在 → 用它;**缺哪一份就用包内那份**(逐份回落,不是整目录回落,
|
|
14
|
+
* 也不是报错 —— 升级新增规范时,旧副本必然缺新那份,报错等于把用户挡在门外)。
|
|
15
|
+
*/
|
|
16
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
|
|
17
|
+
import path from "node:path";
|
|
18
|
+
|
|
19
|
+
import { loadNorms, parseNormDoc } from "./contract.mjs";
|
|
20
|
+
import { TbError } from "./errors.mjs";
|
|
21
|
+
|
|
22
|
+
/** 项目副本相对工作区的位置。 */
|
|
23
|
+
export const PROJECT_NORMS_SUBDIR = path.join(".taskboard", "norms");
|
|
24
|
+
|
|
25
|
+
/** @param {string|null|undefined} workspacePath */
|
|
26
|
+
export function projectNormsDir(workspacePath) {
|
|
27
|
+
const ws = typeof workspacePath === "string" ? workspacePath.trim() : "";
|
|
28
|
+
if (!ws) return null;
|
|
29
|
+
return path.join(ws, PROJECT_NORMS_SUBDIR);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function hasMarkdown(dir) {
|
|
33
|
+
try {
|
|
34
|
+
return readdirSync(dir).some((f) => f.endsWith(".md"));
|
|
35
|
+
} catch {
|
|
36
|
+
return false;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* 解析「本项目实际生效的规范」。
|
|
42
|
+
*
|
|
43
|
+
* @param {{packagedDir:string, workspacePath?:string|null}} input
|
|
44
|
+
* @returns {{source:"packaged"|"project", dir:string, projectDir:string|null, hasProjectCopy:boolean,
|
|
45
|
+
* norms:Array, fallbackIds:string[], ignoredFiles:string[]}}
|
|
46
|
+
*/
|
|
47
|
+
/**
|
|
48
|
+
* 读项目副本(**逐文件容错**):README / 用户自己的笔记这类没有 frontmatter 的文件直接跳过;
|
|
49
|
+
* 有 frontmatter 但格式坏的,记进 `ignored` 而不抛 —— 否则一份坏文件会把整个看板挡在门外。
|
|
50
|
+
*/
|
|
51
|
+
export function readProjectNorms(dir) {
|
|
52
|
+
const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
|
|
53
|
+
const norms = []; const ignored = [];
|
|
54
|
+
for (const f of files) {
|
|
55
|
+
const abs = path.join(dir, f);
|
|
56
|
+
const text = readFileSync(abs, "utf8");
|
|
57
|
+
if (!text.replace(/^\uFEFF/, "").startsWith("---\n")) { ignored.push({ file: f, reason: "no-frontmatter" }); continue; }
|
|
58
|
+
try {
|
|
59
|
+
const parsed = parseNormDoc(text, abs, { allowUnknown: true });
|
|
60
|
+
norms.push({
|
|
61
|
+
id: parsed.meta.norm_id, version: parsed.meta.version, updated: parsed.meta.updated,
|
|
62
|
+
appliesTo: parsed.meta.applies_to, digest: parsed.digest, file: abs,
|
|
63
|
+
relPath: path.join(PROJECT_NORMS_SUBDIR, f), body: parsed.body,
|
|
64
|
+
});
|
|
65
|
+
} catch (error) {
|
|
66
|
+
ignored.push({ file: f, reason: error?.code ?? "invalid", message: error?.message ?? String(error) });
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
return { norms, ignored };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function resolveNorms({ packagedDir, workspacePath = null }) {
|
|
73
|
+
const packaged = loadNorms(packagedDir);
|
|
74
|
+
const dir = projectNormsDir(workspacePath);
|
|
75
|
+
if (!dir || !hasMarkdown(dir)) {
|
|
76
|
+
return { source: "packaged", dir: packagedDir, projectDir: dir, hasProjectCopy: false, norms: packaged, fallbackIds: [], ignoredFiles: [] };
|
|
77
|
+
}
|
|
78
|
+
const local = readProjectNorms(dir);
|
|
79
|
+
const byId = new Map(local.norms.map((n) => [n.id, n]));
|
|
80
|
+
const packagedIds = new Set(packaged.map((n) => n.id));
|
|
81
|
+
const fallbackIds = [];
|
|
82
|
+
const norms = packaged.map((p) => {
|
|
83
|
+
const mine = byId.get(p.id);
|
|
84
|
+
if (!mine) { fallbackIds.push(p.id); return p; }
|
|
85
|
+
return mine;
|
|
86
|
+
});
|
|
87
|
+
const unknown = local.norms.filter((n) => !packagedIds.has(n.id)).map((n) => ({ file: path.basename(n.file), reason: "unknown-id" }));
|
|
88
|
+
return { source: "project", dir, projectDir: dir, hasProjectCopy: true, norms, fallbackIds, ignoredFiles: [...local.ignored, ...unknown] };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** 配置页/接口用的只读视图(带「与内置是否不同」)。 */
|
|
92
|
+
export function normsView({ packagedDir, workspacePath = null }) {
|
|
93
|
+
const resolved = resolveNorms({ packagedDir, workspacePath });
|
|
94
|
+
const packaged = loadNorms(packagedDir);
|
|
95
|
+
const packagedById = new Map(packaged.map((n) => [n.id, n]));
|
|
96
|
+
return {
|
|
97
|
+
source: resolved.source,
|
|
98
|
+
dir: resolved.dir,
|
|
99
|
+
projectDir: resolved.projectDir,
|
|
100
|
+
packagedDir: packagedDir,
|
|
101
|
+
hasProjectCopy: resolved.hasProjectCopy,
|
|
102
|
+
fallbackIds: resolved.fallbackIds,
|
|
103
|
+
ignoredFiles: resolved.ignoredFiles,
|
|
104
|
+
norms: resolved.norms.map((n) => {
|
|
105
|
+
const base = packagedById.get(n.id);
|
|
106
|
+
return {
|
|
107
|
+
id: n.id,
|
|
108
|
+
version: n.version,
|
|
109
|
+
updated: n.updated,
|
|
110
|
+
digest: n.digest,
|
|
111
|
+
origin: resolved.hasProjectCopy && resolved.fallbackIds.includes(n.id) ? "packaged" : resolved.source,
|
|
112
|
+
modified: Boolean(base) && base.digest !== n.digest,
|
|
113
|
+
file: path.basename(n.file),
|
|
114
|
+
};
|
|
115
|
+
}),
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const README = `# 本项目的机器规范(可改)
|
|
120
|
+
|
|
121
|
+
这个目录是**本项目的规范副本**,来源是任务工作台随包分发的默认规范(共 N 份)。
|
|
122
|
+
看板读写时**优先读这里**;这里缺哪一份,就回落用安装包里那份(不会报错)。
|
|
123
|
+
|
|
124
|
+
## 怎么改
|
|
125
|
+
|
|
126
|
+
1. 直接编辑 \`.md\` 正文(frontmatter 的 \`norm_id\` 不要动);
|
|
127
|
+
2. **改正文必须同时把 \`version\` 加 1**,否则会被判「规范被偷偷改了」;
|
|
128
|
+
3. 改完自检:\`node <安装包>/tools/build-norms.mjs --dir .taskboard/norms --check\`
|
|
129
|
+
4. 改完要重算契约基线(否则写操作会按「旧契约」被拦):配置页 →「规范来源」→ 重算 / 或 \`POST /api/projects/<id>/contract/recheck\`。
|
|
130
|
+
|
|
131
|
+
## 要不要入库
|
|
132
|
+
|
|
133
|
+
这个目录在**你的项目工作区**里,要不要 \`git add\` 由你定 —— 想让团队共享就入库,只想本机生效就加进 \`.gitignore\`。
|
|
134
|
+
|
|
135
|
+
## 恢复默认
|
|
136
|
+
|
|
137
|
+
配置页 →「规范来源」→「恢复默认」(会用安装包里的版本覆盖本目录)。
|
|
138
|
+
`;
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* 把包内默认规范复制成项目副本。
|
|
142
|
+
* @param {{packagedDir:string, workspacePath?:string|null, overwrite?:boolean}} input
|
|
143
|
+
*/
|
|
144
|
+
export function materializeProjectNorms({ packagedDir, workspacePath = null, overwrite = false }) {
|
|
145
|
+
const dir = projectNormsDir(workspacePath);
|
|
146
|
+
if (!dir) throw new TbError("WORKSPACE_MISSING", "项目未配置工作区目录(workspacePath)⇒ 无法生成规范副本;请先在「配置 → 当前绑定」填工作区");
|
|
147
|
+
mkdirSync(dir, { recursive: true });
|
|
148
|
+
const packaged = loadNorms(packagedDir);
|
|
149
|
+
const written = []; const kept = [];
|
|
150
|
+
for (const n of packaged) {
|
|
151
|
+
const target = path.join(dir, path.basename(n.file));
|
|
152
|
+
if (existsSync(target) && !overwrite) { kept.push(n.id); continue; }
|
|
153
|
+
copyFileSync(n.file, target);
|
|
154
|
+
written.push(n.id);
|
|
155
|
+
}
|
|
156
|
+
const manifestSrc = path.join(packagedDir, "manifest.json");
|
|
157
|
+
const manifestDst = path.join(dir, "manifest.json");
|
|
158
|
+
if (existsSync(manifestSrc) && (overwrite || !existsSync(manifestDst))) copyFileSync(manifestSrc, manifestDst);
|
|
159
|
+
const readme = path.join(dir, "README.md");
|
|
160
|
+
if (overwrite || !existsSync(readme)) writeFileSync(readme, README.replace("N 份", `${packaged.length} 份`), "utf8");
|
|
161
|
+
return { dir, written, kept, count: packaged.length };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** 只读:副本里是否有内容(给「恢复默认」按钮判断要不要二次确认)。 */
|
|
165
|
+
export function projectNormsPresent(workspacePath) {
|
|
166
|
+
const dir = projectNormsDir(workspacePath);
|
|
167
|
+
return Boolean(dir && hasMarkdown(dir));
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** 读一份规范正文(给配置页「预览」用;不做任何写)。 */
|
|
171
|
+
export function readNormFile(dir, file) {
|
|
172
|
+
const base = path.basename(String(file ?? ""));
|
|
173
|
+
if (!base.endsWith(".md")) throw new TbError("USAGE_ERROR", "只允许读 .md");
|
|
174
|
+
const target = path.join(dir, base);
|
|
175
|
+
if (!existsSync(target)) throw new TbError("NORM_NOT_FOUND", `规范文件不存在:${base}`);
|
|
176
|
+
return readFileSync(target, "utf8");
|
|
177
|
+
}
|
|
@@ -290,3 +290,41 @@ export function summarizeRequirementCompletion(tasks = []) {
|
|
|
290
290
|
}
|
|
291
291
|
return { total, closed, active, counts, verdict, ready, text, tasks: list };
|
|
292
292
|
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* 条目详情的**完整性形态**(`R159` D-1=`c` / D-3=派生,2026-11-04 人拍)。
|
|
296
|
+
*
|
|
297
|
+
* 为什么是派生而不是落库:判据客观(长度 + 末字符 + 归类前缀),随数据自动更新,
|
|
298
|
+
* 不需要迁移与历史回填;真要「人工豁免某一条」时再升级成字段。
|
|
299
|
+
*
|
|
300
|
+
* 三态(顺序有意义 —— 镜像优先,因为镜像是**设计上限**而不是事故):
|
|
301
|
+
* · `mirror` —— 文档镜像/归类归档条目(`【归类 YYYY-MM-DD · …】非需求条目`),正文本来就是片段;
|
|
302
|
+
* · `truncated` —— 正文被 2000 字符截断的残片(早期导入 `slice(0,2000)` 的历史损伤);
|
|
303
|
+
* · `full` —— 其余(含空描述:那是另一种缺口,由 `acceptanceSet` 负责,不是残片)。
|
|
304
|
+
*
|
|
305
|
+
* ⚠️ 只判「形状」,不读盘 ⇒ 判不出「源文已演进 / 源档缺失」(那两条要 cwd + 文件比对,
|
|
306
|
+
* 只在一次性分析工具里做,见 docs/进度/2026-11-04-R159判据说明与R160范围扩写.md §A4)。
|
|
307
|
+
*/
|
|
308
|
+
export const DETAIL_STATES = Object.freeze(["full", "truncated", "mirror"]);
|
|
309
|
+
|
|
310
|
+
/** 2000 字符截断的**下界**(实测 1999/2000 都有,留 10 字符容差)。 */
|
|
311
|
+
export const TRUNCATED_MIN_LEN = 1990;
|
|
312
|
+
|
|
313
|
+
/** 句读/收尾字符:末字符属于它就不算被截断(`|` `>` 是 markdown 表格行尾)。 */
|
|
314
|
+
const SENTENCE_END_CHARS = new Set([..."。!?…;))】」』”\"'.:;!?]`|>"]);
|
|
315
|
+
|
|
316
|
+
const MIRROR_PREFIX = /^【归类\s*\d{4}-\d{2}-\d{2}\s*·/;
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* @param {string|null|undefined} description
|
|
320
|
+
* @returns {"full"|"truncated"|"mirror"}
|
|
321
|
+
*/
|
|
322
|
+
export function deriveDetailState(description) {
|
|
323
|
+
const text = typeof description === "string" ? description : "";
|
|
324
|
+
const head = text.trimStart();
|
|
325
|
+
if (MIRROR_PREFIX.test(head)) return "mirror";
|
|
326
|
+
const trimmed = text.trimEnd();
|
|
327
|
+
if (trimmed === "") return "full";
|
|
328
|
+
if (trimmed.length >= TRUNCATED_MIN_LEN && !SENTENCE_END_CHARS.has(trimmed.at(-1))) return "truncated";
|
|
329
|
+
return "full";
|
|
330
|
+
}
|