@sanqianx/project-knowledge 4.8.0 → 5.0.1

package/.claude-plugin/marketplace.json

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

package/CHANGELOG.md

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

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

package/_site/_test/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/product-diagnostics-ui-test.js

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

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

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

package/_site/_test/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 }),
     },