@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/skills/llm-wiki-skill/workbench/server/src/conversations.ts

@@ -0,0 +1,270 @@
+/**
+ * conversations.ts - 对话（pi session）管理
+ *
+ * 设计：
+ *   - 每个知识库一个会话目录：~/.llm-wiki-agent/sessions/<kb-hash>/
+ *   - kb-hash = sha256(absolute_kb_path).slice(0, 16)
+ *     好处：1) 文件系统安全（无中文/斜杠等）；2) KB 重命名/挪走时旧会话不会丢
+ *   - 会话文件由 pi-agent SessionManager 管理（.jsonl 格式）
+ *
+ * UI 对话气泡转换：
+ *   pi 的 AgentMessage 含 user / assistant / toolResult / 自定义类型；
+ *   UI 只显示 user 文本和 assistant 文本。tool 调用在历史里降级为提示文字。
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { SessionManager, type SessionInfo } from "@earendil-works/pi-coding-agent";
+
+import { APP_DIR } from "./config.js";
+import { stripKnowledgeContextForDisplay } from "./retrieval.js";
+import { formatToolDisplay } from "./tool-status-events.js";
+
+export const SESSIONS_ROOT = join(APP_DIR, "sessions");
+
+export interface ConversationInfo {
+	id: string;
+	path: string;
+	firstMessage: string;
+	modifiedAt: number;
+}
+
+export interface UIMessage {
+	id: string;
+	role: "user" | "assistant";
+	content: string;
+	tools: { name: string; status: "done" }[];
+}
+
+/**
+ * 知识库路径 → 会话目录路径（哈希命名）
+ */
+export function kbSessionDir(kbAbsolutePath: string): string {
+	const hash = createHash("sha256").update(kbAbsolutePath).digest("hex").slice(0, 16);
+	return join(SESSIONS_ROOT, hash);
+}
+
+/**
+ * 确保 KB 的会话目录存在
+ */
+export async function ensureKbSessionDir(kbAbsolutePath: string): Promise<string> {
+	const dir = kbSessionDir(kbAbsolutePath);
+	await mkdir(dir, { recursive: true });
+	return dir;
+}
+
+/**
+ * 列出某 KB 下的所有对话（按修改时间从新到旧）
+ */
+export async function listConversations(kbAbsolutePath: string): Promise<ConversationInfo[]> {
+	const dir = await ensureKbSessionDir(kbAbsolutePath);
+	let raw: SessionInfo[] = [];
+	try {
+		raw = await SessionManager.list(process.cwd(), dir);
+	} catch {
+		return [];
+	}
+
+	return raw
+		.map((info) => ({
+			id: info.id,
+			path: info.path,
+			firstMessage: stripKnowledgeContextForDisplay(info.firstMessage ?? ""),
+			modifiedAt: info.modified instanceof Date ? info.modified.getTime() : 0,
+		}))
+		.sort((a, b) => b.modifiedAt - a.modifiedAt);
+}
+
+/**
+ * pi 的 AgentMessage[] → UI 友好的 UIMessage[]
+ *
+ * 规则：
+ *   - user 文本 → UIMessage{role:"user"}
+ *   - assistant 文本 → UIMessage{role:"assistant"}
+ *     如果该 assistant 消息有工具调用，把工具名标到这个 UIMessage 的 tools 上
+ *   - toolResult / 纯工具调用 / 自定义类型 → 忽略（历史里 tool 状态不重要）
+ */
+export function piMessagesToUIMessages(messages: AgentMessage[]): UIMessage[] {
+	const result: UIMessage[] = [];
+	const toolResults = indexToolResults(messages);
+
+	// 一轮（两条 user 消息之间）里 pi 往往产出多条 assistant 消息：文字 → 工具调用 →
+	// 续写 …… 直播态把整轮聚合进一个气泡，这里合并成一个 UIMessage 以与直播保持一致。
+	let pending: { texts: string[]; tools: string[] } | null = null;
+	const flushAssistant = () => {
+		if (!pending) return;
+		const content = pending.texts.filter((t) => t.trim()).join("\n\n");
+		const tools = pending.tools;
+		if (content.trim() || tools.length > 0) {
+			result.push({
+				id: `a-${result.length}`,
+				role: "assistant",
+				content,
+				tools: tools.map((name) => ({ name, status: "done" as const })),
+			});
+		}
+		pending = null;
+	};
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			flushAssistant();
+			const text = stripKnowledgeContextForDisplay(extractText(msg));
+			if (text.trim()) {
+				result.push({
+					id: `u-${result.length}`,
+					role: "user",
+					content: text,
+					tools: [],
+				});
+			}
+		} else if (msg.role === "assistant") {
+			const text = extractText(msg);
+			const tools = extractToolSummaries(msg, toolResults);
+			if (!pending) pending = { texts: [], tools: [] };
+			if (text.trim()) pending.texts.push(text);
+			pending.tools.push(...tools);
+		}
+		// toolResult 等：忽略，且不 flush（它夹在 assistant 工具调用与续写之间，flush 会错误拆轮）
+	}
+	flushAssistant();
+
+	return result;
+}
+
+interface ToolCallSummarySource {
+	id?: string;
+	name: string;
+	args: Record<string, unknown>;
+	hasArgs: boolean;
+}
+
+interface ToolResultSummarySource {
+	toolCallId?: string;
+	toolName?: string;
+	text: string;
+	isError: boolean;
+	details?: unknown;
+}
+
+function extractText(msg: AgentMessage): string {
+	const content = (msg as { content?: unknown }).content;
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.filter((part): part is { type: string; text: string } => {
+				if (typeof part !== "object" || part === null) return false;
+				const p = part as Record<string, unknown>;
+				return p.type === "text" && typeof p.text === "string";
+			})
+			.map((p) => p.text)
+			.join("");
+	}
+	return "";
+}
+
+function extractToolSummaries(
+	msg: AgentMessage,
+	toolResults: Map<string, ToolResultSummarySource>,
+): string[] {
+	const content = (msg as { content?: unknown }).content;
+	if (!Array.isArray(content)) return [];
+	const summaries: string[] = [];
+	for (const part of content) {
+		if (typeof part !== "object" || part === null) continue;
+		const p = part as Record<string, unknown>;
+		if (p.type === "tool_call" || p.type === "toolCall") {
+			const call = normalizeToolCall(p);
+			if (!call) continue;
+			const result = call.id ? toolResults.get(call.id) : undefined;
+			summaries.push(renderToolSummary(call, result));
+		}
+	}
+	return summaries;
+}
+
+function indexToolResults(messages: AgentMessage[]): Map<string, ToolResultSummarySource> {
+	const results = new Map<string, ToolResultSummarySource>();
+	for (const message of messages) {
+		if (message.role !== "toolResult") continue;
+		const record = message as unknown as Record<string, unknown>;
+		const toolCallId = typeof record.toolCallId === "string" ? record.toolCallId : undefined;
+		if (!toolCallId) continue;
+		results.set(toolCallId, {
+			toolCallId,
+			toolName: typeof record.toolName === "string" ? record.toolName : undefined,
+			text: extractText(message).trim(),
+			isError: record.isError === true,
+			details: record.details,
+		});
+	}
+	return results;
+}
+
+function normalizeToolCall(record: Record<string, unknown>): ToolCallSummarySource | null {
+	const name = typeof record.name === "string"
+		? record.name
+		: typeof record.toolName === "string"
+			? record.toolName
+			: null;
+	if (!name) return null;
+	const id = typeof record.id === "string"
+		? record.id
+		: typeof record.toolCallId === "string"
+			? record.toolCallId
+			: undefined;
+	const rawArgs = record.arguments ?? record.args ?? record.input;
+	const args = isRecord(rawArgs) ? rawArgs : {};
+	return {
+		id,
+		name,
+		args,
+		hasArgs: Object.keys(args).length > 0,
+	};
+}
+
+function renderToolSummary(
+	call: ToolCallSummarySource,
+	result: ToolResultSummarySource | undefined,
+): string {
+	const display = call.hasArgs
+		? formatToolDisplay(call.name, call.args)
+		: { action: "历史工具调用", target: call.name };
+	const resultText = summarizeToolResult(result);
+	const failure = result?.isError ? " 失败" : "";
+	if (!call.hasArgs) {
+		return resultText
+			? `历史工具调用：${call.name}${failure}：${resultText}`
+			: `历史工具调用：${call.name}${failure}`;
+	}
+	return resultText
+		? `${display.action} ${display.target}${failure}：${resultText}`
+		: `${display.action} ${display.target}${failure}`;
+}
+
+function summarizeToolResult(result: ToolResultSummarySource | undefined): string {
+	if (!result) return "";
+	if (result.text) return truncateSummary(redactPrivatePaths(result.text));
+	const details = isRecord(result.details) ? result.details : {};
+	for (const key of ["summary", "message", "error", "path"]) {
+		const value = details[key];
+		if (typeof value === "string" && value.trim()) return truncateSummary(redactPrivatePaths(value.trim()));
+	}
+	return "";
+}
+
+function truncateSummary(value: string): string {
+	return value.length <= 80 ? value : `${value.slice(0, 52)}...${value.slice(-25)}`;
+}
+
+function redactPrivatePaths(value: string): string {
+	return value.split(homedir()).join("~").replace(/\/Users\/[^/\s]+/g, "/Users/<user>");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/skills/llm-wiki-skill/workbench/server/src/digest/batch.ts

@@ -0,0 +1,189 @@
+import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { ModelRef } from "../config.js";
+import {
+	inspectKnowledgeBasePath,
+	validateInspectedSourceFiles,
+} from "../knowledge-bases.js";
+import { mapWithConcurrencyLimit } from "./concurrency.js";
+import { digestFileWithSubagent } from "./subagent.js";
+
+export type BatchDigestEvent =
+	| { type: "start"; total: number; concurrency: number; outputDir: string }
+	| { type: "file_start"; index: number; filePath: string }
+	| { type: "file_progress"; index: number; filePath: string; chars: number }
+	| { type: "file_complete"; index: number; filePath: string; outputPath: string }
+	| { type: "file_error"; index: number; filePath: string; error: string }
+	| { type: "done"; total: number; completed: number; failed: number; outputDir: string };
+
+export interface BatchDigestInput {
+	kbPath: string;
+	filePaths: string[];
+	concurrency?: number;
+	sourceScanId?: string;
+	digestModel?: ModelRef | null;
+}
+
+const ALLOWED_EXTS = new Set([".md", ".txt", ".pdf"]);
+
+export async function runBatchDigest(
+	input: BatchDigestInput,
+	emit: (event: BatchDigestEvent) => Promise<void>,
+): Promise<void> {
+	const validated = await validateBatchDigestInput(input);
+	const purpose = await readPurpose(validated.kbPath);
+	const outputDir = path.join(validated.kbPath, "wiki", "synthesis", "sessions");
+	await mkdir(outputDir, { recursive: true });
+
+	await emit({
+		type: "start",
+		total: validated.filePaths.length,
+		concurrency: validated.concurrency,
+		outputDir,
+	});
+
+	const outcomes = await mapWithConcurrencyLimit(
+		validated.filePaths,
+		validated.concurrency,
+		async (filePath, index) => {
+			await emit({ type: "file_start", index, filePath });
+			try {
+				const resolvedFilePath = await resolveDigestFile(
+					filePath,
+					validated.kbPath,
+					validated.sourceScanId,
+				);
+				const content = await digestFileWithSubagent(
+					{
+						kbPath: validated.kbPath,
+						filePath: resolvedFilePath,
+						purpose,
+						model: input.digestModel ?? null,
+					},
+					async (chars) => {
+						await emit({ type: "file_progress", index, filePath, chars });
+					},
+				);
+				const outputPath = await writeDigestOutput(outputDir, resolvedFilePath, index, content);
+				await emit({ type: "file_complete", index, filePath, outputPath });
+				return outputPath;
+			} catch (err) {
+				const error = err instanceof Error ? err.message : String(err);
+				await emit({ type: "file_error", index, filePath, error });
+				throw err;
+			}
+		},
+	);
+
+	const completed = outcomes.filter((outcome) => outcome.ok).length;
+	await emit({
+		type: "done",
+		total: validated.filePaths.length,
+		completed,
+		failed: validated.filePaths.length - completed,
+		outputDir,
+	});
+}
+
+async function validateBatchDigestInput(input: BatchDigestInput): Promise<{
+	kbPath: string;
+	filePaths: string[];
+	concurrency: 1 | 3 | 5;
+	sourceScanId?: string;
+}> {
+	const kbPath = await realpath(path.resolve(input.kbPath));
+	const kbCheck = await inspectKnowledgeBasePath(kbPath);
+	if (!kbCheck.valid) throw new Error(`不是合法知识库（${kbCheck.reason}）：${kbPath}`);
+
+	const concurrency = input.concurrency ?? 3;
+	if (![1, 3, 5].includes(concurrency)) {
+		throw new Error("concurrency 只能是 1、3 或 5");
+	}
+	if (!Array.isArray(input.filePaths) || input.filePaths.length === 0) {
+		throw new Error("filePaths 不能为空");
+	}
+
+	const filePaths: string[] = [];
+	for (const filePath of input.filePaths) {
+		if (typeof filePath !== "string" || !path.isAbsolute(filePath)) {
+			throw new Error("filePaths 必须是绝对路径");
+		}
+		filePaths.push(path.resolve(filePath));
+	}
+
+	return {
+		kbPath,
+		filePaths: Array.from(new Set(filePaths)),
+		concurrency: concurrency as 1 | 3 | 5,
+		...(input.sourceScanId ? { sourceScanId: input.sourceScanId } : {}),
+	};
+}
+
+async function resolveDigestFile(
+	filePath: string,
+	kbPath: string,
+	sourceScanId?: string,
+): Promise<string> {
+	const resolved = await realpath(filePath);
+	assertReadableDigestFile(resolved);
+	const info = await stat(resolved);
+	if (!info.isFile()) throw new Error(`不是文件：${resolved}`);
+	if (isInside(resolved, kbPath)) return resolved;
+	const sourceCheck = validateInspectedSourceFiles(sourceScanId, [filePath]);
+	if (sourceCheck.ok) return resolved;
+	throw new Error(sourceCheck.error);
+}
+
+function assertReadableDigestFile(filePath: string): void {
+	const ext = path.extname(filePath).toLowerCase();
+	if (!ALLOWED_EXTS.has(ext)) {
+		throw new Error(`不支持的文件类型：${filePath}`);
+	}
+}
+
+async function readPurpose(kbPath: string): Promise<string> {
+	for (const rel of ["purpose.md", ".wiki-schema.md"]) {
+		const content = await readFile(path.join(kbPath, rel), "utf8").catch(() => "");
+		if (content.trim()) return content.trim().slice(0, 2000);
+	}
+	return "";
+}
+
+async function writeDigestOutput(
+	outputDir: string,
+	sourcePath: string,
+	index: number,
+	content: string,
+): Promise<string> {
+	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const base = path.basename(sourcePath, path.extname(sourcePath));
+	const slug = slugify(base) || `material-${index + 1}`;
+	const outputPath = path.join(outputDir, `${slug}-${timestamp}.md`);
+	const body = [
+		"---",
+		`source: ${JSON.stringify(sourcePath)}`,
+		`createdAt: ${JSON.stringify(new Date().toISOString())}`,
+		"stage: 3.5-batch-digest",
+		"---",
+		"",
+		content.trim(),
+		"",
+	].join("\n");
+	await writeFile(outputPath, body, "utf8");
+	return outputPath;
+}
+
+function isInside(target: string, root: string): boolean {
+	const relative = path.relative(root, target);
+	return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function slugify(value: string): string {
+	return value
+		.normalize("NFKD")
+		.replace(/[^\w\u4e00-\u9fa5-]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "")
+		.slice(0, 60);
+}

package/skills/llm-wiki-skill/workbench/server/src/digest/concurrency.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { mapWithConcurrencyLimit } from "./concurrency.js";
+
+test("limits active work to requested concurrency", async () => {
+	let active = 0;
+	let maxActive = 0;
+	const items = Array.from({ length: 10 }, (_, i) => i);
+	const outcomes = await mapWithConcurrencyLimit(items, 3, async (item) => {
+		active++;
+		maxActive = Math.max(maxActive, active);
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		active--;
+		return item * 2;
+	});
+
+	assert.equal(maxActive, 3);
+	assert.deepEqual(
+		outcomes.map((outcome) => outcome.value),
+		items.map((item) => item * 2),
+	);
+	assert.ok(outcomes.every((outcome) => outcome.ok));
+});
+
+test("handles empty and smaller-than-concurrency inputs", async () => {
+	assert.deepEqual(await mapWithConcurrencyLimit([], 3, async (item) => item), []);
+	const outcomes = await mapWithConcurrencyLimit([1, 2], 5, async (item) => item + 1);
+	assert.deepEqual(outcomes.map((outcome) => outcome.value), [2, 3]);
+});
+
+test("rejects invalid concurrency", async () => {
+	await assert.rejects(() => mapWithConcurrencyLimit([1], 0, async (item) => item));
+	await assert.rejects(() => mapWithConcurrencyLimit([1], -1, async (item) => item));
+	await assert.rejects(() => mapWithConcurrencyLimit([1], Number.NaN, async (item) => item));
+});

package/skills/llm-wiki-skill/workbench/server/src/digest/concurrency.ts

@@ -0,0 +1,31 @@
+export interface Outcome<R> {
+	ok: boolean;
+	value?: R;
+	error?: string;
+}
+
+export async function mapWithConcurrencyLimit<T, R>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, index: number) => Promise<R>,
+): Promise<Outcome<R>[]> {
+	if (!Number.isInteger(concurrency) || concurrency < 1) {
+		throw new Error("concurrency must be a positive integer");
+	}
+	const results: Outcome<R>[] = new Array(items.length);
+	let cursor = 0;
+
+	async function worker() {
+		while (cursor < items.length) {
+			const i = cursor++;
+			try {
+				results[i] = { ok: true, value: await fn(items[i] as T, i) };
+			} catch (err) {
+				results[i] = { ok: false, error: err instanceof Error ? err.message : String(err) };
+			}
+		}
+	}
+
+	await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+	return results;
+}

