@finebi/finebi-cli 1.2.0 → 1.3.0

package/README.md

@@ -7,112 +7,10 @@ Array options take a JSON array as one argument, for example `--values '["上海
 ## Install
 
 ```powershell
-npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
+npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
 ```
 
-For local development, prefer `npm link` from this `cli` directory:
-
-```powershell
-cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
-npm link
-finebi-cli --help
-```
-
-After `npm link`, edits under `src` are picked up by the global `finebi-cli` command without linking again. If `finebi-cli` was installed from a packed `.tgz`, rebuild and reinstall the package after code changes:
-
-```powershell
-cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
-npm run pack:cli
-npm install -g .\finebi-finebi-cli-1.0.0.tgz
-```
-
-On Windows, use `where finebi-cli` if the command does not appear to update. Multiple Node.js/npm installations can leave more than one global command shim on `PATH`.
-
-## Publish an Update
-
-Publish from this `cli` directory. A published npm version is immutable, so increment the version before every release. Make and commit the functional changes first, then run the following release checks and version update:
-
-```powershell
-cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
-npm test
-npm run verify:pack
-npm version patch --no-git-tag-version
-```
-
-Use `patch` for bug fixes, `minor` for backward-compatible features, and `major` for breaking changes. `npm version` updates both `package.json` and `package-lock.json`. Review and commit the release version with a Chinese Conventional Commit message, then log in with an npm account authorized to publish under `@finebi`. The package publishes publicly to the official npm registry:
-
-```powershell
-git add package.json package-lock.json
-git commit -m "chore(cli): 发布 1.0.1"
-npm login --registry=https://registry.npmjs.org/
-npm publish --registry=https://registry.npmjs.org/ --access public
-```
-
-After a successful publish, verify the registry version and install it. Public package installation does not require npm authentication:
-
-```powershell
-npm view @finebi/finebi-cli version --registry=https://registry.npmjs.org/
-npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
-finebi-cli version
-```
-
-## Testing
-
-Run these commands from the repository root. On Windows PowerShell use `npm.cmd`; on Linux/macOS use `npm`:
-
-```powershell
-npm.cmd --prefix cli test
-npm.cmd --prefix cli run test:integration:stub
-```
-
-Linux/macOS：
-
-```bash
-npm --prefix cli test
-npm --prefix cli run test:integration:stub
-```
-
-For a real FineBI environment, use the corresponding integration script:
-
-Windows PowerShell：
-
-```powershell
-npm.cmd --prefix cli run test:integration:readonly
-npm.cmd --prefix cli run test:integration:mutating
-npm.cmd --prefix cli run test:integration:real
-```
-
-Linux/macOS：
-
-```bash
-npm --prefix cli run test:integration:readonly
-npm --prefix cli run test:integration:mutating
-npm --prefix cli run test:integration:real
-```
-
-### Real integration prerequisites
-
-Before running a real FineBI test, configure all of the following:
-
-- `cli/tests/fixtures/finebi-integration-environment.json`: set `ready` to `true`, and provide a reachable HTTP(S) `baseUrl`, the test `username`, a positive `revision`, and `passwordSource` pointing to `FINEBI_INTEGRATION_PASSWORD`. `reportDir` may be a relative default or an absolute path.
-- `cli/tests/fixtures/capabilities/`: keep the per-resource snapshots valid and synchronized with the deployed plugin/environment. The commands and request schemas in real cases are checked against this Capability snapshot (aggregated by `fixtures/capabilities/load.js`).
-- `cli/tests/real-cases/*.json`: enable at least one case with `enabled: true`. Readonly cases must use `mutation: false` commands; mutating cases must declare scoped cleanup for resources created by that case.
-- FineBI: deploy the plugin version corresponding to the current source and verify that the configured account can log in and access the required resources. Run mutating cases only in a dedicated test environment.
-- Credentials: inject the password through the environment variable before starting the test. `xxxx` below is only a placeholder and must be replaced locally or by CI Secret injection.
-
-Windows PowerShell:
-
-```powershell
-$env:FINEBI_INTEGRATION_PASSWORD = 'xxxx'
-```
-
-Linux/macOS:
-
-```bash
-export FINEBI_INTEGRATION_PASSWORD='xxxx'
-```
-
-Do not commit the real value or place it in case JSON, CLI arguments, logs, or reports. If `--report-dir` is supplied, it must be an existing writable absolute directory; `--case` can narrow the run to one enabled case. See the complete [CLI testing guide](../docs/cli-testing/20260804-finebi-real-integration/cli-testing-guide.md) for platform-specific setup, real-case authoring with the `finebi-cli-case-authoring` skill, cleanup rules, and report troubleshooting.
+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.
 
 ## Usage
 
@@ -142,39 +40,39 @@ finebi-cli <resource> --help
 finebi-cli <resource> <command> [options]
 ```
 
-Run `finebi-cli capability refresh` manually when backend commands changed, the cache expired, or you want to force a reload.
-
-### Multiple environments
-
-Create an environment by logging in with its name and address:
-
-```powershell
-finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser
-finebi-cli auth login --profile prod --base-url https://prod.example.com/webroot/decision --username admin --password-stdin
-finebi-cli auth list
-finebi-cli auth use test
-finebi-cli capability info --profile prod
-finebi-cli auth info --profile prod
-finebi-cli config set timeout-ms 60000 --profile prod
-finebi-cli auth logout --profile prod
-finebi-cli auth remove prod
-```
-
-Successful login selects that environment as the default; add `--no-use` to keep the existing default. Login to an existing name reuses its address unless overridden. A new name requires `--base-url` or `FINEBI_BASE_URL` and never inherits another environment's identity. Failed authentication leaves existing environments and the default unchanged.
-
-Selection order is `--profile` > `FINEBI_PROFILE` > saved default. The option works before or after the command. Ordinary commands never create missing environments or change the default. Names are case-sensitive, 1–64 ASCII letters/digits/underscores/hyphens, beginning with a letter or digit. `auth list` shows local metadata only, not a live authentication check. JSON responses identify the selected environment in `meta.profile`.
-
-Each environment has separate credentials, connection settings and capabilities. Changing its saved `base-url` clears its credentials and cache. Temporary URL/token overrides do not change saved configuration; a different URL never inherits saved credentials. Requests with temporary credentials fetch capabilities for that invocation without overwriting a saved cache. Explicit session tokens take precedence over saved Access Keys.
-
-`auth logout` revokes the selected environment's saved Key and keeps its connection settings. `auth remove <name>` and `config clear --profile <name>` delete only that local environment and cache, without revoking server credentials. Removing the default does not automatically select another saved environment. Persistent configuration and logout operations use the selected saved environment, not connection override variables.
-
-Existing single-environment configuration is exposed as `default`; read-only commands do not rewrite it. Multi-environment writes migrate it while preserving its credentials and default capability cache. See the [command contract](../docs/commands/README.md#多环境管理) for the complete behavior.
-
-## Access Key
+Run `finebi-cli capability refresh` manually when backend commands changed, the cache expired, or you want to force a reload.
+
+### Multiple environments
+
+Create an environment by logging in with its name and address:
+
+```powershell
+finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser
+finebi-cli auth login --profile prod --base-url https://prod.example.com/webroot/decision --username admin --password-stdin
+finebi-cli auth list
+finebi-cli auth use test
+finebi-cli capability info --profile prod
+finebi-cli auth info --profile prod
+finebi-cli config set timeout-ms 60000 --profile prod
+finebi-cli auth logout --profile prod
+finebi-cli auth remove prod
+```
+
+Successful login selects that environment as the default; add `--no-use` to keep the existing default. Login to an existing name reuses its address unless overridden. A new name requires `--base-url` or `FINEBI_BASE_URL` and never inherits another environment's identity. Failed authentication leaves existing environments and the default unchanged.
+
+Selection order is `--profile` > `FINEBI_PROFILE` > saved default. The option works before or after the command. Ordinary commands never create missing environments or change the default. Names are case-sensitive, 1–64 ASCII letters/digits/underscores/hyphens, beginning with a letter or digit. `auth list` shows local metadata only, not a live authentication check. JSON responses identify the selected environment in `meta.profile`.
+
+Each environment has separate credentials, connection settings and capabilities. Changing its saved `base-url` clears its credentials and cache. Temporary URL/token overrides do not change saved configuration; a different URL never inherits saved credentials. Requests with temporary credentials fetch capabilities for that invocation without overwriting a saved cache. Explicit session tokens take precedence over saved Access Keys.
+
+`auth logout` revokes the selected environment's saved Key and keeps its connection settings. `auth remove <name>` and `config clear --profile <name>` delete only that local environment and cache, without revoking server credentials. Removing the default does not automatically select another saved environment. Persistent configuration and logout operations use the selected saved environment, not connection override variables.
+
+Existing single-environment configuration is exposed as `default`; read-only commands do not rewrite it. Multi-environment writes migrate it while preserving its credentials and default capability cache. See the [command contract](../docs/commands/README.md#多环境管理) for the complete behavior.
+
+## Access Key
 
 After a successful `auth login`, the CLI automatically issues a long-lived Access Key so commands keep working after the short-lived session token (JWT) expires:
 
-- Login provisions a key with description `finebi-cli@<hostname>` for `default`, or `finebi-cli@<hostname>/<profile>` for a named environment, replacing stale keys with the same description. The plaintext key is stored in the environment's `auth.accessKey` and never printed. On POSIX systems, the CLI enforces mode `0700` on the config directory and `0600` on `config.json`. On Windows, it removes inherited ACLs and grants access only to the current user, SYSTEM, and Administrators; failures emit a security warning.
+- Login provisions a key with description `finebi-cli@<hostname>` for `default`, or `finebi-cli@<hostname>/<profile>` for a named environment, replacing stale keys with the same description. The plaintext key is stored in the environment's `auth.accessKey` and never printed. On POSIX systems, the CLI enforces mode `0700` on the config directory and `0600` on `config.json`. On Windows, it removes inherited ACLs and grants access only to the current user, SYSTEM, and Administrators; failures emit a security warning.
 - Business commands send `X-FineBI-CLI-Access-Key` when a key is present, and fall back to the session token otherwise.
 - Add `--no-access-key` to `auth login` to skip issuance and stay on the session token.
 - `auth info` shows `authMode` (`access-key` / `session-token` / `none`) with both the session token and Access Key masked.
@@ -202,9 +100,31 @@ For complex file-based resources, do not expect command help to contain a comple
 
 ## Agent Skills
 
-Use the `finebi-cli` skill when an Agent needs to operate this CLI. The skill should follow the discovery flow above and treat dynamic command help as the source of truth after capability refresh.
+Install the bundled `finebi-cli-agent` Skill into your Agent's directory:
+
+```powershell
+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.
 
-Use the `finebi-cli-command-designer` skill for command design work: new command groups, schema changes, response contracts, help output, and design markdown. Command-specific business rules should be designed in the command document and implemented on the backend; the CLI should only interpret field-level rules declared in the capability schema.
+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.
+
+To update, install the latest CLI package and run `install-skill` again:
+
+```powershell
+npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
+finebi-cli install-skill --agents codex,cursor
+```
+
+Identical installations are left unchanged. Unmodified managed Skills are backed up and updated automatically. Local edits and installations without a recorded checksum are kept, and the command reports an incomplete installation. To explicitly replace them with a backup:
+
+```powershell
+finebi-cli install-skill --agents codex --replace
+```
+
+Backups are stored under `~/.finebi-cli/skill-backups/`; installation records are in `~/.finebi-cli/installation.json`. The command preserves other records and does not change authentication or connection configuration. The Skill follows the discovery flow above and treats dynamic command help as the source of truth after capability refresh.
 
 ## Output
 
@@ -302,11 +222,11 @@ echo your-password | finebi-cli auth login --username 1 --password-stdin
 ## Local Files
 
 - Config: `%USERPROFILE%\.finebi-cli\config.json`
-- Capability cache: `%USERPROFILE%\.finebi-cli\capabilities.json`
-- Named environment caches: `%USERPROFILE%\.finebi-cli\capabilities-profile-<hex-encoded-name>.json` (`default` uses `capabilities.json`).
-
-Multi-environment `config.json` stores `schemaVersion: 2`, `currentProfile` (nullable), and a `profiles` object keyed by environment name. Writes are serialized with a short-lived `config.json.lock` and atomically replace the configuration file. A lock timeout reports an error without modifying the file.
-
-Concurrent logins to the same environment are rejected using `config.json.login-<hex-encoded-name>.lock`; different environments may log in concurrently. Locks are released when the operation settles. If a process is forcibly terminated and leaves a lock behind, verify that the owning operation has stopped before manually removing that lock file.
+- Capability cache: `%USERPROFILE%\.finebi-cli\capabilities.json`
+- Named environment caches: `%USERPROFILE%\.finebi-cli\capabilities-profile-<hex-encoded-name>.json` (`default` uses `capabilities.json`).
+
+Multi-environment `config.json` stores `schemaVersion: 2`, `currentProfile` (nullable), and a `profiles` object keyed by environment name. Writes are serialized with a short-lived `config.json.lock` and atomically replace the configuration file. A lock timeout reports an error without modifying the file.
+
+Concurrent logins to the same environment are rejected using `config.json.login-<hex-encoded-name>.lock`; different environments may log in concurrently. Locks are released when the operation settles. If a process is forcibly terminated and leaves a lock behind, verify that the owning operation has stopped before manually removing that lock file.
 
 Passwords are not persisted by the CLI.

package/package.json

@@ -1,37 +1,40 @@
-{
-  "name": "@finebi/finebi-cli",
-  "version": "1.2.0",
-  "description": "FineBI dynamic capability command line client.",
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "type": "module",
-  "bin": {
-    "finebi-cli": "./src/index.js"
-  },
-  "files": [
+{
+  "name": "@finebi/finebi-cli",
+  "version": "1.3.0",
+  "description": "FineBI dynamic capability command line client.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "finebi-cli": "./src/index.js"
+  },
+  "files": [
     "src",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
   "scripts": {
-    "test": "npm run test:unit && npm run test:process && npm run test:contract && npm run test:integration:stub",
-    "test:unit": "node --test tests/unit/access-key.test.js tests/unit/auth.test.js tests/unit/capability.test.js tests/unit/config-permissions.test.js tests/unit/config.test.js tests/unit/dynamic-command-forwarding.test.js tests/unit/dynamic-command-multipart.test.js tests/unit/dynamic-command-preflight.test.js tests/unit/error-catalog-loader.test.js tests/unit/error-catalog.test.js tests/unit/error-construction-guard.test.js tests/unit/help.test.js tests/unit/http-stub.test.js tests/unit/index-auth-login.test.js tests/unit/index-auth-session.test.js tests/unit/index-browser-auth.test.js tests/unit/index-config.test.js tests/unit/index-dynamic-errors.test.js tests/unit/index-dynamic-render.test.js tests/unit/index-help.test.js tests/unit/index-profiles.test.js tests/unit/output-limits.test.js tests/unit/output.test.js tests/unit/package.test.js tests/unit/schema-options-capability.test.js tests/unit/schema-options-file-input.test.js tests/unit/schema-options-scalar.test.js",
-    "test:process": "node --test tests/process/bench-cli-runner.test.js tests/process/process-cli.test.js tests/process/profiles-cli.test.js",
-    "test:contract": "node --test tests/contract/capability-contract.test.js",
-    "test:integration:stub": "node --test tests/integration/analysis-ds-workflows.test.js tests/integration/assertions.test.js tests/integration/auth-system.test.js tests/integration/case-loader.test.js tests/integration/cli-process.test.js tests/integration/config.test.js tests/integration/dashboard-workflows.test.js tests/integration/entry.test.js tests/integration/failure-security.test.js tests/integration/file-template.test.js tests/integration/mutating-file-input.test.js tests/integration/mutating-resource-ledger.test.js tests/integration/mutating-workflow-guards.test.js tests/integration/readonly-assertions.test.js tests/integration/readonly-file-input.test.js tests/integration/readonly-workflow-contract.test.js tests/integration/report-directory.test.js tests/integration/report-entry.test.js tests/integration/report-secrets.test.js tests/integration/report-summary-artifacts.test.js tests/integration/runner.test.js",
-    "test:integration:readonly": "node tests/integration/entry.js readonly",
-    "test:integration:mutating": "node tests/integration/entry.js mutating",
-    "test:integration:real": "node tests/integration/entry.js all",
-    "prebench": "npm test",
-    "bench": "node bench/src/runner.js",
-    "prepack:cli": "npm test",
-    "pack:cli": "npm pack",
-    "preverify:pack": "npm test",
-    "verify:pack": "npm pack --dry-run"
-  }
-}
+    "prepack": "node ../scripts/build-finebi-cli-agent.mjs",
+    "test:pack": "node ../scripts/test-cli-package.mjs",
+    "test": "npm run test:unit && npm run test:process && npm run test:contract && npm run test:integration:stub",
+    "test:unit": "node --test tests/unit/access-key.test.js tests/unit/auth.test.js tests/unit/capability.test.js tests/unit/config-permissions.test.js tests/unit/config.test.js tests/unit/dynamic-command-forwarding.test.js tests/unit/dynamic-command-multipart.test.js tests/unit/dynamic-command-preflight.test.js tests/unit/error-catalog-loader.test.js tests/unit/error-catalog.test.js tests/unit/error-construction-guard.test.js tests/unit/help.test.js tests/unit/http-stub.test.js tests/unit/index-auth-login.test.js tests/unit/index-auth-session.test.js tests/unit/index-browser-auth.test.js tests/unit/index-config.test.js tests/unit/index-dynamic-errors.test.js tests/unit/index-dynamic-render.test.js tests/unit/index-help.test.js tests/unit/index-profiles.test.js tests/unit/install-skill.test.js tests/unit/output-limits.test.js tests/unit/output.test.js tests/unit/package.test.js tests/unit/schema-options-capability.test.js tests/unit/schema-options-file-input.test.js tests/unit/schema-options-scalar.test.js",
+    "test:process": "node --test tests/process/bench-cli-runner.test.js tests/process/process-cli.test.js tests/process/profiles-cli.test.js",
+    "test:contract": "node --test tests/contract/capability-contract.test.js",
+    "test:integration:stub": "node --test tests/integration/analysis-ds-workflows.test.js tests/integration/assertions.test.js tests/integration/auth-system.test.js tests/integration/case-loader.test.js tests/integration/cli-process.test.js tests/integration/config.test.js tests/integration/dashboard-workflows.test.js tests/integration/entry.test.js tests/integration/failure-security.test.js tests/integration/file-template.test.js tests/integration/mutating-file-input.test.js tests/integration/mutating-resource-ledger.test.js tests/integration/mutating-workflow-guards.test.js tests/integration/readonly-assertions.test.js tests/integration/readonly-file-input.test.js tests/integration/readonly-workflow-contract.test.js tests/integration/report-directory.test.js tests/integration/report-entry.test.js tests/integration/report-secrets.test.js tests/integration/report-summary-artifacts.test.js tests/integration/runner.test.js",
+    "test:integration:readonly": "node tests/integration/entry.js readonly",
+    "test:integration:mutating": "node tests/integration/entry.js mutating",
+    "test:integration:real": "node tests/integration/entry.js all",
+    "prebench": "npm test",
+    "bench": "node bench/src/runner.js",
+    "prepack:cli": "npm test",
+    "pack:cli": "npm pack",
+    "preverify:pack": "npm test",
+    "verify:pack": "npm pack --dry-run"
+  }
+}

package/skills/finebi-cli-agent/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: finebi-cli-agent
+description: 使用 FineBI CLI 查询和管理 FineBI 资源，生成并应用组件（Widget）和仪表板（Dashboard）DSL，优先使用内置 CLI，也支持已安装的全局 @finebi/finebi-cli。用户需要查看或操作分析主题、数据集、计算字段、图表组件、仪表板，或配置 FineBI CLI 连接与认证时使用。
+---
+
+# FineBI CLI Agent
+
+## 目标
+
+优先使用本 Skill 内置的 CLI 完成 FineBI 资源发现、读取、DSL 制品生成和安全写入，也允许使用通过 npm 安装的全局 `@finebi/finebi-cli`。不得依赖原始源码仓库，也不得调用仓库外的另一项 FineBI Skill 才能完成主流程。
+
+## 运行前提
+
+- 使用 Node.js 18.17 或更高版本。
+- 确认目标 FineBI 已部署与所选 CLI 兼容的 `plugin-bi-finebi-cli` 服务端插件。
+- 确认 Agent 能访问目标 FineBI HTTP(S) 地址，并能在用户目录写入 `.finebi-cli` 配置。
+- 将包含本文件的目录记为 `<skill-dir>`。所有脚本均使用 `<skill-dir>` 的绝对路径调用，不根据当前工作目录猜测位置。
+
+## 按需读取参考
+
+- 首次处理业务命令时，读取 [命令工作流](references/command-workflows.md) 的公共约束和目标命令族章节。
+- 包含非只读动作时，读取 [变更计划与删除确认契约](references/mutation-confirmation-contract.md) 的计划、复检和验证规则；包含 `delete` 或失败清理时再读对应章节。
+- 规划 Widget/Dashboard 时按当前场景读取 [场景工作流](references/scenario-workflows.md)；构造或消费交接对象时读取 [语义交接契约](references/handoff-contract.md) 和 [DSL 输入契约](references/dsl-handoff-contract.md) 的公共结构及当前场景字段。
+- 生成 Widget DSL 时，读取 [映射规则](references/mapping-rules.md) 和 [Widget DSL API](references/widget-dsl-api.md) 的公共约束及所用组件、字段类型和 API 章节。
+- 需要可运行的推荐写法示例（分区折线/双轴/表格属性等）时，读取 [Widget DSL 写法示例](references/widget-dsl-api-examples.md)。
+- 生成 Dashboard DSL 时，读取 [Dashboard DSL API](references/dashboard-dsl-api.md) 的公共约束和所用布局、引用及 API 章节；仅引用已有组件时无需加载 Widget API。产物顺序不清楚时读取 [产物顺序](references/artifact-ordering.md)。
+- 解释或生成公式时，先用 `formula functions` 查询当前 FineBI 公式面板；绑定真实字段后，用 `calculated-field validate` 执行原生校验。
+- 同一连续任务内复用未变化的已读内容；只有文件变化、进入未读能力，或上下文压缩后所需规则已不可用时，才补读相关部分。实时 capability、目标和文件摘要校验仍按变更契约执行，不以文档复用代替。
+
+## 执行入口
+
+默认优先使用内置 CLI。未显式指定入口且内置文件存在时，调用：
+
+```text
+node "<skill-dir>/scripts/finebi-cli/src/index.js" <built-in-command> ...
+node "<skill-dir>/scripts/finebi-cli-runner.mjs" inspect <resource> <command>
+node "<skill-dir>/scripts/finebi-cli-runner.mjs" run <resource> <command> ... --json
+```
+
+- 入口优先级：显式指定的 `FINEBI_CLI_PATH` → `<skill-dir>/scripts/finebi-cli/src/index.js` → PATH 中已安装的 `finebi-cli`。需要使用特定全局版本时，将 `FINEBI_CLI_PATH` 指向该 npm 包的 JavaScript 入口或可执行文件；Windows npm `.cmd` 入口也受支持。
+- `config`、`auth`、`capability` 直接调用所选 CLI 入口。使用全局包时可调用 `finebi-cli <command> ...`；显式指定 JavaScript 入口时使用 `node "<CLI 入口绝对路径>" <command> ...`。这些命令与业务 runner 必须使用同一 CLI 安装。
+- 动态业务命令仍使用上述 Skill runner；runner 按同一优先级选择 CLI，以 `shell:false` 启动并脱敏敏感参数。
+- 不因机器上存在全局 CLI 就覆盖默认内置入口。没有任何可用入口时说明缺失，可由用户安装已发布的 `@finebi/finebi-cli`；当前业务任务不自动执行 `npm install`、`npm link` 或 `npx`。
+- CLI 选定后，认证失败、服务端能力缺失或业务命令失败不触发自动换版本重试；需要切换入口时重新核对连接、认证和 capability/help，并重新校验受影响的计划。
+- `inspect` 一次读取 capability 摘要和目标命令 help；不得把完整 capability manifest 输出到模型上下文。
+- 仅以实时 capability 和目标命令 help 判断命令是否存在、参数结构和 `mutation` 属性。
+- 名为 `template` 的动态命令必须先 `inspect`；仅当实时 capability 标记 `mutation:false` 时，才可用于读取文件 schema、Definition 模板和填写指引，不得把模板输出当作写操作授权。
+
+## 安全边界
+
+- 运行时 `mutation:false` 的业务命令可在参数完整且无歧义后执行。
+- 所有非只读命令必须完成计划和执行前校验；仅命令名为 `delete` 的计划需要 `确认执行 <planId>`。`add`、`update`、`data-update` 等非删除命令在用户请求范围内可直接复检执行。
+- `config set/clear`、`auth login/logout`、`capability refresh/clear-cache` 等非删除命令无需额外人工确认，但必须限定在当前任务所需的目标和影响范围。
+- 删除计划的命令、参数、目标、顺序、文件路径、文件 SHA-256、schema 或 capability 任一变化，立即使原确认失效；重新生成计划并请求确认。
+- 非删除计划的文件或前提变化时重新规划和校验，不增加人工确认步骤；不得沿用失效计划。
+- 不得在多个资源、字段或关系之间静默选择；展示候选名称、ID 和归属后让用户消除歧义。
+- 不得在命令、计划、日志或回复中暴露密码、token、cookie、Access Key。优先通过环境变量或标准输入传递密码。
+- 不得把命令成功直接等同于业务完成；存在只读回查命令时必须验证，部分成功必须逐项报告。
+- 失败清理和补偿同样需要计划与验证；包含 `delete` 的清理必须独立确认，非删除补偿在当前任务范围内完成复检后执行。
+
+## 状态机
+
+一次操作只能处于一个可见状态：
+
+- `DISCOVERING`：读取 capability/help，解析资源、字段、ID、文件和依赖。
+- `READY_READONLY`：只读命令参数完整且无歧义，可以执行。
+- `GENERATING_ARTIFACTS`：仅写入已声明的本地 Definition 或 DSL 文件，不执行 FineBI 写命令。
+- `AWAITING_CONFIRMATION`：包含 `delete` 的计划已冻结，等待确认指定 `planId`。
+- `EXECUTING`：执行已复检且未变化的计划；包含 `delete` 时还须已获得确认。
+- `VERIFYING`：使用只读命令核验结果并识别部分成功。
+- `COMPLETED`：计划执行和验证均已完成。
+- `BLOCKED`：能力缺失、目标歧义、运行时漂移或无法满足安全边界。
+
+非只读命令须先完成计划和复检；不含 `delete` 的计划可直接进入 `EXECUTING`，不经过 `AWAITING_CONFIRMATION`。
+
+## 工作流
+
+### 1. 检查连接与认证
+
+先按执行入口规则选定 CLI，再调用其只读状态命令检查配置、认证和 capability 缓存。需要配置地址或登录时，在当前任务范围内说明并执行必要的本地状态变更；缺少目标地址或认证输入时请求补充。成功登录后仍检查 capability 是否刷新成功。
+
+### 2. 发现实时能力
+
+使用 runner 的 `inspect` 模式核对资源、命令、`mutation`、必填参数、文件类型和响应结构。矩阵与运行时不一致时，以运行时结果阻断本次操作并报告差异，不得沿用旧计划或臆造语法。
+
+### 3. 解析资源与字段
+
+按照命令工作流使用 `search`、`info`、`definition`、`schema`、`preview` 等只读命令解析准确 ID、归属关系和字段。遍历分页结果；保留空结果、警告和部分数据标记。
+
+需要生成 JSON Definition 时，先 `inspect` 对应的 `template` 命令；实时 capability 为 `mutation:false` 时执行它，并以返回的 `definitionSchema`、`definitionTemplate` 和填写指引生成文件。不得凭经验猜测 Definition 结构。
+
+模型指标集不走分析表或公共数据集搜索。先调用 `subject info` 查看 `resources.models` 主题模型摘要，再用 `model search --subject-id <subjectId>` 消歧主题内模型，并用 `model info --subject-id <subjectId> --id <modelId>` 获取具体指标、数据集字段和模型计算字段。若用户要求的指标集尚未属于主题，单独以 `public-ds search` 确认唯一的 `type=METRIC_SET` 来源和可编辑目标主题；`model add` 返回的主题内模型 ID 才可用于 `model info/delete` 和字段回查，来源 ID 不得写进 DSL。模型目录命令未出现在实时 capability 时，既有 `widget dsl` 输出中的 `model(...)` 仍可作为只读证据；两类证据都不存在时进入 `BLOCKED`。不得把同名分析表改写成模型指标集。
+
+### 4. 生成 Widget/Dashboard DSL
+
+需要新建或更新 Widget/Dashboard 时：
+
+1. 按语义交接契约构造并校验 `contractVersion: "1.0"` 的交接对象。
+2. 明确列出唯一的绝对 `.js` 产物路径；只写入用户同意的映射路径。
+3. 按 DSL 输入契约、映射规则和对应 API 生成文件。
+4. 物理字段使用 `from("来源表").dim/sum/...`；模型级仅有指标，使用 `model("模型指标集").metrics().sum/avg/min/max/measure(...)`；模型表字段和模型计算字段分别使用 `model("模型指标集").dataset("数据集").dim/sum(...)` 与 `model("模型指标集").calculated().dim/sum(...)`；已保存计算字段使用 `measureID("配置 ID").dim()/sum()`。不把数据集 ID、模型 ID、字段 ID 或关系 ID 写进 DSL，也不把同名 `from(...)` 与 `model(...)` 互换。
+5. Dashboard 统一通过 `.reference("组件名")` 引用组件，不内联组件定义。
+6. 重新读取文件，自检根类型、名称、字段来源、API 和换行。
+
+DSL 生成只授权本地文件写入，不授权任何 FineBI 写命令。模型字段支持模型指标、模型表字段和模型计算字段；模型根级维度和记录数不支持。同一作用域内字段展示名无法唯一解析时返回 `BLOCKED`，不得猜测或静默丢弃语义。
+
+### 5. 执行只读业务命令
+
+展示用途和业务命令 JSON `argv`，再用 runner 的 `run` 模式执行。解析结构化 envelope，只呈现任务所需结果，不重复倾倒原始 stdout。
+
+### 6. 冻结写入计划
+
+计划前先核对目标命令 help 是否能表达用户要求的名称、路径和其他目标属性。能力不支持时必须说明差距并进入 `BLOCKED`，不得把无法传入的目标写进计划。例如 `subject.add` 只有 `parentId` 时，不得承诺创建指定名称的主题。
+
+按照变更确认契约生成计划，包含：精确目标、完整参数、文件绝对路径与 SHA-256、阶段依赖、影响、可逆性、前置验证、后置验证和失败清理策略。删除操作独立成批；不能可靠清理的操作单独执行或放在最后。
+
+如果下游文件只能在上游写命令返回服务端实际 ID 后生成，不得在同一计划中使用占位 ID 或预期 ID。应先规划、复检、执行并回查上游资源；再生成下游文件并冻结新的 `planId`，仅包含 `delete` 时等待确认。典型顺序是：创建主题并回查实际 ID → 生成 Analysis DS Definition 并新建计划 → 创建分析表并回查实际 ID → 生成 Widget/Dashboard DSL 并新建计划。
+
+生成唯一 `planId`；仅包含 `delete` 时将状态设为 `AWAITING_CONFIRMATION` 并要求用户回复 `确认执行 <planId>`，确认前不得执行该删除计划。不含 `delete` 时直接复检并执行。
+
+### 7. 复检、执行与验证
+
+按变更契约核验 capability/help、目标和文件摘要；删除计划先收到精确确认，再实时复检。全部符合计划时严格按阶段执行，每阶段完成后立即只读验证；首个写命令失败后立即停止，不得在同一 `planId` 下修改参数、改写文件或换一种 JSON 继续重试。
+
+失败时汇总已成功或明确部分成功的资源，按依赖逆序生成新的 `cleanupPlanId`。其中 `delete` 必须独立确认；非删除补偿完成复检后执行。
+
+### 8. 完成报告
+
+报告每阶段结果、服务端实际 ID、验证证据、未执行项和残留风险。只有所有计划阶段及验证完成时进入 `COMPLETED`。
+
+## 阻断输出
+
+进入 `BLOCKED` 时报告状态、阻断命令或阶段、已收集只读证据、触发的安全边界，以及继续所需的最小用户操作。不得输出未经验证或可能误导用户执行的写命令。

package/skills/finebi-cli-agent/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "FineBI CLI Agent"
+  short_description: "使用内置 CLI 查询、创建和安全管理 FineBI 资源"
+  default_prompt: "使用 $finebi-cli-agent 完成我的 FineBI 查询、组件或仪表板需求；只读操作直接执行，写操作先让我确认。"
+
+policy:
+  allow_implicit_invocation: true