@research-copilot/plugin 1.1.16 → 1.1.18

package/dist/skills/llm-wiki/workbench/server/src/agent.ts

@@ -0,0 +1,457 @@
+/**
+ * agent.ts - pi-coding-agent SDK 的活跃会话管理
+ *
+ * 阶段一 step 8：从单 in-memory session 升级为
+ *   "活跃上下文 = (当前 KB, 当前对话, pi session 实例)"
+ *
+ * 会话持久化到 ~/.llm-wiki-agent/sessions/<kb-hash>/，由 pi SessionManager 管理。
+ * 任一时刻只有一个 active session（单用户、单浏览器假设）。
+ *
+ * 切换逻辑：
+ *   selectKb(kbPath)            → 先 dispose 老 session，再尝试 continueRecent，
+ *                                 如果该 KB 无任何对话则创建新的
+ *   selectConversation(kbPath, conversationId) → dispose 老 + 打开指定文件
+ *   createNewConversation(kbPath)              → dispose 老 + 新建空白对话
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+	type AgentSession,
+	AuthStorage,
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	ModelRegistry,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+
+import { loadConfig, saveConfig } from "./config.js";
+import type { ModelRef } from "./config.js";
+import { ensureKbSessionDir, listConversations } from "./conversations.js";
+import { scanAndRebuildArtifactIndex } from "./artifacts.js";
+import { createArtifactsExtension } from "./extensions/artifacts.js";
+import knowledgeBaseExtension from "./extensions/knowledge-base.js";
+import { setCurrentKnowledgeBase } from "./extensions/knowledge-base.js";
+import { createNewWikiExtension } from "./extensions/new-wiki.js";
+import { createSynthesisExtension } from "./extensions/synthesis.js";
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PROJECT_SKILLS_DIR = path.join(REPO_ROOT, ".claude", "skills");
+const PI_DEFAULT_SKILLS_DIR = path.join(homedir(), ".pi", "agent", "skills");
+const USER_GLOBAL_SKILLS_DIR = path.join(homedir(), ".claude", "skills");
+
+export const authStorage = AuthStorage.create();
+export const modelRegistry = ModelRegistry.create(authStorage);
+const settingsManager = SettingsManager.create(REPO_ROOT, getAgentDir());
+
+function registerPendingProviders(loader: DefaultResourceLoader): void {
+	const extensions = loader.getExtensions();
+	const runtime = extensions.runtime as {
+		pendingProviderRegistrations?: Array<{
+			name: string;
+			config: Parameters<ModelRegistry["registerProvider"]>[1];
+			extensionPath?: string;
+		}>;
+	};
+	const pending = runtime.pendingProviderRegistrations ?? [];
+	for (const { name, config, extensionPath } of pending) {
+		try {
+			modelRegistry.registerProvider(name, config);
+		} catch (err) {
+			console.warn(
+				`[agent] register provider from ${extensionPath ?? "extension"} failed: ${
+					err instanceof Error ? err.message : err
+				}`,
+			);
+		}
+	}
+	runtime.pendingProviderRegistrations = [];
+}
+
+async function rememberLastUsedKb(kbPath: string): Promise<void> {
+	try {
+		const config = await loadConfig();
+		if (config.lastUsedKbPath === kbPath) return;
+		await saveConfig({ ...config, lastUsedKbPath: kbPath });
+	} catch (err) {
+		console.warn(`[agent] 写入 lastUsedKbPath 失败: ${err instanceof Error ? err.message : err}`);
+	}
+}
+
+export interface ActiveContext {
+	kb: { path: string; name: string };
+	session: AgentSession;
+	conversationId: string;
+	isNew: boolean; // 本次 select 是否新建的会话
+}
+
+let resourceLoaderState: {
+	includeUserGlobal: boolean;
+	promise: Promise<DefaultResourceLoader>;
+} | null = null;
+let active: ActiveContext | null = null;
+
+export async function getResourceLoader(): Promise<DefaultResourceLoader> {
+	const includeUserGlobal = (await loadConfig()).showUserGlobalSkills === true;
+	if (!resourceLoaderState || resourceLoaderState.includeUserGlobal !== includeUserGlobal) {
+		const additionalSkillPaths = [
+			PROJECT_SKILLS_DIR,
+			...(includeUserGlobal ? [USER_GLOBAL_SKILLS_DIR] : []),
+		];
+		resourceLoaderState = {
+			includeUserGlobal,
+			promise: (async () => {
+				const loader = new DefaultResourceLoader({
+					cwd: REPO_ROOT,
+					agentDir: getAgentDir(),
+					additionalSkillPaths,
+					extensionFactories: [
+						knowledgeBaseExtension,
+						createSynthesisExtension(() => active),
+						createNewWikiExtension(),
+						createArtifactsExtension(() => active),
+					],
+				});
+				await loader.reload();
+				registerPendingProviders(loader);
+				console.log(
+					`[agent] ResourceLoader ready (project skills + user-global ${includeUserGlobal ? "on" : "off"})`,
+				);
+				return loader;
+			})().catch((err) => {
+				resourceLoaderState = null;
+				throw err;
+			}),
+		};
+	}
+	return resourceLoaderState.promise;
+}
+
+export async function reloadActiveResources(): Promise<ActiveContext | null> {
+	resourceLoaderState = null;
+	if (!active) return null;
+	return selectConversation(active.kb.path, active.conversationId);
+}
+
+async function disposeActive(): Promise<void> {
+	if (active) {
+		try {
+			active.session.dispose();
+		} catch {
+			// noop
+		}
+		active = null;
+	}
+}
+
+export function getActive(): ActiveContext | null {
+	return active;
+}
+
+export async function getActiveSession(): Promise<AgentSession> {
+	if (!active) {
+		throw new Error("没有活跃对话。请先选择知识库或新建对话。");
+	}
+	return active.session;
+}
+
+export interface LoadedSkillInfo {
+	name: string;
+	description: string;
+	source: "builtin" | "pi-default" | "user-global";
+	skillPath: string;
+}
+
+async function findSkillFiles(root: string): Promise<string[]> {
+	const rootInfo = await stat(root).catch(() => null);
+	if (!rootInfo?.isDirectory()) return [];
+	const results: string[] = [];
+
+	async function walk(dir: string): Promise<void> {
+		const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+		if (entries.some((entry) => entry.isFile() && entry.name === "SKILL.md")) {
+			results.push(path.join(dir, "SKILL.md"));
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name === "node_modules" || entry.name.startsWith(".")) {
+				continue;
+			}
+			await walk(path.join(dir, entry.name));
+		}
+	}
+
+	await walk(root);
+	return results;
+}
+
+function parseSkillFrontmatter(
+	content: string,
+	source: LoadedSkillInfo["source"],
+	skillPath: string,
+): LoadedSkillInfo | null {
+	const match = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!match) return null;
+	const frontmatter = match[1] ?? "";
+	const name = frontmatter.match(/^name:\s*(.+)$/m)?.[1]?.trim();
+	let description = frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim();
+	if (description === "|") {
+		const lines = frontmatter.split("\n");
+		const start = lines.findIndex((line) => line.startsWith("description:"));
+		description = lines
+			.slice(start + 1)
+			.filter((line) => line.startsWith("  "))
+			.map((line) => line.trim())
+			.join(" ")
+			.trim();
+	}
+	if (!name || !description) return null;
+	return { name, description, source, skillPath };
+}
+
+async function scanSkillDirs(): Promise<LoadedSkillInfo[]> {
+	const roots = [
+		{ root: PROJECT_SKILLS_DIR, source: "builtin" as const },
+		{ root: PI_DEFAULT_SKILLS_DIR, source: "pi-default" as const },
+		{ root: USER_GLOBAL_SKILLS_DIR, source: "user-global" as const },
+	];
+
+	const skills: LoadedSkillInfo[] = [];
+	for (const { root, source } of roots) {
+		for (const file of await findSkillFiles(root)) {
+			const parsed = parseSkillFrontmatter(
+				await readFile(file, "utf8").catch(() => ""),
+				source,
+				path.dirname(file),
+			);
+			if (parsed) skills.push(parsed);
+		}
+	}
+	return skills;
+}
+
+function sourceForSkillPath(skillPath: string): LoadedSkillInfo["source"] {
+	const resolved = path.resolve(skillPath);
+	if (resolved === PROJECT_SKILLS_DIR || resolved.startsWith(PROJECT_SKILLS_DIR + path.sep)) {
+		return "builtin";
+	}
+	if (resolved === PI_DEFAULT_SKILLS_DIR || resolved.startsWith(PI_DEFAULT_SKILLS_DIR + path.sep)) {
+		return "pi-default";
+	}
+	return "user-global";
+}
+
+export async function listLoadedSkills(): Promise<LoadedSkillInfo[]> {
+	const loader = await getResourceLoader();
+	const sdkSkills = loader.getSkills().skills;
+	const scanned = await scanSkillDirs();
+	const byPath = new Map(scanned.map((skill) => [path.resolve(skill.skillPath), skill]));
+	const results: LoadedSkillInfo[] = [];
+	const seen = new Set<string>();
+
+	for (const skill of scanned) {
+		if (seen.has(skill.name)) continue;
+		seen.add(skill.name);
+		results.push(skill);
+	}
+	for (const skill of sdkSkills) {
+		if (seen.has(skill.name)) continue;
+		const filePath = (skill as { filePath?: string }).filePath;
+		const dir = filePath ? path.dirname(filePath) : "";
+		const known = dir ? byPath.get(path.resolve(dir)) : undefined;
+		seen.add(skill.name);
+		results.push(
+			known ?? {
+				name: skill.name,
+				description: skill.description,
+				source: dir ? sourceForSkillPath(dir) : "user-global",
+				skillPath: dir,
+			},
+		);
+	}
+	return results;
+}
+
+export interface AvailableModelInfo {
+	provider: string;
+	modelId: string;
+	name: string;
+	reasoning: boolean;
+	contextWindow: number;
+	cost: { input: number; output: number };
+	hasAuth: boolean;
+}
+
+export function listAvailableModels(): AvailableModelInfo[] {
+	modelRegistry.refresh();
+	const available = modelRegistry.getAvailable();
+	return available.map((model) => ({
+		provider: model.provider,
+		modelId: model.id,
+		name: model.name,
+		reasoning: model.reasoning,
+		contextWindow: model.contextWindow,
+		cost: { input: model.cost.input, output: model.cost.output },
+		hasAuth: modelRegistry.hasConfiguredAuth(model),
+	}));
+}
+
+export function getPiDefaultModelRef(): { provider?: string; modelId?: string } {
+	return {
+		provider: settingsManager.getDefaultProvider(),
+		modelId: settingsManager.getDefaultModel(),
+	};
+}
+
+export async function getRoleModel(role: "main" | "digest"): Promise<Model<any> | undefined> {
+	const config = await loadConfig();
+	const ref = config.modelRoles?.[role];
+	if (ref) {
+		const model = getConfiguredModel(ref);
+		if (model) {
+			console.log(`[agent] role=${role} model=${model.provider}/${model.id}`);
+			return model;
+		}
+		console.warn(`[agent] role=${role} model ${ref.provider}/${ref.modelId} 不可用，回退 pi 默认`);
+	}
+	return undefined;
+}
+
+export function getConfiguredModel(ref: ModelRef): Model<any> | undefined {
+	modelRegistry.refresh();
+	const model = modelRegistry.find(ref.provider, ref.modelId);
+	if (model && modelRegistry.hasConfiguredAuth(model)) return model;
+	return undefined;
+}
+
+/**
+ * 选择/进入一个知识库：dispose 老 session，加载/新建该库下的活跃对话。
+ *   - 该 KB 有对话：opens most recent
+ *   - 该 KB 无对话：creates a new one
+ */
+export async function selectKb(kbPath: string): Promise<ActiveContext> {
+	await disposeActive();
+	const kb = await setCurrentKnowledgeBase(kbPath);
+	const dir = await ensureKbSessionDir(kbPath);
+	const loader = await getResourceLoader();
+
+	const existing = await listConversations(kbPath);
+
+	let isNew = false;
+	let sessionManager: ReturnType<typeof SessionManager.create>;
+	const mostRecent = existing[0];
+	if (mostRecent) {
+		sessionManager = SessionManager.open(mostRecent.path);
+	} else {
+		sessionManager = SessionManager.create(process.cwd(), dir);
+		isNew = true;
+	}
+
+	const model = await getRoleModel("main");
+	const { session, modelFallbackMessage } = await createAgentSession({
+		resourceLoader: loader,
+		sessionManager,
+		authStorage,
+		modelRegistry,
+		...(model ? { model } : {}),
+	});
+	if (modelFallbackMessage) console.log(`[agent] ${modelFallbackMessage}`);
+
+	active = { kb, session, conversationId: session.sessionId, isNew };
+	await rememberLastUsedKb(kbPath);
+	console.log(
+		`[agent] selectKb ${kb.name} → conversation ${active.conversationId.slice(0, 8)} (${isNew ? "new" : "resumed"})`,
+	);
+	return active;
+}
+
+/**
+ * 切到该 KB 下指定的对话。
+ */
+export async function selectConversation(
+	kbPath: string,
+	conversationId: string,
+): Promise<ActiveContext> {
+	const list = await listConversations(kbPath);
+	const target = list.find((c) => c.id === conversationId);
+	if (!target) {
+		throw new Error(`对话不存在：${conversationId}`);
+	}
+
+	await disposeActive();
+	const kb = await setCurrentKnowledgeBase(kbPath);
+	const loader = await getResourceLoader();
+
+	const model = await getRoleModel("main");
+	const { session, modelFallbackMessage } = await createAgentSession({
+		resourceLoader: loader,
+		sessionManager: SessionManager.open(target.path),
+		authStorage,
+		modelRegistry,
+		...(model ? { model } : {}),
+	});
+	if (modelFallbackMessage) console.log(`[agent] ${modelFallbackMessage}`);
+
+	active = { kb, session, conversationId: session.sessionId, isNew: false };
+	await rememberLastUsedKb(kbPath);
+	console.log(
+		`[agent] selectConversation ${kb.name} → ${active.conversationId.slice(0, 8)}`,
+	);
+	return active;
+}
+
+/**
+ * 在该 KB 下新建一个空白对话，并设为活跃。
+ */
+export async function createNewConversation(kbPath: string): Promise<ActiveContext> {
+	await disposeActive();
+	const kb = await setCurrentKnowledgeBase(kbPath);
+	const dir = await ensureKbSessionDir(kbPath);
+	const loader = await getResourceLoader();
+
+	const model = await getRoleModel("main");
+	const { session, modelFallbackMessage } = await createAgentSession({
+		resourceLoader: loader,
+		sessionManager: SessionManager.create(process.cwd(), dir),
+		authStorage,
+		modelRegistry,
+		...(model ? { model } : {}),
+	});
+	if (modelFallbackMessage) console.log(`[agent] ${modelFallbackMessage}`);
+
+	active = { kb, session, conversationId: session.sessionId, isNew: true };
+	await rememberLastUsedKb(kbPath);
+	console.log(`[agent] createNewConversation ${kb.name} → ${active.conversationId.slice(0, 8)}`);
+	return active;
+}
+
+/**
+ * 完全清空活跃上下文（不删除磁盘上的会话文件）。
+ */
+export async function clearActive(): Promise<void> {
+	await disposeActive();
+}
+
+/**
+ * 启动时自动恢复 config.lastUsedKbPath 指向的 KB（PRODUCT.md §5.1.1）。
+ * 失败（路径已删除等）不抛错，仅记 warn。
+ */
+export async function bootstrapFromConfig(): Promise<void> {
+	try {
+		await scanAndRebuildArtifactIndex();
+		const config = await loadConfig();
+		if (!config.lastUsedKbPath) return;
+		await selectKb(config.lastUsedKbPath);
+		console.log(`[agent] bootstrap restored: ${config.lastUsedKbPath}`);
+	} catch (err) {
+		console.warn(
+			`[agent] bootstrap restore failed (path may be invalid or removed): ${err instanceof Error ? err.message : err}`,
+		);
+	}
+}

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

