@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guancli/references/gateway.md

@@ -0,0 +1,148 @@
+# 请求转发创建与调用辅助
+
+用于把第三方或客户内部接口文档转换为观远 BI 请求转发配置，并通过 `guancli gateway create` 创建。产品语义以[请求转发 / API Gateway](https://docs.guandata.com/product/bi/api-gateway)为准。
+
+## 从接口文档生成配置
+
+先提取并向用户展示配置草案，至少标明每项来自文档的哪一段：
+
+- 目标方法、URL、超时时间。
+- Header、Query、Body 入参及必填性。
+- 鉴权方式；需要登录或换 token 时转成前置请求。
+- 前置响应 JSONPath 与主请求 `${PRE_REQ.xxx}` 引用。
+- 网关入口方法、路由识别符、登录要求、用户/用户组、调用方 Host 和日志脱敏 Header。
+- 文档地址与调用说明 `usageMarkdown`。
+
+不确定的权限范围、Host 白名单、Secret key 和启用状态必须列为待确认项。不要猜用户 ID、用户组 ID 或把凭据明文放入 JSON。用户确认后再生成配置文件。
+
+## JSON 契约
+
+```json
+{
+  "basicInfo": {
+    "name": "CRM 查询用户",
+    "routes": "crm-query-user",
+    "gatewayMethod": "GET",
+    "targetMethod": "GET",
+    "documentUrl": "https://docs.example.com/crm/users",
+    "usageMarkdown": "Query: keyword；返回 CRM 用户列表。",
+    "enabled": true,
+    "loginRequired": true,
+    "allowedUsers": [{"id": "user-id"}],
+    "allowedUserGroups": [{"id": "group-id"}],
+    "targetUrl": "https://crm.example.com/api/users",
+    "allowedCallerHosts": ["app.example.com"],
+    "maskHeaders": ["Authorization", "Cookie", "X-Auth-Token"]
+  },
+  "config": {
+    "request": {
+      "timeoutSeconds": 120,
+      "headers": [
+        {
+          "paramName": "Authorization",
+          "paramValueOrExpr": "Bearer ${PRE_REQ.accessToken}",
+          "paramDescription": "前置登录返回的 token"
+        }
+      ],
+      "query": [
+        {
+          "paramName": "keyword",
+          "paramValueOrExpr": "${REQUEST.query.keyword}",
+          "paramDescription": "搜索关键词"
+        }
+      ]
+    },
+    "preRequestList": [
+      {
+        "name": "获取 CRM Token",
+        "requestMethod": "POST",
+        "url": "https://crm.example.com/oauth/token",
+        "timeoutSeconds": 30,
+        "documentUrl": "https://docs.example.com/crm/auth",
+        "headers": [{"paramName": "Content-Type", "paramValueOrExpr": "application/json"}],
+        "query": [],
+        "body": "{\"clientId\":\"${SECRET.crm_client_id}\",\"clientSecret\":\"${SECRET.crm_client_secret}\"}",
+        "responseExtractors": [{"name": "accessToken", "jsonPath": "$.accessToken"}]
+      }
+    ]
+  }
+}
+```
+
+规则：
+
+- `routes` 只能包含字母、数字和中划线；创建后不要修改识别符。
+- `gatewayMethod` 只支持 `GET`、`POST`；`targetMethod` 支持 `GET`、`POST`、`PUT`、`DELETE`、`PATCH`。
+- 主请求及前置请求超时为 1–300 秒。
+- `allowedUsers`、`allowedUserGroups` 传资源 ID，不传名称代替 ID。登录开启但两者为空时，所有已登录用户可访问。
+- Header 和 Query 只有显式配置的参数才转发；Body 由调用方整体透传并执行占位符替换。
+- Header 和 Query 配置通过 `required: true|false` 保留原接口的必填性；省略时按可选处理。`gateway get` 只对必填入参生成缺失检查，可选 Query/Header 未传时不会被序列化为 `undefined`。
+- CLI 会在输出 dry-run 计划前检查 Header、Query、前置请求 Body、目标/前置请求 URL 的 query 与 userinfo。`Authorization`、`token`、`password`、`AK/SK`、`API Key`、`client secret` 等敏感参数只能由 `${SECRET.xxx}` 或 `${PRE_REQ.xxx}` 服务端引用组成；明文及 `${REQUEST.xxx}` 会被拒绝，且不会回显配置。自定义 Header 固定值默认拒绝；只有确认为公开非凭据值时才在该参数上显式设置 `allowPlaintext: true`，例如 `X-API-Version: 2026-09`、`X-Client-Type: superapp`、`Prefer: return=representation`。敏感 Header 名或 Bearer/Basic/API-key/JWT 等凭据形式不允许用 `allowPlaintext` 绕过。`allowPlaintext` 只是 CLI 本地确认字段，dry-run 的 `request` 和真实 POST body 都会在提交投影中剔除它，两者保持一致。
+- JSON Body 任意层级出现重复字段时会在 dry-run 和真实创建前直接拒绝，避免校验器只检查最后一个值、却把未规范化的原始 Body 提交给 BI。
+- `enabled`、`loginRequired` 省略时服务端默认 `true`，配置草案中仍应显式写出，便于用户确认。
+
+常用占位符：`${REQUEST.path.n}`、`${REQUEST.query.xxx}`、`${REQUEST.header.xxx}`、`${REQUEST.body.xxx}`、`${CURRENT_USER.xxx}`、`${PRE_REQ.xxx}`、`${SECRET.xxx}`、`${SYSTEM.xxx}`。
+
+## 创建流程
+
+```bash
+guancli auth status
+guancli gateway create ./gateway.json --dry-run
+guancli gateway create ./gateway.json
+```
+
+先检查 dry-run 输出中的目标地址、权限、Secret key、参数映射和 `enabled`。真实创建是外部写操作；只有用户确认草案后才执行。dry-run 计划和创建结果均使用 `schemaVersion: "1.0"`；创建成功返回 `id`、`name`、`routeCode`、`gatewayPath` 和 `enabled`。
+
+服务端仍会最终校验权限、商业授权、路由重名、用户/用户组、Secret 与配置合法性。创建端点为 `POST /api/gateway/manage/routes`，权限资源为 `GATEWAY_ROUTE.UPDATE`；自 2026-09-01 起还需要超级应用商业授权。
+
+## 查找路由并读取调用契约
+
+当用户只给出自然语言需求（例如“调用 CRM 查询客户信息接口”），不要要求用户预先提供识别符，也不要从创建文件或历史对话猜测：
+
+```bash
+guancli gateway search CRM --enabled --limit 20
+guancli gateway get 42
+```
+
+- `search [keyword]` 调用 `POST /api/gateway/manage/routes/query`，关键词由服务端匹配名称或识别符；支持 `--enabled=true|false`、`--offset`、`--limit`。输出为 `schemaVersion: "1.0"` 的脱敏摘要，包含路由 ID、名称、识别符、BI 网关路径、方法、启用状态、访问约束、文档地址和业务说明。
+- 查询结果只代表当前分页。`total` 大于 `items` 数量时仍有后续页；无候选时缩短关键词或省略关键词继续查询。多个候选的名称、说明和方法不足以唯一判断时，列出候选并请用户确认。
+- `get <id>` 调用 `GET /api/gateway/manage/routes/{id}`，默认把后端详情投影成 `schemaVersion: "1.0"` 的稳定调用契约：`gatewayUrlTemplate`、网关方法、追加路径占位符、Query/Header/Body 输入映射、是否必填、访问约束、原始文档/业务说明、CLI 与 SuperApp 示例。
+- 默认输出不包含第三方目标 URL、前置请求 URL 或 `${SECRET.xxx}` 引用。`--raw` 只用于管理员诊断，会原样显示后端详情；不要把 raw 输出放进对话、日志或 SuperApp 代码。
+
+管理查询需要 `GATEWAY_ROUTE.READ`。CLI 的本地契约测试只能验证请求构造和字段投影；最终权限、资源存在性和当前配置仍由 BI 服务端裁决。
+
+## 生成 SuperApp 调用
+
+必须先以 `gateway get` 的返回值为事实源。生成前逐项检查：
+
+- `route.enabled` 必须为 `true`；否则提示管理员启用。
+- 调用方法必须等于 `invocation.method`，不可用目标请求方法代替网关请求方法。
+- 按 `appendPathPlaceholders` 顺序追加并 URL 编码路径；`${REQUEST.path.1}` 对应第一段。若配置引用 `${REQUEST.path.3}`，前两段也必须提供，即使第二段没有被目标模板直接引用。
+- 为所有 `inputMappings[].required=true` 的 Query、Header、Body 输入组装值；缺少时在调用前报出具体参数名。
+- POST 路由的 `bodyMode=passthrough` 表示调用方提供请求体时应原样透传；`bodyRequired=false` 只表示请求体可省略，不得据此从生成代码中删除 body 支持。字符串请求体直接发送，对象请求体再做 JSON 序列化。
+- 响应保持上游语义：204/205 返回 `null`；JSON Content-Type（`application/json` 或 `+json`）调用 `json()`；文本、XML、JavaScript 和表单响应调用 `text()`；其余文件或二进制响应调用 `blob()`。不得无条件执行 `response.json()`。
+- `loginRequired`、`allowedUsers`、`allowedUserGroups` 和 `allowedCallerHosts` 是访问约束。当前用户或来源不满足时提示申请权限或调整白名单。
+- 代码只调用 `/api/gateway/routes/{routeCode}`，不得出现目标服务 URL、前置请求 URL 或敏感凭据。
+
+示例：
+
+```js
+const response = await fetch(
+  `/api/gateway/routes/crm-query-user?keyword=${encodeURIComponent(keyword)}`,
+  { method: "GET", credentials: "include" },
+);
+if (!response.ok) {
+  throw new Error(`请求转发调用失败：${response.status}`);
+}
+const data = await response.json();
+```
+
+追加路径按顺序映射为 `${REQUEST.path.1}`、`${REQUEST.path.2}`。CLI 调试调用示例：
+
+```bash
+guancli gateway invoke crm-query-user --method GET --query keyword=张三 --verbose
+```
+
+出现未授权、路由停用、方法不匹配或参数缺失时，结合返回状态和错误体说明具体修复动作，不要改为绕过网关直连目标服务。
+
+`gateway invoke` 无论成功或失败都会先输出目标响应体；`--verbose` 还会输出状态码和脱敏响应头。HTTP 4xx/5xx 等非 2xx 响应在完成输出后返回错误，进程退出码非零，脚本必须同时保留输出并检查退出码。

package/skills-bundle/guancli/references/metric-batch-query.md

@@ -0,0 +1,82 @@
+# 同轮指标批量查询
+
+`guancli metric batch-query --input queries.json`。完整原生 guancli 也可用 `--input -` 从 stdin 读取 JSON 数组；kit/lite 的 stdin 用于宿主协议，必须使用文件输入。
+同一轮已经确定的独立查询一次提交，CLI 管理并发；读完结果才能确定的下一轮单独提交。
+不要编写循环逐个 `metric query` 或自行安排 Shell 并发。
+
+已确认输入契约时直接复用；缺少必要信息或遇到参数错误时再看 `guancli metric batch-query --help`；多条件筛选示例见 [metric-commands.md](metric-commands.md) 的“结构化条件树示例”。筛选组使用 `conditions` 数组，不使用资源 tree 的 `children`。只使用已确认的指标字段及取值；按错误指出的字段修正，不连续猜键名。
+
+参数确定后将所有独立查询写入同一批次并直接执行；dry-run 仅用于检查计划或排查复杂参数，不作为每批取数的前置步骤。需要 dry-run 时，加 `--fail-on-error` 可让任一计划失败返回非零；全部通过后可用 `&&` 执行同一输入。默认模式仍需检查每项 `status=planned`。正式执行默认模式先检查各项状态；使用 `--fail-on-error` 且退出成功时可直接处理结果，无需重复逐项检查状态。只读查询允许与结果保存、检查和计算组合执行；无法生成结构化运行轨迹时接受降级，不为轨迹增加调用。
+
+批量查询的“保存 + 成功后摘要”示例（queries.json 使用已确认参数）：
+
+```bash
+guancli metric batch-query --input queries.json --fail-on-error -f json > results.json &&
+python3 - <<'PYTHON'
+import json
+with open("results.json") as source:
+    items = json.load(source)["results"]
+print(json.dumps([{"id": item["id"], "columns": item["result"]["columns"],
+                   "rowCount": item["result"]["rowCount"],
+                   "sampleRows": item["result"]["rows"][:5]} for item in items], ensure_ascii=False))
+PYTHON
+```
+
+摘要只展示样例；需要全量计算时在同一本地步骤中使用 results.json 的完整结果，并核对 limit 与完整性。
+仅需直接阅读且输出已足够精简时直接消费 CLI 输出。已有结果的状态检查、完整性检查和计算也在一次本地执行中完成；字段缺失、多义或结果不完整时返回证据，不猜字段、不删筛选。不要为缩短往返扩大数据范围或省略业务校验。
+
+每项必填唯一非空 `id` 和真实 `metricId`。时间范围通过 `filters` 表达，省略表示不额外筛选；支持现有结构化条件树和操作符，不支持需要拆分聚合的多分支 OR。基础查询与 `metric query` 一样，使用指标关联的趋势图卡片，缺失时回退指标值卡片；每项创建独立编辑会话。日期粒度筛选、日期子粒度分组和排序沿用 `metric query` 的能力。错误或不支持的条件显式失败，禁止删除条件后重试以伪装成功。
+
+- `dimensions`：非空维度名称数组；省略时沿用关联卡片的默认分组，显式提供时覆盖该项独立编辑会话的分组。空数组会被拒绝；支持 `日期 toMonth` 等现有粒度语法。
+- `sortAsc` / `sortDesc`：互斥；解析和执行语义与 `metric query` 一致。日期子粒度排序使用同一限定表达式，例如 `日期 toMonth`。
+- `limit`：默认 50，必须为正数。`offset` 默认 0，非负；`offset + limit` 最多 10000。非零 offset 必须显式排序。后端无 offset，CLI 请求至 offset+limit 后截取，不代表全量遍历；排序相同值和跨请求数据变化可能使跨页不稳定，严格分页需选择能唯一定位顺序的分组。
+- `valueFormat`：支持 `raw`（默认）、`formatted` 和 `both`。`raw` 保留 JSON 数字、null 和维度值；`formatted` 沿用 `metric query --value-format formatted` 的指标格式规则，把指标列输出为带精度、千分位、百分号或单位的字符串，维度列保持原值。排序和分页始终基于格式化前的原始值。需要计算并展示同一结果时使用 `both`，一次取数返回原始 `rows` 和位置完全对应的 `formattedRows`，不要为两种格式提交重复查询。
+- `--dry-run`：读取指标详情后生成每项取数请求计划，不执行指标取数，不代表权限、执行或数据完整性已经通过。
+
+完整 guancli 固定并发 10，不限制查询项数量，输入文件至多 1 MiB；超过 10 项的部分排队。batch 不设置整批超时，每个底层接口沿用 `metric query` 的 HTTP 单请求超时。结果逐项写入临时 spool，最终按输入顺序流式输出，内存占用随并发度而不是查询项总数增长；命令取消会传到底层 HTTP 并等待在途 worker 收口。无缓存、无跨批结果复用。每项使用后端生成的独立 UUID 编辑会话，不保存关联卡片；编辑会话生命周期沿用现有 `metric query` 和 BI 后端策略。kit/lite 入口还受宿主实际请求预算约束，超过预算时由 dispatcher 按真实请求数停止。
+
+## 稳定 JSON 协议 v1
+
+顶层 `schemaVersion: "1.0"`、`command: "metric.batch-query"`、`status`、`results`。全部完成成功为 `success`，存在失败为 `partial_failure`。默认有效批次输出完整汇总后退出 0，包括含失败项的批次。使用 `--fail-on-error` 时，任一项为 error 都在输出完整 JSON 后以非零退出，成功项仍保留；适用于正式查询和 dry-run，全部 success 或全部 planned 时退出 0。输入/认证初始化等批次级错误退出非零。
+
+每项保留输入 `id`、`metricId`，按输入顺序返回。`status` 为 `success` / `error` / `planned`；成功时 `result` 包含 `resultMode: "inline"`、实际采用的 `valueFormat`、`columns: [{name,role}]`、`rows` 二维数组、`rowCount`、`offset`、`limit`。raw 模式的指标值保持 JSON 数字；formatted 模式的指标值为展示字符串。both 模式的 `rows` 与 raw 相同，并额外提供 `formattedRows`（包括空结果时的 `[]`），与 rows 共用列、排序和分页；计算读取 rows，展示读取 formattedRows。其它模式不输出 formattedRows。列名直接来自 BI，角色为 dimension/metric，位置与行值一一对应；不存在以本地化展示字段反推新协议的转换。错误为 `error: {code,message,httpStatus?,businessStatus?}`，已有 HTTP/业务状态直接透传，检查每项错误再分析其余成功结果；后端必需字段缺失、类型或行宽变化报 `METRIC_RESPONSE_INVALID`。
+
+原生执行 `timingScope: "native"`，顶层提供 `durationMs`、`concurrencyLimit`、`requestCount`（逻辑 BI 调用数，包含详情、会话和取数，认证重试不计）；每项基础查询通常 3 次调用，显式维度或排序时通常 5 次。每项提供 UTC `startedAt`、`finishedAt`、`durationMs`，可据此检查重叠。
+
+lite/kit 执行会在 replay 轮汇集独立请求；只读请求可标为 parallel，编辑会话 modify 按现有 mutating 契约串行。实际执行并发/时间由宿主负责，`timingScope: "host"` 时不返回原生计时、请求数和并发字段，不能把 kit 重放耗时当成 BI 耗时。现有原生 lite 宿主最多 8 路，WASI 宿主为单路，WASI 不提供本次并发性能保证；完整 guancli 是本次性能验收入口。宿主的总时限沿用其现有策略。
+
+## 服务端与权限边界
+
+复用 `metric query` 的接口链：`GET /api/metric-platform/metrics/{metricId}`、`GET /api/card/{cardId}/edit/session`、`POST /api/card/{cardId}/edit/{sessionId}/data`；显式维度或排序时还会调用 `GET /api/card/{cardId}/edit` 和 `POST /api/oriput/card/{cardId}/edit/{sessionId}/modify`。代理还原后的 Spring 路由均已确认存在。指标详情要求 `METRIC_PLATFORM/read`（PAT pId 90/read）；卡片会话、modify 和取数要求 `BASE/read`，读取编辑配置还要求 `PAGE/update`（PAT 仪表板 pId 1/update）。所以仅查询卡片保存配置时 pId 90/read 可用，显式 dimensions 或 sorting 时 PAT 还要包含仪表板 update；权限不足会逐项返回 403，不能扩大用户资源权限。
+
+每项读取指标关联卡片并在独立编辑会话中取数，不拼接多个聚合结果。未显式提供 dimensions 时保留卡片默认分组；提供 dimensions 或 sorting 时只覆盖该项会话中的对应配置，filters 作为本次取数条件传入。指标详情、卡片配置与取数之间不保证快照；改名、发布或权限变化由服务端最终裁决。当前 batch 输入不包含同比、XTD、recent、占比和排名等高级计算；这些仍由单条 `metric query` 的 v2 分支处理，后续若加入 batch 必须沿用相同分流。
+
+## 指标数值等价对比
+
+仅当用户明确要求比较新旧指标、迁移前后指标或两组候选指标的数值时使用本节；普通 `guanmetric flow verify` 的“可用”验收只需证明指标能成功查询，不默认承担数值等价证明。
+
+对每一对指标构造参数完全对称的查询：
+
+- 使用相同的显式 `dimensions`；日期维度必须使用双方都支持的相同粒度，如 `日期 toMonth`。
+- 对所有分组维度设置确定性排序；单个日期维度通常使用同一表达式作为 `sortAsc`。没有稳定排序时禁止按数组位置比较。
+- 使用相同的 `filters` 固定业务范围和时间范围。涉及“今天”、动态窗口或卡片默认筛选时，优先改成双方相同的固定区间，避免执行时点和默认卡片配置影响结果。
+- 使用 `valueFormat: "raw"`，避免格式、精度、千分位或单位换算制造展示差异。
+- 显式设置足够的 `limit`，但不要把“传了 10000”理解为结果一定完整；后端或关联卡片仍可能存在更小的返回上限。
+
+消费结果时：
+
+1. 逐项检查 `status=success`，任一侧失败则该对为 `query_error`，不能继续比较。
+2. 从 `columns` 找出维度列和指标列，不能按固定列名或固定位置猜测业务列。
+3. 用全部维度值组成复合键，把双方行转换为 `dimensionKey -> raw metric value` 后比较；指标展示名称不同不影响比较。维度键重复、缺失或多指标列无法唯一选择时停止并报告实际列。
+4. 双方键集合相同后再比较相同键的原始值。未获得用户认可时不要擅自增加浮点容差；确需容差时在结论中写明绝对/相对阈值。
+5. 若行数达到已知/疑似服务端或卡片上限、双方行数不同且较短一侧是较长一侧的精确前缀，或无法证明查询覆盖完整范围，状态必须为 `inconclusive_truncated`，不能判为 `different`。按日期等稳定维度拆成不重叠固定区间，确保每个分片低于返回上限后再合并比较。
+
+禁止使用以下证据直接下“数值不一致”结论：
+
+- 未排序的默认前 50 行顺序不同；
+- 仅第一行、前 N 行或数组位置不同；
+- 一侧结果是另一侧的精确前缀；
+- 指标列标题、关联卡片配置或默认展示维度不同；
+- 只观察到指标引用了某个旧 ID，而没有对相同维度键的实际值做比较。
+
+最终结果至少区分 `same`、`different`、`query_error`、`inconclusive_truncated`。汇报 `different` 时给出第一个真正相同维度键下的值差异；汇报 `inconclusive_truncated` 时给出双方行数、限制参数和建议的分片方式。