@mjh-odoo/cli 0.0.0-stage → 0.1.6

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @mjh-odoo/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+跨平台 Odoo 20 开发管理 CLI，命令名为 odoo。提供环境、模块、日志、原生数据库 ZIP 与镜像管理。
+
+## 安装与启动
+
+需要 Node.js 24+、Docker、Compose 和 Buildx。Windows PowerShell 可直接使用；Python/Odoo/PostgreSQL 在目标项目的容器中运行。
+
+```sh
+npm install -g @mjh-odoo/cli
+odoo --help
+odoo --version
+```
+
+进入兼容项目后执行 odoo init、odoo up。CLI 不创建完整 Odoo 项目；项目应包含 compose.yaml、.env.example、完整官方源码及容器脚本，见 [项目契约](docs/architecture.md)。模板密码的非空优先规则从 0.1.1 支持；0.1.0 先用项目的 node scripts/dev.mjs init 准备配置。
+
+从子目录也能发现项目，指定目录时全局参数放在命令之前：
+
+```sh
+odoo --project /path/to/project status --json
+```
+
+## 常用命令
+
+```sh
+odoo config
+odoo doctor --json
+odoo up
+odoo up --no-build --pull never --wait-timeout 600
+odoo status --json
+odoo logs all --since 10m --json
+odoo logs all --since 10m --tail 1000 --level error --context 3 --hide-health --json
+odoo module list --json
+odoo module install first_module second_module
+odoo module update first_module second_module -d target_db
+odoo db list --json
+odoo db backup
+odoo db restore --file /path/to/backup.zip -d restored_db
+odoo down
+```
+
+每个命令支持 --help。模块列表只读；安装和升级会停止 Odoo 并运行维护容器。-d 只改变本次目标，不改 .env。维护失败保留停止状态，先看本次错误输出再修复启动。
+
+日志默认有限快照，持续查看才加 -f；JSON、筛选和文件导出不能与 -f 混用。异常保留上下文，空结果不代表服务无故障。
+
+普通 down 保留卷；只有明确要删除本项目数据库与附件时使用 -v，可先 --dry-run 看计划。恢复已有目标库需要显式 --force；加 `--use` 可以在成功恢复到新库后切换。备份默认保存在工作树外，odoo config 显示位置。
+
+## 与 Odoo Manager 共用存档
+
+在 Odoo Manager 接入项目并设置存档目录后，可以在主目录或任意 Git 工作树中执行：
+
+```sh
+odoo archive save "销售验收版" --tag latest
+odoo archive import /path/to/backup.zip
+odoo archive list --json
+odoo archive tag set latest <archive-id>
+odoo db restore latest --to sales_review --use
+```
+
+桌面端和 CLI 共用存档及标签。标签在命令执行时解析，也可用 `id:<存档ID>` 固定版本。发布只移动标签，已有环境的数据由该环境自行维护。`db use` 更新当前环境的 `PGDATABASE` 并重启原本运行中的 Odoo，原库保留。用 `archive delete <ID> --yes` 删除无标签的 ZIP，用 `db delete <库名> --yes` 删除已切走的数据库和附件。
+
+在新工作树的 `.env` 配置 `ODOO_SEED=tag:latest` 与 `ODOO_SEED_MODE=first-start`，首次 `odoo up` 会从标签恢复到空库，然后启动 Odoo。可在 `.env.example` 预填，使新工作树的 `odoo init` 一起复制配置。默认 `manual`。
+
+`odoo archive seed tag:latest` 为已接入项目设置工作树的首次数据来源，`odoo archive source` 预览。恢复被中断后可用 `odoo db recover --yes` 清理本次创建的残留库。用 `odoo archive library export <新目录>` 和 `odoo archive library import <目录>` 迁移存档及标签。用 `odoo worktree archived` 查看已归档工作树的数据卷。
+
+## 镜像与官方命令
+
+```sh
+odoo image build --dry-run
+odoo image build --platform amd64 --file /path/to/runtime.tar
+odoo image build --target production --tag my-erp:v1
+odoo exec -- --version
+odoo exec -- --help
+odoo help exec
+```
+
+多架构和推送参数见 image build --help；生产镜像需要明确项目标签。exec 将后续参数原样传给容器内官方 Odoo，管理工具本身的说明用 help exec。
+
+## Agent Skill
+
+本仓库和 npm 包携带 [.agents/skills/odoo-cli](.agents/skills/odoo-cli/SKILL.md)。目标项目把完整目录放入自身 .agents/skills/ 后，可使用 `$odoo-cli` 管理该项目；Skill 按需要读取开发、日志或 ZIP 引用。
+
+例如：使用 `$odoo-cli` 为当前项目导出默认数据库的原生 ZIP；或检查最近十分钟错误日志并保留上下文。
+
+开发入口见 仓库根 AGENTS.md、[文档地图](docs/README.md)、[架构](docs/architecture.md)、[开发](docs/development.md) 和 [验证范围](docs/validation.md)。实际版本以 odoo --version 与包发布记录为准。

