@sanqianx/project-knowledge 5.0.9-rc.9 → 5.0.10-rc.1

package/_modules/knowledge-engine/src/runtime/markdown-knowledge-indexer.js

@@ -5,13 +5,17 @@ const { sha256 } = require('./content-hash');
 const CHUNKER_VERSION = 1;
 const DEFAULT_MAX_CHARS = 1200;
 const DEFAULT_OVERLAP_CHARS = 120;
-const EXCLUDED_DIRS = new Set(['.git', '_ai', '_backup', 'node_modules']);
+const EXCLUDED_DIRS = new Set(['.git', '_ai', '_backup', 'node_modules', 'dev-conversations']);
 const DERIVED_INDEX_FILENAME = '00-index.md';
 
 function normalizeRel(value) {
   return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
 }
 
+function isExcludedKnowledgePath(value) {
+  return normalizeRel(value).split('/').some(segment => segment.startsWith('.') || EXCLUDED_DIRS.has(segment.toLowerCase()));
+}
+
 function stripFrontmatter(markdown) {
   return String(markdown || '').replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/, '');
 }
@@ -112,7 +116,7 @@ function listMarkdownFiles(root, options = {}) {
   const files = [];
   const walk = (dir) => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name.toLowerCase())) continue;
       const abs = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(abs);
       else if (entry.isFile() && /\.md$/i.test(entry.name) && (includeDerived || !isDerivedIndex(entry.name))) files.push(abs);
