@joekytc/dsh-swarm 0.1.2 → 0.2.0

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

@@ -0,0 +1,263 @@
+/**
+ * 知识库上下文 Extension
+ *
+ * 阶段一 step 5：向 agent 注入"当前在哪个知识库"的概念。
+ * 不通过拼 system prompt 实现（ADR-7），而是注册工具让 agent 主动查询。
+ *
+ * 工具：
+ *   current_knowledge_base()        → 返回当前库路径 + 元数据
+ *   list_knowledge_base_pages()     → 列出 wiki/ 下所有 .md 文件
+ *
+ * 模块级状态：currentKnowledgeBase
+ *   HTTP 层通过 setCurrentKnowledgeBase() 改它，Extension 工具读它。
+ *   Extension 是单例（一个 process 一份），所以 module state 等价于应用状态。
+ */
+
+import type { Dirent } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { inspectKnowledgeBasePath } from "../knowledge-bases.js";
+import {
+	formatSearchResultsForTool,
+	searchKnowledgeBase,
+} from "../retrieval.js";
+
+// ============= 状态 =============
+
+interface KnowledgeBaseState {
+	path: string;
+	name: string;
+}
+
+let current: KnowledgeBaseState | null = null;
+let pendingKnowledgeContext: string | null = null;
+
+export function getCurrentKnowledgeBase(): KnowledgeBaseState | null {
+	return current;
+}
+
+export async function setCurrentKnowledgeBase(absolutePath: string): Promise<KnowledgeBaseState> {
+	// 共享的有效性检查（PRODUCT.md §6.2 约定）
+	const check = await inspectKnowledgeBasePath(absolutePath);
+	if (!check.valid) {
+		throw new Error(`不是合法知识库（${check.reason}）：${absolutePath}`);
+	}
+
+	const name = absolutePath.split("/").filter(Boolean).pop() ?? absolutePath;
+	current = { path: absolutePath, name };
+	return current;
+}
+
+export function clearCurrentKnowledgeBase(): void {
+	current = null;
+}
+
+export function setPendingKnowledgeContext(context: string): void {
+	pendingKnowledgeContext = context;
+}
+
+export function clearPendingKnowledgeContext(): void {
+	pendingKnowledgeContext = null;
+}
+
+// ============= Extension =============
+
+/**
+ * agent 不读这些目录 / 文件（PRODUCT.md §6.4 Obsidian 共存规则）
+ */
+const IGNORE_NAMES = new Set([
+	".obsidian",
+	".DS_Store",
+	".wiki-tmp",
+	".git",
+	"node_modules",
+	".venv",
+	"venv",
+	".cache",
+]);
+
+const IGNORE_SUFFIXES = [".base", ".canvas"];
+
+function shouldIgnore(name: string): boolean {
+	if (IGNORE_NAMES.has(name)) return true;
+	return IGNORE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+async function listMarkdownFiles(rootDir: string, base: string): Promise<string[]> {
+	const results: string[] = [];
+
+	async function walk(dir: string): Promise<void> {
+		let entries: Dirent[];
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (shouldIgnore(entry.name)) continue;
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				await walk(full);
+			} else if (entry.isFile() && entry.name.endsWith(".md")) {
+				results.push(relative(base, full));
+			}
+		}
+	}
+
+	await walk(rootDir);
+	results.sort();
+	return results;
+}
+
+export default function knowledgeBaseExtension(pi: ExtensionAPI) {
+	pi.on("before_agent_start", async (event) => {
+		const context = pendingKnowledgeContext;
+		if (!context) return undefined;
+		pendingKnowledgeContext = null;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${context}`,
+		};
+	});
+
+	pi.registerTool({
+		name: "current_knowledge_base",
+		label: "当前知识库",
+		description:
+			"Get the absolute filesystem path and basic metadata of the user's currently active knowledge base. ALWAYS call this FIRST before reading, writing, or listing files in the user's knowledge base, since file paths depend on which library the user has selected. Returns an error message if no knowledge base is selected.",
+		parameters: Type.Object({}),
+		async execute(): Promise<{
+			content: { type: "text"; text: string }[];
+			details: Record<string, unknown>;
+		}> {
+			if (!current) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "No knowledge base is currently selected. Ask the user to pick one.",
+						},
+					],
+					details: { selected: false },
+				};
+			}
+
+			// 读 purpose.md 给 agent 一段"这是什么库"的提示
+			let purpose = "";
+			try {
+				purpose = (await readFile(join(current.path, "purpose.md"), "utf8")).slice(0, 500);
+			} catch {
+				// 没 purpose.md 也无所谓
+			}
+
+			const text = [
+				`Current knowledge base:`,
+				`  name: ${current.name}`,
+				`  path: ${current.path}`,
+				purpose ? `\nResearch direction (from purpose.md):\n${purpose}` : "",
+			]
+				.filter(Boolean)
+				.join("\n");
+
+			return {
+				content: [{ type: "text", text }],
+				details: {
+					selected: true,
+					path: current.path,
+					name: current.name,
+				},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "list_knowledge_base_pages",
+		label: "列出知识库页面",
+		description:
+			"List all markdown wiki pages in the user's currently active knowledge base (under raw/ and wiki/, excluding Obsidian / dev / temp files). Returns relative paths from the knowledge base root. Use this to discover what content exists before answering questions about the user's wiki.",
+		parameters: Type.Object({}),
+		async execute(): Promise<{
+			content: { type: "text"; text: string }[];
+			details: Record<string, unknown>;
+		}> {
+			if (!current) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "No knowledge base is currently selected.",
+						},
+					],
+					details: { selected: false },
+				};
+			}
+
+			try {
+				const files = await listMarkdownFiles(current.path, current.path);
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								files.length === 0
+									? "(Knowledge base is empty)"
+									: `${files.length} markdown files:\n${files.join("\n")}`,
+						},
+					],
+					details: { selected: true, count: files.length, files, path: current.path },
+				};
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `Error listing files: ${msg}` }],
+					details: { selected: true, error: msg },
+				};
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "query_knowledge_base",
+		label: "检索知识库",
+		description:
+			"Search the user's current knowledge base for pages relevant to a query. Use this when the user asks a follow-up question that may require pulling additional context from the knowledge base beyond what's already in the conversation.",
+		parameters: Type.Object({
+			query: Type.String(),
+		}),
+		async execute(
+			_toolCallId: string,
+			params: { query?: string },
+		): Promise<{
+			content: { type: "text"; text: string }[];
+			details: Record<string, unknown>;
+		}> {
+			if (!current) {
+				return {
+					content: [{ type: "text", text: "No knowledge base is currently selected." }],
+					details: { selected: false },
+				};
+			}
+			const query = params.query?.trim() ?? "";
+			if (!query) {
+				return {
+					content: [{ type: "text", text: "query 不能为空。" }],
+					details: { selected: true, count: 0, files: [] },
+				};
+			}
+			const search = await searchKnowledgeBase(current.path, query, {
+				totalBudgetChars: 4000,
+			});
+			return {
+				content: [{ type: "text", text: formatSearchResultsForTool(search) }],
+				details: {
+					selected: true,
+					count: search.results.length,
+					files: search.results.map((result) => result.path),
+				},
+			};
+		},
+	});
+}

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

@@ -0,0 +1,42 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { createWiki } from "../wiki-init.js";
+
+interface NewWikiParams {
+	name: string;
+	purpose: 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 createNewWikiExtension() {
+	return function newWikiExtension(pi: ExtensionAPI) {
+		pi.registerTool({
+			name: "new_wiki",
+			label: "新建知识库",
+			description:
+				"在默认知识库根目录下新建一个 llm-wiki 知识库，调用已安装的 llm-wiki-skill 初始化脚本。",
+			parameters: Type.Object({
+				name: Type.String(),
+				purpose: Type.String(),
+			}),
+			async execute(_toolCallId, params: NewWikiParams) {
+				try {
+					const result = await createWiki(params.name, params.purpose);
+					return toolResult(`知识库已创建：~/llm-wiki/${result.name}`, { ...result });
+				} catch (err) {
+					const error = err as Error & { stdout?: string; stderr?: string };
+					return toolResult(`创建知识库失败：${error.message}`, {
+						stdout: error.stdout ?? "",
+						stderr: error.stderr ?? "",
+					});
+				}
+			},
+		});
+	};
+}

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

@@ -0,0 +1,172 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import type { ActiveContext } from "../agent.js";
+
+type ToolContent = { type: "text"; text: string };
+
+interface SedimentParams {
+	topic?: string;
+	note?: string;
+}
+
+function formatLocalIso(date: Date): string {
+	const offsetMinutes = -date.getTimezoneOffset();
+	const sign = offsetMinutes >= 0 ? "+" : "-";
+	const abs = Math.abs(offsetMinutes);
+	const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+	const mm = String(abs % 60).padStart(2, "0");
+	const yyyy = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	const hour = String(date.getHours()).padStart(2, "0");
+	const minute = String(date.getMinutes()).padStart(2, "0");
+	const second = String(date.getSeconds()).padStart(2, "0");
+	return `${yyyy}-${month}-${day}T${hour}:${minute}:${second}${sign}${hh}:${mm}`;
+}
+
+function filenameStamp(date: Date): string {
+	const yyyy = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	const hour = String(date.getHours()).padStart(2, "0");
+	const minute = String(date.getMinutes()).padStart(2, "0");
+	return `${yyyy}-${month}-${day}-${hour}${minute}`;
+}
+
+function extractText(message: AgentMessage): string {
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object") return "";
+			const record = part as Record<string, unknown>;
+			return record.type === "text" && typeof record.text === "string" ? record.text : "";
+		})
+		.join("");
+}
+
+function extractToolNames(message: AgentMessage): string[] {
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return [];
+	const names: string[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") continue;
+		const record = part as Record<string, unknown>;
+		if (record.type !== "tool_call" && record.type !== "toolCall") continue;
+		if (typeof record.name === "string") names.push(record.name);
+		else if (typeof record.toolName === "string") names.push(record.toolName);
+	}
+	return names;
+}
+
+function slugify(input: string): string {
+	const slug = input
+		.trim()
+		.replace(/[^\p{Script=Han}\p{Letter}\p{Number}-]+/gu, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+	return slug || "chat";
+}
+
+function firstUserMessage(messages: AgentMessage[]): string {
+	for (const message of messages) {
+		if (message.role === "user") {
+			const text = extractText(message).trim();
+			if (text) return text.slice(0, 20);
+		}
+	}
+	return "chat";
+}
+
+function renderMessages(messages: AgentMessage[]): string {
+	const parts: string[] = [];
+	for (const message of messages) {
+		if (message.role !== "user" && message.role !== "assistant") continue;
+		const text = extractText(message).trim();
+		const tools = extractToolNames(message);
+		if (!text && tools.length === 0) continue;
+
+		parts.push(message.role === "user" ? "## 👤 用户" : "## 🤖 助手");
+		if (text) parts.push(text);
+		if (tools.length > 0) {
+			parts.push(
+				[
+					"<details>",
+					"<summary>工具调用</summary>",
+					"",
+					tools.map((name) => `- ${name}`).join("\n"),
+					"",
+					"</details>",
+				].join("\n"),
+			);
+		}
+	}
+	return parts.join("\n\n").trimEnd() + "\n";
+}
+
+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("目标路径不在 sessions 目录内");
+	}
+}
+
+function toolResult(text: string, details: Record<string, unknown> = {}) {
+	return { content: [{ type: "text", text } satisfies ToolContent], details };
+}
+
+export function createSynthesisExtension(getActive: () => ActiveContext | null) {
+	return function synthesisExtension(pi: ExtensionAPI) {
+		pi.registerTool({
+			name: "sediment_to_wiki",
+			label: "结晶到知识库",
+			description:
+				"把当前对话结晶为当前知识库 wiki/synthesis/sessions/ 下的一个 markdown 文件。可选 topic 影响文件名。",
+			parameters: Type.Object({
+				topic: Type.Optional(Type.String()),
+				note: Type.Optional(Type.String()),
+			}),
+			async execute(_toolCallId, params: SedimentParams) {
+				const active = getActive();
+				if (!active) return toolResult("当前没有活跃知识库。请先选择一个知识库。");
+
+				const messages = active.session.state.messages;
+				if (messages.length === 0) {
+					return toolResult("当前对话还没有可结晶的内容。");
+				}
+
+				const now = new Date();
+				const sessionsDir = path.join(active.kb.path, "wiki", "synthesis", "sessions");
+				await mkdir(sessionsDir, { recursive: true });
+
+				const topic = params.topic?.trim() ?? "";
+				const slugSource = topic || firstUserMessage(messages);
+				const filename = `${filenameStamp(now)}-${slugify(slugSource)}.md`;
+				const targetPath = path.join(sessionsDir, filename);
+				assertInside(sessionsDir, targetPath);
+
+				const relPath = path.posix.join("wiki", "synthesis", "sessions", filename);
+				const body = [
+					"---",
+					`date: ${formatLocalIso(now)}`,
+					"source: chat",
+					`conversation_id: ${active.conversationId}`,
+					`topic: ${topic}`,
+					"---",
+					params.note?.trim() ? `\n${params.note.trim()}` : "",
+					"\n" + renderMessages(messages),
+				].join("\n");
+
+				await writeFile(targetPath, body, "utf8");
+				return toolResult(`已结晶为 ${relPath}`, { path: relPath });
+			},
+		});
+	};
+}

package/skills/llm-wiki-skill/workbench/server/src/graph-watcher.test.ts

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+	GraphRebuildQueue,
+	KnowledgeBaseGraphWatcher,
+	shouldIgnoreGraphWatchPath,
+} from "./graph.js";
+
+test("graph watcher debounces rebuild triggers", async () => {
+	const clock = new FakeClock();
+	const events = new FakeWatchSource();
+	const triggered: string[] = [];
+	const watcher = new KnowledgeBaseGraphWatcher({
+		createWatcher: (_kbPath, onEvent) => events.create(onEvent),
+		triggerRebuild: (kbPath) => {
+			triggered.push(kbPath);
+			return { ok: true, status: "started" };
+		},
+		debounceMs: 50,
+	});
+	using _timers = clock.install();
+
+	watcher.start("/kb");
+	events.emit("wiki/a.md");
+	events.emit("wiki/b.md");
+	assert.deepEqual(triggered, []);
+	await clock.advance(49);
+	assert.deepEqual(triggered, []);
+	await clock.advance(1);
+	assert.deepEqual(triggered, ["/kb"]);
+	watcher.stop();
+});
+
+test("graph watcher ignores external noise and generated graph artifacts", async () => {
+	const clock = new FakeClock();
+	const events = new FakeWatchSource();
+	const triggered: string[] = [];
+	const watcher = new KnowledgeBaseGraphWatcher({
+		createWatcher: (_kbPath, onEvent) => events.create(onEvent),
+		triggerRebuild: (kbPath) => {
+			triggered.push(kbPath);
+			return { ok: true, status: "started" };
+		},
+		debounceMs: 10,
+	});
+	using _timers = clock.install();
+
+	watcher.start("/kb");
+	for (const filename of [
+		".wiki-tmp/run.json",
+		".git/index",
+		".obsidian/workspace.json",
+		"node_modules/pkg/index.js",
+		".DS_Store",
+		"wiki/graph-data.json",
+		"wiki/knowledge-graph.html",
+		"wiki/knowledge-graph-dark.html",
+		".wiki-graph-layout.json",
+	]) {
+		assert.equal(shouldIgnoreGraphWatchPath(filename), true, filename);
+		events.emit(filename);
+	}
+	await clock.advance(20);
+	assert.deepEqual(triggered, []);
+
+	events.emit("wiki/topics/new-page.md");
+	await clock.advance(10);
+	assert.deepEqual(triggered, ["/kb"]);
+	watcher.stop();
+});
+
+test("graph watcher suspends during batch digest and resumes with one immediate rebuild", async () => {
+	const events = new FakeWatchSource();
+	const triggered: string[] = [];
+	const watcher = new KnowledgeBaseGraphWatcher({
+		createWatcher: (_kbPath, onEvent) => events.create(onEvent),
+		triggerRebuild: (kbPath) => {
+			triggered.push(kbPath);
+			return { ok: true, status: "started" };
+		},
+		debounceMs: 10,
+	});
+
+	watcher.start("/kb");
+	watcher.suspend("/kb");
+	events.emit("wiki/synthesis/sessions/a.md");
+	events.emit("wiki/synthesis/sessions/b.md");
+	assert.deepEqual(triggered, []);
+	watcher.resume("/kb", { trigger: true });
+	assert.deepEqual(triggered, ["/kb"]);
+	watcher.stop();
+});
+
+test("graph rebuild queue merges triggers into one pending rebuild while running", async () => {
+	const gates = [deferred<void>(), deferred<void>()];
+	const calls: string[] = [];
+	let rebuildIndex = 0;
+	const queue = new GraphRebuildQueue({
+		run: async () => {
+			const gate = gates[rebuildIndex++];
+			assert.ok(gate);
+			calls.push("run");
+			await gate.promise;
+		},
+		onError: (err) => {
+			throw err;
+		},
+	});
+
+	assert.equal(queue.trigger().status, "started");
+	assert.equal(queue.trigger().status, "queued");
+	assert.equal(queue.trigger().status, "queued");
+	await Promise.resolve();
+	assert.deepEqual(calls, ["run"]);
+	gates[0]?.resolve();
+	await waitFor(() => calls.length >= 2);
+	assert.deepEqual(calls, ["run", "run"]);
+	gates[1]?.resolve();
+	await queue.waitForIdle();
+	assert.deepEqual(calls, ["run", "run"]);
+});
+
+class FakeWatchSource {
+	private onEvent: ((event: { eventType: string; filename: string | null }) => void) | null = null;
+
+	create(onEvent: (event: { eventType: string; filename: string | null }) => void) {
+		this.onEvent = onEvent;
+		return {
+			close: () => {
+				this.onEvent = null;
+			},
+		};
+	}
+
+	emit(filename: string): void {
+		this.onEvent?.({ eventType: "rename", filename });
+	}
+}
+
+class FakeClock {
+	private now = 0;
+	private nextId = 1;
+	private tasks = new Map<number, { due: number; callback: () => void }>();
+	private originalSetTimeout = globalThis.setTimeout;
+	private originalClearTimeout = globalThis.clearTimeout;
+
+	install() {
+		const self = this;
+		globalThis.setTimeout = ((callback: () => void, ms?: number) => {
+			const id = self.nextId++;
+			self.tasks.set(id, { due: self.now + Number(ms ?? 0), callback });
+			return id as unknown as ReturnType<typeof setTimeout>;
+		}) as typeof setTimeout;
+		globalThis.clearTimeout = ((id: ReturnType<typeof setTimeout>) => {
+			self.tasks.delete(Number(id));
+		}) as typeof clearTimeout;
+		return {
+			[Symbol.dispose]: () => this.restore(),
+		};
+	}
+
+	async advance(ms: number): Promise<void> {
+		this.now += ms;
+		const due = Array.from(this.tasks.entries())
+			.filter(([, task]) => task.due <= this.now)
+			.sort((a, b) => a[1].due - b[1].due);
+		for (const [id, task] of due) {
+			if (!this.tasks.delete(id)) continue;
+			task.callback();
+		}
+		await Promise.resolve();
+	}
+
+	private restore(): void {
+		globalThis.setTimeout = this.originalSetTimeout;
+		globalThis.clearTimeout = this.originalClearTimeout;
+		this.tasks.clear();
+	}
+}
+
+function deferred<T>() {
+	let resolve!: (value: T | PromiseLike<T>) => void;
+	const promise = new Promise<T>((innerResolve) => {
+		resolve = innerResolve;
+	});
+	return { promise, resolve };
+}
+
+async function waitFor(predicate: () => boolean): Promise<void> {
+	for (let i = 0; i < 20; i++) {
+		if (predicate()) return;
+		await Promise.resolve();
+	}
+	assert.equal(predicate(), true);
+}