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/contract.mjs
CHANGED
|
@@ -22,8 +22,14 @@ import path from "node:path";
|
|
|
22
22
|
|
|
23
23
|
import { TbError } from "./errors.mjs";
|
|
24
24
|
|
|
25
|
-
/**
|
|
26
|
-
|
|
25
|
+
/**
|
|
26
|
+
* 随包分发的机器规范(缺一份即 `NORM_NOT_FOUND`)。
|
|
27
|
+
*
|
|
28
|
+
* `item-detail`(卡 `-216` / 需求 `R160`,2026-11-04):`docs/规范/07-条目详情规范.md` 的随包机器版 ——
|
|
29
|
+
* `docs/` 被 gitignore ⇒ 没有 git 历史、不进包、没有 version/digest,`NORM_STALE` 护不到它;
|
|
30
|
+
* 收进这里之后它才真正参与 `contract_version`。
|
|
31
|
+
*/
|
|
32
|
+
export const NORM_IDS = Object.freeze(["flow", "card-update", "doc-editing", "acceptance", "project-defaults", "item-detail"]);
|
|
27
33
|
|
|
28
34
|
/** 参与 contract_version 的门配置项(顺序固定 ⇒ 可复现)。 */
|
|
29
35
|
export const GATE_NAMES = Object.freeze(["attribution", "authorization", "review", "humanReview"]);
|
|
@@ -40,9 +46,12 @@ export function sha256(text) {
|
|
|
40
46
|
* 只认最小 YAML 子集(`key: value` / `key: [a, b]` / 数字 / 引号串)——本仓规范就是这么写的,
|
|
41
47
|
* 引完整 YAML 解析器会把「机器规范的形状」变成第三方依赖的版本风险。
|
|
42
48
|
*
|
|
49
|
+
* `allowUnknown`:只给**项目副本**用 —— 用户在自己目录里多放一份 `notes.md` 不该把整个看板炸掉
|
|
50
|
+
* (卡 `-216`:宁可忽略陌生文件,也不要 `NORM_INVALID` 把读写全挡了)。
|
|
51
|
+
*
|
|
43
52
|
* @returns {{meta:{norm_id:string,version:number,updated:string,applies_to:string[]}, body:string, digest:string}}
|
|
44
53
|
*/
|
|
45
|
-
export function parseNormDoc(text, file = "<norm>") {
|
|
54
|
+
export function parseNormDoc(text, file = "<norm>", { allowUnknown = false } = {}) {
|
|
46
55
|
const raw = String(text ?? "").replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
|
|
47
56
|
if (!raw.startsWith("---\n")) throw new TbError("NORM_INVALID", `规范缺 frontmatter:${file}`, { file });
|
|
48
57
|
const end = raw.indexOf("\n---\n", 4);
|
|
@@ -58,7 +67,7 @@ export function parseNormDoc(text, file = "<norm>") {
|
|
|
58
67
|
meta[key] = parseScalar(line.slice(idx + 1).trim());
|
|
59
68
|
}
|
|
60
69
|
const normId = String(meta.norm_id ?? "");
|
|
61
|
-
if (!NORM_IDS.includes(normId)) {
|
|
70
|
+
if (!NORM_IDS.includes(normId) && !allowUnknown) {
|
|
62
71
|
throw new TbError("NORM_INVALID", `规范 norm_id 非法:${file} · ${JSON.stringify(meta.norm_id)}`, { file, allowed: NORM_IDS });
|
|
63
72
|
}
|
|
64
73
|
if (!Number.isInteger(meta.version) || meta.version < 1) {
|
|
@@ -93,16 +102,17 @@ function stripQuotes(s) {
|
|
|
93
102
|
* 读一个规范目录(`spec/norms/*.md`)。
|
|
94
103
|
*
|
|
95
104
|
* @param {string} dir
|
|
96
|
-
* @param {{requireAll?: boolean}} [opts] `requireAll`(默认 true
|
|
105
|
+
* @param {{requireAll?: boolean}} [opts] `requireAll`(默认 true)=`NORM_IDS` 必须齐;单测造夹具与
|
|
106
|
+
* **读项目副本**(缺项要逐份回落包内)时必须传 `false`。
|
|
97
107
|
*/
|
|
98
|
-
export function loadNorms(dir, { requireAll = true } = {}) {
|
|
108
|
+
export function loadNorms(dir, { requireAll = true, allowUnknown = false } = {}) {
|
|
99
109
|
if (!dir || !existsSync(dir)) throw new TbError("NORM_NOT_FOUND", `机器规范目录不存在:${dir}`, { dir });
|
|
100
110
|
const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
|
|
101
111
|
const norms = [];
|
|
102
112
|
const seen = new Map();
|
|
103
113
|
for (const file of files) {
|
|
104
114
|
const abs = path.join(dir, file);
|
|
105
|
-
const parsed = parseNormDoc(readFileSync(abs, "utf8"), abs);
|
|
115
|
+
const parsed = parseNormDoc(readFileSync(abs, "utf8"), abs, { allowUnknown });
|
|
106
116
|
const prev = seen.get(parsed.meta.norm_id);
|
|
107
117
|
if (prev) throw new TbError("NORM_INVALID", `norm_id 重复:${parsed.meta.norm_id}(${prev} / ${abs})`, { normId: parsed.meta.norm_id });
|
|
108
118
|
seen.set(parsed.meta.norm_id, abs);
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* data-dir-hint.mjs —— 「你这个库是空的,但旧默认目录里还有数据」的**只读**检测(卡 `-236` / 需求 `R173`)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么需要它:默认目录从 `os.tmpdir()/tb-workbench-mvp-a` 改到 `~/.dsh/data/taskboard-workbench` 之后,
|
|
5
|
+
* 老用户的卡还在旧目录里。如果只是静默换目录,用户看到的就是「升级后看板全空」——比原来的 bug 更吓人。
|
|
6
|
+
* 所以启动时做一次**只读**对照:新库 0 张卡 + 旧库有卡 ⇒ 打一条明确的迁移提示(并在 /api/health 里带出来)。
|
|
7
|
+
*
|
|
8
|
+
* 边界(都很硬):
|
|
9
|
+
* - **不复制、不删除、不写入**旧库;只读打开 + 一条 count。旧库打开失败一律当"没有提示",绝不打断启动。
|
|
10
|
+
* - 新库已经有卡 ⇒ 不提示(用户显然已在用新目录)。
|
|
11
|
+
* - 两个目录相同(用户显式把 dataDir 指回旧目录)⇒ 不提示。
|
|
12
|
+
*/
|
|
13
|
+
import { existsSync } from "node:fs";
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
import { DatabaseSync } from "node:sqlite";
|
|
16
|
+
|
|
17
|
+
import { DB_FILENAME, LEGACY_DATA_DIR } from "./config.mjs";
|
|
18
|
+
|
|
19
|
+
export function detectLegacyDataHint({
|
|
20
|
+
dataDir,
|
|
21
|
+
activeTaskCount = 0,
|
|
22
|
+
legacyDir = LEGACY_DATA_DIR,
|
|
23
|
+
dbFilename = DB_FILENAME,
|
|
24
|
+
} = {}) {
|
|
25
|
+
if (!dataDir || !legacyDir) return null;
|
|
26
|
+
if (path.resolve(String(dataDir)) === path.resolve(String(legacyDir))) return null;
|
|
27
|
+
if (Number(activeTaskCount) > 0) return null;
|
|
28
|
+
|
|
29
|
+
const legacyDbPath = path.join(legacyDir, dbFilename);
|
|
30
|
+
if (!existsSync(legacyDbPath)) return null;
|
|
31
|
+
|
|
32
|
+
let legacyTaskCount = 0;
|
|
33
|
+
try {
|
|
34
|
+
const db = new DatabaseSync(legacyDbPath, { readOnly: true });
|
|
35
|
+
try {
|
|
36
|
+
const row = db.prepare("select count(*) as n from tasks").get();
|
|
37
|
+
legacyTaskCount = Number(row?.n ?? 0);
|
|
38
|
+
} finally { db.close(); }
|
|
39
|
+
} catch {
|
|
40
|
+
return null; // 旧库读不开(权限 / 损坏 / 不是本插件库)⇒ 不当提示,更不当错误
|
|
41
|
+
}
|
|
42
|
+
if (legacyTaskCount <= 0) return null;
|
|
43
|
+
|
|
44
|
+
return {
|
|
45
|
+
reason: "EMPTY_ACTIVE_WITH_LEGACY_DATA",
|
|
46
|
+
dataDir: path.resolve(String(dataDir)),
|
|
47
|
+
legacyDir: path.resolve(String(legacyDir)),
|
|
48
|
+
legacyDbPath,
|
|
49
|
+
legacyTaskCount,
|
|
50
|
+
hint: `当前数据目录(${path.resolve(String(dataDir))})没有任务,但旧默认目录 ${legacyDir} 里有 ${legacyTaskCount} 张卡。要看旧数据:把 dataDir 指回旧目录(TB_DATA_DIR=… 或插件配置 dataDir),或自行把 ${dbFilename} 复制过来后重启。本插件不会自动搬库。`,
|
|
51
|
+
};
|
|
52
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 随包人读文档(`spec/docs/`)与**项目副本**的位置解析 / 物化 —— 卡 `-220` / 需求 `R161`
|
|
3
|
+
*
|
|
4
|
+
* ## 与 `norms.mjs` 的分工(别合并)
|
|
5
|
+
* - `norms.mjs`:**机器规范**(`spec/norms/`)。它的正文被 digest 进契约 ⇒ 改正文必须 bump
|
|
6
|
+
* `version`,否则写操作按旧契约被拦。它是**会改变系统行为**的那一份。
|
|
7
|
+
* - 本文件:**人读文档**(`spec/docs/`,开局 / 流程 / 条目 + 模板)。改了**不影响契约、不影响门禁**,
|
|
8
|
+
* 只是「照着做」的说明书。两者放同一张配置卡会让人以为改文档会改行为,所以刻意分开。
|
|
9
|
+
*
|
|
10
|
+
* ## 三处位置(用户要的「可查可看可改」)
|
|
11
|
+
* 1. **包内默认**:随包(`<安装目录>/spec/docs`)—— 只读,升级即被覆盖;
|
|
12
|
+
* 2. **项目存放**:默认 `<工作区>/.taskboard/docs`,**可改**(项目设置 `envConfig.docsDir`);
|
|
13
|
+
* 3. **生效来源**:项目副本存在时以它为准;否则回落包内(逐文件比对,缺的从包内列出来)。
|
|
14
|
+
*
|
|
15
|
+
* ## 纪律
|
|
16
|
+
* - 物化**只在显式调用时**发生(`materializeProjectDocs`),建项目不静默写用户工作区;
|
|
17
|
+
* - 已存在的文件默认**不覆盖**(`kept`),要覆盖必须显式 `overwrite: true`(「恢复默认」按钮);
|
|
18
|
+
* - 目录可不存在:视图层如实回 `exists: false`,不替用户创建。
|
|
19
|
+
*/
|
|
20
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
|
|
21
|
+
import path from "node:path";
|
|
22
|
+
|
|
23
|
+
import { TbError } from "./errors.mjs";
|
|
24
|
+
|
|
25
|
+
/** 项目副本相对工作区的默认位置。 */
|
|
26
|
+
export const PROJECT_DOCS_SUBDIR = path.join(".taskboard", "docs");
|
|
27
|
+
|
|
28
|
+
/** 副本目录里用的 README(**新增**于副本,不进包内默认目录,避免包内多一份自述)。 */
|
|
29
|
+
const PROJECT_README = `# 本项目的开局与流程文档(可改)
|
|
30
|
+
|
|
31
|
+
这里是**本项目的副本**,来源是任务工作台随包分发的默认文档(开局 / 流程 / 条目 + 模板)。
|
|
32
|
+
看板「文档与规范位置」优先读这里;缺哪份就回落用安装包里那份(不会报错)。
|
|
33
|
+
|
|
34
|
+
- 改这里的 \`.md\` **不会**改变看板行为(门禁与契约只吃 \`spec/norms/\` 的机器规范);
|
|
35
|
+
- 这些文档是写给人看的:可以直接按自己项目的习惯改,删到只剩需要的几份也行;
|
|
36
|
+
- 要不要把本目录 \`git add\` 进仓库由你定:想团队共享就入库,只想本机生效就加进 \`.gitignore\`。
|
|
37
|
+
`;
|
|
38
|
+
|
|
39
|
+
/** @param {string|null|undefined} workspacePath */
|
|
40
|
+
export function projectDocsDir(workspacePath) {
|
|
41
|
+
const ws = typeof workspacePath === "string" ? workspacePath.trim() : "";
|
|
42
|
+
if (!ws) return null;
|
|
43
|
+
return path.join(ws, PROJECT_DOCS_SUBDIR);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* 覆盖目录解析:绝对路径直接用;相对路径按工作区解析(空 ⇒ null = 用默认)。
|
|
48
|
+
* 之所以允许相对:项目里常想写 `.taskboard/docs` 这种可入库的路径,而不是钉死本机绝对路径。
|
|
49
|
+
*/
|
|
50
|
+
export function resolveOverrideDir(overrideDir, workspacePath) {
|
|
51
|
+
const raw = typeof overrideDir === "string" ? overrideDir.trim() : "";
|
|
52
|
+
if (!raw) return null;
|
|
53
|
+
if (path.isAbsolute(raw)) return path.normalize(raw);
|
|
54
|
+
const ws = typeof workspacePath === "string" ? workspacePath.trim() : "";
|
|
55
|
+
if (!ws) throw new TbError("WORKSPACE_MISSING", "存放位置写的是相对路径,但项目未配置工作区目录 ⇒ 无法解析");
|
|
56
|
+
return path.normalize(path.join(ws, raw));
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** 递归列 md(副本里可能有 assets/ 子目录)。 */
|
|
60
|
+
export function listDocs(dir) {
|
|
61
|
+
if (!dir || !existsSync(dir)) return [];
|
|
62
|
+
const out = [];
|
|
63
|
+
const walk = (d, base) => {
|
|
64
|
+
for (const name of readdirSync(d).sort()) {
|
|
65
|
+
const abs = path.join(d, name);
|
|
66
|
+
if (statSync(abs).isDirectory()) walk(abs, base);
|
|
67
|
+
else if (name.endsWith(".md")) out.push(path.relative(base, abs));
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
walk(dir, dir);
|
|
71
|
+
return out.sort();
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* 只读视图:包内默认 / 项目存放 / 生效来源。
|
|
76
|
+
* @param {{packagedDir:string, workspacePath?:string|null, overrideDir?:string|null}} input
|
|
77
|
+
*/
|
|
78
|
+
export function docsView({ packagedDir, workspacePath = null, overrideDir = null }) {
|
|
79
|
+
const defaultDir = projectDocsDir(workspacePath);
|
|
80
|
+
const resolvedOverride = resolveOverrideDir(overrideDir, workspacePath);
|
|
81
|
+
const projectDir = resolvedOverride ?? defaultDir;
|
|
82
|
+
const packagedFiles = listDocs(packagedDir);
|
|
83
|
+
const projectFiles = listDocs(projectDir);
|
|
84
|
+
const hasProjectCopy = projectFiles.length > 0;
|
|
85
|
+
return {
|
|
86
|
+
packaged: { dir: packagedDir, files: packagedFiles },
|
|
87
|
+
project: {
|
|
88
|
+
dir: projectDir,
|
|
89
|
+
dirIsOverride: Boolean(resolvedOverride),
|
|
90
|
+
exists: Boolean(projectDir && existsSync(projectDir)),
|
|
91
|
+
files: projectFiles,
|
|
92
|
+
},
|
|
93
|
+
effective: hasProjectCopy ? { source: "project", dir: projectDir } : { source: "packaged", dir: packagedDir },
|
|
94
|
+
missingInProject: hasProjectCopy ? packagedFiles.filter((f) => !projectFiles.includes(f)) : [],
|
|
95
|
+
workspacePath: workspacePath ?? null,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* 把包内默认文档复制成项目副本(显式动作)。
|
|
101
|
+
* @param {{packagedDir:string, workspacePath?:string|null, overrideDir?:string|null, overwrite?:boolean}} input
|
|
102
|
+
*/
|
|
103
|
+
export function materializeProjectDocs({ packagedDir, workspacePath = null, overrideDir = null, overwrite = false }) {
|
|
104
|
+
const resolvedOverride = resolveOverrideDir(overrideDir, workspacePath);
|
|
105
|
+
const dir = resolvedOverride ?? projectDocsDir(workspacePath);
|
|
106
|
+
if (!dir) throw new TbError("WORKSPACE_MISSING", "项目未配置工作区目录 ⇒ 无法生成文档副本;请先在「配置 → 当前绑定」填工作区");
|
|
107
|
+
if (!existsSync(packagedDir)) throw new TbError("DOCS_NOT_FOUND", `随包文档目录不存在:${packagedDir}`);
|
|
108
|
+
mkdirSync(dir, { recursive: true });
|
|
109
|
+
const written = []; const kept = [];
|
|
110
|
+
for (const rel of listDocs(packagedDir)) {
|
|
111
|
+
const target = path.join(dir, rel);
|
|
112
|
+
if (existsSync(target) && !overwrite) { kept.push(rel); continue; }
|
|
113
|
+
mkdirSync(path.dirname(target), { recursive: true });
|
|
114
|
+
copyFileSync(path.join(packagedDir, rel), target);
|
|
115
|
+
written.push(rel);
|
|
116
|
+
}
|
|
117
|
+
const readme = path.join(dir, "README.md");
|
|
118
|
+
// 包内也有 README:上面已复制成包内版本;这里只在「包内没有 README」时补项目自述,避免互相覆盖。
|
|
119
|
+
if (!existsSync(readme)) { writeText(readme, PROJECT_README); written.push("README.md"); }
|
|
120
|
+
return { dir, written, kept, count: listDocs(dir).length };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
function writeText(abs, text) {
|
|
124
|
+
mkdirSync(path.dirname(abs), { recursive: true });
|
|
125
|
+
writeFileSync(abs, text, "utf8");
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** 读一份文档正文(配置页「看一眼」用,只读)。 */
|
|
129
|
+
export function readDocFile(dir, rel) {
|
|
130
|
+
const safe = String(rel ?? "").replace(/^[/\\]+/, "");
|
|
131
|
+
if (!safe || safe.includes("..")) throw new TbError("USAGE_ERROR", "非法文档路径");
|
|
132
|
+
const abs = path.join(dir, safe);
|
|
133
|
+
if (!existsSync(abs)) throw new TbError("DOCS_NOT_FOUND", `文档不存在:${safe}`);
|
|
134
|
+
return { file: safe, text: readFileSync(abs, "utf8") };
|
|
135
|
+
}
|
package/src/core/errors.mjs
CHANGED
|
@@ -88,6 +88,8 @@ export const ERROR_CATEGORY = Object.freeze({
|
|
|
88
88
|
AGENT_CANNOT_FINALIZE: EXIT.DATA,
|
|
89
89
|
|
|
90
90
|
// 冲突
|
|
91
|
+
// 卡 `-229`(R170):开局缺口投递时项目还没绑主会话 ⇒ 冲突类(先绑/重建主会话再重试;非数据错误)
|
|
92
|
+
NO_MAIN_SESSION: EXIT.CONFLICT,
|
|
91
93
|
VERSION_CONFLICT: EXIT.CONFLICT,
|
|
92
94
|
PROJECT_EXISTS: EXIT.CONFLICT,
|
|
93
95
|
// FR-03:非空项目不得删除(仍有任务/需求条目/需求文档正文)⇒ 冲突,须先清空
|
|
@@ -96,6 +98,15 @@ export const ERROR_CATEGORY = Object.freeze({
|
|
|
96
98
|
REQ_IDENTIFIER_CONFLICT: EXIT.CONFLICT,
|
|
97
99
|
DEPENDENCY_EXISTS: EXIT.CONFLICT,
|
|
98
100
|
DOC_EXISTS: EXIT.CONFLICT,
|
|
101
|
+
// 卡 `-238`(R174):执行者按卡选择 —— 三种「选不了」必须**分开报**,否则人分不清该去装 CLI、
|
|
102
|
+
// 还是去改项目设置(forbiddenExecutors 优先级最高)。
|
|
103
|
+
EXECUTOR_UNKNOWN: EXIT.USAGE,
|
|
104
|
+
EXECUTOR_NOT_INSTALLED: EXIT.USAGE,
|
|
105
|
+
EXECUTOR_FORBIDDEN: EXIT.USAGE,
|
|
106
|
+
// 选了一个「不是 CLI 形态」的执行者(team / host-session)却打到 exec-cli 上 ⇒ 用法错误,并指路正确入口
|
|
107
|
+
EXECUTOR_NOT_CLI: EXIT.USAGE,
|
|
108
|
+
// 卡 `-237`(R173):同一个库同一时刻只允许一个写者;follower 的所有写操作一律 409。
|
|
109
|
+
FOLLOWER_READ_ONLY: EXIT.CONFLICT,
|
|
99
110
|
});
|
|
100
111
|
|
|
101
112
|
/** 领域错误:带 code / 退出码 / 可选细节。 */
|
package/src/core/evidence.mjs
CHANGED
|
@@ -10,6 +10,16 @@ import path from "node:path";
|
|
|
10
10
|
import { execFileSync } from "node:child_process";
|
|
11
11
|
|
|
12
12
|
export const EVIDENCE_FIELDS = Object.freeze(["verdict", "deviation", "boundary", "artifacts"]);
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* `kind` 的**唯一枚举**(FR-106 · 0-B-b):证据条目可用的五类。
|
|
16
|
+
* 为什么要收在一处:MCP 的 `card_progress.evidence[]`、MCP 的 `card_evidence_submit`、
|
|
17
|
+
* HTTP 的 `POST /api/tasks/:ref/evidence` 三个入口都要判同一套值 ——
|
|
18
|
+
* 各写一份必然漂移(此前 tools.mjs 里就有一份只到 `reading` 的副本)。
|
|
19
|
+
*/
|
|
20
|
+
export const EVIDENCE_KINDS = Object.freeze(["file", "command", "url", "reading", "commit"]);
|
|
21
|
+
|
|
22
|
+
/** 真正参与 `artifact_refs` 核验的 kind(其余**逐条不进** `artifact_refs` ⇒ 行级 `unchecked`)。 */
|
|
13
23
|
export const EVIDENCE_REF_KINDS = Object.freeze(["commit", "file"]);
|
|
14
24
|
|
|
15
25
|
const text = (v) => (typeof v === "string" ? v.trim() : "");
|
|
@@ -39,6 +49,24 @@ export function normalizeArtifactRefs(refs) {
|
|
|
39
49
|
return out;
|
|
40
50
|
}
|
|
41
51
|
|
|
52
|
+
/**
|
|
53
|
+
* **入口层**白名单校验(FR-106 第 3 条):`artifact_refs[].kind` 不在 `{commit,file}` 内就**显式报错**。
|
|
54
|
+
*
|
|
55
|
+
* 与 `normalizeArtifactRefs` 的分工必须区分清楚:
|
|
56
|
+
* · **规则层**(`normalizeArtifactRefs`)继续**静默丢弃**非法项 —— 契约不变,`tests/task-evidence.test.mjs` D 组钉着;
|
|
57
|
+
* · **入口层**(MCP / HTTP 的写入口)先跑这里,非法即整笔拒(`INVALID_ARTIFACT_REF`)⇒ 调用方拿得到真原因。
|
|
58
|
+
* 只在入口层做,是为了不改动任何既有规则层行为。
|
|
59
|
+
*/
|
|
60
|
+
export function artifactRefKindProblems(refs) {
|
|
61
|
+
if (!Array.isArray(refs)) return [];
|
|
62
|
+
const bad = [];
|
|
63
|
+
refs.forEach((r, index) => {
|
|
64
|
+
const kind = text(r?.kind);
|
|
65
|
+
if (!EVIDENCE_REF_KINDS.includes(kind)) bad.push({ index, kind: kind || null, allowedKinds: [...EVIDENCE_REF_KINDS] });
|
|
66
|
+
});
|
|
67
|
+
return bad;
|
|
68
|
+
}
|
|
69
|
+
|
|
42
70
|
/**
|
|
43
71
|
* 核验 `artifact_refs`:任一解不开即整体 `unresolved`(不"部分通过")。
|
|
44
72
|
* `resolve({kind, ref})` 由调用方注入 —— 默认实现见 `makeResolver`。
|
package/src/core/executor.mjs
CHANGED
|
@@ -96,6 +96,11 @@ export function cliArgsFor({ executorId, cwd, settings }) {
|
|
|
96
96
|
*/
|
|
97
97
|
export const EDIT_PERMISSION_HINTS = Object.freeze([
|
|
98
98
|
"acceptEdits", "bypassPermissions", "--dangerously-skip-permissions",
|
|
99
|
+
// 卡 `-238`:判据从「只认 claude 的写法」扩到「**任一 CLI 的显式写权限**」——
|
|
100
|
+
// codex 的 `-s workspace-write` / `--dangerously-bypass-approvals-and-sandbox`、
|
|
101
|
+
// hermes 的 `--yolo` 都是「允许落盘」的明示开关。这几个 token 语义单一,
|
|
102
|
+
// 扩进来只会**减少**误判成「盲跑」,不会把只读参数误认成可写。
|
|
103
|
+
"workspace-write", "danger-full-access", "--yolo",
|
|
99
104
|
]);
|
|
100
105
|
|
|
101
106
|
export function argsAllowEdits(args) {
|
|
@@ -423,16 +428,25 @@ export async function runCliExecutor({
|
|
|
423
428
|
timeoutMs = DEFAULT_TIMEOUT_MS, spawnImpl = spawn, env = process.env, now = () => Date.now(),
|
|
424
429
|
verifyCommand = null, requirementId = null,
|
|
425
430
|
store = null, heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS,
|
|
431
|
+
// 卡 `-238`(R174):按卡选执行者时,参数与「指令怎么给」由**注册表**决定,不再写死 claude 那套。
|
|
432
|
+
// 两者缺省即老行为(`cliArgsFor` + stdin),**零回归**。
|
|
433
|
+
argsOverride = null, promptVia = "stdin",
|
|
426
434
|
} = {}) {
|
|
427
435
|
if (!executor?.cli) return { started: false, reason: "no-cli-executor" };
|
|
428
436
|
const workdir = cwd ?? project?.workspacePath ?? null;
|
|
429
437
|
if (!workdir) return { started: false, reason: "no-workspace", executorId: executor.id };
|
|
430
438
|
// 测试/离线替身:`TB_CLI_EXECUTOR_BIN` 指定可执行文件时优先使用(不改 executor id 语义)。
|
|
431
|
-
|
|
439
|
+
// `binPath` 优先于裸命令名:宿主由 launchd 拉起时 PATH 常缺 `~/.npm-global/bin`,
|
|
440
|
+
// 只写命令名会在 `exec-cli` 真跑时报 ENOENT(探测到绝对路径就用它)。
|
|
441
|
+
// `TB_CLI_EXECUTOR_BIN` 仍是最高优先(测试/离线替身语义不变)。
|
|
442
|
+
const cli = String(env?.TB_CLI_EXECUTOR_BIN ?? "") || executor.binPath || executor.cli;
|
|
432
443
|
const prompt = buildTaskPrompt(task, { project, requirementId, verifyCommand });
|
|
433
|
-
const
|
|
444
|
+
const explicitArgs = Array.isArray(argsOverride) && argsOverride.length ? argsOverride.map(String) : null;
|
|
445
|
+
const args = explicitArgs ?? cliArgsFor({ executorId: executor.id, cwd: workdir, settings });
|
|
434
446
|
// 参数来源与「能不能写文件」都要如实记进结果(证据与状态都取它,见 isBlindRun)。
|
|
435
|
-
|
|
447
|
+
// `executor` 档=按卡选执行者时注册表给的参数(非 claude 的 CLI 只有这一种来源)。
|
|
448
|
+
const argsSource = explicitArgs ? "executor"
|
|
449
|
+
: (Array.isArray(settings?.teamTemplate?.engineer?.args) && settings.teamTemplate.engineer.args.length) ? "override" : "default";
|
|
436
450
|
const startedAt = now();
|
|
437
451
|
// 基线快照(脏仓库下用于算"本次真实产出")。
|
|
438
452
|
// 拿不到基线**不得静默继续**:在结果上打 `baseline: "unavailable"`,证据评论里显式告警,
|
|
@@ -444,7 +458,7 @@ export async function runCliExecutor({
|
|
|
444
458
|
let beforeSnap = null;
|
|
445
459
|
if (!before) { try { beforeSnap = await snapshotWorkspace(workdir); } catch { beforeSnap = null; } }
|
|
446
460
|
const baseline = before ? "git" : beforeSnap ? "fs" : "unavailable";
|
|
447
|
-
const result = { started: true, executorId: executor.id, cli, cwd: workdir, args, argsSource, argsAllowsEdits: argsAllowEdits(args), baseline, exitCode: null, signal: null, timedOut: false, durationMs: 0, stdout: "", stderr: "", diff: null, ok: false };
|
|
461
|
+
const result = { started: true, executorId: executor.id, cli, cwd: workdir, args, argsSource, argsAllowsEdits: argsAllowEdits(args), promptVia, baseline, exitCode: null, signal: null, timedOut: false, durationMs: 0, stdout: "", stderr: "", diff: null, ok: false };
|
|
448
462
|
// ---- 执行期心跳(2026-10-22 真机 `-122`)----
|
|
449
463
|
// 子进程活着期间必须持续续命认领锁:否则心跳停在开跑那刻,10 分钟后 `claim.stale=true`、
|
|
450
464
|
// 看护按 `session-offline` 判 `stalled/high`,主按钮变「退回待办(重新派发)」——
|
|
@@ -479,8 +493,10 @@ export async function runCliExecutor({
|
|
|
479
493
|
child.stdout?.on("data", (b) => { result.stdout += String(b); });
|
|
480
494
|
child.stderr?.on("data", (b) => { result.stderr += String(b); });
|
|
481
495
|
child.on?.("close", (code, signal) => { clearTimeout(timer); result.exitCode = code; result.signal = signal ?? null; finish(); });
|
|
482
|
-
//
|
|
483
|
-
|
|
496
|
+
// 指令投递:默认走 stdin(避免超长命令行);`promptVia=argv` 的 CLI(hermes `-z <prompt>`)
|
|
497
|
+
// 指令已经在参数里,**不再往 stdin 写**(写了它也不读,白占缓冲),但仍要 end() 收口,
|
|
498
|
+
// 否则子进程等 stdin EOF 会挂到超时。
|
|
499
|
+
try { if (promptVia !== "argv") child.stdin?.write(prompt); child.stdin?.end(); } catch { /* ignore */ }
|
|
484
500
|
});
|
|
485
501
|
} finally {
|
|
486
502
|
stopHeartbeat();
|
|
@@ -600,13 +616,17 @@ export function evidenceComment(task, result, { actor = "cli-executor" } = {}) {
|
|
|
600
616
|
export async function executeTaskWithCli({
|
|
601
617
|
store, task, project, settings = null, role = "engineer", timeoutMs = DEFAULT_TIMEOUT_MS,
|
|
602
618
|
spawnImpl = spawn, env = process.env, now = () => Date.now(), heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS,
|
|
619
|
+
// 卡 `-238`:显式选定的执行者(及其参数)优先于「项目配置解析出来的那个」。
|
|
620
|
+
// 不传时**逐字节**走老路径 —— 项目级配置仍是默认口径。
|
|
621
|
+
resolvedExecutor = null, argsOverride = null, promptVia = "stdin",
|
|
603
622
|
} = {}) {
|
|
604
|
-
const executor = resolveCliExecutor(settings ?? store.getProjectSettings(task.projectId), { role });
|
|
623
|
+
const executor = resolvedExecutor ?? resolveCliExecutor(settings ?? store.getProjectSettings(task.projectId), { role });
|
|
605
624
|
if (!executor) return { ran: false, reason: "no-cli-executor" };
|
|
606
625
|
const verifyCommand = settings?.teamTemplate?.engineer?.verifyCommand ?? null;
|
|
607
626
|
const result = await runCliExecutor({
|
|
608
627
|
task, project, executor, settings, timeoutMs, spawnImpl, env, now,
|
|
609
628
|
verifyCommand, requirementId: task.requirementId ?? null, store, heartbeatIntervalMs,
|
|
629
|
+
argsOverride, promptVia,
|
|
610
630
|
});
|
|
611
631
|
const body = evidenceComment(task, result);
|
|
612
632
|
let review = null; let blocked = null;
|