@sanqianx/project-knowledge 4.8.0 → 5.0.1

package/_site/lib/data-dir.js

@@ -1,81 +1,13 @@
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-const { LEGACY_ASSETS, assetPath } = require('./legacy-data-manifest');
-const { isEmptyJson } = require('./data-state-classifier');
-
-let _resolved = null;
-
-function resolveDataDirPath(options = {}) {
-  const fromEnv = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
-  const homeDir = options.homeDir || os.homedir();
-  return path.resolve(fromEnv || path.join(homeDir, '.project-knowledge'));
-}
-function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
-function getDataDir() { if (!_resolved) _resolved = resolveDataDirPath(); return _resolved; }
-function _resetCache() { _resolved = null; }
-function fileDigest(filePath) { return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); }
-function directoryDigest(root) {
-  const hash = crypto.createHash('sha256');
-  const walk = current => {
-    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const filePath = path.join(current, entry.name);
-      const relative = path.relative(root, filePath).replace(/\\/g, '/');
-      hash.update(`${entry.isDirectory() ? 'd' : 'f'}:${relative}\0`);
-      if (entry.isDirectory()) walk(filePath); else if (entry.isFile()) hash.update(fs.readFileSync(filePath));
-    }
-  };
-  walk(root); return hash.digest('hex');
-}
-function isEmptyAsset(filePath, asset) {
-  if (!fs.existsSync(filePath)) return true;
-  if (asset.kind === 'dir') return fs.readdirSync(filePath).length === 0;
-  if (fs.statSync(filePath).size === 0) return true;
-  if (!filePath.endsWith('.json')) return false;
-  try { const raw = fs.readFileSync(filePath, 'utf8'); return isEmptyJson(JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw)); } catch { return false; }
-}
-function assetsEqual(source, target, asset) { return asset.kind === 'dir' ? directoryDigest(source) === directoryDigest(target) : fileDigest(source) === fileDigest(target); }
-function copyDir(source, target) {
-  fs.mkdirSync(target, { recursive: true });
-  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-    const from = path.join(source, entry.name); const to = path.join(target, entry.name);
-    if (entry.isDirectory()) copyDir(from, to); else if (entry.isFile()) fs.copyFileSync(from, to);
-  }
-}
-
-function migrateFromLegacy({ legacyRoot, logger } = {}) {
-  if (process.env.KB_SKIP_MIGRATION === '1') return { ok: true, migrated: false, reason: 'skipped via KB_SKIP_MIGRATION=1' };
-  if (!legacyRoot || !fs.existsSync(legacyRoot)) return { ok: true, migrated: false, reason: legacyRoot ? 'legacy root does not exist' : 'no legacy root provided' };
-  const dataDir = getDataDir();
-  if (path.resolve(legacyRoot) === dataDir) return { ok: true, migrated: false, reason: 'legacy root equals data dir' };
-  // Packaged application roots may include empty scaffolding such as
-  // `projects/`. It is not user data and must never conflict with populated
-  // runtime data during startup relocation.
-  const sources = LEGACY_ASSETS.filter(asset => {
-    const source = assetPath(legacyRoot, asset);
-    return fs.existsSync(source) && !isEmptyAsset(source, asset);
-  });
-  if (!sources.length) return { ok: true, migrated: false, reason: 'no legacy assets found' };
-  const conflicts = [];
-  for (const asset of sources) {
-    const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
-    if (fs.existsSync(target) && !isEmptyAsset(target, asset) && !assetsEqual(source, target, asset)) conflicts.push(asset.target);
-  }
-  if (conflicts.length) return { ok: false, migrated: false, requiresManualRecovery: true, reason: 'legacy-data-conflict', conflicts, source: legacyRoot, target: dataDir };
-  ensureDataDir(dataDir);
-  const result = { ok: true, migrated: false, files: 0, dirs: 0, source: legacyRoot, target: dataDir };
-  try {
-    for (const asset of sources) {
-      const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
-      if (fs.existsSync(target) && assetsEqual(source, target, asset)) continue;
-      if (asset.kind === 'dir') { if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true }); copyDir(source, target); result.dirs++; }
-      else { fs.mkdirSync(path.dirname(target), { recursive: true }); fs.copyFileSync(source, target); result.files++; }
-    }
-    result.migrated = result.files > 0 || result.dirs > 0;
-    if (result.migrated && logger) logger(`migrated runtime data to ${dataDir} (${result.files} files, ${result.dirs} dirs from ${legacyRoot})`);
-    return result;
-  } catch (error) { return { ...result, ok: false, error: `failed to relocate legacy runtime data: ${error.message}` }; }
-}
-
-module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, migrateFromLegacy, LEGACY_ASSETS, _resetCache };
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+let resolved = null;
+function resolveDataDirPath(options = {}) {
+  const configured = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
+  return path.resolve(configured || path.join(options.homeDir || os.homedir(), '.project-knowledge-v5'));
+}
+function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
+function getDataDir() { if (!resolved) resolved = resolveDataDirPath(); return resolved; }
+function _resetCache() { resolved = null; }
+module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, _resetCache };

