@finebi/finebi-cli 1.6.3 → 2.0.1

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,96 @@
-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")],
+    ["dsh", "DeepSeek Harness", env.DSH_HOME || join(home, ".dsh")],
+    ["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")],
+    ["workbuddy", "WorkBuddy", env.WORKBUDDY_HOME || join(home, ".workbuddy")],
+    ["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

@@ -5,7 +5,7 @@
 1. 用 FineBI CLI 搜索并读取 dashboard info/data，确认唯一来源、看板实例 entryId、queryFields.dId 和真实控件 filterName。按[验收文档](docs/acceptance.md#1-绑定与设计准备)记录指标公式/聚合、单位、时间粒度与时区、筛选作用范围及数据完整性；必要时读取 bean，未知项明确标记，不按组件标题猜语义。
 2. 按下方[阅读路径](#阅读路径)读取当前步骤需要的章节，再修改 public/app-config.json；不要求开场通读全部文档。
 3. 按[设计选择](docs/design.md#设计选择与信息组织)写出页面面向谁、首屏重点、导航、图表分组和信息密度，遵循用户已确认的方向继续开发。新风格说明与已有布局在结构、层级和视觉上的区别。从 overview、workbench、cockpit 或 retail 起步，示例配置仅含占位绑定。
-4. 整页绑定前，按[最小真实查询](docs/acceptance.md#11-最小真实查询)先配置一个组件，启动开发页面，通过开发代理确认真实身份、查询、解析和页面值；再补齐本页需要的指标、图表与真实筛选链路，通过后扩展整页。使用真实接口开发；合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
+4. 整页绑定前，按[最小真实查询](docs/acceptance.md#11-最小真实查询)先确认开发身份，缺少身份时及时请求最小凭据或授权操作；只配置一个组件，启动开发页面，留下真实请求、业务响应与页面值一致的证据，再补齐代表性图表和筛选链路，通过后扩展整页。身份或查询受阻时暂停扩展，不自行切换为 mock、历史响应回放或静态数据预览；阻断处理和用户明确要求离线演示的边界见该验收章节。合成样本仅用于 tests，禁止将开发查询数据写入正式页面、配置或回退数据。
 5. 业务转换放 src/services，页面放 src/pages 或 App.tsx，通用请求与原生解析复用 src/finebi。改动共享组件时检查其他布局，不为换风格复制查询、认证或筛选编码。
 6. 按[分层验收](docs/acceptance.md)执行 npm test、npm run build、浏览器冒烟及真实绑定验收。检查整页和关键状态，分别记录 CLI、开发身份、生产 Cookie 的验证结论；构建成功不等于认证、取数或视觉验收通过。