面向 Odoo 的规范驱动开发

把 DeepSeek Harness 变成一个闭环的 Odoo 工坊：spec → 架构 → 代码 → 验证，全程面对真实实例

<!-- npm 徽章指向已发布的包。如果这个项目被 fork 到别处，
请更新 GitHub 徽章里的 owner/repo。 -->

🇬🇧 English  • 
🇪🇸 Español  • 
🇨🇳 简体中文

作者： Franyer Hidalgo — [email protected]

⭐ 如果这个插件帮你省下了时间，一颗 star 就是很大的帮助 — 它是让这条流水线持续维护下去的信号。
🐛 发现了 bug，或者想要某个功能？ 用任何语言提 issue 都可以。可复现的报告，以及诚实的"这个不管用"的说明，是你最有价值的反馈。

⚡ 概述

dsh-odoo-sdd 把 DeepSeek Harness 变成一条规范驱动（SDD）的 Odoo
开发流水线。有两个理念把它撑起来：

• 闭环反馈 —— agent 会安装和升级模块、读取服务器 traceback，并针对一个
  真实运行中的 Odoo 实例重试。插件从不启动 Docker 或 odoo-bin：你通过一个
  被 gitignore 的 .env 把它指向你已有的实例（dev/staging），工具之间只说
  标准 JSON-RPC。
• 流水线安全 —— 每个阶段都持久化到磁盘，门禁在缺少显式 APPROVED 标记时
  fail-closed，连续三次失败会强制做根因诊断，verify/fix 迭代次数有上限，
  stop.md 会中止一切，而且结论是诚实的：失败的验证会持久化为 FAILED，
  永远不可能被报告成成功。
• 没有 spec 就没有变更 —— 在流水线关闭之后才到来的请求是一次新的变更，
  哪怕它出现在同一个对话里（"顺便把 X 也改了"）：它要么得到自己的（小份）spec，
  要么得到你显式的 waive。这道守卫对实例变更和源码编辑一视同仁，并且会说明三条
  出路里哪一条可用，而不是悄悄改掉。

> [!NOTE]
> 它不是什么： 不是基础设施编排器，不是通过聊天管理凭据的管家，也不是
> 自动提交器。它不写任何 commit，也从不向你索要密码。

环境要求

🔭 工作原理

flowchart TD
A(["想法或需求"]) --> C1["1 CLARIFY访谈与安全问题"]
C1 --> R2["2 READ_SPEC不可变的 spec.md"]
R2 -->|APPROVED| A3["3 ARCHITECTURE模型、视图、安全、测试计划"]
A3 -->|APPROVED| W4["4 WRITE_CODE模块源码与 OCA 文档"]
W4 --> V5["5 VERIFY静态、安装、RPC、UI"]
V5 -->|PASSED| D9(["handoff.md - DONE"])
V5 -->|FAILED| F6["FIX_LOOP根因，最多 5 次迭代"]
F6 --> V5
W4 -.-> M7["odoo_module install 或 upgrade"]
M7 -.->|traceback| E8["odoo_errors"]
E8 -.-> F6

规范是唯一的真相来源，而且它不可变：代码去适应 spec，绝不反过来。门禁默认由
人来回答；当你选择自主模式时，也可以把它们委派给一个人工代理 agent。

✨ 核心特性

• 🎯 永远先有 spec，再写代码。 spec.md 携带编号的验收标准；磁盘上没有
  持久化的 PASSED 结论，就永远到不了 DONE。
• 🔁 真实的反馈闭环。 odoo_module install 返回服务器自己的输出或
  traceback；odoo_errors 读取 ir.logging；失败会变成一个持久化的 FAILED
  结论，而不是一份乐观的总结。
• 🧾 不只是模块。 同一套机器也会跑功能型 spec（mode=functional）：
  配置一个在线实例，并以人工批准的批次加载数据，CSV/Excel 走 Odoo 自己的
  导入器，最后用一份别人能照着复现的 runbook 收尾。
  → 功能路径
• 🔒 有凭据不等于有授权。 一个项目打开第一个 socket 之前，需要一份绑定
  url + db + user 的显式人工授权（.sdd/grants.json）。
• ⏪ 说真话的回滚。 checkpoint 会快照文件，并记录每一次 odoo_execute
  的前像；restore 总会报告 checkpoint 之后创建的文件。撤销不了的东西，它会直说。
• 🧱 文档也是门禁。 odoo_docs 产出 OCA 的 readme/ 片段、Apps 的
  index.html 和强制的 changelog 条目 —— 而且它对一个没有 spec、没有阶段、
  没有实例的已有模块同样可用。
• 🧪 无需实例的静态层。 odoo_validate（结构 + ACL 一致性）和
  odoo_security_scan（原生 SQL、sudo()、auth="none"、QWeb t-raw……）
  在任何东西被安装之前就给出带 file:line 的发现。