@@ -0,0 +1,248 @@
+import { EventEmitter } from "node:events";
+import { createReadStream } from "node:fs";
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { APP_DIR } from "./config.js";
+
+export type ArtifactKind = "html" | "pdf" | "docx" | "pptx" | "xlsx";
+export type ArtifactRenderer = "iframe" | "download-only";
+
+export interface ArtifactManifest {
+	id: string;
+	kind: ArtifactKind;
+	renderer: ArtifactRenderer;
+	metadata: {
+		title: string;
+		createdAt: string;
+		sourceConversationId: string;
+		sourceKbPath: string;
+		sourceSkill: string;
+		sizeBytes: number;
+	};
+	files: Array<{
+		name: string;
+		sizeBytes: number;
+		mimeType: string;
+	}>;
+	primaryFile: string;
+}
+
+interface PendingArtifact {
+	id: string;
+	kind: ArtifactKind;
+	title: string;
+	workspacePath: string;
+	sourceConversationId: string;
+	sourceKbPath: string;
+	sourceSkill: string;
+	createdAt: string;
+}
+
+export interface ArtifactCreatedEvent {
+	id: string;
+	kind: ArtifactKind;
+	title: string;
+	conversationId: string;
+}
+
+export const ARTIFACTS_DIR = path.join(APP_DIR, "artifacts");
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const manifests = new Map<string, ArtifactManifest>();
+const pending = new Map<string, PendingArtifact>();
+export const artifactEvents = new EventEmitter();
+
+export function isValidArtifactId(id: string): boolean {
+	return UUID_RE.test(id);
+}
+
+export function artifactWorkspacePath(id: string): string {
+	assertValidArtifactId(id);
+	return path.join(ARTIFACTS_DIR, id);
+}
+
+export async function scanAndRebuildArtifactIndex(): Promise<void> {
+	manifests.clear();
+	await mkdir(ARTIFACTS_DIR, { recursive: true });
+	const entries = await readdir(ARTIFACTS_DIR, { withFileTypes: true }).catch(() => []);
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !isValidArtifactId(entry.name)) continue;
+		const manifestPath = path.join(ARTIFACTS_DIR, entry.name, "manifest.json");
+		try {
+			const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as ArtifactManifest;
+			if (manifest.id === entry.name) manifests.set(manifest.id, manifest);
+		} catch {
+			// Ignore incomplete artifact workspaces.
+		}
+	}
+}
+
+export async function prepareArtifact(input: {
+	kind: ArtifactKind;
+	title: string;
+	sourceConversationId: string;
+	sourceKbPath: string;
+	sourceSkill?: string;
+}): Promise<{ id: string; workspacePath: string }> {
+	const id = randomUUID();
+	const workspacePath = artifactWorkspacePath(id);
+	await mkdir(workspacePath, { recursive: true });
+	pending.set(id, {
+		id,
+		kind: input.kind,
+		title: input.title.trim() || input.kind.toUpperCase(),
+		workspacePath,
+		sourceConversationId: input.sourceConversationId,
+		sourceKbPath: input.sourceKbPath,
+		sourceSkill: input.sourceSkill ?? input.kind,
+		createdAt: new Date().toISOString(),
+	});
+	return { id, workspacePath };
+}
+
+export async function finalizeArtifact(input: {
+	id: string;
+	primaryFile: string;
+	sourceSkill?: string;
+}): Promise<ArtifactManifest> {
+	assertValidArtifactId(input.id);
+	assertSafeFilename(input.primaryFile);
+	const base = artifactWorkspacePath(input.id);
+	assertInside(ARTIFACTS_DIR, base);
+	const meta = pending.get(input.id);
+	if (!meta) {
+		throw new Error("artifact 未准备或已完成");
+	}
+
+	const files = await listWorkspaceFiles(base);
+	const primary = files.find((file) => file.name === input.primaryFile);
+	if (!primary) {
+		throw new Error(`主文件不存在：${input.primaryFile}`);
+	}
+
+	const manifest: ArtifactManifest = {
+		id: input.id,
+		kind: meta.kind,
+		renderer: meta.kind === "html" ? "iframe" : "download-only",
+		metadata: {
+			title: meta.title,
+			createdAt: meta.createdAt,
+			sourceConversationId: meta.sourceConversationId,
+			sourceKbPath: meta.sourceKbPath,
+			sourceSkill: input.sourceSkill ?? meta.sourceSkill,
+			sizeBytes: primary.sizeBytes,
+		},
+		files,
+		primaryFile: primary.name,
+	};
+
+	await atomicWriteJson(path.join(base, "manifest.json"), manifest);
+	manifests.set(manifest.id, manifest);
+	pending.delete(manifest.id);
+	artifactEvents.emit("artifact_created", {
+		id: manifest.id,
+		kind: manifest.kind,
+		title: manifest.metadata.title,
+		conversationId: manifest.metadata.sourceConversationId,
+	} satisfies ArtifactCreatedEvent);
+	return manifest;
+}
+
+export function listArtifacts(conversationId?: string): ArtifactManifest[] {
+	return [...manifests.values()]
+		.filter((manifest) => !conversationId || manifest.metadata.sourceConversationId === conversationId)
+		.sort((a, b) => a.metadata.createdAt.localeCompare(b.metadata.createdAt));
+}
+
+export function getArtifact(id: string): ArtifactManifest | null {
+	assertValidArtifactId(id);
+	return manifests.get(id) ?? null;
+}
+
+export function resolveArtifactFile(id: string, filename: string): {
+	path: string;
+	mimeType: string;
+	sizeBytes: number;
+} {
+	assertValidArtifactId(id);
+	assertSafeFilename(filename);
+	const manifest = manifests.get(id);
+	if (!manifest) throw new Error("artifact 不存在");
+	const file = manifest.files.find((item) => item.name === filename);
+	if (!file) throw new Error("文件不在 manifest 中");
+	const target = path.join(artifactWorkspacePath(id), filename);
+	assertInside(artifactWorkspacePath(id), target);
+	return { path: target, mimeType: file.mimeType, sizeBytes: file.sizeBytes };
+}
+
+export function createArtifactReadStream(filePath: string) {
+	return createReadStream(filePath);
+}
+
+async function listWorkspaceFiles(base: string): Promise<ArtifactManifest["files"]> {
+	const entries = await readdir(base, { withFileTypes: true });
+	const files: ArtifactManifest["files"] = [];
+	for (const entry of entries) {
+		if (!entry.isFile() || entry.name === "manifest.json") continue;
+		assertSafeFilename(entry.name);
+		const fullPath = path.join(base, entry.name);
+		assertInside(base, fullPath);
+		const info = await stat(fullPath);
+		if (info.size > MAX_FILE_BYTES) {
+			throw new Error(`文件超过 100MB 限制：${entry.name}`);
+		}
+		files.push({
+			name: entry.name,
+			sizeBytes: info.size,
+			mimeType: mimeTypeFor(entry.name),
+		});
+	}
+	if (files.length === 0) throw new Error("artifact 目录中没有可登记文件");
+	files.sort((a, b) => a.name.localeCompare(b.name));
+	return files;
+}
+
+function mimeTypeFor(filename: string): string {
+	const ext = path.extname(filename).toLowerCase();
+	if (ext === ".html" || ext === ".htm") return "text/html; charset=utf-8";
+	if (ext === ".pdf") return "application/pdf";
+	if (ext === ".docx") return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+	if (ext === ".pptx") return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+	if (ext === ".xlsx") return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+	if (ext === ".txt") return "text/plain; charset=utf-8";
+	if (ext === ".json") return "application/json";
+	return "application/octet-stream";
+}
+
+async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
+	const tmp = `${filePath}.tmp`;
+	await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	await rename(tmp, filePath);
+}
+
+function assertValidArtifactId(id: string): void {
+	if (!isValidArtifactId(id)) throw new Error("artifact id 格式错误");
+}
+
+function assertSafeFilename(filename: string): void {
+	if (
+		!filename ||
+		filename.includes("/") ||
+		filename.includes("\\") ||
+		filename.includes("..") ||
+		path.isAbsolute(filename)
+	) {
+		throw new Error("文件名不安全");
+	}
+}
+
+function assertInside(baseDir: string, target: string): void {
+	const resolvedBase = path.resolve(baseDir);
+	const resolvedTarget = path.resolve(target);
+	if (resolvedTarget !== resolvedBase && !resolvedTarget.startsWith(resolvedBase + path.sep)) {
+		throw new Error("路径越界");
+	}
+}