@linkaicli/linkai-cli 0.0.0-stage → 1.0.18

package/knowledge/README.md

@@ -0,0 +1,29 @@
+# 知识库架构
+
+LinkAI-CLI 面向 AI 代理（Codex、Claude Code、DeepSeek 等）。BI 搭建知识以 Markdown 按需读取，租户数据字典通过结构化接口按需读取；命令一律用 `linkai …` 的真实写法，复制即可执行。
+
+| library | 知识库 | 范围与来源 | 当前状态 | 用途 |
+|---|---|---|---|---|
+| `bi-builder` | **BI 搭建知识库** | 公共；服务器优先、CLI 内置兜底 | CLI 已实现；服务端 `/api/app/linkai-kb` 尚未上线，当前读取安装包内置版本 | 数据集 → 卡片 → 看板/报表的强制搭建规则、接口、配置、筛选器、踩坑与 SOP |
+| `data-dictionary` | **数据字典知识库** | 当前租户；`/api/app/ai-kb` 结构化只读接口，仅服务器下发 | 已上线 | 租户视图、字段、关系、指标口径和枚举；AI 编写 SQL 前必须读取 |
+| `integration-flow` | **集成流知识库** | 租户 | 预留 | SCM、ERP、WMS、电商等集成流搭建知识 |
+| `user` | **用户知识库** | 当前用户 | 预留 | 用户个人维护的知识内容 |
+
+[`browser/README.md`](browser/README.md) 是随 CLI 版本发布的浏览器能力说明，不属于四类业务知识库。
+
+## 当前两个知识库怎么配合（自动搭建报表）
+
+```text
+需求（指标/维度/筛选/版式）
+  │
+  ├─ 租户数据字典：选视图、字段、口径、枚举  →  AI 按需求编写数据集 SQL
+  │
+  ├─ 搭建报表知识库：选图表类型、字段角色、排序、筛选器、布局基线  →  写 report spec（YAML）
+  │
+  ├─ linkai build --spec <spec>            CLI 校验 AI 提供的 SQL/spec → 用户确认 → 执行 → 自动验收
+  │
+  └─ 方案知识库：版本、方案地址、方案说明、每张卡片的数据来源与取数逻辑（不输出完整 SQL）
+```
+
+AI 代理的统一入口是仓库根目录的 [`AGENTS.md`](../AGENTS.md)；Claude Code 另有 skill
+[`skills/linkai-report-builder/SKILL.md`](../skills/linkai-report-builder/SKILL.md)，内容与本目录一致。

package/knowledge/browser/README.md

@@ -0,0 +1,40 @@
+# LinkAI 浏览器能力说明
+
+LinkAI 是领谋（LinkMore）为 LinkMoreBI 提供的浏览器与站点自动化能力。下文说明它的组成、工作方式和安全边界。
+
+## 组成
+
+| 组件 | 作用 |
+|---|---|
+| `linkai` 命令行 | AI 代理或用户调用的入口；所有命令输出 JSON 信封 `{"ok":…,"data":…}` |
+| 本机守护进程 | 由 `linkai` 按需自动启动，只监听本机 `127.0.0.1:19835`，在命令行与浏览器扩展之间转发指令 |
+| LinkAI 浏览器扩展 | 安装在 Chrome 中（Manifest V3），通过本机 WebSocket 连接守护进程，用 Chrome 调试接口在页面里执行操作 |
+| 站点适配器 | 把某个网站的能力封装成结构化命令（如 `linkai …`）；纯接口站点不需要打开浏览器 |
+
+## 一条浏览器命令的执行过程
+
+1. AI 代理执行如 `linkai browser open https://bi.linkmore.com --session report`。
+2. `linkai` 检查本机守护进程，不在则自动拉起，并把指令发给它。
+3. 守护进程把指令转给已连接的 LinkAI 扩展。
+4. 扩展在**独立的标签页 / 标签组**中执行：打开页面、读取页面结构（`state` 给出可交互元素编号）、点击、输入、等待、截图等。
+   这些标签与用户正在使用的标签分开管理，不会打断用户浏览。
+5. 结果按原路返回，`linkai` 输出 JSON，AI 代理据此决定下一步。
+
+## 安全边界
+
+- 守护进程只接受本机连接，并校验专用请求头，网页里的脚本无法冒充命令行调用它。
+- 扩展只与本机守护进程通信，不向任何远程服务器上传浏览数据。
+- 站点凭据与会话保存在本机 `~/.linkai/`（权限 0600），不经过命令行参数，不输出到对话。
+- 本 CLI 对用户开放，**不具备操作数据库的能力**：不能直连数据库、不能执行任意 SQL、不能管理数据源；
+  领谋 BI 数据集只能查询空间选表清单中的租户视图，且必须是只读查询。
+
+## 常见问题
+
+| 问题 | 回答要点 |
+|---|---|
+| 需要一直开着浏览器吗？ | 不需要。领谋 BI 搭建是纯接口操作；只有截图验收、网页操作类命令（以及选择浏览器登录时）需要 Chrome 与 LinkAI 扩展 |
+| 会不会动我正在看的页面？ | 不会，命令在 LinkAI 管理的独立标签中执行 |
+| 怎么登录？要给 AI 密码吗？ | 不要把密码发给 AI。首次执行 `linkai login`，在领谋网页完成 OAuth 授权；之后自动续期 |
+| 怎么切换租户？ | 告诉 AI 要切换到哪个租户，它会执行 `linkai login --tenant <租户名>`，之后自动续登也回到这个租户 |
+| 怎么检查连接？ | `linkai doctor` |
+| 支持哪些页面操作？ | `linkai browser --help` 列出全部（打开、读取状态、点击、输入、选择、上传、等待、截图、控制台等） |

package/knowledge/data-dictionary/README.md

