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

package/_site/_test/conversation-store-test.js

@@ -45,6 +45,8 @@ const { ConversationStore, sha256 } = require('../lib/conversation-store');
   assert.strictEqual(store.readEvents(projectId).length, 1);
   assert.strictEqual(store.readEvents(projectId)[0].content, privatePrompt, 'full prompt belongs in the private business store');
   assert.strictEqual(store.readEvents(projectId)[0].contentHash, sha256(privatePrompt));
+  await store.appendBridgeEvent(projectId, { ...store.readEvents(projectId)[0], eventId: 'event-zcode-1', sequence: 12, source: 'zcode' });
+  assert.strictEqual(store.readEvents(projectId).find(event => event.eventId === 'event-zcode-1').source, 'zcode');
   assert(!JSON.stringify(logRecords).includes(privatePrompt), 'conversation body must never enter structured logs');
   assert(JSON.stringify(logRecords).includes(sha256(privatePrompt)), 'logs may retain body hash for correlation');
 

package/_site/_test/fixtures/make-git-repos.js

@@ -49,15 +49,7 @@ function makeRepo({ kind = 'one-commit' } = {}) {
   const commits = [];
   const cleanup = () => {
     if (path.dirname(repoPath) !== path.resolve(os.tmpdir()) || !path.basename(repoPath).startsWith(`kb-fixture-${kind}-${process.pid}-`)) throw new Error('Unsafe fixture cleanup');
-    function remove(directory) {
-      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-        const file = path.join(directory, entry.name);
-        if (entry.isDirectory() && !entry.isSymbolicLink()) remove(file);
-        else { try { fs.unlinkSync(file); } catch (error) { if (error.code !== 'EPERM') throw error; fs.chmodSync(file, 0o600); fs.unlinkSync(file); } }
-      }
-      fs.rmdirSync(directory);
-    }
-    if (fs.existsSync(repoPath)) remove(repoPath);
+    if (fs.existsSync(repoPath)) fs.rmSync(repoPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
   };
 
   if (kind === 'not-git') {

package/_site/_test/index-error-display-contract-test.js

@@ -0,0 +1,10 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const source = fs.readFileSync(path.resolve(__dirname, '../../ui/product.js'), 'utf8');
+for (const field of ['upstreamMessage', 'failureKind', 'upstreamCode', 'requestId', 'attempt', 'httpStatus', 'durationMs']) {
+  assert.ok(source.includes(`esc(r.error.details.${field}`), `index detail must be escaped: ${field}`);
+}
+assert.ok(source.includes("['failed', 'index-pending'].includes(r.state)"));
+console.log('index-error-display-contract-test PASS (real rendering/export covered by engine test:web:faults)');

package/_site/_test/knowledge-engine-client-test.js

@@ -0,0 +1,105 @@
+'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 { spawn } = require('node:child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+const endpoint = require('../lib/runtime-endpoint');
+const control = require('../lib/runtime-control');
+const { EngineKnowledgeClient } = require('../lib/engine-knowledge-client');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-engine-client-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const settings = new SettingsStore({ layout }), registry = new ProjectRegistryStore({ layout }), projects = new ProjectStore({ layout });
+  const projectId = 'project-test', repoPath = path.join(root, 'repo'), knowledgePath = path.join(root, 'knowledge');
+  fs.mkdirSync(repoPath); fs.mkdirSync(knowledgePath);
+  fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# Legacy\n\nlegacy-local-only\n');
+  await settings.initialize(); await registry.initialize();
+  await projects.create(projectId, { repoPath, knowledgePath }, { modules: { engine: { status: 'registered', projectId } } });
+  await projects.updateState(projectId, state => { state.modules = { engine: { status: 'registered', projectId } }; });
+  await registry.add(projectId, { displayNameSnapshot: 'Test' });
+  let invalidIdentity = false, malformed = false, businessError = false, oversized = false, wrongBinding = false;
+  const calls = [];
+  const reference = { scope_project_id: projectId, entry_id: 'changes/aaaaaaaaaaaa.md', commitSha: 'a'.repeat(40), chunk_text: 'Engine authoritative knowledge' };
+  const payload = { ok: true, projectId, backend: 'hybrid+markdown-truth', results: [reference], answer: reference.chunk_text, citations: [{ ...reference, entryId: reference.entry_id }], chunks: [{ chunk_text: reference.chunk_text }] };
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    if (req.url === '/api/runtime/identity') return res.end(JSON.stringify(control.identity(invalidIdentity ? root : layout.getDataDir(), { port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' })));
+    if (req.url === '/api/health') return res.end(JSON.stringify({ name: 'knowledge-engine', dataSchemaVersion: 3 }));
+    if (req.url === '/api/projects') return res.end(JSON.stringify({ projects: [{ projectId, repoPath, knowledgePath: wrongBinding ? root : knowledgePath }] }));
+    let text = ''; for await (const bytes of req) text += bytes;
+    calls.push({ route: req.url, input: JSON.parse(text || '{}') });
+    if (oversized) return res.end(JSON.stringify({ ok: true, text: 'x'.repeat(2 * 1024 * 1024) }));
+    if (businessError) { res.statusCode = 403; return res.end(JSON.stringify({ ok: false, error: { code: 'PATH_OUTSIDE_ROOT', message: 'private-test-secret' } })); }
+    res.end(malformed ? '[]' : JSON.stringify(payload));
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  endpoint.writeEndpoint(layout.getDataDir(), { pid: process.pid, port: server.address().port, host: '127.0.0.1', startedAt: 'test-start' });
+  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
+  try {
+    for (const action of ['search', 'ask', 'get', 'history']) {
+      assert.deepEqual(await runtime[action]({ project: projectId, query: 'knowledge', entry: reference.entry_id, scope: 'brain', apiKey: 'must-not-forward', password: 'must-not-forward' }), payload);
+      const call = calls.at(-1);
+      assert.equal(call.route, `/api/engine/${action}`);
+      assert.equal(call.input.projectId, projectId); assert.equal(call.input.scope, 'brain');
+      assert.ok(!JSON.stringify(call.input).includes('must-not-forward'));
+    }
+    const subprocess = (file, args) => new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [file, ...args], { env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, windowsHide: true });
+      let out = '', err = ''; child.stdout.on('data', b => { out += b; }); child.stderr.on('data', b => { err += b; });
+      child.once('error', reject); child.once('close', code => resolve({ code, out, err }));
+    });
+    const cli = await subprocess(path.resolve(__dirname, '../../bin/project-knowledge-kb.js'), ['search', '--project', projectId, '--query', 'knowledge', '--scope', 'brain', '--json']);
+    assert.equal(cli.code, 0, cli.err); assert.deepEqual(JSON.parse(cli.out), payload);
+    assert.equal(calls.at(-1).input.scope, 'brain');
+    await runtime.get({ projectId, entry: reference.entry_id, space: 'brain:test' });
+    assert.equal(calls.at(-1).input.spaceId, 'brain:test', 'legacy space alias is forwarded');
+    const { createRequire } = require('node:module');
+    const sdk = createRequire(path.resolve(__dirname, '../../package.json'));
+    const { Client } = sdk('@modelcontextprotocol/sdk/client/index.js');
+    const { StdioClientTransport } = sdk('@modelcontextprotocol/sdk/client/stdio.js');
+    const transport = new StdioClientTransport({ command: process.execPath, args: [path.resolve(__dirname, '../../bin/project-knowledge-mcp.js')], env: { ...process.env, KB_DATA_DIR: layout.getDataDir() }, stderr: 'pipe' });
+    const client = new Client({ name: 'engine-regression', version: '1.0.0' });
+    try {
+      await client.connect(transport);
+      const tools = await client.listTools();
+      assert.deepEqual(tools.tools.find(t => t.name === 'project_knowledge_search').inputSchema.properties.scope.enum, ['project', 'domain', 'brain']);
+      for (const action of ['search', 'ask', 'get', 'history']) {
+        const result = await client.callTool({ name: `project_knowledge_${action}`, arguments: { projectId, scope: 'brain', ...(action === 'get' ? { entry: reference.entry_id, space: 'brain:test' } : action === 'history' ? {} : { query: 'knowledge' }) } });
+        assert.ok(!result.isError); assert.deepEqual(JSON.parse(result.content[0].text), payload);
+        assert.equal(calls.at(-1).input.scope, 'brain');
+      }
+    } finally { await client.close(); }
+    invalidIdentity = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
+    invalidIdentity = false; malformed = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
+    malformed = false; businessError = true;
+    await assert.rejects(runtime.get({ projectId, entry: '../outside.md' }), e => e.code === 'PATH_OUTSIDE_ROOT' && !e.message.includes('private-test-secret'));
+    businessError = false; oversized = true;
+    await assert.rejects(runtime.search({ projectId, query: 'knowledge' }), e => e.code === 'ENGINE_INVALID_RESPONSE');
+    oversized = false;
+    const direct = new EngineKnowledgeClient({ layout, engineUrl: `http://127.0.0.1:${server.address().port}` });
+    assert.deepEqual(await direct.request('search', {}, runtime.resolveProject({ projectId })), payload);
+    assert.equal(calls.at(-1).route, '/api/search');
+    wrongBinding = true;
+    await assert.rejects(direct.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_IDENTITY_MISMATCH');
+    wrongBinding = false;
+    for (const engineUrl of ['http://example.com', 'http://secret@127.0.0.1', 'http://127.0.0.1/?apiKey=secret', 'file:///private']) {
+      const unsafe = new EngineKnowledgeClient({ layout, engineUrl });
+      await assert.rejects(unsafe.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_URL_INVALID' && !e.message.includes('secret'));
+    }
+    await assert.rejects(direct.request('../runtime-config', {}, {}), e => e.code === 'INVALID_ARGUMENT');
+    await assert.rejects(runtime.search({ projectId, scope: 'another-brain' }), e => e.code === 'INVALID_ARGUMENT');
+    const unavailable = new EngineKnowledgeClient({ layout, fetchImpl: async () => { throw new Error('private-test-secret'); } });
+    await assert.rejects(unavailable.request('search', {}, runtime.resolveProject({ projectId })), e => e.code === 'ENGINE_UNAVAILABLE' && !e.message.includes('private-test-secret'));
+    console.log('knowledge-engine-client-test PASS (native runtime, CLI and MCP share engine facts)');
+  } finally { await runtime.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); fs.rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/product-brand-contract-test.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ui = path.resolve(__dirname, '../../ui');
+const html = fs.readFileSync(path.join(ui, 'index.html'), 'utf8');
+const css = fs.readFileSync(path.join(ui, 'product.css'), 'utf8');
+const mark = fs.readFileSync(path.join(ui, 'favicon.svg'), 'utf8');
+const favicon = html.match(/<link\b(?=[^>]*\brel="icon")[^>]*\bhref="([^"]+)"/);
+const sidebar = html.match(/<img\b(?=[^>]*\bclass="brand-mark")[^>]*\bsrc="([^"]+)"/);
+
+assert(favicon, 'Product needs an SVG favicon.');
+assert(sidebar, 'Sidebar must use the product mark, not a second drawn icon.');
+assert.equal(sidebar[1], favicon[1], 'Favicon and sidebar must share the exact asset URL.');
+assert.equal(favicon[1].split('?')[0], '/favicon.svg');
+assert.match(favicon[1], /\?v=/, 'Brand changes need a new browser cache identity.');
+assert.match(mark, /viewBox="0 0 64 64"/);
+assert.match(mark, /fill="#516f89"/);
+assert.equal((mark.match(/<path\b/g) || []).length, 1, 'Keep one geometric silhouette.');
+assert.doesNotMatch(mark, /<(?:script|image|text|filter|linearGradient|radialGradient)\b/i);
+assert.doesNotMatch(html, /<span class="brand-mark">知<\/span>/);
+assert.match(css, /\.brand-mark\{[^}]*width:32px;[^}]*height:32px;[^}]*flex:none/);
+console.log('PASS product brand: shared SVG, cache identity, fixed-size layout, no decorative dependencies');

package/_site/_test/release-version-sync-test.js

@@ -90,8 +90,14 @@ try {
   ]);
   const scripts = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).scripts;
   assert.strictEqual(scripts.preversion, 'npm run release:verify');