package/skills/llm-wiki-skill/workbench/server/src/digest/subagent.ts

@@ -0,0 +1,91 @@
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+
+import {
+	authStorage,
+	getConfiguredModel,
+	getResourceLoader,
+	getRoleModel,
+	modelRegistry,
+} from "../agent.js";
+import type { ModelRef } from "../config.js";
+
+export interface DigestFileInput {
+	kbPath: string;
+	filePath: string;
+	purpose: string;
+	model?: ModelRef | null;
+}
+
+export async function digestFileWithSubagent(
+	input: DigestFileInput,
+	onProgress?: (chars: number) => void | Promise<void>,
+): Promise<string> {
+	const loader = await getResourceLoader();
+	const model = input.model
+		? getConfiguredModel(input.model) ?? (await getRoleModel("digest"))
+		: await getRoleModel("digest");
+	const { session, modelFallbackMessage } = await createAgentSession({
+		cwd: input.kbPath,
+		resourceLoader: loader,
+		sessionManager: SessionManager.inMemory(input.kbPath),
+		authStorage,
+		modelRegistry,
+		...(model ? { model } : {}),
+		thinkingLevel: "off",
+		tools: ["read"],
+	});
+	if (modelFallbackMessage) console.log(`[digest] ${modelFallbackMessage}`);
+
+	let output = "";
+	let lastEmittedChars = 0;
+	let lastEmittedAt = 0;
+	const unsubscribe = session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			output += event.assistantMessageEvent.delta;
+			const now = Date.now();
+			if (onProgress && (output.length - lastEmittedChars >= 500 || now - lastEmittedAt >= 300)) {
+				lastEmittedChars = output.length;
+				lastEmittedAt = now;
+				void onProgress(output.length);
+			}
+		}
+	});
+
+	try {
+		await session.prompt(buildDigestPrompt(input));
+		const trimmed = output.trim();
+		if (!trimmed) throw new Error("子代理没有返回内容");
+		await onProgress?.(trimmed.length);
+		return trimmed;
+	} finally {
+		unsubscribe();
+		session.dispose();
+	}
+}
+
+function buildDigestPrompt(input: DigestFileInput): string {
+	return [
+		"你是 llm-wiki 的素材消化子代理。",
+		"只处理一个文件，读完后输出一篇可直接保存到 wiki 的中文 Markdown 笔记。",
+		"不要改写文件，不要调用写入工具，不要输出过程说明。",
+		"",
+		`知识库路径：${input.kbPath}`,
+		`研究方向：${input.purpose || "未提供"}`,
+		`素材文件：${input.filePath}`,
+		"",
+		"输出结构：",
+		"# 标题",
+		"",
+		"## 核心摘要",
+		"用 3-5 条 bullet 说明最重要的信息。",
+		"",
+		"## 关键细节",
+		"整理事实、概念、数字、论点和可复用片段。",
+		"",
+		"## 与研究方向的关系",
+		"说明这份素材为什么值得放进当前知识库。",
+		"",
+		"## 后续问题",
+		"列出 2-5 个值得继续追问的问题。",
+	].join("\n");
+}

