@sanqianx/project-knowledge 4.8.0 → 5.0.0

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [5.0.0] - 2026-10-10
+
+- Fresh-data-only web product. Default state moves to `~/.project-knowledge-v5`;
+  no previous knowledge, project registry, unfinished claims or model profiles
+  are imported. Explicitly selected old data directories are rejected unchanged.
+- Remove shell migration/cutover and engine `/api/migrate`. Engine 0.2.0 uses
+  schema version 3; validate its data generation and runtime authentication
+  before registering projects or enabling consumption. System status reports
+  safe connection stage/error codes instead of silently waiting for takeover.
+- Isolate Workbench, bridge journals and vector configuration under the new
+  product directory. No automatic embedding-credential migration.
+- Queued, unstarted tasks are cancelled on unbind; active knowledge/index write
+  leases still block removal. The visible confirmation dialog updates project
+  selection immediately and rejects stale registry responses without reloading.
+- Reimport can explicitly replace a leftover knowledge-managed Git Hook. Failed
+  imports restore the prior Hook; third-party hooks and existing knowledge files
+  are never overwritten. Import tracks HEAD without analyzing historical commits.
+
+
 ## [4.8.0] - 2026-10-10
 
 - Unified brain web product: six real pages for work, retrieval, memories,

package/README.md

@@ -32,9 +32,8 @@ project-knowledge
    It also registers the host-level `project-knowledge` Bridge consumer.
    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 the local backend. Projects imported with older
-   versions are upgraded automatically on the first drain (canonical workspace
-   identity + conversation baseline — no manual migration).
+3. `project-knowledge` starts a fresh v5 local backend. Import projects again;
+   older registries, knowledge, sessions and unfinished tasks are not migrated.
 
 Notes:
 
@@ -62,7 +61,7 @@ Requires Node.js 22 or newer and Git on `PATH`.
 
 ### Windows desktop
 
-Version 4.8.0 delivers the web product through npm. A new Windows installer
+Version 5.0.0 delivers the web product through npm. A new Windows installer
 and desktop auto-update are not part of this release.
 
 ## Runtime model
@@ -138,7 +137,13 @@ scopes are nested; unconfirmed memory candidates are not task preferences.
 
 ## Storage
 
-Default internal data directory: `~/.project-knowledge/`
+Version 5 is a fresh start, not a data upgrade. Stop the previous process,
+remove any old `KB_DATA_DIR` override, configure models and import projects into
+new empty knowledge directories. Old files remain untouched but are not read.
+See [fresh v5 setup](docs/fresh-v5-start.md). Queued tasks can be cancelled by
+unbinding; only an active knowledge/index writer blocks removal.
+
+Default internal data directory: `~/.project-knowledge-v5/`
 
 Override it with `KB_DATA_DIR`:
 
@@ -157,7 +162,7 @@ Settings, metadata, indexes, caches, runtime state, logs, and recovery assets
 remain in the internal data directory:
 
 ```text
-~/.project-knowledge/
+~/.project-knowledge-v5/
 ├── settings.json
 ├── projects.json                         # minimal project ID/order index
 ├── projects/<projectId>/

package/_modules/knowledge-engine/README.md

@@ -33,7 +33,9 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 
 打开 `http://127.0.0.1:5790` 即调试台。默认绑定 loopback：运行历史包含 commit 证据与知识内容，不出本机。
 
-首次启动为空，不创建演示项目。`--debug` 才开放手工运行、事件注入和模拟失败。独立运行默认只提供读取与诊断；设置 `KNOWLEDGE_ENGINE_CONSUME=1` 开始消费。外壳守护使用 `KB_ENGINE_MANAGED=1`，完成受保护迁移后再通过鉴权控制接口启用消费与执行。
+首次启动为空，不创建演示项目。`--debug` 才开放手工运行、事件注入和模拟失败。独立运行默认只提供读取与诊断；设置 `KNOWLEDGE_ENGINE_CONSUME=1` 开始消费。外壳守护使用 `KB_ENGINE_MANAGED=1`，确认服务身份、运行期鉴权、项目接线及配置后启用消费与执行；不再导入旧外壳任务。
+
+0.2.0 使用全新 schemaVersion 3，独立运行默认目录为 `./data-v3`。旧版状态目录明确拒绝读取，原文件保持不变；不备份后重置、不迁移、不创建 `upgrade-recovery`。同一新版数据目录内的崩溃恢复仍保留。
 
 本模块零新增 npm 依赖、CommonJS、Node ≥18；无头 Agent SDK 由宿主已安装的 Workbench/SDK 提供，缺失时明确失败，不退回假分析。完整产品的 Node 门槛为 ≥22。
 
