docs: document data directory compatibility gate

docs/cn/contributing/development.md

@@ -65,6 +65,58 @@ ChatLab 同时维护 Electron 桌面端和 CLI Web 端。涉及共享业务逻
 - 平台差异通过 adapter 或 service 参数隔离，保持前端获得的数据结构一致。
 - 新增会话、成员、索引、摘要、导出、导入相关能力时，先确认是否能复用或扩展共享 service。
 
+## 数据目录兼容门禁
+
+Electron 桌面端、CLI Web 和 MCP 会共享同一个 `userDataDir`。如果某个新版 runtime 修改了数据库 schema、AI 数据、认证配置或数据目录布局，旧 runtime 继续读写同一目录可能会读错数据或破坏用户数据。因此，凡是会让旧版本无法安全访问同一数据目录的变更，都必须使用数据目录兼容门禁。
+
+兼容标记文件位于：
+
+```text
+<userDataDir>/.chatlab-meta.json
+```
+
+现有 `<userDataDir>/.chatlab` 仍只作为目录 marker，不承载 JSON 配置。
+
+### 什么时候需要提升门禁
+
+以下改动通常需要提升 `minRuntimeVersion`：
+
+- 数据库 schema 迁移会删除、重命名或改变旧版本会访问的表/字段语义
+- AI 对话、助手、技能、工具 allowlist、认证 profile、配置文件格式发生旧版本无法安全解析的变化
+- `userDataDir` 内目录布局变化会导致旧版本读写错误位置
+- 跨端共享数据的 canonical 命名或结构发生不向后兼容变化
+
+如果只是新增旧版本会忽略的可选字段，或修复不影响旧版本读写的数据派生逻辑，通常不需要提升门禁。
+
+### 实现要求
+
+- 使用 `packages/node-runtime/src/data-dir-compat.ts` 里的统一 helper，不要在入口层手写 JSON 读写和版本比较。
+- CLI、MCP、Desktop 启动时必须调用兼容检查；`DatabaseManager` 打开数据库前也会检查，用于捕获长驻旧服务运行期间目录被其他新版 runtime 提升的情况。
+- 执行会提升门禁的迁移时，必须只在迁移实际成功后写入 `.chatlab-meta.json`；如果写入失败，启动或打开数据库必须中断，不能继续对外服务。
+- `minRuntimeVersion` 只使用稳定 semver，例如 `0.25.1`；预发布版本不作为正式兼容判断。
+- 提升只能升高，不能降低；已有更高 `minRuntimeVersion` 时必须保留。
+- `reasons` 要合并去重，便于排查是哪类迁移提升了门禁。
+- HTTP route 遇到数据目录兼容错误时应返回 `DATA_DIR_INCOMPATIBLE` 和 409，而不是普通 500。
+
+隐藏救援开关：
+
+```bash
+CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR=1
+```
+
+这个开关只允许绕过“当前版本低于最低版本”的阻断，不能绕过损坏 JSON、非法字段或非法版本。使用时必须打印明确警告，并说明可能有数据损坏风险。
+
+### 测试要求
+
+修改会影响数据目录兼容性的代码时，至少覆盖：
+
+- 从上一个稳定版本和更早已发布版本升级时数据不丢失
+- `.chatlab-meta.json` 缺失时允许旧数据目录启动
+- 当前 runtime 低于 `minRuntimeVersion` 时 CLI/Desktop/MCP 或 `DatabaseManager` 会阻断
+- 迁移成功后会写入或合并 `minRuntimeVersion`、`dataCompatibilityVersion` 和 `reasons`
+- 已有更高 `minRuntimeVersion` 不会被降低
+- HTTP route 将兼容错误映射为 `DATA_DIR_INCOMPATIBLE`
+
 ## 常见改动入口
 
 | 想改什么 | 先看哪里 |

docs/en/contributing/development.md

@@ -65,6 +65,58 @@ ChatLab maintains both an Electron desktop app and a CLI Web app. When changing
 - Isolate platform differences through adapters or service options, and keep returned frontend data shapes consistent.
 - For new session, member, index, summary, export, or import behavior, first check whether an existing shared service can be reused or extended.
 
