@shikeai/knowledge 0.0.0-stage → 0.8.1

package/lib/index.js

@@ -0,0 +1,375 @@
+import z from "@deepseek-ai/schemastery";
+//#region package.json
+var version = "0.8.1";
+//#endregion
+//#region src/host-entry.js
+/**
+* DSH 插件 Host 半区入口（Node 侧，构建为 lib/index.js）
+*
+* v0.9.1 重构：MCP 接入配置改走 DSH settings namespace（settings.yaml 活配置通道）：
+* 1. settings namespace —— apply 经 ctx.inject(['settings']) 调用
+*    settings.register('knowledge', McpSettingsSchema) 注册 namespace（applies 默认
+*    'live'；注册随本插件 fiber 自动清理；dsh-settings-file 把用户层持久化到
+*    ~/.dsh/settings.yaml，重启不丢）。client 半区经远程 settingsController 的
+*    describe/mutate 读写该 namespace（远程面无 register/update——注册仅宿主侧）
+* 2. scope.watch 驱动重连 —— namespace 提交变更（client 写入）触发 watch 回调 →
+*    createMcp 销毁旧连接、重建并重新注册工具，无需 patchReload / apply 重调用
+* 3. 零依赖 MCP Streamable HTTP 客户端 —— initialize / notifications/initialized /
+*    tools/list（分页）/ tools/call，把知识库 MCP 服务器的工具经 ctx.tools.register
+*    注册为 mcp__knowledge__<name>，智能体会话直接可用；会话失效（HTTP 404/400）
+*    自动重新握手重试一次；初始连接 3 次退避重试后放弃并留日志
+* 4. 显式连接生命周期（createMcp / disposeMcp）—— 模块级 currentCleanup 保存当前
+*    连接句柄；createMcp 进入即 disposeMcp 销毁旧连接再按需重建（url 为空仅销毁），
+*    清理函数同步登记覆盖「握手在途时上下文销毁」的并发窗口
+*
+* 历史结论（v0.8~v0.9.0 踩坑，勿回退）：settings namespace 是注册制——describe 只
+* 返回 settings.register 注册过的 namespace，composition 条目 id ≠ namespace，条目
+* Config 不在 describe 视图中；dsh-mcp-client 的 union schema Config 无法经 settings
+* 通道驱动（volatileForm 死路）；远程 settings 面无 register（client 侧兜底注册永不
+* 成立）。
+*
+* 运行时依赖：@deepseek-ai/schemastery（构造 namespace schema，版本与 profile 一致，
+* 构建时打进 bundle）；其余仅使用全局 fetch（Node 18+）与宿主注入的 ctx 能力。
+*/
+/** 插件标识（与包名一致，bundle patch 的 name 字段对应） */
+const name = "@shikeai/knowledge";
+/** 不声明硬依赖：tools 服务在 apply 内按需经 ctx.inject 动态获取（缺失不阻断激活） */
+const inject = [];
+/** knowledge settings namespace（client 半区 host-mcp-sync.js 的 MCP_NS 同名） */
+const MCP_SETTINGS_NS = "knowledge";
+/**
+* namespace schema：{ url, token }
+* token 不标记 role('secret')：远程 describe 会脱敏 secret 字段，client 半区需要
+* 回读完整值做幂等比对；本地 settings.yaml 明文存储与 v0.8 桥接行为一致
+*/
+const McpSettingsSchema = z.object({
+	url: z.string().default(""),
+	token: z.string().default("")
+});
+/** 已注册的 namespace scope（fiber 存续期复用；dispose 时复位，下次 apply 重新注册） */
+let registeredScope = null;
+/** 当前 scope.watch 的注销函数 */
+let unwatchScope = null;
+const PROTOCOL_VERSION = "2025-06-18";
+const CLIENT_INFO = {
+	name: "@shikeai/knowledge",
+	version
+};
+const ACCEPT = "application/json, text/event-stream";
+const SESSION_HEADER = "mcp-session-id";
+const RPC_TIMEOUT_MS = 15e3;
+let rpcSeq = 0;
+/**
+* 单次 JSON-RPC 调用（application/json 与 text/event-stream 响应自适应；
+* initialize 响应头中的 mcp-session-id 经 onSession 回调带回）
+*/
+async function mcpRpc(url, token, sessionId, method, params, options = {}) {
+	const id = ++rpcSeq;
+	const headers = {
+		"Content-Type": "application/json",
+		Accept: ACCEPT
+	};
+	if (token) headers.Authorization = `Bearer ${token}`;
+	if (sessionId) headers[SESSION_HEADER] = sessionId;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`MCP ${method} 超时`)), RPC_TIMEOUT_MS);
+	let res;
+	try {
+		res = await fetch(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			}),
+			signal: controller.signal
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		const error = /* @__PURE__ */ new Error(`MCP ${method} HTTP ${res.status}${text ? `：${text.slice(0, 200)}` : ""}`);
+		error.status = res.status;
+		throw error;
+	}
+	if (method === "initialize") {
+		const sid = res.headers.get(SESSION_HEADER);
+		if (sid) options.onSession?.(sid);
+	}
+	const contentType = res.headers.get("content-type") || "";
+	let message;
+	if (contentType.includes("text/event-stream")) {
+		message = await readSseMessage(res, id);
+		if (!message) throw new Error(`MCP ${method}：SSE 流中未收到 id=${id} 的响应`);
+	} else message = await res.json();
+	if (message.error) throw new Error(`MCP ${method} 失败：${message.error.message || JSON.stringify(message.error)}`);
+	return message.result;
+}
+/** 从 SSE 流中解析出 id 匹配的 JSON-RPC 响应（读完即取消，不挂住连接） */
+async function readSseMessage(res, wantId) {
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let index;
+			while ((index = buffer.indexOf("\n\n")) >= 0) {
+				const block = buffer.slice(0, index);
+				buffer = buffer.slice(index + 2);
+				for (const line of block.split("\n")) {
+					if (!line.startsWith("data:")) continue;
+					const data = line.slice(5).trim();
+					if (!data) continue;
+					try {
+						const message = JSON.parse(data);
+						if (message.id === wantId) return message;
+					} catch {}
+				}
+			}
+		}
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+	}
+	return null;
+}
+/** 通知类消息（无 id；202/200 均视为成功） */
+async function mcpNotify(url, token, sessionId, method, params) {
+	const headers = {
+		"Content-Type": "application/json",
+		Accept: ACCEPT
+	};
+	if (token) headers.Authorization = `Bearer ${token}`;
+	if (sessionId) headers[SESSION_HEADER] = sessionId;
+	const res = await fetch(url, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			method,
+			params
+		})
+	});
+	if (!res.ok && res.status !== 202) throw new Error(`MCP 通知 ${method} HTTP ${res.status}`);
+	try {
+		await res.body?.cancel();
+	} catch {}
+}
+/** MCP 握手：initialize → notifications/initialized → tools/list（分页取全） */
+async function handshake(url, token, session) {
+	const initialize = async () => {
+		let sessionId = "";
+		await mcpRpc(url, token, "", "initialize", {
+			protocolVersion: PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: CLIENT_INFO
+		}, { onSession: (sid) => {
+			sessionId = sid;
+		} });
+		await mcpNotify(url, token, sessionId, "notifications/initialized", {});
+		session.id = sessionId;
+		return sessionId;
+	};
+	await initialize();
+	const list = [];
+	let cursor;
+	do {
+		const result = await mcpRpc(url, token, session.id, "tools/list", cursor ? { cursor } : {});
+		list.push(...result?.tools ?? []);
+		cursor = result?.nextCursor;
+	} while (cursor);
+	return list;
+}
+/** content 数组转纯文本（text 项拼接；无 text 项时 JSON 兜底） */
+function textOfContent(content) {
+	if (!Array.isArray(content)) return "";
+	const texts = content.filter((item) => item && item.type === "text").map((item) => item.text ?? "");
+	if (texts.length) return texts.join("\n");
+	return content.length ? JSON.stringify(content) : "";
+}
+/** tools/call：会话失效（HTTP 404/400）时重新握手一次后重试 */
+async function callTool(url, token, session, rawName, args) {
+	try {
+		return await mcpRpc(url, token, session.id, "tools/call", {
+			name: rawName,
+			arguments: args
+		});
+	} catch (error) {
+		if (error?.status !== 404 && error?.status !== 400) throw error;
+		console.info(`[knowledge] MCP 会话失效（HTTP ${error.status}），重新握手后重试 ${rawName}`);
+		await handshake(url, token, session);
+		return await mcpRpc(url, token, session.id, "tools/call", {
+			name: rawName,
+			arguments: args
+		});
+	}
+}
+/** 构建单个 DSH 工具定义（形状对齐 dsh-mcp-client 的 createToolDefinition） */
+function makeToolDefinition(tool, url, token, session) {
+	const rawName = tool.name;
+	return {
+		name: `mcp__knowledge__${rawName}`,
+		description: tool.description || "",
+		parameters: tool.inputSchema || {
+			type: "object",
+			properties: {}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					content: {
+						type: "array",
+						items: {}
+					},
+					structuredContent: {
+						type: "object",
+						properties: {},
+						required: []
+					}
+				},
+				required: ["content"],
+				additionalProperties: false
+			},
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: textOfContent(value?.content)
+				}];
+			}
+		},
+		execute: async (args) => {
+			const result = await callTool(url, token, session, rawName, args ?? {});
+			if (result?.isError) throw new Error(textOfContent(result.content) || "知识库工具执行失败");
+			const out = { content: result?.content ?? [] };
+			if (result?.structuredContent !== void 0) out.structuredContent = result.structuredContent;
+			return out;
+		}
+	};
+}
+/** 当前 MCP 连接的清理函数（mcpClient 实例句柄等价物；null = 无活动连接） */
+let currentCleanup = null;
+/** disposeMcp：销毁当前 MCP 连接并注销已注册工具（幂等，可安全重复调用） */
+function disposeMcp() {
+	const cleanup = currentCleanup;
+	currentCleanup = null;
+	if (cleanup) cleanup();
+}
+/**
+* createMcp：销毁旧连接后建立新连接并注册工具（apply 首次加载与配置变更热更新共用入口）
+* - 进入即同步登记本次清理函数：覆盖「握手在途时上下文被销毁」的并发窗口，
+*   清理后握手循环 / 工具注册经 state.disposed 短路，不产生僵尸工具
+* - 连接失败（3 次退避重试后）解除登记并留日志，等待下次配置变更或 DSH 重启重试
+*/
+async function createMcp(tools, url, token) {
+	disposeMcp();
+	if (!url) {
+		console.info("[knowledge] MCP 接入点未配置（url 为空）：设置页配置服务器后自动同步重连");
+		return;
+	}
+	const state = { disposed: false };
+	const disposers = [];
+	const cleanup = () => {
+		state.disposed = true;
+		while (disposers.length) try {
+			disposers.pop()();
+		} catch {}
+	};
+	currentCleanup = cleanup;
+	const session = { id: "" };
+	let list = null;
+	let lastError = null;
+	for (let attempt = 1; attempt <= 3; attempt++) {
+		if (state.disposed) return;
+		try {
+			list = await handshake(url, token, session);
+			break;
+		} catch (error) {
+			lastError = error;
+			console.warn(`[knowledge] MCP 连接失败（第 ${attempt}/3 次）`, error?.message || error);
+			if (attempt < 3) await new Promise((resolve) => setTimeout(resolve, attempt * 1e3));
+		}
+	}
+	if (state.disposed) return;
+	if (!list) {
+		currentCleanup = null;
+		console.warn("[knowledge] MCP 连接最终失败（配置变更或重启 DSH 后重试）", lastError?.message || "");
+		return;
+	}
+	console.info(`[knowledge] MCP 已连接：服务器暴露 ${list.length} 个工具`);
+	for (const tool of list) {
+		if (state.disposed) return;
+		if (!tool || typeof tool.name !== "string" || !tool.name) continue;
+		try {
+			const dispose = tools.register(makeToolDefinition(tool, url, token, session));
+			if (typeof dispose === "function") disposers.push(dispose);
+		} catch (error) {
+			console.warn(`[knowledge] 工具 ${tool.name} 注册失败`, error?.message || error);
+		}
+	}
+	console.info("[knowledge] MCP 工具注册完成（mcp__knowledge__*）");
+}
+/**
+* 插件 apply：注册 knowledge settings namespace 并驱动 MCP 连接生命周期
+* - namespace 注册（幂等，重复 apply 复用已注册 scope；随本插件 fiber 自动清理，
+*   applies 默认 'live'）。注册完成后 client 半区的 describe/mutate 才能查到并
+*   写入该 namespace——这是「设置页 MCP 未就绪」问题的根因修复点
+* - scope.watch：client 半区经远程 settingsController mutate 写入 namespace 后，
+*   以提交的新值 createMcp 销毁旧连接、重建并重新注册工具（无需 patchReload）
+* - 初次建连：以 scope.get() 当前解析值直接建连（watch 仅在提交变更后触发）
+*/
+function apply(ctx) {
+	ctx.effect(() => {
+		disposeMcp();
+		if (unwatchScope) {
+			try {
+				unwatchScope();
+			} catch {}
+			unwatchScope = null;
+		}
+		registeredScope = null;
+	});
+	try {
+		ctx.inject(["settings", "tools"], (injectedCtx) => {
+			const settingsSvc = injectedCtx.settings;
+			if (!settingsSvc || typeof settingsSvc.register !== "function") {
+				console.warn("[knowledge] 宿主 settings 服务无 register 能力，MCP 配置通道不可用");
+				return;
+			}
+			const toolsSvc = injectedCtx.tools;
+			const tools = typeof toolsSvc?.register === "function" ? toolsSvc : toolsSvc?.tools;
+			if (!tools || typeof tools.register !== "function") {
+				console.warn("[knowledge] 宿主 tools 服务无 register 能力，MCP 工具未注册");
+				return;
+			}
+			if (!registeredScope) {
+				try {
+					registeredScope = settingsSvc.register(MCP_SETTINGS_NS, McpSettingsSchema);
+				} catch (error) {
+					console.warn("[knowledge] settings namespace 注册失败，MCP 配置通道不可用", error?.message || error);
+					return;
+				}
+				console.info(`[knowledge] settings namespace '${MCP_SETTINGS_NS}' 已注册（MCP 配置通道就绪）`);
+			}
+			if (unwatchScope) try {
+				unwatchScope();
+			} catch {}
+			unwatchScope = registeredScope.watch((next) => {
+				createMcp(tools, String(next?.url ?? "").trim(), String(next?.token ?? ""));
+			});
+			const value = registeredScope.get() || {};
+			createMcp(tools, String(value.url ?? "").trim(), String(value.token ?? ""));
+		});
+	} catch (error) {
+		console.warn("[knowledge] settings/tools 服务注入失败，MCP 未就绪", error?.message || error);
+	}
+}
+//#endregion
+export { apply, inject, name };

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@shikeai/knowledge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "时刻AI平台桌面端知识库插件（DSH/Cordis 插件）：知识管理（右侧抽屉 + 插件管理页官方插件条目）、成员权限、MCP RAG 检索服务、服务器配置项用户中心云持久化",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./standalone": "./dist/index.es.js",
+    "./dist/*": "./dist/*",
+    "./public/*": "./public/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "dist",
+    "public",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsdown && vite build",
+    "build:lib": "tsdown",
+    "build:lib:watch": "tsdown --watch",
+    "build:standalone": "vite build",
+    "preview": "vite preview"
+  },
+  "keywords": [
+    "shikeai",
+    "knowledge",
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin"
+  ],
+  "author": "shikeai",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "private": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.2"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsdown": "^0.22.2",
+    "vite": "^5.4.10"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.