-  assert.strictEqual(scripts.version, 'node _site/scripts/sync-release-version.js --stage');
+  assert.strictEqual(scripts.version, 'node _site/scripts/sync-release-version.js --stage --web-only');
   assert.strictEqual(scripts.postversion, 'npm run release:verify');
+  const desktopBytes = FILES.filter(file => file.startsWith('desktop/')).map(file => fs.readFileSync(path.join(TEMP, file)));
+  value.version = '9.8.8-rc.1'; fs.writeFileSync(rootPackage, JSON.stringify(value, null, 2) + '\n');
+  assert.strictEqual(run(['--web-only']).status, 0);
+  assert.strictEqual(run(['--check', '--web-only']).status, 0);
+  assert.notStrictEqual(run(['--check']).status, 0, 'desktop still needs explicit synchronization for desktop releases');
+  FILES.filter(file => file.startsWith('desktop/')).forEach((file, i) => assert.deepStrictEqual(fs.readFileSync(path.join(TEMP, file)), desktopBytes[i]));
   console.log('release-version-sync-test PASS');
 } finally {
   fs.rmSync(TEMP, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });

package/_site/_test/sessions-stream-test.js

@@ -5,10 +5,10 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
 
 const ROOT = path.resolve(__dirname, '..', '..');
-const PORT = 7804;
-const BASE = `http://127.0.0.1:${PORT}`;
+let PORT, BASE;
 const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-sse-v2-'));
 const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-sse-repo-'));
 