@@ -0,0 +1,35 @@
+# 数据字典知识库
+
+> 状态：已接入当前租户服务器的结构化只读接口 `/api/app/ai-kb`。本目录只说明使用规则，不保存或兜底真实租户内容。CLI 不提供知识库写入、数据库操作、SQL 生成或任意 SQL 执行能力。
+
+## 作用
+
+搭建报表时回答：用哪个数据源、哪张视图、哪些字段、怎样关联、业务口径和枚举是什么。BI 公共知识库负责“怎么搭建”，数据字典负责“用什么数据”。
+
+## 使用顺序
+
+```bash
+linkai kb-sources
+linkai kb-search --source <sourceId> --question "销售额按月怎么算"
+linkai kb-object --source <sourceId> --db <db> --object <view>
+linkai kb-docs --source <sourceId> [--category caliber] [--search 销售]
+linkai kb-doc --source <sourceId> --doc <docId>
+linkai ds-tables --search <view>
+```
+
+1. `kb-sources`：必须确认 `aligned:true` 并选择 `selectedForDatasets:true` 的 source；若为 false，先确认服务端探库或数据源配置，不能跨 source 混用元数据。
+2. `kb-search`：自然语言召回候选视图和文档片段。`score` 只是相关度，不是正确率。
+3. `kb-object`：核对字段名、类型和关系，不能只凭搜索片段写 SQL。
+4. `kb-docs` / `kb-doc`：读取 `caliber`、`enum`、`relation`、`datapoint`、`other` 文档。`kb-doc` 会自动分页并保证版本一致。
+5. `ds-tables`：最终确认 SQL 中每张视图都在当前数据集白名单。
+6. AI 根据用户需求和证据编写单条只读 SQL，再执行 `sql-check`；CLI 不自行生成业务 SQL。
+
+除 `kb-sources` 外的五个命令会拒绝与当前数据集 source 不一致的请求，返回 `AI_KB_SOURCE_MISMATCH`。
+
+## 失败规则
+
+- 404：source、对象或文档不存在，或当前租户无权查看；核对参数与租户。
+- 409：元数据尚未就绪，或文档分页读取期间发生变化；按提示等待、重试或联系维护方。
+- 503：知识库服务不可用；稍后重试。
+
+以上情况一律不读取本地占位文件。数据字典缺项、口径冲突、需要新视图或修改数据时，告诉用户联系领谋知识库或数据团队；不要尝试绕过。

package/knowledge/data-dictionary/_templates/enum.md

@@ -0,0 +1,7 @@
+# <枚举名>
+
+使用位置：<schema>.<view>.<字段>，…
+
+| 值 | 含义 | 排序 | 备注 |
+|---|---|---|---|
+| | | | |

package/knowledge/data-dictionary/_templates/metric.md

@@ -0,0 +1,5 @@
+# <业务域> 指标口径
+
+| 指标 | 定义（自然语言） | SQL 表达式 | 视图 | 粒度 | 去重键 | 可信度 |
+|---|---|---|---|---|---|---|
+| 销售金额 | <!-- 已支付订单的实付金额，含运费？ --> | <!-- SUM(t.sale_amount) --> | | | | 【待确认】 |

package/knowledge/data-dictionary/_templates/view.md

@@ -0,0 +1,29 @@
+# <schema>.<view>
+
+| 项 | 内容 |
+|---|---|
+| 业务域 | |
+| 粒度（一行代表什么） | |
+| 租户隔离 | 定义引用 `@tenant_code`【数仓定义/实测】 |
+| 刷新频率 / 延迟 | |
+| 主键 / 去重键 | |
+| 来源 | 数仓模型路径、负责人 |
+
+## 字段
+
+| 字段 | 中文名 | 类型 | 含义 | 取值 / 枚举 | 可空 | 备注（常见误用） |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+## 常用 SQL 片段
+
+```sql
+-- 说明适用粒度与过滤条件
+SELECT ...
+FROM <schema>.<view> t
+WHERE t.<日期字段> BETWEEN CAST($1 AS DATE) AND CAST($2 AS DATE)
+```
+
+## 已知问题
+
+- 【实测 YYYY-MM-DD，租户】…

package/knowledge/data-dictionary/enums/.gitkeep

@@ -0,0 +1 @@
+<!-- 按 ../_templates 的模板新增文件 -->

package/knowledge/data-dictionary/index.md

@@ -0,0 +1,12 @@
+# 数据字典索引
+
+> 预留：按下表格式逐行登记租户视图。为空时请用 `linkai ds-tables` 查看可用视图，并向用户确认口径。
+
+| 视图（schema.view） | 业务域 | 粒度 | 主要用途 | 文档 |
+|---|---|---|---|---|
+| <!-- scm_warehouse.ads_gop_sales_item_view --> | <!-- 商品经营 --> | <!-- 日 × 款 × 店 --> | <!-- 销售金额/件数 --> | <!-- views/scm_warehouse.ads_gop_sales_item_view.md --> |
+
+## 最近变更
+
+| 日期 | 视图/指标 | 变更 | 记录人 |
+|---|---|---|---|

package/knowledge/data-dictionary/metrics/.gitkeep

@@ -0,0 +1 @@
+<!-- 按 ../_templates 的模板新增文件 -->

package/knowledge/data-dictionary/views/.gitkeep

@@ -0,0 +1 @@
+<!-- 按 ../_templates 的模板新增文件 -->

package/knowledge/report-builder/README.md