@@ -224,6 +228,7 @@ module.exports = {
   CHUNKER_VERSION,
   chunkMarkdown,
   listMarkdownFiles,
+  isExcludedKnowledgePath,
   isDerivedIndex,
   inferEntryType,
   parseKnowledgeMetadata,

package/_modules/knowledge-engine/src/server.js

@@ -136,7 +136,7 @@ async function api(method, pathname, search, body, store, coordinator, ctx) {
   if (method === 'GET' && pathname === '/api/events') return { events: store.listEvents(search.get('limit')).filter(e => !search.get('projectId') || e.projectId === search.get('projectId')) };
   if (method === 'POST' && pathname === '/api/events' && ctx.debug) return { event: store.addEvent(body) };
   if (method === 'POST' && pathname === '/api/bridge/notify') { if (coordinator.consume) coordinator.drain(); return { accepted: true }; }
-  if (method === 'GET' && pathname === '/api/snapshot') return { projects: store.listProjects(), runs: store.listRuns(search.get('projectId')), events: store.listEvents(50), memories: store.state.memories, sharedScopes: store.state.sharedScopes };
+  if (method === 'GET' && pathname === '/api/snapshot') return { projects: store.listProjects(), runs: store.listRuns(search.get('projectId')), events: store.listEvents(50), memories: coordinator.memories.list(), sharedScopes: store.state.sharedScopes };
   throw httpError(404, 'NOT_FOUND', '接口不存在。');
 }
 

package/_modules/knowledge-engine/src/store.js

@@ -5,6 +5,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { validateProjectId } = require('./runtime/contracts');
 const { RuntimeLayout } = require('./runtime/layout');
+const AtomicFile = require('./runtime/atomic-file');
 
 /**
  * 单文件 JSON 状态层（<data>/engine-state.json）：注册项目、分析运行、事件流。
@@ -39,6 +40,11 @@ class EngineStore {
       for (const [journalId, sequence] of Object.entries(raw.journalCursors || {})) if (!/^(global|sha256:[a-f0-9]{64})$/.test(journalId) || !Number.isSafeInteger(sequence) || sequence < 0) throw new Error('Invalid journal cursor');
       for (const scope of raw.sharedScopes || []) if (!scope || !['brain', 'domain'].includes(scope.kind) || !path.isAbsolute(scope.knowledgePath || '')) throw new Error('Invalid shared scope');
       for (const memory of raw.memories || []) if (!memory || !['candidate', 'confirmed', 'ignored'].includes(memory.status) || typeof memory.text !== 'string' || !memory.evidence?.projectId || !/^[a-f0-9]{40}$/.test(memory.evidence.commitSha || '')) throw new Error('Invalid memory record');
+      for (const memory of raw.memories || []) if (memory.scopeType !== undefined || memory.scopeId !== undefined) {
+        if (!['global', 'domain', 'project'].includes(memory.scopeType)) throw new Error('Invalid memory scope');
+        validateProjectId(memory.scopeId);
+        if (memory.scopeType === 'global' && memory.scopeId !== (memory.brainId || 'brain-default')) throw new Error('Invalid global memory target');
+      }
       this.state = { ...this.state, ...raw };
     } catch (error) {
       if (error.code === 'SCHEMA_UNSUPPORTED') throw error;
@@ -56,12 +62,9 @@ class EngineStore {
   }
 
   save() {
-    fs.mkdirSync(this.dataDir, { recursive: true });
-    const tmp = this.file + '.tmp';
-    const fd = fs.openSync(tmp, 'w', 0o600);
-    try { fs.writeFileSync(fd, JSON.stringify(this.state, null, 2), 'utf8'); fs.fsyncSync(fd); }
-    finally { fs.closeSync(fd); }
-    fs.renameSync(tmp, this.file);
+    // Windows scanners/readers may briefly hold the destination; never unlink
+    // durable state to force a replace, or share a fixed temp name with writers.
+    AtomicFile.writeJsonAtomic(this.file, this.state);
   }
 
   listProjects() {

package/_site/_test/bin-cli-test.js

@@ -78,12 +78,25 @@ function isPortListening(port) {
 async function waitForListening(port, deadlineMs = 8000) {
   const deadline = Date.now() + deadlineMs;
   while (Date.now() < deadline) {
-    if (await isPortListening(port)) return true;
+    if (await canConnect(port)) return true;
     await new Promise(resolve => setTimeout(resolve, 150));
   }
   return false;
 }
 
+function canConnect(port) {
+  // A bind probe can steal the selected port exactly as the child starts.
+  // Readiness checks must connect, never compete with the server's listener.
+  return new Promise(resolve => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    let settled = false;
+    const finish = result => { if (settled) return; settled = true; socket.destroy(); resolve(result); };
+    socket.setTimeout(500, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
 (async () => {
   // Make sure no leftover PID file or server from a previous run.
   removePidFile();
@@ -185,7 +198,7 @@ async function waitForListening(port, deadlineMs = 8000) {
   while (Date.now() < deadline && !detectedPort) {
     const rec = readPidFile();
     if (rec && rec.port && rec.port !== busyPort) {
-      if (await isPortListening(rec.port)) {
+      if (await canConnect(rec.port)) {
         detectedPort = rec.port;
         break;
       }

package/_site/_test/mcp-server-test.js

@@ -113,7 +113,7 @@ async function createMcpClient() {
     let response = await client.request('tools/call', { name: 'project_knowledge_resolve', arguments: { repoPath: repo } });
     assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
     assert.strictEqual(response.result.structuredContent.knowledgePath, markdownKb);
-    assert.strictEqual(response.result.structuredContent.indexPath, layout.getIndexPath());
+    assert.strictEqual(response.result.structuredContent.indexPath, layout.getVectorRootPath(settingsStore.read()));
 
     response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { projectId: 'project-demo', query: 'refresh tokens' } });
     assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');

package/_site/_test/module-agent-start-proxy-test.js

@@ -0,0 +1,65 @@
+'use strict';
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { Readable } = require('node:stream');
+const { EventEmitter } = require('node:events');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+async function budget(method, pathname) {
+  const timers = [], originalTimer = global.setTimeout, originalFetch = global.fetch;
+  const req = Readable.from([]); req.method = method; req.headers = {};
+  const res = new EventEmitter();
+  res.writeHead = () => {}; res.end = () => { res.writableEnded = true; };
+  try {
+    global.setTimeout = (fn, ms, ...args) => { timers.push(ms); return originalTimer(fn, ms, ...args); };
+    global.fetch = async () => new Response('{}', { headers: { 'Content-Type': 'application/json' } });
+    await new ModuleBridge().proxy(req, res, 'http://127.0.0.1:5760' + pathname);
+    return timers[0];
+  } finally { global.setTimeout = originalTimer; global.fetch = originalFetch; }
+}
+
+(async () => {
+  const upstream = http.createServer((req, res) => {
+    const timer = setTimeout(() => { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end('{"accepted":true}'); }, 11000);
+    res.on('close', () => clearTimeout(timer));
+  });
+  await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
+  const bridge = new ModuleBridge();
+  const target = `http://127.0.0.1:${upstream.address().port}/api/claude-workbench/v1/sessions/cold-client/input`;
+  const shell = http.createServer((req, res) => bridge.proxy(req, res, target));
+  await new Promise(resolve => shell.listen(0, '127.0.0.1', resolve));
+  try {
+    const response = await fetch(`http://127.0.0.1:${shell.address().port}/send`, { method: 'POST', body: '{}' });
+    assert.equal(response.status, 200, 'cold native client startup must not be reported as unreachable after ten seconds');
+    assert.equal((await response.json()).accepted, true);
+  } finally {
+    for (const server of [shell, upstream]) { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }
+  }
+  assert.equal(await budget('POST', '/api/claude-workbench/v1/sessions'), 90000);
+  assert.equal(await budget('POST', '/api/claude-workbench/v1/sessions/cold-client/input?scope=project'), 90000);
+  for (const [method, route] of [
+    ['GET', '/api/claude-workbench/v1/sessions'],
+    ['POST', '/api/claude-workbench/v1/sessions/cold-client/abort'],
+    ['POST', '/api/claude-workbench/v1/sessions/cold-client/permission'],
+    ['POST', '/api/engine/runs'],
+    ['POST', '/api/sessions/cold-client/input'],
+  ]) assert.equal(await budget(method, route), 10000, 'unrelated APIs must keep their ordinary timeout');
+  assert.equal(await budget('POST', '/api/claude-workbench/v1/system/pick-folder'), 600000);
+  const originalFetch = global.fetch;
+  let warning, failure;
+  const request = Readable.from([]); request.method = 'GET'; request.headers = {};
+  const response = new EventEmitter(); response.writeHead = () => {};
+  response.end = bytes => { response.writableEnded = true; failure = JSON.parse(bytes); };
+  try {
+    global.fetch = async () => { throw new Error('upstream leaked credential: secret-proxy-fixture'); };
+    const safeBridge = new ModuleBridge({ logger: { warn(...args) { warning = args; } } });
+    await safeBridge.proxy(request, response, 'http://127.0.0.1:5760/api/health?apiKey=secret-proxy-fixture');
+    assert.equal(failure.error, 'MODULE_UNREACHABLE');
+    assert.equal(failure.details.failureKind, 'NETWORK_ERROR');
+    assert.equal(failure.details.timeoutMs, 10000);
+    assert.equal(warning[0], 'module.proxy.failed');
+    assert.equal(warning[2].context.path, '/api/health');
+    assert.ok(!JSON.stringify([failure, warning]).includes('secret-proxy-fixture'), 'diagnostics omit queries, raw errors and credentials');
+  } finally { global.fetch = originalFetch; }
+  console.log('module-agent-start-proxy-test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/module-bridge-eventbridge-test.js

@@ -108,7 +108,7 @@ async function main() {
       vectorHubUrl: DEAD_URL,
       eventBridgeUrl: stubUrl,
       engineUrl: DEAD_URL,
-      registryStore: { listIds: () => ['demo-proj'] },
+      registryStore: { listIds: () => ['demo-proj'], readDisplaySnapshot: id => id === 'demo-proj' ? { displayName: 'demo' } : null },
       projectStore: makeStoreStub(),
     });
 

package/_site/_test/module-wiring-unbind-race-test.js

@@ -0,0 +1,59 @@
+'use strict';
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+async function main() {
+  let releaseRegister, registerStarted, registered = true;
+  const started = new Promise(resolve => { registerStarted = resolve; });
+  const gate = new Promise(resolve => { releaseRegister = resolve; });
+  const engineProjects = new Set();
+  const calls = [];
+  const server = http.createServer(async (req, res) => {
+    req.resume();
+    if (req.method === 'POST' && req.url === '/engine/api/projects') {
+      registerStarted(); await gate;
+      engineProjects.add('project-race'); calls.push('register');
+    }
+    if (req.method === 'DELETE' && req.url === '/engine/api/projects/project-race') { engineProjects.delete('project-race'); calls.push('remove'); }
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({ ok: true, projects: [], id: 'terminal-race', project: { id: 'event-race' }, sequence: 0 }));
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const state = { modules: {} };
+  const bridge = new ModuleBridge({ terminalUrl: base + '/terminal', vectorHubUrl: base + '/vector', eventBridgeUrl: base + '/event', engineUrl: base + '/engine', registryStore: { readDisplaySnapshot: () => registered ? { displayName: 'Race' } : null }, projectStore: { readState: () => state, readConfig: () => ({}), updateState: async (_id, apply) => { apply(state); } } });
+  try {
+    const input = { projectId: 'project-race', name: 'Race', workspacePath: process.cwd(), knowledgePath: process.cwd() };
+    const wiring = bridge.registerProjectLinks(input);
+    await started;
+    const removing = bridge.removeProjectLinks({ projectId: 'project-race', onRemoved: async () => { registered = false; } }).then(() => { registered = false; });
+    // A delayed supervisor registration must settle before removal, never after.
+    await new Promise(resolve => setTimeout(resolve, 100)); releaseRegister();
+    await Promise.all([wiring, removing]);
+    assert.deepEqual([...engineProjects], [], 'delayed wiring must not resurrect a removed engine project');
+    assert.deepEqual(calls, ['register', 'remove']);
+    const before = calls.length;
+    const stale = await bridge.registerProjectLinks(input);
+    assert.equal(calls.length, before, 'a stale registry snapshot cannot register an absent project');
+    assert.equal(stale.engine.status, 'removed');
+    assert.equal(bridge.projectWiringQueue?.size || 0, 0, 'settled operations must not leak per-project queues');
+    let releaseOther;
+    const otherGate = new Promise(resolve => { releaseOther = resolve; });
+    const order = [];
+    const held = bridge._withProjectWiring('project-a', async () => { await otherGate; order.push('a'); });
+    const independent = bridge._withProjectWiring('project-b', async () => { order.push('b'); });
+    await independent; assert.deepEqual(order, ['b'], 'unrelated projects do not share a global wiring lock');
+    releaseOther(); await held; assert.deepEqual(order, ['b', 'a']);
+    // Failed deletion keeps its registry, then a retry can still repair/remove it.
+    registered = true;
+    await assert.rejects(bridge.removeProjectLinks({ projectId: 'project-race', onRemoved: async () => { throw new Error('controlled hook conflict'); } }), /controlled hook conflict/);
+    assert.equal(registered, true);
+    await bridge.registerProjectLinks(input);
+    assert.ok(engineProjects.has('project-race'));
+    await bridge.removeProjectLinks({ projectId: 'project-race', onRemoved: async () => { registered = false; } });
+    assert.deepEqual([...engineProjects], []);
+    console.log('module-wiring-unbind-race-test PASS');
+  } finally { releaseRegister(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/path-consistency-test.js

@@ -98,7 +98,7 @@ async function waitForServer() {
     const resolved = runtime.resolveProject({ repoPath: movedRepo });
     assert.strictEqual(resolved.projectId, 'project-stable');
     assert.strictEqual(resolved.knowledgePath, oldKnowledge);
-    assert.strictEqual(resolved.indexPath, layout.getIndexPath());
+    assert.strictEqual(resolved.indexPath, layout.getVectorRootPath(settingsStore.read()));
     const mcpResolved = await callTool(runtime, 'project_knowledge_resolve', { projectId: 'project-stable' });
     assert.strictEqual(mcpResolved.knowledgePath, resolved.knowledgePath);
     assert.strictEqual(mcpResolved.indexPath, resolved.indexPath);

package/_site/_test/product-diagnostics-ui-test.js

@@ -83,7 +83,11 @@ async function main() {
     if (browser) console.error(await browser.evaluate("JSON.stringify({ toast:document.getElementById('toast').textContent, project:document.getElementById('projectSelect').value, detail:document.getElementById('projectDetail').textContent })"));
     throw error;
   } finally {
-    await browser?.close(); await server.cleanup(); offline.closeAllConnections(); await new Promise(resolve => offline.close(resolve)); fixture.cleanup();
+    try { await browser?.close(); }
+    finally {
+      try { await server.cleanup(); }
+      finally { offline.closeAllConnections(); await new Promise(resolve => offline.close(resolve)); fixture.cleanup(); }
+    }
   }
 }
 main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });

package/_site/_test/product-progress-status-test.js

@@ -0,0 +1,70 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawnServer } = require('./helpers/spawn-server');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+
+const ROOT = path.resolve(__dirname, '../..');
+async function main() {
+  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-product-progress-'));
+  const snapshot = { projects: [], runs: [], events: [], memories: [], sharedScopes: [] };
+  let connections = 0, snapshots = 0, healthRequests = 0;
+  const streams = new Set();
+  const upstream = http.createServer((req, res) => {
+    if (req.url === '/api/progress') {
+      connections++; streams.add(res); res.on('close', () => streams.delete(res));
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
+      res.write(`event: snapshot\ndata: ${JSON.stringify(snapshot)}\n\n`);
+      return;
+    }
+    req.resume();
+    if (req.url === '/api/snapshot') snapshots++;
+    if (req.url.includes('/health')) healthRequests++;
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(req.url === '/api/snapshot' ? snapshot : req.url === '/api/projects' ? { projects: [] } : { ok: true, name: 'knowledge-engine', dataSchemaVersion: 3 }));
+  });
+  await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
+  const moduleUrl = `http://127.0.0.1:${upstream.address().port}`;
+  const port = 8400 + process.pid % 200;
+  const base = `http://127.0.0.1:${port}`;
+  const server = spawnServer({ root: ROOT, port, dataDir: path.join(fixture, 'data'), analysisOwner: 'engine', tag: 'product-progress', extraEnv: {
+    KB_TERMINAL_URL: moduleUrl, KB_VECTORHUB_URL: moduleUrl,
+    KB_EVENTBRIDGE_URL: moduleUrl, KB_KNOWLEDGE_ENGINE_URL: moduleUrl,
+  } });
+  let browser;
+  try {
+    await waitFor(async () => { try { return (await fetch(base + '/api/health')).ok; } catch { return false; } }, 'isolated product', 20000);
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(fixture, 'browser'), url: base, width: 1920, height: 1080 });
+    await browser.setViewport(1920, 1080);
+    const run = expression => browser.evaluate(expression);
+    const status = () => run("document.getElementById('activityConnection').textContent");
+    await waitFor(async () => await status() === '已连接实时更新', 'initial SSE snapshot');
+    assert.equal(connections, 1);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const beforeHealth = healthRequests, beforeSnapshot = snapshots;
+      await run("window.dispatchEvent(new Event('online'))");
+      await waitFor(() => healthRequests > beforeHealth && snapshots > beforeSnapshot, 'online registry and snapshot refresh');
+      assert.equal(await status(), '已连接实时更新', 'a duplicate online event must not leave a healthy stream labelled as recovering');
+      assert.equal(connections, 1, 'a redundant online receipt cannot create another progress subscription');
+    }
+    await browser.send('Network.enable');
+    await browser.send('Network.emulateNetworkConditions', { offline: true, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
+    await waitFor(async () => (await status()).includes('连接中断'), 'genuine offline feedback');
+    await waitFor(() => streams.size === 0, 'offline closes the upstream stream');
+    await browser.send('Network.emulateNetworkConditions', { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
+    await waitFor(async () => await status() === '已连接实时更新' && connections === 2, 'new snapshot and stream after real reconnection');
+    assert.equal(streams.size, 1);
+    assert.equal(browser.exceptions.length, 0);
+    console.log('product-progress-status-test PASS (real product/browser/proxy/SSE; duplicate online stays connected; real offline reconnects once)');
+  } finally {
+    await browser?.close(); await server.cleanup();
+    upstream.closeAllConnections(); await new Promise(resolve => upstream.close(resolve));
+    assert.equal(path.dirname(fixture), path.resolve(os.tmpdir())); assert.ok(path.basename(fixture).startsWith('pk-product-progress-'));
+    fs.rmSync(fixture, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });

package/_site/_test/shared-scope-root-binding-test.js

@@ -0,0 +1,67 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { createEngineServer } = require('../../_modules/knowledge-engine/src/server');
+const { SettingsStore } = require('../lib/settings-store');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-shared-bindings-'));
+  const oldRoot = path.join(root, '原知识根目录'), newRoot = path.join(root, '新知识根目录');
+  const settings = new SettingsStore({ dataDir: path.join(root, 'shell') });
+  await settings.initialize({ knowledge: { rootPath: oldRoot } });
+  await settings.addDomain({ id: 'domain-tools', name: '开发工具' });
+  let engine;
+  async function start() {
+    engine = createEngineServer({ dataDir: path.join(root, 'engine'), consume: false, runtimeToken: 'scope-binding-test' });
+    await engine.ready;
+    await new Promise(resolve => engine.server.listen(0, '127.0.0.1', resolve));
+    return `http://127.0.0.1:${engine.server.address().port}`;
+  }
+  const logs = [];
+  const bridge = new ModuleBridge({ settingsStore: settings, runtimeToken: 'scope-binding-test', logger: { warn: (...args) => logs.push(args) } });
+  const upstream = bridge._fetch.bind(bridge);
+  bridge._fetch = (url, init) => url.startsWith(bridge.engineUrl) ? upstream(url, init) : Promise.resolve({ ok: false });
+  try {
+    bridge.engineUrl = await start();
+    assert.equal((await bridge.syncEngineConfiguration()).scopes, true);
+    const scopes = structuredClone(engine.store.state.sharedScopes);
+    const brain = scopes.find(scope => scope.kind === 'brain');
+    const domain = scopes.find(scope => scope.kind === 'domain');
+    engine.store.addProject({ projectId: 'project-test', repoPath: path.join(root, 'code'), knowledgePath: path.join(root, 'project-knowledge'), domainId: domain.id });
+    engine.store.state.memories.push({ id: 'memory-test', brainId: brain.id, status: 'candidate', text: '保持目录绑定稳定', evidence: { projectId: 'project-test', commitSha: 'a'.repeat(40), entryId: 'README.md' } });
+    engine.store.save();
+    await engine.coordinator.memories.update('memory-test', { status: 'confirmed' });
+    fs.writeFileSync(path.join(domain.knowledgePath, 'README.md'), '# 领域经验\n\n领域知识不能随根目录设置隐式移动。\n');
+    const memoryFile = engine.coordinator.memories.file(brain);
+    const before = fs.readFileSync(memoryFile);
+    await settings.updatePatch({ knowledge: { rootPath: newRoot } });
+    assert.equal((await bridge.syncEngineConfiguration()).scopes, true, 'changing index root must not invalidate shared memory wiring');
+    assert.deepEqual(engine.store.state.sharedScopes.map(scope => scope.knowledgePath), scopes.map(scope => scope.knowledgePath));
+    assert.deepEqual(fs.readFileSync(memoryFile), before);
+    assert.equal(settings.read().brain.knowledgePath, brain.knowledgePath);
+    assert.equal(settings.read().brain.domains[0].knowledgePath, domain.knowledgePath);
+    await assert.rejects(settings.updatePatch({ brain: { knowledgePath: newRoot } }), { code: 'INVALID_ARGUMENT' });
+    await assert.rejects(settings.bindSharedKnowledgePaths([{ ...brain, knowledgePath: newRoot }]), { code: 'IMMUTABLE_FIELD' });
+    await settings.addDomain({ id: 'domain-new', name: '新领域' });
+    assert.equal((await bridge.syncEngineConfiguration()).scopes, true);
+    assert.equal(engine.store.state.sharedScopes.find(scope => scope.id === 'domain-new').knowledgePath, path.join(newRoot, '_shared', 'domain-new'));
+    await engine.close();
+    bridge.engineUrl = await start();
+    assert.equal((await bridge.syncEngineConfiguration()).scopes, true);
+    assert.deepEqual(fs.readFileSync(memoryFile), before);
+    const memory = await engine.coordinator.retrieval.get({ projectId: 'project-test', spaceId: 'brain:brain-default', entryId: 'memories/confirmed.md' });
+    assert.ok(memory.chunks.some(chunk => chunk.chunk_text.includes('保持目录绑定稳定')));
+    const shared = await engine.coordinator.retrieval.get({ projectId: 'project-test', spaceId: 'domain:domain-tools', entryId: 'README.md' });
+    assert.ok(shared.chunks.some(chunk => chunk.chunk_text.includes('不能随根目录设置隐式移动')));
+    await engine.close(); engine = null;
+    const pending = await bridge.syncEngineConfiguration();
+    assert.equal(pending.scopes, false);
+    assert.equal(pending.scopeStatus.status, 'pending');
+    assert.ok(logs.some(entry => entry[0] === 'modules.scopes.pending'));
+    assert.equal(settings.read().brain.knowledgePath, brain.knowledgePath);
+    console.log('shared-scope-root-binding-test PASS');
+  } finally { if (engine) await engine.close(); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/test-server-cleanup-test.js

@@ -5,6 +5,7 @@ const path = require('node:path');
 const { spawnServer } = require('./helpers/spawn-server');
 const freePort = require('./helpers/free-port');
 const { readEndpoint } = require('../lib/runtime-endpoint');
+const { spawn } = require('node:child_process');
 
 (async () => {
   const port = await freePort();
@@ -19,7 +20,10 @@ const { readEndpoint } = require('../lib/runtime-endpoint');
     assert.equal(readEndpoint(spawned.dataDir)?.pid, spawned.child.pid);
     let output = '';
     spawned.child.stderr.on('data', bytes => { output += bytes; });
-    await spawned.cleanup(); stopped = true;
+    const locker = process.platform === 'win32' ? spawn(process.execPath, ['-e', 'process.stdout.write("holding-cwd\\n");setTimeout(()=>process.exit(0),2500)'], { cwd: spawned.dataDir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] }) : null;
+    if (locker) await new Promise((resolve, reject) => { locker.once('error', reject); locker.stdout.once('data', resolve); });
+    try { await spawned.cleanup(); stopped = true; }
+    finally { if (locker?.exitCode === null) { locker.kill(); await new Promise(resolve => locker.once('close', resolve)); } }
     assert.notEqual(spawned.child.exitCode, null, output);
     assert.equal(spawned.child.signalCode, null, 'normal cleanup must drain the server instead of force killing it');
     assert.equal(spawned.child.exitCode, 0, output);

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

@@ -3,11 +3,27 @@ const assert = require('node:assert/strict');
 const path = require('node:path');
 const { StorageLayout } = require('../lib/storage-layout');
 const { ModuleBridge } = require('../lib/module-bridge');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
 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: [] } }) };
+let knowledgeRoot = root;
+const tools = new KnowledgeToolRuntime({
+  layout,
+  settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot } }) },
+  registryStore: { listIds: () => ['project-storage'] },
+  projectStore: {
+    readConfig: () => ({ displayName: 'Storage', repoPath: path.join(root, 'repo'), knowledgePath: path.join(root, 'project') }),
+    readState: () => ({ index: { generation: 3 } }),
+  },
+});
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(root, '.indexes'), 'MCP/CLI resolution must report the vector-hub location, not the retired shell database');
+knowledgeRoot = path.join(root, 'changed root');
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(knowledgeRoot, '.indexes'), 'a running MCP process must reread the selected knowledge root');
+knowledgeRoot = '';
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(layout.getDataDir(), 'vectorhub'));
 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'));

package/_site/lib/engine-connection.js

@@ -24,7 +24,10 @@ async function connectEngine(runtime) {
     step = 'project-wiring';
     for (const id of runtime.registryStore.listIds()) {
       projectId = id;
-      const config = runtime.projectStore.readConfig(id);
+      if (!runtime.registryStore.readDisplaySnapshot(id)) continue;
+      let config;
+      try { config = runtime.projectStore.readConfig(id); }
+      catch (error) { if (!runtime.registryStore.readDisplaySnapshot(id)) continue; throw error; }
       const modules = await bridge.registerProjectLinks({ projectId: id, name: config.displayName, workspacePath: config.repoPath, knowledgePath: config.knowledgePath });
       if (!modules.engine.ok || !modules.eventBridge.ok) throw new Error('PROJECT_WIRING_PENDING');
     }

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

@@ -163,7 +163,7 @@ class KnowledgeToolRuntime {
       repoPath: path.resolve(resolvedRepoPath || config.repoPath),
       knowledgePath: path.resolve(config.knowledgePath),
       kbPath: path.resolve(config.knowledgePath),
-      indexPath: this.layout.getIndexPath(),
+      indexPath: this.layout.getVectorRootPath(this.settingsStore.read({ allowMissing: true })),
       primarySpaceId: `project:${projectId}`,
       relatedProjectIds: Array.isArray(config.relatedProjectIds) ? [...config.relatedProjectIds] : [],
       index: { ...state.index },