@@ -60,6 +60,7 @@ async function waitFor(predicate) {
 }
 
 (async () => {
+  PORT = await freePort(); BASE = `http://127.0.0.1:${PORT}`;
   git(['init', '--initial-branch=main']);
   git(['config', 'user.email', 'sse@example.test']);
   git(['config', 'user.name', 'SSE Test']);

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/simple-import-test.js

@@ -4,10 +4,10 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
 
 const ROOT = path.resolve(__dirname, '..', '..');
-const PORT = 7824;
-const BASE = `http://127.0.0.1:${PORT}`;
+let PORT, BASE;
 const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-v2-'));
 const repoPath = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-import-repo-'));
 const knowledgeRoot = path.join(dataDir, 'knowledge');
@@ -36,6 +36,7 @@ async function waitForServer() {
 }
 
 (async () => {
+  PORT = await freePort(); BASE = `http://127.0.0.1:${PORT}`;
   git(['init', '--initial-branch=main']);
   git(['config', 'user.email', 'import@example.test']);
   git(['config', 'user.name', 'Import Test']);

package/_site/_test/team-knowledge-store-test.js

@@ -4,11 +4,11 @@ const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
 const githubTeamStore = require('../lib/github-team-store');
 
 const ROOT = path.resolve(__dirname, '..', '..');
-const PORT = Number(process.env.KB_TEAM_KNOWLEDGE_PORT || 7837);
-const BASE_URL = `http://127.0.0.1:${PORT}`;
+let PORT, BASE_URL;
 const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `kb-team-v2-${process.pid}-`));
 const DATA_DIR = path.join(TEMP, 'data');
 const SOURCE_ONE = path.join(TEMP, 'source-one');
@@ -51,6 +51,7 @@ async function json(method, route, body) {
 }
 
 (async () => {
+  PORT = process.env.KB_TEAM_KNOWLEDGE_PORT ? Number(process.env.KB_TEAM_KNOWLEDGE_PORT) : await freePort(); BASE_URL = `http://127.0.0.1:${PORT}`;
   let spawned;
   try {
     initializeRepo(SOURCE_ONE, 'Source one');

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

@@ -0,0 +1,31 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
+const { readEndpoint } = require('../lib/runtime-endpoint');
+
+(async () => {
+  const port = await freePort();
+  const spawned = spawnServer({ root: path.resolve(__dirname, '../..'), port, tag: 'graceful-cleanup' });
+  let stopped = false;
+  try {
+    for (let attempt = 0; attempt < 100; attempt++) {
+      const endpoint = readEndpoint(spawned.dataDir);
+      if (endpoint && (await fetch(`http://127.0.0.1:${port}/api/health`).catch(() => null))?.ok) break;
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert.equal(readEndpoint(spawned.dataDir)?.pid, spawned.child.pid);
+    let output = '';
+    spawned.child.stderr.on('data', bytes => { output += bytes; });
+    await spawned.cleanup(); stopped = true;
+    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);
+    assert.ok(!fs.existsSync(spawned.dataDir));
+    assert.ok(!fs.existsSync(spawned.bridgeHome));
+    await assert.rejects(fetch(`http://127.0.0.1:${port}/api/health`));
+    console.log('test-server-cleanup-test PASS (verified graceful shutdown before fixture removal)');
+  } finally { if (!stopped) await spawned.cleanup(); }
+})().catch(error => { console.error(error); process.exitCode = 1; });

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/conversation-store.js

@@ -4,7 +4,7 @@ const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
 const AtomicFile = require('./atomic-file');
 const { StorageLayout } = require('./storage-layout');
 
-const SOURCES = new Set(['claude-code', 'codex', 'opencode']);
+const SOURCES = new Set(['claude-code', 'codex', 'opencode', 'zcode']);
 const ROLES = new Set(['user', 'assistant', null]);
 const SNAPSHOT_STATUSES = new Set(['available', 'no-new-user-prompt', 'unavailable', 'ambiguous']);
 const BINDING_KINDS = new Set(['direct', 'shared-spanning', 'explicit']);

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');