@@ -0,0 +1,80 @@
+# 搭建报表知识库（领谋 BI / LMBI）
+
+在领谋 BI（`https://bi.linkmore.com`）上用接口搭建数据集、卡片、看板（分析方案）和数据报表。
+LMBI 是**纯接口站点**：`linkai` 直接调用 `https://bi-api.linkmore.com/api/app`，登录、换空间、搭建、发布都不需要浏览器；
+浏览器只用于 `shot` 截图验收。
+
+本知识库是 BI 搭建的强制执行约束，由服务器优先下发、CLI 内置版本缺省兜底。AI 不得脱离知识库自由搭建；知识库没有覆盖的结构、配置或步骤必须停下确认，不能自行猜测。
+
+| 文件 | 内容 |
+|---|---|
+| `SOP.md` | **动手前必读**：空间、固定操作顺序、可直接执行 / 需用户额外授权的动作、失败与回滚 |
+| `build-spec.md` | 自动搭建：report spec（YAML）字段说明、执行阶段、断点续跑、验收项 |
+| `references/` | 领域知识：铁律、接口、图表配置、查询引擎、筛选器、踩坑（按任务查，见下表） |
+| 代码 | `clis/linkai/commands.js`（命令注册）、`core.js`（会话/接口/白名单/生成器）、`build.js`（spec 编排）、`templates.js`（74 种图表骨架） |
+| 模版 | `templates/report-spec/`（spec 示例 + SQL + 明细表 spec + 筛选器 body） |
+
+## 登录（用户本人操作一次）
+
+```bash
+linkai login              # 首次在领谋网页完成 OAuth 授权
+linkai status             # 当前租户；autoRelogin:true 表示会自动续登
+linkai tenants            # 当前账号可用租户
+linkai login --tenant XX  # 同账号切换租户，无需重新授权
+linkai login --switch-account # 用户确认切换领谋账号后重新授权
+linkai logout             # 撤销并删除本机 OAuth 会话
+```
+
+只有一个当前租户；首次授权时在网页选择租户。OAuth 会话保存在 `~/.linkai/sites/linkai.session.json`（0600），过期自动续期。
+详见 `references/auth-space.md`（含给用户的完整操作步骤）。
+
+## 命令
+
+所有命令输出 JSON 信封 `{"ok":true,"data":…}`；失败时 `ok:false` 并带错误信息。`linkai <命令> --help` 查看参数。
+
+| 类别 | 命令 | access |
+|---|---|---|
+| 登录/租户 | `login`（含 `--tenant` 切换、`--switch-account` 重新授权）`logout`（write）· `status` `tenants` `kinds`（read） | |
+| SQL | `sql-check` `fmt`（read，本地只读校验 + 服务端字段推断） | |
+| 数据集 | `ds-list` `ds-tables` `ds-fields` `ds-refs` `ds-sql` `ds-match`（复用查重）（read）· `ds-create` `ds-update`（write） | |
+| 卡片 | `card-list` `card-get` `query`（read）· `card-save` `card-chart` `card-meter` `card-table` `card-gantt` `card-sort`（write） | |
+| 填报 | `fill-write --card <cardId> --file <records.json>`（默认预览，`--execute` 写入；一条记录一个元素、字段一次带齐） | write |
+| 工作流 | `flow-start --goal --type create\|modify\|import\|query` `flow-end --status delivered\|abandoned\|failed`（write）· `flow-status`（read）；任何命令可加全局参数 `--flow <id>` | |
+| 多会话协同 | `collab-start` `collab-task` `collab-claim` `collab-release` `collab-note` `collab-close`（write）· `collab-status`（read）；任何命令可加全局参数 `--worker <名称>`。多个会话或子代理改同一方案时先读 `linkai skills read linkai-collab -f plain` | |
+| 看板 | `plan-list` `plan-get`（read）· `plan-create` `plan-add` `plan-filter`（write） | |
+| 报表 | `report-list` `report-card`（read）· `report-publish` `reset-filter`（write） | |
+| **自动搭建** | `build --spec <yaml>`（仅新建，`operation:create`；默认 dry-run；`--execute` 写入；正式名需 `--confirm`；结果含完整方案知识库） | write |
+| **方案知识库** | 修改前 `plan-knowledge-get --plan <planId>` 读取；验收后在知识文件中填写 `changeSummary`，再用 `plan-knowledge --plan <planId> --mode update --file <yaml/json>` 保存完整新版本；历史方案自动补建 v1 | read / write |
+| 基线/清理 | `backup --type card\|plan\|ds --id <id>`（read）· `remove` `clean --prefix zz-…`（write） | |
+| 任意接口 | `api-get --path …`（read）· `api --method POST\|PUT\|DELETE --path … --body …`（write）；数据源/SQL/库表结构类接口被拦截 | |
+| 截图 | `shot --url <页面URL>`（浏览器） | write |
+
+写命令只接受精确 id（`dsId`/`cardId`/`planId`/`folderId`，来自各 `*-list`），名称参数只用于列表过滤。所有写命令返回回读结果。
+
+## 按任务读 references（不要全读）
+
+| 要干什么 | 读 |
+|---|---|
+| 登录 / 切换租户 / AUTH_REQUIRED | `references/auth-space.md` |
+| 写数据集 SQL、租户隔离 | `references/dataset.md`（口径与字段先查 `../data-dictionary/`） |
+| 按 demo 还原看板、视觉与布局基线 | `references/dashboard-patterns.md` |
+| 建卡片、AG 表格列/自定义渲染、显示格式、卡片自带筛选器 | `references/card.md` |
+| 新建或修正填报卡片、字段类型与角色 | `references/fill-import.md` |
+| 某种图表有哪些配置键 | `references/chart-config-schema.md` |
+| 选图表类型 | `linkai kinds` 或 `references/chart-types.md` |
+| 甘特图、指标卡、v2 独有图表 | `references/gantt.md` |
+| 建看板、发报表、标题卡、布局/背景、联动/钻取/跳转 | `references/report.md` |
+| 筛选器类型/运算/默认值/动态日期/分层/不过滤排查 | `references/filters.md` |
+| GROUP BY、排序、分页、总计、报错 | `references/query-engine.md` |
+| 常用接口实测 body / 任意接口路径 | `references/api.md` / `references/api-catalog.md` |
+| 动手前扫一眼 | `references/pitfalls.md` |
+
+## 已知限制
+
+- **截图**：部分环境下 CDP `Page.captureScreenshot` 会超时；`shot` 失败时仍返回页面地址、标题和登录状态，原因写在 `screenshotError`。
+- **没有网络抓包 / console 抓取**：查询问题用 `linkai query --card <cardId>`（返回实际执行 SQL 和数据库报错）；卡片白屏类渲染错误需人工打开 DevTools。
+- **未线上写入验证**：报表筛选器写进卡片 `filters` 的分层模型、`reset-filter --page-card`、联动/钻取/跳转；
+  `build` 的页面样式步骤（`update-page-card` 写背景与卡位透明）——首次使用先用 `zz-` 方案验证，或加 `--no-style` 跳过。
+- 联动、钻取、跳转、填报、推送等接口未封装，只能经 `api` 调用，且属于 SOP 中需要额外授权的范围。
+- **不具备操作数据库的能力**：数据集 SQL 只能是单条只读查询，表必须在 `ds-tables` 清单里（系统库一律拒绝）；不能管理数据源、不能改数仓。
+  清单外的视图需要领谋数据团队开放。

