@linkaicli/linkai-cli 0.0.0-stage → 1.0.17

package/skills/linkai-usage/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: linkai-usage
+version: 2026.11.02.3
+description: LinkAI-CLI 通用用法：查找可用命令、查看参数、理解 JSON 返回与错误码、处理登录与后台服务问题。不确定该用哪个 linkai 命令时使用；领谋 BI 报表搭建请用 linkai-report-builder，网页操作请用 linkai-browser。
+allowed-tools: Bash(linkai:*), Read
+---
+
+# LinkAI-CLI 通用用法
+
+LinkAI-CLI（命令 `linkai`）提供领谋 BI 搭建命令（`linkai …`）和浏览器操作命令（`linkai browser …`）。
+
+## 查找命令
+
+```sh
+linkai list <关键字>                 # 按名称和说明搜索命令
+linkai list --site linkai --limit 20   # 列出领谋 BI 的命令
+linkai build --help -f json     # 查看某个命令的参数
+```
+
+结果分页返回：`{ok:true,data:{commands,total,nextOffset?}}`，用 `--offset <nextOffset>` 翻页。
+不要凭记忆拼参数，先看命令帮助；也不要一次性把全部命令列进上下文。
+
+## 返回结果
+
+- 成功：`{"ok":true,"data":…}`；失败：退出码非 0，`{"ok":false,"error":{"code","message","hint"}}`。日志在 stderr。
+- 按 `error.code` 和 `hint` 处理问题。常见错误码：
+  - `AUTH_REQUIRED`：未登录或登录失效，请用户执行 `linkai login` 并在领谋网页完成 OAuth 授权；不要索要密码。
+  - `status` 返回 `unfinishedFlows`：有未完成或中断的工作流（`reason`：process-killed 进程被强制结束 / build-incomplete 搭建未完成 / outcome-unknown 写操作结果未知 / idle 长时间无活动）。按 `next` 处理：续做加 `--flow <id>`，不做了 `linkai flow-end --flow <id> --status abandoned`；`linkai flow-status` 查看全部。
+  - `DICTIONARY_REQUIRED`：写 SQL 前没有读过当前租户的最新数据字典（切换了租户、重新登录，或服务端更新过数据字典）。按提示执行 `kb-sources`、`kb-search` / `kb-object` / `kb-doc` 核对后再重做，不要沿用旧结论。
+  - `SQL_INVALID`：服务端解析 SQL 失败（字段 / 表不存在或语法错误）。用 `kb-object` / `ds-tables` 核对字段名后改 SQL，`sql-check` 通过前不要执行 `ds-create` / `ds-update`。
+  - `IN_USE`：对象仍被引用（如数据集被卡片引用）。先 `ds-refs` 找到引用它的卡片，经用户确认后先删卡片再删数据集。
+  - `NOT_FOUND` / `FORBIDDEN`：对象已删除或不存在 / 当前用户无权限（如别人的私有数据集）。重新用列表命令确认精确 id，不要重复执行写命令。
+  - `ds-update` 返回 `unchanged: true`：SQL 和名称与线上一致，没有重复保存；不要再执行同样的更新。
+  - `DUPLICATE_NAME`：同名对象已存在，通常是上一次已经创建成功。先 `card-list` / `ds-list` / `plan-list --search <名称>` 确认并复用，不要换名或重复执行同样的创建。
+  - `SQL_READONLY` / `SQL_TABLE_NOT_ALLOWED`：SQL 不是单条只读查询 / 用了不在 `ds-tables` 清单里的视图。换用清单里的视图；确需新视图就停下，告诉用户联系领谋数据团队。
+  - `FILE_NOT_FOUND`：输入文件不存在（相对路径按当前目录解析）。确认文件已写出、路径正确，不要原样重复执行。
+  - `SKILLS_INSTALL_FAILED`：技能目录写不进去（Windows 上常见于目录被占用或无权限）。关闭 AI 工具后重试，或改用 `linkai skills install <工具> --mode rules`。
+  - `CONFIG_INVALID`：卡片或筛选条件违反领谋界面的保存规则（与在界面点保存时的校验一致）。按 message 逐条修正后再保存，规则见 references/card.md「保存前校验」、filters.md §8。
+  - `READ_ONLY`：系统报表 / 系统方案（资源包下发到本租户）只读，本租户改不了。停下告诉用户到来源租户修改后重新下发，不要换接口反复尝试。
+  - `BAD_REQUEST`：请求体结构不对（多见于 `api` 透传）。查 `references/api-catalog.md` 或回读一条现有数据照抄结构，优先用已封装的命令。
+  - `KNOWLEDGE_INVALID`：方案知识文件不完整（缺卡片段落、缺 cardId、修改方案缺 changeSummary 等）。按 message 补齐后重新执行 `plan-knowledge`。
+  - `NETWORK_ERROR`：连不上领谋服务器（CLI 已自动重试过）。不要连续重复执行：等 1～2 分钟再试，仍不通就请用户检查网络或代理；写命令失败后先用只读命令确认结果，再决定是否重做。
+  - `DUPLICATE_DATASET`：当前租户已有完全一样的数据集。直接复用提示里的数据集 id（build spec 写 id 或加 `reuse: auto`）；确需独立一份才加 `--allow-duplicate` 并向用户说明理由。
+  - `COLLAB_CONFLICT`：要写的对象正被别的会话（执行者）处理。按 `linkai-collab` 技能执行：`linkai collab-status --board <任务板>` 看分工，改做别的任务或等对方释放，不要绕过。
+  - `TENANT_MISMATCH`：要写的卡片不属于当前租户。按提示 `linkai login --tenant <租户名>` 切到方案规范指定的租户，`linkai status` 确认后再写；无法确认就停下告诉用户，不要绕过。
+  - `ARGUMENT`：参数或输入有误，按 message 修正。
+- 写操作结果不确定时，先用只读命令查看现状，不要重复执行。
+- 返回成功但数据为空，与执行失败不是一回事。
+- 需要表格等格式时，命令帮助里列出的可用 `-f table|yaml|csv|md|plain`。
+
+## 浏览器与后台服务
+
+```sh
+linkai browser open https://example.com --session research
+linkai browser state --session research
+linkai browser close --session research
+```
+
+页面命令要带 `--session`；`--profile` 指定 Chrome 用户（`linkai profile list` 查看，`linkai profile use <名称>` 设为默认）。
+连接问题先执行 `linkai doctor`；后台服务：`linkai daemon status|restart|stop`。网页操作细节见 linkai-browser。
+
+## 技能与知识库
+
+- 技能：`linkai skills list`；读取：`linkai skills read linkai-report-builder -f plain`。
+- 知识库：`linkai kb` 列出全部文件，`linkai kb --file <路径>` 读取。
+- 用户问到浏览器能力或工作原理时，以《浏览器能力说明》（`linkai kb --file knowledge/browser/README.md`）为准回答，不补充文中没有的内容。