• 🧑⚖️ 模型无法自行放松的策略。 白名单、守卫和委派模式，任何改动都需要
  原生人工批准。
• 🤖 受监督或自主。 同一条流水线，可以由人逐个回答门禁，也可以由人工代理
  agent 无人值守地跑 goal 轮次，直到 DONE 或 BLOCKED。
• 📁 spec 放在你想要的地方。 放在每个项目旁边，或者把每个项目的 spec
  收集到一个可搜索的文件夹里。
• 🖥️ Linux、macOS 和 Windows。 路径、原子写入和 .env 权限都按平台处理，
  并在 CI 的 Windows 上测试。

🚀 快速开始

1. 安装到 profile

dsh plugin --profile web add dsh-odoo-sdd

那会从 npm registry 安装已发布的包 —— 不用 clone，不用 build，你这边没有
任何要编译的东西。dsh plugin 是一个很薄的 pnpm 转发器：它在 profile 目录里
运行 pnpm add，然后注册 bundle（dsh.profile.bundles）。有两个后果值得知道：

• pnpm 必须在你的 PATH 上（不在时 dsh plugin 会报出来）。
• 任何 pnpm spec 都能用，所以你可以锁定版本：
  dsh plugin --profile web add [email protected]。

更想用原生 npm —— 一个依赖这个插件的项目，或者一个 CI job？

npm install dsh-odoo-sdd        # 0.14.0，发布时带有 provenance 证明

> [!IMPORTANT]
> 安装后请重启 DSH 并刷新浏览器标签页。客户端改动（Odoo SDD 设置面板）
> 从已安装的包里加载。

正在改这个插件本身？ 那就安装这份 checkout。lib/ 是构建产物，不提交；
npm install 会通过 prepare 钩子构建它，你也可以随时显式要求：

git clone https://github.com/fhidalgodev/dsh-odoo-sdd && cd dsh-odoo-sdd
npm install          # devDependencies: typescript，随后 prepare 构建 lib/
npm run host:deps    # 可选 peers，编译时需要（no-save）
npm run build        # 生成 lib/ —— 必需，包的 main 是 lib/index.js
dsh plugin --profile odoo add .

> [!NOTE]
> 从 git 安装会在使用者的机器上跑那次 prepare 构建，而 pnpm 会阻止依赖的
> 构建脚本，直到你允许它们：命令会告诉你需要在 profile 的
> pnpm-workspace.yaml 的 allowBuilds 下加入的确切键名。从 registry 安装
> 完全不需要这些 —— tarball 里已经带了 lib/。

dsh plugin add 会把 bundle 记录进 profile 的 package.json
（dsh.profile.bundles），而这个包自带一个 Cordis 补丁
（cordis.patch.yml），它会插入自己的那一行 —— 所以没有手工组装步骤。
dsh --profile --dump-config 会打印组装后的配置树，而不启动任何东西。

2. 给它凭据（每个项目一次）

让 agent 运行 odoo_setup mode=check。它会写一个不含密钥的脚手架，
密码由你自己填：

odoo_setup mode=interactive url=http://localhost:8069 db=odoo_dev username=admin
# 然后在打印出来的文件里填写 ODOO_PASSWORD（推荐使用 Odoo API key）
odoo_setup mode=authorize   # 只问你一次，授权这个确切的目标

或者手动来 —— 插件会使用下列位置中第一个存在的：

一个项目里的多个目标。 需要本地 CE 服务器、EE 预发服务器和客户实例的
工作区，不再覆盖唯一的 .env：每个目标在 .sdd/instances/ 下有自己的文件，
其中一个是激活的。

odoo_setup mode=instance instance=list                       # 有哪些，非机密身份
odoo_setup mode=instance instance=add name=staging url=https://stg.example.com db=stg username=ci
# 在 .sdd/instances/staging.env 中手工填写密钥，然后：
odoo_setup mode=authorize name=staging                       # 授权**那个**目标
odoo_setup mode=instance instance=use name=staging            # 为**本会话**激活它
odoo_setup mode=instance instance=remove name=staging         # 需要 confirm_destructive=true
odoo_setup mode=revoke name=staging                           # 只撤销该目标的授权

激活的目标属于「会话」，不属于项目。 每个对话保存自己的指针
（.sdd/instances/active-.json），因此同一项目上的两个会话可以同时使用
两个环境 —— 一个在预发，另一个在客户的服务器上 —— 互不影响。
未做选择的会话会被「询问」，而不会得到默认值。 新对话中的第一次 Odoo 操作会被拒绝
并返回该问题，其中包含可用目标及其非机密身份：

