@dazitech/cli 3.1.0 → 3.1.1

package/dist/docs/onto//346/234/254/344/275/223/345/274/200/345/217/221/344/274/230/345/214/226/346/200/273/347/273/223.md

@@ -1,242 +1,257 @@
-# 本体开发优化总结
-
-**文档 ID**：`onto/dev-optimization-summary`
-
-> **类型**：开发总结（本轮本体 SDK、init 脚本、规划与 TRAE 引导优化）  
-> **同步路径**：`dazi docs sync` → `资源/docs/onto/本体开发优化总结.md`  
-> **前置依据**：[本体命名规范](./本体命名规范_物理表Cube与对象.md)、[本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)
-
----
-
-## 1. 本轮目标
-
-在 本体命名规范基础上，打通 **规划文档 → init 脚本 → 平台侧栏** 三条链路，解决两类长期缺口：
-
-1. **表/列显示名与业务说明**：侧栏、表预览不再只显示物理字段名。
-2. **平台分类与平台分类**：规划中的「类别/分类」列能幂等挂载到 `ads_categories`，侧栏分组与规划一致。
-
----
-
-## 2. 表显示名与列显示名
-
-### 2.1 问题背景
-
-此前 init 脚本普遍使用 `s.tables.register` + `s.tables.sync_columns`：
-
-- `sync_columns` 仅从物理库同步结构；
-- 对未显式传入的列，最多**推断** `display_name`（token 词典），**不会**写入业务 `description`；
-- 规划文档 §3.x 中的「显示名」「说明」列无法落到平台。
-
-### 2.2 解决方案：`TABLE_REGISTRY` + `register_with_meta`
-
-**脚本约定**：init 顶部维护 `TABLE_REGISTRY`，与规划文档 §2.3 表清单、§3.x 字段表 **逐行对齐**。
-
-```python
-TABLE_REGISTRY = {
-    "dim_account": {
-        "display_name": "科目维表",
-        "description": "会计科目主数据",
-        "columns": [
-            {"name": "account_id", "display_name": "科目 ID", "description": "主键"},
-            {"name": "account_code", "display_name": "科目编码"},
-            # ...
-        ],
-    },
-}
-
-for tbl_name, meta in TABLE_REGISTRY.items():
-    s.tables.register_with_meta(
-        table_name=tbl_name,
-        display_name=meta["display_name"],
-        description=meta.get("description"),
-        columns=meta["columns"],
-        force_column_meta=True,  # 规划变更后重跑 init 时刷新列元数据
-    )
-```
-
-**SDK API**：
-
-| API | 作用 |
-|-----|------|
-| `s.tables.register_with_meta(...)` | `register` → `sync_columns` → `set_column_meta` 三步合一（**推荐**） |
-| `s.tables.set_column_meta(table, columns, force=False)` | 单独批量写列 `display_name` / `description` / `business_role` |
-
-**幂等规则**：
-
-- `force_column_meta=False`（默认）：仅补空显示名或与字段名相同的显示名、空 `description`；
-- `force_column_meta=True`：按入参强制刷新（规划修订后重跑 init）。
-
-### 2.3 平台效果
-
-| 元数据字段 | 用户可见处 |
-|-----------|-----------|
-| 表 `display_name` | 侧栏表名、表列表 |
-| 表 `description` | 表详情/预览说明 |
-| 列 `display_name` | 表预览列标题 |
-| 列 `description` | 列说明、规划口径 |
-
-### 2.4 与 `sync_columns` 的分工
-
-| 操作 | 结构同步 | 表显示名 | 列显示名 | 列说明 |
-|------|---------|---------|---------|--------|
-| `sync_columns` | ✅ | 推断（有限） | 推断（有限） | ❌ |
-| `register_with_meta` + `columns` | ✅ | ✅ | ✅ | ✅ |
-
-智能体生成 init 时须使用 `register_with_meta`，勿仅用 `sync_columns` 代替业务元数据。
-
-### 2.5 示例
-
-| 用途 | 路径 |
-|------|------|
-| 利润 init | `资源/examples/onto/利润示例/setup/profit_ontology_init.py` |
-| 利润分类 | `.../setup/profit_category_mount.py` |
-| 销售 init | `资源/examples/onto/销售示例/setup/sales_ontology_init.py` |
-| 销售分类 | `.../setup/sales_category_mount.py` |
-| 规划 | `规划示例_利润分析本体方案.md`、`规划示例_产品销售本体规划方案.md` |
-
----
-
-## 3. 本体分类功能（重点）
-
-> 详细方案见 [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)。
-
-### 3.1 两类分类，一套语言
-
-| 维度 | 规划语义分类 | ads_categories 平台分类 |
-|------|-------------|------------------------|
-| 作用 | 规划自检、命名约束 | 侧栏展示、资源分组 |
-| 对齐 | 平台 `category_name` **=** 平台标准分类中文名 | 禁止自定义别名 |
-| 树结构 | — | 全部 **平级** 挂空间默认根下 |
-
-### 3.2 SDK 入口
-
-```python
-s.categories.ensure_347(kind="table", category="维度表")
-s.categories.assign_table("维度表", "dim_account")
-s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
-```
-
-实现：`sdk_category_taxonomy.py`（字典）、`sdk_category.py`（`CategoryManager`）、`s.categories` 挂载于 `SpaceHandle`。
-
-### 3.3 六类资源
-
-| kind | 示例标准名 |
-|------|-----------|
-| `table` | 时间维、维度表、事实表、桥表、映射表、配置表、汇总表、临时表 |
-| `cube` | 流程型、主体型、对比型、快照型 |
-| `object` | 主数据、事务、分析、参考、配置 |
-| `relation` | 时间关联、主数据关联、层级自关联、预实关联、桥接关联 |
-| `link` | 归属关系、分析归因、层级关系、对比关系 |
-| `function` | 总览分析、趋势分析、结构分析、预实分析、组织分析 |
-
-### 3.4 `CATEGORY_REGISTRY` + `apply_registry`
-
-独立 `setup/*_category_mount.py` 顶部字典，与规划 **附录 B** 逐行一致；在 **init + seed + 全部函数 publish 之后** 调用：
-
-```python
-CATEGORY_REGISTRY = {
-    "table": {"维度表": ["dim_account"], "事实表": ["fact_gl_journal_entry"]},
-    "cube": {"流程型": ["ActualCube"]},
-    "object": {"主数据": ["Account"], "事务": ["JournalEntry"]},
-    "relation": {"时间关联": [("fact_gl_journal_entry", "dim_date")]},
-    "link": {"归属关系": ["entry_belongs_account"]},
-    "function": {"总览分析": ["profit.fn.get_summary"]},
-}
-
-cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
-```
-
-`skip_missing=True` 仅跳过**成员不存在**的挂载；`ensure_347` 使用的分类名必须在 平台分类字典中存在。
-
-### 3.5 内联挂载平台分类（SDK 参数 `category_347=`）
-
-```python
-s.tables.register_with_meta("dim_account", display_name="科目维表", category_347="维度表", ...)
-s.register_cube("ActualCube", ..., category_347="流程型")
-s.onto.define_object_type("Account", name="科目", category_347="主数据")
-```
-
-与 `apply_registry` 幂等可并存。详见 [SDK 参考 §5.6](./dazi_script_sdk_reference.md)。
-
-### 3.6 实施四阶段（init → seed → 函数 → category_mount）
-
-| 阶段 | 内容 |
-|------|------|
-| B init | 建表、元数据、关系、Cube、本体对象/链接（**不含**分类挂载） |
-| C seed | `*_seed_data.py` 灌数 |
-| D 函数 | `publish --register-function-id`（每个 `functions/*.py`） |
-| E 分类 | `*_category_mount.py` 全量 `apply_registry`（**最后**，类灌数）；或 `--register-platform-category` |
-
-**TRAE 常见问题**：规划列了 function_id 但文件未齐 / 未 publish → `function list` 看不到；补发函数后**只重跑 category_mount**，**勿**为重挂分类重跑完整 init。
-
-**推荐命令序列**：见 [脚本运行常见错误处理](./脚本运行常见错误处理.md) §6、§8。
-
-### 3.7 规划自检（命名规范 §8.4 扩展 6a–6e 平台分类）
-
-| # | 检查项 |
-|---|--------|
-| 6a | 附录 B 与 `*_category_mount.py` `CATEGORY_REGISTRY` 一致 |
-| 6b | 每张表标注 平台标准分类中文名 |
-| 6c | 每个 Cube 标注流程型/主体型/对比型/快照型 |
-| 6d | 对象/链接/关系扩展类别与字典一致 |
-| 6e | 已 run `*_category_mount.py`；侧栏与平台标准分类一致 |
-
-### 3.8 缺陷修复：表类中文名索引
-
-`apply_registry` 报 `平台分类字典中不存在分类: kind='table', category='维度表'` 时，根因是 `TABLE_CATEGORIES` 曾缺中文 key（非脚本 UTF-8 编码问题）。已补充中文名索引与 `resolve_category_meta` 反查兜底；须部署新版 backend。
-
----
-
-## 4. TRAE / 智能体引导
-
-| 改动 | 说明 |
-|------|------|
-| 快速启动 §0 任务模式 | 规划 vs 实现；实施顺序含 `category_mount` |
-| `onto/planning-design` 提示词 | 阶段门禁、附录 B、category_mount 放最后 |
-| `onto/script-publish-run` 提示词 | §4.5 平台分类挂载 |
-| 本体规划指南 | 五阶段实施顺序、平台分类列 |
-| 脚本运行常见错误处理 | TRAE 踩坑与推荐命令 |
-| SDK 参考 §5.6 | `categories` 与 `category_347` |
-
----
-
-## 5. 部署与验收
-
-**测试/生产 backend 须包含**（版本低于下列能力时，init 或 category_mount 会报错）：
-
-| 能力 | 说明 |
-|------|------|
-| 表元数据注册 | `s.tables.register_with_meta` |
-| 平台分类挂载 | `s.categories`、`apply_registry` |
-| 按资源类挂载 | `apply_registry(..., kinds=[...])` |
-| 发布时挂函数分类 | API `register_platform_category` / CLI `--register-platform-category` |
-| 表类中文名索引 | 平台分类字典支持「维度表」「事实表」等标准名 |
-
-**验收**：
-
-1. 侧栏表名、列标题与规划显示名一致。
-2. 侧栏分类名为平台标准分类中文名（含 function 段）。
-3. init / seed 重跑幂等；`category_mount` 重跑幂等。
-4. `CATEGORY_REGISTRY` 与附录 B 一致；`function list` 条数与规划一致。
-
----
-
-## 6. 相关文档
-
-| 文档 | 说明 |
-| ---- | ---- |
-| [本体本体命名规范](./本体命名规范_物理表Cube与对象.md) | 命名与分类真理源 |
-| [本体本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md) | 分类 SDK 设计 |
-| [本体脚本编写指南](./本体脚本编写指南.md) | init / seed / category_mount |
-| [脚本运行常见错误处理](./脚本运行常见错误处理.md) | TRAE 踩坑 |
-| [dazi_script_sdk_reference](./dazi_script_sdk_reference.md) | API 参考 |
-
----
-
-**变更记录**
-
-| 日期 | 说明 |
-| ---- | ---- |
-| 2026-06-06 | 首版 |
-| 2026-06-06 | 增补函数注册门禁与 TRAE 处理说明 |
-| 2026-06-06 | 分类挂载迁至 `*_category_mount.py`；init 不含 apply_registry |
+# 本体开发优化总结
+
+**文档 ID**：`onto/dev-optimization-summary`
+
+> **类型**：开发总结（本轮本体 SDK、init 脚本、规划与 TRAE 引导优化）  
+> **同步路径**：`dazi docs sync` → `资源/docs/onto/本体开发优化总结.md`  
+> **前置依据**：[本体命名规范](./本体命名规范_物理表Cube与对象.md)、[本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)
+
+---
+
+## 1. 本轮目标
+
+在 本体命名规范基础上，打通 **规划文档 → init 脚本 → 平台侧栏** 三条链路，解决两类长期缺口：
+
+1. **表/列显示名与业务说明**：侧栏、表预览不再只显示物理字段名。
+2. **平台分类与平台分类**：规划中的「类别/分类」列能幂等挂载到 `ads_categories`，侧栏分组与规划一致。
+
+---
+
+## 2. 表显示名与列显示名
+
+### 2.1 问题背景
+
+此前 init 脚本普遍使用 `s.tables.register` + `s.tables.sync_columns`：
+
+- `sync_columns` 仅从物理库同步结构；
+- 对未显式传入的列，最多**推断** `display_name`（token 词典），**不会**写入业务 `description`；
+- 规划文档 §3.x 中的「显示名」「说明」列无法落到平台。
+
+### 2.2 解决方案：`TABLE_REGISTRY` + `register_with_meta`
+
+**脚本约定**：init 顶部维护 `TABLE_REGISTRY`，与规划文档 §2.3 表清单、§3.x 字段表 **逐行对齐**。
+
+```python
+TABLE_REGISTRY = {
+    "dim_account": {
+        "display_name": "科目维表",
+        "description": "会计科目主数据",
+        "columns": [
+            {"name": "account_id", "display_name": "科目 ID", "description": "主键"},
+            {"name": "account_code", "display_name": "科目编码"},
+            # ...
+        ],
+    },
+}
+
+for tbl_name, meta in TABLE_REGISTRY.items():
+    s.tables.register_with_meta(
+        table_name=tbl_name,
+        display_name=meta["display_name"],
+        description=meta.get("description"),
+        columns=meta["columns"],
+        force_column_meta=True,  # 规划变更后重跑 init 时刷新列元数据
+    )
+```
+
+**SDK API**：
+
+| API | 作用 |
+|-----|------|
+| `s.tables.register_with_meta(...)` | `register` → `sync_columns` → `set_column_meta` 三步合一（**推荐**） |
+| `s.tables.set_column_meta(table, columns, force=False)` | 单独批量写列 `display_name` / `description` / `business_role` |
+
+**幂等规则**：
+
+- `force_column_meta=False`（默认）：仅补空显示名或与字段名相同的显示名、空 `description`；
+- `force_column_meta=True`：按入参强制刷新（规划修订后重跑 init）。
+
+### 2.3 平台效果
+
+| 元数据字段 | 用户可见处 |
+|-----------|-----------|
+| 表 `display_name` | 侧栏表名、表列表 |
+| 表 `description` | 表详情/预览说明 |
+| 列 `display_name` | 表预览列标题 |
+| 列 `description` | 列说明、规划口径 |
+
+### 2.4 与 `sync_columns` 的分工
+
+| 操作 | 结构同步 | 表显示名 | 列显示名 | 列说明 |
+|------|---------|---------|---------|--------|
+| `sync_columns` | ✅ | 推断（有限） | 推断（有限） | ❌ |
+| `register_with_meta` + `columns` | ✅ | ✅ | ✅ | ✅ |
+
+智能体生成 init 时须使用 `register_with_meta`，勿仅用 `sync_columns` 代替业务元数据。
+
+### 2.5 示例
+
+| 用途 | 路径 |
+|------|------|
+| 利润 init | `资源/examples/onto/利润示例/setup/profit_ontology_init.py` |
+| 利润分类 | `.../setup/profit_category_mount.py` |
+| 销售 init | `资源/examples/onto/销售示例/setup/sales_ontology_init.py` |
+| 销售分类 | `.../setup/sales_category_mount.py` |
+| 规划 | `资源/examples/onto/*/plans/*.md`（索引 `index.json` · `dazi examples onto list`） |
+
+---
+
+## 3. 本体分类功能（重点）
+
+> 详细方案见 [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)。
+
+### 3.1 两类分类，一套语言
+
+| 维度 | 规划语义分类 | ads_categories 平台分类 |
+|------|-------------|------------------------|
+| 作用 | 规划自检、命名约束 | 侧栏展示、资源分组 |
+| 对齐 | 平台 `category_name` **=** 平台标准分类中文名 | 禁止自定义别名 |
+| 树结构 | — | 全部 **平级** 挂空间默认根下 |
+
+### 3.2 SDK 入口
+
+```python
+s.categories.ensure_347(kind="table", category="维度表")
+s.categories.assign_table("维度表", "dim_account")
+s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+实现：`sdk_category_taxonomy.py`（字典）、`sdk_category.py`（`CategoryManager`）、`s.categories` 挂载于 `SpaceHandle`。
+
+### 3.3 六类资源
+
+| kind | 示例标准名 |
+|------|-----------|
+| `table` | 时间维、维度表、事实表、桥表、映射表、配置表、汇总表、临时表 |
+| `cube` | 流程型、主体型、对比型、快照型 |
+| `object` | 主数据、事务、分析、参考、配置 |
+| `relation` | 时间关联、主数据关联、层级自关联、预实关联、桥接关联 |
+| `link` | 归属关系、分析归因、层级关系、对比关系 |
+| `function` | 总览分析、趋势分析、结构分析、预实分析、组织分析 |
+
+### 3.4 `CATEGORY_REGISTRY` + `apply_registry`
+
+独立 `setup/*_category_mount.py` 顶部字典，与规划 **附录 B** 逐行一致；在 **init + seed + 全部函数 publish 之后** 调用：
+
+```python
+CATEGORY_REGISTRY = {
+    "table": {"维度表": ["dim_account"], "事实表": ["fact_gl_journal_entry"]},
+    "cube": {"流程型": ["ActualCube"]},
+    "object": {"主数据": ["Account"], "事务": ["JournalEntry"]},
+    "relation": {"时间关联": [("fact_gl_journal_entry", "dim_date")]},
+    "link": {"归属关系": ["entry_belongs_account"]},
+    "function": {"总览分析": ["profit.fn.get_summary"]},
+}
+
+cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+`skip_missing=True` 仅跳过**成员不存在**的挂载；`ensure_347` 使用的分类名必须在 平台分类字典中存在。
+
+### 3.5 内联挂载平台分类（SDK 参数 `category_347=`）
+
+```python
+s.tables.register_with_meta("dim_account", display_name="科目维表", category_347="维度表", ...)
+s.register_cube("ActualCube", ..., category_347="流程型")
+s.onto.define_object_type("Account", name="科目", category_347="主数据")
+```
+
+与 `apply_registry` 幂等可并存。详见 [SDK 参考 §5.6](./dazi_script_sdk_reference.md)。
+
+### 3.6 实施四阶段（init → seed → 函数 → category_mount）
+
+| 阶段 | 内容 |
+|------|------|
+| B init | 建表、元数据、关系、Cube、本体对象/链接（**不含**分类挂载） |
+| C seed | `*_seed_data.py` 灌数 |
+| D 函数 | `publish --register-function-id`（每个 `functions/*.py`） |
+| E 分类 | `*_category_mount.py` 全量 `apply_registry`（**最后**，类灌数）；或 `--register-platform-category` |
+
+**TRAE 常见问题**：规划列了 function_id 但文件未齐 / 未 publish → `function list` 看不到；补发函数后**只重跑 category_mount**，**勿**为重挂分类重跑完整 init。
+
+**推荐命令序列**：见 [脚本运行常见错误处理](./脚本运行常见错误处理.md) §6、§8。
+
+### 3.7 规划自检（命名规范 §8.4 扩展 6a–6e 平台分类）
+
+| # | 检查项 |
+|---|--------|
+| 6a | 附录 B 与 `*_category_mount.py` `CATEGORY_REGISTRY` 一致 |
+| 6b | 每张表标注 平台标准分类中文名 |
+| 6c | 每个 Cube 标注流程型/主体型/对比型/快照型 |
+| 6d | 对象/链接/关系扩展类别与字典一致 |
+| 6e | 已 run `*_category_mount.py`；侧栏与平台标准分类一致 |
+
+### 3.8 缺陷修复：表类中文名索引
+
+`apply_registry` 报 `平台分类字典中不存在分类: kind='table', category='维度表'` 时，根因是 `TABLE_CATEGORIES` 曾缺中文 key（非脚本 UTF-8 编码问题）。已补充中文名索引与 `resolve_category_meta` 反查兜底；须部署新版 backend。
+
+---
+
+## 4. TRAE / 智能体引导
+
+| 改动 | 说明 |
+|------|------|
+| 快速启动 §0 任务模式 | 规划 vs 实现；实施顺序含 `category_mount` |
+| `onto/planning-design` 提示词 | 阶段门禁、附录 B、category_mount 放最后 |
+| `onto/script-publish-run` 提示词 | §4.5 平台分类挂载 |
+| 本体规划指南 | 五阶段实施顺序、平台分类列 |
+| 脚本运行常见错误处理 | TRAE 踩坑与推荐命令 |
+| SDK 参考 §5.6 | `categories` 与 `category_347` |
+
+---
+
+## 5. 部署与验收
+
+**测试/生产 backend 须包含**（版本低于下列能力时，init 或 category_mount 会报错）：
+
+| 能力 | 说明 |
+|------|------|
+| 表元数据注册 | `s.tables.register_with_meta` |
+| 平台分类挂载 | `s.categories`、`apply_registry` |
+| 按资源类挂载 | `apply_registry(..., kinds=[...])` |
+| 发布时挂函数分类 | API `register_platform_category` / CLI `--register-platform-category` |
+| 表类中文名索引 | 平台分类字典支持「维度表」「事实表」等标准名 |
+
+**验收**：
+
+1. 侧栏表名、列标题与规划显示名一致。
+2. 侧栏分类名为平台标准分类中文名（含 function 段）。
+3. init / seed 重跑幂等；`category_mount` 重跑幂等。
+4. `CATEGORY_REGISTRY` 与附录 B 一致；`function list` 条数与规划一致。
+
+---
+
+## 6. 相关文档
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体本体命名规范](./本体命名规范_物理表Cube与对象.md) | 命名与分类真理源 |
+| [本体本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md) | 分类 SDK 设计 |
+| [本体脚本编写指南](./本体脚本编写指南.md) | init / seed / category_mount |
+| [脚本运行常见错误处理](./脚本运行常见错误处理.md) | TRAE 踩坑 |
+| [dazi_script_sdk_reference](./dazi_script_sdk_reference.md) | API 参考 |
+
+---
+
+**变更记录**
+
+| 日期 | 说明 |
+| ---- | ---- |
+| 2026-06-06 | 首版 |
+| 2026-06-06 | 增补函数注册门禁与 TRAE 处理说明 |
+| 2026-06-06 | 分类挂载迁至 `*_category_mount.py`；init 不含 apply_registry |
+| 2026-06-07 | **§352**：规划示例迁至 `examples/onto/*/plans/`；已删除 `docs/onto/规划示例_*.md` stub |
+
+---
+
+## 7. 351 补充：函数链与智能体门禁（2026-06-07）
+
+详见内部文档 `351-Cursor智能体本体开发优化总结.md`。客户环境要点：
+
+| 能力 | 用法 |
+|------|------|
+| 首次 function run | 可省略 `--params`，回退脚本 `TEST_ARGUMENTS` |
+| save-test-arguments | `dazi onto function save-test-arguments --function-id domain.fn.xxx ...` |
+| 函数预检 | `dazi onto script publish-preview functions/xxx.py --space <空间>` |
+| 实施门禁 | 复制 `资源/examples/onto/_templates/onto_preflight.ps1` 到 `functions/` |
+| init 检查 | [脚本运行常见错误处理 §1.2](./脚本运行常见错误处理.md) 五条条目 |

package/dist/docs/onto//346/234/254/344/275/223/350/204/232/346/234/254/347/274/226/345/206/231/346/214/207/345/215/227.md

@@ -12,7 +12,7 @@
 
 | 文档 | 说明 |
 | ---- | ---- |
-| **[脚本运行常见错误处理](./脚本运行常见错误处理.md)** | setup API 误用、`query_one` 聚合陷阱、**函数禁止 `output.print_json()`**、CLI 参数（`function run` 不支持 JSON 文件、`save-test-arguments` 须 `ofn_xxx`） |
+| **[脚本运行常见错误处理](./脚本运行常见错误处理.md)** | setup API 误用、bind_source 约束、`query_one` 聚合陷阱、**函数禁止 `output.print_json()`**、CLI（`function run` 回退 TEST_ARGUMENTS、`save-test-arguments --function-id`） |
 
 `dazi docs show onto/script-run-troubleshooting` · 智能体另见提示词 **`onto/script-publish-run`**。
 
@@ -39,14 +39,15 @@
             └── *.py
 ```
 
