@sanqianx/project-knowledge 5.0.5 → 5.0.7

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [5.0.7] - 2026-10-10
+
+- Normalize CLI command case and reject unknown commands, extra arguments and
+  invalid ports before any service or data is created.
+- Replace the shared temporary PID and blind orphan scan with per-data-directory
+  local control channels. Stop waits for the backend and owned module shutdown;
+  stale or unrelated PIDs are never signaled.
+- Add verified local instance inventory (`status --all`), explicit targeted stop
+  (`stop --port`) and data-directory selection (`--data`). Display the actual
+  port, version and data directory; refuse unverifiable or mismatched targets.
+
+## [5.0.6] - 2026-10-10
+
+- Do not mistake unregistered, abandoned legacy chat records for a knowledge
+  database on first launch. Preserve their bytes without restoring sessions or
+  importing projects; continue rejecting actual old registries and maintenance.
+- Wait for the background server's real HTTP readiness before reporting success
+  or opening the browser. Surface startup failures in the invoking terminal with
+  a nonzero exit code, and name the exact conflicting data entries.
+- Isolate regression data from the user's default data directory. Add a detached
+  npm CLI startup regression from an unrelated working directory.
+
 ## [5.0.5] - 2026-10-10
 
 - Invalidate in-flight registry snapshots after domain creation, project import,

package/README.md

@@ -58,12 +58,24 @@ project-knowledge              # start in the background and open the UI
 project-knowledge --fg         # run in the foreground
 project-knowledge status       # show the active local backend
 project-knowledge stop         # stop the background backend
+project-knowledge status --all # list verified local instances and data directories
+project-knowledge stop --port 5804 # stop a specific verified instance
+project-knowledge --data "D:/data/knowledge" # select an independent data directory
 project-knowledge --port 9000
 project-knowledge --no-open
 ```
 
 Requires Node.js 22 or newer and Git on `PATH`.
 
+Commands such as `stop`, `STOP`, and `Stop` are equivalent. Unknown commands and
+invalid arguments fail without starting a service. Default start/status/stop are
+scoped to the selected data directory; stopping another directory requires an
+explicit port or `--data`. The CLI uses a local control channel, not a shared PID
+file or blind process termination. Stop succeeds only after the backend and its
+owned modules finish shutdown; independently started modules are preserved.
+An older or unverifiable instance is reported explicitly, never treated as safely
+stopped. Stop the previous running version before upgrading.
+
 ### Windows desktop
 
 Version 5.0.0 delivers the web product through npm. A new Windows installer

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

@@ -14,9 +14,9 @@ const { spawn, spawnSync } = require('child_process');
 const ROOT = path.resolve(__dirname, '..', '..');
 const BIN = path.join(ROOT, 'bin', 'project-knowledge.js');
 const KB_BIN = path.join(ROOT, 'bin', 'project-knowledge-kb.js');
-const PID_FILE = path.join(os.tmpdir(), '.project-knowledge.pid');
 const ISOLATED_STATUS_PORT = 19000 + (process.pid % 1000);
 const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-${process.pid}-`));
+const PID_FILE = path.join(TEST_DATA_DIR, 'runtime-endpoint.json');
 const TEST_BRIDGE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), `kb-bin-cli-bridge-${process.pid}-`));
 const TEST_ENV = { ...process.env, KB_DATA_DIR: TEST_DATA_DIR, KB_SKIP_MIGRATION: '1', AI_CODING_EVENT_BRIDGE_HOME: TEST_BRIDGE_HOME, KB_MODULES_AUTOSTART: '0' };
 
