@sanqianx/project-knowledge 5.0.9-rc.1 → 5.0.9-rc.10

package/_site/_test/vector-storage-root-test.js

@@ -0,0 +1,52 @@
+'use strict';
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ModuleBridge } = require('../lib/module-bridge');
+const root = path.resolve('D:/knowledge storage 中文');
+const layout = new StorageLayout({ dataDir: path.resolve('D:/metadata') });
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: root } }), path.join(root, '.indexes'));
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: '' } }), path.join(layout.getDataDir(), 'vectorhub'));
+const settingsStore = { read: () => ({ knowledge: { rootPath: root }, brain: { id: 'brain-default', domains: [] } }) };
+const bridge = new ModuleBridge({ settingsStore, dataDir: layout.getDataDir() });
+const spec = bridge._supervisedSpecs().find(spec => spec.name === 'vector-hub');
+assert.equal(spec.env.VECTOR_HUB_ROOT, path.join(root, '.indexes'));
+assert.equal(spec.env.VECTOR_HUB_CONFIG, path.join(layout.getDataDir(), 'vectorhub', 'config.json'));
+const calls = [];
+bridge._fetch = async (url, init) => { const body = JSON.parse(init.body); calls.push({ url, body }); return { ok: true, json: async () => url.includes('/api/internal/runtime-config') ? { ok: true, rootPath: path.join(root, '.indexes') } : {} }; };
+bridge.syncEngineConfiguration().then(async status => {
+  assert.equal(calls.find(call => call.url.includes('/api/internal/runtime-config')).body.storageRoot, path.join(root, '.indexes'));
+  assert.equal(status.indexStorage.status, 'ready');
+  let currentRoot = root, release, started;
+  const entered = new Promise(resolve => { started = resolve; });
+  const held = new Promise(resolve => { release = resolve; });
+  const queued = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => ({ knowledge: { rootPath: currentRoot }, brain: { id: 'brain-default', domains: [] } }) } });
+  const applied = [];
+  queued._fetch = async (url, init) => {
+    const body = JSON.parse(init.body);
+    if (url.endsWith('/api/internal/runtime-config')) {
+      applied.push(body.storageRoot);
+      if (applied.length === 1) { started(); await held; }
+      return { ok: true, json: async () => ({ rootPath: body.storageRoot }) };
+    }
+    return { ok: true, json: async () => null };
+  };
+  const first = queued.syncEngineConfiguration(); await entered;
+  currentRoot = path.join(root, 'new root');
+  const second = queued.syncEngineConfiguration(); release();
+  await first;
+  const latest = await second;
+  assert.deepEqual(applied, [path.join(root, '.indexes'), path.join(currentRoot, '.indexes')]);
+  assert.equal(latest.indexStorage.actualPath, path.join(currentRoot, '.indexes'));
+  assert.equal(latest.indexStorage.status, 'ready');
+  const broken = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => { throw new Error('corrupt settings'); } } });
+  let revoked;
+  broken._fetch = async (url, init) => {
+    if (url.endsWith('/api/internal/runtime-config')) revoked = JSON.parse(init.body);
+    return { ok: false };
+  };
+  const unavailable = await broken.syncEngineConfiguration();
+  assert.deepEqual(revoked, { settings: null });
+  assert.equal(unavailable.indexStorage.status, 'pending');
+  console.log('vector-storage-root-test PASS');
+}).catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/workspace-ui-contract-test.js

@@ -11,6 +11,7 @@ for (const view of ['home', 'work', 'search', 'memory', 'projects', 'activity'])
   assert.ok(html.includes(`id="view-${view}"`));
 }
 assert.equal((html.match(/data-view=/g) || []).length, 6, 'diagnostics must not become another primary product');
+assert.match(html, /<select\b[^>]*id="projectSelect"[^>]*\bdisabled\b/, 'project selection is disabled until the initial registry snapshot has loaded');
 for (const id of ['workFrame', 'vectorFrame', 'bridgeFrame', 'engineFrame', 'importDialog', 'importCode', 'importKnowledge', 'importDomain', 'setupImportRoot', 'createDomain', 'logsDialog', 'systemDrawer', 'copyReference']) assert.equal((html.match(new RegExp(`id="${id}"`, 'g')) || []).length, 1);
 assert.ok(html.includes('data-action="import"') && html.includes('不分析全部历史'));
 assert.ok(!html.includes('srcdoc') && !/data-simulate|data-analyze|data-install-hook/.test(html));

