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

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

@@ -0,0 +1,75 @@
+'use strict';
+// Startup-event integration repair. No timers, no polling: the same failure
+// cause will not heal inside one run, so a failed repair is surfaced once and
+// never retried automatically. The next backend start is a new event and gets
+// one fresh attempt; the only in-run retry is the explicit user action.
+
+const { readIntent } = require('./integration-intent');
+
+class IntegrationAutoRepair {
+  constructor({ dataDir, createManager, logger } = {}) {
+    if (typeof createManager !== 'function') throw new Error('IntegrationAutoRepair requires a createManager function.');
+    this.dataDir = dataDir;
+    this.createManager = createManager;
+    this.logger = logger || { info: () => {}, warn: () => {}, error: () => {} };
+    this.attempted = new Set();
+  }
+
+  async _repairOne(client, manager) {
+    const summary = await manager.installAll({ clients: [client] });
+    const capture = summary?.clients?.find(entry => entry.client === client)?.developmentCapture;
+    return { state: capture?.ok === true ? 'repaired' : 'failed', at: new Date().toISOString(), error: capture?.ok === true ? null : (capture?.detail || 'installAll did not report success.') };
+  }
+
+  async _attempt(client, options = {}) {
+    const force = options.force === true;
+    if (!force && this.attempted.has(client)) return null;
+    if (!force) this.attempted.add(client);
+    let result;
+    try {
+      result = await this._repairOne(client, this.createManager());
+    } catch (error) {
+      result = { state: 'failed', at: new Date().toISOString(), error: error.message };
+    }
+    this.results ||= {};
+    this.results[client] = result;
+    this.logger[result.state === 'repaired' ? 'info' : 'warn'](
+      `integrations.auto_repair_${result.state === 'repaired' ? 'succeeded' : 'failed'}`,
+      result.state === 'repaired' ? '启动时自动修复了 Agent 接入。' : '启动自动修复失败，已停止本周期自动重试。',
+      { context: { client, error: result.error } },
+    );
+    return result;
+  }
+
+  async runOnce() {
+    const intent = readIntent(this.dataDir);
+    if (!intent) return this.status();
+    const status = await this.createManager().statusAll({});
+    for (const entry of status?.clients || []) {
+      if (intent.clients[entry.client] !== 'connected') continue;
+      if (entry.developmentCapture?.installed === true) continue;
+      if (this.attempted.has(entry.client)) continue;
+      await this._attempt(entry.client);
+    }
+    return this.status();
+  }
+
+  async retry(client) {
+    return this._attempt(client, { force: true });
+  }
+
+  // A later successful manual install (switch on / retry repair) clears the
+  // startup failure so the badge stops reporting a stale error.
+  markSucceeded(clients) {
+    this.results ||= {};
+    for (const client of clients || []) {
+      if (this.results[client]?.state === 'failed') this.results[client] = { state: 'repaired', at: new Date().toISOString(), error: null };
+    }
+  }
+
+  status() {
+    return { ...(this.results || {}) };
+  }
+}
+
+module.exports = { IntegrationAutoRepair };

package/_site/lib/integration-intent.js

@@ -0,0 +1,88 @@
+'use strict';
+// User intent for external agent integrations.
+//
+// The install state alone cannot distinguish "broken, should heal" from
+// "deliberately removed, must stay away": both look like hooks-absent. This
+// store records the user's switch position per client so the startup repair
+// event only ever touches clients the user actually connected.
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA = 'project-knowledge/integration-intent/v1';
+const FILENAME = 'integration-intent.json';
+const STATES = new Set(['connected', 'disconnected']);
+
+function intentPath(dataDir) {
+  return path.join(path.resolve(dataDir), FILENAME);
+}
+
+function normalize(value) {
+  if (!value || typeof value !== 'object' || value.schema !== SCHEMA) return null;
+  const clients = {};
+  for (const [client, state] of Object.entries(value.clients || {})) {
+    if (STATES.has(state)) clients[client] = state;
+  }
+  return { schema: SCHEMA, clients };
+}
+
+function readIntent(dataDir) {
+  try {
+    return normalize(JSON.parse(fs.readFileSync(intentPath(dataDir), 'utf-8')));
+  } catch {
+    return null;
+  }
+}
+
+function writeIntent(dataDir, clients) {
+  const target = intentPath(dataDir);
+  const temp = `${target}.${process.pid}.tmp`;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(temp, JSON.stringify({ schema: SCHEMA, clients }, null, 2) + '\n', 'utf-8');
+  try {
+    fs.renameSync(temp, target);
+  } catch {
+    // Windows cannot always rename over an existing file.
+    try { fs.unlinkSync(target); } catch {}
+    fs.renameSync(temp, target);
+  }
+  return { schema: SCHEMA, clients };
+}
+
+function markIntent(dataDir, client, state) {
+  if (!STATES.has(state)) throw new Error(`invalid integration intent state: ${state}`);
+  const current = readIntent(dataDir);
+  const clients = { ...(current?.clients || {}), [client]: state };
+  return writeIntent(dataDir, clients);
+}
+
+// Migration: fill entries only for clients the file has never seen AND whose
+// status scan has settled — a mid-flight scan reports installed as undefined,
+// which must never be recorded as a removal decision. A client whose hooks
+// are installed counts as connected (standalone install or pre-upgrade
+// state); settled-but-absent hooks count as disconnected — the store is never
+// allowed to rewrite a decision the user already made.
+function bootstrapIntent(dataDir, clientsStatus) {
+  const current = readIntent(dataDir);
+  const clients = { ...(current?.clients || {}) };
+  let changed = false;
+  for (const entry of clientsStatus || []) {
+    if (!entry || !entry.client || entry.client in clients) continue;
+    if (entry.developmentCapture?.state === 'checking' || entry.developmentCapture?.installed === undefined) continue;
+    clients[entry.client] = entry.developmentCapture?.installed === true ? 'connected' : 'disconnected';
+    changed = true;
+  }
+  if (!changed && current) return current;
+  return writeIntent(dataDir, clients);
+}
+
+// Aggregate badge state for the single-switch UI.
+function summarizeClient(entry, repair) {
+  if (entry.developmentCapture?.state === 'checking' || entry.knowledgeIntegration?.state === 'checking') return 'checking';
+  if (!(entry.available || entry.configFound)) return 'not-detected';
+  if (entry.developmentCapture?.installed === true) return 'connected';
+  if (repair?.[entry.client]?.state === 'failed') return 'error';
+  return 'disconnected';
+}
+
+module.exports = { SCHEMA, FILENAME, intentPath, readIntent, markIntent, bootstrapIntent, summarizeClient };

