npm - @dazitech/cli - Versions diffs - 3.0.9 → 3.1.0 - Mend

@dazitech/cli 3.0.9 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

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 CHANGED Viewed

@@ -1,311 +1,339 @@
-# 本体脚本编写指南
-**文档 ID**: `onto/script-authoring`
-本文说明本体实现单元内 **Python 脚本的目录、类型、发布与运行**（原独立的「脚本开发与发布」已与本文合并）。
-> 终端命令均在 **`dazi-work` 根目录**执行：`dazi ...`（见 [CLI 调用约定](../guides/cli-invocation.md)）。
-## 执行脚本前必读（强制）
-在终端执行 **`dazi onto script publish` / `script run` / `function run` / `save-test-arguments`** 之前，**必须**阅读：
-| 文档 | 说明 |
-| ---- | ---- |
-| **[脚本运行纠错（商务成本实录）](./脚本运行纠错_商务成本方案开发过程.md)** | setup API 误用、`query_one` 聚合陷阱、**函数禁止 `output.print_json()`**、CLI 参数（`function run` 不支持 JSON 文件、`save-test-arguments` 须 `ofn_xxx`） |
-`dazi docs show onto/script-run-troubleshooting` · 智能体另见提示词 **`onto/script-publish-run`**。
-## 环境
-- 推荐 **Python 3.10+**
-- 脚本目录：**`<工作区根>/项目/<业务名>/本体/ontos/<实现名>/setup/`** 与 **`functions/`**（新建本体实现时自动创建）
-- 扩展默认脚本语言：`dazi.onto.defaultScriptLang` = `python`
-- 平台 API：`dazi.serverUrl`；登录：`dazi auth login` / `dazi auth set-token`
-## 目录约定
-```text
-<工作区根>/项目/<业务名>/              ← 业务项目根
-└── 本体/
-    └── ontos/<实现名>/                ← 本体实现单元；README 含 space_id
-        ├── README.md
-        ├── 快速启动_<实现名>.md
-        ├── plans/                     ← 规划阶段 Markdown 产出
-        ├── setup/                     ← 初始化、灌数脚本
-        └── functions/                 ← 本体函数、动作脚本
-            ├── test_arguments/        ← 各 function_id 的 test_arguments JSON
-            ├── save_test_arguments.ps1  ← 可选：批量写入平台（推荐）
-            └── *.py
-```
-参考示例（可复制后修改）位于 **`资源/examples/onto/`**，按 **利润示例**、**销售示例** 两套打包（侧栏 **帮助 → 示例** 或 `dazi examples sync`）。
-| 示例包 | 目录 | 规划文档 | 主要内容 |
-|--------|------|----------|----------|
-| **销售示例**（推荐） | `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/` |
-总览说明：`资源/examples/onto/README.md`（`dazi examples show onto/readme`）。
-> **不再使用** 历史路径 `onto/<space_id>/editorial/`、`editorial/functions/`、`项目/onto_<名称>/脚本/` 等作为本地开发约定。
-## 必读规范（DaziScript）
-编写 `setup/`、`functions/` 下 `.py` 前请阅读：
-| 文档                                                                | 说明                                                                   |
-| ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **[DaziScript SDK 参考](./dazi_script_sdk_reference.md)**           | `space` / `s.sql` / `s.onto` / `s.tables` / Cube 等 API 与本体落库顺序 |
-| **[DaziScript 灌数脚本编写指南](./dazi_script_seed_data_guide.md)** | 造数、补数、`insert_rows` 与 ClickHouse `INSERT` 约束、幂等约定        |
-同步到工作区：`dazi docs sync` → `资源/docs/onto/`。
-## 初始化脚本标准顺序（setup）
-`*_ontology_init.py` 建议按以下顺序执行（与 [本体规划指南](./本体规划指南.md) 物理层 + 表间关系章节一致）：
-| 步骤 | 内容 | API |
-| ---- | ---- | --- |
-| 1 | 建表 | `s.sql.execute(CREATE TABLE ...)` |
-| 2 | 注册表 | `s.tables.register_with_meta`（含表/列 `display_name`、`description`） |
-| 3 | **注册表间关系** | `s.tables.add_relationship(...)` |
-| 4 | 注册 Cube / 派生度量 | `s.register_cube`、`s.upsert_derived_measures` |
-| 5 | 本体对象 / 属性 / 链接 | `s.onto.define_*`、`s.sync_metric_refs` |
-| 6 | **347 对齐分类** | `s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)` |
-### 表间关系 `s.tables.add_relationship`
-在 **表 register 完成之后、Cube 注册之前** 调用；**幂等**，可重复执行 init。
-```python
-s.tables.add_relationship(
-    from_table="sales_order_fact",       # 通常为事实表
-    to_table="product_master",           # 维表
-    join_sql="sales_order_fact.product_id = product_master.product_id",
-    join_keys=[{"from": "product_id", "to": "product_id"}],
-    relationship_type="many_to_one",     # 默认 many_to_one
-    description="销售订单行关联产品主数据",
-)
-```
-验收：`dazi onto space get <space-id>` 中 **`relationship_count`** 与规划条数一致；侧栏 **数据资源 → 表间关系** 可见。
-> **勿与** `s.onto.define_link_type` 混淆：前者写数据空间元数据，后者写业务对象语义链接，**两者都需实施**。
-### 表注册 `TABLE_REGISTRY` + `register_with_meta`
-init 脚本顶部维护与规划文档对齐的 `TABLE_REGISTRY`（项目内 `plans/*.md` 或内置 [规划示例](./规划示例_产品销售本体规划方案.md)），步骤 2 统一调用：
-```python
-TABLE_REGISTRY = {
-    "fact_sales_order_line": {
-        "display_name": "销售订单行事实表",
-        "description": "订单行粒度销售流水",
-        "columns": [
-            {"name": "order_id", "display_name": "订单 ID"},
-            {"name": "date_key", "display_name": "日期键", "description": "关联 dim_date"},
-            # ...
-        ],
-    },
-}
-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 时刷新列元数据
-    )
-```
-- **显示名** → 侧栏与表预览列标题（`display_name`）
-- **说明** → 业务口径、FK、冗余原因（`description`）；`sync_columns` **不会**自动写入
-- 参考：`资源/examples/onto/利润示例/setup/profit_ontology_init.py`、`销售示例/setup/sales_ontology_init.py`
-### 分类注册 `CATEGORY_REGISTRY` + `apply_registry`
-init 脚本顶部维护与规划附录 B 对齐的 `CATEGORY_REGISTRY`（分类名必须是 [347](./本体命名规范_物理表Cube与对象.md) 标准中文名），**所有资源注册完成后**调用：
-```python
-cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
-```
-- 6 类资源平级挂载：`table` / `cube` / `object` / `relation` / `link` / `function`
-- 函数类资源若 init 未 `register_function`，须 `skip_missing=True`
-- 可选：注册 API 传 `category_347="维度表"` 等即时挂载（与 `apply_registry` 幂等可并存）
-- 详见 [349 方案](./本体分类规划与SDK扩展方案.md)、[SDK 参考 §5.6](./dazi_script_sdk_reference.md)
-## 脚本类型
-类型由 **发布命令参数** 区分；初始化与灌数放 `setup/`，本体函数与动作放 `functions/`：
-| 类型                | 路径约定                                                          | 说明                                               |
-| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
-| `ontology_function` | `项目/<业务名>/本体/ontos/<实现名>/functions/**/*.py`             | **必须**带 `--register-function-id` 发布（见下节） |
-| `ontology_action`   | `项目/<业务名>/本体/ontos/<实现名>/functions/**/*.py`             | 发布时加 `--register-action-id` 等 Action 参数     |
-| `data_script`       | `项目/<业务名>/本体/ontos/<实现名>/setup/**/*.py`                 | 普通 `script publish`，不注册函数/动作             |
-`<space-id>` 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取，勿手写错空间。
-## 发布预检
-```powershell
-dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space-id>
-```
-## 发布脚本
-> **勿用** 独立命令 `dazi-onto`（v3 未安装到 PATH）。统一使用 **`dazi onto ...`**。
-### 本体函数：**必须注册**，否则侧栏与测试看不到
-`functions/`（或规划中的本体函数 `.py`）**不能**只执行「普通 publish」：
-**新建函数**：复制 `资源/examples/onto/_templates/ontology_function_template.py`（`dazi examples show onto/template/ontology-function`），或参考 `销售示例/functions/sales_fn_get_summary.py`。`main()` **无参**，业务写在 `_ontology_fn_body(p)`，末尾 **`return _ontology_fn_body(p)`** — **禁止** `output.print_json()`（见 [脚本运行纠错 §3](./脚本运行纠错_商务成本方案开发过程.md#3-函数输出方式错误outputprint_json)）。
-| 仅 `script publish`（无 `--register-function-id`） | 带 `--register-function-id` 发布             |
-| -------------------------------------------------- | -------------------------------------------- |
-| 脚本代码进入 `ads_scripts`                         | 同上 **且** 写入 `ontology_function_defs`    |
-| **不会**出现在 **Onto → 函数列表**                 | 出现在函数列表，可 **运行函数** / 工作台测试 |
-| `dazi onto function run <id>` **找不到**           | `function run`、侧栏运行可用                 |
-因此：**首次发布本体函数时，命令里必须包含 `--register-function-id`**，且 `function_id` 与规划文档、脚本内约定 **完全一致**（建议带点号命名空间，如 `sales.fn.get_summary`，勿随意简写为 `get_summary`）。
-智能体（TRAE 等）实施自检：
-1. 发布命令是否包含 `--register-function-id`？
-2. 发布输出是否含 `functionId: xxx` / `function_registration.ok`？
-3. `dazi onto function list --space <space-id>` 能否看到该 `function_id`？
-任一步不满足 → **视为未注册**，需重新 publish（带注册参数），不要仅 `script run` 以为函数已可用。
-```powershell
-# 初始化 / 灌数：普通发布即可（不要加 register-function-id）
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/xxx_ontology_init.py --space <space-id> --type setup
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/xxx_seed_data.py --space <space-id> --type data
-# ★ 本体函数：必须注册（示例）
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/get_summary.py `
-  --space <space-id> `
-  --register-function-id sales.fn.get_summary
-# 发布并注册为本体动作（示例）
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_action.py `
-  --space <space-id> `
-  --register-action-id my_action_code `
-  --register-action-permission-tag "finance.write"
-```
-发布后验证：
-```powershell
-dazi onto function list --space <space-id>
-dazi onto function run sales.fn.get_summary --space <space-id> --params '{}'
-```
-### 函数测试参数（test_arguments，**发布后必做**）
-仅 `publish` + `function run` **不会**自动写入测试参数；侧栏 **Onto → 运行函数** 依赖函数定义上的 **`test_arguments`** 预填表单。
-> **CLI 易错点**：`function run` **不支持** `--arguments-json-file`；`save-test-arguments` 须用 **`ofn_xxx` 内部 id** 而非 `function_id` 字符串。完整说明见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md)。
-**本地约定（与规划文档 § 函数 / test_arguments 一致）**：
-1. 每个函数一份 JSON：`functions/test_arguments/<function_id>.json`
-2. 脚本内同名常量 `TEST_ARGUMENTS`（与 JSON **保持同步**）
-3. 函数 `main()` 通过 `ctx.params` 读取的键名 = JSON 内 **`arguments`** 对象的键名
-**JSON 格式**（与平台函数定义一致）：
-```json
-{
-  "v": 1,
-  "arguments": {
-    "start_date": "2025-01-01",
-    "end_date": "2026-06-30"
-  },
-  "object_type_code": "SalesAnalysis"
-}
-```
-**保存到平台**（函数 `run` 验证通过后）：
-```powershell
-# 推荐：批量脚本（解析 function list，用内部 id ofn_xxx 调用 PATCH）
-.\项目/<业务名>/本体/ontos/<实现名>/functions/save_test_arguments.ps1
-```
-单条保存（**须用平台内部 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> `
-  --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/sales.fn.get_summary.json
-```
-**PowerShell 传 `--params` 易丢引号**；测试运行可省略 `--params`（用 `{}`），或：
-```powershell
-$env:DAZI_PARAMS='{"start_date":"2025-01-01","end_date":"2026-06-30"}'
-dazi onto function run sales.fn.get_summary --space <space-id> --params $env:DAZI_PARAMS
-```
-验收：`dazi onto function get <function_id> --space <space-id>` 中 **`test_arguments` 非 null**，且 `arguments` 与 JSON 一致。
-亦可在 VS Code 侧栏 **Onto 本体 → 发布函数** 发布（须填写/绑定 **function_id**）；发布后在 **函数** 节点下应能看到该函数。
-函数生命周期与 `update-code` 详见 **[本体函数开发指南](./function-guide.md)**。给 TRAE 的完整命令模板见内置提示词 **`onto/script-publish-run`**（`dazi prompt sync` 后位于 `资源/prompts/onto/`）。
-## 从平台拉取脚本（可选）
-若需将平台上已有脚本拉回本地对照（**非**日常开发主路径）：
-```powershell
-# 推荐：落盘到本体实现目录（按 setup / functions 分子目录）
-dazi onto script sync --space <space-id> --target-dir 项目/<业务名>/本体/ontos/<实现名>
-dazi onto script sync --space <space-id> --type ontology_function --target-dir 项目/<业务名>/本体/ontos/<实现名>
-dazi onto script sync --space <space-id> --dry-run --target-dir 项目/<业务名>/本体/ontos/<实现名>
-# legacy：onto/<space-id>/scripts/（非日常开发入口）
-dazi onto script sync --space <space-id>
-```
-拉取目标目录以 CLI 为准；**新建与修改仍以 `项目/<业务名>/本体/ontos/<实现名>/setup/` 与 `functions/` 为准**。
-## 清理重复脚本
-```powershell
-dazi onto script dedupe --space <space-id> --dry-run
-dazi onto script dedupe --space <space-id> --yes
-```
-## 编写建议
-1. 先阅读 `快速启动_<实现名>.md` 与 `README.md` 中的**数据空间 ID**，并对照 `plans/` 中**表间关系**与**函数 test_arguments** 章节
-2. 在 `setup/`、`functions/` 中按模块拆分 `.py`（初始化、灌数、本体函数可分机文件）
-3. **init 脚本**必须包含 `s.tables.add_relationship`（若规划有表间关系）
-4. 发布与运行：`dazi onto script publish`（**函数必须** `--register-function-id`）→ `function run` 验证 → **`save-test-arguments`**
-5. 本地仅调试 Python 语法时可在 VS Code 中直接运行 `.py`（**不会**自动连平台；连平台须发布后在侧栏或 CLI 执行）
-## 实施自检（智能体 / 人工）
-| 检查项 | 命令 / 位置 |
-| ------ | ----------- |
-| 表已注册 | 侧栏 **数据资源** 或 `dazi onto space get` → `table_count` |
-| **表间关系已注册** | `relationship_count` > 0；侧栏 **表间关系** |
-| **347 分类已挂载** | 侧栏分类视图下表/Cube/对象等按标准中文名分组；init 摘要含 `category_mounts` |
-| 函数已注册 | `dazi onto function list --space <space-id>` |
-| **test_arguments 已保存** | `dazi onto function get <function_id>` → `test_arguments.arguments` |
-| 函数可运行 | `dazi onto function run <function_id> --space <space-id> --params '{}'` |
-## 相关文档
-- [CLI 调用约定](../guides/cli-invocation.md)
-- [本体规划指南](./本体规划指南.md)
-- [本体函数开发指南](./function-guide.md)
-- [本体动作开发](./action-guide.md)
-- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
-- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
-- [349 · 本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
-- [脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)
+# 本体脚本编写指南
+**文档 ID**: `onto/script-authoring`
+本文说明本体实现单元内 **Python 脚本的目录、类型、发布与运行**（原独立的「脚本开发与发布」已与本文合并）。
+> 终端命令均在 **`dazi-work` 根目录**执行：`dazi ...`（见 [CLI 调用约定](../guides/cli-invocation.md)）。
+## 执行脚本前必读（强制）
+在终端执行 **`dazi onto script publish` / `script run` / `function run` / `save-test-arguments`** 之前，**必须**阅读：
+| 文档 | 说明 |
+| ---- | ---- |
+| **[脚本运行常见错误处理](./脚本运行常见错误处理.md)** | setup API 误用、`query_one` 聚合陷阱、**函数禁止 `output.print_json()`**、CLI 参数（`function run` 不支持 JSON 文件、`save-test-arguments` 须 `ofn_xxx`） |
+`dazi docs show onto/script-run-troubleshooting` · 智能体另见提示词 **`onto/script-publish-run`**。
+## 环境
+- 推荐 **Python 3.10+**
+- 脚本目录：**`<工作区根>/项目/<业务名>/本体/ontos/<实现名>/setup/`** 与 **`functions/`**（新建本体实现时自动创建）
+- 扩展默认脚本语言：`dazi.onto.defaultScriptLang` = `python`
+- 平台 API：`dazi.serverUrl`；登录：`dazi auth login` / `dazi auth set-token`
+## 目录约定
+```text
+<工作区根>/项目/<业务名>/              ← 业务项目根
+└── 本体/
+    └── ontos/<实现名>/                ← 本体实现单元；README 含 space_id
+        ├── README.md
+        ├── 快速启动_<实现名>.md
+        ├── plans/                     ← 规划阶段 Markdown 产出
+        ├── setup/                     ← 初始化、灌数脚本
+        └── functions/                 ← 本体函数、动作脚本
+            ├── test_arguments/        ← 各 function_id 的 test_arguments JSON
+            ├── save_test_arguments.ps1  ← 可选：批量写入平台（推荐）
+            └── *.py
+```
+内置示例位于 **`资源/examples/onto/`**（`dazi examples sync`）。**须 `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/` |
+总览说明：`资源/examples/onto/README.md`（`dazi examples show onto/readme`）。
+> **不再使用** 历史路径 `onto/<space_id>/editorial/`、`editorial/functions/`、`项目/onto_<名称>/脚本/` 等作为本地开发约定。
+## 必读规范（DaziScript）
+编写 `setup/`、`functions/` 下 `.py` 前请阅读：
+| 文档                                                                | 说明                                                                   |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **[DaziScript SDK 参考](./dazi_script_sdk_reference.md)**           | `space` / `s.sql` / `s.onto` / `s.tables` / Cube 等 API 与本体落库顺序 |
+| **[DaziScript 灌数脚本编写指南](./dazi_script_seed_data_guide.md)** | 造数、补数、`insert_rows` 与 ClickHouse `INSERT` 约束、幂等约定        |
+同步到工作区：`dazi docs sync` → `资源/docs/onto/`。
+## 初始化脚本标准顺序（setup）
+`*_ontology_init.py` 建议按以下顺序执行（与 [本体规划指南](./本体规划指南.md) 物理层 + 表间关系章节一致）：
+| 步骤 | 内容 | API |
+| ---- | ---- | --- |
+| 1 | 建表 | `s.sql.execute(CREATE TABLE ...)` |
+| 2 | 注册表 | `s.tables.register_with_meta`（含表/列 `display_name`、`description`） |
+| 3 | **注册表间关系** | `s.tables.add_relationship(...)` |
+| 4 | 注册 Cube / 派生度量 | `s.register_cube`、`s.upsert_derived_measures` |
+| 5 | 本体对象 / 属性 / 链接 | `s.onto.define_*`、`s.sync_metric_refs` |
+**平台分类挂载**不在 init 内执行，见下方「分类挂载脚本」与实施顺序。
+### 表间关系 `s.tables.add_relationship`
+在 **表 register 完成之后、Cube 注册之前** 调用；**幂等**，可重复执行 init。
+```python
+s.tables.add_relationship(
+    from_table="sales_order_fact",       # 通常为事实表
+    to_table="product_master",           # 维表
+    join_sql="sales_order_fact.product_id = product_master.product_id",
+    join_keys=[{"from": "product_id", "to": "product_id"}],
+    relationship_type="many_to_one",     # 默认 many_to_one
+    description="销售订单行关联产品主数据",
+)
+```
+验收：`dazi onto space get <space-id>` 中 **`relationship_count`** 与规划条数一致；侧栏 **数据资源 → 表间关系** 可见。
+> **勿与** `s.onto.define_link_type` 混淆：前者写数据空间元数据，后者写业务对象语义链接，**两者都需实施**。
+### 表注册 `TABLE_REGISTRY` + `register_with_meta`
+init 脚本顶部维护与规划文档对齐的 `TABLE_REGISTRY`（项目内 `plans/*.md` 或内置 [规划示例](./规划示例_产品销售本体规划方案.md)），步骤 2 统一调用：
+```python
+TABLE_REGISTRY = {
+    "fact_sales_order_line": {
+        "display_name": "销售订单行事实表",
+        "description": "订单行粒度销售流水",
+        "columns": [
+            {"name": "order_id", "display_name": "订单 ID"},
+            {"name": "date_key", "display_name": "日期键", "description": "关联 dim_date"},
+            # ...
+        ],
+    },
+}
+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 时刷新列元数据
+    )
+```
+- **显示名** → 侧栏与表预览列标题（`display_name`）
+- **说明** → 业务口径、FK、冗余原因（`description`）；`sync_columns` **不会**自动写入
+- 参考：`资源/examples/onto/利润示例/setup/profit_ontology_init.py`、`销售示例/setup/sales_ontology_init.py`
+### 分类挂载脚本 `*_category_mount.py`（推荐，类灌数）
+与 `*_seed_data.py` 一样，**独立 setup 脚本、放在实施流程最后**，避免 init 与函数 publish 的先后顺序问题。
+| 脚本 | 时机 |
+| ---- | ---- |
+| `*_ontology_init.py` | 建表、注册、Cube、对象、链接（**不含**分类挂载） |
+| `*_seed_data.py` | 灌数 |
+| `functions/*.py` | 逐个 `publish --register-function-id` |
+| **`*_category_mount.py`** | **最后**：一次性 `apply_registry` 全量 `CATEGORY_REGISTRY` |
+**标准实施顺序**：
+```
+init → seed → 发布全部函数 → category_mount
+```
+`setup/*_category_mount.py` 顶部维护与规划附录 B 对齐的 `CATEGORY_REGISTRY`（含 table/cube/object/relation/link/**function** 六类）：
+```python
+CATEGORY_REGISTRY = {
+    "table": {"维度表": ["dim_account"], "事实表": ["fact_x"]},
+    "cube": {"流程型": ["ActualCube"]},
+    "object": {"主数据": ["Account"]},
+    "relation": {"时间关联": [("fact_x", "dim_date")]},
+    "link": {"归属关系": ["entry_belongs_account"]},
+    "function": {"总览分析": ["domain.fn.get_summary"]},
+}
+s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+- `skip_missing=True`：函数未 publish 时跳过并 warning；**全部函数就绪后重跑本脚本即可**，无需重跑 init
+- 可选补充：单函数 publish 时 `--register-platform-category`（与 category_mount 幂等可并存）
+- 示例：`利润示例/setup/profit_category_mount.py`、`销售示例/setup/sales_category_mount.py`
+- 详见 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)、[脚本运行常见错误处理](./脚本运行常见错误处理.md) §6
+## 脚本类型
+类型由 **发布命令参数** 区分；初始化与灌数放 `setup/`，本体函数与动作放 `functions/`：
+| 类型                | 路径约定                                                          | 说明                                               |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
+| `ontology_function` | `项目/<业务名>/本体/ontos/<实现名>/functions/**/*.py`             | **必须**带 `--register-function-id` 发布（见下节） |
+| `ontology_action`   | `项目/<业务名>/本体/ontos/<实现名>/functions/**/*.py`             | 发布时加 `--register-action-id` 等 Action 参数     |
+| `data_script`       | `项目/<业务名>/本体/ontos/<实现名>/setup/**/*.py`                 | 普通 `script publish`，不注册函数/动作             |
+`<space-id>` 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取，勿手写错空间。
+## 发布预检
+```powershell
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space-id>
+```
+## 发布脚本
+> **勿用** 独立命令 `dazi-onto`（v3 未安装到 PATH）。统一使用 **`dazi onto ...`**。
+### 本体函数：**必须注册**，否则侧栏与测试看不到
+`functions/`（或规划中的本体函数 `.py`）**不能**只执行「普通 publish」：
+**新建函数**：复制 `资源/examples/onto/_templates/ontology_function_template.py`（`dazi examples show onto/template/ontology-function`），或参考 `销售示例/functions/sales_fn_get_summary.py`。`main()` **无参**，业务写在 `_ontology_fn_body(p)`，末尾 **`return _ontology_fn_body(p)`** — **禁止** `output.print_json()`（见 [脚本运行常见错误处理 §3](./脚本运行常见错误处理.md#3-函数输出禁止-outputprint_json)）。
+| 仅 `script publish`（无 `--register-function-id`） | 带 `--register-function-id` 发布             |
+| -------------------------------------------------- | -------------------------------------------- |
+| 脚本代码进入 `ads_scripts`                         | 同上 **且** 写入 `ontology_function_defs`    |
+| **不会**出现在 **Onto → 函数列表**                 | 出现在函数列表，可 **运行函数** / 工作台测试 |
+| `dazi onto function run <id>` **找不到**           | `function run`、侧栏运行可用                 |
+因此：**首次发布本体函数时，命令里必须包含 `--register-function-id`**，且 `function_id` 与规划文档、脚本内约定 **完全一致**（建议带点号命名空间，如 `sales.fn.get_summary`，勿随意简写为 `get_summary`）。
+智能体（TRAE 等）实施自检：
+1. 发布命令是否包含 `--register-function-id`？
+2. 发布输出是否含 `functionId: xxx` / `function_registration.ok`？
+3. `dazi onto function list --space <space-id>` 能否看到该 `function_id`？
+4. 规划函数数 = `functions/*.py` 文件数 = `function list` 条数？
+5. 平台分类：已 run `*_category_mount.py`（或各 publish 已带 `--register-platform-category`）？
+任一步不满足 → **视为未注册或未分类**，需补 publish / 补跑 `category_mount`，不要仅 `script run` 以为函数已可用。
+```powershell
+# 初始化 / 灌数：普通发布即可（不要加 register-function-id）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/xxx_ontology_init.py --space <space-id> --type setup
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/xxx_seed_data.py --space <space-id> --type data
+# ★ 本体函数：必须注册（示例）；可选同时挂载 平台分类
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/get_summary.py `
+  --space <space-id> `
+  --register-function-id sales.fn.get_summary `
+  --register-platform-category 总览分析
+# 发布并注册为本体动作（示例）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_action.py `
+  --space <space-id> `
+  --register-action-id my_action_code `
+  --register-action-permission-tag "finance.write"
+```
+发布后验证：
+```powershell
+dazi onto function list --space <space-id>
+dazi onto function run sales.fn.get_summary --space <space-id> --params '{}'
+```
+### 函数测试参数（test_arguments，**发布后必做**）
+仅 `publish` + `function run` **不会**自动写入测试参数；侧栏 **Onto → 运行函数** 依赖函数定义上的 **`test_arguments`** 预填表单。
+> **CLI 易错点**：`function run` **不支持** `--arguments-json-file`；`save-test-arguments` 须用 **`ofn_xxx` 内部 id** 而非 `function_id` 字符串。完整说明见 [脚本运行常见错误处理](./脚本运行常见错误处理.md)。
+**本地约定（与规划文档 § 函数 / test_arguments 一致）**：
+1. 每个函数一份 JSON：`functions/test_arguments/<function_id>.json`
+2. 脚本内同名常量 `TEST_ARGUMENTS`（与 JSON **保持同步**）
+3. 函数 `main()` 通过 `ctx.params` 读取的键名 = JSON 内 **`arguments`** 对象的键名
+**JSON 格式**（与平台函数定义一致）：
+```json
+{
+  "v": 1,
+  "arguments": {
+    "start_date": "2025-01-01",
+    "end_date": "2026-06-30"
+  },
+  "object_type_code": "SalesAnalysis"
+}
+```
+**保存到平台**（函数 `run` 验证通过后）：
+```powershell
+# 推荐：批量脚本（解析 function list，用内部 id ofn_xxx 调用 PATCH）
+.\项目/<业务名>/本体/ontos/<实现名>/functions/save_test_arguments.ps1
+```
+单条保存（**须用平台内部 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> `
+  --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/sales.fn.get_summary.json
+```
+**PowerShell 传 `--params` 易丢引号**；测试运行可省略 `--params`（用 `{}`），或：
+```powershell
+$env:DAZI_PARAMS='{"start_date":"2025-01-01","end_date":"2026-06-30"}'
+dazi onto function run sales.fn.get_summary --space <space-id> --params $env:DAZI_PARAMS
+```
+验收：`dazi onto function get <function_id> --space <space-id>` 中 **`test_arguments` 非 null**，且 `arguments` 与 JSON 一致。
+亦可在 VS Code 侧栏 **Onto 本体 → 发布函数** 发布（须填写/绑定 **function_id**）；发布后在 **函数** 节点下应能看到该函数。
+函数生命周期与 `update-code` 详见 **[本体函数开发指南](./function-guide.md)**。给 TRAE 的完整命令模板见内置提示词 **`onto/script-publish-run`**（`dazi prompt sync` 后位于 `资源/prompts/onto/`）。
+## 从平台拉取脚本（可选）
+若需将平台上已有脚本拉回本地对照（**非**日常开发主路径）：
+```powershell
+# 推荐：落盘到本体实现目录（按 setup / functions 分子目录）
+dazi onto script sync --space <space-id> --target-dir 项目/<业务名>/本体/ontos/<实现名>
+dazi onto script sync --space <space-id> --type ontology_function --target-dir 项目/<业务名>/本体/ontos/<实现名>
+dazi onto script sync --space <space-id> --dry-run --target-dir 项目/<业务名>/本体/ontos/<实现名>
+# legacy：onto/<space-id>/scripts/（非日常开发入口）
+dazi onto script sync --space <space-id>
+```
+拉取目标目录以 CLI 为准；**新建与修改仍以 `项目/<业务名>/本体/ontos/<实现名>/setup/` 与 `functions/` 为准**。
+## 清理重复脚本
+```powershell
+dazi onto script dedupe --space <space-id> --dry-run
+dazi onto script dedupe --space <space-id> --yes
+```
+## 编写建议
+1. 先阅读 `快速启动_<实现名>.md` 与 `README.md` 中的**数据空间 ID**，并对照 `plans/` 中**表间关系**与**函数 test_arguments** 章节
+2. 在 `setup/`、`functions/` 中按模块拆分 `.py`（初始化、灌数、本体函数可分机文件）
+3. **init 脚本**必须包含 `s.tables.add_relationship`（若规划有表间关系）
+4. 发布与运行：`dazi onto script publish`（**函数必须** `--register-function-id`）→ `function run` 验证 → **`save-test-arguments`**
+5. 本地仅调试 Python 语法时可在 VS Code 中直接运行 `.py`（**不会**自动连平台；连平台须发布后在侧栏或 CLI 执行）
+## 实施自检（智能体 / 人工）
+| 检查项 | 命令 / 位置 |
+| ------ | ----------- |
+| 表已注册 | 侧栏 **数据资源** 或 `dazi onto space get` → `table_count` |
+| **表间关系已注册** | `relationship_count` > 0；侧栏 **表间关系** |
+| **平台分类已挂载** | 侧栏分类视图下表/Cube/对象/函数按标准中文名分组；`category_mount` 摘要含 `category_mounts` |
+| 函数已注册 | `dazi onto function list --space <space-id>` |
+| **test_arguments 已保存** | `dazi onto function get <function_id>` → `test_arguments.arguments` |
+| 函数可运行 | `dazi onto function run <function_id> --space <space-id> --params '{}'` |
+## 相关文档
+- [CLI 调用约定](../guides/cli-invocation.md)
+- [本体规划指南](./本体规划指南.md)
+- [本体函数开发指南](./function-guide.md)
+- [本体动作开发](./action-guide.md)
+- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
+- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
+- [脚本运行常见错误处理](./脚本运行常见错误处理.md)