@linkaicli/linkai-cli 0.0.0-stage → 1.0.17

package/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md — LinkAI-CLI（给 AI 代理）
+
+本仓库是 **LinkAI-CLI**（命令 `linkai`），LinkMoreBI.CLI 的浏览器与站点自动化底层能力，设计上由 AI 代理调用
+（Codex、Claude Code、DeepSeek 等）。本文件是所有代理的统一入口。
+
+## 六条硬性规定（优先于本文其它内容）
+
+1. **没有操作数据库的能力**：本 CLI 对用户开放，不能直连数据库、执行任意 SQL、管理数据源或改数仓。
+   领谋 BI 数据集只能是单条只读查询，且只能查 `linkai ds-tables` 列出的租户视图；需要新视图或改数据时，告诉用户联系领谋数据团队。
+   不要尝试绕过（命令已在本地拦截，也不要用 `api` 透传去调数据源 / SQL 类接口）。
+2. **方案搭建完成必须交付完整方案知识库**：必须呈现方案地址、版本、方案内容与解决的问题，并按每张业务卡片分别描述卡片内容、数据集、数据来源、粒度和取数逻辑/规则。
+   不再向用户输出完整数据集 SQL。`build --execute` 自动生成；手工修改方案后用 `linkai plan-knowledge --plan <planId> --mode update --file <知识文件>` 同步。服务器不可用时 CLI 内部留存本地，不向用户展示上传信息。
+3. **浏览器能力类问题**：用户问到浏览器能力或工作原理时，先读《浏览器能力说明》（`linkai kb --file knowledge/browser/README.md`），以该文为准回答，不补充文中没有的内容。
+4. **BI 报表必须严格按公共知识库搭建**：开始 BI 任务先读 `knowledge/report-builder/SOP.md`，再按任务读取对应篇章；知识库是执行约束，不是可选参考。
+   不得凭模型经验自由发明接口、字段角色、图表配置、筛选器结构或搭建步骤。知识库缺失、不可用或没有覆盖需求时，停止写操作并把缺口告诉用户。
+5. **数据集 SQL 由 AI 根据需求编写**：先读取当前租户的数据字典，再用 `ds-tables`/`ds-fields` 核验，结合用户确认的口径编写 SQL 文件。
+   CLI 只负责只读/白名单校验、保存、编排和验收，不自行推导或生成业务 SQL；模版里的 SQL 只能作为格式示例，不能直接当作用户方案。
+6. **写方案前必须区分新建或修改**：用户已明确时按其要求；不明确时先主动询问，不能凭同名对象自行判断。新方案用 `operation: create`，知识库从 `v1` 开始；修改原方案必须定位精确 `planId`，先 `plan-knowledge-get` 读取现有知识，完成后同步更新并递增版本。历史方案没有知识库时自动补建 `v1` 基线。
+
+## 调用约定
+
+- 所有命令输出 JSON 信封：成功 `{"ok":true,"data":…}`；失败退出码非 0，`{"ok":false,"error":{"code","message","hint?"}}`。日志走 stderr。
+- 发现命令：`linkai list <关键字>`；看参数：`linkai <site> <command> --help -f json`。不要凭记忆拼参数。
+- 写命令（help 中标 `[write]`）结果不确定时，先用只读命令确认现状，**不要重复执行来"修复"**。
+- **登录只使用 OAuth**：首次登录由用户执行 `linkai login`，在领谋浏览器页面完成授权；CLI 用刷新令牌自动续期。不索要账号密码。同账号切换租户用 `linkai login --tenant <租户名>`；用户要求切换账号时，先问是否要切换领谋账号，确认后执行 `linkai login --switch-account`。
+- 文件参数可用相对路径（相对当前目录）。
+
+## 领谋 BI 自动搭建报表（主要场景）
+
+1. 读规则：`linkai skills read linkai-report-builder -f plain`（或直接读 `skills/linkai-report-builder/SKILL.md`）。
+2. 读知识库：`linkai kb` 列出 BI 公共知识文件；`linkai kb --file knowledge/report-builder/SOP.md` 读取。
+   - 搭建报表知识库：`knowledge/report-builder/`（SOP、build-spec、references）
+   - 数据字典知识库：先 `linkai kb-sources` 取当前租户 source，再用 `kb-search` → `kb-object` → `kb-docs`/`kb-doc` 按需读取；最后用 `ds-tables` 校验 SQL 视图白名单
+   - 浏览器能力说明：`knowledge/browser/README.md`（浏览器能力与工作原理）
+3. `linkai status` 确认当前租户（只有一个当前租户）；返回 `AUTH_REQUIRED` 就把「首次登录」步骤交给用户；切换租户用 `linkai login --tenant <租户名>`。
+4. 新建看板用声明式 spec：`linkai template --output <目录>` 复制模版 → 由 AI 填完整 `knowledge` → `linkai build --spec <目录>/report.example.yaml`（dry-run）
+   → 用户确认 → `--execute`（含正式名需用户授权后再加 `--confirm`）→ 读 `verify.checks` → 完整呈现返回的 `planKnowledge.content`。
+5. 必须先征得用户同意的动作见 `knowledge/report-builder/SOP.md`「需要用户额外明确授权」。
+
+登录与租户：
+
+- **首次登录（用户本人在终端执行一次）**：Mac 打开「终端」、Windows 打开「PowerShell」，执行下面的命令，在弹出的领谋网页完成登录和租户授权：
+
+  ```bash
+  linkai login
+  ```
+
+- 用户说“好了”后执行 `linkai tenants`，确认本次 OAuth 授权的租户。同账号切换租户执行 `linkai login --tenant <租户名>`，无需重新打开授权页。
+- 之后登录过期会用 OAuth 刷新令牌自动续期。AI 可直接执行 `linkai status` 和 `linkai tenants`。
+- 任何命令返回 `AUTH_REQUIRED` → 把上面的首次登录步骤交给用户，等用户说好了再继续。
+- 用户说“切换账号”等类似指令时，先询问是否要切换领谋账号；确认后执行 `linkai login --switch-account` 重新授权。
+
+## 通用系统提示（没有技能机制的 AI 工具，如 DeepSeek API 接入）
+
+执行 `linkai skills prompt` 输出系统提示（内容在 `skills/agent-prompt.md`），复制进该工具的系统提示，并给模型一个执行 shell 命令的工具。
+有技能机制的工具用 `linkai skills install <codex|claude|workbuddy|workbuddy-intl|codebuddy>` 安装，或 `--dir <技能目录>`。
+
+## 开发本仓库
+
+- 本地构建、安装、测试、扩展加载与常见问题：`DEVELOPMENT.md`。
+- 构建：`npm run build`（tsc + 生成 `cli-manifest.json`）；类型检查：`npm run typecheck`。
+- 测试：`npm test`（unit + extension + adapter）；只跑 LMBI：`npx vitest run clis/linkai`。
+- 站点适配器在 `clis/<site>/`，从 `@linkaicli/linkai-cli/registry` 导入 `cli`；`clis/linkai/` 是完整示例。
+- 知识库改动：新确认的 CLI/搭建结论标【实测】写回 `knowledge/report-builder/references/`；数据字典只读，缺项或错误反馈给知识库维护方，不在本仓库写租户口径。

