@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/lib/data-dir.js

@@ -1,13 +1,13 @@
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-let resolved = null;
-function resolveDataDirPath(options = {}) {
-  const configured = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
-  return path.resolve(configured || path.join(options.homeDir || os.homedir(), '.project-knowledge-v5'));
-}
-function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
-function getDataDir() { if (!resolved) resolved = resolveDataDirPath(); return resolved; }
-function _resetCache() { resolved = null; }
-module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, _resetCache };
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+let resolved = null;
+function resolveDataDirPath(options = {}) {
+  const configured = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
+  return path.resolve(configured || path.join(options.homeDir || os.homedir(), '.project-knowledge-v5'));
+}
+function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
+function getDataDir() { if (!resolved) resolved = resolveDataDirPath(); return resolved; }
+function _resetCache() { resolved = null; }
+module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, _resetCache };

package/_site/lib/embedding-service.js

@@ -1,85 +1,85 @@
-const path = require('path');
-const { EMBEDDING_DIMENSIONS } = require('./knowledge-schema');
-
-const DEFAULT_MODEL_ID = 'Xenova/bge-small-zh-v1.5';
-const QUERY_PREFIX = '为这个句子生成表示以用于检索相关文章：';
-
-class LocalEmbeddingService {
-  constructor(options = {}) {
-    this.modelId = options.modelId || DEFAULT_MODEL_ID;
-    this.cacheDir = options.cacheDir ? path.resolve(options.cacheDir) : null;
-    this.remoteHost = String(options.remoteHost || process.env.KB_EMBEDDING_REMOTE_HOST || process.env.HF_ENDPOINT || 'https://huggingface.co/').trim();
-    this.localModelPath = options.localModelPath || process.env.KB_EMBEDDING_LOCAL_PATH || '';
-    this.localFilesOnly = options.localFilesOnly === true;
-    this.pipelineFactory = options.pipelineFactory || null;
-    this.extractor = null;
-    this.loading = null;
-  }
-
-  async load() {
-    if (this.extractor) return this.extractor;
-    if (this.loading) return this.loading;
-    this.loading = (async () => {
-      let pipelineFactory = this.pipelineFactory;
-      if (!pipelineFactory) {
-        const transformers = await import('@huggingface/transformers');
-        if (this.cacheDir) transformers.env.cacheDir = this.cacheDir;
-        if (this.remoteHost) transformers.env.remoteHost = `${this.remoteHost.replace(/\/+$/, '')}/`;
-        if (this.localModelPath) transformers.env.localModelPath = path.resolve(this.localModelPath);
-        transformers.env.allowRemoteModels = !this.localFilesOnly;
-        pipelineFactory = transformers.pipeline;
-      }
-      const extractor = await pipelineFactory('feature-extraction', this.modelId, {
-        dtype: 'fp32',
-        local_files_only: this.localFilesOnly,
-      });
-      this.extractor = extractor;
-      return extractor;
-    })();
-    try {
-      return await this.loading;
-    } catch (error) {
-      const hint = this.localFilesOnly
-        ? `Local model files were not found. Set KB_EMBEDDING_LOCAL_PATH to a directory containing ${this.modelId}.`
-        : `Could not load ${this.modelId} from ${this.remoteHost}. Check the network, or set KB_EMBEDDING_REMOTE_HOST / KB_EMBEDDING_LOCAL_PATH.`;
-      throw new Error(`${hint} ${error.message}`, { cause: error });
-    } finally {
-      this.loading = null;
-    }
-  }
-
-  async embed(text, options = {}) {
-    const normalized = String(text || '').trim();
-    if (!normalized) throw new Error('text is required for embedding');
-    const extractor = await this.load();
-    const input = options.kind === 'query' ? `${QUERY_PREFIX}${normalized}` : normalized;
-    const output = await extractor(input, { pooling: 'cls', normalize: true });
-    const vector = Array.from(output.data || output.tolist?.()[0] || [], Number);
-    if (vector.length !== EMBEDDING_DIMENSIONS) {
-      throw new Error(`embedding model returned ${vector.length} dimensions; expected ${EMBEDDING_DIMENSIONS}`);
-    }
-    return vector;
-  }
-
-  embedQuery(text) {
-    return this.embed(text, { kind: 'query' });
-  }
-
-  embedPassage(text) {
-    return this.embed(text, { kind: 'passage' });
-  }
-
-  status() {
-    return {
-      modelId: this.modelId,
-      dimensions: EMBEDDING_DIMENSIONS,
-      cacheDir: this.cacheDir,
-      remoteHost: this.remoteHost,
-      localModelPath: this.localModelPath || null,
-      loaded: !!this.extractor,
-      localFilesOnly: this.localFilesOnly,
-    };
-  }
-}
-
-module.exports = { LocalEmbeddingService, DEFAULT_MODEL_ID, QUERY_PREFIX };
+const path = require('path');
+const { EMBEDDING_DIMENSIONS } = require('./knowledge-schema');
+
+const DEFAULT_MODEL_ID = 'Xenova/bge-small-zh-v1.5';
+const QUERY_PREFIX = '为这个句子生成表示以用于检索相关文章：';
+
+class LocalEmbeddingService {
+  constructor(options = {}) {
+    this.modelId = options.modelId || DEFAULT_MODEL_ID;
+    this.cacheDir = options.cacheDir ? path.resolve(options.cacheDir) : null;
+    this.remoteHost = String(options.remoteHost || process.env.KB_EMBEDDING_REMOTE_HOST || process.env.HF_ENDPOINT || 'https://huggingface.co/').trim();
+    this.localModelPath = options.localModelPath || process.env.KB_EMBEDDING_LOCAL_PATH || '';
+    this.localFilesOnly = options.localFilesOnly === true;
+    this.pipelineFactory = options.pipelineFactory || null;
+    this.extractor = null;
+    this.loading = null;
+  }
+
+  async load() {
+    if (this.extractor) return this.extractor;
+    if (this.loading) return this.loading;
+    this.loading = (async () => {
+      let pipelineFactory = this.pipelineFactory;
+      if (!pipelineFactory) {
+        const transformers = await import('@huggingface/transformers');
+        if (this.cacheDir) transformers.env.cacheDir = this.cacheDir;
+        if (this.remoteHost) transformers.env.remoteHost = `${this.remoteHost.replace(/\/+$/, '')}/`;
+        if (this.localModelPath) transformers.env.localModelPath = path.resolve(this.localModelPath);
+        transformers.env.allowRemoteModels = !this.localFilesOnly;
+        pipelineFactory = transformers.pipeline;
+      }
+      const extractor = await pipelineFactory('feature-extraction', this.modelId, {
+        dtype: 'fp32',
+        local_files_only: this.localFilesOnly,
+      });
+      this.extractor = extractor;
+      return extractor;
+    })();
+    try {
+      return await this.loading;
+    } catch (error) {
+      const hint = this.localFilesOnly
+        ? `Local model files were not found. Set KB_EMBEDDING_LOCAL_PATH to a directory containing ${this.modelId}.`
+        : `Could not load ${this.modelId} from ${this.remoteHost}. Check the network, or set KB_EMBEDDING_REMOTE_HOST / KB_EMBEDDING_LOCAL_PATH.`;
+      throw new Error(`${hint} ${error.message}`, { cause: error });
+    } finally {
+      this.loading = null;
+    }
+  }
+
+  async embed(text, options = {}) {
+    const normalized = String(text || '').trim();
+    if (!normalized) throw new Error('text is required for embedding');
+    const extractor = await this.load();
+    const input = options.kind === 'query' ? `${QUERY_PREFIX}${normalized}` : normalized;
+    const output = await extractor(input, { pooling: 'cls', normalize: true });
+    const vector = Array.from(output.data || output.tolist?.()[0] || [], Number);
+    if (vector.length !== EMBEDDING_DIMENSIONS) {
+      throw new Error(`embedding model returned ${vector.length} dimensions; expected ${EMBEDDING_DIMENSIONS}`);
+    }
+    return vector;
+  }
+
+  embedQuery(text) {
+    return this.embed(text, { kind: 'query' });
+  }
+
+  embedPassage(text) {
+    return this.embed(text, { kind: 'passage' });
+  }
+
+  status() {
+    return {
+      modelId: this.modelId,
+      dimensions: EMBEDDING_DIMENSIONS,
+      cacheDir: this.cacheDir,
+      remoteHost: this.remoteHost,
+      localModelPath: this.localModelPath || null,
+      loaded: !!this.extractor,
+      localFilesOnly: this.localFilesOnly,
+    };
+  }
+}
+
+module.exports = { LocalEmbeddingService, DEFAULT_MODEL_ID, QUERY_PREFIX };

