@dazitech/cli 3.0.0

package/dist/docs/guides/quickstart.md

@@ -0,0 +1,77 @@
+# 快速开始
+
+**文档 ID**: `guides/quickstart`  
+**适用版本**: dazi-vscode v3.0+
+
+> CLI 调用约定见 **[CLI 调用约定](./cli-invocation.md)**。生产环境在 `dazi-work` 根目录使用 `.\scripts\dazi.ps1`。
+
+## 5 分钟完成首次配置
+
+### 1. 安装扩展
+
+在 VS Code / Cursor 中安装 **搭子** 扩展，或通过 `.vsix`：
+
+```powershell
+code --install-extension dazi-vscode-3.x.x.vsix
+```
+
+### 2. 打开工作区
+
+将 **`dazi-work`** 文件夹作为 VS Code 工作区根目录打开（含 `项目/`、`资源/`、`scripts/`）。  
+DRAP 应用项目位于 **`项目/app_<名称>/`**（完整 monorepo，见 [§331](../../docs/331-应用项目多项目与组件重构.md)）；不再要求根目录必须有 `runtime-apps/`。
+
+### 3. 自检 CLI
+
+```powershell
+cd D:\path\to\dazi-work
+.\scripts\doctor-cli.ps1
+```
+
+应解析到已安装扩展内的 `bundled/clis/dazi.js`（无需 monorepo 源码）。
+
+### 4. 配置服务地址
+
+在 VS Code 设置中搜索 `dazi.serverUrl`，填入搭子平台地址：
+
+```
+https://your-dazi-server.example.com
+```
+
+### 5. 登录
+
+在命令面板（`Ctrl+Shift+P`）搜索 **搭子: 登录**，或终端：
+
+```powershell
+.\scripts\dazi.ps1 auth login
+# 或直接绑定 Token
+.\scripts\dazi.ps1 auth set-token --token "your-jwt-token"
+```
+
+### 6. 初始化工作区
+
+```powershell
+# 新项目（本体空间）
+.\scripts\dazi.ps1 onto space init --space-id <your-space-id>
+
+# 已有 v2 项目迁移
+.\scripts\dazi.ps1 migrate workspace
+```
+
+### 7. 验证环境
+
+```powershell
+.\scripts\dazi.ps1 doctor
+.\scripts\dazi.ps1 env
+.\scripts\dazi.ps1 auth whoami
+```
+
+侧栏「搭子」图标应显示 6 个节点：帮助、数据资源、本体、流程、应用、工作区。
+
+## 下一步
+
+- [CLI 调用约定](./cli-invocation.md)
+- [认证管理](../auth/auth-login.md)
+- [本体开发入门](../onto/space-management.md)
+- [数据流程项目开发](../flow/flow-project-guide.md) — **推荐**：`项目/flow_*`、菜单、pull/push
+- [节点代码编写](../flow/node-code-guide.md) — python-script、sql-query 等
+- [流程开发索引](../flow/flows-guide.md) — Flow 文档入口

package/dist/docs/guides/troubleshooting.md

