@dazitech/cli 3.0.8 → 3.1.0

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,242 @@
+# 脚本运行常见错误处理
+
+**文档 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` 结尾 |
+
+**教训**：对照 `资源/examples/onto/利润示例`、`销售示例` 的 init，勿猜 API。
+
+---
+
+## 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` 不支持 `--arguments-json-file`
+
+```powershell
+# 错误
+dazi onto function run <function_id> --space <空间> --arguments-json-file xxx.json
+
+# 正确：先 save-test-arguments，再 run（不带 JSON 文件）
+dazi onto function run <function_id> --space <空间>
+```
+
+### 4.2 `save-test-arguments` 须用 `ofn_xxx` 内部 ID
+
+```powershell
+# 错误 — function_id 字符串
+dazi onto function save-test-arguments profit.fn.get_summary --space <空间> ...
+
+# 正确 — list 返回的 id 字段
+dazi onto function list --space <空间>
+dazi onto function save-test-arguments ofn_xxxxxxxx --space <空间> `
+  --arguments-json-file <项目路径>/functions/test_arguments/<function_id>.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` 条数。
+
+---
+
+## 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 <空间>` |
+| 函数列表 | `dazi onto function list --space <空间>` |
+| 保存默认参数 | `dazi onto function save-test-arguments <ofn_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、侧栏空白 |