@sanqianx/project-knowledge 5.0.1 → 5.0.2

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [5.0.2] - 2026-10-10
+
+- Add ZCode capture to the unified CLI and web System Status connector setup,
+  including repair, status and safe removal. Keep unverified ZCode knowledge
+  plugin support explicitly separate from working capture hooks.
+- Correct command/config discovery labels and stop treating consumer
+  registration or disabled hooks as proof of capture. Report partial failures
+  with their operation ID and persist connector errors from both web and CLI.
+- Pin event-bridge 0.7.2: external hooks resolve their own Bridge home without
+  inherited environment variables; ZCode events preserve their source. Repair
+  older entries in place and retain third-party hooks within mixed groups.
+
 ## [5.0.1] - 2026-10-10
 
 - Fix project import on Git versions before 2.31: query hooks and common Git

package/README.md

@@ -30,6 +30,11 @@ project-knowledge
      agent conversations in real Git workspaces are captured into each
      imported project's Development Conversation.
    It also registers the host-level `project-knowledge` Bridge consumer.
+   ZCode is supported for Development Capture only; an unverified knowledge
+   plugin is never reported as installed. Use `install --ide zcode --capture-only`
+   or System Status → 外部 Agent 采集 in the web UI. Per-client repair/removal
+   preserves unrelated hooks and existing records. Failures include an operation
+   ID and persist to the local system diagnostic log.
    No client UI needs to be opened; third-party hooks and configs are
    preserved, and a Codex notify conflict is reported instead of overwritten.
 3. `project-knowledge` starts a fresh v5 local backend. Import projects again;

package/_site/_test/agent-capture-ui-test.js

