@dazitech/cli 3.0.8 → 3.0.9

package/README.md

@@ -78,7 +78,7 @@ pnpm run publish:cli
 
 ```powershell
 # 全局
-pnpm add -g @dazitech/cli@3.0.8
+pnpm add -g @dazitech/cli@3.0.9
 
 # 确认 PATH（pnpm 全局 bin）
 pnpm bin -g

package/dist/clis/dazi-app.js

@@ -13077,7 +13077,7 @@ var {
 } = import_index.default;
 
 // cli/shared/src/version.ts
-var DAZI_VERSION = true ? "3.0.8" : readDevVersion();
+var DAZI_VERSION = true ? "3.0.9" : readDevVersion();
 
 // cli/dazi-app/src/lib/httpClient.ts
 init_config();

package/dist/clis/dazi-flow.js

@@ -4982,7 +4982,7 @@ function resolveWorkspace(cwd = process.cwd()) {
 }
 
 // cli/shared/src/version.ts
-var DAZI_VERSION = true ? "3.0.8" : readDevVersion();
+var DAZI_VERSION = true ? "3.0.9" : readDevVersion();
 
 // cli/dazi-flow/src/commands/flows.ts
 var import_path3 = __toESM(require("path"), 1);

package/dist/clis/dazi-onto.js

@@ -3216,7 +3216,7 @@ function resolveWorkspace(cwd = process.cwd()) {
 }
 
 // cli/shared/src/version.ts
-var DAZI_VERSION = true ? "3.0.8" : readDevVersion();
+var DAZI_VERSION = true ? "3.0.9" : readDevVersion();
 
 // cli/shared/src/ontoWorkspaceAudit.ts
 function ontoItemSubdirForScriptType(scriptType) {

package/dist/clis/dazi.js

@@ -3852,7 +3852,7 @@ function resolveWorkspace(cwd = process.cwd()) {
 }
 
 // cli/shared/src/version.ts
-var DAZI_VERSION = true ? "3.0.8" : readDevVersion();
+var DAZI_VERSION = true ? "3.0.9" : readDevVersion();
 
 // cli/shared/src/ontoWorkspaceAudit.ts
 var import_fs3 = __toESM(require("fs"), 1);

package/dist/docs/flow/flow-project-guide.md

@@ -1,7 +1,7 @@
 # 数据流程项目开发指南
 
 **文档 ID**: `flow/flow-project-guide`  
-**适用**: `dazi-vscode` v3.0.7+、`dazi-work` 工作区、业务项目 `项目/<业务名>/`
+**适用**: `dazi-vscode` v3.0.9+、`dazi-work` 工作区、业务项目 `项目/<业务名>/`
 
 ---
 

package/dist/docs/guides/troubleshooting.md

@@ -84,7 +84,7 @@ dazi doctor --workspace-root D:\path\to\dazi-work
 检查 `.cursor/mcp.json` 配置。MCP 需能调用 bundled CLI，示例：
 
 ```powershell
-$env:DAZI_BUNDLED_DIR = "$env:USERPROFILE\.cursor\extensions\dazitech.dazi-vscode-3.0.7\bundled\clis"
+$env:DAZI_BUNDLED_DIR = "$env:USERPROFILE\.cursor\extensions\dazitech.dazi-vscode-3.0.9\bundled\clis"
 node "$env:DAZI_BUNDLED_DIR\dazi.js" mcp stdio
 ```
 
@@ -99,3 +99,14 @@ pnpm run dazi-app -- --version
 ```
 
 应用 CLI 由 bundled + 启动器提供，**不需要** monorepo 源码。
