tuanle96/odoo-ai-skills

# odoo-ai-skills [](https://github.com/tuanle96/odoo-ai-skills/actions/workflows/ci.yml) [](https://github.com/tuanle96/odoo-ai-skills/actions/workflows/tests.yml) [](https://github.com/tuanle96/odoo-ai-skills/actions/workflows/integration.yml) [](https://www.odoo.com) [](#license) [](https://skills.sh/tuanle96/odoo-ai-skills) **odoo-ai-skills 为 [Claude Code](https://docs.claude.com/en/docs/claude-code) / Codex 提供快速的本地 Odoo 实例真实情况与 CI 绑定的证据门禁，从而确保 AI 编写的 Odoo 17–19 代码变更在 PR、UAT 或发布前经过检查、runtime 验证并生成报告。** 它是 **AI 编写的 Odoo 变更的本地优先验证与部署门禁**。引入任何编程 agent、任何托管知识索引、任何 `grep` —— 它们提出名称和模式；而本套件决定该补丁是否*真的对该客户的实例安全*：真实的字段、真实的 MRO、真实的安全机制、真实的 runtime、真实的升级路径。**无需 SaaS，无需席位，无需 API key，元数据绝不离开你的设备。** 🌐 **着陆页：[tuanle96.github.io/odoo-ai-skills](https://tuanle96.github.io/odoo-ai-skills/)** Odoo 在 **runtime** 根据已安装的 addon 依赖图组合每一个模型、视图、安全规则和自动化。字段名称、方法解析顺序、`super()` 链、渲染的视图 arch、记录规则——这些都无法仅凭记忆或 `grep` 可靠地获知。它们只存在于**运行中的实例**里。靠猜测是导致 AI 编写的 Odoo 代码看起来正确、admin 在单条记录上运行也没问题，但对真实用户、在第二个公司、在批处理中或在下一次升级时崩溃的最大原因。 **因此，本套件中的每一项技能都围绕一条规则展开：**  查看完整的 [实战示例](examples/sale-order-walkthrough.md) —— 一个真实的 `sale.order` 变更经历了 introspect → patch → test，并且其模块在 CI 中进行了测试。 ## 为什么会有这个项目 仅凭记忆的话，LLM 会捏造 Odoo 的字段和模型名称，去使用那些已被移除的 API（`attrs`/`states`, ``, `name_get`），在错误的 MRO 层调用 `super()`，为了屏蔽权限错误而滥用 `sudo()`，并且发布了带有不完整 `@api.depends` 的存储计算字段。这些在 **runtime 默默地失败**，而不是在 lint 时——这恰恰是过度自信最危险的地方。本套件通过让 agent 在编写代码前阅读实时的 registry，并编码通用模型所不知道的 Odoo 专属契约（安全、MRO、manifest 配置、版本差异），从而填补了这一空白。 ## 不是托管的知识索引 —— 而是 runtime 验证门禁 托管的 Odoo *知识索引*（一种跨版本预索引 Odoo 源码的云服务）在**广度**方面非常出色：“标准的 `sale.order` 从 v8→19 是什么样的？给我看不同仓库的例子。”如果你愿意，把它当作**上游来源**来使用是个不错的选择。 但是，静态索引在结构上**无法知道在你的实例中什么是真实的**：安装了哪些模块、Studio/OCA/本地补丁对最终的 registry 做了什么更改、该组/公司有效的视图 arch、每个用户/每个公司的安全性、runtime 行为、开发↔生产差异，或者升级是否会保留真实数据。这些恰恰就是那些通过了代码审查却在生产环境中出问题的故障（参见[高风险 playbook](docs/high-risk-playbooks.md)）。 `odoo-ai-skills` 是另一半：它读取**这个运行中的实例**并将提议的变更转化为证据——然后对合并进行门禁拦截。界限很明确：**静态索引只负责建议；而由运行中的实例来决定。** - **本地优先 / 主权。** 所有操作都在你的 shell 中运行。无需账户、无需 API key、无需按席位付费；敏感的实例数据（这就是存在 [`redact`](#the-gate) 的原因）绝对不会离开你的环境。 - **基于实例，而非基于记忆。** 实例*就是*这里所安装内容的索引——无需进行针对每个版本的重复索引工作。 - **验证与强制执行，而不仅仅是查找。** [The Gate](#the-gate) 检查部署：场景测试、环境差异、验证、脱敏、迁移风险，以及 `approve / needs-human / block`（批准 / 需要人工 / 拦截）的裁定。 还想要生态系统的广度？将外部索引的建议作为*声明*输入——`odoo-ai-skills` 会针对实时实例验证每一项，而不是盲目相信（参见 `verify-claims`）。套件自带的 `docs` 查询只是这样一个上游来源，它是本地构建且经过存在性校验的。 ## 快速安装（适用于任何兼容 skills 的 agent） ``` npx skills add tuanle96/odoo-ai-skills ``` 一条命令即可为 Claude Code、Codex、Gemini CLI、GitHub Copilot 以及其他兼容 [Agent Skills](https://skills.sh) 的 agent 安装本套件 （随每个 skill 附带捆绑的 `scripts/`）。要获取完整的 Claude Code 体验 —— 命名空间 router、marketplace 更新 —— 请使用下方的插件 安装方法。 ## 作为 Claude Code 插件安装 本仓库是一个 Claude Code 插件（包含一个 `.claude-plugin/plugin.json` 清单以及 `skills/` 目录）**同时也是**其自己的 marketplace（`.claude-plugin/marketplace.json`）。通过两条命令进行安装： ``` claude plugin marketplace add tuanle96/odoo-ai-skills # register the marketplace claude plugin install odoo-ai-skills@odoo-ai # install the plugin ``` 这 25 个 skill 随后将以命名空间方式加载 —— `/odoo-ai-skills:odoo`（router）、`/odoo-ai-skills:odoo-introspect` 等。以后可以使用 `claude plugin update odoo-ai-skills@odoo-ai` 进行更新。 若想在安装前进行尝试，可直接从本地克隆加载： ``` claude --plugin-dir /path/to/odoo-ai-skills # then /plugin to browse claude plugin validate /path/to/odoo-ai-skills # check the manifest ``` **安装后运行内置的 `odoo-ai` CLI。** 插件会被复制到 Claude 的缓存中，因此请通过 plugin-root 变量而不是相对路径来引用 CLI： ``` "${CLAUDE_PLUGIN_ROOT}"/skills/odoo-introspect/scripts/odoo-ai --db all sale.order ``` （在克隆目录中工作时，如其他地方所示使用 `scripts/odoo-ai` 是没问题的。） ## 作为 Codex 插件安装 本仓库还提供了一个原生的 Codex 适配器（`.codex-plugin/plugin.json`）以及一个 Codex marketplace（`.agents/plugins/marketplace.json`）。从本地 克隆进行安装： ``` codex plugin marketplace add /path/to/odoo-ai-skills codex plugin add odoo-ai-skills@odoo-ai ``` 相同的 `skills/` 目录会被 Codex 复用，并且内置的 CLI 仍然位于： ``` skills/odoo-introspect/scripts/odoo-ai --db all sale.order ``` ## 如何使用 - **刚接触某项任务？** 调用 **`odoo`** skill —— 它会为你路由到正确的子 skill。 - **刚接触该实例 —— 不知道从哪里开始？** `odoo-ai surface` 会对实时的入口点（按钮、cron、自动化、路由）进行排名，这样你就无需盲目猜测入口方法；接着 `odoo-ai esg` 会对真实的跨应用流程进行采样。 - **准备 *添加* 字段/模型/向导/报表/cron/自动化（或覆盖核心流程）？** 首先调用 **`odoo-capabilities`** —— `odoo-ai native-check "<需求>"`（匹配精选卡片，并针对实例进行存在性校验）或者使用 `odoo-ai capabilities ` 查看完整的表面 —— 以便在重新造轮子之前检查 Odoo 已经自带了哪些功能。最好的补丁有时就是不打补丁。 - **准备编写代码？** 首先调用 **`odoo-introspect`** 以 JSON 格式 dump 出模型/流程（`odoo-ai all `），然后使用相关的构建 skill，接着使用 **`odoo-testing`**，最后在合并前使用 **`odoo-review`**。 - **遇到“未生效”的情况？** 在怀疑是代码 bug 之前，先执行 `odoo-ai preflight `。 - **准备重命名/删除字段？** 首先执行 `odoo-ai refs ` 查看所有依赖于它的内容。 ## 环境要求 - **Odoo 17 / 18**（最低版本限制），一直到 **Odoo 19**（当前的 LTS 版本，于 2025 年 9 月发布）。针对 v16 的差异以及 v18.1 → 19 的 API 变更（`check_access`/`has_access`、`@api.private`、`type='jsonrpc'`、`_read_group`/`formatted_read_group`、`aggregator`、`record.env.*`、`odoo.Domain`）在每个 skill 和 `skills/odoo-introspect/references/version-matrix.md` 中均有标注。 - 进行 introspection 时：需要具有 shell 访问权限，以便针对开发/暂存数据库运行 `odoo-bin shell`（自托管或 odoo.sh 分支），或者对于 Odoo Online/SaaS 使用 RPC 回退方案 —— 参见 `skills/odoo-introspect/references/introspection.md`。 - 可选：[`tuanle96/mcp-odoo`](https://github.com/tuanle96/mcp-odoo) MCP server，可将 introspection 暴露为 agent 工具 —— 它还附带了一个包含 4 个仅限凭据的**业务工作流技能**（数据质量门禁、迁移助手、月末结账、代理机构全集群审查）的伙伴包：`npx skills add tuanle96/mcp-odoo`。 ## Odoo 托管的现实情况 你的 Odoo 运行在哪里决定了本套件能做什么： - **自托管 & Odoo.sh** —— 全功能。你拥有 shell / SSH / CI 权限，因此代码路径可以端到端运行：**检查**实时 registry，在 runtime **验证**变更，并在合并、UAT 或发布前强制执行 **CI 绑定的证据门禁**。 - **Odoo Online (SaaS)** —— **仅供参考。** Odoo Online *不允许使用自定义代码*，因此在那里没有什么代码可以验证。目前可通过 RPC 使用：生成的**终端用户指南**（`odoo-user-guide`）。在 **v0.15 路线图**中（针对基于 shell 工具的纯 RPC 模式）：**实例档案**、**配置审计**以及**适配差距**分析 —— 这些目前需要 `odoo-bin shell`，因此在 Online 平台上它们必须等待 RPC 回退方案的实现。 代码门禁针对的是代码可以实际运行的环境（自托管、Odoo.sh）。它绝不会声称能在 Odoo Online 上验证自定义代码。 ## 技能列表 ### 第 0 层 —— 基础（ground-truth 引擎） | Skill | 功能描述 | |-------|--------------| | **odoo-capabilities** | **第 0 步** —— 在重新发明平台行为之前，先了解 Odoo 已经自带了什么。`odoo-ai native-check "<需求>"`（原生能力检查，先门禁后排名）会通过召回匹配约 34 张精选能力卡片（TF-IDF + 意图短语），然后针对实时实例对每张卡片进行**存在性校验**，并返回带有引用证据的候选项；`odoo-ai capabilities ` / `--module ` 会映射出完整的原生表面（向导、动作、cron、自动化、序列、mixins、字段），并以 xmlids 作为证据。`odoo-ai native-learn "<短语>" --card ` 可以对其进行映射教学，从而通过使用提高召回率。仅针对*新增* / 核心覆盖任务触发。 | | **odoo-introspect** | 其他所有 skill 首先调用的引擎。提供 JSON 格式的事实 —— 字段+MRO+super+安全机制 · 视图/按钮 · 菜单/数据/报表 · 真实的 runtime 追踪（包含 SQL 热点 / 写入映射 / 异常摘要） · **每个用户/公司有效的安全规则** —— 外加专注的扫描器：**refs**（反向字段影响，图谱解析的点分路径）、**preflight**（它到底加载了没有？），以及 **state_capture**（断点处的 runtime 值 + 异常事后分析）—— 以及 `odoo-ai` CLI。同时承载了 **The Gate** —— 强制执行套件（场景测试 · 环境对等 · 静态验证器 · 脱敏 · 升级测试套件 · 部署门禁 · 证据包 · BYO-index `verify-claims`）。 | | **odoo-docs | **检查：文档查询** —— 本地开发者文档索引。构建一次官方 Odoo 文档的 TF-IDF 索引（`odoo-ai docs-build --version 18`），然后 `odoo-ai docs "<问题>"` 返回排名靠前的段落 + 权威的 odoo.com URL。从属于 introspection（文档负责*提议*，实例负责*决定*）；在本地构建，绝不通过外部引入（纯净的 CC-BY-SA）。 | ### 第 1 层 —— 核心循环 | Skill | 功能描述 | |-------|--------------| | **odoo-dev** | 安全地进行定制：字段、覆盖、继承模式、正确的 hook、MRO 层。 | | **odoo-module-scaffold** | 新模块骨架 + 正确的 `__manifest__.py`（包含规范的 `external_dependencies`）。 | | **odoo-views** | 视图 XML（form/list/kanban/search）+ 继承/xpath；以及 v17/18 移除 `attrs` 和 ``/`` 的相关变更。 | | **odoo-security** | ACL、记录规则、用户组、多公司 —— 编写规则 + 真实的求值顺序。 | | **odoo-testing** | 测试门禁：`at_install`/`post_install`、非 admin、多公司、批处理、`-i`/`-u`。承载了 **CI 绑定的证据门禁** —— CI 生成的、HMAC 签名的证明（差异目标、变更行覆盖率、runtime 路径绑定、场景满足度、测试质量 lint、变异冒烟测试、红/绿重放），使得“高覆盖率但 runtime 崩溃”成为一个 **block**（拦截），而不是绿色的对勾。人工审查对于敏感领域仍然是强制性的 —— 它强化了信任边界，但并未将其移除。 | | **odoo-review** | 审查门禁：在合并前捕获 AI 发布的安全 / 数据丢失 / 默默牺牲正确性 / 性能等缺陷。 | | **odoo-debug** | 症状→工具表、traceback 解码器、`--dev`、runtime 追踪 + **runtime 状态捕获 / 异常事后分析**和 **debugpy/DAP** 单步调试，以及“我的修改没生效”的 preflight。 | ### 第 2 层 —— 前端与报表 | Skill | 功能描述 | |-------|--------------| | **odoo-owl** | OWL 2 **后端** Web 客户端：组件、自定义字段小部件、patching、服务、静态资源。 | | **odoo-web** | **公共** Web：HTTP 控制器（`http.route`）、网站页面、portal `/my`，以及 `publicWidget`→Interactions 的转变。 | | **odoo-reports** | QWeb PDF/HTML 报表：动作、模板、`_get_report_values`、页面格式。 | | **odoo-statutory-reports** | 通过 `account.report` 引擎实现的动态财务报表：行/表达式模型、引擎（domain/aggregation/custom handler）、`date_scope` 语义、`_report_custom_engine_*` 契约、**自我验证的法定设计**（兜底项 = 0、余额等式、对账行）、制度版本控制、xlsxwriter data-pack 逃生舱。 | | **odoo-valuation-repair** | 损坏的库存估值诊断与修复：`Σ SVL quantity = valued physical stock` 不变量、RCA 查询阶梯（中途启动的估值、配置翻转考古、`lot_valuated` 下的单批次差异）、一个**失败即拒绝的单批次修复 runbook**（DRY-RUN 服务器动作、SaaS 安全、剩余数量清理、无双重层的存储成本同步），以及能够捕获那些 `cost <= 0` 警报永远发现不了的“数值为正但实际错误”成本的每日偏移检查。 | ### 第 3 层 —— 生命周期 | Skill | 功能描述 | |-------|--------------| | **odoo-data** | 数据/demo、`noupdate`、序列、配置参数。 | | **odoo-migration** | 版本升级与迁移脚本（`migrations//`），重命名前的反向影响分析。 | | **odoo-upgrade** | **一切**内容的跨版本迁移 (18→19)：基于真实源码差异**生成**破坏性变更清单、带有文件:行号发现的各模块语义简报、在实时目标容器上进行 runtime 验证循环（`module_not_loaded` 防止静默跳过的假通过）、全集群编排器（`migrate_all.py`：在整个 addons 树上按拓扑移植顺序进行 S/M/L 工作量划分），以及全数据库演练测试套件（`db_upgrade.py`：恢复 → OpenUpgrade → 检查，结构化裁定）。优先编排官方的 `upgrade_code` + OCA `odoo-module-migrate`；数据迁移移交至 `odoo-migration`。 | | **odoo-perf** | 记录集规范、预取/缓存、存储计算成本、索引。 | | **odoo-worktree** | 在实时的开发环境中进行隔离的功能开发：当容器运行主树未提交的文件时，从生产环境切出一个 git worktree 分支；路径范围的同步（`rsync`/`git restore --source`）、幂等的 hook adopt-vs-create 打包，以及强制性的全新安装测试流程。 | | **odoo-deploy** | `odoo.conf`、workers、Docker、CI 测试运行 —— 外加 **odoo.sh**（git-push 部署、暂存排练）以及 Odoo Online 的限制。 | ### 第 4 层 —— 领域 playbook | Skill | 功能描述 | |-------|--------------| | **odoo-domain-playbooks** | 各应用映射（sale/stock/account/mrp/purchase/hr）：关键模型、需进行 introspect 的方法、正确的 hook、陷阱 —— 外加国家/制度 playbook（越南会计：VAS、TT200→TT99 2026、电子发票/税务日历）。 | ### 报告输出 | Skill | 功能描述 | |-------|--------------| | **html-report** | 将任何审计 / 审查 / 分析 / RCA / 摘要渲染为**风格一致、自包含的 HTML 页面** —— 共享加粗的“杂志”主题，CSS 内联（无需 CDN，无需服务器），自动打开。仅用于展示；*不是* Odoo QWeb 商业单据（那是 `odoo-reports`）。 | | **odoo-user-guide** | 从运行中的实例生成关于某项流程的**终端用户操作指南**：使用 `odoo-ai`（入口点发现 + 每个角色的有效安全规则）为步骤奠定基础，在**沙箱**数据库上使用 Playwright 驱动真实的 UI，对每一步进行截图，**在后端断言最终的结果状态**（证明），然后渲染一个自包含的带注释 HTML 指南。以 manifest 为中心且可重复运行；仅限演示数据库，在生产数据变更时强制失败。语音/MP4 在路线图中。 | ### Router | Skill | 功能描述 | |-------|--------------| | **odoo** | 入口点：任务 → skill 决策表。 | ## Introspection 引擎 (`odoo-ai`) 一条命令即可在编写任何代码之前为 agent 收集 ground truth： ``` # everything (fields + views + data) for a model: scripts/odoo-ai --db all sale.order --methods action_confirm,write,create # add the real runtime trace: scripts/odoo-ai --db all sale.order --methods action_confirm \ --record-id 42 --method action_confirm # focused scanners: scripts/odoo-ai --db refs sale.order commitment_date --resolve-paths # who breaks if I change this field scripts/odoo-ai --db preflight my_module # installed? loaded from where? shadowed? scripts/odoo-ai --db security sale.order --user 7 # effective ACL + record rules + restricted fields # runtime values — the JSON analog of an IDE's "inspect variables": scripts/odoo-ai --db state sale.order 42 action_confirm \ --break sale.order._action_confirm --fields state,amount_total # args/locals/self at the breakpoint scripts/odoo-ai --db state sale.order 42 action_confirm --on-exception # full stack + locals if it raises ``` 有关每一层的 JSON 结构和 SaaS RPC 回退方案，请参见 `skills/odoo-introspect/`。 ## The Gate（门禁） 阅读 ground truth 可以阻止 agent *盲目猜测*；但这并不能*证明*变更是安全的。**The Gate** 将这些证据转化为强制执行的检查 —— 现实的目标是 **agent 编写、工具验证、人工批准**，而不是盲目的自动化部署。其中有四项是**纯净且本地的**（不需要 `odoo-bin shell`，也不需要数据库 —— 它们在 CI 或笔记本电脑上运行）： ``` # turn introspection into the MANDATORY tests for this change (risk-tiered): scripts/odoo-ai --db scenarios sale.order --methods action_confirm # → required scenarios + a TransactionCase skeleton # don't claim production safety against a divergent env: scripts/odoo-ai --db dev env-fingerprint # capture each side, then: scripts/odoo-ai env-diff dev.json prod.json # LOCAL — modules/edition/studio/config drift # the odoo-review checklist, as an executable linter (LOCAL, no DB): scripts/odoo-ai validate addons/my_module # attrs/sudo/N+1/batch/version anti-patterns # make introspection JSON safe to share with an external LLM (LOCAL): scripts/odoo-ai redact /tmp/odoo-ai/sale_order.state.json # strip source/locals, mask PII, redact secrets scripts/odoo-ai scan-secrets path/to/file # secret/key scan before it leaves the box # upgrade safety: a RENAME (keep data) vs a DROP (lose it), + a pre-migrate scaffold: scripts/odoo-ai --db upgrade-check sale.order --against old_brief.json scripts/odoo-ai upgrade-diff old_brief.json new_brief.json # LOCAL # aggregate all the evidence into a go/no-go for high-risk modules (LOCAL): scripts/odoo-ai deploy-gate /tmp/odoo-ai/evidence_bundle/ # → approve | needs-human | block ``` 这些源于 v0.7 代码库评估（位于 `plans/reports/` 下），该评估发现本套件在*基础事实收集*方面表现出色，但在*强制执行*方面仅能作为建议。每个门禁的纯逻辑都在没有 Odoo 的情况下进行了单元测试。 ## 发现、采样、测量与强制执行 上述步骤都假定你已经知道要 introspect *什么*。入口点发现回答了冷启动问题 —— *在这个实例中，真实情况从哪里开始？* —— 并让这些工具变得不可跳过： ``` # DISCOVER where to start — rank the live entrypoint surface (buttons, server # actions, crons, automations, reports, HTTP routes), instance-wide or scoped: scripts/odoo-ai --db surface # → ranked roots + top_trace_seeds scripts/odoo-ai --db surface sale.order # ...around one model # UNDERSTAND the overall process — sample the top entrypoints' real traces and # merge them into a cross-model / cross-app flow skeleton (NOT a static map): scripts/odoo-ai --db esg sale.order # → Execution Surface Graph # MEASURE that hallucinations actually drop — score the gate on a benchmark of the # classic LLM Odoo mistakes (account.invoice, customer_id, fields_view_get, …): scripts/odoo-ai --db eval # → detection_rate / truth_recall # ENFORCE no-introspect-no-edit (LOCAL) — block an edit until its model is read: scripts/odoo-ai gate-edit addons/my_module/models/sale_order.py ``` 将 `gate-edit` 配置为 Claude Code 的 **PreToolUse hook**（`skills/odoo-introspect/references/enforcement-hooks.md`），这样 agent 在阅读其 ground truth 之前就*无法*编辑 Odoo 模型 —— Oracle 提出的“即使是完美的工具 ≠ 被使用的工具”失败模式，就此闭环。`surface`/`esg` 始终忠于 *基于 runtime，绝不依赖记忆* 的原则：对流程的理解**源自采样的追踪记录**，绝非来自陈旧、固定的图集。（设计原理：参见 `plans/reports/` 下的代码库分析。） ## v0.14 中的新功能 —— 快速上下文、Instance Dossier 以及面向客户的证据工件 随着模型能力的提升，它们编写看似合理但错误的代码的*速度也更快*了，因此杠杆的作用点从**捕获**糟糕的补丁转移到了**在 agent 编写代码之前为其输入实例事实** —— 并且从一个绿色的对勾转变为审查者、合作伙伴负责人和客户都能看懂的证据工件。v0.14 在这两方面都进行了增加，并加入了面向顾问的界面： ``` # FAST CONTEXT — small, per-model instance facts to feed the agent BEFORE it edits scripts/odoo-ai --db facts sale.order --kind security # model | security | views | flows scripts/odoo-ai --db mcp # ...same facts as a bounded read-only MCP server # INSTANCE DOSSIER — one read-only command: the takeover / pre-sales inventory scripts/odoo-ai --db dossier # modules, Studio, custom fields, security, scripts/odoo-ai dossier-report /tmp/odoo-ai/dossier/dossier.dossier.json # data volumes → upgrade-risk flags → HTML # VALID TEST DATA — business-record fixtures agents keep getting wrong scripts/odoo-ai --db fixture sale_order_stockable # paste-ready TransactionCase skeleton scripts/odoo-ai --db fixture sale_order_stockable --exec # ...or run it in a savepoint + roll back # FIT-GAP (alpha) — classify requirements vs the live instance (decision support, not a consultant) scripts/odoo-ai --db fit-gap --requirements-file reqs.json --domains sale,stock,account # UAT PACK (alpha) — role-based UAT scripts from the live surface + risk scenarios scripts/odoo-ai uat-pack --surface surface.json --scenarios scenarios.json --html # THE EVIDENCE ARTIFACT — the stable, public, client-facing proof (build + validate) scripts/odoo-ai evidence-artifact build --out evidence.json scripts/odoo-ai evidence-artifact validate evidence.json ``` **快照缓存**（`cache`）通过一条硬性规则让温暖的上下文在 agent 循环中保持快速访问 —— **热缓存永远不能批准合并；只有冷运行（全新运行）才有资格进行合并**，并且来源信息伴随着每一个 payload。**The Gate** 现在会将每一个发现分类为 **S0–S4**，并支持可选的 **fail-closed**（失败即拒绝）策略（`deploy-gate --policy …`）：**S3/S4** 级别的发现（无声的数据损坏、ACL 绕过、多公司数据泄漏）会**拦截**合并，除非有 `human_signoff.json` 对其进行降级 —— 绝不会默默地将其置为 *approve*（批准）。复合的 **GitHub Action**（`.github/actions/odoo-gate`）、持久的 **PR 评论** 以及 GitLab 方案让它在 CI 中变为现实（[`docs/ci-integration.md`](docs/ci-integration.md)、[`docs/evidence-artifact.md`](docs/evidence-artifact.md)）。此外，[**Odoo Agent Safety Bench v0**](bench/) 是一个公开、可复现的基准测试，其衡量标准是**不安全变更逃脱率** —— 即不安全变更有多少次未被检测到就到达了 PR/UAT/发布环节 —— *而不是*任务完成率；包含十个严重性加权任务、四种运行模式、一个不断成长的对抗性语料库，并且在设计上**没有单一的主打分数**。 ## 针对真实的 Odoo 进行了测试 除了单元测试套件外，集成冒烟测试还会在 CI 中（`.github/workflows/integration.yml`）**针对实时的 Odoo 17 / 18 / 19 运行每一个检查阶段和门禁** —— 包括入口点发现（`surface`/`esg`/`eval`）：**在 17、18 和 19 版本上均通过了 89/89 项检查**，可以通过 `docker-compose.e2e.yml`（Postgres + 三个 Odoo 版本）在本地用一条命令复现。`eval` 测试套件在所有三个版本上的得分为 **detection_rate 1.0 / truth_recall 1.0**（捕获了每一个典型的幻觉，确认了每一项真实情况）。本套件还针对真实的 **390 模块 Enterprise** 实例（Studio 字段、自定义 addon、多公司）进行了端到端的验证：所有只读检查（字段、MRO、安全、原生能力）、强制执行门禁、BYO-index 的 `verify-claims`（它正确地标记了一个关于该实例中*缺失*模块的外部声明），以及写入/执行层 —— 对 `sale.order.action_confirm` 的 runtime `trace` 捕获了真实的跨应用级联（`stock.picking` / `stock.move` / `quality.check`）并进行了回滚。静态索引无法捕获的那些故障记录在 `docs/high-risk-playbooks.md` 中。 ## 安全 —— 处理 introspection 输出 introspection 阶段会 dump 真实的实例数据。**`state` 捕获会返回 runtime 参数、局部变量以及 `self` 的字段值，并且模型简报上的 `SOURCE=1` 会包含完整的方法主体。** 此输出可能包含密钥、token、API key、密码、客户 PII 或专有业务逻辑。 - **`state` 默认会对常见的敏感键名进行脱敏** —— 名称类似于 `password`、`token、`secret`、`api_key`、`authorization`、`session` 等的局部变量/字典键/字段都会变成 ``。可以通过 `--redact-extra ssn,iban` 进行扩展；仅在受信任的开发机器上使用 `--no-redact` 禁用。脱敏是基于键名的，因此它无法捕获存储在普通名称下的密钥。 - **方法主体源码和字段值不做脱敏处理** —— `SOURCE=1` 和 `--fields` 仍然可能会暴露敏感内容。**在未经审查和脱敏的情况下，请勿将原始的 `state` / 源码 JSON 粘贴到外部 LLM 或公开的 issue 中。** - 在实际可行的情况下，请针对**开发/暂存**数据库而不是生产环境运行 introspection。 - 像对待调试器会话一样对待这些 JSON：对循环中的 agent 很有用，但不适合随意传播。 ## 目录结构 ``` .claude-plugin/plugin.json # plugin manifest .claude-plugin/marketplace.json # self-hosted marketplace (install source) skills//SKILL.md # one skill per directory skills//references/ # progressive-disclosure deep dives skills/odoo-introspect/scripts/ # the introspection engine + odoo-ai CLI ``` ## 开发 introspection 脚本是导入安全的（import-safe）：依赖于环境的工作只在 `odoo-bin shell` 内部运行，而纯辅助函数则在无 Odoo 环境下进行了单元测试。 ``` python -m unittest discover -s tests -p "test_*.py" # gate + tool suite (no Odoo, no pytest) python -m pytest skills/odoo-introspect/scripts/tests -q # pure-function tests python skills/odoo-introspect/scripts/tests/test_pure_functions.py # no-pytest fallback ``` CI（`.github/workflows/`）会在每次 push 时编译所有脚本并运行两个测试套件。 **集成冒烟测试（需要真实的 Odoo）。** `scripts/tests/integration_smoke.py` 会针对实时实例运行检查阶段并对 JSON 结果进行断言（选择字面量、manifest 的 `by_location` 拆分、视图的 `inheritance_chain`、种子化的 `noupdate`、`state` 脱敏）。它是可选的 —— 除非设置了 `ODOO_DB`，否则将被跳过 —— 因此它绝不会破坏单元测试 CI。针对开发容器运行它，或者让 `.github/workflows/integration.yml` 在官方 `odoo:17.0` / `18.0` / `19.0` 镜像上运行它（其中包含一个专门的任务，在 `odoo:18.0` 上运行 `sale_confirm_guard` 的完整实战示例）。有关容器包装器和确切的调用方式，请参见 `skills/odoo-introspect/references/introspection.md`。 ## 贡献与安全 - 贡献：参见 `CONTRIBUTING.md`（项目布局、导入安全的脚本模式、运行单元 + 集成测试）。 - 变更记录在 `CHANGELOG.md` 中。 - 安全地处理 introspection 输出（脱敏、不应共享的内容）：参见 `SECURITY.md`。 ## 许可证 LGPL-3.0-or-later。参见 [`LICENSE`](LICENSE)。

标签：AI辅助开发, Claude Code, Cutter, Odoo, 开源框架, 持续集成, 逆向工具