package/templates/report-spec/cards/detail-table.json

@@ -0,0 +1,12 @@
+{
+  "name": "zz-demo-商品明细",
+  "pageSize": 20,
+  "limitCount": 2000,
+  "columns": [
+    { "header": "商品", "width": 50, "rows": [["商品名称:b"], ["商品编码:grey"]] },
+    { "header": "店铺", "width": 50, "plain": "店铺" },
+    { "header": "销售件数", "width": 50, "plain": "销售件数" },
+    { "header": "销售金额", "width": 50, "plain": "销售金额" }
+  ],
+  "hidden": []
+}

package/templates/report-spec/filters.example.json

@@ -0,0 +1,28 @@
+{
+  "isTenantSystem": true,
+  "userPageSettingId": "{{plan}}",
+  "filterSourceType": 4,
+  "filters": [
+    {
+      "labelName": "店铺",
+      "filterType": 1,
+      "filterOperationType": 2,
+      "filterProperty": 1,
+      "fieldName": "店铺",
+      "indexBlockDataId": "{{dataset:detail}}",
+      "indexBlockDataSourceId": "{{dataSource}}",
+      "defaultValueType": 1,
+      "defaultValue": "\"\"",
+      "isRequired": false,
+      "isDate": false,
+      "isShowAllOption": true,
+      "inOuter": true,
+      "sortNum": 0,
+      "filterSourceType": 4,
+      "userPageSettingId": "{{plan}}",
+      "bindUserPageCards": [
+        { "pageCardId": "{{pageCard:detail}}", "dataSettingComment": "店铺", "dataSettingIds": [] }
+      ]
+    }
+  ]
+}

package/templates/report-spec/plan-knowledge.example.yaml

@@ -0,0 +1,18 @@
+# 修改原方案后，由 AI 按线上回读结果填写；cardId 必须覆盖方案内每张业务卡片。
+# 执行：linkai plan-knowledge --plan <planId> --mode update --file plan-knowledge.example.yaml
+# 不要写入 SQL 正文、凭据或查询结果数据。
+
+summary: 描述方案包含的分析内容和整体使用方式。
+problem: 描述方案解决的业务问题和面向的使用者。
+changeSummary: 描述本次方案修改内容。
+rules:
+  - 公共时间口径、状态范围、筛选和去重规则
+
+cards:
+  - cardId: <从 plan-get/card-list 回读的精确卡片 ID>
+    content: 描述卡片展示内容、用途和阅读方式。
+    source: 描述租户视图或业务数据来源，不粘贴 SQL。
+    grain: 描述数据粒度，例如“日、店铺”。
+    dataLogic: 用自然语言描述指标计算、过滤、关联和汇总规则，不粘贴 SQL。
+    rules:
+      - 补充该卡片特有的时间、状态、去重或异常排除规则

