@sanqianx/project-knowledge 5.0.0 → 5.0.2

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+  directories without `--path-format`, then resolve relative paths against the
+  Git command's working directory. Reject empty, multi-line or echoed-option
+  responses before writing hooks or repository identities.
+- Apply the same correction to commit capture and pin event-bridge console
+  0.7.1 so importing a project and capturing its next commit use consistent
+  workspace metadata. No previous data is migrated.
+- Keep import failure feedback visible with its error code and operation ID.
+  Persist the actual failed transaction stage; system diagnostics default to
+  all projects so failures of not-yet-registered imports are visible/exportable.
+
 ## [5.0.0] - 2026-10-10
 
 - Fresh-data-only web product. Default state moves to `~/.project-knowledge-v5`;

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/git-path-compatibility-test.js

@@ -0,0 +1,80 @@
+const assert = require('assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { resolveGitPath } = require('../lib/git-path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+const { BridgeAdapter } = require('../lib/bridge-adapter');
+const { Logger, LogRepository } = require('../lib/structured-logger');
+const hooks = require('../lib/hook-manager');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-git-path-'));
+  const repo = path.join(root, '中文 空格项目'); fs.mkdirSync(repo);
+  const git = (args, cwd = repo) => {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+    assert.equal(result.status, 0, result.stderr); return result.stdout.trim();
+  };
+  for (const invalid of ['', '--path-format=absolute\n.git/hooks', '.git/hooks\nother', '--unsupported', '\0']) {
+    assert.throws(() => resolveGitPath(repo, invalid), { code: 'INVALID_ARGUMENT' });
+  }
+  assert.equal(resolveGitPath(repo, '.git/hooks\r\n'), path.join(repo, '.git', 'hooks'));
+  git(['init', '-q']); git(['config', 'user.name', 'Git Compatibility']); git(['config', 'user.email', 'git-compat@example.invalid']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# baseline\n'); git(['add', '.']); git(['commit', '-qm', 'baseline']);
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+  await settingsStore.initialize({ knowledge: { rootPath: path.join(root, 'knowledge') } });
+  await registryStore.initialize();
+  const bridgeAdapter = new BridgeAdapter({ dataDir: layout.getDataDir(), bridgeHomeDir: path.join(root, 'bridge') });
+  assert.ok(bridgeAdapter.isAvailable());
+  const logger = new Logger({ layout });
+  const triggerScriptPath = path.resolve(__dirname, '../scripts/hook-trigger.js');
+  const options = { layout, settingsStore, registryStore, projectStore, bridgeAdapter, logger, triggerScriptPath };
+  const lifecycle = new ProjectLifecycleService(options);
+  const input = { localPath: repo, knowledgePath: path.join(root, 'knowledge', 'fresh'), projectId: 'project-git-compat' };
+  const preflight = await lifecycle.preflightImport(input);
+  assert.equal(preflight.ready, true);
+  assert.equal(preflight.checks.git.commonDir, path.join(repo, '.git'));
+  const imported = await lifecycle.importProject(input);
+  assert.equal(imported.hook.hookPath, path.join(repo, '.git', 'hooks', 'post-commit'));
+  assert.equal(imported.config.repoIdentity.commonDir, path.join(repo, '.git'));
+  const nested = path.join(repo, 'src'); fs.mkdirSync(nested);
+  assert.equal((await bridgeAdapter.resolveRepoIdentity(nested)).repoIdentity.commonDir, imported.config.repoIdentity.commonDir);
+  fs.appendFileSync(path.join(repo, 'README.md'), 'commit after import\n'); git(['add', '.']); git(['commit', '-qm', 'captured update']);
+  const sha = git(['rev-parse', 'HEAD']);
+  const journal = await bridgeAdapter.readEvents({ after: 0, limit: 100 });
+  const boundary = journal.events.find(event => event.commitSha === sha && event.schema === 'git-commit-boundary/v1');
+  assert.ok(boundary, 'real Git post-commit Hook must append a durable boundary');
+  assert.equal(boundary.repoIdentity.commonDir, path.join(repo, '.git'));
+  assert.equal(boundary.projectId, input.projectId);
+  await lifecycle.deleteProject(input.projectId);
+  const brokenRegistry = Object.create(registryStore);
+  brokenRegistry.add = async () => { throw new Error('diagnostic registry failure'); };
+  await assert.rejects(new ProjectLifecycleService({ ...options, registryStore: brokenRegistry }).importProject(input), /Project import failed/);
+  const failed = new LogRepository({ layout }).query({ event: 'project.import.failed' }).entries[0];
+  assert.equal(failed.error.message, 'diagnostic registry failure');
+  assert.equal(failed.phase, 'hook-verified');
+  const transaction = JSON.parse(fs.readFileSync(lifecycle.transactionPath(failed.operationId), 'utf8'));
+  assert.equal(transaction.phase, 'failed'); assert.equal(transaction.failurePhase, 'hook-verified');
+  assert.equal(hooks.readHookStatus({ repoPath: repo }).installed, false);
+  const worktree = path.join(root, '关联 工作树'); git(['worktree', 'add', '-qb', 'linked', worktree]);
+  const sharedHook = hooks.installHook({ repoPath: worktree, projectId: 'project-worktree', triggerScriptPath });
+  assert.equal(path.dirname(sharedHook.hookPath), path.join(repo, '.git', 'hooks'));
+  hooks.uninstallHook({ repoPath: worktree, projectId: 'project-worktree' });
+  for (const custom of ['.custom hooks', path.join(root, '绝对 hooks')]) {
+    git(['config', 'core.hooksPath', custom], worktree);
+    const installed = hooks.installHook({ repoPath: worktree, projectId: 'project-worktree', triggerScriptPath });
+    assert.equal(path.dirname(installed.hookPath), path.resolve(worktree, custom));
+    assert.equal(hooks.readHookStatus({ repoPath: worktree }).installed, true);
+    hooks.uninstallHook({ repoPath: worktree, projectId: 'project-worktree' });
+  }
+  await logger.close();
+  console.log(`git-path-compatibility-test PASS (${git(['--version'])}; import → real Hook → journal; worktrees/custom hooks; diagnostic phase)`);
+})().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });

package/_site/_test/product-diagnostics-ui-test.js

@@ -8,10 +8,17 @@ const { spawnServer } = require('./helpers/spawn-server');
 const { findChrome } = require('./helpers/find-chrome');
 const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
 const { createLoggingUiFixture } = require('./helpers/logging-ui-fixture');
+const { Logger } = require('../lib/structured-logger');
+const { StorageLayout } = require('../lib/storage-layout');
 const ROOT = path.resolve(__dirname, '../..');
 
 async function main() {
-  const fixture = await createLoggingUiFixture({ totalLogs: 240 });
+  const fixture = await createLoggingUiFixture({ totalLogs: 240, freshProduct: true });
+  const logger = new Logger({ layout: new StorageLayout({ dataDir: fixture.dataDir }) });
+  await logger.error('project.import.failed', 'Import failed for an unregistered project', {
+    projectId: 'project-import-not-registered', operationId: 'op-import-diagnostic',
+    error: Object.assign(new Error('Git Hook path resolution failed'), { code: 'ENOENT' })
+  });
   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}`;
@@ -35,6 +42,13 @@ async function main() {
     assert.ok(await run("document.getElementById('activityUpdates').textContent.includes('离线')"), 'offline cannot masquerade as empty/success');
     await click('#openSystem'); await click('#openLogs');
     await waitFor(() => run("document.querySelectorAll('#logsContent .log-entry').length === 100"), 'bounded diagnostic rendering');
+    assert.equal(await run("document.getElementById('logsScope').value"), 'all');
+    await run("document.getElementById('logsSearch').value='op-import-diagnostic'"); await click('#loadLogs');
+    await waitFor(() => run("document.getElementById('logsContent').textContent.includes('ENOENT')"), 'unregistered import visible despite active project');
+    await run("document.getElementById('logsScope').value='project'; document.getElementById('logsScope').dispatchEvent(new Event('change'))");
+    await waitFor(() => run("document.querySelectorAll('#logsContent .log-entry').length === 0"), 'current project excludes failed new import');
+    await run("document.getElementById('logsScope').value='all'; document.getElementById('logsScope').dispatchEvent(new Event('change'))");
+    await waitFor(() => run("document.getElementById('logsContent').textContent.includes('op-import-diagnostic')"), 'global diagnostic scope restored');
     assert.equal(await run("document.querySelectorAll('#logsDialog img, #logsDialog script').length"), 0);
     await run("document.getElementById('logsSearch').value='<img src=x onerror=window.__xss=1>'"); await click('#loadLogs');
     await waitFor(() => run("document.querySelectorAll('#logsContent .log-entry').length === 1"), 'real server query filter');
@@ -59,8 +73,8 @@ async function main() {
     // The registry does not own knowledge bytes. Use its actual double-directory binding.
     const project = (await (await fetch(base + '/api/projects/aggregated')).json()).projects[0];
     const retained = path.join(project.knowledgePath, 'keep.md'); fs.writeFileSync(retained, '# 保留知识\n');
-    await run('window.confirm = () => true'); await click('[data-action="unbind"]');
-    await waitFor(() => run("document.getElementById('toast').textContent.includes('无法安全停止写入')"), 'offline writer prevents unsafe unbind');
+    await click('[data-action="unbind"]'); await click('#confirmUnbind');
+    await waitFor(() => run("document.getElementById('unbindFeedback').textContent.includes('无法安全停止写入')"), 'offline writer prevents unsafe unbind');
     assert.equal((await (await fetch(base + '/api/projects/aggregated')).json()).projects.length, 1);
     assert.deepEqual(fs.readdirSync(fixture.repo.path), codeFiles); assert.ok(fs.existsSync(retained));
     assert.equal(browser.exceptions.length, 0, JSON.stringify(browser.exceptions));

package/_site/_test/product-import-ui-test.js

@@ -66,6 +66,18 @@ async function main() {
     await waitFor(() => run("document.getElementById('importDialog').open && !document.getElementById('confirmImport').disabled"), 'setup returns to ready import');
     const values = await run("Object.fromEntries(['importCode','importKnowledge','importName','importDomain'].map(id=>[id,document.getElementById(id).value]))");
     assert.deepEqual(values, { importCode: repo, importKnowledge: knowledge, importName: '回归项目', importDomain: domainId });
+    const racedHook = path.join(repo, '.git', 'hooks', 'post-commit');
+    fs.writeFileSync(racedHook, '#!/bin/sh\necho third-party fixture\n');
+    await click('#confirmImport');
+    await waitFor(() => run("document.getElementById('preflightStatus').textContent.includes('HOOK_CONFLICT') && document.getElementById('preflightStatus').textContent.includes('操作 ID：op-')"), 'durable import failure feedback');
+    await new Promise(resolve => setTimeout(resolve, 750));
+    assert.ok(await run("document.getElementById('preflightStatus').textContent.includes('HOOK_CONFLICT')"), 'failed import must not turn back into a passed preflight');
+    assert.equal((await api('/api/projects/aggregated')).projects.length, 0);
+    assert.equal(fs.readFileSync(racedHook, 'utf8'), '#!/bin/sh\necho third-party fixture\n');
+    const failureLogs = (await api('/api/logs?event=project.import.failed')).entries;
+    assert.equal(failureLogs.length, 1); assert.equal(failureLogs[0].error.code, 'HOOK_CONFLICT');
+    assert.ok(await run(`document.getElementById('preflightStatus').textContent.includes(${JSON.stringify(failureLogs[0].operationId)})`), 'UI operation ID resolves to the persisted failure');
+    fs.unlinkSync(racedHook);
     await click('#confirmImport');
     await waitFor(() => run("!document.getElementById('importDialog').open && document.getElementById('projectDetail').textContent.includes('回归项目')"), 'import feedback', 30000);
     const selected = await run("document.getElementById('projectSelect').value");

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/git-path.js

@@ -0,0 +1,14 @@
+const path = require('path');
+const { DomainError } = require('./contracts');
+
+function resolveGitPath(cwd, output) {
+  const value = String(output || '').trim();
+  // rev-parse may echo unsupported flags with exit code 0. Never let a
+  // multi-line response become a filesystem path or a repository identity.
+  if (!value || /[\r\n\0]/.test(value) || value.startsWith('--')) {
+    throw new DomainError('INVALID_ARGUMENT', 'Git 返回了无效的目录路径，请检查 Git 安装。', { status: 400 });
+  }
+  return path.resolve(cwd, value);
+}
+
+module.exports = { resolveGitPath };

package/_site/lib/hook-manager.js

@@ -3,6 +3,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const AtomicFile = require('./atomic-file');
 const { DomainError, validateProjectId } = require('./contracts');
+const { resolveGitPath } = require('./git-path');
 
 const HOOK_NAME = 'post-commit';
 const HOOK_MARKER = '# PROJECT-KNOWLEDGE-HOOK ';
@@ -28,13 +29,12 @@ function runGit(repoPath, args) {
 function resolveGitHooksDir(_gitDir, repoPath) {
   if (!repoPath) throw new DomainError('INVALID_ARGUMENT', 'repoPath is required.');
   const absolute = path.resolve(repoPath);
-  const hooksPath = runGit(absolute, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
-  if (!hooksPath) throw new DomainError('HOOK_INVALID', 'Git returned an empty hooks path.', { status: 400 });
-  return path.resolve(absolute, hooksPath);
+  const hooksPath = runGit(absolute, ['rev-parse', '--git-path', 'hooks']);
+  return resolveGitPath(absolute, hooksPath);
 }
 
 function repoGitDir(repoPath) {
-  try { return runGit(path.resolve(repoPath), ['rev-parse', '--path-format=absolute', '--git-dir']); }
+  try { return resolveGitPath(path.resolve(repoPath), runGit(path.resolve(repoPath), ['rev-parse', '--git-dir'])); }
   catch { return null; }
 }
 

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/post-commit-automation.js

@@ -27,7 +27,7 @@ async function handlePostCommitEvent(event = {}, deps = {}) {
   if (!resolved.registryStore.readDisplaySnapshot(projectId)) throw new DomainError('PROJECT_NOT_FOUND', 'Hook projectId is not registered.', { status: 404 });
   const config = resolved.projectStore.readConfig(projectId);
   const runtimeRoot = path.resolve(runGit(path.resolve(event.repoRoot), ['rev-parse', '--show-toplevel']).stdout);
-  const commonDir = path.resolve(runGit(runtimeRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']).stdout);
+  const commonDir = path.resolve(runtimeRoot, runGit(runtimeRoot, ['rev-parse', '--git-common-dir']).stdout);
   if (config.repoIdentity && config.repoIdentity.commonDir
     && !resolved.layout.pathsEqual(config.repoIdentity.commonDir, commonDir)) {
     if (fs.existsSync(config.repoPath)) {

package/_site/lib/project-lifecycle-service.js

@@ -6,6 +6,7 @@ const { DomainError, createId } = require('./contracts');
 const AtomicFile = require('./atomic-file');
 const hookManagerDefault = require('./hook-manager');
 const { resolveEffectiveAiProfile } = require('./ai-profile-resolver');
+const { resolveGitPath } = require('./git-path');
 
 function slugify(value) {
   const slug = String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
@@ -86,12 +87,12 @@ class ProjectLifecycleService {
         checks.git = { ok: false, status: 'non-git', plannedInit: true, message: 'Directory is not a Git repository. Import will run `git init` before proceeding.' };
       } else {
         const head = runGit(localPath, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true });
-        const commonDir = runGit(localPath, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+        const commonDir = runGit(localPath, ['rev-parse', '--git-common-dir']);
         const branch = runGit(localPath, ['branch', '--show-current'], { allowFailure: true });
         repoInspection = {
           ok: true,
           repoPath: top.ok ? path.resolve(top.stdout) : path.resolve(localPath),
-          commonDir: commonDir.ok ? path.resolve(commonDir.stdout) : '',
+          commonDir: commonDir.ok ? resolveGitPath(localPath, commonDir.stdout) : '',
           headCommit: head.ok ? head.stdout : null,
           branch: branch.ok ? branch.stdout : '',
           emptyRepo: !head.ok,
@@ -270,9 +271,9 @@ class ProjectLifecycleService {
       journal.gitInitialized = initialized.ok;
     }
     const top = runGit(repoPath, ['rev-parse', '--show-toplevel']).stdout;
-    const commonDir = runGit(repoPath, ['rev-parse', '--path-format=absolute', '--git-common-dir']).stdout;
+    const commonDir = runGit(repoPath, ['rev-parse', '--git-common-dir']).stdout;
     const head = runGit(repoPath, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true });
-    return { repoPath: path.resolve(top), commonDir: path.resolve(commonDir), head: head.ok ? head.stdout : null };
+    return { repoPath: path.resolve(top), commonDir: resolveGitPath(repoPath, commonDir), head: head.ok ? head.stdout : null };
   }
 
   async importProject(input = {}) {
@@ -376,14 +377,18 @@ class ProjectLifecycleService {
       await log.info?.('project.import.completed', 'Project import completed.', { projectId, phase: 'registry-commit', durationMs: Date.now() - Date.parse(journal.startedAt) });
       return { ok: true, operationId, projectId, config: created.config, state: created.state, hook, gitInitialized: journal.gitInitialized === true };
     } catch (error) {
+      journal.failurePhase = journal.phase;
       const rollbackWarnings = await this.rollbackImport(journal);
       journal.phase = 'failed';
       journal.failedAt = new Date().toISOString();
       journal.error = { code: error.code || '', message: String(error.message || error) };
       journal.rollbackWarnings = rollbackWarnings;
       this.writeJournal(journal);
-      await log.error?.('project.import.failed', 'Project import failed.', { projectId: journal.projectId || '', phase: journal.phase, error, context: { rollbackWarnings } });
-      if (error instanceof DomainError) throw error;
+      await log.error?.('project.import.failed', 'Project import failed.', { projectId: journal.projectId || '', phase: journal.failurePhase, error, context: { rollbackWarnings } });
+      if (error instanceof DomainError) {
+        if (!error.operationId) error.operationId = operationId;
+        throw error;
+      }
       throw new DomainError('INVALID_ARGUMENT', 'Project import failed.', { status: 500, operationId, cause: error, details: { rollbackWarnings } });
     }
   }

package/_site/lib/requirement-recorder.js

@@ -98,9 +98,9 @@ class GitReader {
       const top = topResult.status === 0 && String(topResult.stdout || '').trim()
         ? path.resolve(String(topResult.stdout).trim())
         : null;
-      const commonResult = this.run(repoPath, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+      const commonResult = this.run(repoPath, ['rev-parse', '--git-common-dir']);
       const commonDir = commonResult.status === 0 && String(commonResult.stdout || '').trim()
-        ? path.resolve(String(commonResult.stdout).trim())
+        ? path.resolve(repoPath, String(commonResult.stdout).trim())
         : null;
       let repoIdentity = null;
       if (top && bridgeIdentityModule) {

package/_site/lib/server-app.js

@@ -234,12 +234,12 @@ async function inspectGitRepository(repoPath) {
     execGit(root, ['rev-parse', '--verify', 'HEAD']),
     execGit(root, ['branch', '--show-current']),
     execGit(root, ['status', '--porcelain=v1', '--untracked-files=normal']),
-    execGit(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']),
+    execGit(root, ['rev-parse', '--git-common-dir']),
   ]);
   return {
     repoStatus: head.ok ? 'ok' : 'empty',
     repoPath: top.ok ? path.resolve(top.stdout.trim()) : root,
-    commonDir: commonDir.ok ? path.resolve(commonDir.stdout.trim()) : '',
+    commonDir: commonDir.ok ? path.resolve(root, commonDir.stdout.trim()) : '',
     headCommit: head.ok ? head.stdout.trim() : null,
     branch: branch.ok ? branch.stdout.trim() : '',
     dirty: status.ok && Boolean(status.stdout.trim()),
@@ -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/_site/scripts/hook-trigger.js

@@ -8,6 +8,7 @@ const { readLiveEndpoint } = require('../lib/runtime-endpoint');
 const { StorageLayout } = require('../lib/storage-layout');
 const { Logger } = require('../lib/structured-logger');
 const { BridgeAdapter } = require('../lib/bridge-adapter');
+const { resolveGitPath } = require('../lib/git-path');
 
 let bridgeIdentityModule = null;
 try {
@@ -96,11 +97,11 @@ function post(body) {
       if (toplevel) {
         let workspaceRoot = path.resolve(toplevel);
         try { workspaceRoot = fs.realpathSync.native(workspaceRoot) || workspaceRoot; } catch { workspaceRoot = path.resolve(toplevel); }
-        const commonDir = git(['rev-parse', '--path-format=absolute', '--git-common-dir']);
+        const commonDir = git(['rev-parse', '--git-common-dir']);
         const remoteRaw = git(['config', '--get', 'remote.origin.url']);
         repoIdentity = bridgeIdentityModule.buildRepoIdentityV1({
           workspaceRoot,
-          commonDir: commonDir ? path.resolve(commonDir) : null,
+          commonDir: commonDir ? resolveGitPath(repoRoot, commonDir) : null,
           remote: remoteRaw ? bridgeIdentityModule.normalizeGitUrl(remoteRaw) : null,
         });
       }

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/docs/fresh-v5-start.md

@@ -17,6 +17,12 @@ project-knowledge
 
 如果模块是自己独立启动的旧进程，请在它原来的终端中停止后重启新版外壳。外壳不会擅自杀死其他服务；版本或运行期鉴权不一致时显示具体连接阶段，不接管旧服务数据。
 
+5.0.1 修复旧版 Git 的项目导入失败（日志中的路径包含
+`--path-format=absolute` 和换行）。升级 5.0.0 → 5.0.1 不需要清空新版数据或
+重新配置模型。失败项目可以直接重试导入；原代码、第三方 Hook 与旧知识文件不删除。
+导入失败会在弹窗保留错误码和操作 ID，系统诊断默认查询“系统与所有项目”，
+可按操作 ID 查找导入事务的真实失败阶段和原始错误。
+
 ## 解绑与恢复
 
 “解绑并保留数据”从项目列表移除登记、取消未开始任务并卸下本项目托管 Hook，保留代码、知识、会话及证据。实际分析或索引写入尚未结束时仍禁止解绑，防止丢失写入状态。队列本身不再被当成正在运行。

package/module-runtime-manifest.json

@@ -1,9 +1,9 @@
 {
   "schema": "project-knowledge/module-content/v1",
   "productFiles": {
-    "ui/index.html": "fd79551591729f6874c95089e479d46f208ab3b45cf45ba21eff1f6967757f7d",
-    "ui/product.js": "d5fca94df54075d598f271e01ea41ac9cce3a9847ea4f246e4f20c47daed43ed",
-    "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.0",
+      "version": "0.7.2",
       "files": {
         "LICENSE": "94a3bded67f76ec9f6333ad3370111bcb6e5cadbeb6f306a8112f9543320ecc2",
-        "README.md": "847242d93395aae17b42bbaa7fc8e36e6f89edecf11a1639b94b34c98729e1a9",
-        "console/index.html": "680e6393c9ef88ea35c1eabff537e0b10f7a91c55986f18bca6bfe2a333eed6e",
-        "package.json": "63b9846552b8ac3b7e361bd86bb1d9389d55e7232934aaa939b168e43ad650b7",
-        "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": "ea6c9638efcb7abdb45916747a4984a97c6df31cf3fc601d221e1730fa01409b",
-        "src/bridge/core/runtime-home.js": "e68a3c927b02ca27299755c60c8f709f7ce97c9f4c5080deefe518bf60d9d989",
+        "src/bridge/core/repo-context.js": "1627d416fd6aaa43d8c4be8ce5097bb69244b1afe7f1ce5e9f71956c5542ce3f",
+        "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.0",
+  "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.0",
+    "@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.0",
+  "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.0",
+  "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.0",
+        "@sanqianx/project-knowledge@5.0.2",
         "project-knowledge-mcp"
       ]
     }

package/ui/index.html

@@ -32,11 +32,12 @@
   </main>
 </div>
 <div id="drawerBackdrop" class="drawer-backdrop" hidden></div>
-<dialog id="logsDialog" class="reference-dialog"><div class="dialog-heading"><h2>系统诊断记录</h2><button data-close="logsDialog" aria-label="关闭">×</button></div><div class="actions"><input id="logsSearch" placeholder="查找失败原因或提交 SHA" aria-label="筛选诊断记录"><button id="loadLogs">查询</button><button id="exportLogs">导出诊断记录</button></div><div id="logsStatus" class="muted"></div><div id="logsContent"></div></dialog>
+<dialog id="logsDialog" class="reference-dialog"><div class="dialog-heading"><h2>系统诊断记录</h2><button data-close="logsDialog" aria-label="关闭">×</button></div><div class="actions"><select id="logsScope" aria-label="诊断范围"><option value="all">系统与所有项目</option><option value="project">当前项目</option></select><input id="logsSearch" placeholder="查找失败原因、操作 ID 或提交 SHA" aria-label="筛选诊断记录"><button id="loadLogs">查询</button><button id="exportLogs">导出诊断记录</button></div><div id="logsStatus" class="muted"></div><div id="logsContent"></div></dialog>
 <aside class="drawer" id="systemDrawer" hidden aria-label="系统状态">
   <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,13 +19,14 @@
   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);
     if (init.body) init.headers = { 'Content-Type': 'application/json', ...init.headers };
     const response = await fetch(url, init);
     const data = await response.json();
-    if (!response.ok || data.ok === false && !allowNotReady) throw Object.assign(new Error(data.error?.message || data.message || (typeof data.error === 'string' ? data.error : `请求失败 (${response.status})`)), { code: data.error?.code || data.error });
+    if (!response.ok || data.ok === false && !allowNotReady) throw Object.assign(new Error(data.error?.message || data.message || (typeof data.error === 'string' ? data.error : `请求失败 (${response.status})`)), { code: data.error?.code || data.error, operationId: data.error?.operationId || response.headers.get('X-Operation-Id') || '' });
     return data;
   }
   function toast(text) { $('toast').textContent = text; $('toast').hidden = false; clearTimeout(toastTimer); toastTimer = setTimeout(() => { $('toast').hidden = true; }, 4000); }
@@ -182,22 +183,51 @@
   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;
     logStream?.close(); logStream = null;
     const params = new URLSearchParams({ pageSize: '100', q: $('logsSearch').value.trim() });
-    if (state.projectId) params.set('projectId', state.projectId);
+    const projectOnly = $('logsScope').value === 'project' && Boolean(state.projectId);
+    if (projectOnly) params.set('projectId', state.projectId);
     const result = await api(`/api/logs?${params}`);
     if (epoch !== logEpoch || !$('logsDialog').open) return;
     $('logsDialog').dataset.streamCursor = result.streamCursor || '';
     $('logsContent').replaceChildren();
     for (const record of [...(result.entries || [])].reverse()) appendLog(record);
-    $('logsStatus').textContent = `${(result.entries || []).length} 条诊断记录 · 当前项目`;
+    $('logsStatus').textContent = `${(result.entries || []).length} 条诊断记录 · ${projectOnly ? '当前项目' : '系统与所有项目'}`;
     if (!$('logsSearch').value.trim()) {
       const streamParams = new URLSearchParams({ streamCursor: result.streamCursor || '' });
-      if (state.projectId) streamParams.set('projectId', state.projectId);
+      if (projectOnly) streamParams.set('projectId', state.projectId);
       logStream = new EventSource(`/api/logs/stream?${streamParams}`);
       logStream.addEventListener('logs/appended', event => { if (epoch === logEpoch && $('logsDialog').open) appendLog(JSON.parse(event.data).record); });
     }
@@ -306,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)]);
@@ -324,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') {
@@ -335,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);
@@ -350,6 +383,7 @@
   on('engineDialog', 'close', () => post('engine', { type: 'kb:visibility', visible: false }));
   on('openLogs', 'click', async () => { closeSystem(); $('logsDialog').showModal(); await loadLogs(); });
   on('logsDialog', 'close', () => { logEpoch++; logStream?.close(); logStream = null; });
+  on('logsScope', 'change', loadLogs);
   on('copyReference', 'click', async () => {
     const text = $('referenceMeta').textContent + '\n\n' + $('referenceContent').textContent;
     try { await navigator.clipboard.writeText(text); }
@@ -357,7 +391,7 @@
     toast('已复制知识与来源。');
   });
   on('loadLogs', 'click', loadLogs);
-  on('exportLogs', 'click', async () => { const params = new URLSearchParams({ q: $('logsSearch').value.trim() }); if (state.projectId) params.set('projectId', state.projectId); const response = await fetch(`/api/logs/export?${params}`); if (!response.ok) throw new Error('诊断导出失败。'); const blob = await response.blob(); const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = 'knowledge-diagnostics.jsonl'; link.click(); setTimeout(() => URL.revokeObjectURL(url), 1000); });
+  on('exportLogs', 'click', async () => { const params = new URLSearchParams({ q: $('logsSearch').value.trim() }); if ($('logsScope').value === 'project' && state.projectId) params.set('projectId', state.projectId); const response = await fetch(`/api/logs/export?${params}`); if (!response.ok) throw new Error('诊断导出失败。'); const blob = await response.blob(); const url = URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = 'knowledge-diagnostics.jsonl'; link.click(); setTimeout(() => URL.revokeObjectURL(url), 1000); });
   on('createDomain', 'click', () => { $('domainForm').reset(); $('domainDialog').showModal(); });
   on('domainForm', 'submit', async e => { e.preventDefault(); await api('/api/domains', { method: 'POST', body: Object.fromEntries(new FormData(e.target)) }); $('domainDialog').close(); await refreshRegistry(); });
   on('memoryForm', 'submit', async e => { e.preventDefault(); await api(`/api/engine/memories/${encodeURIComponent(editingMemoryId)}`, { method: 'PATCH', body: { text: $('memoryText').value } }); $('memoryDialog').close(); await refreshSnapshot(); });
@@ -388,8 +422,15 @@
   on('importForm', 'submit', async e => {
     e.preventDefault(); if (!state.preflight?.ready || state.preflight.plannedGitInit && !$('importForm').elements.confirmGitInit.checked || state.preflight.checks.hook?.replacementProjectId && !$('importForm').elements.confirmReplaceHook.checked) return;
     $('confirmImport').disabled = true; $('confirmImport').textContent = '正在登记…';
-    try { const result = await api('/api/projects/import', { method: 'POST', body: importInput() }); state.projectId = result.projectId; state.epoch++; $('importDialog').close(); await refreshRegistry(); Object.keys(frames).forEach(frameContext); setView('projects'); toast(Object.values(result.modules).every(m => m.ok) ? '项目已导入，四个模块已连接。' : '项目已导入，部分接线待恢复。'); }
-    finally { $('confirmImport').textContent = '导入项目'; if ($('importDialog').open) checkImport(); }
+    let failed = false, registered = false;
+    try { const result = await api('/api/projects/import', { method: 'POST', body: importInput() }); registered = true; state.projectId = result.projectId; state.epoch++; $('importDialog').close(); await refreshRegistry(); Object.keys(frames).forEach(frameContext); setView('projects'); toast(Object.values(result.modules).every(m => m.ok) ? '项目已导入，四个模块已连接。' : '项目已导入，部分接线待恢复。'); }
+    catch (error) {
+      failed = true;
+      if (registered) { toast(`项目已登记，但页面状态刷新失败：${error.message}`); return; }
+      $('preflightStatus').textContent = `导入失败：${error.message}\n错误码：${error.code || 'UNKNOWN'}${error.operationId ? `\n操作 ID：${error.operationId}` : ''}\n请在系统诊断记录中查看详细原因。`;
+      $('preflightStatus').classList.add('issue'); $('confirmImport').disabled = false;
+    }
+    finally { $('confirmImport').textContent = '导入项目'; if ($('importDialog').open && !failed) checkImport(); }
   });
   window.addEventListener('hashchange', () => setView(location.hash.slice(1)));
   window.addEventListener('offline', () => {