package/bin/odoo.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { createProgram } from '../src/cli.mjs';
+
+const {version} = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+try {
+  await createProgram({version}).parseAsync(process.argv);
+} catch (error) {
+  console.error('错误: ' + error.message);
+  process.exitCode = error.exitCode || 1;
+}

package/docs/README.md

@@ -0,0 +1,11 @@
+# 开发文档地图
+
+| 任务 | 优先阅读 |
+| --- | --- |
+| 安装和日常命令 | [项目 README](../README.md)、odoo --help |
+| 定位命令、配置和 Base 交互 | [架构与项目契约](architecture.md) |
+| 修改、测试、打包与交付 | [开发流程](development.md) |
+| 使用 CLI 管理目标项目 | [odoo-cli Skill](../.agents/skills/odoo-cli/SKILL.md) |
+| 核对实际验证范围 | [验证证据](validation.md) |
+
+按当前任务定位实现；不要默认把整个历史验证或所有 Odoo 源码读入上下文。代码行为与已确认约束不一致时明确指出并修正。大任务按需建立 docs/tasks/<任务>.md，记录范围、相关提交、有效证据、未完成项和下一步；不创建空目录。

package/docs/architecture.md

@@ -0,0 +1,34 @@
+# 架构与目标项目契约
+
+## 管理 CLI 的代码
+
+| 文件 | 职责 |
+| --- | --- |
+| bin/odoo.mjs | 读取包版本，启动命令解析和错误出口 |
+| src/cli.mjs | Commander 命令树、帮助、参数校验与命令分派 |
+| src/project.mjs | 向上查找目标、Compose 上下文、数据库/服务名检查、进程执行和操作锁 |
+| src/commands.mjs | 环境、服务、模块、数据库操作 |
+| src/lib/environment.mjs | .env 解析、初始化、项目身份、端口、存档位置与脱敏配置 |
+| src/lib/logs.mjs | 有限日志、事件、上下文、脱敏和导出 |
+| src/lib/image.mjs | Buildx 镜像计划、平台约束和离线输出 |
+| .agents/skills/odoo-cli/ | 管理操作的可复用 Agent Skill，随 npm 包提供 |
+
+全局 --project 放在子命令之前；否则从调用目录向上寻找同时含 compose.yaml 与 .env.example 的项目。npm 包安装位置不影响项目定位。
+
+## 目标项目提供什么
+
+| 目标文件/目录 | 用途 |
+| --- | --- |
+| compose.yaml、.env.example | 项目识别与运行配置 |
+| .env | 本机配置，真实值不入 Git |
+| odoo/odoo-bin、odoo/ | 官方进程和完整源码 |
+| addons/ | 项目、外部和非生产模块 |
+| scripts/runtime.py | serve、install、upgrade 等容器运行逻辑 |
+| scripts/backup_utils.py | ZIP validate、restore，调用官方 load |
+| config/、Dockerfile | 运行配置与镜像构建 |
+
+Compose 服务名为 odoo 和 db。CLI 显式指定主 Compose、环境文件及项目身份。模块维护通过 runtime.py 的一次性容器执行；ZIP 备份调用运行容器中的官方 odoo db dump，恢复通过 backup_utils.py 调用官方 db load --neutralize。管理命令的 -d 默认读取 PGDATABASE，不自动切换项目默认库。
+
+只读命令通过 validateEnv 读取已有配置，init/up 可准备缺失的 .env。支持固定模板密码的版本为 0.1.1+；已有环境不改写。项目内兼容脚本有自己的语法和副作用，不能假设与全部 CLI 选项相同。
+
+环境、日志、镜像能力也可能存在于项目内兼容入口。修改共享行为时检查对应项目实现和测试，任务记录列出需要同步的消费方；不自动改无关仓库。

