@dazitech/cli 3.0.7 → 3.0.9

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

@@ -2,67 +2,122 @@
 
 **文档 ID**: `onto/function-guide`
 
+> **执行脚本前必读**：[`脚本运行纠错_商务成本方案开发过程.md`](./脚本运行纠错_商务成本方案开发过程.md)（CLI、SQL、`output.print_json` 等常见误用）。
+
 ## 函数生命周期
 
 ```
-在 项目/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 \
-  --space <space-id> \
-  --function-id my_function \
-  --display-name "我的函数" \
-  --entry main
-```
+## 新建函数
 
-或使用 `script publish`（等价，见 [本体脚本编写指南](./本体脚本编写指南.md)）：
+**推荐**：复制 `资源/examples/onto/_templates/ontology_function_template.py` 或 `销售示例/functions/sales_fn_*.py`，再改业务逻辑。
 
 ```bash
-dazi onto script publish 项目/onto_<项目名>/脚本/my_func.py \
+# 发布新函数（路径指向本体实现单元 functions/ 目录）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
   --space <space-id> \
-  --register-function-id my_function
+  --register-function-id domain.fn.my_analysis
 ```
 
-`<space-id>` 取自 **`项目/onto_<项目名>/README.md`**。
+`<space-id>` 取自 **`项目/<业务名>/本体/ontos/<实现名>/README.md`**。
 
 ## 更新已有函数代码
 
 ```bash
-# 用工作副本快速更新（不做完整 publish 流程）
 dazi onto function update-code <function-id> \
   --space <space-id> \
   --stem my_func
 ```
 
-`--stem` 为脚本文件名（不含扩展名），须与 `脚本/` 下文件一致。
+`--stem` 为脚本文件名（不含扩展名），须与 `functions/` 下文件一致。
 
 ## 运行函数
 
 ```bash
 dazi onto function run <function-id> \
   --space <space-id> \
-  --params '{"key": "value"}'
+  --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 <function-id> \
+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
 ```
 
