@sanqianx/project-knowledge 5.0.9-rc.2 → 5.0.9-rc.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "project-knowledge",
-      "version": "5.0.9-rc.2",
+      "version": "5.0.9-rc.4",
       "source": "./plugins/project-knowledge",
       "description": "Search durable project decisions and implementation history through MCP."
     }

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [5.0.9-rc.4] - 2026-10-11
+
+- Pin Workbench 0.13.2-rc.2: resolve the installed ZCode provider resource
+  layout without rewriting desktop or personal configuration, and label
+  runtime failures with the correct agent.
+- Disable the project selector until the first registry snapshot. This fixes
+  the startup interaction race exposed by the Node 22 packaged UI regression.
+- Latest is unchanged; real installed acceptance and client authentication are
+  independent gates, not implied by a successful version probe.
+
+## [5.0.9-rc.3] - 2026-10-11
+
+- Route engine-wired CLI and MCP reads through the same authoritative engine
+  as the web UI, preserving commit references and project/domain/brain scopes.
+  Verify the selected runtime identity and reject unavailable, mismatched or
+  malformed services instead of silently querying a different local index.
+- Preserve the MCP `space` alias and expose explicit scope selection. Bound
+  responses and never forward profile or credential objects to read routes.
+- Drain isolated regression servers before Windows fixture cleanup. Candidate
+  publication still does not promote latest or claim complete acceptance.
+
 ## [5.0.9-rc.2] - 2026-10-11
 
 - Pin the verified Workbench 0.13.2-rc.1 and vector-hub 1.0.8-rc.1 candidates.

package/README.md

@@ -160,6 +160,15 @@ Queries never create or rewrite configuration. If the internal index is
 unavailable, search falls back to current Markdown. Project, domain and brain
 scopes are nested; unconfirmed memory candidates are not task preferences.
 
+For engine-wired projects, the CLI and MCP delegate `search`, `ask`, `get` and
+`history` to the same engine used by the web UI, including commit provenance.
+They verify the running instance against the selected data directory; an
+unavailable or mismatched instance is an explicit failure, not a second local
+index with different facts. Only projects without engine wiring retain the
+local legacy read contract. Use `--scope domain` or `--scope brain` to broaden
+CLI searches; MCP accepts the equivalent `scope`. Shared-file reads accept
+`--space <spaceId>` (MCP: `space` or `spaceId`).
+
 ## Storage
 
 Version 5 is a fresh start, not a data upgrade. Stop the previous process,

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/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/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/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,
     },

