@dazitech/cli 3.0.6 → 3.0.8

package/dist/docs/onto/dazi_script_seed_data_guide.md

@@ -1,155 +1,158 @@
-# DaziScript 灌数脚本编写指南
-
-**文档 ID**: `onto/dazi-script-seed-data-guide`  
-**适用**: dazi-vscode v3 + ClickHouse 数据空间
-
-> **用途**：约定工作区内「一次性 / 可重复执行」的造数、补数、历史回填脚本的写法，供人与 LLM 统一遵循。  
-> SDK API 见 **[dazi_script_sdk_reference](./dazi_script_sdk_reference.md)**；目录与发布见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
-
----
-
-## 1. 什么是灌数脚本
-
-**灌数脚本**指在**已存在表结构**（或同脚本内先 DDL）的前提下，向当前空间写入**演示数据、回归数据、历史样本**的 DaziScript。
-
-### 1.1 放置位置（v3）
-
-| 类型           | 推荐路径                                                                                               |
-| -------------- | ------------------------------------------------------------------------------------------------------ |
-| **项目内开发** | `<工作区根>/项目/onto_<项目名>/脚本/<名称>.py`                                                         |
-| **参考示例**   | `资源/examples/onto/setup/`（初始化+灌数一体）、`资源/examples/onto/function/`（分析函数，非灌数专篇） |
-
-- `space_id` 以 **`项目/onto_<项目名>/README.md`** 为准（扩展「新建项目」时已绑定）。
-- 侧栏 **帮助 → 📎 示例 → 下载所有示例**，或：`dazi examples sync` → `资源/examples/`。
-- 须定义 **`main()`**，**不要**写 `if __name__ == "__main__":`。
-
-> 不再使用 `spaces/<space_id>/editorial/scripts/setup/` 作为 v3 本地约定路径。
-
----
-
-## 2. 硬约束（违反易导致联调失败）
-
-### 2.1 ClickHouse：`INSERT ... VALUES` 与注释
-
-- **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**。常见报错：`CANNOT_PARSE_INPUT_ASSERTION_FAILED`、`Code: 27`。
-- **允许**：在**整条** `INSERT` **之前**写注释；或拆成多条 `INSERT`。
-- **推荐**：大批量灌数用 **`s.sql.insert_rows(table, rows)`**（`rows` 为 `list[dict]`）。
-
-### 2.2 幂等与可重复执行
-
-- 先 `query_one` / `count()` 判断已有数据，满足阈值则**跳过**或**仅补差额**。
-- 「清空再灌」须**显式开关**（如 `--force`），**默认**不破坏已有数据。
-
-### 2.3 数据质量
-
-- 枚举字段勿含多余空格；`Date` / `DateTime` 与表定义、SDK 规整规则一致。
-
-### 2.4 输出与验收
-
-- 关键步骤 `output.print`；结束可用 `output.success(...)`。
-- 机器解析约定：`__JSON_SUMMARY__` + JSON（与回归脚本一致）。
-
----
-
-## 3. 推荐模式对照
-
-| 场景          | 推荐做法                                                           |
-| ------------- | ------------------------------------------------------------------ |
-| 少量固定行    | 单条 `INSERT ... VALUES`，元组间**无**行间 `--`；或拆多条 `INSERT` |
-| 多批次、多行  | **`s.sql.insert_rows`** + Python 生成 `list[dict]`                 |
-| 需读 SQL 文件 | 注释写在 **INSERT 块上方**（Python 侧），不要塞进 `VALUES` 中间    |
-
----
-
-## 4. 示例：`insert_rows`（推荐）
-
-将 `space_id`、表名、列名替换为项目 README 与规划文档中的真实值。表须已存在（或在本脚本前文 DDL 创建）。
-
-```python
-"""示例：按空间灌入演示数据（幂等 + insert_rows）
-
-放置：项目/onto_<项目名>/脚本/demo_seed.py
-space_id：见项目 README.md
-"""
-
-import json
-
-
-def main():
-    space_id = "space__your_id_here"  # 与 README 一致
-    table = "your_fact_table"
-    s = space.get(space_id)
-
-    try:
-        n = int(s.sql.query_one(f"SELECT count() FROM {table}") or 0)
-    except Exception:
-        n = 0
-    if n > 0:
-        output.print(f"{table} 已有 {n} 行，跳过灌数")
-        return
-
-    rows = [
-        {"id": "row_001", "name": "样例A", "metric_value": 100.5, "biz_date": "2025-01-10"},
-        {"id": "row_002", "name": "样例B", "metric_value": 200.0, "biz_date": "2025-01-11"},
-    ]
-
-    inserted = s.sql.insert_rows(table, rows)
-    output.print(f"已插入 {inserted} 行")
-    output.success("灌数完成")
-    output.print("__JSON_SUMMARY__" + json.dumps(
-        {"ok": True, "table": table, "inserted": inserted},
-        ensure_ascii=True,
-        default=str,
-    ))
-```
-
----
-
-## 5. 示例：单条 `execute` + `VALUES`
-
-```python
-def main():
-    s = space.get("space__your_id_here")
-    if int(s.sql.query_one("SELECT count() FROM your_fact_table WHERE id = 'row_001'") or 0) > 0:
-        output.print("已存在，跳过")
-        return
-
-    s.sql.execute(
-        """
-        INSERT INTO your_fact_table VALUES
-        ('row_001', '样例A', 100.5, toDate('2025-01-10')),
-        ('row_002', '样例B', 200.0, toDate('2025-01-11'))
-        """
-    )
-    output.success("灌数完成")
-```
-
----
-
-## 6. 发布与执行（dazi-vscode）
-
-在工作区根目录（`--space` 与项目 README 一致）：
-
-```bash
-# 预检
-dazi onto script publish-preview 项目/onto_<项目名>/脚本/demo_seed.py --space <space-id>
-
-# 发布到平台（data_script / 初始化脚本）
-dazi onto script publish 项目/onto_<项目名>/脚本/demo_seed.py --space <space-id>
-
-# 若已入库且已知 script-id，可在平台侧执行；或通过 Onto 侧栏运行
-dazi onto script run --script-id <script-id> --space <space-id> --params '{}'
-```
-
-**参考完整初始化+灌数**：复制 `资源/examples/onto/setup/profit_ontology_init.py` 到 `项目/.../脚本/` 后按空间改 `space_id` 与表名，再发布执行。
-
-> **已废弃**：`dazi-agent run --file "spaces/.../editorial/..."` — 请改用上表 `dazi onto script publish` / `function run`。
-
----
-
-## 7. 相关文档
-
-- [DaziScript SDK 参考](./dazi_script_sdk_reference.md)
-- [本体脚本编写指南](./本体脚本编写指南.md)
-- [本体脚本编写指南](./本体脚本编写指南.md)
-- [本体规划指南](./本体规划指南.md)
+# DaziScript 灌数脚本编写指南
+
+**文档 ID**: `onto/dazi-script-seed-data-guide`  
+**适用**: dazi-vscode v3 + ClickHouse 数据空间
+
+> **用途**：约定工作区内「一次性 / 可重复执行」的造数、补数、历史回填脚本的写法，供人与 LLM 统一遵循。  
+> SDK API 见 **[dazi_script_sdk_reference](./dazi_script_sdk_reference.md)**；目录与发布见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
+
+---
+
+## 1. 什么是灌数脚本
+
+**灌数脚本**指在**已存在表结构**（或同脚本内先 DDL）的前提下，向当前空间写入**演示数据、回归数据、历史样本**的 DaziScript。
+
+### 1.1 放置位置（v3）
+
+| 类型           | 推荐路径                                                                                               |
+| -------------- | ------------------------------------------------------------------------------------------------------ |
+| **项目内开发** | `<工作区根>/项目/<业务名>/本体/ontos/<实现名>/setup/<名称>.py`                                         |
+| **参考示例**   | **`资源/examples/onto/销售示例/setup/`**（init + seed）、**`资源/examples/onto/利润示例/setup/`**（init 模板） |
+
+- `space_id` 以 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 为准（扩展「新建本体实现」时已绑定）。
+- 侧栏 **帮助 → 📎 示例 → 下载所有示例**，或：`dazi examples sync` → `资源/examples/`。
+- 须定义 **`main()`**，**不要**写 `if __name__ == "__main__":`。
+
+> 不再使用 `spaces/<space_id>/editorial/scripts/setup/`、`项目/onto_<名称>/脚本/` 作为 v3 本地约定路径。
+
+---
+
+## 2. 硬约束（违反易导致联调失败）
+
+### 2.1 ClickHouse：`INSERT ... VALUES` 与注释
+
+- **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**。常见报错：`CANNOT_PARSE_INPUT_ASSERTION_FAILED`、`Code: 27`。
+- **允许**：在**整条** `INSERT` **之前**写注释；或拆成多条 `INSERT`。
+- **推荐**：大批量灌数用 **`s.sql.insert_rows(table, rows)`**（`rows` 为 `list[dict]`）。
+
+### 2.2 幂等与可重复执行
+
+- 先 `query_one` / `count()` 判断已有数据，满足阈值则**跳过**或**仅补差额**。
+- 「清空再灌」须**显式开关**（如 `--force`），**默认**不破坏已有数据。
+
+### 2.3 数据质量
+
+- 枚举字段勿含多余空格；`Date` / `DateTime` 与表定义、SDK 规整规则一致。
+
+### 2.4 输出与验收
+
+- 关键步骤 `output.print`；结束可用 `output.success(...)`。
+- 机器解析约定：`__JSON_SUMMARY__` + JSON（与回归脚本一致）。
+
+---
+
+## 3. 推荐模式对照
+
+| 场景          | 推荐做法                                                           |
+| ------------- | ------------------------------------------------------------------ |
+| 少量固定行    | 单条 `INSERT ... VALUES`，元组间**无**行间 `--`；或拆多条 `INSERT` |
+| 多批次、多行  | **`s.sql.insert_rows`** + Python 生成 `list[dict]`                 |
+| 需读 SQL 文件 | 注释写在 **INSERT 块上方**（Python 侧），不要塞进 `VALUES` 中间    |
+
+---
+
+## 4. 示例：`insert_rows`（推荐）
+
+将 `space_id`、表名、列名替换为实现单元 README 与规划文档中的真实值。表须已存在（或在本脚本前文 DDL 创建）。
+
+```python
+"""示例：按空间灌入演示数据（幂等 + insert_rows）
+
+放置：项目/<业务名>/本体/ontos/<实现名>/setup/demo_seed.py
+space_id：见实现单元 README.md
+"""
+
+import json
+
+
+def main():
+    space_id = "space__your_id_here"  # 与 README 一致
+    table = "your_fact_table"
+    s = space.get(space_id)
+
+    try:
+        n = int(s.sql.query_one(f"SELECT count() FROM {table}") or 0)
+    except Exception:
+        n = 0
+    if n > 0:
+        output.print(f"{table} 已有 {n} 行，跳过灌数")
+        return
+
+    rows = [
+        {"id": "row_001", "name": "样例A", "metric_value": 100.5, "biz_date": "2025-01-10"},
+        {"id": "row_002", "name": "样例B", "metric_value": 200.0, "biz_date": "2025-01-11"},
+    ]
+
+    inserted = s.sql.insert_rows(table, rows)
+    output.print(f"已插入 {inserted} 行")
+    output.success("灌数完成")
+    output.print("__JSON_SUMMARY__" + json.dumps(
+        {"ok": True, "table": table, "inserted": inserted},
+        ensure_ascii=True,
+        default=str,
+    ))
+```
+
+---
+
+## 5. 示例：单条 `execute` + `VALUES`
+
+```python
+def main():
+    s = space.get("space__your_id_here")
+    if int(s.sql.query_one("SELECT count() FROM your_fact_table WHERE id = 'row_001'") or 0) > 0:
+        output.print("已存在，跳过")
+        return
+
+    s.sql.execute(
+        """
+        INSERT INTO your_fact_table VALUES
+        ('row_001', '样例A', 100.5, toDate('2025-01-10')),
+        ('row_002', '样例B', 200.0, toDate('2025-01-11'))
+        """
+    )
+    output.success("灌数完成")
+```
+
+---
+
+## 6. 发布与执行（dazi-vscode）
+
+在工作区根目录（`--space` 与实现单元 README 一致）：
+
+```bash
+# 预检
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/setup/demo_seed.py --space <space-id>
+
+# 发布到平台（data_script / 初始化脚本）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/demo_seed.py --space <space-id>
+
+# 若已入库且已知 script-id，可在平台侧执行；或通过 Onto 侧栏运行
+dazi onto script run --script-id <script-id> --space <space-id> --params '{}'
+```
+
+**参考完整初始化+灌数**：
+
+- **推荐（已落地）**：`资源/examples/onto/销售示例/setup/sales_ontology_init.py`、`sales_seed_data.py`（见 [规划示例_产品销售本体规划方案.md](./规划示例_产品销售本体规划方案.md)）
+- **通用模板**：复制 `资源/examples/onto/利润示例/setup/profit_ontology_init.py` 到 `项目/<业务名>/本体/ontos/<实现名>/setup/` 后按空间改 `space_id` 与表名，再发布执行。
+
+> **已废弃**：`dazi-agent run --file "spaces/.../editorial/..."` — 请改用上表 `dazi onto script publish` / `function run`。
+
+---
+
+## 7. 相关文档
+
+- [DaziScript SDK 参考](./dazi_script_sdk_reference.md)
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体规划指南](./本体规划指南.md)

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