This session has no environment chosen yet, and this project defines 2 instance(s):
- acme: https://… db=acme user=admin
- globex: https://… db=globex user=admin   (the project's last used)
ASK THE DEVELOPER which one THIS session should use, then record the answer:
- an existing one: `odoo_setup mode=instance instance=use name=`
- a new one: `odoo_setup mode=instance instance=add name= url=… db=… username=…`, …

继承项目最近使用的目标只在第一次方便，之后就很危险：另一个会话切换环境会静默地把正在
工作的会话重定向，而它的工具回答仍然只是 OK。每个会话问一次即可消除这一点。
.sdd/instances/active.json 仅作为问题中显示的建议保留。没有具名实例的项目
（只有 .sdd/.env，单目标布局）永远不会被询问，而 requireInstanceChoice: false
可为偏好者恢复旧的继承行为。

授权是按目标的（url+db+user），因此同一台服务器上的两个实例是两个授权。
authorize 接受目标的名称，这正是让切换可恢复的关键：授权会在 12 小时后过期，
而"必须先激活才能授权"曾是一个死循环 —— use 要求目标有有效授权，而 authorize
只能看到当前激活的那个。直接命名即可打破循环：无需离开 main 就能授权 staging。

激活一个没有有效授权的目标仍会被拒绝：指针决定变更发往哪里，所以它不能指向
没有人批准过的目标。当存在多个实例且没有激活任何一个时，所有连接工具
都会拒绝，而不是按顺序挑选 —— 旧的 .sdd/.env 会作为 default 原样继续工作，
直到你自己决定迁移。

mkdir -p ~/.config/dsh-odoo-sdd && cd ~/.config/dsh-odoo-sdd
cp /.env.example .env && chmod 600 .env
# 填写：ODOO_URL, ODOO_DB, ODOO_USERNAME，以及**一个**密钥：
#   ODOO_PASSWORD=<账户密码>   或   ODOO_API_KEY=

密钥有两个被接受的名字。 会读取 ODOO_PASSWORD 和 ODOO_API_KEY，推荐使用
API 密钥：Odoo 在通过 RPC 接受密码的任何地方都接受它（设置 → 用户 → API 密钥，
并使用全局范围的密钥）。如果两者都设置了，ODOO_PASSWORD 优先，插件会报告
另一个被忽略，这样轮换后的凭据不会被漏掉。

只有一个地方 API 密钥不适用，这是 Odoo 的规则而非插件的规定：odoo_session
和 odoo_import 认证的是 Web 会话，而 Odoo 以 interactive: True 认证交互式
登录，仅在相反情况下才查询 API 密钥表。若需要这两者，请配置账户密码；其他一切
都可以用密钥完成。

插件使用哪个 API

在 19+ 上插件使用现代的 JSON-2 API：没有 uid 往返，具名参数由 Odoo 自身校验，
@api.readonly 方法路由到只读副本，错误以 HTTP 状态加结构化响应体返回。当路由缺失
在三种情况下会自动回退到经典 JSON-RPC：路由缺失、服务器版本更旧，或者该凭据在那里根本
不可用。最后一种很重要：JSON-2 只接受 Authorization: Bearer，因此用密码配置的目标每次调用都会
返回 401 —— 而 401 意味着请求从未执行，所以改用另一传输方式不会造成重复副作用。服务器确实处理过
并拒绝的调用（403、422、领域错误）绝不重发。
json2 会报告路由缺失，而不是静默降级。

业务动作（action_*、button_*、do_*）始终使用 execute_kw：JSON-2 没有位置
参数形式，而为插件并不知道签名的方法臆造位置→名称映射，正是它拒绝做出的那种静默
误发。

> [!WARNING]
> 绝不要把密码粘贴到聊天、spec、commit 或 issue 里。插件会拒绝组/其他用户可读的
> .env，在每一次工具输出中脱敏密钥，并把会话 cookie 存到 .sdd/session.json
> （mode 600），从不把它们返回给模型。

3. 提出你的需求

为 Odoo 19 实现一个销售订单审批模块，使用 SDD 工作流。

agent 会从会话的 skill 目录里取出 odoo-sdd-workflow 并遵循协议。如果你想
说得更明确 —— 或者想确保完整指令被加载 —— 把消息以 /odoo-sdd-workflow 开头。

如果要在运行中的实例上做配置和数据工作，请改成这样说：

在我的 dev 实例里配置公司、税和会计科目表，然后导入
这个 customers.csv —— 功能型 SDD，dev 环境，不要碰生产。

那会选择 odoo-functional-sdd（或显式写 /odoo-functional-sdd）
以及下面描述的 functional spec 模式。

🧭 五个阶段

字符串要翻译吗？（translations）

CLARIFY 会连同授权问题一起询问，答案记录在 spec 上 —— 不是全局设置，与版本选择完全一致。
同一个工作区可以既有委内瑞拉的客户项目，也有完全不交付语言的内部修复。

sdd_phase operation=clarify spec_id= mode=… licensed=… translations=["es_VE","es_PA"]

