@dazitech/cli 3.0.7 → 3.0.8

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

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

package/dist/docs/guides/quickstart.md

@@ -17,8 +17,11 @@ code --install-extension dazi-vscode-3.x.x.vsix
 
 ### 2. 打开工作区
 
-将 **`dazi-work`** 文件夹作为 VS Code 工作区根目录打开（含 `项目/`、`资源/`、`scripts/`）。  
-DRAP 应用项目位于 **`项目/app_<名称>/`**（完整 monorepo，见 [§331](../../docs/331-应用项目多项目与组件重构.md)）；不再要求根目录必须有 `runtime-apps/`。
+将 **`dazi-work`** 文件夹作为 VS Code 工作区根目录打开（含 `项目/`、`资源/`、`scripts/`）。
+
+业务项目位于 **`项目/<业务名>/`**，内含固定子目录 `本体/`、`流程/`、`应用/`。  
+本体开发入口为 **`项目/<业务名>/本体/ontos/<实现名>/`**（含 `plans/`、`setup/`、`functions/`；`space_id` 写在 `README.md`）。  
+应用组件位于 **`项目/<业务名>/应用/apps/<app_id>/`**（见 [§331](../../docs/331-应用项目多项目与组件重构.md)）。
 
 ### 3. 自检 CLI
 
@@ -49,11 +52,21 @@ dazi auth set-token --token "your-jwt-token"
 
 ### 6. 初始化工作区
 
+**推荐（v3 业务项目 + per-item 本体）**：
+
+1. 命令面板执行 **搭子: 新建业务项目**，创建 `项目/<业务名>/`
+2. 命令面板执行 **搭子: 新建本体实现**，在 `本体/ontos/<实现名>/` 下生成 `plans/`、`setup/`、`functions/` 及 `快速启动_<实现名>.md`
+3. 在 `ontos/<实现名>/README.md` 中确认或填写数据空间 ID
+
+**兼容（历史 CLI 布局，非日常开发入口）**：
+
 ```powershell
-# 新项目（本体空间）
 dazi onto space init --space-id <your-space-id>
+```
+
+已有 v2 项目迁移：
 
-# 已有 v2 项目迁移
+```powershell
 dazi migrate workspace
 ```
 
@@ -72,6 +85,7 @@ dazi auth whoami
 - [CLI 调用约定](./cli-invocation.md)
 - [认证管理](../auth/auth-login.md)
 - [本体开发入门](../onto/space-management.md)
+- [工作区 v3 规范](./workspace-v3.md) — 业务项目目录树与 per-item 本体结构
 - [数据流程项目开发](../flow/flow-project-guide.md) — **推荐**：`项目/<业务名>/流程/flows/`、菜单、pull/push
 - [节点代码编写](../flow/node-code-guide.md) — python-script、sql-query 等
 - [流程开发索引](../flow/flows-guide.md) — Flow 文档入口

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.5\bundled\clis"
+$env:DAZI_BUNDLED_DIR = "$env:USERPROFILE\.cursor\extensions\dazitech.dazi-vscode-3.0.7\bundled\clis"
 node "$env:DAZI_BUNDLED_DIR\dazi.js" mcp stdio
 ```
 

package/dist/docs/guides/workspace-v3.md

@@ -2,52 +2,72 @@
 
 **文档 ID**: `guides/workspace-v3`  
 **适用版本**: dazi-vscode v3.0+  
-**最后更新**: 2026-05-28（应用项目 `项目/app_*`）
+**最后更新**: 2026-06-05（业务项目 + per-item 本体结构）
 
 ## 目录结构（搭子工作区，如 dazi-work）
 
 ```text
 <workspace>/
 ├── 项目/