package/_site/lib/contracts.js

@@ -71,6 +71,11 @@ const ERROR_CODES = Object.freeze([
   'KNOWLEDGE_WRITE_MOVED',
   'MODEL_CONFIG_MOVED',
   'MODULE_UNREACHABLE',
+  'ENGINE_UNAVAILABLE',
+  'ENGINE_IDENTITY_MISMATCH',
+  'ENGINE_INVALID_RESPONSE',
+  'ENGINE_REQUEST_FAILED',
+  'ENGINE_URL_INVALID',
 ]);
 
 const IMMUTABLE_PROJECT_FIELDS = Object.freeze([

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

@@ -0,0 +1,72 @@
+'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 };

package/_site/lib/knowledge-tool-runtime.js

@@ -12,6 +12,7 @@ const { EMBEDDING_DIMENSIONS } = require('./knowledge-schema');
 const { DomainError } = require('./contracts');
 const { KnowledgeRetrievalService } = require('./knowledge-retrieval-service');
 const { ConversationStore } = require('./conversation-store');
+const { EngineKnowledgeClient } = require('./engine-knowledge-client');
 
 function gitRoot(candidate) {
   const resolved = path.resolve(candidate || process.cwd());
@@ -97,6 +98,7 @@ class KnowledgeToolRuntime {
     this.settingsStore = options.settingsStore || new SettingsStore({ layout: this.layout });
     this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
     this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.engineClient = options.engineClient || new EngineKnowledgeClient({ layout: this.layout, engineUrl: options.engineUrl, fetchImpl: options.fetchImpl });
     this.database = null;
     this.embedder = null;
     this.conversationStore = options.conversationStore || new ConversationStore({
@@ -279,10 +281,13 @@ class KnowledgeToolRuntime {
 
   async search(input = {}) {
     const project = this.resolveProject(input);
+    if (this.projectStore.readState(project.projectId).modules?.engine) return this.engineClient.request('search', input, project);
     return this.retrievalService.search({ ...input, project });
   }
 
   async ask(input = {}) {
+    const project = this.resolveProject(input);
+    if (this.projectStore.readState(project.projectId).modules?.engine) return this.engineClient.request('ask', input, project);
     const searched = await this.search(input);
     const citations = searched.results.slice(0, 5).map((result, index) => ({
       index: index + 1,
@@ -300,6 +305,7 @@ class KnowledgeToolRuntime {
 
   async get(input = {}) {
     const project = this.resolveProject(input);
+    if (this.projectStore.readState(project.projectId).modules?.engine) return this.engineClient.request('get', input, project);
     const entryId = String(input.entryId || input.entry || '').trim().replace(/\\/g, '/');
     if (!entryId) throw new DomainError('INVALID_ARGUMENT', 'entry is required.');
     const target = path.resolve(project.knowledgePath, ...entryId.split('/'));
@@ -321,6 +327,7 @@ class KnowledgeToolRuntime {
 
   async history(input = {}) {
     const project = this.resolveProject(input);
+    if (this.projectStore.readState(project.projectId).modules?.engine) return this.engineClient.request('history', input, project);
     const changesRoot = path.join(project.knowledgePath, 'changes');
     const results = markdownFiles(project.knowledgePath).filter(file => this.layout.isPathInside(changesRoot, file, { realpath: true })).map(file => {
       const text = fs.readFileSync(file, 'utf8');

package/_site/lib/module-bridge.js

@@ -24,6 +24,7 @@
 
 const { spawn, spawnSync } = require('child_process');
 const path = require('path');
+const { StorageLayout } = require('./storage-layout');
 const fs = require('fs');
 const crypto = require('crypto');
 const { once } = require('events');
@@ -310,10 +311,19 @@ class ModuleBridge {
     } };
   }
 
-  async syncEngineConfiguration() {
-    if (this.syncingConfig) return this.configStatus || { scopes: false, model: false };
-    this.syncingConfig = true;
-    const status = { scopes: false, model: false, embedding: false };
+  syncEngineConfiguration() {
+    if (this.configSyncPromise) return this.configSyncPromise.catch(() => undefined).then(() => this.syncEngineConfiguration());
+    const pending = this._syncEngineConfiguration().finally(() => { if (this.configSyncPromise === pending) this.configSyncPromise = null; });
+    this.configSyncPromise = pending;
+    return pending;
+  }
+
+  async _syncEngineConfiguration() {
+    const dataDir = this.dataDir || require('./data-dir').getDataDir();
+    let indexPath = null;
+    try { indexPath = new StorageLayout({ dataDir }).getVectorRootPath(this.settingsStore?.read()); }
+    catch { /* Corrupt settings must not switch storage or prevent credential revocation. */ }
+    const status = { scopes: false, scopeStatus: { status: 'pending' }, model: false, embedding: false, indexStorage: { expectedPath: indexPath, actualPath: null, status: 'pending' } };
     const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${this.runtimeToken}` };
     try {
       if (this.settingsStore) {
@@ -321,11 +331,28 @@ class ModuleBridge {
         if (settings.knowledge.rootPath) {
           const brain = settings.brain;
           const root = path.join(settings.knowledge.rootPath, '_shared');
-          const scopes = [{ id: brain.id, kind: 'brain', brainId: brain.id, name: brain.name, knowledgePath: path.join(root, brain.id) }, ...brain.domains.map(d => ({ id: d.id, kind: 'domain', brainId: brain.id, domainId: d.id, name: d.name, knowledgePath: path.join(root, d.id) }))];
-          status.scopes = (await this._fetch(`${this.engineUrl}/api/scopes`, { method: 'POST', headers, body: JSON.stringify({ scopes }) })).ok;
+          const response = await this._fetch(`${this.engineUrl}/api/snapshot`);
+          if (!response.ok) throw new DomainError('ENGINE_UNAVAILABLE', '共享知识接线暂时不可用。');
+          const prior = (await response.json()).sharedScopes || [];
+          // Root settings govern new directories and derived indexes, never move
+          // existing knowledge. Retain engine-acknowledged bindings in the spine.
+          const binding = (item, kind) => {
+            const existing = prior.find(scope => scope.id === item.id && scope.kind === kind && scope.brainId === brain.id);
+            if (existing && !path.isAbsolute(existing.knowledgePath || '')) throw new DomainError('DATA_CORRUPT', '共享目录绑定损坏。');
+            return item.knowledgePath || existing?.knowledgePath || path.join(root, item.id);
+          };
+          const scopes = [{ id: brain.id, kind: 'brain', brainId: brain.id, name: brain.name, knowledgePath: binding(brain, 'brain') }, ...brain.domains.map(d => ({ id: d.id, kind: 'domain', brainId: brain.id, domainId: d.id, name: d.name, knowledgePath: binding(d, 'domain') }))];
+          const applied = await this._fetch(`${this.engineUrl}/api/scopes`, { method: 'POST', headers, body: JSON.stringify({ scopes }) });
+          if (!applied.ok) throw new DomainError('SHARED_SCOPE_APPLY_FAILED', '共享目录接线未完成。');
+          await this.settingsStore.bindSharedKnowledgePaths?.(scopes);
+          status.scopes = true; status.scopeStatus = { status: 'ready' };
         }
       }
-    } catch { /* A scope failure must not prevent revoking a stale model key. */ }
+    } catch (error) {
+      status.scopeStatus = { status: 'pending', code: ['DATA_CORRUPT', 'IMMUTABLE_FIELD', 'ENGINE_UNAVAILABLE', 'SHARED_SCOPE_APPLY_FAILED'].includes(error.code) ? error.code : 'ENGINE_UNAVAILABLE' };
+      this.logger.warn('modules.scopes.pending', 'Shared knowledge wiring is pending; existing data is retained.', { context: { code: status.scopeStatus.code } });
+      // A scope failure must not prevent revoking a stale model key.
+    }
     try {
       let profile = null;
       try {
@@ -341,10 +368,15 @@ class ModuleBridge {
         const resolved = await this._fetch(`${this.terminalUrl}/api/claude-workbench/v1/internal/embedding-config`, { method: 'POST', headers, body: '{}' });
         if (resolved.ok) settings = await resolved.json();
       } catch { /* Revocation wins over a previously cached runtime key. */ }
-      const applied = await this._fetch(`${this.vectorHubUrl}/api/internal/runtime-config`, { method: 'POST', headers, body: JSON.stringify({ settings }) });
+      const applied = await this._fetch(`${this.vectorHubUrl}/api/internal/runtime-config`, { method: 'POST', headers, body: JSON.stringify({ settings, ...(indexPath ? { storageRoot: indexPath } : {}) }) });
       status.embedding = applied.ok && !!settings;
+      if (applied.ok) {
+        const result = await applied.json();
+        status.indexStorage.actualPath = result.rootPath || null;
+        status.indexStorage.status = result.rootPath && path.resolve(result.rootPath) === indexPath ? 'ready' : 'pending';
+      }
     } catch { /* Public status contains no resolved configuration. */ }
-    this.syncingConfig = false; this.configStatus = status;
+    this.configStatus = status;
     return status;
   }
 
@@ -559,12 +591,13 @@ class ModuleBridge {
         this.logger.warn('modules.supervisor', '@sanqianx/vector-hub runtime not installed; expecting an external service.', {});
       } else {
         const dataDir = this.dataDir || require('./data-dir').getDataDir();
-        const root = path.join(dataDir, 'vectorhub');
+        const configRoot = path.join(dataDir, 'vectorhub');
+        const root = new StorageLayout({ dataDir }).getVectorRootPath(this.settingsStore?.read());
         specs.push({
           name: 'vector-hub',
           command: `node ${JSON.stringify(vectorHubEntry)} serve --host ${urlHost(this.vectorHubUrl)} --port ${urlPort(this.vectorHubUrl, 8787)} --root ${JSON.stringify(root)}`,
           url: this.vectorHubUrl,
-          env: { VECTOR_HUB_ROOT: root, VECTOR_HUB_CONFIG: path.join(root, 'config.json'), VECTOR_HUB_LEGACY_CONFIG: path.join(root, 'no-legacy-config.json'), KB_VECTOR_MANAGED: '1', KB_VECTOR_RUNTIME_TOKEN: this.runtimeToken },
+          env: { VECTOR_HUB_ROOT: root, VECTOR_HUB_CONFIG: path.join(configRoot, 'config.json'), VECTOR_HUB_LEGACY_CONFIG: path.join(configRoot, 'no-legacy-config.json'), KB_VECTOR_MANAGED: '1', KB_VECTOR_RUNTIME_TOKEN: this.runtimeToken },
         });
       }
     }

package/_site/lib/server-app.js

@@ -921,7 +921,7 @@ function createRequestHandler(runtime, options = {}) {
       }
       if (method === 'GET' && pathname === '/api/brain') {
         const settings = runtime.settingsStore.read();
-        return send(res, 200, { ok: true, brain: settings.brain, knowledgeRoot: settings.knowledge.rootPath, configuration: runtime.moduleBridge.configStatus || null });
+        return send(res, 200, { ok: true, brain: settings.brain, knowledgeRoot: settings.knowledge.rootPath, indexStoragePath: runtime.layout.getVectorRootPath(settings), configuration: runtime.moduleBridge.configStatus || null });
       }
       if (method === 'PATCH' && pathname === '/api/brain') {
         const body = await readJsonBody(req);
@@ -982,8 +982,8 @@ function createRequestHandler(runtime, options = {}) {
         if (body.logging) throw new DomainError('IMMUTABLE_FIELD', 'Logging storage and capture policy are not user settings.', { status: 409 });
         if (!Object.keys(patch).length) throw new DomainError('INVALID_ARGUMENT', 'Only the knowledge root is mutable on this route.');
         const settings = await runtime.settingsStore.updatePatch(patch);
-        await runtime.moduleBridge.syncEngineConfiguration();
-        return send(res, 200, { ok: true, settings: { ...settings, ai: publicAiProfilesConfig(settings.ai) } });
+        const configuration = await runtime.moduleBridge.syncEngineConfiguration();
+        return send(res, 200, { ok: true, settings: { ...settings, ai: publicAiProfilesConfig(settings.ai) }, configuration });
       }
 
       if (method === 'GET' && pathname === '/api/projects') return send(res, 200, { ok: true, projects: listProjectViews(runtime.registryStore, runtime.projectStore) });

package/_site/lib/settings-store.js

@@ -1,6 +1,7 @@
 const { SCHEMAS, DomainError, publicAiProfilesConfig } = require('./contracts');
 const AtomicFile = require('./atomic-file');
 const { StorageLayout } = require('./storage-layout');
+const path = require('node:path');
 
 function defaultSettings() {
   return {
@@ -43,9 +44,12 @@ function validateSettings(settings) {
   }
   settings.brain = settings.brain || { id: 'brain-default', name: '我的智脑', domains: [] };
   if (settings.brain.id !== 'brain-default' || typeof settings.brain.name !== 'string' || !settings.brain.name.trim() || settings.brain.name.length > 100 || !Array.isArray(settings.brain.domains)) throw new DomainError('DATA_CORRUPT', 'Brain metadata is invalid.', { status: 500 });
+  const validBinding = value => value === undefined || typeof value === 'string' && path.isAbsolute(value);
+  if (!validBinding(settings.brain.knowledgePath)) throw new DomainError('DATA_CORRUPT', 'Brain knowledge binding is invalid.', { status: 500 });
   const ids = new Set();
   for (const domain of settings.brain.domains) {
     if (!domain || !/^domain-[a-z0-9-]+$/.test(domain.id) || ids.has(domain.id) || typeof domain.name !== 'string' || !domain.name.trim() || domain.name.length > 100) throw new DomainError('DATA_CORRUPT', 'Domain metadata is invalid.', { status: 500 });
+    if (!validBinding(domain.knowledgePath)) throw new DomainError('DATA_CORRUPT', 'Domain knowledge binding is invalid.', { status: 500 });
     ids.add(domain.id);
   }
   const logging = settings.logging || {};
@@ -92,6 +96,7 @@ class SettingsStore {
 
   async updatePatch(patch) {
     return this.atomic.withFileLock(this.lockPath, async () => {
+      if (patch?.brain && (Object.prototype.hasOwnProperty.call(patch.brain, 'knowledgePath') || patch.brain.domains?.some?.(domain => Object.prototype.hasOwnProperty.call(domain, 'knowledgePath')))) throw new DomainError('INVALID_ARGUMENT', '共享知识目录绑定只允许受控接线写入。');
       if (patch && patch.logging && typeof patch.logging === 'object') {
         const unknown = Object.keys(patch.logging).find(key => key !== 'levels');
         if (unknown) throw new DomainError('INVALID_ARGUMENT', `Logging setting is read-only or unsupported: ${unknown}.`, { details: { field: unknown } });
@@ -120,6 +125,21 @@ class SettingsStore {
     });
   }
 
+  async bindSharedKnowledgePaths(scopes) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const settings = this.read();
+      let changed = false;
+      for (const scope of scopes) {
+        const target = scope.kind === 'brain' && scope.id === settings.brain.id ? settings.brain : settings.brain.domains.find(domain => domain.id === scope.id);
+        if (!target || !path.isAbsolute(scope.knowledgePath || '')) throw new DomainError('INVALID_ARGUMENT', '共享知识绑定无效。');
+        if (target.knowledgePath && !this.layout.pathsEqual(target.knowledgePath, scope.knowledgePath)) throw new DomainError('IMMUTABLE_FIELD', '共享知识目录不能隐式移动。', { status: 409 });
+        if (!target.knowledgePath) { target.knowledgePath = path.resolve(scope.knowledgePath); changed = true; }
+      }
+      if (changed) { settings.updatedAt = new Date().toISOString(); validateSettings(settings); this.atomic.writeJsonAtomic(this.filePath, settings); }
+      return settings;
+    });
+  }
+
   readPublicView(options = {}) {
     const settings = this.read(options);
     return {

package/_site/lib/storage-layout.js

@@ -49,6 +49,10 @@ class StorageLayout {
   getRegistryLockPath() { return path.join(this.dataDir, 'runtime', 'locks', 'projects.lock'); }
 
   getIndexPath() { return path.join(this.dataDir, 'index', 'knowledge.lancedb'); }
+  getVectorRootPath(settings) {
+    const root = settings?.knowledge?.rootPath;
+    return root ? path.join(path.resolve(root), '.indexes') : path.join(this.dataDir, 'vectorhub');
+  }
   getCachePath(...segments) { return path.join(this.dataDir, 'cache', ...segments); }
   getRuntimePath(...segments) { return path.join(this.dataDir, 'runtime', ...segments); }
   getRecoveryPath(...segments) { return path.join(this.dataDir, 'recovery', ...segments); }

package/bin/project-knowledge-kb.js

@@ -25,7 +25,9 @@ Read-only local knowledge tools:
   project-knowledge-kb get     --project <projectId-or-legacy-slug> --entry <path>
   project-knowledge-kb history --project <projectId-or-legacy-slug> [--limit 20]
 
-Add --json for machine-readable output. These commands never modify knowledge or project configuration.\n`);
+Add --scope project|domain|brain for a search range, --space <id> for a cited
+shared entry, and --json for machine-readable output. These commands never
+modify knowledge or project configuration.\n`);
 }
 
 async function main(argv = process.argv.slice(2), options = {}) {
@@ -38,7 +40,7 @@ async function main(argv = process.argv.slice(2), options = {}) {
   if (!args.project) throw new Error('--project is required');
   const runtime = options.runtime || new KnowledgeToolRuntime(options);
   try {
-    const input = { project: args.project, query: args.query, limit: args.limit, entry: args.entry };
+    const input = { project: args.project, query: args.query, limit: args.limit, entry: args.entry, scope: args.scope, spaceId: args.spaceId || args.space };
     let result;
     if (args.command === 'search') result = await runtime.search(input);
     else if (args.command === 'ask') result = await runtime.ask(input);

package/bin/project-knowledge-mcp.js

@@ -11,6 +11,7 @@ const { KnowledgeToolRuntime } = require('../_site/lib/knowledge-tool-runtime');
 const { serializeErrorEnvelope, createId } = require('../_site/lib/contracts');
 
 const SERVER_NAME = 'project-knowledge';
+const SCOPE = { type: 'string', enum: ['project', 'domain', 'brain'], description: 'Knowledge range: current project (default), its domain, or its brain.' };
 const SERVER_INSTRUCTIONS = `Project Knowledge is the durable source of prior project decisions and implementation history. Knowledge content is read-only; the only write operation appends an explicit supplemental Prompt event to the shared conversation truth.
 
 At the start of work in a registered Git repository, and before answering questions about prior work or implementing a non-trivial change:
@@ -56,7 +57,7 @@ const TOOLS = [
   },
   {
     name: 'project_knowledge_search',
-    description: 'Search durable project knowledge using the current project and its explicitly related-project scope. This tool is read-only.',
+    description: 'Search the same durable knowledge and commit citations as the product UI, within the selected project, domain or brain. This tool is read-only.',
     inputSchema: {
       type: 'object',
       required: ['query'],
@@ -66,6 +67,7 @@ const TOOLS = [
         projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
         project: { type: 'string', description: 'Optional registered project slug.' },
         limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+        scope: SCOPE,
       },
       additionalProperties: false,
     },
@@ -82,6 +84,7 @@ const TOOLS = [
         projectId: { type: 'string' },
         project: { type: 'string' },
         limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+        scope: SCOPE,
       },
       additionalProperties: false,
     },
@@ -95,6 +98,8 @@ const TOOLS = [
       properties: {
         entry: { type: 'string', minLength: 1, description: 'Entry identifier returned by search.' },
         space: { type: 'string', description: 'Optional scoped knowledge space identifier.' },
+        spaceId: { type: 'string', description: 'Knowledge space identifier returned by a citation; alias of space.' },
+        scope: SCOPE,
         repoPath: { type: 'string' },
         projectId: { type: 'string' },
         project: { type: 'string' },
@@ -112,6 +117,7 @@ const TOOLS = [
         projectId: { type: 'string' },
         project: { type: 'string' },
         limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+        scope: SCOPE,
       },
       additionalProperties: false,
     },