@finebi/finebi-cli 1.6.1 → 1.6.3

package/skills/finebi-cli-agent/scripts/finebi-cli/src/error-catalog.js

@@ -19,8 +19,8 @@ export const ERROR_CATALOG = [
         recoverableByAgent: true,
         defaultRetryable: false,
         pathSemantics: "Browser authorization base URL",
-        canonicalNextActions: ["finebi-cli config set base-url <https-url>"],
-        expectedAgentBehaviors: ["configure an HTTPS URL or localhost HTTP URL", "rerun browser login"],
+        canonicalNextActions: ["finebi-cli config set base-url <http-or-https-url>"],
+        expectedAgentBehaviors: ["configure an HTTP or HTTPS URL", "rerun browser login"],
         benchmarkTags: ["auth", "browser", "url-validation"],
     },
     {

package/skills/finebi-cli-agent/scripts/finebi-cli/src/help.js

@@ -116,10 +116,13 @@ const BUILT_IN_RESOURCES = {
       },
       {
         name: "inspect",
-        summary: "Check a local web app project configuration without remote validation.",
-        usage: "finebi-cli app inspect --path <project>",
-        options: [{name: "--path", type: "string", description: "Existing project directory; relative paths resolve from the current directory."}],
-        details: ["Checks app-config.json structure and widget bindings locally. Remote dashboard and permission checks are not performed."],
+        summary: "Summarize a local web app configuration; optionally validate against the bundled template.",
+        usage: "finebi-cli app inspect --path <project> [--strict]",
+        options: [
+          {name: "--path", type: "string", description: "Existing project directory; relative paths resolve from the current directory."},
+          {name: "--strict", type: "boolean", description: "Validate against this CLI's bundled template rules; custom app extensions may not match."},
+        ],
+        details: ["By default, reads app-config.json as a JSON object and reports a summary with configValidated: false. --strict enables local template validation. Neither mode validates remote resources or permissions; inspection is not an application acceptance gate."],
       },
     ],
   },