package/skills/llm-wiki-skill/workbench/server/src/extensions/artifacts.ts

@@ -0,0 +1,81 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type { ActiveContext } from "../agent.js";
+import {
+	type ArtifactKind,
+	finalizeArtifact,
+	prepareArtifact,
+} from "../artifacts.js";
+
+interface PrepareParams {
+	kind: ArtifactKind;
+	title: string;
+	sourceSkill?: string;
+}
+
+interface FinalizeParams {
+	id: string;
+	primaryFile: string;
+	sourceSkill?: string;
+}
+
+type ToolContent = { type: "text"; text: string };
+
+function toolResult(text: string, details: Record<string, unknown> = {}) {
+	return { content: [{ type: "text", text } satisfies ToolContent], details };
+}
+
+export function createArtifactsExtension(getActive: () => ActiveContext | null) {
+	return function artifactsExtension(pi: ExtensionAPI) {
+		pi.registerTool({
+			name: "prepare_artifact",
+			label: "准备产物目录",
+			description:
+				"为 HTML/PDF/Word/PPT/Excel 产物创建工作目录。生成文件前先调用它，返回 id 和 workspacePath。",
+			parameters: Type.Object({
+				kind: Type.Union([
+					Type.Literal("html"),
+					Type.Literal("pdf"),
+					Type.Literal("docx"),
+					Type.Literal("pptx"),
+					Type.Literal("xlsx"),
+				]),
+				title: Type.String(),
+				sourceSkill: Type.Optional(Type.String()),
+			}),
+			async execute(_toolCallId, params: PrepareParams) {
+				const active = getActive();
+				if (!active) return toolResult("当前没有活跃知识库。请先选择一个知识库。");
+				const prepared = await prepareArtifact({
+					kind: params.kind,
+					title: params.title,
+					sourceConversationId: active.conversationId,
+					sourceKbPath: active.kb.path,
+					sourceSkill: params.sourceSkill,
+				});
+				return toolResult(`已准备产物目录：${prepared.workspacePath}`, prepared);
+			},
+		});
+
+		pi.registerTool({
+			name: "finalize_artifact",
+			label: "登记产物",
+			description:
+				"文件生成完成后调用，登记 manifest.json 并通知前端打开右抽屉。primaryFile 必须是产物目录里的文件名。",
+			parameters: Type.Object({
+				id: Type.String(),
+				primaryFile: Type.String(),
+				sourceSkill: Type.Optional(Type.String()),
+			}),
+			async execute(_toolCallId, params: FinalizeParams) {
+				try {
+					const manifest = await finalizeArtifact(params);
+					return toolResult(`产物已登记：${manifest.id} / ${manifest.primaryFile}`, { manifest });
+				} catch (err) {
+					return toolResult(`登记产物失败：${err instanceof Error ? err.message : String(err)}`);
+				}
+			},
+		});
+	};
+}