@dazitech/cli 3.0.8 → 3.1.0

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 与 `*_category_mount.py` 顶部字典一致（见 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)） |
+| 6b | **表平台分类** | 每张表标注 平台标准分类中文名（时间维/维度表/事实表等） |
+| 6c | **Cube 平台分类** | 每个 Cube 标注 流程型/主体型/对比型/快照型 |
+| 6d | **对象/链接/关系分类** | 对象标 主数据/事务/分析/参考；链接与关系标扩展类别 |
+| 6e | **分类挂载** | 已 run `*_category_mount.py` 或注册时 `category_347=`；侧栏与平台标准分类一致 |
+
+---
+
+## 9. 相关文档索引
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体规划指南](./本体规划指南.md) | 规划章节、Cube 强制、自检 |
+| [规划示例：产品销售](./规划示例_产品销售本体规划方案.md) | 完整示例（待按本规范修订表名） |
+| [规划示例：利润分析](./规划示例_利润分析本体方案.md) | GL 域示例（待修订） |
+| [DaziScript SDK 参考](./dazi_script_sdk_reference.md) | `register_cube`、`define_object_type` API |
+| [本体脚本编写指南](./本体脚本编写指南.md) | init / seed / 表间关系实施 |
+| [本体分类规划与 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/345/274/200/345/217/221/344/274/230/345/214/226/346/200/273/347/273/223.md

@@ -0,0 +1,242 @@
+# 本体开发优化总结
+
+**文档 ID**：`onto/dev-optimization-summary`
+
+> **类型**：开发总结（本轮本体 SDK、init 脚本、规划与 TRAE 引导优化）  
+> **同步路径**：`dazi docs sync` → `资源/docs/onto/本体开发优化总结.md`  
+> **前置依据**：[本体命名规范](./本体命名规范_物理表Cube与对象.md)、[本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)
+
+---
+
+## 1. 本轮目标
+
+在 本体命名规范基础上，打通 **规划文档 → init 脚本 → 平台侧栏** 三条链路，解决两类长期缺口：
+
+1. **表/列显示名与业务说明**：侧栏、表预览不再只显示物理字段名。
+2. **平台分类与平台分类**：规划中的「类别/分类」列能幂等挂载到 `ads_categories`，侧栏分组与规划一致。
+
+---
+
+## 2. 表显示名与列显示名
+
+### 2.1 问题背景
+
+此前 init 脚本普遍使用 `s.tables.register` + `s.tables.sync_columns`：
+
+- `sync_columns` 仅从物理库同步结构；
+- 对未显式传入的列，最多**推断** `display_name`（token 词典），**不会**写入业务 `description`；
+- 规划文档 §3.x 中的「显示名」「说明」列无法落到平台。
+
+### 2.2 解决方案：`TABLE_REGISTRY` + `register_with_meta`
+
+**脚本约定**：init 顶部维护 `TABLE_REGISTRY`，与规划文档 §2.3 表清单、§3.x 字段表 **逐行对齐**。
+
+```python
+TABLE_REGISTRY = {
+    "dim_account": {
+        "display_name": "科目维表",
+        "description": "会计科目主数据",
+        "columns": [
+            {"name": "account_id", "display_name": "科目 ID", "description": "主键"},
+            {"name": "account_code", "display_name": "科目编码"},
+            # ...
+        ],
+    },
+}
+
+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 时刷新列元数据
+    )
+```
+
+**SDK API**：
+
+| API | 作用 |
+|-----|------|
+| `s.tables.register_with_meta(...)` | `register` → `sync_columns` → `set_column_meta` 三步合一（**推荐**） |
+| `s.tables.set_column_meta(table, columns, force=False)` | 单独批量写列 `display_name` / `description` / `business_role` |
+
+**幂等规则**：
+
+- `force_column_meta=False`（默认）：仅补空显示名或与字段名相同的显示名、空 `description`；
+- `force_column_meta=True`：按入参强制刷新（规划修订后重跑 init）。
+
+### 2.3 平台效果
+
+| 元数据字段 | 用户可见处 |
+|-----------|-----------|
+| 表 `display_name` | 侧栏表名、表列表 |
+| 表 `description` | 表详情/预览说明 |
+| 列 `display_name` | 表预览列标题 |
+| 列 `description` | 列说明、规划口径 |
+
+### 2.4 与 `sync_columns` 的分工
+
+| 操作 | 结构同步 | 表显示名 | 列显示名 | 列说明 |
+|------|---------|---------|---------|--------|
+| `sync_columns` | ✅ | 推断（有限） | 推断（有限） | ❌ |
+| `register_with_meta` + `columns` | ✅ | ✅ | ✅ | ✅ |
+
+智能体生成 init 时须使用 `register_with_meta`，勿仅用 `sync_columns` 代替业务元数据。
+
+### 2.5 示例
+
+| 用途 | 路径 |
+|------|------|
+| 利润 init | `资源/examples/onto/利润示例/setup/profit_ontology_init.py` |
+| 利润分类 | `.../setup/profit_category_mount.py` |
+| 销售 init | `资源/examples/onto/销售示例/setup/sales_ontology_init.py` |
+| 销售分类 | `.../setup/sales_category_mount.py` |
+| 规划 | `规划示例_利润分析本体方案.md`、`规划示例_产品销售本体规划方案.md` |
+
+---
+
+## 3. 本体分类功能（重点）
+
+> 详细方案见 [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)。
+
+### 3.1 两类分类，一套语言
+
+| 维度 | 规划语义分类 | ads_categories 平台分类 |
+|------|-------------|------------------------|
+| 作用 | 规划自检、命名约束 | 侧栏展示、资源分组 |
+| 对齐 | 平台 `category_name` **=** 平台标准分类中文名 | 禁止自定义别名 |
+| 树结构 | — | 全部 **平级** 挂空间默认根下 |
+
+### 3.2 SDK 入口
+
+```python
+s.categories.ensure_347(kind="table", category="维度表")
+s.categories.assign_table("维度表", "dim_account")
+s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+实现：`sdk_category_taxonomy.py`（字典）、`sdk_category.py`（`CategoryManager`）、`s.categories` 挂载于 `SpaceHandle`。
+
+### 3.3 六类资源
+
+| kind | 示例标准名 |
+|------|-----------|
+| `table` | 时间维、维度表、事实表、桥表、映射表、配置表、汇总表、临时表 |
+| `cube` | 流程型、主体型、对比型、快照型 |
+| `object` | 主数据、事务、分析、参考、配置 |
+| `relation` | 时间关联、主数据关联、层级自关联、预实关联、桥接关联 |
+| `link` | 归属关系、分析归因、层级关系、对比关系 |
+| `function` | 总览分析、趋势分析、结构分析、预实分析、组织分析 |
+
+### 3.4 `CATEGORY_REGISTRY` + `apply_registry`
+
+独立 `setup/*_category_mount.py` 顶部字典，与规划 **附录 B** 逐行一致；在 **init + seed + 全部函数 publish 之后** 调用：
+
+```python
+CATEGORY_REGISTRY = {
+    "table": {"维度表": ["dim_account"], "事实表": ["fact_gl_journal_entry"]},
+    "cube": {"流程型": ["ActualCube"]},
+    "object": {"主数据": ["Account"], "事务": ["JournalEntry"]},
+    "relation": {"时间关联": [("fact_gl_journal_entry", "dim_date")]},
+    "link": {"归属关系": ["entry_belongs_account"]},
+    "function": {"总览分析": ["profit.fn.get_summary"]},
+}
+
+cat_counts = s.categories.apply_registry(CATEGORY_REGISTRY, skip_missing=True)
+```
+
+`skip_missing=True` 仅跳过**成员不存在**的挂载；`ensure_347` 使用的分类名必须在 平台分类字典中存在。
+
+### 3.5 内联挂载平台分类（SDK 参数 `category_347=`）
+
+```python
+s.tables.register_with_meta("dim_account", display_name="科目维表", category_347="维度表", ...)
+s.register_cube("ActualCube", ..., category_347="流程型")
+s.onto.define_object_type("Account", name="科目", category_347="主数据")
+```
+
+与 `apply_registry` 幂等可并存。详见 [SDK 参考 §5.6](./dazi_script_sdk_reference.md)。
+
+### 3.6 实施四阶段（init → seed → 函数 → category_mount）
+
+| 阶段 | 内容 |
+|------|------|
+| B init | 建表、元数据、关系、Cube、本体对象/链接（**不含**分类挂载） |
+| C seed | `*_seed_data.py` 灌数 |
+| D 函数 | `publish --register-function-id`（每个 `functions/*.py`） |
+| E 分类 | `*_category_mount.py` 全量 `apply_registry`（**最后**，类灌数）；或 `--register-platform-category` |
+
+**TRAE 常见问题**：规划列了 function_id 但文件未齐 / 未 publish → `function list` 看不到；补发函数后**只重跑 category_mount**，**勿**为重挂分类重跑完整 init。
+
+**推荐命令序列**：见 [脚本运行常见错误处理](./脚本运行常见错误处理.md) §6、§8。
+
+### 3.7 规划自检（命名规范 §8.4 扩展 6a–6e 平台分类）
+
+| # | 检查项 |
+|---|--------|
+| 6a | 附录 B 与 `*_category_mount.py` `CATEGORY_REGISTRY` 一致 |
+| 6b | 每张表标注 平台标准分类中文名 |
+| 6c | 每个 Cube 标注流程型/主体型/对比型/快照型 |
+| 6d | 对象/链接/关系扩展类别与字典一致 |
+| 6e | 已 run `*_category_mount.py`；侧栏与平台标准分类一致 |
+
+### 3.8 缺陷修复：表类中文名索引
+
+`apply_registry` 报 `平台分类字典中不存在分类: kind='table', category='维度表'` 时，根因是 `TABLE_CATEGORIES` 曾缺中文 key（非脚本 UTF-8 编码问题）。已补充中文名索引与 `resolve_category_meta` 反查兜底；须部署新版 backend。
+
+---
+
+## 4. TRAE / 智能体引导
+
+| 改动 | 说明 |
+|------|------|
+| 快速启动 §0 任务模式 | 规划 vs 实现；实施顺序含 `category_mount` |
+| `onto/planning-design` 提示词 | 阶段门禁、附录 B、category_mount 放最后 |
+| `onto/script-publish-run` 提示词 | §4.5 平台分类挂载 |
+| 本体规划指南 | 五阶段实施顺序、平台分类列 |
+| 脚本运行常见错误处理 | TRAE 踩坑与推荐命令 |
+| SDK 参考 §5.6 | `categories` 与 `category_347` |
+
+---
+
+## 5. 部署与验收
+
+**测试/生产 backend 须包含**（版本低于下列能力时，init 或 category_mount 会报错）：
+
+| 能力 | 说明 |
+|------|------|
+| 表元数据注册 | `s.tables.register_with_meta` |
+| 平台分类挂载 | `s.categories`、`apply_registry` |
+| 按资源类挂载 | `apply_registry(..., kinds=[...])` |
+| 发布时挂函数分类 | API `register_platform_category` / CLI `--register-platform-category` |
+| 表类中文名索引 | 平台分类字典支持「维度表」「事实表」等标准名 |
+
+**验收**：
+
+1. 侧栏表名、列标题与规划显示名一致。
+2. 侧栏分类名为平台标准分类中文名（含 function 段）。
+3. init / seed 重跑幂等；`category_mount` 重跑幂等。
+4. `CATEGORY_REGISTRY` 与附录 B 一致；`function list` 条数与规划一致。
+
+---
+
+## 6. 相关文档
+
+| 文档 | 说明 |
+| ---- | ---- |
+| [本体本体命名规范](./本体命名规范_物理表Cube与对象.md) | 命名与分类真理源 |
+| [本体本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md) | 分类 SDK 设计 |
+| [本体脚本编写指南](./本体脚本编写指南.md) | init / seed / category_mount |
+| [脚本运行常见错误处理](./脚本运行常见错误处理.md) | TRAE 踩坑 |
+| [dazi_script_sdk_reference](./dazi_script_sdk_reference.md) | API 参考 |
+
+---
+
+**变更记录**
+
+| 日期 | 说明 |
+| ---- | ---- |
+| 2026-06-06 | 首版 |
+| 2026-06-06 | 增补函数注册门禁与 TRAE 处理说明 |
+| 2026-06-06 | 分类挂载迁至 `*_category_mount.py`；init 不含 apply_registry |