@finebi/finebi-cli 1.5.0 → 1.6.1

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,30 @@
+# FineBI 动态页面开发
+
+## 开发顺序
+
+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。
+3. 按[设计选择](docs/design.md#设计选择与信息组织)写出页面面向谁、首屏重点、导航、图表分组和信息密度，遵循用户已确认的方向继续开发。新风格说明与已有布局在结构、层级和视觉上的区别。从 overview、workbench、cockpit 或 retail 起步，示例配置仅含占位绑定。
+4. 先跑通一个指标、一张图和一个真实控件（源看板有控件时）的查询、展示、应用与恢复默认，再扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
+5. 业务转换放 src/services，页面放 src/pages 或 App.tsx，通用请求与原生解析复用 src/finebi。改动共享组件时检查其他布局，不为换风格复制查询、认证或筛选编码。
+6. 按[分层验收](docs/acceptance.md)执行 npm test、npm run build、浏览器冒烟及真实绑定验收。检查整页和关键状态，分别记录 CLI、开发身份、生产 Cookie 的验证结论；构建成功不等于认证、取数或视觉验收通过。
+
+## 数据规则
+
+- 用 CLI 指定 `--dimension-ids` 时，必须同时列出需要的维度和指标；只传维度会关闭未选指标。模板目前不提供字段选择配置，浏览器查询沿用保存配置；完整语义见[数据契约](docs/data-contract.md#字段选择)。
+- 先检查 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。开发代理不属于构建产物；不要把它部署为共享多用户服务。
+- 目录来源配置 directoryEntryId，原生请求保留 reportEntryId；需目标平台 HTTP 接口支持目录权限预检与 MOUNT 查询，不得失败后回退到分析主题。不支持交叉表、服务端续页、全局排序或托管发布命令。
+- 图表按生命周期销毁；异步请求取消且旧响应不得覆盖新条件。失败状态不得展示过期数据充当最新结果。
+- 验收证据、截图和临时脚本放项目 temp/，不随包发布。交付记录已验证/失败/未验证项、运行方式、模板版本和业务绑定范围；模板维护流程由 CLI 源仓库负责，本项目无需其脚本才能开发和验收。
+
+项目创建不会安装依赖、启动服务、初始化 Git 或发布，按用户授权范围执行后续步骤。

package/templates/web-app/README.md

@@ -0,0 +1,36 @@
+# 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. 按[开发与验收](docs/acceptance.md)执行 `npm test`、`npm run build`、`npm run test:browser`，再验证真实绑定。浏览器验收页使用合成数据，不连接 FineBI。`npm run preview` 只展示 dist，不启用开发身份代理；真实生产取数需要同源 FineBI 路径。
+
+## 配置
+
+`layout` 为 `overview`（顶部概览）、`workbench`（侧栏工作台）、`cockpit`（绿色经营驾驶舱）或 `retail`（米白经营简报）。可用 `finebi-cli app create --name my-retail --path <parent> --layout retail` 创建；默认配置仍为空绑定，不会请求示例资源。`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)。
+
+cockpit 的配置骨架在 [examples/cockpit.config.json](examples/cockpit.config.json)，仅包含占位绑定。替换所有 `REPLACE_*`，再复制到 `public/app-config.json`；可删除不需要的组件，KPI 数量也可调整。`insights:true` 开启当前查询观察，`dataNotes` 补充口径。多系列 `series`、表格字段/本地筛选和控件作用映射见 [页面骨架](docs/design.md)。示例中的 `filterNames:[]` 表示不覆盖控件，必须按真实映射配置，不能直接当成业务默认。
+
+retail 的 [examples/retail.config.json](examples/retail.config.json) 提供零售分析绑定骨架：四项 KPI、趋势、门店 TOP10、区域/品类、门店类型和明细。采用横向导航、米白背景和蓝橙图表，不依赖侧栏。示例不含业务数据，`REPLACE_*`、模型选择、时区及筛选作用范围必须核实替换；普通分析来源需删除目录入口占位字段。金额与百分比、毫秒月份的显式显示配置见[页面骨架](docs/design.md)。
+
+目录发布看板在配置中增加 `directoryEntryId`，使用与该入口匹配的 dashboardId/实例。模板将其原样作为 `reportEntryId` 传给 Cookie 查询接口及开发代理；目标平台需同时支持目录权限预检和 MOUNT 查询，不能只支持 CLI 目录查询。错误独立显示，不回退“我的分析”。
+
+筛选先编辑、再点击“应用筛选”；“恢复全部默认”重新查询看板保存条件。模板支持文本、单选/多选、数值选择和日期类控件，完整类型、空值语义与配置示例以[筛选契约](docs/filters.md)为准；`app inspect` 仅检查本地配置，绑定后仍需验证真实条件生效。