@dazitech/cli 3.0.0

package/dist/docs/onto/dazi_script_seed_data_guide.md

@@ -0,0 +1,155 @@
+# DaziScript 灌数脚本编写指南
+
+**文档 ID**: `onto/dazi-script-seed-data-guide`  
+**适用**: dazi-vscode v3 + ClickHouse 数据空间
+
+> **用途**：约定工作区内「一次性 / 可重复执行」的造数、补数、历史回填脚本的写法，供人与 LLM 统一遵循。  
+> SDK API 见 **[dazi_script_sdk_reference](./dazi_script_sdk_reference.md)**；目录与发布见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
+
+---
+
+## 1. 什么是灌数脚本
+
+**灌数脚本**指在**已存在表结构**（或同脚本内先 DDL）的前提下，向当前空间写入**演示数据、回归数据、历史样本**的 DaziScript。
+
+### 1.1 放置位置（v3）
+
+| 类型 | 推荐路径 |
+|------|----------|
+| **项目内开发** | `<工作区根>/项目/onto_<项目名>/脚本/<名称>.py` |
+| **参考示例** | `资源/examples/onto/setup/`（初始化+灌数一体）、`资源/examples/onto/function/`（分析函数，非灌数专篇） |
+
+- `space_id` 以 **`项目/onto_<项目名>/README.md`** 为准（扩展「新建项目」时已绑定）。
+- 侧栏 **帮助 → 📎 示例 → 下载所有示例**，或：`.\scripts\dazi.ps1 examples sync` → `资源/examples/`。
+- 须定义 **`main()`**，**不要**写 `if __name__ == "__main__":`。
+
+> 不再使用 `spaces/<space_id>/editorial/scripts/setup/` 作为 v3 本地约定路径。
+
+---
+
+## 2. 硬约束（违反易导致联调失败）
+
+### 2.1 ClickHouse：`INSERT ... VALUES` 与注释
+
+- **`VALUES` 与各元组之间禁止 SQL 行注释 `--`**。常见报错：`CANNOT_PARSE_INPUT_ASSERTION_FAILED`、`Code: 27`。
+- **允许**：在**整条** `INSERT` **之前**写注释；或拆成多条 `INSERT`。
+- **推荐**：大批量灌数用 **`s.sql.insert_rows(table, rows)`**（`rows` 为 `list[dict]`）。
+
+### 2.2 幂等与可重复执行
+
+- 先 `query_one` / `count()` 判断已有数据，满足阈值则**跳过**或**仅补差额**。
+- 「清空再灌」须**显式开关**（如 `--force`），**默认**不破坏已有数据。
+
+### 2.3 数据质量
+
+- 枚举字段勿含多余空格；`Date` / `DateTime` 与表定义、SDK 规整规则一致。
+
+### 2.4 输出与验收
+
+- 关键步骤 `output.print`；结束可用 `output.success(...)`。
+- 机器解析约定：`__JSON_SUMMARY__` + JSON（与回归脚本一致）。
+
+---
+
+## 3. 推荐模式对照
+
+| 场景 | 推荐做法 |
+|------|----------|
+| 少量固定行 | 单条 `INSERT ... VALUES`，元组间**无**行间 `--`；或拆多条 `INSERT` |
+| 多批次、多行 | **`s.sql.insert_rows`** + Python 生成 `list[dict]` |
+| 需读 SQL 文件 | 注释写在 **INSERT 块上方**（Python 侧），不要塞进 `VALUES` 中间 |
+
+---
+
+## 4. 示例：`insert_rows`（推荐）
+
+将 `space_id`、表名、列名替换为项目 README 与规划文档中的真实值。表须已存在（或在本脚本前文 DDL 创建）。
+
+```python
+"""示例：按空间灌入演示数据（幂等 + insert_rows）
+
+放置：项目/onto_<项目名>/脚本/demo_seed.py
+space_id：见项目 README.md
+"""
+
+import json
+
+
+def main():
+    space_id = "space__your_id_here"  # 与 README 一致
+    table = "your_fact_table"
+    s = space.get(space_id)
+
+    try:
+        n = int(s.sql.query_one(f"SELECT count() FROM {table}") or 0)
+    except Exception:
+        n = 0
+    if n > 0:
+        output.print(f"{table} 已有 {n} 行，跳过灌数")
+        return
+
+    rows = [
+        {"id": "row_001", "name": "样例A", "metric_value": 100.5, "biz_date": "2025-01-10"},
+        {"id": "row_002", "name": "样例B", "metric_value": 200.0, "biz_date": "2025-01-11"},
+    ]
+
+    inserted = s.sql.insert_rows(table, rows)
+    output.print(f"已插入 {inserted} 行")
+    output.success("灌数完成")
+    output.print("__JSON_SUMMARY__" + json.dumps(
+        {"ok": True, "table": table, "inserted": inserted},
+        ensure_ascii=True,
+        default=str,
+    ))
+```
+
+---
+
+## 5. 示例：单条 `execute` + `VALUES`
+
+```python
+def main():
+    s = space.get("space__your_id_here")
+    if int(s.sql.query_one("SELECT count() FROM your_fact_table WHERE id = 'row_001'") or 0) > 0:
+        output.print("已存在，跳过")
+        return
+
+    s.sql.execute(
+        """
+        INSERT INTO your_fact_table VALUES
+        ('row_001', '样例A', 100.5, toDate('2025-01-10')),
+        ('row_002', '样例B', 200.0, toDate('2025-01-11'))
+        """
+    )
+    output.success("灌数完成")
+```
+
+---
+
+## 6. 发布与执行（dazi-vscode）
+
+在工作区根目录（`--space` 与项目 README 一致）：
+
+```bash
+# 预检
+.\scripts\dazi.ps1 onto script publish-preview 项目/onto_<项目名>/脚本/demo_seed.py --space <space-id>
+
+# 发布到平台（data_script / 初始化脚本）
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/demo_seed.py --space <space-id>
+
+# 若已入库且已知 script-id，可在平台侧执行；或通过 Onto 侧栏运行
+.\scripts\dazi.ps1 onto script run --script-id <script-id> --space <space-id> --params '{}'
+```
+
+**参考完整初始化+灌数**：复制 `资源/examples/onto/setup/profit_ontology_init.py` 到 `项目/.../脚本/` 后按空间改 `space_id` 与表名，再发布执行。
+
+> **已废弃**：`dazi-agent run --file "spaces/.../editorial/..."` — 请改用上表 `.\scripts\dazi.ps1 onto script publish` / `function run`。
+
+---
+
+## 7. 相关文档
+
+- [DaziScript SDK 参考](./dazi_script_sdk_reference.md)
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体规划指南](./本体规划指南.md)

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