package/knowledge/report-builder/SOP.md

@@ -0,0 +1,91 @@
+# LMBI（领谋 BI）操作 SOP
+
+当用户要求查看、搭建或修改领谋 BI 的数据集、卡片、看板（分析方案）、数据报表、筛选器或排序时，使用 `linkai`。
+LMBI 是纯接口站点：adapter 直接调用 `https://bi-api.linkmore.com/api/app`，浏览器只用于 `shot` 截图验收。
+领域规则和接口细节见 `knowledge/report-builder/`。
+
+> **本知识库是 BI 搭建的强制执行约束，不是可选参考。** AI 必须先读本 SOP，再按任务读取对应篇章；不得凭模型经验自由发明接口、字段角色、图表配置、筛选器结构或操作步骤。知识库缺失、不可用或没有覆盖需求时，停止写操作并说明缺口。
+
+新建或修正填报卡片时，先读 `references/fill-import.md` 的硬性规则，保存后按该篇要求做页面验收。
+
+> **本 CLI 对用户开放，不具备操作数据库的能力**：不能直连数据库、执行任意 SQL、管理数据源或改数仓。
+> 数据集只能是单条只读查询、只能查 `ds-tables` 清单里的视图（本地先校验）；缺视图或数据问题请用户联系领谋数据团队。
+> 数据集 SQL 必须由 AI 根据用户需求、当前租户服务器下发的数据字典、实时 `ds-tables`/`ds-fields` 和用户确认的业务口径编写。CLI 只负责校验、保存、编排和验收，不自行生成业务 SQL。
+
+## 先确认租户
+
+- 只有一个当前租户。动手前 `linkai status` 看 `tenantName`，和用户确认就是要搭建的租户；不是就 `linkai login --tenant <租户名>`。
+- 返回 `AUTH_REQUIRED`：把 `references/auth-space.md`「给用户的操作步骤」交给用户，请用户执行 `linkai login`，在领谋网页完成 OAuth 授权。**不要在对话里索要密码。**
+- 用户说“好了”后执行 `linkai tenants`，核对当前租户。同账号切换租户用 `linkai login --tenant <租户名>`，无需浏览器重新授权。
+
+## 先确认新建还是修改
+
+- 用户明确说新建：使用 `operation: create`，方案知识库从 v1 开始。
+- 用户明确说修改：先用列表和回读定位精确 `planId`，执行 `plan-knowledge-get` 读取现有知识，修改完成后执行 `plan-knowledge --mode update`；已有知识库版本递增，历史方案没有知识库时自动补建 v1。
+- 用户没有说明：写入前必须先询问，不能凭同名方案或本地 state 自行判断。
+
+## 固定顺序
+
+> 整套新建看板优先用声明式自动搭建 `linkai build --spec …`（`build-spec.md`），它按下面的顺序编排并自动回读验收；
+> 修改已有对象、单点调整时按下面的步骤手工执行。
+
+1. **登录**：`linkai status`；返回 `AUTH_REQUIRED` 就请用户执行首次登录（见上）。OAuth 会话过期时自动续期。
+2. **租户**：`status` 的 `tenantName` 必须是用户要搭建的租户，不是就 `linkai login --tenant <租户名>`。
+   **切换租户后必须重新读取新租户的数据字典**（`kb-sources` → `kb-search` / `kb-object` / `kb-doc`），数据字典会不定时更新，不能沿用其它租户或旧的结论；
+   CLI 在写 SQL（`ds-create` / `ds-update` / `build --execute`）前强制校验，未读或服务端已更新返回 `DICTIONARY_REQUIRED`。
+3. **精确定位**：用 `ds-list` / `card-list` / `plan-list` / `report-list` 找对象，写操作只接受列表里的精确 id
+   （`dsId` / `cardId` / `planId` / `folderId`）。名称只用于过滤，同名多个时停下来问用户。
+4. **只读检查**：`ds-sql`、`ds-fields`、`ds-refs`、`card-get`、`plan-get`、`query`，确认现状和影响范围
+   （改数据集前看 `ds-refs`：被哪些卡片引用）。
+5. **基线**：修改已有对象前 `linkai backup --type card|ds|plan --id <id>`，保存到 `~/.linkai/artifacts/linkai/backups/`。
+   新建对象不需要基线。
+6. **先查再建（复用）**：新建数据集前用 `linkai ds-match --file <sql>` 查当前租户里有没有完全一样或相似的数据集；`build` 的 dry-run 结果 `reuse` 里也会列出可复用的数据集和卡片。
+   完全一样的直接复用（spec 的 datasets 写 `id`，或 spec 加 `reuse: auto`）；相似的比较 `columns` 与口径后决定复用、在原数据集上调整（先 `ds-refs` 看影响），还是新建。
+   `ds-create` 遇到完全一样的数据集会拒绝（`DUPLICATE_DATASET`），确需独立一份要说明理由后加 `--allow-duplicate`。复用的数据集、卡片是共享对象，不要为了自己的方案原地修改。
+7. **最小写入**：只改用户指定的对象和字段。临时/试验对象一律用 `zz-<任务名>-` 前缀命名。
+8. **写后回读**：生成器与 `card-save`、`ds-create/update`、`plan-add/filter`、`report-publish`、`card-sort` 都会返回回读结果；
+   再用 `linkai query --card <cardId>` 核对 `code`、`total`、`sql`，必要时 `linkai shot --url <URL>` 截图。
+9. **方案知识库**（方案搭建完成必做）：完整呈现版本、方案地址、方案内容、解决的问题，以及每张业务卡片的数据集、数据来源、粒度和取数逻辑/规则。
+   新建方案使用 `build --execute` 返回的 `planKnowledge.content`；修改方案执行 `linkai plan-knowledge --plan <planId> --mode update --file <知识文件>`。不输出完整 SQL，不展示服务器上传信息。
+
+OAuth 会话过期时，CLI 自动续期并保留当前租户。
+
+## 可以直接执行
+
+- 全部只读命令：`status`、`tenants`、`kinds`、`sql-check`、`fmt`、`ds-list/ds-tables/ds-fields/ds-sql/ds-refs`、`card-list/card-get`、`query`、
+  `plan-list/plan-get`、`report-list/report-card`、`backup`、`api-get`，
+  以及不带 `--execute` 的 `build`（只校验、输出执行计划）。
+- 在用户要求搭建/修改的范围内：新建 `zz-` 前缀的数据集/卡片/看板做试验，
+  修改用户点名的卡片或数据集，名字全部为 `zz-` 前缀的 `build --execute`，验收后同步 `plan-knowledge`，以及 `clean --prefix zz-<本任务>-` 清理自己建的临时对象。
+
+## 需要用户额外明确授权
+
+| 动作 | 影响 |
+|---|---|
+| `build --execute --confirm`（spec 含正式名：dry-run 的 `formalNames` 非空） | 建出对所有空间成员可见的正式数据集/卡片/方案/报表；先把 `formalNames` 与执行计划给用户确认 |
+| `remove --folder <folderId>` 删除任何非 `zz-` 前缀的数据集/卡片/看板/报表 | 进回收站，仍影响正在使用的人 |
+| `report-publish` 正式名报表、把卡片加入**他人在用**的看板 | 对所有空间成员可见 |
+| `plan-filter`（覆盖看板筛选器模板，全量覆盖、不在数组里的会被删） | 所有用户下次重置后生效 |
+| 修改**已被看板/报表引用**的卡片或数据集（`ds-update`、`card-save`、`card-sort`） | 所有挂载处同步变化 |
+| 切换到用户没提到的租户后写入（`login --tenant`） | 写入落到另一个租户 |
+| `api --method POST/PUT/DELETE` 调未封装接口 | 无 REST 语义保证，POST 可能新建对象 |
+| 角色/用户、填报回写、推送相关接口 | 空间配置或对外发送，默认不做 |
+| `fill-write --execute` 写填报数据；删除填报记录（`/index-block/del-new-fill-field-value`） | 写入/删除客户业务数据；先给预览和记录清单，删除必须用户明确同意并先备份 |
+
+数据集 SQL 只能是单条只读查询；本 CLI 不提供任何数据库、数据源、数仓写入或管理能力（相关接口在 `api` 透传中也被拦截）。
+
+## 失败和回滚
+
+- **判断是否已写入**：写命令报错后，先用对应的只读命令（`card-list`/`ds-list`/`plan-get`）确认对象是否已建出或已变化。
+  `card-chart/table/gantt/meter` 是"先 new 建壳、再 update-new 落配置"两步：若第二步失败，会留下一个空壳卡片，
+  用返回或 `card-list` 找到它，`zz-` 前缀直接 `clean`，正式名告诉用户后再删。
+- **回滚卡片**：`linkai card-save --file <~/.linkai/artifacts/linkai/backups/card-<id>-*.json>`，再 `query` 核对。
+- **回滚数据集**：`linkai ds-update --ds <dsId> --name <名称> --file <backups/ds-<id>-*.sql>`（id 不变，卡片映射不断）。
+- **回滚看板筛选器**：从 `backups/plan-<id>-*.json` 取 filters 重新组 body 走 `plan-filter`。
+- **误删**：回收站接口 `POST /index-block/get-recycle-station-page-list` / `revocer-recycle-station` 可恢复，执行前取得用户同意。
+- 不要用重复执行写命令来"修复"未知状态；先回读，再决定。
+
+## 凭据与产物
+
+- 本机仅保存 OAuth 会话和刷新令牌（`~/.linkai/sites/linkai.session.json`，0600）；AI 不读取或输出其内容。旧版保存的账号密码在首次使用时自动删除。
+- 基线、截图、取数结果保存在 `~/.linkai/artifacts/linkai/`（已忽略），可能含业务数据，不粘贴到对话。

