@dazitech/cli 3.0.8 → 3.1.0

package/dist/docs/onto//346/234/254/344/275/223/350/247/204/345/210/222/346/214/207/345/215/227.md

@@ -1,173 +1,304 @@
-# 本体规划指南
-
-## 目标
-
-在 `plans/` 目录中完成本体实现单元的概念设计，包括：
-
-- 业务域与边界
-- 对象类型（Object Type）与关键属性
-- **物理表间关系**（事实表 → 维表的 JOIN / FK 语义）
-- 链接类型（Link Type）与基数（**业务对象层**，与表间关系分层写清）
-- 动作（Action）与规则（Rule）的初步清单
-- 本体函数清单及 **test_arguments**（默认测试入参）约定
-
-## 本体、Cube 与物理表：三者关系与「业务世界」方法
-
-规划时须分清三层，**自上而下**以业务语言为主，**自下而上**以存储与分析为落地；避免把「本体」写成「表的别名」或「Cube 的副本」。
-
-| 层级                          | 是什么                                                                   | 典型职责                                                                                                 | 规划文档里写什么                                                                                                                                                                                                                                                                                    |
-| ----------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **物理表（Table）**           | ClickHouse 等引擎中的事实/维表                                           | 存储、排序键、约束、ETL 落地；面向写入与物理优化                                                         | **首层物理模型宜为业务明细/维表/流水等**，分析向宽表、主题汇总表宜作为**派生层**；**避免**规划落地时默认「每个分析对象各建一张 `fact_*_analysis`」且仅此一层——否则与「每个 Cube 复制一个对象」仍是同一类一对一，只是顺序颠倒。表名、主键/关联列与源系统对齐；**不**把表名直接当作业务对象的唯一名字 |
-| **Cube**                      | 面向分析语义的数据集视图（维度、度量、聚合）                             | 报表、语义查询、指标白名单；`qualified_name` 多以前缀 `CubeName.member` 出现                             | 需要哪些 Cube、维/度量与业务度量的对应；Cube 名可用分析域习惯（如带 `Analytics` / `Cube` 后缀）                                                                                                                                                                                                     |
-| **本体（Ontology 对象类型）** | **业务世界**中的对象类型：身份、类型化**链接**、挂载函数/动作/规则的锚点 | 让业务与产品讨论「客户」「订单」「合同」而非「第几张表第几列」；链接表达有向业务关系，而非仅外键数值相等 | **对象类型 `code`** 用稳定**业务英文标识**（如 `Order`、`Customer`）；与 Cube 名、表名**刻意区分**；`bind_source` 声明「当前由哪个 Cube 支撑该对象的读模型」                                                                                                                                        |
-
-**「业务世界」方法（规划阶段强制自检）**：
-
-- 先列 **对象类型** 与 **链接**（谁与谁、业务动词/名词），再反推需要哪些表、是否已有 Cube、是否要新建表或宽表；**反推表时**区分「事件/明细/主数据」与「仅为报表服务的汇总表」，勿把**第一步物理落点**默认识别为「按分析主题各一张事实表」。
-- 接受 **多对一**：多表、多 Cube 可收敛为一种业务对象；一宽表也可拆成多种业务对象。
-- **链接**两端必须是对象类型 **`code`**，不是 Cube 名；表中仅有 `xxx_id` 时，规划文中仍应写清本体链接语义。
-
-### 物理表间关系 vs 本体链接（强制分层）
-
-| 维度 | **物理表间关系** | **本体链接（Link Type）** |
-| ---- | ---------------- | ------------------------- |
-| 所在层 | 数据空间 / ClickHouse | 本体 Ontology |
-| 规划章节 | 物理层设计 → **「表间关系」**（建议 §3.x） | 本体层设计 → **「链接类型」** |
-| 侧栏可见 | **数据资源 → 数据空间 → 表间关系** | **Onto 本体 → 链接** |
-| 实施 API | `s.tables.add_relationship(...)`（init 脚本，**表 register 之后**） | `s.onto.define_link_type(...)` |
-| 典型形态 | 事实表 `many_to_one` 维表（`product_id` → `product_master`） | `SalesOrder` → `Product`（订单包含产品） |
-
-**常见遗漏**：只写本体 `define_link_type`，init 脚本未调用 `add_relationship` → 空间 **`relationship_count` 为 0**，流程多表 JOIN、AI 读空间上下文时缺少关系元数据。
-
-**规划文档必含「表间关系」小节**，至少列清：
-
-| 列 | 说明 |
-| -- | ---- |
-| 从表 / 到表 | 物理表名，通常 **从事实表到维表** |
-| 关系类型 | 如 `many_to_one` |
-| join_keys | 如 `product_id → product_id` |
-| join_sql | 如 `sales_order_fact.product_id = product_master.product_id` |
-| 对应本体链接 | 可选对照表，便于评审 |
-
-**与业界对象中心实践的对照**：上述分层与「对象优先、数据为 backing」的思路，可与 **Palantir Foundry Ontology**（对象类型、链接、Action、Function 分层）等成熟产品对照阅读；落地脚本时以平台当前 API 与 **`dazi onto`** 能力为准，**不**假设已实现对方全部特性。
-
-## 必读文档
-
-1. **本体规划示例（推荐）**：[`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md) — 含表间关系、test_arguments 与完整脚本对照（`dazi docs sync` 后位于 `资源/docs/onto/`）
-2. **补充示例**：[`规划示例_利润分析本体方案.md`](./规划示例_利润分析本体方案.md) — 利润分析域参考
-3. **工作区与 CLI**：`guides/workspace-v3.md`、`guides/cli-reference.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）
-4. **可运行脚本示例**：`资源/examples/onto/销售示例/`（推荐）、`资源/examples/onto/利润示例/`（`dazi examples sync` 或侧栏 **帮助 → 示例**）
-
-## 产出约定
-
-- **本体方案（规划文档）**：新建/修改的 Markdown **必须**落在 **`项目/<业务名>/本体/ontos/<实现名>/plans/<规划主题>.md`**（这是规划阶段的真产出；**不是**改 `本体规划指南.md`）。
-- 进入脚本实现阶段：遵循 **`本体脚本编写指南.md`**（含发布）、**`function-guide.md`**。
-
-## 空间约束（强制）
-
-- 本体实现单元创建时已绑定 **数据空间**；`space_id` 以 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 为准。
-- 若 README 中无 `space_id`（非扩展「新建本体实现」创建），不得新建规划文件，须先让用户补全空间或重新创建实现单元。
-
-## LLM 执行指引（必须遵循）
-
-面向 **dazi-vscode v3**：终端用 **`dazi`**（本体/流程/数据/鉴权），DRAP 在 **`项目/app_<名称>/` 应用项目根** 用 **`pnpm run dazi-app --`**；**禁止**全局 `dazi-onto` / 已废弃的 `dazi-agent`。
-
-### 工作区与项目
-
-- **工作区根**：VS Code 已打开的文件夹；多根工作区时在设置 **`dazi.workspaceRoot`** 指定。
-- **平台与登录**：`dazi.serverUrl`；`dazi auth login` 或 `dazi auth set-token`（Token 存 `.dazi/auth.json`）。
-- **业务项目与本体实现单元**（扩展「新建本体实现」时已选定数据空间，**无需**再建 `onto/<space_id>/` 等平行目录）：
-
-```text
-<工作区根>/
-  项目/<业务名>/                    ← 业务项目根
-    本体/                           ← 本体根目录
-      ontos/<实现名>/               ← 本体实现单元（工作单元）
-        README.md                   ← 数据空间 ID、实现元信息（规划/实施均以此为准）
-        快速启动_<实现名>.md
-        plans/                      ← 规划阶段 Markdown 产出
-        setup/                      ← 初始化 / 灌数脚本
-        functions/                  ← 本体函数 / 动作脚本
-          test_arguments/           ← 各 function_id 的 test_arguments JSON（与 .py 内 TEST_ARGUMENTS 同步）
-  资源/docs/onto/                   ← 本体指南与规划示例（dazi docs sync）
-  资源/dataspaces/                  ← 侧栏下载的表结构 Markdown
-```
-
-### 规划开始前
-
-1. 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取 **数据空间 ID**（可与设置 `dazi.spaceId` 对照，以 README 为准）。
-2. 未绑定 `space_id` 时 **不得** 新建规划 Markdown，须先让用户通过扩展创建本体实现单元或明确空间。
-
-### 规划阶段最小流程
-
-在 **工作区根目录** 打开终端执行：
-
-```bash
-dazi doctor
-dazi auth whoami
-dazi docs sync    # 可选：同步帮助文档到 资源/docs/
-```
-
-**核对数据空间与现网资产**（`<space_id>` 取自当前实现单元的 `README.md`，勿另猜目录）：
-
-```bash
-dazi onto space list
-dazi onto space get <space_id>    # 可选：查看空间详情
-```
-
-**扩展侧栏（规划阶段主要入口）**：
-
-| 目的          | 操作                                                                                  |
-| ------------- | ------------------------------------------------------------------------------------- |
-| 确认绑定空间  | 打开 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 中的数据空间 ID               |
-| 查看表 / Cube | **数据资源** → 对应数据空间 → 展开表、Cube                                            |
-| 下载表结构    | 表节点右键「下载表信息」→ `资源/dataspaces/`                                          |
-| 同步帮助文档  | **帮助** → 下载文档（`dazi docs sync`）                                               |
-
-> 规划阶段**不**要求本地 `snapshot.json`、`editorial/` 或 `onto/<space_id>/` 目录；以侧栏 **数据资源** 与项目内文档为准即可。
-
-规划阶段 **只产出 Markdown**：写入 **`项目/<业务名>/本体/ontos/<实现名>/plans/<主题>.md`**，**首选参考** [`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md)。此阶段不发布脚本。
-
-### 进入脚本实施
-
-脚本写在 **`项目/<业务名>/本体/ontos/<实现名>/setup/`**（初始化、灌数）与 **`functions/`**（本体函数、动作；Python，见 `dazi.onto.defaultScriptLang`）。发布与运行见 **`本体脚本编写指南.md`**、**`function-guide.md`**：
-
-```bash
-dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space_id>
-dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
-  --space <space_id> \
-  --register-function-id <function_id>
-dazi onto function run <function_id> --space <space_id> --params '{}'
-# 函数测试通过后，保存 test_arguments（侧栏「运行函数」预填参数，见本体脚本编写指南）
-```
-
-亦可在侧栏 **Onto 本体** 使用「发布函数」「运行函数」等命令（与终端 CLI **同源** bundled；`--space` 与实现单元 README 中的 `space_id` 一致）。
-
-**实施顺序（强制）**：
-
-1. `setup/*_ontology_init.py`：建表 → `tables.register` → **`tables.add_relationship`** → Cube → 本体对象/链接  
-2. `setup/*_seed_data.py`：灌数（幂等）  
-3. `functions/*.py`：发布并 **`--register-function-id`**  
-4. 运行函数验证 → **`save-test-arguments`** 写入各函数定义的 `test_arguments`
-
-实施前可用 `dazi onto function list --space <space_id>` 核对平台已有函数定义；`dazi onto space get <space_id>` 核对 **`relationship_count`** 是否与规划一致。
-
-### 失败处理
-
-- 命令失败时输出 **完整错误** 与修复建议（登录、`dazi.serverUrl`、工作区路径、`space_id`），**不得** 静默跳过。
-- v2 → v3 命令对照见 `guides/troubleshooting.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）。
-
-## 自检
-
-- 是否写清对象类型、链接、函数/Action、规则（如适用）
-- **物理表间关系**：是否单独成章（从表/到表、join_keys、join_sql、关系类型）；是否与 init 脚本步骤对应
-- **`define_link_type` 与对象类型 code**：链接两端须为**已规划且将先创建**的对象类型 **`code`**（与 `define_object_type` 一致）；**勿**将 **Cube 名** 或表名当作对象类型 `code`。勿混用仅中文名而无稳定 `code`。
-- **函数 test_arguments**：每个 `function_id` 是否在规划中列出默认参数；是否与 `functions/test_arguments/<function_id>.json` 一致
-- 是否给出实施步骤、风险与验收（含 **relationship_count**、**test_arguments 非 null**）
-
-## 相关文档
-
-- [本体脚本编写指南](./本体脚本编写指南.md)
-- [本体规划指南](./本体规划指南.md)
-- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
-- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+# 本体规划指南
+
+## 目标
+
+在 `plans/` 目录中完成本体实现单元的概念设计，包括：
+
+> **智能体默认模式**：新建/评估类任务为 **独立规划**（见动态生成的 `快速启动_*.md` §0）。规划示例与 `资源/examples/` 仅供**只读对照**，不得整篇复制为 `plans/` 或整目录复制 `setup/`。
+
+## 任务模式与反模式
+
+| 模式 | 产出 | 禁止 |
+| ---- | ---- | ---- |
+| **独立规划**（默认） | `plans/<主题>.md` + 差异说明 + 自检 | 无 plans 写 init；复制其他 `ontos/` 或示例 init |
+| **对照实施** | 按 plans 写 `setup/`、`functions/` | 脚本与 plans 不一致 |
+| **快速演示** | 用户明确要求时复制示例改 `space_id` | 冒充完整规划评审 |
+
+**反模式（评审不合格）**：
+
+- 利润/科目/预算域却照搬销售订单表结构且无差异说明
+- 规划示例表名/Cube/对象 **逐字相同** 且无业务章节论证
+- 引用 `项目/<客户>/本体/ontos/` 历史项目作通用模板
+- 缺 Cube 独立章节即进入 `register_cube`
+
+提示词：**`onto/planning-design`**（规划）→ **`onto/script-publish-run`**（实施）。
+
+规划须包括：
+
+- 业务域与边界
+- **物理表**与 **表间关系**
+- **Cube 层**（分析语义：维度、度量、派生度量；`bind_source` 的数据来源）
+- 对象类型（Object Type）与关键属性
+- 链接类型（Link Type）与基数（**业务对象层**，与表间关系分层写清）
+- 动作（Action）与规则（Rule）的初步清单
+- 本体函数清单及 **test_arguments**（默认测试入参）约定
+
+## 本体、Cube 与物理表：三者关系与「业务世界」方法
+
+规划时须分清三层，**自上而下**以业务语言为主，**自下而上**以存储与分析为落地；避免把「本体」写成「表的别名」或「Cube 的副本」。
+
+| 层级                          | 是什么                                                                   | 典型职责                                                                                                 | 规划文档里写什么                                                                                                                                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **物理表（Table）**           | ClickHouse 等引擎中的事实/维表                                           | 存储、排序键、约束、ETL 落地；面向写入与物理优化                                                         | 表名使用 **`fact_` / `dim_` / `bridge_` 等前缀**（**强制 `dim_date` + `date_key`**）；详见 **[本体本体命名规范](./本体命名规范_物理表Cube与对象.md)** |
+| **Cube**                      | 面向分析语义的数据集视图（维度、度量、聚合）                             | 报表、语义查询、指标白名单；`qualified_name` 多以前缀 `CubeName.member` 出现                             | **PascalCase + `Cube` 后缀**；标注 Process/Subject/Comparison/Snapshot 类别；见 [命名规范 §4](./本体命名规范_物理表Cube与对象.md#4-cube类别与命名) |
+| **本体（Ontology 对象类型）** | **业务世界**中的对象类型：身份、类型化**链接**、挂载函数/动作/规则的锚点 | 让业务与产品讨论「客户」「订单」「合同」而非「第几张表第几列」；链接表达有向业务关系，而非仅外键数值相等 | **`code` 无前缀** PascalCase 业务名；标注 Master/Transaction/Analytical 等**分类**（非 code 前缀）；见 [命名规范 §5](./本体命名规范_物理表Cube与对象.md#5-本体对象palantir-思想与分类) |
+
+**「业务世界」方法（规划阶段强制自检）**：
+
+- 先列 **对象类型** 与 **链接**（谁与谁、业务动词/名词），再反推需要哪些表、是否已有 Cube、是否要新建表或宽表；**反推表时**区分「事件/明细/主数据」与「仅为报表服务的汇总表」，勿把**第一步物理落点**默认识别为「按分析主题各一张事实表」。
+- 接受 **多对一**：多表、多 Cube 可收敛为一种业务对象；一宽表也可拆成多种业务对象。
+- **链接**两端必须是对象类型 **`code`**，不是 Cube 名；表中仅有 `xxx_id` 时，规划文中仍应写清本体链接语义。
+
+### 物理表间关系 vs 本体链接（强制分层）
+
+| 维度 | **物理表间关系** | **本体链接（Link Type）** |
+| ---- | ---------------- | ------------------------- |
+| 所在层 | 数据空间 / ClickHouse | 本体 Ontology |
+| 规划章节 | 物理层设计 → **「表间关系」**（建议 §3.x） | 本体层设计 → **「链接类型」** |
+| 侧栏可见 | **数据资源 → 数据空间 → 表间关系** | **Onto 本体 → 链接** |
+| 实施 API | `s.tables.add_relationship(...)`（init 脚本，**表 register 之后**） | `s.onto.define_link_type(...)` |
+| 典型形态 | 事实表 `many_to_one` 维表（`product_id` → `product_master`） | `SalesOrder` → `Product`（订单包含产品） |
+
+**常见遗漏**：只写本体 `define_link_type`，init 脚本未调用 `add_relationship` → 空间 **`relationship_count` 为 0**，流程多表 JOIN、AI 读空间上下文时缺少关系元数据。
+
+**常见遗漏（TRAE / 智能体）**：规划只写**物理表 + 对象类型 + 函数**，**未写 Cube 层** → init 脚本无 `register_cube`、`bind_source` 无读模型、函数 SQL 与侧栏 **数据资源 → Cube** 无法对照验收。**Cube 层须独立成章，不可省略。**
+
+**规划文档必含「表间关系」小节**，至少列清：
+
+| 列 | 说明 |
+| -- | ---- |
+| 从表 / 到表 | 物理表名，通常 **从事实表到维表** |
+| 关系类型 | 如 `many_to_one` |
+| join_keys | 如 `product_id → product_id` |
+| join_sql | 如 `sales_order_fact.product_id = product_master.product_id` |
+| 对应本体链接 | 可选对照表，便于评审 |
+
+## 物理层元数据：显示名与说明（强制）
+
+规划文档中的物理表字段表，须区分 **显示名** 与 **说明**，以便 init 脚本映射到 `s.tables.register_with_meta`：
+
+| 规划列 | 平台字段 | 用途 | 示例 |
+| ------ | -------- | ---- | ---- |
+| **显示名** | `display_name` | 侧栏、表预览、AI 上下文的短标签 | `凭证 ID`、`借方` |
+| **说明** | `description` | 业务口径、FK 指向、冗余原因 | `关联 dim_date`、 `冗余` |
+
+**表清单**建议列：`表名 | 显示名 | 说明 | 角色`（「中文名」统一改称 **显示名**）。
+
+**字段表**建议列：`字段名 | 类型 | 显示名 | 说明`（原单列「说明」若混有 FK/PK 标记，拆到 **说明** 列；**显示名** 写面向用户的短标签）。
+
+init 脚本在 `setup/*_ontology_init.py` 顶部维护 `TABLE_REGISTRY`，与规划 **一一对应**。内置参考：`资源/examples/onto/利润示例`、`销售示例` 的 init 与 `资源/docs/onto/规划示例_*.md`；详见 [本体脚本编写指南 §表注册](./本体脚本编写指南.md#表注册-table_registry--register_with_meta)。
+
+## 平台分类（平台分类对齐 · 强制）
+
+规划阶段的 **规划语义分类**（表/Cube/对象/关系/链接/函数）须与平台 **`ads_categories`** 使用**同一套标准中文名**（见 [本体分类规划与SDK扩展方案](./本体分类规划与SDK扩展方案.md)、[命名规范 §3](./本体命名规范_物理表Cube与对象.md)）。
+
+| 规划要求 | 说明 |
+| -------- | ---- |
+| 各资源表增加 **平台分类** 列 | 物理表、Cube、对象、表间关系、链接、函数清单均须标注 |
+| 附录 B | `plans/<主题>.md` 末尾附 **CATEGORY_REGISTRY 对照表**，与 `setup/*_category_mount.py` 顶部字典逐行一致 |
+| 分类挂载 | **独立脚本** `*_category_mount.py`：init + seed + 全部函数 publish **之后** 执行 `apply_registry`（类灌数） |
+| 平级目录 | 6 类资源挂空间默认根下，**不**建多层分类树 |
+
+**英文分类 → 平台中文名**（摘录）：
+
+| 资源 | 英文（规划列） | 规划列 / 平台分类名 |
+| ---- | -------------- | ---------------- |
+| Cube | Process | 流程型 |
+| Cube | Subject | 主体型 |
+| Cube | Comparison | 对比型 |
+| 对象 | Master | 主数据 |
+| 对象 | Transaction | 事务 |
+| 对象 | Analytical | 分析 |
+| 对象 | Reference | 参考 |
+| 关系 | — | 时间关联 / 主数据关联 / 层级自关联 / 预实关联 / 桥接关联 |
+| 链接 | — | 归属关系 / 分析归因 / 层级关系 / 对比关系 |
+| 函数 | — | 总览分析 / 趋势分析 / 结构分析 / 预实分析 / 组织分析 |
+
+参考附录 B：[规划示例_产品销售](./规划示例_产品销售本体规划方案.md#附录-b平台-分类挂载对照表category_registry)、[规划示例_利润分析](./规划示例_利润分析本体方案.md#附录-b平台-分类挂载对照表category_registry)。
+
+## 规划文档标准结构（建议章节）
+
+新建 `plans/<主题>.md` 时，**至少**包含下列章节（顺序可微调，**不可缺项**）：
+
+| 章节 | 内容要点 |
+| ---- | -------- |
+| 一、业务场景与边界 | 域定义、分析目标、空间/数据源约束 |
+| 二、物理层设计 | 事实表/维表、字段、主键 |
+| 三、表间关系 | 见上文「表间关系」表格 |
+| **四、Cube 层设计** | **独立成章**；见下文 |
+| 五、本体层设计 | 对象类型、`bind_source`→Cube、属性、链接类型 |
+| 六、本体函数设计 | function_id、参数、返回值、**test_arguments** |
+| **与参照示例的差异说明** | 新建/评估时**必填**；说明业务域、表/Cube/对象与内置示例的不同 |
+| 七、实施计划 | 分阶段任务（含 Cube 注册步骤） |
+| 八、风险与验收 | 含 Cube 数量、派生度量、relationship_count |
+| **附录 B：平台分类挂载对照** | `CATEGORY_REGISTRY` 与 `*_category_mount.py` 一致 |
+| **附录：规划完整性自检清单** | 见本文 [§规划文档完整性自检清单](#规划文档完整性自检清单) |
+
+参考全文结构：[规划示例_产品销售本体规划方案.md](./规划示例_产品销售本体规划方案.md)、[规划示例_利润分析本体方案.md](./规划示例_利润分析本体方案.md)。
+
+## Cube 层设计（强制独立章节）
+
+Cube 是 **表 → 分析语义 → 本体读模型** 的中间层。规划阶段若跳过 Cube，实施阶段将无法完成 `s.register_cube`、`s.onto.bind_source(..., "dazi_cube", ...)` 及 `sync_metric_refs`。
+
+**每个 Cube 至少写清**：
+
+| 列 | 说明 |
+| -- | ---- |
+| Cube 名 | 如 `SalesCube`、`ActualCube`；与对象类型 `code`、表名**区分** |
+| 事实源表 | 主事实表（可多 Cube 共享同一事实表、不同维度切片） |
+| 维度 | 参与 GROUP BY / 筛选的字段列表 |
+| 度量 | 列名、聚合（sum/uniq/count 等）、业务含义 |
+| 派生度量 | 表达式（如 avg = amount/qty）、说明 |
+| 支撑的对象类型 | 哪些 `define_object_type` 通过 `bind_source` 绑定本 Cube |
+
+**自检**：每个需对外分析的对象类型，是否在 Cube 层有**明确**读模型（或文档说明为何共用某 Cube）；init 脚本步骤中是否有 **「注册 N 个 Cube」** 与规划 **N 一致**。
+
+**与业界对象中心实践的对照**：上述分层与「对象优先、数据为 backing」的思路，可与 **Palantir Foundry Ontology**（对象类型、链接、Action、Function 分层）等成熟产品对照阅读；落地脚本时以平台当前 API 与 **`dazi onto`** 能力为准，**不**假设已实现对方全部特性。
+
+## 必读文档
+
+1. **本体规划示例（推荐）**：[`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md) — 含表间关系、test_arguments 与完整脚本对照（`dazi docs sync` 后位于 `资源/docs/onto/`）
+2. **本体命名规范**：[`本体命名规范_物理表Cube与对象.md`](./本体命名规范_物理表Cube与对象.md)（`onto/naming-conventions`）— 物理表前缀、`dim_date`、Cube 类别、对象 Palantir 式分类
+3. **补充示例**：[`规划示例_利润分析本体方案.md`](./规划示例_利润分析本体方案.md) — 利润分析域参考
+4. **工作区与 CLI**：`guides/workspace-v3.md`、`guides/cli-reference.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）
+5. **可运行脚本示例**：`资源/examples/onto/销售示例/`（推荐）、`资源/examples/onto/利润示例/`（`dazi examples sync` 或侧栏 **帮助 → 示例**）
+
+## 产出约定
+
+- **本体方案（规划文档）**：新建/修改的 Markdown **必须**落在 **`项目/<业务名>/本体/ontos/<实现名>/plans/<规划主题>.md`**（这是规划阶段的真产出；**不是**改 `本体规划指南.md`）。
+- 进入脚本实现阶段：遵循 **`本体脚本编写指南.md`**（含发布）、**`function-guide.md`**。
+- **执行脚本前必读（强制）**：[`脚本运行常见错误处理.md`](./脚本运行常见错误处理.md)（`onto/script-run-troubleshooting`）。
+
+## 空间约束（强制）
+
+- 本体实现单元创建时已绑定 **数据空间**；`space_id` 以 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 为准。
+- 若 README 中无 `space_id`（非扩展「新建本体实现」创建），不得新建规划文件，须先让用户补全空间或重新创建实现单元。
+
+## LLM 执行指引（必须遵循）
+
+面向 **dazi-vscode v3**：终端用 **`dazi`**（本体/流程/数据/鉴权），DRAP 在 **`项目/app_<名称>/` 应用项目根** 用 **`pnpm run dazi-app --`**；**禁止**全局 `dazi-onto` / 已废弃的 `dazi-agent`。
+
+### 工作区与项目
+
+- **工作区根**：VS Code 已打开的文件夹；多根工作区时在设置 **`dazi.workspaceRoot`** 指定。
+- **平台与登录**：`dazi.serverUrl`；`dazi auth login` 或 `dazi auth set-token`（Token 存 `.dazi/auth.json`）。
+- **业务项目与本体实现单元**（扩展「新建本体实现」时已选定数据空间，**无需**再建 `onto/<space_id>/` 等平行目录）：
+
+```text
+<工作区根>/
+  项目/<业务名>/                    ← 业务项目根
+    本体/                           ← 本体根目录
+      ontos/<实现名>/               ← 本体实现单元（工作单元）
+        README.md                   ← 数据空间 ID、实现元信息（规划/实施均以此为准）
+        快速启动_<实现名>.md
+        plans/                      ← 规划阶段 Markdown 产出
+        setup/                      ← 初始化 / 灌数脚本
+        functions/                  ← 本体函数 / 动作脚本
+          test_arguments/           ← 各 function_id 的 test_arguments JSON（与 .py 内 TEST_ARGUMENTS 同步）
+  资源/docs/onto/                   ← 本体指南与规划示例（dazi docs sync）
+  资源/dataspaces/                  ← 侧栏下载的表结构 Markdown
+```
+
+### 规划开始前
+
+1. 从 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 读取 **数据空间 ID**（可与设置 `dazi.spaceId` 对照，以 README 为准）。
+2. 未绑定 `space_id` 时 **不得** 新建规划 Markdown，须先让用户通过扩展创建本体实现单元或明确空间。
+
+### 规划阶段最小流程
+
+在 **工作区根目录** 打开终端执行：
+
+```bash
+dazi doctor
+dazi auth whoami
+dazi docs sync    # 可选：同步帮助文档到 资源/docs/
+```
+
+**核对数据空间与现网资产**（`<space_id>` 取自当前实现单元的 `README.md`，勿另猜目录）：
+
+```bash
+dazi onto space list
+dazi onto space get <space_id>    # 可选：查看空间详情
+```
+
+**扩展侧栏（规划阶段主要入口）**：
+
+| 目的          | 操作                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------- |
+| 确认绑定空间  | 打开 **`项目/<业务名>/本体/ontos/<实现名>/README.md`** 中的数据空间 ID               |
+| 查看表 / Cube | **数据资源** → 对应数据空间 → 展开表、Cube                                            |
+| 下载表结构    | 表节点右键「下载表信息」→ `资源/dataspaces/`                                          |
+| 同步帮助文档  | **帮助** → 下载文档（`dazi docs sync`）                                               |
+
+> 规划阶段**不**要求本地 `snapshot.json`、`editorial/` 或 `onto/<space_id>/` 目录；以侧栏 **数据资源** 与项目内文档为准即可。
+
+规划阶段 **只产出 Markdown**：写入 **`项目/<业务名>/本体/ontos/<实现名>/plans/<主题>.md`**，**首选参考** [`规划示例_产品销售本体规划方案.md`](./规划示例_产品销售本体规划方案.md)。此阶段不发布脚本。
+
+**定稿门槛**：对照 [§规划文档完整性自检清单](#规划文档完整性自检清单)，**尤其第 4 项 Cube 层**；未通过不得进入脚本实施。
+
+### 进入脚本实施
+
+脚本写在 **`项目/<业务名>/本体/ontos/<实现名>/setup/`**（初始化、灌数）与 **`functions/`**（本体函数、动作；Python，见 `dazi.onto.defaultScriptLang`）。发布与运行见 **`本体脚本编写指南.md`**、**`function-guide.md`**：
+
+```bash
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py --space <space_id>
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
+  --space <space_id> \
+  --register-function-id <function_id>
+dazi onto function run <function_id> --space <space_id> --params '{}'
+# 函数测试通过后，保存 test_arguments（侧栏「运行函数」预填参数，见本体脚本编写指南）
+```
+
+亦可在侧栏 **Onto 本体** 使用「发布函数」「运行函数」等命令（与终端 CLI **同源** bundled；`--space` 与实现单元 README 中的 `space_id` 一致）。
+
+**实施顺序（强制）**：
+
+1. `setup/*_ontology_init.py`：建表 → `tables.register_with_meta` → **`tables.add_relationship`** → Cube → 本体对象/链接（**不含**分类挂载）  
+2. `setup/*_seed_data.py`：灌数（幂等）  
+3. `functions/*.py`：发布并 **`--register-function-id`**（可选 `--register-platform-category`）  
+4. 运行函数验证 → **`save-test-arguments`** 写入各函数定义的 `test_arguments`  
+5. `setup/*_category_mount.py`：**最后**执行全量 `CATEGORY_REGISTRY` + `apply_registry`（含 function 段）
+
+实施前可用 `dazi onto function list --space <space_id>` 核对平台已有函数定义；`dazi onto space get <space_id>` 核对 **`relationship_count`** 是否与规划一致。
+
+### 失败处理
+
+- 命令失败时输出 **完整错误** 与修复建议（登录、`dazi.serverUrl`、工作区路径、`space_id`），**不得** 静默跳过。
+- init / 函数发布与 CLI 参数常见误用见 **[脚本运行常见错误处理](./脚本运行常见错误处理.md)**（`dazi docs show onto/script-run-troubleshooting`）。
+- v2 → v3 命令对照见 `guides/troubleshooting.md`（`dazi docs sync` 后位于 `资源/docs/guides/`）。
+
+## 规划文档完整性自检清单
+
+规划 Markdown **定稿前**（进入 `setup/` 脚本编写前），逐项勾选。**任一项未满足则不得开始 init 脚本**（智能体 / TRAE 须先补全规划）。
+
+| # | 检查项 | 通过标准 |
+| - | ------ | -------- |
+| 1 | **业务场景** | 已写清域边界、分析目标、适用空间 |
+| 2 | **物理表** | 每张表有用途、主键/关键字段；事实表与维表角色明确；字段表含 **显示名** 与 **说明** 列 |
+| 2a | **表元数据注册** | `setup/*_init.py` 含 `TABLE_REGISTRY`，表/列 `display_name`、`description` 与规划一致，经 `register_with_meta` 注册 |
+| 3 | **表间关系** | 独立小节；每条含从表/到表、类型、join_keys、join_sql；条数与 init 中 `add_relationship` 一致 |
+| 4 | **Cube 层** | **独立成章**；每个 Cube 含事实源、维度、度量、派生度量；数量与 init 中 `register_cube` 一致 |
+| 5 | **对象类型** | 每个 `code` 稳定英文标识；**非**表名/Cube 名 |
+| 6 | **bind_source** | 每个分析对象已声明绑定哪个 Cube（对照表或属性映射表） |
+| 7 | **链接类型** | 两端为对象类型 `code`；与表间关系分层写清 |
+| 8 | **函数清单** | 每个 `function_id`、参数、返回值；无遗漏核心分析能力 |
+| 9 | **test_arguments** | 每个函数默认入参已列出（或注明无参） |
+| 10 | **实施与验收** | 分阶段计划含 Cube 步骤；验收含 Cube 注册、relationship_count、函数可运行 |
+| 6a | **CATEGORY_REGISTRY** | 规划附录 B 与 `*_category_mount.py` 顶部字典一致；6 类资源齐全 |
+| 6b | **表 平台分类** | 每张表标注时间维/维度表/事实表等标准名 |
+| 6c | **Cube 平台分类** | 每个 Cube 标注流程型/主体型/对比型/快照型 |
+| 6d | **对象/链接/关系 平台分类** | 对象标主数据/事务/分析/参考；链接与关系标扩展类别 |
+| 6e | **分类挂载验收** | 已 run `*_category_mount.py`；侧栏分类名与平台标准分类一致；重跑幂等 |
+
+**命名规范扩展项**（详见 [本体命名规范 §8.4](./本体命名规范_物理表Cube与对象.md#84-自检清单在-本体规划指南-原-10-项基础上扩展)）：`dim_date` / `date_key`、表前缀、Cube 类别、对象分类、三层对照表、**平台分类 6a–6e**。
+
+可将上表复制到 `plans/<主题>.md` 末尾作为 **附录**，评审时逐项打勾。
+
+## 相关文档
+
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体规划指南](./本体规划指南.md)
+- [规划示例：产品销售本体（推荐）](./规划示例_产品销售本体规划方案.md)
+- [规划示例：利润分析本体（补充）](./规划示例_利润分析本体方案.md)
+- [本体分类规划与 SDK 扩展方案](./本体分类规划与SDK扩展方案.md)
+- [脚本运行常见错误处理](./脚本运行常见错误处理.md)