@@ -0,0 +1,68 @@
+# 本体函数开发指南
+
+**文档 ID**: `onto/function-guide`
+
+## 函数生命周期
+
+```
+在 项目/onto_<项目名>/脚本/ 编写 .py → publish-preview（预检）→ publish（入库）→ update-code（更新）
+```
+
+## 新建函数
+
+```bash
+# 发布新函数（路径指向本体项目 脚本/ 目录）
+.\scripts\dazi.ps1 onto function publish 项目/onto_<项目名>/脚本/my_func.py \
+  --space <space-id> \
+  --function-id my_function \
+  --display-name "我的函数" \
+  --entry main
+```
+
+或使用 `script publish`（等价，见 [本体脚本编写指南](./本体脚本编写指南.md)）：
+
+```bash
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/my_func.py \
+  --space <space-id> \
+  --register-function-id my_function
+```
+
+`<space-id>` 取自 **`项目/onto_<项目名>/README.md`**。
+
+## 更新已有函数代码
+
+```bash
+# 用工作副本快速更新（不做完整 publish 流程）
+.\scripts\dazi.ps1 onto function update-code <function-id> \
+  --space <space-id> \
+  --stem my_func
+```
+
+`--stem` 为脚本文件名（不含扩展名），须与 `脚本/` 下文件一致。
+
+## 运行函数
+
+```bash
+.\scripts\dazi.ps1 onto function run <function-id> \
+  --space <space-id> \
+  --params '{"key": "value"}'
+```
+
+## 保存测试参数
+
+```bash
+.\scripts\dazi.ps1 onto function save-test-arguments <function-id> \
+  --space <space-id> \
+  --params '{"test_param": 42}'
+```
+
+## 函数脚本结构
+
+```python
+def main(params: dict) -> dict:
+    """
+    函数入口，params 由平台传入。
+    返回值会作为函数输出。
+    """
+    return {"result": params.get("value", 0) * 2}
+```

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

