@mjh-odoo/cli 0.0.0-stage → 0.1.6

package/.agents/skills/odoo-cli/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: odoo-cli
+description: 使用 odoo CLI 管理 Odoo 开发项目的环境、模块、日志、镜像和原生数据库 ZIP。适用于启动排查、安装升级模块、数据库存档与恢复；CLI 自身源码开发遵循所在仓库的工程文档。
+---
+
+# Odoo CLI 项目管理
+
+使用当前项目的真实命令和配置完成任务，不创建新的项目管理协议。
+
+## 先定位项目与入口
+
+- 在目标项目确认 `compose.yaml`、`.env.example`；从子目录运行会向上寻找项目。CLI 源码库或纯模块库未必是可运行项目。
+- 操作其他目录时用全局参数：`odoo --project /path/to/project <命令>`，`--project` 放在子命令前。先读目标项目的 AGENTS.md。
+- 用 `odoo --version` 和相应 `--help` 核对能力。未知或报错的参数先查帮助，不猜测新命令。
+- `.env` 已存在就保留。首次初始化可用 `odoo init`；CLI 0.1.0 会覆盖模板的显式密码，遇到该版本时用项目现有的 `node scripts/dev.mjs init`，或使用支持此规则的 0.1.1+。
+- 缺少全局 CLI 时，先看项目内 `node scripts/dev.mjs --help`；仅使用它实际支持的语法。模块/数据库列表等能力需要管理 CLI。需要安装时使用 `npm install -g @mjh-odoo/cli`。
+
+## 根据任务读取
+
+| 任务 | 读取与操作 |
+| --- | --- |
+| 查看状态、启动、应用配置、模块安装升级 | [开发操作](references/development.md) |
+| 查日志、定位维护失败 | [日志排查](references/logs.md) |
+| 数据库 ZIP 保存、恢复、选择目标库 | [数据库存档](references/database.md) |
+| 镜像构建或离线包 | `odoo image build --help`，并读取目标项目的构建发布说明 |
+
+## 操作约束与交付
+
+- 查看配置用 `odoo config`，输出已脱敏。需要判断本机密码是否配置时只在本机读取必要字段，不把整份 `.env` 或真实密码写进日志、提交、PR 或任务记录。
+- 只读排查先用 `status`、`config` 和有限日志；不要为读取日志自动启动服务或重建镜像。缺少 `.env` 时说明尚未初始化，按任务需要处理。项目内兼容脚本的读取副作用可能不同，调用前检查已有配置与帮助。
+- `down` 保留数据卷；仅当用户已明确要求删除该项目数据时使用 `-v/--volumes`。已有目标库的覆盖只在用户明确要求时带 `--force`；沿用已有授权，不重复索要确认。
+- 安装/升级和恢复会停止该项目的 Odoo。失败时保留停止状态与维护输出，修复后再启动，不把普通服务日志当成一次性维护容器的完整记录。
+- 数据库存档是 Odoo 原生 ZIP，代码和模块由项目 Git 独立维护；回退代码不会撤销数据库升级。
+- 一次操作完成后报告目标项目/数据库、实际结果及未验证内容。查询为空只代表查询范围没有结果；执行成功不等于业务验收通过。

package/.agents/skills/odoo-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Odoo CLI"
+  short_description: "使用 odoo 命令管理开发环境、模块、日志与数据库 ZIP 存档"
+  default_prompt: "使用 $odoo-cli 管理当前 Odoo 项目，按任务检查配置、运行状态与目标数据库。"

package/.agents/skills/odoo-cli/references/database.md

@@ -0,0 +1,43 @@
+# 数据库与 Odoo ZIP
+
+先用 `odoo config` 核对当前工作树，`odoo db list --json` 查库名、当前库和恢复来源。项目存档由 Odoo Manager 保存，各工作树通过同一 Git 仓库识别项目。
+
+## 保存与发布
+
+```sh
+odoo archive save "销售验收版" -d odoo --tag latest
+odoo archive import /path/to/source.zip
+odoo archive list --json
+odoo archive tag set latest <存档ID>
+odoo archive tag list
+```
+
+保存需要运行中的 Odoo，导入通过目标项目的 Odoo 运行镜像校验 ZIP。默认保存只生成存档。需要同时更新标签时传 `--tag`，保存成功后才移动标签。导入后可用 `archive tag set` 更新标签。可把标签指回旧 ID。只有单独交付文件时才使用 `odoo db backup --file /path/to/backup.zip`。备份包含数据库和 filestore，保留原生 Odoo ZIP。
+
+## 恢复与切换
+
+```sh
+odoo db restore latest --to sales_review
+odoo db use sales_review
+odoo db restore id:<存档ID> --to sales_copy --use
+```
+
+标签在命令执行时解析，恢复记录实际 ID。恢复默认中和外发任务，切换失败恢复原数据库配置。保留旧库以便回退。用 `--file <路径>` 恢复未导入的 Odoo ZIP，只有用户明确指定要覆盖目标库才使用 `--force`。验收需要核对记录、模块状态和真实附件内容。
+
+`ODOO_SEED=tag:latest` 或 `id:<存档ID>` 搭配 `ODOO_SEED_MODE=first-start`，使 `odoo up` 在新开发环境空库时加载对应版本。用 `manual` 手动恢复。现有工作树的数据由该环境自己维护。
+
+删除 ZIP 用 `odoo archive delete <存档ID> --yes`，带标签的存档须先移动或移除标签。删除环境中的数据库及附件用 `odoo db delete <数据库> --yes`，先切走当前库。分别核对目标并确认用户已授权该次删除。
+
+## 恢复失败与迁移
+
+恢复失败先查任务输出的校验、恢复、验证或切换阶段。普通恢复会清理本次新建的库。若仍有「恢复未完成」记录，确认目标环境后用 `odoo db recover --yes` 清理再重试，禁止将该库切为当前库。
+
+```sh
+odoo archive seed tag:latest
+odoo archive source
+odoo archive library export /path/to/new-library-directory
+odoo archive library import /path/to/library-directory
+odoo worktree archived
+```
+
+项目级来源用于新工作树。工作树内显式的 `ODOO_SEED_MODE=first-start` 和 `ODOO_SEED` 优先，`ODOO_SEED_MODE=empty` 可选空库。存档库目录包含原生 ZIP 与索引，带走 ID、标签和备注。导入保留本机已有的同名标签。清理已归档工作树卷使用 `odoo worktree clean <Compose标识> --yes`，先核对工作树和卷并取得用户授权。

