@finebi/finebi-cli 1.6.1 → 1.6.2

package/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/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 内置模板规则的兼容性，不作为定制应用验收门禁。绑定后仍需通过项目测试、构建与真实浏览器验证条件生效。