package/knowledge/report-builder/build-spec.md

@@ -0,0 +1,79 @@
+# 自动搭建：report spec 与 `linkai build`
+
+一份 YAML（或 JSON）描述一张新看板：数据集、卡片、分区布局、筛选器、要发布的报表，以及最终方案知识库所需的业务语义。`build` 按依赖顺序编排已有命令，
+把 SOP 的「最小写入、写后回读、正式名需授权」固化下来。完整示例：`templates/report-spec/report.example.yaml`。
+
+## 工作流（AI 代理照做）
+
+1. **确认任务类型与租户**：先确认用户要新建还是修改；不明确就询问。`build` 只用于新建，spec 必须写 `operation: create`。再用 `linkai status` 核对当前租户。
+2. **摸数**：先 `linkai kb-sources` 选择与数据集一致的 source，用 `kb-search` 找候选、`kb-object` 核对字段和关系、`kb-docs`/`kb-doc` 读取口径与枚举；
+   再用 `linkai ds-tables` 确认视图白名单，已有数据集字段可用 `ds-fields` 查看。口径不确定时向用户确认，并列明时间范围、去重键、状态枚举。
+3. **AI 写 SQL 与 spec**：AI 根据用户需求、数据字典和已确认口径编写每个 SQL 文件，再从模版复制并修改 spec；CLI 不自行生成业务 SQL。试验阶段所有名字用 `zz-<任务名>-` 前缀。
+   单条 SQL 先 `linkai sql-check --file x.sql` 校验（白名单 + 字段推断）。
+4. **dry-run**：`linkai build --spec spec.yaml`。看 `steps`（执行计划）、`layout`（每块坐标）、`formalNames`（正式名清单）。
+   校验失败或缺授权时命令以退出码 2 失败（`{"ok":false,"error":{"code":"ARGUMENT",…}}`），message 里逐条列出问题。
+5. **执行**：`linkai build --spec spec.yaml --execute`。含正式名时，**先把 `formalNames` 给用户确认**，得到明确授权后再加 `--confirm`。
+6. **看验收**：命令成功不等于搭建成功——必须看 `data.ok` 与 `data.verify.checks`，全部 `ok:true` 才算完成；失败项按 `detail` 处理（`query` 的 message 是数据库报错）。
+   有浏览器时再 `linkai shot --url "https://bi.linkmore.com/view/plan?plan=<planId>"`。
+7. **交付**：完整呈现结果里的 `planKnowledge.content`，包括版本、方案地址、方案说明，以及每张业务卡片的数据集、数据来源、粒度和取数逻辑/规则。不要输出完整 SQL，也不要展示服务器上传信息。
+8. **收尾**：试验通过后，把 spec 里的 `zz-` 名换成正式名重新 build（或保留试验对象由用户决定），`linkai clean --prefix zz-<任务名>-` 清理。
+
+## 字段
+
+| 路径 | 必填 | 说明 |
+|---|---|---|
+| `version` | 是 | 固定 `1` |
+| `operation` | 是 | 固定 `create`；修改已有方案不用 `build` 猜测，完成修改后执行 `plan-knowledge --mode update` |
+| `name` | 是 | 方案（看板）名 |
+| `tenant` | 否 | 租户名 / 编码 / id；执行时与当前登录租户核对，不一致就停下 |
+| `knowledge.summary` / `problem` | 是 | 方案包含什么、解决什么问题；最终完整呈现给用户 |
+| `knowledge.rules` | 否 | 方案公共时间、状态、筛选、去重等规则 |
+| `layout.contentX` / `contentWidth` | 否 | 默认 `2` / `20`（24 格画布居中，`references/report.md`「方案左右留白」） |
+| `layout.pageBackgroundColor` | 否 | 默认 `#F4F3EE`（`references/dashboard-patterns.md` §0） |
+| `layout.titleHeight` | 否 | 分区标题卡高度，默认 `2` |
+| `reuse` | 否 | 复用查重：`suggest`（默认，dry-run 在 `reuse` 里列出可复用对象）/ `auto`（当前租户里完全一样的数据集、卡片直接复用，不再新建）/ `off` |
+| `datasets[]` | | `key` + (`name` + `sql` 文件路径) 新建；或 `key` + `id` 复用已有数据集；`reuse: false` 表示这个数据集不参与自动复用 |
+| `cards[]` | | `key`、`type`、`dataset`（数据集 key），按类型补字段（下表）；`sort` 可选，写法同 `card-sort --spec`；`reuse: false` 不参与自动复用。自动复用的已有卡片是共享对象，不会改它的排序 |
+| `cards[].knowledge` | 是 | `content`、`source`、`grain`、`dataLogic` 必填，`rules` 可选；每张业务卡片生成一个独立知识段落 |
+| `sections[]` | | 自上而下的分区：`title`（`serial`/`title`/`subtitle`，可省）+ `rows[]` |
+| `sections[].rows[]` | | `height`（格）+ `cards[]`（`card` = 卡片 key，`width` 可省 = 均分剩余宽度） |
+| `filters` | 否 | 方案筛选器 body（JSON 文件），**全量覆盖**；格式见 `references/filters.md` §2 与 `references/api.md` |
+| `publish.reports[]` | 否 | `card`（卡片 key）+ `name`：把卡片发布为数据报表 |
+
+### 卡片类型
+
+| `type` | 字段 | 对应命令 |
+|---|---|---|
+| `chart` | `name`、`kind`（`linkai kinds`）、`dim`（列表，第一个当 x 轴）、`meas`（列表）、`series`（可选） | `card-chart` |
+| `meter` | `name`、`col`、`subtitle`、`color` | `card-meter`（`meter/list`） |
+| `table` | `spec`：内联对象或 `.json` 路径（格式见 `references/card.md`「一把出」，`spec.name` 必填）；默认开启自适应宽度，`spec.fitTableWidth: false` 才关闭；列的 `width` 是比例 | `card-table` |
+| `gantt` | `spec`：同上（`references/gantt.md`） | `card-gantt` |
+| `existing` | `id`：已有卡片 id，只参与布局 | — |
+
+头部多指标统计卡的基线是 `meter/meterList` 类型六（`references/dashboard-patterns.md` §1），生成器暂未覆盖：
+先用 `meter` 或 `existing` 占位，建好后 `card-get` → 按 `references/card.md` 改 `chartSetting` → `card-save`。
+
+### 筛选器占位符
+
+`filters` 文件里可以写：`{{plan}}`（方案 id）、`{{pageCard:<卡片key>}}`（该卡片在方案里的 pageCardId，用于
+`bindUserPageCards[].pageCardId`）、`{{dataset:<数据集key>}}`、`{{dataSource}}`。引用不存在的 key 会直接报错。
+顶层必须 `"isTenantSystem": true`（租户系统模板）。
+
+## 执行阶段（`--execute`）
+
+| 阶段 | 做什么 | 关键约束 |
+|---|---|---|
+| 1 数据集 | `ds-create` 同款逻辑：白名单校验 → 格式化 → 去结尾分号 → 保存 | 表不在白名单直接失败 |
+| 2 卡片 | 生成器建卡（new + update-new 两步），有 `sort` 则设持久排序并回读 `sqlHasOrderBy` | 列名必须与数据集列别名一致 |
+| 3 方案与布局 | 建空方案；`new-page-card` 直接带目标坐标落位；标题卡 `cardType:5`（单行、无装饰线） | PC 在内容区内、PC/手机无重叠（dry-run 已校验） |
+| 4 页面样式 | `update-page-card`：页面背景色；标题卡与 `meter` 卡位透明；有分区标题时隐藏数据卡外层标题 | 写前回读，缺卡或方案详情不全则跳过并在结果里说明；`--no-style` 可跳过 |
+| 5 筛选器 | 替换占位符 → `plan-filter`（全量覆盖 + reset-user-filter 回读） | |
+| 6 报表 | `operate-report` 发布 | 正式名需 `--confirm` |
+| 7 验收 | 逐卡 `query`（code 200）、方案回读（卡片齐全、越界、重叠、背景色）、排序生效 | `verify.ok` 为总结论 |
+| 8 方案知识库 | 线上回读方案 → 卡片 → 数据集，与 AI 提供的 knowledge 合并，生成版本化完整知识库并保存到服务器 | 服务不可用时内部写入 `~/.linkai/artifacts/linkai/plan-knowledge/` 待同步；最终只向用户呈现知识正文 |
+
+**断点续跑**：每完成一步写入 `<spec 文件>.state.json`（记录已建对象 id）。中途失败修正后重跑同一命令，已完成的步骤跳过，不会重复建对象。
+要从头重建：删除 state 文件（并先 `clean` 掉已建的 `zz-` 对象）。state 文件含对象 id，不含凭据。
+
+**失败处理**：不要重复执行来"修复"未知状态；先看返回的 `log` 与 state 文件，再用只读命令（`ds-list`/`card-list`/`plan-get`）确认现状。
+回滚规则见 `SOP.md`「失败和回滚」。

