@finebi/finebi-cli 1.2.1 → 1.3.0

package/skills/finebi-cli-agent/references/formula-functions.md

@@ -0,0 +1,247 @@
+## 四、函数库
+
+按函数名定位本文件对应行；官方单函数页和场景页可在 [来源索引](formula-help-index.md) 查找。引擎、使用位置和重载限制见 [官方使用边界](formula-help-boundaries.md)。`PERIOD_TD`、`TOSTRING`、`WINDOW_MEDIAN` 是既有实例参考的补充项，不代表本次官方目录有完整单函数说明，使用前查询目标面板。
+
+本文件用于选型与简例；生成具体调用前，按下表进入逐参数说明。每个函数均有独立小节和来源链接，覆盖参数含义、类型、可省略性、已知默认值及边界；未明确的原文约定不补造。
+
+| 函数族 | 参数手册 |
+|---|---|
+| 文本、拆分、替换、格式、正则 | [文本参数](formula-parameters-text.md) |
+| 日期构造、偏移、差值、提取、周 | [日期参数](formula-parameters-date.md) |
+| 数值、三角、随机、逻辑、空值 | [数值与逻辑参数](formula-parameters-math-logic.md) |
+| 聚合、累计、同期、排名、汇总 | [聚合与表格计算参数](formula-parameters-aggregate.md) |
+| DEF、CLEAN、LOD、WINDOW、RANK_AGG、引用 | [分析函数参数](formula-parameters-analysis.md) |
+
+### ▸ 聚合函数（`XXX_AGG`）
+
+按当前分析维度，对指标做聚合，返回一列数据（行数与当前分析维度行数一致）。参数 `array` 必须是**非聚合函数公式**的返回值（指标字段、维度、或指标字段与普通公式的计算结果）。
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `SUM_AGG(array)` | 汇总求和 | `SUM_AGG(${销售额})` |
+| `AVG_AGG(array)` | 汇总平均值 | `AVG_AGG(${销售额})` |
+| `COUNT_AGG(array)` | 对非空值计数；统计全部记录用 `COUNT_AGG(1)` | `COUNT_AGG(${订单号})` |
+| `COUNTD_AGG(array)` | 对非空值去重计数 | `COUNTD_AGG(${会员ID})` |
+| `APPROX_COUNTD_AGG(array)` | **[Direct 独有]** 近似去重计数（大数据量性能好，结果近似；仅部分数据库支持，见注） | `APPROX_COUNTD_AGG(${会员ID})` |
+| `MAX_AGG(array)` | 最大值（array 为非数值字段时只能在 def 中使用） | `MAX_AGG(${销售额})` |
+| `MIN_AGG(array)` | 最小值 | `MIN_AGG(${销售额})` |
+| `MEDIAN_AGG(array)` | 数值中位数；官方限定组件使用，MySQL 不支持 | `MEDIAN_AGG(${销售额})` |
+| `PERCENTILE_AGG(array, 百分位)` | 指定百分位的值；百分位为 0~1 之间的**数值常量**（如 0.66），不支持文本和日期 | `PERCENTILE_AGG(${销售额}, 0.95)` |
+| `STDEV_AGG(array)` | 总体标准差，对应 Excel `STDEV.P` | `STDEV_AGG(${销售额})` |
+| `VAR_AGG(array)` | 方差 | `VAR_AGG(${销售额})` |
+
+> `APPROX_COUNTD_AGG` 与 `PERCENTILE_AGG` 的数据库白名单及组合限制见 [官方使用边界](formula-help-boundaries.md#2-数据库与标量函数限制)。近似计数不用于要求精确人数或账目核对的口径。
+
+### ▸ 表格计算（行间 / 排名 / 累计，指标必须是聚合函数或聚合指标）
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `ACC_SUM(指标, range)` | 跨行累计；`range`：0 对所有行累计，1 对组内累计 | `ACC_SUM(SUM_AGG(${销售额}), 0)` |
+| `PERIOD_ANLS(指标, datepart)` | 上期末值；`datepart`："Y" 上年末、"M" 上月末、"W" 上周期末；不支持 "Q" | `PERIOD_ANLS(SUM_AGG(${销售额}), "Y")` |
+| `PREVIOUS_PERIOD(指标)` | 按分析区日期分组取得上一周期值（日分组取上一日、年月分组取上月） | `PREVIOUS_PERIOD(SUM_AGG(${销售额}))` |
+| `SAME_PERIOD(指标, datepart)` | 同期值；"Y" 上年同期、"M" 上月同期、"W" 上周同期。返回基期值，增长率还需除法再减 1 | `SAME_PERIOD(SUM_AGG(${销售额}), "Y")` |
+| `RANK_ANLS(指标, range, order)` | 跨行排名；`range`：0 所有行，1 组内；`order`："asc" 升序 / "desc" 降序 | `RANK_ANLS(SUM_AGG(${销售额}), 0, "desc")` |
+| `TOTAL(指标, range, agg)` | 跨行汇总；`range`：0 所有行，1 组内；`agg`："sum" / "avg" / "max" / "min" | `TOTAL(SUM_AGG(${销售额}), 0, "avg")` |
+| `PERIOD_TD(指标, datepart)` | **[Direct 独有]** 截至当前期间的累计同比 / 累计环比；`datepart`："Y" 累计同比（需拖入年、年月字段），"M" 累计环比（需拖入年月、年月日字段） | `PERIOD_TD(SUM_AGG(${销售额}), "Y")` |
+
+> 表格计算依赖横纵轴 / 行列维度中添加的字段，维度字段不满足计算要求时该指标会标红。
+
+### ▸ 数值 / 数学
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `ABS(x)` | 绝对值 | `ABS(-1.5) = 1.5` |
+| `CEILING(x)` | 抽取远离零取整；直连向正无穷取整 | `CEILING(-2.5)`：抽取 -3、直连 -2 |
+| `FLOOR(x)` | 抽取向零取整；直连向负无穷取整 | `FLOOR(-2.5)`：抽取 -2、直连 -3 |
+| `INT(x)` | 抽取向负无穷取整；直连向零截断 | `INT(-4.8)`：抽取 -5、直连 -4 |
+| `ROUND(x, n)` | 四舍五入到 n 位（n<0 时在小数点左侧舍入） | `ROUND(2.15, 1) = 2.2`、`ROUND(21.5, -1) = 20` |
+| `TRUNC(x[, n])` | 截断到 n 位（不四舍五入）；省略 n 则截为整数 | `TRUNC(-8.98, 1) = -8.9` |
+| `MOD(x, y)` | 抽取余数符号随除数；直连随被除数 | `MOD(-3, 2)`：抽取 1、直连 -1 |
+| `POWER(x, n)` | 乘方（可用 `^` 替代）；负数底数要求整数指数 | `POWER(6, 2) = 36`、`5 ^ 2 = 25` |
+| `SQRT(x)` | 平方根（负数返回空值） | `SQRT(64) = 8` |
+| `SIGN(x)` | 符号：正 1 / 零 0 / 负 -1 | `SIGN(-0.00001) = -1` |
+| `EXP(x)` | e 的 x 次方 | `EXP(3) = 20.09` |
+| `LN(x)` | 自然对数 | `LN(EXP(3)) = 3` |
+| `LOG(x, base)` | 指定底数的对数（省略 base 默认 10） | `LOG(16, 2) = 4`、`LOG(10) = 1` |
+| `LOG10(x)` | 以 10 为底的对数 | `LOG10(100) = 2` |
+| `MAX(a, b, ...)` | 参数中的最大值（非聚合） | `MAX(${A}, ${B}, 0)` |
+| `MIN(a, b, ...)` | 参数中的最小值（非聚合） | `MIN(${A}, 100)` |
+| `PROMOTION(v1, v2)` | v2 相对 v1 的提升比例 `(v2-v1)/ABS(v1)`；基数为 0 时另行处理 | `PROMOTION(-12, 14) ≈ 2.1667` |
+| `PI()` | 圆周率；可带参数表示 π 的整数倍，`PI(3) = 9.42` | `SIN(PI()/2) = 1` |
+| `RAND()` | [0,1) 均匀随机数，每次计算可变化 | `RAND() * 60` |
+| `RANDBETWEEN(a, b)` | 两数之间的随机整数；整数部分相同时返回该整数部分 | `RANDBETWEEN(12.333, 13.233) = 13` |
+| `FACT(x)` | **[Spider 独有]** 阶乘（非整数先截尾） | `FACT(5) = 120` |
+| `SIN(x) / COS(x) / TAN(x)` | 三角函数（参数为弧度） | `SIN(45 * PI()/180)` |
+| `ASIN(x) / ACOS(x) / ATAN(x)` | 反三角函数（返回弧度）；ASIN/ACOS 输入须在 [-1,1] | `ACOS(0.5) ≈ 1.047` |
+| `ATAN2(x, y)` | 坐标 (x,y) 与 x 轴的夹角（弧度），参数顺序为 x、y；(0,0) 报错 | `ATAN2(2, 2) ≈ 0.785` |
+| `DEGREES(x)` / `RADIANS(x)` | 弧度 ↔ 角度互转 | `DEGREES(PI()/2) = 90` |
+
+### ▸ 日期
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `DATE(year, month, day)` | 构造日期；month/day 进位为抽取文档明确的行为，直连需核验 | `DATE(1978, 9, 19)`；抽取 `DATE(2000, 13, 5) = 2001-01-05` |
+| `TIME(hour, minute, second)` | 构造时间（日期取系统当天） | `TIME(14, 40, 0)` |
+| `TODAY()` | 当前日期 | `TODAY()` |
+| `NOW()` | 当前日期时间 | `NOW()` |
+| `TODATE(参数)` | 转为日期。5 种参数：日期直接返回；毫秒数；文本；文本+格式；文本+格式+语言 | `TODATE("2007-10-15")`、`TODATE("20110830", "yyyyMMdd")`、`TODATE("星期一1/15/07", "EEEMM/dd/yy", "zh")` |
+| `DATETONUMBER(date)` | 自 1970-01-01 00:00:00 GMT 的毫秒数 | `DATETONUMBER("2008-08-08")` |
+| `DATEDELTA(date, n)` | 日期偏移 n 天（n 可正负零） | `DATEDELTA("2008-08-08", -10) = 2008-07-29` |
+| `MONTHDELTA(date, n)` | 日期偏移 n 个月 | `MONTHDELTA("2008-08-08", 4) = 2008-12-08` |
+| `YEARDELTA(date, n)` | 日期偏移 n 年 | `YEARDELTA("2008-10-10", 10) = 2018-10-10` |
+| `DATEDIF(start, end, unit)` | end − start，可为负；"Y" 年 / "M" 月 / "D" 天 / "MD" 忽略年月取日差 / "YM" 忽略年日取月差 / "YD" 忽略年取日差；空日期须先拦截 | `DATEDIF("2001-02-28", "2004-03-20", "MD") = -8` |
+| `DATESUBDATE(d1, d2, op)` | d1 − d2 的时间差（可为负）。op："s"/"S" 秒，"m"/"M" **分钟**，"h"/"H" 小时，"d"/"D" 天，"w"/"W" 周 | `DATESUBDATE("2008-08-08", "2008-06-06", "h") = 1512` |
+| `DAYS360(start, end, method)` | **[Spider 独有]** 按每年 360 天（每月 30 天）算天数差；method：FALSE/空为美国法，TRUE 为欧洲法 | `DAYS360("1998/1/30", "1998/2/1") = 1` |
+| `YEAR([date[, 格式]])` | 年份（可空参取当前，下同） | `YEAR("2000/1/1") = 2000` |
+| `MONTH([date[, 格式]])` | 月份 1~12 | `MONTH("2000/1/1") = 1` |
+| `DAY([date[, 格式]])` | 日 1~31 | `DAY("2000/1/1") = 1` |
+| `QUARTER([date[, 格式]])` | 季度 1~4 | `QUARTER("2000/1/1") = 1` |
+| `HOUR([time[, 格式]])` | 小时 0~23 | `HOUR("11:32:40") = 11` |
+| `MINUTE([time[, 格式]])` | 分钟 0~59 | `MINUTE("15:36:25") = 36` |
+| `SECOND([time[, 格式]])` | 秒 0~59 | `SECOND("15:36:25") = 25` |
+| `WEEKDAY(date)` | 星期几，0=周日 … 6=周六 | `WEEKDAY("2005/9/10") = 6` |
+| `WEEK([date[, "F1"/"F7"]])` | 周序号；抽取 F1 为含 1 月 1 日的周算第 1 周，F7（默认）为首个完整周算第 1 周；周起始日由平台设置决定；直连文档仅给出 0/1 参 | `WEEK("2010-01-01", "F1") = 1`（抽取） |
+| `WEEKDATE(year, month, weekOfMonth, dayOfWeek)` | 指定年月的第几周、周几的日期；dayOfWeek=-1 表示该周最后一天 | `WEEKDATE(2009, 10, 2, 1)` |
+| `DAYSOFMONTH(date)` | 该月天数 | `DAYSOFMONTH("1900-02-01") = 28` |
+| `DAYSOFQUARTER(date)` | 该季度天数 | `DAYSOFQUARTER("2009-02-01") = 90` |
+| `DAYSOFYEAR(year)` | 该年天数 | `DAYSOFYEAR(2008) = 366` |
+| `DAYVALUE(date)` | 自 1900 年以来的天数 | `DAYVALUE("2008/08/08") = 39667` |
+| `LUNAR(year, month, day)` | **[Spider 独有]** 公历年月日转农历表示，年份范围以目标面板为准 | `LUNAR(2011, 7, 21)` |
+
+> 提取函数 YEAR/MONTH/DAY/QUARTER/HOUR/MINUTE/SECOND 都允许空参 `YEAR()`，表示取当前系统服务器时间对应值；抽取支持 0/1/2 参，指定格式须同时提供日期输入；直连按官方明确签名使用 0/1 参，详见日期参数手册。
+
+### ▸ 文本
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `CONCATENATE(t1, t2, ...)` | 显式拼接字符串，直连 NULL 行为依数据库而异 | `CONCATENATE(${省}, ${市})` |
+| `LEFT(s, n)` | 左侧取 n 个字符（省略 n 默认 1） | `LEFT("Finesoftware", 8) = "Finesoft"` |
+| `RIGHT(s, n)` | 右侧取 n 个字符 | `RIGHT("Itisinteresting", 6) = "esting"` |
+| `MID(s, start, len)` | 从 start（1 起始）取 len 个字符 | `MID("Finemoresoftware", 9, 8) = "software"` |
+| `LEN(s)` | 字符数；参数为数组时返回数组长度 | `LEN("你好") = 2`、`LEN(["a","b"]) = 2` |
+| `UPPER(s)` / `LOWER(s)` | 转大写 / 转小写 | `UPPER("notes") = "NOTES"` |
+| `PROPER(s)` | **[Spider 独有]** 每个单词首字母大写 | `PROPER("hello world") = "Hello World"` |
+| `TRIM(s)` | 去首尾空格 | `TRIM(" Monthly Report ")` |
+| `REPLACE(text, old, new)` | 子串替换；另有形式 `REPLACE(old_text, start_num, num_chars, new_text)` 按位置替换 | `REPLACE("abcd", "a", "re") = "rebcd"`、`REPLACE("0123456789", 5, 4, "*") = "0123*89"` |
+| `SUBSTITUTE(text, old, new[, n])` | **[Spider 独有]** 替换 old；指定 n 只替换第 n 次出现，否则全替换 | `SUBSTITUTE("database", "base", "model") = "datamodel"` |
+| `FIND(find_text, within, start_num)` | 子串位置（1 起始，start_num 默认 1）；**未找到返回 0** | `FIND("o", "Information", 2) = 4`、`FIND("o", "Information", 12) = 0` |
+| `INDEXOF(str, index)` | 取 index（0 起始）处的字符；也支持数组 | `INDEXOF("FineBI", 0) = "F"`、`INDEXOF(["a","b","c"], 1) = "b"` |
+| `STARTWITH(str1, str2)` | 是否以 str2 开头，返回 1/0，区分大小写 | `STARTWITH("FineBI", "Fine") = 1` |
+| `ENDWITH(str1, str2)` | 是否以 str2 结尾，返回 1/0，区分大小写 | `ENDWITH("FineBI", "BI") = 1` |
+| `EXACT(a, b)` | 完全相等（区分大小写、忽略格式），返回 TRUE/1 | `EXACT("Spreadsheet", "spreadsheet") = 0` |
+| `REGEXP(str, pattern[, mode])` | 正则匹配；第三参仅抽取文档支持，模式及转义见 [使用边界](formula-help-boundaries.md#2-数据库与标量函数限制) | `REGEXP("aaaaac", "a*c") = true` |
+| `REPEAT(s, n)` | 重复 n 次 | `REPEAT("$", 4) = "$$$$"` |
+| `SPLIT(s, delimiter)` | **[Spider 独有]** 按分隔符拆成数组；取某段用 `INDEXOF(SPLIT(...), n)` | `SPLIT("hello,world", ",") = ["hello","world"]` |
+| `CHAR(code)` | 数值代码转字符 | `CHAR(88) = "X"` |
+| `CODE(s)` | 首个字符的数值代码，对应计算机使用的字符集 | `CODE("S") = 83` |
+| `FORMAT(object, format)` | 返回文本；抽取支持数值/日期等，直连首参只支持日期；年 yy/yyyy、月 M/MM、日 d/dd | 抽取 `FORMAT(1.5, "0%") = "150%"`；`FORMAT(DATE(2007,1,13), "yyyy-MM-dd")` |
+| `NUMTO(number, boolean)` | **[Spider 独有]** 数字的中文表示；boolean 控制读数方式 | `NUMTO(2345, false) = "二千三百四十五"` |
+| `TODOUBLE(text)` | 文本转数值 | `TODOUBLE("123.21")` |
+| `TOINTEGER(text)` | 文本转整数 | `TOINTEGER("123")` |
+| `TOSTRING(object)` | **[Direct 独有]** 其他类型转文本 | `TOSTRING(123) = "123"` |
+
+### ▸ 逻辑
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `IF(条件1, 结果1, 条件2, 结果2, ..., 其他结果)` | 多分支判断：满足条件 1 返回结果 1，满足条件 2 返回结果 2，…，否则返回其他结果；也支持标准三参 `IF(条件, 真值, 假值)`。所有结果类型须相同，其他结果可省略 | `IF(${单价}<4000, "类型A", ${单价}<8000, "类型B", "类型C")`、`IF(ISNULL(${x}), 0, ${x})` |
+| `SWITCH(表达式, 值1, 结果1, 值2, 结果2, ..., 其他结果)` | 按值相等匹配，至少 3 参；结果保持同类型，直连要求一致。默认结果可省略，未匹配且无默认时返回 NULL；区间判断用 IF | `SWITCH(${季度}, 1, "Q1", 2, "Q2", 3, "Q3", 4, "Q4", "其他")` |
+| `AND(c1, c2, ...)` | 全部为真返回 1，否则 0 | `AND(1+7=8, 5+7=12) = 1` |
+| `OR(c1, c2, ...)` | 任一为真返回 1，全假返回 0 | `OR(1+7=8, 5+7=11) = 1` |
+| `NOT(条件表达式)` | 取反，返回 1/0 | `NOT(IN(${城市}, "北京", "上海"))` |
+| `ISNULL(object)` | 所有值全为 NULL 或空字符串返回真，否则假；直连单参、抽取可多参 | `ISNULL(${x})` |
+| `IFERROR(value1, value2)` | value1 是异常值（正无穷、负无穷、NaN，**不含空值**）时返回 value2，否则返回 value1 | `IFERROR(${A} / ${B}, 0)`、`IFERROR(100/0, 1) = 1` |
+| `NVL(v1, v2, ...)` | 返回第一个非 null、非空字符串值；参数至少一个且类型统一 | `NVL(${Sales}, 0)`、`NVL(${A}, ${B}, 0)` |
+| `IN(exp, para1, para2, ...)` | exp 是否属于集合；参数类型一致，exp 不能为 NULL 或多值参数；候选项为常量、常量表达式或组件参数 | `IN(${城市}, "北京", "上海", "广州")` |
+
+### ▸ 分析函数（跨数据行 / 静态动态指标）
+
+> 自助主题按目标面板选择 `DEF` 家族 / `WINDOW_*` / `RANK_AGG`，Direct 还受数据库限制。标准主题跨粒度计算用 LOD；跨行错期需求不能假定可直接翻译成 LOD。
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `DEF(指标, [维度1, 维度2], [过滤1, 过滤2])` | 定义**静态**指标：满足过滤条件的明细数据按指定维度对指标聚合；后两参数可省略 | `DEF(SUM_AGG(${购买数量}), [${产品}], [${是否会员} = "是"])` |
+| `DEF_ADD(指标, [维度], [过滤])` | 定义**动态**指标：在分析区域已有维度基础上**增加**指定维度聚合 | `DEF_ADD(SUM_AGG(${购买数量}), [${产品}], [])` |
+| `DEF_SUB(指标, [维度], [过滤])` | 定义**动态**指标：在分析区域已有维度基础上**减去**指定维度聚合 | `DEF_SUB(SUM_AGG(${购买数量}), [${产品}], [])` |
+| `EARLIER(字段)` | 上一个视图（分析区当前行）的计算值，只能用于 def/def_add/def_sub，常做行间过滤；**参数性质必须是 disAgg（不能是 agg、不能是 dual/常量）**——所以字段、字段与常量的运算（如 `EARLIER(${序号} - 2)`）、`SUB_DIM` 等维度引用表达式均可，纯常量不行（组内行间累计的组合写法见"引用函数"节） | `DEF(SUM_AGG(${购买数量}), [${序号}], [${序号} <= EARLIER(${序号})])` |
+| `CLEAN(字段1, ...) / CLEAN("ALL")` | 在当前 DEF 中忽略界面过滤；字段形式与 ALL 形式范围不同，均不清权限过滤、同层显式过滤；见 [过滤边界](formula-help-boundaries.md#4-def-与过滤范围) | `DEF(SUM_AGG(${指标}), [${省份}, ${城市}], [CLEAN(${城市})])` |
+| `CLEAN_WIDGET(字段1, ...) / CLEAN_WIDGET("ALL")` | 忽略指定字段（或全部字段）在**组件**中产生的过滤效果；用法同 CLEAN | `DEF_ADD(SUM_AGG(${指标}), [], [CLEAN_WIDGET("ALL")])` |
+| `WINDOW_(AVG\|MAX\|MIN\|SUM\|MEDIAN\|STDEV\|VAR)(指标, [分组字段], [排序字段, 排序方式], [窗口上限, 窗口下限])` | 对窗口做相应聚合。指标必填；省分组即整组，省排序按默认顺序，省窗口即整分区。边界 `"first"/"last"` 为组内首/末行，0 为当前行，-n/n 为前/后 n 行 | `WINDOW_SUM(SUM_AGG(${销售额}), [${城市}], [SUM_AGG(${销售额})], [-2, 0])` |
+| `RANK_AGG([分组字段], [排序字段, 排序方式], 排序模式)` | 按规则排序求排名；**三个参数全部可省**：省分组字段即整组参与；排序方式省略默认 "asc"；排序模式省略默认 COMMON。排序方式 "asc"/"desc"；排序模式：COMMON（1,2,2,4）/ DENSE（1,2,2,3）/ UNIQUE（1,2,3,4）/ PERCENTILE（0,0.33,0.33,1） | `RANK_AGG([${省份}], [SUM_AGG(${销售额})])`（按省份分组、按销售额升序、COMMON 模式） |
+
+> `WINDOW_MEDIAN` 为 **[Spider 独有]**（Direct 白名单不含）；WINDOW 函数的分组/排序字段需为聚合性质且来源分析视图。
+> **排序字段与排序方式成对出现在同一数组内**：`[排序字段1, 方式1, 排序字段2, 方式2]`；如省略方式，应全部省略，默认升序。例：`WINDOW_AVG(SUM_AGG(${销售额}), [${品类}], [${年月}, "ASC"], [-2, 0])` 按品类分组、按年月升序，取当前及前两行平均；只有月份连续且每月一行时才是连续三个月。
+> DEF 维度参数与过滤条件参数用数组 `[ ]` 表达；`DEF` 的维度数组可用 `ADD_DIM()` / `SUB_DIM()` 动态引入外部视图维度；`DEF_ADD` / `DEF_SUB` 的维度参数不支持引用函数。字段元素写成 `${字段名}`。
+> **维度/过滤参数也允许单参数裸写**（不强制是数组）：如 `DEF(COUNTD_AGG(${产品}), ${省份})`、`DEF(指标, ${d}, ${f} > 0)` 都合法（代码 `isDEF` 不再强制 list 校验）。**生成公式时仍优先数组形式 `[ ]`** 以保持风格统一，单参数裸写仅作允许，不主动采用。
+> **DEF 的过滤条件可引用其他计算指标/聚合字段**：只要过滤条件整体性质是 disAgg/dual 即可。例如 `目标差额` 是另一个 DEF_ADD 的结果字段（disAgg），可写 `DEF(COUNTD_AGG(${产品}), [${省份}], ${目标差额} > 0)` 统计差额为正的去重产品数。
+> `RANK_AGG` 与 `RANK_ANLS` 的区别：`RANK_ANLS` 是表格计算——对结果集整体排名，`range` 控制全表/组内，指标参数为聚合结果；`RANK_AGG` 是窗口排名——按 `[分组字段]` 分区、按 `[排序字段, 排序方式]` 排序后求排名，排序字段必须是**严格的聚合结果**，表格计算的结果（如 `TOTAL(...)`）不能作为它的排序字段。
+
+### ▸ LOD 表达式（FIXED / INCLUDE / EXCLUDE，仅直连标准版）
+
+LOD（Level of Detail，详细级别）表达式用 `{ }` 花括号包裹，是 Direct 引擎的**直连标准版**业务细分专属能力，用来实现类似 Tableau 的 FIXED 效果：
+
+```
+{FIXED|INCLUDE|EXCLUDE 维度1, 维度2...: 聚合表达式}
+```
+
+| 关键字 | 含义 | 内部对应 |
+|--------|------|---------|
+| `FIXED` | 定义**静态**指标：无视分析区域的维度，只按声明维度聚合；第一个参数（维度）可省略 | DEF |
+| `INCLUDE` | 定义**动态**指标：在分析区域已有维度基础上**增加**声明维度聚合；第一个参数可省略 | DEF_ADD |
+| `EXCLUDE` | 定义**动态**指标：在分析区域已有维度基础上**减去**声明维度聚合；第一个参数可省略 | DEF_SUB |
+
+规则：
+
+- 冒号 `:` 后必须是聚合表达式；维度（冒号前）不能是聚合表达式。
+- 维度不能是 `INCLUDE` / `EXCLUDE` 自身。
+- LOD 表达式内部引用的字段之间需有关联关系：没有维度时聚合指标可以没有关联，有维度时需要有关联。
+- LOD 表达式可以嵌套，最大嵌套层级 2 层。
+- `INCLUDE` / `EXCLUDE` 的结果必须为数值，且不支持作为维度输出。
+- 校验层允许兄弟节点共存，不代表不同主题的函数可混写。标准主题生成 LOD 时不混入其面板不支持的 DEF/WINDOW。嵌套另外受参数性质与层数限制，见 [合法性约束](formula-validation.md)。
+
+示例：
+
+| 公式 | 说明 |
+|------|------|
+| `{FIXED ${产品}: SUM_AGG(${购买数量})}` | 无视分析区域维度，只按"产品"维度聚合购买数量 |
+| `{FIXED: SUM_AGG(${购买数量})}` | 维度省略：对全部明细聚合，等价于全局总计 |
+| `{INCLUDE ${产品}: SUM_AGG(${购买数量})}` | 在分析区域维度基础上增加"产品"维度聚合 |
+| `{EXCLUDE ${产品}: SUM_AGG(${购买数量})}` | 在分析区域维度基础上减去"产品"维度聚合 |
+
+### ▸ 引用函数（动态引入 / 判断分析区字段）
+
+`ADD_DIM` / `SUB_DIM` 用来在 `def` / `window` / `field_in` 里**动态引入"指定视图（分析区）"的维度**，写出来是"维度引用"，不返回数值，不能单独作为公式结果输出。
+
+| 函数 | 说明 | 示例 |
+|------|------|------|
+| `ADD_DIM(维度1, ...)` | **维度并集**：返回「指定视图的全部维度 **+** 函数声明的维度」。指定视图：用在 `def` 的维度参数中时指外部视图（分析区），其他场景指当前所在视图。参数为空则只返回指定视图的全部维度。参数必须是维度字段；只能配合 def / window / field_in 使用 | `DEF(SUM_AGG(${销售额}), [ADD_DIM(${产品})], [])`：按「分析区维度 + 产品」聚合 |
+| `SUB_DIM(维度1, ...)` | **维度差集**：返回「指定视图的全部维度 **−** 函数声明的维度」；参数为空同样返回指定视图的全部维度。指定视图定义、参数约束、配合对象同 `ADD_DIM` | `WINDOW_SUM(SUM_AGG(${销售额}), [SUB_DIM(${年月})], [${年月}], ["first", 0])`：按「分析区维度 − 年月」分组做组内行间计算 |
+| `FIELD_IN([参考字段集], [待检查字段集])` | 判断参考字段集是否**完全包含**待检查字段集（忽略内部顺序），返回 1/0；两个参数都必须是字段声明数组（如 `ADD_DIM()` 的返回值、或 `[${字段}]` 形式的字段数组） | `IF(FIELD_IN(ADD_DIM(), [${个人}]), ${个人成本}, ${公司成本})` |
+
+**ADD_DIM / SUB_DIM 与 DEF 家族的等价关系**（生成公式时的选型捷径）：
+
+- `DEF_ADD(指标, [维度])` ≡ `DEF(指标, [ADD_DIM(维度)])` —— 两者都按「分析区维度 ∪ {维度}」聚合
+- `DEF_SUB(指标, [维度])` ≡ `DEF(指标, [SUB_DIM(维度)])` —— 两者都按「分析区维度 − {维度}」聚合
+- `DEF_ADD(指标, [])` ≡ `DEF(指标, [ADD_DIM()])` —— 两者都按「分析区全部维度」聚合
+
+即：**动态"增加/减少维度"既可以直接用 `DEF_ADD` / `DEF_SUB`，也可以用 `DEF` 配合 `ADD_DIM` / `SUB_DIM` 表达，二者等价**。**选型优先 `ADD_DIM` / `SUB_DIM`（见"七、选型优先级"）**：生成时统一写 `DEF(指标, [ADD_DIM(维度)])` / `DEF(指标, [SUB_DIM(维度)])`，同一维度集可复用于 `FIELD_IN` 判断、`WINDOW` 分组、`EARLIER` 组内累计；`DEF_ADD` / `DEF_SUB` 保留为等价的快捷写法。
+
+> 组内行间累计的常用写法会用到 `SUB_DIM`（配合 `EARLIER`），例如：`DEF_ADD(SUM_AGG(${销售额}), [${年月}], [EARLIER(SUB_DIM(${年月})) = SUB_DIM(${年月}), ${年月} <= EARLIER(${年月})])`。
+
+> **条件计数排名模式**（无原生 RANK 函数时，用 DEF + COUNTD_AGG + 行间过滤实现名次）：统计「某指标优于当前行」的维度成员个数，+1 即当前行排名。
+> - 例（漏斗分析按节点客户数排名）：`排名 = DEF(COUNTD_AGG(${关键节点})+1, [${关键节点}], [${每个节点的客户数} > EARLIER(${每个节点的客户数})])`
+> - 解读：过滤条件筛出「客户数比当前节点大」的所有节点行，`COUNTD_AGG` 对其去重计数即「优于当前的节点个数」，+1 即排名；外层 IF 可把凑不齐窗口的行置空（如首节点）。
+> - 第 1 参数是 `COUNTD_AGG(维度)+1`（agg + dual = agg，符合 DEF 指标参数须 agg 的约束）；过滤条件用 `EARLIER` 引用当前行的累计/排名字段做行间判断。
+
+### ▸ 函数性质速查
+
+函数库前文按**用途**分（聚合/表格计算/数值/日期/文本/逻辑/分析函数/引用）；下面按**校验层性质**归类，用于混用判定（与规则 9 一致）：
+
+- **聚合类（agg）**（可作为表格计算/分析函数的指标参数）：`SUM_AGG`、`AVG_AGG`、`COUNT_AGG`、`COUNTD_AGG`、`APPROX_COUNTD_AGG`、`MAX_AGG`、`MIN_AGG`、`MEDIAN_AGG`、`PERCENTILE_AGG`、`STDEV_AGG`、`VAR_AGG`；**WINDOW 系列 / `RANK_AGG`**（性质继承指标参数，必为 agg）
+- **非聚合类（disAgg）**（按行计算，可与明细字段混用）：数学、日期、文本、逻辑等普通函数与明细/维度字段；**`DEF` 家族（`DEF`/`DEF_ADD`/`DEF_SUB`）**；**LOD（`FIXED`/`INCLUDE`/`EXCLUDE`，仅直连标准版）**；`ADD_DIM`/`SUB_DIM`（维度引用，配合 def/window/field_in 使用，不返回数值）
+- **表格计算类（tableCal）**（在聚合结果之上按行/组计算）：`TOTAL`、`ACC_SUM`、`RANK_ANLS`、`PREVIOUS_PERIOD`、`SAME_PERIOD`、`PERIOD_ANLS`、`PERIOD_TD`
+- **常量类（dual，可跨界混用）**：字面量、`TRUE/FALSE/NULL`、组件参数、用户标记的常量字段、`FIELD_IN`
+
+> **返回类型速记**：判断/逻辑类返回逻辑结果，数值化规则见 [语法规则 3](formula-syntax.md)；`IF`/`SWITCH` 按分支结果类型；文本类（`CONCATENATE`/`LEFT`/`RIGHT`/`MID`/`REPLACE`/`SUBSTITUTE`/`FORMAT`/`TOSTRING` 等）返回文本；`YEAR`/`MONTH`/`DAY` 等返回数值；`DATE`/`TODAY`/`TODATE` 返回日期。
+
+---

package/skills/finebi-cli-agent/references/formula-generation.md

@@ -0,0 +1,121 @@
+## 七、需求 → 公式生成指南
+
+AI 从"数据分析需求"出发生成 FineBI 公式时，按下面的流程与模板进行。
+
+### 需求澄清（生成公式之前）
+
+用户的问题常是"没头没尾"的（如「算个同比」「做个占比」「为啥我这公式报错」）。**直接拼公式前先判断信息是否完整**，缺关键字段就追问，不要默默假设。
+
+**按任务补齐必要信息**：先从上下文或目标主题查询取得；只询问会改变本次公式口径的缺项，纯文本清洗不要求无关的分组/分母信息。离线示例可明确假设后给模板。
+
+| 信息维度 | 缺失时的典型表现 | 追问示例 |
+|---------|----------------|---------|
+| **引擎/数据源** | 不知该用 Spider / Direct / 直连标准版 | "数据是抽取还是直连？" |
+| **组件维度** | 不知聚合粒度、不知表格计算的"组"怎么分 | "公式用在什么组件？维度拖了什么？" |
+| **指标字段** | 不知对哪个字段聚合 | "对哪个字段算？" |
+| **聚合范围/分母** | "占比""累计""排名"没说范围 | "占总计还是组内？组按什么维度分？" |
+| **时间窗口语义** | "同比""最近""累计"语义不明 | "年同比还是月同比？跨年怎么算？" |
+| **公式内容** | 用户问"为啥报错"但没贴公式 | "把公式贴出来看一下" |
+
+**模糊术语消歧**（用户常说的词有多义，必须确认）：
+
+| 用户说 | 可能指 | 必问点 |
+|--------|-------|--------|
+| 同比 / 环比 | 上年同期 / 上月同期 / 上周同期 / 日期分组的上一周期 | 明确基期；SAME_PERIOD 的 M 指上月同期，不是去年同月 |
+| 占比 | 占总计 / 组内 / 品类内 | 分母是什么范围？ |
+| 累计 | 全表 / 组内 / 按月滚动（含跨年处理） | 按什么范围累？跨年怎么算？ |
+| 排名 | 全表 / 组内 / 分区 | 在什么范围内排？ |
+| 最近一次 / 最新值 | last value（**公式层无解**） | 见下方"公式无解" |
+
+**公式非法时的反馈**：用户贴的公式不合法时，不只说"非法"——按第五章错误码规则表给「**错误码 / 原因 / 修正示例**」三段式回复（如「61500033 tableCal 输出文本：`IF(RANK_ANLS(...)<=3,"是","否")` 整体是 tableCal 且输出文本，改成 `IF(...<=3,1,0)` 输出数值即可」）。
+
+**公式层无解的需求**：遇到下列需求**不要硬写公式**，直接引导到替代方案——
+
+| 需求 | 替代方案 |
+|------|---------|
+| last value（取关联字段，如"最近一次购买的商品名"） | 组件层"末行"汇总（基于日期排序）/ 自助数据集 ETL |
+| Top N 过滤（只显示前 N 名） | 组件 Top N，或先写排名再用组件条件过滤；公式本身只返回值，不隐藏行 |
+| 跨表关联 / 多源 join | 数据集层联表 / ETL |
+
+### 生成流程
+
+1. **确定引擎并查询目标主题**：先确认目标主题是自助分析（Spider / Direct）还是标准分析，参考 [引擎差异速查](formula-contexts.md#引擎差异速查) 选择候选函数；再按公式 Skill 的「目标主题查询」要求获取当前实例面板，核对主题和 profile。下面的函数族和模板只在目标主题支持时使用。
+2. **确认分析区域**：了解公式所在组件已放置了哪些维度/指标（行/列维度）。这决定聚合范围、表格计算的"组"、以及 `DEF_ADD`/`DEF_SUB` 的"分析区域已有维度"。
+3. **判断需求类型**：需求落在"需求 → 函数族对照"的哪一类，选对应函数族。
+4. **拼公式**：字段统一使用已有字段名 `${字段名}`，字符串常量双引号，函数名大写。
+5. **生成 Model JavaScript 引用**：调用 `calculated-field validate/add/update` 时，扫描最终公式并按 `context` 目录来源为每个出现位置生成 `.reference(...)`、`.modelReference(...)` 或 `.parameterReference(name, position)`；参数名称取 `availableReferences.parameters`，不声明来源表。同一份 JavaScript 先校验再写入。
+6. **自检**：按"公式合法性约束清单"逐条核对；Model DSL 另外检查 `formula` 与引用声明的位置、字段名，以及来源表或模型名完全一致。
+
+### 选型优先级（生成公式时的决策顺序）
+
+生成公式时，按下面的顺序决策（自上而下优先满足；前一条不满足则不能进入下一条）：
+
+| 优先级 | 原则 | 说明 |
+|--------|------|------|
+| 1 | **合法性** | 先保证公式合法（见"公式合法性约束清单"）：聚合不嵌套、聚合与非聚合不混用（按节点边界判）、分析函数嵌套限制（同级可共存、嵌套受限，见"嵌套与共存规则"）等。不合法直接排除该写法。 |
+| 2 | **目标环境支持** | 按主题类型、引擎、数据库和面板选择；同名函数仍可能存在重载和语义差异。自助主题按面板选 DEF/WINDOW；标准主题跨粒度选 LOD。标准主题无法表达的跨行需求先由数据层提供结果，不把 LOD 当通用窗口替代。 |
+| 3 | **动态指标统一表达** | 涉及"在分析区基础上增/减维度"时，优先写 `DEF(指标, [ADD_DIM(维度)])` / `DEF(指标, [SUB_DIM(维度)])`；`DEF_ADD` / `DEF_SUB` 是等价的快捷写法。统一用 `ADD_DIM` / `SUB_DIM` 的好处：同一维度集可直接复用于 `FIELD_IN` 判断、`WINDOW` 分组、`EARLIER` 组内累计，写法一致。 |
+| 4 | **计算成本** | 同等语义下优先能预计算/明细级计算的表达式（普通函数、简单聚合组合），避免不必要的运行时计算（`DEF`/LOD/`WINDOW_`、表格计算、`FIELD_IN` 都会引入额外计算成本）。 |
+| 5 | **简洁优先** | 在满足以上优先级的前提下，选最短、最直白、嵌套最少的写法；不为炫技引入不必要函数。 |
+
+> 前 4 条是硬规则、顺序不可颠倒；第 5 条是兜底偏好，不覆盖第 3 条——动态指标统一写 `ADD_DIM` / `SUB_DIM`，即使 `DEF_ADD` 更短。
+
+### 需求 → 函数族对照
+
+| 需求意图 | 首选函数 | 备注 |
+|---------|---------|------|
+| 求和 / 平均 / 计数 / 去重计数 / 最值 / 中位数 / 分位数 / 标准差 / 方差 | `SUM_AGG` / `AVG_AGG` / `COUNT_AGG` / `COUNTD_AGG` / `MAX_AGG` / `MIN_AGG` / `MEDIAN_AGG` / `PERCENTILE_AGG` / `STDEV_AGG` / `VAR_AGG` | 直接聚合 |
+| 占比 / 构成比 | 值 / `TOTAL(值, 0, "sum")` | 分母为整体合计 |
+| 同比 / 环比 | `SAME_PERIOD(值, "Y"/"M")`、`PREVIOUS_PERIOD(值)` | 需相关时间维度在行/列 |
+| 上期期末值 | `PERIOD_ANLS(值, "Y"/"M")` | 表格计算 |
+| 累计（运行合计） | `ACC_SUM(值, 0/1)` | 0 全表、1 组内 |
+| 排名 | `RANK_ANLS(值, 0/1, "asc"/"desc")`；按维度分区排名用 `RANK_AGG([分组], [排序字段, 方式], 模式)` | 前者表格计算、后者窗口排名 |
+| 条件统计 | `SUM_AGG(IF(条件, 1, 0))`、`SUM_AGG(IF(条件, ${指标}, 0))` | 聚合内用 IF |
+| 复合指标（连乘 / 几何均值） | `EXP(TOTAL(LN(${x}), 1, "sum"))` | `${x}` 须为聚合结果 |
+| 静态指标（无视分析维度） | `DEF(值, [维度], [过滤])` 或 `{FIXED 维度: 聚合}`（仅直连标准版） | 只按声明维度聚合 |
+| 动态指标（增 / 减维度） | 优先 `DEF(值, [ADD_DIM(维度)])` / `DEF(值, [SUB_DIM(维度)])`；等价快捷写法 `DEF_ADD(值, [维度], [])` / `DEF_SUB(值, [维度], [])`；直连标准版另有 `{INCLUDE ...}` / `{EXCLUDE ...}` | 在分析区域维度基础上增减 |
+| 窗口聚合（分区排序后的移动 / 累计） | `WINDOW_SUM` / `WINDOW_AVG` 等 | 窗口函数 |
+| 判断 / 过滤 / 分类 / 空值处理 | `IF` / `SWITCH` / `IN` / `AND` / `OR` / `NOT` / `ISNULL` / `NVL` / `IFERROR` | 逻辑函数 |
+| 文本处理 | `CONCATENATE` / `LEFT` / `RIGHT` / `MID` / `LEN` / `REPLACE` / `SUBSTITUTE` / `FIND` / `REGEXP` 等 | 文本函数 |
+| 日期处理 | `DATE` / `YEAR` / `MONTH` / `DAY` / `DATEDIF` / `DATEDELTA` / `TODATE` 等 | 日期函数 |
+
+> 上表中的"值"指聚合表达式（如 `SUM_AGG(${销售额})`）。凡表格计算/分析函数的指标参数，都必须先聚合。
+
+### 常用公式模板
+
+| 需求 | 模板 |
+|------|------|
+| 占比 | `SUM_AGG(${销售额}) / TOTAL(SUM_AGG(${销售额}), 0, "sum")` |
+| 同比 | `SUM_AGG(${销售额}) / SAME_PERIOD(SUM_AGG(${销售额}), "Y") - 1` |
+| 环比 | `SUM_AGG(${销售额}) / PREVIOUS_PERIOD(SUM_AGG(${销售额})) - 1` |
+| 累计 | `ACC_SUM(SUM_AGG(${销售额}), 0)` |
+| 组内累计 | `ACC_SUM(SUM_AGG(${销售额}), 1)` |
+| 全表排名 | `RANK_ANLS(SUM_AGG(${销售额}), 0, "desc")` |
+| 组内排名 | `RANK_ANLS(SUM_AGG(${销售额}), 1, "desc")` |
+| 按部门分组的销售额排名 | `RANK_AGG([${部门}], [SUM_AGG(${销售额}), "desc"])` |
+| 条件计数 | `SUM_AGG(IF(${销售额} > 10000, 1, 0))` |
+| 条件求和 | `SUM_AGG(IF(${地区} = "华东", ${销售额}, 0))` |
+| 复合指标连乘 | `EXP(TOTAL(LN(${良品率}), 1, "sum"))` |
+| 去重客户数 | `COUNTD_AGG(${客户ID})` |
+| 静态指标（总销售额，无视分析维度） | 自助主题：`DEF(SUM_AGG(${销售额}), [], [])`；标准主题：`{FIXED : SUM_AGG(${销售额})}`；均需目标主题原生校验 |
+| 空值兜底 | `NVL(${销售额}, 0)`、`IF(ISNULL(${销售额}), 0, ${销售额})` |
+| 除零保护 | `IFERROR(${销售额} / ${成本}, 0)` |
+| 字段拼接 | `CONCATENATE(${省份}, ${城市})` |
+| 时间段判断 | `${日期} >= TODATE("2024-01-01") && ${日期} < TODATE("2024-02-01")` |
+
+### 生成后自检清单
+
+1. 字段引用用 `${字段名}`，与数据集/组件实际字段名一致（区分大小写）。
+2. 字符串常量一律双引号。
+3. 聚合函数参数是明细级表达式，无聚合嵌套。
+4. 表格计算指标参数先聚合；嵌套快速计算按目标面板及原生校验判断，不能仅以“常量”绕过指标要求。
+5. 未混用窗口函数与表格计算；分析函数若嵌套，符合"嵌套与共存规则"（同级兄弟节点可共存，但 DEF 家族维度区禁含 DEF_ADD/DEF_SUB、LOD 维度区禁含 INCLUDE/EXCLUDE 等）。
+6. 未使用中缀 SQL 关键字（AND/OR/IN/LIKE/BETWEEN/IS NULL）。
+7. 判断结果用于数值计数时显式 `IF(条件,1,0)`。
+8. 日期与字符串比较前先 `TODATE`。
+9. 目标引擎支持所用函数（无 Spider/Direct 独有函数错用、无 LOD 用于非直连标准版）。
+10. 已按"选型优先级"决策：优先双引擎通用函数、动态指标统一用 `ADD_DIM` / `SUB_DIM`、无多余的运行时分析函数。
+
+实际交付还需说明公式位置、分组/排序、缺失值策略和验证状态。清洗与日期例题见 [文本日期模板](formula-recipes-text-date.md)，官方业务案例见 [分析模板](formula-recipes-analysis.md)；不要把语法校验通过写成业务结果已验证。
+
+---

package/skills/finebi-cli-agent/references/formula-glossary.md

@@ -0,0 +1,17 @@
+## 八、术语表
+
+| 术语 | 定义 |
+|------|------|
+| 明细 | 未聚合的原始数据行 |
+| 聚合函数 | `XXX_AGG` 系列，按分析维度对明细聚合，每个维度组输出一行 |
+| 非聚合函数 | 普通函数（数学/文本/日期/逻辑），按明细行计算，不改变行数 |
+| 常量类 | 字面量、`TRUE/FALSE/NULL`、组件参数、常量字段、`FIELD_IN`，可跨界混用 |
+| 表格计算 | `TOTAL`/`ACC_SUM`/`RANK_ANLS` 等，在聚合结果之上按行/组计算 |
+| 窗口函数 | `WINDOW_` 系列 / `RANK_AGG`，按分组字段分区、排序字段排序后聚合，独立聚合范围 |
+| 分析函数 | DEF 家族 / LOD / WINDOW 家族的统称，各自形成独立的聚合范围 |
+| 引用函数 | `ADD_DIM` / `SUB_DIM` / `FIELD_IN`，动态引入/判断分析视图字段 |
+| 自定义函数 | 以 `@函数名(...)` 语法调用的自定义函数 |
+| 聚合范围 | 一次聚合的粒度定义（按哪些维度分组）。分析函数同级可多个共存，嵌套受限（见"嵌套与共存规则"） |
+| 分析区域 | 组件中已放置的维度/指标，决定表格计算的分组、以及 `DEF_ADD`/`DEF_SUB` 的"已有维度" |
+| 预计算 / 运行时 | 简单聚合 + 普通函数可预计算；DEF/LOD/WINDOW、表格计算、`FIELD_IN` 等需运行时计算 |
+| 分析视图 | 组件承载数据/维度/指标的视图结构 |

package/skills/finebi-cli-agent/references/formula-help-boundaries.md

@@ -0,0 +1,87 @@
+# 官方函数使用边界
+
+用于把 [函数库](formula-functions.md) 中的候选表达式放到正确位置。本文按官方单函数页提炼；逐篇链接见 [来源索引](formula-help-index.md)。帮助页中的「实时数据」按直连理解，但主题类型与数据库能力仍须单独确认。
+
+## 1. 位置、主题和版本
+
+| 位置或主题 | 选型约束 |
+|---|---|
+| 自助数据集新增公式列 | 输出明细级字段；聚合函数不能直接输出。按固定维度计算用 DEF；窗口或排名放在 DEF 指标位，并给 DEF 提供完整视图维度 |
+| 组件明细表 | 不直接输出聚合、WINDOW 或快速计算；需要明细结果时检查 DEF 包裹后的粒度 |
+| 组件分组表、交叉表、图表 | 聚合随分析区维度变化；WINDOW 的维度须存在于分析视图；快速计算依赖行列布局和日期分组 |
+| 自助分析主题 | 官方 DEF、EARLIER、CLEAN 和 WINDOW 页面限定该主题；直连数据还需核对数据库 |
+| 标准分析主题 | 使用 `{FIXED ... : ...}`、`{INCLUDE ... : ...}`、`{EXCLUDE ... : ...}`；不因底层都是 Direct 就沿用自助主题 DEF 写法 |
+| 指标中心、组件的动态维度引用 | ADD_DIM / SUB_DIM / FIELD_IN；官方排除明细表；不能把字段声明数组当普通标量输出 |
+
+分析区维度包括图表属性中的维度；官方 DEF 概述说明已拖入但隐藏的字段不参与计算。组件合计行有自己的视图，不能假定它等于可见行相加。
+
+版本定位（只用于排查旧实例，不代替能力查询）：IN / NOT 为 6.0.9；多条件 IF / IFERROR 为 6.0.16；CLEAN / CLEAN_WIDGET 为 6.1；WINDOW / RANK_AGG 为 6.1.2；PERCENTILE_AGG 的抽取支持为 6.1.4；ADD_DIM / SUB_DIM / FIELD_IN 为 7.0。多条件 IF 最多 200 个条件，嵌套限制还受服务器配置控制。
+
+## 2. 数据库与标量函数限制
+
+| 函数或场景 | 写公式前检查 |
+|---|---|
+| MEDIAN_AGG | 数值参数、组件中使用；官方明确 MySQL 不支持 |
+| PERCENTILE_AGG | 第二参为 [0,1] 内数值常量；直连列举 Sybase IQ、Oracle、PostgreSQL 9.4+、ClickHouse、Greenplum、Transwarp Inceptor、Redshift、MaxCompute、Teradata、Hologres、DB2 11.1+、Hive、GaussDB(DWS) 8.1.1+、Dremio；Hive / MaxCompute 只对整数计算；Redshift 同时做有序聚合时要求同一字段 |
+| APPROX_COUNTD_AGG | 官方列举 ClickHouse、Oracle 12.1.0.2+、SQL Server 2019+、Presto、Redshift、Vertica；Redshift 多字段有序聚合受限；Vertica 不可同时精确去重与近似去重 |
+| WINDOW / RANK_AGG | 官方提示部分直连数据库不支持，列举 MySQL、ClickHouse；不同版本须查目标面板和原生校验 |
+| FORMAT | 抽取首参可为日期、数值等；直连首参只支持日期；Kyligence 企业版不支持。格式结果是文本，后续数值计算在 FORMAT 前完成 |
+| REGEXP | 抽取支持 2/3 参；直连只给出 2 参，SAP Sybase、Microsoft SQL Server 不支持；第三参不是通用数据库能力 |
+| FIND | 1 起始、未找到为 0，区分大小写；直连建议显式写第三参 1；它与 0 起始取字符的 INDEXOF 不可互换 |
+| LEN / INDEXOF / SPLIT | LEN 计字符（含空格），抽取还支持数组长度；INDEXOF 取指定位置，支持数组；SPLIT 为抽取函数，分隔符按普通文本处理，不能直接写正则分割 |
+| LEFT / RIGHT / MID | LEFT/RIGHT 长度省略默认 1、不能为负、超长取全文；MID 起点从 1 开始，超出末尾得空串，截取长度超出则取到末尾，起点小于 1 或负长度报错 |
+| MAX / MIN | 比较同一行参数，不做跨行汇总；抽取为非零个数值参数，直连要求非零个同类型参数 |
+| LN / LOG / LOG10 / FACT | 对数真数要求正数；FACT 输入非负，非整数截尾且只用于抽取；精度舍入用 ROUND/TRUNC，不依赖 TODOUBLE 的页面展示小数位 |
+| IF / SWITCH / NVL / IFERROR | 结果参数保持同类型；IF 混合文本与数字可能转文本，不能用“报错”字符串作为数值指标默认值；SWITCH 直连要求结果同类型；IFERROR 不兜空值 |
+
+REGEXP 抽取第三参模式可相加：1 UNIX_LINES、2 忽略大小写、4 注释、8 多行、16 字面量、32 DOTALL、64 Unicode 大小写、128 规范等效。64 要与 2 配合才启用 Unicode 的大小写折叠。公式字符串里的反斜杠需要再转义一层，例如 `REGEXP(${编码}, "\\d+")`；放入 JavaScript 字符串时还需按 JS 字符串规则转义。纯数字场景可用 `REGEXP(${编码}, "^[0-9]+$")`，其中 `+` 要求至少一个字符。
+
+上述数据库清单是官方页面快照，不是未来版本的全量承诺。页面与实例面板不同，记录具体 profile 和版本，再以实际主题校验判断；不要扩写数据库白名单。
+
+## 3. 日期参数与时间口径
+
+| 需求 | 边界 |
+|---|---|
+| TODATE | 抽取支持单参（日期/数值/文本）、双文本参、三文本参（第三参 zh/en）；直连文档只支持单参和双文本参 |
+| YEAR / MONTH / DAY / QUARTER / HOUR / MINUTE / SECOND | 允许 0 参取服务器当前值；抽取支持额外格式参。直连优先用 0/1 参：部分页注意事项与签名对第二参描述不一致，先 TODATE 解析更明确 |
+| 日期系列数 | 多个抽取函数接受 1900 年系列数；直连通常只接受日期/文本。`TODATE(数值)` 则解释为 1970 年起的毫秒，不是 Excel 日期序号 |
+| 秒与毫秒 | 10 位秒时间戳先乘 1000；13 位毫秒直接 TODATE。DATETONUMBER 返回毫秒；显示的时区由目标环境决定 |
+| DATEDIF | `end-start`，Y/M 按年月差，不能直接当完整周岁/满月数；MD/YM/YD 忽略相应部分。两日期类型保持一致；官方抽取页说明空日期会按 NOW 计算，需先判空 |
+| DATESUBDATE | `date1-date2`，与 DATEDIF 参数方向相反；M 是分钟，DATEDIF 的 M 是月 |
+| WEEK | F1/F7 决定第一周定义，不决定周一还是周日开周；检查平台「周开始于」。直连不默认支持第二参 |
+| 日期格式 | 使用 `yyyy-MM-dd HH:mm:ss`；M 是月、m 是分钟，d 是日。避免从示例大写 YYYY 推导跨年日期规则 |
+| 空值 | 对日期偏移、差值和转换先判空，避免误算为当前日期或纪元日期 |
+
+`DAYSOFYEAR` 直连文档要求日期/文本参数，抽取可用年份数值；`DATE`、`TIME`、`WEEKDATE` 直连要求数值参数。DATE 的月日进位以抽取说明为依据，不默认移植到直连数据库。
+
+## 4. DEF 与过滤范围
+
+DEF 的指定维度决定粒度；DEF_ADD/DEF_SUB 从分析区增减维度，不支持作为维度输出，官方单函数页排除明细表和数据集。数据集的固定粒度分析用 DEF。过滤数组内各条件按且执行；过滤条件不能直接是聚合函数，可以引用已形成明细性质的 DEF 结果。
+
+| 写法 | 可忽略的范围 | 保留的限制 |
+|---|---|---|
+| `CLEAN(${城市})` | 当前 DEF 的城市字段组件过滤、钻取及普通仪表板过滤组件过滤 | 字段形式不清联动/跳转，不含树类和复合过滤组件 |
+| `CLEAN("ALL")` | 当前 DEF 中界面字段过滤，包括联动、跳转、钻取、过滤组件 | 不清仪表板/组件之外的权限过滤、定时调度过滤 |
+| `CLEAN_WIDGET(${城市})` / `CLEAN_WIDGET("ALL")` | 组件内过滤器和钻取的相应过滤 | 仪表板过滤组件、联动和跳转继续有效 |
+
+CLEAN/CLEAN_WIDGET 参数不可空，仅作为 DEF 家族过滤数组里的独立条件。同层显式条件仍执行；不清内层/外层 DEF 自己声明的条件。例如：
+
+```text
+DEF(SUM_AGG(${销售额}), [], [CLEAN(${月份}), ${月份}=7])
+```
+
+含义是忽略界面对月份的过滤，再按本层 `月份=7` 计算；不保证突破数据权限拿到所有历史记录。
+
+DEF 结果常以维度匹配回原视图。同一个按客户计算的值在多条订单上可重复出现，后续用 AVG/SUM/COUNTD 前先确认业务粒度。深层 DEF 和数据编辑中穿插改变行数/顺序的步骤会增加查询复杂度；在不改变结果的前提下减少依赖层数、合并同粒度计算。默认单公式 DEF 嵌套限制在官方使用须知中为 4，实际以管理员配置为准；不要为生成公式自动调整系统参数。
+
+## 5. 窗口、快速计算与引用维度
+
+WINDOW 的指标必填；分组、排序、窗口可省略，生成时为顺序敏感计算显式指定排序。窗口偏移按结果行数计算，不按日历天数；缺月、重复日期、并列排序都须先处理或明确口径。`[-2,0]` 包含当前行，`[-3,-1]` 排除当前行。分区前两行可能不足完整窗口。
+
+同一日期字段重复拖入分析区并设置年/月分组时，WINDOW 会带入该字段的所有分组；按年分区、月排序应准备两个不同字段。排名要求同分可复现时，用业务上稳定的第二排序键；只按金额的 UNIQUE 不保证同金额记录的固定先后。
+
+快速计算中 range 的 0/1 分别为全表/组内，group 来自组件布局。PREVIOUS_PERIOD 支持年、年季度、年月日、年月、年周数；SAME_PERIOD/PERIOD_ANLS 官方列出年季度、年月日、年月、年周数。`datepart` 为 Y/M/W，PERIOD_ANLS 不支持 Q。RANK_ANLS 的范围和顺序应为常量，不放 IF/SWITCH 动态表达式。原生校验通过后，还需检查目标组件时间维度是否满足要求。
+
+ADD_DIM/SUB_DIM 在 DEF 维度位引用外部视图，在 WINDOW 等其他场景引用当前视图；外层再包 DEF 时，“外部视图”会改变。ADD_DIM() 是全部视图维度，不是无分组；要累计时间序列，通常从分组里减去时间维度。FIELD_IN 的参数是字段声明集合，按字段 ID 匹配，忽略顺序，不是 IN 的数据值集合。引用函数不可放入 DEF_ADD/DEF_SUB 的维度参数。
+
+LOD 的 INCLUDE/EXCLUDE 空维度表示不增加/不排除任何视图维度；只有 FIXED 空维度固定为全局聚合。LOD 不是日历错位或窗口的通用替代品，无法表达的标准主题需求应先在数据层提供结果。