@dazitech/cli 3.0.8 → 3.0.9

package/dist/docs/onto//346/234/254/344/275/223/345/221/275/345/220/215/350/247/204/350/214/203_/347/211/251/347/220/206/350/241/250Cube/344/270/216/345/257/271/350/261/241.md

@@ -0,0 +1,402 @@
+# 本体命名规范 · 物理表、Cube 与对象
+
+**文档 ID**: `onto/naming-conventions`
+
+> **类型**：规范（物理层 · Cube 层 · 本体层 · 三层对照）  
+> **适用版本**：`dazi-vscode` v3.0.9+  
+> **前置阅读**：[本体规划指南](./本体规划指南.md)
+
+---
+
+## 目录
+
+1. [总则：三层各有一套命名语言](#1-总则三层各有一套命名语言)
+2. [物理表：类别与前缀](#2-物理表类别与前缀)
+3. [时间维 dim_date（强制）](#3-时间维-dim_date强制)
+4. [Cube：类别与命名](#4-cube类别与命名)
+5. [本体对象：Palantir 思想与分类](#5-本体对象palantir-思想与分类)
+6. [链接类型命名](#6-链接类型命名)
+7. [三层对照与迁移示例（销售域）](#7-三层对照与迁移示例销售域)
+8. [规划文档写法与自检清单](#8-规划文档写法与自检清单)
+9. [相关文档索引](#9-相关文档索引)
+
+---
+
+## 1. 总则：三层各有一套命名语言
+
+本体规划须同时设计 **物理表、Cube、本体对象** 三层；三者 **刻意区分命名**，避免「一张表一个对象一个 Cube 同名」的一一复制。
+
+| 层级 | 面向谁 | 命名风格 | 核心原则 |
+| ---- | ------ | -------- | -------- |
+| **物理表** | DBA / ETL / ClickHouse | **`{前缀}_{实体}`** snake_case | 从表名即可判断存储角色（事实/维/桥/配置…） |
+| **Cube** | 分析 / 报表 / 语义层 | **`{主题}{Analytics\|Cube}`** PascalCase | 表达**分析主题与粒度**，可共享同一 fact 表 |
+| **本体对象** | 业务 / 产品 / 智能体 | **`{业务名词}`** PascalCase，**无前缀** | 贴近 **业务世界**（Palantir Object Type 思想），用**分类**而非前缀区分角色 |
+
+```text
+  业务世界（本体）          分析语义（Cube）           存储落地（物理表）
+  ─────────────────        ─────────────────         ─────────────────
+  Product          ←──    ProductSalesCube    ←──   dim_product
+  SalesOrder       ←──    SalesCube           ←──   fact_sales_order_line
+  (时间分析)        ←──    (SalesCube 时间维)   ←──   dim_date + date_key
+```
+
+**规划顺序（推荐）**：
+
+1. 列出 **本体对象类型** 与 **链接**（业务语言）
+2. 反推需要的 **Cube**（读模型 / 度量白名单）
+3. 再落 **物理表**（fact / dim / dim_date / bridge…）
+
+---
+
+## 2. 物理表：类别与前缀
+
+### 2.1 命名格式
+
+```text
+{类别前缀}_{业务域}_{实体}[_{粒度}]
+```
+
+- 全小写 **snake_case**
+- **类别前缀必填**；禁止 `product_master`、`customer_dimension` 等混用后缀
+- 单域实现可省略业务域：`dim_product`；多域共空间时用 `dim_sales_product`
+
+### 2.2 表类别（7 类 + 强制时间维）
+
+| 前缀 | 角色 | 典型粒度 | 本体读模型 | 规划必写 |
+| ---- | ---- | -------- | ---------- | -------- |
+| **`dim_`** | 维度 / 主数据 | 一行一实体 | 是（或经 JOIN 进 Cube） | 业务维表必写 |
+| **`fact_`** | 事实 / 明细 / 事件 | 一行一业务事件 | **是（Cube 主源）** | 核心必写 |
+| **`bridge_`** | 桥表（多对多） | 关系对 | 视场景 | 有多对多时必写 |
+| **`map_`** | 映射 / 对照 / 码表 | 源→目标 | 辅助 | 有码表转换时写 |
+| **`cfg_`** | 配置 / 参数 / 版本 | 配置行 | 一般不作分析对象 | 有预算版本等时写 |
+| **`agg_`** | 预聚合 / 主题汇总 | 维组合汇总 | 可选（性能层） | 有固定汇总口径时写 |
+| **`tmp_`** | 临时 / 中间 | 不限 | **否** | 仅 ETL 说明，不进核心表清单 |
+
+### 2.3 各类约束摘要
+
+**`fact_*`**
+
+- 含可加性度量或事件计数
+- **必须**含 **`date_key`** → `dim_date`（见 §3）
+- 可保留业务日期列（如 `order_date`）作展示；**分析 JOIN 优先 `date_key`**
+- 外键与维表 PK **同名**：`product_id`、`customer_id`
+
+**`dim_*`**
+
+- PK：`{entity}_id`（或与事实表 FK 统一的 `{entity}_key`）
+- 规划注明 SCD 策略（Type 1 / Type 2）
+
+**`bridge_*` / `map_*` / `cfg_*` / `agg_*` / `tmp_*`**
+
+- 见 §2.2；`tmp_*` 不得作为 `bind_source` 或 Cube 唯一事实源
+
+### 2.4 主键 / 外键约定
+
+| 对象 | 约定 | 示例 |
+| ---- | ---- | ---- |
+| 时间维 PK | **`date_key`** Int32 | `20250605`（YYYYMMDD） |
+| 业务维 PK | `{entity}_id` | `product_id` |
+| 事实表 FK | 与维表 PK **同名** | `date_key`, `product_id` |
+
+---
+
+## 3. 时间维 dim_date（强制）
+
+### 3.1 何时必须
+
+| 场景 | 要求 |
+| ---- | ---- |
+| 任意含日期的 **`fact_*`** | **必须** `dim_date` + 事实表 **`date_key`** |
+| 仅时点快照、无趋势 | 可豁免，规划 **显式说明理由** |
+| 公历 + 会计期间 | **一张** `dim_date`，用列扩展（`fiscal_year`, `fiscal_period`） |
+
+### 3.2 最小字段集
+
+**表名**：`dim_date`（**全空间通常唯一一张**）
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| **`date_key`** | **Int32** | **PK**，推荐 `YYYYMMDD` |
+| `calendar_date` | Date | 自然日 |
+| `year` / `quarter` / `month` | Int | 公历层次 |
+| `week_of_year` / `day_of_week` | Int | 周、星期 |
+| `is_weekend` | UInt8 | 0/1 |
+| `year_month` | String | 如 `2025-06` |
+| `fiscal_year` / `fiscal_period` | Int | 会计日历（可选） |
+
+**排序键**：`ORDER BY (date_key)`
+
+### 3.3 事实表关联
+
+```text
+fact_*.date_key  →  dim_date.date_key
+```
+
+灌数：`date_key = toYYYYMMDD(order_date)`。YoY/MoM 函数优先通过 **`dim_date`** 做 period shift，而非硬编码 `toYear(order_date)`。
+
+---
+
+## 4. Cube：类别与命名
+
+Cube 是 **物理表 → 分析语义 → 本体读模型** 的中间层；命名应体现 **分析主题**，而非复制表名或对象名。
+
+### 4.1 命名格式
+
+```text
+{主题域}{分析焦点}{Cube|Analytics}
+```
+
+| 规则 | 说明 |
+| ---- | ---- |
+| **PascalCase** | `SalesCube`、`ProductSalesCube` |
+| **后缀** | 推荐 **`Cube`**（与平台 `register_cube` 一致）；可选 `Analytics`（如 `SalesAnalytics`），**同一实现单元内统一一种** |
+| **禁止** | 与对象 `code` 完全相同（`Product` ≠ Cube 名）；与物理表名相同（`dim_product`） |
+| **qualified_name** | 成员为 `CubeName.member`（如 `SalesCube.sales_amount`） |
+
+### 4.2 Cube 类别
+
+| 类别 | 用途 | 事实源 | 命名示例 |
+| ---- | ---- | ------ | -------- |
+| **流程型 Process** | 以事务/事件为主线，多维度切片 | 主 `fact_*` | `SalesCube`、`GlJournalCube` |
+| **主体型 Subject** | 以单一业务主体聚合（产品/客户/科目） | 同一 fact 或 subject 切片 | `ProductSalesCube`、`CustomerSalesCube` |
+| **对比型 Comparison** | 预实、同比口径、A/B 版本 | 多个 fact 或带 version 维 | `BudgetVsActualCube` |
+| **快照型 Snapshot** | 时点库存、余额（非可加事件） | 快照 fact 或 agg | `InventorySnapshotCube` |
+| **时间增强** | 时间智能（通常 **不单独建 Cube**） | 通过 **`dim_date`** JOIN 进 Process/Subject Cube | 优先在 `SalesCube` 上挂 `year`/`month`/`fiscal_period` 维，而非孤立 `TimeSalesCube` |
+
+> **建议**：旧示例中的 `TimeSalesCube` 在新规范下 **合并进 Process Cube** + **`dim_date`**；仅当时间主题完全独立（如专用日历配置分析）才保留独立 Cube。
+
+### 4.3 每个 Cube 规划必写
+
+| 列 | 说明 |
+| -- | ---- |
+| Cube 名 | 符合 §4.1 |
+| **类别** | Process / Subject / Comparison / Snapshot |
+| 事实源表 | 主 `fact_*` 表名 |
+| 时间维 | 是否 JOIN `dim_date`；时间成员来自哪些列 |
+| 维度 | GROUP BY / 筛选字段 |
+| 度量 | 列名、聚合、业务含义 |
+| 派生度量 | 表达式与口径 |
+| **支撑的对象类型** | 哪些对象 `bind_source` 绑定本 Cube |
+
+### 4.4 Cube 与多对象
+
+- **多对象可绑同一 Cube**（如 `SalesOrder` 与 `SalesAnalysis` 均绑 `SalesCube`，属性映射不同）
+- **一对象只绑一个主 Cube**（读模型）；明细补全可在函数 SQL 中 JOIN `dim_*`
+- 同一 `fact_*` 可注册 **多个 Cube**（不同维度切片）
+
+---
+
+## 5. 本体对象：Palantir 思想与分类
+
+### 5.1 与 Palantir Foundry Ontology 的对照
+
+| Palantir 概念 | 搭子平台 | 命名要点 |
+| ------------- | -------- | -------- |
+| **Object Type** | `define_object_type(code, name, ...)` | **`code` 无前缀**，PascalCase 单数业务名 |
+| **Property** | `define_property` | 业务属性名；度量/维度带 Cube `qualified_name` |
+| **Link Type** | `define_link_type` | 业务关系语义，非表 FK 名 |
+| **Action Type** | `define_action` | 动词短语 code |
+| **Function** | `register_function` / 函数脚本 | `domain.fn.name`（带点号命名空间） |
+
+**核心思想**（规划阶段强制）：
+
+- 对象类型描述 **业务世界中「是什么」**，不是「哪张表」
+- **先对象与链接，后表与 Cube**；允许多表/多 Cube 支撑一对象，也允许多对象视角看同一 fact
+- 对象 **`code` 不加 `dim_` / `fact_` / `Obj` 前缀**；分类用 **文档标签 + 规划表格**，不写入 `code`
+
+### 5.2 对象类型 code 格式
+
+```text
+{BusinessNoun}           # PascalCase，英文单数为主
+{BusinessNoun}{Role}     # 必要时消歧，如 BudgetLine、SalesOrderLine
+```
+
+| 规则 | 正确 | 错误 |
+| ---- | ---- | ---- |
+| 业务名词 | `Product`, `Customer`, `SalesOrder` | `dim_product`, `ProductObject` |
+| 稳定标识 | `JournalEntry`, `Account` | `TblAccount`, `FactSales` |
+| 与表/Cube 区分 | `Product` + `ProductSalesCube` + `dim_product` | 三者同名 |
+
+**中文 `name`**：面向业务用户（产品、客户、销售订单）；**`code`**：面向 API / 脚本 / 链接引用。
+
+### 5.3 对象分类（无 code 前缀）
+
+规划文档中为每个对象类型标注 **以下一类**（可多标签，但须有一个主分类）：
+
+| 分类 | 英文标签 | 业务含义 | 典型对象 | 读模型来源 |
+| ---- | -------- | -------- | -------- | ---------- |
+| **主数据** | `Master` | 长期存在、可被多次引用 | `Product`, `Customer`, `Account`, `CostCenter` | Subject Cube 或 `dim_*` + 函数补全 |
+| **事务/事件** | `Transaction` | 一次业务发生、有时间性 | `SalesOrder`, `JournalEntry`, `BudgetLine` | Process Cube / 主 `fact_*` |
+| **分析上下文** | `Analytical` | 分析会话/切片上的「上下文对象」，非 ERP 主数据 | `SalesAnalysis`, `ProfitAnalysis` | Process Cube（常无独立 `dim_*`） |
+| **参考** | `Reference` | 枚举型、码表级、体量小 | `Channel`, `Currency`, `OrderStatus` | `dim_*` 或 Cube 维度 |
+| **配置** | `Configuration` | 版本、日历、口径规则 | `BudgetVersion`, `FiscalCalendar` | `cfg_*` 或专用 dim |
+
+**Palantir 式自检**：
+
+- 能否用 **一句业务话** 向非技术人员解释该对象？（「销售订单是一次成交记录」✓）
+- 链接是否表达 **业务关系** 而非「表 A 的 id 等于表 B 的 id」？
+- Action/Function 是否挂在 **对象** 上，而非挂在表名上？
+
+### 5.4 bind_source 约定
+
+| 对象分类 | 典型 bind_source |
+| -------- | ---------------- |
+| Master / Reference | Subject Cube 或 Process Cube 的子集 |
+| Transaction | Process Cube |
+| Analytical | Process Cube（同一 fact，属性偏度量/筛选） |
+| Configuration | 可无 Cube；函数直读 `cfg_*` / `dim_*` |
+
+规划须有 **对象 → Cube → 主 fact/dim** 对照表（见 §7）。
+
+### 5.5 本体函数 function_id（补充）
+
+对象 **`code` 无前缀**；函数仍用 **命名空间**（与 Palantir Function 类似）：
+
+```text
+{domain}.fn.{action_name}     # 如 sales.fn.get_summary, profit.fn.yoy_analysis
+{domain}.action.{code}        # Action 脚本注册
+```
+
+---
+
+## 6. 链接类型命名
+
+链接描述 **对象之间** 的有向业务关系；与物理表 `add_relationship` **分层**，但应 **可对照**。
+
+### 6.1 格式
+
+```text
+{from_role}_{verb}_{to_role}     # snake_case
+{verb}_{to_role}                 # 简式（from 在 define_link_type 参数中已体现）
+```
+
+| 规则 | 示例 |
+| ---- | ---- |
+| 业务动词/介词 | `order_contains_product`, `entry_posts_to_account` |
+| 基数在 API 参数中声明 | `define_link_type(..., cardinality=...)` |
+| 禁止 | `product_id_fk`, `rel_sales_product`（物理层命名） |
+
+### 6.2 与表间关系对照
+
+| 物理关系 | 本体链接（示例） |
+| -------- | ---------------- |
+| `fact_sales_order_line` → `dim_product` | `SalesOrder` —*contains*→ `Product` |
+| `fact_sales_order_line` → `dim_customer` | `SalesOrder` —*sold_to*→ `Customer` |
+| `fact_gl_journal_entry` → `dim_account` | `JournalEntry` —*posts_to*→ `Account` |
+
+---
+
+## 7. 三层对照与迁移示例（销售域）
+
+### 7.1 旧名 → 新名（物理表）
+
+| 现名（不规范） | 新名 | 类别 |
+| -------------- | ---- | ---- |
+| — | **`dim_date`** | 时间维（**新增**） |
+| `product_master` | `dim_product` | 维 |
+| `customer_dimension` | `dim_customer` | 维 |
+| `channel_dimension` | `dim_channel` | 维 |
+| `sales_order_fact` | `fact_sales_order_line` | 事实（订单行粒度） |
+
+**`fact_sales_order_line` 增补**：`date_key Int32` → `dim_date.date_key`
+
+### 7.2 Cube（建议）
+
+| 现 Cube | 类别 | 建议调整 |
+| ------- | ---- | -------- |
+| `SalesCube` | Process | 保留；事实源改为 `fact_sales_order_line`；时间维来自 **`dim_date`** |
+| `ProductSalesCube` | Subject | 保留 |
+| `CustomerSalesCube` | Subject | 保留 |
+| `ChannelSalesCube` | Subject | 保留 |
+| `TimeSalesCube` | — | **合并**进 `SalesCube`（`dim_date` 列），或标注 deprecated |
+
+### 7.3 本体对象（基本不变，补分类）
+
+| code | 分类 | bind_source | 主物理支撑 |
+| ---- | ---- | ----------- | ---------- |
+| `Product` | Master | `ProductSalesCube` | `dim_product` |
+| `Customer` | Master | `CustomerSalesCube` | `dim_customer` |
+| `Channel` | Reference | `ChannelSalesCube` | `dim_channel` |
+| `SalesOrder` | Transaction | `SalesCube` | `fact_sales_order_line` |
+| `SalesAnalysis` | Analytical | `SalesCube` | 同 fact |
+
+### 7.4 利润域（摘要）
+
+| 物理（新） | Cube（示例） | 对象（示例） |
+| ---------- | ------------ | ------------ |
+| `dim_date`, `dim_account`, `dim_cost_center` | `GlJournalCube`, `BudgetCube` | `Account`, `CostCenter` |
+| `fact_gl_journal_entry`, `fact_budget_entry` | `ActualCube`, `BudgetVsActualCube` | `JournalEntry`, `BudgetLine` |
+
+---
+
+## 8. 规划文档写法与自检清单
+
+### 8.1 物理层章节结构（建议）
+
+```markdown
+### 3.0 时间维（强制）
+### 3.1 事实表（fact_*）
+### 3.2 维度表（dim_*）
+### 3.3 桥表 / 映射 / 配置 / 汇总（按需）
+### 3.x 表间关系（含 fact → dim_date）
+```
+
+### 8.2 Cube 层章节结构（建议）
+
+```markdown
+## 四、Cube 层设计
+### 4.0 Cube 清单与类别
+| Cube | 类别 | 事实源 | 支撑对象 |
+### 4.1 SalesCube（Process）…
+```
+
+### 8.3 本体层章节结构（建议）
+
+```markdown
+## 五、本体层设计
+### 5.1 对象类型清单
+| code | 分类 | name | bind_source |
+### 5.2 对象属性 …
+### 5.3 链接类型 …
+### 5.4 三层对照总表
+| 对象 code | 分类 | Cube | 主 fact/dim |
+```
+
+### 8.4 自检清单（在 [本体规划指南](./本体规划指南.md) 原 10 项基础上扩展）
+
+| # | 检查项 | 通过标准 |
+| - | ------ | -------- |
+| 2a | **dim_date** | 含 `dim_date`，PK 为 **`date_key`** |
+| 2b | **fact 时间键** | 每张 `fact_*` 含 **`date_key`** 并关联 `dim_date` |
+| 2c | **表前缀** | 使用 `fact_`/`dim_`/…，无 `_master`、`_dimension` 混用 |
+| 4a | **Cube 类别** | 每个 Cube 标注 Process/Subject/Comparison/Snapshot |
+| 4b | **Cube 命名** | PascalCase + `Cube` 后缀；不与对象 code 同名 |
+| 5a | **对象分类** | 每个对象类型标注 Master/Transaction/Analytical/Reference/Configuration |
+| 5b | **对象 code** | PascalCase **无前缀**；与表名/Cube 名区分 |
+| 5c | **三层对照** | 附录含 对象↔Cube↔表 对照 |
+| 6a | **CATEGORY_REGISTRY** | 规划附录 B 与 init 顶部字典一致（见 [349](./本体分类规划与SDK扩展方案.md)） |
+| 6b | **表平台分类** | 每张表标注 347 标准中文名（时间维/维度表/事实表等） |
+| 6c | **Cube 平台分类** | 每个 Cube 标注 流程型/主体型/对比型/快照型 |
+| 6d | **对象/链接/关系分类** | 对象标 主数据/事务/分析/参考；链接与关系标扩展类别 |
+| 6e | **分类挂载** | init 含 `apply_registry` 或注册时 `category_347=`；侧栏与 347 一致 |
+
+---
+
+## 9. 相关文档索引
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体规划指南](./本体规划指南.md) | 规划章节、Cube 强制、自检 |
+| [规划示例：产品销售](./规划示例_产品销售本体规划方案.md) | 完整示例（待按本规范修订表名） |
+| [规划示例：利润分析](./规划示例_利润分析本体方案.md) | GL 域示例（待修订） |
+| [DaziScript SDK 参考](./dazi_script_sdk_reference.md) | `register_cube`、`define_object_type` API |
+| [本体脚本编写指南](./本体脚本编写指南.md) | init / seed / 表间关系实施 |
+| [349 · 本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md) | 平台分类与 CATEGORY_REGISTRY |
+
+---
+
+**变更记录**
+
+| 日期 | 说明 |
+| ---- | ---- |
+| 2026-06-05 | 首版：物理表 7 类 + dim_date；Cube 4+1 类；本体对象 Palantir 式 5 分类；三层对照与自检扩展 |

package/dist/docs/onto//346/234/254/344/275/223/350/204/232/346/234/254/347/274/226/345/206/231/346/214/207/345/215/227.md

@@ -6,6 +6,16 @@
 
 > 终端命令均在 **`dazi-work` 根目录**执行：`dazi ...`（见 [CLI 调用约定](../guides/cli-invocation.md)）。
 
+## 执行脚本前必读（强制）
+
+在终端执行 **`dazi onto script publish` / `script run` / `function run` / `save-test-arguments`** 之前，**必须**阅读：
+
+| 文档 | 说明 |
+| ---- | ---- |
+| **[脚本运行纠错（商务成本实录）](./脚本运行纠错_商务成本方案开发过程.md)** | setup API 误用、`query_one` 聚合陷阱、**函数禁止 `output.print_json()`**、CLI 参数（`function run` 不支持 JSON 文件、`save-test-arguments` 须 `ofn_xxx`） |
+
+`dazi docs show onto/script-run-troubleshooting` · 智能体另见提示词 **`onto/script-publish-run`**。
+
 ## 环境
 
 - 推荐 **Python 3.10+**
@@ -58,10 +68,11 @@
 | 步骤 | 内容 | API |
 | ---- | ---- | --- |
 | 1 | 建表 | `s.sql.execute(CREATE TABLE ...)` |
-| 2 | 注册表 | `s.tables.register` + `s.tables.sync_columns` |
+| 2 | 注册表 | `s.tables.register_with_meta`（含表/列 `display_name`、`description`） |
 | 3 | **注册表间关系** | `s.tables.add_relationship(...)` |
 | 4 | 注册 Cube / 派生度量 | `s.register_cube`、`s.upsert_derived_measures` |
 | 5 | 本体对象 / 属性 / 链接 | `s.onto.define_*`、`s.sync_metric_refs` |
+| 6 | **347 对齐分类** | `s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)` |
 
 ### 表间关系 `s.tables.add_relationship`
 
@@ -82,6 +93,50 @@ s.tables.add_relationship(
 
 > **勿与** `s.onto.define_link_type` 混淆：前者写数据空间元数据，后者写业务对象语义链接，**两者都需实施**。
 
+### 表注册 `TABLE_REGISTRY` + `register_with_meta`
+
+init 脚本顶部维护与规划文档对齐的 `TABLE_REGISTRY`（项目内 `plans/*.md` 或内置 [规划示例](./规划示例_产品销售本体规划方案.md)），步骤 2 统一调用：
+
+```python
+TABLE_REGISTRY = {
+    "fact_sales_order_line": {
+        "display_name": "销售订单行事实表",
+        "description": "订单行粒度销售流水",
+        "columns": [
+            {"name": "order_id", "display_name": "订单 ID"},
+            {"name": "date_key", "display_name": "日期键", "description": "关联 dim_date"},
+            # ...
+        ],
+    },
+}
+
+for tbl_name, meta in TABLE_REGISTRY.items():
+    s.tables.register_with_meta(
+        table_name=tbl_name,
+        display_name=meta["display_name"],
+        description=meta.get("description"),
+        columns=meta["columns"],
+        force_column_meta=True,  # 规划变更后重跑 init 时刷新列元数据
+    )
+```
+
+- **显示名** → 侧栏与表预览列标题（`display_name`）
+- **说明** → 业务口径、FK、冗余原因（`description`）；`sync_columns` **不会**自动写入
+- 参考：`资源/examples/onto/利润示例/setup/profit_ontology_init.py`、`销售示例/setup/sales_ontology_init.py`
+
+### 分类注册 `CATEGORY_REGISTRY` + `apply_registry`
+
+init 脚本顶部维护与规划附录 B 对齐的 `CATEGORY_REGISTRY`（分类名必须是 [347](./本体命名规范_物理表Cube与对象.md) 标准中文名），**所有资源注册完成后**调用：
+
+```python
+cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+- 6 类资源平级挂载：`table` / `cube` / `object` / `relation` / `link` / `function`
+- 函数类资源若 init 未 `register_function`，须 `skip_missing=True`
+- 可选：注册 API 传 `category_347="维度表"` 等即时挂载（与 `apply_registry` 幂等可并存）
+- 详见 [349 方案](./本体分类规划与SDK扩展方案.md)、[SDK 参考 §5.6](./dazi_script_sdk_reference.md)
+
 ## 脚本类型
 
 类型由 **发布命令参数** 区分；初始化与灌数放 `setup/`，本体函数与动作放 `functions/`：
@@ -108,6 +163,8 @@ dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/fun
 
 `functions/`（或规划中的本体函数 `.py`）**不能**只执行「普通 publish」：
 
+**新建函数**：复制 `资源/examples/onto/_templates/ontology_function_template.py`（`dazi examples show onto/template/ontology-function`），或参考 `销售示例/functions/sales_fn_get_summary.py`。`main()` **无参**，业务写在 `_ontology_fn_body(p)`，末尾 **`return _ontology_fn_body(p)`** — **禁止** `output.print_json()`（见 [脚本运行纠错 §3](./脚本运行纠错_商务成本方案开发过程.md#3-函数输出方式错误outputprint_json)）。
+
 | 仅 `script publish`（无 `--register-function-id`） | 带 `--register-function-id` 发布             |
 | -------------------------------------------------- | -------------------------------------------- |
 | 脚本代码进入 `ads_scripts`                         | 同上 **且** 写入 `ontology_function_defs`    |
@@ -152,6 +209,8 @@ dazi onto function run sales.fn.get_summary --space <space-id> --params '{}'
 
 仅 `publish` + `function run` **不会**自动写入测试参数；侧栏 **Onto → 运行函数** 依赖函数定义上的 **`test_arguments`** 预填表单。
 
+> **CLI 易错点**：`function run` **不支持** `--arguments-json-file`；`save-test-arguments` 须用 **`ofn_xxx` 内部 id** 而非 `function_id` 字符串。完整说明见 [脚本运行纠错](./脚本运行纠错_商务成本方案开发过程.md)。
+
 **本地约定（与规划文档 § 函数 / test_arguments 一致）**：
 
 1. 每个函数一份 JSON：`functions/test_arguments/<function_id>.json`
@@ -235,6 +294,7 @@ dazi onto script dedupe --space <space-id> --yes
 | ------ | ----------- |
 | 表已注册 | 侧栏 **数据资源** 或 `dazi onto space get` → `table_count` |
 | **表间关系已注册** | `relationship_count` > 0；侧栏 **表间关系** |
+| **347 分类已挂载** | 侧栏分类视图下表/Cube/对象等按标准中文名分组；init 摘要含 `category_mounts` |
 | 函数已注册 | `dazi onto function list --space <space-id>` |
 | **test_arguments 已保存** | `dazi onto function get <function_id>` → `test_arguments.arguments` |
 | 函数可运行 | `dazi onto function run <function_id> --space <space-id> --params '{}'` |
@@ -247,3 +307,5 @@ dazi onto script dedupe --space <space-id> --yes
 - [本体动作开发](./action-guide.md)
 - [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
 - [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [349 · 本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
+- [脚本运行纠错（商务成本方案实录）](./脚本运行纠错_商务成本方案开发过程.md)