@@ -35,8 +35,7 @@ function run(args, opts = {}) {
 function readPidFile() {
   try {
     if (!fs.existsSync(PID_FILE)) return null;
-    const lines = fs.readFileSync(PID_FILE, 'utf-8').trim().split('\n');
-    return { pid: parseInt(lines[0], 10), port: lines[1] ? parseInt(lines[1], 10) : null };
+    return JSON.parse(fs.readFileSync(PID_FILE, 'utf8'));
   } catch { return null; }
 }
 

package/_site/_test/claude-workbench-test.js

@@ -9,6 +9,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
+const TEST_DATA = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-workbench-unit-'));
+process.env.KB_DATA_DIR = TEST_DATA;
+process.on('exit', () => fs.rmSync(TEST_DATA, { recursive: true, force: true }));
 const runner = require('../lib/claude-cli-runner');
 
 const ROOT = path.resolve(__dirname, '..', '..');

package/_site/_test/cli-instance-management-test.js

@@ -0,0 +1,62 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+const endpoint = require('../lib/runtime-endpoint');
+const control = require('../lib/runtime-control');
+const packageRoot = process.env.KB_CLI_TEST_PACKAGE || path.resolve(__dirname, '../..');
+const bin = path.join(packageRoot, 'bin/project-knowledge.js');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-instance-management-'));
+const a = path.join(root, '知识库 A'), b = path.join(root, '知识库 B');
+const temp = path.join(root, 'isolated-temp'); fs.mkdirSync(temp);
+const env = { ...process.env, KB_DATA_DIR: a, TEMP: temp, TMP: temp, KB_MODULES_AUTOSTART: '0', AI_CODING_EVENT_BRIDGE_HOME: path.join(root, 'bridge') };
+const pids = [];
+function run(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`CLI timeout: ${stdout} ${stderr}`)); }, 25000);
+    child.stdout.on('data', c => { stdout += c; }); child.stderr.on('data', c => { stderr += c; });
+    child.once('error', reject); child.once('exit', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+  });
+}
+async function usable(port) { try { return (await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(700) })).ok; } catch { return false; } }
+let foreign;
+(async () => {
+  foreign = http.createServer((req, res) => { res.writeHead(404); res.end('not knowledge'); });
+  await new Promise(resolve => foreign.listen(0, '127.0.0.1', resolve));
+  const foreignPort = foreign.address().port;
+  fs.writeFileSync(path.join(temp, '.project-knowledge.pid'), `${process.pid}\n${foreignPort}`);
+  for (const args of [['stoop'], ['STOP', 'unexpected'], ['stop', '--port', '12junk'], ['stop', '--port', '65536'], ['stop', '--port'], ['stop', '--all']]) {
+    const result = await run(args); assert.equal(result.code, 1, JSON.stringify(result));
+    assert(!/Already running|starting in background/.test(result.stdout));
+  }
+  assert.equal(fs.existsSync(a), false, 'invalid commands must not create data or services');
+  const noInstance = await run(['STOP']); assert.equal(noInstance.code, 0); assert.match(noInstance.stdout, /No background/);
+  assert.equal(await usable(foreignPort), false); assert(foreign.listening, 'shared legacy PID must not kill an unrelated process');
+  const launchedA = await run(['START', '--no-open']); assert.equal(launchedA.code, 0, launchedA.stderr);
+  const infoA = endpoint.readEndpoint(a); pids.push(infoA.pid); assert(await usable(infoA.port));
+  const launchedB = await run(['start', '--data', b, '--no-open']); assert.equal(launchedB.code, 0, launchedB.stderr);
+  const infoB = endpoint.readEndpoint(b); pids.push(infoB.pid); assert(await usable(infoB.port)); assert.notEqual(infoA.port, infoB.port);
+  const status = await run(['STATUS']); assert.equal(status.code, 0); assert.match(status.stdout, new RegExp(`PID ${infoA.pid}`));
+  const inventory = await run(['STATUS', '--all']); assert.equal(inventory.code, 0, inventory.stderr);
+  assert.match(inventory.stdout, new RegExp(`PID ${infoA.pid}`)); assert.match(inventory.stdout, new RegExp(`PID ${infoB.pid}`));
+  const wrongPort = await run(['STOP', '--port', String(foreignPort)]); assert.equal(wrongPort.code, 1); assert(foreign.listening);
+  const conflict = await run(['stop', '--data', a, '--port', String(infoB.port)]); assert.equal(conflict.code, 1); assert(await usable(infoB.port));
+  await assert.rejects(() => control.request(a, { action: 'stop', pid: infoA.pid + 1, port: infoA.port, startedAt: infoA.startedAt }), /身份/);
+  assert(await usable(infoA.port));
+  const stoppedA = await run(['STOP']); assert.equal(stoppedA.code, 0, stoppedA.stderr); assert.match(stoppedA.stdout, new RegExp(`:${infoA.port}`));
+  assert.equal(await usable(infoA.port), false); assert(await usable(infoB.port), 'default stop must preserve a different data directory');
+  const stoppedB = await run(['stop', '--port', String(infoB.port)]); assert.equal(stoppedB.code, 0, stoppedB.stderr); assert.equal(await usable(infoB.port), false);
+  assert.equal((await run(['stop'])).code, 0, 'repeated stop is harmless');
+  fs.writeFileSync(path.join(a, 'runtime-endpoint.json'), JSON.stringify({ schema: endpoint.SCHEMA, pid: process.pid, host: '127.0.0.1', port: foreignPort }));
+  const stale = await run(['STOP']); assert.equal(stale.code, 1); assert.match(stale.stderr, /控制通道不可用/); assert(foreign.listening, 'a live but unrelated recorded PID is never signaled');
+  const refused = await run(['start', '--no-open']); assert.equal(refused.code, 1); assert(foreign.listening);
+  console.log('CLI instance management PASS: case, strict arguments, inventory, two directories, targeted stop, spoof protection, stale/shared PID safety');
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(async () => {
+  foreign?.closeAllConnections(); if (foreign?.listening) await new Promise(resolve => foreign.close(resolve));
+  for (const data of [a, b]) try { const info = await control.request(data, { action: 'status' }, 500); await control.request(data, { action: 'stop', pid: info.instance.pid, port: info.instance.port, startedAt: info.instance.startedAt }); } catch {}
+});

package/_site/_test/fresh-product-data-test.js

@@ -16,6 +16,20 @@ const { connectEngine } = require('../lib/engine-connection');
   assert.equal(fs.readFileSync(path.join(old, 'projects.json'), 'utf8'), bytes);
   const fresh = path.join(root, 'fresh'); initializeProductData(fresh); initializeProductData(fresh);
   assert.equal(JSON.parse(fs.readFileSync(path.join(fresh, 'product-data.json'))).schema, DATA_SCHEMA);
+  const auxiliary = path.join(root, 'auxiliary');
+  const session = path.join(auxiliary, 'runtime', 'claude-sessions', 'unregistered-test', 'session.json');
+  fs.mkdirSync(path.dirname(session), { recursive: true });
+  fs.writeFileSync(session, 'untouched abandoned chat');
+  fs.writeFileSync(path.join(auxiliary, 'launcher.log'), 'old startup failure');
+  initializeProductData(auxiliary);
+  assert.equal(fs.readFileSync(session, 'utf8'), 'untouched abandoned chat');
+  for (const entry of ['claims', 'runs', 'promotions', 'transactions', 'unknown-business-state']) {
+    const pending = path.join(root, entry);
+    fs.mkdirSync(path.join(pending, 'runtime', entry), { recursive: true });
+    fs.writeFileSync(path.join(pending, 'runtime', entry, 'record.json'), '{}');
+    assert.throws(() => initializeProductData(pending), error => error.code === 'SCHEMA_UNSUPPORTED' && error.message.includes(`runtime/${entry}`));
+    assert.equal(fs.existsSync(path.join(pending, 'product-data.json')), false);
+  }
   const paths = [];
   let activationStatus = 403;
   const logs = [];

package/_site/_test/launcher-readiness-test.js

@@ -0,0 +1,80 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const net = require('node:net');
+const { spawn } = require('node:child_process');
+const endpoint = require('../lib/runtime-endpoint');
+
+const packageRoot = process.env.KB_LAUNCHER_TEST_PACKAGE || path.resolve(__dirname, '../..');
+const bin = path.join(packageRoot, 'bin/project-knowledge.js');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-launcher-readiness-'));
+const data = path.join(root, '.project-knowledge-v5');
+const record = path.join(data, 'runtime/claude-sessions/project-a/session.json');
+const recordBytes = JSON.stringify({ schema: 'claude-workbench-session/v1', sessionId: 'old-test', projectSlug: 'project-a', state: 'running', metadata: { automation: true } });
+fs.mkdirSync(path.dirname(record), { recursive: true });
+fs.writeFileSync(record, recordBytes);
+const env = { ...process.env, KB_DATA_DIR: data, KB_MODULES_AUTOSTART: '0', AI_CODING_EVENT_BRIDGE_HOME: path.join(root, 'bridge') };
+let serverPid;
+
+function run(args, overrides = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], { cwd: root, env: { ...env, ...overrides }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`CLI timed out: ${stdout} ${stderr}`)); }, 25000);
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('exit', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+  });
+}
+async function freePort() {
+  const server = net.createServer();
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+
+(async () => {
+  const port = await freePort();
+  const launched = await run(['--no-open'], { KB_SITE_PORT: String(port) });
+  serverPid = endpoint.readEndpoint(data)?.pid;
+  assert.equal(launched.code, 0, launched.stderr);
+  assert.match(launched.stdout, new RegExp(`is ready at http://127.0.0.1:${port}`));
+  assert(serverPid && endpoint.isProcessAlive(serverPid));
+  const response = await fetch(`http://127.0.0.1:${port}/api/state`);
+  assert.equal(response.status, 200, 'ready must mean HTTP is usable, not only a PID exists');
+  const state = await response.json();
+  assert.deepEqual(state.projects, [], 'abandoned sessions must not import projects or enqueue analysis');
+  assert.equal(fs.readFileSync(record, 'utf8'), recordBytes);
+  const again = await run(['--no-open']);
+  assert.equal(again.code, 0);
+  assert.match(again.stdout, /Already running/);
+  const stopped = await run(['stop']);
+  assert.equal(stopped.code, 0);
+  for (let attempt = 0; attempt < 50 && endpoint.isProcessAlive(serverPid); attempt++) await new Promise(resolve => setTimeout(resolve, 100));
+  assert.equal(endpoint.isProcessAlive(serverPid), false);
+  serverPid = null;
+
+  const oldData = path.join(root, 'actual-old-data');
+  fs.mkdirSync(oldData);
+  const original = JSON.stringify({ projectOrder: ['old-project'] });
+  fs.writeFileSync(path.join(oldData, 'projects.json'), original);
+  const failed = await run(['--no-open', '--port', String(port)], { KB_DATA_DIR: oldData });
+  assert.equal(failed.code, 1, 'background failures must return nonzero to the invoking terminal');
+  assert.match(failed.stderr, /启动失败/);
+  assert.match(failed.stderr, /projects\.json/);
+  assert(!/is ready|Listening at/.test(failed.stdout));
+  assert.equal(fs.readFileSync(path.join(oldData, 'projects.json'), 'utf8'), original);
+  assert.equal(fs.existsSync(path.join(oldData, 'product-data.json')), false);
+  const log = fs.readFileSync(path.join(oldData, 'launcher.log'), 'utf8');
+  assert.match(log, /startup failed/);
+  assert(!/Listening at/.test(log), 'never advertise a listener before initialization succeeds');
+  console.log('launcher readiness PASS: unrelated cwd, abandoned records, HTTP readiness, stop, terminal failure, legacy preservation');
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(() => {
+  if (serverPid && endpoint.readEndpoint(data)?.pid === serverPid) {
+    try { process.kill(serverPid); } catch {}
+  }
+});

package/_site/_test/run-all-tests.js

@@ -54,13 +54,15 @@ function runOne(file) {
   // Every test child gets its own Bridge journal sandbox so hook-trigger /
   // server runtimes never touch the developer's ~/.ai-coding-event-bridge.
   const bridgeHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-bridge-${process.pid}-`));
+  const dataHome = fs.mkdtempSync(path.join(os.tmpdir(), `kb-runall-data-${process.pid}-`));
   const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
     cwd: ROOT,
     encoding: 'utf-8',
     timeout: PER_TEST_TIMEOUT_MS,
-    env: { ...process.env, FORCE_COLOR: '0', AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
+    env: { ...process.env, FORCE_COLOR: '0', KB_DATA_DIR: dataHome, AI_CODING_EVENT_BRIDGE_HOME: bridgeHome, KB_MODULES_AUTOSTART: '0' },
   });
   try { fs.rmSync(bridgeHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
+  try { fs.rmSync(dataHome, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch {}
   const failure = result.status === 0 ? null : classifyFailure(result);
   return {
     file,

package/_site/lib/cli-instances.js

@@ -0,0 +1,43 @@
+'use strict';
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const control = require('./runtime-control');
+
+function url(info) { return `http://${info.host === '::1' ? '[::1]' : info.host}:${info.port}`; }
+async function current(dataDir) {
+  try { const response = await control.request(dataDir, { action: 'status' }, 1500); return { ...response.instance, status: response.status }; }
+  catch (error) { if (['ENOENT', 'ECONNREFUSED', 'EPIPE'].includes(error.code)) return null; throw error; }
+}
+async function atPort(port) {
+  const response = await fetch(`http://127.0.0.1:${port}/api/runtime/identity`, { signal: AbortSignal.timeout(1200), headers: { Connection: 'close' } });
+  if (!response.ok) throw new Error(`端口 ${port} 不是可控制的知识库实例（HTTP ${response.status}）。`);
+  const info = await response.json();
+  if (info.schema !== control.SCHEMA || info.name !== 'project-knowledge' || info.port !== port || !path.isAbsolute(info.dataDir || '')) throw new Error(`端口 ${port} 的实例身份无效，已拒绝控制。`);
+  const verified = await current(info.dataDir);
+  if (!verified || verified.pid !== info.pid || verified.port !== port || verified.startedAt !== info.startedAt) throw new Error(`端口 ${port} 的实例已变化，已拒绝控制。`);
+  return verified;
+}
+function listeningPorts() {
+  let output;
+  if (process.platform === 'win32') {
+    output = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', "Get-NetTCPConnection -State Listen -ErrorAction Stop | Where-Object { $_.LocalAddress -in @('127.0.0.1','0.0.0.0','::1','::') } | Select-Object -ExpandProperty LocalPort -Unique"], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    return [...new Set(output.split(/\s+/).map(Number).filter(n => Number.isInteger(n) && n > 0 && n <= 65535))];
+  }
+  if (process.platform === 'darwin') output = execFileSync('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn'], { encoding: 'utf8', timeout: 5000 });
+  else output = execFileSync('ss', ['-tlnH'], { encoding: 'utf8', timeout: 5000 });
+  return [...new Set([...output.matchAll(/:(\d+)(?:\s|$)/gm)].map(match => Number(match[1])))];
+}
+async function all() {
+  const ports = listeningPorts(), instances = [], seen = new Set();
+  // Bounded read-only probes; no PID is ever killed by inventory discovery.
+  for (let i = 0; i < ports.length; i += 8) {
+    const found = await Promise.all(ports.slice(i, i + 8).map(port => atPort(port).catch(() => null)));
+    for (const info of found) if (info && !seen.has(info.pid + ':' + info.port)) { seen.add(info.pid + ':' + info.port); instances.push(info); }
+  }
+  return instances.sort((a, b) => a.port - b.port);
+}
+async function stop(info) {
+  const result = await control.request(info.dataDir, { action: 'stop', pid: info.pid, port: info.port, startedAt: info.startedAt });
+  if (result.status !== 'stopped') throw new Error('停止尚未确认。');
+}
+module.exports = { current, atPort, all, stop, url };

package/_site/lib/product-data.js

@@ -5,6 +5,10 @@ const { DomainError } = require('./contracts');
 
 const DATA_SCHEMA = 'project-knowledge/fresh-product-data/v1';
 
+function hasData(file) {
+  return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
+}
+
 function initializeProductData(dataPath) {
   const marker = path.join(dataPath, 'product-data.json');
   if (fs.existsSync(marker)) {
@@ -13,11 +17,18 @@ function initializeProductData(dataPath) {
     return;
   }
   // Old registries and unfinished claims must never become fresh product work.
-  const oldData = ['settings.json', 'projects.json', 'projects', 'runtime', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json'].some(name => {
-    const file = path.join(dataPath, name);
-    return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
-  });
-  if (oldData) throw new DomainError('SCHEMA_UNSUPPORTED', '不再迁移旧版知识库数据。请取消旧 KB_DATA_DIR 设置，或指定新的空数据目录，然后重新导入项目。', { status: 409 });
+  const oldData = ['settings.json', 'projects.json', 'projects', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json']
+    .filter(name => hasData(path.join(dataPath, name)));
+  const runtimePath = path.join(dataPath, 'runtime');
+  if (fs.existsSync(runtimePath)) {
+    if (!fs.statSync(runtimePath).isDirectory()) oldData.push('runtime');
+    else for (const name of fs.readdirSync(runtimePath)) {
+      // Unregistered legacy chat records cannot be resumed by a fresh registry.
+      // They are neither knowledge nor pending maintenance, and stay untouched.
+      if (name !== 'claude-sessions' && hasData(path.join(runtimePath, name))) oldData.push(`runtime/${name}`);
+    }
+  }
+  if (oldData.length) throw new DomainError('SCHEMA_UNSUPPORTED', `数据目录 ${dataPath} 包含旧版业务数据（${oldData.join('、')}）。新版不会迁移或删除它们；请将 KB_DATA_DIR 指向新的空目录，然后重新导入项目。`, { status: 409, details: { dataPath, entries: oldData } });
   AtomicFile.writeJsonAtomic(marker, { schema: DATA_SCHEMA, createdAt: new Date().toISOString() });
 }
 

package/_site/lib/runtime-control.js

@@ -0,0 +1,89 @@
+'use strict';
+const net = require('node:net');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SCHEMA = 'project-knowledge/runtime-control/v1';
+function normalizeDataDir(value) {
+  const absolute = path.resolve(value);
+  return process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+}
+function controlPath(dataDir) {
+  const hash = crypto.createHash('sha256').update(normalizeDataDir(dataDir)).digest('hex').slice(0, 32);
+  return process.platform === 'win32' ? `\\\\.\\pipe\\project-knowledge-${hash}` : path.join(dataDir, 'runtime-control.sock');
+}
+function identity(dataDir, endpoint = {}) {
+  return { schema: SCHEMA, name: 'project-knowledge', pid: process.pid, dataDir: path.resolve(dataDir), ...endpoint };
+}
+function request(dataDir, message, timeoutMs = 45000) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(controlPath(dataDir));
+    let buffer = '', done = false;
+    const timer = setTimeout(() => socket.destroy(new Error('知识库控制请求超时，停止尚未确认。')), timeoutMs);
+    const finish = (error, result) => {
+      if (done) return; done = true;
+      clearTimeout(timer); socket.destroy();
+      if (error) reject(error); else resolve(result);
+    };
+    socket.once('connect', () => socket.write(JSON.stringify(message) + '\n'));
+    socket.on('data', chunk => {
+      buffer += chunk.toString();
+      if (buffer.length > 65536) return finish(new Error('无效的实例响应。'));
+      if (!buffer.includes('\n')) return;
+      try {
+        const value = JSON.parse(buffer.slice(0, buffer.indexOf('\n')));
+        if (!value.ok) return finish(new Error(value.message || '实例控制失败。'));
+        if (value.instance?.schema !== SCHEMA || normalizeDataDir(value.instance.dataDir) !== normalizeDataDir(dataDir)) return finish(new Error('实例身份不匹配，已拒绝控制。'));
+        finish(null, value);
+      } catch (error) { finish(error); }
+    });
+    socket.once('error', error => finish(error));
+    socket.once('end', () => { if (!buffer.includes('\n')) finish(new Error('实例断开连接，停止尚未确认。')); });
+  });
+}
+
+async function listen(dataDir, info, stop) {
+  const address = controlPath(dataDir);
+  if (process.platform !== 'win32' && fs.existsSync(address)) {
+    try { await request(dataDir, { action: 'status' }, 1000); throw new Error('另一个知识库实例已占用控制通道。'); }
+    catch (error) {
+      if (!['ECONNREFUSED', 'ENOENT'].includes(error.code)) throw error;
+      fs.unlinkSync(address);
+    }
+  }
+  const sockets = new Set();
+  let stopping = false, stoppingSocket;
+  const server = net.createServer(socket => {
+    sockets.add(socket); socket.once('close', () => sockets.delete(socket));
+    socket.on('error', () => {});
+    socket.setTimeout(45000, () => socket.destroy());
+    let buffer = '';
+    socket.on('data', chunk => {
+      buffer += chunk.toString();
+      if (buffer.length > 16384) return socket.destroy();
+      if (!buffer.includes('\n')) return;
+      socket.removeAllListeners('data');
+      const respond = value => { if (!socket.destroyed) socket.end(JSON.stringify({ ...value, instance: info }) + '\n'); };
+      let message;
+      try { message = JSON.parse(buffer.slice(0, buffer.indexOf('\n'))); }
+      catch { return respond({ ok: false, message: '无效的控制请求。' }); }
+      if (message.action === 'status') return respond({ ok: true, status: stopping ? 'stopping' : 'running' });
+      // A stale endpoint/port must never become a signal to an unrelated PID.
+      if (message.action !== 'stop' || message.pid !== info.pid || message.port !== info.port || message.startedAt !== info.startedAt) return respond({ ok: false, message: '实例身份已变化，已拒绝停止。' });
+      if (stopping) return respond({ ok: false, message: '实例正在停止，请稍后查询状态。' });
+      stopping = true; stoppingSocket = socket;
+      Promise.resolve().then(stop).then(() => respond({ ok: true, status: 'stopped' })).catch(error => respond({ ok: false, message: error.message }));
+    });
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(address, resolve); });
+  if (process.platform !== 'win32') fs.chmodSync(address, 0o600);
+  return {
+    close() {
+      // Keep only the requesting socket for the final shutdown acknowledgement.
+      return new Promise(resolve => { server.close(resolve); for (const socket of sockets) if (socket !== stoppingSocket) socket.destroy(); if (stopping) resolve(); });
+    },
+  };
+}
+
+module.exports = { SCHEMA, normalizeDataDir, identity, controlPath, request, listen };

package/_site/lib/server-app.js

@@ -5,6 +5,7 @@ const crypto = require('crypto');
 
 const dataDir = require('./data-dir');
 const runtimeEndpoint = require('./runtime-endpoint');
+const runtimeControl = require('./runtime-control');
 const hookManager = require('./hook-manager');
 const claudeCliRunner = require('./claude-cli-runner');
 const { StorageLayout } = require('./storage-layout');
@@ -965,6 +966,10 @@ function createRequestHandler(runtime, options = {}) {
       if (method === 'GET' && pathname === '/api/health') {
         return send(res, 200, { ok: true, schema: 'server-health/v2', logger: runtime.logger.getHealth(), projects: runtime.registryStore.listIds().length });
       }
+      if (method === 'GET' && pathname === '/api/runtime/identity') {
+        if (!isLoopback(req.socket?.remoteAddress?.replace(/^::ffff:/, ''))) throw new DomainError('ORIGIN_FORBIDDEN', 'Runtime identity is local-only.', { status: 403 });
+        return send(res, 200, runtime.instanceIdentity);
+      }
       if (method === 'GET' && pathname === '/api/state') {
         const settings = runtime.settingsStore.readPublicView();
         return send(res, 200, { ok: true, schema: 'server-state/v2', settings, projects: listProjectViews(runtime.registryStore, runtime.projectStore), logger: runtime.logger.getHealth() });
@@ -1467,6 +1472,7 @@ async function startServer(options = {}) {
   }
   let startup;
   let server;
+  let controlServer;
   try {
     startup = await initializeRuntime(runtime);
     const handler = createRequestHandler(runtime, { ...options, port, host });
@@ -1533,10 +1539,14 @@ async function startServer(options = {}) {
       if (runtime.bridgeConsumerService) await runtime.bridgeConsumerService.stop().catch(() => {});
       await runtime.moduleBridge.stopSupervised();
       await runtime.logger.close();
+      await controlServer?.close();
       runtimeEndpoint.clearEndpoint(runtime.dataPath, { pid: process.pid });
     })();
     return stopping;
   };
+  runtime.instanceIdentity = runtimeControl.identity(runtime.dataPath, { host, port, version: require('../../package.json').version, startedAt: runtimeEndpoint.readEndpoint(runtime.dataPath)?.startedAt || new Date().toISOString() });
+  try { controlServer = await runtimeControl.listen(runtime.dataPath, runtime.instanceIdentity, () => stop('cli-control')); }
+  catch (error) { await stop('control-startup-failed'); throw error; }
   return { server, runtime, startup, startupPromise, stop, host, port };
 }
 

package/_site/server.js

@@ -3,10 +3,13 @@ const { startServer, installProcessHandlers } = require('./lib/server-app');
 
 const instancePromise = startServer();
 installProcessHandlers(instancePromise);
+module.exports = instancePromise;
 
 instancePromise.then(instance => {
   process.stdout.write(`Project Knowledge listening on http://${instance.host}:${instance.port}\n`);
 }).catch(error => {
-  process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
-  process.exitCode = 1;
+  if (require.main === module) {
+    process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
+    process.exitCode = 1;
+  }
 });

package/bin/project-knowledge.js

@@ -1,439 +1,170 @@
 #!/usr/bin/env node
-
-// project-knowledge CLI — start in background by default (auto-opens browser).
-// Pattern modeled on tokmeter's bin.js: detached child + PID file + port fallback.
-// Run `project-knowledge --help` for usage.
-
-const path = require('path');
-const { spawn, spawnSync, exec, execSync } = require('child_process');
-const { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync } = require('fs');
-const net = require('net');
-const os = require('os');
-const { getDataDir } = require('../_site/lib/data-dir');
-const runtimeEndpoint = require('../_site/lib/runtime-endpoint');
-
+'use strict';
+const path = require('node:path');
+const fs = require('node:fs');
+const net = require('node:net');
+const { spawn, spawnSync, exec } = require('node:child_process');
+const { resolveDataDirPath } = require('../_site/lib/data-dir');
+const endpoint = require('../_site/lib/runtime-endpoint');
+const instances = require('../_site/lib/cli-instances');
 const pkg = require('../package.json');
-const DEFAULT_PORT = parseInt(process.env.KB_SITE_PORT || '5757', 10);
-const PORT_RANGE = 20;
-const PID_FILE = path.join(os.tmpdir(), '.project-knowledge.pid');
-const DATA_DIR = getDataDir();
-
-function readPid() {
-  try {
-    if (!existsSync(PID_FILE)) return null;
-    const lines = readFileSync(PID_FILE, 'utf8').trim().split('\n');
-    return parseInt(lines[0], 10);
-  } catch { return null; }
-}
-
-function readPort() {
-  try {
-    if (!existsSync(PID_FILE)) return null;
-    const lines = readFileSync(PID_FILE, 'utf8').trim().split('\n');
-    return lines[1] ? parseInt(lines[1], 10) : null;
-  } catch { return null; }
-}
-
-function writePid(pid, port) {
-  try {
-    writeFileSync(PID_FILE, `${pid}\n${port}`, 'utf8');
-  } catch (err) {
-    console.error(`Warning: failed to write PID file at ${PID_FILE}: ${err.message}`);
-  }
-}
-
-function removePid(expectedPid) {
-  try {
-    if (expectedPid != null && readPid() !== Number(expectedPid)) return;
-    unlinkSync(PID_FILE);
-  } catch { /* ignore */ }
-}
-
-function isProcessAlive(pid) {
-  if (!pid || Number.isNaN(pid)) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function openBrowser(url) {
-  let cmd;
-  if (process.platform === 'win32') {
-    cmd = `start "" "${url}"`;
-  } else if (process.platform === 'darwin') {
-    cmd = `open "${url}"`;
-  } else {
-    cmd = `xdg-open "${url}"`;
-  }
-  try { exec(cmd); } catch { /* best-effort */ }
-}
-
-function isPortFree(port, host = '127.0.0.1') {
-  return new Promise((resolve) => {
-    const tester = net.createServer();
-    let settled = false;
-    const finish = (free) => {
-      if (settled) return;
-      settled = true;
-      tester.removeAllListeners();
-      tester.close(() => resolve(free));
-    };
-    tester.once('error', () => finish(false));
-    tester.once('listening', () => finish(true));
-    tester.listen(port, host);
-    // Under AV scan / cold cache a listen() can be slower than the probe
-    // timeout; a false "busy" cascades into "No free port found". 3s is slow
-    // enough for one probe while still bounding the 20-port scan.
-    setTimeout(() => finish(false), 3000);
-  });
-}
-
-async function findFreePort(start, host = '127.0.0.1') {
-  for (let offset = 0; offset < PORT_RANGE; offset++) {
-    const port = start + offset;
-    if (await isPortFree(port, host)) return port;
-  }
-  throw new Error(`No free port found in range ${start}-${start + PORT_RANGE - 1}`);
-}
-
-// Find PIDs whose TCP socket is LISTENING on `port`. Cross-platform wrapper
-// around netstat / lsof / ss. Returns a deduped list, possibly empty.
-function findListeningPids(port) {
-  try {
-    let cmd;
-    if (process.platform === 'win32') {
-      cmd = `netstat -ano | findstr ":${port} " | findstr "LISTENING"`;
-    } else if (process.platform === 'darwin') {
-      cmd = `lsof -nP -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null`;
-    } else {
-      cmd = `ss -tlnpH 'sport = :${port}' 2>/dev/null | grep -oP 'pid=\\K[0-9]+'`;
-    }
-    const stdout = execSync(cmd, { windowsHide: true, encoding: 'utf8', timeout: 3000 });
-    const pids = stdout.split(/\r?\n/).map((line) => {
-      const nums = line.match(/\d+/g);
-      return nums && nums.length ? parseInt(nums[nums.length - 1], 10) : null;
-    }).filter(Boolean);
-    return Array.from(new Set(pids));
-  } catch {
-    return [];
-  }
-}
-
-// Read another process's command line so we can verify it's ours before
-// killing it. Returns '' on any failure (permissions, process gone, etc).
-function getProcessCommandLine(pid) {
-  try {
-    let cmd, stdout;
-    if (process.platform === 'win32') {
-      stdout = execSync(`wmic process where "ProcessId=${pid}" get CommandLine /value`,
-        { windowsHide: true, encoding: 'utf8', timeout: 3000 });
-      const m = stdout.match(/CommandLine=(.+)/);
-      return m ? m[1].trim() : '';
-    }
-    stdout = execSync(`ps -p ${pid} -o args= 2>/dev/null`,
-      { encoding: 'utf8', timeout: 3000 });
-    return stdout.trim();
-  } catch {
-    return '';
-  }
-}
-
-// Scan DEFAULT_PORT..+PORT_RANGE for a LISTENING PID whose command line looks
-// like our server. Used as a fallback when the PID file is missing/stale so the
-// CLI isn't blind to long-running orphans.
-function findOrphanProcess() {
-  const startPort = readPort() || DEFAULT_PORT;
-  for (let offset = 0; offset < PORT_RANGE; offset++) {
-    const port = startPort + offset;
-    for (const candidate of findListeningPids(port)) {
-      const cmdline = getProcessCommandLine(candidate).toLowerCase();
-      if (cmdline.includes('project-knowledge') && cmdline.includes('node')) {
-        return { pid: candidate, port };
-      }
-    }
-  }
-  return null;
-}
-
-// ── Subcommands ──
-function cmdStop() {
-  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
-  if (endpoint) {
-    try {
-      process.kill(endpoint.pid);
-      runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: endpoint.pid });
-      if (readPid() === endpoint.pid) removePid(endpoint.pid);
-      console.log(`project-knowledge stopped (PID ${endpoint.pid}).`);
-    } catch {
-      console.error(`Failed to stop process ${endpoint.pid}`);
-      process.exit(1);
-    }
-    process.exit(0);
-  }
-  const pid = readPid();
-  if (pid && isProcessAlive(pid)) {
-    try {
-      process.kill(pid);
-      removePid();
-      console.log(`project-knowledge stopped (PID ${pid}).`);
-    } catch {
-      console.error(`Failed to stop process ${pid}`);
-      process.exit(1);
-    }
-    process.exit(0);
-  }
-  if (pid) {
-    // Stale PID file — record pointed at a dead process. Drop it so the
-    // orphan-scan below can take over without being misled.
-    removePid();
-    console.log('Process already stopped.');
-  }
-
-  // Fallback: the PID file can disappear (manual cleanup, antivirus, OS temp
-  // cleanup) while the server keeps running. Without this scan the CLI has no
-  // way to stop an orphan whose PID it never recorded.
-  const orphan = findOrphanProcess();
-  if (orphan) {
-    try {
-      process.kill(orphan.pid);
-      console.log(`Stopped orphan project-knowledge (PID ${orphan.pid}) on port ${orphan.port}.`);
-      process.exit(0);
-    } catch {
-      console.error(`Found PID ${orphan.pid} on port ${orphan.port} but failed to stop it.`);
-      process.exit(1);
-    }
-  }
-  console.log('No background process found.');
-  process.exit(0);
-}
-
-function cmdStatus() {
-  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
-  if (endpoint) {
-    console.log(`project-knowledge is running (PID ${endpoint.pid}) at http://${endpoint.host}:${endpoint.port} [${endpoint.mode}]`);
-    process.exit(0);
-  }
-  const pid = readPid();
-  if (pid && isProcessAlive(pid)) {
-    const port = readPort() || DEFAULT_PORT;
-    console.log(`project-knowledge is running (PID ${pid}) at http://localhost:${port}`);
-    process.exit(0);
-  }
-  if (pid) removePid();
-
-  // PID file is gone or stale — check the port directly.
-  const orphan = findOrphanProcess();
-  if (orphan) {
-    console.log(`project-knowledge is running (orphan, PID ${orphan.pid}) at http://localhost:${orphan.port}`);
-    console.log('(No PID file on disk — recovered via port scan. Run "project-knowledge stop" to clean up.)');
-    process.exit(0);
-  }
-  console.log('project-knowledge is not running.');
-  process.exit(0);
-}
 
