@finebi/finebi-cli 1.6.0 → 1.6.2

package/README.md

@@ -44,11 +44,15 @@ finebi-cli <resource> <command> [options]
 Create and inspect a local dynamic web app project without connecting to FineBI:
 
 ```powershell
-finebi-cli app create --name sales-dashboard --path D:\work
+finebi-cli app create --name sales-dashboard --path D:\work --layout cockpit
 finebi-cli app inspect --path D:\work\sales-dashboard
 ```
 
-`app create` copies the bundled `web-app` template, sets the project npm name, and records the template version in `public/app-config.json`. It rejects an existing destination and does not install dependencies or run project scripts. `app inspect` checks the local configuration and reports `remoteValidated: false`; use the generated project to perform the real login and data request checks in a browser.
+`app create` copies the bundled `web-app` template, sets the project npm name, and records the template version in `public/app-config.json`. It rejects an existing destination and does not install dependencies or run project scripts. `app inspect` reads a JSON object and reports a configuration summary with `configValidated: false` and `remoteValidated: false`. Optional `--strict` validates against the CLI bundled template rules, which may not match custom app extensions. Inspection is not an acceptance gate; use the generated project tests, build and real browser checks to verify the application.
+
+`--layout` accepts `overview` (default), `workbench`, or the green `cockpit` layout. Cockpit shares the existing Cookie query and authentication flow, with configurable KPI/chart/table bindings, independent retries, and a custom month picker. The generated README and `examples/cockpit.config.json` describe the placeholder bindings; no business data or credentials are bundled. Published sources require `directoryEntryId` and a platform HTTP endpoint that supports directory permissions; failed queries never switch sources.
+
+Use `--layout retail` for a warm paper-style retail brief with horizontal navigation, a KPI strip, and blue/orange charts. `examples/retail.config.json` contains placeholder retail bindings; see the generated design guide for explicit KPI and month-label formats. Creation leaves the project unbound and does not query a server.
 
 Run `finebi-cli capability refresh` manually when backend commands changed, the cache expired, or you want to force a reload.
 
@@ -65,13 +69,13 @@ For temporary field selection, first read the target instance's field directory:
 
 ```powershell
 finebi-cli dashboard info --id <dashboardId>
-finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '["<dId>"]' --filter "合同付款类型=分期付款"
+finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '["<dimensionDId>","<measureDId>"]' --filter "合同付款类型=分期付款"
 finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '[]'
 ```
 
-Use `entries[].queryFields[].dId` where `selectable=true`; this is a component-local key, not a dataset `fieldId` or field name. `queryFields` includes disabled fields and reports their saved `used` flag. Omit `--dimension-ids` to keep the saved selection. An explicit `[]` removes selectable dimensions while retaining summary/chart metrics; a detail table returns no columns or rows. Existing filters remain effective. Empty output columns do not imply that native pagination totals are zero.
+Use `entries[].queryFields[].dId` where `selectable=true`; this is a component-local key, not a dataset `fieldId` or field name. `queryFields` includes disabled fields and reports their saved `used` flag. Omit `--dimension-ids` to keep the saved selection. The list is a complete whitelist of dimensions and measures: unlisted selectable fields are disabled. Include measure dIds explicitly to keep their output; selecting only measures disables selectable dimensions. An explicit `[]` disables all selectable dimensions and measures; a detail table returns no columns or rows. Existing filters remain effective. Empty output columns do not imply that native pagination totals are zero.
 
-For a published dashboard, pass the same `--directory-entry-id` to `dashboard info` and `dashboard data`, and use dIds from that source. Installing this npm package updates only the client and bundled Skill. These commands require a compatible server plugin and platform Provider; the plugin directly depends on the dimension-selection and published-source APIs. Refresh capabilities after the server update.
+For a published dashboard, pass the same `--directory-entry-id` to `dashboard info` and `dashboard data`, and use dIds from that source. Installing this npm package updates only the client and bundled Skill. These commands require a server plugin and platform Provider supporting the complete dimension-and-measure whitelist; the plugin directly depends on the dimension-selection and published-source APIs. Refresh capabilities after the server update.
 
 ### Multiple environments
 
