@sanqianx/project-knowledge 5.0.17 → 5.0.18-rc.1

package/_site/_test/integration-auto-repair-test.js

@@ -0,0 +1,92 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { markIntent } = require('../lib/integration-intent');
+const { IntegrationAutoRepair } = require('../lib/integration-auto-repair');
+
+const tmpDataDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'kb-auto-repair-'));
+
+const makeManager = ({ statusClients, onInstall }) => {
+  const calls = { statusAll: 0, installAll: [] };
+  return {
+    calls,
+    async statusAll() {
+      calls.statusAll += 1;
+      return { clients: statusClients.map(client => ({ ...client, developmentCapture: { ...client.developmentCapture } })) };
+    },
+    async installAll(options) {
+      calls.installAll.push(options);
+      return onInstall(options);
+    },
+  };
+};
+
+(async () => {
+  // D + E: runOnce repairs exactly the connected-and-not-installed clients, once.
+  {
+    const dir = tmpDataDir();
+    markIntent(dir, 'claude', 'connected');
+    markIntent(dir, 'codex', 'disconnected');
+    markIntent(dir, 'zcode', 'connected');
+    const manager = makeManager({
+      statusClients: [
+        { client: 'claude', developmentCapture: { installed: false } },
+        { client: 'codex', developmentCapture: { installed: false } },
+        { client: 'zcode', developmentCapture: { installed: true } },
+      ],
+      onInstall: async options => ({ clients: [{ client: options.clients[0], developmentCapture: { ok: true } }] }),
+    });
+    const repair = new IntegrationAutoRepair({ dataDir: dir, createManager: () => manager });
+    await repair.runOnce();
+    assert.equal(manager.calls.installAll.length, 1, 'disconnected and already-installed clients are never repaired');
+    assert.deepEqual(manager.calls.installAll[0], { clients: ['claude'] });
+    const repaired = repair.status().claude;
+    assert.equal(repaired.state, 'repaired');
+    assert.equal(repaired.error, null);
+    assert.ok(!Number.isNaN(Date.parse(repaired.at)), 'at must be an ISO timestamp');
+    await repair.runOnce();
+    assert.equal(manager.calls.statusAll, 2, 'second run rescans status');
+    assert.equal(manager.calls.installAll.length, 1, 'a second runOnce must not repair the same client again');
+  }
+  // F + G: failures are recorded without interrupting others; retry repairs.
+  {
+    const dir = tmpDataDir();
+    for (const client of ['claude', 'codex', 'zcode']) markIntent(dir, client, 'connected');
+    let claudeBroken = true;
+    const manager = makeManager({
+      statusClients: [
+        { client: 'claude', developmentCapture: { installed: false } },
+        { client: 'codex', developmentCapture: { installed: false } },
+        { client: 'zcode', developmentCapture: { installed: false } },
+      ],
+      onInstall: async options => {
+        const client = options.clients[0];
+        if (client === 'claude' && claudeBroken) throw new Error('boom');
+        if (client === 'zcode') return { clients: [{ client, developmentCapture: { ok: false, detail: 'hook conflict' } }] };
+        return { clients: [{ client, developmentCapture: { ok: true } }] };
+      },
+    });
+    const repair = new IntegrationAutoRepair({ dataDir: dir, createManager: () => manager });
+    await repair.runOnce();
+    assert.equal(manager.calls.installAll.length, 3, 'every connected-and-not-installed client gets one attempt');
+    const status = repair.status();
+    assert.equal(status.claude.state, 'failed');
+    assert.ok(status.claude.error, 'a thrown installAll records the error message');
+    assert.equal(status.codex.state, 'repaired', 'a failing client does not interrupt the others');
+    assert.equal(status.zcode.state, 'failed');
+    assert.ok(status.zcode.error, 'ok=false records a detail as the error');
+    claudeBroken = false;
+    const retried = await repair.retry('claude');
+    assert.equal(retried.state, 'repaired');
+    assert.equal(retried.error, null);
+    assert.equal(manager.calls.installAll.length, 4, 'retry ignores the attempted set');
+    assert.deepEqual(manager.calls.installAll[3], { clients: ['claude'] });
+    assert.equal(repair.status().claude.state, 'repaired', 'a successful retry overwrites the failure');
+    const snapshot = repair.status();
+    snapshot.claude = { state: 'tampered' };
+    assert.equal(repair.status().claude.state, 'repaired', 'status() returns a copy');
+  }
+  console.log('integration auto repair test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/integration-intent-test.js

@@ -0,0 +1,63 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { SCHEMA, readIntent, markIntent, bootstrapIntent, summarizeClient } = require('../lib/integration-intent');
+
+const tmpDataDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'kb-intent-'));
+const intentPath = dataDir => path.join(dataDir, 'integration-intent.json');
+
+// A: markIntent merges atomically and readIntent round-trips.
+{
+  const dir = tmpDataDir();
+  const first = markIntent(dir, 'claude', 'connected');
+  assert.deepEqual(first, { schema: SCHEMA, clients: { claude: 'connected' } });
+  const second = markIntent(dir, 'codex', 'disconnected');
+  assert.deepEqual(second, { schema: SCHEMA, clients: { claude: 'connected', codex: 'disconnected' } });
+  assert.deepEqual(readIntent(dir), { schema: SCHEMA, clients: { claude: 'connected', codex: 'disconnected' } });
+  assert.deepEqual(fs.readdirSync(dir), ['integration-intent.json'], 'atomic write must not leave temp files behind');
+  assert.throws(() => markIntent(dir, 'claude', 'sometimes'), 'invalid states must throw');
+  assert.equal(readIntent(tmpDataDir()), null, 'missing file reads as null');
+  const corrupt = tmpDataDir();
+  fs.writeFileSync(intentPath(corrupt), '{ not json');
+  assert.equal(readIntent(corrupt), null, 'corrupt file reads as null');
+  const foreign = tmpDataDir();
+  fs.writeFileSync(intentPath(foreign), JSON.stringify({ schema: 'someone-else/v9', clients: { claude: 'connected' } }));
+  assert.equal(readIntent(foreign), null, 'schema mismatch reads as null');
+  const unknown = tmpDataDir();
+  fs.writeFileSync(intentPath(unknown), JSON.stringify({ schema: SCHEMA, clients: { claude: 'connected', codex: 'weird-state' } }));
+  assert.deepEqual(readIntent(unknown), { schema: SCHEMA, clients: { claude: 'connected' } }, 'unknown client values are dropped');
+}
+// B: bootstrapIntent only fills gaps and never rewrites decisions.
+{
+  const dir = tmpDataDir();
+  markIntent(dir, 'claude', 'disconnected');
+  const clientsStatus = [
+    { client: 'claude', developmentCapture: { installed: true } },
+    { client: 'codex', developmentCapture: { installed: true } },
+    { client: 'zcode', developmentCapture: { installed: false } },
+  ];
+  const bootstrapped = bootstrapIntent(dir, clientsStatus);
+  assert.deepEqual(bootstrapped, { schema: SCHEMA, clients: { claude: 'disconnected', codex: 'connected', zcode: 'disconnected' } }, 'existing entries are never overwritten');
+  const before = fs.statSync(intentPath(dir)).mtimeMs;
+  bootstrapIntent(dir, clientsStatus);
+  assert.equal(fs.statSync(intentPath(dir)).mtimeMs, before, 'no-change bootstrap must not rewrite the file');
+  const fresh = tmpDataDir();
+  const created = bootstrapIntent(fresh, [{ client: 'codex', developmentCapture: { installed: false } }]);
+  assert.deepEqual(created, { schema: SCHEMA, clients: { codex: 'disconnected' } });
+  assert.deepEqual(readIntent(fresh), created, 'bootstrap creates the file when missing');
+}
+// C: summarizeClient covers all five states plus precedence rules.
+{
+  const failedRepair = { claude: { state: 'failed', at: new Date().toISOString(), error: 'boom' } };
+  assert.equal(summarizeClient({ client: 'claude', available: true, developmentCapture: { state: 'checking' } }, null), 'checking');
+  assert.equal(summarizeClient({ client: 'claude', available: true, developmentCapture: {}, knowledgeIntegration: { state: 'checking' } }, null), 'checking');
+  assert.equal(summarizeClient({ client: 'claude', available: false, developmentCapture: { state: 'checking' } }, null), 'checking', 'checking wins over not-detected');
+  assert.equal(summarizeClient({ client: 'claude', available: false, configFound: false, developmentCapture: {} }, null), 'not-detected');
+  assert.equal(summarizeClient({ client: 'claude', available: false, configFound: true, developmentCapture: {} }, null), 'disconnected', 'configFound alone counts as detected');
+  assert.equal(summarizeClient({ client: 'claude', available: true, developmentCapture: { installed: true } }, failedRepair), 'connected', 'installed outranks a failed repair');
+  assert.equal(summarizeClient({ client: 'claude', available: true, developmentCapture: {} }, failedRepair), 'error');
+  assert.equal(summarizeClient({ client: 'claude', available: true, developmentCapture: {} }, null), 'disconnected');
+}
+console.log('integration intent test PASS');

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

@@ -50,7 +50,9 @@ async function main() {
   const stub = http.createServer((req, res) => {
     const url = new URL(req.url, 'http://localhost');
     hits.push(`${req.method} ${url.pathname}${url.search}`);
-    if (url.pathname === '/api/health') { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ ok: true })); return; }
+    // Real console health carries registeredProjects; the identity check
+    // rejects generic {"ok":true} bodies from foreign port squatters.
+    if (url.pathname === '/api/health') { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ ok: true, registeredProjects: registered.length })); return; }
     if (url.pathname === '/api/echo') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ echo: `${req.method} ${url.pathname}`, query: Object.fromEntries(url.searchParams) }));