package/GUIDE.md

@@ -0,0 +1,150 @@
+# LinkAI-CLI 安装与使用指南
+
+让 AI 助手（Codex、Claude Code、WorkBuddy、CodeBuddy、DeepSeek 等）帮你在领谋 BI 里自动搭建报表。
+整个过程你只需要：**安装一次、登录一次、接入一次 AI 工具**，之后直接对 AI 说需求。
+
+> 所有命令都在「终端」里执行：Mac 打开「终端」（启动台搜索“终端”）；Windows 打开「PowerShell」（开始菜单搜索“PowerShell”）。
+> 每一步都是：**复制命令 → 按说明修改尖括号或中文部分 → 回车执行**。
+
+---
+
+## 第 1 步：安装 Node.js（已安装可跳过）
+
+打开 https://nodejs.org ，下载 **LTS** 版本，双击安装，一路「下一步」。装完后**重新打开终端**，执行：
+
+```bash
+node --version
+```
+
+看到 `v20` 或更高的版本号即可。
+
+## 第 2 步：安装 LinkAI-CLI
+
+```bash
+npm install -g @linkaicli/linkai-cli
+```
+
+验证：
+
+```bash
+linkai --version
+```
+
+看到版本号即安装成功。
+
+> 安装包不依赖其它 npm 包，内网或断网时也可以直接 `npm install -g <安装包路径>.tgz` 安装。
+
+> Mac 若提示权限不足（`EACCES`），改用：`sudo npm install -g @linkaicli/linkai-cli`，按提示输入**电脑开机密码**。
+
+## 第 3 步：登录领谋 BI（只需一次）
+
+执行下面这行：
+
+```bash
+linkai login
+```
+
+在弹出的领谋网页核对终端与页面上的授权短码，完成登录并选择租户。
+CLI 保存授权后，原页面会显示所选租户授权成功；浏览器不会跳转本机临时端口。
+之后访问令牌过期会**自动续期**。
+
+AI 工具的技能可用 `linkai skills install <工具>` 安装（WorkBuddy、Codex、Claude Code、CodeBuddy）。
+
+- 同账号切换租户：`linkai login --tenant 你的租户名称`，无需重新授权。
+- 切换领谋账号：先确认切换意图，再执行 `linkai login --switch-account`，在网页重新授权。
+
+> **不要把密码发给 AI。** AI 也不会向你要密码。
+
+## 第 4 步：接入 AI 工具
+
+按下表为你使用的 AI 工具安装技能：
+
+| AI 工具 | 复制执行 | 之后 |
+|---|---|---|
+| Codex | `linkai skills install codex` | 新开一个 Codex 会话 |
+| Claude Code | `linkai skills install claude` | 新开一个会话 |
+| WorkBuddy（国内版） | `linkai skills install workbuddy` | 重启 WorkBuddy，在「技能管理」里确认 5 个 `linkai-` 技能已启用 |
+| WorkBuddy（海外版） | `linkai skills install workbuddy-intl` | 同上 |
+| CodeBuddy | `linkai skills install codebuddy` | 重启 CodeBuddy |
+| 其它支持「技能」的工具 | `linkai skills install --dir <该工具的技能目录>` | 按该工具说明重启 |
+| DeepSeek 等没有技能功能的工具 | `linkai skills prompt` | 把输出的整段文字复制到该工具的「系统提示 / 自定义指令」里，并确保它能执行终端命令 |
+
+**不想在技能列表里显示**（WorkBuddy、Codex、Claude Code 支持）：加 `--mode rules`，例如
+
+```bash
+linkai skills install workbuddy --mode rules
+```
+
+这样只会在该工具的全局规则文件里写入一小段说明（WorkBuddy：`~/.workbuddy/AGENTS.md`），技能列表里不会出现 linkai 的技能，AI 需要时会自己读取完整规则。
+之后想恢复成技能列表方式，去掉 `--mode rules` 重新执行即可；两种方式不会同时存在。
+
+> AI 工具第一次运行 `linkai` 命令时，可能会弹出「允许联网 / 允许执行命令」的确认，选择**允许**（可选「以后都允许 linkai 开头的命令」）。
+
+## 第 5 步：开始使用
+
+在 AI 工具里直接说，例如：
+
+- 「我现在在领谋 BI 的哪个租户？」
+- 「好了」（完成第 3 步后说，AI 会告诉你租户或请你选择默认租户）
+- 「帮我搭一个销售看板：本期销售金额、件数、按渠道的日趋势、商品明细，先给我看计划」
+- 「切换到 XX 租户」
+- 「把刚才那个方案的方案知识库给我」
+
+AI 会先给你看搭建计划（不会直接动手），你确认后才执行；正式发布、删除等操作也会先问你。
+搭建完成后，AI 会完整呈现：**方案知识库版本、方案地址、方案内容与解决的问题，以及每张业务卡片对应的数据集、数据来源、粒度和取数逻辑/规则**。完整 SQL 不作为交付物展示。
+
+## 升级
+
+**自动升级**：有新版本时，LinkAI-CLI 会在命令结束后于后台自动下载、校验并安装，下次运行即为新版本，并在结果里提示“已自动升级”；技能随之自动更新。不需要手动操作。
+确实需要关闭时设置环境变量 `LINKAI_NO_AUTO_UPGRADE=1`。
+
+手动升级（自动升级不可用时）：
+
+```bash
+linkai daemon stop                               # 先停后台服务，避免安装时文件被占用
+npm install -g @linkaicli/linkai-cli@latest      # 或：npm install -g <安装包路径>.tgz
+```
+
+升级后第一次运行任何 `linkai` 命令时，会自动把这台电脑上已装的 linkai 技能（或规则段）更新到新版本，并在结果里提示；之后新开一个 AI 会话即可。
+用 `--dir` 装到自定义目录的技能不会自动更新，需要再执行一次 `linkai skills install --dir <目录>`。
+
+### 从 1.0.16 及更早版本升级（一次性）
+
+1.0.17 起安装包改名为 `@linkaicli/linkai-cli`，并开始支持自动升级。之前装的是 `@linkmore/linkai-cli`，需要先卸载旧包再安装新包（登录、技能、本机数据都保留）：
+
+```bash
+linkai daemon stop
+npm uninstall -g @linkmore/linkai-cli
+npm install -g @linkaicli/linkai-cli
+linkai --version
+```
+
+之后的版本都会自动升级，不再需要手动操作。
+
+## 卸载
+
+```bash
+linkai daemon stop                # 先停止后台服务
+linkai skills uninstall codex        # 把 codex 换成你在用的 AI 工具
+linkai logout                   # 撤销并删除本机 OAuth 会话
+npm uninstall -g @linkaicli/linkai-cli
+```
+
+## 常见问题
+
+| 问题 | 解决 |
+|---|---|
+| 提示 `linkai: command not found` / 无法识别 linkai | 关掉终端重新打开；仍不行就重新执行第 2 步 |
+| 安装时提示 `EEXIST`，或 `linkai --version` 显示的不是本工具 | 电脑上装了另一个同名命令（如 link-ai.tech 的 linkai-cli）。先 `npm uninstall -g linkai-cli`，再重新执行第 2 步 |
+| 升级时报 `ENOTEMPTY … rename … .linkai-cli-XXXX` | 上次升级中断留下的临时目录。先 `linkai daemon stop`，删除 npm 全局目录下 `@linkaicli/` 里以 `.linkai-cli-` 开头的目录（只删这些），再重新安装 |
+| AI 说「需要登录」 | 按第 3 步执行 `linkai login` |
+| 改了领谋密码 | 如授权失效，重新执行 `linkai login --switch-account` |
+| 想换账号 | 确认后执行 `linkai login --switch-account` |
+| AI 说「没有可用视图 / 不能操作数据库」 | 这是正常的安全限制：需要的数据视图请联系领谋数据团队开通 |
+| 公共电脑 | 用完执行 `linkai logout`，撤销并删除本机 OAuth 会话 |
+| 检查整体状态 | `linkai status` |
+
+## 操作日志
+
+为改进产品和排查问题，LinkAI-CLI 会把每次命令的操作记录（命令名、参数、调用的接口路径、耗时、成功与否、错误码、调用它的 AI 工具及版本、AI 自报的模型名称）实时上报到领谋服务器，按你的租户和账号保存。
+不会上报密码、令牌、SQL 原文、填报的数据值或文件内容（文件只记大小和校验值）。暂时无法上报时先保存在本机 `~/.linkai/oplog/`，下次自动补传。

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 jackwener
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+LinkAI-CLI
+Copyright 2026 LinkMore
+
+This product includes software developed by third parties and licensed under
+the Apache License, Version 2.0. See the LICENSE file for the license terms.
+Files in this distribution have been modified from their original form.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# LinkAI-CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LinkMoreBI.CLI 的浏览器与站点自动化底层能力（命令 `linkai`），面向 AI 代理调用（Codex、Claude Code、DeepSeek 等）。
+
+- **站点适配器**：把网站 / 接口封装成结构化命令，统一 JSON 输出，写命令带回读。当前内置 **领谋 BI**（`linkai build`、`linkai status` 等）。
+- **浏览器桥接**：通过本机守护进程 + Chrome 扩展，在独立标签页里打开页面、读取状态、截图（`linkai browser …`）。
+- **自动搭建报表**：搭建报表知识库 + 数据字典知识库 + 声明式 spec，`linkai build` 一条命令完成
+  数据集 → 卡片 → 看板 → 筛选器 → 报表 → 验收，并输出完整、版本化的方案知识库（方案地址、方案说明，以及每张卡片的数据与取数规则；不输出完整 SQL）。
+- **不具备操作数据库的能力**：面向用户开放，不能直连数据库、执行任意 SQL 或管理数据源；数据集只能是只读查询、只能查空间选表清单里的视图。
+
+**用户安装与使用：见 [`GUIDE.md`](GUIDE.md)。** 本地构建与安装：见 [`DEVELOPMENT.md`](DEVELOPMENT.md)。AI 代理请从 [`AGENTS.md`](AGENTS.md) 开始。发布流程见 [`release/README.md`](release/README.md)。
+
+## 安装
+
+需要 Node.js >= 20.18.1。
+
+```bash
+npm install -g @linkaicli/linkai-cli     # 或在本仓库：npm ci && npm run build && npm link
+linkai --version
+```
+
+浏览器桥接（仅 `shot`、`browser` 类命令需要；领谋 BI 搭建是纯接口，不需要浏览器）：
+
+1. 打开 `chrome://extensions`，开启「开发者模式」。
+2. 「加载已解压的扩展程序」，选择本仓库的 `extension/` 目录（或发布包中的扩展目录）。
+3. `linkai doctor` 检查守护进程与扩展连接。
+
+## 领谋 BI 快速开始
+
+```bash
+linkai login                            # 首次登录：在领谋网页完成 OAuth 授权；之后自动续期
+linkai status             # 当前租户
+
+linkai template --output my-report                                                # 复制报表模版
+linkai build --spec my-report/report.example.yaml                                 # dry-run：执行计划 + 布局
+linkai build --spec my-report/report.example.yaml --execute                       # 新建、自动验收并生成方案知识库
+linkai plan-knowledge --plan <planId> --mode update --file plan-knowledge.yaml     # 修改原方案后同步方案知识库
+```
+
+全部命令：`linkai --help`；知识库：`linkai kb`；规则：`linkai skills read linkai-report-builder -f plain`。
+
+## 在 AI 工具中使用
+
+```bash
+linkai skills install codex     # 安装到 Codex（~/.codex/skills），装完新开一个会话
+linkai skills install claude    # 安装到 Claude Code（~/.claude/skills）
+```
+
+升级 linkai 后，第一次运行任何命令会自动更新本机已装的技能（`--dir` 自定义目录除外）。没有技能机制的模型（如 DeepSeek API 接入），把 `AGENTS.md` 里的「通用系统提示」放进系统提示。
+在 Codex 里首次运行 `linkai` 时，如果弹出联网或写入 `~/.linkai` 的授权请求，选择允许（可选「以后都允许 linkai 开头的命令」）。
+
+## 目录
+
+| 路径 | 内容 |
+|---|---|
+| `src/` | CLI 核心：命令注册、执行、输出、守护进程、浏览器桥接 |
+| `extension/` | Chrome 扩展（浏览器桥接） |
+| `clis/linkai/` | 领谋 BI 适配器：`commands.js`、`core.js`、`build.js`、`templates.js` |
+| `knowledge/report-builder/` | 搭建报表知识库（SOP、build-spec、references） |
+| `knowledge/data-dictionary/` | 数据字典知识库（预留） |
+| `knowledge/browser/` | 浏览器能力说明 |
+| `templates/report-spec/` | 自动搭建报表模版 |
+| `skills/` | AI 技能：`linkai-report-builder`、`linkai-data-workflow`、`linkai-collab`（多会话协同）、`linkai-usage`、`linkai-browser` |
+
+## 本地数据
+
+`~/.linkai/`：`sites/`（站点凭据与会话，0600）、`artifacts/`（基线、截图、取数结果）、守护进程状态。
+可用 `LINKAI_SITE_CONFIG_DIR`、`LINKAI_ARTIFACTS_DIR` 改位置。版本检查默认关闭（设置 `LINKAI_UPDATE_URL` 启用）。
+
+## 开发
+
+```bash
+npm ci
+npm run build          # tsc + 打包 dist/bundle（发布用单文件）+ 生成 cli-manifest.json
+npm run typecheck
+npm test               # unit + extension + adapter
+```
+
+本地安装（开发链接 / 按用户方式安装）、扩展加载、模拟用户全流程与常见问题见 [`DEVELOPMENT.md`](DEVELOPMENT.md)。
+
+## 许可
+
+Apache License 2.0，见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。