@@ -101,13 +105,13 @@ Existing single-environment configuration is exposed as `default`; read-only com
 
 ## 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:
+Password login issues a long-lived Access Key by default; browser authorization saves the Key received after approval. Business commands prefer `X-BI-CLI-Access-Key`, then fall back to the session token. The server also accepts `X-FineBI-CLI-Access-Key` as a compatibility alias.
+
+- Add `--no-access-key` to password login to keep only the session token. Password login replaces old Keys with the same machine/profile description; browser authorization does not automatically remove existing Keys.
+- `auth info` shows `authMode` (`access-key` / `session-token` / `none`) with credentials masked.
+- `auth logout` revokes the saved Key before clearing local credentials, even after the JWT expires. Failed revocation preserves credentials for retry; `--force` permits local cleanup without confirmed server revocation.
 
-- 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.
-- `auth logout` revokes the server-side key via `self-revoke` (works even after the JWT expired), then clears local credentials. If revocation fails, credentials are preserved for retry; use `auth logout --force` only when local credentials must be removed without confirmed server revocation.
+The [authentication contract](../docs/commands/README.md#access-key-行为) defines issuance, profile descriptions, headers, compatibility and failure behavior. Local credential storage is described under [Local Files](#local-files).
 
 ```powershell
 finebi-cli auth login --username 1
@@ -263,4 +267,4 @@ Multi-environment `config.json` stores `schemaVersion: 2`, `currentProfile` (nul
 
 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.
+Passwords are not persisted by the CLI. Saved session tokens and Access Keys remain usable credential values in `config.json`; they are not encrypted at rest. On POSIX, the CLI restricts the directory to `0700` and the file to `0600`. On Windows, it attempts to remove inherited ACLs and grant access to the current user, SYSTEM and Administrators; failures emit a security warning. Protect this directory and its backups.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finebi/finebi-cli",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "FineBI dynamic capability command line client.",
   "license": "UNLICENSED",
   "publishConfig": {

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

@@ -1,137 +1,57 @@
 ---
 name: finebi-cli-agent
-description: 使用 FineBI CLI 查询和管理 FineBI 资源，生成并应用组件（Widget）和仪表板（Dashboard）DSL，优先使用内置 CLI，也支持已安装的全局 @finebi/finebi-cli。用户需要查看或操作分析主题、数据集、计算字段、图表组件、仪表板，配置 FineBI CLI 连接与认证，或生成动态 HTML 看板、数据 Web 应用时使用。
+description: 使用 FineBI CLI 查询和管理资源、生成组件与仪表板 DSL，或创建连接 FineBI 的动态 HTML 看板和数据 Web 应用。适用于 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>` 的绝对路径调用，不根据当前工作目录猜测位置。
-
-## 按需读取参考
-
-- 生成动态 HTML 页面或数据 Web 应用时，读取 [应用模板工作流](references/web-app.md)，通过本地 app create 创建工程，再遵循项目 AGENTS.md。
-
-- 首次处理业务命令时，读取 [命令工作流](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) 导航的拆分文件，不一次加载全部：写组件前读 [widget-dsl-core.md](references/widget-dsl-core.md)（根入口/字段工厂/Builder）；配置图表类型与通道编码读 [widget-dsl-encodings.md](references/widget-dsl-encodings.md)；调整样式、视觉通道、轴或排序读 [widget-dsl-styles.md](references/widget-dsl-styles.md)；配置过滤、配色、数值格式或查枚举读 [widget-dsl-contexts.md](references/widget-dsl-contexts.md)。
-- 需要可运行的推荐写法示例（分区折线/双轴/表格属性等）时，读取 [Widget DSL 写法示例](references/widget-dsl-api-examples.md)。
-- 生成 Dashboard DSL 时，按需读取 [Dashboard DSL API](references/dashboard-dsl-api.md) 导航的拆分文件，不一次加载全部：写板前读 [dashboard-dsl-core.md](references/dashboard-dsl-core.md)（根入口/布局/移动端/字段写法）；挂载或配置具体条目类型读 [dashboard-dsl-items.md](references/dashboard-dsl-items.md)；需要可抄写法或场景模板读 [dashboard-dsl-examples.md](references/dashboard-dsl-examples.md)。仅引用已有组件时无需加载 Widget API。产物顺序不清楚时读取 [产物顺序](references/artifact-ordering.md)。
-- 解释或生成公式时，先用 `formula functions` 查询当前 FineBI 公式面板；绑定真实字段后，用 `calculated-field validate` 执行原生校验。
-- 同一连续任务内复用未变化的已读内容；只有文件变化、进入未读能力，或上下文压缩后所需规则已不可用时，才补读相关部分。实时 capability、目标和文件摘要校验仍按变更契约执行，不以文档复用代替。
+使用本 Skill 完成资源发现、DSL 生成、业务执行和验证。参考资料与 CLI 均随包提供，主流程不依赖源码仓库或另一项 FineBI Skill。
 
 ## 执行入口
 
-默认优先使用内置 CLI。未显式指定入口且内置文件存在时，调用：
+将本文件所在目录记为 `<skill-dir>`，使用绝对路径调用。Node.js 要求 18.17 或更高版本。
 
 ```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
+node "<skill-dir>/scripts/finebi-cli-runner.mjs" inspect <resource> <command> [--profile <name>]
+node "<skill-dir>/scripts/finebi-cli-runner.mjs" run <resource> <command> ... --json [--profile <name>]
 ```
 
-- 入口优先级：显式指定的 `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 结构。
-
-模型来源探查先用 `public-ds search` 确认 `type=METRIC_SET` 来源，再调用 `model source-info --id <sourceId>` 获取字段目录和来源展示提示，无需主题。字段状态、来源文本与后续命名空间确认按 [Model 工作流](references/command-workflows.md#76-model-metric-set) 判读。
-
-生成制品时，先调用 `subject info` 查看 `resources.models` 主题模型摘要，再用 `model search --subject-id <subjectId>` 消歧主题内模型，并用 `model info --subject-id <subjectId> --id <modelId>` 获取具体指标、数据集字段和模型计算字段。若用户要求的指标集尚未属于主题，确认唯一来源和可编辑目标主题；`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` 时报告状态、阻断命令或阶段、已收集只读证据、触发的安全边界，以及继续所需的最小用户操作。不得输出未经验证或可能误导用户执行的写命令。
+- 入口优先级：显式 `FINEBI_CLI_PATH` → 内置 `scripts/finebi-cli/src/index.js` → PATH 中已安装的 `finebi-cli`。显式入口可为 JavaScript 文件、可执行文件或 Windows npm `.cmd`。
+- `config`、`auth`、`capability`、`app` 直接使用所选 CLI；动态业务命令使用 runner。两者必须来自同一安装。全局入口使用 `finebi-cli ...`，JavaScript 入口使用 `node "<入口绝对路径>" ...`。
+- 内置入口存在时不因全局包已安装而替换它。不自动执行 `npm install`、`npm link` 或 `npx`；业务失败不触发换版本重试。缺少入口时说明缺失。
+- 只有远端业务需要可访问的 FineBI、兼容插件和有效身份。首次远端调用前检查连接、认证和 capability；缺少地址或认证输入时请求最小补充。成功登录后确认 capability 刷新成功。
+- 连续任务复用已核实的入口、profile、目标 ID 和未过期的 capability/help；环境、目标前提或 schema 变化时重查。写前复检与删除确认后的实时复检仍按[变更契约](references/mutation-confirmation-contract.md)执行。
+- 多环境任务统一使用 `--profile <name>`；环境发现、登录和默认环境保护见[命令公共规则](references/command-workflows.md#1-使用规则)。不为普通业务任务切换机器默认环境。
+
+## 按任务读取
+
+先选择当前任务所在行，再读取相关章节；不预先加载所有参考。长文先定位标题或关键符号。同一连续任务复用已读内容，上下文压缩或进入新能力时只补读必要部分。
+
+| 当前任务 | 首先读取 | 按需补充 |
+|---|---|---|
+| 查询资源、字段或预览数据 | [命令工作流](references/command-workflows.md) §1 和目标资源章节 | 消费 `dashboard data` 时读[结果契约](references/dashboard-data-result.md)，保留首视图范围与 warnings |
+| Excel/CSV 到分析表、组件和仪表板 | [文件转看板](references/file-to-dashboard.md) | 只读当前阶段所需的 API 与变更规则 |
+| 创建或修改 Analysis DS 步骤 | [Analysis DS 工作流](references/command-workflows.md#71-analysis-ds) | 写 JS 时读 [Analysis DSL API](references/analysis-dsl-api.md) |
+| 新建或修改 Widget | [场景工作流](references/scenario-workflows.md)＋[Widget API 导航](references/widget-dsl-api.md) | [映射规则](references/mapping-rules.md)仅查本次图表、字段与通道；需要推荐写法时读[示例](references/widget-dsl-api-examples.md) |
+| 新建或修改 Dashboard | [场景工作流](references/scenario-workflows.md)＋[Dashboard API 导航](references/dashboard-dsl-api.md) | 仅引用已有组件时无需读 Widget API；来源与顺序见[产物顺序](references/artifact-ordering.md) |
+| 解释、生成或排查公式 | [公式入口](references/formula.md) | 教学/离线模板声明假设；实际主题落地前查询目标主题面板，再以同一份 JS 做 `calculated-field validate` |
+| 动态 HTML 看板、数据 Web 应用 | [应用模板工作流](references/web-app.md) | 本地 `app create` 不需要登录；绑定真实数据时再检查连接与业务能力，开发遵循生成项目 AGENTS.md |
+| FineBI 非只读命令或失败清理 | [变更计划与删除确认](references/mutation-confirmation-contract.md) | 读取本次计划、复检、验证及适用的清理章节 |
+| 跨执行体交接 DSL 任务 | [语义交接](references/handoff-contract.md)＋[DSL 输入契约](references/dsl-handoff-contract.md) | 完整 JSON 与文件映射用于外部交接；同一 Agent 连续执行按场景流程记录必要语义即可 |
+
+## 常用执行路径
+
+1. **查询：** 先用 runner `inspect` 确认目标命令的实时能力、参数与 `mutation`，随后 `run`。已知准确 ID 时直接 `info` 核验名称、归属和所需字段；只有缺少 ID 或需消歧时搜索。宣称名称唯一前遍历搜索的全部分页。
+2. **生成：** 本 Agent 可以自行生成和修复本任务的 DSL 文件。按场景流程核实资源、业务语义和唯一产物路径，再按对应 API 生成并回读自检。路径可由用户指定或安排在当前任务隔离临时目录；不为内部语义对象或路径增加审批。只有用户要求审阅或业务歧义尚未消除时才等待用户决定。
+3. **写入：** 用户要求保存、更新或端到端完成时，生成后按变更契约冻结计划、复检、执行并逐阶段只读验证。仅要求生成本地 DSL 时到文件自检结束，不调用 FineBI 写命令。需要上游实际 ID 才能生成下游文件时分阶段规划，禁止占位 ID。
+4. **输出：** 使用[输出策略](references/command-workflows.md#11-输出与上下文)选择投影或落盘。报告实际结果、实际 ID、验证证据、warnings、未完成项和残留风险；只读回查成功不能代替前端显示与出数验证。
+
+## 关键边界
+
+- 命令存在性、参数、schema 和 `mutation` 以当前连接的 capability/help 为准；`inspect` 只取摘要，不把完整 manifest 放入上下文。读取动态 `template` 前先 inspect，只有 `mutation:false` 才作为只读模板使用。
+- 所有非只读命令完成计划与执行前校验；已授权的 `add/update/data-update` 等非删除动作直接复检执行。只有 `delete` 计划要求 `确认执行 <planId>`，内容变化即使旧确认失效；删除清理同样独立确认。`config/auth/capability` 的必要非删除变更限定在当前任务范围。
+- 不在多个合理资源、字段或关系之间静默选择。字段命名空间、模型来源与主题内模型 ID、组件引用唯一性按对应场景/API 核验，不把同名分析表当作模型。物理字段、模型字段和计算字段的写法见 Widget API 根入口；数据集、模型、字段或关系 ID 不写入 DSL 字段名称。
+- 文件只写入当前任务明确的路径；生成后回读自检，执行前校验 realpath 与 SHA-256。首个写阶段失败即停，汇总实际成功/部分成功资源后重新规划，禁止在原计划内偷偷换参数或文件重试。
+- 密码、token、Cookie、Access Key 不进入命令、日志或回复；密码优先用环境变量或 stdin。业务任务不扫描源码仓库猜命令或绕过 CLI 调内部 API。
+- 能力缺失、歧义或前提不满足时说明阻断阶段、只读证据及继续所需最小输入；不得声称未执行的命令或验证已成功。

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

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

package/skills/finebi-cli-agent/references/artifact-ordering.md

@@ -13,7 +13,7 @@
 
 按以下顺序写入：
 
-1. 校验完整交接对象和文件映射。
+1. 校验语义输入和文件映射；跨执行体使用完整交接 JSON，同一 Agent 可使用已核实的内部记录。
 2. 为每个 `requestedWidgets[]` 生成一个 Widget DSL 文件。
 3. 重新读取并自检全部 Widget 文件。
 4. 当场景为 `CREATE_DASHBOARD` 时生成 Dashboard DSL 文件。
@@ -25,5 +25,5 @@ Dashboard DSL 只通过 `.reference("组件名")` 挂载组件。即使组件属
 
 - 任一 Widget 无法映射时停止，不生成 Dashboard。
 - 已写入文件若随后发现自检失败，只修正文件映射中对应的目标文件；不创建替代文件。
-- 不删除、创建或修改 FineBI 服务端资源。
-- 不负责决定 CLI 写入顺序、确认计划或失败清理，这些属于 Plan Skill。
+- 文件生成阶段不删除、创建或修改 FineBI 服务端资源。
+- CLI 写入顺序、计划和失败清理属于执行阶段。独立 DSL 编写器只返回本地制品；完整 Agent 在用户请求包含保存或更新时，再按变更契约执行远端阶段。

package/skills/finebi-cli-agent/references/command-workflows.md

@@ -14,6 +14,16 @@
 
 搜索结果存在分页时必须遍历完整结果。结果存在多个合理候选时，展示名称、ID 和归属信息，不得静默选择。
 
+已知准确资源 ID 时直接 `info` 核验名称、归属和任务需要的字段，不重新遍历全局搜索。只有名称、归属未知或存在冲突时才搜索；按名称生成 Dashboard 引用仍须证明组件名在解析范围内唯一。连续任务可以复用前提未变化的资源证据；写入仍执行变更契约要求的目标复检。
+
+### 1.1 输出与上下文
+
+- 小结果直接解析 envelope，只向用户呈现任务所需内容，不重复输出原始 stdout。
+- 已知响应结构时用 `--select <paths>` 投影；路径以目标 help/schema 或已有响应为准，不猜字段。保留判断成功/失败、分页、warnings、空结果和部分成功所需的信息；不能通过只选第一条候选制造唯一性。
+- 大型 schema、DSL、数据或未知结构的完整响应用 `--save <绝对路径>` 保存到当前任务隔离目录。stdout 返回的是落盘摘要，业务数据在保存的 JSON envelope 中；随后按需定向读取，不将摘要当作真实查询数据。
+- `--max-chars` 会截断 stdout 文本。runner 需要解析完整 JSON，使用 runner 时选择 `--select` 或 `--save`，不传 `--max-chars`。直接 CLI 的截断输出只能用于快速查看，不能作为完整 JSON、全量候选或验证证据。
+- `--save` 优先于 `--max-chars`；失败 envelope 不做成功数据投影，错误仍应完整检查。落盘文件和摘要可能含业务信息，遵循当前任务的数据与凭据边界。
+
 ## 2. 当前命令矩阵
 
 动态 HTML 看板与数据 Web 应用使用本地 `app create/inspect`，不属于远端 capability；具体开发流程见[应用模板工作流](web-app.md)。
@@ -104,7 +114,26 @@
 （内部试用开关开启的服务器）；正式版默认态下 `add` 仅支持原样引用创建（create/from/fromExcel），
 `template` 仅 `basic` 场景，不得规划改表工作流（见第 2 节 † 注）。
 
-创建与步骤覆盖使用 AnalysisTableDsl JS 文件：`add --subject-id <id> --file <x.js>` 创建新表（DSL `from(表原始名)` 声明来源，原始名= search 返回的 `id`，全局唯一；Excel 源用 `fromExcel(attachId, "Sheet1", ...)`（Sheet 名逐个传字符串），attachId 来自 `upload-excel`），`update --id <id> --file <x.js>` 覆盖步骤链（来源不变，DSL `from` 必须匹配现有来源）。创建后使用响应中的实际 `id`/`ids` 逐一调用 `info`，失败清理必须覆盖 `ids` 中的全部实际 ID。`dsl --id <id>` 反读已保存表的可编辑 DSL 文本（Bean→DSL），适用于「读取 → 修改 → 写回」；写回用 `update`。**影响面透出（2026-08-31）**：`update` 响应带 `changedFields`（保存前后字段差分，rename 以旧名消失 + 新名出现表达）；`dsl` 反读响应带 `resultToIdentifyNameMap`（结果字段名 ≠ identify name 的别名差异条目，组件引用按 identify name 解析）。**别名保留（2026-08-31）**：DSL 可选 `resultName(resultFieldName, identifyName)` 声明（key=最后一步结果字段名=字段转义名，value=对外 identify name；未声明完全交给平台）；`dsl` 反读把别名差异输出为 `.resultName(...)` 声明，写回即幂等——rename 涉及被组件引用的字段时，声明 `resultName("新名", "旧名")` 保留 identify name，组件不失效。改表工作流：`dsl` 看别名层（评估 rename 风险）→ `update` → 看 `changedFields` → 需要保留别名时在 DSL 声明 `resultName(...)` → `verify-data` 验证。AnalysisTableDsl 语句面见 handoff-dsl-writer 的 `analysis-dsl-api.md`（八类步骤 + 可选 resultName 声明：来源/过滤/排序/字段设置/公式列/分组汇总/左右合并/上下合并；`template --scenario <basic|formula|group|full>` 给可替换模板）。**合并步骤（2026-08-31）**：`join("右表原始名", joinType.X).on(左字段, 右字段).renameResult(旧名, 新名)` 左右合并、`union("表A").union("表B").alignField(左, 右).withFields(...).withAllFields().renameResult(...)` 上下合并——右表/合并表**只支持同主题内数据集**（用 `analysis-ds.search` 确认表在当前主题）；结果字段由引擎推导（抽取表合并依据去重成一个字段、直连表全保留）；改名语句是 `renameResult`（避让字段设置的 `rename`）。先按第 4 节区分引擎类型；DIRECT 数据集不得因更新状态或摘要 `usable` 规划、执行 `data-update`。SPIDER 的 `data-update` 可能触发数据重算，不能视为可逆。`delete` 必须独立确认。
+#### 7.1.1 创建与读取
+
+创建与步骤覆盖均使用 AnalysisTableDsl JS 文件。`add --subject-id <id> --file <x.js>` 创建新表，DSL `from(表原始名)` 声明来源；原始名是 search 返回的 `id`，全局唯一。Excel 源用 `fromExcel(attachId, "Sheet1", ...)`，Sheet 名逐个传字符串，attachId 来自 `upload-excel`。
+
+创建后使用响应中的实际 `id`/`ids` 逐一调用 `info`，失败清理必须覆盖 `ids` 中的全部实际 ID。`dsl --id <id>` 反读已保存表的可编辑 DSL 文本（Bean→DSL），用于「读取 → 修改 → 写回」。语句面见 DSL 编写器的 `analysis-dsl-api.md`：来源、过滤、排序、字段设置、公式列、分组汇总、左右合并、上下合并及可选 `resultName` 声明；模板通过 `template --scenario <basic|formula|group|full>` 获取，场景支持以实时能力为准。
+
+#### 7.1.2 更新与字段别名
+
+`update --id <id> --file <x.js>` 覆盖步骤链，来源不变，DSL `from` 必须匹配现有来源。响应 `changedFields` 表示保存前后字段差分，rename 以旧名消失＋新名出现表达。`dsl` 的 `resultToIdentifyNameMap` 列出结果字段名与 identify name 不同的别名；组件引用按 identify name 解析。
+
+`resultName(resultFieldName, identifyName)` 的 key 是最后一步结果字段名（字段转义名），value 是对外 identify name；未声明时交给平台。反读输出 `.resultName(...)`，写回保持别名幂等。重命名涉及被引用字段时，生成 `resultName("新名", "旧名")` 保留 identify name。先读 `dsl` 评估别名风险，在写前准备好别名声明；`update` 后检查 `changedFields` 并验证组件出数，不把 DSL 回读一致当作前端验证通过。
+
+#### 7.1.3 合并与引擎限制
+
+- 左右合并：`join("右表原始名", joinType.X).on(左字段, 右字段).renameResult(旧名, 新名)`。
+- 上下合并：`union("表A").union("表B").alignField(左, 右).withFields(...).withAllFields().renameResult(...)`。
+- 右表和合并表只支持同主题内数据集，使用已核实 ID 的 `info` 或必要的 `analysis-ds.search` 确认归属。结果字段由引擎推导：抽取表合并依据去重成一个字段，直连表全保留；改名使用 `renameResult`，与字段设置的 `rename` 区分。
+- 按第 4 节区分引擎。DIRECT 不因更新状态或摘要 `usable` 执行 `data-update`；SPIDER 的 `data-update` 可能触发重算，不能视为可逆。`delete` 独立确认。
+
+#### 7.1.4 主题共享钻取目录
 
 主题共享钻取目录：`drill-directory.update --subject-id <id> --file <directory.js>` 使用 `DrillDirectoryModel.builder("目录名").levels([from("表").dim("省"), from("表").dim("市")]).build()` 创建，用 `.dissolve()` 解散。`drill-directory.dsl --subject-id <id> --name <目录名>` 回读；目录按主题内精确名称定位。解散保留原字段，操作影响主题共享字段面板；目录重名且层级不同、字段已属于其他目录时拒绝写入，不能隐式覆盖。
 
@@ -118,7 +147,7 @@
 
 ### 7.3 Dashboard 与 Widget
 
-查询仪表板组件时，先从同一来源的 `dashboard info` 读取目标条目的 `queryFields`，用 `selectable=true` 的 `dId` 构造 `dashboard data --dimension-ids '["<dId>"]'`。这些 ID 是组件内部键，不是数据集 fieldId；目录包含关闭的字段，`used` 表示保存状态。省略参数沿用配置，`[]` 关闭全部可选维度；汇总组件的指标保留，明细表按列选择。可同时传 `--filter` 或 `--filters-file`；选择不清除过滤、不保存配置。插件直接依赖支持维度选择和发布来源查询的 Provider；编译构件与部署平台需具备相同接口契约。字段目录、空列表与兼容语义见 `docs/dashboard-command-design.md` 的查询契约。
+查询仪表板组件时，先从同一来源的 `dashboard info` 读取目标条目的 `queryFields`，用 `selectable=true` 的 `dId` 构造 `dashboard data --dimension-ids '["<dimensionDId>","<measureDId>"]'`。这些 ID 是组件内部键，不是数据集 fieldId；目录包含关闭的字段，`used` 表示保存状态。省略参数沿用配置；列表是维度和指标的完整白名单，未列出的可选字段全部关闭。只传维度会关闭未选指标，只传指标会关闭全部可选维度；`[]` 关闭全部可选维度和指标，明细表无列及数据行。可同时传 `--filter` 或 `--filters-file`；选择不清除过滤、不保存配置。插件直接依赖支持维度与指标完整白名单选择和发布来源查询的 Provider；编译构件与部署平台需具备相同接口契约。字段目录、空列表与兼容语义见 `docs/dashboard-command-design.md` 的查询契约。
 
 查询目录发布版时，从 `dashboard search` 的候选位置选定 `locations[].entryId`，对 `dashboard info` 和 `dashboard data` 都携带同一 `--directory-entry-id <directoryEntryId>`。先从该来源的 `info` 获取组件实例 `entries[].entryId` 和控件实际 `filterName`，再查询该组件。检查响应 `source=PUBLISHED_DIRECTORY` 及 `directoryEntryId`；普通来源为 `MY_ANALYSIS`。目录入口不能当作组件实例 ID，平台不支持或目录授权失败时不得丢弃入口参数后重试普通看板。