@@ -171,7 +174,7 @@ const BUILT_IN_RESOURCES = {
         examples: [
           "finebi-cli config set base-url http://localhost:37799/webroot/decision",
           "finebi-cli config set timeout-ms 30000",
-          "finebi-cli config set capability-ttl-ms 600000",
+          "finebi-cli config set capability-ttl-ms 72000000",
         ],
       },
       {

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/AGENTS.md

@@ -3,17 +3,30 @@
 ## 开发顺序
 
 1. 用 FineBI CLI 搜索并读取 dashboard info/data，确认唯一来源、看板实例 entryId、queryFields.dId 和真实控件 filterName。按[验收文档](docs/acceptance.md#1-绑定与设计准备)记录指标公式/聚合、单位、时间粒度与时区、筛选作用范围及数据完整性；必要时读取 bean，未知项明确标记，不按组件标题猜语义。
-2. 阅读 [数据契约](docs/data-contract.md)、[筛选](docs/filters.md)、[认证部署](docs/auth-and-deploy.md)，再修改 public/app-config.json。
+2. 按下方[阅读路径](#阅读路径)读取当前步骤需要的章节，再修改 public/app-config.json；不要求开场通读全部文档。
 3. 按[设计选择](docs/design.md#设计选择与信息组织)写出页面面向谁、首屏重点、导航、图表分组和信息密度，遵循用户已确认的方向继续开发。新风格说明与已有布局在结构、层级和视觉上的区别。从 overview、workbench、cockpit 或 retail 起步，示例配置仅含占位绑定。
-4. 先跑通一个指标、一张图和一个真实控件（源看板有控件时）的查询、展示、应用与恢复默认，再扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
+4. 整页绑定前，按[最小真实查询](docs/acceptance.md#11-最小真实查询)先配置一个组件，启动开发页面，通过开发代理确认真实身份、查询、解析和页面值；再补齐本页需要的指标、图表与真实筛选链路，通过后扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
 5. 业务转换放 src/services，页面放 src/pages 或 App.tsx，通用请求与原生解析复用 src/finebi。改动共享组件时检查其他布局，不为换风格复制查询、认证或筛选编码。
 6. 按[分层验收](docs/acceptance.md)执行 npm test、npm run build、浏览器冒烟及真实绑定验收。检查整页和关键状态，分别记录 CLI、开发身份、生产 Cookie 的验证结论；构建成功不等于认证、取数或视觉验收通过。
 
+## 阅读路径
+
+首次进入项目先读本文件、[数据契约](docs/data-contract.md)和[绑定与设计准备](docs/acceptance.md#1-绑定与设计准备)。其余文档在对应步骤读取，同一任务中已读且未变化的章节直接复用。
+
+| 当前步骤 | 阅读内容 |
+|---|---|
+| 配置并启动最小真实查询 | [README 开始](README.md#开始)、[本地开发认证](docs/auth-and-deploy.md#本地开发)、[最小真实查询](docs/acceptance.md#11-最小真实查询) |
+| 绑定真实筛选控件 | [筛选与联动](docs/filters.md)中对应控件类型、作用范围、应用与恢复默认的规则；无控件时无需预读 |
+| 确定页面结构、配置展示或扩展 UI | [设计选择与信息组织](docs/design.md#设计选择与信息组织)及本次布局、展示能力对应章节 |
+| 执行整页验收与交付 | [开发与验收](docs/acceptance.md)第 2–5 节 |
+| 部署或验证生产身份 | [生产认证与部署](docs/auth-and-deploy.md#生产) |
+
 ## 数据规则
 
-- 用 CLI 指定 `--dimension-ids` 时，必须同时列出需要的维度和指标；只传维度会关闭未选指标。模板目前不提供字段选择配置，浏览器查询沿用保存配置；完整语义见[数据契约](docs/data-contract.md#字段选择)。
+- `widgets[].dimensionIds` 为可选字段，常规绑定省略以沿用保存配置；需要指定时列出所需维度和指标的完整白名单，只传维度会关闭未选指标。与 CLI `--dimension-ids` 使用同一来源的可选 dId，完整语义见[数据契约](docs/data-contract.md#字段选择)。
 - 先检查 normalization、warnings、range，再选择唯一 dataset；多模型需显式 datasetId。
 - display 用于显示；计算仅使用 AVAILABLE 的 value，保留 DECIMAL_STRING 精度。禁止从百分比/千分位/单位文本恢复数值。受限值、未知值不能补零。
+- 分组表 BIGROUP 使用 table 展示，按原生汇总标记区分数据、小计和总计；不能混加各类行。交叉表 BICROSS 按 top 槽位对应 left 数值，仅用 table 展示当前矩阵，不能按重复的指标 dId 合并列或固定绑定跨查询槽位。详见 docs/data-contract.md。
 - 不按名称猜字段、不累加 UNKNOWN 行、不从首页估算全量 KPI。KPI 示例仅消费单行结果。
 - 控件筛选通过真实名称生成 refer；无控件时不伪造服务端过滤。搜索和排序的范围必须在页面说明。
 - 筛选绑定先核对源控件类型，配置/状态/请求统一通过 src/finebi/filters.js 校验。完整支持矩阵、逗号和 null 保留字、恢复默认与筛选空值语义见 docs/filters.md；不以更换 type 绕过服务端能力限制。
@@ -21,9 +34,9 @@
 
 ## 认证与交付
 
-- 开发凭证只存在服务端环境 FINEBI_DEV_* 或内存；禁止 VITE_* 凭证、前端 localStorage token、提交 .env 和认证日志。
+- 开发凭证由 Node 从 FINEBI_DEV_* 环境或项目 .env.local 读取；新会话自动保存到 .env.local。优先复用 token，获取时密码优先、浏览器授权兜底，具体流程见 docs/auth-and-deploy.md。禁止 VITE_* 凭证、前端 localStorage token、提交凭据文件和认证秘密日志。
 - 生产应用使用同源当前用户 Cookie。开发代理不属于构建产物；不要把它部署为共享多用户服务。
-- 目录来源配置 directoryEntryId，原生请求保留 reportEntryId；需目标平台 HTTP 接口支持目录权限预检与 MOUNT 查询，不得失败后回退到分析主题。不支持交叉表、服务端续页、全局排序或托管发布命令。
+- 目录来源配置 directoryEntryId，原生请求保留 reportEntryId；需目标平台 HTTP 接口支持目录权限预检与 MOUNT 查询，不得失败后回退到分析主题。不支持服务端续页、全局排序或托管发布命令。
 - 图表按生命周期销毁；异步请求取消且旧响应不得覆盖新条件。失败状态不得展示过期数据充当最新结果。
 - 验收证据、截图和临时脚本放项目 temp/，不随包发布。交付记录已验证/失败/未验证项、运行方式、模板版本和业务绑定范围；模板维护流程由 CLI 源仓库负责，本项目无需其脚本才能开发和验收。
 

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/README.md

@@ -4,14 +4,19 @@
 
 ## 开始
 
+按 [Agent 阅读路径](AGENTS.md#阅读路径)分阶段读取文档，再执行以下步骤。
+
 1. 安装依赖：`npm ci`。
-2. 填写 `public/app-config.json`。`dashboardId` 来自目标看板；`widgets[].entryId` 使用板内实例 ID；图表 `categoryFieldId/valueFieldId` 使用本次 `dashboard info` 的结果字段 dId。相同实例可以有不同展示，但 KPI 必须对应单行查询结果。
-3. 在当前进程设置 `FINEBI_DEV_BASE_URL`（完整 decision 地址）和 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或 `FINEBI_DEV_TOKEN`。不要把值写入 VITE_* 或 app-config。
-4. `npm run dev`，访问 `http://localhost:4173`。开发代理仅监听本机，自动以开发身份登录，凭证不返回浏览器。
-5. 按[开发与验收](docs/acceptance.md)执行 `npm test`、`npm run build`、`npm run test:browser`，再验证真实绑定。浏览器验收页使用合成数据，不连接 FineBI。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
+2. 先在 `public/app-config.json` 中填写一个真实组件的最小绑定。`dashboardId` 来自目标看板；`widgets[].entryId` 使用板内实例 ID；图表 `categoryFieldId/valueFieldId` 使用本次 `dashboard info` 的结果字段 dId。相同实例可以有不同展示，但 KPI 必须对应单行查询结果。
+3. 在项目 `.env.local` 设置 `FINEBI_DEV_BASE_URL`（完整 decision 地址）；有账密时填写 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，只有 SSO 时省略。也可提供已有的 FineBI 会话 `FINEBI_DEV_TOKEN`，不能使用 CLI Access Key。不要把值写入 VITE_* 或 app-config。
+4. `npm run dev`，访问 `http://localhost:4173`。代理优先复用 token，再尝试密码，最后按终端提示进行浏览器授权。新 token 自动保存到 `.env.local`；过期后恢复并重试一次。浏览器授权的服务端插件和 HTTPS 要求见 [认证与部署](docs/auth-and-deploy.md)。
+5. 按[最小真实查询](docs/acceptance.md#11-最小真实查询)核对实际请求与页面值，补齐适用的代表性图表和筛选链路，通过后再扩展整页。
+6. 按[开发与验收](docs/acceptance.md)执行 `npm test`、`npm run build`、`npm run test:browser`，并完成整页真实绑定验收。浏览器验收页使用合成数据，不连接 FineBI。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
 
 ## 配置
 
+`widgets[].dimensionIds` 可选，常规绑定省略以沿用组件保存配置。需要指定维度和指标时填写完整白名单，`[]` 会关闭全部可选字段；示例、代理校验与同实例多绑定规则见[字段选择](docs/data-contract.md#字段选择)。
+
 `layout` 为 `overview`（顶部概览）、`workbench`（侧栏工作台）、`cockpit`（绿色经营驾驶舱）或 `retail`（米白经营简报）。可用 `finebi-cli app create --name my-retail --path <parent> --layout retail` 创建；默认配置仍为空绑定，不会请求示例资源。`maxRows` 默认 1000，上限 10000；`pageSize` 是本地展示页大小，1–100。
 
 ```json
@@ -31,6 +36,8 @@ cockpit 的配置骨架在 [examples/cockpit.config.json](examples/cockpit.confi
 
 retail 的 [examples/retail.config.json](examples/retail.config.json) 提供零售分析绑定骨架：四项 KPI、趋势、门店 TOP10、区域/品类、门店类型和明细。采用横向导航、米白背景和蓝橙图表，不依赖侧栏。示例不含业务数据，`REPLACE_*`、模型选择、时区及筛选作用范围必须核实替换；普通分析来源需删除目录入口占位字段。金额与百分比、毫秒月份的显式显示配置见[页面骨架](docs/design.md)。
 
+分组表 BIGROUP 可使用 `type: "table"` 展示，保留分组键及小计、总计行；字段和值状态、首页范围见[数据契约](docs/data-contract.md#分组表)。交叉表 BICROSS 同样绑定为 `type: "table"`，按行列分组路径显示当前矩阵；通常省略 tableFieldIds，以保留随查询变化的全部交叉列。它不提供服务端翻页、节点展开或原生合并单元格，字段和双轴范围见[交叉表契约](docs/data-contract.md#交叉表)。
+
 目录发布看板在配置中增加 `directoryEntryId`，使用与该入口匹配的 dashboardId/实例。模板将其原样作为 `reportEntryId` 传给 Cookie 查询接口及开发代理；目标平台需同时支持目录权限预检和 MOUNT 查询，不能只支持 CLI 目录查询。错误独立显示，不回退“我的分析”。
 
-筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 仅检查本地配置，绑定后仍需验证真实条件生效。
+筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 默认只查看配置摘要；可选 `--strict` 检查与 CLI 内置模板规则的兼容性，不作为定制应用验收门禁。绑定后仍需通过项目测试、构建与真实浏览器验证条件生效。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/acceptance.md

@@ -10,12 +10,25 @@
 |---|---|
 | 来源 | CLI profile、目标地址、dashboardId、目录入口或分析主题；板内实例 entryId |
 | 字段与指标 | queryFields.dId、选定 datasetId、维度/指标、公式或聚合、单位；记录数不能自动解释为去重对象数 |
+| 字段选择 | 常规绑定省略 dimensionIds；配置时核对完整白名单与输出列，分别验证省略、维度加指标、仅指标和空列表；同实例不同展示绑定分别核对请求 |
 | 时间 | 时间粒度、原值编码、显示时区；日期条件与时间戳轴标签分开核实 |
 | 筛选 | 真实控件名、类型、默认行为、候选项来源、组件作用范围；无源控件时不添加服务端筛选 |
 | 范围 | 返回行数、hasNext、normalization、warnings；不根据首页推算全量 |
 | 设计 | 使用者和主要决策、首屏重点、导航/分组/密度，与既有布局的区别 |
 
-先完成一个指标、一张图，以及存在时的一个真实筛选：源结果 → 页面值 → 应用条件 → 恢复保存默认。证据不足时说明未知项，继续不依赖该项的工作。
+清单先覆盖最小绑定，扩展组件时逐项补齐；不必先完成整板配置。证据不足时说明未知项，继续不依赖该项的工作。
+
+### 1.1 最小真实查询
+
+在配置整页组件之前，先验证开发页面的真实取数链路：
+
+1. 用同一来源的 CLI info/data 选择一个模板支持且有可核对数据的组件，例如单行 KPI；检查 resultType、normalization、warnings、range 和结果字段，不按标题或 chartType 判断可用性。CLI 查询成功仅用于准备绑定，不能证明浏览器适配和开发身份可用。
+2. 在 public/app-config.json 中只填写该组件的真实绑定及必要配置；目录来源保留 directoryEntryId，需要字段选择时保留相同 dimensionIds。不要先复制整页占位组件，也不为测试凭空创建源指标或控件。
+3. 按 [README 开始](../README.md#开始)安装依赖、配置开发身份并运行 npm run dev。打开实际应用，通过开发代理触发原生查询；优先复用已有会话，需要登录时遵循[本地开发认证](auth-and-deploy.md#本地开发)，不要把 CLI Access Key 当作会话 token，也不要在已有会话可用时重复索要密码。
+4. 核对请求来源和参数、业务响应、适配状态与页面显示值。单凭 HTTP 200、CLI 成功或合成验收页 PASS 不算通过；空结果只能证明当前空态，需另选有可核对数据的组件或条件验证值的消费。脱敏证据放项目 temp/，不得记录凭证。
+5. 该组件通过后，按本页需求补齐一个指标和一张图的代表性绑定；源中不存在或本页不需要的类型注明不适用。有真实筛选时验证“源结果 → 页面值 → 应用条件 → 恢复保存默认”，确认请求及显示与条件一致。完成这些适用检查后再扩展整页，并继续验证新增绑定。
+
+身份、权限、接口或适配失败时，记录失败层与原因，先解决当前链路再扩大绑定；缺少访问条件时可继续不依赖真实数据的设计工作，但真实查询须标记未验证。开发身份通过不代表生产 Cookie 验证通过，身份边界见第 4 节。
 
 ## 2. 本地自动检查
 

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/auth-and-deploy.md

@@ -2,9 +2,24 @@
 
 ## 本地开发
 
-Vite开发插件读取服务端环境 `FINEBI_DEV_BASE_URL`、`FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或已有短期 `FINEBI_DEV_TOKEN`。BASE_URL必须是目标完整decision地址。支持由本地.env.local提供，禁止提交文件；不要使用VITE_前缀。
+Vite开发插件读取项目 `.env.local` 或进程环境中的 `FINEBI_DEV_BASE_URL`（完整 decision 地址），可选 `FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD` 和已有 FineBI 会话 `FINEBI_DEV_TOKEN`。进程环境优先；不要使用 `VITE_` 前缀，不要把 CLI Access Key 填入 TOKEN。
 
-代理在内存保存开发会话，只接受本机同源、带XMLHttpRequest标记的POST；白名单限制为配置看板及组件查询，不代理登录管理或任意接口。浏览器无需持有开发账号凭证。失效返回AUTH_REQUIRED；密码方式下一次显式重试重新登录，token方式需更新token并重启开发服务。不要向他人开放开发服务端口。
+```dotenv
+FINEBI_DEV_BASE_URL=https://bi.example/webroot/decision
+# 有用户名密码时填写；只有 SSO 时省略这两项。
+FINEBI_DEV_USERNAME=your-user
+FINEBI_DEV_PASSWORD=your-password
+```
+
+首次查询按以下顺序认证：复用有效 token；需要登录时先尝试配置的用户名密码；没有完整账密或密码明确被拒绝时，终端显示浏览器授权链接和确认码，并尝试打开浏览器。先通过客户原 FineBI/SSO 入口登录，再打开授权链接核对账号与确认码。开发进程主动轮询领取会话，不要求 FineBI 服务器连接本机，也不改变 SSO 回跳地址。
+
+浏览器授权要求服务端插件提供 `/api/bi-cli/dev-session-auth/*`，使用 HTTPS（仅回环允许 HTTP）。旧插件返回 `AUTH_PLUGIN_REQUIRED`，应更新插件；密码路径不依赖新增端点。客户端终端只显示授权地址、确认码、账号与状态，不显示密码或 token。
+
+新会话写入 `.env.local` 的 `FINEBI_DEV_TOKEN`、`FINEBI_DEV_TOKEN_BASE_URL`、`FINEBI_DEV_TOKEN_USERNAME`；保留其他配置，缺少 BASE_URL 时补入本次地址。保存的 token 与目标地址绑定，切换地址不复用旧 token。文件写入先限制权限（POSIX 0600；Windows 当前用户、SYSTEM、Administrators），失败返回 `AUTH_STORAGE_FAILED`。文件禁止提交或随包发布。token 只由 Node 读取；授权交出的是真实会话权限，并非仅限本应用看板。
+
+明确过期时清除保存的旧 token，按上述顺序恢复，再重试原查询一次。并发请求共享认证；旧请求不能清除新会话。再次失效、授权拒绝或超时后返回 `AUTH_REQUIRED`，用户处理后点击重试。密码明确拒绝后本次运行不重复尝试；网络故障、上游 5xx、查询 403 不触发浏览器授权。认证文件保存会更新内存，不需要重启；手动修改地址或账密配置后需重启开发服务。若进程环境还设置了旧 TOKEN，它会覆盖文件，重新启动前应移除该覆盖。
+
+代理只接受本机同源、带 XMLHttpRequest 标记的 POST；白名单限制为配置看板及组件查询，不向浏览器开放登录管理或任意接口。不要向他人开放开发服务端口。Vite 禁止访问 `.env*` 和 `temp/`，关闭服务会取消待完成的授权。会话有效期由 FineBI 决定；SSO 的 IP/终端/附加 Cookie 约束、退出登录行为及多节点部署需在客户环境验证，自动化测试不等于所有 SSO 已兼容。
 
 代理使用共享筛选校验器校验配置与 refer，类型、编码、候选值和默认语义统一见[筛选契约](filters.md)，不维护独立编码规则。
 

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/data-contract.md

@@ -1,38 +1,66 @@
-# 数据契约与适配范围
-
-## 输入与版本
-
-浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；v1 浏览器只覆盖 DETAIL 和 CHART，不等于 Java 适配器的全部覆盖。
-
-配置 directoryEntryId 时请求增加 reportEntryId，开发代理校验来源与配置严格相等后透传。目标平台 HTTP 查询服务需同时支持目录权限预检与 MOUNT 模式；仅升级 CLI Provider 不代表该 HTTP 入口已支持。权限/版本错误直接呈现，不移除入口后重试。各展示组件独立请求，批量加载限制三路并发，单个组件失败不遮蔽其他结果；同一原生实例可有不同展示和筛选绑定。
-
-### 字段选择
-
-当前模板没有字段选择配置，浏览器请求不传 `dimensionSelections`，因此沿用组件保存的维度和指标配置。页面展示字段的绑定不等于服务端字段选择；用 CLI 验证自定义选择得到的结果，也不代表模板会自动使用同一选择。
-
-支持完整白名单语义的平台接口通过 `dimensionSelections` 按组件指定维度和指标的 `dId` 列表；CLI 对应参数为 `dashboard data --dimension-ids`。ID 从同一来源的 `dashboard info` 中目标实例的 `queryFields` 取得，只选 `selectable=true` 的字段，包括已关闭但仍可选择的字段；不能用字段名或底层数据集字段 ID 代替。
-
-- 不传选择项时沿用保存配置。
-- 显式列表是维度和指标的完整白名单，未列出的可选字段全部关闭；需要维度和指标同时输出时必须一起列出。
-- 只传维度会关闭未选指标，只传指标会关闭全部可选维度；`[]` 关闭全部可选维度和指标，不保证各组件都有有效输出，明细表不返回列及数据行。
-- 选择只影响本次查询，不保存配置、不清除过滤、不按列表顺序重排字段，也不能添加组件未配置的字段。
-
-这套语义要求目标平台 Provider/HTTP 查询接口支持维度和指标完整白名单；只升级 CLI 不会为模板增加字段选择能力。
-
-## 消费顺序
-
-检查 normalization（COMPLETE/PARTIAL/UNSUPPORTED）→ warnings → 选唯一 dataset → 按 columns 解释 rows[].cells → 按 range 说明范围。COMPLETE 只表示本次结构转换完整，不表示全集。多模型需指定 datasetId；UNKNOWN 行不得自动求和。
-
-columns 含 key、fieldId、name、type、encoding。key 仅在本次dataset内唯一；fieldId 是结果字段ID，不能当底层数据集字段ID。绑定使用fieldId，不使用可能重复的name。
-
-cells 含 value、display、state、reason：AVAILABLE 可用，NULL 确认空值，UNAVAILABLE 无法可靠解释，RESTRICTED 权限受限。表格优先显示 display，受限单元格统一显示“受限”。计算不能从 display 反解析数字；DECIMAL_STRING 保留上游值，JS Number 仅用于图形坐标且不能用于高精度金额计算。DATE 的 EPOCH_MILLIS_STRING 保留毫秒字符串，不擅自改变时区。日期元数据支持原生类型3、13、15、20；未知类型保守返回不可用。
-
-浏览器适配器不能获知服务端 cellCharLimit，字符串不能据此承诺未经截断的数据库原文。图表可见数值不代表底层明细；数值型字符串不会被猜成图表指标。交叉表/分组表及缺少内联模型的图形明确为不支持；多模型、computedState 和缺列都会保留警告。
-
-## 范围
-
-明细表 range.total 采用有效原生row；PAGE是本次首页，pageLimit不提供续页。hasNext=true 原样保留并产生 NEXT_PAGE_UNSUPPORTED；即使返回数等于总数，也不覆盖这一状态。当前仅提供已加载结果的搜索、排序和分页，页面显示该范围。图表UNPAGED也不等于底层明细全量，可能存在Top N或聚合。
-
-服务端返回空数组与缺失组件不同：前者可显示空数据，后者是 INVALID_RESPONSE。受限/失败/不支持结果不回退静态样本。
-
-表格排序使用 AVAILABLE 的 value，DECIMAL_STRING 按十进制字符串比较，支持合法指数而不转换为浮点金额；缺值排在可用值之后。搜索、展示筛选和 CSV 使用 displayCell 的统一值状态呈现；CSV 导出当前匹配集合而非仅当前页，含 UNKNOWN 行标识并转义公式前缀。图表坐标允许 Number 近似，展开数据表保留原始显示值。经营观察仅消费当前结果的状态、行数和单值 KPI，不自动累加 UNKNOWN 行或推断业务比率。
+# 数据契约与适配范围
+
+## 输入与版本
+
+浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；浏览器覆盖 DETAIL、BIGROUP、BICROSS 和 CHART。交叉表采用下述浏览器矩阵契约；CLI Java 标准化器的交叉表支持范围独立，不由浏览器能力推断。
+
+配置 directoryEntryId 时请求增加 reportEntryId，开发代理校验来源与配置严格相等后透传。目标平台 HTTP 查询服务需同时支持目录权限预检与 MOUNT 模式；仅升级 CLI Provider 不代表该 HTTP 入口已支持。权限/版本错误直接呈现，不移除入口后重试。各展示组件独立请求，批量加载限制三路并发，单个组件失败不遮蔽其他结果；同一原生实例可有不同展示和筛选绑定。
+
+### 字段选择
+
+`widgets[].dimensionIds?: string[]` 是可选的服务端字段选择配置。常规绑定省略该字段，浏览器不为该实例发送选择项，沿用组件保存的维度和指标启用状态；不会强制启用保存态隐藏字段。显式配置时，请求发送 `dimensionSelections: { [entryId]: dimensionIds }`。页面展示字段的绑定不等于服务端字段选择；CLI 查询使用的列表需要显式写入对应展示绑定才会在模板中生效。
+
+支持完整白名单语义的平台接口通过 `dimensionSelections` 按组件指定维度和指标的 `dId` 列表；CLI 对应参数为 `dashboard data --dimension-ids`。ID 从同一来源的 `dashboard info` 中目标实例的 `queryFields` 取得，只选 `selectable=true` 的字段，包括已关闭但仍可选择的字段；不能用字段名或底层数据集字段 ID 代替。
+
+- 不传选择项时沿用保存配置。
+- 显式列表是维度和指标的完整白名单，未列出的可选字段全部关闭；需要维度和指标同时输出时必须一起列出。
+- 只传维度会关闭未选指标，只传指标会关闭全部可选维度；`[]` 关闭全部可选维度和指标，不保证各组件都有有效输出，明细表不返回列及数据行。
+- 选择只影响本次查询，不保存配置、不清除过滤、不按列表顺序重排字段，也不能添加组件未配置的字段。
+
+配置只接受无重复、无空白项的字符串数组，`null` 非法；不能用 `[]` 代替省略。需要同时输出城市和销售额时，可在目标 `widgets[]` 条目添加以下属性（占位 ID 需替换）：
+
+```json
+"dimensionIds": ["<城市dId>", "<销售额dId>"]
+```
+
+各展示绑定独立查询；同一 `entryId` 可以配置不同的字段选择。直接调用批量 `queryWidgets` 时，同一实例必须使用相同选择集合，否则拒绝请求；列表顺序不影响集合比较，省略与 `[]` 不等价。开发代理校验选择属于请求实例，且匹配该实例至少一个配置绑定，再原样转发；不会丢弃选择或补回指标。
+
+这套语义要求目标平台 HTTP 查询接口支持维度和指标完整白名单，CLI 验证还需对应 Provider 支持。未选字段上的过滤继续生效；展示绑定必须与所选输出相符，缺列不能补零。模板不提供运行时字段选择器。
+
+## 消费顺序
+
+检查 normalization（COMPLETE/PARTIAL/UNSUPPORTED）→ warnings → 选唯一 dataset → 按 columns 解释 rows[].cells → 按 range 说明范围。COMPLETE 只表示本次结构转换完整，不表示全集。多模型需指定 datasetId；UNKNOWN 行不得自动求和。
+
+columns 含 key、fieldId、name、type、encoding。key 仅在本次dataset内唯一；fieldId 是结果字段ID，不能当底层数据集字段ID。绑定使用fieldId，不使用可能重复的name。
+
+cells 含 value、display、state、reason：AVAILABLE 可用，NULL 确认空值，UNAVAILABLE 无法可靠解释，RESTRICTED 权限受限。表格优先显示 display，受限单元格统一显示“受限”。计算不能从 display 反解析数字；DECIMAL_STRING 保留上游值，JS Number 仅用于图形坐标且不能用于高精度金额计算。DATE 的 EPOCH_MILLIS_STRING 保留毫秒字符串，不擅自改变时区。日期元数据支持原生类型3、13、15、20；未知类型保守返回不可用。
+
+浏览器适配器不能获知服务端 cellCharLimit，字符串不能据此承诺未经截断的数据库原文。图表可见数值不代表底层明细；数值型字符串不会被猜成图表指标。缺少内联模型的图形明确为不支持；多模型、computedState 和缺列都会保留警告。
+
+### 分组表
+
+原生 BIGROUP 转为 GROUP_TABLE，提供 main 数据集。按 header 的 dId 对齐列，递归保留父级分组键；节点有指标或为叶子时输出行，不丢弃父级汇总。指标采用原生 value，缺失时只接受 text 中的规范十进制数值，不反解析 formatText、单位或百分号。分组键只有明确的字符串类型可作为 value，数值/日期分组保留展示文本并标记 GROUP_KEY_SEMANTICS_UNKNOWN，不冒充原始字段值。
+
+行类型依据指标的 rowSumInfo：DATA、SUBTOTAL、GRAND_TOTAL；标记缺失、冲突或同一行指标分类不一致时为 UNKNOWN，不根据“合计”等标题猜测。表格显示数据／小计／总计，CSV 保留行类型。父级键、指标权限及字段歧义分别保留；重复指标不取第一个充数，不把缺值补零。含小计、总计或 UNKNOWN 的数据集不能直接累加所有行。
+
+### 交叉表
+
+原生 BICROSS 转为 CROSS_TABLE/main，以当前返回视图的矩阵展示。按 top 树叶子及其 values 的顺序建立列槽位，再按同一位置读取 left 叶子 values；保留多级分组、指标横排/竖排及原生合计位置，不按重复的指标 dId 合并交叉列。top/left 都必须存在。没有列维度时，平台返回空 top 轴，使用 left 有序指标槽位；空视图与缺失轴结构分开处理。
+
+首列 fieldId 为 `cross:row`，展示行分组完整路径；后续列为 `cross:0`、`cross:1` 等本次查询的槽位 ID，标题拼接列分组路径。这些 ID 不是 FineBI 的 dId，不能用于 dimensionIds 或跨查询固定字段绑定。通常只配置 `type: "table"`，省略 tableFieldIds/localFilterFieldIds 以展示全部返回列；按原生指标 dId 配置图形或 KPI 不适用于这个矩阵。模板展示路径标题，不复刻原生合并单元格、树展开和布局样式。
+
+`columns[].path` 和 `rows[].path` 保留有序 `{fieldId,label,state}`，值单元格的 `sourceFieldId` 保留原生指标 dId。展示标题中，追加的指标名称与末级列分组名称相同时只显示一次，指标放在行维度时，仅当末级路径的 fieldId 与该行非空指标 dId 一致，且名称与前一级相同时，隐藏末级重复标题。两种去重均不折叠真实分组层级的同名标签，不修改 path 或单元格映射。DATA 行展示时省略内部 `__summary_dim_id__` 承载节点的“合计”，保留真实业务分组名称及完整 path。
+
+行 kind 来自 rowSumInfo；列 kind 及单元格 columnKind 来自 colSumInfo，未知或冲突保持 UNKNOWN。列小计/总计明确标注，CSV 保留展示路径标题与行类型；不能混加各级汇总。受限轴标签显示“受限”，关联单元格也保持受限。具有非空指标 dId、authority=true 且 value/text/formatText 均显式为 null 的单元格为 NULL，表格和 CSV 显示“—”；无指标的结构占位、缺失值载荷或权限未知仍为 UNAVAILABLE，不补零。
+
+返回值少于列槽位时标记 PARTIAL，缺格保留 MISSING_CELL；原生列指标 ID 与对应数值 ID 冲突时标记 PARTIAL/AMBIGUOUS_FIELD。数值多于列槽位、轴缺失或节点同时携带子树与非空 values 的未覆盖结构标记 UNSUPPORTED，不能截掉多余值或按猜测顺序对齐。
+
+## 范围
+
+明细表 range.total 采用有效原生row；PAGE是本次首页，pageLimit不提供续页。hasNext=true 原样保留并产生 NEXT_PAGE_UNSUPPORTED；即使返回数等于总数，也不覆盖这一状态。普通分组表的分页单位为 GROUP，总组数未知；展开后的 returnedRowCount 可以超过首页组数。开启 showRowHeaderIcon 的表头展开模式标记 INITIAL_VIEW，不给出普通页码或续页状态；原生 hasNext 仍产生续页警告。当前仅提供已加载结果的搜索、排序和分页，页面显示该范围。图表UNPAGED也不等于底层明细全量，可能存在Top N或聚合。
+
+交叉表 range.mode 为 INITIAL_VIEW，page/pageSize/pageUnit/total 均不声明普通表格分页或总数。`range.axes.horizontal/vertical` 分别保留原生 X/Y 的 hasNext/hasPrevious；任一方向还有数据即给出 NEXT_PAGE_UNSUPPORTED。合并 hasNext/hasPrevious 只有两轴均明确为 false 才为 false，否则保留 true 或未知。页面分别显示横向、纵向还有数据的状态；本地分页、搜索、排序和 CSV 只覆盖当前返回矩阵，不请求服务端续页或展开节点。
+
+服务端返回空数组与缺失组件不同：前者可显示空数据，后者是 INVALID_RESPONSE。受限/失败/不支持结果不回退静态样本。
+
+表格排序使用 AVAILABLE 的 value，DECIMAL_STRING 按十进制字符串比较，支持合法指数而不转换为浮点金额；缺值排在可用值之后。搜索、展示筛选和 CSV 使用 displayCell 的统一值状态呈现；CSV 导出当前匹配集合而非仅当前页，保留数据、小计、总计及 UNKNOWN 行标识并转义公式前缀。图表坐标允许 Number 近似，展开数据表保留原始显示值。经营观察仅消费当前结果的状态、行数和单值 KPI，不自动累加 UNKNOWN 行或推断业务比率。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/docs/filters.md

@@ -8,7 +8,7 @@
 
 开发时从同一看板的 `dashboard info` 获取真实控件 `filterName` 和实例信息，必要时读取 `dashboard bean` 确认控件类型、绑定字段、保存默认值和作用范围。`name` 必须使用解码后的真实控件名；`label` 仅用于显示。重名控件需先在源看板消除歧义，不能用 label 或组件 ID 替代请求键。没有控件时 `filters` 保持空数组，不把任意字段伪造成服务端筛选。
 
-`app inspect` 和浏览器只检查本地配置，不访问远端，也不能证明控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
+`app inspect` 默认只展示配置摘要，`--strict` 才按 CLI 内置模板规则检查。浏览器加载配置时使用项目内的校验规则；本地配置校验不能证明远端控件类型或作用范围正确。交付前必须用真实接口证明条件生效。配置不复制源看板默认值，恢复默认后由服务端读取当前保存条件。
 
 ### 1.2 条件组合与刷新
 
@@ -87,7 +87,7 @@
 更换同语义 UI 组件时，沿用表中的状态类型和统一编码器。新增能力按以下链路扩展：
 
 1. 确认源控件的类型、名称、字段、默认值、作用范围及真实请求编码，区分浏览器内部控件状态与 HTTP refer 协议；检查目标部署版本确实支持覆盖。
-2. 扩展 `src/finebi/types.ts` 和 `filters.js` 中的配置、状态校验、编码和反向请求校验。CLI 的 `app inspect`、客户端和开发代理共用该模块，不另建一套允许列表。
+2. 扩展 `src/finebi/types.ts` 和 `filters.js` 中的配置、状态校验、编码和反向请求校验。客户端和开发代理共用项目内该模块，不另建一套允许列表。CLI 的 `app inspect --strict` 使用随 CLI 分发的模板模块，不能用它约束定制项目的扩展。
 3. 在 `FilterBar` 或业务页面接入控件。动态候选项必须有经过验证的接口、访问者权限、搜索/分页语义、加载失败状态、依赖条件和请求取消策略；级联还须定义上游变化后下游选择的保留或清除方式。不从样本推断完整候选项。
 4. 测试合法值、非法值、保留字、名称冲突、空值、恢复默认、开放区间和组合提交；再用真实看板核对请求、数据范围与组件展示。源码或单测通过不能代替部署与浏览器验收。
 5. 同步本契约、模板支持摘要并重新生成分发物。图表库和 UI 组件库选型见[页面骨架](design.md)。

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/gitignore.template

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+temp/
+.env
+.env.local
+.env.*.local

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/scripts/browser-session.mjs

@@ -0,0 +1,59 @@
+import {spawn} from 'node:child_process';
+
+function openBrowser(url) {
+  const [command,args]=process.platform==='win32' ? ['rundll32.exe',['url.dll,FileProtocolHandler',url]]
+    : process.platform==='darwin' ? ['open',[url]] : ['xdg-open',[url]];
+  const child=spawn(command,args,{stdio:'ignore',windowsHide:true});child.on('error',()=>{});child.unref();
+}
+
+export function sleep(ms,signal) {
+  return new Promise((resolve,reject)=>{
+    if(signal?.aborted){reject(Error('AUTH_REQUIRED'));return;}
+    const abort=()=>{clearTimeout(timer);reject(Error('AUTH_REQUIRED'));};
+    const timer=setTimeout(()=>{signal?.removeEventListener('abort',abort);resolve();},ms);
+    signal?.addEventListener('abort',abort,{once:true});
+  });
+}
+
+export async function authRequest(url,body,{fetchImpl=fetch,signal}={}) {
+  const controller=new AbortController();
+  const abort=()=>controller.abort();
+  if(signal?.aborted)abort();else signal?.addEventListener('abort',abort,{once:true});
+  const timer=setTimeout(abort,30000);
+  try {
+    const response=await fetchImpl(url,{method:'POST',redirect:'manual',headers:{'Content-Type':'application/json'},body:JSON.stringify(body),signal:controller.signal});
+    const payload=await response.json().catch(()=>null);
+    return {response,payload};
+  } catch {throw Error(signal?.aborted?'AUTH_REQUIRED':'UPSTREAM_UNAVAILABLE');}
+  finally {clearTimeout(timer);signal?.removeEventListener('abort',abort);}
+}
+
+export async function browserSession(baseUrl,options={}) {
+  const {signal,notify=console.info,openBrowser:launch=openBrowser,sleep:wait=sleep}=options;
+  const target=new URL(baseUrl);
+  if(target.protocol!=='https:' && !(target.protocol==='http:' && ['localhost','127.0.0.1','[::1]'].includes(target.hostname)))throw Error('AUTH_HTTPS_REQUIRED');
+  const root=baseUrl.replace(/\/$/,'')+'/api/bi-cli/dev-session-auth';
+  const started=await authRequest(root+'/start',{description:'FineBI Web 本地开发'},options);
+  if(started.response.status===404)throw Error('AUTH_PLUGIN_REQUIRED');
+  if(!started.response.ok)throw Error('AUTH_UNAVAILABLE');
+  const data=started.payload?.data;
+  if(!data || !/^[A-Za-z0-9_-]{43}$/.test(data.deviceCode) || !/^[A-Z2-9]{4}-[A-Z2-9]{4}$/.test(data.userCode)
+    || data.verificationPath!==`/api/bi-cli/dev-session-auth/authorize?code=${data.userCode}` || data.expiresIn!==600 || data.interval!==5)throw Error('AUTH_PROTOCOL_ERROR');
+  const verification=baseUrl.replace(/\/$/,'')+data.verificationPath;
+  notify(`请先通过原有入口登录 FineBI，再打开授权页：${verification}\n核对确认码：${data.userCode}。授权会将当前账号会话保存到本地 .env.local。`);
+  try{await launch(verification);}catch{notify('未能打开浏览器，请手动打开上述授权页。');}
+  const deadline=Date.now()+data.expiresIn*1000;
+  while(Date.now()<deadline && !signal?.aborted) {
+    await wait(data.interval*1000,signal);
+    const polled=await authRequest(root+'/poll',{deviceCode:data.deviceCode},options);
+    if(polled.response.status===429)continue;
+    if(polled.response.status===404)throw Error('AUTH_REQUIRED');
+    if(!polled.response.ok)throw Error('AUTH_UNAVAILABLE');
+    const result=polled.payload?.data;
+    if(result?.status==='pending')continue;
+    if(result?.status==='approved' && typeof result.token==='string' && /^[\x21-\x7e]+$/.test(result.token) && !/[;,]/.test(result.token) && typeof result.username==='string')return result;
+    if(['denied','expired','consumed'].includes(result?.status))throw Error('AUTH_REQUIRED');
+    throw Error('AUTH_PROTOCOL_ERROR');
+  }
+  throw Error('AUTH_REQUIRED');
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/scripts/dev-proxy.mjs

@@ -1,24 +1,13 @@
 // Development only: the browser never receives the developer's session token.
 import {validateRefer} from '../src/finebi/filters.js';
-export function createDevMiddleware(config, env = process.env, fetchImpl = fetch) {
+import {validateDimensionSelections} from '../src/finebi/config.js';
+import {createDevSession} from './dev-session.mjs';
+export function createDevMiddleware(config, env = process.env, fetchImpl = fetch, sessionOptions = {}) {
   const prefix = config.basePath.replace(/\/$/, '');
   const queryPath = `${prefix}/v5/api/dashboard/report/${encodeURIComponent(config.dashboardId)}/widgets/query`;
-  let token = env.FINEBI_DEV_TOKEN || '';
-  let login;
+  const session = createDevSession(env,{...sessionOptions,fetchImpl});
   const reply = (res, status, errorCode) => {res.writeHead(status, {'Content-Type':'application/json','Cache-Control':'no-store'});res.end(JSON.stringify({success:false,errorCode}));};
-  async function session() {
-    if (token) return token;
-    if (!env.FINEBI_DEV_USERNAME || !env.FINEBI_DEV_PASSWORD) throw new Error('AUTH_REQUIRED');
-    if (!login) login = (async()=>{
-      const response = await fetchImpl(`${env.FINEBI_DEV_BASE_URL.replace(/\/$/, '')}/login`, {method:'POST',redirect:'error',headers:{'Content-Type':'application/json'},body:JSON.stringify({username:env.FINEBI_DEV_USERNAME,password:env.FINEBI_DEV_PASSWORD,encrypted:false,tenantId:''}),signal:AbortSignal.timeout(30000)});
-      const body = await response.json();
-      if (!response.ok || typeof body?.data?.accessToken !== 'string' || !body.data.accessToken) throw new Error('AUTH_REQUIRED');
-      token=body.data.accessToken;
-      return token;
-    })().finally(()=>{login=undefined;});
-    return login;
-  }
-  return async (req, res, next) => {
+  const middleware = async (req, res, next) => {
     const pathname = new URL(req.url, 'http://localhost').pathname;
     if (!pathname.startsWith(prefix+'/') && pathname !== prefix) return next();
     const host = req.headers.host || '';
@@ -33,25 +22,37 @@ export function createDevMiddleware(config, env = process.env, fetchImpl = fetch
       if (!Array.isArray(body.widgetIds) || !body.widgetIds.length || body.widgetIds.some(id=>!config.widgets.some(w=>w.entryId===id)) || !Number.isSafeInteger(body.pageLimit) || body.pageLimit<1 || body.pageLimit>config.maxRows) throw new Error('INVALID_REQUEST');
       if(body.reportEntryId!==config.directoryEntryId)throw new Error('INVALID_SOURCE');
       validateRefer(config.filters || [],body.refer);
+      validateDimensionSelections(config.widgets,body.widgetIds,body.dimensionSelections);
     } catch {return reply(res,400,'INVALID_REQUEST');}
     if (!env.FINEBI_DEV_BASE_URL) return reply(res,401,'AUTH_REQUIRED');
     try {
       const target = new URL(env.FINEBI_DEV_BASE_URL);
       if (!['http:','https:'].includes(target.protocol) || target.username || target.password || target.search || target.hash) throw new Error('INVALID_TARGET');
-      const auth=await session();
+      for(let attempt=0;attempt<2;attempt++) {
+      const auth=await session.get();
       const response=await fetchImpl(`${target.href.replace(/\/$/, '')}/v5/api/dashboard/report/${encodeURIComponent(config.dashboardId)}/widgets/query`, {
         method:'POST',redirect:'manual',signal:AbortSignal.timeout(30000),
         headers:{'Content-Type':'application/json','X-Requested-With':'XMLHttpRequest',Cookie:`fine_auth_token=${auth}`},
-        body:JSON.stringify({widgetIds:body.widgetIds,includeWidgetBean:true,pageLimit:body.pageLimit,refer:body.refer || {},...(config.directoryEntryId?{reportEntryId:config.directoryEntryId}:{})}),
+        body:JSON.stringify({widgetIds:body.widgetIds,includeWidgetBean:true,pageLimit:body.pageLimit,refer:body.refer || {},...(config.directoryEntryId?{reportEntryId:config.directoryEntryId}:{}),...(body.dimensionSelections!==undefined?{dimensionSelections:body.dimensionSelections}:{})}),
       });
-      if (response.status===401 || response.status>=300 && response.status<400 || response.headers.get('content-type')?.includes('text/html')) {token='';return reply(res,401,'AUTH_REQUIRED');}
-      if (response.status===403) return reply(res,403,'PERMISSION_DENIED');
-      const json=await response.json();
-      if (response.status===401 || ['TIME_OUT','JWT_EXPIRED','LOGIN_INFO_NOT_AVAILABLE','CANNOT_GET_TOKEN'].includes(json.errorCode)) {token='';return reply(res,401,'AUTH_REQUIRED');}
       if (response.status===403) return reply(res,403,'PERMISSION_DENIED');
+      const loginResponse=response.status===401 || response.status>=300 && response.status<400 || response.ok && response.headers.get('content-type')?.includes('text/html');
+      const json=loginResponse ? null : await response.json();
+      if (loginResponse || response.ok && ['TIME_OUT','JWT_EXPIRED','LOGIN_INFO_NOT_AVAILABLE','CANNOT_GET_TOKEN'].includes(json?.errorCode ?? json?.code)) {
+        await session.invalidate(auth);
+        if(attempt===0)continue;
+        return reply(res,401,'AUTH_REQUIRED');
+      }
       // Forward only the query envelope, never upstream headers or login payloads.
       res.writeHead(response.status,{'Content-Type':'application/json','Cache-Control':'no-store'});
-      res.end(JSON.stringify(json.success===true ? {success:true,data:json.data} : {success:false,errorCode:json.errorCode || 'QUERY_FAILED'}));
-    } catch (error) {reply(res,error.message==='AUTH_REQUIRED'?401:502,error.message==='AUTH_REQUIRED'?'AUTH_REQUIRED':'UPSTREAM_UNAVAILABLE');}
+      return res.end(JSON.stringify(json.success===true ? {success:true,data:json.data} : {success:false,errorCode:json.errorCode || json.code || 'QUERY_FAILED'}));
+      }
+    } catch (error) {
+      const code=['AUTH_REQUIRED','AUTH_PLUGIN_REQUIRED','AUTH_HTTPS_REQUIRED','AUTH_PROTOCOL_ERROR','AUTH_UNAVAILABLE','AUTH_STORAGE_FAILED'].includes(error.message)?error.message:'UPSTREAM_UNAVAILABLE';
+      if(code!=='UPSTREAM_UNAVAILABLE') (sessionOptions.notify || console.info)(`FineBI 开发认证：${code}。请检查终端提示与 .env.local，修正后重试。`);
+      reply(res,code==='AUTH_REQUIRED'?401:502,code);
+    }
   };
+  middleware.dispose=()=>session.dispose();
+  return middleware;
 }

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/scripts/dev-session.mjs

@@ -0,0 +1,57 @@
+import {resolve} from 'node:path';
+import {saveSession} from './session-file.mjs';
+import {authRequest,browserSession} from './browser-session.mjs';
+
+export function createDevSession(env,options={}) {
+  const {fetchImpl=fetch,browser=browserSession,notify=console.info}=options;
+  const file=options.file || resolve('.env.local');
+  const save=options.save || ((...args)=>saveSession(file,...args));
+  const baseUrl=(env.FINEBI_DEV_BASE_URL || '').replace(/\/$/,'');
+  let token=env.FINEBI_DEV_TOKEN || '';
+  if(env.FINEBI_DEV_TOKEN_BASE_URL && env.FINEBI_DEV_TOKEN_BASE_URL.replace(/\/$/,'')!==baseUrl)token='';
+  let username=env.FINEBI_DEV_TOKEN_USERNAME || '';
+  let pending,clearing,passwordRejected=false;
+  const controller=new AbortController();
+  const valid=value=>typeof value==='string' && /^[\x21-\x7e]+$/.test(value) && !/[;,]/.test(value);
+  if(token && !valid(token))token='';
+
+  async function acquire() {
+    if(!baseUrl || controller.signal.aborted)throw Error('AUTH_REQUIRED');
+    const target=new URL(baseUrl);
+    if(!['http:','https:'].includes(target.protocol) || target.username || target.password || target.search || target.hash)throw Error('AUTH_PROTOCOL_ERROR');
+    let result;
+    if(!passwordRejected && env.FINEBI_DEV_USERNAME && env.FINEBI_DEV_PASSWORD) {
+      const {response,payload}=await authRequest(baseUrl+'/login',{username:env.FINEBI_DEV_USERNAME,password:env.FINEBI_DEV_PASSWORD,encrypted:false,tenantId:''},{fetchImpl,signal:controller.signal});
+      if(response.status>=500 || response.status===429)throw Error('UPSTREAM_UNAVAILABLE');
+      if(response.ok && valid(payload?.data?.accessToken))result={token:payload.data.accessToken,username:env.FINEBI_DEV_USERNAME};
+      else if([401,403].includes(response.status) || response.status>=300 && response.status<400 || payload?.errorCode || payload?.code || response.headers.get('content-type')?.includes('text/html')) {
+        passwordRejected=true;notify('密码登录被拒绝或需要交互登录，转为浏览器授权；本次运行不再重复尝试该密码。');
+      } else throw Error('AUTH_PROTOCOL_ERROR');
+    }
+    if(!result)result=await browser(baseUrl,{fetchImpl,signal:controller.signal,notify});
+    if(controller.signal.aborted)throw Error('AUTH_REQUIRED');
+    if(!valid(result?.token) || typeof result.username!=='string')throw Error('AUTH_PROTOCOL_ERROR');
+    if(username && username!==result.username)notify(`开发身份已切换：${username} → ${result.username}`);
+    try{await save(baseUrl,result.token,result.username);}catch{throw Error('AUTH_STORAGE_FAILED');}
+    token=result.token;username=result.username;
+    notify(`FineBI 开发会话已保存，当前账号：${username}`);
+    return token;
+  }
+  return {
+    async get() {
+      if(clearing)await clearing;
+      if(controller.signal.aborted)throw Error('AUTH_REQUIRED');
+      if(token)return token;
+      if(!pending)pending=acquire().finally(()=>{pending=undefined;});
+      return pending;
+    },
+    async invalidate(rejected) {
+      if(token!==rejected)return;
+      token='';
+      // Serialize invalidation with acquisition so an old response cannot overwrite a new session on disk.
+      clearing=save(baseUrl,'',username).catch(()=>{throw Error('AUTH_STORAGE_FAILED');}).finally(()=>{clearing=undefined;});
+      await clearing;
+    },
+    dispose(){controller.abort();},
+  };
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/scripts/session-file.mjs

@@ -0,0 +1,45 @@
+import {lstat, readFile, open, mkdir, rename, chmod, unlink} from 'node:fs/promises';
+import {dirname, resolve} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+
+async function regularFile(path) {
+  try {const info=await lstat(path);if(!info.isFile() || info.isSymbolicLink())throw Error('SESSION_FILE_UNSAFE');}
+  catch(error){if(error.code!=='ENOENT')throw error;}
+}
+
+async function restrict(path) {
+  if(process.platform!=='win32'){await chmod(path,0o600);return;}
+  const options={encoding:'utf8',windowsHide:true};
+  const identity=spawnSync('whoami.exe',['/user','/fo','csv','/nh'],options);
+  const sid=identity.status===0 && identity.stdout.match(/"[^"]*","(S-[^"]+)"/)?.[1];
+  if(!sid)throw Error('SESSION_FILE_PERMISSIONS');
+  const result=spawnSync('icacls.exe',[path,'/inheritance:r','/grant:r',`*${sid}:(F)`,'*S-1-5-18:(F)','*S-1-5-32-544:(F)'],options);
+  if(result.status!==0)throw Error('SESSION_FILE_PERMISSIONS');
+}
+
+export async function saveSession(path,baseUrl,token,username='') {
+  path=resolve(path);
+  await regularFile(path);
+  const original=await readFile(path,'utf8').catch(error=>{if(error.code==='ENOENT')return '';throw error;});
+  const updates={FINEBI_DEV_TOKEN:token,FINEBI_DEV_TOKEN_BASE_URL:baseUrl,FINEBI_DEV_TOKEN_USERNAME:username};
+  if(!/^\s*(?:export\s+)?FINEBI_DEV_BASE_URL\s*=/m.test(original))updates.FINEBI_DEV_BASE_URL=baseUrl;
+  const retained=original.split(/\r?\n/).filter(line=>{
+    const key=line.match(/^\s*(?:export\s+)?([\w]+)\s*=/)?.[1];return !Object.hasOwn(updates,key);
+  }).join('\n').replace(/\n*$/,'');
+  const content=(retained?retained+'\n':'')+Object.entries(updates).map(([key,value])=>`${key}=${JSON.stringify(value)}`).join('\n')+'\n';
+  const temp=resolve(dirname(path),'temp');
+  await mkdir(temp,{recursive:true});
+  if((await lstat(temp)).isSymbolicLink())throw Error('SESSION_FILE_UNSAFE');
+  const stage=resolve(temp,`.finebi-session-${randomUUID()}`);
+  const handle=await open(stage,'wx',0o600);
+  try {
+    await restrict(stage);
+    await handle.writeFile(content,'utf8');await handle.sync();await handle.close();
+    await regularFile(path);
+    // A concurrent configuration edit wins; do not overwrite it with the earlier snapshot.
+    const current=await readFile(path,'utf8').catch(error=>{if(error.code==='ENOENT')return '';throw error;});
+    if(current!==original)throw Error('SESSION_FILE_CHANGED');
+    await rename(stage,path);
+  } finally {await handle.close().catch(()=>{});await unlink(stage).catch(error=>{if(error.code!=='ENOENT')throw error;});}
+}