@@ -0,0 +1,82 @@
+# 故障排查
+
+**文档 ID**: `guides/troubleshooting`
+
+> 终端命令统一使用 **`dazi-work` 根目录** 下的 `.\scripts\dazi.ps1`（见 [CLI 调用约定](./cli-invocation.md)）。
+
+## CLI 命令找不到（优先排查）
+
+```powershell
+cd D:\path\to\dazi-work
+.\scripts\doctor-cli.ps1
+```
+
+常见原因：
+
+| 原因 | 处理 |
+|------|------|
+| 未安装 `dazi-vscode.vsix` | 安装扩展后重跑 doctor-cli |
+| **Trae 已装扩展但 doctor 报未安装** | Trae 扩展在 `%USERPROFILE%\.trae\extensions`；更新 `dazi-work/scripts` 后重跑 doctor，或 `.\scripts\sync-clis-from-extension.ps1` |
+| 扩展在但 `bundled/clis/dazi.js` 缺失 | 用完整 `pnpm run vsix` 重打包装；勿用缺 bundled 的旧包 |
+| 直接输入 `dazi` / `dazi-onto` | 改用 `.\scripts\dazi.ps1 ...`（无全局 `dazi-onto`） |
+| 未安装 Node.js 18+ | 安装 Node 并加入 PATH |
+
+环境详情：
+
+```powershell
+.\scripts\dazi.ps1 doctor
+.\scripts\dazi.ps1 env
+```
+
+## 401 未授权
+
+```powershell
+.\scripts\dazi.ps1 auth whoami
+.\scripts\dazi.ps1 auth login
+.\scripts\dazi.ps1 auth set-token --token "<new-token>"
+```
+
+Token 保存在 `~/.dazi/auth.json`，检查是否过期。
+
+## 扩展侧栏空白
+
+1. 检查 `dazi.serverUrl` 配置是否正确
+2. 执行 `.\scripts\dazi.ps1 auth whoami` 确认登录状态
+3. 右键侧栏节点选「刷新」
+
+## 工作区目录找不到
+
+```powershell
+.\scripts\dazi.ps1 doctor --workspace-root D:\path\to\dazi-work
+```
+
+或在 VS Code 设置中配置 `dazi.workspaceRoot`。
+
+## 从 v2 迁移后命令不匹配
+
+| 旧命令 | v3 命令（dazi-work 根目录） |
+|--------|----------------------------|
+| `dazi-agent snapshot refresh` | `.\scripts\dazi.ps1 onto space snapshot` |
+| `dazi-agent function-def list` | `.\scripts\dazi.ps1 onto function list` |
+| `dazi-agent flow snapshot pull` | `.\scripts\dazi.ps1 flow snapshot pull` |
+
+## MCP 连不上
+
+检查 `.cursor/mcp.json` 配置。MCP 需能调用 bundled CLI，示例：
+
+```powershell
+$env:DAZI_BUNDLED_DIR = "$env:USERPROFILE\.cursor\extensions\dazitech.dazi-vscode-3.0.0\bundled\clis"
+node "$env:DAZI_BUNDLED_DIR\dazi.js" mcp stdio
+```
+
+或使用 `.\scripts\dazi.ps1 mcp stdio`（在 dazi-work 根目录）。
+
+## DRAP：`dazi-app` 找不到
+
+```powershell
+cd D:\path\to\dazi-work\项目\app_<名称>
+pnpm install
+pnpm run dazi-app -- --version
+```
+
+应用 CLI 由 bundled + 启动器提供，**不需要** monorepo 源码。

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