• 省略 translations 意味着该工作不翻译。 这是一个正常答案，因此与 mode 和 licensed
  不同，它不是 fail-closed 关卡。
• 代码是 gettext 形式（ll 或 ll_CC：es_VE、es_PA、pt_BR、fr）。格式错误的代码会
  在还能纠正时被拒绝，而不是变成一个服务器永远不会加载的文件。
• 声明语言会让 odoo_i18n 进入计划，并在 test-plan.md 中加入对应的验收标准：
  "存在 i18n/.po 且没有导出的条目留有空 msgstr" —— 由
  odoo_i18n operation=check 验证。
• sdd_phase status 会报告它们，因此"我们翻译了吗？"无需打开 state.json 即可回答。

在 ARCHITECTURE 阶段，agent 还会主动询问那些"早决定很便宜、晚发现很昂贵"的
事情：form/tree 之外的额外视图类型（包括用于描述模型如何被搜索的
search 视图 —— 自定义过滤器、收藏夹）、报表（通过
ir.actions.report/QWeb 的 PDF、SQL、CSV/XLSX、外部工具）、web tours
（onboarding、测试，或都不需要 —— 并说明加载它的 asset bundle，因为没有任何
bundle 加载的 tour 永远不会执行）以及演示数据（哪些文件、用途是什么）。每一项
都要明确回答："form + tree only"、"no reports needed"、"no tours needed"、
"no demo data"。这些是指引性决定：记录在 ## Views / ## Reports /
## Tours / ## Demo data 中，并在 sdd_phase status 里作为警告呈现，按设计不
阻塞 —— 安全模型才是唯一 fail-closed 的内容门禁。各版本的 tour API、执行它的
HttpCase 以及演示数据的陷阱都在
resources/references/tours-and-demo.md。

每个 spec 的产物（全部在磁盘上，可断点续跑）：

specs/-/
├── spec.md · architecture.md · test-plan.md
├── verify-verdict.txt   # 持久化的诚实结论
├── state.json           # 阶段、失败次数、迭代次数
├── kb.json              # 决策、被弃用的选项、blockers、诊断
├── docs-report.md · security-report.md
└── handoff.md           # 运行收尾时由 sdd_handoff 写入

🧩 功能路径（配置与导入）

不是每一项 Odoo 工作都是写代码。搭建一家公司、它的税、它的用户和它的主数据，
属于配置与数据，而且发生在在线实例上 —— 在那里，一次误点不是失败的测试，
而是一条真实记录。同一套 SDD 机器用一个不同的中间阶段和更严格的收尾规则覆盖它。

graph TD
C1["1 CLARIFY目标、实例、ENVIRONMENT"] --> R2["2 READ_SPECspec.md、标准、来源"]
R2 -->|APPROVED| A3["3 ARCHITECTUREto-be 流程、批次、风险"]
A3 -->|APPROVED| X4["4 APPLY_CONFIG发现 + 已批准的批次"]
X4 --> V5["5 VERIFY重新读取记录，逐条 AC 取证"]
V5 -->|PASSED| D9(["runbook.md + handoff.md - DONE"])
V5 -->|FAILED| F6["FIX_LOOP"]
F6 --> X4

style X4 fill:#1e1e2e,stroke:#f9e2af,stroke-width:2px,color:#cdd6f4

一次改动是如何到达实例的。 没有任何东西是"写着看看会怎样"：

1. 先做发现，在它自己的审批之下：哪些模型、哪些字段、多少条记录。读取
   不是变更，但一个被批准的 scope 才能阻止"只是看看"变成一次改动。
2. 计划：设计变成批次。每个批次声明它的目标和环境、用到的版本和能力、公司
   和上下文、它覆盖的验收标准、有序的操作、记录标识、前置条件、预期结果、风险、
   恢复方式和手工步骤。
3. 批准：人看到确切的批次，并通过原生审批通道批准它。回执绑定 spec、设计、
   计划和批次的哈希 —— 改动其中任何一个，审批即失效。
4. 应用：一次一个操作，重新校验那些哈希，在调用之前和结果之后分别
   持久化每个操作的状态。
5. 未知结果不是重试。 一次变更之后的超时可能意味着 Odoo 已经提交了，所以
   该操作会被标记为 indeterminate，批次停止，运行挂起，直到有人来对账。
6. 诚实地收尾：sdd_phase succeed 要求每条验收标准都有明确的 pass，安全
   审查是强制的，runbook 也是强制的（谁来做、在哪个公司、前置条件、验证过的
   菜单路径、带字段标签的步骤、预期结果、如何检查以及如何撤销）—— 无论文档策略
   怎么说。

