@sanqianx/project-knowledge 5.0.12 → 5.0.13

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [5.0.13] - 2026-10-13
+
+- 修复独立 bridge 与产品 bridge 同时接入导致同一项目生成两个知识目录：接入/修复只替换明确的旧自有入口，并去除当前入口的重复项。
+- Claude Code、ZCode 重复采集不再显示为正常；保留混合分组中的第三方 Hook、知识读取、模型配置和历史日志。
+- Codex 通知链识别默认旧 bridge，包括已知通知分支中嵌套的旧入口；保留第三方通知，不恢复退役的重复采集。
+
 ## [5.0.12] - 2026-10-12
 
 - 冻结 rc.3 已验收的三客户端开发前知识读取：Claude Code、Codex、ZCode 获取统一事实及适用的已确认长期记忆。

package/README.md

@@ -56,6 +56,11 @@ Notes:
   `project-knowledge-integrations install --ide codex --capture-only`.
   Repeating setup does not add notification wrappers. Removing capture restores
   the preserved notification chain and leaves captured records on disk.
+- Capture repair replaces the known old standalone Bridge entry with the
+  current product Bridge and keeps one capture hook per event. Claude Code
+  and ZCode mixed-group third-party hooks and knowledge-context hooks remain
+  intact. Duplicate or stale entries are reported as needing repair rather
+  than healthy; existing journals are not moved or deleted.
 
 The local service listens on `127.0.0.1:5757` by default. The CLI can select a
 nearby free port and records the active loopback endpoint so managed Git Hooks