@@ -0,0 +1,53 @@
+# 工作区 v3 规范
+
+**文档 ID**: `guides/workspace-v3`  
+**适用版本**: dazi-vscode v3.0+  
+**最后更新**: 2026-05-28（应用项目 `项目/app_*`）
+
+## 目录结构（搭子工作区，如 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_* 并存
+```
+
+> v3.1+ **推荐**在 `项目/app_<名称>/` 下维护 DRAP，由扩展「新建应用项目」生成。详见 [§331](../../docs/331-应用项目多项目与组件重构.md)。
+
+## 目录说明
+
+| 路径 | 对应 CLI | 用途 |
+|------|----------|------|
+| `项目/onto_<名称>/` | `.\scripts\dazi.ps1 onto ...` | 本体规划、脚本、发布 |
+| `项目/app_<名称>/` | `pnpm run dazi-app -- ...`（在应用项目根） | DRAP monorepo；组件在 `apps/<app_id>/` |
+| `项目/app_<名称>/apps/<app_id>/` | 同上 + `--cwd apps/<app_id>` | 单个应用组件源码 |
+| `资源/docs/` | `.\scripts\dazi.ps1 docs ...` | 同步后的内置文档 |
+| `scripts/` | `.\scripts\dazi.ps1 ...` | 本体/流程/鉴权/数据（非 DRAP） |
+| `~/.dazi/auth.json` | 共享 | 登录凭据（扩展与 CLI 共用） |
+
+## 扩展侧栏对应
+
+| 侧栏 | 工作区路径 |
+|------|------------|
+| 本体 | `项目/onto_*` |
+| App 应用 | `项目/app_*`（monorepo）→ `apps/<app_id>` |
+| 数据资源 | 平台数据空间（非目录） |
+
+## v2 → v3 目录映射
+
+| v2 | v3（搭子工作区） |
+|----|----------------|
+| `ontology/` | `项目/onto_*` |
+| `runtime-apps/apps/*` | `项目/app_*/apps/*`（推荐）或 `<ws>/runtime-apps/apps/*`（兼容） |
+| `.dazi-agent/auth.json` | `~/.dazi/auth.json` |
+
+## 相关文档
+
+- [§331 应用项目多项目与组件重构](../../docs/331-应用项目多项目与组件重构.md)
+- [§333 本轮扩展总结](../../docs/333-dazi-vscode应用项目多项目与本轮优化总结.md)
+- [CLI 调用约定](./cli-invocation.md)

package/dist/docs/index.json

@@ -0,0 +1,204 @@
+{
+  "version": "3.0.0-beta.3",
+  "updatedAt": "2026-05-29T00:00:00.000Z",
+  "docs": [
+    {
+      "id": "guides/quickstart",
+      "title": "快速开始",
+      "category": "guides",
+      "file": "guides/quickstart.md"
+    },
+    {
+      "id": "guides/cli-invocation",
+      "title": "CLI 调用约定",
+      "category": "guides",
+      "file": "guides/cli-invocation.md"
+    },
+    {
+      "id": "guides/workspace-v3",
+      "title": "工作区 v3 规范",
+      "category": "guides",
+      "file": "guides/workspace-v3.md"
+    },
+    {
+      "id": "guides/migrate-v2-v3",
+      "title": "从 v2 迁移到 v3",
+      "category": "guides",
+      "file": "guides/migrate-v2-v3.md"
+    },
+    {
+      "id": "guides/cli-reference",
+      "title": "CLI 命令速查",
+      "category": "guides",
+      "file": "guides/cli-reference.md"
+    },
+    {
+      "id": "guides/troubleshooting",
+      "title": "故障排查",
+      "category": "guides",
+      "file": "guides/troubleshooting.md"
+    },
+    {
+      "id": "guides/mcp-setup",
+      "title": "MCP 配置指南",
+      "category": "guides",
+      "file": "guides/mcp-setup.md"
+    },
+    {
+      "id": "auth/auth-login",
+      "title": "认证登录",
+      "category": "auth",
+      "file": "auth/auth-login.md"
+    },
+    {
+      "id": "auth/token-management",
+      "title": "Token 管理",
+      "category": "auth",
+      "file": "auth/token-management.md"
+    },
+    {
+      "id": "onto/space-management",
+      "title": "本体空间管理",
+      "category": "onto",
+      "file": "onto/space-management.md"
+    },
+    {
+      "id": "onto/function-guide",
+      "title": "本体函数开发",
+      "category": "onto",
+      "file": "onto/function-guide.md"
+    },
+    {
+      "id": "onto/action-guide",
+      "title": "本体动作（Action）开发",
+      "category": "onto",
+      "file": "onto/action-guide.md"
+    },
+    {
+      "id": "onto/rule-guide",
+      "title": "本体规则管理",
+      "category": "onto",
+      "file": "onto/rule-guide.md"
+    },
+    {
+      "id": "onto/planning-guide",
+      "title": "本体规划指南",
+      "category": "onto",
+      "file": "onto/本体规划指南.md"
+    },
+    {
+      "id": "onto/planning-example-profit",
+      "title": "规划示例：利润分析本体",
+      "category": "onto",
+      "file": "onto/规划示例_利润分析本体方案.md"
+    },
+    {
+      "id": "onto/script-authoring",
+      "title": "本体脚本编写指南（含发布）",
+      "category": "onto",
+      "file": "onto/本体脚本编写指南.md"
+    },
+    {
+      "id": "onto/dazi-script-sdk-reference",
+      "title": "DaziScript SDK 参考",
+      "category": "onto",
+      "file": "onto/dazi_script_sdk_reference.md"
+    },
+    {
+      "id": "onto/dazi-script-seed-data-guide",
+      "title": "DaziScript 灌数指南",
+      "category": "onto",
+      "file": "onto/dazi_script_seed_data_guide.md"
+    },
+    {
+      "id": "flow/flow-project-guide",
+      "title": "数据流程项目开发指南",
+      "category": "flow",
+      "file": "flow/flow-project-guide.md"
+    },
+    {
+      "id": "flow/流程开发最佳实践-VS-flow0案例",
+      "title": "流程开发最佳实践（VS-flow0 案例）",
+      "category": "flow",
+      "file": "flow/流程开发最佳实践-VS-flow0案例.md"
+    },
+    {
+      "id": "flow/variables-guide",
+      "title": "流程变量系统指南",
+      "category": "flow",
+      "file": "flow/variables-guide.md"
+    },
+    {
+      "id": "flow/node-code-guide",
+      "title": "节点代码编写指南",
+      "category": "flow",
+      "file": "flow/node-code-guide.md"
+    },
+    {
+      "id": "flow/flows-guide",
+      "title": "Flow 文档索引",
+      "category": "flow",
+      "file": "flow/flows-guide.md"
+    },
+    {
+      "id": "flow/run-guide",
+      "title": "Flow 运行管理",
+      "category": "flow",
+      "file": "flow/run-guide.md"
+    },
+    {
+      "id": "flow/snapshot-guide",
+      "title": "Flow 快照管理",
+      "category": "flow",
+      "file": "flow/snapshot-guide.md"
+    },
+    {
+      "id": "flow/source-guide",
+      "title": "数据源管理",
+      "category": "flow",
+      "file": "flow/source-guide.md"
+    },
+    {
+      "id": "flow/plan-guide",
+      "title": "Flow 执行计划",
+      "category": "flow",
+      "file": "flow/plan-guide.md"
+    },
+    {
+      "id": "app/app-init",
+      "title": "应用初始化",
+      "category": "app",
+      "file": "app/app-init.md"
+    },
+    {
+      "id": "app/build-upload",
+      "title": "应用构建与上传",
+      "category": "app",
+      "file": "app/build-upload.md"
+    },
+    {
+      "id": "app/release-guide",
+      "title": "应用发布管理",
+      "category": "app",
+      "file": "app/release-guide.md"
+    },
+    {
+      "id": "data/data-spaces",
+      "title": "数据空间管理",
+      "category": "data",
+      "file": "data/data-spaces.md"
+    },
+    {
+      "id": "data/table-preview",
+      "title": "数据表预览",
+      "category": "data",
+      "file": "data/table-preview.md"
+    },
+    {
+      "id": "data/cube-guide",
+      "title": "数据集（Cube）管理",
+      "category": "data",
+      "file": "data/cube-guide.md"
+    }
+  ]
+}

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

@@ -0,0 +1,48 @@
+# 本体动作（Action）开发
+
+**文档 ID**: `onto/action-guide`
+
+## Action 概念
+
+Action 是可被外部系统触发的本体操作，通常用于：
+- 写入数据
+- 触发业务流程
+- 执行审批操作
+
+## 列出动作
+
+```bash
+.\scripts\dazi.ps1 onto action list --space <space-id>
+```
+
+## 发布 Action
+
+脚本放在 **`项目/onto_<项目名>/脚本/`**（可与函数脚本同目录，用文件名区分）：
+
+```bash
+.\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"
+```
+
+`<space-id>` 取自项目 **`README.md`**。
+
+## 更新 Action 代码
+
+```bash
+.\scripts\dazi.ps1 onto action update-code my_action_code \
+  --space <space-id> \
+  --stem my_action
+```
+
+## Action 脚本结构
+
+```python
+def main(params: dict, context: dict) -> dict:
+    """
+    Action 入口。
+    context 包含触发者信息、权限标签等。
+    """
+    return {"status": "ok"}
+```

package/dist/docs/onto/dazi_script_sdk_reference.md

@@ -0,0 +1,168 @@
+# DaziScript SDK 参考
+
+**文档 ID**: `onto/dazi-script-sdk-reference`  
+**适用**: dazi-vscode v3 + 搭子平台 DaziScript（ClickHouse 数据空间）
+
+> 给 LLM 与开发者提供精简、可执行的 SDK 规范。脚本目录、类型与 **`.\scripts\dazi.ps1 onto script publish`** 等见 **[本体脚本编写指南](./本体脚本编写指南.md)**。
+
+## 1. 工作区与脚本放置（dazi-vscode）
+
+| 用途 | 路径 |
+|------|------|
+| **日常开发**（推荐） | `<工作区根>/项目/onto_<项目名>/脚本/*.py` |
+| **空间 ID** | `项目/onto_<项目名>/README.md` 中的数据空间 ID |
+| **参考示例** | `资源/examples/onto/setup/`、`资源/examples/onto/function/`（侧栏 **帮助 → 示例** 或 `.\scripts\dazi.ps1 examples sync`） |
+| **本文档** | `资源/docs/onto/dazi_script_sdk_reference.md`（`.\scripts\dazi.ps1 docs sync` 后） |
+
+- **禁止**将 `onto/<space_id>/editorial/` 作为 v3 本地开发约定（历史路径，仅 CLI `script sync` 可能拉回平台副本）。
+- 脚本入口仅需定义 **`main()`**；平台执行时自动调用，**不要**写 `if __name__ == "__main__":`。
+
+## 2. 基本约束
+
+- 数据引擎：**ClickHouse**
+- 新建空间须显式指定（若脚本内创建空间）：
+  - `storage_engine="clickhouse"`
+  - `connection_config={"database": "<db_name>"}`
+- 执行前确认已登录（`.\scripts\dazi.ps1 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
+# 预检
+.\scripts\dazi.ps1 onto script publish-preview 项目/onto_<项目名>/脚本/my_setup.py --space <space-id>
+
+# 发布（初始化/灌数类脚本）
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/my_setup.py --space <space-id>
+
+# 发布并注册为本体函数
+.\scripts\dazi.ps1 onto script publish 项目/onto_<项目名>/脚本/my_func.py \
+  --space <space-id> \
+  --register-function-id my_func
+
+# 运行已入库函数
+.\scripts\dazi.ps1 onto function run my_func --space <space-id> --params '{}'
+```
+
+亦可用侧栏 **Onto 本体** → 发布函数 / 运行函数。
+
+## 8. 回归与 JSON 摘要
+
+- 支持 `--json` 时，输出前缀统一：`__JSON_SUMMARY__`
+- 非 0 退出码即失败
+- 会改写数据的步骤须提供跳过/禁用开关
+
+**内置参考示例**（在用户工作区：**侧栏 帮助 → 示例 → 下载所有示例**，或执行 `.\scripts\dazi.ps1 examples sync`，得到 **`资源/examples/`**；可复制到 **`项目/<onto_项目名>/脚本/`** 再改，勿直接改写同步下来的只读备份）：
+
+- 初始化：**`<工作区根>/资源/examples/onto/setup/profit_ontology_init.py`**
+- 函数样例：**`<工作区根>/资源/examples/onto/function/profit_fn_*.py`**