环境必须声明，绝不假设。 目标上的 ODOO_SDD_ENVIRONMENT 会说 dev、
staging 或 production。声明了与目标不同环境的计划会被拒绝
（environment-mismatch），未声明环境的目标会被要求补上
（NEEDS_ENVIRONMENT），而生产环境额外需要一份声明的备份引用以及它自己的审批。
高风险改动先在 staging 中验证。

导入走 Odoo 自己的导入器，绝不走手写解析器：

odoo_import use=prepare file=... model=res.partner   # 上传文件，带它自己的审批
odoo_import use=preview   ...                        # ODOO 读到了什么：工作表、表头、样本
odoo_import use=map       ...                        # 每一列一个决定，不能留空
odoo_import use=plan      ...                        # 变成一个 `apply` 批次
odoo_functional operation=approve / apply            # 批次路径，保持不变

版本契约是显式的（主版本 10–19：旧端点上用 file/import_id + JSONP，新端点上用
ufile/id + JSON，应用时用 do/execute_import），不在已验证版本族内的版本会被
拒绝并告知该调查什么，而不是靠猜。上传之后被改动的文件会让映射失效；应答里
出现 nextrow 意味着导入器在文件中途停下了，会被报告为部分完成，绝不会报告为
成功 —— 而它已经计入的行绝不会被重发。会话 cookie 留在 .sdd/session.json
（mode 600）里，不进入任何工具结果。

> [!NOTE]
> 功能路径需要一个实例，而导入器需要一个 web 会话：在
> odoo_import use=prepare 之前先运行一次 odoo_session。

🧰 17 个工具

🎛️ 委派模式

流水线一开始会问要委派多少 —— 每个项目用
odoo_setup mode=autonomy decision=... 记录一次：

> [!TIP]
> 在自主模式下刹车依然上膛：stop.md、迭代上限和诊断阶梯都还在，而 BLOCKED
> 是运行唯一会呼叫人的方式。连接授权不受这个开关覆盖 —— 实例仍然需要由人
> 授权一次。

🧠 上下文工程分层

🛡️ 安全性、回滚与可追溯性

流水线假设 agent 迟早会出错，所以每一条变更路径都有回退方式，也有证明发生过什么
的方式。

• 有凭据不等于有授权。 在任何工具向实例打开 socket 之前，必须已经有一个
  人批准过那个确切的目标。odoo_setup mode=authorize 通过宿主的原生审批
  通道发问，只有 allowed-once 结果才会在 .sdd/grants.json（0600，被
  gitignore）里存下回执。回执绑定 url + db + username 的指纹，所以改动其中
  任何一个都会让它失效；mode=revoke 会删除它。没有有效回执时，根本不会发出
  任何客户端，因此一个配置好的 .env 不可能被悄悄使用。在 AUTONOMOUS 模式下
  没有回答者，所以运行会报告 NOT AUTHORIZED 并挂起 —— 这正是重点。
• 模型无法放松自己的策略。 修改白名单或策略守卫（odoo_config mode=set）
  以及切换委派模式（odoo_setup mode=autonomy），每一项都需要原生审批。
• 没有 spec，就没有变更 —— 除非你显式 waive。 无论请求是什么，哪怕它就是
  同一个对话里的"顺便把 X 也改了"，一次变更都需要处于写作阶段的 spec
  （WRITE_CODE、VERIFY、FIX_LOOP、APPLY_CONFIG），或者一个你为本次
  会话批准的 waiver。这道门禁覆盖两个面：实例变更（odoo_execute、
  odoo_module、odoo_import prepare）以及通过宿主 write/edit 工具做的源码
  编辑。写 spec 文档本身（specs/、.sdd/）永远不会被挡 —— 否则那条出路也会被
  挡住。小改动就是小 spec：mode=bug、一条验收标准、没有设计访谈。如果你不想
  为它写 spec，也可以用 sdd_phase operation=waive detail="..."：它会把你的话记录下来、需要你的审批，并且只覆盖
  本次会话：下一次对话会重新回到这条策略之下，而在它之下做的每一项变更仍然会
  作为决策记入 KB。requireSpecForChanges: false 是人的关闭开关。
  诚实的漏洞： 守卫看到的是宿主工具调用，所以通过 bash 做的变更
  （heredoc、sed -i）不受门禁 —— 流水线是路径，不是监狱。

在哪里询问（specPolicyScope，默认 "odoo"）。要求 spec 只在有 Odoo 工作的
地方才有意义，而守卫过去只检查一件事：路径是否落在会话根目录内。因此按配置文件级别
安装的插件会封锁与 Odoo 毫无关系的文件夹里的写入。使用 "odoo" 时，文件编辑只在
目录显示 Odoo 工作迹象时才受门禁：

• .sdd/ 中有真正的插件状态（config、specs、checkpoints、waiver）—— 不是只含
  audit.jsonl 的 .sdd/，审计监听器会为每一次工具调用写入它，因此它只意味着
  "这里跑过东西"，而不是"这是 Odoo 项目"；