+## Data Directory Compatibility Gate
+
+Electron desktop, CLI Web, and MCP can share the same `userDataDir`. If a newer runtime changes the database schema, AI data, auth config, or data directory layout, an older runtime may read incorrect data or corrupt user data. Any change that makes old runtimes unsafe for the same data directory must use the data directory compatibility gate.
+
+The compatibility metadata file is:
+
+```text
+<userDataDir>/.chatlab-meta.json
+```
+
+The existing `<userDataDir>/.chatlab` file remains only a directory marker and should not be converted to JSON.
+
+### When To Raise The Gate
+
+Usually raise `minRuntimeVersion` when:
+
+- a database migration deletes, renames, or changes the meaning of tables/columns that older versions access
+- AI chats, assistants, skills, tool allowlists, auth profiles, or config files change in a way older versions cannot safely parse
+- the `userDataDir` layout changes so older versions would read or write the wrong location
+- shared cross-runtime data changes canonical names or structure in a non-backward-compatible way
+
+Adding optional fields that old versions safely ignore, or changing only regenerable derived data, usually does not require raising the gate.
+
+### Implementation Rules
+
+- Use the helpers in `packages/node-runtime/src/data-dir-compat.ts`; do not hand-roll JSON reads, writes, or semver comparison in entry points.
+- CLI, MCP, and Desktop startup must check compatibility. `DatabaseManager` also checks before opening a database so long-running stale services can notice when another newer runtime raises the gate.
+- A migration that raises the gate should write `.chatlab-meta.json` only after the migration actually succeeds. If writing the meta file fails, startup or database open must abort instead of continuing to serve requests.
+- `minRuntimeVersion` must be a stable semver such as `0.25.1`; prerelease versions are not accepted as the formal compatibility version.
+- Raising can only increase the requirement. If an existing meta file already requires a higher version, keep it.
+- Merge and de-duplicate `reasons` so future debugging can identify which migration raised the gate.
+- HTTP routes that hit a data directory compatibility error should return `DATA_DIR_INCOMPATIBLE` with HTTP 409, not a generic 500.
+
+Hidden rescue override:
+
+```bash
+CHATLAB_ALLOW_INCOMPATIBLE_DATA_DIR=1
+```
+
+This only bypasses “current runtime is below the required version.” It must not bypass broken JSON, invalid fields, or invalid versions. When used, the runtime must print a clear warning about data corruption risk.
+
+### Test Requirements
+
+Compatibility-related changes should cover:
+
+- upgrades from the previous stable version and earlier released versions without data loss
+- missing `.chatlab-meta.json` allowing old data directories to start
+- CLI/Desktop/MCP or `DatabaseManager` blocking when the current runtime is below `minRuntimeVersion`
+- successful migrations writing or merging `minRuntimeVersion`, `dataCompatibilityVersion`, and `reasons`
+- existing higher `minRuntimeVersion` values not being lowered
+- HTTP routes mapping compatibility failures to `DATA_DIR_INCOMPATIBLE`
+
 ## Common Change Entry Points
 
 | If you want to change | Start here |
@@ -85,8 +137,11 @@ ChatLab maintains both an Electron desktop app and a CLI Web app. When changing
 - After changing TypeScript or Vue code, run at least the relevant type check.
 - After changing public docs, run `pnpm docs:build` or targeted formatting checks for the changed Markdown/config files.
 - After changing shared cross-platform logic, confirm Electron and CLI Web entry points do not diverge in behavior.
+- Daily default test command is `pnpm test`; to prioritize related tests, run `pnpm test -- path/to/file.test.ts`.
+- `pnpm test` should include only unit/integration tests and must not depend on real LLMs, real Electron, real browsers, real network, or long-running E2E.
 - Unit tests tightly coupled to one business module should live next to the tested file and use `*.test.ts` or `*.test.js`.
 - Cross-module, integration, E2E, test utility, or unclear-ownership tests should live in the root `tests/` directory.
+- SQL behavior, database migrations, Fastify routes, and cross-package services should prefer lightweight in-memory SQLite or temporary file fixtures that exercise real behavior. Adapter-layer tests should focus on argument passing, permission filtering, error mapping, and response contracts instead of repeating lower-level algorithm matrices.
 
 ## i18n And Copy