@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guands/references/workflows.md

@@ -0,0 +1,256 @@
+# guands 典型工作流
+
+## 创建新数据库连接
+
+```bash
+# 1. 查看可用连接器
+guands connector list
+
+# 2. 查看连接器配置模板
+guands connector get <cn_id>
+
+# 3. 测试连接
+guands account test <cn_id> --config '{"host":"db.example.com","port":5432,"database":"analytics","username":"reader","password":"xxx"}'
+
+# 4. 创建账号
+guands account create <cn_id> --config '{"name":"分析库","host":"db.example.com","port":5432,"database":"analytics","username":"reader","password":"xxx"}'
+
+# 5. 浏览表结构
+guands account schemas <ac_id>
+guands account tables <ac_id> --schema public
+guands account columns <ac_id> --table orders
+```
+
+## 重命名数据库连接账号
+
+```bash
+guands account rename <ac_id> --name "新的显示名称"
+```
+
+该操作原地更新账户名称并保留 acId、凭证、权限和已有数据集引用。命令会在更新前后回读账号；
+如果后端不支持原地更新或回读未生效，会直接报错。禁止用删除后重建替代账户改名。
+
+## 批量整理数据集
+
+```bash
+# 1. 查看目录树
+guands dir tree
+
+# 2. 创建新目录
+guands dir create --name "归档" --parent <root_dir_id>
+
+# 3. 搜索要移动的数据集
+guands dataset list 旧版
+
+# 4. 批量移动
+guands dataset batch-move --ids "ds1,ds2,ds3" --dir-id <archive_dir_id>
+```
+
+## 从数据库创建数据集
+
+```bash
+# 1. 查看账号列表
+guands account list
+
+# 2. 预览表数据确认
+guands account preview <ac_id> --table orders
+
+# 3. 创建抽取数据集（默认模式，priority=MEDIUM）
+#    注意：创建成功后 BI 服务端会自动触发首次全量抽数（状态 UPDATING/WAITING），
+#    无需也不要立即手动 refresh（会报 5001「当前数据集有任务正在执行中」）
+guands dataset create-db --ac-id <ac_id> --tables "orders,customers" --dir-id <dirId>
+
+# 4. 创建直连数据集（默认启用实时卡片缓存，interval=600s）
+guands dataset create-db --ac-id <ac_id> --tables "orders" --mode direct --dir-id <dirId>
+
+# 5. 直连数据集，禁用实时卡片缓存
+guands dataset create-db --ac-id <ac_id> --tables "orders" --mode direct --realtime=false --dir-id <dirId>
+
+# 6. 直连数据集，自定义缓存间隔（秒）
+guands dataset create-db --ac-id <ac_id> --tables "orders" --mode direct --cache-interval 300 --dir-id <dirId>
+
+# 7. 通过自定义 SQL 创建数据集（支持 JOIN、子查询、类型转换等）
+guands dataset create-query --ac-id <ac_id> --name "用户订单汇总" --sql "SELECT u.id, u.name, SUM(o.amount) AS total FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.id, u.name" --dir-id <dirId>
+
+# 8. SQL 直连数据集
+guands dataset create-query --ac-id <ac_id> --name "实时订单" --sql "SELECT * FROM orders WHERE status = 'active'" --mode direct --dir-id <dirId>
+```
+
+## 从 CSV/Excel 导入数据集
+
+```bash
+# 1. 预览文件结构
+guands dataset import /tmp/sales.csv --preview --dir-id <dirId>
+
+# 2. 直接导入
+guands dataset import /tmp/sales.csv --dir-id <dirId>
+
+# 3. 导入 Excel（单 Sheet 自动选择；多 Sheet 必须指定一个名称）
+guands dataset import /tmp/report.xlsx --sheet "销售明细" --dir-id <dirId>
+
+# 4. Excel 表头不在第 1 行（如前几行是标题说明）
+guands dataset import /tmp/report.xlsx --sheet "销售明细" --header-row 3 --dir-id <dirId>
+
+# 5. CSV 自动探测不准时显式指定编码/分隔符
+guands dataset import /tmp/data.csv --encoding GB18030 --delimiter ";" --dir-id <dirId>
+
+# 6. 逐列指定类型，覆盖服务端推断（前若干行为空的数值列常被推断成 STRING）
+guands dataset import /tmp/world.csv --dir-id <dirId> \
+  --col-type "Ease of Business=DOUBLE" --col-type "Year=INT"
+
+# 7. 大文件默认等待导入完成，可延长等待超时
+guands dataset import /tmp/large.xlsx --sheet "数据" --timeout 900 --dir-id <dirId>
+
+# 8. 慢网络上传大文件在上传阶段报超时（HTTP 上传默认 120 秒）时，用 GUANCLI_UPLOAD_TIMEOUT（整数秒）调大
+GUANCLI_UPLOAD_TIMEOUT=600 guands dataset import /tmp/large.csv --dir-id <dirId>
+```
+
+**import 格式约束**（解析行为由 BI 服务端决定）：
+
+- 表头默认取第 1 行。**Excel** 可用 `--header-row N`（1-based）指定表头所在行；**CSV 服务端只认第 1 行为表头**，表头前有标题/空行时必须先预处理文件（删掉表头前的行）或转换为 xlsx 再导入
+- CSV 编码（UTF-8/GB18030 等，含 UTF-8 BOM 自动处理）和分隔符（逗号/分号等）默认自动探测；探测不准时用 `--encoding` / `--delimiter`（取值 COMMA/TAB/SEMICOLON/PIPE/SPACE 或单个字符）显式指定，`--encoding`/`--delimiter` 仅对 CSV 有效
+- 列类型默认按内容推断。**前若干行为空的数值列可能被推断成 STRING**（后续 `AVG()`/`SUM()` 会返回空）；用 `--col-type "列名=类型"`（可重复）显式覆盖，类型取值 `INT/LONG/SHORT/FLOAT/DOUBLE/STRING/DATE/TIMESTAMP/BOOL`。列名拼错会被忽略并提示可用列名
+- 导入前会自动做解析校验：若解析结果只有 1 列且表头疑似含分隔符（典型的"真表头+数据挤进一列"症状），会拒绝导入并提示调整参数；不确定时先 `--preview` 检查字段结构
+- 上传前会识别文件实际内容；扩展名为 `.csv`、实际为 XLSX/ZIP/OLE 容器时直接拒绝，请恢复正确的 Excel 扩展名后重试
+- `dataset import` 每次只接受一个文件并且最多创建一个数据集；批量导入请由调用方逐个执行命令
+- Excel 的 Sheet 名称由 BI 上传接口解析；单 Sheet 自动选择，多 Sheet 必须用 `--sheet <名称>` 精确指定一个。CLI 不引入本地 Excel 解析依赖
+- 真实导入默认等待本次创建触发的导入任务到终态；只有 `FINISHED` 才返回 0，`FAILED/CANCELED`、等待超时、同步创建失败或缺少 taskId 均返回非零。失败数据集不会被自动删除
+- import 时不支持直接配置去重主键，需建集后用 `dataset primary-key set <dsId> --columns "id"` 补充；清空使用 `dataset primary-key clear <dsId>`
+
+## 替换现有 CSV/Excel 数据集数据
+
+用新文件替换现有数据集的底层数据，保留 dsId 不变，下游卡片/页面引用不断开。
+仅支持 CSV/Excel 类型数据集。
+
+**重要**：替换前会自动校验 CSV header 与目标数据集 schema 是否一致（列数+列名），
+不一致时拒绝执行。建议首次替换或不确定时先用 `--dry-run` 预览计划。
+
+```bash
+# 先用 dry-run 查看替换计划（不执行）
+guands dataset replace-data <dsId> /tmp/fixed.csv --dry-run   # 或不带 --yes 直接跑：都只打印计划
+
+# 确认后实际替换
+guands dataset replace-data <dsId> /tmp/fixed.csv --yes
+
+# 用新的 Excel 文件替换；多 Sheet 必须指定一个名称
+guands dataset replace-data <dsId> /tmp/updated.xlsx --sheet "销售明细" --yes
+```
+
+追加 Excel 数据同样遵循单 Sheet 规则：
+
+```bash
+guands dataset append-data <dsId> /tmp/daily.xlsx --sheet "当日数据" --yes
+```
+
+`append-data` / `replace-data` 的 Excel Sheet 名称由 BI 上传接口解析。单 Sheet 自动选择；
+多 Sheet 未传 `--sheet` 时命令会停止并列出候选名称，不会把所有 Sheet 隐式合并后写入目标数据集。
+
+**新文件与数据集列结构不一致时**（物理列增减/改名）：replace-data 不改结构，schema 预校验会直接拒绝执行（避免整列 null）。文件数据集的结构变更暂无保 dsId 的 CLI 方案（`sync-schema` 支持数据库类和 GUAN_FORM 数据集，不支持文件数据集），需重新 `dataset import` 建集或在 BI 网页端处理。
+
+## 源端结构变更后同步 schema（AI 字段映射工作流）
+
+源端加列/删列/改名/改类型后，用 `sync-schema` 把数据集结构对齐到源端最新结构，
+对应 BI 网页端"更新模型结构"流程。改名字段通过映射保留 fdId，下游卡片引用不断。
+支持数据库类数据集（抽取/直连）和填报数据集（GUAN_FORM）；直连数据集 apply 只能用 `--mode reset`。
+GUAN_FORM 从数据集 `config.tableId` 定位关联 Form，通过 `/api/thirdparty/data/preview` 获取当前字段，
+再复用 `compare-field → do-change`；它不调用数据库 account preview，也不支持 `--sql`。
+
+**⚠ 严禁用"删除数据集再重建"替代以下任何修改**（重建后 dsId/fdId 全变，
+下游卡片、ETL、权限、调度、血缘引用全部断裂，且原数据不可恢复）：
+
+- 修改数据集的模型 SQL → `sync-schema plan <dsId> --sql "新 SQL"` 原地改（保 dsId/fdId）
+- 修改物理字段名 → SQL 数据集在 `--sql` 中用 `AS 新名` + plan.json 填 newFdName 映射；表抽取数据集源表列改名后直接 `sync-schema plan` 映射
+- 修改字段展示名 → `dataset alias` / `dataset update-fields`（与结构无关，直接原地改）
+- 增删列/改类型 → 本节 sync-schema 流程
+
+```bash
+# 1. 生成同步计划（预览源端最新结构 + 服务端按 name/alias 自动关联）
+guands dataset sync-schema plan <dsId>
+# SQL 数据集要同时改查询语句时：
+guands dataset sync-schema plan <dsId> --sql "SELECT id, cust_name AS customer_name, amount FROM orders"
+
+# 2. 检查计划文件（sync-schema-plan-<dsId>.json），处理 unmappedOrig 中每个字段：
+#    - 判断是"改名"还是"删除"：对比 unmappedOrig（源端消失的旧字段）与 addedNew（源端新增列），
+#      名称语义相近且类型兼容的（如 cust_nm → customer_name、拼音↔中文、加前缀）大概率是改名
+#    - 改名 → 填 newFdName 为 addedNew 中的对应列名
+#    - 确认删除 → 置 confirmDrop: true
+#    ⚠ AI 判断规则：高置信（类型一致 + 名称明显对应）可直接填映射；
+#      低置信或删除大量字段时必须先与用户确认，不要擅自 confirmDrop
+
+# 3. dry-run 核对最终请求体（assoc 映射 + onlySynchronizeSchema）
+guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only --dry-run
+
+# 4. 提交（--mode 必选，对应网页端"请确认更新方式"弹窗）
+#    schema-only: 仅更新数据结构，不触发覆写数据（未关联字段数据将被删除）
+#    reset:       重置数据集，触发全量覆写并更新结构（直连只能用这个）
+guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only
+
+# 5. 验收：改名字段 fdId 不变，新列出现，删除列消失
+guands dataset fields <dsId>
+```
+
+**安全闸门**（apply 自动校验，不满足直接报错）：
+
+- unmappedOrig 中每个字段必须已填 `newFdName` 或显式 `confirmDrop: true`
+- 主键字段不允许删除；主键列会按映射后的新列名自动透传（keyColumns）
+- 字段保留比例低于 `--min-match-ratio`（默认 0.5）拒绝执行——变化过大通常是配错了源表/SQL，确认无误可 `--force`
+- 提交前会重新预览源端结构并核对数据集当前字段，计划过期（期间源端又变了/别人改过 schema）会拒绝并要求重新 plan
+- 提交后严格回读最终物理字段集合、字段类型和数据集可用状态；matched/remapped 必须保留原 fdId、confirmedDrops 必须消失、added 必须出现。任一不一致或 GET/解析失败都返回非零
+
+**注意**：
+- 改名映射后 BI 会把旧字段名保留为展示名（alias），物理名变为新列名——与网页端行为一致，下游按展示名引用不受影响
+- `--mode reset` 会触发全量覆写，大表耗时较长，用 `--timeout` 调整等待时间
+- 后置验收失败时远端变更可能已经生效；先执行 `dataset fields` 回读并重新生成 plan，禁止直接重试旧 plan
+- `rowCount` 是延迟元数据快照，不作为数据完整性证明；真实数据可用性从数据集预览、卡片或 ETL 等下游入口验证
+- 文件上传（CSV/Excel）数据集不走 sync-schema，结构变化直接用 `dataset import` 重导或见 replace-data 一节
+
+## GUAN_FORM 模型漂移闭环
+
+Form 与 GUAN_FORM Dataset 是两个独立资源。Form 新增、删除或改名字段后，普通 `dataset refresh` 只刷新已有模型中的数据，**不会**自动演进 Dataset 模型结构。必须使用下面的原地同步流程；严禁删除并重建数据集，否则 dsId、fdId、下游引用、权限、调度和历史状态都会丢失。
+
+```bash
+# 1. 分别回读 Form 与 Dataset，确认 fmId/dsId、当前字段和关联关系
+guands form get <fmId>
+guands dataset get <dsId>
+guands dataset fields <dsId>
+
+# 2. 生成模型漂移计划；GUAN_FORM 从 config.tableId 读取 Form 最新字段
+guands dataset sync-schema plan <dsId> --out sync-schema-plan-<dsId>.json
+
+# 3. 检查 matched / unmappedOrig / addedNew
+#    改名：为对应 unmappedOrig 填 newFdName，保留原 fdId
+#    删除：必须显式填 confirmDrop: true
+
+# 4. 先预演。GUAN_FORM 默认优先 schema-only；未经用户明确授权不得 reset
+guands dataset sync-schema apply <dsId> \
+  --plan sync-schema-plan-<dsId>.json \
+  --mode schema-only \
+  --dry-run
+
+# 5. 正式提交；只有严格后置验收全部通过才返回 0
+guands dataset sync-schema apply <dsId> \
+  --plan sync-schema-plan-<dsId>.json \
+  --mode schema-only
+
+# 6. 独立回读字段定义
+guands dataset fields <dsId>
+
+# 7. 从真实下游入口查询新增字段；空数据或 rowCount=0 不等于结构失败
+guancli ds preview <dsId> --columns "<新增字段1>,<新增字段2>" --limit 20
+```
+
+成功输出包含 `matched`、`remapped`、`confirmedDrops`、`added` 和最终 `status`。如果命令提示“schema 变更已提交，但后置验收失败”，远端可能已部分或全部生效：先执行 `dataset fields` 和真实下游查询确认现状，再重新生成 plan；不要循环重试原计划。
+
+## create-db vs create-query 选择指南
+
+| 场景 | 命令 | 说明 |
+|---|---|---|
+| 按表名批量创建 | `create-db --tables "t1,t2,t3"` | 一次创建多张表对应的数据集 |
+| 需要自定义数据集名称 | `create-db --tables "t1" --ds-names "用户表"` | 表名和数据集名不同时 |
+| 多表 JOIN / 子查询 | `create-query --sql "SELECT ..."` | 单条 SQL 创建单个数据集 |
+| 类型转换 / 计算列 | `create-query --sql "SELECT a::int, ..."` | SQL 中包含类型转换或表达式 |
+| 带 WHERE 条件 | `create-query --sql "SELECT * FROM t WHERE ..."` | 只需要部分数据 |
+
+两个命令都支持 `--mode extract/direct`、`--dir-id`、`--realtime`、`--cache-interval`。
+抽取模式下还支持 `--incremental`、`--incremental-sql`、`--preclean`、`--preclean-rule`；
+`create-db` 建集时额外支持 `--primary-keys`。建集后修改主键统一使用 `dataset primary-key set/clear`。