@@ -0,0 +1,52 @@
+# 本体规则（Rule）管理
+
+**文档 ID**: `onto/rule-guide`
+
+## 规则概念
+
+规则（Rule）存储在 `ads_ontology_rules` 表，通过种子脚本写入，通常用于：
+- 数据校验规则
+- 业务约束条件
+- 权限规则集
+
+## 列出规则
+
+```bash
+.\scripts\dazi.ps1 onto rule list --space <space-id>
+
+# 按规则集过滤
+.\scripts\dazi.ps1 onto rule list --space <space-id> --rule-set finance_rules
+```
+
+## 执行规则种子
+
+```bash
+.\scripts\dazi.ps1 onto rule run-seed --space <space-id> --stem cw_001_rules_seed
+```
+
+## 种子脚本示例
+
+```python
+def main(params: dict, s) -> dict:
+    rules = [
+        {
+            "code": "fin_001",
+            "name": "余额不能为负",
+            "rule_set": "finance_rules",
+            "expression": "balance >= 0",
+        }
+    ]
+    s.ontology_rules.upsert(rules)
+    return {"count": len(rules)}
+```
+
+## 删除规则
+
+```bash
+# 删除单条
+.\scripts\dazi.ps1 onto rule delete fin_001 --space <space-id>
+
+# 按规则集批量删除（先 dry-run）
+.\scripts\dazi.ps1 onto rule delete-all --space <space-id> --rule-set old_rules --dry-run
+.\scripts\dazi.ps1 onto rule delete-all --space <space-id> --rule-set old_rules --yes
+```

package/dist/docs/onto/space-management.md

@@ -0,0 +1,46 @@
+# 本体空间管理
+
+**文档 ID**: `onto/space-management`
+
+## 空间概念
+
+本体空间（Space）是搭子平台的基础组织单位，每个空间包含：
+- 函数定义（FunctionDef）
+- 动作定义（ActionDef）
+- 规则（Rule）
+- 脚本（Script）
+
+## 列出空间
+
+```bash
+.\scripts\dazi.ps1 onto space list
+```
+
+## 初始化本地工作区
+
+```bash
+.\scripts\dazi.ps1 onto space init --space-id <space-id>
+```
+
+本地目录结构：
+```
+onto/<space-id>/
+  editorial/
+    functions/    ← 函数工作副本
+    actions/      ← 动作工作副本
+  functions/      ← 函数定义元数据
+  actions/        ← 动作定义元数据
+  rules/          ← 规则元数据
+  scripts/        ← 脚本文件
+  .dazi-space.json
+```
+
+## 拉取快照
+
+将远端本体数据同步到本地：
+
+```bash
+.\scripts\dazi.ps1 onto space snapshot --space-id <space-id>
+```
+
+快照保存到 `onto/<space-id>/snapshot.json`。

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

