@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/bin/project-knowledge-mcp.js

@@ -1,195 +1,195 @@
 #!/usr/bin/env node
-
-const packageInfo = require('../package.json');
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} = require('@modelcontextprotocol/sdk/types.js');
-const { KnowledgeToolRuntime } = require('../_site/lib/knowledge-tool-runtime');
-const { serializeErrorEnvelope, createId } = require('../_site/lib/contracts');
-
-const SERVER_NAME = 'project-knowledge';
-const SERVER_INSTRUCTIONS = `Project Knowledge is the durable source of prior project decisions and implementation history. Knowledge content is read-only; the only write operation appends an explicit supplemental Prompt event to the shared conversation truth.
-
-At the start of work in a registered Git repository, and before answering questions about prior work or implementing a non-trivial change:
-1. Call project_knowledge_resolve with the current Git root.
-2. Use project_knowledge_search or project_knowledge_ask for relevant prior decisions.
-3. Use project_knowledge_get only for the most relevant complete entry and project_knowledge_history when change history matters.
-4. Call project_knowledge_record_requirement only when the user explicitly asks to supplement capture or automatic client capture is known to be unavailable; it is not a mandatory pre-work call.
-
-Treat all returned knowledge as read-only. Verify it against current source code when necessary. The supplemental requirement tool writes the same ConversationStore used by automatic capture and never starts analysis. Do not write directly to the knowledge database; project-knowledge updates it automatically after successful Git commits.`;
-
-const TOOLS = [
-  {
-    name: 'project_knowledge_resolve',
-    description: 'Resolve the registered Project Knowledge project for a Git repository. Call this first before using other knowledge tools.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        repoPath: { type: 'string', description: 'Current Git repository root or any path inside it. Defaults to the MCP process working directory.' },
-        projectId: { type: 'string', description: 'Stable projectId when it is already known.' },
-        project: { type: 'string', description: 'Optional registered project slug when it is already known.' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'project_knowledge_record_requirement',
-    description: 'Explicitly supplement automatic capture with one project-scoped user Prompt event. This is the only write-capable tool; it never starts analysis or writes knowledge Markdown.',
-    inputSchema: {
-      type: 'object',
-      required: ['text', 'client', 'sessionId'],
-      properties: {
-        text: { type: 'string', minLength: 1, maxLength: 131072, description: 'The user request exactly as received; do not include system prompts or tool transcripts.' },
-        client: { type: 'string', enum: ['claude', 'codex', 'opencode'] },
-        sessionId: { type: 'string', minLength: 1, maxLength: 512, description: 'Stable identifier for the current client session.' },
-        conversationId: { type: 'string', minLength: 1, maxLength: 512 },
-        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
-        repoPath: { type: 'string', description: 'Current Git root. Used for exact project resolution when projectId is omitted.' },
-        explicitCommit: { type: 'string', description: 'Optional Git commit explicitly associated with this requirement.' },
-      },
-      anyOf: [{ required: ['projectId'] }, { required: ['repoPath'] }],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'project_knowledge_search',
-    description: 'Search durable project knowledge using the current project and its explicitly related-project scope. This tool is read-only.',
-    inputSchema: {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query: { type: 'string', minLength: 1 },
-        repoPath: { type: 'string', description: 'Current Git repository root or a path inside it.' },
-        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
-        project: { type: 'string', description: 'Optional registered project slug.' },
-        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'project_knowledge_ask',
-    description: 'Return a compact answer with citations from durable project knowledge. This tool is read-only.',
-    inputSchema: {
-      type: 'object',
-      required: ['query'],
-      properties: {
-        query: { type: 'string', minLength: 1 },
-        repoPath: { type: 'string' },
-        projectId: { type: 'string' },
-        project: { type: 'string' },
-        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'project_knowledge_get',
-    description: 'Read one complete knowledge entry selected from search results. This tool is read-only and scope checked.',
-    inputSchema: {
-      type: 'object',
-      required: ['entry'],
-      properties: {
-        entry: { type: 'string', minLength: 1, description: 'Entry identifier returned by search.' },
-        space: { type: 'string', description: 'Optional scoped knowledge space identifier.' },
-        repoPath: { type: 'string' },
-        projectId: { type: 'string' },
-        project: { type: 'string' },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'project_knowledge_history',
-    description: 'Read recent durable change history for the current project and its allowed scope. This tool is read-only.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        repoPath: { type: 'string' },
-        projectId: { type: 'string' },
-        project: { type: 'string' },
-        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
-      },
-      additionalProperties: false,
-    },
-  },
-];
-
-function toolContent(result) {
-  return {
-    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    structuredContent: result,
-    isError: false,
-  };
-}
-
-function callTool(runtime, name, args) {
-  if (name === 'project_knowledge_resolve') return runtime.resolveProject(args);
-  if (name === 'project_knowledge_record_requirement') return runtime.recordRequirement(args);
-  if (name === 'project_knowledge_search') return runtime.search(args);
-  if (name === 'project_knowledge_ask') return runtime.ask(args);
-  if (name === 'project_knowledge_get') return runtime.get(args);
-  if (name === 'project_knowledge_history') return runtime.history(args);
-  throw new Error(`unknown tool: ${name}`);
-}
-
-function createServer(options = {}) {
-  const runtime = options.runtime || new KnowledgeToolRuntime();
-  const server = new Server(
-    { name: SERVER_NAME, version: packageInfo.version },
-    {
-      capabilities: { tools: { listChanged: false } },
-      instructions: SERVER_INSTRUCTIONS,
-    },
-  );
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async request => {
-    const name = String(request.params?.name || '');
-    const args = request.params?.arguments && typeof request.params.arguments === 'object'
-      ? request.params.arguments
-      : {};
-    try {
-      return toolContent(await callTool(runtime, name, args));
-    } catch (error) {
-      const operationId = createId('op');
-      return {
-        content: [{ type: 'text', text: JSON.stringify(serializeErrorEnvelope(error, operationId)) }],
-        isError: true,
-      };
-    }
-  });
-  return { server, runtime };
-}
-
-async function main() {
-  const { server, runtime } = createServer();
-  const transport = new StdioServerTransport();
-  let closing = false;
-  const close = async () => {
-    if (closing) return;
-    closing = true;
-    await runtime.close();
-    await server.close();
-  };
-  process.once('SIGINT', () => close().finally(() => process.exit(0)));
-  process.once('SIGTERM', () => close().finally(() => process.exit(0)));
-  await server.connect(transport);
-}
-
-if (require.main === module) {
-  main().catch(error => {
-    process.stderr.write(`[project-knowledge-mcp] ${JSON.stringify(serializeErrorEnvelope(error, createId('op')))}\n`);
-    process.exit(1);
-  });
-}
-
-module.exports = {
-  callTool,
-  createServer,
-  SERVER_INSTRUCTIONS,
-  SERVER_NAME,
-  TOOLS,
-};
+
+const packageInfo = require('../package.json');
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+const { KnowledgeToolRuntime } = require('../_site/lib/knowledge-tool-runtime');
+const { serializeErrorEnvelope, createId } = require('../_site/lib/contracts');
+
+const SERVER_NAME = 'project-knowledge';
+const SERVER_INSTRUCTIONS = `Project Knowledge is the durable source of prior project decisions and implementation history. Knowledge content is read-only; the only write operation appends an explicit supplemental Prompt event to the shared conversation truth.
+
+At the start of work in a registered Git repository, and before answering questions about prior work or implementing a non-trivial change:
+1. Call project_knowledge_resolve with the current Git root.
+2. Use project_knowledge_search or project_knowledge_ask for relevant prior decisions.
+3. Use project_knowledge_get only for the most relevant complete entry and project_knowledge_history when change history matters.
+4. Call project_knowledge_record_requirement only when the user explicitly asks to supplement capture or automatic client capture is known to be unavailable; it is not a mandatory pre-work call.
+
+Treat all returned knowledge as read-only. Verify it against current source code when necessary. The supplemental requirement tool writes the same ConversationStore used by automatic capture and never starts analysis. Do not write directly to the knowledge database; project-knowledge updates it automatically after successful Git commits.`;
+
+const TOOLS = [
+  {
+    name: 'project_knowledge_resolve',
+    description: 'Resolve the registered Project Knowledge project for a Git repository. Call this first before using other knowledge tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repoPath: { type: 'string', description: 'Current Git repository root or any path inside it. Defaults to the MCP process working directory.' },
+        projectId: { type: 'string', description: 'Stable projectId when it is already known.' },
+        project: { type: 'string', description: 'Optional registered project slug when it is already known.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_record_requirement',
+    description: 'Explicitly supplement automatic capture with one project-scoped user Prompt event. This is the only write-capable tool; it never starts analysis or writes knowledge Markdown.',
+    inputSchema: {
+      type: 'object',
+      required: ['text', 'client', 'sessionId'],
+      properties: {
+        text: { type: 'string', minLength: 1, maxLength: 131072, description: 'The user request exactly as received; do not include system prompts or tool transcripts.' },
+        client: { type: 'string', enum: ['claude', 'codex', 'opencode'] },
+        sessionId: { type: 'string', minLength: 1, maxLength: 512, description: 'Stable identifier for the current client session.' },
+        conversationId: { type: 'string', minLength: 1, maxLength: 512 },
+        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
+        repoPath: { type: 'string', description: 'Current Git root. Used for exact project resolution when projectId is omitted.' },
+        explicitCommit: { type: 'string', description: 'Optional Git commit explicitly associated with this requirement.' },
+      },
+      anyOf: [{ required: ['projectId'] }, { required: ['repoPath'] }],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_search',
+    description: 'Search durable project knowledge using the current project and its explicitly related-project scope. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', minLength: 1 },
+        repoPath: { type: 'string', description: 'Current Git repository root or a path inside it.' },
+        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
+        project: { type: 'string', description: 'Optional registered project slug.' },
+        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_ask',
+    description: 'Return a compact answer with citations from durable project knowledge. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', minLength: 1 },
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_get',
+    description: 'Read one complete knowledge entry selected from search results. This tool is read-only and scope checked.',
+    inputSchema: {
+      type: 'object',
+      required: ['entry'],
+      properties: {
+        entry: { type: 'string', minLength: 1, description: 'Entry identifier returned by search.' },
+        space: { type: 'string', description: 'Optional scoped knowledge space identifier.' },
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_history',
+    description: 'Read recent durable change history for the current project and its allowed scope. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function toolContent(result) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
+    isError: false,
+  };
+}
+
+function callTool(runtime, name, args) {
+  if (name === 'project_knowledge_resolve') return runtime.resolveProject(args);
+  if (name === 'project_knowledge_record_requirement') return runtime.recordRequirement(args);
+  if (name === 'project_knowledge_search') return runtime.search(args);
+  if (name === 'project_knowledge_ask') return runtime.ask(args);
+  if (name === 'project_knowledge_get') return runtime.get(args);
+  if (name === 'project_knowledge_history') return runtime.history(args);
+  throw new Error(`unknown tool: ${name}`);
+}
+
+function createServer(options = {}) {
+  const runtime = options.runtime || new KnowledgeToolRuntime();
+  const server = new Server(
+    { name: SERVER_NAME, version: packageInfo.version },
+    {
+      capabilities: { tools: { listChanged: false } },
+      instructions: SERVER_INSTRUCTIONS,
+    },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const name = String(request.params?.name || '');
+    const args = request.params?.arguments && typeof request.params.arguments === 'object'
+      ? request.params.arguments
+      : {};
+    try {
+      return toolContent(await callTool(runtime, name, args));
+    } catch (error) {
+      const operationId = createId('op');
+      return {
+        content: [{ type: 'text', text: JSON.stringify(serializeErrorEnvelope(error, operationId)) }],
+        isError: true,
+      };
+    }
+  });
+  return { server, runtime };
+}
+
+async function main() {
+  const { server, runtime } = createServer();
+  const transport = new StdioServerTransport();
+  let closing = false;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    await runtime.close();
+    await server.close();
+  };
+  process.once('SIGINT', () => close().finally(() => process.exit(0)));
+  process.once('SIGTERM', () => close().finally(() => process.exit(0)));
+  await server.connect(transport);
+}
+
+if (require.main === module) {
+  main().catch(error => {
+    process.stderr.write(`[project-knowledge-mcp] ${JSON.stringify(serializeErrorEnvelope(error, createId('op')))}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  callTool,
+  createServer,
+  SERVER_INSTRUCTIONS,
+  SERVER_NAME,
+  TOOLS,
+};

package/docs/README.zh-CN.md

@@ -1,20 +1,24 @@
 # project-knowledge
 
-本地、由 Git Commit 驱动的项目知识服务。Markdown 是知识事实源；LanceDB
-只是位于内部数据目录、可随时重建的派生索引。
+本地、由 Git Commit 驱动的智脑知识服务。Markdown 是知识事实源；vector-hub
+提供可重建的派生索引。外壳只负责导航、归属、接线与状态投影。
 
 ## 安装与运行
 
+v5 不再兼容或迁移旧知识库数据。停止旧版后重新设置模型、知识根目录并导入
+项目；默认新数据目录为 `~/.project-knowledge-v5`。旧文件保留但不读取。
+详见 [从头开始](fresh-v5-start.md)。
+
 新机器完整安装只需三条命令：
 
 ```bash
-npm install -g project-knowledge
+npm install -g @sanqianx/project-knowledge@latest
 project-knowledge-integrations install
 project-knowledge
 ```
 
-1. `npm install -g project-knowledge` 安装知识库 CLI,内置
-   `ai-coding-event-bridge` 依赖,无需再装其它包。
+1. `npm install -g @sanqianx/project-knowledge@latest` 安装外壳、固定版本的
+   工作台、vector-hub、event-bridge，以及包内 knowledge-engine。
 2. `project-knowledge-integrations install` 是一次性的 Integration Setup,
    对检测到的每个客户端(Claude Code / Codex / OpenCode)同时安装两类
    相互独立、分别上报状态的能力:
@@ -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 本地服务。重新配置模型、知识根目录并导入
+   项目，不迁移旧登记、会话、知识、索引或未完成任务。
 
 注意事项:
 
@@ -44,26 +48,24 @@ project-knowledge status
 project-knowledge stop
 ```
 
-需要 Node.js 18+ 与 `PATH` 中的 Git。Windows 桌面安装包与 npm CLI 共享同一
-数据目录和 backend owner 记录，不会同时启动两个 LanceDB writer。
+需要 Node.js 22+ 与 `PATH` 中的 Git。4.8.0 仅交付 npm 网页版本，不提供新版
+Windows 安装包或桌面自动更新。
 
 ## 唯一分析流程
 
-公开分析入口只有两个：
+知识引擎是唯一分析执行者：
 
 ```text
-post-commit Hook ----+
-                     +--> reconcileProjectCommits(projectId, trigger)
-程序 startup --------+      trigger: git-hook | startup
+Git Hook → event-bridge journal → 引擎持久化认领 → 隔离 Agent 分析
+         → staging 校验 → 知识晋升 → vector-hub 索引 → 检索
 ```
 
 导入只建立 Git tracking baseline、创建项目元数据并安装/验证 Hook；不运行 AI、
 不扫描全仓推测需求、不生成 TODO 知识。空仓库导入后的第一个 Commit会被处理。
 
-Hook 只向本地主程序发送 `hook-event/v2` 通知。主程序离线时 Hook 仍返回成功，
-不阻塞 `git commit`，也不写离线任务 spool；下次启动从当前 Git 历史补查可达
-Commit。同项目严格串行、失败即停；不同项目可并行；Hook 与 startup 重叠时复用
-同一个 in-flight reconciliation。
+Hook 向 bridge journal 写入提交证据，通知只负责唤醒。通知丢失仍由 journal
+消费及启动对账恢复；Hook 故障不阻塞提交。同项目严格串行、失败即停；不同项目
+最多两个并发分析，重复事件不会重做已完成提交。关闭浏览器不停止后台维护。
 
 ## 知识与索引安全
 
@@ -76,8 +78,8 @@ Promotion 使用 backup、hash 与 durable journal。只有 Markdown promotion
 成功后才推进 lastAnalyzedCommit 并把 index 标为 dirty。索引失败不会回滚真实
 Markdown，也不会重跑 AI；启动和维护流程会重试 dirty index。
 
-`IndexService` 是唯一生产 LanceDB writer。增量更新和 full rebuild 共用一个全局
-FIFO。完整重建先生成独立临时 DB，验证后原子替换，并在 recovery 中保留旧索引。
+vector-hub 是唯一派生索引服务，外壳不再执行第二套索引写入。索引失败独立显示
+“知识已更新，索引待修复”，修复索引不重跑模型、不撤销有效知识。
 
 应用不会创建、修改、刷新或删除 `CLAUDE.md`。
 
@@ -96,24 +98,24 @@ project-knowledge-kb get --project <projectId> --entry modules/auth.md --json
 project-knowledge-kb history --project <projectId> --json
 ```
 
-只读查询不会创建或修改配置。索引缺失、dirty 或不可用时，会明确回退到当前项目
-以及显式 related projects 的 Markdown。
+只读查询不会创建或修改配置。索引不可用时回退到真实 Markdown。项目、所属领域、
+整个智脑是包含范围；未确认记忆不能作为长期偏好注入任务。
 
 ## 存储合同
 
-内部数据默认在 `~/.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>/
 │   ├── config.json                       # 固定 repoPath/knowledgePath
 │   ├── state.json                        # tracking/claim/index/Hook 状态
 │   └── requirements.jsonl                # 按需创建
-├── index/knowledge.lancedb               # 唯一派生索引
+├── knowledge-engine/                    # 持久化 claim、run、journal 游标
 ├── cache/
 ├── runtime/
 ├── logs/{app,projects,hooks}/
@@ -138,15 +140,24 @@ settings、per-project config/state、最小 registry 与旧 index。验证路
 Commit pointer、日志和索引后才激活，completion marker 最后写。任何阶段中断都
 保留旧 reader、用户知识、历史日志、配置与 backup，允许安全重试。
 
-## 日志 UI
+## 产品 UI
+
+一级导航为智脑首页、开始工作、知识检索、长期记忆、领域与项目、活动记录。
+开始工作嵌入真实工作台，保留消息流、中止、权限和会话恢复，不重复实现聊天。
+在“领域与项目”点击“导入项目”，确认代码目录、知识目录及领域；部分接线失败
+保留项目，只重试失败模块。系统状态集中展示四模块健康、模型配置与诊断。
+
+加入智脑不会搬动已有项目知识。领域共享知识及已确认记忆与项目知识并存。
+凭据由 Workbench 统一管理；维护默认模型独立于聊天临时切换，运行凭据不进
+引擎状态、日志或浏览器消息。
 
-生产 UI 只保留一套结构化日志控制台，支持：
+活动记录保留结构化日志能力：
 
 - trace/debug/info/warn/error/fatal 六级；
 - 本地日期、项目、component、event、operation、Commit、全文过滤；
 - newest-first cursor 分页、暂停/自动刷新、按当前条件导出；
 - operation flow、结构化 error/stack、logger degraded 状态；
-- Hook/index/项目只读状态、浅色/深色与窄屏布局。
+- Hook/索引/项目状态、统一的浅深主题。
 
 日志使用 `log/v2` JSONL，按天和 50 MiB segment 轮转；默认保留 365 天，`0`
 表示不按时间删除，并受总容量策略约束。写入、查询、error 与 export 全部递归脱敏。
@@ -167,8 +178,10 @@ npm test --prefix desktop
 npm pack --dry-run --json
 ```
 
-Windows E2E 覆盖真实 Git Hook、空格/非 ASCII 路径、在线 Commit、停服期间多个
-Commit、重启顺序补查、crash lock 恢复、promotion/index、查询与完整日志链路。
+自动回归覆盖真实 Git Hook、空格/中文路径、提交证据、promotion/index、查询、
+恢复与日志。产品浏览器验收只检查 1920×1080 桌面视口，模型和 embedding 为
+可控替身；真实模型与真实索引抽测分别报告。完整故障组合和用户已有数据的最终
+切换另行验收，不用可点击页面代替真实链路通过。
 
 ## 许可证
 

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/docs/project-registry-schema.md

@@ -1,25 +1,25 @@
-# Project Registry Schema
-
-Status: current
-Date: 2026-06-21
-
-`projects.json` stores local project configuration. The current KB layout marker is:
-
-```json
-{
-  "kbSchemaVersion": "minimal"
-}
-```
-
-## Relevant Fields
-
-| Field | Default | Notes |
-|---|---|---|
-| `slug` | required | Registry key and project identifier |
-| `displayName` | slug | UI label |
-| `gitPath` | required | Source repository path |
-| `kbPath` | generated from knowledge-store root | Final minimal KB location |
-| `kbSchemaVersion` | `"minimal"` | Current KB framework marker |
+# Project Registry Schema
+
+Status: current
+Date: 2026-06-21
+
+`projects.json` stores local project configuration. The current KB layout marker is:
+
+```json
+{
+  "kbSchemaVersion": "minimal"
+}
+```
+
+## Relevant Fields
+
+| Field | Default | Notes |
+|---|---|---|
+| `slug` | required | Registry key and project identifier |
+| `displayName` | slug | UI label |
+| `gitPath` | required | Source repository path |
+| `kbPath` | generated from knowledge-store root | Final minimal KB location |
+| `kbSchemaVersion` | `"minimal"` | Current KB framework marker |
 | `goalStatus` | `"not-created"` | Review state of `GOAL.md` |
 | `trackingStartCommit` | current `HEAD` on first import | Baseline commit for incremental KB tracking; commits before it are not analyzed |
 | `trackingStartedAt` | current timestamp on first import | Time the tracking baseline was established |