dsh-taskboard 0.3.3 → 0.4.1

package/lib/host/templates.js

@@ -0,0 +1,166 @@
+import { readFile } from "node:fs/promises";
+//#region src/host/templates.ts
+/**
+* Host-side task-template store (0.4.0): one JSON side file next to the
+* ledger, seeded with the built-in templates on first load, mutated through
+* the same atomic persist discipline as the ledger.
+*
+* Pure data, no Cordis deps — the routes layer owns it and tests drive it
+* directly against a temp dir.
+*
+* @module dsh-taskboard/host/templates
+*/
+/** The built-in templates seeded when the side file does not exist yet. */
+const BUILTIN_TEMPLATES = [
+	{
+		id: "tpl-bugfix",
+		name: "Bug 修复",
+		task: {
+			title: "修复：",
+			prompt: [
+				"修复以下问题并按序交接：",
+				"1. 复现问题（写最小复现步骤或测试）",
+				"2. 定位根因，说明为什么会发生",
+				"3. 修复并补回归测试",
+				"4. 运行相关测试套件确认无回归"
+			].join("\n"),
+			urgency: "urgent",
+			checklist: [
+				"已复现并定位根因",
+				"修复已提交到任务分支",
+				"回归测试通过"
+			]
+		}
+	},
+	{
+		id: "tpl-release",
+		name: "发布检查",
+		task: {
+			title: "发布：",
+			prompt: "执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。",
+			urgency: "normal",
+			checklist: [
+				"版本号已更新（package.json 与版本常量同步）",
+				"构建通过",
+				"全部测试通过",
+				"变更记录已写"
+			]
+		}
+	},
+	{
+		id: "tpl-patrol",
+		name: "例行巡检",
+		task: {
+			title: "巡检：",
+			prompt: [
+				"例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。",
+				"发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。",
+				"输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。"
+			].join("\n"),
+			urgency: "relaxed",
+			execution: {
+				mode: "scheduled",
+				cron: "0 9 * * 1"
+			}
+		}
+	}
+];
+/** Mint a template id. */
+function newTemplateId() {
+	return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+* The template store. NOT thread-synchronized like the ledger (template
+* writes are rare, human-paced GUI operations; last-write-wins is fine).
+*/
+var TemplateStore = class {
+	file;
+	templates;
+	loaded = false;
+	/** @param file - absolute side-file path (next to the ledger). */
+	constructor(file) {
+		this.file = file;
+	}
+	/** Load once; a missing file seeds the built-ins; a corrupt file resets. */
+	async ensure() {
+		if (this.loaded) return;
+		let parsed;
+		try {
+			const raw = await readFile(this.file, "utf8");
+			const value = JSON.parse(raw);
+			if (Array.isArray(value.templates)) parsed = value.templates.filter((t) => typeof t === "object" && t !== null && typeof t.id === "string" && typeof t.name === "string" && typeof t.task === "object");
+		} catch {}
+		if (parsed === void 0) {
+			const now = Date.now();
+			parsed = BUILTIN_TEMPLATES.map((t, i) => ({
+				...t,
+				task: { ...t.task },
+				builtin: true,
+				createdAt: now,
+				updatedAt: now + i
+			}));
+			try {
+				await this.persist(parsed);
+			} catch {}
+		}
+		this.templates = parsed;
+		this.loaded = true;
+	}
+	/** Atomic persist (temp + rename), same discipline as the ledger. */
+	async persist(templates) {
+		const { mkdir, writeFile, rename } = await import("node:fs/promises");
+		const { dirname, join } = await import("node:path");
+		await mkdir(dirname(this.file), { recursive: true });
+		const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`);
+		await writeFile(temp, JSON.stringify({ templates }, null, 2), "utf8");
+		await rename(temp, this.file);
+	}
+	/** All templates (oldest first). */
+	async list() {
+		await this.ensure();
+		return (this.templates ?? []).slice();
+	}
+	/**
+	* Create or replace a template by id (a body without id creates).
+	* @returns the stored template.
+	*/
+	async upsert(input) {
+		await this.ensure();
+		const templates = this.templates ?? [];
+		const name = input.name.trim();
+		if (name.length === 0 || name.length > 60) throw new Error("模板名必须 1..60 字符");
+		const now = Date.now();
+		const existing = input.id !== void 0 ? templates.find((t) => t.id === input.id) : void 0;
+		const stored = existing !== void 0 ? {
+			...existing,
+			name,
+			task: input.task,
+			updatedAt: now
+		} : {
+			id: input.id ?? newTemplateId(),
+			name,
+			task: input.task,
+			createdAt: now,
+			updatedAt: now
+		};
+		const index = existing !== void 0 ? templates.indexOf(existing) : -1;
+		if (index >= 0) templates[index] = stored;
+		else templates.push(stored);
+		await this.persist(templates);
+		return stored;
+	}
+	/** Delete a template by id; returns whether it existed. */
+	async remove(id) {
+		await this.ensure();
+		const templates = this.templates ?? [];
+		const index = templates.findIndex((t) => t.id === id);
+		if (index < 0) return false;
+		templates.splice(index, 1);
+		await this.persist(templates);
+		return true;
+	}
+};
+//#endregion
+export { BUILTIN_TEMPLATES, TemplateStore };
+
+//# sourceMappingURL=templates.js.map

package/lib/host/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","names":[],"sources":["../../src/host/templates.ts"],"sourcesContent":["/**\n * Host-side task-template store (0.4.0): one JSON side file next to the\n * ledger, seeded with the built-in templates on first load, mutated through\n * the same atomic persist discipline as the ledger.\n *\n * Pure data, no Cordis deps — the routes layer owns it and tests drive it\n * directly against a temp dir.\n *\n * @module dsh-taskboard/host/templates\n */\nimport { readFile } from 'node:fs/promises'\nimport type { TaskTemplate } from '../shared/api.ts'\n\n/** The built-in templates seeded when the side file does not exist yet. */\nexport const BUILTIN_TEMPLATES: ReadonlyArray<{ id: string; name: string; task: TaskTemplate['task'] }> = [\n  {\n    id: 'tpl-bugfix',\n    name: 'Bug 修复',\n    task: {\n      title: '修复：',\n      prompt: [\n        '修复以下问题并按序交接：',\n        '1. 复现问题（写最小复现步骤或测试）',\n        '2. 定位根因，说明为什么会发生',\n        '3. 修复并补回归测试',\n        '4. 运行相关测试套件确认无回归',\n      ].join('\\n'),\n      urgency: 'urgent',\n      checklist: ['已复现并定位根因', '修复已提交到任务分支', '回归测试通过'],\n    },\n  },\n  {\n    id: 'tpl-release',\n    name: '发布检查',\n    task: {\n      title: '发布：',\n      prompt: '执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。',\n      urgency: 'normal',\n      checklist: ['版本号已更新（package.json 与版本常量同步）', '构建通过', '全部测试通过', '变更记录已写'],\n    },\n  },\n  {\n    id: 'tpl-patrol',\n    name: '例行巡检',\n    task: {\n      title: '巡检：',\n      prompt: [\n        '例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。',\n        '发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。',\n        '输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。',\n      ].join('\\n'),\n      urgency: 'relaxed',\n      execution: { mode: 'scheduled', cron: '0 9 * * 1' },\n    },\n  },\n]\n\n/** Mint a template id. */\nfunction newTemplateId(): string {\n  return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`\n}\n\n/**\n * The template store. NOT thread-synchronized like the ledger (template\n * writes are rare, human-paced GUI operations; last-write-wins is fine).\n */\nexport class TemplateStore {\n  private templates: TaskTemplate[] | undefined\n  private loaded = false\n\n  /** @param file - absolute side-file path (next to the ledger). */\n  constructor(private readonly file: string) {}\n\n  /** Load once; a missing file seeds the built-ins; a corrupt file resets. */\n  private async ensure(): Promise<void> {\n    if (this.loaded) return\n    let parsed: TaskTemplate[] | undefined\n    try {\n      const raw = await readFile(this.file, 'utf8')\n      const value = JSON.parse(raw) as { templates?: unknown }\n      if (Array.isArray(value.templates)) {\n        parsed = value.templates.filter((t): t is TaskTemplate =>\n          typeof t === 'object' && t !== null && typeof (t as TaskTemplate).id === 'string'\n          && typeof (t as TaskTemplate).name === 'string' && typeof (t as TaskTemplate).task === 'object')\n      }\n    } catch { /* missing or corrupt → seed */ }\n    if (parsed === undefined) {\n      const now = Date.now()\n      parsed = BUILTIN_TEMPLATES.map((t, i) => ({ ...t, task: { ...t.task }, builtin: true, createdAt: now, updatedAt: now + i }))\n      try { await this.persist(parsed) } catch { /* best effort — the seed returns in-memory */ }\n    }\n    this.templates = parsed\n    this.loaded = true\n  }\n\n  /** Atomic persist (temp + rename), same discipline as the ledger. */\n  private async persist(templates: TaskTemplate[]): Promise<void> {\n    const { mkdir, writeFile, rename } = await import('node:fs/promises')\n    const { dirname, join } = await import('node:path')\n    await mkdir(dirname(this.file), { recursive: true })\n    const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)\n    await writeFile(temp, JSON.stringify({ templates }, null, 2), 'utf8')\n    await rename(temp, this.file)\n  }\n\n  /** All templates (oldest first). */\n  async list(): Promise<TaskTemplate[]> {\n    await this.ensure()\n    return (this.templates ?? []).slice()\n  }\n\n  /**\n   * Create or replace a template by id (a body without id creates).\n   * @returns the stored template.\n   */\n  async upsert(input: { id?: string; name: string; task: TaskTemplate['task'] }): Promise<TaskTemplate> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const name = input.name.trim()\n    if (name.length === 0 || name.length > 60) throw new Error('模板名必须 1..60 字符')\n    const now = Date.now()\n    const existing = input.id !== undefined ? templates.find(t => t.id === input.id) : undefined\n    const stored: TaskTemplate = existing !== undefined\n      ? { ...existing, name, task: input.task, updatedAt: now }\n      : { id: input.id ?? newTemplateId(), name, task: input.task, createdAt: now, updatedAt: now }\n    const index = existing !== undefined ? templates.indexOf(existing) : -1\n    if (index >= 0) templates[index] = stored\n    else templates.push(stored)\n    await this.persist(templates)\n    return stored\n  }\n\n  /** Delete a template by id; returns whether it existed. */\n  async remove(id: string): Promise<boolean> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const index = templates.findIndex(t => t.id === id)\n    if (index < 0) return false\n    templates.splice(index, 1)\n    await this.persist(templates)\n    return true\n  }\n}\n"],"mappings":"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"}