package/_site/lib/engine-connection.js

@@ -1,93 +1,93 @@
-const { DomainError } = require('./contracts');
-const { execGit } = require('./git-runner');
-
-function connectEngine(runtime) {
-  if (runtime.analysisOwner === 'legacy') return Promise.resolve();
-  if (runtime.engineConnecting) { runtime.engineReconnectRequested = true; return runtime.engineConnecting; }
-  const job = connectEngineOnce(runtime).finally(() => {
-    runtime.engineConnecting = null;
-    if (runtime.engineReconnectRequested && !runtime.engineConnectionClosed) { runtime.engineReconnectRequested = false; void connectEngine(runtime); }
-  });
-  runtime.engineConnecting = job;
-  return job;
-}
-async function connectEngineOnce(runtime) {
-  let step = 'engine-health';
-  let projectId = '';
-  let httpStatus = 0;
-  try {
-    const bridge = runtime.moduleBridge;
-    if (bridge.engineCompatible === undefined) bridge.engineCompatible = false;
-    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${bridge.runtimeToken}` };
-    const health = await bridge._fetch(`${bridge.engineUrl}/api/health`);
-    httpStatus = health.status;
-    if (!health.ok) throw new Error('ENGINE_UNAVAILABLE');
-    const engine = await health.json();
-    if (engine.name !== 'knowledge-engine' || engine.dataSchemaVersion !== 3) throw new Error('ENGINE_VERSION_MISMATCH');
-    step = 'runtime-authentication';
-    const auth = await bridge._fetch(`${bridge.engineUrl}/api/runtime-auth`, { headers });
-    httpStatus = auth.status;
-    if (!auth.ok) throw new Error('RUNTIME_AUTH_REQUIRED');
-    bridge.engineCompatible = true;
-    if (engine.executionEnabled === false) { bridge.resetRuntimeConfiguration?.(); runtime.projectConnections?.clear(); }
-    step = 'project-wiring';
-    const remote = bridge._listEngineProjects ? await bridge._listEngineProjects() : [];
-    runtime.projectConnections ||= new Map();
-    const enabled = [], pending = [];
-    let cursor = 0;
-    const ids = runtime.registryStore.listIds();
-    const wire = async () => { while (cursor < ids.length) {
-      const id = ids[cursor++];
-      if (!runtime.registryStore.readDisplaySnapshot(id)) continue;
-      let config;
-      try { config = runtime.projectStore.readConfig(id); }
-      catch { pending.push({ projectId: id, code: 'PROJECT_CONFIG_UNAVAILABLE' }); continue; }
-      const fingerprint = JSON.stringify(config);
-      if (runtime.projectConnections.get(id) === fingerprint && remote.some(p => p.projectId === id && p.repoPath === config.repoPath && p.knowledgePath === config.knowledgePath)) { enabled.push(id); continue; }
-      try {
-      const modules = await bridge.registerProjectLinks({ projectId: id, name: config.displayName, workspacePath: config.repoPath, knowledgePath: config.knowledgePath });
-      if (!modules.engine.ok || !modules.eventBridge.ok) { pending.push({ projectId: id, code: 'PROJECT_WIRING_PENDING' }); continue; }
-      // Engine activation can proceed while the terminal starts, but caching
-      // that partial wiring would prevent subsequent readiness passes repairing it.
-      if (modules.terminal?.ok !== false) runtime.projectConnections.set(id, fingerprint);
-      enabled.push(id);
-      } catch { pending.push({ projectId: id, code: 'PROJECT_WIRING_PENDING' }); }
-    } };
-    await Promise.all([wire(), wire()]);
-    projectId = '';
-    step = 'runtime-configuration';
-    await bridge.syncEngineConfiguration();
-    step = 'engine-activation';
-    const activated = await bridge._fetch(`${bridge.engineUrl}/api/control`, { method: 'POST', headers, body: JSON.stringify({ enabled: true, projectIds: enabled }) });
-    httpStatus = activated.status;
-    if (!activated.ok) throw new Error(activated.status === 403 ? 'RUNTIME_AUTH_REQUIRED' : 'ENGINE_ACTIVATION_FAILED');
-    runtime.ownership = { owner: 'engine', ready: true, ...(pending.length ? { pendingProjects: pending, message: '部分项目接线待恢复，其他已连接项目可正常维护。' } : {}) };
-  } catch (error) {
-    const codes = ['ENGINE_UNAVAILABLE', 'ENGINE_VERSION_MISMATCH', 'PROJECT_WIRING_PENDING', 'RUNTIME_AUTH_REQUIRED', 'ENGINE_ACTIVATION_FAILED'];
-    const code = codes.includes(error.message) ? error.message : 'ENGINE_CONNECTION_FAILED';
-    if (['ENGINE_VERSION_MISMATCH', 'RUNTIME_AUTH_REQUIRED'].includes(code)) runtime.moduleBridge.engineCompatible = false;
-    const messages = {
-      ENGINE_VERSION_MISMATCH: '检测到旧版知识引擎，请停止旧版服务后重新启动新版。',
-      RUNTIME_AUTH_REQUIRED: '引擎服务与外壳鉴权不一致，请停止旧版服务后重新启动新版。',
-      PROJECT_WIRING_PENDING: '项目接线未完成，请检查模块连接。',
-    };
-    const message = messages[code] || '知识引擎连接未完成，服务恢复后自动重试。';
-    const previous = runtime.ownership?.error;
-    runtime.ownership = { owner: 'engine', ready: false, message, error: { code, step, httpStatus, ...(projectId ? { projectId } : {}) } };
-    if (previous?.code !== code || previous?.step !== step || (previous?.projectId || '') !== projectId) await runtime.logger.warn('engine.connection_pending', message, { component: 'engine-connection', phase: step, projectId, context: { code, httpStatus } });
-  }
-}
-
-async function forwardCommitToBridge(runtime, event) {
-  const config = runtime.projectStore.readConfig(event.projectId);
-  if (!runtime.layout.pathsEqual(config.repoPath, event.repoRoot) || !/^[a-f0-9]{40}$/i.test(event.head || '')) throw new DomainError('INVALID_ARGUMENT', '提交通知与项目绑定不匹配。');
-  const exists = await execGit(config.repoPath, ['cat-file', '-e', `${event.head}^{commit}`]);
-  if (!exists.ok) throw new DomainError('INVALID_ARGUMENT', '提交不属于当前仓库。');
-  const identity = await runtime.bridgeAdapter.resolveRepoIdentity(config.repoPath);
-  const result = await runtime.bridgeAdapter.appendCommitBoundary({ projectId: event.projectId, repoIdentity: identity.repoIdentity, commitSha: event.head, branch: event.branch || null, operationId: event.operationId });
-  if (result.status !== 'captured') throw new DomainError('MODULE_UNREACHABLE', '事件记录失败，请恢复事件模块后重试。', { status: 503 });
-  runtime.moduleBridge._fetch(`${runtime.moduleBridge.engineUrl}/api/bridge/notify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }).catch(() => {});
-  return { journalSequence: result.boundary?.journalSequence || result.boundary?.sequence };
-}
-
-module.exports = { connectEngine, forwardCommitToBridge };
+const { DomainError } = require('./contracts');
+const { execGit } = require('./git-runner');
+
+function connectEngine(runtime) {
+  if (runtime.analysisOwner === 'legacy') return Promise.resolve();
+  if (runtime.engineConnecting) { runtime.engineReconnectRequested = true; return runtime.engineConnecting; }
+  const job = connectEngineOnce(runtime).finally(() => {
+    runtime.engineConnecting = null;
+    if (runtime.engineReconnectRequested && !runtime.engineConnectionClosed) { runtime.engineReconnectRequested = false; void connectEngine(runtime); }
+  });
+  runtime.engineConnecting = job;
+  return job;
+}
+async function connectEngineOnce(runtime) {
+  let step = 'engine-health';
+  let projectId = '';
+  let httpStatus = 0;
+  try {
+    const bridge = runtime.moduleBridge;
+    if (bridge.engineCompatible === undefined) bridge.engineCompatible = false;
+    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${bridge.runtimeToken}` };
+    const health = await bridge._fetch(`${bridge.engineUrl}/api/health`);
+    httpStatus = health.status;
+    if (!health.ok) throw new Error('ENGINE_UNAVAILABLE');
+    const engine = await health.json();
+    if (engine.name !== 'knowledge-engine' || engine.dataSchemaVersion !== 3) throw new Error('ENGINE_VERSION_MISMATCH');
+    step = 'runtime-authentication';
+    const auth = await bridge._fetch(`${bridge.engineUrl}/api/runtime-auth`, { headers });
+    httpStatus = auth.status;
+    if (!auth.ok) throw new Error('RUNTIME_AUTH_REQUIRED');
+    bridge.engineCompatible = true;
+    if (engine.executionEnabled === false) { bridge.resetRuntimeConfiguration?.(); runtime.projectConnections?.clear(); }
+    step = 'project-wiring';
+    const remote = bridge._listEngineProjects ? await bridge._listEngineProjects() : [];
+    runtime.projectConnections ||= new Map();
+    const enabled = [], pending = [];
+    let cursor = 0;
+    const ids = runtime.registryStore.listIds();
+    const wire = async () => { while (cursor < ids.length) {
+      const id = ids[cursor++];
+      if (!runtime.registryStore.readDisplaySnapshot(id)) continue;
+      let config;
+      try { config = runtime.projectStore.readConfig(id); }
+      catch { pending.push({ projectId: id, code: 'PROJECT_CONFIG_UNAVAILABLE' }); continue; }
+      const fingerprint = JSON.stringify(config);
+      if (runtime.projectConnections.get(id) === fingerprint && remote.some(p => p.projectId === id && p.repoPath === config.repoPath && p.knowledgePath === config.knowledgePath)) { enabled.push(id); continue; }
+      try {
+      const modules = await bridge.registerProjectLinks({ projectId: id, name: config.displayName, workspacePath: config.repoPath, knowledgePath: config.knowledgePath });
+      if (!modules.engine.ok || !modules.eventBridge.ok) { pending.push({ projectId: id, code: 'PROJECT_WIRING_PENDING' }); continue; }
+      // Engine activation can proceed while the terminal starts, but caching
+      // that partial wiring would prevent subsequent readiness passes repairing it.
+      if (modules.terminal?.ok !== false) runtime.projectConnections.set(id, fingerprint);
+      enabled.push(id);
+      } catch { pending.push({ projectId: id, code: 'PROJECT_WIRING_PENDING' }); }
+    } };
+    await Promise.all([wire(), wire()]);
+    projectId = '';
+    step = 'runtime-configuration';
+    await bridge.syncEngineConfiguration();
+    step = 'engine-activation';
+    const activated = await bridge._fetch(`${bridge.engineUrl}/api/control`, { method: 'POST', headers, body: JSON.stringify({ enabled: true, projectIds: enabled }) });
+    httpStatus = activated.status;
+    if (!activated.ok) throw new Error(activated.status === 403 ? 'RUNTIME_AUTH_REQUIRED' : 'ENGINE_ACTIVATION_FAILED');
+    runtime.ownership = { owner: 'engine', ready: true, ...(pending.length ? { pendingProjects: pending, message: '部分项目接线待恢复，其他已连接项目可正常维护。' } : {}) };
+  } catch (error) {
+    const codes = ['ENGINE_UNAVAILABLE', 'ENGINE_VERSION_MISMATCH', 'PROJECT_WIRING_PENDING', 'RUNTIME_AUTH_REQUIRED', 'ENGINE_ACTIVATION_FAILED'];
+    const code = codes.includes(error.message) ? error.message : 'ENGINE_CONNECTION_FAILED';
+    if (['ENGINE_VERSION_MISMATCH', 'RUNTIME_AUTH_REQUIRED'].includes(code)) runtime.moduleBridge.engineCompatible = false;
+    const messages = {
+      ENGINE_VERSION_MISMATCH: '检测到旧版知识引擎，请停止旧版服务后重新启动新版。',
+      RUNTIME_AUTH_REQUIRED: '引擎服务与外壳鉴权不一致，请停止旧版服务后重新启动新版。',
+      PROJECT_WIRING_PENDING: '项目接线未完成，请检查模块连接。',
+    };
+    const message = messages[code] || '知识引擎连接未完成，服务恢复后自动重试。';
+    const previous = runtime.ownership?.error;
+    runtime.ownership = { owner: 'engine', ready: false, message, error: { code, step, httpStatus, ...(projectId ? { projectId } : {}) } };
+    if (previous?.code !== code || previous?.step !== step || (previous?.projectId || '') !== projectId) await runtime.logger.warn('engine.connection_pending', message, { component: 'engine-connection', phase: step, projectId, context: { code, httpStatus } });
+  }
+}
+
+async function forwardCommitToBridge(runtime, event) {
+  const config = runtime.projectStore.readConfig(event.projectId);
+  if (!runtime.layout.pathsEqual(config.repoPath, event.repoRoot) || !/^[a-f0-9]{40}$/i.test(event.head || '')) throw new DomainError('INVALID_ARGUMENT', '提交通知与项目绑定不匹配。');
+  const exists = await execGit(config.repoPath, ['cat-file', '-e', `${event.head}^{commit}`]);
+  if (!exists.ok) throw new DomainError('INVALID_ARGUMENT', '提交不属于当前仓库。');
+  const identity = await runtime.bridgeAdapter.resolveRepoIdentity(config.repoPath);
+  const result = await runtime.bridgeAdapter.appendCommitBoundary({ projectId: event.projectId, repoIdentity: identity.repoIdentity, commitSha: event.head, branch: event.branch || null, operationId: event.operationId });
+  if (result.status !== 'captured') throw new DomainError('MODULE_UNREACHABLE', '事件记录失败，请恢复事件模块后重试。', { status: 503 });
+  runtime.moduleBridge._fetch(`${runtime.moduleBridge.engineUrl}/api/bridge/notify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }).catch(() => {});
+  return { journalSequence: result.boundary?.journalSequence || result.boundary?.sequence };
+}
+
+module.exports = { connectEngine, forwardCommitToBridge };

