@finebi/finebi-cli 1.6.3 → 2.0.0

package/README.md

@@ -12,6 +12,8 @@ npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
 
 This package includes the CLI and the complete `finebi-cli-agent` Skill. Contact service personnel to obtain the FineBI server plugin and have an administrator install or enable it before connecting to FineBI.
 
+For the five-step installation, authentication and verification flow, see the bundled [Agent installation guide](agent-installation-guide.md).
+
 ## Usage
 
 Built-in help is always available and does not require server config, login, or a capability refresh:
@@ -145,7 +147,7 @@ finebi-cli install-skill --list
 finebi-cli install-skill --agents codex,cursor
 ```
 
-Run `finebi-cli install-skill` in an interactive terminal to choose Agents. Non-interactive use requires `--agents`. Supported IDs are `claude-code`, `codex`, `cursor`, `gemini-cli`, `github-copilot`, `opencode`, `cline`, `windsurf`, `trae`, `trae-cn`, `openclaw`, `roo`, and `qwen-code`. Custom `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and `XDG_CONFIG_HOME` directories are respected.
+Run `finebi-cli install-skill` in an interactive terminal to choose Agents. Non-interactive use requires `--agents`. Supported IDs are `claude-code`, `codex`, `dsh`, `cursor`, `gemini-cli`, `github-copilot`, `opencode`, `cline`, `windsurf`, `trae`, `trae-cn`, `openclaw`, `roo`, and `qwen-code`. Custom `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `DSH_HOME`, and `XDG_CONFIG_HOME` directories are respected. For DeepSeek Harness, use `finebi-cli install-skill --agents dsh`; Skills are installed to `~/.dsh/skills` by default, or `<DSH_HOME>/skills` when `DSH_HOME` is set.
 
 Skill installation is local and does not require a server connection or credentials. It copies the Skill included in this installed npm version, including its own CLI runtime. Restart your Agent or refresh its Skills after installation. npm installation alone does not install Skills into Agent directories.
 

package/agent-installation-guide.md

@@ -0,0 +1,70 @@
+# FineBI CLI 安装指南
+
+以下步骤面向 AI Agent，登录授权需要用户配合完成。执行前确认已安装 Node.js 18.17 或更高版本（含 npm）。
+
+## 第 1 步 安装 CLI
+
+```shell
+npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
+finebi-cli version
+```
+
+## 第 2 步 安装 Skill
+
+查询当前版本支持的 Agent，将示例中的 `codex` 替换为实际目标，如 `claude-code`、`cursor`、`dsh`（DeepSeek Harness）；多个目标用逗号分隔。WorkBuddy 仅在列表中出现 `workbuddy` 时选用。目录及环境变量约定见 [CLI 使用说明](README.md#agent-skills)。
+
+```shell
+finebi-cli install-skill --list
+finebi-cli install-skill --agents codex
+```
+
+安装后刷新技能或重启 Agent，确认已加载 `finebi-cli-agent`。若提示本地 Skill 有修改，保留并告知用户，不自动覆盖。
+
+升级时重复第 1、2 步：更新 npm 包不会自动更新已安装到 Agent 目录的 Skill；重新安装 Skill 后再次刷新技能或重启 Agent。
+
+## 第 3 步 确认插件依赖
+
+请用户联系服务人员获取与 FineBI 环境匹配的 **FineBI CLI Agent Interface** 插件（`com.finebi.plugin.finebi.cli`），由管理员在 FineBI 插件管理中安装并启用。本机 npm 和 Skill 安装不包含服务端插件部署。
+
+## 第 4 步 登录认证
+
+向用户获取 FineBI 决策平台根地址，先查看已有环境：
+
+```shell
+finebi-cli auth list --json
+```
+
+已有目标环境时，使用 `finebi-cli config get --profile <名称>` 核对地址，再复用该名称；新服务器使用新的环境名。不要直接改写现有环境的 `base-url`，它会清除该环境的凭据和能力缓存。以下以 `bi` 为示例，将名称和地址替换为已确认的目标；`--no-use` 保留原默认环境，后续命令显式指定同一 profile。
+
+```shell
+finebi-cli auth login --profile bi --base-url https://bi.example.com/webroot/decision --browser --no-use
+```
+
+将命令返回的授权链接和确认码展示给用户，请用户在同一 FineBI 服务的网页中登录并确认授权。保持命令运行，等待授权结果。
+
+若无法使用浏览器授权，让用户在自己的交互终端执行以下命令，并按提示输入密码；不要让用户把密码发到聊天中。
+
+```shell
+finebi-cli auth login --profile bi --base-url https://bi.example.com/webroot/decision --username your-user --no-use
+```
+
+浏览器授权成功后保存 CLI Access Key；账号密码登录默认也尝试签发 Key，签发失败会警告并降级为会话 Token。登录成功后会自动尝试刷新能力；应逐项检查 warning，不能把登录成功等同于业务命令已可用。认证与凭据安全说明见 [CLI 使用说明](README.md#access-key)。
+
+## 第 5 步 验证
+
+```shell
+finebi-cli auth info --profile bi --json
+finebi-cli capability refresh --profile bi --json
+finebi-cli system command-index --profile bi --json
+finebi-cli subject search --help --profile bi --json
+```
+
+`auth info` 仅展示本地凭据状态，不验证服务端有效性；在线 `capability refresh` 成功才说明当前连接能取得服务端能力。命令帮助来自能力缓存，也不证明业务资源可访问。
+
+需要确认业务访问时，在用户授权范围内执行一条实际只读查询，例如：
+
+```shell
+finebi-cli subject search --profile bi --limit 1 --json
+```
+
+分别报告 CLI 版本、Skill 加载状态、在线能力发现和实际业务查询结果；未执行业务查询时明确注明。查询零命中只能说明本次没有找到可见主题，不能推断其他业务权限。失败时说明未完成项，不将本地缓存视为在线连接成功。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.6.3",
+  "version": "2.0.0",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -15,6 +15,7 @@
     "src",
     "skills",
     "README.md",
+    "agent-installation-guide.md",
     "templates"
   ],
   "engines": {

package/skills/finebi-cli-agent/scripts/finebi-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.6.3",
+  "version": "2.0.0",
   "private": true,
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",

package/skills/finebi-cli-agent/scripts/finebi-cli/src/skill-files.js

@@ -9,6 +9,7 @@ export function agentCatalog({home = homedir(), env = process.env} = {}) {
   return [
     ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
     ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
+    ["dsh", "DeepSeek Harness", env.DSH_HOME || join(home, ".dsh")],
     ["cursor", "Cursor", join(home, ".cursor")],
     ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
     ["github-copilot", "GitHub Copilot", join(home, ".copilot")],

package/src/skill-files.js

@@ -9,6 +9,7 @@ export function agentCatalog({home = homedir(), env = process.env} = {}) {
   return [
     ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
     ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
+    ["dsh", "DeepSeek Harness", env.DSH_HOME || join(home, ".dsh")],
     ["cursor", "Cursor", join(home, ".cursor")],
     ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
     ["github-copilot", "GitHub Copilot", join(home, ".copilot")],