package/_site/lib/module-bridge.js

@@ -12,9 +12,14 @@
  *   - module removal with keepSessions semantics
  *
  * Configuration (env, loopback defaults):
- *   KB_TERMINAL_URL     default http://127.0.0.1:5760
- *   KB_VECTORHUB_URL    default http://127.0.0.1:8787
- *   KB_EVENTBRIDGE_URL  default http://127.0.0.1:8790
+ *   KB_TERMINAL_URL     default http://127.0.0.1:5760 (managed: dynamic when busy)
+ *   KB_VECTORHUB_URL    default http://127.0.0.1:8787 (managed: dynamic when busy)
+ *   KB_EVENTBRIDGE_URL  default http://127.0.0.1:8790 (managed: dynamic when busy)
+ *   KB_KNOWLEDGE_ENGINE_URL default http://127.0.0.1:5790 (managed: dynamic when busy)
+ *   An explicitly injected URL is treated as an external service and never
+ *   rewritten. Managed modules resolve a final URL before spawn: healthy
+ *   identity match reuses the port, otherwise the next free port from
+ *   preferred +0..+19 is taken; all busy fails loudly (NO_FREE_MODULE_PORT).
  *   KB_MODULES_AUTOSTART  '0' to stop spawning the vendored module services
  *                         (they start with the shell by default)
  *   KB_TERMINAL_COMMAND  explicit node command line for the terminal service
@@ -23,8 +28,10 @@
  */
 
 const { spawn, spawnSync } = require('child_process');
+const net = require('net');
 const path = require('path');
 const { StorageLayout } = require('./storage-layout');
+const { resolveModuleUrl } = require('./module-port-resolver');
 const fs = require('fs');
 const crypto = require('crypto');
 const { once } = require('events');
