@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guands/references/calc-fields-boundaries-and-pitfalls.md

@@ -0,0 +1,160 @@
+# guands 计算字段、职责边界与易错点
+
+## 数据集计算字段
+
+在数据集上直接新建计算字段，无需创建 ETL。支持普通 SQL 表达式、窗口函数和聚合函数。
+
+`--calc-type` 选项：
+- `normal`（默认）: 行级表达式，如 `[利润]/[销售额]`
+- `window`: 窗口函数，如 `SUM([x]) OVER(PARTITION BY [y] ORDER BY [z])`
+- `aggregation`: 聚合函数，如 `SUM([利润])/SUM([销售额])`，结果在卡片中按维度聚合
+
+```bash
+# 新建计算字段
+guands dataset calc-field add <dsId> --name "利润率" --formula "[利润]/[销售额]"
+guands dataset calc-field add <dsId> --name "发货天数" --formula "datediff([发货日期], [订单日期])" --type INT
+guands dataset calc-field add <dsId> --name "状态" --formula "CASE WHEN [利润] > 0 THEN '盈利' ELSE '亏损' END" --type STRING
+guands dataset calc-field add <dsId> --name "利润率_聚合" --formula "SUM([利润])/SUM([销售额])" --calc-type aggregation
+
+# 更新计算字段
+guands dataset calc-field update <dsId> --fd-id <fdId> --formula "[利润]/[销售额]*100"
+guands dataset calc-field update <dsId> --fd-id <fdId> --name "新利润率" --formula "[利润]/[销售额]"
+
+# 删除计算字段
+guands dataset calc-field delete <dsId> --fd-id <fdId> --yes
+```
+
+**批量新建计算字段**（N 个字段用一次命令，不要循环调用 add）：
+
+```bash
+# vcs.json 是 JSON 数组，每条含 name/formula 必填，alias/fdType/calculationType/annotation 可选
+guands dataset calc-field batch-add <dsId> --file vcs.json --dry-run   # 先预检
+guands dataset calc-field batch-add <dsId> --file vcs.json
+# 中途失败后修正文件并幂等重跑（已创建成功的同名字段自动跳过）
+guands dataset calc-field batch-add <dsId> --file vcs.json --skip-existing
+```
+
+batch-add 特性：
+- 提交前本地预检：批内/与现有字段的展示名冲突、保留字符、公式 `[字段引用]` 完整性
+- 批内字段互相引用时自动按依赖拓扑排序创建（如"利润率分档"引用"利润率"），循环引用报错
+- 逐条提交（后端无批量端点），失败默认继续并汇总记账，`--fail-fast` 首错即停；依赖失败字段的条目自动级联跳过
+- 输入兼容 `guancli ds get <srcDsId> --raw` 输出的字段对象原样内容（fdId/dsId 等自动忽略），
+  跨数据集/跨环境克隆计算字段（计算字段分布在 `columns` 与 `virtualColumns` 中，按 formula 非空过滤）：
+  `guancli ds get <srcDsId> --raw | jq '[(.data.columns[]?, .data.virtualColumns[]?) | select(.formula != null and .formula != "")]' > vcs.json`
+
+**对齐已有字段用 `calc-field apply`**(不存在则建,已存在且一致则跳过,不一致默认整批中断并逐项列出
+`formula`/`fdType`/`alias`/`annotation` 线上与本次的取值)。文件里没写 `fdType` 时 apply **不断言类型**
+(新建仍按 DOUBLE 建):COUNT 一类在线上是 LONG 的字段不会因为文件缺省而被判成"不一致"。
+
+**公式语法**：
+- 抽取/上传数据集 → Apache Spark SQL 语法
+- 直连数据集 → 目标数据库 SQL 语法
+- 公式中用 `[字段名]` 方括号引用字段（中文、特殊字符均需方括号转义）
+
+**分组字段（把维度取值归类分档）用 CASE WHEN 计算字段实现**：
+
+BI UI 的「新建分组字段」本质是后端把分组配置翻译成 CASE 表达式执行，用 calc-field 直接写
+CASE WHEN 公式等价且更可控。不提供单独的分组字段命令。自然语言 → 公式对照：
+
+```bash
+# "把省份按华东/华南分组，其余归为其他"（项目分组）
+guands dataset calc-field add <dsId> --name "区域分组" --type STRING \
+  --formula "CASE WHEN [省份] IN ('上海','江苏','浙江') THEN '华东' WHEN [省份] IN ('广东','广西') THEN '华南' ELSE '其他' END"
+
+# "金额大于1000算高，其余算低"（条件分组）
+guands dataset calc-field add <dsId> --name "金额分档" --type STRING \
+  --formula "CASE WHEN [金额] > 1000 THEN '高' ELSE '低' END"
+
+# "金额每100一档"（固定步长分组）
+guands dataset calc-field add <dsId> --name "金额区间" --type STRING \
+  --formula "CONCAT(FLOOR([金额]/100)*100, '-', FLOOR([金额]/100)*100+100)"
+
+# "未分组的值各自独立显示"（不合并为"其他"）→ ELSE 返回源字段
+#   ... ELSE [省份] END
+```
+
+注意事项：
+- 写 IN 列表前先用 `guancli ds preview <dsId>` 或 `guancli ds execute-sql --inputs <dsId> --sql "SELECT DISTINCT \`<字段>\` FROM \`<数据集名>\`"` 确认字段实际取值，避免拼错枚举值
+- 多个分组字段一起建时用 `calc-field batch-add`
+- BI UI 里通过可视化编辑器创建的分组字段，在 `dataset fields` 输出的来源列显示为「分组列」；
+  这类字段 CLI 无法原地修改分组配置（只能 UI 改，或用 CASE WHEN 计算字段重建后删除原字段）
+
+**何时用数据集计算字段 vs 卡片级 calcField vs ETL**：
+
+| 场景 | 推荐方式 | 原因 |
+|---|---|---|
+| 行级计算（如 `[利润]/[销售额]`） | **数据集计算字段**（`--calc-type normal`） | 所有卡片和筛选器都能引用 |
+| 需要在筛选器中引用的计算字段 | **数据集计算字段** | selector 只能绑定数据集物理字段 |
+| 聚合计算（如 `SUM([利润])/SUM([销售额])`） | **数据集计算字段**（`--calc-type aggregation`） | 所有卡片都能引用，按维度自动聚合 |
+| 维度取值分组/分档（区域分组、金额分档） | **数据集计算字段**（CASE WHEN，见上节） | 等价于 UI 分组字段且 CLI 可控 |
+| 窗口函数（如 `SUM([x]) OVER(PARTITION BY [y])`） | **数据集计算字段**（`--calc-type window`） | 数据集级别支持窗口函数 |
+| 多表 JOIN + 复杂转换 | **ETL**（guanetl） | 需要先合表再计算 |
+| 只为单个图表临时使用的公式 | **卡片级 calcField** | 不污染数据集 |
+
+## 数据集影响分析
+
+```bash
+# 查看数据集被哪些卡片使用
+guands dataset cards <ds_id>
+
+# 查看数据集字段详情（含物理字段和计算字段）
+guands dataset fields <ds_id>
+```
+
+## 与 guancli 的职责边界（选择决策树）
+
+**核心原则**：guancli = 只读分析，guands = 写操作 + 数据集管理。两者共享认证配置。
+
+| 你要做什么？ | 用哪个工具 | 命令 |
+|---|---|---|
+| 查看数据集目录树 | guancli | `guancli ds tree` |
+| 搜索数据集 | guands | `guands dataset list <关键词>` |
+| 查看数据集详情+血缘+上下游 | guancli | `guancli ds get <dsId>` |
+| 查看数据集字段列表（含计算字段） | guands | `guands dataset fields <dsId>` |
+| 预览数据集数据 | guancli | `guancli ds preview <dsId>` |
+| 创建数据集 | guands | `guands dataset create-db/create-query/import` |
+| 刷新数据集 | guands | `guands dataset refresh <dsId>` |
+| 配置增量/定时更新 | guands | `guands dataset update-setting/schedule` |
+| 设置/清空去重主键 | guands | `guands dataset primary-key set/clear` |
+| 新建/更新/删除计算字段 | guands | `guands dataset calc-field add/update/delete` |
+| 批量新建计算字段 | guands | `guands dataset calc-field batch-add <dsId> --file vcs.json` |
+| 重命名/移动/删除数据集 | guands | `guands dataset rename/move/delete` |
+| 替换/追加数据集数据 | guands | `guands dataset replace-data / append-data` |
+| 清理数据集数据 | guands | `guands dataset clear-data <dsId> --where/--all` |
+| 查看数据集行列权限 | guands | `guands dataset permission get <dsId>` |
+| 查看数据集被哪些卡片使用 | guands | `guands dataset cards <dsId>` |
+| 查看 ETL 详情/血缘 | guancli | `guancli etl get <etlId>` |
+| 查看页面详情/卡片列表 | guancli | `guancli page get <pgId>` |
+| 管理连接器/账号 | guands | `guands connector/account` |
+| 管理目录 | guands | `guands dir` |
+
+**简记**：需要"改"数据集的任何属性 → guands；只需要"看"信息或分析血缘 → guancli
+
+## AI 使用易错点
+
+以下是 AI 调用此工具时容易犯的错误，请特别注意：
+
+1. **密码必须 Base64 编码**：`wrapAuthConfig` 已自动处理，但如果直接构造 `--config` JSON，`password` 字段需要是 Base64 编码后的值
+2. **异步 API 必须轮询**：`account tables`、`account preview`、`dataset create-db/create-query` 中的预览步骤都是异步的，CLI 会在进程内部轮询到 `FINISHED` 再继续，任务 ID 不对外暴露
+3. **创建数据集必须先获取列信息**：不能跳过预览步骤直接创建，后端要求 `columns` 字段非空
+4. **`sourceType` 枚举值**：抽取用 `GUAN_INDEX`（不是 `GUANINDEX`），直连用 `DIRECT_CONNECT_DATABASE`
+5. **抽取模式必须包含 `priority`**：默认 `"MEDIUM"`，否则 BI 界面显示为空
+6. **`cron` 字段必填**：即使不启用定时更新，也需要传递默认的 `cron` 配置
+7. **SQL 中的表名引用**：PostgreSQL 表名需要双引号包裹（如 `"link_data_source"`），优先使用 `fetchTableSQLMap` 获取服务端生成的 SQL
+8. **API 方法区分**：`get-table-list-async` 和 `get-schema-list` 是 **GET** 请求，`batch-preview-table-data-async` 和 `preview-table-data-async` 是 **POST** 请求
+9. **删除 API 路径特殊**：账号删除是 `/api/oridel/account/{id}`，数据集删除是 `/api/oridel/data-source/{id}`（不是 `/api/account/{id}/delete`）；数据集批量移动是 `/api/data-source/move`（没有 `/batch-move` 路由，单个移动才是 `/api/data-source/{dsId}/move`）
+10. **增量 SQL 必须使用时间宏**：不要使用 `CURDATE()`、`NOW()`、`CURRENT_DATE` 等数据库函数，应使用 BI 时间宏如 `{{{today}}}`、`{{{yesterday}}}`、`{{{today - 7 days}}}`。时间宏语法是三花括号 `{{{ expression }}}`，不是 `${参数名}`
+11. **`account preview` 服务端截断为 30 行**：`preview-table-data-async` API 的行数限制由后端域级配置 `datasourcePreviewLineLimit` 控制，默认 30 行。客户端无法传递 limit 参数覆盖此值，即使 SQL 中写了更大的 LIMIT 也会被服务端截断。如果输出恰好 30 行，CLI 会打印截断警告。需要全量数据时应使用 `guands dataset` 相关命令或 `guancli ds preview` 代替
+11. **update-setting 会读取现有配置**：`dataset update-setting` 会先 GET 当前数据集配置，保留现有 cron 等设置，只更新增量相关字段
+12. **refresh --wait 有超时**：默认 300 秒，大数据集全量更新可能需要更长时间，用 `--timeout 600` 增加；若原 task 失败后发现后续 task，继续等待仍共享这一个总超时预算
+13. **不要对同一数据集并行触发多个 refresh**：`dataset refresh` 会先检查数据集状态，已有更新时普通调用不重复提交，`--wait` 会加入已有任务。需要并行刷新多个数据集时，按数据集分别执行 `dataset refresh <dsId> --wait`（可并行起多个进程），结论以各数据集自身状态为准
+14. **定时更新频率限制**：`dataset schedule` 最高支持 5 分钟一次，低于 1 小时间隔会输出性能警告。建议 ODS 增量至少每小时，避免对数据库造成过大压力
+15. **不提供取消任务能力**：CLI 没有按任务 ID 取消任务的命令；需要停止正在执行的刷新时请到 BI 管理中心任务详情操作
+16. **create-db/create-query 抽取模式会自动触发首次抽数**：建集成功后 BI 服务端自动入队一次全量抽数（`dataset get` 显示 UPDATING/WAITING、rowCount=0 属正常加载中）。不要写"建完统一 refresh"的脚本；CLI 虽会识别已有任务并避免重复提交，但正确姿势仍是建集后用 `dataset refresh <dsId> --wait` 加入已有抽数，或轮询 `dataset get <dsId>` 等状态变 FINISHED。只有自动抽数明确 FAILED 且没有后续成功任务时才重跑
+17. **大批量抽数失败先查并行争抢，别急着怪单表太大**：BI 侧存在多道约 30 分钟级别的硬超时（任务最大运行时长 / Spark 单 job 超时 / 数据库连接 Socket timeout，具体阈值以目标环境管理中心配置为准），且「数据库数据集更新失败重试」默认未启用。批量建/刷几十张大表时，多任务争抢数据库连接池与集群资源，单表耗时可能远超串行基准（串行参考：200 万行/40 列 ≈ 2 分钟，1000 万行/40 列 ≈ 10 分钟），被拖过超时即 FAILED 且不会自动重试。诊断与应对：
+    - `create-db --wait` 会逐表报出首抽 FAILED 及原因摘要；深层堆栈需在 BI 管理中心任务详情查看
+    - 大表分批创建/刷新（每批 5~10 张，用 `create-db --wait` 等上一批首抽完成再提交下一批），避免同时全量入队
+    - 零散 FAILED 的表等高峰过后单独 `dataset refresh <dsId> --wait` 重跑即可，通常能成功
+    - 长期方案：请 BI 管理员在管理中心启用「数据库数据集更新支持失败重试」并评估调大超时阈值
+18. **填报表单不会自动暴露成数据集**：表单（fmId）与数据集（dsId）是两类实体，`dataset list` 搜不到表单。要让表单数据进下游 ETL，先用 `guands dataset create-form <fmId>` 创建 GUAN_FORM 填报数据集（fmId 用 `guancli form list` 查）。数据集 live-linked 到表单：表单新增数据后需 `dataset refresh` 或配置 `dataset schedule` 定时同步。要求环境已开通表单填报功能（未开通时表单接口返回 423）
+19. **`--dir-id` 只接受数据集(DATA_SET)目录树中的目录 ID**：BI 中页面/ETL/工作流等各资源有独立目录树，目录 ID 互不通用。有效 ID 一律以 `guands dir tree` 输出为准。注意读写行为不对称：`dataset list --dir-id <无效ID>` 静默返回空列表（不报错），而 move/import/create-db 等写操作会失败（服务端报 1002/1012「数据集存储目录不存在」）。CLI 已在写操作前做目录预校验并给出具体原因，勿以 `list` 不报错推断目录 ID 有效

