@dazitech/cli 3.0.9 → 3.1.0

package/dist/docs/onto/function-guide.md

@@ -1,123 +1,123 @@
-# 本体函数开发指南
-
-**文档 ID**: `onto/function-guide`
-
-> **执行脚本前必读**：[`脚本运行纠错_商务成本方案开发过程.md`](./脚本运行纠错_商务成本方案开发过程.md)（CLI、SQL、`output.print_json` 等常见误用）。
-
-## 函数生命周期
-
-```
-编写 .py → publish-preview（可选）→ publish（--register-function-id 入库）
-  → function run 验证 → save-test-arguments（写入 test_arguments，侧栏预填）
-  → 后续改代码：update-code
-```
-
-工作路径：`项目/<业务名>/本体/ontos/<实现名>/functions/`；本地 JSON：`functions/test_arguments/<function_id>.json`。
-
-## 新建函数
-
-**推荐**：复制 `资源/examples/onto/_templates/ontology_function_template.py` 或 `销售示例/functions/sales_fn_*.py`，再改业务逻辑。
-
-```bash
-# 发布新函数（路径指向本体实现单元 functions/ 目录）
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
-  --space <space-id> \
-  --register-function-id domain.fn.my_analysis
-```
-
-`<space-id>` 取自 **`项目/<业务名>/本体/ontos/<实现名>/README.md`**。
-
-## 更新已有函数代码
-
-```bash
-dazi onto function update-code <function-id> \
-  --space <space-id> \
-  --stem my_func
-```
-
-`--stem` 为脚本文件名（不含扩展名），须与 `functions/` 下文件一致。
-
-## 运行函数
-
-```bash
-dazi onto function run <function-id> \
-  --space <space-id> \
-  --params '{}'
-```
-
-> **`function run` 不支持 `--arguments-json-file`**。详见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md#4-cli-参数认知错误)。
-
-PowerShell 下复杂 JSON 建议用环境变量 `DAZI_PARAMS` 或侧栏运行（使用已保存的 `test_arguments`）。详见 [本体脚本编写指南](./本体脚本编写指南.md#函数测试参数test_arguments发布后必做)。
-
-## 保存测试参数（test_arguments）
-
-函数 **`run` 验证通过后**，须将默认入参写入函数定义，侧栏 **Onto → 运行函数** 才会预填。
-
-**本地文件**：`functions/test_arguments/<function_id>.json`（格式见 [本体脚本编写指南](./本体脚本编写指南.md)）。
-
-```bash
-dazi onto function save-test-arguments <ofn_internal_id> \
-  --space <space-id> \
-  --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/<function_id>.json
-```
-
-> **注意**：须用平台**内部 id** `ofn_xxx`（`dazi onto function list` 返回），不是 `function_id` 字符串。
-
-## 函数脚本结构（标准模板）
-
-本体函数与 setup/seed 脚本不同：**`main()` 无参**，平台注入 `ctx`、`space`、`onto`；**必须 return** `function_result`，**禁止** `output.print_json()`。
-
-```python
-TEST_ARGUMENTS = {
-    "v": 1,
-    "arguments": {"start_date": "2025-01-01", "end_date": "2026-06-30"},
-    "object_type_code": "SalesAnalysis",
-}
-
-
-def _ontology_fn_body(p):
-    params = dict(p.get_params() or {})
-    start_date = params.get("start_date", "")
-    end_date = params.get("end_date", "")
-
-    rows = p.sql.query(f"SELECT sum(amount) AS total FROM fact WHERE date >= '{start_date}'")
-    row = rows[0] if rows else {}
-    total = float(row.get("total", 0) or 0)
-
-    return p.function_result(
-        columns=["total"],
-        data=[{"total": total}],
-        row_count=1,
-    )
-
-
-def main():
-    s = space.get(ctx.space_id or "")
-    _Ports = type(
-        "_Ports",
-        (),
-        {
-            "get_params": lambda self: dict(ctx.params or {}),
-            "function_result": lambda self, **kw: onto.function_result(**kw),
-        },
-    )
-    p = _Ports()
-    p.sql = s.sql
-    return _ontology_fn_body(p)
-```
-
-| 要点 | 说明 |
-| ---- | ---- |
-| 入口 | **`def main():`**（无 `params` 形参） |
-| 入参 | `ctx.params` → `p.get_params()` |
-| 空间 / SQL | `s = space.get(ctx.space_id)` → `p.sql = s.sql` |
-| 出参 | **`return p.function_result(columns=..., data=..., row_count=...)`** |
-| 禁止 | `output.print_json`、`main(params: dict)`、裸 `return {"k": v}` |
-
-可复制模板：`资源/examples/onto/_templates/ontology_function_template.py` · 参考实现：`销售示例/functions/sales_fn_get_summary.py`。
-
-## 相关文档
-
-- [脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)
-- [本体脚本编写指南](./本体脚本编写指南.md)
-- [DaziScript SDK 参考](./dazi_script_sdk_reference.md)
+# 本体函数开发指南
+
+**文档 ID**: `onto/function-guide`
+
+> **执行脚本前必读**：[`脚本运行常见错误处理.md`](./脚本运行常见错误处理.md)（CLI、SQL、`output.print_json` 等常见误用）。
+
+## 函数生命周期
+
+```
+编写 .py → publish-preview（可选）→ publish（--register-function-id 入库）
+  → function run 验证 → save-test-arguments（写入 test_arguments，侧栏预填）
+  → 后续改代码：update-code
+```
+
+工作路径：`项目/<业务名>/本体/ontos/<实现名>/functions/`；本地 JSON：`functions/test_arguments/<function_id>.json`。
+
+## 新建函数
+
+**推荐**：复制 `资源/examples/onto/_templates/ontology_function_template.py` 或 `销售示例/functions/sales_fn_*.py`，再改业务逻辑。
+
+```bash
+# 发布新函数（路径指向本体实现单元 functions/ 目录）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
+  --space <space-id> \
+  --register-function-id domain.fn.my_analysis
+```
+
+`<space-id>` 取自 **`项目/<业务名>/本体/ontos/<实现名>/README.md`**。
+
+## 更新已有函数代码
+
+```bash
+dazi onto function update-code <function-id> \
+  --space <space-id> \
+  --stem my_func
+```
+
+`--stem` 为脚本文件名（不含扩展名），须与 `functions/` 下文件一致。
+
+## 运行函数
+
+```bash
+dazi onto function run <function-id> \
+  --space <space-id> \
+  --params '{}'
+```
+
+> **`function run` 不支持 `--arguments-json-file`**。详见 [脚本运行常见错误处理](./脚本运行常见错误处理.md#4-cli-参数误用)。
+
+PowerShell 下复杂 JSON 建议用环境变量 `DAZI_PARAMS` 或侧栏运行（使用已保存的 `test_arguments`）。详见 [本体脚本编写指南](./本体脚本编写指南.md#函数测试参数test_arguments发布后必做)。
+
+## 保存测试参数（test_arguments）
+
+函数 **`run` 验证通过后**，须将默认入参写入函数定义，侧栏 **Onto → 运行函数** 才会预填。
+
+**本地文件**：`functions/test_arguments/<function_id>.json`（格式见 [本体脚本编写指南](./本体脚本编写指南.md)）。
+
+```bash
+dazi onto function save-test-arguments <ofn_internal_id> \
+  --space <space-id> \
+  --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/<function_id>.json
+```
+
+> **注意**：须用平台**内部 id** `ofn_xxx`（`dazi onto function list` 返回），不是 `function_id` 字符串。
+
+## 函数脚本结构（标准模板）
+
+本体函数与 setup/seed 脚本不同：**`main()` 无参**，平台注入 `ctx`、`space`、`onto`；**必须 return** `function_result`，**禁止** `output.print_json()`。
+
+```python
+TEST_ARGUMENTS = {
+    "v": 1,
+    "arguments": {"start_date": "2025-01-01", "end_date": "2026-06-30"},
+    "object_type_code": "SalesAnalysis",
+}
+
+
+def _ontology_fn_body(p):
+    params = dict(p.get_params() or {})
+    start_date = params.get("start_date", "")
+    end_date = params.get("end_date", "")
+
+    rows = p.sql.query(f"SELECT sum(amount) AS total FROM fact WHERE date >= '{start_date}'")
+    row = rows[0] if rows else {}
+    total = float(row.get("total", 0) or 0)
+
+    return p.function_result(
+        columns=["total"],
+        data=[{"total": total}],
+        row_count=1,
+    )
+
+
+def main():
+    s = space.get(ctx.space_id or "")
+    _Ports = type(
+        "_Ports",
+        (),
+        {
+            "get_params": lambda self: dict(ctx.params or {}),
+            "function_result": lambda self, **kw: onto.function_result(**kw),
+        },
+    )
+    p = _Ports()
+    p.sql = s.sql
+    return _ontology_fn_body(p)
+```
+
+| 要点 | 说明 |
+| ---- | ---- |
+| 入口 | **`def main():`**（无 `params` 形参） |
+| 入参 | `ctx.params` → `p.get_params()` |
+| 空间 / SQL | `s = space.get(ctx.space_id)` → `p.sql = s.sql` |
+| 出参 | **`return p.function_result(columns=..., data=..., row_count=...)`** |
+| 禁止 | `output.print_json`、`main(params: dict)`、裸 `return {"k": v}` |
+
+可复制模板：`资源/examples/onto/_templates/ontology_function_template.py` · 参考实现：`销售示例/functions/sales_fn_get_summary.py`。
+
+## 相关文档
+
+- [脚本运行常见错误处理](./脚本运行常见错误处理.md)
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [DaziScript SDK 参考](./dazi_script_sdk_reference.md)

package/dist/docs/onto//346/234/254/344/275/223/345/210/206/347/261/273/350/247/204/345/210/222/344/270/216SDK/346/211/251/345/261/225/346/226/271/346/241/210.md

@@ -1,17 +1,18 @@
-# 349 · 本体分类规划与 SDK 扩展方案
+# 本体分类规划与 SDK 扩展方案
 
 **文档 ID**：`onto/category-taxonomy-sdk`
 
-> **文档编号**：349  
-> **类型**：规范 + 实施方案（对齐 §347 · `ads_categories` 平台分类）  
+> **类型**：规范 + 实施方案（对齐 `ads_categories` 平台分类）  
 > **同步路径**：`dazi docs sync` → `资源/docs/onto/本体分类规划与SDK扩展方案.md`  
-> **前置依据**：[本体命名规范 §347](./本体命名规范_物理表Cube与对象.md)、[本体规划指南](./本体规划指南.md)
+> **前置依据**：[本体命名规范](./本体命名规范_物理表Cube与对象.md)、[本体规划指南](./本体规划指南.md)
 
 ---
 
 ## 1. 目标
 
-将 **347 语义分类**（规划表「类别/分类」列）与 **`ads_categories` 平台分类**（侧栏分组、桥表挂载）打通，支持 init 脚本幂等注册。
+将 **规划语义分类**（规划表「类别/分类」列）与 **`ads_categories` 平台分类**（侧栏分组、桥表挂载）打通，支持 init 脚本幂等注册。
+
+> **术语**：下文 **平台标准分类** = 侧栏 `ads_categories` 使用的标准中文名（如「维度表」「总览分析」）。SDK 中的 `category_347`、`ensure_347` 为历史参数/方法名，**含义即平台标准分类**，与文档编号无关。
 
 **约束**：本体规划阶段分类 **全部平级**（挂空间默认根下，不建多层树）。
 
@@ -19,18 +20,18 @@
 
 ## 2. 两类分类，一套语言
 
-| 维度 | 347 语义分类 | ads_categories 平台分类 |
+| 维度 | 规划语义分类 | ads_categories 平台分类 |
 |------|-------------|------------------------|
 | 作用 | 规划自检、命名约束 | 侧栏展示、资源分组 |
-| 对齐 | 平台 `category_name` **=** 347 标准中文名 | 禁止自定义别名 |
+| 对齐 | 平台 `category_name` **=** 平台标准分类中文名 | 禁止自定义别名 |
 
 ---
 
-## 3. 347 标准分类字典（6 类资源）
+## 3. 平台标准分类字典（6 类资源）
 
 ### 3.1 物理表（`category_kind=dataspace_table`）
 
-| 347 类别 | 前缀 | 平台分类名 |
+| 平台分类类别 | 前缀 | 平台分类名 |
 |----------|------|------------|
 | 时间维 | `dim_date` | 时间维 |
 | 维度表 | `dim_` | 维度表 |
@@ -43,18 +44,18 @@
 
 ### 3.2 Cube（`category_kind=cube`）
 
-| 347 类别 | 平台分类名 |
+| 平台分类类别 | 平台分类名 |
 |----------|------------|
 | Process | 流程型 |
 | Subject | 主体型 |
 | Comparison | 对比型 |
 | Snapshot | 快照型 |
 
-> 时间增强不单独建 Cube（347 §4.2），不设平台分类。
+> 时间增强不单独建 Cube（命名规范 §4.2），不设平台分类。
 
 ### 3.3 本体对象（`category_kind=ontology_object_type`）
 
-| 347 分类 | 平台分类名 |
+| 平台分类 | 平台分类名 |
 |----------|------------|
 | Master | 主数据 |
 | Transaction | 事务 |
@@ -62,7 +63,7 @@
 | Reference | 参考 |
 | Configuration | 配置 |
 
-### 3.4 表间关系（`category_kind=relation`，347 扩展）
+### 3.4 表间关系（`category_kind=relation`，平台扩展）
 
 | 关系类别 | 平台分类名 |
 |----------|------------|
@@ -72,7 +73,7 @@
 | 预实关联 | 预实关联 |
 | 桥接关联 | 桥接关联 |
 
-### 3.5 本体链接（`category_kind=ontology_link_type`，347 扩展）
+### 3.5 本体链接（`category_kind=ontology_link_type`，平台扩展）
 
 | 链接类别 | 平台分类名 |
 |----------|------------|
@@ -81,7 +82,7 @@
 | 层级/结构 | 层级关系 |
 | 对比/映射 | 对比关系 |
 
-### 3.6 本体函数（`category_kind=ontology_function`，347 扩展）
+### 3.6 本体函数（`category_kind=ontology_function`，平台扩展）
 
 | 函数类别 | 平台分类名 |
 |----------|------------|
@@ -105,9 +106,9 @@ s.categories.assign_table("维度表", "dim_account")
 s.categories.auto_assign_tables(["dim_account", "fact_gl_journal_entry"])
 ```
 
-### 4.2 init 脚本
+### 4.2 分类挂载脚本 `*_category_mount.py`
 
-**方式 A — 批量**（推荐）：顶部 `CATEGORY_REGISTRY` 与规划 **附录 B** 对齐；资源注册完成后：
+**方式 A — 批量**（推荐，类灌数）：独立 `setup/*_category_mount.py` 顶部 `CATEGORY_REGISTRY` 与规划 **附录 B** 对齐；在 **init + seed + 全部函数 publish 之后** 执行：
 
 ```python
 cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
@@ -133,16 +134,16 @@ s.onto.register_function("sales.fn.get_summary", adapter, category_347="总览
 | 产出 | 位置 | 说明 |
 | ---- | ---- | ---- |
 | 规划附录 B | `plans/<主题>.md` | 6 类资源分类对照表 |
-| `CATEGORY_REGISTRY` | `setup/*_ontology_init.py` 顶部 | 与附录 B 逐行一致 |
-| 分类步骤 | init 末尾 | `[10/10] apply_registry` |
+| `CATEGORY_REGISTRY` | `setup/*_category_mount.py` 顶部 | 与附录 B 逐行一致 |
+| 分类步骤 | 流程最后 | publish + run `*_category_mount.py` |
 
-参考：[规划示例_产品销售](./规划示例_产品销售本体规划方案.md#附录-b347-分类挂载对照表category_registry)、[规划示例_利润分析](./规划示例_利润分析本体方案.md#附录-b347-分类挂载对照表category_registry)。
+参考：[规划示例_产品销售](./规划示例_产品销售本体规划方案.md#附录-b平台-分类挂载对照表category_registry)、[规划示例_利润分析](./规划示例_利润分析本体方案.md#附录-b平台-分类挂载对照表category_registry)。
 
 ---
 
 ## 6. 验收标准
 
-1. 平台侧栏分类名与 347 标准表一致
+1. 平台侧栏分类名与平台标准分类表一致
 2. `dim_*` / `fact_*` 自动归入维度表/事实表
 3. init 重跑幂等，桥表不重复
 4. `CATEGORY_REGISTRY` 与规划附录 B 逐行一致
@@ -153,7 +154,7 @@ s.onto.register_function("sales.fn.get_summary", adapter, category_347="总览
 
 | 文档 | 路径（`dazi docs sync` 后） |
 | ---- | --------------------------- |
-| 347 命名规范 | `资源/docs/onto/本体命名规范_物理表Cube与对象.md` |
+| 本体命名规范 | `资源/docs/onto/本体命名规范_物理表Cube与对象.md` |
 | 本体规划指南 | `资源/docs/onto/本体规划指南.md` |
 | SDK 参考 §5.6 | `资源/docs/onto/dazi_script_sdk_reference.md` |
 | 脚本编写指南 | `资源/docs/onto/本体脚本编写指南.md` |
@@ -164,5 +165,5 @@ s.onto.register_function("sales.fn.get_summary", adapter, category_347="总览
 
 | 日期 | 说明 |
 | ---- | ---- |
-| 2026-06-06 | 首版：对齐 347 分类方案 + SDK 设计 |
+| 2026-06-06 | 首版：对齐 平台分类方案 + SDK 设计 |
 | 2026-06-06 | 改为 `dazi-vscode` 完整可同步正文（客户环境不依赖 `dazi/docs/`） |