@sanqianx/project-knowledge 5.0.20 → 5.0.22

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

@@ -0,0 +1,43 @@
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { StartupIntegrationRepair } = require('../lib/startup-integration-repair');
+const { markIntent } = require('../lib/integration-intent');
+const { isProcessAlive } = require('../lib/runtime-endpoint');
+const workerFile = path.join(__dirname, 'fixtures/startup-repair-worker.cjs');
+async function main() {
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-startup-repair-empty-'));
+  markIntent(empty, 'codex', 'disconnected');
+  const idle = new StartupIntegrationRepair({ dataDir: empty, workerFile: 'does-not-exist' });
+  assert.deepEqual(await idle.runOnce(), {}); assert.equal(idle.child, null); await idle.close();
+  for (const mode of ['normal', 'manual', 'crash', 'hang']) {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-startup-repair-'));
+    markIntent(dataDir, 'claude', 'connected'); markIntent(dataDir, 'codex', 'connected');
+    markIntent(dataDir, 'zcode', 'disconnected');
+    const logs = [];
+    const repair = new StartupIntegrationRepair({ dataDir, managerOptions: { homeDir: mode }, workerFile,
+      timeoutMs: mode === 'hang' ? 150 : 3000, logger: { warn: (...args) => logs.push(args) } });
+    try {
+      const result = repair.runOnce();
+      assert.equal(repair.runOnce(), result, 'one startup event must not spawn duplicate repair jobs');
+      if (mode === 'manual') repair.markSucceeded(['claude']);
+      const status = await result;
+      assert.equal(status.zcode, undefined, 'disconnected clients must not acquire repair state');
+      if (mode === 'normal') {
+        assert.equal(status.claude.state, 'failed'); assert.equal(status.codex.state, 'repaired');
+        repair.markSucceeded(['claude']); assert.equal(repair.status().claude.state, 'repaired');
+      } else if (mode === 'manual') {
+        assert.equal(status.claude, undefined, 'late startup failure must not overwrite a manual install');
+        assert.equal(status.codex.state, 'repaired');
+      } else {
+        assert.equal(status.claude.state, 'failed'); assert.equal(status.codex.state, 'failed');
+        assert.equal(logs.length, 1, 'worker failure must be reported without automatic retries');
+      }
+    } finally { await repair.close(); }
+    assert.equal(isProcessAlive(repair.child.pid), false, 'owned worker must be reaped on close');
+  }
+  console.log('Startup repair worker PASS: intent isolation, one attempt, manual success precedence, timeout, crash and owned cleanup');
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/workspace-ui-contract-test.js

@@ -1,31 +1,31 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const root = path.resolve(__dirname, '../..');
-const html = fs.readFileSync(path.join(root, 'ui/index.html'), 'utf8');
-const script = fs.readFileSync(path.join(root, 'ui/product.js'), 'utf8');
-const css = fs.readFileSync(path.join(root, 'ui/product.css'), 'utf8');
-for (const view of ['home', 'work', 'search', 'memory', 'projects', 'activity']) {
-  assert.equal((html.match(new RegExp(`data-view="${view}"`, 'g')) || []).length, 1);
-  assert.ok(html.includes(`id="view-${view}"`));
-}
-assert.equal((html.match(/data-view=/g) || []).length, 6, 'diagnostics must not become another primary product');
-assert.match(html, /<select\b[^>]*id="projectSelect"[^>]*\bdisabled\b/, 'project selection is disabled until the initial registry snapshot has loaded');
-for (const id of ['workFrame', 'vectorFrame', 'bridgeFrame', 'engineFrame', 'importDialog', 'importCode', 'importKnowledge', 'importDomain', 'setupImportRoot', 'createDomain', 'logsDialog', 'systemDrawer', 'copyReference']) assert.equal((html.match(new RegExp(`id="${id}"`, 'g')) || []).length, 1);
-assert.ok(html.includes('data-action="import"') && html.includes('不分析全部历史'));
-assert.ok(!html.includes('srcdoc') && !/data-simulate|data-analyze|data-install-hook/.test(html));
-assert.equal((script.match(/\.src = /g) || []).length, 1, 'frames initialize once, not on project/theme/page changes');
-for (const contract of ['kb:theme', 'kb:select-project', 'kb:scope', 'kb:knowledge', 'kb:ready']) assert.ok(script.includes(contract));
-assert.ok(script.includes('event.origin !== location.origin') && script.includes('contentWindow === event.source'), 'module messages must be from the expected frame and origin');
-assert.ok(script.includes('state.epoch++') && script.includes('referenceEpoch') && script.includes('logEpoch'), 'late project/reference/log feedback must be isolated');
-assert.match(script, /on\('domainForm'[\s\S]*?await refreshRegistry\(true\)/, 'domain writes must invalidate pre-mutation reads');
-assert.match(script, /registered = true;[\s\S]*?await refreshRegistry\(true\)/, 'import must not reuse a pre-import snapshot');
-assert.ok(script.includes('esc(r.title)') && script.includes('esc(m.text)') && script.includes('esc(project.name)'));
-assert.ok(script.includes('text.textContent = record.message') && script.includes("'logs/appended'"), 'diagnostics stay inert and stream live');
-assert.ok(script.includes('URL.revokeObjectURL(url)') && script.includes('logStream?.close()'));
-assert.ok(script.includes('resumeImport = true') && script.includes("$('importDialog').showModal()") && script.includes("p.code === 'KNOWLEDGE_ROOT_MISSING'"), 'first import can return from setup without resetting its input');
-assert.ok(css.includes('height:100%') && css.includes('.view.module-view{padding:0;overflow:hidden}') && css.includes('overflow-wrap:anywhere'));
-assert.ok(css.includes('html[data-theme=dark]') && css.includes('prefers-reduced-motion'));
-assert.doesNotThrow(() => new Function(script));
-console.log('workspace UI contract test PASS (source contract; not browser acceptance)');
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const root = path.resolve(__dirname, '../..');
+const html = fs.readFileSync(path.join(root, 'ui/index.html'), 'utf8');
+const script = fs.readFileSync(path.join(root, 'ui/product.js'), 'utf8');
+const css = fs.readFileSync(path.join(root, 'ui/product.css'), 'utf8');
+for (const view of ['home', 'work', 'search', 'memory', 'projects', 'activity']) {
+  assert.equal((html.match(new RegExp(`data-view="${view}"`, 'g')) || []).length, 1);
+  assert.ok(html.includes(`id="view-${view}"`));
+}
+assert.equal((html.match(/data-view=/g) || []).length, 6, 'diagnostics must not become another primary product');
+assert.match(html, /<select\b[^>]*id="projectSelect"[^>]*\bdisabled\b/, 'project selection is disabled until the initial registry snapshot has loaded');
+for (const id of ['workFrame', 'vectorFrame', 'bridgeFrame', 'engineFrame', 'importDialog', 'importCode', 'importKnowledge', 'importDomain', 'setupImportRoot', 'createDomain', 'logsDialog', 'systemDrawer', 'copyReference']) assert.equal((html.match(new RegExp(`id="${id}"`, 'g')) || []).length, 1);
+assert.ok(html.includes('data-action="import"') && html.includes('不分析全部历史'));
+assert.ok(!html.includes('srcdoc') && !/data-simulate|data-analyze|data-install-hook/.test(html));
+assert.equal((script.match(/\.src = /g) || []).length, 1, 'frames initialize once, not on project/theme/page changes');
+for (const contract of ['kb:theme', 'kb:select-project', 'kb:scope', 'kb:knowledge', 'kb:ready']) assert.ok(script.includes(contract));
+assert.ok(script.includes('event.origin !== location.origin') && script.includes('contentWindow === event.source'), 'module messages must be from the expected frame and origin');
+assert.ok(script.includes('state.epoch++') && script.includes('referenceEpoch') && script.includes('logEpoch'), 'late project/reference/log feedback must be isolated');
+assert.match(script, /on\('domainForm'[\s\S]*?await refreshRegistry\(true\)/, 'domain writes must invalidate pre-mutation reads');
+assert.match(script, /registered = true;[\s\S]*?await refreshRegistry\(true\)/, 'import must not reuse a pre-import snapshot');
+assert.ok(script.includes("title: String(r.title || r.entryId || '')") && script.includes('esc(m.text)') && script.includes('esc(project.name)'));
+assert.ok(script.includes('text.textContent = record.message') && script.includes("'logs/appended'"), 'diagnostics stay inert and stream live');
+assert.ok(script.includes('URL.revokeObjectURL(url)') && script.includes('logStream?.close()'));
+assert.ok(script.includes('resumeImport = true') && script.includes("$('importDialog').showModal()") && script.includes("p.code === 'KNOWLEDGE_ROOT_MISSING'"), 'first import can return from setup without resetting its input');
+assert.ok(css.includes('height:100%') && css.includes('.view.module-view{padding:0;overflow:hidden}') && css.includes('overflow-wrap:anywhere'));
+assert.ok(css.includes('html[data-theme=dark]') && css.includes('prefers-reduced-motion'));
+assert.doesNotThrow(() => new Function(script));
+console.log('workspace UI contract test PASS (source contract; not browser acceptance)');

package/_site/_test/zcode-capture-integration-test.js

@@ -59,6 +59,8 @@ const { runCli } = require('../../bin/project-knowledge-integrations');
     assert.equal(fs.readFileSync(configFile, 'utf8'), untouched);
 
     const runtime = createRuntime({ dataDir: layout.getDataDir(), logger, analysisOwner: 'engine', bridgeAdapter: new BridgeAdapter({ dataDir: layout.getDataDir(), bridgeHomeDir }) });
+    let startupRepairStops = 0;
+    runtime.integrationAutoRepair = { close: async () => { startupRepairStops++; }, status: () => ({}) };
     server = http.createServer(createRequestHandler(runtime, { integrationOptions: options }));
     await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
     const base = `http://127.0.0.1:${server.address().port}`;
@@ -68,6 +70,7 @@ const { runCli } = require('../../bin/project-knowledge-integrations');
       return response.json();
     };
     const apiInstall = await request('/api/integrations/install', { clients: ['zcode'], captureOnly: true });
+    assert.equal(startupRepairStops, 1, 'manual install cancels concurrent startup repair');
     assert.equal(apiInstall.complete, true);
     assert(apiInstall.operationId);
     const apiStatus = await request('/api/integrations/status');
@@ -82,6 +85,7 @@ const { runCli } = require('../../bin/project-knowledge-integrations');
     assert(errors.some(entry => entry.operationId === failed.operationId && entry.context.client === 'zcode' && entry.error.message.includes('JSON')), 'actual failed phase and operation ID are persisted');
     fs.writeFileSync(configFile, JSON.stringify(twice));
     const removed = await request('/api/integrations/uninstall', { clients: ['zcode'], captureOnly: true });
+    assert.equal(startupRepairStops, 3, 'manual uninstall cancels startup repair before removing client hooks');
     assert.equal(removed.complete, true);
     assert.deepEqual(removed.clients, [], 'capture-only removal does not invoke knowledge plugin operations');
     assert.equal(removed.capture[0].state, 'removed');

package/_site/lib/integration-auto-repair.js

@@ -44,10 +44,12 @@ class IntegrationAutoRepair {
   async runOnce() {
     const intent = readIntent(this.dataDir);
     if (!intent) return this.status();
-    const status = await this.createManager().statusAll({});
+    const clients = Object.entries(intent.clients).filter(([, state]) => state === 'connected').map(([client]) => client);
+    if (!clients.length) return this.status();
+    const status = await this.createManager().statusAll({ clients });
     for (const entry of status?.clients || []) {
-      if (intent.clients[entry.client] !== 'connected') continue;
-      if (entry.developmentCapture?.installed === true) continue;
+      if (readIntent(this.dataDir)?.clients[entry.client] !== 'connected') continue;
+      if (entry.developmentCapture?.installed !== false) continue;
       if (this.attempted.has(entry.client)) continue;
       await this._attempt(entry.client);
     }

package/_site/lib/integration-repair-worker.js

@@ -0,0 +1,16 @@
+'use strict';
+const { IntegrationManager } = require('./integration-installer');
+const { IntegrationAutoRepair } = require('./integration-auto-repair');
+process.once('message', async input => {
+  const logger = Object.fromEntries(['info', 'warn', 'error'].map(level => [level, (...args) => {
+    if (process.connected) process.send({ kind: 'log', level, args });
+  }]));
+  try {
+    const repair = new IntegrationAutoRepair({ dataDir: input.dataDir, logger,
+      createManager: () => new IntegrationManager({ ...input.managerOptions, logger }) });
+    const results = await repair.runOnce();
+    process.send({ ok: true, results }, () => process.disconnect());
+  } catch {
+    process.send({ ok: false }, () => process.disconnect());
+  }
+});

package/_site/lib/server-app.js

@@ -1332,6 +1332,7 @@ function createRequestHandler(runtime, options = {}) {
       if (method === 'POST' && pathname === '/api/integrations/install') {
         runtime.integrationStatusScan?.invalidate();
         const body = await readJsonBody(req);
+        await runtime.integrationAutoRepair?.close();
         const manager = new IntegrationManager({ ...options.integrationOptions, rootDir: runtime.rootDir, logger: runtime.logger, operationId: requestOperationId, bridgeHomeDir: runtime.bridgeAdapter.hookBinding().bridgeHomeDir });
         const clients = Array.isArray(body.clients) && body.clients.length
           ? body.clients.map(client => String(client))
@@ -1355,6 +1356,7 @@ function createRequestHandler(runtime, options = {}) {
       }
       if (method === 'POST' && pathname === '/api/integrations/uninstall') {
         const body = await readJsonBody(req);
+        await runtime.integrationAutoRepair?.close();
         const manager = new IntegrationManager({ ...options.integrationOptions, rootDir: runtime.rootDir, logger: runtime.logger, operationId: requestOperationId, bridgeHomeDir: runtime.bridgeAdapter.hookBinding().bridgeHomeDir });
         if (body.disableAllCapture === true) {
           const summary = await manager.disableAllCapture({});
@@ -1563,17 +1565,17 @@ async function startServer(options = {}) {
   }
 
   // Startup-event integration repair: one attempt per connected-but-broken
-  // client, failures surfaced and never retried in this run. No timers.
+  // client, failures surfaced and never retried in this run. Native checks
+  // run in an owned worker so they cannot block HTTP or launcher readiness.
   try {
-    runtime.integrationAutoRepair = new (require('./integration-auto-repair').IntegrationAutoRepair)({
+    runtime.integrationAutoRepair = new (require('./startup-integration-repair').StartupIntegrationRepair)({
       dataDir: runtime.dataPath,
       logger: runtime.logger,
-      createManager: () => new IntegrationManager({
+      managerOptions: {
         ...options.integrationOptions,
         rootDir: runtime.rootDir,
-        logger: runtime.logger,
         bridgeHomeDir: runtime.bridgeAdapter.hookBinding().bridgeHomeDir,
-      }),
+      },
     });
     runtime.integrationAutoRepair.runOnce().catch(error => {
       runtime.logger.warn('integrations.auto_repair_skipped', '启动自动修复未完成。', { error });
@@ -1587,6 +1589,7 @@ async function startServer(options = {}) {
     if (stopping) return stopping;
     stopping = (async () => {
       runtime.integrationStatusScan?.close();
+      await runtime.integrationAutoRepair?.close();
       clearInterval(maintenanceTimer);
       clearInterval(configurationTimer);
       clearTimeout(readyTimer); runtime.moduleBridge.onReady = null;

package/_site/lib/startup-integration-repair.js

@@ -0,0 +1,77 @@
+'use strict';
+const path = require('node:path');
+const { fork, spawn } = require('node:child_process');
+const { readIntent } = require('./integration-intent');
+
+// Native client commands can block for minutes. Keep the whole startup
+// status/repair operation outside the HTTP and launcher readiness process.
+class StartupIntegrationRepair {
+  constructor({ dataDir, managerOptions = {}, logger, workerFile, timeoutMs = 120000 } = {}) {
+    this.dataDir = dataDir; this.managerOptions = managerOptions; this.logger = logger;
+    this.workerFile = workerFile || path.join(__dirname, 'integration-repair-worker.js');
+    this.timeoutMs = timeoutMs; this.results = {}; this.manualSuccess = new Set();
+    this.closed = false; this.promise = null; this.child = null;
+  }
+  status() { return { ...this.results }; }
+  markSucceeded(clients) {
+    for (const client of clients || []) {
+      this.manualSuccess.add(client);
+      if (this.results[client]?.state === 'failed') this.results[client] = { state: 'repaired', at: new Date().toISOString(), error: null };
+    }
+  }
+  runOnce() {
+    if (this.promise) return this.promise;
+    const clients = Object.entries(readIntent(this.dataDir)?.clients || {}).filter(([, state]) => state === 'connected').map(([client]) => client);
+    if (this.closed || !clients.length) return Promise.resolve(this.status());
+    this.promise = new Promise(resolve => {
+      const child = fork(this.workerFile, [], { stdio: ['ignore', 'ignore', 'ignore', 'ipc'], windowsHide: true, detached: process.platform !== 'win32' });
+      this.child = child;
+      let settled = false;
+      const finish = (results, code) => {
+        if (settled) return; settled = true; clearTimeout(timer);
+        if (!this.closed) {
+          for (const [client, result] of Object.entries(results || {})) {
+            if (clients.includes(client) && !this.manualSuccess.has(client)) this.results[client] = result;
+          }
+          if (code) {
+            for (const client of clients) if (!this.manualSuccess.has(client)) this.results[client] = { state: 'failed', at: new Date().toISOString(), error: '启动接入检查未完成，请在 Agent 接入中重试。' };
+            Promise.resolve(this.logger?.warn?.('integrations.auto_repair_skipped', '启动接入检查未完成，主界面继续可用。', { context: { code, clients } })).catch(() => {});
+          }
+        }
+        resolve(this.status());
+      };
+      const timer = setTimeout(() => { void this.terminate().catch(() => {}); finish(null, 'INTEGRATION_REPAIR_TIMEOUT'); }, this.timeoutMs);
+      child.on('message', message => {
+        if (message?.kind === 'log') {
+          if (['info', 'warn', 'error'].includes(message.level) && Array.isArray(message.args) && /^integrations?\./.test(message.args[0] || '')) {
+            Promise.resolve(this.logger?.[message.level]?.(...message.args)).catch(() => {});
+          }
+          return;
+        }
+        finish(message?.results, message?.ok ? null : 'INTEGRATION_REPAIR_FAILED');
+      });
+      child.once('error', () => finish(null, 'INTEGRATION_REPAIR_SPAWN_FAILED'));
+      child.once('exit', () => finish(null, this.closed ? null : 'INTEGRATION_REPAIR_EXITED'));
+      const allowed = ['rootDir', 'homeDir', 'version', 'packageSpec', 'marketplaceSource', 'codexMarketplaceSource', 'bridgeHomeDir', 'bridgeConsumerName', 'claudeSettingsFile', 'codexConfigFile', 'zcodeConfigFile', 'openCodePluginsDir', 'env'];
+      child.send({ dataDir: this.dataDir, managerOptions: Object.fromEntries(allowed.filter(key => this.managerOptions[key] !== undefined).map(key => [key, this.managerOptions[key]])) }, error => { if (error) finish(null, 'INTEGRATION_REPAIR_SEND_FAILED'); });
+    });
+    return this.promise;
+  }
+  terminate() {
+    const child = this.child;
+    if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('启动接入检查进程尚未停止。')), 5000);
+      child.once('exit', () => { clearTimeout(timer); resolve(); });
+      if (process.platform === 'win32') {
+        // Only this live worker and its native probe children are owned here.
+        const killer = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        killer.once('error', () => child.kill());
+      } else {
+        try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+      }
+    });
+  }
+  async close() { this.closed = true; await this.terminate(); }
+}
+module.exports = { StartupIntegrationRepair };

package/docs/fresh-v5-start.md

@@ -15,6 +15,8 @@ project-knowledge
 
 5.0.6 修复首次启动被未登记的旧工作台会话误拦截：仅有日志、默认提示词及孤立会话的目录可以创建空的新登记，孤立会话保留原字节但不会恢复或触发任务。实际旧项目、设置、引擎状态或维护任务仍拒绝迁移，错误列出具体目录和冲突项。后台启动命令等待 HTTP 就绪后才报成功；启动失败直接在终端显示原因并返回非零退出码，不提前打开浏览器。
 
+5.0.22 将启动时的 Agent 接入检查和自动修复放入独立进程，慢客户端命令不再占住后台就绪通知、网页或实例控制。检查失败可在 Agent 接入中重试，停止服务会同时结束自有检查进程；无需清空数据。若仍提示启动未完成，请同时保留 `project-knowledge --version`、`project-knowledge status` 和报错所指 `launcher.log` 的末尾记录，以区分进程失败与慢启动。
+
 在“系统状态”重新配置模型与后台默认模型、embedding 和知识根目录，然后在“领域与项目”导入代码目录及新的空知识目录。原代码目录无需移动。若残留旧知识库托管 Hook，导入预检会要求明确确认替换；不会覆盖第三方 Hook。导入建立 HEAD 基线，不分析已有历史。
 
 如果模块是自己独立启动的旧进程，请在它原来的终端中停止后重启新版外壳。外壳不会擅自杀死其他服务；版本或运行期鉴权不一致时显示具体连接阶段，不接管旧服务数据。