@@ -5,14 +5,18 @@
 ## 函数生命周期
 
 ```
-在 项目/onto_<项目名>/脚本/ 编写 .py → publish-preview（预检）→ publish（入库）→ update-code（更新）
+编写 .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`。
+
 ## 新建函数
 
 ```bash
-# 发布新函数（路径指向本体项目 脚本/ 目录）
-dazi onto function publish 项目/onto_<项目名>/脚本/my_func.py \
+# 发布新函数（路径指向本体实现单元 functions/ 目录）
+dazi onto function publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
   --space <space-id> \
   --function-id my_function \
   --display-name "我的函数" \
@@ -22,12 +26,12 @@ dazi onto function publish 项目/onto_<项目名>/脚本/my_func.py \
 或使用 `script publish`（等价，见 [本体脚本编写指南](./本体脚本编写指南.md)）：
 
 ```bash
-dazi onto script publish 项目/onto_<项目名>/脚本/my_func.py \
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
   --space <space-id> \
   --register-function-id my_function
 ```
 
-`<space-id>` 取自 **`项目/onto_<项目名>/README.md`**。
+`<space-id>` 取自 **`项目/<业务名>/本体/ontos/<实现名>/README.md`**。
 
 ## 更新已有函数代码
 
@@ -38,22 +42,45 @@ dazi onto function update-code <function-id> \
   --stem my_func
 ```
 
