@finebi/finebi-cli 1.6.1 → 1.6.2

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/examples/retail.config.json

@@ -1,185 +1,185 @@
-{
-  "schemaVersion": "1",
-  "templateVersion": "0.3.0",
-  "title": "零售经营简报",
-  "description": "请根据同一来源的真实指标、字段和控件替换绑定。",
-  "basePath": "/webroot/decision",
-  "layout": "retail",
-  "dashboardId": "REPLACE_DASHBOARD_ID",
-  "directoryEntryId": "REPLACE_DIRECTORY_ENTRY_ID",
-  "maxRows": 1000,
-  "pageSize": 8,
-  "insights": false,
-  "widgets": [
-    {
-      "entryId": "REPLACE_ENTRY_1",
-      "name": "销售额",
-      "type": "kpi",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "valueFieldId": "REPLACE_VALUE_1",
-      "valueFormat": "number"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_2",
-      "name": "毛利",
-      "type": "kpi",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "valueFieldId": "REPLACE_VALUE_2",
-      "valueFormat": "number"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_3",
-      "name": "比率指标",
-      "type": "kpi",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "valueFieldId": "REPLACE_VALUE_3",
-      "valueFormat": "percent"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_4",
-      "name": "计数指标",
-      "type": "kpi",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "valueFieldId": "REPLACE_VALUE_4",
-      "valueFormat": "number"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_5",
-      "name": "销售与毛利趋势",
-      "type": "line",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_5",
-      "valueFieldId": "REPLACE_VALUE_5",
-      "categoryFormat": "epoch-month",
-      "categoryTimeZone": "Asia/Shanghai",
-      "series": [
-        {
-          "fieldId": "REPLACE_SERIES_5_1",
-          "label": "销售额"
-        },
-        {
-          "fieldId": "REPLACE_SERIES_5_2",
-          "label": "毛利"
-        }
-      ]
-    },
-    {
-      "entryId": "REPLACE_ENTRY_6",
-      "name": "销售额 TOP10 门店",
-      "type": "bar",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_6",
-      "valueFieldId": "REPLACE_VALUE_6"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_7",
-      "name": "区域销售构成",
-      "type": "pie",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_7",
-      "valueFieldId": "REPLACE_VALUE_7"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_8",
-      "name": "品类销售额",
-      "type": "bar",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_8",
-      "valueFieldId": "REPLACE_VALUE_8"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_9",
-      "name": "自有店 / 管理店销售趋势",
-      "type": "line",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_9",
-      "valueFieldId": "REPLACE_VALUE_9",
-      "categoryFormat": "epoch-month",
-      "categoryTimeZone": "Asia/Shanghai",
-      "series": [
-        {
-          "fieldId": "REPLACE_SERIES_9_1",
-          "label": "自有店"
-        },
-        {
-          "fieldId": "REPLACE_SERIES_9_2",
-          "label": "管理店"
-        }
-      ]
-    },
-    {
-      "entryId": "REPLACE_ENTRY_10",
-      "name": "生活馆 / 时尚馆销售趋势",
-      "type": "line",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_10",
-      "valueFieldId": "REPLACE_VALUE_10",
-      "categoryFormat": "epoch-month",
-      "categoryTimeZone": "Asia/Shanghai",
-      "series": [
-        {
-          "fieldId": "REPLACE_SERIES_10_1",
-          "label": "生活馆"
-        },
-        {
-          "fieldId": "REPLACE_SERIES_10_2",
-          "label": "时尚馆"
-        }
-      ]
-    },
-    {
-      "entryId": "REPLACE_ENTRY_11",
-      "name": "门店风格构成",
-      "type": "pie",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_11",
-      "valueFieldId": "REPLACE_VALUE_11"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_12",
-      "name": "门店性质构成",
-      "type": "pie",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "categoryFieldId": "REPLACE_CATEGORY_12",
-      "valueFieldId": "REPLACE_VALUE_12"
-    },
-    {
-      "entryId": "REPLACE_ENTRY_13",
-      "name": "门店经营明细",
-      "type": "table",
-      "description": "替换为已核实的源指标口径与范围。",
-      "filterNames": [],
-      "tableFieldIds": [
-        "REPLACE_TABLE_FIELD_1",
-        "REPLACE_TABLE_FIELD_2",
-        "REPLACE_TABLE_FIELD_3",
-        "REPLACE_TABLE_FIELD_4"
-      ],
-      "localFilterFieldIds": [
-        "REPLACE_TABLE_FIELD_1"
-      ]
-    }
-  ],
-  "filters": [
-    {
-      "name": "REPLACE_STORE_CONTROL",
-      "label": "店名（精确匹配）",
-      "type": "text"
-    }
-  ],
-  "dataNotes": [
-    "请填写已核实的来源、单位、期间、门店计数口径与控件作用范围。未确认公式时保留源指标名称。"
-  ]
-}
+{
+  "schemaVersion": "1",
+  "templateVersion": "0.3.0",
+  "title": "零售经营简报",
+  "description": "请根据同一来源的真实指标、字段和控件替换绑定。",
+  "basePath": "/webroot/decision",
+  "layout": "retail",
+  "dashboardId": "REPLACE_DASHBOARD_ID",
+  "directoryEntryId": "REPLACE_DIRECTORY_ENTRY_ID",
+  "maxRows": 1000,
+  "pageSize": 8,
+  "insights": false,
+  "widgets": [
+    {
+      "entryId": "REPLACE_ENTRY_1",
+      "name": "销售额",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_1",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_2",
+      "name": "毛利",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_2",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_3",
+      "name": "比率指标",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_3",
+      "valueFormat": "percent"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_4",
+      "name": "计数指标",
+      "type": "kpi",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "valueFieldId": "REPLACE_VALUE_4",
+      "valueFormat": "number"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_5",
+      "name": "销售与毛利趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_5",
+      "valueFieldId": "REPLACE_VALUE_5",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_5_1",
+          "label": "销售额"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_5_2",
+          "label": "毛利"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_6",
+      "name": "销售额 TOP10 门店",
+      "type": "bar",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_6",
+      "valueFieldId": "REPLACE_VALUE_6"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_7",
+      "name": "区域销售构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_7",
+      "valueFieldId": "REPLACE_VALUE_7"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_8",
+      "name": "品类销售额",
+      "type": "bar",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_8",
+      "valueFieldId": "REPLACE_VALUE_8"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_9",
+      "name": "自有店 / 管理店销售趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_9",
+      "valueFieldId": "REPLACE_VALUE_9",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_9_1",
+          "label": "自有店"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_9_2",
+          "label": "管理店"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_10",
+      "name": "生活馆 / 时尚馆销售趋势",
+      "type": "line",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_10",
+      "valueFieldId": "REPLACE_VALUE_10",
+      "categoryFormat": "epoch-month",
+      "categoryTimeZone": "Asia/Shanghai",
+      "series": [
+        {
+          "fieldId": "REPLACE_SERIES_10_1",
+          "label": "生活馆"
+        },
+        {
+          "fieldId": "REPLACE_SERIES_10_2",
+          "label": "时尚馆"
+        }
+      ]
+    },
+    {
+      "entryId": "REPLACE_ENTRY_11",
+      "name": "门店风格构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_11",
+      "valueFieldId": "REPLACE_VALUE_11"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_12",
+      "name": "门店性质构成",
+      "type": "pie",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "categoryFieldId": "REPLACE_CATEGORY_12",
+      "valueFieldId": "REPLACE_VALUE_12"
+    },
+    {
+      "entryId": "REPLACE_ENTRY_13",
+      "name": "门店经营明细",
+      "type": "table",
+      "description": "替换为已核实的源指标口径与范围。",
+      "filterNames": [],
+      "tableFieldIds": [
+        "REPLACE_TABLE_FIELD_1",
+        "REPLACE_TABLE_FIELD_2",
+        "REPLACE_TABLE_FIELD_3",
+        "REPLACE_TABLE_FIELD_4"
+      ],
+      "localFilterFieldIds": [
+        "REPLACE_TABLE_FIELD_1"
+      ]
+    }
+  ],
+  "filters": [
+    {
+      "name": "REPLACE_STORE_CONTROL",
+      "label": "店名（精确匹配）",
+      "type": "text"
+    }
+  ],
+  "dataNotes": [
+    "请填写已核实的来源、单位、期间、门店计数口径与控件作用范围。未确认公式时保留源指标名称。"
+  ]
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/index.html

@@ -1,2 +1,2 @@
-<!doctype html>
-<html lang="zh-CN"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>FineBI 数据应用</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>
+<!doctype html>
+<html lang="zh-CN"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>FineBI 数据应用</title></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>

package/skills/finebi-cli-agent/scripts/finebi-cli/templates/web-app/public/app-config.json

@@ -1,11 +1,11 @@
-{
-  "schemaVersion": "1",
-  "title": "FineBI 数据应用",
-  "basePath": "/webroot/decision",
-  "layout": "overview",
-  "dashboardId": "",
-  "maxRows": 1000,
-  "pageSize": 8,
-  "widgets": [],
-  "filters": []
-}
+{
+  "schemaVersion": "1",
+  "title": "FineBI 数据应用",
+  "basePath": "/webroot/decision",
+  "layout": "overview",
+  "dashboardId": "",
+  "maxRows": 1000,
+  "pageSize": 8,
+  "widgets": [],
+  "filters": []
+}

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;});}
+}