package/lib/host/tools.js

@@ -1,4 +1,4 @@
-import { asIsolation, asStatus, asUrgency, canTransition, effectivePrompt, isClaim, isClaimedBy, newCommentId, newTaskId, normalizeBody, normalizeExecution, normalizeModel, normalizePrompt, normalizeTitle, summarize, syncClaim } from "../shared/protocol.js";
+import { asIsolation, asStatus, asUrgency, canTransition, checklistFromTexts, effectivePrompt, isClaim, isClaimedBy, newCommentId, newTaskId, normalizeBody, normalizeExecution, normalizeExecutionReport, normalizeModel, normalizePrompt, normalizeTitle, summarize, syncClaim } from "../shared/protocol.js";
 import { defineTool } from "./sdk.js";
 //#region src/host/tools.ts
 /** Render side: one compact task line (id/status/version are load-bearing). */
@@ -7,6 +7,7 @@ function taskLine(t) {
 	if (t.blocked) parts.push("·受阻");
 	if (t.executionMode === "scheduled") parts.push("·定时");
 	if (t.commentCount !== void 0 && t.commentCount > 0) parts.push(`·评论${t.commentCount}`);
+	if (t.checklist !== void 0 && t.checklist.total > 0) parts.push(`·清单${t.checklist.done}/${t.checklist.total}`);
 	if (t.lastExecutionOutcome !== void 0) parts.push(`·上次执行${t.lastExecutionOutcome}`);
 	if (t.trashed === true) parts.push("·已删");
 	return parts.join(" ");
@@ -26,6 +27,16 @@ function taskDetail(t) {
 	if (t.presetId !== void 0) lines.push(`执行模式: ${t.presetId}（未指定时为部署默认 preset）`);
 	lines.push(`描述: ${t.description.length > 0 ? t.description : "（无）"}`);
 	lines.push(`执行 Prompt: ${t.effectivePrompt ?? effectivePrompt(t)}`);
+	if (t.checklist !== void 0 && t.checklist.length > 0) {
+		const done = t.checklist.filter((i) => i.checked).length;
+		lines.push(`验收清单 (${done}/${t.checklist.length}):`);
+		for (const item of t.checklist) {
+			const mark = item.checked ? "☑" : "☐";
+			const who = item.checkedBy === void 0 ? "" : item.checkedBy === "user" ? " ·用户勾选" : ` ·agent ${String(item.checkedBy).slice(0, 24)}勾选`;
+			const note = item.note !== void 0 ? ` ·证据: ${item.note}` : "";
+			lines.push(`  ${mark} ${item.text}${who}${note}`);
+		}
+	}
 	if (t.comments.length > 0) {
 		lines.push(`评论 (${t.comments.length}):`);
 		for (const c of t.comments) {
@@ -38,7 +49,8 @@ function taskDetail(t) {
 		for (const e of t.executions) {
 			const at = e.startedAt !== void 0 ? new Date(e.startedAt).toISOString() : "?";
 			const err = e.error !== void 0 ? ` 错误: ${e.error}` : "";
-			lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${err}`);
+			const report = e.report !== void 0 ? " [已交报告]" : "";
+			lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${report}${err}`);
 		}
 	} else lines.push("执行记录: 无");
 	const updatedBy = t.updatedBy.kind === "agent" ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : "user";
@@ -303,6 +315,11 @@ function registerTaskboardTools(ctx, deps) {
 			presetId: {
 				type: "string",
 				description: "Agent preset the execution session is composed from (its tool set / persona); default = the deployment default preset. Optional."
+			},
+			checklist: {
+				type: "array",
+				description: `Acceptance checklist (DoD) item texts (≤30 × 200 chars); agents check them off at handoff, the user reviews.`,
+				items: { type: "string" }
 			}
 		},
 		output: {
@@ -327,6 +344,7 @@ function registerTaskboardTools(ctx, deps) {
 				const model = args.model !== void 0 ? checkModel(deps, args.model) : void 0;
 				const isolation = args.isolation === void 0 ? void 0 : asIsolation(args.isolation);
 				const presetId = args.presetId?.trim() || void 0;
+				const checklist = args.checklist !== void 0 ? checklistFromTexts(args.checklist) : void 0;
 				const now = deps.now();
 				const task = {
 					id: newTaskId(),
@@ -341,6 +359,7 @@ function registerTaskboardTools(ctx, deps) {
 					model,
 					...isolation !== void 0 ? { isolation } : {},
 					...presetId !== void 0 ? { presetId } : {},
+					...checklist !== void 0 ? { checklist } : {},
 					version: 1,
 					createdAt: now,
 					updatedAt: now,
@@ -636,6 +655,187 @@ function registerTaskboardTools(ctx, deps) {
 			}
 		}
 	})));
+	disposers.push(register(defineTool({
+		name: "taskboard_checklist",
+		description: "Manage the task's acceptance checklist (DoD). Actions: \"add\" (append item texts, ≤10 per call), \"check\" (mark an item done, with an optional evidence note), \"uncheck\" (reopen an item). Checking items NEVER completes the task — done stays a user-only action. Requires ifVersion.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Task id."
+			},
+			action: {
+				type: "string",
+				required: true,
+				description: "add | check | uncheck."
+			},
+			ifVersion: {
+				type: "number",
+				required: true,
+				description: "Task version you read; fails on mismatch."
+			},
+			items: {
+				type: "array",
+				description: "Item texts to append (action=add only; 1..10 per call, 200 chars each).",
+				items: { type: "string" }
+			},
+			itemId: {
+				type: "string",
+				description: "The checklist item id (action=check/uncheck)."
+			},
+			note: {
+				type: "string",
+				description: "Evidence note recorded with the check (≤400 chars)."
+			}
+		},
+		output: {
+			schema: JSON_OUT,
+			render: (_args, value) => {
+				const v = value;
+				if (v.task === void 0 || v.checklist === void 0) return [{
+					type: "text",
+					text: "清单操作失败。"
+				}];
+				const lines = v.checklist.map((i, index) => `${i.checked === true ? "☑" : "☐"} [${index + 1}] ${String(i.text)}${i.note !== void 0 ? `（证据: ${String(i.note)}）` : ""} id=${String(i.id)}`);
+				return [{
+					type: "text",
+					text: `任务 ${v.task.id} 验收清单 ${v.done ?? 0}/${v.total ?? 0} 已完成，当前 v${v.task.version}：\n${lines.join("\n")}`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			try {
+				const { actor } = caller(exec);
+				const task = store.get(args.id);
+				if (task === void 0 || task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
+				versionGuard(task, args.ifVersion);
+				if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
+				const next = structuredClone(task);
+				const checklist = next.checklist === void 0 ? [] : [...next.checklist];
+				if (args.action === "add") {
+					const texts = args.items ?? [];
+					if (texts.length === 0 || texts.length > 10) throw new ToolError(ERR.invalidInput, "items must carry 1..10 texts per add call");
+					if (checklist.length + texts.length > 30) throw new ToolError(ERR.invalidInput, `checklist may hold at most 30 items (currently ${checklist.length})`);
+					checklist.push(...checklistFromTexts(texts));
+				} else if (args.action === "check") {
+					if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for check");
+					const item = checklist.find((i) => i.id === args.itemId);
+					if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
+					const note = args.note !== void 0 && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : void 0;
+					item.checked = true;
+					item.checkedBy = actor.sessionId;
+					item.checkedAt = deps.now();
+					if (note !== void 0) item.note = note;
+				} else if (args.action === "uncheck") {
+					if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for uncheck");
+					const item = checklist.find((i) => i.id === args.itemId);
+					if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
+					item.checked = false;
+					delete item.checkedBy;
+					delete item.checkedAt;
+					delete item.note;
+				} else throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`);
+				if (checklist.length > 0) next.checklist = checklist;
+				else delete next.checklist;
+				next.version = task.version + 1;
+				next.updatedAt = deps.now();
+				next.updatedBy = actor;
+				await store.mutate("task-updated", (ledger) => {
+					const i = ledger.tasks.findIndex((t) => t.id === args.id);
+					ledger.tasks[i] = next;
+					return [next];
+				});
+				const progress = next.checklist !== void 0 ? {
+					done: next.checklist.filter((i) => i.checked).length,
+					total: next.checklist.length
+				} : {
+					done: 0,
+					total: 0
+				};
+				return json({
+					task: {
+						id: next.id,
+						version: next.version
+					},
+					checklist: next.checklist ?? [],
+					...progress
+				});
+			} catch (error) {
+				fail(error);
+			}
+		}
+	})));
+	disposers.push(register(defineTool({
+		name: "taskboard_execution_report",
+		description: "Submit the structured execution report for the task you are currently executing (summary / changed files / how you verified / artifacts / remaining risk). Submit BEFORE moving the task to in_review; a later submission overwrites the previous report. Commits and diffs are host-collected — do not repeat them.",
+		parameters: {
+			summary: {
+				type: "string",
+				required: true,
+				description: "What was done (1..2000 chars)."
+			},
+			changedFiles: {
+				type: "array",
+				description: "Files you changed (paths, ≤50 × 300 chars).",
+				items: { type: "string" }
+			},
+			checks: {
+				type: "array",
+				description: "How the work was verified (e.g. test commands + outcomes, ≤50 entries).",
+				items: { type: "string" }
+			},
+			artifacts: {
+				type: "array",
+				description: "Artifacts worth reviewing (build outputs, screenshots, docs, ≤30 entries).",
+				items: { type: "string" }
+			},
+			risk: {
+				type: "string",
+				description: "Known remaining risks or follow-ups (≤2000 chars, optional)."
+			}
+		},
+		output: {
+			schema: JSON_OUT,
+			render: (_args, value) => {
+				const v = value;
+				if (v.taskId === void 0 || v.report === void 0) return [{
+					type: "text",
+					text: "报告提交失败。"
+				}];
+				return [{
+					type: "text",
+					text: `执行报告已记录到任务 ${v.taskId}（执行 ${v.executionId}）：${v.report.summary?.slice(0, 120) ?? ""}\n接下来：taskboard_comment_add 留交接评论，然后 taskboard_move 移至待验收 in_review。`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			try {
+				const { sessionId } = caller(exec);
+				const report = normalizeExecutionReport(args);
+				let taskId;
+				let executionId;
+				await store.mutate("execution-recorded", (ledger) => {
+					for (const task of ledger.tasks) {
+						const execution = task.executions.find((e) => e.sessionId === sessionId && e.outcome === "running");
+						if (execution !== void 0) {
+							execution.report = report;
+							taskId = task.id;
+							executionId = execution.id;
+							return [task];
+						}
+					}
+				});
+				if (taskId === void 0 || executionId === void 0) throw new ToolError(ERR.forbidden, "no running execution belongs to this session — the report can only be submitted while the taskboard execution session is still running");
+				return json({
+					taskId,
+					executionId,
+					report
+				});
+			} catch (error) {
+				fail(error);
+			}
+		}
+	})));
 	return disposers;
 }
 //#endregion