-内置示例位于 **`资源/examples/onto/`**（`dazi examples sync`）。**须 `plans/` 定稿后**再借鉴或复制 init/seed（见快速启动 §0、§3；规划任务用提示词 **`onto/planning-design`**）。
+内置示例位于 **`资源/examples/onto/`**（`dazi examples sync`）。**规划前 / 脚本前须至少阅读一个完整示例**（`README.md` + `plans/*.md`）。**须 `plans/` 定稿后**再借鉴或复制 init/seed（见快速启动 §0、§3；规划任务用提示词 **`onto/planning-design`**）。
 
-| 示例包 | 目录 | 规划文档 | 主要内容 |
-|--------|------|----------|----------|
-| **销售示例**（推荐） | `onto/销售示例/` | [规划示例_产品销售本体规划方案](./规划示例_产品销售本体规划方案.md) | `setup/sales_ontology_init.py`、`sales_seed_data.py`、7 个 `sales_fn_*.py`、`test_arguments/` |
-| **利润示例**（补充） | `onto/利润示例/` | [规划示例_利润分析本体方案](./规划示例_利润分析本体方案.md) | `setup/profit_ontology_init.py`、`profit_seed_data.py`、7 个 `profit_fn_*.py`、`test_arguments/` |
+| 示例 | 目录 | 规划（plans/） | 主要内容 |
+|------|------|----------------|----------|
+| 产品销售 | `onto/销售示例/` | `plans/规划示例_产品销售本体规划方案.md` | init、seed、7 函数、category_mount |
+| 利润 GL | `onto/利润示例/` | `plans/规划示例_利润分析本体方案.md` | 同上 |
+| 设备运营 | `onto/设备运营/` | `plans/化工设备运营分析本体方案.md` | 11 函数、OEE 等 |
 