-## 函数脚本结构
+> **注意**：须用平台**内部 id** `ofn_xxx`（`dazi onto function list` 返回），不是 `function_id` 字符串。
+
+## 函数脚本结构（标准模板）
+
+本体函数与 setup/seed 脚本不同：**`main()` 无参**，平台注入 `ctx`、`space`、`onto`；**必须 return** `function_result`，**禁止** `output.print_json()`。
 
 ```python
-def main(params: dict) -> dict:
-    """
-    函数入口，params 由平台传入。
-    返回值会作为函数输出。
-    """
-    return {"result": params.get("value", 0) * 2}
+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/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)**。
+
 ## 拉取快照
 
 将远端本体数据同步到本地：

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

@@ -0,0 +1,168 @@
+# 349 · 本体分类规划与 SDK 扩展方案
+
+**文档 ID**：`onto/category-taxonomy-sdk`
+
+> **文档编号**：349  
+> **类型**：规范 + 实施方案（对齐 §347 · `ads_categories` 平台分类）  
+> **同步路径**：`dazi docs sync` → `资源/docs/onto/本体分类规划与SDK扩展方案.md`  
+> **前置依据**：[本体命名规范 §347](./本体命名规范_物理表Cube与对象.md)、[本体规划指南](./本体规划指南.md)
+
+---
+
+## 1. 目标
+
+将 **347 语义分类**（规划表「类别/分类」列）与 **`ads_categories` 平台分类**（侧栏分组、桥表挂载）打通，支持 init 脚本幂等注册。
+
+**约束**：本体规划阶段分类 **全部平级**（挂空间默认根下，不建多层树）。
+
+---
+
+## 2. 两类分类，一套语言
+
+| 维度 | 347 语义分类 | ads_categories 平台分类 |
+|------|-------------|------------------------|
+| 作用 | 规划自检、命名约束 | 侧栏展示、资源分组 |
+| 对齐 | 平台 `category_name` **=** 347 标准中文名 | 禁止自定义别名 |
+
+---
+
+## 3. 347 标准分类字典（6 类资源）
+
+### 3.1 物理表（`category_kind=dataspace_table`）
+
+| 347 类别 | 前缀 | 平台分类名 |
+|----------|------|------------|
+| 时间维 | `dim_date` | 时间维 |
+| 维度表 | `dim_` | 维度表 |
+| 事实表 | `fact_` | 事实表 |
+| 桥表 | `bridge_` | 桥表 |
+| 映射表 | `map_` | 映射表 |
+| 配置表 | `cfg_` | 配置表 |
+| 汇总表 | `agg_` | 汇总表 |
+| 临时表 | `tmp_` | 临时表 |
+
+### 3.2 Cube（`category_kind=cube`）
+
+| 347 类别 | 平台分类名 |
+|----------|------------|
+| Process | 流程型 |
+| Subject | 主体型 |
+| Comparison | 对比型 |
+| Snapshot | 快照型 |
+
+> 时间增强不单独建 Cube（347 §4.2），不设平台分类。
+
+### 3.3 本体对象（`category_kind=ontology_object_type`）
+
+| 347 分类 | 平台分类名 |
+|----------|------------|
+| Master | 主数据 |
+| Transaction | 事务 |
+| Analytical | 分析 |
+| Reference | 参考 |
+| Configuration | 配置 |
+
+### 3.4 表间关系（`category_kind=relation`，347 扩展）
+
+| 关系类别 | 平台分类名 |
+|----------|------------|
+| 时间关联 | 时间关联 |
+| 主数据关联 | 主数据关联 |
+| 层级自关联 | 层级自关联 |
+| 预实关联 | 预实关联 |
+| 桥接关联 | 桥接关联 |
+
+### 3.5 本体链接（`category_kind=ontology_link_type`，347 扩展）
+
+| 链接类别 | 平台分类名 |
+|----------|------------|
+| 归属/包含 | 归属关系 |
+| 分析归因 | 分析归因 |
+| 层级/结构 | 层级关系 |
+| 对比/映射 | 对比关系 |
+
+### 3.6 本体函数（`category_kind=ontology_function`，347 扩展）
+
+| 函数类别 | 平台分类名 |
+|----------|------------|
+| 总览 | 总览分析 |
+| 趋势 | 趋势分析 |
+| 结构 | 结构分析 |
+| 预实 | 预实分析 |
+| 组织 | 组织分析 |
+
+---
+
+## 4. SDK 设计
+
+### 4.1 模块
+
+```python
+s.categories                    # CategoryManager
+s.categories.apply_registry(CATEGORY_REGISTRY)
+s.categories.ensure_347(kind="table", category="维度表")
+s.categories.assign_table("维度表", "dim_account")
+s.categories.auto_assign_tables(["dim_account", "fact_gl_journal_entry"])
+```
+
+### 4.2 init 脚本
+
+**方式 A — 批量**（推荐）：顶部 `CATEGORY_REGISTRY` 与规划 **附录 B** 对齐；资源注册完成后：
+
+```python
+cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+**方式 B — 内联**（P2）：各注册 API 支持 `category_347=`，注册后即时挂载（与方式 A 幂等可并存）：
+
+```python
+s.tables.register_with_meta("dim_product", ..., category_347="维度表")
+s.register_cube("SalesCube", ..., category_347="流程型")
+s.onto.define_object_type("Product", "产品", category_347="主数据")
+s.tables.add_relationship(..., category_347="时间关联")
+s.onto.define_link_type(..., category_347="归属关系")
+s.onto.register_function("sales.fn.get_summary", adapter, category_347="总览分析")
+```
+
+函数类资源若 init 未 `register_function`，批量方式须 `skip_missing=True`。
+
+---
+
+## 5. 规划与 init 约定
+
+| 产出 | 位置 | 说明 |
+| ---- | ---- | ---- |
+| 规划附录 B | `plans/<主题>.md` | 6 类资源分类对照表 |
+| `CATEGORY_REGISTRY` | `setup/*_ontology_init.py` 顶部 | 与附录 B 逐行一致 |
+| 分类步骤 | init 末尾 | `[10/10] apply_registry` |
+
+参考：[规划示例_产品销售](./规划示例_产品销售本体规划方案.md#附录-b347-分类挂载对照表category_registry)、[规划示例_利润分析](./规划示例_利润分析本体方案.md#附录-b347-分类挂载对照表category_registry)。
+
+---
+
+## 6. 验收标准
+
+1. 平台侧栏分类名与 347 标准表一致
+2. `dim_*` / `fact_*` 自动归入维度表/事实表
+3. init 重跑幂等，桥表不重复
+4. `CATEGORY_REGISTRY` 与规划附录 B 逐行一致
+
+---
+
+## 7. 相关文档
+
+| 文档 | 路径（`dazi docs sync` 后） |
+| ---- | --------------------------- |
+| 347 命名规范 | `资源/docs/onto/本体命名规范_物理表Cube与对象.md` |
+| 本体规划指南 | `资源/docs/onto/本体规划指南.md` |
+| SDK 参考 §5.6 | `资源/docs/onto/dazi_script_sdk_reference.md` |
+| 脚本编写指南 | `资源/docs/onto/本体脚本编写指南.md` |
+
+---
+
+**变更记录**
+
+| 日期 | 说明 |
+| ---- | ---- |
+| 2026-06-06 | 首版：对齐 347 分类方案 + SDK 设计 |
+| 2026-06-06 | 改为 `dazi-vscode` 完整可同步正文（客户环境不依赖 `dazi/docs/`） |