package/_site/_test/capture-hook-dedup-test.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { IntegrationManager } = require(process.env.PK_TEST_INTEGRATION_ROOT
+  ? path.join(process.env.PK_TEST_INTEGRATION_ROOT, '_site/lib/integration-installer') : '../lib/integration-installer');
+const { bridgeBinding, planCaptureHooks, repairCaptureHooks } = require('../lib/capture-hook-config');
+const bridge = require('@sanqianx/ai-coding-event-bridge-console/src/bridge');
+const ROOT = path.resolve(__dirname, '../..');
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-capture-dedup-'));
+const HOME = path.join(TEMP, '用户 空格');
+const OLD = path.join(HOME, '.ai-coding-event-bridge');
+const CURRENT = path.join(HOME, '.project-knowledge-v5/events');
+const options = { homeDir: HOME, bridgeHomeDir: CURRENT };
+const shim = home => path.join(home, 'bin/bridge-hook.cjs');
+const cmd = home => ({ type: 'command', command: `node "${shim(home)}"` });
+const processHook = home => ({ type: 'process', command: 'node', args: [shim(home), '--source', 'zcode'], timeoutMs: 15000 });
+const events = ['UserPromptSubmit', 'Stop'];
+const read = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+function write(file, object) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(object, null, 2) + '\n'); }
+function manager(extra = {}) { return new IntegrationManager({ rootDir: ROOT, env: {}, ...options, ...extra }); }
+
+async function main() {
+  const claude = path.join(HOME, '.claude/settings.json');
+  const third = { type: 'command', command: 'node "notify-user.cjs"', timeout: 10 };
+  const context = { type: 'command', command: 'node "context-hook.cjs" --client claude' };
+  const lookalike = { type: 'command', command: `node "${shim(OLD)}" && echo keep-user-wrapper` };
+  const customHome = path.join(HOME, 'independent-third-party-bridge');
+  const unrelated = { model: 'user-model', env: { PRIVATE_TEST_TOKEN: 'do-not-back-up-unrelated-secret' } };
+  write(claude, { ...unrelated, hooks: Object.fromEntries(events.map(event => [event, [
+    { matcher: '*', hooks: [cmd(OLD), third, cmd(CURRENT)] },
+    { matcher: '*', hooks: [cmd(OLD), cmd(CURRENT), context, lookalike, cmd(customHome)] },
+  ]])) });
+  const before = fs.readFileSync(claude, 'utf8');
+  const logs = [];
+  const item = manager({ logger: { info: (...args) => logs.push(args), error: (...args) => logs.push(args) } });
+  assert.equal((await item.statusCaptureClaude()).state, 'needs-repair', 'duplicate capture cannot be reported healthy');
+  assert.equal(fs.readFileSync(claude, 'utf8'), before, 'status is read-only');
+  const installed = await item.captureOperation('install', 'claude');
+  assert.equal(installed.removedLegacy, 4);
+  assert.equal(installed.removedDuplicates, 2);
+  assert(logs.some(row => row[2]?.context?.removedLegacy === 4 && row[2]?.context?.removedDuplicates === 2), 'repair counts are persisted without raw configuration');
+  assert(!JSON.stringify(logs).includes('do-not-back-up-unrelated-secret'));
+  let saved = read(claude);
+  assert.equal(saved.model, unrelated.model); assert.deepEqual(saved.env, unrelated.env);
+  for (const event of events) {
+    const hooks = saved.hooks[event].flatMap(group => group.hooks);
+    assert.equal(hooks.filter(hook => hook.command === cmd(CURRENT).command).length, 1);
+    assert.equal(hooks.filter(hook => hook.command === cmd(OLD).command).length, 0);
+    for (const keep of [third, context, lookalike, cmd(customHome)]) assert(hooks.some(hook => JSON.stringify(hook) === JSON.stringify(keep)), 'mixed-group third-party hooks survive');
+  }
+  assert(!fs.readFileSync(installed.backupFile, 'utf8').includes('do-not-back-up-unrelated-secret'), 'backup contains only removed owned invocations');
+  assert.equal((await item.statusCaptureClaude()).state, 'installed');
+  const after = fs.readFileSync(claude, 'utf8');
+  assert.equal((await item.installCaptureClaude()).changed, false);
+  assert.equal(fs.readFileSync(claude, 'utf8'), after, 'repeat repair is byte-idempotent');
+  await item.uninstallCaptureClaude();
+  saved = read(claude);
+  for (const event of events) assert(saved.hooks[event].flatMap(group => group.hooks).some(hook => hook.command === third.command), 'uninstall keeps other hooks in the same group');
+
+  const zcode = path.join(HOME, '.zcode/cli/config.json');
+  const zContext = { type: 'process', command: 'node', args: ['context-hook.cjs', '--client', 'zcode'] };
+  write(zcode, { ...unrelated, hooks: { enabled: true, events: Object.fromEntries(events.map(event => [event, [{ hooks: [processHook(OLD), third, processHook(CURRENT), processHook(CURRENT), zContext] }]])) } });
+  assert.equal((await item.statusCaptureZCode()).state, 'needs-repair');
+  const zInstalled = await item.installCaptureZCode();
+  assert.equal(zInstalled.removedLegacy, 2); assert.equal(zInstalled.removedDuplicates, 2);
+  const zBeforeRepeat = fs.readFileSync(zcode, 'utf8');
+  await item.installCaptureZCode();
+  assert.equal(fs.readFileSync(zcode, 'utf8'), zBeforeRepeat);
+  await item.uninstallCaptureZCode();
+  assert.deepEqual(read(zcode).env, unrelated.env);
+  assert.deepEqual(read(zcode).hooks.events.UserPromptSubmit[0].hooks, [third, zContext]);
+
+  write(claude, { hooks: Object.fromEntries(events.map(event => [event, [{ hooks: [cmd(OLD)] }]])) });
+  const onlyLegacy = fs.readFileSync(claude, 'utf8');
+  assert.throws(() => repairCaptureHooks(claude, 'claude', options), /入口未完整/);
+  const failed = manager({ bridgeModule: { installers: { claudeCode: { installClaudeCodeHook: async () => { throw new Error('runtime materialization failed'); } } } } });
+  await assert.rejects(failed.installCaptureClaude(), /materialization failed/);
+  assert.equal(fs.readFileSync(claude, 'utf8'), onlyLegacy, 'failed runtime install cannot retire working old capture');
+  const conflict = manager({ bridgeModule: { installers: { claudeCode: { installClaudeCodeHook: async () => ({ added: [], runtime: { conflict: true } }) } } } });
+  await assert.rejects(conflict.installCaptureClaude(), /版本冲突/);
+  assert.equal(fs.readFileSync(claude, 'utf8'), onlyLegacy, 'a runtime conflict cannot retire old capture');
+  const dry = manager({ dryRun: true });
+  await dry.installCaptureClaude(); await dry.uninstallCaptureClaude();
+  assert.equal(fs.readFileSync(claude, 'utf8'), onlyLegacy);
+  fs.writeFileSync(claude, '{invalid JSON');
+  assert.throws(() => planCaptureHooks(claude, 'claude', options), /JSON/);
+  assert.equal(fs.readFileSync(claude, 'utf8'), '{invalid JSON');
+  assert.equal(bridgeBinding(['node', `${shim(OLD)}.user-script`], options), '');
+  assert.equal(bridgeBinding(['node', shim(OLD), '--custom-argument'], options), '');
+  assert.equal(bridgeBinding([['node'], shim(OLD)], options), '');
+  write(claude, { hooks: { UserPromptSubmit: [null, { hooks: [cmd(OLD), cmd(CURRENT)] }], Stop: [{ hooks: [cmd(CURRENT)] }] } });
+  repairCaptureHooks(claude, 'claude', options);
+  assert.equal(read(claude).hooks.UserPromptSubmit[0], null, 'repair does not silently drop unrelated malformed groups');
+  write(claude, { hooks: Object.fromEntries(events.map(event => [event, [{ hooks: [cmd(OLD), cmd(CURRENT)] }]])) });
+  const originalRead = fs.readFileSync;
+  let reads = 0;
+  fs.readFileSync = function(file, ...args) {
+    const value = originalRead.call(this, file, ...args);
+    if (file === claude && ++reads === 2) write(claude, { ...JSON.parse(value), userConcurrentEdit: 'kept' });
+    return value;
+  };
+  try { assert.throws(() => repairCaptureHooks(claude, 'claude', options), error => error.code === 'CONFIG_CHANGED'); }
+  finally { fs.readFileSync = originalRead; }
+  assert.equal(read(claude).userConcurrentEdit, 'kept', 'a concurrent user edit is never overwritten');
+
+  // Real Git + real installed shims: the stale store is registered, but no
+  // repaired client invocation recreates it or sends duplicate events.
+  const repo = path.join(TEMP, '代码 中文 project');
+  fs.mkdirSync(repo, { recursive: true });
+  const git = spawnSync('git', ['init', '-q'], { cwd: repo, encoding: 'utf8', windowsHide: true });
+  assert.equal(git.status, 0, git.stderr);
+  const obsoleteStore = path.join(TEMP, 'knowledge/old-slug/dev-conversations');
+  const canonicalStore = path.join(TEMP, 'knowledge/Canonical-abcdef/dev-conversations');
+  await bridge.ensureRuntimeHome({ homeDir: OLD });
+  await bridge.projectRegistry.addProject({ home: OLD, path: repo, store: obsoleteStore });
+  await bridge.projectRegistry.addProject({ home: CURRENT, path: repo, store: canonicalStore });
+  fs.rmSync(path.join(TEMP, 'knowledge/old-slug'), { recursive: true, force: true });
+  write(claude, { hooks: Object.fromEntries(events.map(event => [event, [{ hooks: [cmd(OLD), cmd(CURRENT), cmd(CURRENT)] }]])) });
+  await item.installCaptureClaude();
+  const env = { ...process.env }; delete env.AI_CODING_EVENT_BRIDGE_HOME;
+  for (const [event, payload] of [
+    ['UserPromptSubmit', { prompt: 'isolated dedup test request' }],
+    ['Stop', { last_assistant_message: 'isolated dedup test answer' }],
+  ]) {
+    const hooks = read(claude).hooks[event].flatMap(group => group.hooks);
+    assert.equal(hooks.length, 1);
+    const call = spawnSync(process.execPath, [shim(CURRENT)], { cwd: repo, env, input: JSON.stringify({ hook_event_name: event, cwd: repo, session_id: 'dedup-test', ...payload }), encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    assert.equal(call.status, 0, call.stderr);
+  }
+  const journal = path.join(canonicalStore, 'journal/events.jsonl');
+  const captured = fs.readFileSync(journal, 'utf8').trim().split(/\r?\n/).map(line => JSON.parse(line));
+  assert.deepEqual(captured.map(row => row.eventType), ['user_prompt', 'assistant_response']);
+  assert(!fs.existsSync(obsoleteStore), 'the stale second directory is not recreated');
+  write(zcode, { hooks: { enabled: true, events: Object.fromEntries(events.map(event => [event, [{ hooks: [processHook(OLD), processHook(CURRENT), processHook(CURRENT)] }]])) } });
+  await item.installCaptureZCode();
+  for (const [event, payload] of [
+    ['UserPromptSubmit', { prompt: 'isolated zcode dedup request' }],
+    ['Stop', { last_assistant_message: 'isolated zcode dedup answer' }],
+  ]) {
+    const hooks = read(zcode).hooks.events[event].flatMap(group => group.hooks);
+    assert.equal(hooks.length, 1);
+    const call = spawnSync(process.execPath, hooks[0].args, { cwd: repo, env, input: JSON.stringify({ hook_event_name: event, cwd: repo, session_id: 'zcode-dedup-test', ...payload }), encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    assert.equal(call.status, 0, call.stderr);
+  }
+  const afterZCode = fs.readFileSync(journal, 'utf8').trim().split(/\r?\n/).map(line => JSON.parse(line));
+  assert.deepEqual(afterZCode.map(row => row.source), ['claude-code', 'claude-code', 'zcode', 'zcode']);
+  assert(!fs.existsSync(obsoleteStore), 'ZCode also cannot recreate the old knowledge folder');
+  console.log('capture-hook-dedup-test PASS (duplicate status, exact ownership, mixed-group preservation, idempotency, runtime failure and real journal capture)');
+}
+
+main().catch(error => { console.error(error.stack); process.exitCode = 1; }).finally(() => {
+  assert(path.resolve(TEMP).startsWith(path.resolve(os.tmpdir()) + path.sep));
+  fs.rmSync(TEMP, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+});

package/_site/_test/codex-notify-capture-e2e-test.js

@@ -73,10 +73,12 @@ async function main() {
   assert(captured.every(event => event.repoIdentity.workspaceId === registered.id && path.resolve(event.projectPath).toLowerCase() === path.resolve(repoPath).toLowerCase()), 'workspace comes from rollout metadata, not the notification or server cwd');
   assert(!JSON.stringify(captured).includes('NOT-EVIDENCE'), 'notification summaries are never captured as conversation facts');
 
-  const beforeRepeat = fs.statSync(cursorFile).mtimeMs;
+  const beforeRepeat = JSON.parse(fs.readFileSync(cursorFile, 'utf8')).updatedAt;
   await new Promise(resolve => setTimeout(resolve, 25));
   invokeNotify(notify, payload);
-  await waitFor(() => fs.statSync(cursorFile).mtimeMs !== beforeRepeat, 'second notification reaches the real cursor reader');
+  // Filesystems may coalesce mtime; the durable cursor timestamp proves that
+  // the reader completed another pass rather than merely touching a file.
+  await waitFor(() => JSON.parse(fs.readFileSync(cursorFile, 'utf8')).updatedAt !== beforeRepeat, 'second notification reaches the real cursor reader');
   assert.strictEqual(readEvents(eventsFile).length, 2, 'duplicate notify cannot duplicate captured evidence');
 
   invokeNotify(notify, JSON.stringify({ type: 'agent-turn-complete', 'thread-id': 'missing-session-e2e', 'last-assistant-message': 'must not be fabricated' }));

package/_site/_test/codex-notify-upgrade-test.js

@@ -165,6 +165,22 @@ async function main() {
   assert.strictEqual(readNotify(fanoutOnly.configFile), null, 'uninstall removes the notify entry only if no third-party notifier remains');
   assertUnrelatedSettings(fanoutOnly);
 
+  const defaultLegacy = name => ['node', path.join(TEMP, name, 'home', '.ai-coding-event-bridge', 'bin', 'bridge-hook.cjs')];
+  const rawLegacy = fixture('legacy-default-home', defaultLegacy('legacy-default-home'));
+  await assertInstallIdempotent(rawLegacy);
+  assert(!descendants(readNotify(rawLegacy.configFile)).some(command => command[1] === defaultLegacy('legacy-default-home')[1]), 'replace the known old standalone Bridge instead of chaining it as a third party');
+  await rawLegacy.manager.uninstallCaptureCodex();
+  assert.strictEqual(readNotify(rawLegacy.configFile), null, 'uninstall must not resurrect a retired Bridge home');
+
+  const nestedLegacyCommand = defaultLegacy('nested-legacy-default-home');
+  const legacyRadar = [...radar, '--previous-notify', JSON.stringify(nestedLegacyCommand)];
+  const nestedLegacy = fixture('nested-legacy-default-home', oldFanout('old-with-legacy-next', legacyRadar, staleBridge));
+  await assertInstallIdempotent(nestedLegacy);
+  assert(!descendants(readNotify(nestedLegacy.configFile)).some(command => command[1] === nestedLegacyCommand[1]), 'remove known stale Bridge capture hidden in a compatible notification branch');
+  assert(descendants(readNotify(nestedLegacy.configFile)).some(command => JSON.stringify(command) === JSON.stringify(radar)), 'preserve Radar and its non-notify arguments');
+  await nestedLegacy.manager.uninstallCaptureCodex();
+  assert.deepStrictEqual(readNotify(nestedLegacy.configFile), radar);
+
   // Missing files alone never authorize deleting a third-party notifier.
   // Neither a matching script basename nor the word devtask-radar is ownership.
   for (const [name, command] of [

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

@@ -79,7 +79,7 @@ const { runCli } = require('../../bin/project-knowledge-integrations');
     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');
+    assert(errors.some(entry => entry.operationId === failed.operationId && entry.context.client === 'zcode' && entry.error.message.includes('JSON')), 'actual failed phase and operation ID are persisted');
     fs.writeFileSync(configFile, JSON.stringify(twice));
     const removed = await request('/api/integrations/uninstall', { clients: ['zcode'], captureOnly: true });
     assert.equal(removed.complete, true);

package/_site/lib/capture-hook-config.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { writeFileAtomic } = require('./atomic-file');
+
+const EVENTS = ['UserPromptSubmit', 'Stop'];
+function normalized(file) {
+  const value = path.resolve(file).replace(/\\/g, '/');
+  return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+function nodeCommand(command) { return /(?:^|[\\/])node(?:\.exe)?$/i.test(command || ''); }
+
+// Only exact, known Bridge invocations are ours. A shell wrapper, extra
+// argument or a lookalike filename never authorizes removing a user hook.
+function bridgeBinding(args, options) {
+  if (!Array.isArray(args) || typeof args[0] !== 'string' || !nodeCommand(args[0]) || typeof args[1] !== 'string') return '';
+  if (args.length !== 2 && !(args.length === 4 && args[2] === '--source' && ['claude-code', 'claude', 'zcode', 'codex', 'opencode'].includes(args[3]))) return '';
+  const actual = normalized(args[1]);
+  const current = normalized(path.join(options.bridgeHomeDir, 'bin', 'bridge-hook.cjs'));
+  const legacy = normalized(path.join(options.homeDir || os.homedir(), '.ai-coding-event-bridge', 'bin', 'bridge-hook.cjs'));
+  return actual === current ? 'current' : actual === legacy ? 'legacy' : '';
+}
+
+function hookArgs(hook) {
+  if (!hook || typeof hook !== 'object') return null;
+  if (hook.type === 'process' && Array.isArray(hook.args)) return [hook.command, ...hook.args];
+  if (hook.type !== 'command' || typeof hook.command !== 'string') return null;
+  const match = hook.command.trim().match(/^(?:"([^"]+)"|'([^']+)'|(\S+))\s+(?:"([^"]+)"|'([^']+)'|(\S+))(?:\s+--source\s+(claude-code|claude|zcode|codex|opencode))?$/);
+  return match ? [match[1] || match[2] || match[3], match[4] || match[5] || match[6], ...(match[7] ? ['--source', match[7]] : [])] : null;
+}
+
+function configuration(file) {
+  const source = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  let config;
+  try { config = source ? JSON.parse(source) : {}; } catch { throw new Error('Agent 配置不是有效 JSON，未修改。'); }
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Agent 配置必须是 JSON 对象，未修改。');
+  return { source, config };
+}
+
+function planCaptureHooks(file, client, options, removeCurrent = false) {
+  if (!['claude', 'zcode'].includes(client)) throw new Error('不支持的采集配置类型。');
+  const { source, config } = configuration(file);
+  const hooks = config.hooks;
+  if (hooks != null && (typeof hooks !== 'object' || Array.isArray(hooks))) throw new Error('Agent hooks 配置格式异常，未修改。');
+  const events = client === 'zcode' ? hooks?.events : hooks;
+  if (events != null && (typeof events !== 'object' || Array.isArray(events))) throw new Error('Agent 事件配置格式异常，未修改。');
+  const removed = [], counts = {};
+  for (const event of EVENTS) {
+    const groups = events?.[event];
+    if (groups == null) { counts[event] = { current: 0, legacy: 0 }; continue; }
+    if (!Array.isArray(groups)) throw new Error('Agent 事件列表格式异常，未修改。');
+    const count = { current: 0, legacy: 0 };
+    for (const group of groups) {
+      if (group?.hooks != null && !Array.isArray(group.hooks)) throw new Error('Agent Hook 列表格式异常，未修改。');
+      for (const hook of group?.hooks || []) { const binding = bridgeBinding(hookArgs(hook), options); if (binding) count[binding]++; }
+    }
+    counts[event] = count;
+    // Materialize the replacement first; never remove the only working old
+    // capture when installing the new runtime has failed.
+    if (!count.current) continue;
+    let keptCurrent = false;
+    const removedGroup = Symbol('empty-owned-group');
+    events[event] = groups.map((group, groupIndex) => {
+      if (!Array.isArray(group?.hooks)) return group;
+      const kept = group.hooks.filter((hook, hookIndex) => {
+        const binding = bridgeBinding(hookArgs(hook), options);
+        if (!binding) return true;
+        if (removeCurrent && binding === 'legacy') return true;
+        if (!removeCurrent && binding === 'current' && !keptCurrent) { keptCurrent = true; return true; }
+        // Back up only owned invocation fields, never unrelated config/env.
+        const saved = Object.fromEntries(['type', 'command', 'args', 'timeout', 'timeoutMs'].filter(key => hook[key] !== undefined).map(key => [key, hook[key]]));
+        removed.push({ event, groupIndex, hookIndex, hook: saved, binding });
+        return false;
+      });
+      return kept.length === group.hooks.length ? group : kept.length ? { ...group, hooks: kept } : removedGroup;
+    }).filter(group => group !== removedGroup);
+  }
+  return { source, config, counts, removed, repairNeeded: Object.values(counts).some(count => count.legacy > 0 || count.current > 1) };
+}
+
+function writePlan(file, client, plan) {
+  if (!plan.removed.length) return { changed: false, removedLegacy: 0, removedDuplicates: 0 };
+  const assertUnchanged = () => {
+    if (fs.readFileSync(file, 'utf8') !== plan.source) throw Object.assign(new Error('Agent 配置已被其他程序修改，请重试接入。'), { code: 'CONFIG_CHANGED' });
+  };
+  assertUnchanged();
+  const backupFile = `${file}.project-knowledge-capture-${Date.now()}-${crypto.randomBytes(4).toString('hex')}.bak`;
+  writeFileAtomic(backupFile, JSON.stringify({ schema: 'project-knowledge/capture-backup/v1', client, removed: plan.removed }, null, 2) + '\n');
+  const eol = plan.source.includes('\r\n') ? '\r\n' : '\n';
+  writeFileAtomic(file, (JSON.stringify(plan.config, null, 2) + '\n').replace(/\n/g, eol), { beforeRename: assertUnchanged });
+  return { changed: true, backupFile, removedLegacy: plan.removed.filter(row => row.binding === 'legacy').length, removedDuplicates: plan.removed.filter(row => row.binding === 'current').length };
+}
+
+function repairCaptureHooks(file, client, options) {
+  const plan = planCaptureHooks(file, client, options);
+  if (EVENTS.some(event => !plan.counts[event].current)) throw new Error('当前 Bridge 入口未完整建立，保留旧采集接线。');
+  if (!fs.existsSync(path.join(options.bridgeHomeDir, 'bin', 'bridge-hook.cjs'))) throw new Error('当前 Bridge 运行入口缺失，保留旧采集接线。');
+  return writePlan(file, client, plan);
+}
+
+function removeCaptureHooks(file, client, options) {
+  return writePlan(file, client, planCaptureHooks(file, client, options, true));
+}
+
+module.exports = { bridgeBinding, planCaptureHooks, repairCaptureHooks, removeCaptureHooks };

package/_site/lib/codex-notify-config.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { bridgeBinding } = require('./capture-hook-config');
 
 function readNotify(configFile) {
   const source = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : '';
@@ -79,7 +80,7 @@ function inspectTree(args, options, state, depth = 0) {
       || args.length !== (next ? 6 : 4)) throw Object.assign(new Error('托管通知链格式异常，未覆盖现有配置。'), { code: 'CAPTURE_CONFLICT' });
     state.owned = true;
     inspectTree(next && next.args, options, state, depth + 1);
-  } else if (sameCommand(args, bridgeCommand(options.bridgeHomeDir))) {
+  } else if (bridgeBinding(args, options)) {
     state.owned = true;
   } else if (desktopCommand(args)) {
     const previous = nested(args, '--previous-notify');
@@ -114,7 +115,7 @@ function rewriteTree(args, options, state, canAnchor = true) {
     const cleaned = rewriteTree(next && next.args, options, state, false);
     return anchor ? fanout(cleaned, options) : cleaned;
   }
-  if (sameCommand(args, bridgeCommand(options.bridgeHomeDir))) return null;
+  if (bridgeBinding(args, options)) return null;
   if (desktopCommand(args)) {
     const previous = nested(args, '--previous-notify');
     const cleaned = rewriteTree(previous && previous.args, options, state, canAnchor);

package/_site/lib/integration-installer.js

@@ -8,6 +8,7 @@ const { applyEdits, modify, parse } = require('jsonc-parser');
 const packageInfo = require('../../package.json');
 const { resolveDataDirPath } = require('./data-dir');
 const { planNotify, writeNotify } = require('./codex-notify-config');
+const { planCaptureHooks, repairCaptureHooks, removeCaptureHooks } = require('./capture-hook-config');
 
 // Fail-open module resolution: a missing/unloadable Bridge package must
 // degrade Development Capture status, never crash server startup.
@@ -253,7 +254,8 @@ class IntegrationManager {
     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 });
+      const repairContext = { ...context, ...(typeof result.changed === 'boolean' ? { changed: result.changed } : {}), ...(Number.isInteger(result.removedLegacy) ? { removedLegacy: result.removedLegacy, removedDuplicates: result.removedDuplicates } : {}) };
+      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: repairContext });
       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 });
@@ -266,19 +268,24 @@ class IntegrationManager {
       this.planned.push({ command: 'bridge', args: ['installZcodeHook', this.bridgeHomeDir] });
       return { state: 'planned', installed: false, detail: '计划接入 ZCode 会话采集，未修改配置。' };
     }
+    planCaptureHooks(this.zcodeConfigFile, 'zcode', this);
     await this.bridge.installers.zcode.installZcodeHook(this._captureInstallerOptions('zcode'));
+    const repaired = repairCaptureHooks(this.zcodeConfigFile, 'zcode', this);
     const status = await this.statusCaptureZCode();
     if (!status.installed) throw new Error('ZCode Hook 写入后校验失败，请检查 hooks.enabled 与事件配置。');
-    return status;
+    return { ...status, ...repaired };
   }
 
   async statusCaptureZCode() {
     const status = await this.bridge.installers.zcode.statusZcodeHook(this._captureInstallerOptions('zcode'));
+    const plan = planCaptureHooks(this.zcodeConfigFile, 'zcode', this);
+    if (plan.repairNeeded || status.installed && !fs.existsSync(path.join(this.bridgeHomeDir, 'bin', 'bridge-hook.cjs'))) return { state: 'needs-repair', installed: false, conflict: false, repairNeeded: true, detail: '检测到重复、旧接线或缺失的 Bridge 入口，请执行接入/修复。' };
     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 采集，未修改配置。' };
+    removeCaptureHooks(this.zcodeConfigFile, 'zcode', this);
     await this.bridge.installers.zcode.uninstallZcodeHook(this._captureInstallerOptions('zcode'));
     return { state: 'removed', installed: false, detail: '已移除 ZCode 托管采集，保留第三方配置与已有记录。' };
   }
@@ -288,12 +295,17 @@ class IntegrationManager {
       this.planned.push({ command: 'bridge', args: ['installClaudeCodeHook', this.bridgeHomeDir] });
       return { state: 'planned', installed: false, conflict: false, detail: 'managed Bridge hooks (dry-run)' };
     }
+    planCaptureHooks(this.claudeSettingsFile, 'claude', this);
     const result = await this.bridge.installers.claudeCode.installClaudeCodeHook(this._captureInstallerOptions());
-    return { state: 'installed', installed: true, conflict: false, detail: `managed hooks: ${result.added.join(', ') || 'already present'}` };
+    if (result.runtime?.conflict) throw new Error('Bridge 运行版本冲突，保留旧采集接线。');
+    const repaired = repairCaptureHooks(this.claudeSettingsFile, 'claude', this);
+    return { state: 'installed', installed: true, conflict: false, detail: `managed hooks: ${result.added.join(', ') || 'already present'}`, ...repaired };
   }
 
   async statusCaptureClaude() {
     const status = await this.bridge.installers.claudeCode.statusClaudeCodeHook(this._captureInstallerOptions());
+    const plan = planCaptureHooks(this.claudeSettingsFile, 'claude', this);
+    if (plan.repairNeeded || status.installed && !fs.existsSync(path.join(this.bridgeHomeDir, 'bin', 'bridge-hook.cjs'))) return { state: 'needs-repair', installed: false, conflict: false, repairNeeded: true, detail: '检测到重复、旧接线或缺失的 Bridge 入口，请执行接入/修复。' };
     return {
       state: status.installed ? 'installed' : 'not-installed',
       installed: status.installed,
@@ -303,6 +315,8 @@ class IntegrationManager {
   }
 
   async uninstallCaptureClaude(options = {}) {
+    if (this.dryRun) return { state: 'planned', detail: '计划移除 Claude Code 采集，未修改配置。' };
+    removeCaptureHooks(this.claudeSettingsFile, 'claude', this);
     await this.bridge.installers.claudeCode.uninstallClaudeCodeHook({
       ...this._captureInstallerOptions(),
       unregisterConsumer: options.unregisterConsumer === true,

package/module-runtime-manifest.json

@@ -7,10 +7,10 @@
     "ui/favicon.svg": "c48be946b224112ebb0238b44263f7a61bda31e531afa895c2e9801c0ff24f32",
     "plugins/project-knowledge/hooks/claude.json": "d61510327e3e1facbb4c645228e9f50cad05a88b33d80c4c22e5ba9f8b9f5359",
     "plugins/project-knowledge/scripts/context-hook.cjs": "b138fab6d8fcb35f8101ccfda565ccec694acb888f94347c5864c804ebb5e1a0",
-    "plugins/project-knowledge/.claude-plugin/plugin.json": "2322a6ab161d407736647abf836cb9669b8fe628c644884627d91d330975992e",
-    "plugins/project-knowledge/.mcp.json": "b2b7eea17eb9c934b71452048fc29cd354af320fac4525048b9bd570402096c7",
+    "plugins/project-knowledge/.claude-plugin/plugin.json": "cf50fe8dacbec068c46e531114c1f81576e63578692ab165795b96c69ace63a3",
+    "plugins/project-knowledge/.mcp.json": "6b4e25e51cc24361810af627be6bda0a97cc416230056308fab56ed5ddc1d73b",
     "plugins/project-knowledge/hooks/codex.json": "216e03c07295606ef6ebb2c4f669ad0d790b5e7c4f3f34600488033db75e4239",
-    "plugins/project-knowledge/.codex-plugin/plugin.json": "7a51b3c5db64c57e7c35ad0511ca206a833a95c09628f94b64caca25be9a55fe"
+    "plugins/project-knowledge/.codex-plugin/plugin.json": "33075d6e47ba58c443eda339706f57688efb9974fa3bbb08f7cc09604602a87f"
   },
   "modules": {
     "terminal": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {

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

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "project-knowledge",
   "hooks": "./hooks/claude.json",
-  "version": "5.0.12",
+  "version": "5.0.13",
   "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.12",
+  "version": "5.0.13",
   "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.12",
+        "@sanqianx/project-knowledge@5.0.13",
         "project-knowledge-mcp"
       ]
     }