• 根目录有 __manifest__.py —— 该目录就是一个模块；
• 下一层有 __manifest__.py —— 该目录包含模块；
• 本会话中已对该根目录使用过 odoo_* 工具。

实例变更始终受门禁：它本身就是 odoo_* 调用，也就是证据本身。stop.md 仍然
停止一切，无论是否已采用，因为它是紧急停止而非范围问题。"everywhere" 恢复旧的
全面行为，而拒绝信息现在会指出触发策略的信号，不再让你猜测。

三条出路，三条都可用。（1）为本次变更开一个小的 spec，（2）继续已覆盖它的
spec，（3）请开发者豁免 —— sdd_phase operation=waive detail="..."。第三条过去要求
spec_id，这使它在唯一需要它的场景中不可用：没有 spec 的目录，你必须先创建一个
spec 才能说你不想要 spec。豁免是按项目和会话的，现在 spec_id 对它（以及
waive revoke=true）是可选的，而其他所有操作仍然要求它。
- 变更前先 checkpoint。 在 requireCheckpointBeforeMutation 开启时（默认），
odoo_execute 的变更会被拒绝，直到 sdd_checkpoint create 已对活动 spec 做过
快照 —— 并且在 WRITE_CODE 之前直接被拒绝。快照会跳过符号链接（lstat），
也绝不复制 .env 或密钥材料。
- fail-closed 守卫。 内部守卫失败时会带一个可见的理由拒绝，而不是放行调用。
- 文件回滚。 sdd_checkpoint restore 把快照中的文件逐字节放回；
sdd_phase rollback 把 spec 退回 WRITE_CODE 并记录失败，让循环从一个已知
状态重新开始。checkpoint 快照的是项目树，所以在 central specs 布局下，
spec 文档（它们位于项目之外）故意不属于快照的一部分：spec 是不可变的真相
来源，不是要回滚的代码。
- 数据回滚（尽力而为，并且对此诚实）。 每一次通过 odoo_execute 的
create/write/unlink 都会把它的前像记录进 checkpoint 日志，并盖上数据库
以及它所应用到的目标（url+db+user）的戳；restore restore_data=true confirm_destructive=true 会反向重放，并拒绝来自其他目标的日志。重放在该
变更用过的公司上下文中运行，把读取形态转换成写入值（many2one、x2many），在
补偿每个操作时标记它，使重试不会重复其中任何一个，并报告它无法恢复的字段
（二进制内容、只读或非存储字段）。被重新创建的记录会拿到新的 id ——
报告会说明这一点。它覆盖的是通过插件写入的数据 —— 不包括模块安装/升级的
副作用，那些不会在数据库层面被还原。
- restore 会报告漂移。 restore 总会列出 checkpoint 之后创建的文件，
所以不会有东西被悄悄留下；remove_created=true 会删除它们（仅在快照的根之内）
以与快照完全一致。
- 文档是门禁，不是脚注。 ARCHITECTURE 把决定记录在 ## Documentation，
WRITE_CODE 产出 OCA 片段 + Apps 的 index.html + 强制的 changelog 条目，
而 DONE 由 documentationPolicy 把关（默认 required；另有 optional 和
off）。插件做不到的事，它会直说：gen-odoo-readme、towncrier、Ruff 和
pylint 需要 shell，所以片段才是真相来源，编译 README.rst 仍然是你的步骤。
- 生命周期：插件拥有自己的状态，也能把它交还。 odoo_setup mode=purge
会打印一份计划（它拥有什么、它有意保留什么），并且只有在
confirm_destructive=true 加原生人工批准之后才删除。它绝不碰 .env
（你的凭据）、stop.md（你的刹车）或 specs/（你的文档）。
- 持久化状态。 流水线状态、KB、结论、授权和日志都用原子替换写入，损坏的
文件会被隔离在原文件旁边而不是被覆盖：sdd_phase status 会报告这次恢复。
- 可追溯性。 .sdd/audit.jsonl 记录每一次工具调用及其结果
（ok / error / denied）、耗时和阶段；sdd_phase status 打印 logbook；
sdd_handoff 把整次运行冻结进 handoff.md。
- 紧急刹车。 stop.md（位于 .sdd/stop.md 或 specs//stop.md）
会中止所有工具；迭代上限和诊断阶梯会把运行导向 BLOCKED，而不是无限循环。

🔐 安全与网络策略

• 不回传任何数据。 插件唯一的外发网络调用发往你写在 .env 里的实例
  URL。没有遥测，没有更新检查，没有第三方端点。
• 传输守卫（fail-closed）。 http:// 只对回环主机（localhost、127.x、
  ::1、*.localhost）接受；其他任何目标都必须是 https://，否则凭据加载
  会被拒绝 —— 对远程主机用明文 http 会把 API key 明文发出去。