package/docs/development.md

@@ -0,0 +1,40 @@
+# CLI 开发与交付
+
+## 准备与检查
+
+需要 Node.js 24+。首次准备依赖用 npm ci --ignore-scripts；依赖和安装状态未变时不重复安装。
+
+```sh
+npm run check
+npm test
+```
+
+参数、帮助与项目副作用检查由 test/cli.test.mjs 覆盖；环境、日志和镜像各有独立测试文件。验证与改动相符，文档或 Skill 变化只补链接、语法、命令帮助和打包检查，不为此启动用户数据库。
+
+## 任务和合并
+
+从最新 main 或包含所需前置改动的明确基线创建 codex/ 任务分支。工作树由原生工具管理；同一检出一个写入任务，审查优先只读。小而完整的变更及时集成，单一逻辑 PR 可 squash，有独立意义的历史保留。
+
+行为变化更新 README 或对应专题。PR 写清问题、最终行为、验证和限制；跨会话复杂任务才维护 docs/tasks/<任务>.md，不复制聊天记录或凭据。
+
+## 独立集成验收
+
+test/docker-acceptance.py 需要 Python、Docker、兼容 Base 与已有基础镜像，脚本创建可丢弃测试项目。使用前阅读脚本和帮助，明确临时资源；不能在用户开发库运行删除卷或覆盖恢复。
+
+```sh
+python3 test/docker-acceptance.py /absolute/path/to/base /absolute/path/to/installed/odoo
+```
+
+单元测试不等于真实 Docker/平台验收。新增数据库或运行行为需在独立实例验证；没有对应设备时明确未测试，不把 CI 配置当结果。
+
+## Skill 维护
+
+Skill 源码为 .agents/skills/odoo-cli/，SKILL.md 只保留定位、路由和必要边界，开发、日志、数据库的细节在 references/。修改后使用可用的 skill-creator 校验器检查 frontmatter 与 agents/openai.yaml，并核对文中命令的真实帮助。
+
+消费项目把完整目录放到自己的 .agents/skills/odoo-cli，保持同一内容。复制时保留官方技能与许可，不把真实项目路径和配置写入 Skill。npm 包中的同一路径可作为分发来源；项目内 .agents/skills 是 Agent 的发现位置。
+
+## 打包与发布
+
+使用 npm pack 生成候选，检查 files 白名单只包含可发布文件；安装到独立临时前缀，运行实际 odoo --version、--help、init 和相应功能，确认 Skill 的入口与引用一同存在。
+
+main 是可集成主线，发布标签 v<版本> 固定验收结果。package.json 的候选版本不等于已在 npm 发布；发布状态以实际 registry/Release 结果为准。包发布、Git 推送与镜像上传分别遵循用户已授权范围，认证由本人处理，不记录凭据。

package/docs/validation.md