package/module-runtime-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema": "project-knowledge/module-content/v1",
   "productFiles": {
-    "ui/index.html": "db9cc5624132d336ee6b31ba37c93572b89e382f68e4b6331b4b886be8253bb5",
+    "ui/index.html": "0cb319212230af66f3530bb1b57915894f41789f1ea1c57bb8ae54b0f01164a8",
     "ui/product.js": "50d26a9aa3a95889804f8ca771dada9e1ea89d6956851e58dadf119a75842b9c",
     "ui/product.css": "3f89daeb52c5f1ed8a79150c9a84200187474a013fd97c6d7c8799d850e5b0b7",
     "ui/favicon.svg": "c48be946b224112ebb0238b44263f7a61bda31e531afa895c2e9801c0ff24f32"
@@ -10,10 +10,10 @@
     "terminal": {
       "name": "@sanqianx/claude-ai-workbench",
       "installName": "claude-ai-workbench",
-      "version": "0.13.2-rc.1",
+      "version": "0.13.2-rc.2",
       "files": {
         "LICENSE": "c1b9df1275e769f3dbab000d1e457a2d4b0f28eb5da6c77e48dc37eeba202ed7",
-        "README.md": "7efdf88b6eabdd3280fe69b6b78fce4ad9c1b5373ed5fc59e2a3db39d3f774d0",
+        "README.md": "f2e3bf656a5fc82588881691fc570fceb1e0ab6b47c6124ed26a538915887543",
         "apps/agent-terminal/app.css": "39cc65ac65bcb390f4aa21d9b783182ca229557f6bec15090f69598120161917",
         "apps/agent-terminal/app.js": "2fedcc79f9515ebae89d1c7dc996d732aa1d0946038eaaa045438121bf27f551",
         "apps/agent-terminal/index.html": "6a52ba210696c8aed99e2786e21d2771340070d51583199dd74c8da41edf0257",
@@ -27,20 +27,20 @@
         "apps/minimal-test-host/README.md": "fa73136f4ee3865c2d91eb97b2e8c03679aa4688e44c1e1c8ec6e27d604b0de5",
         "docs/sdk/FILE_LAYOUT.md": "17882f96505c8161bfb66876684b9d2d3f50021a111b8b844502d3cb4e97870a",
         "docs/sdk/INTEGRATION.md": "d4c0c80d2d2fc610205102d703a429bfaa20f9f3a48f1718f5bab02ee90138df",
-        "docs/sdk/openapi.yaml": "c14dd8a1989a6fbb748285d8b488f553e5673d52ff2439c124c435f65a57b570",
+        "docs/sdk/openapi.yaml": "1961c83c7992a02ecf942d9eb9dd3632af34daac2fefc059943acc130b7ca45a",
         "docs/sdk/README.md": "7ab591d39c36a3b84cfdf487ff567040ec453975f3ef0fba86dc822094667b61",
-        "package.json": "21b1d94149a71e9678e4a50c3146d292c2672f206ef621ae919850b67660804b",
+        "package.json": "c1109d568b15616b7e38014463265459beddab822a5f3bfa2ff9edb25c5a1b53",
         "packages/client/index.d.ts": "fb66b7b21ac936cddcb7f74543cf4f3bb7e80c169534ec249ab8ef2356224162",
         "packages/client/index.js": "92fe5ddd32289d729f336f669e47bd9601e562f5a4309ee4fa7f7f15b567edc2",
-        "packages/client/package.json": "5b5ea236e6a0769fd71b32759e0d87a33b84f4211ad298fe60452e5e8cb8bc3d",
+        "packages/client/package.json": "02af5ac530c8d5974d3425961acb98312c005f6e9729603392ea53109b3a57cc",
         "packages/client/README.md": "342dff9b1dcbc85fccc9b980ed3e4e455aa71133af1d0805b8431ea2ac564ef8",
         "packages/contracts/index.d.ts": "edc717067bfb864c6c95df0c408a799fbf90b7552519131e6dc35af3f9eb9006",
         "packages/contracts/index.js": "565b4a88190dbb8994cd0a9309b30b00f64305d65505fff9fa360d7ce69dfb58",
-        "packages/contracts/package.json": "95887ef01fa0e1ccc4f8e22089bfabe8252566e38cbfb8aef0882cfe8fe22e61",
+        "packages/contracts/package.json": "7a84f54780c27c9c862b4c0f1071be7d9b8af86cbbcb0fa6358dcb8e4c504b88",
         "packages/contracts/README.md": "44d83a3cc508cec6c5c20dfa1f2c08d5ea03e3afb2853639fdc0a9cc8eb5b9c8",
         "packages/core/index.d.ts": "c95b24a13f8aeeb128497833cf298790563baca6036ea5d29a9d8daff53199d7",
         "packages/core/index.js": "5579ceb1a63d3f962f5656c75f82cf60cd834fd270b4aa95e581bf38e4432448",
-        "packages/core/package.json": "d21084880b3d52e371d208c071ec94a3df456ea483055acc4a65b1aa7ec2fb9a",
+        "packages/core/package.json": "c699e3ab0453dd528d6a1a85a95b15c61957da4674bd8eb79ec6c4c3babf99de",
         "packages/core/README.md": "e222c546104a168f1038d95c6c4efb8e5603edd6145ab2cab79cab977fb710e5",
         "packages/server/bin/agent-terminal-server.js": "b01297ab245a2b994bf42043b7469bd6e71d8f76a4bb99d4ed651e71844c152f",
         "packages/server/bin/claude-workbench-server.js": "a8c46ed7e71afcc10e00a104ed6f2d0ac05346a743b33c3a5bd11b1314d80f40",
@@ -59,7 +59,7 @@
         "packages/server/lib/drivers/cli-json-runner.js": "c3febcea2df92b72125d053a4ffe6349e61caa98491acb6123ae964b6b90de8a",
         "packages/server/lib/drivers/codex-driver.js": "cb6f60048af534d836c7e95c494fbd16aa28ba24c5e94d76edb2eb9720f4cb54",
         "packages/server/lib/drivers/opencode-driver.js": "119b11663d926a3f5f7c63c960264784879459b3f84e6fdf482b4346697a6376",
-        "packages/server/lib/drivers/zcode-driver.js": "507dcd56e17066703f2467a96bb3c9efca6b7b1810a78d607ac576508e8d4615",
+        "packages/server/lib/drivers/zcode-driver.js": "6204a174de7a3735c86a902350c17edbd596bd22eb15c69f4de44fe2b77b51a9",
         "packages/server/lib/event-stream.js": "b0f20bac19933a1a428c22938ae2666a1231b74a4330619b885171662133f48b",
         "packages/server/lib/folder-picker.js": "70f55df999262b90433f2b4251aa69dd70a23b55a84756b5f1d24dbeacfbda31",
         "packages/server/lib/http-handler.js": "c0b1cc19c66beef0f0d9b8db48ede6b110bff59d410b81673bab2e81c05b01d7",
@@ -71,8 +71,8 @@
         "packages/server/lib/session-archive-store.js": "d3335b832a6e9fb9792991056f6596a997a4959efa6e62b60fb60133fb724196",
         "packages/server/lib/system-doctor.js": "2b0e858d69d8fb268eaed950c9883473ee9850684b532bc2db8e14674a974919",
         "packages/server/lib/ui-preferences-store.js": "e108cb22e7cc1f3438704913d5401e01de2c0e717eb2abd3bdc4727209393819",
-        "packages/server/lib/workbench-service.js": "b5caac09665b21a118a0cd826adfa3f3006e68989182e4d80bf3a4554b951250",
-        "packages/server/package.json": "77ded7b6683df90e731a0f0204ea56698a19f2a138959bee18355ba987eb04c2",
+        "packages/server/lib/workbench-service.js": "c1d1148b9b55b2701b6513f7cf1e2724569a8055e1431a05642ed620d8de7cfd",
+        "packages/server/package.json": "9e07de268280ea80f7490bec6b6afd1756a570b0f35a4edf8930b8742e9a36cc",
         "packages/server/README.md": "a34cfaa4f4e859008b44e2be8e1aafb56e97fe83e6129c968a8562945fa843f3",
         "packages/ui/ai-profile-settings.d.ts": "0551b6c6eda6d18ea89a976daddf01b2161195f4874fe2d67a57cd9ecc6ce643",
         "packages/ui/ai-profile-settings.js": "e92bbac67a1199d473e4e44b32d1cc76c5b6c79306d4fef9d9067a1bb6ec42ca",
@@ -80,7 +80,7 @@
         "packages/ui/claude-terminal.js": "96bd217a4a7e4792ae3fbaaf46249ecee13b0f4e01fc6d25a1b8b22d8f8fe00c",
         "packages/ui/index.d.ts": "e547ab39640fe7519fb367b78442dc8a2c51b2efd17b66f8b0a003b154b36ead",
         "packages/ui/index.js": "f4394aabd395938f5c3fe587e430471d4033e83945a9b9c7e0149ad4040982c9",
-        "packages/ui/package.json": "47418b48345efd2099b5b0861eed4a04db8cfe613efc95cec4aa181c373af72c",
+        "packages/ui/package.json": "f8840a1425921e6c2698a5480467e4e484bc5ba1fdfed5c32d5e75c40796b973",
         "packages/ui/README.md": "793c4a9c286fee23f39062a1976ca3afe9d2816dcdb55e156ba940e1ef514f89",
         "packages/ui/theme.css": "8f03a081272a7db11b196f7a70d0fafb1f8d954778f329f1ba53d110d9d5fd98",
         "src/assets/claude-prompts.json": "cb111f2e0a45afe8a31c251a504d1ab5375966ed61291660e61fd2efd77f6d9f",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.9-rc.2",
+  "version": "5.0.9-rc.4",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {
@@ -84,7 +84,7 @@
     "@sanqianx/vector-hub": "1.0.8-rc.1",
     "buffer": "^6.0.3",
     "cheerio": "^1.2.0",
-    "claude-ai-workbench": "npm:@sanqianx/claude-ai-workbench@0.13.2-rc.1",
+    "claude-ai-workbench": "npm:@sanqianx/claude-ai-workbench@0.13.2-rc.2",
     "cross-spawn": "7.0.6",
     "dotenv": "^17.4.2",
     "gpt-tokenizer": "^3.4.0",

package/plugins/project-knowledge/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "project-knowledge",
-  "version": "5.0.9-rc.2",
+  "version": "5.0.9-rc.4",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "project-knowledge",
-  "version": "5.0.9-rc.2",
+  "version": "5.0.9-rc.4",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.mcp.json

@@ -6,7 +6,7 @@
       "args": [
         "-y",
         "--package",
-        "@sanqianx/project-knowledge@5.0.9-rc.2",
+        "@sanqianx/project-knowledge@5.0.9-rc.4",
         "project-knowledge-mcp"
       ]
     }

package/ui/index.html

@@ -20,7 +20,7 @@
     <button id="openSystem" class="system-button"><span class="dot" id="systemDot"></span><span><b id="systemTitle">正在检查系统</b><small id="systemDetail">本机知识服务</small></span><svg viewBox="0 0 24 24"><path d="m9 6 6 6-6 6"/></svg></button>
   </aside>
   <main>
-    <header class="topbar"><div><small id="breadcrumb">我的智脑</small><h1 id="pageTitle">智脑首页</h1></div><div class="spacer"></div><select id="projectSelect" aria-label="当前项目"><option value="">尚未导入项目</option></select><button id="themeToggle" class="icon-button" title="切换浅色或深色主题" aria-label="切换主题"><svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="4"/><path d="M12 2v3M12 19v3M2 12h3M19 12h3"/></svg></button></header>
+    <header class="topbar"><div><small id="breadcrumb">我的智脑</small><h1 id="pageTitle">智脑首页</h1></div><div class="spacer"></div><select id="projectSelect" aria-label="当前项目" disabled><option value="">尚未导入项目</option></select><button id="themeToggle" class="icon-button" title="切换浅色或深色主题" aria-label="切换主题"><svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="4"/><path d="M12 2v3M12 19v3M2 12h3M19 12h3"/></svg></button></header>
     <div class="content">
       <section class="view" id="view-home"><div class="welcome"><div><small>工作概览</small><h2 id="homeTitle">我的智脑</h2><p>保存项目事实，连接相关经验。你的长期偏好，只在确认后使用。</p></div><div class="actions"><button class="primary" data-go="work">开始工作</button><button data-action="import">导入项目</button></div></div><div id="homeContent"></div></section>
       <section class="view module-view" id="view-work"><div id="workEmpty" class="empty" hidden>导入项目后，就可以在这里开始工作。<button data-action="import">导入项目</button></div><div class="work-layout" id="workLayout"><div class="frame-container"><iframe id="workFrame" title="Agent 工作台" referrerpolicy="same-origin"></iframe></div><aside class="knowledge-context"><header><h2>本次知识引用</h2><small id="contextScope">任务发送前自动检索</small></header><div id="contextContent" class="empty small-empty">发送任务后显示实际检索到的项目事实、领域经验和已确认记忆。</div></aside></div></section>