-function printHelp() {
+function help() {
   console.log(`project-knowledge ${pkg.version}
 
-Local knowledge-base dashboard manager.
-
 Usage:
-  project-knowledge              Start in background (default), auto-open browser
-  project-knowledge --fg         Start in foreground (Ctrl+C to stop)
-  project-knowledge stop         Stop the background process
-  project-knowledge status       Check if running
-  project-knowledge install      Install coding-agent integrations
-  project-knowledge update       Update coding-agent integrations
-  project-knowledge uninstall    Remove coding-agent integrations
-  project-knowledge integrations status
-                                Check Claude Code, OpenCode, and Codex integrations
+  project-knowledge [start]      Start in background and open the UI
+  project-knowledge --fg         Start in foreground
+  project-knowledge stop         Stop this data directory and its owned modules
+  project-knowledge status       Show this data directory's instance
+  project-knowledge status --all List controllable local knowledge instances
+  project-knowledge stop --port 5804
+                                Stop the verified instance on this port
+  project-knowledge install|update|uninstall|integrations
+                                Manage coding-agent integrations
 
 Options:
-  -p, --port <port>   Port to run on (default: ${DEFAULT_PORT}, auto-fallback ±${PORT_RANGE})
-      --host <host>   Host to bind on (default: 127.0.0.1)
-      --no-open       Don't auto-open browser
-      --fg            Run in foreground
-  -v, --version       Print version and exit
-  -h, --help          Show this help message
-
-Runtime data lives next to the npm global root; PID file at ${PID_FILE}.
-`);
-  process.exit(0);
+  -p, --port <port>  Port (default: 5757, startup auto-fallback +19)
+      --data <dir>   Select data directory (default: ~/.project-knowledge-v5)
+      --host <host>  Bind host (default: 127.0.0.1)
+      --no-open      Do not open browser
+      --fg           Run in foreground
+  -v, --version      Print version
+  -h, --help         Show help
+
+Commands are case-insensitive. Unknown commands never start a service.`);
+}
+function parse(args) {
+  const commands = new Set(['start', 'stop', 'status', 'install', 'update', 'uninstall', 'integrations']);
+  let command = 'start';
+  if (args[0] && !args[0].startsWith('-')) {
+    command = args.shift().toLowerCase();
+    if (!commands.has(command)) throw new Error(`Unknown command: ${command}. Run project-knowledge --help.`);
+  }
+  if (['install', 'update', 'uninstall', 'integrations'].includes(command)) return { command, forwarded: args };
+  const options = { command, port: Number(process.env.KB_SITE_PORT || 5757), host: '127.0.0.1', open: true };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (['--port', '-p', '--host', '--data'].includes(arg)) {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) throw new Error(`Missing value for ${arg}.`);
+      if (arg === '--port' || arg === '-p') { options.port = Number(value); options.portExplicit = true; }
+      else if (arg === '--data') options.dataDir = value;
+      else options.host = value;
+    } else if (arg === '--no-open') options.open = false;
+    else if (arg === '--fg') options.foreground = true;
+    else if (arg === '--all') options.all = true;
+    else throw new Error(`${arg.startsWith('-') ? 'Unknown option' : 'Unexpected argument'}: ${arg}.`);
+  }
+  if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) throw new Error('Port must be an integer from 1 to 65535.');
+  if (options.all && (command !== 'status' || options.portExplicit)) throw new Error('--all is only supported by status, without --port.');
+  if (command !== 'start' && (options.foreground || !options.open || options.host !== '127.0.0.1')) throw new Error('Startup options cannot be used with stop/status.');
+  return options;
 }
-
-// ── Parse args ──
-const args = process.argv.slice(2);
-
-const integrationCommands = new Set(['install', 'update', 'uninstall', 'integrations']);
-if (integrationCommands.has(args[0])) {
-  const forwarded = args[0] === 'integrations'
-    ? (args.slice(1).length ? args.slice(1) : ['status'])
-    : args;
-  const result = spawnSync(
-    process.execPath,
-    [path.join(__dirname, 'project-knowledge-integrations.js'), ...forwarded],
-    { stdio: 'inherit', windowsHide: true }
-  );
-  process.exit(result.status == null ? 1 : result.status);
+function openBrowser(url) {
+  const command = process.platform === 'win32' ? `start "" "${url}"` : process.platform === 'darwin' ? `open "${url}"` : `xdg-open "${url}"`;
+  exec(command, () => {});
+}
+function notify(message) { if (process.connected) process.send(message, () => {}); }
+function waitForStartup(child, log) {
+  return new Promise((resolve, reject) => {
+    const finish = (error, value) => {
+      clearTimeout(timer); child.removeAllListeners('message'); child.removeAllListeners('exit');
+      if (child.connected) child.disconnect();
+      if (error) reject(error); else resolve(value);
+    };
+    const timer = setTimeout(() => finish(new Error(`启动尚未完成，请运行 project-knowledge status 并查看 ${log}`)), 45000);
+    child.on('message', message => {
+      if (message?.type === 'kb:launcher-ready') finish(null, message);
+      else if (message?.type === 'kb:launcher-failed') finish(new Error(message.message));
+    });
+    child.once('error', error => finish(error));
+    child.once('exit', code => finish(new Error(`后台进程在启动完成前退出（${code}），请查看 ${log}`)));
+  });
 }
-
-// Subcommands first
-if (args[0] === 'stop') cmdStop();
-if (args[0] === 'status') cmdStatus();
-
-let port = DEFAULT_PORT;
-let host = '127.0.0.1';
-let shouldOpen = true;
-let foreground = false;
-let portExplicit = false;
-let hostExplicit = false;
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === '--help' || arg === '-h') {
-    printHelp();
-  } else if (arg === '--version' || arg === '-v') {
-    console.log(pkg.version);
-    process.exit(0);
-  } else if ((arg === '--port' || arg === '-p') && args[i + 1]) {
-    const parsed = parseInt(args[i + 1], 10);
-    if (Number.isNaN(parsed)) {
-      console.error('Error: --port must be a number');
-      process.exit(1);
+function portFree(port, host) {
+  return new Promise(resolve => {
+    const tester = net.createServer();
+    let done = false;
+    const timer = setTimeout(() => finish(false), 3000);
+    function finish(free) {
+      if (done) return; done = true; clearTimeout(timer); tester.close(() => resolve(free));
     }
-    port = parsed;
-    portExplicit = true;
-    i++;
-  } else if (arg === '--host' && args[i + 1]) {
-    host = args[i + 1];
-    hostExplicit = true;
-    i++;
-  } else if (arg === '--no-open') {
-    shouldOpen = false;
-  } else if (arg === '--fg') {
-    foreground = true;
-  } else if (arg.startsWith('-')) {
-    console.error(`Unknown option: ${arg}\nRun \`project-knowledge --help\` for usage.`);
-    process.exit(1);
-  }
+    tester.once('error', () => finish(false)); tester.once('listening', () => finish(true)); tester.listen(port, host);
+  });
 }