@@ -0,0 +1,19 @@
+# 验证证据
+
+记录日期：2026-11-03。package.json 目前为本地 0.1.1 候选；已发布版本为 0.1.0，候选尚未上传或创建发布标签。
+
+## 已发布 0.1.0
+
+32 项 Node 测试与 Windows/macOS/Linux Node 24 CI 曾通过；npm pack 后安装到临时前缀，实际可执行文件帮助、版本和独立 Docker 验收通过。
+
+macOS ARM64 的临时项目覆盖空库启动、批量模块安装/升级、数据库参数不改默认配置、原生 ZIP 的真实附件逐字节恢复、有限日志、普通 down 保留数据与显式删测试卷。所有临时项目资源已清理，用户开发数据未操作。
+
+## 本地 0.1.1 候选
+
+40 项 Node 测试通过，涵盖模板三个密码非空优先、部分留空、重复 init、引号、缺失字段和 CRLF。真实打包安装后验证固定/随机密码及 Compose 传递；重复 init 保留现有 .env。
+
+本轮新增文档与 CLI Skill，40 项测试及语法检查通过。npm pack 安装后的实际命令完成帮助、init 和 Compose 配置验证；分发包含 SKILL.md、agents/openai.yaml 及全部 3 个引用文件，共 5 个 Skill 文件。四份项目副本一致，格式/UI 元数据与 144 处本地链接通过检查，官方技能和现有 .env 未变。现有 CI 打包步骤已增加 Skill 入口/元数据存在检查，本候选尚未在远端执行。
+
+## 平台范围
+
+本机为 macOS ARM64、Node 26.8.1。0.1.1 的远端跨平台 CI 尚未执行；Windows 原生/WSL/Linux Docker 仍需对应设备验证。已有旧版本 CI 不代表当前候选已通过。

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@mjh-odoo/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "Cross-platform Odoo development CLI: environments, modules, database archives, logs and images",
+  "type": "module",
+  "bin": {
+    "odoo": "bin/odoo.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "LGPL-3.0-only",
+  "author": "MaJianhang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjh-odoo/odoo-cli.git"
+  },
+  "homepage": "https://github.com/mjh-odoo/odoo-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mjh-odoo/odoo-cli/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    ".agents/skills/odoo-cli/",
+    "LICENSE",
+    "COPYRIGHT"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check bin/odoo.mjs && node --check src/cli.mjs && node --check src/commands.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "dependencies": {
+    "commander": "15.0.0"
+  }
+}