@@ -41,9 +43,9 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| GET | `/api/health` | 版本 / uptime / 计数 / journal 游标 |
+| GET | `/api/health` | 版本 / dataSchemaVersion / uptime / 计数 / journal 游标 |
 | GET / POST | `/api/projects` | 项目列表 / 注册（按 projectId 幂等） |
-| DELETE | `/api/projects/:id` | 摘除登记 |
+| DELETE | `/api/projects/:id` | 摘除登记，取消未开始任务；实际运行或写入租约未释放时返回 409；保留代码、知识和证据 |
 | GET | `/api/runs?projectId=` | 分析运行列表（新→旧） |
 | POST | `/api/runs` | 仅调试模式手工运行；必填完整 `commitSha` |
 | GET | `/api/runs/:id` | 运行详情（含 staging manifest） |
@@ -57,7 +59,8 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 | GET / PATCH | `/api/memories`、`/api/memories/:id` | 候选和已确认记忆；编辑、确认、忽略持久化 |
 | POST | `/api/scopes` | 外壳投影智脑、领域共享目录；受运行期鉴权保护 |
 | POST | `/api/runtime-config` | 运行期模型配置，仅保留在内存；受鉴权保护 |
-| POST | `/api/migrate`、`/api/control` | 暂停状态迁移 / 迁移完成后启用；受鉴权保护 |
+| GET | `/api/runtime-auth` | 本机服务确认运行期鉴权；受鉴权保护，不对浏览器反代 |
+| POST | `/api/control` | 外壳完成接线后启用；受鉴权保护。旧 `/api/migrate` 已删除 |
 
 鉴权接口只接受无浏览器 Origin 的本机服务调用，使用 `KB_ENGINE_RUNTIME_TOKEN` 的 Bearer token。外壳不能把这些接口或解析后的凭据转发到浏览器。登记投影只接受白名单元数据，API key 不写入 EngineStore、任务记录或日志。
 
@@ -71,11 +74,11 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 - 晋升与索引分别记录。索引失败保留已晋升知识并显示待修复，不重新调用模型。
 - 项目、领域、智脑检索使用包含范围。向量只提供排序，显示内容必须来自当前真实文件；索引不可用时降级为文件检索。
 - 候选必须有已晋升文件中的引用依据，未确认候选不能进入任务。确认记录原子持久化后写共享记忆文件，派生索引异步更新，索引失败不会撤销有效记忆。
-- 旧脚手架演示状态先备份，不显示成真实项目。损坏的正式状态不覆盖、不清空。
+- 旧格式不读取、不自动迁移。损坏的正式状态不覆盖、不清空。
 
 ## 验证与尚未验收项
 
-`npm test` 覆盖真实 Git/Hook、真实分项目 journal、真实 vector-hub 文件索引、晋升、重复抑制、FIFO/并发、记忆、迁移及进程隔离。自动测试中的模型和 embedding 是可控替身。
+`npm test` 覆盖真实 Git/Hook、真实分项目 journal、真实 vector-hub 文件索引、晋升、重复抑制、FIFO/并发、记忆、旧格式拒绝、新版恢复及进程隔离。自动测试中的模型和 embedding 是可控替身。
 
 `npm run test:web` 使用兄弟源码仓库启动隔离的五服务网页环境，只有模型与 embedding 是替身。单一 1920×1080 视口验证双目录 UI 导入、真实 Hook 到自动刷新、原生消息流与中止、快速项目切换/草稿/历史、迟到检索及文件响应、领域检索、记忆落盘、四 iframe 身份与主题、唯一进度连接、诊断关闭和保留数据解绑；不会在用户代码仓库提交。该脚本是开发验收工具，不属于引擎生产运行依赖。
 

package/_modules/knowledge-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/ai-coding-knowledge-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Knowledge engine module for project-knowledge: commit-boundary triggered knowledge analysis/generation (trigger plane) and retrieval for development assistants (retrieval plane).",
   "license": "Apache-2.0",
   "main": "src/server.js",

package/_modules/knowledge-engine/src/coordinator.js

@@ -97,6 +97,14 @@ class EngineCoordinator extends EventEmitter {
     this.ready.then(() => this.pump());
     return run;
   }