-│   ├── onto_<名称>/          ← 本体项目（规划、脚本、快速启动）
-│   └── app_<名称>/           ← ★ 应用项目 = DRAP monorepo（sdk、templates、apps）
-├── 资源/                     ← 帮助文档、提示词等（dazi docs sync）
-├── scripts/                  ← dazi.ps1、doctor-cli（终端 CLI 包装）
-├── tools/dazi-clis/          ← 可选：离线 bundled CLI 副本
-└── （可选）runtime-apps/     ← 兼容旧布局；可与 项目/app_* 并存
+│   └── <业务名>/                 ← 业务项目（固定子目录：本体、流程、应用）
+│       ├── README.md
+│       ├── 本体/
+│       │   ├── README.md
+│       │   ├── onto-assets/      ← 平台元数据缓存（侧栏懒拉取）
+│       │   └── ontos/
+│       │       └── <实现名>/     ← ★ 本体实现工作单元
+│       │           ├── README.md              ← space_id（权威）
+│       │           ├── 快速启动_<实现名>.md
+│       │           ├── plans/                 ← 本实现规划
+│       │           ├── setup/                 ← init / seed 脚本
+│       │           └── functions/             ← 本体函数
+│       ├── 流程/
+│       │   ├── plans/
+│       │   └── flows/<流程名>/...
+│       └── 应用/
+│           ├── plans/
+│           └── apps/<组件名>/...
+├── 资源/                         ← 帮助文档、提示词等（dazi docs sync）
+├── scripts/                      ← dazi.ps1、doctor-cli（终端 CLI 包装）
+├── tools/dazi-clis/              ← 可选：离线 bundled CLI 副本
+└── （可选）runtime-apps/         ← 兼容旧布局
 ```
 
-> v3.1+ **推荐**在 `项目/app_<名称>/` 下维护 DRAP，由扩展「新建应用项目」生成。详见 [§331](../../docs/331-应用项目多项目与组件重构.md)。
+> v3.1+ 应用项目位于 `项目/<业务名>/应用/apps/<组件名>/`。详见 [§331](../../docs/331-应用项目多项目与组件重构.md)。
 
 ## 目录说明
 
-| 路径                             | 对应 CLI                                   | 用途                                   |
-| -------------------------------- | ------------------------------------------ | -------------------------------------- |
-| `项目/onto_<名称>/`              | `dazi onto ...`                            | 本体规划、脚本、发布                   |
-| `项目/app_<名称>/`               | `pnpm run dazi-app -- ...`（在应用项目根） | DRAP monorepo；组件在 `apps/<app_id>/` |
-| `项目/app_<名称>/apps/<app_id>/` | 同上 + `--cwd apps/<app_id>`               | 单个应用组件源码                       |
-| `资源/docs/`                     | `dazi docs ...`                            | 同步后的内置文档                       |
-| `scripts/`                       | `dazi ...`                                 | 本体/流程/鉴权/数据（非 DRAP）         |
-| `~/.dazi/auth.json`              | 共享                                       | 登录凭据（扩展与 CLI 共用）            |
+| 路径                                                       | 对应 CLI                                   | 用途                                   |
+| ---------------------------------------------------------- | ------------------------------------------ | -------------------------------------- |
+| `项目/<业务名>/本体/ontos/<实现名>/`                       | `dazi onto ...`                            | 本体规划、脚本、发布（per-item spaceId） |
+| `项目/<业务名>/本体/onto-assets/`                          | `dazi onto ...`                            | 平台对象/函数/动作/规则缓存            |
+| `项目/<业务名>/流程/flows/<流程名>/`                       | `dazi flow ...`                            | 数据流程定义与节点代码                 |
+| `项目/<业务名>/应用/apps/<app_id>/`                        | `pnpm run dazi-app -- ...`（在应用项目根） | DRAP 应用组件源码                      |
+| `资源/docs/`                                               | `dazi docs ...`                            | 同步后的内置文档                       |
+| `scripts/`                                                 | `dazi ...`                                 | 本体/流程/鉴权/数据（非 DRAP）         |
+| `~/.dazi/auth.json`                                        | 共享                                       | 登录凭据（扩展与 CLI 共用）            |
 
 ## 扩展侧栏对应
 
-| 侧栏     | 工作区路径                                |
-| -------- | ----------------------------------------- |
-| 本体     | `项目/onto_*`                             |
-| App 应用 | `项目/app_*`（monorepo）→ `apps/<app_id>` |
-| 数据资源 | 平台数据空间（非目录）                    |
+| 侧栏     | 工作区路径                                              |
+| -------- | ------------------------------------------------------- |
+| 本体     | `项目/<业务名>/本体/ontos/<实现名>/` → plans/setup/functions |
+| 流程     | `项目/<业务名>/流程/flows/<流程名>/`                      |
+| App 应用 | `项目/<业务名>/应用/apps/<app_id>/`                       |
+| 数据资源 | 平台数据空间（非目录）                                  |
 
 ## v2 → v3 目录映射
 
 | v2                      | v3（搭子工作区）                                                 |
 | ----------------------- | ---------------------------------------------------------------- |
-| `ontology/`             | `项目/onto_*`                                                    |
-| `runtime-apps/apps/*`   | `项目/app_*/apps/*`（推荐）或 `<ws>/runtime-apps/apps/*`（兼容） |
+| `ontology/`             | `项目/<业务名>/本体/ontos/<实现名>/`                             |
+| `项目/onto_<名称>/`     | `项目/<业务名>/本体/ontos/<实现名>/`（并入业务项目）             |
+| `runtime-apps/apps/*`   | `项目/<业务名>/应用/apps/*`（推荐）或 `<ws>/runtime-apps/apps/*`（兼容） |
 | `.dazi-agent/auth.json` | `~/.dazi/auth.json`                                              |
 
 ## 相关文档
 
 - [§331 应用项目多项目与组件重构](../../docs/331-应用项目多项目与组件重构.md)
 - [§333 本轮扩展总结](../../docs/333-dazi-vscode应用项目多项目与本轮优化总结.md)
+- [§346 本体结构对齐开发方案](../../docs/346-dazi-vscode本体结构对齐开发方案.md)
 - [CLI 调用约定](./cli-invocation.md)

package/dist/docs/index.json

@@ -1,6 +1,6 @@
 {
-  "version": "3.0.5",
-  "updatedAt": "2026-05-29T00:00:00.000Z",
+  "version": "3.0.9",
+  "updatedAt": "2026-06-05T12:00:00.000Z",
   "docs": [
     {
       "id": "guides/quickstart",
@@ -88,10 +88,16 @@
     },
     {
       "id": "onto/planning-example-profit",
-      "title": "规划示例：利润分析本体",
+      "title": "规划示例：利润分析本体（GL 域）",
       "category": "onto",
       "file": "onto/规划示例_利润分析本体方案.md"
     },
+    {
+      "id": "onto/planning-example-sales",
+      "title": "规划示例：产品销售本体",
+      "category": "onto",
+      "file": "onto/规划示例_产品销售本体规划方案.md"
+    },
     {
       "id": "onto/script-authoring",
       "title": "本体脚本编写指南（含发布）",

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

@@ -18,16 +18,16 @@ dazi onto action list --space <space-id>
 
 ## 发布 Action
 
-脚本放在 **`项目/onto_<项目名>/脚本/`**（可与函数脚本同目录，用文件名区分）：
+脚本放在 **`项目/<业务名>/本体/ontos/<实现名>/functions/`**（可与函数脚本同目录，用文件名区分）：
 
 ```bash
-dazi onto script publish 项目/onto_<项目名>/脚本/my_action.py \
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_action.py \
   --space <space-id> \
   --register-action-id my_action_code \
   --register-action-permission-tag "finance.write"
 ```
 
-`<space-id>` 取自项目 **`README.md`**。
+`<space-id>` 取自实现单元 **`README.md`**（`项目/<业务名>/本体/ontos/<实现名>/README.md`）。
 
 ## 更新 Action 代码
 

package/dist/docs/onto/dazi_script_sdk_reference.md

@@ -1,174 +1,178 @@
-# DaziScript SDK 参考
-
-**文档 ID**: `onto/dazi-script-sdk-reference`  
-**适用**: dazi-vscode v3 + 搭子平台 DaziScript（ClickHouse 数据空间）
-
-> 给 LLM 与开发者提供精简、可执行的 SDK 规范。脚本目录、类型与 **`dazi onto script publish`** 等见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
-
-## 1. 工作区与脚本放置（dazi-vscode）
-
-| 用途                 | 路径                                                                                                        |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **日常开发**（推荐） | `<工作区根>/项目/onto_<项目名>/脚本/*.py`                                                                   |
-| **空间 ID**          | `项目/onto_<项目名>/README.md` 中的数据空间 ID                                                              |
-| **参考示例**         | `资源/examples/onto/setup/`、`资源/examples/onto/function/`（侧栏 **帮助 → 示例** 或 `dazi examples sync`） |
-| **本文档**           | `资源/docs/onto/dazi_script_sdk_reference.md`（`dazi docs sync` 后）                                        |
-
-- **禁止**将 `onto/<space_id>/editorial/` 作为 v3 本地开发约定（历史路径，仅 CLI `script sync` 可能拉回平台副本）。
-- 脚本入口仅需定义 **`main()`**；平台执行时自动调用，**不要**写 `if __name__ == "__main__":`。
-
-## 2. 基本约束
-
-- 数据引擎：**ClickHouse**
-- 新建空间须显式指定（若脚本内创建空间）：
-  - `storage_engine="clickhouse"`
-  - `connection_config={"database": "<db_name>"}`
-- 执行前确认已登录（`dazi auth whoami`）且 `dazi.serverUrl` 正确。
-
-## 3. 顶层对象与推荐调用
-
-常用对象：
-
-- `space`：空间管理与切换
-- `s.sql`：原始 SQL
-- `s.tables`：表注册与列同步
-- `s.register_cube(...)`：Cube 注册
-- `s.onto`：本体定义（对象、属性、链接、函数、活动）
-- `s.ontology`：对象中心能力（objects/features）
-- `s.ontology_rules`：规则集与规则
-- `s.scripts`：脚本记录管理
-- `output`：打印与成功提示（`output.print` / `output.success`）
-
-命名规范（便于 LLM 推断）：
-
-- 读操作：`exists_*`、`get_*`、`require_*`、`list_*`
-- 写操作：`create_*`、`ensure_*`、`update_*`、`delete_*`
-- 派生/同步：`create_from_*`、`sync_*`
-
-推荐本体落库路径（与 **[本体规划指南](./本体规划指南.md)** 一致）：
-
-1. `s.onto.define_object_type` → `s.onto.bind_source(..., "dazi_cube", config={"cube": ...})`
-2. `s.onto.define_property`（`dimension` / `measure` 须带与 Cube 成员一致的 `qualified_name`）
-3. `s.onto.define_link_type`（两端为对象类型 **`code`**，非 Cube 名）
-4. `s.onto.register_function` / `s.onto.define_action`
-5. `s.ontology.features.attach(object_code, feature_type, feature_id)`（`feature_type`: `function | action | rule`）
-
-**关于 `s.ontology.objects.create_from_cubes`**：SDK 仍提供，**易与业务语义脱节**；规划文档、示例包与交付脚本**不应依赖**。仅隔离烟测按需使用。
-
-## 4. 返回结构规范
-
-### 4.1 批量派生返回（ResultBatch）
-
-```json
-{
-  "ok": true,
-  "created": [],
-  "updated": [],
-  "skipped": [],
-  "errors": [],
-  "summary": {
-    "requested": 0,
-    "created": 0,
-    "updated": 0,
-    "skipped": 0,
-    "errors": 0
-  }
-}
-```
-
-### 4.2 特征绑定返回（示例）
-
-```json
-{
-  "ok": true,
-  "id": "xxx",
-  "created": true,
-  "updated": false,
-  "message": ""
-}
-```
-
-## 5. 模块速查
-
-### 5.1 `space`
-
-- `s = space.create(name, space_id=None, storage_engine="clickhouse", connection_config={"database": ...}, ...)`
-- `s = space.get(name_or_id)`
-- `space.use(handle_or_name)`
-
-### 5.2 `s.sql`
-
-- `s.sql.query(sql)` / `s.sql.query_one(sql)` / `s.sql.execute(sql)`
-- `s.sql.insert_rows(table, rows)`（`rows` 为 `list[dict]`）
-
-**ClickHouse：`INSERT ... VALUES` 与注释**
-
-- **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**，否则易出现 `Code: 27` 等解析错误。
-- **推荐**：大批量灌数用 **`s.sql.insert_rows`**；详见 **[dazi_script_seed_data_guide](./dazi_script_seed_data_guide.md)**。
-
-### 5.3 `s.tables`
-
-- `s.tables.register(table_name, label=...)`
-- `s.tables.sync_columns(table_name)`
-- `s.tables.list()` / `s.tables.discover()`
-- `s.tables.add_relationship(...)`
-
-### 5.4 Cube
-
-- `s.register_cube(name, table, title, measures, dimensions)`
-
-### 5.5 `s.onto`
-
-- `s.onto.define_object_type(code, name, ...)`
-- `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_action(action_code, ...)`
-
-### 5.6 `s.ontology` / `s.ontology_rules` / `s.scripts`
-
-见上文；规则：`ensure_rule_set` + `upsert_rule`；脚本记录：`create` / `ensure` / `list` 等。
-
-## 6. 标准初始化流程（建议）
-
-1. 确认 `space_id`（项目 README）
-2. 建表与灌数（`s.sql`；灌数规范见 seed 指南）
-3. `s.tables.register` + `sync_columns`
-4. `s.register_cube`
-5. `s.onto` 定义对象、属性、链接
-6. 注册函数/动作并 `features.attach`
-7. 配置规则（如需要）
-
-## 7. 在 dazi-vscode 中发布与运行
-
-开发完成后，在工作区根目录：
-
-```bash
-# 预检
-dazi onto script publish-preview 项目/onto_<项目名>/脚本/my_setup.py --space <space-id>
-
-# 发布（初始化/灌数类脚本）
-dazi onto script publish 项目/onto_<项目名>/脚本/my_setup.py --space <space-id>
-
-# 发布并注册为本体函数
-dazi onto script publish 项目/onto_<项目名>/脚本/my_func.py \
-  --space <space-id> \
-  --register-function-id my_func
-
-# 运行已入库函数
-dazi onto function run my_func --space <space-id> --params '{}'
-```
-
-亦可用侧栏 **Onto 本体** → 发布函数 / 运行函数。
-
-## 8. 回归与 JSON 摘要
-
-- 支持 `--json` 时，输出前缀统一：`__JSON_SUMMARY__`
-- 非 0 退出码即失败
-- 会改写数据的步骤须提供跳过/禁用开关
-
-**内置参考示例**（在用户工作区：**侧栏 帮助 → 示例 → 下载所有示例**，或执行 `dazi examples sync`，得到 **`资源/examples/`**；可复制到 **`项目/<onto_项目名>/脚本/`** 再改，勿直接改写同步下来的只读备份）：
-
-- 初始化：**`<工作区根>/资源/examples/onto/setup/profit_ontology_init.py`**
-- 函数样例：**`<工作区根>/资源/examples/onto/function/profit_fn_*.py`**
+# DaziScript SDK 参考
+
+**文档 ID**: `onto/dazi-script-sdk-reference`  
+**适用**: dazi-vscode v3 + 搭子平台 DaziScript（ClickHouse 数据空间）
+
+> 给 LLM 与开发者提供精简、可执行的 SDK 规范。脚本目录、类型与 **`dazi onto script publish`** 等见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
+
+## 1. 工作区与脚本放置（dazi-vscode）
+
+| 用途                 | 路径                                                                                                        |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **日常开发**（推荐） | `<工作区根>/项目/<业务名>/本体/ontos/<实现名>/setup/*.py`（初始化、灌数）                                   |
+|                      | `<工作区根>/项目/<业务名>/本体/ontos/<实现名>/functions/*.py`（本体函数、动作）                           |
+| **空间 ID**          | `项目/<业务名>/本体/ontos/<实现名>/README.md` 中的数据空间 ID                                              |
+| **参考示例**         | **`资源/examples/onto/利润示例/`**、**`资源/examples/onto/销售示例/`**（侧栏 **帮助 → 示例** 或 `dazi examples sync`；总览 `onto/README.md`） |
+| **本文档**           | `资源/docs/onto/dazi_script_sdk_reference.md`（`dazi docs sync` 后）                                        |
+
+- **禁止**将 `onto/<space_id>/editorial/` 作为 v3 本地开发约定（历史路径，仅 CLI `script sync` 可能拉回平台副本）。
+- 脚本入口仅需定义 **`main()`**；平台执行时自动调用，**不要**写 `if __name__ == "__main__":`。
+
+## 2. 基本约束
+
+- 数据引擎：**ClickHouse**
+- 新建空间须显式指定（若脚本内创建空间）：
+  - `storage_engine="clickhouse"`
+  - `connection_config={"database": "<db_name>"}`
+- 执行前确认已登录（`dazi auth whoami`）且 `dazi.serverUrl` 正确。
+
+## 3. 顶层对象与推荐调用
+
+常用对象：
+
+- `space`：空间管理与切换
+- `s.sql`：原始 SQL
+- `s.tables`：表注册与列同步
+- `s.register_cube(...)`：Cube 注册
+- `s.onto`：本体定义（对象、属性、链接、函数、活动）
+- `s.ontology`：对象中心能力（objects/features）
+- `s.ontology_rules`：规则集与规则
+- `s.scripts`：脚本记录管理
+- `output`：打印与成功提示（`output.print` / `output.success`）
+
+命名规范（便于 LLM 推断）：
+
+- 读操作：`exists_*`、`get_*`、`require_*`、`list_*`
+- 写操作：`create_*`、`ensure_*`、`update_*`、`delete_*`
+- 派生/同步：`create_from_*`、`sync_*`
+
+推荐本体落库路径（与 **[本体规划指南](./本体规划指南.md)** 一致）：
+
+1. `s.onto.define_object_type` → `s.onto.bind_source(..., "dazi_cube", config={"cube": ...})`
+2. `s.onto.define_property`（`dimension` / `measure` 须带与 Cube 成员一致的 `qualified_name`）
+3. `s.onto.define_link_type`（两端为对象类型 **`code`**，非 Cube 名）
+4. `s.onto.register_function` / `s.onto.define_action`
+5. `s.ontology.features.attach(object_code, feature_type, feature_id)`（`feature_type`: `function | action | rule`）
+
+**关于 `s.ontology.objects.create_from_cubes`**：SDK 仍提供，**易与业务语义脱节**；规划文档、示例包与交付脚本**不应依赖**。仅隔离烟测按需使用。
+
+## 4. 返回结构规范
+
+### 4.1 批量派生返回（ResultBatch）
+
+```json
+{
+  "ok": true,
+  "created": [],
+  "updated": [],
+  "skipped": [],
+  "errors": [],
+  "summary": {
+    "requested": 0,
+    "created": 0,
+    "updated": 0,
+    "skipped": 0,
+    "errors": 0
+  }
+}
+```
+
+### 4.2 特征绑定返回（示例）
+
+```json
+{
+  "ok": true,
+  "id": "xxx",
+  "created": true,
+  "updated": false,
+  "message": ""
+}
+```
+
+## 5. 模块速查
+
+### 5.1 `space`
+
+- `s = space.create(name, space_id=None, storage_engine="clickhouse", connection_config={"database": ...}, ...)`
+- `s = space.get(name_or_id)`
+- `space.use(handle_or_name)`
+
+### 5.2 `s.sql`
+
+- `s.sql.query(sql)` / `s.sql.query_one(sql)` / `s.sql.execute(sql)`
+- `s.sql.insert_rows(table, rows)`（`rows` 为 `list[dict]`）
+
+**ClickHouse：`INSERT ... VALUES` 与注释**
+
+- **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**，否则易出现 `Code: 27` 等解析错误。
+- **推荐**：大批量灌数用 **`s.sql.insert_rows`**；详见 **[dazi_script_seed_data_guide](./dazi_script_seed_data_guide.md)**。
+
+### 5.3 `s.tables`
+
+- `s.tables.register(table_name, label=...)`
+- `s.tables.sync_columns(table_name)`
+- `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"}]`
+
+### 5.4 Cube
+
+- `s.register_cube(name, table, title, measures, dimensions)`
+
+### 5.5 `s.onto`
+
+- `s.onto.define_object_type(code, name, ...)`
+- `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_action(action_code, ...)`
+
+### 5.6 `s.ontology` / `s.ontology_rules` / `s.scripts`
+
+见上文；规则：`ensure_rule_set` + `upsert_rule`；脚本记录：`create` / `ensure` / `list` 等。
+
+## 6. 标准初始化流程（建议）
+
+1. 确认 `space_id`（实现单元 README）
+2. 建表与灌数（`s.sql`；灌数规范见 seed 指南）
+3. `s.tables.register` + `sync_columns`
+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. 配置规则（如需要）
+
+## 7. 在 dazi-vscode 中发布与运行
+
+开发完成后，在工作区根目录：
+
+```bash
+# 预检
+dazi onto script publish-preview 项目/<业务名>/本体/ontos/<实现名>/setup/my_setup.py --space <space-id>
+
+# 发布（初始化/灌数类脚本）
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/setup/my_setup.py --space <space-id>
+
+# 发布并注册为本体函数
+dazi onto script publish 项目/<业务名>/本体/ontos/<实现名>/functions/my_func.py \
+  --space <space-id> \
+  --register-function-id my_func
+
+# 运行已入库函数
+dazi onto function run my_func --space <space-id> --params '{}'
+```
+
+亦可用侧栏 **Onto 本体** → 发布函数 / 运行函数。
+
+## 8. 回归与 JSON 摘要
+
+- 支持 `--json` 时，输出前缀统一：`__JSON_SUMMARY__`
+- 非 0 退出码即失败
+- 会改写数据的步骤须提供跳过/禁用开关
+
+**内置参考示例**（在用户工作区：**侧栏 帮助 → 示例 → 下载所有示例**，或执行 `dazi examples sync`，得到 **`资源/examples/`**；可复制到 **`项目/<业务名>/本体/ontos/<实现名>/setup/`** 或 **`functions/`** 再改，勿直接改写同步下来的只读备份）：
+
+- **规划全文（推荐）**：**`资源/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/`
+- **销售示例（推荐，含表间关系 + test_arguments）**：`资源/examples/onto/销售示例/setup/sales_ontology_init.py`、`sales_seed_data.py`、`functions/sales_fn_*.py`