package/_site/lib/engine-connection.js

@@ -0,0 +1,67 @@
+const { DomainError } = require('./contracts');
+const { execGit } = require('./git-runner');
+
+async function connectEngine(runtime) {
+  if (runtime.analysisOwner === 'legacy' || runtime.engineConnecting) return;
+  runtime.engineConnecting = true;
+  let step = 'engine-health';
+  let projectId = '';
+  let httpStatus = 0;
+  try {
+    const bridge = runtime.moduleBridge;
+    if (bridge.engineCompatible === undefined) bridge.engineCompatible = false;
+    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${bridge.runtimeToken}` };
+    const health = await bridge._fetch(`${bridge.engineUrl}/api/health`);
+    httpStatus = health.status;
+    if (!health.ok) throw new Error('ENGINE_UNAVAILABLE');
+    const engine = await health.json();
+    if (engine.name !== 'knowledge-engine' || engine.dataSchemaVersion !== 3) throw new Error('ENGINE_VERSION_MISMATCH');
+    step = 'runtime-authentication';
+    const auth = await bridge._fetch(`${bridge.engineUrl}/api/runtime-auth`, { headers });
+    httpStatus = auth.status;
+    if (!auth.ok) throw new Error('RUNTIME_AUTH_REQUIRED');
+    bridge.engineCompatible = true;
+    step = 'project-wiring';
+    for (const id of runtime.registryStore.listIds()) {
+      projectId = id;
+      const config = runtime.projectStore.readConfig(id);
+      const modules = await bridge.registerProjectLinks({ projectId: id, name: config.displayName, workspacePath: config.repoPath, knowledgePath: config.knowledgePath });
+      if (!modules.engine.ok || !modules.eventBridge.ok) throw new Error('PROJECT_WIRING_PENDING');
+    }
+    projectId = '';
+    step = 'runtime-configuration';
+    await bridge.syncEngineConfiguration();
+    step = 'engine-activation';
+    const activated = await bridge._fetch(`${bridge.engineUrl}/api/control`, { method: 'POST', headers, body: JSON.stringify({ enabled: true }) });
+    httpStatus = activated.status;
+    if (!activated.ok) throw new Error(activated.status === 403 ? 'RUNTIME_AUTH_REQUIRED' : 'ENGINE_ACTIVATION_FAILED');
+    runtime.ownership = { owner: 'engine', ready: true };
+  } catch (error) {
+    const codes = ['ENGINE_UNAVAILABLE', 'ENGINE_VERSION_MISMATCH', 'PROJECT_WIRING_PENDING', 'RUNTIME_AUTH_REQUIRED', 'ENGINE_ACTIVATION_FAILED'];
+    const code = codes.includes(error.message) ? error.message : 'ENGINE_CONNECTION_FAILED';
+    if (['ENGINE_VERSION_MISMATCH', 'RUNTIME_AUTH_REQUIRED'].includes(code)) runtime.moduleBridge.engineCompatible = false;
+    const messages = {
+      ENGINE_VERSION_MISMATCH: '检测到旧版知识引擎，请停止旧版服务后重新启动新版。',
+      RUNTIME_AUTH_REQUIRED: '引擎服务与外壳鉴权不一致，请停止旧版服务后重新启动新版。',
+      PROJECT_WIRING_PENDING: '项目接线未完成，请检查模块连接。',
+    };
+    const message = messages[code] || '知识引擎连接未完成，服务恢复后自动重试。';
+    const previous = runtime.ownership?.error;
+    runtime.ownership = { owner: 'engine', ready: false, message, error: { code, step, httpStatus, ...(projectId ? { projectId } : {}) } };
+    if (previous?.code !== code || previous?.step !== step || (previous?.projectId || '') !== projectId) await runtime.logger.warn('engine.connection_pending', message, { component: 'engine-connection', phase: step, projectId, context: { code, httpStatus } });
+  } finally { runtime.engineConnecting = false; }
+}
+
+async function forwardCommitToBridge(runtime, event) {
+  const config = runtime.projectStore.readConfig(event.projectId);
+  if (!runtime.layout.pathsEqual(config.repoPath, event.repoRoot) || !/^[a-f0-9]{40}$/i.test(event.head || '')) throw new DomainError('INVALID_ARGUMENT', '提交通知与项目绑定不匹配。');
+  const exists = await execGit(config.repoPath, ['cat-file', '-e', `${event.head}^{commit}`]);
+  if (!exists.ok) throw new DomainError('INVALID_ARGUMENT', '提交不属于当前仓库。');
+  const identity = await runtime.bridgeAdapter.resolveRepoIdentity(config.repoPath);
+  const result = await runtime.bridgeAdapter.appendCommitBoundary({ projectId: event.projectId, repoIdentity: identity.repoIdentity, commitSha: event.head, branch: event.branch || null, operationId: event.operationId });
+  if (result.status !== 'captured') throw new DomainError('MODULE_UNREACHABLE', '事件记录失败，请恢复事件模块后重试。', { status: 503 });
+  runtime.moduleBridge._fetch(`${runtime.moduleBridge.engineUrl}/api/bridge/notify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }).catch(() => {});
+  return { journalSequence: result.boundary?.journalSequence || result.boundary?.sequence };
+}
+
+module.exports = { connectEngine, forwardCommitToBridge };

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; }
 }
 