@@ -83,6 +90,40 @@ function defaultEventBridgeUrl() {
 
 function defaultEngineUrl() { return String(process.env.KB_KNOWLEDGE_ENGINE_URL || 'http://127.0.0.1:5790').replace(/\/+$/, ''); }
 
+// Health identity markers: an HTTP 200 alone can come from any foreign
+// service that grabbed the port. Only a body that matches the product
+// counts as "our module already running" (reuse); anything else is
+// foreign and the resolver moves to another port instead of crash-looping.
+const MODULE_IDENTITY = {
+  terminal: body => body && typeof body === 'object' && body.status === 'ok' && typeof body.apiVersion === 'string',
+  vectorHub: body => body && typeof body === 'object' && Array.isArray(body.projects),
+  eventBridge: body => body && typeof body === 'object' && typeof body.registeredProjects === 'number',
+  engine: body => body && typeof body === 'object' && body.name === 'knowledge-engine',
+};
+
+// kind -> bridge URL property, explicit env override, spawn spec name
+const MODULE_URL_TARGETS = [
+  { kind: 'terminal', prop: 'terminalUrl', env: 'KB_TERMINAL_URL', specName: 'terminal' },
+  { kind: 'vectorHub', prop: 'vectorHubUrl', env: 'KB_VECTORHUB_URL', specName: 'vector-hub' },
+  { kind: 'eventBridge', prop: 'eventBridgeUrl', env: 'KB_EVENTBRIDGE_URL', specName: 'event-bridge' },
+  { kind: 'engine', prop: 'engineUrl', env: 'KB_KNOWLEDGE_ENGINE_URL', specName: 'knowledge-engine' },
+];
+
+function specNameToKind(specName) {
+  return MODULE_URL_TARGETS.find(target => target.specName === specName)?.kind || null;
+}
+
+function tcpPortFree(host, port) {
+  return new Promise(resolve => {
+    const tester = net.createServer();
+    let done = false;
+    const finish = free => { if (done) return; done = true; tester.close(() => resolve(free)); };
+    tester.once('error', () => finish(false));
+    tester.once('listening', () => finish(true));
+    tester.listen(port, host);
+  });
+}
+
 class ModuleBridge {
   constructor(options = {}) {
     this.logger = options.logger || { info: () => {}, warn: () => {}, error: () => {} };
@@ -90,6 +131,15 @@ class ModuleBridge {
     this.vectorHubUrl = options.vectorHubUrl || defaultVectorHubUrl();
     this.eventBridgeUrl = options.eventBridgeUrl || defaultEventBridgeUrl();
     this.engineUrl = options.engineUrl || defaultEngineUrl();
+    // Explicitly injected URLs (option or env) mean an external service;
+    // only managed defaults participate in dynamic port resolution.
+    this.explicitModuleUrls = {
+      terminal: Boolean(options.terminalUrl || process.env.KB_TERMINAL_URL),
+      vectorHub: Boolean(options.vectorHubUrl || process.env.KB_VECTORHUB_URL),
+      eventBridge: Boolean(options.eventBridgeUrl || process.env.KB_EVENTBRIDGE_URL),
+      engine: Boolean(options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL),
+    };
+    this.moduleUrlSources = { terminal: 'pending', vectorHub: 'pending', eventBridge: 'pending', engine: 'pending' };
     this.runtimeToken = options.runtimeToken || crypto.randomBytes(32).toString('hex');
     this.registryStore = options.registryStore || null;
     this.projectStore = options.projectStore || null;
@@ -303,23 +353,43 @@ class ModuleBridge {
     };
   }
 
-  async _probe(base) {
-    const route = base === this.terminalUrl ? '/api/claude-workbench/v1/health' : '/api/health';
-    try { const response = await this._fetch(`${base}${route}`, { timeoutMs: 2000 }); return response.ok; } catch { return false; }
+  /**
+   * Classify what is listening on a module URL.
+   * 'module'     HTTP 2xx + product identity marker -> safe to reuse
+   * 'foreign'    HTTP responded but identity mismatch -> never reuse
+   * 'unreachable' no HTTP answer (free port or non-HTTP listener)
+   */
+  async _probeClass(base, kind) {
+    const route = kind === 'terminal' ? '/api/claude-workbench/v1/health' : '/api/health';
+    const marker = MODULE_IDENTITY[kind];
+    if (!marker) return 'unreachable';
+    try {
+      const response = await this._fetch(`${base}${route}`, { timeoutMs: 2000 });
+      if (!response.ok) return 'unreachable';
+      let body;
+      try { body = await response.json(); } catch { return 'foreign'; }
+      return marker(body) ? 'module' : 'foreign';
+    } catch { return 'unreachable'; }
+  }
+
+  async _probe(base, kind) {
+    const resolvedKind = kind || (base === this.terminalUrl ? 'terminal' : null);
+    if (!resolvedKind) return false;
+    return (await this._probeClass(base, resolvedKind)) === 'module';
   }
 
   async modulesHealth() {
     const [terminal, vectorHub, eventBridge, engine] = await Promise.all([
-      this._probe(this.terminalUrl),
-      this._probe(this.vectorHubUrl),
-      this._probe(this.eventBridgeUrl),
-      this._probe(this.engineUrl),
+      this._probe(this.terminalUrl, 'terminal'),
+      this._probe(this.vectorHubUrl, 'vectorHub'),
+      this._probe(this.eventBridgeUrl, 'eventBridge'),
+      this._probe(this.engineUrl, 'engine'),
     ]);
     return { ok: true, modules: {
-      terminal: { url: this.terminalUrl, up: terminal },
-      vectorHub: { url: this.vectorHubUrl, up: vectorHub },
-      eventBridge: { url: this.eventBridgeUrl, up: eventBridge },
-      engine: { url: this.engineUrl, up: engine },
+      terminal: { url: this.terminalUrl, up: terminal, source: this.moduleUrlSources.terminal },
+      vectorHub: { url: this.vectorHubUrl, up: vectorHub, source: this.moduleUrlSources.vectorHub },
+      eventBridge: { url: this.eventBridgeUrl, up: eventBridge, source: this.moduleUrlSources.eventBridge },
+      engine: { url: this.engineUrl, up: engine, source: this.moduleUrlSources.engine },
     } };
   }
 
@@ -617,8 +687,10 @@ class ModuleBridge {
    */
   async startSupervised() {
     if (String(process.env.KB_MODULES_AUTOSTART || '') === '0') return;
+    await this._resolveManagedUrls();
     await Promise.all(this._supervisedSpecs().map(async spec => {
-      if (await this._probe(spec.url)) {
+      const kind = specNameToKind(spec.name);
+      if (kind && await this._probeClass(spec.url, kind) === 'module') {
         this.logger.info('modules.supervisor', 'Module service already up; not spawning.', { context: { name: spec.name, url: spec.url } });
         this.onReady?.(spec.name); return;
       }
@@ -626,6 +698,31 @@ class ModuleBridge {
     }));
   }
 
+  /**
+   * Resolve final managed URLs BEFORE any spec is built or a process is
+   * spawned, so inter-module env wiring (engine URL, bridge URL, ...) uses
+   * the final dynamic ports. Sequential on purpose: parallel scans could
+   * race two kinds into the same overlapping candidate range
+   * (8787..8806 vs 8790..8809).
+   */
+  async _resolveManagedUrls() {
+    for (const target of MODULE_URL_TARGETS) {
+      const preferredUrl = this[target.prop];
+      const resolved = await resolveModuleUrl({
+        kind: target.kind,
+        preferredUrl,
+        explicit: this.explicitModuleUrls[target.kind],
+        portFree: port => tcpPortFree(urlHost(preferredUrl), port),
+        probe: url => this._probeClass(url, target.kind),
+      });
+      this[target.prop] = resolved.url;
+      this.moduleUrlSources[target.kind] = resolved.source;
+      if (resolved.source !== 'external') {
+        this.logger.info('modules.port_resolution', 'Module URL resolved.', { context: { kind: target.kind, source: resolved.source, url: resolved.url, port: resolved.port, offset: resolved.offset } });
+      }
+    }
+  }
+
   _supervisedSpecs() {
     const specs = [];
     // C2 minimal wiring: the terminal service receives the non-secret product
@@ -740,7 +837,8 @@ class ModuleBridge {
     let attemptsReady = 0;
     const checkReady = async () => {
       if (this.stopped || child.exitCode !== null || ++attemptsReady > 20) return;
-      if (await this._probe(spec.url)) { this.resetRuntimeConfiguration(); this.onReady?.(spec.name); return; }
+      const kind = specNameToKind(spec.name);
+      if (kind && await this._probeClass(spec.url, kind) === 'module') { this.resetRuntimeConfiguration(); this.onReady?.(spec.name); return; }
       const timer = setTimeout(() => { this.restartTimers.delete(timer); checkReady(); }, 500);
       this.restartTimers ||= new Set(); this.restartTimers.add(timer);
     };

package/_site/lib/module-port-resolver.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Dynamic module URL resolution.
+//
+// Managed modules used to bind fixed default ports (terminal 5760,
+// vector-hub 8787, event-bridge 8790, engine 5790).  When a foreign process
+// occupied one of those ports the module crash-looped and the feature stayed
+// degraded.  This resolver picks the final URL BEFORE any module is spawned:
+//
+//   explicit env/option URL -> external service, untouched (legacy behavior)
+//   healthy identity match  -> reused (standalone module keeps running)
+//   otherwise               -> first free port from preferred +0..+19
+//   all busy                -> NO_FREE_MODULE_PORT (loud, never silent)
+
+function invalidUrl(value) {
+  return Object.assign(new Error(`Invalid module URL: ${value}`), { code: 'INVALID_MODULE_URL' });
+}
+
+function parsePreferredUrl(value) {
+  let parsed;
+  try { parsed = new URL(String(value)); } catch { throw invalidUrl(value); }
+  const port = Number(parsed.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw invalidUrl(value);
+  return { parsed, port };
+}
+
+function rebuildUrl(parsed, port) {
+  const host = parsed.hostname.includes(':') ? `[${parsed.hostname}]` : parsed.hostname;
+  return `${parsed.protocol}//${host}:${port}`;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.kind module kind, used in errors/logs only
+ * @param {string} options.preferredUrl default URL with an explicit port
+ * @param {boolean} options.explicit true when the URL was injected explicitly
+ * @param {(port: number) => Promise<boolean>} options.portFree TCP bind probe
+ * @param {(url: string) => Promise<'module'|'foreign'|'unreachable'>} options.probe
+ * @param {number} [options.scanRange] candidate count starting at the preferred port
+ * @returns {Promise<{url: string, source: 'external'|'reused'|'dynamic', port: number, offset: number}>}
+ */
+async function resolveModuleUrl({ kind, preferredUrl, explicit, portFree, probe, scanRange = 20 }) {
+  const { parsed, port } = parsePreferredUrl(preferredUrl);
+  if (explicit) return { url: preferredUrl, source: 'external', port, offset: 0 };
+  if (await probe(preferredUrl) === 'module') return { url: preferredUrl, source: 'reused', port, offset: 0 };
+  const range = Math.max(1, Number.isInteger(scanRange) ? scanRange : 20);
+  for (let offset = 0; offset < range && port + offset <= 65535; offset++) {
+    const candidate = port + offset;
+    if (await portFree(candidate)) {
+      return { url: rebuildUrl(parsed, candidate), source: 'dynamic', port: candidate, offset };
+    }
+  }
+  const last = Math.min(port + range - 1, 65535);
+  throw Object.assign(new Error(`No free port found for ${kind} in ${port}-${last}.`), { code: 'NO_FREE_MODULE_PORT' });
+}
+
+module.exports = { resolveModuleUrl };

package/_site/lib/server-app.js

@@ -1304,6 +1304,7 @@ function createRequestHandler(runtime, options = {}) {
       // Integration and Development Capture per client, with separate status.
       if (method === 'GET' && pathname === '/api/integrations/status') {
         runtime.integrationStatusScan ||= new (require('./integration-status-scan').IntegrationStatusScan)();
+        const intentStore = require('./integration-intent');
         const managerOptions = { ...options.integrationOptions, rootDir: runtime.rootDir, logger: runtime.logger, operationId: requestOperationId, bridgeHomeDir: runtime.bridgeAdapter.hookBinding().bridgeHomeDir };
         const projectId = url.searchParams.get('projectId');
         if (projectId && !runtime.registryStore.listIds().includes(projectId)) throw new DomainError('PROJECT_NOT_FOUND', '当前项目尚未登记。', { status: 404 });
@@ -1311,6 +1312,14 @@ function createRequestHandler(runtime, options = {}) {
         const requested = url.searchParams.get('clients');
         const clients = requested ? requested.split(',').filter(Boolean).map(require('./integration-installer').normalizeClient) : undefined;
         const summary = await runtime.integrationStatusScan.read(managerOptions, { captureOnly: url.searchParams.get('captureOnly') === '1', cwd, clients }, { force: url.searchParams.get('refresh') === '1' });
+        const repair = runtime.integrationAutoRepair?.status() || null;
+        const intent = intentStore.bootstrapIntent(runtime.dataPath, summary.clients);
+        summary.clients = summary.clients.map(entry => ({
+          ...entry,
+          intent: intent.clients[entry.client] || 'disconnected',
+          summary: intentStore.summarizeClient(entry, repair),
+          repair: repair?.[entry.client] || null,
+        }));
         return send(res, 200, { ok: true, ...summary });
       }
       if (method === 'POST' && pathname === '/api/integrations/install') {
@@ -1327,6 +1336,13 @@ function createRequestHandler(runtime, options = {}) {
           scope: body.scope || 'user',
         });
         const complete = summary.bridge.ok && summary.clients.every(entry => (!entry.knowledgeIntegration || entry.knowledgeIntegration.ok) && (!entry.developmentCapture || entry.developmentCapture.ok));
+        if (complete) {
+          const intentStore = require('./integration-intent');
+          for (const entry of summary.clients) {
+            if (entry.developmentCapture?.ok || entry.knowledgeIntegration?.ok) intentStore.markIntent(runtime.dataPath, entry.client, 'connected');
+          }
+          runtime.integrationAutoRepair?.markSucceeded?.(summary.clients.map(entry => entry.client));
+        }
         await runtime.logger[complete ? 'info' : 'error'](`integrations.install_${complete ? 'completed' : 'failed'}`, complete ? 'Agent 接入完成。' : 'Agent 接入未完成，请查看各工具的失败原因。', { operationId: requestOperationId, context: { clients: summary.clients.map(entry => entry.client) } });
         return send(res, 200, { ok: true, complete, operationId: requestOperationId, ...summary });
       }
@@ -1342,7 +1358,13 @@ function createRequestHandler(runtime, options = {}) {
           : undefined;
         const knowledgeResults = body.captureOnly === true ? [] : await manager.operate('uninstall', clients && clients.length ? clients : manager.detectClients(), { scope: body.scope || 'user' });
         const captureResults = body.knowledgeOnly === true ? [] : await manager.operateCapture('uninstall', clients && clients.length ? clients : manager.detectClients(), {});
-        return send(res, 200, { ok: true, complete: [...knowledgeResults, ...captureResults].every(entry => entry.ok), operationId: requestOperationId, clients: knowledgeResults, capture: captureResults });
+        const complete = [...knowledgeResults, ...captureResults].every(entry => entry.ok);
+        if (complete) {
+          const intentStore = require('./integration-intent');
+          const removed = new Set([...knowledgeResults, ...captureResults].map(entry => entry.client));
+          for (const client of removed) intentStore.markIntent(runtime.dataPath, client, 'disconnected');
+        }
+        return send(res, 200, { ok: true, complete, operationId: requestOperationId, clients: knowledgeResults, capture: captureResults });
       }
 
       if (method === 'GET' && pathname === '/api/ai-profiles') {
@@ -1532,6 +1554,26 @@ async function startServer(options = {}) {
     runtime.logger.warn('modules.supervisor_failed', 'Module supervisor failed to start.', { error });
   }
 
+  // Startup-event integration repair: one attempt per connected-but-broken
+  // client, failures surfaced and never retried in this run. No timers.
+  try {
+    runtime.integrationAutoRepair = new (require('./integration-auto-repair').IntegrationAutoRepair)({
+      dataDir: runtime.dataPath,
+      logger: runtime.logger,
+      createManager: () => new IntegrationManager({
+        ...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 });
+    });
+  } catch (error) {
+    runtime.logger.warn('integrations.auto_repair_unavailable', '启动自动修复不可用。', { error });
+  }
+
   let stopping = null;
   const stop = async reason => {
     if (stopping) return stopping;

package/docs/release-5.0.17-acceptance.md

@@ -2,7 +2,7 @@
 
 ## 发布状态
 
-2026-10-15：最终候选 `5.0.17-rc.3` 验收通过，正在准备正式 `5.0.17` 的独立下载验收，`latest` 仍为 `5.0.16`。本文件不得被解读为正式版已放行。Electron、Windows 安装包和窄屏矩阵均不在本次范围；用户报告故障的另一台电脑尚需更新后回验。npm 内文档是打包时快照，正式包自己的验收结果在测试完成后追加到仓库当前文档。
+2026-10-15：最终候选 `5.0.17-rc.3` 和正式 `5.0.17` 均已独立下载安装验收通过，官方 npm 的 `latest`、`next` 均为 `5.0.17`，`npm view ...@latest version --prefer-online` 已再次确认。Electron、Windows 安装包和窄屏矩阵不在本次范围；用户报告故障的另一台电脑尚需更新后回验。npm 内文档是打包时快照，正式包自己的验收结果在测试完成后追加到仓库当前文档，未重发或修改同版本 npm 包。
 
 ## 交付范围
 
@@ -96,4 +96,22 @@ GLM 报告分别保存在两个仓库的 `.local-test-data/ui-refresh-2026-10-15
 
 ### 正式包
 
-待补：正式包自己的官方收据、安装版重测及 latest 晋升结果。未填写之前不报告正式交付完成。
+官方全新安装收据：`D:\SanQian.Xu\.pk-acceptance-temp\kb-registry-product-Vn5JOh\registry-installation.json`，源码提交 `7fac75f63bca0ca9d4c125cff8029c6e8822a4c1`，integrity `sha512-HhFfsEDF4UbZlbSmPyBbnAgvKGd2tgXmhPDXW3H5VGNRGmiN7DfXA2fmwVvqOr/Fe59d4KoQsrdEsOIpsmNJ5Q==`。Workbench `0.13.2-rc.17`、vector-hub `1.0.8-rc.8`、bridge `0.7.2`、vendored engine `0.2.7-rc.10`；包内内容和官方模块 integrity 均核对通过。
+
+| 正式验收项 | 实际结果 |
+|---|---|
+| 源码冻结复跑 | 正式提交的 Node 24 外壳 134/134，215568ms；Node 22 134/134 记录保留。Workbench 双 Node 405，engine 双 Node 185 通过/1 跳过；未修改模块也补跑 vector-hub 73、bridge 30，均通过。浏览器自动脚本排除不计通过，真实浏览器另列 |
+| 真进程生命周期 | 正式安装目录 `acceptance-data` 下的 startup/restart/shutdown JSON：四模块启动、独立退出后的守护恢复、大写 STOP、四个子进程正常关闭均通过 |
+| 真实提交闭环 | `智脑桌面验收-E0OL29/real-agent-formal-refresh-acceptance.json`：单提交 `2769908ce00b6b8aeab178e83b6f1bbca0c16871`，双项目 `7f1c331d`、`f5870071` 均晋升、索引并可检索；并行分析区间实际重叠 |
+| 真实向量 | 正式引擎的语义查询包含 10 个校验向量片段、`index:vector-hub` 命中和对应正式提交，不以文本降级冒充向量成功 |
+| 真网页和模型 | 会话 `sess-001c5cbec432`，真实 MiniMax-M3.1-Flash-Preview，76 个文本增量，回答逐字引用新知识原文和完整提交；最后自然 idle、持久化 turn-end，通过后端独立核验 |
+| 刷新与滚轮 | 工作中向上滚动后切到活动页，活动自动显示真实维护“已更新·可检索”；返回工作台内容增长至 2075，阅读位置仍为 0，未发送草稿保留，iframe 只加载一次 |
+| 网络恢复 | 正式页面断网显示连接中断，恢复后重新读取状态，草稿、会话和引用仍存在；仍为 1 WebSocket / 2 订阅，桌面 1436×730、无横向溢出、浏览器控制台无错误 |
+| 完整历史 | 独立替身环境 `智脑桌面验收-TIFVtg`，正式包后端新建 25 轮，分页 20+5；真实网页向上翻阅后 DOM 同时包含第 01 与第 25 轮，共 25 轮。仅此长历史项使用替身，不混入真实模型结果 |
+| 正式发布 | 正式包先发 next，以上验收完成后才执行 dist-tag latest；第一次 npm view 仍命中旧元数据，保留该观察。dist-tag 官方端点随后已为 5.0.17，最后 npm view @latest 也确认为 5.0.17 |
+
+最终证据副本集中在 `project-knowledge-base/.local-test-data/ui-refresh-2026-10-15/`：`formal-registry-installation.json`、`formal-installed-{startup,restart,shutdown}.json`、`formal-real-commits.json`、`formal-real-workbench.json`、`formal-complete-history.json`、`node24-formal-source-pass.md`、`node22-final-pass.md` 与 `glm-final-review.md`。两张正式桌面截图为 `formal-real-workbench.jpg`、`formal-complete-history.jpg`。
+
+相关源码均已推送远程 Git；本轮未更新或重启原 5757 用户实例（仍为 5.0.16），没有修改用户知识、历史、凭据、原生 Hook 信任或第三方通知。请在实际出现故障的电脑按日常方式 stop、安装官方 @latest、检查版本并启动。Windows 若独立 IDE 的 MCP 持有原生库导致 EBUSY，应先退出相应会话后重试，不删除原生文件或清空数据。
+
+本轮网页范围验收完成，不等于对其他设备、私有语料或未保存过的旧历史作无缺陷保证。Electron 与 macOS 原生安装未实施、不计为通过。

package/module-runtime-manifest.json

@@ -1,24 +1,24 @@
 {
   "schema": "project-knowledge/module-content/v1",
   "productFiles": {
-    "ui/index.html": "1ad9cd83d1727e98b90391c1ab5ab9b99b5812d1ab9e9262bf1e8f3b49e3331d",
-    "ui/product.js": "1a5cee1cdebaffe097cef4f908bc7e595b16734a08f7495ed0d52b9b81137f5e",
-    "ui/product.css": "0c31d4937780b3a277689b4619208ad0e5dc59a84d7e27fc16b5f1815d59b47c",
+    "ui/index.html": "737b8f5c745270797950c5975f458a13ffe1ea738f921e814bfbbe5e56813fed",
+    "ui/product.js": "da7ea12a394212766cb0994fe0026ab2cccbba866063cdcc4c1662573e3c6dfa",
+    "ui/product.css": "4f300b08c086a939831d7ee69df01f23641457c0d606af29e9d4ce8a6d28bc9d",
     "ui/favicon.svg": "c48be946b224112ebb0238b44263f7a61bda31e531afa895c2e9801c0ff24f32",
     "plugins/project-knowledge/hooks/claude.json": "d61510327e3e1facbb4c645228e9f50cad05a88b33d80c4c22e5ba9f8b9f5359",
     "plugins/project-knowledge/hooks/codex.json": "216e03c07295606ef6ebb2c4f669ad0d790b5e7c4f3f34600488033db75e4239",
     "plugins/project-knowledge/scripts/context-hook.cjs": "da666153ad5723592cce42d25337ae649f7d93e43fab76b3c6d1263933de063f",
     "plugins/project-knowledge/scripts/mcp-launcher.cjs": "7c68830b5c73eb53ef030756a4de33987f7eab6b1a6cc15602835aac3f954893",
-    "plugins/project-knowledge/.claude-plugin/plugin.json": "0cc5384cb0c368e79550077587eb64b69a57bcd401af545be2b7c97dae3c13d0",
-    "plugins/project-knowledge/.codex-plugin/plugin.json": "6968e066cc84b2d91034b1279d90c256415548bc9518fe62ae7f2055ef8e013a",
-    "plugins/project-knowledge/.mcp.json": "63dab0b2484b49dce2ab4565595e030a7c88e4196bc35a54d14445ff24399921",
+    "plugins/project-knowledge/.claude-plugin/plugin.json": "ad8cf459af8242236bb71c4a7e98a24b015415404bb44aedb920fbe0fef943ec",
+    "plugins/project-knowledge/.codex-plugin/plugin.json": "ee91251067ce65c54001e915c3960672a595045cf6db4f7c3d56ab7101eff4c0",
+    "plugins/project-knowledge/.mcp.json": "9bc8e766dbe8893726fef90e9f909cdc04ae22d25e85b26e517ead72ff69d771",
     "ui/live-client.js": "0d81fa894c629bb839e1931fc3c5ebad4d831aae8232d6ce8c0f542e9e3559e8"
   },
   "modules": {
     "terminal": {
       "name": "@sanqianx/claude-ai-workbench",
       "installName": "claude-ai-workbench",
-      "version": "0.13.2-rc.17",
+      "version": "0.13.2-rc.18",
       "files": {
         "LICENSE": "c1b9df1275e769f3dbab000d1e457a2d4b0f28eb5da6c77e48dc37eeba202ed7",
         "README.md": "43938c8a64397d340dcf633edc40a7cea7dd8a95b5f82cf612b2c15b66c380b6",
@@ -35,20 +35,20 @@
         "apps/minimal-test-host/README.md": "fa73136f4ee3865c2d91eb97b2e8c03679aa4688e44c1e1c8ec6e27d604b0de5",
         "docs/sdk/FILE_LAYOUT.md": "17882f96505c8161bfb66876684b9d2d3f50021a111b8b844502d3cb4e97870a",
         "docs/sdk/INTEGRATION.md": "d4c0c80d2d2fc610205102d703a429bfaa20f9f3a48f1718f5bab02ee90138df",
-        "docs/sdk/openapi.yaml": "7c7dd11f5b261cf92cd4d64f8b1eeddd56b79f2617fa7236107dc185a02d2ce3",
+        "docs/sdk/openapi.yaml": "ece89afdd4e1a58f01f7e8db6581cee91baf2c918d68208e86200ff5abe0ac9d",
         "docs/sdk/README.md": "7ab591d39c36a3b84cfdf487ff567040ec453975f3ef0fba86dc822094667b61",
-        "package.json": "20169c89b949300b9f3ba325b989f6a7aabf1a11097e31f898094eb5956863d5",
+        "package.json": "cfa3c5e1ca1f5dd4727fd96b3639f4b989a135451549f970047a72dd588be646",
         "packages/client/index.d.ts": "587a66845052dc5cc03c4f41d678808140ea258fdf914be1c6dd2f6c07c1aff1",
         "packages/client/index.js": "6c7abce75086b68c18b9fdab372eff8b70d4bb81da6e7e0f46e4af57de0c523d",
-        "packages/client/package.json": "0b1a9727003087a25b66e5d99a860785d9fcd5d008dbfc514547d791b2cb9e46",
+        "packages/client/package.json": "eb65b7e8d9dd1fe21c86b04830e83b1d86ed4f69b3dbf04428b33efb125ab6be",
         "packages/client/README.md": "342dff9b1dcbc85fccc9b980ed3e4e455aa71133af1d0805b8431ea2ac564ef8",
         "packages/contracts/index.d.ts": "109ed9559b23f92b3840c484b9dd7f293a46866a3937a52e631e52692bb41927",
         "packages/contracts/index.js": "5eeb195d9c4cc54dab064510684ae1350d325fbaf47ff824dad4a04a5bb67d11",
-        "packages/contracts/package.json": "b79a3fdd09c635b2645ecab11ab6e789d1883aeac4f13d35dc11f4f09947808d",
+        "packages/contracts/package.json": "cffc5c24c523871b52e4e6b1ab0d3d7b81cfd11c3e1f53f14d681874eaee8d4b",
         "packages/contracts/README.md": "44d83a3cc508cec6c5c20dfa1f2c08d5ea03e3afb2853639fdc0a9cc8eb5b9c8",
         "packages/core/index.d.ts": "c95b24a13f8aeeb128497833cf298790563baca6036ea5d29a9d8daff53199d7",
         "packages/core/index.js": "825640d0edc7dd130f22da1f580d2cda355566a40b0b36e42e5f38909605bbfa",
-        "packages/core/package.json": "271a20f55ca486cd9a788b857381d8997c96de17029516bacd1dee4a3f1a3573",
+        "packages/core/package.json": "935f642db83942faecd1c9276c0f48365f968a6b17c4fd768d93272db891dbcc",
         "packages/core/README.md": "e222c546104a168f1038d95c6c4efb8e5603edd6145ab2cab79cab977fb710e5",
         "packages/server/bin/agent-terminal-server.js": "043dff4d76e3fd213b666a55e581ed1e72f9e5b8de6cb798fbf42bd39ed26861",
         "packages/server/bin/claude-workbench-server.js": "b03c730b6d86faf6974afea26c74109d59b1bbc1ecc656c1d6270258708694ac",
@@ -67,10 +67,10 @@
         "packages/server/lib/context-resolver.js": "d3060bfe35fb184e521847fc0900cf6114f8ebf3120ce13ed39dfc224af54660",
         "packages/server/lib/conversation-capture.js": "9f3ee29003eaea4778dc1e4b7e23e868f2ba0268bd43db07317acba62f48a094",
         "packages/server/lib/diagnostics.js": "b45687fcc07f8baeb33ffd08efdc875494d4e3205887514fdfd7e1ce6370753b",
-        "packages/server/lib/drivers/cli-json-runner.js": "23704b5ea76564f5200d4088f53afd67a7fd03f17e98f7ebaeebd40a1fc4f2ac",
-        "packages/server/lib/drivers/codex-driver.js": "74368620dd3357268228ea2cf9a5c1318e3fc3e24849869d4d91c9698d554652",
-        "packages/server/lib/drivers/opencode-driver.js": "7155d0fcd091ac5ff9ec9275b6694a34321e7d16a5305da4adf080c50d054c0d",
-        "packages/server/lib/drivers/zcode-driver.js": "bf8fb9d49346aa51207565fb7838ef29b667544119e9e24ec115f3de0e7820f2",
+        "packages/server/lib/drivers/cli-json-runner.js": "3802a9066bd78062c40441d43b23bf97333ec742f877c59f4426e4cb118e8e54",
+        "packages/server/lib/drivers/codex-driver.js": "a9fb31e5a3a34d24f976e275546721f968e7a8af901019c6d5fab10ebfa5b9e4",
+        "packages/server/lib/drivers/opencode-driver.js": "b7e0a338b32c2616fa3ce1fa438be5abc9794218eb1744b3a6eac877122a8c28",
+        "packages/server/lib/drivers/zcode-driver.js": "cb25b9d84e1bb8fb2b12aa4add656af2448c090cd99210e9dca9f55657764504",
         "packages/server/lib/drivers/zcode-profile-runtime.js": "77c5ac83551cc424375918863d4a31039984492c3a1c987a615a072ac7cb1f14",
         "packages/server/lib/event-stream.js": "3e6cf39b4599a3b1c9897da31d73c28b288a3d57f7a177ed90618de91977d3c4",
         "packages/server/lib/folder-picker.js": "70f55df999262b90433f2b4251aa69dd70a23b55a84756b5f1d24dbeacfbda31",
@@ -84,8 +84,8 @@
         "packages/server/lib/session-history.js": "7836167666d8032b9894a241ca42befa33fd034d7c9bd894a6399f57f31a2906",
         "packages/server/lib/system-doctor.js": "d098a046f425e90ef25209be69d78beefdfd9c2af92f08068a9bfc52053a8f7d",
         "packages/server/lib/ui-preferences-store.js": "e108cb22e7cc1f3438704913d5401e01de2c0e717eb2abd3bdc4727209393819",
-        "packages/server/lib/workbench-service.js": "a9cea8a68bee8dd93a705c54d747794fbd47a3694d6194ce739e6030e62da2b6",
-        "packages/server/package.json": "d59b110305fd9e428d8e3d8240d955ee2d84a1af7ad923d7f19df05392e7b912",
+        "packages/server/lib/workbench-service.js": "12477e3556b4c3d49adc3b69c0783f79335d87fbfc727ba5a19c598e2a4118d4",
+        "packages/server/package.json": "bf4e1c055e6115c17fe5b3636ac477bd430176aa9650ce5e1013862fae6342c8",
         "packages/server/README.md": "a34cfaa4f4e859008b44e2be8e1aafb56e97fe83e6129c968a8562945fa843f3",
         "packages/ui/ai-profile-settings.d.ts": "0551b6c6eda6d18ea89a976daddf01b2161195f4874fe2d67a57cd9ecc6ce643",
         "packages/ui/ai-profile-settings.js": "e92bbac67a1199d473e4e44b32d1cc76c5b6c79306d4fef9d9067a1bb6ec42ca",
@@ -93,7 +93,7 @@
         "packages/ui/claude-terminal.js": "96bd217a4a7e4792ae3fbaaf46249ecee13b0f4e01fc6d25a1b8b22d8f8fe00c",
         "packages/ui/index.d.ts": "e547ab39640fe7519fb367b78442dc8a2c51b2efd17b66f8b0a003b154b36ead",
         "packages/ui/index.js": "f4394aabd395938f5c3fe587e430471d4033e83945a9b9c7e0149ad4040982c9",
-        "packages/ui/package.json": "6bc87d45f6df2e1d8de5784dfd5a99b473d35eff72590da026d3bf8fefcccc18",
+        "packages/ui/package.json": "f08f2d43068ae70dd8740744f414d45eb3968f4724668ebdbc7d4b1b672d67e2",
         "packages/ui/README.md": "793c4a9c286fee23f39062a1976ca3afe9d2816dcdb55e156ba940e1ef514f89",
         "packages/ui/theme.css": "8f03a081272a7db11b196f7a70d0fafb1f8d954778f329f1ba53d110d9d5fd98",
         "src/assets/claude-prompts.json": "cb111f2e0a45afe8a31c251a504d1ab5375966ed61291660e61fd2efd77f6d9f",