@research-copilot/plugin 1.1.17 → 1.1.19

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

@@ -0,0 +1,164 @@
+import { copyFile, mkdir, open, readFile, rename, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+type AuthCredential = { type: "api_key"; key: string } | Record<string, unknown>;
+type AuthData = Record<string, AuthCredential>;
+
+const AUTH_DIR = path.join(homedir(), ".pi", "agent");
+const AUTH_PATH = path.join(AUTH_DIR, "auth.json");
+
+const ENV_KEYS = [
+	"ANTHROPIC_API_KEY",
+	"OPENAI_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"GOOGLE_API_KEY",
+	"OPENROUTER_API_KEY",
+	"XAI_API_KEY",
+];
+
+export interface AuthProviderStatus {
+	id: string;
+	type: string;
+	configured: boolean;
+}
+
+export async function getAuthStatus() {
+	const authFileExists = Boolean(await stat(AUTH_PATH).catch(() => null));
+	const data = await readAuthData();
+	const providers = Object.entries(data).map(([id, credential]) => ({
+		id,
+		type:
+			credential && typeof credential === "object" && "type" in credential
+				? String((credential as { type?: unknown }).type ?? "unknown")
+				: "unknown",
+		configured: true,
+	}));
+	const envKeys = ENV_KEYS.map((name) => ({ name, present: Boolean(process.env[name]) }));
+	return { authFileExists, providers, envKeys };
+}
+
+async function readAuthData(): Promise<AuthData> {
+	try {
+		const raw = await readFile(AUTH_PATH, "utf8");
+		const parsed = JSON.parse(raw);
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as AuthData)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
+async function writeFileAtomic(filePath: string, content: string): Promise<void> {
+	const tmpPath = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+	const handle = await open(tmpPath, "w", 0o600);
+	try {
+		await handle.writeFile(content, "utf8");
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await rename(tmpPath, filePath);
+}
+
+export async function setAuthKey(provider: string, key: string): Promise<void> {
+	const cleanProvider = provider.trim().toLowerCase();
+	const cleanKey = key.trim();
+	if (!cleanProvider) throw new Error("provider is required");
+	if (!cleanKey) throw new Error("key is required");
+
+	await mkdir(AUTH_DIR, { recursive: true, mode: 0o700 });
+	const existing = await readAuthData();
+	const existed = Boolean(await stat(AUTH_PATH).catch(() => null));
+	const backupPath = `${AUTH_PATH}.bak.${Math.floor(Date.now() / 1000)}`;
+	if (existed) await copyFile(AUTH_PATH, backupPath);
+
+	const next: AuthData = {
+		...existing,
+		[cleanProvider]: { type: "api_key", key: cleanKey },
+	};
+
+	try {
+		await writeFileAtomic(AUTH_PATH, JSON.stringify(next, null, 2) + "\n");
+	} catch (err) {
+		if (existed) await copyFile(backupPath, AUTH_PATH).catch(() => undefined);
+		throw err;
+	}
+}
+
+function redact(message: string, key: string | undefined): string {
+	if (!key) return message;
+	return message.split(key).join("[redacted]");
+}
+
+async function getStoredApiKey(provider: string): Promise<string | undefined> {
+	const data = await readAuthData();
+	const credential = data[provider];
+	if (
+		credential &&
+		typeof credential === "object" &&
+		(credential as { type?: unknown }).type === "api_key" &&
+		typeof (credential as { key?: unknown }).key === "string"
+	) {
+		return (credential as { key: string }).key;
+	}
+	return undefined;
+}
+
+async function parseError(res: Response, key: string): Promise<string> {
+	const raw = await res.text().catch(() => "");
+	const text = raw ? `${res.status} ${res.statusText}: ${raw.slice(0, 500)}` : `${res.status} ${res.statusText}`;
+	return redact(text, key);
+}
+
+async function testAnthropicLike(
+	baseUrl: string,
+	key: string,
+	model: string,
+	extraHeaders: Record<string, string> = {},
+): Promise<void> {
+	const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/messages`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"x-api-key": key,
+			"anthropic-version": "2023-06-01",
+			...extraHeaders,
+		},
+		body: JSON.stringify({
+			model,
+			max_tokens: 1,
+			messages: [{ role: "user", content: "ping" }],
+		}),
+	});
+	if (!res.ok) throw new Error(await parseError(res, key));
+}
+
+async function testOpenAI(key: string): Promise<void> {
+	const res = await fetch("https://api.openai.com/v1/models", {
+		headers: { Authorization: `Bearer ${key}` },
+	});
+	if (!res.ok) throw new Error(await parseError(res, key));
+}
+
+export async function testAuthConnection(provider: string): Promise<{ ok: boolean; message?: string; error?: string }> {
+	const cleanProvider = provider.trim().toLowerCase();
+	const key = await getStoredApiKey(cleanProvider);
+	if (!key) return { ok: false, error: "未找到该 provider 的已保存 key" };
+
+	try {
+		if (cleanProvider === "anthropic") {
+			await testAnthropicLike("https://api.anthropic.com", key, "claude-haiku-4-5");
+		} else if (cleanProvider === "openai") {
+			await testOpenAI(key);
+		} else if (cleanProvider === "deepseek") {
+			await testAnthropicLike("https://api.deepseek.com/anthropic", key, "deepseek-v4-flash");
+		} else {
+			return { ok: true, message: "已保存。该 provider 暂无内置连通测试。" };
+		}
+		return { ok: true, message: "连接成功，模型可用" };
+	} catch (err) {
+		return { ok: false, error: redact(err instanceof Error ? err.message : String(err), key) };
+	}
+}

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

@@ -0,0 +1,130 @@
+/**
+ * config.ts - llm-wiki-agent 自身的应用配置
+ *
+ * 位置：~/.llm-wiki-agent/config.json
+ * 内容：UI 偏好、外部知识库登记、默认模型等（**绝不**含 API key —— ADR-13）
+ *
+ * 设计：
+ *   - 文件缺失：返回默认值，不写盘（等真有内容要存再写）
+ *   - 文件损坏：抛错，不静默覆盖用户数据
+ *   - 写入：原子（先 .tmp 再 rename）
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const APP_DIR = join(homedir(), ".llm-wiki-agent");
+export const DEFAULT_KNOWLEDGE_BASE_ROOT = join(homedir(), "llm-wiki");
+
+const CONFIG_FILE = join(APP_DIR, "config.json");
+
+export interface AppConfig {
+	version: 1;
+	externalKnowledgeBases: string[];
+	/** 最后一次使用的 KB 绝对路径。下次启动用于自动恢复（PRODUCT.md §5.1.1）。 */
+	lastUsedKbPath?: string;
+	showUserGlobalSkills?: boolean;
+	modelRoles?: {
+		main?: ModelRef | null;
+		digest?: ModelRef | null;
+	};
+	uiPrefs?: {
+		sidebarExpandedKbs?: string[];
+	};
+}
+
+export interface ModelRef {
+	provider: string;
+	modelId: string;
+}
+
+const DEFAULT_CONFIG: AppConfig = {
+	version: 1,
+	externalKnowledgeBases: [],
+};
+
+export async function loadConfig(): Promise<AppConfig> {
+	let raw: string;
+	try {
+		raw = await readFile(CONFIG_FILE, "utf8");
+	} catch (err) {
+		if (isNotFound(err)) return { ...DEFAULT_CONFIG };
+		throw new Error(`读取 ${CONFIG_FILE} 失败：${(err as Error).message}`);
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(
+			`${CONFIG_FILE} 格式损坏（不是合法 JSON），请手动修复或删除：${(err as Error).message}`,
+		);
+	}
+
+	return normalize(parsed);
+}
+
+export async function saveConfig(config: AppConfig): Promise<void> {
+	await mkdir(dirname(CONFIG_FILE), { recursive: true });
+	const tmp = `${CONFIG_FILE}.tmp`;
+	await writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+	await rename(tmp, CONFIG_FILE);
+}
+
+function normalize(raw: unknown): AppConfig {
+	if (typeof raw !== "object" || raw === null) {
+		throw new Error(`${CONFIG_FILE} 顶层不是对象`);
+	}
+	const obj = raw as Record<string, unknown>;
+	const version = obj.version === 1 ? 1 : 1; // 当前只支持 v1，未来加迁移
+	const external = Array.isArray(obj.externalKnowledgeBases)
+		? obj.externalKnowledgeBases.filter((p): p is string => typeof p === "string")
+		: [];
+	const lastUsedKbPath =
+		typeof obj.lastUsedKbPath === "string" && obj.lastUsedKbPath ? obj.lastUsedKbPath : undefined;
+	const showUserGlobalSkills = obj.showUserGlobalSkills === true;
+	const modelRoles = normalizeModelRoles(obj.modelRoles);
+	const uiPrefs = normalizeUiPrefs(obj.uiPrefs);
+	return {
+		version,
+		externalKnowledgeBases: external,
+		lastUsedKbPath,
+		showUserGlobalSkills,
+		...(modelRoles ? { modelRoles } : {}),
+		...(uiPrefs ? { uiPrefs } : {}),
+	};
+}
+
+function normalizeModelRef(raw: unknown): ModelRef | null | undefined {
+	if (raw === null) return null;
+	if (typeof raw !== "object" || raw === undefined) return undefined;
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.provider !== "string" || typeof obj.modelId !== "string") return undefined;
+	if (!obj.provider.trim() || !obj.modelId.trim()) return undefined;
+	return { provider: obj.provider.trim(), modelId: obj.modelId.trim() };
+}
+
+function normalizeModelRoles(raw: unknown): AppConfig["modelRoles"] | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const obj = raw as Record<string, unknown>;
+	const main = normalizeModelRef(obj.main);
+	const digest = normalizeModelRef(obj.digest);
+	const result: NonNullable<AppConfig["modelRoles"]> = {};
+	if (main !== undefined) result.main = main;
+	if (digest !== undefined) result.digest = digest;
+	return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function normalizeUiPrefs(raw: unknown): AppConfig["uiPrefs"] | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const obj = raw as Record<string, unknown>;
+	const sidebarExpandedKbs = Array.isArray(obj.sidebarExpandedKbs)
+		? obj.sidebarExpandedKbs.filter((value): value is string => typeof value === "string")
+		: undefined;
+	return sidebarExpandedKbs ? { sidebarExpandedKbs } : undefined;
+}
+
+function isNotFound(err: unknown): boolean {
+	return (err as NodeJS.ErrnoException)?.code === "ENOENT";
+}

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

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+import test from "node:test";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+import { piMessagesToUIMessages } from "./conversations.js";
+
+test("piMessagesToUIMessages renders history summaries for tool calls and results", () => {
+	const messages = piMessagesToUIMessages([
+		userMessage("请读取文件"),
+		assistantMessage("我来读取。", [
+			{
+				type: "toolCall",
+				id: "call-1",
+				name: "read",
+				arguments: { path: `${homedir()}/wiki/index.md` },
+			},
+		]),
+		toolResultMessage("call-1", "read", "读取完成", false),
+	]);
+
+	assert.deepEqual(messages, [
+		{ id: "u-0", role: "user", content: "请读取文件", tools: [] },
+		{
+			id: "a-1",
+			role: "assistant",
+			content: "我来读取。",
+			tools: [{ name: "读取 ~/wiki/index.md：读取完成", status: "done" }],
+		},
+	]);
+});
+
+test("piMessagesToUIMessages uses best-effort summary for old incomplete tool calls", () => {
+	const messages = piMessagesToUIMessages([
+		assistantMessage("", [{ type: "tool_call", toolName: "bash" }]),
+	]);
+
+	assert.deepEqual(messages, [
+		{
+			id: "a-0",
+			role: "assistant",
+			content: "",
+			tools: [{ name: "历史工具调用：bash", status: "done" }],
+		},
+	]);
+});
+
+test("piMessagesToUIMessages omits empty summaries for messages without tools", () => {
+	const messages = piMessagesToUIMessages([
+		assistantMessage("普通回答", []),
+	]);
+
+	assert.deepEqual(messages, [
+		{ id: "a-0", role: "assistant", content: "普通回答", tools: [] },
+	]);
+});
+
+test("piMessagesToUIMessages does not invent details missing from tool results", () => {
+	const messages = piMessagesToUIMessages([
+		assistantMessage("执行命令。", [
+			{ type: "toolCall", id: "call-2", name: "bash", arguments: {} },
+		]),
+		toolResultMessage("call-2", "bash", "", true),
+	]);
+
+	assert.deepEqual(messages[0]?.tools, [
+		{ name: "历史工具调用：bash 失败", status: "done" },
+	]);
+});
+
+test("piMessagesToUIMessages redacts private paths in historical tool results", () => {
+	const messages = piMessagesToUIMessages([
+		assistantMessage("读取文件。", [
+			{
+				type: "toolCall",
+				id: "call-private",
+				name: "read",
+				arguments: { path: `${homedir()}/wiki/private.md` },
+			},
+		]),
+		toolResultMessage("call-private", "read", `读取完成：${homedir()}/wiki/private.md`, false),
+	]);
+
+	assert.equal(JSON.stringify(messages).includes(homedir()), false);
+	assert.deepEqual(messages[0]?.tools, [
+		{ name: "读取 ~/wiki/private.md：读取完成：~/wiki/private.md", status: "done" },
+	]);
+});
+
+function userMessage(text: string): AgentMessage {
+	return {
+		role: "user",
+		content: [{ type: "text", text }],
+	} as AgentMessage;
+}
+
+function assistantMessage(text: string, extra: unknown[]): AgentMessage {
+	return {
+		role: "assistant",
+		content: [
+			...(text ? [{ type: "text", text }] : []),
+			...extra,
+		],
+	} as AgentMessage;
+}
+
+function toolResultMessage(
+	toolCallId: string,
+	toolName: string,
+	text: string,
+	isError: boolean,
+): AgentMessage {
+	return {
+		role: "toolResult",
+		toolCallId,
+		toolName,
+		content: text ? [{ type: "text", text }] : [],
+		isError,
+	} as AgentMessage;
+}

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

@@ -0,0 +1,255 @@
+/**
+ * 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);
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			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 (text.trim() || tools.length > 0) {
+				result.push({
+					id: `a-${result.length}`,
+					role: "assistant",
+					content: text,
+					tools: tools.map((name) => ({ name, status: "done" as const })),
+				});
+			}
+		}
+		// 忽略 toolResult 等其他类型
+	}
+
+	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);
+}