-
-// ── Background launch ──
-if (!foreground) {
-  const endpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
-  if (endpoint) {
-    const url = `http://${endpoint.host}:${endpoint.port}`;
-    console.log(`Already running (PID ${endpoint.pid}) at ${url}`);
-    if (shouldOpen) openBrowser(url);
-    process.exit(0);
-  }
-  const existingPid = readPid();
-  if (existingPid && isProcessAlive(existingPid)) {
-    const actualPort = readPort() || DEFAULT_PORT;
-    const url = `http://localhost:${actualPort}`;
-    console.log(`Already running (PID ${existingPid}) at ${url}`);
-    if (shouldOpen) openBrowser(url);
-    process.exit(0);
-  }
-  removePid();
-
-  // Re-spawn self with --fg so the child owns the PID file
-  const forwarded = [];
-  if (portExplicit) forwarded.push('--port', String(port));
-  if (hostExplicit) forwarded.push('--host', host);
-  if (!shouldOpen) forwarded.push('--no-open');
-
-  // The parent doesn't know the final port (the child may fall back when the
-  // default is busy), so it must not print a URL or open the browser — the
-  // child does both once it is actually listening. The child's output goes to
-  // a log file: a detached child with stdio:'ignore' is undiagnosable when
-  // startup fails or the port falls back.
-  const LAUNCH_LOG = path.join(DATA_DIR, 'launcher.log');
-  let logFd;
-  try {
-    mkdirSync(path.dirname(LAUNCH_LOG), { recursive: true });
-    logFd = openSync(LAUNCH_LOG, 'a');
-  } catch { /* best-effort: fall back to discarding output */ }
-  const stdio = logFd == null ? 'ignore' : ['ignore', logFd, logFd];
-
-  const child = spawn(
-    process.execPath,
-    [...process.argv.slice(1), '--fg', ...forwarded],
-    { detached: true, stdio, windowsHide: true }
-  );
-  child.unref();
-
-  console.log('project-knowledge starting in background');
-  console.log(`Diagnostics: ${LAUNCH_LOG}`);
-  console.log(`Use "project-knowledge status" to check, "project-knowledge stop" to stop.`);
-  process.exit(0);
+async function freePort(port, host) {
+  for (let offset = 0; offset < 20 && port + offset <= 65535; offset++) if (await portFree(port + offset, host)) return port + offset;
+  throw new Error(`No free port found near ${port}.`);
 }
-
-// ── Foreground: start server ──
-process.env.KB_SITE_HOST = host;
+function show(info) { console.log(`project-knowledge is ${info.status === 'stopping' ? 'stopping' : 'running'} (PID ${info.pid}) at ${instances.url(info)} [${info.version}]\nData dir: ${info.dataDir}`); }
 
 async function main() {
-  const existingEndpoint = runtimeEndpoint.readLiveEndpoint(DATA_DIR);
-  if (existingEndpoint && existingEndpoint.pid !== process.pid) {
-    console.log(`Already running (PID ${existingEndpoint.pid}) at http://${existingEndpoint.host}:${existingEndpoint.port}`);
-    process.exit(0);
-  }
-  const actualPort = portExplicit ? port : await findFreePort(port, host);
-  process.env.KB_SITE_PORT = String(actualPort);
-
-  const claim = runtimeEndpoint.claimEndpoint(DATA_DIR, {
-    pid: process.pid,
-    host,
-    port: actualPort,
-    mode: process.env.KB_RUNTIME_MODE || 'cli',
-  });
-  if (!claim.claimed) {
-    const active = claim.endpoint;
-    if (active) {
-      console.log(`Already running (PID ${active.pid}) at http://${active.host}:${active.port}`);
-    } else {
-      console.error('Another project-knowledge process is starting. Please try again in a moment.');
-    }
-    process.exit(active ? 0 : 1);
-  }
-  writePid(process.pid, actualPort);
-  const cleanup = () => {
-    removePid(process.pid);
-    runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
-  };
-  process.on('exit', cleanup);
-  process.on('SIGINT', () => { cleanup(); process.exit(0); });
-  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
-  // Windows console-close sends SIGBREAK; Node doesn't run exit handlers after
-  // a forceful TerminateProcess, but SIGBREAK does fire before the process is
-  // torn down, so we can still clean up here.
-  if (process.platform === 'win32') {
-    process.on('SIGBREAK', () => { cleanup(); process.exit(0); });
-  }
-
-  const url = `http://localhost:${actualPort}`;
-  if (actualPort !== port) {
-    console.log(`(Port ${port} was busy, using ${actualPort} instead)`);
-  }
-  console.log(`project-knowledge ${pkg.version}`);
-  console.log(`Listening at ${url}`);
-  // Resolve data dir the same way server.js will, so we can show the user
-  // where their config and KB files live BEFORE the server boots.
-  try {
-    console.log(`Data dir: ${getDataDir()}`);
-  } catch {}
-
-  require(path.join(__dirname, '..', '_site', 'server.js'));
-
-  if (shouldOpen) setTimeout(() => openBrowser(url), 500);
-}
-
-main().catch((err) => {
-  console.error(err.message);
-  removePid(process.pid);
-  runtimeEndpoint.clearEndpoint(DATA_DIR, { pid: process.pid });
-  process.exit(1);
+  const options = parse(process.argv.slice(2));
+  if (options.help) { help(); return; }
+  if (options.version) { console.log(pkg.version); return; }
+  if (options.forwarded) {
+    const args = options.command === 'integrations' ? (options.forwarded.length ? options.forwarded : ['status']) : [options.command, ...options.forwarded];
+    const result = spawnSync(process.execPath, [path.join(__dirname, 'project-knowledge-integrations.js'), ...args], { stdio: 'inherit', windowsHide: true });
+    process.exitCode = result.status ?? 1; return;
+  }
+  const dataDir = resolveDataDirPath({ dataDir: options.dataDir });
+  process.env.KB_DATA_DIR = dataDir;
+  if (options.all) {
+    const found = await instances.all();
+    if (!found.length) console.log('No controllable project-knowledge instances found.');
+    for (const info of found) show(info);
+    return;
+  }
+  const existing = options.command !== 'start' && options.portExplicit ? await instances.atPort(options.port) : await instances.current(dataDir);
+  const unverified = !existing && endpoint.readLiveEndpoint(dataDir, { removeStale: false });
+  if (unverified) throw new Error(`数据目录已有实例记录（PID ${unverified.pid}，端口 ${unverified.port}），但控制通道不可用。请先确认该实例，不会重复启动、误停止或报告已停止。`);
+  if (existing && options.dataDir && options.command !== 'start' && path.resolve(existing.dataDir).toLowerCase() !== dataDir.toLowerCase()) throw new Error('指定端口不属于指定数据目录，已拒绝控制。');
+  if (options.command === 'status') {
+    if (existing) show(existing);
+    else console.log(`project-knowledge is not running for ${dataDir}.\nUse "project-knowledge status --all" to inspect other data directories.`);
+    return;
+  }
+  if (options.command === 'stop') {
+    if (!existing) { console.log(`No background process found for ${dataDir}.`); return; }
+    await instances.stop(existing);
+    console.log(`project-knowledge stopped (PID ${existing.pid}) at ${instances.url(existing)}.\nData dir: ${existing.dataDir}`);
+    return;
+  }
+  if (existing) {
+    if (existing.status === 'stopping') throw new Error('实例正在停止，请稍后再启动。');
+    const url = instances.url(existing); console.log(`Already running (PID ${existing.pid}) at ${url}\nData dir: ${existing.dataDir}`);
+    notify({ type: 'kb:launcher-ready', url }); if (options.open) openBrowser(url); return;
+  }
+  // A live claim with no control channel is starting, legacy, or unverified.
+  // Never trust a reused/shared PID as proof or kill it to make room.
+  if (!options.foreground) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const log = path.join(dataDir, 'launcher.log'), fd = fs.openSync(log, 'a');
+    const child = spawn(process.execPath, [...process.argv.slice(1), '--fg'], { detached: true, stdio: ['ignore', fd, fd, 'ipc'], windowsHide: true });
+    fs.closeSync(fd); child.unref();
+    console.log(`project-knowledge starting in background\nDiagnostics: ${log}`);
+    const ready = await waitForStartup(child, log);
+    console.log(`project-knowledge is ready at ${ready.url}\nUse "project-knowledge status" to check, "project-knowledge stop" to stop.`);
+    return;
+  }
+  const port = options.portExplicit ? options.port : await freePort(options.port, options.host);
+  process.env.KB_SITE_HOST = options.host; process.env.KB_SITE_PORT = String(port);
+  console.log(`project-knowledge ${pkg.version}\nData dir: ${dataDir}`);
+  if (port !== options.port) console.log(`(Port ${options.port} was busy, using ${port} instead)`);
+  const { startServer, installProcessHandlers } = require('../_site/lib/server-app');
+  const promise = startServer(); installProcessHandlers(promise);
+  const instance = await promise;
+  if (process.platform === 'win32') process.once('SIGBREAK', () => instance.stop('SIGBREAK'));
+  const url = instances.url({ host: options.host, port });
+  console.log(`Listening at ${url}`); notify({ type: 'kb:launcher-ready', url });
+  if (options.open) setTimeout(() => openBrowser(url), 500);
+}
+main().catch(error => {
+  const control = ['stop', 'status'].includes(process.argv[2]?.toLowerCase());
+  console.error(process.argv.includes('--fg') ? `[project-knowledge] startup failed: ${error.message}` : `${control ? '控制失败' : '启动失败'}：${error.message}`);
+  notify({ type: 'kb:launcher-failed', message: error.message });
+  process.exitCode = 1;
 });

package/docs/fresh-v5-start.md

@@ -13,6 +13,8 @@ project-knowledge
 
 需要 Node ≥22 和 Git。默认使用 `~/.project-knowledge-v5`，四模块的托管数据也在此目录内。若环境变量 `KB_DATA_DIR` 仍指向旧目录，请取消该设置或改为新的空目录。不要把旧 `projects.json`、设置或引擎状态复制进新目录。
 
+5.0.6 修复首次启动被未登记的旧工作台会话误拦截：仅有日志、默认提示词及孤立会话的目录可以创建空的新登记，孤立会话保留原字节但不会恢复或触发任务。实际旧项目、设置、引擎状态或维护任务仍拒绝迁移，错误列出具体目录和冲突项。后台启动命令等待 HTTP 就绪后才报成功；启动失败直接在终端显示原因并返回非零退出码，不提前打开浏览器。
+
 在“系统状态”重新配置模型与后台默认模型、embedding 和知识根目录，然后在“领域与项目”导入代码目录及新的空知识目录。原代码目录无需移动。若残留旧知识库托管 Hook，导入预检会要求明确确认替换；不会覆盖第三方 Hook。导入建立 HEAD 基线，不分析已有历史。
 
 如果模块是自己独立启动的旧进程，请在它原来的终端中停止后重启新版外壳。外壳不会擅自杀死其他服务；版本或运行期鉴权不一致时显示具体连接阶段，不接管旧服务数据。
@@ -25,6 +27,12 @@ project-knowledge
 
 ## 解绑与恢复
 
+5.0.7 的命令不区分大小写，`STOP` 与 `stop` 相同。未知命令不会误启动。
+`status` 和 `stop` 默认只控制当前数据目录；`status --all` 查看可控制的本机实例，
+`stop --port 5804` 指定停止目标，`--data "D:/data/knowledge"` 明确选择数据目录。
+停止通过本机控制通道等待外壳及其托管模块退出，不再使用共享临时 PID 或盲杀。
+未验证或正在启动的实例不会误报已停止，独立启动的模块也不会被结束。
+
 “解绑并保留数据”从项目列表移除登记、取消未开始任务并卸下本项目托管 Hook，保留代码、知识、会话及证据。实际分析或索引写入尚未结束时仍禁止解绑，防止丢失写入状态。队列本身不再被当成正在运行。
 
 删除的是旧版本兼容路径，不是新版的故障恢复能力：v5 自身的重启恢复、提交去重、并发限制、失败重试和索引修复仍有效。`upgrade-recovery` 不再存在。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.5",
+  "version": "5.0.7",
   "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.5",
+  "version": "5.0.7",
   "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.5",
+  "version": "5.0.7",
   "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.5",
+        "@sanqianx/project-knowledge@5.0.7",
         "project-knowledge-mcp"
       ]
     }