@dazitech/cli 3.0.9 → 3.1.1

package/dist/docs/onto//350/204/232/346/234/254/350/277/220/350/241/214/345/270/270/350/247/201/351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -0,0 +1,297 @@
+# 脚本运行常见错误处理
+
+**文档 ID**: `onto/script-run-troubleshooting`  
+**级别**: **执行脚本前必读（强制）** — 在终端执行 `dazi onto script publish` / `script run` / `function run` / `save-test-arguments` **之前**须通读  
+**适用**: 本体 `setup/`、`functions/` 脚本编写、发布与运行；智能体见提示词 `onto/script-publish-run`
+
+> 路径占位：`<项目路径>` = `项目/<业务名>/本体/ontos/<实现名>`，`<空间>` 取自实现单元 `README.md`。
+
+---
+
+## 1. setup 脚本 API 误用
+
+| 错误写法 | 正确写法 | 说明 |
+| -------- | -------- | ---- |
+| `s.onto.sync_metrics()` | 删除；必要时 `s.sync_metric_refs()` | `sync_metrics` 不存在 |
+| `s.cubes.upsert(...)` | `s.register_cube(...)` | 无 `s.cubes` |
+| `define_object_type(code, label=name)` | `define_object_type(code, name=...)` | 第二参数为 `name` |
+| `define_object_type(title=...)` | `define_object_type(name=...)` | 参数名为 `name` |
+| `bind_source(source_type=..., source_name=...)` | `bind_source(obj_code, "dazi_cube", config={"cube": "CubeName"})` | 见利润/销售示例 |
+| `define_property(object_type_code=..., title=...)` | `define_property(obj_code, code, name, ...)` | 位置参数 |
+| `define_link_type(title=..., from_object_type=...)` | `define_link_type(name=..., from_object_type_code=..., to_object_type_code=...)` | 以 `_code` 结尾 |
+| **Reference 对象无 Cube 仍 define_property** | 参考型对象不 `bind_source` 则**禁止** `define_property` | 见 §1.1 |
+
+**教训**：对照 `资源/examples/onto/利润示例`、`销售示例` 的 init，勿猜 API。
+
+### 1.1 无 Cube 绑定的对象禁止 define_property
+
+| 对象分类（347） | bind_source | define_property |
+| --------------- | ----------- | --------------- |
+| 主数据 / 事务 / 分析 | **必须**绑定 Cube | ✅ 可定义属性 |
+| 参考 / 配置（无 Cube） | 无 | ❌ **禁止** — 会报「对象类型未绑定任何 DaziCube」 |
+
+规划阶段：Reference/Master 无 Cube 时，属性章节须标注「跳过或需补 Cube + bind_source」。
+
+### 1.2 本域首次 init 检查表（5 条）
+
+init `script run` 前逐项确认：
+
+| # | 检查项 | 通过标准 |
+| --- | ------ | -------- |
+| 1 | **dim_date** | 共用空间时确认已存在，或 init 含幂等 `ensure_dim_date` |
+| 2 | **bind_source** | 每个需读模型的分析/主数据/事务对象已绑定 Cube |
+| 3 | **define_property** | 无 Cube 的参考对象未调用 define_property |
+| 4 | **function_result** | 函数模板使用 `columns=`/`data=` kwargs，非 dict positional |
+| 5 | **relationship_count** | init 日志关系数与 plans §表间关系一致 |
+| 6 | **init 不含 apply_registry** | 分类在 `*_category_mount.py`；init 只做表/Cube/对象/链接 |
+
+### 1.3 init 与 category_mount 职责分离
+
+| 脚本 | 职责 | 时机 |
+| ---- | ---- | ---- |
+| `*_ontology_init.py` | 建表、register_with_meta、关系、Cube、对象/链接、sync_metric_refs | init → seed 之前 |
+| `*_category_mount.py` | `CATEGORY_REGISTRY` + `apply_registry` | **最后**（全部函数 publish 后） |
+
+**禁止**：在 init 内调用 `s.categories.apply_registry`（函数未 publish 时 function 段会被 skip；重跑 init 成本高）。
+
+`dazi onto script publish-preview` 对 `*init*.py` 会报错 `[init-no-apply-registry]`。
+
+---
+
+## 2. SQL 聚合：`query_one` 返回类型
+
+**现象**：`float' object has no attribute 'get'`
+
+```python
+# 错误
+total_row = p.sql.query_one("SELECT sum(amount) AS grand_total FROM ...")
+grand_total = float(total_row.get("grand_total", 0))
+```
+
+**原因**：聚合场景下 `query_one()` 可能返回标量而非字典行。
+
+**修复**：
+
+```python
+total_rows = p.sql.query("SELECT sum(amount) AS grand_total FROM ...")
+total_row = total_rows[0] if total_rows else {}
+grand_total = float(total_row.get("grand_total", 0) or 0)
+```
+
+---
+
+## 3. 函数输出：禁止 `output.print_json`
+
+**现象**：`AttributeError: 'OutputModule' has no attribute 'print_json'`
+
+本体函数须 **`return`** 结构化结果，不能当 setup 脚本用 `output` 打印 JSON。
+
+```python
+def _ontology_fn_body(p):
+    rows = p.sql.query("SELECT ...")
+    return p.function_result(columns=[...], data=rows, row_count=len(rows))
+
+def main():
+    s = space.get(ctx.space_id or "")
+    # 组装 p（见 ontology_function_template.py）
+    return _ontology_fn_body(p)
+```
+
+**禁止**：`output.print_json()`、`main(params: dict)`、裸 `return {"k": v}` 代替 `function_result`。
+
+**模板**：`资源/examples/onto/_templates/ontology_function_template.py`
+
+---
+
+## 4. CLI 参数误用
+
+### 4.1 `function run` 与默认参数
+
+**推荐顺序**：`publish` → `function run`（验证）→ `save-test-arguments`（侧栏预填）。
+
+未传 `--params` 或 `--params '{}'` 时，CLI **自动回退**：
+
+1. 已保存的 `test_arguments.arguments`
+2. 否则脚本内 `TEST_ARGUMENTS.arguments`
+
+```powershell
+# 首次 run（无 save-test-arguments 也可，回退脚本内 TEST_ARGUMENTS）
+dazi onto function run sales.fn.yoy_analysis --space <空间>
+
+# 显式传参
+dazi onto function run sales.fn.yoy_analysis --space <空间> --params '{"start_date":"2025-01-01","end_date":"2025-12-31"}'
+```
+
+**不支持** `--arguments-json-file`（勿与 save-test-arguments 混淆）。
+
+### 4.2 `save-test-arguments`：ofn_xxx 或 --function-id
+
+```powershell
+# 推荐：function_id 别名（无需查 ofn_xxx）
+dazi onto function save-test-arguments --function-id profit.fn.get_summary --space <空间> `
+  --arguments-json-file <项目路径>/functions/test_arguments/profit.fn.get_summary.json
+
+# 或使用平台内部 id
+dazi onto function list --space <空间> --json   # 含 save_command 字段
+dazi onto function save-test-arguments ofn_xxxxxxxx --space <空间> `
+  --arguments-json-file <项目路径>/functions/test_arguments/profit.fn.get_summary.json
+```
+
+### 4.3 函数发布未带 `--register-function-id`
+
+仅 `script publish` 时代码入库，**不会**出现在 Onto → 函数列表，`function run` 失败。
+
+```powershell
+dazi onto script publish <项目路径>/functions/xxx_fn.py --space <空间> `
+  --register-function-id <domain>.fn.<name>
+dazi onto function list --space <空间>   # 必须能看到该 id
+```
+
+可选同时挂载平台分类：`--register-platform-category 总览分析`
+
+---
+
+## 5. 函数「未注册」（规划有、侧栏无）
+
+| 现象 | 根因 |
+| ---- | ---- |
+| `CATEGORY_REGISTRY` / plans 列了 N 个函数 | 规划清单 ≠ 已发布函数 |
+| `functions/` 文件数 < 规划数 | 脚本未写完 |
+| `function list` 只有 1 条 | 多数未 `publish --register-function-id` |
+
+**结论**：init **不负责**注册本体函数；每个 `functions/*.py` 须单独 publish 并注册。
+
+**门禁**：规划函数数 = `functions/*.py` 数 = `function list` 条数。可运行 `functions/onto_preflight.ps1`（见 `资源/examples/onto/_templates/`）自动核对。
+
+## 5.1 本体函数 publish-preview 静态预检
+
+`dazi onto script publish-preview` / `script publish`（本体函数）会在本地检查：
+
+| 级别 | 规则 |
+| ---- | ---- |
+| error | 禁止 `output.print_json`；须 `def main():`；须 `function_result(columns=...)` kwargs |
+| warn | 缺少 `TEST_ARGUMENTS`；`params.get("start_date", "")` 空串默认 |
+
+有 **error** 时预检失败，须修复后再 publish。
+
+---
+
+## 6. 平台分类挂载时机
+
+**推荐**：与灌数一样，使用独立 `setup/*_category_mount.py`，放在流程**最后**：
+
+```
+init → seed → 发布全部函数 → category_mount
+```
+
+| 方式 | 何时 |
+| ---- | ---- |
+| **`*_category_mount.py`**（推荐） | 全量 `CATEGORY_REGISTRY` + `apply_registry`；函数齐后一次执行 |
+| `--register-platform-category` | 单函数 publish 时内联（与 category_mount 幂等可并存） |
+| init 内 `apply_registry` | **不推荐**（函数未 publish 时 function 段被跳过，须重跑 init） |
+
+`skip_missing=True` 时，未注册函数会被跳过；**补发函数后只重跑 category_mount**，无需重跑 init。
+
+---
+
+## 7. 平台分类字典报错
+
+**现象**：
+
+```
+ValueError: 平台分类字典中不存在分类: kind='table', category='维度表'
+```
+
+（旧版日志可能显示乱码，非脚本 UTF-8 损坏。）
+
+**原因**：`category` 须为**平台标准分类中文名**（如「维度表」「事实表」），且测试环境 backend 须含完整平台分类字典。
+
+**处理**：
+
+1. 确认 `CATEGORY_REGISTRY` 使用标准名，与 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md) 一致  
+2. 部署含 `s.categories` 与表类中文名索引的 backend 版本  
+
+---
+
+## 8. 表/列显示名未写入
+
+仅用 `register` + `sync_columns` 时，列 `description` **不会**自动写入规划中的业务说明。
+
+**推荐**：
+
+```python
+s.tables.register_with_meta(
+    table_name,
+    display_name=meta["display_name"],
+    description=meta.get("description"),
+    columns=meta["columns"],
+    force_column_meta=True,
+)
+```
+
+见 [本体脚本编写指南 · 表注册](./本体脚本编写指南.md#表注册-table_registry--register_with_meta)。
+
+---
+
+## 9. 标准 CLI 顺序（通用）
+
+在 `dazi-work` 根目录，将 `<项目路径>`、`<空间>` 替换为实际值。
+
+```powershell
+# 1. init
+dazi onto script publish <项目路径>/setup/xxx_ontology_init.py --space <空间> --type setup
+dazi onto script run --file <项目路径>/setup/xxx_ontology_init.py --space <空间>
+
+# 2. seed（如有）
+dazi onto script publish <项目路径>/setup/xxx_seed_data.py --space <空间> --type data
+dazi onto script run --file <项目路径>/setup/xxx_seed_data.py --space <空间>
+
+# 3. 每个本体函数
+dazi onto script publish <项目路径>/functions/xxx_fn.py --space <空间> `
+  --register-function-id <domain>.fn.<name> `
+  --register-platform-category <平台分类名>
+
+# 4. 平台分类挂载（最后一步，类灌数）
+dazi onto script publish <项目路径>/setup/xxx_category_mount.py --space <空间> --type setup
+dazi onto script run --file <项目路径>/setup/xxx_category_mount.py --space <空间>
+
+# 5. 测试参数与验证
+dazi onto function list --space <空间>
+dazi onto function save-test-arguments <ofn_id> --space <空间> --arguments-json-file ...
+dazi onto function run <function_id> --space <空间>
+```
+
+---
+
+## 10. 修改脚本后的重发流程
+
+| 脚本类型 | 操作 |
+| -------- | ---- |
+| setup / data | `script publish` → `script run` |
+| 本体函数 | `script publish`（含 `--register-function-id`）→ `function run` → 参数变更时重做 `save-test-arguments` |
+
+---
+
+## 11. 命令速查
+
+| 目的 | 命令 |
+| ---- | ---- |
+| 发布 setup | `dazi onto script publish <path> --space <空间> --type setup` |
+| 发布 data | `dazi onto script publish <path> --space <空间> --type data` |
+| 发布并注册函数 | `... --register-function-id <id> [--register-platform-category <分类>]` |
+| 执行脚本 | `dazi onto script run --file <path> --space <空间>` |
+| 运行函数 | `dazi onto function run <function_id> --space <空间>`（无参时回退 TEST_ARGUMENTS） |
+| 函数列表 | `dazi onto function list --space <空间> [--json]` |
+| 保存默认参数 | `dazi onto function save-test-arguments --function-id <id> --space <空间> --arguments-json-file <json>` |
+
+---
+
+## 12. 相关文档
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体脚本编写指南](./本体脚本编写指南.md) | 目录、四阶段实施、test_arguments |
+| [本体函数开发指南](./function-guide.md) | 函数模板、`save-test-arguments` |
+| [DaziScript SDK 参考](./dazi_script_sdk_reference.md) | API 与 `s.categories` |
+| [本体开发优化总结](./本体开发优化总结.md) | 表显示名、平台分类、函数四阶段 |
+| [故障排查](../guides/troubleshooting.md) | CLI 环境、401、侧栏空白 |

package/dist/examples/index.json

@@ -1,18 +1,222 @@
 {
-  "version": "3.0.9",
-  "updatedAt": "2026-06-05T18:00:00.000Z",
+  "version": "3.1.1",
+  "updatedAt": "2026-06-07T12:00:00.000Z",
   "examples": [
     {
       "id": "onto/readme",
-      "title": "Onto 示例总览（利润 + 销售）",
+      "title": "Onto 内置示例总览（销售 + 利润 + 设备运营）",
       "category": "onto",
       "file": "onto/README.md"
     },
     {
-      "id": "onto/template/ontology-function",
-      "title": "本体函数脚本模板（标准 main + function_result）",
+      "id": "onto/template/onto-preflight",
+      "title": "Onto 函数 publish 门禁脚本模板",
       "category": "onto-模板",
-      "file": "onto/_templates/ontology_function_template.py"
+      "file": "onto/_templates/onto_preflight.ps1"
+    },
+    {
+      "id": "onto/index",
+      "title": "Onto 示例索引（index.yaml）",
+      "category": "onto",
+      "file": "onto/index.yaml"
+    },
+    {
+      "id": "onto/index-json",
+      "title": "Onto 示例索引（index.json，CLI 机器可读）",
+      "category": "onto",
+      "file": "onto/index.json"
+    },
+    {
+      "id": "onto/sales/readme",
+      "title": "销售示例 · 总览",
+      "category": "onto-销售",
+      "file": "onto/销售示例/README.md"
+    },
+    {
+      "id": "onto/sales/plan",
+      "title": "销售示例 · 规划正文",
+      "category": "onto-销售",
+      "file": "onto/销售示例/plans/规划示例_产品销售本体规划方案.md"
+    },
+    {
+      "id": "onto/profit/readme",
+      "title": "利润示例 · 总览",
+      "category": "onto-利润",
+      "file": "onto/利润示例/README.md"
+    },
+    {
+      "id": "onto/profit/plan",
+      "title": "利润示例 · 规划正文",
+      "category": "onto-利润",
+      "file": "onto/利润示例/plans/规划示例_利润分析本体方案.md"
+    },
+    {
+      "id": "onto/equip-ops/readme",
+      "title": "设备运营 · 总览",
+      "category": "onto-设备运营",
+      "file": "onto/设备运营/README.md"
+    },
+    {
+      "id": "onto/equip-ops/plan",
+      "title": "设备运营 · 规划正文",
+      "category": "onto-设备运营",
+      "file": "onto/设备运营/plans/化工设备运营分析本体方案.md"
+    },
+    {
+      "id": "onto/equip-ops/setup/ontology-init",
+      "title": "设备运营 · 本体初始化",
+      "category": "onto-设备运营-初始化",
+      "file": "onto/设备运营/setup/equip_ops_ontology_init.py"
+    },
+    {
+      "id": "onto/equip-ops/setup/seed-data",
+      "title": "设备运营 · 演示灌数",
+      "category": "onto-设备运营-初始化",
+      "file": "onto/设备运营/setup/equip_ops_seed_data.py"
+    },
+    {
+      "id": "onto/equip-ops/setup/category-mount",
+      "title": "设备运营 · 平台分类挂载",
+      "category": "onto-设备运营-初始化",
+      "file": "onto/设备运营/setup/equip_ops_category_mount.py"
+    },
+    {
+      "id": "onto/equip-ops/function/get-summary",
+      "title": "设备运营 · 运营总览",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_get_summary.py"
+    },
+    {
+      "id": "onto/equip-ops/function/oee",
+      "title": "设备运营 · OEE 分析",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_oee_analysis.py"
+    },
+    {
+      "id": "onto/equip-ops/function/availability",
+      "title": "设备运营 · 可用率分析",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_availability_analysis.py"
+    },
+    {
+      "id": "onto/equip-ops/function/downtime-breakdown",
+      "title": "设备运营 · 停机分解",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_downtime_breakdown.py"
+    },
+    {
+      "id": "onto/equip-ops/function/maintenance-compliance",
+      "title": "设备运营 · 维保合规",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_maintenance_compliance.py"
+    },
+    {
+      "id": "onto/equip-ops/function/energy-intensity",
+      "title": "设备运营 · 能耗强度",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_energy_intensity.py"
+    },
+    {
+      "id": "onto/equip-ops/function/plan-vs-actual",
+      "title": "设备运营 · 计划 vs 实际",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_plan_vs_actual.py"
+    },
+    {
+      "id": "onto/equip-ops/function/unit-comparison",
+      "title": "设备运营 · 装置对比",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_unit_comparison.py"
+    },
+    {
+      "id": "onto/equip-ops/function/top-fault-equipment",
+      "title": "设备运营 · 故障设备 Top N",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_top_fault_equipment.py"
+    },
+    {
+      "id": "onto/equip-ops/function/yoy",
+      "title": "设备运营 · 同比 (YoY)",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_yoy_analysis.py"
+    },
+    {
+      "id": "onto/equip-ops/function/mom",
+      "title": "设备运营 · 环比 (MoM)",
+      "category": "onto-设备运营-函数",
+      "file": "onto/设备运营/functions/equip_ops_fn_mom_analysis.py"
+    },
+    {
+      "id": "onto/equip-ops/function/save-test-arguments",
+      "title": "设备运营 · 批量保存 test_arguments",
+      "category": "onto-设备运营-工具",
+      "file": "onto/设备运营/functions/save_test_arguments.ps1"
+    },
+    {
+      "id": "onto/equip-ops/test-args/get-summary",
+      "title": "test_arguments · equip_ops.fn.get_summary",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.get_summary.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/oee",
+      "title": "test_arguments · equip_ops.fn.oee_analysis",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.oee_analysis.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/availability",
+      "title": "test_arguments · equip_ops.fn.availability_analysis",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.availability_analysis.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/downtime-breakdown",
+      "title": "test_arguments · equip_ops.fn.downtime_breakdown",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.downtime_breakdown.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/maintenance-compliance",
+      "title": "test_arguments · equip_ops.fn.maintenance_compliance",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.maintenance_compliance.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/energy-intensity",
+      "title": "test_arguments · equip_ops.fn.energy_intensity",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.energy_intensity.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/plan-vs-actual",
+      "title": "test_arguments · equip_ops.fn.plan_vs_actual",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.plan_vs_actual.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/unit-comparison",
+      "title": "test_arguments · equip_ops.fn.unit_comparison",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.unit_comparison.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/top-fault-equipment",
+      "title": "test_arguments · equip_ops.fn.top_fault_equipment",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.top_fault_equipment.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/yoy",
+      "title": "test_arguments · equip_ops.fn.yoy_analysis",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.yoy_analysis.json"
+    },
+    {
+      "id": "onto/equip-ops/test-args/mom",
+      "title": "test_arguments · equip_ops.fn.mom_analysis",
+      "category": "onto-设备运营-测试参数",
+      "file": "onto/设备运营/functions/test_arguments/equip_ops.fn.mom_analysis.json"
     },
     {
       "id": "onto/profit/setup/ontology-init",
@@ -26,6 +230,12 @@
       "category": "onto-利润-初始化",
       "file": "onto/利润示例/setup/profit_seed_data.py"
     },
+    {
+      "id": "onto/profit/setup/category-mount",
+      "title": "利润分析 · 平台分类挂载",
+      "category": "onto-利润-初始化",
+      "file": "onto/利润示例/setup/profit_category_mount.py"
+    },
     {
       "id": "onto/profit/function/get-summary",
       "title": "利润分析 · 利润总览",
@@ -128,6 +338,12 @@
       "category": "onto-销售-初始化",
       "file": "onto/销售示例/setup/sales_seed_data.py"
     },
+    {
+      "id": "onto/sales/setup/category-mount",
+      "title": "产品销售 · 平台分类挂载",
+      "category": "onto-销售-初始化",
+      "file": "onto/销售示例/setup/sales_category_mount.py"
+    },
     {
       "id": "onto/sales/function/get-summary",
       "title": "产品销售 · 销售概览",

package/dist/examples/onto/README.md

@@ -1,51 +1,49 @@
 # Onto 内置示例
 
-`dazi examples sync` 后位于 **`资源/examples/onto/`**。复制到业务项目的 **`项目/<业务名>/本体/ontos/<实现名>/`** 对应子目录后再改 `space_id` 与业务字段。
+`dazi examples sync` 后位于 **`资源/examples/onto/`**。每个子目录是**完整本体单元**（与业务 `ontos/<实现>/` 同构）：
 
-## 利润示例（`利润示例/`）
+```text
+<示例名>/
+├── README.md
+├── plans/          ← ★ 规划正文（真理源）
+├── setup/          ← init、seed、category_mount
+└── functions/      ← 本体函数 + test_arguments
+```
+
+**规划 / 脚本前**：须至少阅读 **一个** 示例的 `README.md` + `plans/*.md`。索引见 **`index.yaml`** / **`index.json`**（`dazi examples onto list`）。
 
-| 路径 | 说明 | 规划文档 |
-|------|------|----------|
-| `setup/profit_ontology_init.py` | GL 域 init（科目/分录/预算表、Cube、对象、链接） | [规划示例_利润分析本体方案](../../docs/onto/规划示例_利润分析本体方案.md) |
-| `setup/profit_seed_data.py` | 演示灌数（科目树、成本中心、实际分录、预算） | 同上 |
-| `functions/profit_fn_*.py` | 7 个 GL 分析函数（总览/同比/环比/预实/科目/组织/Top 科目） | 同上 |
-| `functions/test_arguments/*.json` | 各 `profit.fn.*` 默认测试入参 | 规划 §6.5 |
-| `functions/save_test_arguments.ps1` | 批量写入平台 `test_arguments` | 发布函数后执行 |
+## 示例一览
 
-发布后须 **`function run` 验证** → **`save-test-arguments`** 写入默认测试入参（见规划 §6.5）。
+| 目录 | 域 | 规划（plans/） | 函数数 |
+|------|-----|----------------|--------|
+| [销售示例](./销售示例/) | 销售、订单、渠道 | `规划示例_产品销售本体规划方案.md` | 7 |
+| [利润示例](./利润示例/) | GL、科目、预实 | `规划示例_利润分析本体方案.md` | 7 |
+| [设备运营](./设备运营/) | 设备、OEE、停机 | `化工设备运营分析本体方案.md` | 11 |
 
-推荐空间：`space__zlj`（以你的实现单元 README 为准）。
+> 规划正文仅在 `examples/onto/<示例>/plans/`；`dazi examples onto show <id> --plan`。
 
-## 销售示例（`销售示例/`）
+## 复制到业务项目
 
-| 路径 | 说明 | 规划文档 |
-|------|------|----------|
-| `setup/sales_ontology_init.py` | 产品销售 init（表间关系 + Cube + 本体） | [规划示例_产品销售本体规划方案](../../docs/onto/规划示例_产品销售本体规划方案.md) |
-| `setup/sales_seed_data.py` | 演示灌数（产品/销售/维表） | 同上 |
-| `functions/sales_fn_*.py` | 7 个销售分析函数 | 同上 |
-| `functions/test_arguments/*.json` | 各 `function_id` 默认测试入参 | 与规划 §函数清单一致 |
-| `functions/save_test_arguments.ps1` | 批量写入平台 `test_arguments` | 发布函数后执行 |
+```text
+资源/examples/onto/<示例>/setup/*       → 项目/<业务>/本体/ontos/<实现>/setup/
+资源/examples/onto/<示例>/functions/*   → 项目/<业务>/本体/ontos/<实现>/functions/
+```
 
-推荐空间：`space__zlj`（以你的实现单元 README 为准）。
+规划须在本项目 **`plans/` 独立撰写**；示例 `plans/` 仅供只读对照（见快速启动 §0）。
 
-## 模板（`_templates/`）
+## 模板与工具
 
 | 路径 | 说明 |
 |------|------|
-| `_templates/ontology_function_template.py` | **新建本体函数时复制此文件**；`main()` → `return _ontology_fn_body(p)`，禁止 `output.print_json()` |
-
-`dazi examples show onto/template/ontology-function`
-
-## 复制示例
-
-```text
-资源/examples/onto/利润示例/setup/*.py              → 项目/<业务>/本体/ontos/<实现>/setup/
-资源/examples/onto/利润示例/functions/*.py            → 项目/<业务>/本体/ontos/<实现>/functions/
-资源/examples/onto/利润示例/functions/test_arguments/ → .../functions/test_arguments/
-
-资源/examples/onto/销售示例/setup/*.py              → 项目/<业务>/本体/ontos/<实现>/setup/
-资源/examples/onto/销售示例/functions/*.py            → 项目/<业务>/本体/ontos/<实现>/functions/
-资源/examples/onto/销售示例/functions/test_arguments/ → .../functions/test_arguments/
+| [_templates/ontology_function_template.py](./_templates/ontology_function_template.py) | 新建函数结构模板 |
+| [_templates/onto_preflight.ps1](./_templates/onto_preflight.ps1) | 函数数 / publish-preview 门禁 |
+
+```powershell
+dazi examples onto list
+dazi examples onto suggest 设备 OEE
+dazi examples onto show equip-ops --plan
+dazi examples list --category onto
+dazi examples show onto/readme
 ```
 
-侧栏 **帮助 → 示例** 可按分类浏览；`dazi examples list --category onto-利润-函数` 可过滤。
+侧栏 **帮助 → 示例** 可按 `onto-销售-函数`、`onto-设备运营-函数` 等分类浏览。