package/skills-bundle/guands/references/command-reference.md

@@ -0,0 +1,267 @@
+# guands 常用命令参考
+
+## 常用命令
+
+### 连接器（Connector）
+
+```bash
+guands connector list                    # 列出所有连接器
+guands connector get <cn_id>             # 连接器详情
+```
+
+### 连接账号（Account）
+
+```bash
+guands account list                      # 列出所有账号
+guands account list 关键词               # 搜索账号
+guands account get <ac_id>               # 账号配置详情
+guands account schemas <ac_id>           # 列出 Schema
+guands account tables <ac_id>            # 列出表
+guands account tables <ac_id> --schema public  # 指定 Schema 列出表
+guands account columns <ac_id> --table users   # 查看表的列信息（schema 缺省取账号配置的 schema/database）
+guands account columns <ac_id> --table users --schema sales  # 显式指定 Schema
+guands account test <cn_id> --config '{"host":"localhost","port":5432,...}'
+guands account create <cn_id> --config '{"name":"生产库","host":"db.example.com",...}'
+guands account rename <ac_id> --name "新名称"  # 原地改名，保留 acId、凭证、权限和数据集引用
+guands account update <ac_id> --host 10.0.0.8 --password 'secret' --dry-run  # 预览连接配置更新计划
+guands account update <ac_id> --host 10.0.0.8 --password 'secret'            # 原地更新连接配置
+guands account update <ac_id> --config '{"port":"3307","password":"secret"}' # 字段级增量 JSON
+guands account preview <ac_id> --table users  # 预览表数据（默认最多 30 行）
+guands account preview <ac_id> --sql "SELECT * FROM orders LIMIT 10"  # SQL 查询预览
+guands account refresh <ac_id>           # 刷新元数据缓存
+guands account delete <ac_id> --yes      # 删除账号
+```
+
+`account rename` 会先确认账号存在，调用后端名称更新接口后再回读校验；相同名称为 no-op。
+命令不会删除或重建账号，底层不支持、权限不足或回读不一致时直接失败。
+
+`account update` 原地更新连接配置（host/端口/库名/用户/密码/schema），保留 acId、权限和数据集引用：
+
+- 只需提供要修改的字段，其余从线上现状合并；`--config` 是字段级增量 JSON，不是全量覆盖。
+- **密码等敏感字段后端不回读**：字段在当前连接模式下激活且必填时（常规数据库账号的 password 即是），修改配置必须重新提供 `--password`（与 BI 编辑账户行为一致）；密码托管等条件模式下不生效的字段无需提供，显式传入会被拒绝，避免持久化无效值。
+- 所有显式提供的字段必须属于该连接器的表单字段且在当前配置下生效，否则报错（拦截拼写错误和不生效的模式字段）。
+- 默认先做连接测试，失败则不做任何修改；`--skip-test` 可跳过，服务端落库前仍会再认证一次，认证失败账号保持原状。
+- 仅支持基础数据库类连接器（MySQL/PostgreSQL/Oracle/SQL Server/ClickHouse 等标准 host/port 表单）；
+  MongoDB、SAP、FTP、服务器文件、对象存储等特殊连接器不支持，jdbcUrl 含 `${...}` 占位符的账号不支持。
+- 仅账号所有者可执行；改所有者、换连接器类型（cnId）不支持。仅改名用 `account rename`。
+- 先 `--dry-run` 查看合并后的请求计划（敏感字段脱敏显示），确认后再真实执行。
+
+### 数据集（DataSource）
+
+> **注意**：`dataset list` / `dataset get` 返回的行数（rowCount）是后端记录的元数据快照，不会在每次查询时实时计算，refresh 后也不一定立即更新。该值仅供参考，不应作为数据完整性校验的依据。
+>
+> **`dataset list --dir-id <dirId>` 为「子树递归」语义**：返回该目录**及其所有子目录**下的全部数据集，而非仅直属一层。底部「共 N 个数据集」是该范围的命中总数（默认只显示前 50 条，用 `--offset` / `--limit` 翻页）。需要程序化解析时用 `-f json`（输出统一字段的 JSON 数组）。
+
+```bash
+guands dataset list                      # 列出数据集
+guands dataset list 销售                 # 按名称搜索
+guands dataset list --type DIRECT_CONNECT  # 按类型筛选
+guands dataset list --ac-id <acId>       # 按账号筛选
+guands dataset list --dir-id <dirId>     # 按目录筛选（含所有子目录，递归）
+guands dataset get <ds_id>               # 数据集详情（含字段）
+guands dataset fields <ds_id>            # 字段列表（含计算字段和敏感标记）
+guands dataset cards <ds_id>             # 使用该数据集的卡片
+guands dataset refresh <ds_id>           # 触发更新（立即返回，"添加新数据"模式）
+guands dataset refresh <ds_id> --wait   # 触发更新并等待完成
+guands dataset refresh <ds_id> --wait --timeout 600  # 最多等10分钟
+guands dataset refresh <ds_id> --overwrite --wait    # "覆盖旧数据"模式（全量覆盖，忽略增量配置）
+# WebService(API) 数据集（displayType=WEB_SERVICE）暂不支持 refresh/schedule/update-setting/sync-schema/save-as，
+# CLI 读到该类型会直接拒绝且不提交请求，只能在 BI 网页端操作
+guands dataset update-setting <ds_id> --incremental --incremental-sql "SELECT * FROM t WHERE dt >= '{{{today - 7 days}}}'" --preclean --preclean-rule "dt >= '{{{today - 7 days}}}'"  # 配置增量（先删后插）
+guands dataset update-setting <ds_id> --incremental --incremental-sql "SELECT * FROM t WHERE dt >= '{{{yesterday}}}'"  # 配置增量 SQL
+guands dataset primary-key set <ds_id> --columns "id"       # 设置/替换去重主键（异步任务，默认等待并回读验证）
+guands dataset primary-key set <ds_id> --columns "tenant_id,id" --dry-run  # 预览复合主键修改请求
+guands dataset primary-key clear <ds_id>                    # 清空去重主键（异步任务，默认等待并回读验证）
+guands dataset update-setting <ds_id> --incremental=false  # 关闭增量
+guands dataset update-setting <ds_id> --auto-sync-schema on   # 开启"自动更新数据结构"（更新时源端新增列自动带入；缺列结构不变；抽取需配合增量启用，直连直接生效）
+guands dataset sync-schema plan <ds_id>                    # 按源端最新结构生成 schema 同步计划（数据库或 GUAN_FORM；加列/删列/改名/改类型）
+guands dataset sync-schema plan <ds_id> --sql "SELECT ..." # SQL 数据集同时改查询语句
+guands dataset sync-schema apply <ds_id> --plan plan.json --mode schema-only  # 提交同步（仅更新结构，不覆写数据）
+guands dataset sync-schema apply <ds_id> --plan plan.json --mode reset        # 提交同步并重置数据集（全量覆写；直连只能用此模式）
+guands dataset rename <ds_id> --name "新名称"
+guands dataset alias <ds_id> --fd-id <fd_id> --alias "展示名"   # 单字段改展示名
+guands dataset update-fields <ds_id> --alias <fd_id>=用户名 --annotation <fd_id>=注释  # 批量改展示名/注释（可重复；空值=清除）
+guands dataset update-fields <ds_id> --file updates.json   # 批量文件模式: [{"fdId":...,"alias":...,"annotation":...}]，字段中文化推荐
+#   展示名规则（CLI 已做写前预校验）: 不能含保留字符 [ ] ` ( ) { }（全角（）〔〕可用）；
+#   展示名在数据集内必须唯一，且不能与其他字段的原始名相同（后端 2002 duplicateFieldError）
+guands dataset move <ds_id> --dir-id <dir_id>
+guands dataset save-as <ds_id> --name "副本" --dir-id <dir_id>  # --dir-id 缺省=保存到源数据集所在目录
+guands dataset delete <ds_id> --yes
+guands dataset batch-move --ids "ds1,ds2" --dir-id <dir_id>
+guands dataset batch-delete --ids "ds1,ds2" --yes
+guands dataset create-db --ac-id <acId> --tables "t1,t2" --dir-id <dirId>  # 从表名批量创建抽取数据集
+# 表 SQL 一律取自服务端按数据源方言生成的结果（MySQL 反引号 / PG 双引号）；账号表列表拉取失败时整批不创建，
+# 单张表名不在列表中（大小写、schema 前缀不一致）时跳过该表并计入失败，可先用 account tables <acId> 核对或改用 create-query
+guands dataset create-db --ac-id <acId> --tables "t1" --ds-names "用户表" --dir-id <dirId>  # 指定数据集显示名称
+guands dataset create-db --ac-id <acId> --tables "t1" --mode direct --dir-id <dirId>  # 从 DB 创建直连数据集
+guands dataset create-db --ac-id <acId> --tables "t1" --mode direct --realtime=false --dir-id <dirId>  # 直连但禁用实时卡片缓存
+guands dataset create-db --ac-id <acId> --tables "t1" --mode direct --cache-interval 300 --dir-id <dirId>  # 直连，缓存 5 分钟
+guands dataset create-db --ac-id <acId> --tables "orders" --incremental --incremental-sql "SELECT * FROM orders WHERE data_date >= '{{{today - 7 days}}}'" --preclean --preclean-rule "data_date >= '{{{today - 7 days}}}'" --dir-id <dirId>  # 创建时直接配置增量
+guands dataset create-db --ac-id <acId> --tables "users" --incremental --incremental-sql "SELECT * FROM users WHERE update_time >= '{{{yesterday}}}'" --primary-keys "id" --dir-id <dirId>  # 创建时配置主键去重
+guands dataset create-query --ac-id <acId> --name "自定义查询" --sql "SELECT u.id, o.amount FROM users u JOIN orders o ON u.id = o.uid" --dir-id <dirId>  # 从 SQL 创建
+guands dataset create-query --ac-id <acId> --name "直连查询" --sql "SELECT * FROM orders" --mode direct --dir-id <dirId>  # SQL 直连
+guands dataset create-form <fmId> --dir-id <dirId>         # 从填报表单创建填报数据集（fmId 用 guancli form list 查）
+guands dataset create-form <fmId1> <fmId2> --ds-names "表A,表B" --dir-id <dirId>  # 批量，显示名一一对应
+guands dataset import /tmp/data.csv --dir-id <dirId>                        # 从 CSV 创建数据集
+guands dataset import /tmp/report.xlsx --sheet "销售明细" --preview --dir-id <dirId>  # 多 Sheet Excel 必须指定一个 Sheet
+guands dataset import /tmp/report.xlsx --sheet "销售明细" --header-row 3 --dir-id <dirId>  # Excel 表头在第 3 行
+guands dataset import /tmp/data.csv --encoding GB18030 --delimiter ";" --dir-id <dirId>  # 显式指定 CSV 编码/分隔符
+guands dataset import /tmp/large.xlsx --sheet "数据" --timeout 900 --dir-id <dirId>  # 默认等待导入任务完成，大文件可延长超时
+guands dataset replace-data <dsId> /tmp/fixed.csv          # 不带 --yes：只打印执行计划（对象/行数/风险），非零退出
+guands dataset replace-data <dsId> /tmp/fixed.csv --yes    # 用户确认后：替换现有数据集数据（保留 dsId）
+guands dataset replace-data <dsId> /tmp/report.xlsx --sheet "销售明细" --yes  # 多 Sheet Excel 必须指定一个 Sheet
+guands dataset append-data <dsId> /tmp/new_rows.csv --yes  # 追加数据（保留已有数据）
+guands dataset append-data <dsId> /tmp/report.xlsx --sheet "销售明细" --yes  # 多 Sheet Excel 必须指定一个 Sheet
+guands dataset append-data <dsId> /tmp/daily.csv --distinct-by "订单ID" --yes  # 追加并按主键去重
+guands dataset clear-data <dsId> --where "日期 < 2024-01-01" --yes  # 按条件清理数据（危险操作，默认只预览）
+guands dataset clear-data <dsId> --all --yes                       # 清空全部数据（保留结构与 dsId）
+guands dataset permission get <dsId>                               # 查看行列权限（只读，含模板内容）
+```
+
+`sync-schema apply` 的 `--mode` 必填；GUAN_FORM 优先使用 `schema-only`，只有用户明确授权全量覆写时才可用 `reset`。提交后 CLI 严格回读最终物理字段集合、字段类型、数据集状态，并分别校验 matched、remapped、confirmedDrops、added；任一不一致都返回非零。后置验收失败不代表远端一定未生效，禁止直接重试旧 plan，应先执行 `dataset fields <dsId>` 回读，再重新生成 plan。`rowCount` 是延迟快照，不参与该门禁。
+
+`dataset refresh` 会先读取数据集 `status` 和当前任务信息。状态为
+`WAITING/PROCESSING/UPDATING` 时，普通 refresh 返回成功但不重复提交；`--wait`
+改为等待已有任务。`CREATING/CLEARING/CHANGING_KEYS/CHANGE_SCHEMA` 等其他互斥操作
+只会阻止提交并返回明确冲突，不会被当成已有 refresh 成功。`--raw`
+在此 no-op 场景输出带 `submitted:false`、`reason:already_updating` 的本地 JSON，
+用于让脚本区分“已提交”和“已有更新，无需重复提交”。`--overwrite` 不会静默加入
+现有任务，因为无法证明现有任务也是覆盖更新，会明确报冲突并要求稍后重试；已提交的
+覆盖更新如果失败，也不会用另一个普通任务的成功替代。
+
+若本次更新任务 `FAILED/CANCELED`，同一数据集仍可能被另一个任务更新成功；
+`dataset refresh --wait` 会在能证明存在后续更新任务时继续等待或按数据集最新
+`FINISHED` 收敛。CLI 不提供按任务 ID 查询、等待或取消任务的命令：等待一律以
+dsId 为入口（`refresh --wait`、`create-db --wait`），当前状态用 `dataset get <dsId>` 查看。
+
+`dataset import` 每次只接受一个文件并且最多创建一个数据集。Excel 单 Sheet 自动选择；
+多 Sheet 文件必须用 `--sheet <名称>` 指定一个，名称由 BI 上传接口解析并返回，CLI
+不在本地解析 Excel。该命令与普通异步创建命令不同：它默认等待
+`/api/import/batch-import` 触发的导入到终态。任务只有 `FINISHED` 才返回 0；
+`FAILED/CANCELED`、等待超时、同步创建失败或响应缺少任务标识都返回非零。
+命令不会自动删除失败数据集。上传前还会检查 `.csv` 文件内容，若实际是
+XLSX/ZIP/OLE 容器会直接拒绝，避免服务端先创建乱码数据集再异步失败。
+
+`append-data` 对应 BI UI 的「追加数据」：已有数据保留，新数据追加进去；
+`--distinct-by "列a,列b"` 按指定物理列去重（重复时保留新数据，即 upsert 语义），
+适合周期性补数。追加前自动校验文件列名与数据集一致，追加后报告行数增量。
+支持 `--dry-run` 先看执行计划。`append-data` 和 `replace-data` 均不会隐式合并
+Excel Sheet：单 Sheet 自动选择，多 Sheet 必须通过 `--sheet <名称>` 指定一个；
+Sheet 名称在真实执行时由 BI 上传接口解析并校验，CLI 不在本地解析 Excel。
+
+### 清理数据（clear-data，危险操作）
+
+```bash
+guands dataset clear-data <dsId> --where "日期 < 2024-01-01"          # 先预览（默认不执行）
+guands dataset clear-data <dsId> --where "日期 < 2024-01-01" --yes    # 确认清理
+guands dataset clear-data <dsId> --where "区域 in 华东,华南" --where "金额 > 1000" --yes  # 多条件 AND
+guands dataset clear-data <dsId> --all --dry-run                      # 只看全量清空会删掉什么
+guands dataset clear-data <dsId> --all --yes                          # 清空全部数据（结构与 dsId 保留）
+```
+
+对应 BI UI 的「数据清理」，被清理的数据不可恢复。安全设计：
+
+- 必须显式二选一：`--where`（按条件）或 `--all`（清空全部）
+- 默认只调 preview-on-clear 展示待清理数据样本，追加 `--yes` 才真正执行
+- `--where` 格式 `"字段 操作符 值"`，操作符支持 `= != > >= < <= in not-in contains not-contains between is-null not-null`；`in`/`not-in` 值逗号分隔，`between` 是 `"起,止"`，`is-null`/`not-null` 不带值；字段可用名称或别名
+- 仅支持抽取(GUAN_INDEX)/API/文件上传类型数据集；直连不支持；数据集正在刷新时后端拒绝清理
+- 执行后回读行数，报告 `清理前 → 清理后（清理 N 行）`
+
+### 行列权限（permission，只读）
+
+```bash
+guands dataset permission get <dsId>    # 查看行/列权限配置（含关联模板内容）
+```
+
+展示列权限（禁用列/可见列）、行权限（条件规则/自定义表达式 + 默认规则）、
+是否对所有者生效，以及每条规则适用的用户/用户组。
+若数据集关联了行列权限模板（BI「行列权限模板」功能），实际生效的是模板规则，
+命令会自动读取并展示模板名称与模板内的规则内容。
+设置/修改行列权限暂不支持 CLI，请走 BI 网页端（数据集 → 行列权限）。
+
+### 计算字段（Calc Field）
+
+```bash
+guands dataset calc-field add <ds_id> --name "利润率" --formula "[利润]/[销售额]"
+guands dataset calc-field add <ds_id> --name "天数" --formula "datediff([发货日期], [订单日期])" --type INT
+guands dataset calc-field add <ds_id> --name "利润率_聚合" --formula "SUM([利润])/SUM([销售额])" --calc-type aggregation
+guands dataset calc-field update <ds_id> --fd-id <fd_id> --formula "[利润]/[销售额]*100"
+guands dataset calc-field delete <ds_id> --fd-id <fd_id> --yes
+guands dataset calc-field batch-add <ds_id> --file vcs.json      # 批量新建（N 个字段不要循环调 add）
+```
+
+### 定时更新（Schedule）
+
+```bash
+guands dataset schedule <ds_id> --cron-type daily --hour 2 --minute 0    # 每天 02:00
+guands dataset schedule <ds_id> --cron-type hourly --interval 4          # 每 4 小时
+guands dataset schedule <ds_id> --cron-type minute --interval 30         # 每 30 分钟
+guands dataset schedule <ds_id> --cron-type weekly --day-of-week MON --hour 6  # 每周一 06:00
+guands dataset schedule <ds_id> --cron-type monthly --day-of-month 1 --hour 3  # 每月 1 号 03:00
+guands dataset schedule <ds_id> --disable                                # 关闭定时更新
+```
+
+### 等待异步结果
+
+```bash
+guands dataset refresh <dsId> --wait --timeout 600        # 等待本次刷新到终态
+guands dataset create-db --ac-id <acId> --tables "t1,t2" --wait --timeout 900 --dir-id <dirId>  # 等待每张表首次全量抽数
+guands dataset get <dsId>                                  # 查看当前 status / lastExecution
+```
+
+没有独立的任务命令：不支持按任务 ID 查询、等待或取消任务。等待都以 dsId 为入口，
+失败原因由 CLI 在进程内部补取并直接展示。
+
+### 目录（Directory）
+
+```bash
+guands dir tree                          # 查看目录树
+guands dir tree -k ODS --max-depth 3     # 大环境按名称过滤 / 限制深度，避免输出被截断
+guands dir create --name "ODS" --parent <parent_dir_id>   # 父目录先在目录树中预检
+guands dir rename <dir_id> --name "新名称"                # 保留目录 ID 与父目录，回读树校验生效
+guands dir delete <dir_id> --yes                          # 目录必须为空
+```
+
+服务端把目录改名和移动做成了同一个接口且 `parentDirId` 必填，`dir rename` 会先回读
+该目录当前的父目录一并提交，所以改名不会把目录挪到根目录下。
+
+`dir delete` 是**物理删除**，不进回收站、不可恢复。与页面删除（`guanvis page delete`，软删、
+页面进回收站）不同——但页面那边同样没有 CLI 恢复命令，要还原只能人工登录 BI 网页端。
+
+### 表单目录（Form Folder）
+
+表单目录是 SurveyEngine 的目录，与数据集目录（`dir`）无关。目录功能由 BI 环境的
+survey-engine 服务配置决定（`custom.function.access.folder`），可能开启也可能关闭；
+CLI 自动探测：未开启环境所有表单在根目录（folderId=0），folder 写命令与 `form move`
+会在发请求前直接拒绝并提示开启方法。
+
+```bash
+guands form folder status                # 探测目录功能是否开启（-f json 输出 {"folderEnabled": bool}）
+guands form folder tree                  # 查看表单目录树（两种环境都可用；未开启时为单层）
+guands form folder create --name "巡检" --parent 0    # 创建目录（--parent 缺省为根目录 0）
+guands form folder rename <folderId> --name "新名称"  # 重命名（回读树校验生效）
+guands form folder move <folderId> --to <targetId>    # 移动目录（禁止移入自身子树；--to 0 为根目录）
+guands form folder delete <folderId> --yes            # 删除空目录
+guands form move <fmId1> <fmId2> --to <folderId>      # 移动表单到目录，逐个报告成败
+```
+
+## 输出格式
+
+- `--raw`：原样输出当前子命令调用的后端 API JSON；不同 endpoint 的 `response` 结构不同，**不承诺全 CLI 统一 schema**
+- `-f json`：将已转换为表格的查询结果输出为 JSON 数组；目前主要适用于 `list` / `fields` 等表格型命令，**不是 create/import/update 等写命令的统一机器接口**。例外(有固定字段的结果对象):
+  - `dataset get <dsId> -f json` → `{dsId, name, displayType, rowCount, colCount, acId, status, description, parentDirId, ctime, utime, fields:[{fdId, name, alias, fdType, metaType, calculationType, formula, source}]}`,`source` 为 `physical`/`calculated`/`group`。当前身份无该数据集读取权限(服务端返回 `hasPermission:false` 的受限对象,不含字段和行列数)、详情为空或缺 `name`/`displayType`/`columns` 时退出码非 0、stdout 不输出,不会给出空的 `fields`;
+  - `dataset import … -f json` → `{dsIds:[…], dirId, datasets:[{name, dsId, taskId, status, error}]}`,`dsIds` 与文本输出末行 `dsIds:` 相同;`status` 为 `FINISHED`/`FAILED`/`CANCELED`/`TIMEOUT`/`CREATE_FAILED`/`UNCONFIRMED`,任一项不是 `FINISHED` 时退出码非 0(对象照常输出)。进度、提示与 `-v` 的轮询诊断都走 stderr
+- `-f csv`：CSV 格式输出
+- `-f expanded`：PostgreSQL 风格竖向展开
+- 默认：对齐表格格式，适合 AI 消费
+
+自动化脚本使用 `--raw` 时必须按子命令解析，并在继续调用前断言 ID 非空。常用路径：
+
+| 命令 | ID 路径 |
+|---|---|
+| `dataset list --raw` | `.response.contents[].dsId` |
+| `dataset fields <dsId> --raw` | `.response.columns[].fdId` 和 `.response.virtualColumns[].fdId` |
+| `dataset create-db/create-query/import --raw` | `.response[].response.dsId` |
+| `dataset import --raw` 的任务 ID | `.response[].response.taskId` |
+
+`dataset list` 的普通查询、`--name`、`--dir-id` 都使用同一搜索 endpoint，当前 `--raw` 均为 `response.contents[]`。

package/skills-bundle/guands/references/incremental-and-schedule.md

@@ -0,0 +1,157 @@
+# guands 增量更新与定时调度
+
+## ODS 批量抽取工作流（先全量再补增量）
+
+按清单逐表创建抽取数据集，先全量抽取，再配置增量条件。
+
+```bash
+# 1. 确认账号和表
+guands account list
+guands account tables <ac_id>
+
+# 2. 创建抽取数据集（全量，不启用增量）
+#    BI 会在建集成功后自动触发首次全量抽数，无需手动 refresh
+guands dataset create-db --ac-id <ac_id> --tables "orders" --ds-names "订单表" --dir-id <dir_id>
+
+# 3. 等待自动触发的全量抽数完成（不要立即 refresh，会报 5001 任务冲突）
+#    轮询 dataset get 直到状态为 FINISHED；数据量大时适当拉长等待间隔
+guands dataset get <ds_id>
+
+# 3b. 如确需再次全量更新（如自动抽数失败后重跑），等状态不再是 UPDATING/WAITING 后执行
+guands dataset refresh <ds_id> --wait
+
+# 4. 配置增量更新（先删后插方式，7天回溯，使用时间宏 {{{ expression }}}）
+guands dataset update-setting <ds_id> \
+  --incremental \
+  --incremental-sql "SELECT * FROM orders WHERE data_date >= '{{{today - 7 days}}}'" \
+  --preclean \
+  --preclean-rule "data_date >= '{{{today - 7 days}}}'"
+
+# 5. 或者配置增量更新 + 主键去重方式
+#    增量设置和主键修改是两套独立协议，分别执行
+guands dataset update-setting <ds_id> \
+  --incremental \
+  --incremental-sql "SELECT * FROM orders WHERE update_time >= '{{{yesterday}}}'"
+guands dataset primary-key set <ds_id> --columns "id"
+
+# 6. 验证增量配置
+guands dataset get <ds_id>
+```
+
+**例外情况：数据量太大跳过全量，直接增量补完**
+
+```bash
+# 创建时直接启用增量
+guands dataset create-db --ac-id <ac_id> --tables "big_table" --dir-id <dirId> \
+  --incremental \
+  --incremental-sql "SELECT * FROM big_table WHERE data_date >= '{{{today - 30 days}}}'" \
+  --preclean \
+  --preclean-rule "data_date >= '{{{today - 30 days}}}'"
+
+# 触发增量更新并等待
+guands dataset refresh <ds_id> --wait
+```
+
+## 配置定时更新
+
+完成增量配置后，设定定时调度让数据集自动更新：
+
+```bash
+# 每天凌晨 2 点自动增量更新
+guands dataset schedule <ds_id> --cron-type daily --hour 2 --minute 0
+
+# 每 4 小时更新一次
+guands dataset schedule <ds_id> --cron-type hourly --interval 4
+
+# 每 30 分钟更新一次
+guands dataset schedule <ds_id> --cron-type minute --interval 30
+
+# 每周一凌晨 6 点
+guands dataset schedule <ds_id> --cron-type weekly --day-of-week MON --hour 6
+
+# 每月 1 号凌晨 3 点
+guands dataset schedule <ds_id> --cron-type monthly --day-of-month 1 --hour 3
+
+# 关闭定时更新
+guands dataset schedule <ds_id> --disable
+```
+
+**调度类型说明**：
+
+| cron-type | 参数 | 说明 | 示例 |
+|---|---|---|---|
+| `daily` | `--hour`, `--minute` | 每天指定时间执行 | `--hour 2 --minute 30` → 每天 02:30 |
+| `hourly` | `--interval`, `--minute` | 每隔 N 小时执行 | `--interval 4` → 每 4 小时 |
+| `minute` | `--interval` | 每隔 N 分钟执行（最小 5） | `--interval 15` → 每 15 分钟 |
+| `weekly` | `--day-of-week`, `--hour`, `--minute` | 每周指定日期时间 | `--day-of-week MON --hour 6` → 每周一 06:00 |
+| `monthly` | `--day-of-month`, `--hour`, `--minute` | 每月指定日期时间 | `--day-of-month 1 --hour 3` → 每月 1 号 03:00 |
+
+- `--day-of-week` 取值：`MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, `SUN`（支持逗号分隔多个，如 `MON,WED,FRI`）
+- `--day-of-month` 取值：`1`-`31` 或 `L`（最后一天），支持逗号分隔多个
+- 默认不开启定时，必须显式调用 `schedule` 命令才会打开
+- `schedule` 会先读取数据集当前配置再整体提交 `data-setting`：抽取数据集透传现有增量配置；直连数据集透传现有 `realTimeUpdateSetting` 与 `directConnectUpdateSetting`（服务端对直连缺这两项会报错或清空配置）。WebService(API) 数据集直接拒绝
+
+**调度频率限制**：最高 5 分钟一次，低于 1 小时会输出性能警告。建议 ODS 增量至少每小时更新。
+
+## 增量方式选择指南
+
+| 增量方式 | 适用场景 | 配置参数 |
+|---|---|---|
+| 先删后插 | 有明确时间分区字段，按时间范围覆盖 | `--preclean --preclean-rule "..."` |
+| 主键去重 | 有唯一主键，新数据覆盖旧数据 | `dataset primary-key set <dsId> --columns "id"` |
+| 全量 | 数据量小或无增量条件 | 不启用 `--incremental` |
+
+## 增量语义限制（重要，配置前必读）
+
+增量更新有两个 BI 服务端固有的语义限制，配置和核数时必须考虑：
+
+1. **主键去重要求主键列非空且唯一**。主键列含 null 时去重行为未定义：建集和 refresh 时可能把多个 null-key 行折叠成一行（静默丢行），也可能产生重复，且全程不会报错。执行 `dataset primary-key set` 前先确认源表该列无 null（脏数据需先清洗或换主键列）。主键修改会触发异步数据重写，CLI 默认等待任务完成并回读验证；清空主键使用 `dataset primary-key clear`。
+2. **时间窗口增量没有 DELETE 语义**。增量 SQL 按 `updated_at >= {{{时间宏}}}` 只能拉到新增/更新的行，源表物理删除的行会在 BI 数据集中永久残留。源表会删行（退单/撤销/物理删除）的场景，需要：
+   - 周期性全量更新兜底（`dataset refresh --overwrite` 或定时全量），或
+   - 用 preClean 先删后插并保证删除发生在 preClean 覆盖的时间窗口内。
+
+另外注意：数据集的 **schema 在建集时冻结**，默认 refresh 不同步源端结构变化：
+- 源表 `ADD COLUMN` 后 refresh 不会带入新列（refresh 仍报成功）
+- 源表 `DROP COLUMN` 后 refresh 仍报成功，但该列值会全部变 null（静默清空）
+
+两种处理方式（无需重建数据集）：
+- **日常加列场景**：`dataset update-setting <dsId> --auto-sync-schema on` 开启"自动更新数据结构"，之后每次更新检测到源端新增列会自动加入（缺列时结构保持不变，不能处理删列/改名）。抽取数据集该开关挂在增量配置下，需增量启用才生效；直连数据集直接生效
+- **删列/改名/改类型或一次性结构对齐**：用 `dataset sync-schema` 走完整"更新模型结构"流程（见下方工作流），改名字段保留 fdId、下游卡片引用不断
+
+## 时间宏使用说明
+
+增量 SQL 和 preClean 规则中**必须使用 BI 时间宏**（而非 `CURDATE()`、`CURRENT_DATE` 等数据库函数），
+这样 BI 在执行更新时会自动替换为当前日期值。
+
+**时间宏语法**：`{{{ expression }}}`（三花括号包裹表达式）
+
+```
+# 正确 ✓ — 使用 BI 时间宏（三花括号）
+SELECT * FROM orders WHERE data_date >= '{{{today - 7 days}}}'
+SELECT * FROM orders WHERE update_time >= '{{{yesterday}}}'
+SELECT * FROM orders WHERE create_date >= '{{{first day of this month}}}'
+
+# 错误 ✗ — 使用数据库函数（不会被 BI 识别和管理）
+SELECT * FROM orders WHERE data_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
+```
+
+**常用时间宏表达式**：
+
+| 表达式 | 含义 | 示例结果（假设今天 2026-03-31） |
+|---|---|---|
+| `{{{today}}}` | 今天 | 2026-03-31 |
+| `{{{yesterday}}}` | 昨天 | 2026-03-30 |
+| `{{{today - 1 days}}}` | 昨天（等同 yesterday） | 2026-03-30 |
+| `{{{today - 7 days}}}` | 7 天前 | 2026-03-24 |
+| `{{{today - 30 days}}}` | 30 天前 | 2026-03-01 |
+| `{{{first day of this month}}}` | 本月第一天 | 2026-03-01 |
+| `{{{first day of last month}}}` | 上月第一天 | 2026-02-01 |
+| `{{{last day of last month}}}` | 上月最后一天 | 2026-02-28 |
+| `{{{today - 1 months}}}` | 一个月前 | 2026-02-28 |
+| `{{{monday}}}` | 本周一 | 2026-03-30 |
+
+**注意**：时间宏与动态参数是两套不同的机制：
+- **时间宏** `{{{ expr }}}` — 由 `time_macro` 库在 SQL 执行前自动解析替换，无需预先定义
+- **动态参数** `[DYNAMIC_PARAMS.name]` — 需要在 BI 中预先创建参数实体，适用于用户交互式筛选
+
+增量 SQL 场景应使用**时间宏**。