package/.agents/skills/odoo-cli/references/development.md

@@ -0,0 +1,37 @@
+# 环境与模块
+
+## 常用入口
+
+```sh
+odoo init
+odoo config
+odoo doctor --json
+odoo status --json
+odoo up --no-build --wait-timeout 600
+odoo down
+```
+
+`init` 只准备本机配置。`up` 默认构建镜像，再启动并等待健康；已有镜像用 `--no-build`，完全离线还可指定 `--pull never`。等待超时不表示数据库可丢弃，应查看实际状态和日志。
+
+首次初始化按代码目录分配项目身份和宿主端口，形成独立数据卷。支持模板密码规则的版本保留三个非空模板密码，空项才生成。已有 `.env` 始终保留。管理员初始密码只用于空库；改配置不会重置已有后台账号或 PostgreSQL 角色。
+
+修改 `.env` 后用 `odoo up --no-build` 重建服务配置；只变更配置模板或镜像依赖时需要重新构建。`restart` 默认处理 Odoo，先重启选定服务，再执行 `up --no-build --wait` 确保服务就绪；`restart all` 包含当前项目的数据库。其他项目不在 all 的范围内。配置修改仍建议明确执行 `up`。
+
+## 模块安装与升级
+
+```sh
+odoo module list --json
+odoo module install first_module second_module
+odoo module update first_module second_module -d target_db
+odoo module update first_module --no-restart
+```
+
+模块名用空格分隔。`-d/--database` 覆盖本次维护目标，不修改项目的 `PGDATABASE`。安装用于未安装模块，升级用于已安装模块；Python 热重载不代替字段、视图和数据结构的升级。
+
+无模块名时 `module update` 会拒绝执行，只有显式 `--all` 才升级已安装的项目扩展；它不代表升级整个官方核心。维护会确保数据库运行、停止 Web、使用一次性容器执行，成功后按选项启动。失败先保存本次命令的错误输出。
+
+## 镜像
+
+先用 `odoo image build --dry-run` 看本机基础镜像计划。完整项目镜像需要 `--target production --tag <项目:版本>`。单架构离线包使用 `--platform amd64 --file /path/to/image.tar`，服务器用 Docker load 导入。
+
+多架构推送需要已支持相应架构的 Buildx 构建器以及显式 `--push --tag`；发布目标和权限沿用当前用户授权，不从本地构建任务推导为上传任务。

package/.agents/skills/odoo-cli/references/logs.md

@@ -0,0 +1,14 @@
+# 日志排查
+
+先在复现窗口查询错误。CLI 0.1.2 起可用 `--hide-health` 去掉成功的健康检查，失败请求仍可查到。
+
+```sh
+odoo logs all --since 10m --tail 1000 --level error --context 3 --hide-health --json
+odoo logs all --since 2026-11-03T09:25:30+08:00 --until 2026-11-03T09:26:30+08:00 --tail 1000 --hide-health --json
+```
+
+`matched` 是命中数，`shown` 包括命中和相邻事件，`context=true` 标记相邻事件。找到可疑错误后，用其时间戳限定前后 30 秒，查看完整堆栈和其他服务。日志先按容器行数取样再筛选，`tailReached=true` 时可扩大行数或缩小时间窗。
+
+需要现场复现时再用 `odoo logs -f`；Ctrl+C 只结束查看。筛选、JSON 和文件选项不能与 follow 混用。导出可用 `--file .local/logs/debug.json`，拒绝覆盖已有文件，内容中的业务数据仍需按任务处理。
+
+安装、升级或恢复使用的临时维护容器可能已经被移除；优先保留失败命令的输出。当前服务日志不能补回该容器的全部错误。不要因日志中只有 health 200 就判断模块已正确安装或业务正常。

package/COPYRIGHT

@@ -0,0 +1,3 @@
+Copyright (C) 2026 MaJianhang.
+
+The management helpers were extracted from the locally maintained Odoo Community base (commit c901e640). This CLI package does not contain Odoo server source, project configuration, database contents or attachments.