package/_site/lib/engine-knowledge-client.js

@@ -1,72 +1,76 @@
-'use strict';
-const { DomainError } = require('./contracts');
-const endpoint = require('./runtime-endpoint');
-const control = require('./runtime-control');
-
-class EngineKnowledgeClient {
-  constructor({ layout, engineUrl, fetchImpl = fetch, timeoutMs = 20000 }) {
-    this.layout = layout;
-    this.engineUrl = engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL;
-    this.fetch = fetchImpl;
-    this.timeoutMs = timeoutMs;
-  }
-
-  async json(url, options = {}) {
-    let response;
-    try { response = await this.fetch(url, { ...options, redirect: 'error', signal: AbortSignal.timeout(this.timeoutMs) }); }
-    catch { throw new DomainError('ENGINE_UNAVAILABLE', '知识引擎连接失败或超时，请在系统状态中检查服务。', { status: 503 }); }
-    let payload;
-    try {
-      const reader = response.body.getReader();
-      const chunks = []; let size = 0;
-      try {
-        while (true) {
-          const part = await reader.read(); if (part.done) break;
-          size += part.value.byteLength;
-          if (size > 2 * 1024 * 1024) { await reader.cancel(); throw new Error('response limit'); }
-          chunks.push(Buffer.from(part.value));
-        }
-      } finally { reader.releaseLock(); }
-      payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('invalid envelope');
-    } catch { throw new DomainError('ENGINE_INVALID_RESPONSE', '知识引擎返回了无效响应。', { status: 502 }); }
-    if (!response.ok || payload.ok === false) {
-      const code = /^[A-Z][A-Z0-9_]{0,79}$/.test(payload.error?.code || '') ? payload.error.code : 'ENGINE_REQUEST_FAILED';
-      throw new DomainError(code, '知识引擎未完成读取，请检查项目接线或请求参数。', { status: response.ok ? 502 : response.status });
-    }
-    return payload;
-  }
-
-  async target(project) {
-    if (this.engineUrl) {
-      let url; try { url = new URL(this.engineUrl); } catch {}
-      if (!url || !['http:', 'https:'].includes(url.protocol) || !endpoint.isLoopbackHost(url.hostname.replace(/^\[|\]$/g, '')) || url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname)) throw new DomainError('ENGINE_URL_INVALID', '知识引擎地址必须是无凭据的本机服务地址。');
-      const health = await this.json(new URL('/api/health', url));
-      const registered = await this.json(new URL('/api/projects', url));
-      const match = registered.projects?.find(item => item.projectId === project.projectId && item.enabled !== false);
-      if (health.name !== 'knowledge-engine' || health.dataSchemaVersion !== 3 || !match || !this.layout.pathsEqual(match.repoPath, project.repoPath) || !this.layout.pathsEqual(match.knowledgePath, project.knowledgePath)) throw new DomainError('ENGINE_IDENTITY_MISMATCH', '知识引擎与当前项目目录绑定不匹配。', { status: 409 });
-      return { url, prefix: '/api' };
-    }
-    const live = endpoint.readLiveEndpoint(this.layout.getDataDir(), { removeStale: false });
-    if (!live) throw new DomainError('ENGINE_UNAVAILABLE', '知识库服务尚未运行，请先启动 project-knowledge。', { status: 503 });
-    const url = new URL(`http://${live.host.includes(':') ? `[${live.host}]` : live.host}:${live.port}`);
-    const identity = await this.json(new URL('/api/runtime/identity', url));
-    if (identity.schema !== control.SCHEMA || identity.name !== 'project-knowledge' || identity.pid !== live.pid || identity.port !== live.port || identity.startedAt !== live.startedAt || !identity.dataDir || !this.layout.pathsEqual(identity.dataDir, this.layout.getDataDir())) throw new DomainError('ENGINE_IDENTITY_MISMATCH', '知识库实例与当前数据目录不匹配，已拒绝读取。', { status: 409 });
-    return { url, prefix: '/api/engine' };
-  }
-
-  async request(action, input, project) {
-    if (!['search', 'ask', 'get', 'history'].includes(action)) throw new DomainError('INVALID_ARGUMENT', '仅支持知识读取操作。');
-    if (input.scope !== undefined && !['project', 'domain', 'brain'].includes(input.scope)) throw new DomainError('INVALID_ARGUMENT', '知识范围必须是项目、领域或智脑。');
-    const target = await this.target(project);
-    // Forward only the read contract, never profiles, credentials or context objects.
-    const body = { projectId: project.projectId };
-    for (const key of ['query', 'limit', 'entryId', 'entry', 'scope', 'spaceId']) if (input[key] !== undefined) body[key] = input[key];
-    if (body.spaceId === undefined && input.space !== undefined) body.spaceId = input.space;
-    const result = await this.json(new URL(`${target.prefix}/${action}`, target.url), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
-    const valid = action === 'get' ? Array.isArray(result.chunks) : Array.isArray(result.results);
-    if (result.ok !== true || !valid || (action === 'ask' && (typeof result.answer !== 'string' || !Array.isArray(result.citations)))) throw new DomainError('ENGINE_INVALID_RESPONSE', '知识引擎返回了无效读取结果。', { status: 502 });
-    return result;
-  }
-}
-module.exports = { EngineKnowledgeClient };
+'use strict';
+const { DomainError } = require('./contracts');
+const endpoint = require('./runtime-endpoint');
+const control = require('./runtime-control');
+
+class EngineKnowledgeClient {
+  constructor({ layout, engineUrl, fetchImpl = fetch, timeoutMs = 20000 }) {
+    this.layout = layout;
+    this.engineUrl = engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async json(url, options = {}) {
+    let response;
+    try { response = await this.fetch(url, { ...options, redirect: 'error', signal: AbortSignal.timeout(this.timeoutMs) }); }
+    catch { throw new DomainError('ENGINE_UNAVAILABLE', '知识引擎连接失败或超时，请在系统状态中检查服务。', { status: 503 }); }
+    let payload;
+    try {
+      const reader = response.body.getReader();
+      const chunks = []; let size = 0;
+      try {
+        while (true) {
+          const part = await reader.read(); if (part.done) break;
+          size += part.value.byteLength;
+          if (size > 2 * 1024 * 1024) { await reader.cancel(); throw new Error('response limit'); }
+          chunks.push(Buffer.from(part.value));
+        }
+      } finally { reader.releaseLock(); }
+      payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('invalid envelope');
+    } catch { throw new DomainError('ENGINE_INVALID_RESPONSE', '知识引擎返回了无效响应。', { status: 502 }); }
+    if (!response.ok || payload.ok === false) {
+      // The engine reports a failed read as { ok:false, error:'<CODE>' }; some
+      // proxies wrap the same code as { error:{ code:'<CODE>' } }. Both carry
+      // the same contract, so the code must survive either envelope.
+      const raw = typeof payload.error === 'string' ? payload.error : payload.error?.code;
+      const code = /^[A-Z][A-Z0-9_]{0,79}$/.test(raw || '') ? raw : 'ENGINE_REQUEST_FAILED';
+      throw new DomainError(code, '知识引擎未完成读取，请检查项目接线或请求参数。', { status: response.ok ? 502 : response.status });
+    }
+    return payload;
+  }
+
+  async target(project) {
+    if (this.engineUrl) {
+      let url; try { url = new URL(this.engineUrl); } catch {}
+      if (!url || !['http:', 'https:'].includes(url.protocol) || !endpoint.isLoopbackHost(url.hostname.replace(/^\[|\]$/g, '')) || url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname)) throw new DomainError('ENGINE_URL_INVALID', '知识引擎地址必须是无凭据的本机服务地址。');
+      const health = await this.json(new URL('/api/health', url));
+      const registered = await this.json(new URL('/api/projects', url));
+      const match = registered.projects?.find(item => item.projectId === project.projectId && item.enabled !== false);
+      if (health.name !== 'knowledge-engine' || health.dataSchemaVersion !== 3 || !match || !this.layout.pathsEqual(match.repoPath, project.repoPath) || !this.layout.pathsEqual(match.knowledgePath, project.knowledgePath)) throw new DomainError('ENGINE_IDENTITY_MISMATCH', '知识引擎与当前项目目录绑定不匹配。', { status: 409 });
+      return { url, prefix: '/api' };
+    }
+    const live = endpoint.readLiveEndpoint(this.layout.getDataDir(), { removeStale: false });
+    if (!live) throw new DomainError('ENGINE_UNAVAILABLE', '知识库服务尚未运行，请先启动 project-knowledge。', { status: 503 });
+    const url = new URL(`http://${live.host.includes(':') ? `[${live.host}]` : live.host}:${live.port}`);
+    const identity = await this.json(new URL('/api/runtime/identity', url));
+    if (identity.schema !== control.SCHEMA || identity.name !== 'project-knowledge' || identity.pid !== live.pid || identity.port !== live.port || identity.startedAt !== live.startedAt || !identity.dataDir || !this.layout.pathsEqual(identity.dataDir, this.layout.getDataDir())) throw new DomainError('ENGINE_IDENTITY_MISMATCH', '知识库实例与当前数据目录不匹配，已拒绝读取。', { status: 409 });
+    return { url, prefix: '/api/engine' };
+  }
+
+  async request(action, input, project) {
+    if (!['search', 'ask', 'get', 'history'].includes(action)) throw new DomainError('INVALID_ARGUMENT', '仅支持知识读取操作。');
+    if (input.scope !== undefined && !['project', 'domain', 'brain'].includes(input.scope)) throw new DomainError('INVALID_ARGUMENT', '知识范围必须是项目、领域或智脑。');
+    const target = await this.target(project);
+    // Forward only the read contract, never profiles, credentials or context objects.
+    const body = { projectId: project.projectId };
+    for (const key of ['query', 'limit', 'entryId', 'entry', 'scope', 'spaceId']) if (input[key] !== undefined) body[key] = input[key];
+    if (body.spaceId === undefined && input.space !== undefined) body.spaceId = input.space;
+    const result = await this.json(new URL(`${target.prefix}/${action}`, target.url), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+    const valid = action === 'get' ? Array.isArray(result.chunks) : Array.isArray(result.results);
+    if (result.ok !== true || !valid || (action === 'ask' && (typeof result.answer !== 'string' || !Array.isArray(result.citations)))) throw new DomainError('ENGINE_INVALID_RESPONSE', '知识引擎返回了无效读取结果。', { status: 502 });
+    return result;
+  }
+}
+module.exports = { EngineKnowledgeClient };