-`--stem` 为脚本文件名（不含扩展名），须与 `脚本/` 下文件一致。
+`--stem` 为脚本文件名（不含扩展名），须与 `functions/` 下文件一致。
 
 ## 运行函数
 
 ```bash
 dazi onto function run <function-id> \
   --space <space-id> \
-  --params '{"key": "value"}'
+  --params '{}'
 ```
 
-## 保存测试参数
+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 <function-id> \
+# 从 JSON 文件保存（推荐）
+dazi onto function save-test-arguments <ofn_internal_id> \
   --space <space-id> \
-  --params '{"test_param": 42}'
+  --arguments-json-file 项目/<业务名>/本体/ontos/<实现名>/functions/test_arguments/<function_id>.json
+```
+
+```bash
+# 或直接传 JSON（简单参数）
+dazi onto function save-test-arguments <ofn_internal_id> \
+  --space <space-id> \
+  --params '{"v":1,"arguments":{"start_date":"2025-01-01"},"object_type_code":"SalesAnalysis"}'
+```
+
+> **注意**：当前 CLI 的 PATCH 路径使用平台**内部 id**（`ofn_xxx`，由 `dazi onto function list` 返回），**不是** `function_id` 字符串（如 `sales.fn.get_summary` 可能 404）。批量保存可用 `functions/save_test_arguments.ps1`（见本体脚本编写指南）。
+
+验收：
+
+```bash
+dazi onto function get <function-id> --space <space-id>
+# 确认 test_arguments.arguments 与 JSON 一致
 ```
 
 ## 函数脚本结构

package/dist/docs/onto/space-management.md

@@ -23,7 +23,7 @@ dazi onto space list
 dazi onto space init --space-id <space-id>
 ```
 
-本地目录结构：
+本地目录结构（**历史/遗留布局**，由 CLI `space init` 生成）：
 
 ```
 onto/<space-id>/
@@ -37,6 +37,8 @@ onto/<space-id>/
   .dazi-space.json
 ```
 
+> **推荐工作区结构（v3）**：日常开发与文档约定使用 **`项目/<业务名>/本体/ontos/<实现名>/`** 实现单元布局（`README.md` 为 `space_id` 权威来源，`plans/`、`setup/`、`functions/`、`快速启动_<实现名>.md`）。`dazi onto space init` 生成的 **`onto/<space-id>/`** 仅用于 CLI 拉取快照、同步脚本等**对照/迁移**场景，**不应**作为新建本体项目的主开发路径。详见 **[本体规划指南](./本体规划指南.md)**、**[本体脚本编写指南](./本体脚本编写指南.md)**。
+
 ## 拉取快照
 
 将远端本体数据同步到本地：