@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/_recipes/dashboard/gates/page_check.js

@@ -0,0 +1,16 @@
+var DSID = "{{.DsID}}";
+var d = JSON.parse(readFile(argv[0]));
+var r = run("guancli", ["page", "get", d.pgId, "--brief"]);
+if (r.code !== 0) throw new Error("page get 失败: " + r.stderr.slice(0, 300));
+var out = r.stdout;
+var cards = out.match(/# Card \d+:/g) || [];
+if (cards.length < {{.MinCards}}) throw new Error("页面卡片数 " + cards.length + " < {{.MinCards}}");
+var types = {}; var m; var re = /\*\*Type:\*\* ([A-Z_]+)/g;
+while ((m = re.exec(out)) !== null) { types[m[1]] = true; }
+var tc = Object.keys(types).length;
+if (tc < {{.MinTypes}}) throw new Error("图表类型只有 " + Object.keys(types).join(",") + " 共 " + tc + " 种 (<{{.MinTypes}})");
+var idm = out.match(/\*\*ID:\*\* ([0-9a-z]+)/);
+if (!idm) throw new Error("未解析到卡片 ID");
+var c = run("guancli", ["card", "get", idm[1], "--brief"]);
+if (c.code !== 0 || c.stdout.indexOf(DSID) < 0) throw new Error("首卡未绑定数据集 " + DSID);
+console.log("PAGE-OK cards=" + cards.length + " types=" + tc);

package/skills-bundle/_recipes/dashboard/gates/report_check.js

@@ -0,0 +1,4 @@
+var d = JSON.parse(readFile(argv[0]));
+if (!d.pgId || !/^[a-z][0-9a-z]{18,30}$/.test(d.pgId)) throw new Error("pgId 缺失或格式错: " + d.pgId);
+if (!(d.cards >= {{.MinCards}})) throw new Error("cards 需 >={{.MinCards}}, 实际: " + d.cards);
+console.log("REPORT-OK " + d.pgId + " cards=" + d.cards);

package/skills-bundle/_recipes/dashboard/knowledge/01.md

@@ -0,0 +1 @@
+guanvis 工作流：guanvis init {{.DsID}} -d /dash 生成 schema.js → write_file 写 /dash/card_01_*.js…、/dash/selector_01_*.js（可选）、/dash/page.js → guanvis genid 8 生成 setId 用的 ID（每个 card/selector/page 都要 .setId(独立ID)）→ guanvis preview /dash 校验 → guanvis publish /dash 发布

package/skills-bundle/_recipes/dashboard/knowledge/02.md

@@ -0,0 +1 @@
+强烈建议先 cat /skills/guanvis/evals/sales_dashboard/ 下的示例（card_*.js/selector_01_region.js/page.js 都很短），照它的模式写：字段引用 f("字段名")，聚合 f("字段",{aggrType:AggrType.SUM})，注册 registerCard(card.build())；selector 用 createSelector("名").setId(id).bindField(f("维度")).setMultiSelect(true).linkToAll()；page 布局 placeCard(cardIndex,x,y,w,h)（12 列栅格，selector 不占 card index）

package/skills-bundle/_recipes/dashboard/knowledge/03.md

@@ -0,0 +1 @@
+guanvis 的 JS DSL 不是 Node/ESM：禁止 import/export/require/new Card()/card.build('x') 这类写法（会直接 SyntaxError）；只用 var + 工厂函数链式调用，如 var card = createCard(ChartType.KPI_CARD, "标题")...（第一个参数是 ChartType，第二个是标题）；每张卡一个文件 card_01_*.js…，不要合并成 cards.js；所有 .setId() 的值必须用 guanvis genid 生成的 24 位 ID

package/skills-bundle/_recipes/dashboard/knowledge/04.md

@@ -0,0 +1 @@
+卡片 zone API 只有三个：.addRow(f("维度")) 放维度/X轴、.addMetric(f("度量",{aggrType:AggrType.SUM})) 放度量、.addColumn(f("维度")) 只用于分组着色；折线/柱状/饼图的维度一律 addRow，DATA_GRID 明细也是 addRow(维度)+addMetric(度量)；每张卡都必须 .bindDataset(DS)。没有 addDimension/addXAxis 这类方法

package/skills-bundle/_recipes/dashboard/knowledge/05.md

@@ -0,0 +1 @@
+不要逐个 cat 检查已有文件（任务卡已给出工作区文件列表与内容）；按『guanvis init（如缺 schema.js）→写全部 JS 文件→guanvis preview /dash→按报错修正→guanvis publish /dash→写 /report/dashboard.json』直接推进

package/skills-bundle/_recipes/dashboard/knowledge/06.md

@@ -0,0 +1 @@
+preview/publish 报错时按报错提示修改对应 JS 文件重试；publish 成功后 pgId 就是 page.js 里 .setId() 的值，卡片数就是 registerCard 的数量

package/skills-bundle/_recipes/dashboard/template.json

@@ -0,0 +1,41 @@
+{
+  "_comment": "dashboard 配方。逻辑仍在 internal/helm/planner.go:这里只有文本与阈值。占位符是 text/template 具名字段:DsName/DsID/DsIDShort/Title/EtlRootDir/MinCards/MinTypes。",
+  "id": "PLAN-{{.DsIDShort}}",
+  "default_title": "{{.DsName}} 分析看板",
+  "min_cards": 4,
+  "min_types": 3,
+  "goal": "用 guanvis 在 BI 上创建并发布一个基于数据集 {{.DsName}}（dsId: {{.DsID}}）的仪表板（页面标题含『{{.Title}}』），发布成功后把结果写入 /report/dashboard.json，内容为 {\"pgId\":\"<page.js 里 setId 的页面ID>\",\"cards\":<卡片数量>}。数据与结构必须真实创建，禁止杜撰。",
+  "ideas_prefix": "\n建议的卡片构成：",
+  "acceptance": [
+    "页面已发布到 BI：至少 {{.MinCards}} 张卡片、至少 {{.MinTypes}} 种不同图表类型",
+    "卡片绑定数据集 {{.DsID}}",
+    "/report/dashboard.json 记录真实 pgId 与卡片数"
+  ],
+  "constraints": [
+    "工程目录用 /dash；页面标题必须含『{{.Title}}』",
+    "不要修改或删除 BI 上任何已有资源；只新建本任务的页面",
+    "不要使用 guanvis screenshot（本任务用数据回读验收）"
+  ],
+  "budgets": {
+    "max_iterations": 5,
+    "max_turns": 24,
+    "max_tool_calls": 32,
+    "max_no_progress": 3
+  },
+  "gates": [
+    {
+      "name": "report-json",
+      "script": "report_check.js",
+      "args": "/report/dashboard.json",
+      "expect_regex": "REPORT-OK"
+    },
+    {
+      "name": "page-live",
+      "script": "page_check.js",
+      "args": "/report/dashboard.json",
+      "expect_regex": "PAGE-OK",
+      "timeout_ms": 90000,
+      "depends_on": "report-json"
+    }
+  ]
+}

package/skills-bundle/_recipes/etl/gates/etl_live_check.js

@@ -0,0 +1,10 @@
+var DSID = "{{.DsID}}";
+var d = JSON.parse(readFile(argv[0]));
+var r = run("guancli", ["etl", "get", d.etlId, "--brief"]);
+if (r.code !== 0) throw new Error("etl get 失败: " + r.stderr.slice(0, 300));
+var out = r.stdout;
+if (out.indexOf(DSID) < 0) throw new Error("ETL 未引用输入数据集 " + DSID);
+if (out.indexOf("OUTPUT_DATASET") < 0) throw new Error("ETL 无输出节点");
+var m = out.match(/总节点数:\*\* (\d+)/);
+if (!m || parseInt(m[1]) < 3) throw new Error("节点数不足 3（需 输入+加工+输出），实际: " + (m ? m[1] : "未解析到"));
+console.log("ETL-OK nodes=" + m[1]);

package/skills-bundle/_recipes/etl/gates/etl_report_check.js

@@ -0,0 +1,3 @@
+var d = JSON.parse(readFile(argv[0]));
+if (!d.etlId || !/^[a-z][0-9a-z]{18,30}$/.test(d.etlId)) throw new Error("etlId 缺失或格式错: " + d.etlId);
+console.log("REPORT-OK " + d.etlId);

package/skills-bundle/_recipes/etl/knowledge/01.md

@@ -0,0 +1 @@
+guanetl 工作流：guanetl create --name "<ETL名>" --dir /etlwork --parent-dir {{.EtlRootDir}}（--parent-dir 必须带上，否则 save 报『ETL路径无效』；命令输出的 dataFlowId 就是 etlId，立刻记下）→ 编写 /etlwork/etl/etl.go → guanetl export --dir /etlwork → guanetl preview <输出节点id> --dir /etlwork --require-nonempty → guanetl save --dir /etlwork → 把 {"etlId":"<dataFlowId>"} 写入 /report/etl.json。忘了 etlId 可 cat /etlwork/_guanetl_state.json 找 dataFlowId

package/skills-bundle/_recipes/etl/knowledge/02.md

@@ -0,0 +1,9 @@
+etl.go 完整骨架（照此模式写，包导入与 DefineETL 签名不得改动）：
+package main
+import . "guanetl/internal/framework"
+func DefineETL() []Node {
+  in := BasicInputDataset("id_1001", "输入", "{{.DsID}}", []Field{BasicField("Region", "STRING"), BasicField("GDP", "DOUBLE")}, Position{X: 100, Y: 100})
+  agg := BasicGroupBy("id_1002", "按区域聚合", in, []GroupByColumn{BasicGroupByColumn("Region", "STRING")}, []AggregationColumn{BasicAggregationColumnWithAlias("GDP", "DOUBLE", "SUM", "GDP合计")}, Position{X: 340, Y: 100})
+  out := BasicOutputDataset("id_1003", "输出", agg, "<输出数据集名>", Position{X: 580, Y: 100})
+  return []Node{out}
+}

package/skills-bundle/_recipes/etl/knowledge/03.md

@@ -0,0 +1 @@
+硬约束：节点 ID 必须 id_数字 且唯一；BasicInputDataset 的 []Field 只声明本 ETL 用到的字段、类型必须与字段清单一致（STRING 不得声明成数值）；聚合类型仅 SUM/COUNT/COUNT_DISTINCT/AVG/MIN/MAX；行筛选用 BasicFilterRows、等值 JOIN 用 BasicJoinData，不要写 SQL；export 不通过就不要 preview/save

package/skills-bundle/_recipes/etl/knowledge/04.md

@@ -0,0 +1 @@
+顺序固定 export→preview→save，按报错修 /etlwork/etl/ 下文件后从失败步骤重跑；preview 用输出节点 id（如 guanetl preview id_1003 --dir /etlwork --require-nonempty）；首次 save 出现 [save.first_save_fallback] 提示是正常路径不是错误

package/skills-bundle/_recipes/etl/knowledge/05.md

@@ -0,0 +1 @@
+完整 API 参考在 /skills/guanetl/references/ETL_AI_DEVELOP.md（较大，仅在骨架之外的节点用法拿不准时 cat 对应小节）

package/skills-bundle/_recipes/etl/template.json

@@ -0,0 +1,39 @@
+{
+  "_comment": "etl 配方。逻辑仍在 internal/helm/planner.go:这里只有文本与阈值。",
+  "id": "PLAN-ETL-{{.DsIDShort}}",
+  "default_title": "{{.DsName}} 加工",
+  "goal": "用 guanetl 基于数据集 {{.DsName}}（dsId: {{.DsID}}）新建一个 ETL（名称含『{{.Title}}』）：从该输入数据集经至少一个加工节点（聚合/筛选/计算列等）产出一个输出数据集定义，完成 export → preview → save 闭环；保存成功后把 {\"etlId\":\"<dataFlowId>\"} 写入 /report/etl.json。禁止杜撰；本任务只建结构并保存，不要 run、不要配置调度。",
+  "ideas_prefix": "\n建议的加工思路：",
+  "acceptance": [
+    "ETL 已保存到 BI（guancli etl get 可查），引用输入数据集 {{.DsID}}",
+    "至少 3 个节点：输入 + ≥1 个加工节点 + 输出",
+    "/report/etl.json 记录真实 etlId"
+  ],
+  "constraints": [
+    "工作目录用 /etlwork；只编辑 /etlwork/etl/ 下文件，不要手改 _exported.json/_base_etl.json 等系统文件",
+    "不要修改或删除 BI 上任何已有资源；不要 run、不要 schedule（本任务只建结构）",
+    "ETL 名称必须含『{{.Title}}』"
+  ],
+  "budgets": {
+    "max_iterations": 5,
+    "max_turns": 24,
+    "max_tool_calls": 32,
+    "max_no_progress": 3
+  },
+  "gates": [
+    {
+      "name": "report-json",
+      "script": "etl_report_check.js",
+      "args": "/report/etl.json",
+      "expect_regex": "REPORT-OK"
+    },
+    {
+      "name": "etl-live",
+      "script": "etl_live_check.js",
+      "args": "/report/etl.json",
+      "expect_regex": "ETL-OK",
+      "timeout_ms": 90000,
+      "depends_on": "report-json"
+    }
+  ]
+}

package/skills-bundle/_recipes/hints.json

@@ -0,0 +1,46 @@
+[
+  {
+    "needle": "not a builder .build() result",
+    "hint": "registerCard/registerSelector/registerPage 必须传 .build() 的结果（如 registerCard(card.build())）；这个报错来自加载的每个 JS 文件，不一定在你最近改的文件——逐个检查所有 card_*.js/selector_*.js 的 register 行"
+  },
+  {
+    "needle": "require is not defined",
+    "hint": "本引擎无 require/import：删除模块语法，直接顶层 var + 工厂函数（createCard/createSelector/createPage）"
+  },
+  {
+    "needle": "Unexpected reserved word",
+    "hint": "不支持 import/export 等 ESM 语法：改为 var 声明 + 工厂函数链式调用"
+  },
+  {
+    "needle": "has no member",
+    "hint": "方法名不存在：卡片 zone 只有 addRow/addColumn/addMetric/addSort；页面布局用 placeCard/addRow/addFullWidthCard/addHalfWidthCards，selector 不用 place"
+  },
+  {
+    "needle": "references card index",
+    "hint": "placeCard 的数字索引按 registerCard 注册顺序从 0 起算，registerSelector 不占索引；越界说明把 selector 也数进去了"
+  },
+  {
+    "needle": "invalid x position",
+    "hint": "页面是 12 列栅格：每个 placeCard 的 x+w 不得超过 12"
+  },
+  {
+    "needle": "overflows grid",
+    "hint": "页面是 12 列栅格：每个 placeCard 的 x+w 不得超过 12"
+  },
+  {
+    "needle": "No such file or directory",
+    "hint": "路径不存在：检查绝对路径拼写；工作区文件清单见上方「工作区现状」"
+  },
+  {
+    "needle": "参数缺失",
+    "hint": "工具调用必须带全必填参数（edit_block 需要 path/old_string/new_string），不要重复发送残缺调用"
+  },
+  {
+    "needle": "ETL路径无效",
+    "hint": "guanetl create 必须带 --parent-dir <ETL目录id>（guancli etl tree --max-depth 1 查根目录 id），重新 create 后重走 export→preview→save"
+  },
+  {
+    "needle": "missing properties",
+    "hint": "工具调用必须带全必填参数（edit_block 需要 path/old_string/new_string），不要重复发送残缺调用"
+  }
+]

package/skills-bundle/guancli/.commandface.json

@@ -0,0 +1,155 @@
+{
+  "identity": "guancli",
+  "commands": [
+    {
+      "path": "auth",
+      "short": "认证自检（只读）"
+    },
+    {
+      "path": "auth status",
+      "short": "查看认证配置与服务端探测结果"
+    },
+    {
+      "path": "auth whoami",
+      "short": "查看当前 BI 登录用户信息"
+    },
+    {
+      "path": "card",
+      "short": "卡片操作",
+      "kitProxy": true
+    },
+    {
+      "path": "commandface",
+      "short": "输出实际生效的命令面（机器可读 JSON，供构建链路生成文档）",
+      "hidden": true
+    },
+    {
+      "path": "ds",
+      "short": "数据集相关操作"
+    },
+    {
+      "path": "ds execute-sql",
+      "short": "执行 SQL 查询数据集"
+    },
+    {
+      "path": "ds get",
+      "short": "获取数据集详情"
+    },
+    {
+      "path": "ds preview",
+      "short": "预览数据集数据"
+    },
+    {
+      "path": "ds search",
+      "short": "搜索数据集"
+    },
+    {
+      "path": "ds tree",
+      "short": "获取数据集目录树"
+    },
+    {
+      "path": "etl",
+      "short": "ETL 相关操作"
+    },
+    {
+      "path": "etl get",
+      "short": "获取ETL详情"
+    },
+    {
+      "path": "etl preview",
+      "short": "预览 ETL 节点数据"
+    },
+    {
+      "path": "etl search",
+      "short": "搜索ETL"
+    },
+    {
+      "path": "etl tree",
+      "short": "获取ETL目录树"
+    },
+    {
+      "path": "fetch",
+      "short": "通用 BI API 调用",
+      "hidden": true
+    },
+    {
+      "path": "form",
+      "short": "表单填报操作 (CRUD)"
+    },
+    {
+      "path": "form add",
+      "short": "插入数据"
+    },
+    {
+      "path": "form delete",
+      "short": "删除数据"
+    },
+    {
+      "path": "form list",
+      "short": "列出/搜索表单 (--tree 显示目录结构)"
+    },
+    {
+      "path": "form query",
+      "short": "查询表单数据"
+    },
+    {
+      "path": "form schema",
+      "short": "查看表单字段结构"
+    },
+    {
+      "path": "form update",
+      "short": "更新数据"
+    },
+    {
+      "path": "gateway",
+      "short": "请求转发路由创建与调用",
+      "kitProxy": true
+    },
+    {
+      "path": "metric",
+      "short": "指标相关操作",
+      "kitProxy": true
+    },
+    {
+      "path": "metric_attribution",
+      "short": "指标树归因相关操作",
+      "kitProxy": true
+    },
+    {
+      "path": "page",
+      "short": "页面相关操作"
+    },
+    {
+      "path": "page get",
+      "short": "获取页面详情"
+    },
+    {
+      "path": "page search",
+      "short": "搜索页面"
+    },
+    {
+      "path": "page tree",
+      "short": "获取页面目录树"
+    },
+    {
+      "path": "server-version",
+      "short": "查看当前 BI 版本",
+      "kitProxy": true
+    },
+    {
+      "path": "task",
+      "short": "任务排查相关操作",
+      "kitProxy": true
+    },
+    {
+      "path": "version",
+      "short": "打印版本信息"
+    },
+    {
+      "path": "workflow",
+      "short": "工作流/数据流相关操作（高级应用）",
+      "hidden": true,
+      "kitProxy": true
+    }
+  ]
+}