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

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.9-rc.2",
+  "version": "5.0.9-rc.3",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {

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.3",
   "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.3",
   "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.3",
         "project-knowledge-mcp"
       ]
     }