@@ -111,7 +111,7 @@ function installHook(options = {}) {
       // refusing — otherwise import promises a migration the installer
       // rejects for every repo hooked by an older KB generation.
     }
-    if (marker && marker.projectId !== projectId) {
+    if (marker && marker.projectId !== projectId && options.replaceManagedHookProjectId !== marker.projectId) {
       throw new DomainError('HOOK_CONFLICT', 'The managed hook belongs to another project.', { status: 409 });
     }
     if (existing === body) return { ok: true, installed: true, updated: false, hookPath, projectId, managedVersion: MANAGED_VERSION };

package/_site/lib/integration-installer.js

@@ -6,6 +6,7 @@ const { spawnSync } = require('child_process');
 const crossSpawn = require('cross-spawn');
 const { applyEdits, modify, parse } = require('jsonc-parser');
 const packageInfo = require('../../package.json');
+const { resolveDataDirPath } = require('./data-dir');
 
 // Fail-open module resolution: a missing/unloadable Bridge package must
 // degrade Development Capture status, never crash server startup.
@@ -327,7 +328,7 @@ class IntegrationManager {
     this.bridgeConsumerName = options.bridgeConsumerName || DEFAULT_BRIDGE_CONSUMER;
     this.bridgeHomeDir = options.bridgeHomeDir
       || this.env.AI_CODING_EVENT_BRIDGE_HOME
-      || path.join(this.homeDir, '.ai-coding-event-bridge');
+      || 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 || '';

package/_site/lib/module-bridge.js

@@ -186,6 +186,7 @@ class ModuleBridge {
   }
 
   proxyEngine(req, res, pathname, search) {
+    if (this.engineCompatible === false) throw new DomainError('ENGINE_CONNECTION_PENDING', '知识引擎连接尚未确认，请查看系统状态；不会读取旧服务中的知识。', { status: 503 });
     return this.proxy(req, res, `${this.engineUrl}/api/${pathname.replace(/^\/api\/engine\/?/, '')}${search || ''}`);
   }
 
@@ -230,6 +231,7 @@ class ModuleBridge {
   }
 
   async _listEngineProjects() {
+    if (this.engineCompatible === false) return [];
     try {
       const response = await this._fetch(`${this.engineUrl}/api/projects`);
       if (!response.ok) return [];
@@ -333,16 +335,6 @@ class ModuleBridge {
       const response = await this._fetch(`${this.engineUrl}/api/runtime-config`, { method: 'POST', headers, body: JSON.stringify({ projectId: 'default', profile }) });
       status.model = response.ok && !!profile;
     } catch { /* Status projection only: never log resolved profiles or raw errors. */ }
-    try {
-      const legacyResponse = await this._fetch(`${this.vectorHubUrl}/api/internal/embedding-config`, { method: 'POST', headers, body: '{}' });
-      if (legacyResponse.ok) {
-        const legacy = await legacyResponse.json();
-        if (legacy.settings && /^embedding-[a-f0-9]{64}$/.test(legacy.migrationId || '')) {
-          const imported = await this._fetch(`${this.terminalUrl}/api/claude-workbench/v1/internal/import-embedding`, { method: 'POST', headers, body: JSON.stringify(legacy) });
-          if (imported.ok) await this._fetch(`${this.vectorHubUrl}/api/internal/retire-embedding`, { method: 'POST', headers, body: JSON.stringify({ migrationId: legacy.migrationId }) });
-        }
-      }
-    } catch { /* Failed migration retains the module's protected configuration. */ }
     try {
       let settings = null;
       try {
@@ -462,7 +454,7 @@ class ModuleBridge {
       if (!requireEngine) result.engine = { ok: true, status: 'not-owner' };
       else {
       const response = await this._fetch(`${this.engineUrl}/api/projects/${encodeURIComponent(projectId)}`, { method: 'DELETE' });
-      if (response.status === 409) throw new DomainError('PROJECT_BUSY', '知识维护仍在运行，不能解绑。', { status: 409, retryable: true });
+      if (response.status === 409) throw new DomainError('PROJECT_BUSY', '此项目正在执行知识维护，请等待写入结束后再解绑。未开始的排队任务会随解绑取消。', { status: 409, retryable: true });
       result.engine = { ok: response.ok || response.status === 404, status: response.ok || response.status === 404 ? 'removed' : 'pending' };
       }
     } catch (error) { if (error.code === 'PROJECT_BUSY') throw error; result.engine = { ok: false, status: 'pending' }; }
@@ -549,7 +541,7 @@ class ModuleBridge {
           name: 'terminal',
           command: `node ${JSON.stringify(terminalEntry)}`,
           url: this.terminalUrl,
-          env: { AGENT_TERMINAL_PORT: urlPort(this.terminalUrl, 5760), AGENT_TERMINAL_HOST: urlHost(this.terminalUrl), KB_WORKBENCH_RUNTIME_TOKEN: this.runtimeToken, KB_KNOWLEDGE_ENGINE_URL: this.engineUrl, KB_EVENT_BRIDGE_URL: this.eventBridgeUrl },
+          env: { AGENT_TERMINAL_DATA_DIR: path.join(this.dataDir || require('./data-dir').getDataDir(), 'workbench'), AGENT_TERMINAL_PORT: urlPort(this.terminalUrl, 5760), AGENT_TERMINAL_HOST: urlHost(this.terminalUrl), KB_WORKBENCH_RUNTIME_TOKEN: this.runtimeToken, KB_KNOWLEDGE_ENGINE_URL: this.engineUrl, KB_EVENT_BRIDGE_URL: this.eventBridgeUrl },
         });
       } else {
         this.logger.warn('modules.supervisor', 'claude-ai-workbench runtime not installed; expecting an external service.', {});
@@ -572,7 +564,7 @@ class ModuleBridge {
           name: 'vector-hub',
           command: `node ${JSON.stringify(vectorHubEntry)} serve --host ${urlHost(this.vectorHubUrl)} --port ${urlPort(this.vectorHubUrl, 8787)} --root ${JSON.stringify(root)}`,
           url: this.vectorHubUrl,
-          env: { VECTOR_HUB_ROOT: root, VECTOR_HUB_CONFIG: process.env.VECTOR_HUB_CONFIG || path.join(root, 'config.json'), VECTOR_HUB_LEGACY_CONFIG: process.env.VECTOR_HUB_LEGACY_CONFIG || path.join(require('os').homedir(), '.vector-hub', 'config.json'), KB_VECTOR_MANAGED: '1', KB_VECTOR_RUNTIME_TOKEN: this.runtimeToken },
+          env: { VECTOR_HUB_ROOT: root, VECTOR_HUB_CONFIG: path.join(root, 'config.json'), VECTOR_HUB_LEGACY_CONFIG: path.join(root, 'no-legacy-config.json'), KB_VECTOR_MANAGED: '1', KB_VECTOR_RUNTIME_TOKEN: this.runtimeToken },
         });
       }
     }
@@ -589,9 +581,7 @@ class ModuleBridge {
       if (!eventBridgeEntry) {
         this.logger.warn('modules.supervisor', '@sanqianx/ai-coding-event-bridge-console runtime not installed; expecting an external service.', {});
       } else {
-        const homeArgs = process.env.AI_CODING_EVENT_BRIDGE_HOME
-          ? ` --home ${JSON.stringify(process.env.AI_CODING_EVENT_BRIDGE_HOME)}`
-          : '';
+        const homeArgs = ` --home ${JSON.stringify(process.env.AI_CODING_EVENT_BRIDGE_HOME || path.join(this.dataDir || require('./data-dir').getDataDir(), 'events'))}`;
         specs.push({
           name: 'event-bridge',
           command: `node ${JSON.stringify(eventBridgeEntry)} serve --host ${urlHost(this.eventBridgeUrl)} --port ${urlPort(this.eventBridgeUrl, 8790)}${homeArgs}`,

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/product-data.js

@@ -0,0 +1,24 @@
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const { DomainError } = require('./contracts');
+
+const DATA_SCHEMA = 'project-knowledge/fresh-product-data/v1';
+
+function initializeProductData(dataPath) {
+  const marker = path.join(dataPath, 'product-data.json');
+  if (fs.existsSync(marker)) {
+    const value = AtomicFile.readJsonStrict(marker);
+    if (value.schema !== DATA_SCHEMA) throw new DomainError('SCHEMA_UNSUPPORTED', '数据目录格式不受支持，请使用新的空目录重新导入项目。', { status: 409 });
+    return;
+  }
+  // Old registries and unfinished claims must never become fresh product work.
+  const oldData = ['settings.json', 'projects.json', 'projects', 'runtime', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json'].some(name => {
+    const file = path.join(dataPath, name);
+    return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
+  });
+  if (oldData) throw new DomainError('SCHEMA_UNSUPPORTED', '不再迁移旧版知识库数据。请取消旧 KB_DATA_DIR 设置，或指定新的空数据目录，然后重新导入项目。', { status: 409 });
+  AtomicFile.writeJsonAtomic(marker, { schema: DATA_SCHEMA, createdAt: new Date().toISOString() });
+}
+
+module.exports = { initializeProductData, DATA_SCHEMA };

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,
@@ -163,6 +164,8 @@ class ProjectLifecycleService {
           // Legacy v1 hook: import will replace it; that's the migration
           // path (T03 case 2), not a conflict.
           checks.hook = { ok: true, reason: 'legacy-v1' };
+        } else if (hookStatus.kbManaged && hookStatus.projectId !== input.projectId) {
+          checks.hook = { ok: true, replacementProjectId: hookStatus.projectId };
         } else {
           checks.hook = { ok: true };
         }
@@ -268,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 = {}) {
@@ -354,7 +357,15 @@ class ProjectLifecycleService {
       journal.created.metadata = this.layout.getProjectMetadataDir(projectId);
       journal.phase = 'metadata-created';
       this.writeJournal(journal);
-      const hook = this.hookManager.installHook({ repoPath: git.repoPath, projectId, triggerScriptPath: this.triggerScriptPath, dataDir: this.layout.getDataDir(), ...this.bridgeAdapter?.hookBinding?.() });
+      const priorHook = this.hookManager.readHookStatus({ repoPath: git.repoPath });
+      if (priorHook.kbManaged && priorHook.projectId !== projectId) {
+        if (input.replaceManagedHookProjectId !== priorHook.projectId || this.registryStore.readDisplaySnapshot(priorHook.projectId)) throw new DomainError('HOOK_CONFLICT', '目录中留有另一项目的知识库 Hook。请确认替换旧托管 Hook 后重新导入。', { status: 409 });
+        journal.replacedHook = { path: priorHook.hookPath, content: fs.readFileSync(priorHook.hookPath, 'utf8') };
+        this.writeJournal(journal);
+      }
+      journal.created.hookPath = priorHook.hookPath;
+      this.writeJournal(journal);
+      const hook = this.hookManager.installHook({ repoPath: git.repoPath, projectId, triggerScriptPath: this.triggerScriptPath, dataDir: this.layout.getDataDir(), ...this.bridgeAdapter?.hookBinding?.(), replaceManagedHookProjectId: input.replaceManagedHookProjectId });
       journal.created.hookPath = hook.hookPath;
       journal.phase = 'hook-verified';
       this.writeJournal(journal);
@@ -366,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 } });
     }
   }
@@ -419,7 +434,13 @@ class ProjectLifecycleService {
       try { await this.registryStore.remove(journal.projectId); } catch (error) { warnings.push(`registry:${error.message}`); }
     }
     if (journal.created.hookPath && journal.projectId && journal.repoPath) {
-      try { this.hookManager.uninstallHook({ repoPath: journal.repoPath, projectId: journal.projectId }); } catch (error) { warnings.push(`hook:${error.message}`); }
+      try {
+        const unchanged = journal.replacedHook && fs.existsSync(journal.replacedHook.path) && fs.readFileSync(journal.replacedHook.path, 'utf8') === journal.replacedHook.content;
+        if (!unchanged) {
+          this.hookManager.uninstallHook({ repoPath: journal.repoPath, projectId: journal.projectId });
+          if (journal.replacedHook) AtomicFile.writeFileAtomic(journal.replacedHook.path, journal.replacedHook.content, { mode: 0o755 });
+        }
+      } catch (error) { warnings.push(`hook:${error.message}`); }
     }
     if (journal.created.metadata && fs.existsSync(journal.created.metadata)) {
       try { fs.rmSync(journal.created.metadata, { recursive: true, force: true }); } catch (error) { warnings.push(`metadata:${error.message}`); }

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

@@ -11,7 +11,6 @@ const { StorageLayout } = require('./storage-layout');
 const { SettingsStore } = require('./settings-store');
 const { ProjectRegistryStore } = require('./project-registry-store');
 const { ProjectStore } = require('./project-store');
-const { MigrationService } = require('./migration-service');
 const { ProjectLifecycleService } = require('./project-lifecycle-service');
 const { RequirementRecorder } = require('./requirement-recorder');
 const { ConversationStore } = require('./conversation-store');
@@ -25,7 +24,8 @@ const { handlePostCommitEvent, recoverOrphanedClaims } = require('./post-commit-
 const { KnowledgePromotionService, hashBuffer } = require('./knowledge-promotion');
 const { resolveEffectiveAiProfile } = require('./ai-profile-resolver');
 const { ModuleBridge } = require('./module-bridge');
-const { prepareEngineCutover, finishEngineCutover, forwardCommitToBridge } = require('./engine-cutover');
+const { connectEngine, forwardCommitToBridge } = require('./engine-connection');
+const { initializeProductData } = require('./product-data');
 const { IndexService } = require('./index-service');
 const { KnowledgeDatabase } = require('./knowledge-db');
 const { LocalEmbeddingService } = require('./embedding-service');
@@ -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()),
@@ -442,6 +442,7 @@ class RuntimeKnowledgeAnalyzer {
 function createRuntime(options = {}) {
   const rootDir = path.resolve(options.rootDir || path.resolve(__dirname, '..', '..'));
   const dataPath = path.resolve(options.dataDir || dataDir.getDataDir());
+  if (options.analysisOwner === 'engine') initializeProductData(dataPath);
   const layout = options.layout || new StorageLayout({ dataDir: dataPath });
   const settingsStore = options.settingsStore || new SettingsStore({ layout });
   const registryStore = options.registryStore || new ProjectRegistryStore({ layout });
@@ -466,7 +467,7 @@ function createRuntime(options = {}) {
     secretsProvider,
   });
   const activeTasks = new Map();
-  const bridgeAdapter = options.bridgeAdapter || new BridgeAdapter({ dataDir: dataPath });
+  const bridgeAdapter = options.bridgeAdapter || new BridgeAdapter({ dataDir: dataPath, ...(options.analysisOwner === 'engine' ? { bridgeHomeDir: process.env.AI_CODING_EVENT_BRIDGE_HOME || path.join(dataPath, 'events') } : {}) });
   const conversationStore = options.conversationStore || new ConversationStore({ layout, projectStore, logger });
   const bridgeConsumerService = options.bridgeConsumerService || new BridgeConsumerService({
     bridgeAdapter,
@@ -505,12 +506,11 @@ function createRuntime(options = {}) {
     isProjectBusy: projectId => isProjectBusy(projectId, projectStore, activeTasks),
     bridgeAdapter,
   });
-  const migrationService = options.migrationService || new MigrationService({ layout, legacyDataDir: dataPath, logger });
   const moduleBridge = options.moduleBridge || new ModuleBridge({ registryStore, projectStore, settingsStore, logger, dataDir: dataPath });
   return {
     analysisOwner: options.analysisOwner || 'legacy', ownership: { owner: options.analysisOwner || 'legacy', ready: false },
     rootDir, dataPath, layout, settingsStore, registryStore, projectStore, logger, logRepository,
-    activeTasks, bridgeAdapter, bridgeConsumerService, conversationStore, conversationQuery, indexAdapter, indexService, promotionService, reconciler, lifecycleService, requirementRecorder, knowledgeRuntime, migrationService, moduleBridge,
+    activeTasks, bridgeAdapter, bridgeConsumerService, conversationStore, conversationQuery, indexAdapter, indexService, promotionService, reconciler, lifecycleService, requirementRecorder, knowledgeRuntime, moduleBridge,
   };
 }
 
@@ -648,22 +648,11 @@ async function reconcileLegacyHookMigration(runtime, projectId, config, state) {
 }
 
 async function initializeRuntime(runtime) {
-  // Legacy v4.1.x package-root data is intentionally NOT relocated: this is a
-  // fresh knowledge-base system and old runtime data is not migrated. The
-  // relocation previously aborted startup on conflict, bricking fresh
-  // machines whose npm package dir carried stale v4.1.x-era files.
-  await runtime.logger.info('server.startup_started', 'Server startup began.', { phase: 'migration' });
-  const migration = await runtime.migrationService.migrateIfNeeded();
-  if (!migration.ok || migration.requiresManualRecovery) {
-    throw new DomainError('MIGRATION_FAILED', 'Runtime data migration did not complete safely.', {
-      status: 500,
-      details: { reason: migration.reason || (migration.error && migration.error.code) || '' },
-    });
-  }
+  await runtime.logger.info('server.startup_started', 'Server startup began with fresh product data.', { phase: 'initialization' });
+  const migration = { ok: true, migrated: false, reason: 'fresh-data-only' };
   dataDir.ensureDataDir(runtime.dataPath);
   await runtime.settingsStore.initialize();
   await runtime.registryStore.initialize();
-  if (runtime.analysisOwner !== 'legacy') await prepareEngineCutover(runtime);
   const recoveredPromotions = runtime.analysisOwner === 'legacy' ? await runtime.promotionService.recoverAll() : [];
   // Promotion recovery runs first because it can legitimately finish and clear
   // a claim. Any claim left after that belonged to the previous process. Make
@@ -904,7 +893,7 @@ function createRequestHandler(runtime, options = {}) {
       const moduleUi = pathname.match(/^\/modules\/(terminal|vectorhub|eventbridge|engine)\/(.*)$/);
       if (moduleUi && method === 'GET') return runtime.moduleBridge.proxyModuleUi(req, res, moduleUi[1], moduleUi[2], url.search);
       if (pathname.startsWith('/api/engine/') || pathname === '/api/engine') {
-        if (['/api/engine/runtime-config', '/api/engine/scopes', '/api/engine/control', '/api/engine/migrate'].includes(pathname)) throw new DomainError('FORBIDDEN', 'Runtime configuration is not exposed to browsers.', { status: 403 });
+        if (['/api/engine/runtime-config', '/api/engine/runtime-auth', '/api/engine/scopes', '/api/engine/control', '/api/engine/migrate'].includes(pathname)) throw new DomainError('FORBIDDEN', 'Runtime configuration is not exposed to browsers.', { status: 403 });
         return runtime.moduleBridge.proxyEngine(req, res, pathname, url.search);
       }
 
@@ -926,7 +915,7 @@ function createRequestHandler(runtime, options = {}) {
       }
       if (method === 'POST' && pathname === '/api/modules/configure') {
         await readJsonBody(req);
-        await finishEngineCutover(runtime);
+        await connectEngine(runtime);
         return send(res, 200, { ok: true, configuration: await runtime.moduleBridge.syncEngineConfiguration() });
       }
       if (method === 'GET' && pathname === '/api/brain') {
@@ -1506,10 +1495,10 @@ async function startServer(options = {}) {
     if (runtime.analysisOwner === 'legacy') runtime.indexService.retryDirtyProjects().catch(error => runtime.logger.error('index.retry_failed', 'Index retry failed.', { error }));
   }, Number(process.env.KB_MAINTENANCE_INTERVAL_MS || 60 * 60 * 1000));
   maintenanceTimer.unref?.();
-  const configurationTimer = setInterval(() => { finishEngineCutover(runtime).then(() => runtime.moduleBridge.syncEngineConfiguration()).catch(() => {}); }, 30000);
+  const configurationTimer = setInterval(() => { connectEngine(runtime).catch(() => {}); }, 30000);
   configurationTimer.unref?.();
   runtime.moduleBridge.syncEngineConfiguration().catch(() => {});
-  finishEngineCutover(runtime).catch(() => {});
+  connectEngine(runtime).catch(() => {});
 
   // T3.5 进程编排：拉起包内自带的模块服务并守护（默认开启，KB_MODULES_AUTOSTART=0 关闭）
   try {

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/docs/README.zh-CN.md

@@ -5,6 +5,10 @@
 
 ## 安装与运行
 
+v5 不再兼容或迁移旧知识库数据。停止旧版后重新设置模型、知识根目录并导入
+项目；默认新数据目录为 `~/.project-knowledge-v5`。旧文件保留但不读取。
+详见 [从头开始](fresh-v5-start.md)。
+
 新机器完整安装只需三条命令：
 
 ```bash
@@ -23,8 +27,8 @@ project-knowledge
      Git 工作区里的 Agent 对话捕捉进已导入项目的「开发对话」。
    同时注册 host 级 `project-knowledge` Bridge consumer。全程无需打开任何
    客户端 UI;第三方 hooks 与配置完整保留;Codex notify 冲突只上报不覆盖。
-3. `project-knowledge` 启动本地服务。旧版本导入的项目会在第一次 drain 时
-   自动升级(补写 canonical workspace 身份 + 建立对话 baseline),无需手工迁移。
+3. `project-knowledge` 启动全新的 v5 本地服务。重新配置模型、知识根目录并导入
+   项目，不迁移旧登记、会话、知识、索引或未完成任务。
 
 注意事项:
 
@@ -99,12 +103,12 @@ project-knowledge-kb history --project <projectId> --json
 
 ## 存储合同
 
-内部数据默认在 `~/.project-knowledge/`，可用 `KB_DATA_DIR` 修改。用户必须先设置
+内部数据默认在 `~/.project-knowledge-v5/`，可用 `KB_DATA_DIR` 修改。用户必须先设置
 global knowledge root，再导入项目；它只影响未来导入。每个项目导入时固化绝对
 knowledgePath，修改 global root 不会移动已有项目。
 
 ```text
-~/.project-knowledge/
+~/.project-knowledge-v5/
 ├── settings.json
 ├── projects.json                         # 仅 ID、顺序、最小显示快照
 ├── projects/<projectId>/