• 密钥隔离。 密钥只由 credentials.ts 读取一次，并且只注入到 RPC 参数里。
  每一份工具输出在展示给模型或持久化进 KB 之前，都会经过两层脱敏（已知密钥 +
  通用的 password= / Bearer / api_key= / session_id 形态）以及家目录路径
  掩码（/home/user/… → ~/…）。
• 会话 cookie 永远不会到达模型。 odoo_session 把 cookie 写入
  .sdd/session.json（chmod 600），只返回路径。
• 构建之外没有安装脚本。 唯一的生命周期脚本是 prepare/prepack，它们把
  src/ 编译成随包发布的 lib/，别的什么都不做 —— 没有网络，没有
  postinstall，没有 shell。两者的失败策略故意相反：prepare（在安装时运行）
  从不弄挂一次安装 —— 没有 devDependencies 或没有可选宿主 peers 时，它会说明
  自己无法检查什么，并在不做类型检查的情况下产出，好让插件仍能加载 —— 而
  prepack（在发布时运行）拒绝打包一个它无法通过类型检查的构建。prepack
  同时保证已发布的 tarball 绝不会缺少它 main 所承诺的入口点（那个失败真实
  发生过：一个干净的 clone 打包了 39 个文件，其中 lib/ 下零个；它的续集也
  是真的：一个在 npm install 期间做类型检查的 prepare，在安装那些 peers 的
  步骤能运行之前就让每个 CI job 都失败了）。
• 宿主要求声明了两次，遵循 dsh-market 的发现约定：engines.dsh 以及在
  @deepseek-ai/{cordis,dsh-tools,schemastery} 上 lockstep 的可选 peer 范围。
  在没有 tools 服务的宿主上，插件会带一个显式错误拒绝挂载，而不是带着故障启动。

🖥️ 平台支持

DSH 能跑的地方插件就能跑，并声称支持 Linux、macOS 和 Windows —— 这个声明
由 CI 矩阵来检验而不是断言（ubuntu-latest 和 windows-latest，Node 20
和 22）。

📁 spec 存放在哪里

项目根目录就是当前会话中打开的文件夹，所以它不是插件级的设置。spec 文档跟着它走：

在 central 布局下，每个项目都有自己的子文件夹，带一个 .dsh-project-root 标记；
如果两个项目共用同一个目录名，还会加一个哈希后缀 —— 外来的文件夹绝不会被收养。
.sdd/ 始终留在项目里。

/
├── .sdd/                       # 插件自有，已 gitignore
│   ├── .env                    # 凭据（chmod 600）
│   ├── config.json             # 项目配置
│   ├── grants.json             # 人工授权回执
│   ├── session.json            # Playwright cookie
│   ├── audit.jsonl             # 每一次工具调用，已脱敏
│   ├── setup-state.json        # 上手引导 + 委派决定
│   ├── active/.json # 本会话的指针（spec、阶段、checkpoint）
│   ├── active.json             # 项目最近使用的 spec（参考用；见 adoptProjectPointerHint）
│   └── checkpoints//       # manifest + 文件快照 + 数据日志
└── specs/-/         # 或者 central 文件夹

spec 指针属于「会话」，不属于项目。 每个对话写入自己的
.sdd/active/.json，因此同一个项目上打开的两个会话不再互相覆盖，
也无法用对方的 spec 来授权改动。.sdd/active.json 仅保留为项目最近使用的
spec：没有自己指针的会话，在它足够新（< 12 小时）且该 spec 仍然存在时，会把它
当作提示采用。若要严格范围 —— 每个会话在声明之前都没有 spec
（sdd_phase status spec_id=…）—— 请在面板或 odoo_config 中设置
adoptProjectPointerHint: false。checkpoint 的快照仍属于项目；而哪个是
你的回滚目标是每个会话各自的，删除时会清除所有指向它的指针引用。

> [!TIP]
> 同时打开多个项目时，读一读每个工具结果都带的那行
> Project root: … [provenance]，或者问 odoo_config mode=read —— 它会返回
> 解析出的根目录、它的来源和生效的 spec 目录。

⚙️ 配置

在 Web UI 中打开 Settings → Odoo SDD。一切都可以在那里编辑，另外在你需要的
地方还提供了几个可复制粘贴的预设。

> 宿主要求：设置面板需要 dsh >= 0.2.0-rc.1。该版本移除了面板原先绑定的
> settingsScope 服务，改为根据插件自身的 Config schema 生成表单（条目 odoo-sdd）。
> 在更旧的宿主上该分区不会出现，插件会在控制台说明原因；工具与流水线照常工作，
> 可用 odoo_config mode=read|set 在对话中编辑同样的值。

