@linkaicli/linkai-cli 1.0.21 → 1.0.23

package/AGENTS.md

@@ -21,6 +21,7 @@
 
 - 所有命令输出 JSON 信封：成功 `{"ok":true,"data":…}`；失败退出码非 0，`{"ok":false,"error":{"code","message","hint?"}}`。日志走 stderr。
 - 发现命令：`linkai list <关键字>`；看参数：`linkai <site> <command> --help -f json`。不要凭记忆拼参数。
+- **工作流**：每个业务任务（搭建、修改、导入）的第一条命令是 `linkai flow-start --goal "<一句话目标>" --type create|modify|import|query [--plan <planId>]`（修改已有方案必带 `--plan`），结束时 `linkai flow-end --status delivered|abandoned|failed`。
 - 写命令（help 中标 `[write]`）结果不确定时，先用只读命令确认现状，**不要重复执行来"修复"**。
 - **登录只使用 OAuth**：首次登录由用户执行 `linkai login`，在领谋浏览器页面完成授权；CLI 用刷新令牌自动续期。不索要账号密码。同账号切换租户用 `linkai login --tenant <租户名>`；用户要求切换账号时，先问是否要切换领谋账号，确认后执行 `linkai login --switch-account`。
 - 文件参数可用相对路径（相对当前目录）。

package/GUIDE.md

@@ -2,6 +2,7 @@
 
 让 AI 助手（Codex、Claude Code、WorkBuddy、CodeBuddy、DeepSeek 等）帮你在领谋 BI 里自动搭建报表。
 整个过程你只需要：**安装一次、登录一次、接入一次 AI 工具**，之后直接对 AI 说需求。
+能做什么、怎么说、有哪些边界，见安装包内的用户手册 `MANUAL.md`。
 
 > 所有命令都在「终端」里执行：Mac 打开「终端」（启动台搜索“终端”）；Windows 打开「PowerShell」（开始菜单搜索“PowerShell”）。
 > 每一步都是：**复制命令 → 按说明修改尖括号或中文部分 → 回车执行**。

package/MANUAL.md

