@finebi/finebi-cli 1.5.0 → 1.6.0

package/src/profiles.js

@@ -1,158 +1,158 @@
-import {closeSync, existsSync, mkdirSync, openSync, rmSync} from "node:fs";
-import {dirname, join} from "node:path";
-
-import {normalizeConfig, readConfig, writeConfigAtomically} from "./config.js";
-
-export class ProfileError extends Error {}
-
-export function validateProfileName(name) {
-  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) {
-    throw new ProfileError("Profile name must contain 1-64 letters, digits, underscores or hyphens and start with a letter or digit.");
-  }
-  return name;
-}
-
-export function readProfiles(path) {
-  const config = readConfig(path);
-  if (config.schemaVersion === 2) {
-    if (!config.profiles || typeof config.profiles !== "object" || Array.isArray(config.profiles)) {
-      throw new ProfileError("Invalid profiles configuration.");
-    }
-    return {multi: true, currentProfile: config.currentProfile ?? null, profiles: config.profiles};
-  }
-  // Preserve legacy session tokens when a single-environment file is migrated.
-  if (config.token && !config.auth?.token) {
-    config.auth = {...config.auth, token: config.token};
-  }
-  const present = existsSync(path);
-  return {multi: false, currentProfile: present ? "default" : null, profiles: present ? {default: config} : {}};
-}
-
-export function selectProfile(path, requested, {allowCreate = false, optional = false} = {}) {
-  const store = readProfiles(path);
-  const name = requested ?? store.currentProfile ?? (!store.multi ? "default" : null);
-  if (!name) {
-    if (optional) return null;
-    throw new ProfileError("No default environment is selected. Run finebi-cli auth use <name> or pass --profile <name>.");
-  }
-  validateProfileName(name);
-  const implicitInitial = !requested && !store.multi && !existsSync(path);
-  if (!Object.hasOwn(store.profiles, name) && !allowCreate && !implicitInitial && !optional) {
-    throw new ProfileError(`Environment '${name}' does not exist. Create it with finebi-cli auth login --profile ${name} --base-url <url>.`);
-  }
-  if (requested && !Object.hasOwn(store.profiles, name) && !allowCreate) {
-    throw new ProfileError(`Environment '${name}' does not exist.`);
-  }
-  return name;
-}
-
-export function readProfile(path, name) {
-  const store = readProfiles(path);
-  return normalizeConfig(name && Object.hasOwn(store.profiles, name) ? store.profiles[name] : {});
-}
-
-export function profileCapabilityPath(path, name) {
-  if (!name || name === "default") return path;
-  // Hex encoding preserves case-sensitive names on case-insensitive filesystems.
-  return join(dirname(path), `capabilities-profile-${Buffer.from(validateProfileName(name)).toString("hex")}.json`);
-}
-
-export function saveProfile(path, name, config, {makeCurrent = false, forceMulti = false, writer = writeConfigAtomically} = {}) {
-  validateProfileName(name);
-  return withProfileLock(path, () => {
-    const store = readProfiles(path);
-    if (!store.multi && name === "default" && !forceMulti) {
-      writer(path, config);
-      return;
-    }
-    const profiles = {...store.profiles, [name]: config};
-    writer(path, {schemaVersion: 2, currentProfile: makeCurrent ? name : store.currentProfile, profiles});
-  });
-}
-
-export function useProfile(path, name) {
-  validateProfileName(name);
-  return withProfileLock(path, () => {
-    const store = readProfiles(path);
-    if (!Object.hasOwn(store.profiles, name)) throw new ProfileError(`Environment '${name}' does not exist.`);
-    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: name, profiles: store.profiles});
-  });
-}
-
-export function removeProfile(path, name) {
-  validateProfileName(name);
-  return withProfileLock(path, () => {
-    const store = readProfiles(path);
-    if (!Object.hasOwn(store.profiles, name)) {
-      if (!store.multi && name === "default") return;
-      throw new ProfileError(`Environment '${name}' does not exist.`);
-    }
-    if (!store.multi && name === "default") {
-      rmSync(path);
-      return;
-    }
-    const profiles = {...store.profiles};
-    delete profiles[name];
-    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: store.currentProfile === name ? null : store.currentProfile, profiles});
-  });
-}
-
-export async function withProfileLoginLock(path, name, operation) {
-  validateProfileName(name);
-  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
-  const lock = `${path}.login-${Buffer.from(name).toString("hex")}.lock`;
-  let fd;
-  try {
-    fd = openSync(lock, "wx", 0o600);
-  } catch (error) {
-    if (error.code === "EEXIST") throw new ProfileError(`An operation for environment '${name}' is already in progress. Retry after it finishes.`);
-    throw error;
-  }
-  try {
-    return await operation();
-  } finally {
-    closeSync(fd);
-    rmSync(lock, {force: true});
-  }
-}
-
-function withProfileLock(path, operation) {
-  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
-  const lock = `${path}.lock`;
-  const deadline = Date.now() + 3000;
-  let fd;
-  while (fd === undefined) {
-    try {
-      fd = openSync(lock, "wx", 0o600);
-    } catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      if (Date.now() >= deadline) throw new ProfileError("Configuration is locked by another process. Retry after it finishes.");
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-    }
-  }
-  try {
-    return operation();
-  } finally {
-    closeSync(fd);
-    rmSync(lock, {force: true});
-  }
-}
-
-export function parseConnectionArgs(argv) {
-  const args = [];
-  const flags = {};
-  const names = {"--profile": "profile", "--base-url": "baseUrl", "--token": "token"};
-  for (let index = 0; index < argv.length; index++) {
-    const [option, ...inline] = argv[index].split("=");
-    if (!Object.hasOwn(names, option)) {
-      args.push(argv[index]);
-      continue;
-    }
-    const value = inline.length ? inline.join("=") : argv[++index];
-    if (!value?.trim() || value.startsWith("--")) throw new ProfileError(`${option} requires a value.`);
-    const key = names[option];
-    if (Object.hasOwn(flags, key)) throw new ProfileError(`${option} must only be supplied once.`);
-    flags[key] = value.trim();
-  }
-  return {args, flags};
-}
+import {closeSync, existsSync, mkdirSync, openSync, rmSync} from "node:fs";
+import {dirname, join} from "node:path";
+
+import {normalizeConfig, readConfig, writeConfigAtomically} from "./config.js";
+
+export class ProfileError extends Error {}
+
+export function validateProfileName(name) {
+  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) {
+    throw new ProfileError("Profile name must contain 1-64 letters, digits, underscores or hyphens and start with a letter or digit.");
+  }
+  return name;
+}
+
+export function readProfiles(path) {
+  const config = readConfig(path);
+  if (config.schemaVersion === 2) {
+    if (!config.profiles || typeof config.profiles !== "object" || Array.isArray(config.profiles)) {
+      throw new ProfileError("Invalid profiles configuration.");
+    }
+    return {multi: true, currentProfile: config.currentProfile ?? null, profiles: config.profiles};
+  }
+  // Preserve legacy session tokens when a single-environment file is migrated.
+  if (config.token && !config.auth?.token) {
+    config.auth = {...config.auth, token: config.token};
+  }
+  const present = existsSync(path);
+  return {multi: false, currentProfile: present ? "default" : null, profiles: present ? {default: config} : {}};
+}
+
+export function selectProfile(path, requested, {allowCreate = false, optional = false} = {}) {
+  const store = readProfiles(path);
+  const name = requested ?? store.currentProfile ?? (!store.multi ? "default" : null);
+  if (!name) {
+    if (optional) return null;
+    throw new ProfileError("No default environment is selected. Run finebi-cli auth use <name> or pass --profile <name>.");
+  }
+  validateProfileName(name);
+  const implicitInitial = !requested && !store.multi && !existsSync(path);
+  if (!Object.hasOwn(store.profiles, name) && !allowCreate && !implicitInitial && !optional) {
+    throw new ProfileError(`Environment '${name}' does not exist. Create it with finebi-cli auth login --profile ${name} --base-url <url>.`);
+  }
+  if (requested && !Object.hasOwn(store.profiles, name) && !allowCreate) {
+    throw new ProfileError(`Environment '${name}' does not exist.`);
+  }
+  return name;
+}
+
+export function readProfile(path, name) {
+  const store = readProfiles(path);
+  return normalizeConfig(name && Object.hasOwn(store.profiles, name) ? store.profiles[name] : {});
+}
+
+export function profileCapabilityPath(path, name) {
+  if (!name || name === "default") return path;
+  // Hex encoding preserves case-sensitive names on case-insensitive filesystems.
+  return join(dirname(path), `capabilities-profile-${Buffer.from(validateProfileName(name)).toString("hex")}.json`);
+}
+
+export function saveProfile(path, name, config, {makeCurrent = false, forceMulti = false, writer = writeConfigAtomically} = {}) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!store.multi && name === "default" && !forceMulti) {
+      writer(path, config);
+      return;
+    }
+    const profiles = {...store.profiles, [name]: config};
+    writer(path, {schemaVersion: 2, currentProfile: makeCurrent ? name : store.currentProfile, profiles});
+  });
+}
+
+export function useProfile(path, name) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!Object.hasOwn(store.profiles, name)) throw new ProfileError(`Environment '${name}' does not exist.`);
+    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: name, profiles: store.profiles});
+  });
+}
+
+export function removeProfile(path, name) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!Object.hasOwn(store.profiles, name)) {
+      if (!store.multi && name === "default") return;
+      throw new ProfileError(`Environment '${name}' does not exist.`);
+    }
+    if (!store.multi && name === "default") {
+      rmSync(path);
+      return;
+    }
+    const profiles = {...store.profiles};
+    delete profiles[name];
+    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: store.currentProfile === name ? null : store.currentProfile, profiles});
+  });
+}
+
+export async function withProfileLoginLock(path, name, operation) {
+  validateProfileName(name);
+  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
+  const lock = `${path}.login-${Buffer.from(name).toString("hex")}.lock`;
+  let fd;
+  try {
+    fd = openSync(lock, "wx", 0o600);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new ProfileError(`An operation for environment '${name}' is already in progress. Retry after it finishes.`);
+    throw error;
+  }
+  try {
+    return await operation();
+  } finally {
+    closeSync(fd);
+    rmSync(lock, {force: true});
+  }
+}
+
+function withProfileLock(path, operation) {
+  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + 3000;
+  let fd;
+  while (fd === undefined) {
+    try {
+      fd = openSync(lock, "wx", 0o600);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new ProfileError("Configuration is locked by another process. Retry after it finishes.");
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    closeSync(fd);
+    rmSync(lock, {force: true});
+  }
+}
+
+export function parseConnectionArgs(argv) {
+  const args = [];
+  const flags = {};
+  const names = {"--profile": "profile", "--base-url": "baseUrl", "--token": "token"};
+  for (let index = 0; index < argv.length; index++) {
+    const [option, ...inline] = argv[index].split("=");
+    if (!Object.hasOwn(names, option)) {
+      args.push(argv[index]);
+      continue;
+    }
+    const value = inline.length ? inline.join("=") : argv[++index];
+    if (!value?.trim() || value.startsWith("--")) throw new ProfileError(`${option} requires a value.`);
+    const key = names[option];
+    if (Object.hasOwn(flags, key)) throw new ProfileError(`${option} must only be supplied once.`);
+    flags[key] = value.trim();
+  }
+  return {args, flags};
+}

package/src/skill-files.js

@@ -1,94 +1,94 @@
-import {createHash, randomUUID} from "node:crypto";
-import {existsSync} from "node:fs";
-import {cp, mkdir, lstat, mkdtemp, readFile, readdir, rename, rm} from "node:fs/promises";
-import {homedir} from "node:os";
-import {join, dirname, resolve} from "node:path";
-
-export function agentCatalog({home = homedir(), env = process.env} = {}) {
-  const config = env.XDG_CONFIG_HOME || join(home, ".config");
-  return [
-    ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
-    ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
-    ["cursor", "Cursor", join(home, ".cursor")],
-    ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
-    ["github-copilot", "GitHub Copilot", join(home, ".copilot")],
-    ["opencode", "OpenCode", join(config, "opencode")],
-    ["cline", "Cline", join(home, ".agents")],
-    ["windsurf", "Windsurf", join(home, ".codeium", "windsurf")],
-    ["trae", "Trae", join(home, ".trae")],
-    ["trae-cn", "Trae CN", join(home, ".trae-cn")],
-    ["openclaw", "OpenClaw", [".openclaw", ".clawdbot", ".moltbot"].map(p => join(home, p)).find(existsSync) || join(home, ".openclaw")],
-    ["roo", "Roo Code", join(home, ".roo")],
-    ["qwen-code", "Qwen Code", join(home, ".qwen")],
-  ].map(([id, name, root]) => ({id, name, directory: join(root, "skills"), detected: existsSync(root)}));
-}
-
-export async function hashTree(root, prefix = "") {
-  const files = {};
-  for (const entry of (await readdir(join(root, prefix), {withFileTypes: true})).sort((a, b) => a.name.localeCompare(b.name))) {
-    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isSymbolicLink()) throw new Error(`Skill contains a symbolic link: ${name}`);
-    if (entry.isDirectory()) Object.assign(files, await hashTree(root, name));
-    else files[name] = createHash("sha256").update(await readFile(join(root, name))).digest("hex");
-  }
-  return files;
-}
-
-function sameHashes(left, right) {
-  return left && right && Object.keys(left).length === Object.keys(right).length
-    && Object.keys(left).every(key => left[key] === right[key]);
-}
-
-export async function installSkills({source, home, env, agents, replace = false, previous = []}) {
-  const catalog = agentCatalog({home, env});
-  const selected = agents.map(id => {
-    const agent = catalog.find(item => item.id === id);
-    if (!agent) throw new Error(`Unknown Agent: ${id}`);
-    return agent;
-  });
-  const sourceHashes = await hashTree(source);
-  const results = [];
-  for (const agent of selected) {
-    const target = join(agent.directory, "finebi-cli-agent");
-    let backup;
-    let candidate;
-    try {
-      const stat = await lstat(target).catch(error => { if (error.code !== "ENOENT") throw error; });
-      if (stat) {
-        if (stat.isSymbolicLink()) throw new Error("Skill target is a symbolic link; refusing to replace it.");
-        const actual = await hashTree(target);
-        if (sameHashes(sourceHashes, actual)) {
-          results.push({agent: agent.id, path: target, status: "unchanged", hashes: sourceHashes});
-          continue;
-        }
-        const recorded = previous.find(item => item.agent === agent.id && item.path === target)?.hashes;
-        if (!replace && !sameHashes(recorded, actual)) {
-          results.push({agent: agent.id, path: target, status: "kept"});
-          continue;
-        }
-        backup = join(home, ".finebi-cli", "skill-backups", `${agent.id}-${randomUUID()}`);
-        await mkdir(dirname(backup), {recursive: true});
-        await cp(target, backup, {recursive: true, errorOnExist: true, force: false});
-        if (!sameHashes(actual, await hashTree(backup))) throw new Error("Skill backup integrity check failed.");
-      }
-      await mkdir(agent.directory, {recursive: true});
-      candidate = await mkdtemp(join(agent.directory, ".finebi-cli-stage-"));
-      await cp(source, candidate, {recursive: true});
-      if (!sameHashes(sourceHashes, await hashTree(candidate))) throw new Error("Skill copy integrity check failed.");
-      const old = `${candidate}-old`;
-      if (stat) await rename(target, old);
-      try { await rename(candidate, target); }
-      catch (error) { if (stat) await rename(old, target); throw error; }
-      candidate = undefined;
-      // Delete only the relocated, backed-up directory inside this Agent's skills directory.
-      if (stat && backup && dirname(resolve(old)) === resolve(agent.directory)) await rm(old, {recursive: true});
-      if (!sameHashes(sourceHashes, await hashTree(target))) throw new Error("Installed Skill integrity check failed.");
-      results.push({agent: agent.id, path: target, status: "installed", hashes: sourceHashes, ...(backup ? {backup} : {})});
-    } catch (error) {
-      results.push({agent: agent.id, path: target, status: "failed", error: error.message, ...(backup ? {backup} : {})});
-    } finally {
-      if (candidate && dirname(resolve(candidate)) === resolve(agent.directory)) await rm(candidate, {recursive: true, force: true});
-    }
-  }
-  return results;
-}
+import {createHash, randomUUID} from "node:crypto";
+import {existsSync} from "node:fs";
+import {cp, mkdir, lstat, mkdtemp, readFile, readdir, rename, rm} from "node:fs/promises";
+import {homedir} from "node:os";
+import {join, dirname, resolve} from "node:path";
+
+export function agentCatalog({home = homedir(), env = process.env} = {}) {
+  const config = env.XDG_CONFIG_HOME || join(home, ".config");
+  return [
+    ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
+    ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
+    ["cursor", "Cursor", join(home, ".cursor")],
+    ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
+    ["github-copilot", "GitHub Copilot", join(home, ".copilot")],
+    ["opencode", "OpenCode", join(config, "opencode")],
+    ["cline", "Cline", join(home, ".agents")],
+    ["windsurf", "Windsurf", join(home, ".codeium", "windsurf")],
+    ["trae", "Trae", join(home, ".trae")],
+    ["trae-cn", "Trae CN", join(home, ".trae-cn")],
+    ["openclaw", "OpenClaw", [".openclaw", ".clawdbot", ".moltbot"].map(p => join(home, p)).find(existsSync) || join(home, ".openclaw")],
+    ["roo", "Roo Code", join(home, ".roo")],
+    ["qwen-code", "Qwen Code", join(home, ".qwen")],
+  ].map(([id, name, root]) => ({id, name, directory: join(root, "skills"), detected: existsSync(root)}));
+}
+
+export async function hashTree(root, prefix = "") {
+  const files = {};
+  for (const entry of (await readdir(join(root, prefix), {withFileTypes: true})).sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Skill contains a symbolic link: ${name}`);
+    if (entry.isDirectory()) Object.assign(files, await hashTree(root, name));
+    else files[name] = createHash("sha256").update(await readFile(join(root, name))).digest("hex");
+  }
+  return files;
+}
+
+function sameHashes(left, right) {
+  return left && right && Object.keys(left).length === Object.keys(right).length
+    && Object.keys(left).every(key => left[key] === right[key]);
+}
+
+export async function installSkills({source, home, env, agents, replace = false, previous = []}) {
+  const catalog = agentCatalog({home, env});
+  const selected = agents.map(id => {
+    const agent = catalog.find(item => item.id === id);
+    if (!agent) throw new Error(`Unknown Agent: ${id}`);
+    return agent;
+  });
+  const sourceHashes = await hashTree(source);
+  const results = [];
+  for (const agent of selected) {
+    const target = join(agent.directory, "finebi-cli-agent");
+    let backup;
+    let candidate;
+    try {
+      const stat = await lstat(target).catch(error => { if (error.code !== "ENOENT") throw error; });
+      if (stat) {
+        if (stat.isSymbolicLink()) throw new Error("Skill target is a symbolic link; refusing to replace it.");
+        const actual = await hashTree(target);
+        if (sameHashes(sourceHashes, actual)) {
+          results.push({agent: agent.id, path: target, status: "unchanged", hashes: sourceHashes});
+          continue;
+        }
+        const recorded = previous.find(item => item.agent === agent.id && item.path === target)?.hashes;
+        if (!replace && !sameHashes(recorded, actual)) {
+          results.push({agent: agent.id, path: target, status: "kept"});
+          continue;
+        }
+        backup = join(home, ".finebi-cli", "skill-backups", `${agent.id}-${randomUUID()}`);
+        await mkdir(dirname(backup), {recursive: true});
+        await cp(target, backup, {recursive: true, errorOnExist: true, force: false});
+        if (!sameHashes(actual, await hashTree(backup))) throw new Error("Skill backup integrity check failed.");
+      }
+      await mkdir(agent.directory, {recursive: true});
+      candidate = await mkdtemp(join(agent.directory, ".finebi-cli-stage-"));
+      await cp(source, candidate, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(candidate))) throw new Error("Skill copy integrity check failed.");
+      const old = `${candidate}-old`;
+      if (stat) await rename(target, old);
+      try { await rename(candidate, target); }
+      catch (error) { if (stat) await rename(old, target); throw error; }
+      candidate = undefined;
+      // Delete only the relocated, backed-up directory inside this Agent's skills directory.
+      if (stat && backup && dirname(resolve(old)) === resolve(agent.directory)) await rm(old, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(target))) throw new Error("Installed Skill integrity check failed.");
+      results.push({agent: agent.id, path: target, status: "installed", hashes: sourceHashes, ...(backup ? {backup} : {})});
+    } catch (error) {
+      results.push({agent: agent.id, path: target, status: "failed", error: error.message, ...(backup ? {backup} : {})});
+    } finally {
+      if (candidate && dirname(resolve(candidate)) === resolve(agent.directory)) await rm(candidate, {recursive: true, force: true});
+    }
+  }
+  return results;
+}

package/templates/web-app/AGENTS.md

@@ -0,0 +1,27 @@
+# FineBI 动态页面开发
+
+## 开发顺序
+
+1. 用 FineBI CLI 搜索并读取 dashboard info/data，确认看板实例 entryId、queryFields.dId、真实控件 filterName 和可访问来源。
+2. 阅读 [数据契约](docs/data-contract.md)、[筛选](docs/filters.md)、[认证部署](docs/auth-and-deploy.md)，再修改 public/app-config.json。
+3. 从 overview 或 workbench 布局开始，按页面需求选择图表库和UI组件库；默认ECharts和Ant Design筛选控件均可替换，约定见[页面骨架](docs/design.md)。业务转换放 src/services，页面放 src/pages 或 App.tsx。通用请求与原生解析集中在 src/finebi，避免页面散落 fetch 或重复协议实现。
+4. 使用真实接口开发；样本仅用于 tests，禁止将开发阶段查询数据写入正式页面、配置或回退数据。
+5. npm test、npm run build，再通过浏览器核对请求、字段、图表、刷新和权限状态。构建成功不等于认证或取数成功。
+
+## 数据规则
+
+- 先检查 normalization、warnings、range，再选择唯一 dataset；多模型需显式 datasetId。
+- display 用于显示；计算仅使用 AVAILABLE 的 value，保留 DECIMAL_STRING 精度。禁止从百分比/千分位/单位文本恢复数值。受限值、未知值不能补零。
+- 不按名称猜字段、不累加 UNKNOWN 行、不从首页估算全量 KPI。KPI 示例仅消费单行结果。
+- 控件筛选通过真实名称生成 refer；无控件时不伪造服务端过滤。搜索和排序的范围必须在页面说明。
+- 筛选绑定先核对源控件类型，配置/状态/请求统一通过 src/finebi/filters.js 校验。完整支持矩阵、逗号和 null 保留字、恢复默认与筛选空值语义见 docs/filters.md；不以更换 type 绕过服务端能力限制。
+- pageLimit 是首页大小，不是分页。不得循环放大请求以绕过 maxRows；hasNext=true 必须保留警告，不能宣称全量。
+
+## 认证与交付
+
+- 开发凭证只存在服务端环境 FINEBI_DEV_* 或内存；禁止 VITE_* 凭证、前端 localStorage token、提交 .env 和认证日志。
+- 生产应用使用同源当前用户 Cookie。开发代理不属于构建产物；不要把它部署为共享多用户服务。
+- v1 不支持目录发布来源、交叉表、服务端续页、全局排序或静态托管发布；遇到需求先说明缺口。
+- 图表按生命周期销毁；异步请求取消且旧响应不得覆盖新条件。失败状态不得展示过期数据充当最新结果。
+
+项目创建不会安装依赖、启动服务、初始化 Git 或发布，按用户授权范围执行后续步骤。

package/templates/web-app/README.md

@@ -0,0 +1,30 @@
+# FineBI 动态数据应用
+
+这是运行时调用 FineBI 的静态应用。开发者通过 CLI 发现资源后配置绑定；生产查询使用访问者自己的登录态。
+
+## 开始
+
+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. `npm test`、`npm run build`。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
+
+## 配置
+
+`layout` 为 `overview`（顶部概览）或 `workbench`（侧栏工作台）。`maxRows` 默认 1000，上限 10000；`pageSize` 是本地展示页大小，1–100。
+
+```json
+{
+  "schemaVersion":"1", "title":"销售分析", "basePath":"/webroot/decision",
+  "layout":"overview", "dashboardId":"真实看板ID", "maxRows":1000, "pageSize":8,
+  "widgets":[
+    {"entryId":"真实实例ID", "name":"销售趋势", "type":"line", "categoryFieldId":"日期结果字段ID", "valueFieldId":"销售结果字段ID"}
+  ],
+  "filters":[]
+}
+```
+
+默认组件 type 支持 table、kpi、bar、line、pie；多模型时指定 datasetId。配置不包含数据或任何凭证。协议和限制见 [数据契约](docs/data-contract.md)、[筛选与联动](docs/filters.md)、[认证与部署](docs/auth-and-deploy.md)。布局、图表库和UI组件库的选型与替换约定见 [页面骨架](docs/design.md)。
+
+筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 仅检查本地配置，绑定后仍需验证真实条件生效。

package/templates/web-app/docs/auth-and-deploy.md

@@ -0,0 +1,17 @@
+# 认证与部署
+
+## 本地开发
+
+Vite开发插件读取服务端环境 `FINEBI_DEV_BASE_URL`、`FINEBI_DEV_USERNAME/FINEBI_DEV_PASSWORD`，或已有短期 `FINEBI_DEV_TOKEN`。BASE_URL必须是目标完整decision地址。支持由本地.env.local提供，禁止提交文件；不要使用VITE_前缀。
+
+代理在内存保存开发会话，只接受本机同源、带XMLHttpRequest标记的POST；白名单限制为配置看板及组件查询，不代理登录管理或任意接口。浏览器无需持有开发账号凭证。失效返回AUTH_REQUIRED；密码方式下一次显式重试重新登录，token方式需更新token并重启开发服务。不要向他人开放开发服务端口。
+
+筛选仅允许配置中的控件名和单值数组：下拉值必须属于 options，date 值必须是有效的 YYYY-MM-DD 日历日期，不使用固定日期白名单。空日期通过省略参数恢复保存条件，代理拒绝空字符串和多值日期数组。
+
+## 生产
+
+`npm run build` 输出dist，开发代理不会进入产物。将静态资源托管在与FineBI相同源的应用子路径，basePath配置为实际decision路径。用户先通过FineBI登录，查询携带当前Cookie，服务端按当前身份判断资源、数据和字段权限。
+
+登录失效、HTTP403、查询失败分别显示状态，用户登录后点击重试。生产包不保存开发token、不调用CLI、不自动以开发者账号重登。`npm run preview`不注入身份，只用于产物展示；本版不提供部署上传/发布命令、跨域认证、嵌入SSO或目录发布来源查询。
+
+交付应检查dist无凭证，核对真实查询网络与页面；开发身份验证通过不能证明所有生产用户有权访问，发布目录权限需另行验证。

package/templates/web-app/docs/data-contract.md

@@ -0,0 +1,21 @@
+# 数据契约与适配范围
+
+## 输入与版本
+
+浏览器调用 `/v5/api/dashboard/report/{dashboardId}/widgets/query`，传板内实例 widgetIds、includeWidgetBean=true、pageLimit、refer。原生结果仅在 src/finebi/normalize.ts 解析。输出 schemaVersion=1，与 CLI 标准化结果采用相同的字段、值状态与范围语义；v1 浏览器只覆盖 DETAIL 和 CHART，不等于 Java 适配器的全部覆盖。
+
+## 消费顺序
+
+检查 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。受限/失败/不支持结果不回退静态样本。

package/templates/web-app/docs/design.md

@@ -0,0 +1,13 @@
+# 页面骨架
+
+图表库和UI组件库不限定，按页面的展示、交互和设计需求选择。模板默认使用ECharts绘图，筛选栏默认使用Ant Design和date-fns；开发时可替换为D3等图表实现，或选用合适的UI组件库，也可使用原生控件。更换库需要调整对应展示组件、依赖和样式，不是app-config中的自动切换选项。
+
+替换展示实现时继续复用src/finebi的取数与认证逻辑，遵循[数据契约](data-contract.md)和[筛选契约](filters.md)，保留值状态、数据范围提示、空/错误状态及请求取消处理；按所选库的生命周期释放图表、监听器和其他资源。
+
+默认FilterBar提供可搜索单选/多选、日期及年月区间日历、输入框、空值勾选、重置和应用按钮；其他日期类输入保留对应格式。日历与选择器采用中文界面，筛选卡片展示待应用状态，小屏幕自动换行，区间日历可滚动。主题在FilterBar的ConfigProvider中配置，布局在src/styles.css中调整。搜索仅过滤配置的候选项，不触发远端候选查询。
+
+`layout=overview` 使用顶部标题/刷新、筛选栏、双列图表和通栏表格，适合单页分析。
+
+`layout=workbench` 增加侧栏应用导航，适合后续扩展多页面。两者共用src/styles.css的颜色、间距和面板规则；小屏幕收为单列。通过修改应用页面与业务组件扩展，不复制请求/认证/解析代码。
+
+默认Chart组件基于ECharts提供柱状、折线和饼图的基本映射、resize和dispose；Widget提供KPI和错误边界，DataTable提供范围明确的本地搜索/分页。Agent按业务绑定categoryFieldId/valueFieldId，不以返回形状猜图表类型。复杂图形需新增明确的适配与测试。