@@ -0,0 +1,85 @@
+'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 { createRequire } = require('node:module');
+const coreRoot = path.resolve(process.env.KB_CAPTURE_TEST_CORE_ROOT || path.join(__dirname, '../..'));
+const fromCore = createRequire(path.join(coreRoot, 'package.json'));
+const { createRuntime, initializeRuntime, createRequestHandler } = fromCore('./_site/lib/server-app');
+const { BridgeAdapter } = fromCore('./_site/lib/bridge-adapter');
+const { ModuleBridge } = fromCore('./_site/lib/module-bridge');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+const { Journal } = fromCore('@sanqianx/ai-coding-event-bridge-console/src/bridge');
+const { spawnSync } = require('node:child_process');
+
+async function main() {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-agent-capture-ui-'));
+  const dataDir = path.join(temp, 'data');
+  const homeDir = path.join(temp, '用户 空格');
+  const eventsHome = path.join(dataDir, 'events');
+  const configFile = path.join(homeDir, '.zcode', 'cli', 'config.json');
+  fs.mkdirSync(path.dirname(configFile), { recursive: true });
+  fs.writeFileSync(configFile, JSON.stringify({ provider: { name: 'retain' } }));
+  const offline = http.createServer((req, res) => { res.writeHead(503, { 'content-type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: { message: '本轮测试中非采集模块离线' } })); });
+  await new Promise(resolve => offline.listen(0, '127.0.0.1', resolve));
+  const offlineUrl = `http://127.0.0.1:${offline.address().port}`;
+  const runtime = createRuntime({ dataDir, analysisOwner: 'engine', bridgeAdapter: new BridgeAdapter({ dataDir, bridgeHomeDir: eventsHome }), moduleBridge: new ModuleBridge({ terminalUrl: offlineUrl, engineUrl: offlineUrl, eventBridgeUrl: offlineUrl, vectorHubUrl: offlineUrl }) });
+  await initializeRuntime(runtime);
+  const server = http.createServer(createRequestHandler(runtime, { integrationOptions: { homeDir, env: {}, commandResolver: () => '' } }));
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  let browser;
+  try {
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(temp, 'browser'), url: base, width: 1920, height: 1080 });
+    await browser.setViewport(1920, 1080);
+    const run = expression => browser.evaluate(expression);
+    const click = selector => run(`document.querySelector(${JSON.stringify(selector)}).click()`);
+    await click('#openSystem');
+    await waitFor(() => run("document.querySelectorAll('#agentCaptureList .agent-capture-row').length === 4"), 'four capture statuses');
+    assert.equal(await run("document.querySelector('[data-agent-client=claude]').disabled"), true);
+    assert.equal(await run("document.querySelector('[data-agent-client=zcode]').disabled"), false);
+    assert(await run("document.getElementById('agentCaptureList').textContent.includes('检测到配置')"));
+    await click('[data-agent-client=zcode][data-agent-capture=install]');
+    await waitFor(() => run("document.querySelector('[data-agent-client=zcode][data-agent-capture=uninstall]') !== null"), 'installed status reloaded from backend');
+    const config = JSON.parse(fs.readFileSync(configFile));
+    assert.equal(config.hooks.enabled, true);
+    const hook = config.hooks.events.UserPromptSubmit[0].hooks[0];
+    const env = { ...process.env }; delete env.AI_CODING_EVENT_BRIDGE_HOME; delete env.AI_CODING_EVENT_BRIDGE_CAPTURE;
+    const child = spawnSync(process.execPath, hook.args, { env, input: JSON.stringify({ hook_event_name: 'UserPromptSubmit', session_id: 'ui-zcode-session', cwd: temp, prompt: '从网页接入后写入真实 journal' }), encoding: 'utf8', timeout: 15000 });
+    assert.equal(child.status, 0, child.stderr);
+    const events = await new Journal(path.join(eventsHome, 'journal')).readEvents({});
+    assert.equal(events.length, 1); assert.equal(events[0].source, 'zcode');
+    await click('[data-agent-client=zcode][data-agent-capture=install]');
+    await waitFor(() => run("!document.querySelector('[data-agent-client=zcode]').disabled"), 'repair response');
+    assert.equal(JSON.parse(fs.readFileSync(configFile)).hooks.events.UserPromptSubmit.length, 1);
+    assert.equal(await run('document.documentElement.scrollWidth > innerWidth'), false);
+    const artifacts = path.resolve(process.env.KB_CAPTURE_TEST_ARTIFACTS || path.join(__dirname, '../..', '.agent-state/acceptance/agent-capture'));
+    await browser.screenshot(path.join(artifacts, '1920-light.png'));
+    await click('#closeSystem'); await click('#themeToggle'); await click('#openSystem');
+    await waitFor(() => run("document.querySelector('[data-agent-client=zcode][data-agent-capture=uninstall]') !== null"), 'theme retains capture status');
+    await browser.screenshot(path.join(artifacts, '1920-dark.png'));
+    fs.writeFileSync(configFile, '{invalid JSON');
+    await click('[data-agent-client=zcode][data-agent-capture=install]');
+    await waitFor(() => run("document.getElementById('agentCaptureFeedback').textContent.includes('操作 ID')"), 'partial failure rendered');
+    assert(await run("document.getElementById('agentCaptureFeedback').classList.contains('issue')"));
+    const logs = (await (await fetch(base + '/api/logs?event=integration.capture.failed')).json()).entries;
+    assert(logs.length > 0 && logs[0].error.message.includes('valid JSON'));
+    fs.writeFileSync(configFile, JSON.stringify(config));
+    await click('#refreshAgentCapture');
+    await waitFor(() => run("document.querySelector('[data-agent-client=zcode][data-agent-capture=uninstall]') !== null"), 'manual status retry');
+    await click('[data-agent-client=zcode][data-agent-capture=uninstall]');
+    await waitFor(() => run("!document.querySelector('[data-agent-client=zcode]').disabled && document.querySelector('[data-agent-client=zcode][data-agent-capture=uninstall]') === null"), 'removed capture status');
+    assert.equal(JSON.parse(fs.readFileSync(configFile)).provider.name, 'retain');
+    assert.equal((await new Journal(path.join(eventsHome, 'journal')).readEvents({})).length, 1, 'removal retains prior evidence');
+    assert.equal(browser.exceptions.length, 0, JSON.stringify(browser.exceptions));
+    console.log(`agent-capture-ui-test PASS (1920x1080; real install/repair/Hook/journal/error logs/removal/light+dark; core=${coreRoot})`);
+  } finally {
+    await browser?.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
+    offline.closeAllConnections(); await new Promise(resolve => offline.close(resolve)); await runtime.logger.close();
+    fs.rmSync(temp, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+main().catch(error => { console.error(error.stack); process.exitCode = 1; });

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

@@ -0,0 +1,107 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { spawnSync } = require('child_process');
+const { IntegrationManager, normalizeClient, SUPPORTED_CLIENTS } = require('../lib/integration-installer');
+const { createRuntime, createRequestHandler } = require('../lib/server-app');
+const { BridgeAdapter } = require('../lib/bridge-adapter');
+const { Logger, LogRepository } = require('../lib/structured-logger');
+const { StorageLayout } = require('../lib/storage-layout');
+const { runCli } = require('../../bin/project-knowledge-integrations');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-zcode-capture-'));
+  const homeDir = path.join(temp, '用户 空格');
+  const bridgeHomeDir = path.join(temp, 'events');
+  const configFile = path.join(homeDir, '.zcode', 'cli', 'config.json');
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const logger = new Logger({ layout });
+  const options = { homeDir, env: {}, bridgeHomeDir, zcodeConfigFile: configFile, commandResolver: () => '', logger };
+  const manager = new IntegrationManager(options);
+  let server;
+  try {
+    assert(SUPPORTED_CLIENTS.includes('zcode'));
+    assert.equal(normalizeClient(' ZCode '), 'zcode');
+    assert.deepEqual(manager.detectClients(), []);
+    const before = await manager.statusAll();
+    assert.equal(before.clients.length, 4, 'status includes tools not found without installing them');
+    assert.equal(before.clients.find(a => a.client === 'zcode').developmentCapture.installed, false);
+    assert(!fs.existsSync(configFile), 'status and uninstall must not manufacture user config');
+    await manager.operateCapture('uninstall', ['zcode']);
+    assert(!fs.existsSync(configFile));
+
+    fs.mkdirSync(path.dirname(configFile), { recursive: true });
+    const thirdParty = { type: 'process', command: 'other', args: ['third-party'] };
+    fs.writeFileSync(configFile, JSON.stringify({ provider: { name: '保留' }, hooks: { enabled: false, events: { Stop: [{ hooks: [thirdParty] }] } } }));
+    assert.deepEqual(manager.detectClients(), ['zcode'], 'desktop ZCode config is discoverable without a PATH CLI');
+    const installed = await manager.installAll({ clients: ['zcode'], captureOnly: true });
+    assert(installed.bridge.ok && installed.clients[0].developmentCapture.ok);
+    assert.equal(installed.clients[0].knowledgeIntegration, undefined);
+    const config = JSON.parse(fs.readFileSync(configFile));
+    assert.equal(config.hooks.enabled, true);
+    assert.equal(config.provider.name, '保留');
+    assert(config.hooks.events.Stop[0].hooks.some(h => h.command === 'other'));
+    await manager.installAll({ clients: ['zcode'], captureOnly: true });
+    const twice = JSON.parse(fs.readFileSync(configFile));
+    assert.equal(twice.hooks.events.UserPromptSubmit.length, 1);
+    assert.equal(twice.hooks.events.Stop.length, 2);
+    const status = await manager.statusAll({ clients: ['zcode'] });
+    assert(status.clients[0].configFound && status.clients[0].developmentCapture.installed);
+    assert.equal(status.clients[0].knowledgeIntegration.installed, false);
+    assert.equal(status.clients[0].knowledgeIntegration.supported, false, 'capture never claims an unverified retrieval plugin');
+    assert.equal(await runCli(['update', '--ide', 'zcode', '--capture-only', '--json'], { manager }), 0);
+    const dry = new IntegrationManager({ ...options, dryRun: true });
+    const untouched = fs.readFileSync(configFile, 'utf8');
+    await runCli(['uninstall', '--ide', 'zcode', '--capture-only', '--dry-run'], { manager: dry });
+    assert.equal(fs.readFileSync(configFile, 'utf8'), untouched);
+
+    const runtime = createRuntime({ dataDir: layout.getDataDir(), logger, analysisOwner: 'engine', bridgeAdapter: new BridgeAdapter({ dataDir: layout.getDataDir(), bridgeHomeDir }) });
+    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}`;
+    const request = async (route, body) => {
+      const response = await fetch(base + route, body ? { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) } : {});
+      assert.equal(response.status, 200);
+      return response.json();
+    };
+    const apiInstall = await request('/api/integrations/install', { clients: ['zcode'], captureOnly: true });
+    assert.equal(apiInstall.complete, true);
+    assert(apiInstall.operationId);
+    const apiStatus = await request('/api/integrations/status');
+    assert(apiStatus.clients.find(a => a.client === 'zcode').developmentCapture.installed);
+    fs.writeFileSync(configFile, '{invalid JSON');
+    const failed = await request('/api/integrations/install', { clients: ['zcode'], captureOnly: true });
+    assert.equal(failed.complete, false, 'HTTP 200 does not imply capture succeeded');
+    assert.equal(failed.clients[0].developmentCapture.ok, false);
+    assert(failed.clients[0].developmentCapture.error.code);
+    await logger.flush();
+    const errors = new LogRepository({ layout }).query({ event: 'integration.capture.failed' }).entries;
+    assert(errors.some(entry => entry.operationId === failed.operationId && entry.context.client === 'zcode' && entry.error.message.includes('valid 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(removed.complete, true);
+    assert.deepEqual(removed.clients, [], 'capture-only removal does not invoke knowledge plugin operations');
+    assert.equal(removed.capture[0].state, 'removed');
+    const after = JSON.parse(fs.readFileSync(configFile));
+    assert.equal(after.provider.name, '保留');
+    assert.deepEqual(after.hooks.events.Stop[0].hooks, [thirdParty]);
+    assert.equal((await manager.statusAll({ clients: ['zcode'] })).clients[0].developmentCapture.installed, false);
+    const facade = manager._bridgeFacade();
+    assert(await facade.getConsumer('project-knowledge'), 'removing one connector retains the host consumer');
+
+    const cliEnv = { ...process.env, USERPROFILE: homeDir, HOME: homeDir, KB_DATA_DIR: layout.getDataDir(), AI_CODING_EVENT_BRIDGE_HOME: bridgeHomeDir };
+    const cli = spawnSync(process.execPath, [path.resolve(__dirname, '../../bin/project-knowledge-integrations.js'), 'install', '--ide', 'zcode', '--capture-only', '--json'], { env: cliEnv, encoding: 'utf8', timeout: 15000 });
+    assert.equal(cli.status, 0, cli.stderr);
+    assert(JSON.parse(cli.stdout).clients[0].developmentCapture.installed);
+    await logger.flush();
+    assert(new LogRepository({ layout }).query({ event: 'integration.capture.completed' }).entries.length > 0, 'CLI operations also write durable logs');
+    console.log('zcode-capture-integration-test PASS');
+  } finally {
+    if (server) { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); }
+    await logger.close();
+    // This test owns a single mkdtemp sandbox, never real Agent configs.
+    fs.rmSync(temp, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+})().catch(error => { console.error(error.stack); process.exitCode = 1; });

package/_site/lib/integration-installer.js

@@ -20,17 +20,19 @@ try {
 const INTEGRATION_NAME = 'project-knowledge';
 const MARKETPLACE_NAME = 'project-knowledge';
 const DEFAULT_MARKETPLACE_SOURCE = 'SanQianX/project-knowledge-base';
-const SUPPORTED_CLIENTS = ['claude', 'opencode', 'codex'];
+const SUPPORTED_CLIENTS = ['claude', 'opencode', 'codex', 'zcode'];
 const DEFAULT_BRIDGE_CONSUMER = 'project-knowledge';
 const CLIENT_LABELS = {
   claude: 'Claude Code',
   opencode: 'OpenCode',
   codex: 'Codex',
+  zcode: 'ZCode',
 };
 const CLIENT_METHOD_SUFFIX = {
   claude: 'Claude',
   opencode: 'OpenCode',
   codex: 'Codex',
+  zcode: 'ZCode',
 };
 
 function normalizeClient(value) {
@@ -323,26 +325,28 @@ class IntegrationManager {
     this.commandResolver = options.commandResolver || defaultCommandResolver;
     this.dryRun = Boolean(options.dryRun);
     this.logger = options.logger || null;
+    this.operationId = options.operationId || '';
     this.planned = [];
     this.bridge = options.bridgeModule || bridgeModule;
     this.bridgeConsumerName = options.bridgeConsumerName || DEFAULT_BRIDGE_CONSUMER;
     this.bridgeHomeDir = options.bridgeHomeDir
       || this.env.AI_CODING_EVENT_BRIDGE_HOME
       || path.join(resolveDataDirPath({ dataDir: this.env.KB_DATA_DIR || '', homeDir: this.homeDir }), 'events');
-    this.claudeSettingsFile = options.claudeSettingsFile || '';
-    this.codexConfigFile = options.codexConfigFile || '';
-    this.openCodePluginsDir = options.openCodePluginsDir || '';
+    this.claudeSettingsFile = options.claudeSettingsFile || path.join(this.homeDir, '.claude', 'settings.json');
+    this.codexConfigFile = options.codexConfigFile || path.join(this.homeDir, '.codex', 'config.toml');
+    this.openCodePluginsDir = options.openCodePluginsDir || path.join(openCodeConfigDir(this.homeDir, this.env), 'plugin');
+    this.zcodeConfigFile = options.zcodeConfigFile || path.join(this.homeDir, '.zcode', 'cli', 'config.json');
   }
 
   _bridgeFacade() {
     return this.bridge.createBridge({ homeDir: this.bridgeHomeDir });
   }
 
-  _captureInstallerOptions() {
+  _captureInstallerOptions(client) {
     return {
       homeDir: this.bridgeHomeDir,
       settingsFile: this.claudeSettingsFile || undefined,
-      configFile: this.codexConfigFile || undefined,
+      configFile: client === 'zcode' ? this.zcodeConfigFile : this.codexConfigFile,
       pluginsDir: this.openCodePluginsDir || undefined,
     };
   }
@@ -382,6 +386,42 @@ class IntegrationManager {
 
   // ---- Development Capture connectors (Bridge hooks / notify / plugin) ----
 
+  async captureOperation(operation, client, options = {}) {
+    const startedAt = Date.now();
+    const context = { client, operation };
+    try {
+      const result = await this[`${operation}Capture${CLIENT_METHOD_SUFFIX[client]}`](options);
+      const ok = !result.conflict && result.state !== 'failed';
+      if (operation !== 'status' || !ok) this.log(ok ? 'info' : 'error', `integration.capture.${ok ? 'completed' : 'failed'}`, ok ? 'Agent 采集接线操作完成。' : 'Agent 采集接线未完成。', { operationId: this.operationId, durationMs: Date.now() - startedAt, error: ok ? undefined : Object.assign(new Error(result.detail), { code: 'CAPTURE_CONFLICT' }), context });
+      return { ok, ...result, ...(!ok ? { error: { code: 'CAPTURE_CONFLICT', message: result.detail } } : {}) };
+    } catch (error) {
+      this.log('error', 'integration.capture.failed', 'Agent 采集接线操作失败。', { operationId: this.operationId, durationMs: Date.now() - startedAt, error, context });
+      return { ok: false, state: 'failed', installed: false, detail: error.message, error: { code: error.code || 'CAPTURE_FAILED', message: error.message } };
+    }
+  }
+
+  async installCaptureZCode() {
+    if (this.dryRun) {
+      this.planned.push({ command: 'bridge', args: ['installZcodeHook', this.bridgeHomeDir] });
+      return { state: 'planned', installed: false, detail: '计划接入 ZCode 会话采集，未修改配置。' };
+    }
+    await this.bridge.installers.zcode.installZcodeHook(this._captureInstallerOptions('zcode'));
+    const status = await this.statusCaptureZCode();
+    if (!status.installed) throw new Error('ZCode Hook 写入后校验失败，请检查 hooks.enabled 与事件配置。');
+    return status;
+  }
+
+  async statusCaptureZCode() {
+    const status = await this.bridge.installers.zcode.statusZcodeHook(this._captureInstallerOptions('zcode'));
+    return { state: status.installed ? 'installed' : 'not-installed', installed: status.installed, conflict: false, detail: status.installed ? '已配置用户输入与回答采集；请重新打开 ZCode 会话。' : 'ZCode 会话采集尚未接入。' };
+  }
+
+  async uninstallCaptureZCode() {
+    if (this.dryRun) return { state: 'planned', detail: '计划移除 ZCode 采集，未修改配置。' };
+    await this.bridge.installers.zcode.uninstallZcodeHook(this._captureInstallerOptions('zcode'));
+    return { state: 'removed', installed: false, detail: '已移除 ZCode 托管采集，保留第三方配置与已有记录。' };
+  }
+
   async installCaptureClaude() {
     if (this.dryRun) {
       this.planned.push({ command: 'bridge', args: ['installClaudeCodeHook', this.bridgeHomeDir] });
@@ -397,7 +437,7 @@ class IntegrationManager {
       state: status.installed ? 'installed' : 'not-installed',
       installed: status.installed,
       conflict: false,
-      detail: status.installed ? `managed events: ${status.managedEvents.join(', ')}` : 'managed hooks not installed',
+      detail: status.installed ? '已配置用户输入与回答采集。' : '会话采集 Hook 尚未配置。',
     };
   }
 
@@ -453,7 +493,7 @@ class IntegrationManager {
       state: status.installed ? 'installed' : status.thirdParty ? 'conflict' : 'not-installed',
       installed: Boolean(status.installed),
       conflict: Boolean(status.thirdParty),
-      detail: status.installed ? 'managed notify installed' : status.thirdParty ? 'third-party notify present' : 'notify not installed',
+      detail: status.installed ? '已配置提交回合后的会话采集。' : status.thirdParty ? '已有第三方通知配置，不会覆盖；请查看诊断记录。' : '会话采集通知尚未配置。',
     };
   }
 
@@ -481,7 +521,7 @@ class IntegrationManager {
       state: status.installed ? 'installed' : 'not-installed',
       installed: Boolean(status.installed),
       conflict: false,
-      detail: status.installed ? 'managed plugin installed' : `plugin not installed (${status.thirdPartyFiles} third-party files preserved)`,
+      detail: status.installed ? '已配置会话采集插件。' : '会话采集插件尚未配置，保留其他插件。',
     };
   }
 
@@ -510,9 +550,21 @@ class IntegrationManager {
   }
 
   detectClients() {
-    return SUPPORTED_CLIENTS.filter(client => Boolean(this.executable(client)));
+    return SUPPORTED_CLIENTS.filter(client => Boolean(this.executable(client)) || client === 'zcode' && this.captureConfigFound(client));
   }
 
+  captureConfigFound(client) {
+    const target = { claude: this.claudeSettingsFile, codex: this.codexConfigFile, opencode: path.dirname(this.openCodePluginsDir), zcode: this.zcodeConfigFile }[client];
+    try { const stat = fs.statSync(target); return client === 'opencode' ? stat.isDirectory() : stat.isFile(); } catch { return false; }
+  }
+
+  // Capture support does not imply a verified MCP/plugin installer. Never
+  // present ZCode knowledge retrieval as installed merely because hooks exist.
+  statusZCode() { return { state: 'not-supported', supported: false, installed: false, detail: 'ZCode 当前支持会话采集；知识检索插件未接入，不会自动安装。' }; }
+  installZCode() { return this.statusZCode(); }
+  updateZCode() { return this.statusZCode(); }
+  uninstallZCode() { return this.statusZCode(); }
+
   execute(client, args, options = {}) {
     const startedAt = Date.now();
     const command = this.executable(client);
@@ -805,13 +857,7 @@ class IntegrationManager {
     const results = [];
     for (const rawClient of clients) {
       const client = normalizeClient(rawClient);
-      const suffix = CLIENT_METHOD_SUFFIX[client];
-      try {
-        const result = await this[`${operation}Capture${suffix}`](options);
-        results.push({ client, label: CLIENT_LABELS[client], ok: true, ...result });
-      } catch (error) {
-        results.push({ client, label: CLIENT_LABELS[client], ok: false, state: 'failed', detail: error.message });
-      }
+      results.push({ client, label: CLIENT_LABELS[client], ...(await this.captureOperation(operation, client, options)) });
     }
     return results;
   }
@@ -839,11 +885,7 @@ class IntegrationManager {
         }
       }
       if (options.knowledgeOnly !== true) {
-        try {
-          entry.developmentCapture = { ok: true, ...(await this[`installCapture${suffix}`]()) };
-        } catch (error) {
-          entry.developmentCapture = { ok: false, state: 'failed', detail: error.message };
-        }
+        entry.developmentCapture = await this.captureOperation('install', client);
       }
       summary.clients.push(entry);
     }
@@ -851,7 +893,7 @@ class IntegrationManager {
   }
 
   async statusAll(options = {}) {
-    const clients = options.clients && options.clients.length ? options.clients.map(normalizeClient) : this.detectClients();
+    const clients = options.clients && options.clients.length ? options.clients.map(normalizeClient) : SUPPORTED_CLIENTS;
     const summary = { clients: [], bridge: null };
     try {
       summary.bridge = { ok: true, ...(await this.bridgeStatus()) };
@@ -860,17 +902,15 @@ class IntegrationManager {
     }
     for (const client of clients) {
       const suffix = CLIENT_METHOD_SUFFIX[client];
-      const entry = { client, label: CLIENT_LABELS[client], available: Boolean(this.executable(client)) };
-      try {
-        entry.knowledgeIntegration = { ok: true, ...(await this[`status${suffix}`]()) };
-      } catch (error) {
-        entry.knowledgeIntegration = { ok: false, state: 'failed', detail: error.message };
-      }
-      try {
-        entry.developmentCapture = { ok: true, ...(await this[`statusCapture${suffix}`]()) };
-      } catch (error) {
-        entry.developmentCapture = { ok: false, state: 'failed', detail: error.message };
+      const entry = { client, label: CLIENT_LABELS[client], available: Boolean(this.executable(client)), configFound: this.captureConfigFound(client) };
+      if (!options.captureOnly) {
+        try {
+          entry.knowledgeIntegration = { ok: true, ...(await this[`status${suffix}`]()) };
+        } catch (error) {
+          entry.knowledgeIntegration = { ok: false, state: 'failed', detail: error.message };
+        }
       }
+      entry.developmentCapture = await this.captureOperation('status', client);
       summary.clients.push(entry);
     }
     return summary;
@@ -881,6 +921,7 @@ class IntegrationManager {
   async disableAllCapture(options = {}) {
     const clients = options.clients && options.clients.length ? options.clients.map(normalizeClient) : SUPPORTED_CLIENTS;
     const results = await this.operateCapture('uninstall', clients, { unregisterConsumer: false });
+    if (results.some(result => !result.ok)) return { clients: results, consumer: { ok: false, state: 'kept', detail: '部分采集未能移除，保留宿主消费者，请修复失败项后重试。' } };
     let consumer = null;
     try {
       consumer = { ok: true, ...(await this.unregisterBridgeConsumer()) };

package/_site/lib/server-app.js

@@ -1292,13 +1292,13 @@ function createRequestHandler(runtime, options = {}) {
       // Unified Integration Setup surface: one action manages Knowledge
       // Integration and Development Capture per client, with separate status.
       if (method === 'GET' && pathname === '/api/integrations/status') {
-        const manager = new IntegrationManager({ rootDir: runtime.rootDir });
-        const summary = await manager.statusAll({});
+        const manager = new IntegrationManager({ ...options.integrationOptions, rootDir: runtime.rootDir, logger: runtime.logger, operationId: requestOperationId, bridgeHomeDir: runtime.bridgeAdapter.hookBinding().bridgeHomeDir });
+        const summary = await manager.statusAll({ captureOnly: url.searchParams.get('captureOnly') === '1' });
         return send(res, 200, { ok: true, ...summary });
       }
       if (method === 'POST' && pathname === '/api/integrations/install') {
         const body = await readJsonBody(req);
-        const manager = new IntegrationManager({ rootDir: runtime.rootDir });
+        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))
           : undefined;
@@ -1308,12 +1308,13 @@ function createRequestHandler(runtime, options = {}) {
           captureOnly: body.captureOnly === true,
           scope: body.scope || 'user',
         });
-        await runtime.logger.info('integrations.install_completed', 'Integration setup completed.', { context: { clients: summary.clients.map(entry => entry.client) } });
-        return send(res, 200, { ok: true, ...summary });
+        const complete = summary.bridge.ok && summary.clients.every(entry => (!entry.knowledgeIntegration || entry.knowledgeIntegration.ok) && (!entry.developmentCapture || entry.developmentCapture.ok));
+        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 });
       }
       if (method === 'POST' && pathname === '/api/integrations/uninstall') {
         const body = await readJsonBody(req);
-        const manager = new IntegrationManager({ rootDir: runtime.rootDir });
+        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({});
           return send(res, 200, { ok: true, ...summary });
@@ -1321,9 +1322,9 @@ function createRequestHandler(runtime, options = {}) {
         const clients = Array.isArray(body.clients) && body.clients.length
           ? body.clients.map(client => String(client))
           : undefined;
-        const knowledgeResults = await manager.operate('uninstall', clients && clients.length ? clients : manager.detectClients(), { scope: body.scope || 'user' });
+        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, clients: knowledgeResults, capture: captureResults });
+        return send(res, 200, { ok: true, complete: [...knowledgeResults, ...captureResults].every(entry => entry.ok), operationId: requestOperationId, clients: knowledgeResults, capture: captureResults });
       }
 
       if (method === 'GET' && pathname === '/api/ai-profiles') {

package/bin/project-knowledge-integrations.js

@@ -5,6 +5,8 @@ const {
   SUPPORTED_CLIENTS,
   normalizeClient,
 } = require('../_site/lib/integration-installer');
+const { Logger } = require('../_site/lib/structured-logger');
+const { createId } = require('../_site/lib/contracts');
 
 function printHelp() {
   console.log(`project-knowledge-integrations
@@ -23,6 +25,7 @@ Clients:
   claude       Claude Code plugin (MCP + Skill) + managed Bridge hooks
   opencode     OpenCode MCP + global Skill + managed Bridge plugin
   codex        Codex plugin (MCP + Skill) + managed Bridge notify
+  zcode        ZCode managed Bridge hooks (capture only; no verified MCP installer)
   all          All supported clients
 
 Options:
@@ -99,7 +102,7 @@ function selectClients(requested, manager) {
 
 function printCapabilityLine(prefix, capability) {
   if (!capability) return;
-  const mark = capability.ok ? 'OK' : 'FAIL';
+  const mark = capability.supported === false ? 'INFO' : capability.ok ? 'OK' : 'FAIL';
   console.log(`  [${mark}] ${prefix}: ${capability.state} - ${capability.detail}`);
 }
 
@@ -109,10 +112,18 @@ async function runCli(argv = process.argv.slice(2), dependencies = {}) {
     printHelp();
     return 0;
   }
+  const logger = dependencies.manager ? null : new Logger();
   const manager = dependencies.manager || new IntegrationManager({
+    logger,
+    operationId: createId('op'),
     dryRun: options.dryRun,
     marketplaceSource: options.marketplaceSource || undefined,
   });
+  try { return await runOperation(options, manager); }
+  finally { if (logger) await logger.close(); }
+}
+
+async function runOperation(options, manager) {
   const clients = selectClients(options.clients, manager);
 
   if (options.operation === 'disable-capture') {
@@ -130,7 +141,7 @@ async function runCli(argv = process.argv.slice(2), dependencies = {}) {
     return summary.clients.some(result => !result.ok) || !summary.consumer.ok ? 1 : 0;
   }
 
-  if (options.operation === 'install') {
+  if (options.operation === 'install' || options.operation === 'update' && options.captureOnly) {
     // One action configures Knowledge Integration + Development Capture
     // together (per-client flags narrow the scope). No client UI is needed.
     const summary = await manager.installAll({ clients, knowledgeOnly: options.knowledgeOnly, captureOnly: options.captureOnly, scope: options.scope });

package/docs/README.zh-CN.md

@@ -85,6 +85,23 @@ vector-hub 是唯一派生索引服务，外壳不再执行第二套索引写入
 
 ## 需求记录与查询
 
+### 外部 Agent 会话采集
+
+在网页左下角打开“系统状态 → 外部 Agent 采集”，对使用的工具点击“接入”或
+“修复”；“移除采集”只移除托管 Hook，不删除历史记录或第三方配置。
+“检测到命令/检测到配置”与“已配置采集”是不同状态，未检测到不等于没有安装。
+配置完成后重新打开外部 Agent 会话，再到活动记录验证新会话是否出现。
+
+```powershell
+project-knowledge-integrations status --all
+project-knowledge-integrations install --ide zcode --capture-only
+project-knowledge-integrations uninstall --ide zcode --capture-only
+```
+
+ZCode 接入当前仅包含会话采集，不会冒充已安装 MCP/知识检索插件。
+接入失败会显示操作 ID，并写入数据目录 `logs/system/YYYY-MM-DD.jsonl`；
+网页“系统诊断记录”可查看和导出。注册消费者本身不能代替安装 Agent Hook。
+
 Claude Code、Codex、OpenCode 集成可在编码前追加用户真实需求元数据。记录写入
 项目 `requirements.jsonl`，不会触发分析或写知识。
 

package/module-runtime-manifest.json

@@ -1,9 +1,9 @@
 {
   "schema": "project-knowledge/module-content/v1",
   "productFiles": {
-    "ui/index.html": "d090decbb17ffc17ac2ac0ec63b69979e0436d712959e5ca49a02d6d9de7e59d",
-    "ui/product.js": "3d04538ca38f6cc1b85ae0337d61c244b6769e4f15f9d029e8ab096991d17dfb",
-    "ui/product.css": "1e68f087cec85a69f4497492d31fd1dd8712cf5176b0c721ce765de36ce606e1"
+    "ui/index.html": "e7291caab778eba3c5499d8286804ad1f4ef31c87a957f69c8fb77befc01321b",
+    "ui/product.js": "1a6ddedd97b00c3f798c13a0a55b0f63790e701483492bc97d28cae4034efaf8",
+    "ui/product.css": "73554abf3f951ea01a2bfe2df81748b702a6ca4488eea16bfe5afe04ef1dea70"
   },
   "modules": {
     "terminal": {
@@ -174,17 +174,17 @@
     "eventBridge": {
       "name": "@sanqianx/ai-coding-event-bridge-console",
       "installName": "@sanqianx/ai-coding-event-bridge-console",
-      "version": "0.7.1",
+      "version": "0.7.2",
       "files": {
         "LICENSE": "94a3bded67f76ec9f6333ad3370111bcb6e5cadbeb6f306a8112f9543320ecc2",
-        "README.md": "847242d93395aae17b42bbaa7fc8e36e6f89edecf11a1639b94b34c98729e1a9",
-        "console/index.html": "680e6393c9ef88ea35c1eabff537e0b10f7a91c55986f18bca6bfe2a333eed6e",
-        "package.json": "a6c9fc47669a5aa64dd48d38d3fc2b4fb07322cfb41bbd42b0ac174f37560715",
-        "src/agent-detect.js": "06d58150c4295f7d5980ac47fd6fb1a680f1b7c27fd3dcd3f57049825dc5f092",
+        "README.md": "4699558a9498f93a83587523ef5cae019d2146867f355134ea27100ac6245769",
+        "console/index.html": "bdc61db0ca9e6b5d8886418c1c03df141f39ab722f50d0c16bba75fe57ac46f0",
+        "package.json": "f6b965a9ce9440039d96767c7d126a8149cffa56559693955cca15b0707bcd60",
+        "src/agent-detect.js": "2a4752218e6cdb4151ae9796b23558c2dd94b55217a20fa1f1a76f506bb2f781",
         "src/bin.js": "e443cfabb8df1a694c9e2415a292db81f183d9e31b7fe8f5f9a14d2a09d03052",
         "src/bridge/bin/commit-boundary.js": "2c87126d9d6467ddae13acc1d0997f2124a68174738b8cd6f8614e7eeccb3d0d",
         "src/bridge/connectors/capture-guard.js": "aa9c51a6012966c5b6eb66a40b61ada61fd2cfd43fd4f6985d7b655421e8a1e3",
-        "src/bridge/connectors/claude-code/hook-entry.js": "abc224d4f76d372bc02649c5e1005674d089a3dbd83e09ce4c35a33b3a75c937",
+        "src/bridge/connectors/claude-code/hook-entry.js": "c88b9ace27e4d148ee7b04724ec2f990a0c71c6e59a4d22afb4c9a8e2e72048e",
         "src/bridge/connectors/claude-code/notify.js": "4325684ac92c1a2e531aefc5cbcbc886dc2b58080c410ee5e879574593f077cd",
         "src/bridge/connectors/codex/cursor-store.js": "077784e9c6b895dde95247706381dbaca68892e1382f3a957c3e90efb51059f5",
         "src/bridge/connectors/codex/hook-entry.js": "d180a3713609b251ba8a9fdffbcf202346b1098ce4e07cd3ae696216a9f56e96",
@@ -199,21 +199,21 @@
         "src/bridge/core/journal-router.js": "5fe48ae4240034f030807c80bdba35c6ef2cb7bfa3fa310105ce0fb77d272131",
         "src/bridge/core/journal.js": "13c72396c970e6acd9a97900a926daa108aded01d8bb3735213e0feff8aa20b6",
         "src/bridge/core/lock.js": "484988ce593d138183e7d94648ece97c88661e7fa8379f0ef7335a634fe15ba3",
-        "src/bridge/core/normalizer.js": "34b4023efada0cfdcaaba98775b072041eaf623eb7fde48953654dc27d470ae1",
+        "src/bridge/core/normalizer.js": "e8eaa3582538c8f45dfc8d3ceb21c1e2f46347917d086436cfd361d32f62302e",
         "src/bridge/core/paths.js": "6e829c00105d3b9214942f33af6225b338c668ff4cdda5c3ab92cb759d54be30",
         "src/bridge/core/project-registry.js": "8c5cc8e18d55af1a0c2d682c25ea1c37eb6f4687cf3eaa5997fc57532560d866",
         "src/bridge/core/repo-context.js": "1627d416fd6aaa43d8c4be8ce5097bb69244b1afe7f1ce5e9f71956c5542ce3f",
-        "src/bridge/core/runtime-home.js": "e68a3c927b02ca27299755c60c8f709f7ce97c9f4c5080deefe518bf60d9d989",
+        "src/bridge/core/runtime-home.js": "f2bfffba20c8256259cecc1014261897a4d6f721807c04b2e4d2b3dc973f14e1",
         "src/bridge/core/semver.js": "7f87ed40f3af3ae0480abc9934946358f0caa5d951472d5892b088aa468ec0f1",
         "src/bridge/core/turn-identity.js": "4ee79410d0122ca93cea565591c183db6bff64b0a467f50a4e590de4ee78c399",
         "src/bridge/index.js": "7f56d08fdcfa815a45f50c73b27d0627497ac364da55cd8e6635351f734b57b2",
         "src/bridge/installers/claude-code/installer.js": "c0a8a39d654e886fad838a54a2acb535096384d6307c88eb5dc813992efefbd2",
         "src/bridge/installers/codex/installer.js": "0c8542c2320b7e7b654ad22163bd5ee26f3792545f521e096ee5c795f2ec9303",
         "src/bridge/installers/opencode/installer.js": "27f2ed3629e55b4ee083c6d0d4ceafc614145102ead2ba99630ad979c120ab08",
-        "src/bridge/installers/zcode/installer.js": "8bca7dfd4a31cf632a86480282c28a665ee23dc3838d643dcd883db6cc053af7",
+        "src/bridge/installers/zcode/installer.js": "625343d6a9fc81b81fb3d1fcd12ac6cdf6d33fae45925631db88aaf74fe497ff",
         "src/bridge/query/conversation-query.js": "89db83f3f4bf5e2807603589da9fa03b4b494e1cb94afc772e57572ccdcb0854",
         "src/pick-folder.js": "70f55df999262b90433f2b4251aa69dd70a23b55a84756b5f1d24dbeacfbda31",
-        "src/server.js": "b2b62e5e7404d82dfc6e749d1860e3cfa072a9f669e61777355eed33762e6b5d"
+        "src/server.js": "d521073673b4e1cc84cc9fab46aae5c07f3274f7cdcf20f78696b7808be5103c"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {
@@ -80,7 +80,7 @@
     "@huggingface/transformers": "3.8.1",
     "@lancedb/lancedb": "0.31.0",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@sanqianx/ai-coding-event-bridge-console": "0.7.1",
+    "@sanqianx/ai-coding-event-bridge-console": "0.7.2",
     "@sanqianx/vector-hub": "1.0.7",
     "buffer": "^6.0.3",
     "cheerio": "^1.2.0",

package/plugins/project-knowledge/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "project-knowledge",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "project-knowledge",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.mcp.json

@@ -6,7 +6,7 @@
       "args": [
         "-y",
         "--package",
-        "@sanqianx/project-knowledge@5.0.1",
+        "@sanqianx/project-knowledge@5.0.2",
         "project-knowledge-mcp"
       ]
     }

package/ui/index.html

@@ -37,6 +37,7 @@
   <header><h2>系统状态</h2><button id="closeSystem" class="icon-button" aria-label="关闭系统状态">×</button></header>
   <div class="drawer-content">
     <section><h3>模块连接</h3><div id="moduleHealth"></div><button id="repairWiring">修复当前项目接线</button><p class="muted" id="wiringFeedback"></p><p class="muted" id="captureStatus"></p></section>
+    <section id="agentCaptureSection"><div class="actions"><h3>外部 Agent 采集</h3><button id="refreshAgentCapture">检查状态</button></div><p class="muted">只接入你使用的工具。采集外部开发会话，不会重新安装 Agent，也不影响已有记录。</p><div id="agentCaptureList"></div><p id="agentCaptureFeedback" class="feedback" role="status"></p></section>
     <section><h3>后台维护模型</h3><p class="muted">使用持久化默认模型，不跟随聊天中的临时切换。</p><select id="maintenanceModel" aria-label="后台维护默认模型"></select><div class="actions"><button id="saveMaintenance">保存默认模型</button><button id="configureProviders">管理模型供应商</button></div><p id="configurationStatus" class="muted"></p></section>
     <section><h3>向量检索模型</h3><p id="embeddingStatus" class="muted">正在读取配置。</p><button id="openEmbedding">配置向量模型</button><p class="muted">凭据由工作台统一保存。未配置时仍可使用文本检索。</p></section>
     <section><h3>智脑设置</h3><label>名称<input id="brainName" maxlength="100"></label><label>知识根目录<div class="input-with-action"><input id="knowledgeRoot"><button id="pickRoot">选择</button></div></label><p class="muted">修改根目录不会移动已有项目知识或共享知识。</p><button id="saveBrainSettings">保存设置</button></section>

package/ui/product.css

@@ -1,4 +1,5 @@
 :root{--page:#f3f5f7;--surface:#fff;--surface2:#f8f9fb;--surface3:#edf1f4;--line:#dce2e8;--text:#202733;--muted:#687587;--faint:#8e99a7;--nav:#eef1f4;--accent:#516f89;--accent-soft:#e6edf3;--good:#397761;--bad:#a05252;--bad-soft:#fbeeee;color-scheme:light}
+.agent-capture-row{display:flex;align-items:center;gap:16px;padding:16px 0;border-bottom:1px solid var(--line)}.agent-capture-row>div:first-child{flex:1;min-width:0}.agent-capture-row small{display:block;color:var(--muted);margin-top:8px;overflow-wrap:anywhere}.agent-capture-row .actions{flex-shrink:0}#agentCaptureFeedback{white-space:pre-wrap}
 #logsDialog{display:flex;flex-direction:column;overflow:hidden}#logsDialog:not([open]){display:none}#logsContent{overflow:auto;min-height:0;flex:1;margin-top:16px}#logsContent .row{align-items:flex-start;cursor:pointer}#logsContent pre{flex:1;min-width:0;margin:0}#logsContent .log-entry{border-bottom:1px solid var(--line)}#logsContent .log-detail{padding:16px;background:var(--surface2);max-height:320px;overflow:auto}#logsContent [data-level=warn],#logsContent [data-level=error],#logsContent [data-level=fatal]{color:var(--bad)}#logsContent .row time,#logsContent .row pre{color:inherit}
 @media(prefers-reduced-motion:reduce){*,*::before,*::after{scroll-behavior:auto!important;animation:none!important;transition:none!important}}
 .knowledge-context{overflow-x:hidden}.reference{overflow-wrap:anywhere}.reference small{min-width:0;max-width:100%}

package/ui/product.js

@@ -19,6 +19,7 @@
   const label = run => ({ queued: '排队', running: '维护中', succeeded: '已更新 · 可检索', 'index-pending': '知识已更新 · 索引待修复', failed: '维护失败', cancelled: '已取消' })[run.state] || run.state;
   const badge = (text, status = '') => `<span class="status ${esc(status)}">${esc(text)}</span>`;
   let toastTimer, refreshTimer, preflightTimer, editingMemoryId, logStream, logEpoch = 0, referenceEpoch = 0, snapshotEpoch = 0, registryEpoch = 0, registryPromise = null, resumeImport = false, unbindProjectId = '', unbinding = false;
+  let captureEpoch = 0, captureBusy = false;
   async function api(url, options = {}) {
     const { allowNotReady, ...init } = options;
     if (init.body && typeof init.body !== 'string') init.body = JSON.stringify(init.body);
@@ -182,7 +183,35 @@
   async function openSystem() {
     $('systemDrawer').hidden = false; $('drawerBackdrop').hidden = false;
     $('brainName').value = state.brain.name; $('knowledgeRoot').value = state.root;
-    await loadMaintenance();
+    await Promise.all([loadMaintenance(), loadAgentCapture()]);
+  }
+  async function loadAgentCapture() {
+    const epoch = ++captureEpoch;
+    try {
+      const result = await api('/api/integrations/status?captureOnly=1');
+      if (epoch !== captureEpoch) return;
+      $('agentCaptureList').innerHTML = result.clients.map(agent => {
+        const capture = agent.developmentCapture;
+        const found = agent.available || agent.configFound;
+        const software = agent.available ? '检测到命令' : agent.configFound ? '检测到配置' : '未检测到';
+        const status = !capture.ok ? '接线异常' : capture.installed ? '已配置采集' : '未接入';
+        return `<div class="agent-capture-row"><div><b>${esc(agent.label)}</b><small>${esc(software)} · ${esc(status)}</small><small>${esc(capture.detail)}</small></div><div class="actions"><button data-agent-capture="install" data-agent-client="${esc(agent.client)}" ${!found || captureBusy ? 'disabled' : ''}>${capture.installed ? '修复' : '接入'}</button>${capture.installed ? `<button data-agent-capture="uninstall" data-agent-client="${esc(agent.client)}" ${captureBusy ? 'disabled' : ''}>移除采集</button>` : ''}</div></div>`;
+      }).join('');
+    } catch (error) { if (epoch === captureEpoch) $('agentCaptureList').textContent = `无法检查采集状态：${error.message}`; }
+  }
+  async function changeAgentCapture(client, operation) {
+    if (captureBusy) return;
+    captureBusy = true; captureEpoch++;
+    all('[data-agent-capture]').forEach(button => { button.disabled = true; });
+    $('agentCaptureFeedback').textContent = operation === 'install' ? '正在配置采集 Hook…' : '正在移除托管采集，已有记录保留…';
+    try {
+      const result = await api(`/api/integrations/${operation}`, { method: 'POST', body: { clients: [client], captureOnly: true } });
+      const capture = operation === 'install' ? result.clients[0]?.developmentCapture : result.capture[0];
+      const success = result.complete === true && capture?.ok;
+      $('agentCaptureFeedback').textContent = success ? operation === 'install' ? '采集配置已保存。请重新打开外部 Agent 会话，实际记录可在活动页面查看。' : '已移除托管采集，第三方配置与已有记录保留。' : `接入操作未完成：${capture?.detail || result.bridge?.detail || '请检查系统诊断记录。'}\n操作 ID：${result.operationId || '—'}`;
+      $('agentCaptureFeedback').classList.toggle('issue', !success);
+    } catch (error) { $('agentCaptureFeedback').textContent = `操作失败：${error.message}`; $('agentCaptureFeedback').classList.add('issue'); }
+    finally { captureBusy = false; await loadAgentCapture(); post('eventBridge', { type: 'kb:refresh-agents' }); }
   }
   async function loadLogs() {
     const epoch = ++logEpoch;
@@ -307,6 +336,7 @@
       if (button.dataset.action === 'import') openImport();
       if (button.dataset.action === 'repair') await repair();
       if (button.dataset.action === 'system') await openSystem();
+      if (button.dataset.agentCapture) await changeAgentCapture(button.dataset.agentClient, button.dataset.agentCapture);
       if (button.dataset.action === 'unbind') { const p = activeProject(); if (p && !unbinding) { unbindProjectId = p.projectId; $('unbindProjectName').textContent = `解绑「${p.name}」？`; $('unbindFeedback').textContent = ''; $('unbindDialog').showModal(); } }
       if (button.dataset.retryRun) { await api(`/api/engine/runs/${encodeURIComponent(button.dataset.retryRun)}/retry`, { method: 'POST', body: {} }); await refreshSnapshot(); }
       if (button.dataset.contextIndex !== undefined) await openReference(state.contexts.get(state.projectId).references[Number(button.dataset.contextIndex)]);
@@ -325,6 +355,7 @@
     if (event.origin !== location.origin || !event.data || typeof event.data !== 'object') return;
     const key = Object.keys(frames).find(k => $(frames[k].id).contentWindow === event.source); if (!key) return;
     const message = event.data;
+    if (message.type === 'kb:open-integrations' && key === 'eventBridge') { openSystem().then(() => $('agentCaptureSection').scrollIntoView({ block: 'start' })).catch(error => toast(error.message)); return; }
     if (message.type === 'kb:ready') { frames[key].ready = true; frameContext(key); if (frames[key].openSettings) { post(key, { type: 'kb:open-settings' }); frames[key].openSettings = false; } }
     if (message.requestId && message.requestId !== frames[key].requestId) return;
     if (message.type === 'kb:knowledge' && key === 'terminal') {
@@ -336,6 +367,7 @@
   on('themeToggle', 'click', () => { document.documentElement.dataset.theme = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark'; localStorage.setItem('kb.theme', document.documentElement.dataset.theme); Object.keys(frames).forEach(key => post(key, { type: 'kb:theme', theme: document.documentElement.dataset.theme })); });
   on('openSystem', 'click', openSystem); on('closeSystem', 'click', closeSystem); on('drawerBackdrop', 'click', closeSystem);
   on('repairWiring', 'click', repair);
+  on('refreshAgentCapture', 'click', () => captureBusy ? undefined : loadAgentCapture());
   on('configureProviders', 'click', () => { closeSystem(); setView('work'); initializeFrame('terminal'); if (frames.terminal.ready) post('terminal', { type: 'kb:open-settings' }); else frames.terminal.openSettings = true; });
   on('saveMaintenance', 'click', async () => { await api('/api/terminal/maintenance-default', { method: 'PUT', body: { profileId: $('maintenanceModel').value || null } }); const result = await api('/api/modules/configure', { method: 'POST', body: {} }); $('configurationStatus').textContent = result.configuration.model ? '后台默认模型已保存并同步。' : '配置已保存，后台运行配置尚未同步，请检查模块连接。'; });
   on('openEmbedding', 'click', openEmbedding);