@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanwf/references/WORKFLOW_NODES.md

@@ -0,0 +1,166 @@
+# 工作流数据流扩展节点参考
+
+本文档描述工作流数据流中相对于 BI ETL 的超集节点类型。
+通用 ETL 节点（INPUT_DATASET、OUTPUT_DATASET、SQL_SCRIPT 等）的用法参见 `ETL_AI_DEVELOP.md`（symlink 到 guanetl）。
+
+## 透传节点（LoadNodeFromFile 模式）
+
+以下节点在 `guanwf edit` 导入时自动保存为 `node_XXXX.json` 独立文件，`etl.go` 中通过 `LoadNodeFromFile` 引用。
+这些节点配置复杂且与数据库连接紧密绑定，通常不需要手动修改。
+
+### INPUT_DATASOURCE（数据源输入）
+
+数据库直连输入，无上游 source。从关系型数据库中读取数据到数据流。
+
+```go
+// 透传模式（edit 路径推荐）
+node_1001 := LoadNodeFromFile("node_1001.json")
+
+// 结构化模式（create 路径）
+node_1001 := BasicInputDatasource("id_1001", "数据库输入", InputDatasourceConfig{
+    BaseConfig: BaseConfig{Position: Position{X: 100, Y: 100}},
+    AcId:       "ac_xxx",
+    CnId:       "cn_yyy",
+    Sql:        ReadSQLFile("input_query.sql"),
+    SourceType: "DIRECT_CONNECT",
+})
+```
+
+配置说明：
+- `AcId`: 数据账号 ID（通过 `guands account list` 获取）
+- `CnId`: 数据连接 ID（通过 `guands account get <acId>` 获取）
+- `Sql`: 查询 SQL（支持 ReadSQLFile 引用独立文件）
+- `SourceType`: `DIRECT_CONNECT`（数据库直连）或 `DATASET`（引用数据集）
+
+### OUTPUT_DATASOURCE（数据源输出）
+
+数据回写到数据库，有上游 source。
+
+```go
+// 透传模式（edit 路径推荐）
+node_1005 := LoadNodeFromFile("node_1005.json", node_1004)
+
+// 结构化模式（create 路径）
+node_1005 := BasicOutputDatasource("id_1005", "数据回写", node_1004, OutputDatasourceConfig{
+    BaseConfig:  BaseConfig{Position: Position{X: 500, Y: 100}},
+    AcId:        "ac_xxx",
+    CnId:        "cn_yyy",
+    TargetTable: "target_table",
+    UpdateMode:  UpdateModeOVERWRITE,
+})
+```
+
+配置说明：
+- `TargetTable`: 目标表名
+- `UpdateMode`: `UpdateModeOVERWRITE`（覆盖）、`UpdateModeAPPEND`（追加）、`UpdateModeUPSERT`（更新插入）；字面量 `"OVERWRITE"` 等仍可用，`guanetl lint` 会提示改用常量
+- `Schema`: 目标 schema（可选）
+- `PrimaryKeys`: UPSERT 模式的主键列
+- `PreSql`/`PostSql`: 写入前/后执行的 SQL（可选）
+
+### INCREMENT_OUTPUT_DATASET（增量输出数据集）
+
+增量方式写入观远数据集（与 OUTPUT_DATASET 的区别是支持增量更新策略）。
+
+```go
+// 透传模式
+node_1006 := LoadNodeFromFile("node_1006.json", node_1005)
+```
+
+配置说明：
+- `OutputDsId`: 输出数据集 ID（序列化为服务端的 `dsId` 键；绑定已有数据集时填写）
+- `ParentDirID`: 输出数据集目录（DATA_SET 目录树 id，新建输出必填，缺失会导致运行期报错）
+- `UpdateMode`: `UpdateModeAPPEND`（追加）或 `UpdateModeUPSERT`（更新插入）
+- `PrimaryKeys`: UPSERT 模式的主键列
+
+推荐优先使用透传模式（LoadNodeFromFile），可保留服务端节点的全部配置。
+
+## 原生 DSL 节点
+
+以下节点有结构化的 Go DSL 函数，import 后会生成可直接编辑的代码。
+
+### TRIM_COLUMNS（去空格）
+
+对指定列去除首尾空格。
+
+```go
+node := BasicTrimColumns("id_1002", "去空格", source, []string{"name", "address"}, Position{X: 300, Y: 100})
+```
+
+参数：
+- `columnNames`: 要处理的列名列表（对应 BI 端 `columnNames` 字段）
+
+### COMBINE_COLUMNS（合并列）
+
+将多个列合并为一个新列。
+
+```go
+node := BasicCombineColumns("id_1005", "合并地址", source, "full_address", []string{"city", "street"}, ", ", false, Position{X: 600, Y: 100})
+```
+
+参数：
+- `targetFieldName`: 新列名
+- `fields`: 要合并的源列名列表
+- `separator`: 分隔符
+- `removeSelectedFields`: 是否删除源列
+
+## 透传 DSL 节点（复杂 mappings 类）
+
+以下节点因配置结构复杂（含嵌套数组/对象），import 时使用 `LoadNodeFromFile` 透传模式保存完整 JSON，确保往返保真。
+
+### VALUE_MAPPER（值映射/值替换）
+
+将指定列的值按映射表替换。
+
+```go
+// import 自动生成（透传模式）
+node_1003 := LoadNodeFromFile("node_id_1003.json", source)
+```
+
+配置说明（编辑 `node_*.json` 文件）：
+- `column`: 源列名
+- `targetField`: 目标列名（可与源列相同）
+- `mappings`: 映射规则数组
+- `defaultValue`: 不匹配时的默认值
+
+### SINGLE_VALUE_MAPPER（Null 值替换）
+
+将指定列的 null 值替换为固定值。import 时使用 LoadNodeFromFile 透传模式。
+
+```go
+// import 自动生成（透传模式）
+node_1004 := LoadNodeFromFile("node_id_1004.json", source)
+```
+
+配置说明（编辑 `node_*.json` 文件中的 `mappings` 数组）：
+- `mappings`: 列值映射列表，每条包含：
+  - `colName`: 目标列名
+  - `origValue`: 原始值（`null` 表示匹配 null）
+  - `toValue`: 替换值
+
+## SQL Fallback 节点
+
+以下节点类型不做原生支持，import 时由 guanetl-server 生成等价 SQL 转为 `BasicSqlScript`：
+
+| 节点类型 | 说明 |
+|---|---|
+| `COLLAPSE_COLUMNS` | 列转行 |
+| `UNCOLLAPSE_COLUMNS` | 行转列 |
+| `BENCHMARKING` | 智能对标 |
+| `FREQ_PATTERN` | 关联性挖掘 |
+| `DATA_INSIGHT` | 智能归因 |
+
+## 不支持的节点类型
+
+以下节点类型在当前版本中不支持 import，遇到时会报错：
+
+| 节点类型 | 说明 |
+|---|---|
+| `SAP_ERP_INPUT` | SAP ERP 输入 |
+| `FTP_INPUT` | FTP 输入 |
+
+## LoadNodeFromFile 使用规则
+
+1. **透传与结构化可互换**：用户可以把 `LoadNodeFromFile(...)` 替换为 `BasicInputDatasource(...)`（或反过来），框架不限制。
+2. **修改透传节点**：直接编辑对应的 `node_XXXX.json` 文件即可。
+3. **JSON 文件命名**：`node_` + 节点 ID（sanitize 后保留字母/数字/下划线/连字符）+ `.json`。
+4. **sources 自动处理**：export 时 `LoadedNode.ToMap()` 会根据函数参数中的 sources 自动更新 `sources` 字段。