package/templates/report-spec/report.example.yaml

@@ -0,0 +1,123 @@
+# 自动搭建报表模版（report spec v1）
+# 用法：
+#   linkai build --spec templates/report-spec/report.example.yaml                 # 只校验 + 输出执行计划（不写入）
+#   linkai build --spec <spec> --execute                                          # 全部为 zz- 前缀时直接执行
+#   linkai build --spec <spec> --execute --confirm                                # 含正式名：用户明确授权后才加 --confirm
+# 规则与字段说明：knowledge/report-builder/build-spec.md
+# 文件路径（sql / spec / filters）相对本文件所在目录。
+# sql/ 下内容仅为格式示例；实际 SQL 必须由 AI 根据用户需求、当前租户数据字典和确认后的业务口径重新编写，CLI 不生成业务 SQL。
+
+version: 1
+operation: create                   # 必填；linkai build 只新建。修改原方案先确认 planId，完成后用 plan-knowledge --mode update 同步知识库
+name: zz-demo-商品经营看板          # 方案名；zz- 前缀 = 试验对象，可用 linkai clean --prefix zz-demo- 清理
+# tenant: 示例租户                  # 可选：写上租户名，执行时会核对当前登录的租户，不一致就停下
+
+knowledge:                          # 最终完整呈现给用户；同时版本化保存为「<方案名>方案知识库」
+  summary: 汇总商品经营核心指标、销售趋势、渠道结构和商品明细，形成从总览到明细的分析路径。
+  problem: 帮助经营人员快速判断销售规模、变化趋势和渠道贡献，并定位到具体商品明细。
+  rules:
+    - 指标口径、时间范围和状态范围以当前租户数据字典及用户确认结果为准
+    - 页面筛选条件会同时作用于已绑定的业务卡片
+
+layout:                             # 可省略，默认值即运营分析方案视觉基线
+  contentX: 2
+  contentWidth: 20
+  pageBackgroundColor: "#F4F3EE"
+  titleHeight: 2
+
+datasets:                           # SQL 只能查租户视图（linkai ds-tables）；口径先查数据字典知识库
+  - key: kpi
+    name: zz-demo-经营KPI
+    sql: sql/kpi.sql
+  - key: trend
+    name: zz-demo-日趋势
+    sql: sql/trend.sql
+  - key: channel
+    name: zz-demo-渠道占比
+    sql: sql/channel.sql
+  - key: detail
+    name: zz-demo-商品明细
+    sql: sql/detail.sql
+  # 复用已有数据集：- { key: base, id: <dsId> }
+
+cards:
+  - key: kpi_sales
+    type: meter                     # 单数值指标卡（meter/list）；头部多指标的 meterList 类型六见 knowledge 卡片篇
+    dataset: kpi
+    name: zz-demo-销售金额
+    col: 销售金额
+    subtitle: 本期销售金额
+    knowledge:
+      content: 展示当前筛选范围内的销售金额，用于观察整体经营规模。
+      source: 商品销售明细租户视图
+      grain: 当前筛选范围汇总为一行
+      dataLogic: 对符合已确认订单状态和时间口径的销售金额求和。
+  - key: kpi_qty
+    type: meter
+    dataset: kpi
+    name: zz-demo-销售件数
+    col: 销售件数
+    subtitle: 本期销售件数
+    knowledge:
+      content: 展示当前筛选范围内的销售件数，用于观察商品销量规模。
+      source: 商品销售明细租户视图
+      grain: 当前筛选范围汇总为一行
+      dataLogic: 对符合已确认订单状态和时间口径的销售件数求和。
+  - key: trend
+    type: chart
+    dataset: trend
+    name: zz-demo-销售日趋势
+    kind: line/multiple             # linkai kinds 查全部 74 种
+    dim: [月日, 日期序]             # 第一个维度当 x 轴；日期序只用于排序（不画）
+    meas: [销售金额]
+    series: 渠道
+    sort: "日期序:asc"
+    knowledge:
+      content: 按日期展示销售金额变化，并按渠道区分系列，用于识别趋势和异常波动。
+      source: 商品销售明细租户视图
+      grain: 日期、渠道
+      dataLogic: 按业务日期和渠道汇总销售金额，以日期序升序展示。
+  - key: channel
+    type: chart
+    dataset: channel
+    name: zz-demo-渠道销售占比
+    kind: pie/donut
+    dim: [渠道]
+    meas: [销售金额]
+    sort: "销售金额:desc"           # 饼/环图默认按数值降序
+    knowledge:
+      content: 展示各渠道销售金额占比，用于判断渠道贡献结构。
+      source: 商品销售明细租户视图
+      grain: 渠道
+      dataLogic: 按渠道汇总销售金额并降序排列，计算各渠道在当前筛选范围内的贡献。
+  - key: detail
+    type: table                     # AG 明细表，spec 格式见 knowledge 卡片篇「一把出」
+    dataset: detail
+    spec: cards/detail-table.json
+    sort: "销售金额:desc"
+    knowledge:
+      content: 展示商品维度的销售明细，用于从汇总指标下钻定位具体商品表现。
+      source: 商品销售明细租户视图
+      grain: 商品
+      dataLogic: 按商品聚合销售金额和销售件数，并按销售金额降序展示。
+  # 复用已有卡片：- { key: old, type: existing, id: <cardId> }
+
+sections:                           # 自上而下；每个分区一个标题卡（cardType 5，高 2 格）+ 若干行
+  - title: { serial: "01", title: 经营总览, subtitle: 本期核心指标 }
+    rows:
+      - height: 6
+        cards: [ { card: kpi_sales }, { card: kpi_qty } ]          # 不写 width 时均分内容区
+  - title: { serial: "02", title: 趋势与结构, subtitle: 按渠道拆分 }
+    rows:
+      - height: 16
+        cards: [ { card: trend, width: 12 }, { card: channel, width: 8 } ]
+  - title: { serial: "03", title: 商品明细 }
+    rows:
+      - height: 30
+        cards: [ { card: detail } ]
+
+filters: filters.example.json        # 可选：方案筛选器模板（全量覆盖）；占位符见 build-spec.md
+
+publish:                             # 可选：把卡片发布为数据报表（正式名需要 --confirm）
+  reports:
+    - { card: detail, name: zz-demo-商品明细报表 }