-总览说明：`资源/examples/onto/README.md`（`dazi examples show onto/readme`）。
+索引：`资源/examples/onto/index.json` · 总览：`dazi examples show onto/readme` · 路由：`dazi examples onto suggest <关键词>`
 
 > **不再使用** 历史路径 `onto/<space_id>/editorial/`、`editorial/functions/`、`项目/onto_<名称>/脚本/` 等作为本地开发约定。
 
@@ -96,7 +97,7 @@ s.tables.add_relationship(
 
 ### 表注册 `TABLE_REGISTRY` + `register_with_meta`
 
-init 脚本顶部维护与规划文档对齐的 `TABLE_REGISTRY`（项目内 `plans/*.md` 或内置 [规划示例](./规划示例_产品销售本体规划方案.md)），步骤 2 统一调用：
+init 脚本顶部维护与规划文档对齐的 `TABLE_REGISTRY`（本项目 `plans/*.md` 或示例 `资源/examples/onto/<名>/plans/*.md`），步骤 2 统一调用：
 
 ```python
 TABLE_REGISTRY = {
@@ -237,7 +238,7 @@ dazi onto function run sales.fn.get_summary --space <space-id> --params '{}'
 
 仅 `publish` + `function run` **不会**自动写入测试参数；侧栏 **Onto → 运行函数** 依赖函数定义上的 **`test_arguments`** 预填表单。
 
-> **CLI 易错点**：`function run` **不支持** `--arguments-json-file`；`save-test-arguments` 须用 **`ofn_xxx` 内部 id** 而非 `function_id` 字符串。完整说明见 [脚本运行常见错误处理](./脚本运行常见错误处理.md)。
+> **CLI 要点**：`function run` 无 `--params` 时回退 `TEST_ARGUMENTS`；`save-test-arguments` 推荐 **`--function-id`**（亦可用 `ofn_xxx`）。完整说明见 [脚本运行常见错误处理](./脚本运行常见错误处理.md)。
 
 **本地约定（与规划文档 § 函数 / test_arguments 一致）**：
 
@@ -268,7 +269,7 @@ dazi onto function run sales.fn.get_summary --space <space-id> --params '{}'
 单条保存（**须用平台内部 id `ofn_xxx`**，先 `dazi onto function list --space <space-id>` 查看；直接传 `sales.fn.xxx` 可能 **404**）：
 
 ```powershell
-dazi onto function save-test-arguments ofn_156a399fbe0e4636 --space <space-id> `
+dazi onto function save-test-arguments --function-id sales.fn.get_summary --space <space-id> `
   --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/sales.fn.get_summary.json
 ```
 
@@ -333,7 +334,6 @@ dazi onto script dedupe --space <space-id> --yes
 - [本体规划指南](./本体规划指南.md)
 - [本体函数开发指南](./function-guide.md)
 - [本体动作开发](./action-guide.md)
-- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
-- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [内置示例总览](../../examples/onto/README.md)（`资源/examples/onto/`）
 - [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
 - [脚本运行常见错误处理](./脚本运行常见错误处理.md)