package/skills-bundle/js/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: js
+description: 在观远 BI 工作站内用 JavaScript 写多步数据加工、聚合分析与批量 BI 调用脚本。适用：带逻辑/循环/分组聚合的加工、批量调用 BI API（run("guancli", ["fetch", …]) 或 fetch --batch）、脚本中间穿插 shell 工具（run("date"/"jq"/"wc"/"rg"/"sed"/…)）、JSONL 中间结果逐行处理、生成报告文件。跨技能路由：单步 JSON 变换直接用 jq 更省；创建/修改 BI 资源（ETL/卡片/数据集/指标/工作流）不要在 js 里做，回 shell 层用对应 CLI（先读 guanetl/guanvis/guands/guanmetric/guanwf 技能）；只查单个资源详情直接用 guancli，不必套 js。
+---
+
+# js — 工作站 JavaScript 脚本引擎
+
+goja 引擎，ES2020 级语法。定位：把"多次取数 → 加工 → 聚合 → 落盘/汇报"压缩成一条命令完成，中间数据不占对话上下文。
+
+## 方言与限制（先读，避开 Node 惯性）
+
+- 语法：async/await、可选链 `?.`、`??`、解构、模板字符串、BigInt 均可用。
+- **无 ESM/require**：不要写 `import`/`export`/`require()`，单文件顶层代码直接写。
+- **无 fetch/XMLHttpRequest**：BI 访问唯一通道是 `run("guancli", ["fetch", ...])`（`run()` 也能调 shell 工具，但**只有 guancli 能出网**）。
+- **无 setTimeout/setInterval**：轮询用同步 `sleep(ms)`。所有内置 API 都是同步的，不返回 Promise（写 async 语法也能跑，但没有必要）。
+- 脚本抛出未捕获异常（含 async 体内的未处理拒绝）→ 退出码 1，错误与 JS 栈打到 stderr。
+- `js -e '{"a":1}'` 会把 `{...}` 解析为语句块（标准 JS 坑）：对象字面量表达式请加括号 `({a:1})`。
+
+## 执行形态
+
+```bash
+js /work/task.js arg1 arg2     # 脚本 + 参数（脚本内经 argv 读取）
+js -e '1+1'                    # 单行表达式；结果非 undefined 时自动打印
+cat rows.jsonl | js -e 'readStdin().trim().split("\n").length'
+```
+
+**标准姿势：超过 3 行的脚本一律先 write_file 落盘再执行**（脚本成为工作区持久工件，失败后用 edit_block 小步修改重跑，不要整段重发）；`-e` 只写单行；stdin 保留给数据管道（脚本内容不从 stdin 读）。
+
+### -e 引号规则（实测，只记一条：外层单引号）
+
+- **`-e` 的表达式一律用单引号包裹，JS 内部字符串用双引号或反引号**。单引号内一切字面传递：`"文本"`、正则 `\d+`、`||`、`${}` 模板串、JSON 字面量、甚至换行都安全。
+- 表达式里需要单引号字符 → 不要玩 `'\''` 逃逸，直接让 JS 用双引号/反引号字符串。
+- **不要裸写**：`js -e console.log(0||5)` 的 `||`/`|`/`>` 会被 shell 当算子切走（实测报"命令不存在: 5)"）。
+- **不要用双引号包表达式**：本 shell 在双引号内会把 `\n`/`\t`/`\\` 转成真实控制字符（与 bash 不同），JS 字符串转义 `"a\nb"` 会断行成 SyntaxError；除非双写 `\\n`，但这条规则太易错，直接用单引号回避。
+
+## 内置 API（全部同步）
+
+| API | 说明 |
+|---|---|
+| `console.log/info(...)` | 打印到 stdout（对象自动 JSON 序列化，空格分隔） |
+| `console.error/warn(...)` | 打印到 stderr |
+| `argv` | 脚本参数数组（不含脚本路径） |
+| `env` | 环境变量对象（如 `env.GUANCLI_BASE_URL`） |
+| `readFile(path)` | 读文件全文为字符串（路径一律 `/` 开头的绝对路径） |
+| `writeFile(path, s)` / `appendFile(path, s)` | 写/追加文件（自动创建父目录） |
+| `listDir(path)` | 目录项数组 `[{name, dir, size}, ...]` |
+| `readStdin()` | 读入全部 stdin（管道数据入口；重复调用返回同一份） |
+| `forEachLine(path, (line, i) => {...})` | 流式逐行处理；回调显式 `return false` 提前终止；返回已处理行数 |
+| `sleep(ms)` | 同步休眠（轮询任务状态用） |
+| `run(cmd, args, {stdin})` | 调用 shell 工具或只读 BI CLI，返回 `{code, stdout, stderr}`（见下节） |
+
+## 调用外部命令：run()
+
+`run()` 能调两类东西：**只读 BI 查询链**与**整条 shell 工具链**。
+
+```javascript
+// ① BI 只读查询
+const r = run("guancli", ["fetch", "GET", "/api/user/profile"]);
+if (r.code !== 0) throw new Error(r.stderr);
+const profile = JSON.parse(r.stdout);
+
+// ② shell 工具：算一半、取个值、接着算
+const now = run("date", ["+%Y-%m-%d"]).stdout.trim();
+const n = parseInt(run("wc", ["-l", "/data.csv"]).stdout, 10);
+const ids = run("jq", ["-r", ".[].id", "/list.json"]).stdout.trim().split("\n");
+```
+
+- **可调**：`guancli`、`guancli-kit`，以及全部 coreutils 子命令（`date`/`wc`/`sort`/`cut`/`head`/`tail`/`test`/`printf`/…）与独立工具 `jq`/`rg`/`sed`/`find`。写的是**命令名**，不是资产名——`run("coreutils", …)` 会被拒；`run("grep", …)` 也会被拒（`run()` 不做 grep→rg 翻译，直接写 `run("rg", …)`）。
+- `run("rg", [pattern], {stdin})` 已自动补 `-`（WASI 下 rg 不认 stdin，不补会去搜整个工作区）；显式给了文件参数时不补。
+- **不可调，且是刻意设计,不要尝试绕过**：`guanetl`/`guanvis`/`guands`/`guanmetric`/`guanwf` 这些写操作 CLI（报"模块 js 不允许调用 …"），以及 js 自身。原因：写操作必须走各自技能的工作流约束（编辑红线、export→preview→save、dry-run），且每个写操作应是 shell 层一条可见命令，不能藏进脚本循环里批量执行。正确分工：**js 负责计算和产出参数/文件，写操作回 shell 层用对应 CLI 消费它们**。
+- **批量仍然交给 shell**：`run()` 每次都要现起一个 wasm 实例，循环里调 100 次就是 100 次实例化。整列数据的过滤/排序/统计写成一条 shell 管道快得多；`run()` 用在"零星取一两个值"的场合。
+- 命令自身失败经 `code`/`stderr` 表达；宿主协议层失败（白名单拒绝、响应超 8MB 等）抛异常，可 try/catch。
+- BI 凭证由宿主自动注入，脚本内**不要**处理任何 token。
+- 单次响应上限 8MB：大结果让 fetch 落文件（batch 协议的 `output` 字段，或 `fetch ... --output /work/big.json`），再 readFile/forEachLine 处理。
+
+### 批量调用（一次 run 跑 N 个请求）
+
+`fetch --batch` 走 JSONL 协议：请求逐行写入 stdin，结果逐行返回（严格串行、复用连接，对 BI 后端友好）。
+
+```javascript
+const ids = ["ds1", "ds2", "ds3"];
+const reqs = ids.map((id, i) =>
+  JSON.stringify({ id: String(i), method: "GET", path: `/api/dataset/${id}` })
+).join("\n");
+const out = run("guancli", ["fetch", "--batch"], { stdin: reqs });
+const results = out.stdout.trim().split("\n").map(JSON.parse); // {id, ok, body|error}
+```
+
+## 大文件处理（重要）
+
+中间结果约定用 **JSONL**（一行一个 JSON 对象），配合 `forEachLine` 逐行加工——**不要**对大文件整体 `JSON.parse`（实例内存有限，大对象树会 OOM）：
+
+```javascript
+let total = 0, byRegion = {};
+forEachLine("/work/rows.jsonl", (line) => {
+  const row = JSON.parse(line);
+  total += row.amount;
+  byRegion[row.region] = (byRegion[row.region] || 0) + row.amount;
+});
+writeFile("/work/summary.json", JSON.stringify({ total, byRegion }, null, 2));
+console.log("done:", total);
+```
+
+## 完整示例：批量审计数据集字段
+
+```javascript
+// /work/audit.js —— 用法: js /work/audit.js <目录ID>
+const dirId = argv[0];
+if (!dirId) throw new Error("用法: js /work/audit.js <目录ID>");
+
+const list = run("guancli", ["fetch", "GET", `/api/directories/${dirId}/data-sources`]);
+if (list.code !== 0) throw new Error(list.stderr);
+const datasets = JSON.parse(list.stdout).result || [];
+
+const reqs = datasets.map((ds, i) =>
+  JSON.stringify({ id: ds.dsId, method: "GET", path: `/api/datasets/${ds.dsId}` })
+).join("\n");
+const out = run("guancli", ["fetch", "--batch"], { stdin: reqs });
+
+const report = out.stdout.trim().split("\n").map(JSON.parse).map((r) => {
+  if (!r.ok) return { dsId: r.id, error: r.error };
+  const d = JSON.parse(r.body).result;
+  return { dsId: r.id, name: d.name, cols: (d.schema || []).length };
+}).sort((a, b) => (b.cols || 0) - (a.cols || 0));
+
+writeFile("/work/audit_report.json", JSON.stringify(report, null, 2));
+console.log(`审计完成 ${report.length} 个数据集，字段最多:`, report[0]);
+```
+
+## 坑与替代
+
+| 惯性写法 | 替代 |
+|---|---|
+| `import x from "y"` / `require("y")` | 删掉，单文件顶层直接写 |
+| `fetch(url)` / axios | `run("guancli", ["fetch", "GET", path])` |
+| `run("guanetl"/"guanvis"/…)` 写操作 | 宿主白名单拒绝；js 只产出参数/文件，写操作回 shell 层执行 |
+| `run("grep", …)` | 宿主白名单拒绝（不翻译）；直接 `run("rg", …)` |
+| 用 `run()` 循环处理整列数据 | 每次调用都是一次 wasm 实例化；整列加工写成 shell 管道，`run()` 只取零星值 |
+| `run("coreutils", ["date"])` | 直接 `run("date", [...])`——白名单的键是命令名不是资产名 |
+| `setTimeout(fn, ms)` | `sleep(ms)` 后直接调用 |
+| `process.argv` / `process.env` | `argv` / `env` |
+| `fs.readFileSync` | `readFile(path)` |
+| 金额精确聚合用 float | 下推 SQL（guancli ds execute-sql / card preview）或 BigInt |
+| 排序大数据集 | 下推 SQL ORDER BY；文本行管道用 shell `sort`；小数据 `arr.sort()` |
+| 单步 JSON 变换套 js | 直接 `... \| jq '...'` 更省 |