@@ -0,0 +1,145 @@
+# 本体脚本编写指南
+
+**文档 ID**: `onto/script-authoring`
+
+本文说明本体项目内 **Python 脚本的目录、类型、发布与运行**（原独立的「脚本开发与发布」已与本文合并）。
+
+> 终端命令均在 **`dazi-work` 根目录**执行：`.\scripts\dazi.ps1 ...`（见 [CLI 调用约定](../guides/cli-invocation.md)）。
+
+## 环境
+
+- 推荐 **Python 3.10+**
+- 脚本目录：**`<工作区根>/项目/onto_<项目名>/脚本/`**（新建本体项目时自动创建）
+- 扩展默认脚本语言：`dazi.onto.defaultScriptLang` = `python`
+- 平台 API：`dazi.serverUrl`；登录：`.\scripts\dazi.ps1 auth login` / `.\scripts\dazi.ps1 auth set-token`
+
+## 目录约定
+
+```text
+<工作区根>/项目/onto_<项目名>/    ← 扩展「新建项目」；README 含 space_id
+├── README.md
+├── 快速启动.md
+├── 规划/
+└── 脚本/                          ← 所有本体 Python 脚本（函数/动作/灌数/初始化）
+    ├── main.py
+    └── ...
+```
+
+参考示例（可复制后修改）位于 **`资源/examples/onto/`**（侧栏 **帮助 → 示例** 或 `.\scripts\dazi.ps1 examples sync`）。
+
+> **不再使用** 历史路径 `onto/<space_id>/editorial/`、`editorial/functions/` 等作为本地开发约定。
+
+## 必读规范（DaziScript）
+
+编写 `脚本/` 下 `.py` 前请阅读：
+
+| 文档 | 说明 |
+|------|------|
+| **[DaziScript SDK 参考](./dazi_script_sdk_reference.md)** | `space` / `s.sql` / `s.onto` / `s.tables` / Cube 等 API 与本体落库顺序 |
+| **[DaziScript 灌数脚本编写指南](./dazi_script_seed_data_guide.md)** | 造数、补数、`insert_rows` 与 ClickHouse `INSERT` 约束、幂等约定 |
+
+同步到工作区：`.\scripts\dazi.ps1 docs sync` → `资源/docs/onto/`。
+
+## 脚本类型
+
+类型由 **发布命令参数** 区分；文件可平铺在 `脚本/`，也可分子目录（如 `脚本/functions/`、`脚本/actions/`）：
+
+| 类型 | 路径约定 | 说明 |
+|------|---------|------|
+| `ontology_function` | `项目/onto_<项目名>/脚本/**/*.py` | **必须**带 `--register-function-id` 发布（见下节） |
+| `ontology_action` | `项目/onto_<项目名>/脚本/**/*.py` | 发布时加 `--register-action-id` 等 Action 参数 |
+| `data_script` | `项目/onto_<项目名>/脚本/**/*.py` | 普通 `script publish`，不注册函数/动作 |
+
+`<space-id>` 从 **`项目/onto_<项目名>/README.md`** 读取，勿手写错空间。
+
+## 发布预检
+
+```powershell
+.\scripts\dazi.ps1 onto script publish-preview 项目/onto_<项目名>/脚本/my_func.py --space <space-id>
+```
+
+## 发布脚本
+
+> **勿用** 独立命令 `dazi-onto`（v3 未安装到 PATH）。统一使用 **`.\scripts\dazi.ps1 onto ...`**。
+
+### 本体函数：**必须注册**，否则侧栏与测试看不到
+
+`脚本/functions/`（或规划中的本体函数 `.py`）**不能**只执行「普通 publish」：
+
+| 仅 `script publish`（无 `--register-function-id`） | 带 `--register-function-id` 发布 |
+|--------------------------------------------------|----------------------------------|
+| 脚本代码进入 `ads_scripts` | 同上 **且** 写入 `ontology_function_defs` |
+| **不会**出现在 **Onto → 函数列表** | 出现在函数列表，可 **运行函数** / 工作台测试 |
+| `.\scripts\dazi.ps1 onto function run <id>` **找不到** | `function run`、侧栏运行可用 |
+
+因此：**首次发布本体函数时，命令里必须包含 `--register-function-id`**，且 `function_id` 与规划文档、脚本内约定 **完全一致**（建议带点号命名空间，如 `sales.fn.get_summary`，勿随意简写为 `get_summary`）。
+
+智能体（TRAE 等）实施自检：
+
+1. 发布命令是否包含 `--register-function-id`？  
+2. 发布输出是否含 `functionId: xxx` / `function_registration.ok`？  
+3. `.\scripts\dazi.ps1 onto function list --space <space-id>` 能否看到该 `function_id`？  
+
+任一步不满足 → **视为未注册**，需重新 publish（带注册参数），不要仅 `script run` 以为函数已可用。
+
+```powershell
+# 初始化 / 灌数：普通发布即可（不要加 register-function-id）
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/setup/xxx_ontology_init.py --space <space-id> --type setup
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/setup/xxx_seed_data.py --space <space-id> --type data
+
+# ★ 本体函数：必须注册（示例）
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/functions/get_summary.py `
+  --space <space-id> `
+  --register-function-id sales.fn.get_summary
+
+# 发布并注册为本体动作（示例）
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/my_action.py `
+  --space <space-id> `
+  --register-action-id my_action_code `
+  --register-action-permission-tag "finance.write"
+```
+
+发布后验证：
+
+```powershell
+.\scripts\dazi.ps1 onto function list --space <space-id>
+.\scripts\dazi.ps1 onto function run sales.fn.get_summary --space <space-id>
+```
+
+亦可在 VS Code 侧栏 **Onto 本体 → 发布函数** 发布（须填写/绑定 **function_id**）；发布后在 **函数** 节点下应能看到该函数。
+
+函数生命周期与 `update-code` 详见 **[本体函数开发指南](./function-guide.md)**。给 TRAE 的完整命令模板见内置提示词 **`onto/script-publish-run`**（`.\scripts\dazi.ps1 prompt sync` 后位于 `资源/prompts/onto/`）。
+
+## 从平台拉取脚本（可选）
+
+若需将平台上已有脚本拉回本地对照（**非**日常开发主路径）：
+
+```powershell
+.\scripts\dazi.ps1 onto script sync --space <space-id>
+.\scripts\dazi.ps1 onto script sync --space <space-id> --type ontology_function
+.\scripts\dazi.ps1 onto script sync --space <space-id> --dry-run
+```
+
+拉取目标目录以 CLI 为准；**新建与修改仍以 `项目/onto_<项目名>/脚本/` 为准**。
+
+## 清理重复脚本
+
+```powershell
+.\scripts\dazi.ps1 onto script dedupe --space <space-id> --dry-run
+.\scripts\dazi.ps1 onto script dedupe --space <space-id> --yes
+```
+
+## 编写建议
+
+1. 先阅读 `快速启动.md` 与 `README.md` 中的**数据空间 ID**
+2. 在 `脚本/` 中按模块拆分 `.py`（初始化、灌数、本体函数可分机文件）
+3. 发布与运行：`.\scripts\dazi.ps1 onto script publish`（**函数必须** `--register-function-id`）/ 侧栏 **Onto 本体**；函数运行见 **[function-guide](./function-guide.md)**、**[action-guide](./action-guide.md)**
+4. 本地仅调试 Python 语法时可用 VS Code 运行 `脚本/main.py`（**不会**自动连平台；连平台须发布后在侧栏或 CLI 执行）
+
+## 相关文档
+
+- [CLI 调用约定](../guides/cli-invocation.md)
+- [本体规划指南](./本体规划指南.md)
+- [本体函数开发指南](./function-guide.md)
+- [本体动作开发](./action-guide.md)
+- [规划示例：利润分析本体](./规划示例_利润分析本体方案.md)

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

@@ -0,0 +1,131 @@
+# 本体规划指南
+
+## 目标
+
+在 `规划/` 目录中完成本体项目的概念设计，包括：
+
+- 业务域与边界
+- 对象类型（Object Type）与关键属性
+- 链接类型（Link Type）与基数
+- 动作（Action）与规则（Rule）的初步清单
+
+## 本体、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` 时，规划文中仍应写清本体链接语义。
+
+**与业界对象中心实践的对照**：上述分层与「对象优先、数据为 backing」的思路，可与 **Palantir Foundry Ontology**（对象类型、链接、Action、Function 分层）等成熟产品对照阅读；落地脚本时以平台当前 API 与 **`.\scripts\dazi.ps1 onto`** 能力为准，**不**假设已实现对方全部特性。
+
+## 必读文档
+
+1. **本体规划示例**：`规划示例_利润分析本体方案.md`（扩展内置于 `docs/onto/`；同步到工作区后为 `资源/docs/onto/规划示例_利润分析本体方案.md`）
+2. **工作区与 CLI**：`guides/workspace-v3.md`、`guides/cli-reference.md`（`.\scripts\dazi.ps1 docs sync` 后位于 `资源/docs/guides/`）
+
+## 产出约定
+
+- **本体方案（规划文档）**：新建/修改的 Markdown **必须**落在 **`项目/{{项目名称}}/规划/<规划主题>.md`**（这是规划阶段的真产出；**不是**改 `本体规划指南.md`）。
+- 进入脚本实现阶段：遵循 **`本体脚本编写指南.md`**（含发布）、**`function-guide.md`**。
+
+## 空间约束（强制）
+
+- 本体项目创建时已绑定 **数据空间**；`space_id` 以 **`项目/<文件夹名>/README.md`** 为准。
+- 若 README 中无 `space_id`（非扩展「新建项目」创建的本体项目），不得新建规划文件，须先让用户补全空间或重新创建项目。
+
+## LLM 执行指引（必须遵循）
+
+面向 **dazi-vscode v3**：终端用 **`.\scripts\dazi.ps1`**（本体/流程/数据/鉴权），DRAP 在 **`项目/app_<名称>/` 应用项目根** 用 **`pnpm run dazi-app --`**；**禁止**全局 `dazi-onto` / 已废弃的 `dazi-agent`。
+
+### 工作区与项目
+
+- **工作区根**：VS Code 已打开的文件夹；多根工作区时在设置 **`dazi.workspaceRoot`** 指定。
+- **平台与登录**：`dazi.serverUrl`；`.\scripts\dazi.ps1 auth login` 或 `.\scripts\dazi.ps1 auth set-token`（Token 存 `.dazi/auth.json`）。
+- **本体项目即工作单元**（扩展「新建项目」时已选定数据空间，**无需**再建 `onto/<space_id>/` 等平行目录）：
+
+```text
+<工作区根>/
+  项目/onto_<名称>/
+    README.md       ← 数据空间 ID、项目元信息（规划/实施均以此为准）
+    规划/           ← 规划阶段 Markdown 产出
+    脚本/           ← 本体 Python 脚本
+  资源/docs/onto/   ← 本体指南与规划示例（.\scripts\dazi.ps1 docs sync）
+  资源/dataspaces/  ← 侧栏下载的表结构 Markdown
+```
+
+### 规划开始前
+
+1. 从 **`项目/<文件夹名>/README.md`** 读取 **数据空间 ID**（可与设置 `dazi.spaceId` 对照，以 README 为准）。
+2. 未绑定 `space_id` 时 **不得** 新建规划 Markdown，须先让用户通过扩展创建本体项目或明确空间。
+
+### 规划阶段最小流程
+
+在 **工作区根目录** 打开终端执行：
+
+```bash
+.\scripts\dazi.ps1 doctor
+.\scripts\dazi.ps1 auth whoami
+.\scripts\dazi.ps1 docs sync    # 可选：同步帮助文档到 资源/docs/
+```
+
+**核对数据空间与现网资产**（`<space_id>` 取自当前项目的 `README.md`，勿另猜目录）：
+
+```bash
+.\scripts\dazi.ps1 onto space list
+.\scripts\dazi.ps1 onto space get <space_id>    # 可选：查看空间详情
+```
+
+**扩展侧栏（规划阶段主要入口）**：
+
+| 目的           | 操作 |
+| -------------- | ---- |
+| 确认绑定空间   | 打开 **`项目/onto_<名称>/README.md`** 中的数据空间 ID |
+| 查看表 / Cube  | **数据资源** → 对应数据空间 → 展开表、Cube |
+| 下载表结构     | 表节点右键「下载表信息」→ `资源/dataspaces/` |
+| 同步帮助文档   | **帮助** → 下载文档（`.\scripts\dazi.ps1 docs sync`） |
+
+> 规划阶段**不**要求本地 `snapshot.json`、`editorial/` 或 `onto/<space_id>/` 目录；以侧栏 **数据资源** 与项目内文档为准即可。
+
+规划阶段 **只产出 Markdown**：写入 **`项目/<onto_项目>/规划/<主题>.md`**，可参考 **`规划示例_利润分析本体方案.md`**。此阶段不发布脚本。
+
+### 进入脚本实施
+
+脚本写在 **`项目/<onto_项目>/脚本/`**（Python，见 `dazi.onto.defaultScriptLang`）。发布与运行见 **`本体脚本编写指南.md`**、**`function-guide.md`**：
+
+```bash
+.\scripts\dazi.ps1 onto script publish-preview 项目/onto_<名称>/脚本/my_func.py --space <space_id>
+.\scripts\dazi.ps1 onto script publish 项目/onto_<名称>/脚本/my_func.py \
+  --space <space_id> \
+  --register-function-id <function_id>
+.\scripts\dazi.ps1 onto function run <function_id> --space <space_id> --params '{}'
+```
+
+亦可在侧栏 **Onto 本体** 使用「发布函数」「运行函数」等命令（与终端 CLI **同源** bundled；`--space` 与项目 README 中的 `space_id` 一致）。
+
+实施前可用 `.\scripts\dazi.ps1 onto function list --space <space_id>` 核对平台已有函数定义，**开发入口始终是 `项目/<onto_项目>/脚本/`**，不以历史 `onto/`、`editorial` 目录为约定路径。
+
+### 失败处理
+
+- 命令失败时输出 **完整错误** 与修复建议（登录、`dazi.serverUrl`、工作区路径、`space_id`），**不得** 静默跳过。
+- v2 → v3 命令对照见 `guides/troubleshooting.md`（`.\scripts\dazi.ps1 docs sync` 后位于 `资源/docs/guides/`）。
+
+## 自检
+
+- 是否写清对象类型、链接、函数/Action、规则（如适用）
+- **`define_link_type` 与对象类型 code**：链接两端须为**已规划且将先创建**的对象类型 **`code`**（与 `define_object_type` 一致）；**勿**将 **Cube 名** 或表名当作对象类型 `code`。勿混用仅中文名而无稳定 `code`。
+- 是否给出实施步骤、风险与验收
+
+## 相关文档
+
+- [本体脚本编写指南](./本体脚本编写指南.md)
+- [本体规划指南](./本体规划指南.md)
+- [本体规划示例文档](./规划示例_利润分析本体方案.md)