@sanqianx/project-knowledge 4.8.0 → 5.0.0

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/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

@@ -163,6 +163,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 };
         }
@@ -354,7 +356,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);
@@ -419,7 +429,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/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');
@@ -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/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>/

package/docs/fresh-v5-start.md

@@ -0,0 +1,28 @@
+# v5 从头开始
+
+本版按用户确认不再迁移以前的知识库数据。旧文件留在原位置，但新版不会读取它们；没有对用户代码仓库或旧知识目录执行删除。
+
+## 更新
+
+```bash
+project-knowledge stop
+npm install -g @sanqianx/project-knowledge@latest --registry=https://registry.npmjs.org/
+project-knowledge-integrations update
+project-knowledge
+```
+
+需要 Node ≥22 和 Git。默认使用 `~/.project-knowledge-v5`，四模块的托管数据也在此目录内。若环境变量 `KB_DATA_DIR` 仍指向旧目录，请取消该设置或改为新的空目录。不要把旧 `projects.json`、设置或引擎状态复制进新目录。
+
+在“系统状态”重新配置模型与后台默认模型、embedding 和知识根目录，然后在“领域与项目”导入代码目录及新的空知识目录。原代码目录无需移动。若残留旧知识库托管 Hook，导入预检会要求明确确认替换；不会覆盖第三方 Hook。导入建立 HEAD 基线，不分析已有历史。
+
+如果模块是自己独立启动的旧进程，请在它原来的终端中停止后重启新版外壳。外壳不会擅自杀死其他服务；版本或运行期鉴权不一致时显示具体连接阶段，不接管旧服务数据。
+
+## 解绑与恢复
+
+“解绑并保留数据”从项目列表移除登记、取消未开始任务并卸下本项目托管 Hook，保留代码、知识、会话及证据。实际分析或索引写入尚未结束时仍禁止解绑，防止丢失写入状态。队列本身不再被当成正在运行。
+
+删除的是旧版本兼容路径，不是新版的故障恢复能力：v5 自身的重启恢复、提交去重、并发限制、失败重试和索引修复仍有效。`upgrade-recovery` 不再存在。
+
+## 回归范围
+
+旧格式迁移专用测试随旧实现删除，替换为旧目录拒绝且原字节不变、空状态启动、连接失败诊断与恢复、旧托管 Hook 的显式替换和回滚测试。真实提交链路继续由引擎 Git/Hook/journal/晋升/索引回归和五服务网页回归覆盖。模型替身和真实模型的结果分开记录；旧版本真实调用记录不计为本版通过。