+  async removeProject(projectId) {
+    await this.ready;
+    // An indexing job can still hold a write lease even after its state changes.
+    if (this.active.has(projectId)) throw Object.assign(new Error('此项目正在执行知识维护，请等待写入结束后再解绑。'), { status: 409, code: 'PROJECT_BUSY' });
+    const result = this.store.removeProject(projectId);
+    if (result.removed) this.emit('progress', this.store.addEvent({ type: 'project.unregister', projectId, summary: `已解绑项目，取消 ${result.cancelledRuns} 个未开始任务；知识与提交证据保留。` }));
+    return result;
+  }
   drain() {
     if (this.drainJob) return this.drainJob;
     if (this.closed) return Promise.resolve();
@@ -115,8 +123,8 @@ class EngineCoordinator extends EventEmitter {
         let through = cursor;
         for (const event of events) {
           if (this.closed) break;
-          const p = this.store.listProjects().find(p => (journal.journalId !== 'global' && p.journalId === journal.journalId)
-            || ((journal.journalId === 'global' || !p.journalId) && event.repoIdentity?.workspaceRoot && this.layout.pathsEqual(p.repoPath, event.repoIdentity.workspaceRoot)));
+          const p = this.store.listProjects().find(p => p.enabled !== false && ((journal.journalId !== 'global' && p.journalId === journal.journalId)
+            || ((journal.journalId === 'global' || !p.journalId) && event.repoIdentity?.workspaceRoot && this.layout.pathsEqual(p.repoPath, event.repoIdentity.workspaceRoot))));
           if (p) {
             if (event.schema === 'ai-coding-event/v1' && ['user_prompt', 'assistant_response'].includes(event.eventType)) await this.conversations.appendBridgeEvent(p.projectId, { ...event, journalId: journal.journalId });
             if (event.schema === 'git-commit-boundary/v1' && /^[a-f0-9]{7,64}$/i.test(event.commitSha || '')) {
@@ -124,7 +132,7 @@ class EngineCoordinator extends EventEmitter {
               const baseline = p.runtime.lastAnalyzedCommit || p.trackingStartCommit;
               const completed = this.reconciler.processingLedger.read(p.projectId, event.commitSha);
               const historical = baseline && (baseline === event.commitSha || (await execGit(p.repoPath, ['merge-base', '--is-ancestor', event.commitSha, baseline])).ok);
-              if (!completed && !historical) this.enqueue({ projectId: p.projectId, commitSha: event.commitSha, trigger: 'git-hook', journalId: journal.journalId, journalSequence: event.sequence });
+              if (!completed && !historical && this.store.getProject(p.projectId)?.enabled) this.enqueue({ projectId: p.projectId, commitSha: event.commitSha, trigger: 'git-hook', journalId: journal.journalId, journalSequence: event.sequence });
             }
           }
           through = event.sequence;

package/_modules/knowledge-engine/src/server.js

@@ -5,7 +5,6 @@ const fs = require('node:fs');
 const crypto = require('node:crypto');
 const { EngineStore } = require('./store');
 const { EngineCoordinator } = require('./coordinator');
-const { importLegacyState } = require('./migration');
 const AtomicFile = require('./runtime/atomic-file');
 
 const VERSION = require('../package.json').version;
@@ -13,7 +12,7 @@ const UI_DIR = path.resolve(__dirname, '..', 'ui');
 const STATIC_FILES = new Map([['/', ['index.html', 'text/html']], ['/index.html', ['index.html', 'text/html']], ['/app.js', ['app.js', 'text/javascript']], ['/app.css', ['app.css', 'text/css']]]);
 
 function createEngineServer(options = {}) {
-  const dataDir = options.dataDir || path.join(process.cwd(), 'data');
+  const dataDir = options.dataDir || path.join(process.cwd(), 'data-v3');
   const store = options.store || new EngineStore(dataDir, { deferLoad: true });
   let releaseLease;
   const coordinator = new EngineCoordinator(store, { ...options, initializeHook: async () => {
@@ -46,14 +45,13 @@ function createEngineServer(options = {}) {
     }
     if (pathname.startsWith('/api/')) {
       const body = await readBody(req);
-      if (pathname === '/api/migrate' && req.method === 'POST') {
-        if (!trusted(req)) throw httpError(403, 'RUNTIME_AUTH_REQUIRED', '仅允许受信任外壳迁移运行状态。');
-        await coordinator.ready;
-        send(res, 200, { ok: true, ...await importLegacyState(coordinator, body) }); return;
+      if (pathname === '/api/runtime-auth' && req.method === 'GET') {
+        if (!trusted(req)) throw httpError(403, 'RUNTIME_AUTH_REQUIRED', '仅允许受信任外壳检查连接。');
+        send(res, 200, { ok: true, dataSchemaVersion: store.state.schemaVersion }); return;
       }
       if (pathname === '/api/control' && req.method === 'POST') {
         if (!trusted(req)) throw httpError(403, 'RUNTIME_AUTH_REQUIRED', '仅允许受信任外壳切换运行所有权。');
-        if (body.enabled !== true) throw httpError(400, 'INVALID_ARGUMENT', '只支持完成迁移后的启用操作。');
+        if (body.enabled !== true) throw httpError(400, 'INVALID_ARGUMENT', '只支持外壳完成接线后的启用操作。');
         await coordinator.activate(); send(res, 200, { ok: true }); return;
       }
       if (pathname === '/api/runtime-config' && req.method === 'POST') {
@@ -102,7 +100,7 @@ function createEngineServer(options = {}) {
 }
 
 async function api(method, pathname, search, body, store, coordinator, ctx) {
-  if (method === 'GET' && pathname === '/api/health') return { name: 'knowledge-engine', version: VERSION, debug: ctx.debug, executionEnabled: coordinator.executionEnabled, uptimeSec: Math.floor((Date.now() - ctx.startedAt) / 1000), dataDir: ctx.dataDir, counts: { projects: store.state.projects.length, runs: store.state.runs.length, running: coordinator.active.size }, journal: { cursor: store.state.cursor, cursors: store.state.journalCursors, consumer: 'knowledge-engine', enabled: coordinator.consume, error: coordinator.journalError || null }, concurrency: coordinator.concurrency };
+  if (method === 'GET' && pathname === '/api/health') return { name: 'knowledge-engine', version: VERSION, dataSchemaVersion: store.state.schemaVersion, debug: ctx.debug, executionEnabled: coordinator.executionEnabled, uptimeSec: Math.floor((Date.now() - ctx.startedAt) / 1000), dataDir: ctx.dataDir, counts: { projects: store.state.projects.length, runs: store.state.runs.length, running: coordinator.active.size }, journal: { cursor: store.state.cursor, cursors: store.state.journalCursors, consumer: 'knowledge-engine', enabled: coordinator.consume, error: coordinator.journalError || null }, concurrency: coordinator.concurrency };
   if (method === 'GET' && pathname === '/api/projects') return { projects: store.listProjects() };
   if (method === 'GET' && pathname === '/api/memories') return { memories: coordinator.memories.list(Object.fromEntries(search)) };
   const memoryMatch = pathname.match(/^\/api\/memories\/([^/]+)$/);
@@ -118,8 +116,9 @@ async function api(method, pathname, search, body, store, coordinator, ctx) {
   }
   const projectMatch = pathname.match(/^\/api\/projects\/([^/]+)$/);
   if (method === 'DELETE' && projectMatch) {
-    if (!store.removeProject(decodeURIComponent(projectMatch[1]))) throw httpError(404, 'NOT_FOUND', '项目未登记。');
-    return { removed: true, keptData: true };
+    const result = await coordinator.removeProject(decodeURIComponent(projectMatch[1]));
+    if (!result.removed) throw httpError(404, 'NOT_FOUND', '项目未登记。');
+    return { ...result, keptData: true };
   }
   if (method === 'GET' && pathname === '/api/runs') return { runs: store.listRuns(search.get('projectId')) };
   const runMatch = pathname.match(/^\/api\/runs\/([^/]+)(\/retry)?$/);

package/_modules/knowledge-engine/src/store.js

@@ -14,21 +14,14 @@ class EngineStore {
   constructor(dataDir, options = {}) {
     this.dataDir = dataDir;
     this.file = path.join(dataDir, 'engine-state.json');
-    this.state = { schemaVersion: 2, projects: [], runs: [], events: [], cursor: 0, journalCursors: {}, memories: [], sharedScopes: [] };
+    this.state = { schemaVersion: 3, projects: [], runs: [], events: [], cursor: 0, journalCursors: {}, memories: [], sharedScopes: [] };
     if (!options.deferLoad) this.load();
   }
 
   load() {
     try {
       const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
-      if (raw && (raw.schemaVersion === undefined || raw.schemaVersion === 1)) {
-        const backup = path.join(this.dataDir, `legacy-debug-state-${crypto.randomUUID()}.json`);
-        require('./runtime/atomic-file').writeJsonAtomic(backup, raw);
-        this.state.legacyStateBackup = backup;
-        this.save();
-        return;
-      }
-      if (raw?.schemaVersion !== 2) throw new Error('Unsupported engine state');
+      if (raw?.schemaVersion !== 3) throw Object.assign(new Error('不再读取旧版引擎数据，请使用新的空数据目录重新导入项目。'), { code: 'SCHEMA_UNSUPPORTED' });
       if (!raw || !Array.isArray(raw.projects) || !Array.isArray(raw.runs) || !Array.isArray(raw.events) || !Number.isSafeInteger(raw.cursor) || raw.cursor < 0) throw new Error('Invalid engine state');
       if (raw.memories && !Array.isArray(raw.memories) || raw.sharedScopes && !Array.isArray(raw.sharedScopes) || raw.journalCursors && (typeof raw.journalCursors !== 'object' || Array.isArray(raw.journalCursors))) throw new Error('Invalid engine projections');
       const ids = new Set();
@@ -40,7 +33,7 @@ class EngineStore {
       const runIds = new Set();
       for (const run of raw.runs) {
         validateProjectId(run.projectId);
-        if (!/^run-[a-f0-9-]{36}$/.test(run.runId || '') || runIds.has(run.runId) || !/^[a-f0-9]{40}$/.test(run.commitSha || '') || !['queued', 'running', 'failed', 'succeeded', 'index-pending'].includes(run.state) || !Number.isSafeInteger(run.sequence) || run.sequence < 1) throw new Error('Invalid queued run');
+        if (!/^run-[a-f0-9-]{36}$/.test(run.runId || '') || runIds.has(run.runId) || !/^[a-f0-9]{40}$/.test(run.commitSha || '') || !['queued', 'running', 'failed', 'succeeded', 'index-pending', 'cancelled'].includes(run.state) || !Number.isSafeInteger(run.sequence) || run.sequence < 1) throw new Error('Invalid queued run');
         runIds.add(run.runId);
       }
       for (const [journalId, sequence] of Object.entries(raw.journalCursors || {})) if (!/^(global|sha256:[a-f0-9]{64})$/.test(journalId) || !Number.isSafeInteger(sequence) || sequence < 0) throw new Error('Invalid journal cursor');
@@ -48,6 +41,7 @@ class EngineStore {
       for (const memory of raw.memories || []) if (!memory || !['candidate', 'confirmed', 'ignored'].includes(memory.status) || typeof memory.text !== 'string' || !memory.evidence?.projectId || !/^[a-f0-9]{40}$/.test(memory.evidence.commitSha || '')) throw new Error('Invalid memory record');
       this.state = { ...this.state, ...raw };
     } catch (error) {
+      if (error.code === 'SCHEMA_UNSUPPORTED') throw error;
       if (error.code !== 'ENOENT') throw Object.assign(new Error('引擎状态损坏，已保留原文件；请从备份恢复。'), { code: 'DATA_CORRUPT', cause: error });
     }
   }
@@ -129,11 +123,14 @@ class EngineStore {
   }
 
   removeProject(projectId) {
-    if (this.state.runs.some(r => r.projectId === projectId && ['queued', 'running'].includes(r.state))) throw Object.assign(new Error('请等待当前维护运行结束后再解绑。'), { status: 409, code: 'PROJECT_BUSY' });
+    if (this.state.runs.some(r => r.projectId === projectId && r.state === 'running')) throw Object.assign(new Error('此项目正在执行知识维护，请等待写入结束后再解绑。'), { status: 409, code: 'PROJECT_BUSY' });
     const before = this.state.projects.length;
+    const now = new Date().toISOString();
+    const cancelled = this.state.runs.filter(r => r.projectId === projectId && r.state === 'queued');
+    for (const run of cancelled) Object.assign(run, { state: 'cancelled', phase: 'cancelled', finishedAt: now, cancellationReason: 'project-unbound' });
     this.state.projects = this.state.projects.filter(p => p.projectId !== projectId);
     this.save();
-    return this.state.projects.length < before;
+    return { removed: this.state.projects.length < before, cancelledRuns: cancelled.length };
   }
 
   listRuns(projectId) {

package/_modules/knowledge-engine/ui/app.js

@@ -50,7 +50,7 @@ function fmtTime(iso) {
 }
 function fmtDuration(ms) { return ms == null ? '–' : ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`; }
 function shortSha(sha) { return sha ? sha.slice(0, 7) : '–'; }
-function stateBadge(state) { return `<span class="badge ${escapeHtml(state)}">${escapeHtml(({ queued: '排队', running: '运行中', succeeded: '可检索', failed: '失败', 'index-pending': '索引待修复' })[state] || state)}</span>`; }
+function stateBadge(state) { return `<span class="badge ${escapeHtml(state)}">${escapeHtml(({ queued: '排队', running: '运行中', succeeded: '可检索', failed: '失败', 'index-pending': '索引待修复', cancelled: '已取消' })[state] || state)}</span>`; }
 function typeBadge(type) { return `<span class="badge type">${escapeHtml(type)}</span>`; }
 function scopedPath(path) { return scopedProjectId ? `${path}${path.includes('?') ? '&' : '?'}projectId=${encodeURIComponent(scopedProjectId)}` : path; }
 function successfulRun(runs) { return runs.find(run => run.promotedAt) || null; }

package/_site/_test/fresh-hook-reimport-test.js

@@ -0,0 +1,53 @@
+const assert = require('assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+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 hooks = require('../lib/hook-manager');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-fresh-hook-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'fresh') });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+  const triggerScriptPath = path.resolve(__dirname, '../scripts/hook-trigger.js');
+  await settingsStore.initialize({ knowledge: { rootPath: path.join(root, 'knowledge') } });
+  await registryStore.initialize();
+  const options = { layout, settingsStore, registryStore, projectStore, triggerScriptPath };
+  const lifecycle = new ProjectLifecycleService(options);
+  const repo = path.join(root, '中文 项目'); fs.mkdirSync(repo);
+  const git = args => execFileSync('git', args, { cwd: repo, windowsHide: true, encoding: 'utf8' }).trim();
+  git(['init', '-q']); git(['config', 'user.name', 'Fresh Test']); git(['config', 'user.email', 'fresh@example.invalid']);
+  fs.writeFileSync(path.join(repo, 'user-code.txt'), 'unchanged'); git(['add', '.']); git(['commit', '-qm', 'baseline']);
+  const old = hooks.installHook({ repoPath: repo, projectId: 'project-old', triggerScriptPath, dataDir: path.join(root, 'old') });
+  const oldBytes = fs.readFileSync(old.hookPath, 'utf8');
+  const input = { localPath: repo, projectId: 'project-new', storageName: 'new' };
+  const preflight = await lifecycle.preflightImport(input);
+  assert.equal(preflight.checks.hook.replacementProjectId, 'project-old');
+  for (const confirmation of [undefined, 'project-wrong']) {
+    await assert.rejects(lifecycle.importProject({ ...input, replaceManagedHookProjectId: confirmation }), { code: 'HOOK_CONFLICT' });
+    assert.equal(fs.readFileSync(old.hookPath, 'utf8'), oldBytes);
+    assert.equal(registryStore.listIds().length, 0);
+  }
+  const brokenRegistry = Object.create(registryStore);
+  brokenRegistry.add = async () => { throw new Error('registry write failed'); };
+  await assert.rejects(new ProjectLifecycleService({ ...options, registryStore: brokenRegistry }).importProject({ ...input, replaceManagedHookProjectId: 'project-old' }));
+  assert.equal(fs.readFileSync(old.hookPath, 'utf8'), oldBytes, 'failed import restores the old managed hook');
+  const result = await lifecycle.importProject({ ...input, replaceManagedHookProjectId: 'project-old' });
+  assert.equal(hooks.readHookStatus({ repoPath: repo }).projectId, 'project-new');
+  assert.equal(result.state.lastAnalyzedCommit, null);
+  assert.equal(result.state.trackingStartCommit, git(['rev-parse', 'HEAD']));
+  assert.deepEqual(fs.readdirSync(result.config.knowledgePath), []);
+  assert.equal(fs.readFileSync(path.join(repo, 'user-code.txt'), 'utf8'), 'unchanged');
+  await lifecycle.deleteProject('project-new');
+  const thirdParty = '#!/bin/sh\necho third-party\n'; fs.writeFileSync(old.hookPath, thirdParty);
+  await assert.rejects(lifecycle.importProject({ ...input, replaceManagedHookProjectId: 'project-old' }), { code: 'HOOK_CONFLICT' });
+  assert.equal(fs.readFileSync(old.hookPath, 'utf8'), thirdParty);
+  console.log('PASS explicit fresh Hook replacement, rollback, baseline, third-party protection');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/fresh-product-data-test.js

@@ -0,0 +1,42 @@
+const assert = require('assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { initializeProductData, DATA_SCHEMA } = require('../lib/product-data');
+const { resolveDataDirPath } = require('../lib/data-dir');
+const { connectEngine } = require('../lib/engine-connection');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-fresh-product-'));
+  assert.equal(resolveDataDirPath({ dataDir: '', homeDir: root }), path.join(root, '.project-knowledge-v5'));
+  const old = path.join(root, 'old'); fs.mkdirSync(old);
+  const bytes = JSON.stringify({ projects: ['old-project'], activeClaim: 'old-claim' });
+  fs.writeFileSync(path.join(old, 'projects.json'), bytes);
+  assert.throws(() => initializeProductData(old), { code: 'SCHEMA_UNSUPPORTED' });
+  assert.equal(fs.readFileSync(path.join(old, 'projects.json'), 'utf8'), bytes);
+  const fresh = path.join(root, 'fresh'); initializeProductData(fresh); initializeProductData(fresh);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(fresh, 'product-data.json'))).schema, DATA_SCHEMA);
+  const paths = [];
+  let activationStatus = 403;
+  const logs = [];
+  const runtime = {
+    analysisOwner: 'engine', registryStore: { listIds: () => [] }, logger: { warn: async (...args) => logs.push(args) },
+    moduleBridge: { engineUrl: 'http://engine.invalid', runtimeToken: 'private-local-token', syncEngineConfiguration: async () => {}, _fetch: async url => {
+      paths.push(url);
+      if (url.endsWith('/api/health')) return { ok: true, status: 200, json: async () => ({ name: 'knowledge-engine', version: '0.2.0', dataSchemaVersion: 3 }) };
+      if (url.endsWith('/api/runtime-auth')) return { ok: true, status: 200 };
+      return { ok: activationStatus === 200, status: activationStatus };
+    } },
+  };
+  await connectEngine(runtime);
+  assert.equal(runtime.ownership.ready, false);
+  assert.equal(runtime.ownership.error.code, 'RUNTIME_AUTH_REQUIRED');
+  assert.equal(runtime.ownership.error.step, 'engine-activation');
+  assert.ok(!JSON.stringify(logs).includes('private-local-token'));
+  assert.ok(paths.every(url => !url.includes('migrate')));
+  await connectEngine(runtime);
+  assert.equal(logs.length, 1, 'identical connection failures are not repeatedly logged');
+  activationStatus = 200; await connectEngine(runtime);
+  assert.deepEqual(runtime.ownership, { owner: 'engine', ready: true });
+  console.log('PASS fresh data isolation, legacy rejection, precise connection failure, recovery without migration');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/module-model-configuration-test.js

@@ -33,7 +33,8 @@ const { ModuleBridge } = require('../lib/module-bridge');
     assert.equal(status.model, true); assert.equal(status.embedding, true);
     assert.equal(appliedModel.mainModel, 'durable-default'); assert.equal(appliedVector.model, 'embedding-model');
     assert.ok(!JSON.stringify(status).includes('key'));
-    assert.ok(hits.indexOf('/api/claude-workbench/v1/internal/import-embedding') < hits.indexOf('/api/internal/retire-embedding'));
+    assert.ok(!hits.some(route => /import-embedding|retire-embedding/.test(route)), 'fresh product must not import old credentials');
+    assert.ok(!hits.includes('/api/internal/embedding-config'));
     profile = null; settings = null;
     const revoked = await bridge.syncEngineConfiguration();
     assert.equal(revoked.model, false); assert.equal(revoked.embedding, false);

package/_site/_test/tracking-start-test.js

@@ -51,6 +51,7 @@ function commit(target, name) {
     settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
     triggerScriptPath: path.join(temp, 'hook-trigger.js'),
     hookManager: {
+      readHookStatus: () => ({ kbManaged: false }),
       installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
       uninstallHook: () => ({ ok: true }),
     },

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/hook-manager.js

@@ -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 || '';