+
+## 本体脚本：发布 / 运行 / test_arguments
+
+| 现象 | 原因 | 处理 |
+| ---- | ---- | ---- |
+| init 报 `sync_metrics` / `cubes` 不存在 | API 误用 | 见 [脚本运行纠错](../onto/脚本运行纠错_商务成本方案开发过程.md) §1 |
+| 函数聚合 SQL 报 `float` 无 `.get()` | `query_one` 用于多列聚合 | 改用 `query()` 取 `rows[0]`，见纠错文档 §2 |
+| `function run --arguments-json-file` unknown | 该子命令不支持此参数 | 先 `save-test-arguments`，再 `function run <function_id>` |
+| `save-test-arguments` 404 | 传了 `function_id` 而非 `ofn_xxx` | `dazi onto function list` 取内部 `id` |
+
+完整 CLI 清单与商务成本方案实录：`dazi docs show onto/script-run-troubleshooting`（`dazi docs sync` 后位于 `资源/docs/onto/`）。

package/dist/docs/index.json

@@ -1,6 +1,6 @@
 {
   "version": "3.0.9",
-  "updatedAt": "2026-06-05T12:00:00.000Z",
+  "updatedAt": "2026-06-06T12:00:00.000Z",
   "docs": [
     {
       "id": "guides/quickstart",
@@ -86,6 +86,18 @@
       "category": "onto",
       "file": "onto/本体规划指南.md"
     },
+    {
+      "id": "onto/naming-conventions",
+      "title": "本体命名规范（物理表 · Cube · 对象）",
+      "category": "onto",
+      "file": "onto/本体命名规范_物理表Cube与对象.md"
+    },
+    {
+      "id": "onto/category-taxonomy-sdk",
+      "title": "349 · 本体分类规划与 SDK 扩展方案",
+      "category": "onto",
+      "file": "onto/本体分类规划与SDK扩展方案.md"
+    },
     {
       "id": "onto/planning-example-profit",
       "title": "规划示例：利润分析本体（GL 域）",
@@ -116,6 +128,13 @@
       "category": "onto",
       "file": "onto/dazi_script_seed_data_guide.md"
     },
+    {
+      "id": "onto/script-run-troubleshooting",
+      "title": "【必读】脚本运行纠错（商务成本实录）",
+      "category": "onto",
+      "file": "onto/脚本运行纠错_商务成本方案开发过程.md",
+      "featured": true
+    },
     {
       "id": "flow/local-files-spec",
       "title": "流程本地文件规范与示例",

package/dist/docs/onto/dazi_script_sdk_reference.md

@@ -3,7 +3,8 @@
 **文档 ID**: `onto/dazi-script-sdk-reference`  
 **适用**: dazi-vscode v3 + 搭子平台 DaziScript（ClickHouse 数据空间）
 
-> 给 LLM 与开发者提供精简、可执行的 SDK 规范。脚本目录、类型与 **`dazi onto script publish`** 等见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
+> 给 LLM 与开发者提供精简、可执行的 SDK 规范。脚本目录、类型与 **`dazi onto script publish`** 等见 **[本体脚本编写指南](./本体脚本编写指南.md)**。  
+> **执行脚本前必读（强制）**：[脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md)。
 
 ## 1. 工作区与脚本放置（dazi-vscode）
 
@@ -102,6 +103,24 @@
 - `s.sql.query(sql)` / `s.sql.query_one(sql)` / `s.sql.execute(sql)`
 - `s.sql.insert_rows(table, rows)`（`rows` 为 `list[dict]`）
 
+**`query_one` 与多列聚合**
+
+- `query_one` 适合 `SELECT count()` 等**单列标量**；对 `SELECT sum(a), count(b) ...` 等多列聚合，**勿**对返回值调用 `.get()`（可能得到 float 而非 dict）。
+- **推荐**：`rows = s.sql.query(sql); row = rows[0] if rows else {}`（函数脚本内为 `p.sql.query`）。详见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md#2-函数聚合查询返回类型错误)。
+
+### 5.2.1 本体函数输出（`ontology_function`）
+
+与 setup/seed 不同，本体函数运行时平台注入 `ctx`、`space`、`onto`：
+
+| 要点 | 说明 |
+| ---- | ---- |
+| 入口 | `def main():`（**无** `params` 形参） |
+| 入参 | `ctx.params` → `p.get_params()` |
+| 出参 | **`return p.function_result(columns=..., data=..., row_count=...)`** |
+| 禁止 | `output.print_json()`（`OutputModule` 无此方法）、裸 `return {"k": v}` |
+
+标准模板：`资源/examples/onto/_templates/ontology_function_template.py`。详见 [function-guide](./function-guide.md#函数脚本结构标准模板)、[脚本运行纠错 §3](./脚本运行纠错_商务成本方案开发过程.md#3-函数输出方式错误outputprint_json)。
+
 **ClickHouse：`INSERT ... VALUES` 与注释**
 
 - **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**，否则易出现 `Code: 27` 等解析错误。
@@ -109,25 +128,70 @@
 
 ### 5.3 `s.tables`
 
-- `s.tables.register(table_name, label=...)`
-- `s.tables.sync_columns(table_name)`
+- `s.tables.register(table_name, display_name=..., description=..., label=..., category_347=...)` — `label` 为 `display_name` 简写别名；已注册时可刷新表显示名与说明；`category_347` 为 347 标准中文名（如 `"维度表"`），注册后**即时挂载**平台分类
+- `s.tables.sync_columns(table_name)` — 从物理库同步列；未显式传入元数据时仅**推断** `display_name`（token 词典），**不**写入业务 `description`
+- `s.tables.set_column_meta(table_name, columns=[{name, display_name, description, business_role}], force=False)` — 批量写入列显示名与说明（须先 register + sync_columns）
+- `s.tables.register_with_meta(table_name, display_name=..., description=..., columns=[...], force_column_meta=False, category_347=...)` — 上三者合一（**推荐** setup 脚本使用）
 - `s.tables.list()` / `s.tables.discover()`
-- `s.tables.add_relationship(from_table, to_table, join_sql, relationship_type="many_to_one", join_keys=None, description=None)` — 注册**数据空间表间关系**（幂等）；`join_keys` 示例：`[{"from": "product_id", "to": "product_id"}]`
+- `s.tables.add_relationship(from_table, to_table, join_sql, relationship_type="many_to_one", join_keys=None, description=None, category_347=...)` — 注册**数据空间表间关系**（幂等）；`category_347` 如 `"主数据关联"`、`"时间关联"`
 
 ### 5.4 Cube
 
-- `s.register_cube(name, table, title, measures, dimensions)`
+- `s.register_cube(name, table, title, measures, dimensions, category_347=...)` — `category_347` 如 `"流程型"`、`"主体型"`
 
 ### 5.5 `s.onto`
 
-- `s.onto.define_object_type(code, name, ...)`
+- `s.onto.define_object_type(code, name, ..., category_347=...)` — 如 `category_347="主数据"`
 - `s.onto.bind_source(object_type_code, "dazi_cube", config={"cube": "CubeName"})`
 - `s.onto.define_property(...)`
-- `s.onto.define_link_type(code, name, from_object_type_code, to_object_type_code, ...)`
-- `s.onto.register_function(function_id, adapter, ...)`
+- `s.onto.define_link_type(code, name, from_object_type_code, to_object_type_code, ..., category_347=...)` — 如 `category_347="归属关系"`
+- `s.onto.register_function(function_id, adapter, ..., category_347=...)` — 如 `category_347="总览分析"`
 - `s.onto.define_action(action_code, ...)`
 
-### 5.6 `s.ontology` / `s.ontology_rules` / `s.scripts`
+**常见误用**（setup 脚本）：不存在 `s.onto.sync_metrics()`、`s.cubes.upsert`；`define_object_type` 第二参数为 `name` 非 `label`；链接类型参数为 `from_object_type_code` / `to_object_type_code`。对照表见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md#1-setup-脚本-api-误用多次尝试才正确)。
+
+### 5.6 `s.categories`（347 对齐分类）
+
+挂载到 `ads_categories` 默认根下的平级目录，桥表关联表/Cube/对象/关系/链接/函数。分类名必须与 [347 规范](./本体命名规范_物理表Cube与对象.md) 标准中文名一致。详见 [349 方案](./本体分类规划与SDK扩展方案.md)。
+
+- `s.categories` — `CategoryManager` 实例（按空间懒加载）
+- `s.categories.ensure_347(kind, category)` — 确保平级分类目录存在（幂等）；`kind` 支持 `table` / `cube` / `object` / `relation` / `link` / `function`
+- `s.categories.assign_table(category, table_name)` — 挂载物理表
+- `s.categories.assign_cube(category, cube_name)` — 挂载 Cube
+- `s.categories.assign_object(category, object_type_code)` — 挂载对象类型
+- `s.categories.assign_relation(category, from_table, to_table)` — 挂载表间关系
+- `s.categories.assign_link(category, link_code)` — 挂载链接类型
+- `s.categories.assign_function(category, function_id)` — 挂载本体函数（如 `profit.fn.get_summary`）
+- `s.categories.auto_assign_tables(table_names)` — 按表名前缀自动推断 347 类别并挂载
+- `s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)` — 批量应用 init 顶部注册表
+
+**`CATEGORY_REGISTRY` 结构**（与规划附录 B 对齐）：
+
+```python
+CATEGORY_REGISTRY = {
+    "table": {"维度表": ["dim_account"], "事实表": ["fact_gl_journal_entry"]},
+    "cube": {"流程型": ["ActualCube"], "主体型": ["AccountActualCube"]},
+    "object": {"主数据": ["Account"], "事务": ["JournalEntry"], "分析": ["ProfitAnalysis"]},
+    "relation": {"时间关联": [("fact_x", "dim_date")], "主数据关联": [("fact_x", "dim_y")]},
+    "link": {"归属关系": ["entry_belongs_account"], "分析归因": ["analysis_by_account"]},
+    "function": {"总览分析": ["profit.fn.get_summary"]},  # 函数未注册时须 skip_missing=True
+}
+```
+
+**两种用法**（可并存，挂载幂等）：
+
+1. **批量**（推荐 init 末尾）：`s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)`
+2. **内联**（注册时即时挂载）：
+
+```python
+s.tables.register_with_meta("dim_product", display_name="产品维表", category_347="维度表", ...)
+s.register_cube("SalesCube", table=fact, title="...", category_347="流程型", ...)
+s.onto.define_object_type("Product", "产品", category_347="主数据")
+s.tables.add_relationship(..., category_347="主数据关联")
+s.onto.define_link_type("order_contains_product", "...", ..., category_347="归属关系")
+```
+
+### 5.7 `s.ontology` / `s.ontology_rules` / `s.scripts`
 
 见上文；规则：`ensure_rule_set` + `upsert_rule`；脚本记录：`create` / `ensure` / `list` 等。
 
@@ -135,12 +199,13 @@
 
 1. 确认 `space_id`（实现单元 README）
 2. 建表与灌数（`s.sql`；灌数规范见 seed 指南）
-3. `s.tables.register` + `sync_columns`
+3. `s.tables.register_with_meta`（`TABLE_REGISTRY` 含表/列 `display_name`、`description`）
 4. **`s.tables.add_relationship`**（与规划「表间关系」一致；**勿省略**）
 5. `s.register_cube`
 6. `s.onto` 定义对象、属性、链接
 7. 注册函数/动作并 `features.attach`；**发布后** CLI `save-test-arguments` 写入 `test_arguments`（见 [function-guide](./function-guide.md)）
-8. 配置规则（如需要）
+8. `s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)`（347 对齐分类）
+9. 配置规则（如需要）
 
 ## 7. 在 dazi-vscode 中发布与运行
 
@@ -174,5 +239,6 @@ dazi onto function run my_func --space <space-id> --params '{}'
 
 - **规划全文（推荐）**：**`资源/docs/onto/规划示例_产品销售本体规划方案.md`**（含表间关系、test_arguments）
 - **完整落地参考**（init / seed / 7 个 sales 函数）：**`项目/潘达石化/本体/ontos/产品销售本体方案/`**
-- **利润示例（GL 域）**：`资源/examples/onto/利润示例/setup/profit_ontology_init.py`、`profit_seed_data.py`、`function/profit_fn_*.py`、`function/test_arguments/`
+- **利润示例（GL 域）**：`资源/examples/onto/利润示例/setup/profit_ontology_init.py`、`profit_seed_data.py`、`functions/profit_fn_*.py`、`functions/test_arguments/`
 - **销售示例（推荐，含表间关系 + test_arguments）**：`资源/examples/onto/销售示例/setup/sales_ontology_init.py`、`sales_seed_data.py`、`functions/sales_fn_*.py`
+- **脚本运行纠错（实录）**：`资源/docs/onto/脚本运行纠错_商务成本方案开发过程.md` — setup API、`query_one`、CLI test_arguments 踩坑

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

@@ -2,6 +2,8 @@
 
 **文档 ID**: `onto/function-guide`
 
+> **执行脚本前必读**：[`脚本运行纠错_商务成本方案开发过程.md`](./脚本运行纠错_商务成本方案开发过程.md)（CLI、SQL、`output.print_json` 等常见误用）。
+
 ## 函数生命周期
 
 ```
@@ -14,21 +16,13 @@
 
 ## 新建函数
 
-```bash
-# 发布新函数（路径指向本体实现单元 functions/ 目录）
-dazi onto function publish 项目/<业务名>/本体/ontos/<实现名>/functions/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
+# 发布新函数（路径指向本体实现单元 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>` 取自 **`项目/<业务名>/本体/ontos/<实现名>/README.md`**。
@@ -36,7 +30,6 @@ dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/m
 ## 更新已有函数代码
 
 ```bash
-# 用工作副本快速更新（不做完整 publish 流程）
 dazi onto function update-code <function-id> \
   --space <space-id> \
   --stem my_func
@@ -52,6 +45,8 @@ dazi onto function run <function-id> \
   --params '{}'
 ```
 
+> **`function run` 不支持 `--arguments-json-file`**。详见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md#4-cli-参数认知错误)。
+
 PowerShell 下复杂 JSON 建议用环境变量 `DAZI_PARAMS` 或侧栏运行（使用已保存的 `test_arguments`）。详见 [本体脚本编写指南](./本体脚本编写指南.md#函数测试参数test_arguments发布后必做)。
 
 ## 保存测试参数（test_arguments）
@@ -61,35 +56,68 @@ PowerShell 下复杂 JSON 建议用环境变量 `DAZI_PARAMS` 或侧栏运行（
 **本地文件**：`functions/test_arguments/<function_id>.json`（格式见 [本体脚本编写指南](./本体脚本编写指南.md)）。
 
 ```bash
-# 从 JSON 文件保存（推荐）
 dazi onto function save-test-arguments <ofn_internal_id> \
   --space <space-id> \
   --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"}'
-```
+> **注意**：须用平台**内部 id** `ofn_xxx`（`dazi onto function list` 返回），不是 `function_id` 字符串。
 
-> **注意**：当前 CLI 的 PATCH 路径使用平台**内部 id**（`ofn_xxx`，由 `dazi onto function list` 返回），**不是** `function_id` 字符串（如 `sales.fn.get_summary` 可能 404）。批量保存可用 `functions/save_test_arguments.ps1`（见本体脚本编写指南）。
+## 函数脚本结构（标准模板）
 
-验收：
+本体函数与 setup/seed 脚本不同：**`main()` 无参**，平台注入 `ctx`、`space`、`onto`；**必须 return** `function_result`，**禁止** `output.print_json()`。
 
-```bash
-dazi onto function get <function-id> --space <space-id>
-# 确认 test_arguments.arguments 与 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}` |
 
-```python
-def main(params: dict) -> dict:
-    """
-    函数入口，params 由平台传入。
-    返回值会作为函数输出。
-    """
-    return {"result": params.get("value", 0) * 2}
-```
+可复制模板：`资源/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

@@ -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/`） |