package/templates/report-spec/sql/channel.sql

@@ -0,0 +1,7 @@
+-- 渠道占比：渠道 + 销售金额（环图）。
+SELECT
+  t.channel_name     AS 渠道,
+  SUM(t.sale_amount) AS 销售金额
+FROM scm_warehouse.ads_gop_sales_item_view t
+WHERE t.biz_date BETWEEN CAST($1 AS DATE) AND CAST($2 AS DATE)
+GROUP BY 1

package/templates/report-spec/sql/detail.sql

@@ -0,0 +1,10 @@
+-- 商品明细：一行一个商品；保留唯一键（商品编码）避免全维度 GROUP BY 合并相同行。
+SELECT
+  t.item_code        AS 商品编码,
+  t.item_name        AS 商品名称,
+  t.shop_name        AS 店铺,
+  SUM(t.sale_qty)    AS 销售件数,
+  SUM(t.sale_amount) AS 销售金额
+FROM scm_warehouse.ads_gop_sales_item_view t
+WHERE t.biz_date BETWEEN CAST($1 AS DATE) AND CAST($2 AS DATE)
+GROUP BY 1, 2, 3

package/templates/report-spec/sql/kpi.sql

@@ -0,0 +1,8 @@
+-- 经营 KPI：一行，供指标卡使用。
+-- ⚠ 表名必须在 `linkai ds-tables` 白名单内（租户视图）；字段口径以数据字典知识库为准。
+-- $1/$2 为参数变量（开始/结束日期），由方案筛选器（filterProperty:2）传入，见 knowledge 查询引擎篇 §2.1。
+SELECT
+  SUM(t.sale_amount) AS 销售金额,
+  SUM(t.sale_qty)    AS 销售件数
+FROM scm_warehouse.ads_gop_sales_item_view t
+WHERE t.biz_date BETWEEN CAST($1 AS DATE) AND CAST($2 AS DATE)

package/templates/report-spec/sql/trend.sql

@@ -0,0 +1,9 @@
+-- 日趋势：月日（x 轴文本）+ 日期序（排序用整数）+ 渠道（系列）+ 销售金额。
+SELECT
+  DATE_FORMAT(t.biz_date, '%m-%d')                  AS 月日,
+  CAST(DATE_FORMAT(t.biz_date, '%Y%m%d') AS INT)    AS 日期序,
+  t.channel_name                                    AS 渠道,
+  SUM(t.sale_amount)                                AS 销售金额
+FROM scm_warehouse.ads_gop_sales_item_view t
+WHERE t.biz_date BETWEEN CAST($1 AS DATE) AND CAST($2 AS DATE)
+GROUP BY 1, 2, 3