# ~/.dsh/profiles//cordis.patch.yml（可选：同样的字段，作为补丁）
- insert:
- id: odoo-sdd
config:
specsMode: project      # project | central
specsRoot: ''           # specsMode=central 时的绝对文件夹
specsDir: specs         # specsMode=project 时项目内的文件夹
executeAllowlist: []    # odoo_execute 可以 create/write/unlink 的模型
methodAllowlist: []     # 功能批次可调用的 "model.method" 对（任意模型）
# 即席 RPC 不需要列表：任意公共方法 + confirm_destructive
communityRepoUrl: https://github.com/odoo/odoo
enterpriseRepoUrl: https://github.com/odoo/enterprise
communityRepoPath: ''   # 本地 OS 路径；设置后会**覆盖** communityRepoUrl
enterpriseRepoPath: ''  # 企业版同理
odooApi: auto           # auto | json2 | jsonrpc（auto 在 401 时回退）
autonomy: supervised    # supervised | autonomous
licensed: community     # community | enterprise（OCA 总会被搜索）
requireCheckpointBeforeMutation: true
requireSpecForChanges: true     # 每一项变更都需要处于写作阶段的 spec（或 waiver）
specPolicyScope: odoo           # odoo（仅在检测到 Odoo 工作时）| everywhere
securityReviewRequired: true
securityInterviewRequired: true
auditAllTools: true
maxCheckpoints: 5
documentationPolicy: required   # required | optional | off
documentationLanguage: ''       # 留空 = 英文，除非项目另有规定

> [!IMPORTANT]
> 有两个配置存储，更具体的那一个获胜：Settings（用户级，
> ~/.dsh/settings.yaml）和项目的 .sdd/config.json（由
> odoo_config mode=set 按项目写入）。如果某个键在面板里改过之后看起来被忽略
> 了，那就是项目文件把它钉住了 —— odoo_config mode=read 会报告生效值。

🤖 模型体验

agent 看到 15 个自包含描述的工具。典型流程：
sdd_phase init → 安全访谈 + odoo_connect → 带 APPROVED 的门禁阶段 →
sdd_checkpoint create → 写代码 → odoo_security_scan →
odoo_module install → 出现 traceback 时用 odoo_errors + sdd_phase fail
（它可能强制一次诊断）→ 修复（或 sdd_phase rollback）→ 重新验证 →
sdd_phase succeed → sdd_handoff → DONE。工具响应是可执行的文本：服务器
traceback、门禁拒绝理由和补救说明。

工作流 skill 在挂载时注册，所以它的名称和描述会自动出现在每个会话的 skill
目录中。完整指令在模型选中它时加载（目录里只有摘要），或者在你输入
/odoo-sdd-workflow 时加载。

⚠️ 已知限制与待办工作

• 远程测试 —— 没有实例的 shell 访问就无法运行 --test-enable；第二层验证是
  RPC/UI 测试。待办：如果你暴露测试运行器，就提供一个可选的 odoo_run_tests
  工具。
• 数据回滚是尽力而为 —— 测试会写入所连接的数据库，而且没有临时克隆
  （这是设计决定：目标由你提供并归你所有）。sdd_checkpoint 能撤销通过
  odoo_execute 写入的数据，但模块安装/升级不会在数据库层面被还原。请使用
  可丢弃的数据库。
• 静态安全扫描的范围 —— odoo_security_scan 是基于规则的源码文本检查
  （没有 AST，没有污点追踪），所以它能抓住常见的 Odoo 错误，但不是全部；它补充
  人工审查，绝不替代人工审查。
• 变更策略管的是工具调用，不是 shell —— write/edit 和 Odoo 工具会受门禁
  约束；而通过 bash 写入的文件（heredoc、sed -i）不会，因为宿主不会事后检查
  一条 shell 命令写了什么。这条策略让流水线成为阻力最小的路径、让例外保持可见；
  它不是沙箱。
• 多实例 —— 每个项目一个目标（.env）。待办：具名实例配置
  （dev、staging）。
• 面板中仅作信息的字段 —— autonomy 和 securityInterviewRequired 会被
  存储和报告，但流水线从 .sdd/setup-state.json 读取委派决定（用
  odoo_setup mode=autonomy 设置），并通过 ARCHITECTURE 的内容门禁强制执行安全
  访谈。已记为待办工作。
• 没有富 UI 渲染器 —— 工具输出就是 DSH web GUI 里的文本。

❓ 故障排查

🧩 实现细节

插件形态、源码地图与安全决策 —— 点击展开

插件形态

遵循 DSH 工具插件约定（dsh-tool-todo、dsh-tool-goal）：具名导出 name、
inject、Config（schemastery schema）和 apply(ctx, config)，并用
@deepseek-ai/dsh-tools 的 defineTool 注册每个工具。浏览器那一半是一个普通的
JS ModuleLoader bundle，它贡献 Odoo SDD 设置区块。

源码地图