package/module-runtime-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "project-knowledge/module-content/v1",
   "productFiles": {
-    "ui/index.html": "110e9ee2797e38b5fc955d033cbdeba7bd30cdb3f5fe023db36e42a0cf0a9f01",
-    "ui/product.js": "883bd1ba63e793c7c61e35958a45489584de732d8387169135307bf8a34aa293",
+    "ui/index.html": "fd79551591729f6874c95089e479d46f208ab3b45cf45ba21eff1f6967757f7d",
+    "ui/product.js": "d5fca94df54075d598f271e01ea41ac9cce3a9847ea4f246e4f20c47daed43ed",
     "ui/product.css": "1e68f087cec85a69f4497492d31fd1dd8712cf5176b0c721ce765de36ce606e1"
   },
   "modules": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/project-knowledge",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
   "main": "_site/server.js",
   "scripts": {
@@ -49,6 +49,7 @@
     "docs/project-registry-schema.md",
     "docs/team-knowledge-mode-a-plan.md",
     "docs/testing-strategy.md",
+    "docs/fresh-v5-start.md",
     "README.md",
     "NOTICE",
     "CHANGELOG.md"

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "project-knowledge",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

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

@@ -1,6 +1,6 @@
 {
   "name": "project-knowledge",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "Read durable project decisions and implementation history from Project Knowledge.",
   "author": {
     "name": "SanQianX",

package/plugins/project-knowledge/.mcp.json

@@ -6,7 +6,7 @@
       "args": [
         "-y",
         "--package",
-        "@sanqianx/project-knowledge@4.8.0",
+        "@sanqianx/project-knowledge@5.0.0",
         "project-knowledge-mcp"
       ]
     }

package/ui/index.html

@@ -54,9 +54,10 @@
   <p id="embeddingFeedback" class="muted" role="status"></p>
   <div class="dialog-actions"><button type="button" id="disableEmbedding">停用向量模型</button><button type="button" data-close="embeddingDialog">取消</button><button type="submit" class="primary">保存配置</button></div>
 </form></dialog>
-<dialog id="importDialog"><form id="importForm"><div class="dialog-heading"><h2>导入项目</h2><button type="button" data-close="importDialog" aria-label="关闭">×</button></div><p class="muted">绑定代码与知识目录。只建立跟踪基线，不分析全部历史。</p><label>代码目录<div class="input-with-action"><input name="localPath" id="importCode" required placeholder="D:\SanQian.Xu\my-project"><button type="button" id="pickCode">选择</button></div></label><label>项目名称<input name="displayName" id="importName" required maxlength="200"></label><label>知识目录<div class="input-with-action"><input name="knowledgePath" id="importKnowledge" required placeholder="D:\SanQian.Xu\knowledge\my-project"><button type="button" id="pickKnowledge">选择</button></div></label><label>所属领域<select name="domainId" id="importDomain"></select></label><label id="gitInitChoice" class="checkbox" hidden><input type="checkbox" name="confirmGitInit">这个目录不是 Git 仓库，我确认初始化 Git。</label><div id="preflightStatus" class="feedback" role="status">填写目录后检查导入条件。</div><button type="button" id="setupImportRoot" hidden>设置知识根目录</button><div class="dialog-actions"><button type="button" data-close="importDialog">取消</button><button type="submit" class="primary" id="confirmImport" disabled>导入项目</button></div></form></dialog>
+<dialog id="importDialog"><form id="importForm"><div class="dialog-heading"><h2>导入项目</h2><button type="button" data-close="importDialog" aria-label="关闭">×</button></div><p class="muted">绑定代码与新的空知识目录。只建立跟踪基线，不读取旧知识、不分析全部历史。</p><label>代码目录<div class="input-with-action"><input name="localPath" id="importCode" required placeholder="D:\SanQian.Xu\my-project"><button type="button" id="pickCode">选择</button></div></label><label>项目名称<input name="displayName" id="importName" required maxlength="200"></label><label>知识目录<div class="input-with-action"><input name="knowledgePath" id="importKnowledge" required placeholder="D:\SanQian.Xu\knowledge\my-project"><button type="button" id="pickKnowledge">选择</button></div></label><label>所属领域<select name="domainId" id="importDomain"></select></label><label id="gitInitChoice" class="checkbox" hidden><input type="checkbox" name="confirmGitInit">这个目录不是 Git 仓库，我确认初始化 Git。</label><label id="replaceHookChoice" class="checkbox" hidden><input type="checkbox" name="confirmReplaceHook">目录留有旧知识库的托管 Hook，我确认替换为新项目接线。不会覆盖第三方 Hook。</label><div id="preflightStatus" class="feedback" role="status">填写目录后检查导入条件。</div><button type="button" id="setupImportRoot" hidden>设置知识根目录</button><div class="dialog-actions"><button type="button" data-close="importDialog">取消</button><button type="submit" class="primary" id="confirmImport" disabled>导入项目</button></div></form></dialog>
 <dialog id="domainDialog"><form id="domainForm"><div class="dialog-heading"><h2>创建领域</h2><button type="button" data-close="domainDialog" aria-label="关闭">×</button></div><label>领域名称<input name="name" required maxlength="100" placeholder="例如：开发工具"></label><p class="muted">领域用于共享相关项目的知识，不是新的代码项目。</p><div class="dialog-actions"><button type="button" data-close="domainDialog">取消</button><button class="primary" type="submit">创建领域</button></div></form></dialog>
 <dialog id="memoryDialog"><form id="memoryForm"><div class="dialog-heading"><h2>编辑记忆</h2><button type="button" data-close="memoryDialog" aria-label="关闭">×</button></div><label>内容<textarea id="memoryText" maxlength="2000" required rows="5"></textarea></label><p id="memoryEvidence" class="muted"></p><div class="dialog-actions"><button type="button" data-close="memoryDialog">取消</button><button type="submit" class="primary">保存修改</button></div></form></dialog>
+<dialog id="unbindDialog"><form id="unbindForm"><div class="dialog-heading"><h2>解绑项目</h2><button type="button" data-close="unbindDialog" aria-label="关闭">×</button></div><p id="unbindProjectName"></p><p class="muted">项目将从列表移除，取消尚未开始的维护任务。代码、知识文件、提交证据和会话历史仍保留。正在执行的知识写入结束前不会解绑。</p><p id="unbindFeedback" class="feedback" role="status"></p><div class="dialog-actions"><button type="button" data-close="unbindDialog">取消</button><button class="primary" type="submit" id="confirmUnbind">解绑并保留数据</button></div></form></dialog>
 <dialog id="referenceDialog" class="reference-dialog"><div class="dialog-heading"><h2 id="referenceTitle">知识引用</h2><div class="actions"><button id="copyReference">复制引用</button><button data-close="referenceDialog" aria-label="关闭">×</button></div></div><p id="referenceMeta" class="muted"></p><pre id="referenceContent"></pre></dialog>
 <dialog id="engineDialog" class="engine-dialog"><div class="dialog-heading"><h2>知识引擎诊断</h2><button data-close="engineDialog" aria-label="关闭">×</button></div><iframe id="engineFrame" title="知识引擎诊断" referrerpolicy="same-origin"></iframe></dialog>
 <div id="toast" class="toast" role="status" aria-live="polite" hidden></div>

package/ui/product.js

@@ -16,9 +16,9 @@
   const domainName = id => state.brain.domains.find(d => d.id === id)?.name || '未分组';
   const projectName = id => state.projects.find(p => p.projectId === id)?.name || id;
   const time = value => value ? new Date(value).toLocaleString('zh-CN', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }) : '—';
-  const label = run => ({ queued: '排队', running: '维护中', succeeded: '已更新 · 可检索', 'index-pending': '知识已更新 · 索引待修复', failed: '维护失败' })[run.state] || run.state;
+  const label = run => ({ queued: '排队', running: '维护中', succeeded: '已更新 · 可检索', 'index-pending': '知识已更新 · 索引待修复', failed: '维护失败', cancelled: '已取消' })[run.state] || run.state;
   const badge = (text, status = '') => `<span class="status ${esc(status)}">${esc(text)}</span>`;
-  let toastTimer, refreshTimer, preflightTimer, editingMemoryId, logStream, logEpoch = 0, referenceEpoch = 0, snapshotEpoch = 0, resumeImport = false;
+  let toastTimer, refreshTimer, preflightTimer, editingMemoryId, logStream, logEpoch = 0, referenceEpoch = 0, snapshotEpoch = 0, registryEpoch = 0, registryPromise = null, resumeImport = false, unbindProjectId = '', unbinding = false;
   async function api(url, options = {}) {
     const { allowNotReady, ...init } = options;
     if (init.body && typeof init.body !== 'string') init.body = JSON.stringify(init.body);
@@ -149,23 +149,29 @@
     stream.addEventListener('progress', () => { if (state.stream === stream) scheduleRefresh(); });
     stream.onerror = () => { if (state.stream === stream) $('activityConnection').textContent = '连接中断，正在恢复快照'; };
   }
-  async function refreshRegistry() {
-    if (!navigator.onLine || state.refreshing) return;
-    state.refreshing = true;
+  function refreshRegistry(force = false) {
+    if (!navigator.onLine) return Promise.resolve();
+    if (registryPromise && !force) return registryPromise;
+    const epoch = ++registryEpoch;
+    const job = (async () => {
     try {
       const [brain, projects, health] = await Promise.all([api('/api/brain'), api('/api/projects/aggregated'), api('/api/modules/health')]);
+      if (epoch !== registryEpoch) return;
       state.brain = brain.brain; state.root = brain.knowledgeRoot; state.projects = projects.projects; state.health = health.modules; state.ownership = health.ownership;
       if (!activeProject()) { state.projectId = state.projects[0]?.projectId || ''; state.epoch++; Object.keys(frames).forEach(frameContext); }
       renderProjectOptions(); renderSystem(); connectProgress(); await refreshSnapshot(); setView(state.view);
     } catch (error) { toast(error.message); }
-    finally { state.refreshing = false; connectProgress(); }
+    finally { if (epoch === registryEpoch) { registryPromise = null; connectProgress(); } }
+    })();
+    registryPromise = job;
+    return job;
   }
   function renderSystem() {
     const down = Object.keys(modules).filter(key => !state.health[key]?.up);
     const pending = state.ownership?.owner === 'engine' && !state.ownership.ready;
     $('systemDot').className = `dot ${down.length || pending ? 'issue' : 'up'}`;
-    $('systemTitle').textContent = pending ? '知识引擎接管待恢复' : down.length ? '部分服务需要处理' : '系统连接正常';
-    $('systemDetail').textContent = pending ? state.ownership.message || '迁移未完成，原知识与提交证据保留。' : down.length ? down.map(k => modules[k]).join('、') : '本机知识服务已连接';
+    $('systemTitle').textContent = pending ? '知识引擎连接待恢复' : down.length ? '部分服务需要处理' : '系统连接正常';
+    $('systemDetail').textContent = pending ? `${state.ownership.message || '服务恢复后自动重试。'}${state.ownership.error ? ` · ${state.ownership.error.step} (${state.ownership.error.code})` : ''}` : down.length ? down.map(k => modules[k]).join('、') : '本机知识服务已连接';
     $('moduleHealth').innerHTML = Object.entries(modules).map(([key, name]) => `<div class="row"><div><b>${esc(name)}</b><small>${esc(state.health[key]?.url || '')}</small></div>${badge(state.health[key]?.up ? '在线' : '离线', state.health[key]?.up ? 'up' : 'issue')}</div>`).join('');
     if (!navigator.onLine) {
       $('systemDot').className = 'dot issue'; $('systemTitle').textContent = '网页连接中断';
@@ -267,9 +273,9 @@
     $('importForm').reset(); state.importId = `project-${crypto.randomUUID()}`; state.preflight = null; state.preflightEpoch++;
     $('importDomain').innerHTML = '<option value="">未分组</option>' + state.brain.domains.map(d => `<option value="${esc(d.id)}">${esc(d.name)}</option>`).join('');
     $('importDomain').value = activeProject()?.domainId || '';
-    $('gitInitChoice').hidden = true; $('confirmImport').disabled = true; $('preflightStatus').textContent = '填写目录后检查导入条件。'; $('importDialog').showModal();
+    $('gitInitChoice').hidden = true; $('replaceHookChoice').hidden = true; $('confirmImport').disabled = true; $('preflightStatus').textContent = '填写目录后检查导入条件。'; $('importDialog').showModal();
   }
-  function importInput() { return { projectId: state.importId, brainId: state.brain.id, domainId: $('importDomain').value || null, localPath: $('importCode').value.trim(), knowledgePath: $('importKnowledge').value.trim(), displayName: $('importName').value.trim(), knowledgeLanguage: 'zh-CN', confirmGitInit: $('importForm').elements.confirmGitInit.checked }; }
+  function importInput() { return { projectId: state.importId, brainId: state.brain.id, domainId: $('importDomain').value || null, localPath: $('importCode').value.trim(), knowledgePath: $('importKnowledge').value.trim(), displayName: $('importName').value.trim(), knowledgeLanguage: 'zh-CN', confirmGitInit: $('importForm').elements.confirmGitInit.checked, replaceManagedHookProjectId: $('importForm').elements.confirmReplaceHook.checked ? state.preflight?.checks.hook?.replacementProjectId : undefined }; }
   const problemLabels = { KNOWLEDGE_ROOT_MISSING: '请在系统状态中设置知识根目录。', AI_PROFILE_REQUIRED: '请配置可用模型；后台默认模型在系统状态中设置。', DUPLICATE_PROJECT: '此项目已导入，请打开已有项目。', HOOK_CONFLICT: '存在第三方 Hook，不会覆盖。请先检查冲突。', PATH_MISSING: '代码目录不存在。', PATH_REQUIRED: '请选择代码目录。' };
   async function checkImport() {
     const epoch = ++state.preflightEpoch; $('confirmImport').disabled = true;
@@ -279,12 +285,12 @@
     try {
       const result = await api('/api/projects/preflight-import', { method: 'POST', body: importInput(), allowNotReady: true });
       if (epoch !== state.preflightEpoch || !$('importDialog').open) return;
-      state.preflight = result; $('gitInitChoice').hidden = !result.plannedGitInit;
+      state.preflight = result; $('gitInitChoice').hidden = !result.plannedGitInit; $('replaceHookChoice').hidden = !result.checks.hook?.replacementProjectId;
       const messages = result.problems.map(p => problemLabels[p.code] || p.message);
       $('setupImportRoot').hidden = !result.problems.some(p => p.code === 'KNOWLEDGE_ROOT_MISSING');
       $('preflightStatus').textContent = result.ready ? result.plannedGitInit ? '目录检查通过。请确认初始化 Git；不分析历史。' : '检查通过。只建立当前提交的跟踪基线，不分析历史。' : [...new Set(messages)].join('\n');
       $('preflightStatus').classList.toggle('issue', !result.ready);
-      $('confirmImport').disabled = !result.ready || result.plannedGitInit && !$('importForm').elements.confirmGitInit.checked || !$('importKnowledge').value.trim();
+      $('confirmImport').disabled = !result.ready || result.plannedGitInit && !$('importForm').elements.confirmGitInit.checked || result.checks.hook?.replacementProjectId && !$('importForm').elements.confirmReplaceHook.checked || !$('importKnowledge').value.trim();
     } catch (error) { if (epoch === state.preflightEpoch) $('preflightStatus').textContent = error.message; }
   }
   document.addEventListener('click', e => {
@@ -292,7 +298,7 @@
     const execute = async () => {
       if (button.dataset.view) setView(button.dataset.view);
       if (button.dataset.go) { if (button.dataset.go === 'memory') state.memoryTab = 'candidate'; setView(button.dataset.go); }
-      if (button.dataset.close) $(button.dataset.close).close();
+      if (button.dataset.close && !(button.dataset.close === 'unbindDialog' && unbinding)) $(button.dataset.close).close();
       if (button.dataset.selectProject) selectProject(button.dataset.selectProject);
       if (button.dataset.scope) { state.scope = button.dataset.scope; all('[data-scope]').forEach(b => b.classList.toggle('active', b.dataset.scope === state.scope)); post('vectorHub', { type: 'kb:scope', scope: state.scope }); }
       if (button.dataset.memoryTab) { state.memoryTab = button.dataset.memoryTab; renderMemories(); }
@@ -300,7 +306,7 @@
       if (button.dataset.action === 'import') openImport();
       if (button.dataset.action === 'repair') await repair();
       if (button.dataset.action === 'system') await openSystem();
-      if (button.dataset.action === 'unbind') { const p = activeProject(); if (p && confirm(`解绑 ${p.name}？代码、知识文件和会话历史将保留。`)) { await api(`/api/projects/${encodeURIComponent(p.projectId)}`, { method: 'DELETE', body: { deleteKnowledge: false } }); toast('已解绑，数据仍保留。'); await refreshRegistry(); } }
+      if (button.dataset.action === 'unbind') { const p = activeProject(); if (p && !unbinding) { unbindProjectId = p.projectId; $('unbindProjectName').textContent = `解绑「${p.name}」？`; $('unbindFeedback').textContent = ''; $('unbindDialog').showModal(); } }
       if (button.dataset.retryRun) { await api(`/api/engine/runs/${encodeURIComponent(button.dataset.retryRun)}/retry`, { method: 'POST', body: {} }); await refreshSnapshot(); }
       if (button.dataset.contextIndex !== undefined) await openReference(state.contexts.get(state.projectId).references[Number(button.dataset.contextIndex)]);
       if (button.dataset.memoryAction) {
@@ -355,12 +361,32 @@
   on('createDomain', 'click', () => { $('domainForm').reset(); $('domainDialog').showModal(); });
   on('domainForm', 'submit', async e => { e.preventDefault(); await api('/api/domains', { method: 'POST', body: Object.fromEntries(new FormData(e.target)) }); $('domainDialog').close(); await refreshRegistry(); });
   on('memoryForm', 'submit', async e => { e.preventDefault(); await api(`/api/engine/memories/${encodeURIComponent(editingMemoryId)}`, { method: 'PATCH', body: { text: $('memoryText').value } }); $('memoryDialog').close(); await refreshSnapshot(); });
+  on('unbindForm', 'submit', async e => {
+    e.preventDefault(); if (!unbindProjectId || unbinding) return;
+    const projectId = unbindProjectId;
+    unbinding = true; $('confirmUnbind').disabled = true; $('confirmUnbind').textContent = '正在解绑…';
+    $('unbindFeedback').textContent = '正在停止项目接线并移除登记，磁盘文件不会删除。';
+    try {
+      await api(`/api/projects/${encodeURIComponent(projectId)}`, { method: 'DELETE', body: { deleteKnowledge: false } });
+      state.contexts.delete(projectId);
+      state.projects = state.projects.filter(project => project.projectId !== projectId);
+      if (state.projectId === projectId) { state.projectId = state.projects[0]?.projectId || ''; state.epoch++; }
+      renderProjectOptions(); render(); Object.keys(frames).forEach(frameContext);
+      $('unbindDialog').close(); unbindProjectId = '';
+      // A late read started before DELETE cannot restore the removed project.
+      await refreshRegistry(true); localStorage.setItem('kb.project', state.projectId);
+      Object.keys(frames).forEach(frameContext);
+      toast('项目已从列表移除，代码、知识和会话仍保留。');
+    } catch (error) { $('unbindFeedback').textContent = error.message; }
+    finally { unbinding = false; $('confirmUnbind').disabled = false; $('confirmUnbind').textContent = '解绑并保留数据'; }
+  });
+  on('unbindDialog', 'cancel', e => { if (unbinding) e.preventDefault(); });
   on('importForm', 'input', e => {
     if (e.target.id === 'importCode') { const name = e.target.value.trim().split(/[\\/]/).filter(Boolean).pop() || ''; $('importName').value = name; if (state.root) $('importKnowledge').value = `${state.root.replace(/[\\/]+$/, '')}/${name}-${state.importId.slice(-6)}`; }
     clearTimeout(preflightTimer); $('confirmImport').disabled = true; preflightTimer = setTimeout(checkImport, 250);
   });
   on('importForm', 'submit', async e => {
-    e.preventDefault(); if (!state.preflight?.ready || state.preflight.plannedGitInit && !$('importForm').elements.confirmGitInit.checked) return;
+    e.preventDefault(); if (!state.preflight?.ready || state.preflight.plannedGitInit && !$('importForm').elements.confirmGitInit.checked || state.preflight.checks.hook?.replacementProjectId && !$('importForm').elements.confirmReplaceHook.checked) return;
     $('confirmImport').disabled = true; $('confirmImport').textContent = '正在登记…';
     try { const result = await api('/api/projects/import', { method: 'POST', body: importInput() }); state.projectId = result.projectId; state.epoch++; $('importDialog').close(); await refreshRegistry(); Object.keys(frames).forEach(frameContext); setView('projects'); toast(Object.values(result.modules).every(m => m.ok) ? '项目已导入，四个模块已连接。' : '项目已导入，部分接线待恢复。'); }
     finally { $('confirmImport').textContent = '导入项目'; if ($('importDialog').open) checkImport(); }

package/vendor-manifest.json

@@ -3,19 +3,18 @@
   "modules": {
     "knowledge-engine": {
       "name": "@sanqianx/ai-coding-knowledge-engine",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "root": "_modules/knowledge-engine",
       "files": {
-        "README.md": "27e06c47c58e75e3081296cbdb2885df2d346fbd87bd7e415254db501d8ef35d",
-        "package.json": "f6949c331796b8351e55293d2be5a18b4ac7a203b9270c564eeefd692a006daf",
+        "README.md": "c12b9bc9aa49dce6eaad0e6f3fd611466ab1ef6b17d2bdfb69a6dab6a42ab5ed",
+        "package.json": "6740fa3dec72ebae49fa903a4b5f8ddc2adf52d11ba9f7c4bc1f36a603636578",
         "src/analysis-contract.js": "90354d1e9b4eff74fdd9d47e097cdb5d47944785c2be66811f64e5958c94d8e7",
         "src/analysis-worker.js": "a105cabe6e1573b2d986b1e7a5aaf615e2fb53524156fc8e4e2c0a71f2c97e55",
         "src/bin.js": "22208907431d0f3a971a669c7e5eb44b3b7af9bbb36fd7ba17c3b90c4288bd70",
         "src/bridge-client.js": "ae0dba21e4286694bcd9e064ca36564ec997969ae1eb1ce4f8a6665e447cbffe",
-        "src/coordinator.js": "4e82cce47c8c16294ddc77eb946eb1c3a2f8bfd8918e05742c80845ed8ecf10c",
+        "src/coordinator.js": "e85f1f604d2090bd466244d73cf8e1862e0cbe436e62d4a2f7193afd2fac7843",
         "src/headless-analyzer.js": "2473b28d4bf06088abbcafa21d491560a9ca0ab100024c912a36bc6f981d8576",
         "src/memories.js": "0a8667e6daba99fa5022393951a28e96cdadf98af85b6af9a6be96c7f4e896fc",
-        "src/migration.js": "b018871727f3277e4a24350fef1911fbb89e2158578339210d88efc2e309be32",
         "src/retrieval.js": "acbf76bb93fd13dac391c2e918891a56ace869db5583d2a5994641b6782496d6",
         "src/runtime/README.md": "9be676eca76a7857b34d7357194e6f0ee733c22e61d962d53984715dbec7f673",
         "src/runtime/atomic-file.js": "9846b4b69db5ded811acf19a1181ef93615d93efaa542b858e552a7f3124ad23",
@@ -35,10 +34,10 @@
         "src/runtime/layout.js": "c48fa1db62e5df1edefe13218e470c5ceea4ef2781293512c2c18e5c2ba0c7e9",
         "src/runtime/markdown-knowledge-indexer.js": "44a76a9adefad07e78f77b1106b10d6c1cc7873d76362df4c546892b21f3939c",
         "src/runtime/scanner.js": "d99fa8d74a6fbbaae75ca49f62127e14cf9e48b1404e4b4d597ef39df5441410",
-        "src/server.js": "e2d983eaa9f4ffc240caab467fad8e21c6124779ac3f27c9cec2c4f06827ef65",
-        "src/store.js": "b778d93b97cd6a1174fccd3a5de1f2b170934a262e11e4447e7fdc698ac386e0",
+        "src/server.js": "e7f0b07b7a8cf2623690b9d2d23492f2c95737dc974adfeea049610a4b5ded55",
+        "src/store.js": "71f0417c2c1e42b89429e3dee1adff7b2c09e86682cb3f4843ce6d9e5aafd7ec",
         "ui/app.css": "7ad370c269e60a7b5ec907d81a607b2d16bd07b2d7c22a81f102dab51eeb2889",
-        "ui/app.js": "5f4f6fc6faeb951938a821e846e948de8859d7c908e04f6f93bf73208493993e",
+        "ui/app.js": "91ee6d8c31712e6af46de2eecbd72bbc5236c06b7cd055800831e7d57f84a0be",
         "ui/index.html": "ce3565cfefd4838b11d37a91a906ef26ca5a1834844fe3f7c897b56851a3c418"
       }
     }