@@ -0,0 +1,239 @@
+# LinkAI-CLI 用户手册
+
+> 适用版本：1.0.22（2026-11-06）。安装、登录、接入 AI 工具见 `GUIDE.md`；本手册说明**能做什么、怎么说、会发生什么、有哪些边界**。
+
+LinkAI-CLI（命令 `linkai`）是领谋 BI 的 AI 命令行。你不需要记命令：在 WorkBuddy、Claude Code、Codex、CodeBuddy 等 AI 助手里**用中文说需求**，
+AI 会按领谋的规则、用**你自己的领谋账号和权限**去做，做完把结果和依据交给你。
+
+---
+
+## 一、能力一览
+
+| 能力 | 一句话说明 | 典型说法 |
+|---|---|---|
+| 问数 | 直接问业务数据，拿到数字或小表，并说明口径和数据截至时间 | 「今天采购了多少、入库了多少？」 |
+| 自动搭建看板 | 从需求到数据集、卡片、看板、筛选器、报表一次搭好，并逐项验收 | 「帮我搭一个销售看板……先给我看计划」 |
+| 修改已有看板 | 加卡片、改图表、调排序、改筛选器、改取数口径 | 「经营看板加一张按渠道的退货率趋势」 |
+| 方案知识库 | 每个看板一份带版本的说明：解决什么问题、每张卡片怎么取数 | 「把这个看板的方案知识给我」 |
+| 数据导入与填报 | 把 Excel / CSV 按规则写进填报卡片，写前预览、写后回读 | 「把这份店铺预算导进经营看板」 |
+| 复用已有成果 | 建之前先查本租户已有的数据集 / 卡片，能复用就不重复建 | （自动进行） |
+| 数据核对与排查 | 卡片空白、数字对不上时，沿来源一步步查原因 | 「这张卡片为什么是空的？」 |
+| 多会话协同 | 多个 AI 会话并行做同一个方案时自动分工，不互相覆盖 | 「开两个子任务并行搭这三张卡」 |
+| 浏览器操作（可选） | 打开领谋页面截图验收、做网页操作 | 「搭完截个图给我看看」 |
+
+---
+
+## 二、使用场景
+
+### 场景 1：问数——直接问一个数
+
+**怎么说**：只想知道一个数或一张小表时直接问，越具体越好（指标、时间范围、维度）。
+
+- 「今天采购数量有多少，入库了多少？」
+- 「本月各二级品类销售额排名前 20 的款」
+- 「上个月各店铺的退货率」
+
+**会发生什么**：
+
+1. 问题有歧义时，AI 先问你。比如「入库」指物料还是成品，「销售额」含不含退货。
+2. AI 把问题交给领谋服务端的**小满问数**：检索口径、选数据源、生成查询，并按你的数据权限执行。
+3. 小满答不了时，AI 改为**兜底**：读当前租户的数据字典，自己写只读查询。查询要先过领谋的数据集校验，再由服务端执行。
+   回答里会注明「小满未能回答，以下由 AI 按数据字典口径查询」。
+4. 回答直接写在对话里，包括：
+   - 数字或小表；
+   - 口径：数据来源、用到的视图和字段；
+   - 时间范围；
+   - 「数据截至 X」：数仓多为每天凌晨更新，「今天」的数可能还不完整。
+
+**边界**：
+
+- **只能看到你在领谋里本来就能看到的数据。**
+- 明细最多返回 1000 行；没有导出权限的账号最多 50 行。需要全量明细，请改问汇总，或找管理员导出。
+- 有频率限制：每人每分钟 6 次、每小时 60 次、每天 300 次，每人每小时最多返回 5000 行。
+- 不支持「翻页取数」，同一类问题反复换条件也会被暂停。这是防批量导出，不是故障。
+- 同一个问题 5 分钟内再问，直接返回上次的结果。
+- 没查到时 AI 会说「没有查到」，不会说成 0。
+
+---
+
+### 场景 2：自动搭建一个新看板
+
+**怎么说**：说清楚想看什么、给谁看，并让 AI 先出计划。
+
+- 「帮我搭一个销售看板：本期销售金额、件数、按渠道的日趋势、商品明细，先给我看计划」
+- 「在 XX 租户建一个聚水潭销售明细看板，支持按订单 / 付款 / 发货时间和品牌、店铺、渠道筛选」
+
+**会发生什么**：
+
+1. AI 确认**当前租户**和**新建还是修改**。没说清楚时，它会问你。
+2. 读领谋的搭建规则和本租户的数据字典，按你确认的口径写数据集查询。
+3. **先演练、不写入**：给你看要建哪些数据集、卡片、看板、筛选器，以及执行计划。
+4. 你确认后才写入，依次建数据集、卡片、看板、筛选器和报表，并逐项回读验收。
+   - 数据集保存前，先在领谋做「运行」生成字段，再试取数，取数失败不保存。
+   - 卡片和筛选器按领谋界面的保存规则校验。
+5. 交付一份**方案知识库**：方案地址、版本、方案内容、解决的问题，以及每张卡片的内容、数据集、数据来源、粒度和取数规则。
+
+**要你明确同意的动作**（AI 会先问）：
+
+- 使用正式名称：对所有成员可见；
+- 覆盖看板筛选器；
+- 修改已被其它看板或报表引用的卡片、数据集；
+- 删除非试验对象；
+- 切换到你没提到的租户后写入。
+
+试验对象统一用 `zz-` 前缀，可以一键清理。
+
+---
+
+### 场景 3：修改已有看板
+
+**怎么说**：说出看板名称和要改的内容。
+
+- 「经营看板加一张按渠道的退货率趋势」
+- 「明细表按支付时间倒序」「销售看板的店铺筛选改成多选」
+- 「把趋势图的销售额改成不含运费」
+
+**会发生什么**：
+
+1. AI 定位看板，先读它现有的方案知识；改动前备份卡片、方案或数据集。
+2. 按规则修改，并回读确认生效。
+3. 同步更新方案知识库，版本加一并写明本次修改。没有方案知识的历史看板，会自动补建 v1。
+
+**系统分析方案（领谋下发的看板）只能看不能改。**
+AI 可以读它的方案知识，回答「这个数是怎么取的」，但不能改它的卡片、筛选器、排序，也不能删除。
+需要按本租户调整时，请在领谋网页上把它**另存为本租户的分析方案**，再让 AI 改新方案。
+
+---
+
+### 场景 4：查看与维护方案知识库
+
+- 「把经营看板的方案知识给我」：返回完整说明，包括每张卡片的取数逻辑。
+- 「这个看板的销售额是怎么算的？」：AI 按方案知识和卡片配置回答。
+
+方案知识只写口径与规则，**不向你输出完整的查询 SQL**。
+服务器暂时不可用时，CLI 先在本机暂存，恢复后自动补传。
+
+---
+
+### 场景 5：数据导入与填报
+
+**怎么说**：
+
+- 「把这份店铺预算导进经营看板」
+- 「本月实际数据更新到经营看板」「重传一下，看看数据对不对」
+- 「新建一张填报卡片，用来录入每月目标」
+
+**会发生什么**：
+
+1. AI 找到对应看板和本租户的导入规范，核对文件的字段、单位、业务键和更新方式。
+2. 先预览将写入的记录和范围，你确认后才写入。
+3. 写完回读填报数据和业务汇总，报告实际写入的数量和范围。
+   没把握的地方会写「未确认」，不会把「请求条数」当成「成功条数」。
+
+**边界**：
+
+- 「看看数据」不算导入授权。
+- 删除旧数据、改变口径、扩大写入范围，都要你另外同意。
+- 删除填报记录前，必须先备份并经你同意。
+- 只往**当前登录租户**写，目标卡片不属于当前租户时会被拦下。
+
+---
+
+### 场景 6：数据核对与问题排查
+
+- 「这张卡片为什么是空的 / 一直转圈？」：AI 按页面方式查询这张卡片，看数据库报错和实际执行的查询。
+- 「看板上的数和我 Excel 里的对不上」：AI 沿来源单元格、转换、业务键、聚合、筛选逐步溯源，给出具体差异和证据，不擅自改源数。
+- 「这个数据集被哪些卡片用了？」：列出引用关系，改之前先评估影响。
+
+---
+
+### 场景 7：多个 AI 会话一起做
+
+一个看板由多个会话或子代理并行推进时，用本机任务板分工：
+- 读取、校验、预览全部并行；
+- 改同一个对象之前先「认领」，别人正在改的对象会被拒绝写入，避免互相覆盖；
+- 做完的成果（查询文件、对象 id、口径结论）随时共享，避免重复做。
+
+只在同一台电脑上生效。单个会话做一个方案时，不需要这些。
+
+---
+
+### 场景 8：截图验收与网页操作（可选）
+
+「把经营看板截个图给我」「搭完截个图看看」：AI 执行 `linkai plan-shot --plan <方案名>`，按名称找到方案，
+**等全部卡片取完数后把整个方案截成一张图**（不只是首屏），并告诉你哪些卡片没有数据。同名方案有多个时，AI 会先问你是哪一个。
+
+- 截图期间 LinkAI 自己的 Chrome 窗口会短暂到前台（窗口在后台时浏览器不画图表），不动你自己的标签页。
+
+- 需要 Chrome 和 LinkAI 浏览器扩展。
+- 操作在 LinkAI 管理的独立标签页里进行，**不会动你正在看的页面**，扩展也不会把浏览数据传到外部。
+- 搭建和修改本身是纯接口操作，不需要浏览器。
+- 检查浏览器连接：`linkai doctor`。
+
+---
+
+## 三、权限与安全
+
+- **用你自己的账号**：首次在领谋网页完成授权，之后自动续期；AI 不会、也不应该索要你的密码。
+- **只做你本来能做的事**：取数按你的数据权限，写入按你的账号权限；租户之间严格隔离。
+- **不能操作数据库**：不能直连数据库、执行任意 SQL、管理数据源或改数仓。数据集只能是单条只读查询，只能用本租户开放的视图；需要新视图，请联系领谋数据团队。
+- **部分接口不对 CLI 开放**：例如知识库文档维护、小满调试接口。口径的补充和纠正，请在领谋网页上维护。
+- **关键操作先确认**：见场景 2、5 的清单。
+- **全程留痕**：每次操作都记入领谋的 CLI 操作日志，问数还会记录问题、口径和查询，网页「CLI 记录」可查，便于追溯。查询结果本身不记录。
+
+---
+
+## 四、常用说法与小技巧
+
+| 想要 | 可以这样说 |
+|---|---|
+| 换租户 | 「切到 XX 租户」→ AI 执行 `linkai login --tenant <租户名>`，不用重新授权 |
+| 换账号 | 「切换账号」→ AI 先问你，确认后重新授权 |
+| 先看不写 | 「先给我看计划 / 先预览，别写入」 |
+| 只改试验版 | 「用 zz- 前缀先建一套试试」，之后「清理 zz- 试验对象」 |
+| 要依据 | 「这个数的口径是什么？数据截至什么时候？」 |
+| 新会话继续上次的活 | 直接说继续。AI 会看到上次没完成的任务，按提示续做或结束 |
+
+**给 AI 的建议**：每个任务一开始，AI 应先开一个「工作流」并写明目标，修改已有看板时还要带上看板 id，结束时关闭。
+这样领谋网页上能看清每个任务做了什么。AI 漏了这一步时，CLI 会提醒它补上。
+
+---
+
+## 五、常见问题
+
+| 问题 | 说明 |
+|---|---|
+| AI 说「需要登录」 | 在终端执行 `linkai login`，在领谋网页完成授权，然后告诉 AI「好了」 |
+| AI 说「被限流了」 | 问数超过频率或数据量限制，按提示的时间再试；需要大量数据请改问汇总 |
+| AI 说「这是系统分析方案，不能改」 | 在网页上另存为本租户的分析方案，再让 AI 改新方案 |
+| AI 说「没有可用视图 / 不能操作数据库」 | 正常的安全限制；需要的数据请联系领谋数据团队开放 |
+| AI 说「需要重新读取数据字典」 | 字典在服务端更新过，或换了租户；AI 重读后会继续，不用你操作 |
+| 终端里的版本和 AI 用的版本不一样 | 电脑上装了两份（常见于 WorkBuddy 自带的 Node）。执行 `linkai doctor` 查看各份位置，只保留一份 |
+| 怎么升级 | 自动进行。发布了必须升级的版本时，下一条命令会先自动升级再执行，技能随之更新 |
+| 公共电脑用完 | `linkai logout`，撤销授权并删除本机登录信息 |
+
+---
+
+## 附：命令参考（AI 使用，供了解）
+
+所有命令输出 JSON。查看参数：`linkai <命令> --help -f json`。标「写」的命令会改动领谋里的数据。
+
+| 类别 | 命令 |
+|---|---|
+| 登录与环境 | `login`、`logout`、`status`、`tenants`、`doctor` |
+| 问数 | `ask`（读） |
+| 数据字典（只读） | `kb-sources`、`kb-search`、`kb-catalog`、`kb-object`、`kb-docs`、`kb-doc` |
+| 搭建知识库 | `kb`、`kinds`（74 种图表）、`template` |
+| 自动搭建 | `build`（默认演练；`--execute` 写入；正式名还需 `--confirm`） |
+| 数据集 | `ds-list`、`ds-tables`、`ds-fields`、`ds-sql`、`ds-refs`、`ds-match`、`sql-check`、`fmt`；写：`ds-create`、`ds-update` |
+| 卡片 | `card-list`、`card-get`、`query`；写：`card-chart`、`card-table`、`card-meter`、`card-gantt`、`card-save`、`card-sort` |
+| 看板（分析方案） | `plan-list`、`plan-get`；写：`plan-create`、`plan-add`、`plan-filter`、`reset-filter` |
+| 报表 | `report-list`、`report-card`；写：`report-publish` |
+| 方案知识库 | `plan-knowledge-get`；写：`plan-knowledge` |
+| 填报 | 写：`fill-write`（默认预览，`--execute` 写入） |
+| 维护 | `backup`；写：`remove`（需授权）、`clean`（只清 `zz-` 试验对象） |
+| 工作流 | `flow-start`、`flow-end`、`flow-status` |
+| 多会话协同 | `collab-start`、`collab-status`、`collab-task`、`collab-claim`、`collab-release`、`collab-note`、`collab-close` |
+| 截图与浏览器（可选） | `plan-shot`（方案整页截图）、`shot`（任意页面首屏）、`browser …` |
+| 接入 AI 工具 | `skills install <workbuddy｜workbuddy-intl｜claude｜codex｜codebuddy>`、`skills prompt`（无技能机制的工具，如 DeepSeek API） |
+| 未封装接口 | `api-get`、`api`（数据源、SQL 类等接口不开放） |