package/_site/_test/module-dynamic-port-test.js

@@ -0,0 +1,118 @@
+'use strict';
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { resolveModuleUrl } = require('../lib/module-port-resolver');
+const { ModuleBridge } = require('../lib/module-bridge');
+
+const countingProbe = outcome => {
+  const seen = [];
+  return {
+    probe: async url => { seen.push(url); return outcome; },
+    get seen() { return seen; },
+    get calls() { return seen.length; },
+  };
+};
+
+const countingPortFree = isFree => {
+  const seen = [];
+  return {
+    portFree: async port => { seen.push(port); return isFree(port); },
+    get seen() { return seen; },
+    get calls() { return seen.length; },
+  };
+};
+
+(async () => {
+  // A: healthy module on the preferred port is reused without any port scan.
+  {
+    const probe = countingProbe('module');
+    const portFree = countingPortFree(() => false);
+    const resolved = await resolveModuleUrl({ kind: 'terminal', preferredUrl: 'http://127.0.0.1:5760', explicit: false, portFree: portFree.portFree, probe: probe.probe });
+    assert.equal(resolved.source, 'reused');
+    assert.equal(resolved.url, 'http://127.0.0.1:5760');
+    assert.equal(resolved.port, 5760);
+    assert.deepEqual(probe.seen, ['http://127.0.0.1:5760']);
+    assert.equal(portFree.calls, 0, 'reuse must never invoke portFree');
+  }
+  // B: foreign occupant on the preferred port moves the module to the next free port.
+  {
+    const probe = countingProbe('foreign');
+    const portFree = countingPortFree(port => port === 5761);
+    const resolved = await resolveModuleUrl({ kind: 'terminal', preferredUrl: 'http://127.0.0.1:5760', explicit: false, portFree: portFree.portFree, probe: probe.probe });
+    assert.equal(resolved.source, 'dynamic');
+    assert.equal(resolved.url, 'http://127.0.0.1:5761');
+    assert.equal(resolved.port, 5761);
+    assert.equal(resolved.offset, 1);
+    assert.deepEqual(portFree.seen, [5760, 5761]);
+  }
+  // C: unreachable preferred port skips three busy ports before picking the fourth.
+  {
+    const probe = countingProbe('unreachable');
+    const portFree = countingPortFree(port => port === 8790);
+    const resolved = await resolveModuleUrl({ kind: 'vector-hub', preferredUrl: 'http://127.0.0.1:8787', explicit: false, portFree: portFree.portFree, probe: probe.probe });
+    assert.equal(resolved.source, 'dynamic');
+    assert.equal(resolved.url, 'http://127.0.0.1:8790');
+    assert.equal(resolved.port, 8790);
+    assert.equal(resolved.offset, 3);
+    assert.deepEqual(portFree.seen, [8787, 8788, 8789, 8790]);
+  }
+  // D: exhausted scan range fails loudly with kind and port span in the message.
+  {
+    const probe = countingProbe('unreachable');
+    const portFree = countingPortFree(() => false);
+    await assert.rejects(
+      () => resolveModuleUrl({ kind: 'event-bridge', preferredUrl: 'http://127.0.0.1:8790', explicit: false, portFree: portFree.portFree, probe: probe.probe }),
+      error => {
+        assert.equal(error.code, 'NO_FREE_MODULE_PORT');
+        assert.ok(error.message.includes('event-bridge'), `message must name the module kind: ${error.message}`);
+        assert.ok(error.message.includes('8790'), `message must name the first scanned port: ${error.message}`);
+        assert.ok(error.message.includes('8809'), `message must name the last scanned port: ${error.message}`);
+        return true;
+      },
+    );
+    assert.equal(portFree.calls, 20, 'default scanRange must probe 20 consecutive ports before failing');
+    assert.deepEqual(portFree.seen, Array.from({ length: 20 }, (_, index) => 8790 + index));
+  }
+  // E: an explicit external URL short-circuits before any probe or port scan.
+  {
+    const probe = countingProbe('module');
+    const portFree = countingPortFree(() => true);
+    const resolved = await resolveModuleUrl({ kind: 'knowledge-engine', preferredUrl: 'http://192.168.1.5:5790', explicit: true, portFree: portFree.portFree, probe: probe.probe });
+    assert.equal(resolved.source, 'external');
+    assert.equal(resolved.url, 'http://192.168.1.5:5790');
+    assert.equal(probe.calls, 0, 'explicit external URL must never be probed');
+    assert.equal(portFree.calls, 0, 'explicit external URL must never trigger a port scan');
+  }
+  // F: a preferred URL without an explicit port is rejected.
+  {
+    const probe = countingProbe('module');
+    const portFree = countingPortFree(() => true);
+    await assert.rejects(
+      () => resolveModuleUrl({ kind: 'terminal', preferredUrl: 'http://127.0.0.1', explicit: false, portFree: portFree.portFree, probe: probe.probe }),
+      error => { assert.equal(error.code, 'INVALID_MODULE_URL'); return true; },
+    );
+  }
+  // G (integration): an HTTP service squatting on the preferred port with
+  // 404 responses — exactly what happens when the shell's own fallback range
+  // 5757..5776 lands on the terminal default 5760 — must not be misread as a
+  // module and must not crash-loop: the bridge moves to the next free port.
+  {
+    const squatter = http.createServer((req, res) => { res.writeHead(404, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'not found' })); });
+    await new Promise(resolve => squatter.listen(0, '127.0.0.1', resolve));
+    const squatterPort = squatter.address().port;
+    const bridge = new ModuleBridge();
+    // Isolate the terminal leg: everything else is explicit/external so the
+    // resolution loop only probes the squatter port for the terminal kind.
+    bridge.terminalUrl = `http://127.0.0.1:${squatterPort}`;
+    bridge.explicitModuleUrls = { terminal: false, vectorHub: true, eventBridge: true, engine: true };
+    try {
+      await bridge._resolveManagedUrls();
+      assert.equal(bridge.moduleUrlSources.terminal, 'dynamic', '404 squatter must force a dynamic move, never reuse');
+      assert.equal(bridge.terminalUrl, `http://127.0.0.1:${squatterPort + 1}`, 'module moves to the port right after the squatter');
+    } finally {
+      squatter.closeAllConnections?.();
+      await new Promise(resolve => squatter.close(resolve));
+    }
+  }
+  console.log('module dynamic port test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/non-release-ci-test.js

@@ -8,7 +8,7 @@ const workflow = fs.readFileSync(workflowPath, 'utf8');
 
 assert.match(workflow, /^\s*push:/m, 'non-release CI must run for branch pushes');
 assert.match(workflow, /^\s*pull_request:/m, 'non-release CI must run for pull requests');
-assert.match(workflow, /node:\s*\['18\.x', '24\.x'\]/, 'Linux CI must cover Node 18 and 24');
+assert.match(workflow, /node:\s*\['22\.x', '24\.x'\]/, 'Linux CI must cover the declared Node >=22 contract (oldest supported 22.x plus current 24.x)');
 assert.match(workflow, /runs-on:\s*windows-latest/, 'CI must include a Windows job');
 assert.match(workflow, /npm test -- --no-report/, 'CI must run the core regression suite');
 assert.match(workflow, /npm pack --dry-run --json/, 'CI must audit the npm package contents');

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

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

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

@@ -1,68 +1,75 @@
-'use strict';
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ModuleBridge } = require('../lib/module-bridge');
-const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
-const root = path.resolve('D:/knowledge storage 中文');
-const layout = new StorageLayout({ dataDir: path.resolve('D:/metadata') });
-assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: root } }), path.join(root, '.indexes'));
-assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: '' } }), path.join(layout.getDataDir(), 'vectorhub'));
-const settingsStore = { read: () => ({ knowledge: { rootPath: root }, brain: { id: 'brain-default', domains: [] } }) };
-let knowledgeRoot = root;
-const tools = new KnowledgeToolRuntime({
-  layout,
-  settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot } }) },
-  registryStore: { listIds: () => ['project-storage'] },
-  projectStore: {
-    readConfig: () => ({ displayName: 'Storage', repoPath: path.join(root, 'repo'), knowledgePath: path.join(root, 'project') }),
-    readState: () => ({ index: { generation: 3 } }),
-  },
-});
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(root, '.indexes'), 'MCP/CLI resolution must report the vector-hub location, not the retired shell database');
-knowledgeRoot = path.join(root, 'changed root');
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(knowledgeRoot, '.indexes'), 'a running MCP process must reread the selected knowledge root');
-knowledgeRoot = '';
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(layout.getDataDir(), 'vectorhub'));
-const bridge = new ModuleBridge({ settingsStore, dataDir: layout.getDataDir() });
-const spec = bridge._supervisedSpecs().find(spec => spec.name === 'vector-hub');
-assert.equal(spec.env.VECTOR_HUB_ROOT, path.join(root, '.indexes'));
-assert.equal(spec.env.VECTOR_HUB_CONFIG, path.join(layout.getDataDir(), 'vectorhub', 'config.json'));
-const calls = [];
-bridge._fetch = async (url, init) => { const body = JSON.parse(init.body); calls.push({ url, body }); return { ok: true, json: async () => url.includes('/api/internal/runtime-config') ? { ok: true, rootPath: path.join(root, '.indexes') } : {} }; };
-bridge.syncEngineConfiguration().then(async status => {
-  assert.equal(calls.find(call => call.url.includes('/api/internal/runtime-config')).body.storageRoot, path.join(root, '.indexes'));
-  assert.equal(status.indexStorage.status, 'ready');
-  let currentRoot = root, release, started;
-  const entered = new Promise(resolve => { started = resolve; });
-  const held = new Promise(resolve => { release = resolve; });
-  const queued = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => ({ knowledge: { rootPath: currentRoot }, brain: { id: 'brain-default', domains: [] } }) } });
-  const applied = [];
-  queued._fetch = async (url, init) => {
-    const body = JSON.parse(init.body);
-    if (url.endsWith('/api/internal/runtime-config')) {
-      applied.push(body.storageRoot);
-      if (applied.length === 1) { started(); await held; }
-      return { ok: true, json: async () => ({ rootPath: body.storageRoot }) };
-    }
-    return { ok: true, json: async () => null };
-  };
-  const first = queued.syncEngineConfiguration(); await entered;
-  currentRoot = path.join(root, 'new root');
-  const second = queued.syncEngineConfiguration(); release();
-  await first;
-  const latest = await second;
-  assert.deepEqual(applied, [path.join(root, '.indexes'), path.join(currentRoot, '.indexes')]);
-  assert.equal(latest.indexStorage.actualPath, path.join(currentRoot, '.indexes'));
-  assert.equal(latest.indexStorage.status, 'ready');
-  const broken = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => { throw new Error('corrupt settings'); } } });
-  let revoked;
-  broken._fetch = async (url, init) => {
-    if (url.endsWith('/api/internal/runtime-config')) revoked = JSON.parse(init.body);
-    return { ok: false };
-  };
-  const unavailable = await broken.syncEngineConfiguration();
-  assert.deepEqual(revoked, { settings: null });
-  assert.equal(unavailable.indexStorage.status, 'pending');
-  console.log('vector-storage-root-test PASS');
-}).catch(error => { console.error(error); process.exitCode = 1; });
+'use strict';
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ModuleBridge } = require('../lib/module-bridge');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+const root = path.resolve('D:/knowledge storage 中文');
+const layout = new StorageLayout({ dataDir: path.resolve('D:/metadata') });
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: root } }), path.join(root, '.indexes'));
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: '' } }), path.join(layout.getDataDir(), 'vectorhub'));
+const settingsStore = { read: () => ({ knowledge: { rootPath: root }, brain: { id: 'brain-default', domains: [] } }) };
+let knowledgeRoot = root;
+const tools = new KnowledgeToolRuntime({
+  layout,
+  settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot } }) },
+  registryStore: { listIds: () => ['project-storage'] },
+  projectStore: {
+    readConfig: () => ({ displayName: 'Storage', repoPath: path.join(root, 'repo'), knowledgePath: path.join(root, 'project') }),
+    readState: () => ({ index: { generation: 3 } }),
+  },
+});
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(root, '.indexes'), 'MCP/CLI resolution must report the vector-hub location, not the retired shell database');
+knowledgeRoot = path.join(root, 'changed root');
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(knowledgeRoot, '.indexes'), 'a running MCP process must reread the selected knowledge root');
+knowledgeRoot = '';
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(layout.getDataDir(), 'vectorhub'));
+const bridge = new ModuleBridge({ settingsStore, dataDir: layout.getDataDir() });
+// The supervisor refuses to spawn the vendored vector-hub on Node < 22
+// (module-bridge: "vector-hub declares engines >= 22"), so its supervised
+// spec — and these env assertions — only exist on qualifying runtimes.
+const vectorHubSpec = bridge._supervisedSpecs().find(spec => spec.name === 'vector-hub');
+if (parseInt(process.versions.node, 10) >= 22) {
+  assert.equal(vectorHubSpec.env.VECTOR_HUB_ROOT, path.join(root, '.indexes'));
+  assert.equal(vectorHubSpec.env.VECTOR_HUB_CONFIG, path.join(layout.getDataDir(), 'vectorhub', 'config.json'));
+} else {
+  assert.equal(vectorHubSpec, undefined, 'vector-hub must not be supervised on Node < 22');
+}
+const calls = [];
+bridge._fetch = async (url, init) => { const body = JSON.parse(init.body); calls.push({ url, body }); return { ok: true, json: async () => url.includes('/api/internal/runtime-config') ? { ok: true, rootPath: path.join(root, '.indexes') } : {} }; };
+bridge.syncEngineConfiguration().then(async status => {
+  assert.equal(calls.find(call => call.url.includes('/api/internal/runtime-config')).body.storageRoot, path.join(root, '.indexes'));
+  assert.equal(status.indexStorage.status, 'ready');
+  let currentRoot = root, release, started;
+  const entered = new Promise(resolve => { started = resolve; });
+  const held = new Promise(resolve => { release = resolve; });
+  const queued = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => ({ knowledge: { rootPath: currentRoot }, brain: { id: 'brain-default', domains: [] } }) } });
+  const applied = [];
+  queued._fetch = async (url, init) => {
+    const body = JSON.parse(init.body);
+    if (url.endsWith('/api/internal/runtime-config')) {
+      applied.push(body.storageRoot);
+      if (applied.length === 1) { started(); await held; }
+      return { ok: true, json: async () => ({ rootPath: body.storageRoot }) };
+    }
+    return { ok: true, json: async () => null };
+  };
+  const first = queued.syncEngineConfiguration(); await entered;
+  currentRoot = path.join(root, 'new root');
+  const second = queued.syncEngineConfiguration(); release();
+  await first;
+  const latest = await second;
+  assert.deepEqual(applied, [path.join(root, '.indexes'), path.join(currentRoot, '.indexes')]);
+  assert.equal(latest.indexStorage.actualPath, path.join(currentRoot, '.indexes'));
+  assert.equal(latest.indexStorage.status, 'ready');
+  const broken = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => { throw new Error('corrupt settings'); } } });
+  let revoked;
+  broken._fetch = async (url, init) => {
+    if (url.endsWith('/api/internal/runtime-config')) revoked = JSON.parse(init.body);
+    return { ok: false };
+  };
+  const unavailable = await broken.syncEngineConfiguration();
+  assert.deepEqual(revoked, { settings: null });
+  assert.equal(unavailable.indexStorage.status, 'pending');
+  console.log('vector-storage-root-test PASS');
+}).catch(error => { console.error(error); process.exitCode = 1; });