package/knowledge/report-builder/references/api-catalog.md

@@ -0,0 +1,106 @@
+# 常用接口目录
+
+> 领谋 BI 搭建报表相关、前端在用的接口。路径省略 `/api/app` 前缀（`linkai api` / `api-get` 会自动补）。
+> 优先使用已封装的 `linkai` 命令；数据源、SQL、库表结构等接口不对外开放，透传调用会被拒绝。
+
+查找：`linkai kb --file knowledge/report-builder/references/api-catalog.md` 后按关键字搜索。
+
+## `index-block`
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/index-block/new` | 新版指标创建 CalculationMode：1计算数量，2求和，3求平均 |
+| POST | `/index-block/update-new` | 修改新版指标 CalculationMode：1计算数量，2求和，3求平均 |
+| POST | `/index-block/new-fill-field` | 写自由填报：body `{usedIndexBlockId, fillValues:[{key:"fillfieldid", value?, fillFieldValue}]}`，一条记录一个元素；优先用 `linkai fill-write` |
+| POST | `/index-block/get-new-fill-report` | 新版查询填报记录 |
+| POST | `/index-block/del-new-fill-field-value` | 删除填报记录：body `[{ids:[记录ID], isFreeFill, indexBlockDataId:<卡片数据集ID>}]`；需用户明确同意 |
+| POST | `/index-block/save-new-index-block-fill-color` | 新版保存填色值 |
+| POST | `/index-block/new-import-fill-data` | 新版导入填报文件 |
+| POST | `/index-block/save-fill-view` | 添加填报视图 |
+| POST | `/index-block/update-fill-view` | 更新填报视图 |
+| POST | `/index-block/del-fill-view` | 删除填报视图 |
+| POST | `/index-block/operate-report` | 添加或修改报表 报表列表入参 |
+| POST | `/index-block/get-new-index-block-detail` | 新版获取一个指标详情 指标块 |
+| GET | `/index-block/column-value-dimensions` | 获取列值 |
+| POST | `/index-block/get-filter-field-value-info` | 新版获取过滤条件的值 |
+| POST | `/index-block/get-new-index-block-data` | 新版指标获取数据 指标块id |
+| POST | `/index-block/get-data-set` | 数据集查询数据 指标块id |
+| POST | `/index-block/get-thrid-platform-data` | 获取同步数据信息 |
+| GET | `/index-block/{id}/new-get-index-block-data-setting-list` | 新版获取表单权限指标的字段信息 |
+| POST | `/index-block/new-get-index-block-data-power-list` | 新版获取数据权限详细信息 |
+| POST | `/index-block/new-save-index-block-data-power` | 新版保存数据权限 |
+| POST | `/index-block/new-get-column-power-list` | 新版获取列权限详细信息 |
+| POST | `/index-block/new-save-column-power` | 新版保存列权限详细信息 |
+| POST | `/index-block/new-get-fill-power-list` | 新版获取指标权限的填报 |
+| POST | `/index-block/new-save-fill-power-detail` | 新版保存指标权的填报信息 |
+| GET | `/index-block/new-get-fill-power-by-page-card/{usedIndexBlockId}` | 新版报表卡片获取填报权限 卡片ID |
+| POST | `/index-block/del-source-table` | 删除导入的表 |
+| GET | `/index-block/has-fill-table/{indexBlockDataId}` | 查看是否有填报表 |
+| POST | `/index-block/fill-table/{indexBlockDataId}` | 创建填报表 |
+| POST | `/index-block/get-data-set-infos` | 获取数据集列表 |
+| GET | `/index-block/data-set-quoted-infos/{indexBlockDataId}` | 获取数据集被引用信息 |
+| POST | `/index-block/operate-data-set-lock` | 锁定解锁数据集 |
+| POST | `/index-block/or-update-folder-bussiness` | 添加或修改文件夹 |
+| POST | `/index-block/delete-folder-bussiness` | 删除业务 |
+| GET | `/index-block/folders` | 获取树形文件夹 0方案, 1报表, 2大屏, 3数据集, 4指标 |
+| POST | `/index-block/get-index-block-data-folder-bussiness-info` | 获取数据集文件夹的列表 |
+| POST | `/index-block/get-index-block-folder-bussiness-info` | 获取指标文件夹的列表 |
+| POST | `/index-block/get-index-block-report-folder-bussiness-info` | 获取报表文件夹的列表 |
+| POST | `/index-block/get-page-setting-folder-bussiness-info` | 获取方案文件夹的列表 |
+| POST | `/index-block/get-page-screen-folder-bussiness-info` | 获取大屏文件夹的列表 |
+| POST | `/index-block/get-business-type-counts` | 获取文件夹列表七天内增长值 |
+| POST | `/index-block/copy-bussiness-data` | 业务复制功能 |
+| POST | `/index-block/get-bussiness-story` | 获取业务的故事 |
+| POST | `/index-block/save-bussiness-story` | 保存业务的故事 |
+| POST | `/index-block/get-recycle-station-page-list` | 获取回收站信息 |
+| POST | `/index-block/revocer-recycle-station` | 恢复回收站信息 |
+| POST | `/index-block/save-file-info-from-url` | 保存文件信息 文件URL链接 文件描述 |
+
+## `page-setting`
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/page-setting/get-new-page-card-list/{userPageSettingId}` | 新版根据方案id获取该方案的卡片信息 |
+| POST | `/page-setting/get-new-page-card-report` | 新版获取报表信息 报表Id |
+| POST | `/page-setting/get-new-page-plan/{userPageSettingId}` | 新版获取方案详情 是否为编辑模式；编辑模式直接读取租户系统级过滤条件，不复制个人条件 |
+| POST | `/page-setting/get-new-linkage-relations/{sourcePageCardId}` | 新版获取卡片的联动关系 源卡片id 字段索引 |
+| POST | `/page-setting/get-page-card/{pageCardId}` | 获取单个卡片信息 |
+| POST | `/page-setting/get-new-page-card/{pageCardId}` | 新版获取单个卡片信息 |
+| GET | `/page-setting/user-config` | 查询用户全局配置 |
+| POST | `/page-setting/new-create-empty-plan` | 新版创建一个空方案 |
+| PUT | `/page-setting/plan-mobile-flag` | 更新方案手机标识 |
+| POST | `/page-setting/page-card` | 新增一个卡片 |
+| POST | `/page-setting/new-page-card` | 新版新增一个卡片 |
+| POST | `/page-setting/update-page-card` | 修改卡片,只能修改宽度，高度，坐标 |
+| POST | `/page-setting/new-update-page-card-index-block` | 修改卡片指标的ChartSetting |
+| POST | `/page-setting/new-update-page-card-index-block-width-height` | 新版修改卡片指标的宽高 |
+| POST | `/page-setting/new-update-page-card-index-block-direction` | 新版修改卡片指标的宽高 |
+| GET | `/page-setting/page-card-direction/{usedIndexBlockId}` | 获取卡片的横竖屏设置 |
+| PUT | `/page-setting/page-card-index-block-sort-field` | 修改卡片指标的排序字段 |
+| POST | `/page-setting/replace-page-card` | 替换一个卡片 |
+| DELETE | `/page-setting/page-card/{pageCardId}` | 删除一个卡片 |
+| POST | `/page-setting/batch-add-or-update-filter` | 新增修改一批过滤条件 |
+| POST | `/page-setting/reset-user-filter` | 重置当前用户的过滤条件。 卡片条件重置为来源指标条件；方案条件按业务层级重置为后台原始模板或租户系统模板。 |
+| PUT | `/page-setting/filter-value` | 修改过滤条件的默认值 |
+| GET | `/page-setting/variable-list` | 获取变量下拉框数据源 |
+| POST | `/page-setting/get-new-target-page-card-all-list` | [以卡片关联]获取全部的卡片 |
+| POST | `/page-setting/linkages-save` | 联动关系保存 返回开关状态 |
+| POST | `/page-setting/update-drill-switch` | 修改钻取开关状态 |
+| POST | `/page-setting/get-drill-relation-list` | 查询在钻取关系列表 |
+| POST | `/page-setting/new-link-card/{indexBlockId}` | 新版创建一个跳转卡片 |
+| POST | `/page-setting/link-add-or-update` | 更新卡片数据跳转 |
+| POST | `/page-setting/get-new-link-info/{pageCardId}` | 新版获取卡片数据跳转数据 |
+| POST | `/page-setting/get-new-target-query-transfer` | 新版获取卡片跳转的选项数据 当前卡片id 选中的跳转目标值，指标卡片Id 跳转类型：1指标卡片，2分析页面，3链接 |
+| POST | `/page-setting/get-new-target-query` | 获取卡片跳转、联动的选项数据 |
+| GET | `/page-setting/link-names` | 获取跳转链接 |
+| POST | `/page-setting/get-link-params` | 跳转业务单据通过Code换取调整链接 |
+| POST | `/page-setting/get-new-index-block-data` | 获取新版指标数据 指标块id |
+| POST | `/page-setting/get-thrid-api-url` | 第三方获取api链接 |
+| POST | `/page-setting/save-page-setting-refersh-param` | 保存方案自动刷新参数 |
+| POST | `/page-setting/new-export-fill-tempelate` | 新版导出填报模板 |
+
+## `options-config`
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/options-config/get-select-option-values/{optionsConfigId}` | 获取下拉框值的数据源 配置id 选项code |