package/README.md

@@ -67,6 +67,7 @@ npm install -g @linkaicli/linkai-cli
 
 ## 更多
 
+- 能力与使用场景（用户手册）：安装包内的 `MANUAL.md`
 - 完整的安装与使用说明：安装包内的 `GUIDE.md`
 - AI 代理调用约定：安装包内的 `AGENTS.md`
 - 浏览器扩展（截图验收、网页操作才需要）：请联系领谋获取

package/THIRD_PARTY_NOTICES.txt

@@ -1,4 +1,4 @@
-@linkaicli/linkai-cli 1.0.21 安装包内含以下第三方软件（已打包进 dist/bundle）。
+@linkaicli/linkai-cli 1.0.23 安装包内含以下第三方软件（已打包进 dist/bundle）。
 
 ── @colors/colors@1.5.0（MIT）
 

package/cli-manifest.json

@@ -1657,6 +1657,50 @@
     "modulePath": "linkai/commands.js",
     "sourceFile": "linkai/commands.js"
   },
+  {
+    "site": "linkai",
+    "name": "plan-shot",
+    "description": "分析方案整页截图：按方案名称或 id 打开方案，等全部卡片加载完后把整个方案截成一张 PNG（需要 Chrome 与 LinkAI 扩展；在独立标签中进行）",
+    "access": "read",
+    "domain": "bi.linkmore.com",
+    "strategy": "ui",
+    "browser": true,
+    "args": [
+      {
+        "name": "plan",
+        "type": "string",
+        "required": true,
+        "help": "方案名称或方案 id（名称按 plan-list 精确匹配，多个同名时报出候选让用户选）"
+      },
+      {
+        "name": "output",
+        "type": "string",
+        "required": false,
+        "help": "截图保存路径（默认 ~/.linkai/artifacts/linkai/shots/<方案名>-<时间>.png）"
+      },
+      {
+        "name": "width",
+        "type": "int",
+        "default": 1600,
+        "required": false,
+        "help": "截图宽度（像素），默认 1600"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 120,
+        "required": false,
+        "help": "整个截图最多用多少秒（打开方案、等卡片取数、截图），默认 120；方案很大时加大"
+      }
+    ],
+    "defaultFormat": "json",
+    "type": "js",
+    "modulePath": "linkai/commands.js",
+    "sourceFile": "linkai/commands.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "defaultWindowMode": "foreground"
+  },
   {
     "site": "linkai",
     "name": "query",