@dazitech/cli 3.0.7 → 3.0.9

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

@@ -2,36 +2,57 @@
 
 **文档 ID**: `onto/script-authoring`
 
-本文说明本体项目内 **Python 脚本的目录、类型、发布与运行**（原独立的「脚本开发与发布」已与本文合并）。
+本文说明本体实现单元内 **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+**
-- 脚本目录：**`<工作区根>/项目/onto_<项目名>/脚本/`**（新建本体项目时自动创建）
+- 脚本目录：**`<工作区根>/项目/<业务名>/本体/ontos/<实现名>/setup/`** 与 **`functions/`**（新建本体实现时自动创建）
 - 扩展默认脚本语言：`dazi.onto.defaultScriptLang` = `python`
 - 平台 API：`dazi.serverUrl`；登录：`dazi auth login` / `dazi auth set-token`
 
 ## 目录约定
 
 ```text
-<工作区根>/项目/onto_<项目名>/    ← 扩展「新建项目」；README 含 space_id
-├── README.md
-├── 快速启动.md
-├── 规划/
-└── 脚本/                          ← 所有本体 Python 脚本（函数/动作/灌数/初始化）
-    ├── main.py
-    └── ...
+<工作区根>/项目/<业务名>/              ← 业务项目根
+└── 本体/
+    └── 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`）。
+参考示例（可复制后修改）位于 **`资源/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/<space_id>/editorial/`、`editorial/functions/`、`项目/onto_<名称>/脚本/` 等作为本地开发约定。
 
 ## 必读规范（DaziScript）
 
-编写 `脚本/` 下 `.py` 前请阅读：
+编写 `setup/`、`functions/` 下 `.py` 前请阅读：
 
 | 文档                                                                | 说明                                                                   |
 | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
@@ -40,22 +61,98 @@
 
 同步到工作区：`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)
+
 ## 脚本类型
 
-类型由 **发布命令参数** 区分；文件可平铺在 `脚本/`，也可分子目录（如 `脚本/functions/`、`脚本/actions/`）：
+类型由 **发布命令参数** 区分；初始化与灌数放 `setup/`，本体函数与动作放 `functions/`：
 
-| 类型                | 路径约定                          | 说明                                               |
-| ------------------- | --------------------------------- | -------------------------------------------------- |
-| `ontology_function` | `项目/onto_<项目名>/脚本/**/*.py` | **必须**带 `--register-function-id` 发布（见下节） |
-| `ontology_action`   | `项目/onto_<项目名>/脚本/**/*.py` | 发布时加 `--register-action-id` 等 Action 参数     |
-| `data_script`       | `项目/onto_<项目名>/脚本/**/*.py` | 普通 `script publish`，不注册函数/动作             |
+| 类型                | 路径约定                                                          | 说明                                               |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
+| `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>` 从 **`项目/onto_<项目名>/README.md`** 读取，勿手写错空间。
+`<space-id>` 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取，勿手写错空间。
 
 ## 发布预检
 
 ```powershell
-dazi onto script publish-preview 项目/onto_<项目名>/脚本/my_func.py --space <space-id>
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space-id>
 ```
 
 ## 发布脚本
@@ -64,7 +161,9 @@ dazi onto script publish-preview 项目/onto_<项目名>/脚本/my_func.py --spa
 
 ### 本体函数：**必须注册**，否则侧栏与测试看不到
 
-`脚本/functions/`（或规划中的本体函数 `.py`）**不能**只执行「普通 publish」：
+`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` 发布             |
 | -------------------------------------------------- | -------------------------------------------- |
@@ -84,16 +183,16 @@ dazi onto script publish-preview 项目/onto_<项目名>/脚本/my_func.py --spa
 
 ```powershell
 # 初始化 / 灌数：普通发布即可（不要加 register-function-id）
-dazi onto script publish 项目/onto_<项目名>/脚本/setup/xxx_ontology_init.py --space <space-id> --type setup
-dazi onto script publish 项目/onto_<项目名>/脚本/setup/xxx_seed_data.py --space <space-id> --type data
+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 项目/onto_<项目名>/脚本/functions/get_summary.py `
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/get_summary.py `
   --space <space-id> `
   --register-function-id sales.fn.get_summary
 
 # 发布并注册为本体动作（示例）
-dazi onto script publish 项目/onto_<项目名>/脚本/my_action.py `
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_action.py `
   --space <space-id> `
   --register-action-id my_action_code `
   --register-action-permission-tag "finance.write"
@@ -103,9 +202,57 @@ dazi onto script publish 项目/onto_<项目名>/脚本/my_action.py `
 
 ```powershell
 dazi onto function list --space <space-id>
-dazi onto function run sales.fn.get_summary --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/`）。
@@ -115,12 +262,16 @@ dazi onto function run sales.fn.get_summary --space <space-id>
 若需将平台上已有脚本拉回本地对照（**非**日常开发主路径）：
 
 ```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>
-dazi onto script sync --space <space-id> --type ontology_function
-dazi onto script sync --space <space-id> --dry-run
 ```
 
-拉取目标目录以 CLI 为准；**新建与修改仍以 `项目/onto_<项目名>/脚本/` 为准**。
+拉取目标目录以 CLI 为准；**新建与修改仍以 `项目/<业务名>/本体/ontos/<实现名>/setup/` 与 `functions/` 为准**。
 
 ## 清理重复脚本
 
@@ -131,10 +282,22 @@ dazi onto script dedupe --space <space-id> --yes
 
 ## 编写建议
 
-1. 先阅读 `快速启动.md` 与 `README.md` 中的**数据空间 ID**
-2. 在 `脚本/` 中按模块拆分 `.py`（初始化、灌数、本体函数可分机文件）
-3. 发布与运行：`dazi onto script publish`（**函数必须** `--register-function-id`）/ 侧栏 **Onto 本体**；函数运行见 **[function-guide](./function-guide.md)**、**[action-guide](./action-guide.md)**
-4. 本地仅调试 Python 语法时可用 VS Code 运行 `脚本/main.py`（**不会**自动连平台；连平台须发布后在侧栏或 CLI 执行）
+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 '{}'` |
 
 ## 相关文档
 
@@ -142,4 +305,7 @@ dazi onto script dedupe --space <space-id> --yes
 - [本体规划指南](./本体规划指南.md)
 - [本体函数开发指南](./function-guide.md)
 - [本体动作开发](./action-guide.md)
-- [规划示例：利润分析本体](./规划示例_利润分析本体方案.md)
+- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
+- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [349 · 本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
+- [脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)