package/src/archive-library.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import { copyFile, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { archiveLocation, insertArchive, pointTag, projectTags, tagName, transaction, withArchiveCatalog } from './archive.mjs';
+
+const filename = 'odoo-archives.json';
+const validId = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/;
+const textFields = ['title', 'note', 'environment', 'database', 'created', 'revision'];
+
+async function digest(file) {
+  const hash = createHash('sha256');
+  for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function checkedCopy(source, target, size, hash) {
+  const info = await lstat(source);
+  if (!info.isFile() || info.size !== size) throw new Error('ZIP 不存在或大小不符：' + path.basename(source));
+  await copyFile(source, target, fs.constants.COPYFILE_EXCL);
+  if (process.platform !== 'win32') fs.chmodSync(target, 0o600);
+  const result = await digest(target);
+  if (hash && result !== hash) throw new Error('ZIP 校验失败：' + path.basename(source));
+  return result;
+}
+
+export async function exportLibrary(root, destination) {
+  const inventory = await withArchiveCatalog(root, false, (db, project) => {
+    db.exec('BEGIN');
+    try {
+      const archives = db.prepare('SELECT * FROM archives WHERE projectId = ? ORDER BY created').all(project.id);
+      const tags = projectTags(db, project.id);
+      const seed = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'project_seeds'").get()
+        ? db.prepare('SELECT reference FROM project_seeds WHERE projectId = ?').get(project.id)?.reference : undefined;
+      return {project: project.name, archives, tags, seed};
+    } finally { db.exec('COMMIT'); }
+  });
+  if (!inventory.archives.length) throw new Error('当前项目没有可导出的存档。');
+  const folder = path.resolve(destination);
+  const parent = fs.realpathSync(path.dirname(folder));
+  const checkout = path.relative(root, parent);
+  if (!checkout || (!path.isAbsolute(checkout) && checkout !== '..' && !checkout.startsWith('..' + path.sep))) {
+    throw new Error('请将存档库导出到项目目录之外。');
+  }
+  await mkdir(folder, {mode: 0o700});
+  try {
+    const archives = [];
+    for (const archive of inventory.archives) {
+      if (!validId.test(archive.id)) throw new Error('不支持的存档 ID：' + archive.id);
+      const sha256 = await checkedCopy(archive.file, path.join(folder, archive.id + '.zip'), archive.bytes);
+      archives.push({id: archive.id, ...Object.fromEntries(textFields.map(key => [key, archive[key]])), bytes: archive.bytes, source: archive.source, sha256});
+    }
+    await writeFile(path.join(folder, filename), JSON.stringify({format: 1, ...inventory, archives}, null, 2) + '\n', {flag: 'wx', mode: 0o600});
+    return {directory: folder, archives: archives.length, tags: inventory.tags.length};
+  } catch (error) {
+    await rm(folder, {recursive: true, force: true});
+    throw error;
+  }
+}
+
+async function readInventory(folder) {
+  const file = path.join(folder, filename);
+  const info = await lstat(file);
+  if (!info.isFile() || info.size > 16 * 1024 * 1024) throw new Error('存档库索引文件无效。');
+  const data = JSON.parse(await readFile(file, 'utf8'));
+  if (data?.format !== 1 || !Array.isArray(data.archives) || !data.archives.length || !Array.isArray(data.tags)) {
+    throw new Error('请选择包含 odoo-archives.json 的存档库目录。');
+  }
+  const ids = new Set();
+  for (const row of data.archives) {
+    if (!row || typeof row.id !== 'string' || !validId.test(row.id) || ids.has(row.id) ||
+        !Number.isSafeInteger(row.bytes) || row.bytes <= 0 || !/^[a-f0-9]{64}$/.test(row.sha256) ||
+        !['backup', 'import'].includes(row.source) || textFields.some(key => typeof row[key] !== 'string') ||
+        !row.title.trim() || row.title.length > 120 || row.note.length > 2000 || !Number.isFinite(Date.parse(row.created))) {
+      throw new Error('存档库的存档记录无效。');
+    }
+    ids.add(row.id);
+  }
+  const tags = new Set();
+  for (const row of data.tags) {
+    if (!row || typeof row.tag !== 'string' || tags.has(tagName(row.tag)) || !ids.has(row.archiveId)) throw new Error('存档库的标签记录无效。');
+    tags.add(row.tag);
+  }
+  if (data.seed !== undefined && data.seed !== 'empty' &&
+    !(typeof data.seed === 'string' && (data.seed.startsWith('tag:') ? tagName(data.seed.slice(4)) :
+      data.seed.startsWith('id:') && ids.has(data.seed.slice(3))))) throw new Error('存档库的首次启动来源无效。');
+  return data;
+}
+
+export async function importLibrary(root, source) {
+  const folder = fs.realpathSync(path.resolve(source));
+  const manifest = await readInventory(folder);
+  return withArchiveCatalog(root, true, async (db, project) => {
+    const existing = db.prepare('SELECT * FROM archives WHERE id = ?');
+    const staged = [], added = [], skippedTags = [];
+    let retained = 0;
+    try {
+      for (const row of manifest.archives) {
+        const file = path.join(folder, row.id + '.zip');
+        const prior = existing.get(row.id);
+        if (prior) {
+          if (prior.projectId !== project.id || prior.bytes !== row.bytes || await digest(prior.file) !== row.sha256) {
+            throw new Error('本机已有内容不同或属于其他项目的存档：' + row.id);
+          }
+          retained++;
+          continue;
+        }
+        const target = archiveLocation(db, root, row.id);
+        const temporary = target + '.' + randomUUID() + '.part';
+        staged.push({temporary, archive: {...row, projectId: project.id, file: target}});
+        await checkedCopy(file, temporary, row.bytes, row.sha256);
+      }
+      transaction(db, () => {
+        for (const {temporary, archive} of staged) {
+          fs.linkSync(temporary, archive.file);
+          added.push(archive.file);
+          insertArchive(db, archive);
+        }
+        const tags = new Map(projectTags(db, project.id).map(tag => [tag.tag, tag.archiveId]));
+        for (const row of manifest.tags) {
+          if (!tags.has(row.tag)) pointTag(db, project.id, row.tag, row.archiveId);
+          else if (tags.get(row.tag) !== row.archiveId) skippedTags.push(row.tag);
+        }
+        if (manifest.seed) db.prepare('INSERT INTO project_seeds VALUES (?, ?) ON CONFLICT(projectId) DO NOTHING').run(project.id, manifest.seed);
+      });
+      return {imported: staged.length, retained, skippedTags};
+    } catch (error) {
+      for (const file of added) fs.rmSync(file, {force: true});
+      throw error;
+    } finally {
+      for (const {temporary} of staged) fs.rmSync(temporary, {force: true});
+    }
+  });
+}

package/src/archive.mjs

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function catalogFile() {
+  const home = os.homedir();
+  const appData = process.platform === 'darwin' ? path.join(home, 'Library', 'Application Support')
+    : process.platform === 'win32' ? process.env.APPDATA || path.join(home, 'AppData', 'Roaming')
+      : process.env.XDG_CONFIG_HOME || path.join(home, '.config');
+  return process.env.ODOO_MANAGER_CATALOG || path.join(appData, 'Odoo Manager', 'manager.sqlite');
+}
+
+function gitCommonDirectory(root) {
+  try {
+    const value = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      {cwd: root, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore']});
+    return fs.realpathSync(value.trim());
+  } catch { return null; }
+}
+
+function resolveProject(db, root, optional) {
+  const direct = db.prepare('SELECT * FROM projects WHERE root = ?').get(root);
+  if (direct) return direct;
+  const common = gitCommonDirectory(root);
+  if (!common && optional) return null;
+  if (!common) throw new Error('请先在 Odoo Manager 接入当前项目。');
+  const matches = db.prepare('SELECT * FROM projects').all()
+    .filter(project => gitCommonDirectory(project.root) === common);
+  if (!matches.length && optional) return null;
+  if (matches.length !== 1) throw new Error(matches.length ? '当前工作树匹配了多个项目，请从已接入的项目目录执行。' : '请先在 Odoo Manager 接入当前项目。');
+  return matches[0];
+}
+
+export async function withArchiveCatalog(root, write, action, {optional = false} = {}) {
+  const file = catalogFile();
+  if (!fs.statSync(file, {throwIfNoEntry: false})?.isFile()) {
+    if (optional) return null;
+    throw new Error('找不到本机存档库，请先在 Odoo Manager 接入项目。');
+  }
+  const {DatabaseSync} = await import('node:sqlite');
+  const db = new DatabaseSync(file, {readOnly: !write});
+  try {
+    db.exec('PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;');
+    const project = resolveProject(db, root, optional);
+    if (!project) return null;
+    if (write) ensureArchiveTags(db);
+    return await action(db, project);
+  } finally { db.close(); }
+}
+
+const hasTable = (db, name) => !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+
+export function transaction(db, action) {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const result = action();
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+export function ensureArchiveTags(db) {
+  transaction(db, () => {
+    db.exec(`CREATE TABLE IF NOT EXISTS archive_tags (
+      projectId TEXT NOT NULL REFERENCES projects(id),
+      tag TEXT NOT NULL,
+      archiveId TEXT NOT NULL REFERENCES archives(id),
+      PRIMARY KEY (projectId, tag)
+    );
+    CREATE TABLE IF NOT EXISTS project_seeds (
+      projectId TEXT PRIMARY KEY REFERENCES projects(id), reference TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS project_runtimes (
+      root TEXT PRIMARY KEY, projectId TEXT NOT NULL REFERENCES projects(id), composeProject TEXT NOT NULL
+    )`);
+    if (hasTable(db, 'archive_defaults')) {
+      db.exec(`INSERT OR IGNORE INTO archive_tags
+        SELECT projectId, 'latest', archiveId FROM archive_defaults;
+        DROP TABLE archive_defaults;`);
+    }
+  });
+}
+
+export function projectTags(db, projectId) {
+  if (hasTable(db, 'archive_tags')) {
+    return db.prepare('SELECT tag, archiveId FROM archive_tags WHERE projectId = ? ORDER BY tag').all(projectId);
+  }
+  if (hasTable(db, 'archive_defaults')) {
+    return db.prepare("SELECT 'latest' AS tag, archiveId FROM archive_defaults WHERE projectId = ?").all(projectId);
+  }
+  return [];
+}
+
+export async function archiveList(root, {json}) {
+  const result = await withArchiveCatalog(root, false, (db, project) => {
+    const tags = projectTags(db, project.id);
+    const rows = db.prepare('SELECT id, title, note, environment, database, bytes, created, revision, source FROM archives WHERE projectId = ? ORDER BY created DESC').all(project.id);
+    return rows.map(archive => ({...archive, tags: tags.filter(tag => tag.archiveId === archive.id).map(tag => tag.tag)}));
+  });
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else if (!result.length) console.log('此项目还没有数据库存档。');
+  else for (const archive of result) console.log([archive.id, archive.title, archive.database, archive.tags.join(', ')].filter(Boolean).join('  '));
+}
+
+function findArchive(db, projectId, id, requireFile = true) {
+  const row = db.prepare('SELECT * FROM archives WHERE projectId = ? AND id = ?').get(projectId, id);
+  if (!row) throw new Error('此项目没有该存档：' + id);
+  if (requireFile && (!path.isAbsolute(row.file) || !fs.statSync(row.file, {throwIfNoEntry: false})?.isFile())) {
+    throw new Error('存档 ZIP 已丢失或不可用：' + id + '。请在 Odoo Manager 检查存档。');
+  }
+  return row;
+}
+
+export function tagName(value) {
+  if (!/^[a-z][a-z0-9._-]{0,63}$/.test(value)) throw new Error('标签须以小写字母开头，最多 64 字符，可包含小写字母、数字、点、下划线和短横线。');
+  return value;
+}
+
+function findReference(db, projectId, reference) {
+  if (reference.startsWith('id:')) return findArchive(db, projectId, reference.slice(3));
+  const tags = projectTags(db, projectId);
+  const explicitTag = reference.startsWith('tag:');
+  const tag = explicitTag ? tagName(reference.slice(4)) : reference === 'default' ? 'latest' : reference;
+  const selected = tags.find(row => row.tag === tag);
+  if (!selected && (explicitTag || reference === 'default' || reference === 'latest')) throw new Error('此项目尚未设置标签：' + tag);
+  return findArchive(db, projectId, selected?.archiveId || reference);
+}
+
+export async function resolveArchive(root, reference) {
+  return withArchiveCatalog(root, false, (db, project) => findReference(db, project.id, reference));
+}
+
+export async function archiveSeed(root, reference, {json} = {}) {
+  const result = await withArchiveCatalog(root, reference !== undefined, (db, project) => {
+    if (reference !== undefined) transaction(db, () => {
+      if (reference.startsWith('tag:')) tagName(reference.slice(4));
+      else if (reference.startsWith('id:')) findReference(db, project.id, reference);
+      else if (reference !== 'empty') throw new Error('数据来源使用 tag:<标签>、id:<存档ID> 或 empty。');
+      db.prepare('INSERT INTO project_seeds VALUES (?, ?) ON CONFLICT(projectId) DO UPDATE SET reference = excluded.reference')
+        .run(project.id, reference);
+    });
+    return hasTable(db, 'project_seeds') ? db.prepare('SELECT reference FROM project_seeds WHERE projectId = ?').get(project.id)?.reference : null;
+  });
+  console.log(json ? JSON.stringify({reference: result || 'empty'}) : (result || 'empty'));
+}
+
+export async function startupSeed(root, values, preview = false) {
+  if (values.ENV === 'PROD' || values.ODOO_SEED_MODE === 'empty' ||
+      (values.ODOO_SEED && values.ODOO_SEED_MODE !== 'first-start')) return {reference: null, source: 'env'};
+  const configured = values.ODOO_SEED && values.ODOO_SEED_MODE === 'first-start' ? values.ODOO_SEED : null;
+  return await withArchiveCatalog(root, false, (db, project) => {
+    const projectSeed = root !== project.root && hasTable(db, 'project_seeds') ? db.prepare('SELECT reference FROM project_seeds WHERE projectId = ?').get(project.id)?.reference : null;
+    const reference = configured || projectSeed || null;
+    const source = configured ? 'env' : 'project';
+    if (!reference || reference === 'empty') return {reference: null, source};
+    if (!preview) return {reference, source};
+    try {
+      const archive = findReference(db, project.id, reference);
+      return {reference, source, archive: {id: archive.id, title: archive.title}};
+    } catch (error) { return {reference, source, issue: error.message}; }
+  }, {optional: true}) || {reference: configured, source: configured ? 'env' : 'project',
+    ...(configured && preview ? {issue: '请先在 Odoo Manager 接入当前项目。'} : {})};
+}
+
+export async function rememberRuntime(root, composeProject) {
+  return withArchiveCatalog(root, true, (db, project) => {
+    if (root === project.root) return;
+    db.prepare('INSERT INTO project_runtimes VALUES (?, ?, ?) ON CONFLICT(root) DO UPDATE SET composeProject = excluded.composeProject')
+      .run(root, project.id, composeProject);
+  }, {optional: true});
+}
+
+export async function archiveTags(root, {json}) {
+  const rows = await withArchiveCatalog(root, false, (db, project) =>
+    projectTags(db, project.id).map(row => ({...row, title: findArchive(db, project.id, row.archiveId, false).title})));
+  if (json) console.log(JSON.stringify(rows, null, 2));
+  else for (const row of rows) console.log(row.tag + ' → ' + row.title + ' (' + row.archiveId + ')');
+}
+
+export async function archiveTag(root, tag, id) {
+  tagName(tag);
+  await withArchiveCatalog(root, true, (db, project) => transaction(db, () => {
+    if (!id) {
+      db.prepare('DELETE FROM archive_tags WHERE projectId = ? AND tag = ?').run(project.id, tag);
+      console.log('已移除标签：' + tag);
+      return;
+    }
+    const row = findArchive(db, project.id, id);
+    pointTag(db, project.id, tag, row.id);
+    console.log(tag + ' → ' + row.title + ' (' + row.id + ')');
+  }));
+}
+
+export async function archiveDefault(root, id) {
+  if (id) return archiveTag(root, 'latest', id);
+  const selected = await withArchiveCatalog(root, false, (db, project) => projectTags(db, project.id).find(row => row.tag === 'latest'));
+  console.log(selected?.archiveId || '此项目尚未设置 latest。');
+}
+
+export async function deleteArchive(root, id) {
+  await withArchiveCatalog(root, true, (db, project) => transaction(db, () => {
+    const row = findArchive(db, project.id, id, false);
+    const tags = projectTags(db, project.id).filter(tag => tag.archiveId === id);
+    if (tags.length) throw new Error('请先移动或移除标签：' + tags.map(row => row.tag).join(', '));
+    if (db.prepare('SELECT 1 FROM project_seeds WHERE projectId = ? AND reference = ?').get(project.id, 'id:' + id)) {
+      throw new Error('该存档用于新工作树首次启动，请先更改项目的数据来源。');
+    }
+    if (!path.isAbsolute(row.file) || path.basename(row.file) !== row.id + '.zip') throw new Error('无法确认存档文件位置。');
+    fs.rmSync(row.file, {force: true});
+    db.prepare('DELETE FROM archives WHERE projectId = ? AND id = ?').run(project.id, id);
+    console.log('已删除存档：' + row.title);
+  }));
+}
+
+export function pointTag(db, projectId, tag, id) {
+  db.prepare('INSERT INTO archive_tags VALUES (?, ?, ?) ON CONFLICT(projectId, tag) DO UPDATE SET archiveId = excluded.archiveId')
+    .run(projectId, tag, id);
+}
+
+export function insertArchive(db, archive) {
+  const {id, projectId, title, note, environment, database, file, bytes, created, revision, source} = archive;
+  db.prepare('INSERT INTO archives (id, projectId, title, note, environment, database, file, bytes, created, revision, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+    .run(id, projectId, title, note, environment, database, file, bytes, created, revision, source);
+}
+
+export function saveArchive(db, archive, tag) {
+  transaction(db, () => {
+    insertArchive(db, archive);
+    if (tag) pointTag(db, archive.projectId, tag, archive.id);
+  });
+}
+
+export function archiveLocation(db, root, id) {
+  const settings = JSON.parse(db.prepare('SELECT value FROM settings WHERE id = 1').get()?.value || '{}');
+  if (typeof settings.archiveRoot !== 'string' || !path.isAbsolute(settings.archiveRoot)) {
+    throw new Error('请在 Odoo Manager 设置存档目录。');
+  }
+  fs.mkdirSync(settings.archiveRoot, {recursive: true});
+  const directory = fs.realpathSync(settings.archiveRoot);
+  const roots = [root, ...db.prepare('SELECT root FROM environments').all().map(env => env.root)];
+  if (roots.some(checkout => {
+    const relative = path.relative(checkout, directory);
+    return !relative || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
+  })) throw new Error('请选择项目和工作树之外的存档目录。');
+  return path.join(directory, id + '.zip');
+}
+
+export function archiveSource(db, project, root) {
+  const name = db.prepare('SELECT name FROM environments WHERE projectId = ? AND root = ?').get(project.id, root)?.name;
+  let revision = '';
+  try {
+    const git = args => execFileSync('git', args, {cwd: root, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore']}).trim();
+    revision = git(['rev-parse', 'HEAD']) + (git(['status', '--porcelain']) ? '（有未提交改动）' : '');
+  } catch { /* Git metadata is optional. */ }
+  return {environment: name || path.basename(root), revision};
+}