@finebi/finebi-cli 1.2.1 → 1.4.0

package/skills/finebi-cli-agent/references/formula-parameters-math-logic.md

@@ -0,0 +1,271 @@
+# 数值与逻辑函数参数详解
+
+每节链接对应官方单函数页。未标为可选的参数按完整签名提供；原文未说明的默认值与隐式转换不作保证。数值函数按行处理，跨记录统计另查 [聚合与表格计算参数](formula-parameters-aggregate.md)。
+
+## 1. 取整、绝对值与比较
+
+### ABS
+
+`ABS(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1378.html)
+
+- `number`：必需的单个数值，任意实数；返回非负绝对值，不接受额外参数。
+
+### INT
+
+`INT(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1380.html)
+
+- `number`：一个待取整实数。抽取允许数值/文本，**沿数值减小方向**取整，`INT(-4.8)=-5`；直连要求数值，**向 0** 取整，`INT(-4.8)=-4`。
+
+### CEILING
+
+`CEILING(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1438.html)
+
+- `number`：一个待舍入数值。抽取沿**绝对值增大**方向取整，-2.5 → -3；直连沿**数值增大**方向取整，-2.5 → -2。没有 Excel 的第二个倍数参数。
+
+### FLOOR
+
+`FLOOR(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1429.html)
+
+- `number`：一个待舍入数值。抽取沿**绝对值减小**方向取整，-2.5 → -2；直连沿**数值减小**方向取整，-2.5 → -3。没有第二个精度参数。
+
+### ROUND
+
+`ROUND(number, num_digits)` · [原文](https://help.fanruan.com/finebi/doc-view-1379.html)
+
+- `number`：数值，要舍入的数字。
+- `num_digits`：数值，舍入位数；大于 0 保留相应小数位，0 舍入到整数，小于 0 在小数点左侧舍入。原文未声明可省略，生成时显式提供。
+- 通常按四舍五入；浮点精度异常时原文提到 `old_round`，但没有完整独立参数契约，使用前查询目标面板，不直接假设所有实例均支持。
+
+### TRUNC
+
+`TRUNC(number[, num_digits])` · [原文](https://help.fanruan.com/finebi/doc-view-1433.html)
+
+- `number`：数值，要截尾的数字。
+- `num_digits`：可省略数值，截尾精度；省略时保留整数。原文明确正小数位示例 `TRUNC(-8.98,1)=-8.9`，未细述负精度边界。
+- 不四舍五入，`TRUNC(-8.9)=-8`。
+
+### SIGN
+
+`SIGN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1437.html)
+
+- `number`：一个任意实数；正数返回 1，0 返回 0，负数返回 -1。
+
+### MAX
+
+`MAX(number1, number2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1431.html)
+
+- `number1, number2, ...`：至少一个被比较值。抽取要求数值；直连要求所有参数类型相同。返回这组参数中的最大值，不是对当前分组所有记录聚合。
+
+### MIN
+
+`MIN(number1, number2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1432.html)
+
+- `number1, number2, ...`：至少一个被比较值。抽取要求数值；直连要求所有参数类型相同。返回参数列表中的最小值；跨记录取最小值使用 MIN_AGG。
+
+## 2. 幂、对数、余数和比例
+
+### SQRT
+
+`SQRT(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1427.html)
+
+- `number`：一个非负数值；负数按原文返回空值。返回算术平方根。
+
+### POWER
+
+`POWER(number, power)` · [原文](https://help.fanruan.com/finebi/doc-view-1449.html)
+
+- `number`：数值底数，可为实数。
+- `power`：数值指数；底数为负时必须为整数，否则报错。可用 `number^power` 表达相同乘幂。
+
+### EXP
+
+`EXP(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1441.html)
+
+- `number`：一个任意实数，作为常数 e 的指数；不是自定义底数。自定义底数使用 POWER。
+
+### LN
+
+`LN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1436.html)
+
+- `number`：一个**正实数**，返回以 e 为底的自然对数；底数无需且不能另传。
+
+### LOG10
+
+`LOG10(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1428.html)
+
+- `number`：一个**正实数**，返回以 10 为底的对数；只有一个参数。
+
+### LOG
+
+`LOG(number[, base])` · [原文](https://help.fanruan.com/finebi/doc-view-1430.html)
+
+- `number`：数值，待求对数的正实数。
+- `base`：数值底数，可省略，**默认 10**。有效实数对数要求底数大于 0 且不为 1；原文未说明无效底数时具体返回空值还是报错。
+
+### MOD
+
+`MOD(number, divisor)` · [原文](https://help.fanruan.com/finebi/doc-view-1439.html)
+
+- `number`：数值，被除数。
+- `divisor`：数值，除数；原文描述除数为 0 时余数无穷大，业务公式应先拦截零除数。
+- 抽取余数符号与**除数**相同，`MOD(-3,2)=1`；直连与**被除数**相同，`MOD(-3,2)=-1`。两个参数都需提供。
+
+### PROMOTION
+
+`PROMOTION(value1, value2)` · [原文](https://help.fanruan.com/finebi/doc-view-1440.html)
+
+- `value1`：数值，提升比例的**基期值**，可为负。
+- `value2`：数值，对比的新值。
+- 结果为 `(value2-value1)/ABS(value1)`；参数顺序不能颠倒。零基数结果原文未细述，业务须指定处理口径。
+
+### FACT
+
+`FACT(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1434.html)
+
+- `number`：一个非负数值；非整数先截尾取整，再求阶乘，`FACT(1.9)=1`，`FACT(0)=1`。实时/直连不支持。
+
+## 3. 三角、角度和随机数
+
+### PI
+
+`PI([number])` · [原文](https://help.fanruan.com/finebi/doc-view-1448.html)
+
+- `number`：可省略的数值，原文含义为 π 的**整数倍数**；无参返回 π，`PI(3)` 返回其三倍。文档显示 3.14/9.42 是展示值，不代表只保留两位精度。
+
+### SIN
+
+`SIN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1451.html)
+
+- `number`：一个数值角度，单位为**弧度**；若输入是度数，先乘 `PI()/180`。返回正弦值。
+
+### COS
+
+`COS(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1446.html)
+
+- `number`：一个以**弧度**表示的数值角度；度数需先转换。返回余弦值。
+
+### TAN
+
+`TAN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1452.html)
+
+- `number`：一个以**弧度**表示的数值角度；度数需先转换。返回正切值，原文未规定奇点的返回行为。
+
+### ASIN
+
+`ASIN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1443.html)
+
+- `number`：目标角度的正弦值，数值范围 **[-1,1]**；返回 [-π/2,π/2] 内的弧度，包含端点。不是把度数作为输入。
+
+### ACOS
+
+`ACOS(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1442.html)
+
+- `number`：目标角度的余弦值，数值范围 **[-1,1]**；返回 [0,π] 内的弧度。
+
+### ATAN
+
+`ATAN(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1444.html)
+
+- `number`：目标角度的正切值，一个数值；返回 (-π/2,π/2) 内的弧度，不包含端点。
+
+### ATAN2
+
+`ATAN2(x_num, y_num)` · [原文](https://help.fanruan.com/finebi/doc-view-1445.html)
+
+- `x_num`：数值，点的 **x 坐标**，在第一个位置。
+- `y_num`：数值，点的 **y 坐标**，在第二个位置。两者同时为 0 报除零错误。
+- 返回从 x 轴到该点方向的弧度，范围 (-π,π]；逆时针为正、顺时针为负。注意不能套用其他语言的 `atan2(y,x)` 顺序。
+
+### DEGREES
+
+`DEGREES(angle)` · [原文](https://help.fanruan.com/finebi/doc-view-1447.html)
+
+- `angle`：一个**弧度**数值，返回角度制数值。
+
+### RADIANS
+
+`RADIANS(angle)` · [原文](https://help.fanruan.com/finebi/doc-view-1450.html)
+
+- `angle`：一个**度数**数值，返回弧度；与 DEGREES 转换方向相反。
+
+### RAND
+
+`RAND()` · [原文](https://help.fanruan.com/finebi/doc-view-1426.html)
+
+无参数，返回 [0,1) 的均匀随机数，每次计算可变化；没有种子或上限参数。区间变换用 `RAND()*(b-a)+a`。
+
+### RANDBETWEEN
+
+`RANDBETWEEN(value1, value2)` · [原文](https://help.fanruan.com/finebi/doc-view-1435.html)
+
+- `value1`：第一个数值端点。
+- `value2`：第二个数值端点。返回两值之间的随机整数；整数部分相同时返回该整数部分，如 12.333、12.233 → 12。
+- 原文没有完整定义倒序端点、负数端点和边界包含规则；不要把其他产品的端点规则当成已证实行为。没有第三个种子参数。
+
+## 4. 条件与空值
+
+### IF
+
+`IF(condition1, result1, condition2, result2, ..., other_result)`，单条件形式 `IF(condition, true_result, false_result)` · [原文](https://help.fanruan.com/finebi/doc-view-1377.html)
+
+- `condition1, condition2, ...`：布尔或数值条件，推荐显式比较/逻辑结果或 0/1；按顺序匹配，第一个满足的分支获胜。
+- `result1, result2, ...`：对应条件成立时返回的值，所有结果保持同类型。原文旧三参说明提到混合类型可能变文本，不以此生成隐式类型混合。
+- `other_result`：所有条件不满足时的返回值；官方该页未明确省略后的结果，生成时显式提供业务兜底值。
+- 6.0.16 增强多条件形式；最多 200 个条件。更早版本按三参 IF 嵌套。字段若经过“指标条件”，普通 IF 使用受限，不能忽略聚合性质。
+
+### SWITCH
+
+`SWITCH(expression, value1, result1, value2, result2, ...[, other_result])` · [原文](https://help.fanruan.com/finebi/doc-view-360.html)
+
+- `expression`：被判断的表达式。
+- `value1, value2, ...`：与 expression **按值相等匹配**的候选值；每个值后必须跟对应结果。日期匹配值用 `TODATE(...)` 等日期类型表达式，不拿日期值与裸文本混比。
+- `result1, result2, ...`：对应候选值的返回结果，类型保持一致。
+- `other_result`：可省略；没有匹配且省略时返回 NULL。它是末尾参数，不写 `else` 关键字。
+- 至少 3 个参数（表达式、一个候选值、一个结果），区间条件选 IF。
+
+### AND
+
+`AND(logical1, logical2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1383.html)
+
+- 每个 `logical`：布尔或数值条件；全部真返回 1，任意假返回 0。可传多个条件；原文未规定空参结果，不生成 `AND()`。
+
+### OR
+
+`OR(logical1, logical2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1384.html)
+
+- 每个 `logical`：布尔或数值条件；任意真返回 1，全部假返回 0。原文未规定空参结果，不生成 `OR()`。
+
+### NOT
+
+`NOT(condition)` · [原文](https://help.fanruan.com/finebi/doc-view-2189.html)
+
+- `condition`：必需的单个布尔或数值条件；返回其逻辑反值。可组合 `NOT(IN(...))`；自 6.0.9 提供。
+
+### IN
+
+`IN(exp, para1, para2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-2188.html)
+
+- `exp`：待检查的单值表达式，任意类型但不能为 NULL；若是组件参数，不能为多值参数。
+- `para1, para2, ...`：候选集合，由常量、常量表达式或组件参数组成；多个候选依次作为参数列出，不无依据改成一个普通数组参数。
+- 全部参数类型保持一致。多值组件参数可用于候选侧；exp 属于候选集合返回 1，否则 0。自 6.0.9 提供。
+
+### ISNULL
+
+`ISNULL(object)`（直连）；`ISNULL(object1, object2, ...)`（抽取）· [原文](https://help.fanruan.com/finebi/doc-view-1478.html)
+
+- `object`：任意类型待检查值。直连只允许一个；抽取允许多个，**所有值均为 NULL 或空字符串**才返回 1，否则 0。不要把空格字符串、0 或 FALSE 自动视作空。
+
+### NVL
+
+`NVL(value1, value2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1479.html)
+
+- `value1, value2, ...`：至少一个参数，按顺序选第一个非 NULL、非空字符串值；所有值类型统一，可包含 NULL。
+- 全为空返回 NULL；默认值也是显式参数，如 `NVL(${金额},0)`，函数没有隐含 0 默认值。
+
+### IFERROR
+
+`IFERROR(value1, value2)` · [原文](https://help.fanruan.com/finebi/doc-view-2324.html)
+
+- `value1`：被检查的表达式；异常值指正无穷、负无穷和 NaN，**不包含空值**。
+- `value2`：value1 为异常值时的替代值，与 value1 字段类型相同；否则返回 value1。两参均需提供。
+- 自 6.0.16 提供；不承担语法错误恢复，也不能替代 NVL 判空。

package/skills/finebi-cli-agent/references/formula-parameters-text.md

@@ -0,0 +1,217 @@
+# 文本函数参数详解
+
+本册按官方单函数页逐项解释参数；函数用途和示例见 [函数库](formula-functions.md)，数据库总限制见 [使用边界](formula-help-boundaries.md)。签名中的 `[, x]` 表示可省略尾参，省略不等于传 `NULL`。未明确标为可省略的参数按完整签名提供；原文未声明的默认值、越界结果和隐式转换不作保证。
+
+## 1. 大小写与清洗
+
+### UPPER
+
+`UPPER(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1464.html)
+
+- `text`：一个文本参数，要转换成大写的文本或文本字段；返回转换后的文本。
+
+### LOWER
+
+`LOWER(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1471.html)
+
+- `text`：一个文本参数，要转换成小写的文本或文本字段；非字母字符不变。
+
+### PROPER
+
+`PROPER(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1475.html)
+
+- `text`：一个文本参数，可为文本公式或双引号字符串。首字母及每个非字母字符后的首字母大写，其余字母小写。直连不支持。
+
+### TRIM
+
+`TRIM(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1453.html)
+
+- `text`：一个文本参数，清除其首尾所有空格；不是删除文本内部所有空格。
+
+## 2. 截取、查找与拆分
+
+### LEFT
+
+`LEFT(text[, num_chars])` · [原文](https://help.fanruan.com/finebi/doc-view-1457.html)
+
+- `text`：待截取对象，原文允许任意类型；按文本左端截取。
+- `num_chars`：数值，返回的字符个数，必须 ≥ 0；省略默认 1，超过文本长度返回全文。
+
+### RIGHT
+
+`RIGHT(text[, num_chars])` · [原文](https://help.fanruan.com/finebi/doc-view-1465.html)
+
+- `text`：待截取对象，原文允许任意类型；按文本右端截取。
+- `num_chars`：数值，返回的字符个数，必须 ≥ 0；省略默认 1，超过文本长度返回全文。
+
+### MID
+
+`MID(text, start_num, num_chars)` · [原文](https://help.fanruan.com/finebi/doc-view-1459.html)
+
+- `text`：待截取对象，原文允许任意类型。
+- `start_num`：数值，起始字符位置，**从 1 开始**；小于 1 报错，大于文本长度返回空文本。
+- `num_chars`：数值，返回字符个数；负数报错。剩余字符不足时返回从起点到末尾的文本。
+
+### LEN
+
+`LEN(args)` · [原文](https://help.fanruan.com/finebi/doc-view-1472.html)
+
+- `args`：单个待计数对象。文本输入返回字符数，空格也计数；抽取还允许数组并返回数组元素数。直连页只说明单个文本输入，不能将数组重载推广到直连。
+
+### FIND
+
+`FIND(find_text, within_text[, start_num])` · [原文](https://help.fanruan.com/finebi/doc-view-1468.html)
+
+- `find_text`：要查找的子串；原文允许任意类型。
+- `within_text`：被搜索的完整文本；原文允许任意类型。
+- `start_num`：数值，从此位置开始查找，**位置从 1 开始**；省略默认 1。实时/直连写法应显式补 1，且不支持负值。
+- 返回首次命中的位置，未找到返回 **0**；参数顺序是“找什么、在哪找、从哪找”。
+
+### INDEXOF
+
+`INDEXOF(str1, index)` · [原文](https://help.fanruan.com/finebi/doc-view-1467.html)
+
+- `str1`：被读取对象，原文允许任意类型，示例覆盖字符串和数组。
+- `index`：数值，下标**从 0 开始**。文本输入取该位置的一个字符，返回文本；数组示例 `INDEXOF(["a","b","c"],1)` 取第二个元素 `"b"`。原文未规定越界结果。
+
+### SPLIT
+
+`SPLIT(string1, string2)` · [原文](https://help.fanruan.com/finebi/doc-view-1463.html)
+
+- `string1`：要拆分的字符串或字段；原文允许任意类型参数。
+- `string2`：分隔符，如 `","` 或 `"有限公司"`；原文允许任意类型，但公式中字符串分隔符用双引号。返回字符串数组，取某一段需再用 INDEXOF。
+- 直连不支持；原文明确 6.0 不支持把分隔符写成正则表达式，目标版本未确认前用字面分隔符。
+
+## 3. 替换、重复与拼接
+
+### REPLACE
+
+[原文](https://help.fanruan.com/finebi/doc-view-1469.html)给出两个独立重载，不能混用参数位置。
+
+`REPLACE(text, textorreplace, replacetext)`：
+
+- `text`：原始文本；任意类型参数。
+- `textorreplace`：要被替换的旧字符串；任意类型参数。
+- `replacetext`：用于替换的新文本；任意类型参数。原文未明确多次命中时的全部/首次规则，需要指定第几次时用 SUBSTITUTE。
+
+`REPLACE(old_text, start_num, num_chars, new_text)`：
+
+- `old_text`：原始文本；任意类型参数。
+- `start_num`：数值，开始替换的位置，按原文 `REPLACE("1980",3,2,"99")` 示例从 **1** 计数。
+- `num_chars`：数值，要被替换的旧字符个数，不是新文本的长度。
+- `new_text`：替换进去的文本；任意类型参数。四参均需提供，原文未声明位置越界行为。
+
+### SUBSTITUTE
+
+`SUBSTITUTE(text, old_text, new_text[, instance_num])` · [原文](https://help.fanruan.com/finebi/doc-view-1458.html)
+
+- `text`：原始文本；任意类型参数。
+- `old_text`：要查找并替换的旧文本；任意类型参数。
+- `new_text`：替换后的新文本；任意类型参数。
+- `instance_num`：可省略的数值，指定替换旧文本的**第几次出现**，按示例从 1 开始；不是字符位置。省略则替换全部出现。仅抽取支持。
+
+### REPEAT
+
+`REPEAT(text, number_times)` · [原文](https://help.fanruan.com/finebi/doc-view-1462.html)
+
+- `text`：要重复的文本，原文允许任意类型。
+- `number_times`：数值，重复次数；原文未规定负数或小数的处理，按业务使用非负整数。
+
+### CONCATENATE
+
+`CONCATENATE(text1, text2, ...)` · [原文](https://help.fanruan.com/finebi/doc-view-1470.html)
+
+- `text1, text2, ...`：按参数顺序合并的文本项，可传多个；文本常量加双引号，字段使用字段引用。
+- 原文未声明最少参数个数或省略默认值。直连拼接 NULL 的行为依数据库而异，业务需要空文本时先对相应参数使用 `NVL(字段, "")`。
+
+## 4. 比较与正则
+
+### STARTWITH
+
+`STARTWITH(str1, str2)` · [原文](https://help.fanruan.com/finebi/doc-view-1477.html)
+
+- `str1`：被检查的完整字符串。
+- `str2`：要匹配的开头字符串。原文允许两个任意类型参数；匹配区分大小写，返回逻辑结果。
+
+### ENDWITH
+
+`ENDWITH(str1, str2)` · [原文](https://help.fanruan.com/finebi/doc-view-1455.html)
+
+- `str1`：被检查的完整文本；虽然参数表允许任意类型，注意事项明确**不支持时间类型**，日期时间需先转换成文本。
+- `str2`：要匹配的结尾字符串。两者均区分大小写，返回逻辑结果。
+
+### EXACT
+
+`EXACT(text1, text2)` · [原文](https://help.fanruan.com/finebi/doc-view-1460.html)
+
+- `text1`：第一组比较文本，原文允许任意类型。
+- `text2`：第二组比较文本，原文允许任意类型。按内容完全相同判断，区分大小写、忽略格式差异；空格属于内容。
+
+### REGEXP
+
+`REGEXP(str, pattern[, intNumber])`（抽取）；`REGEXP(str, pattern)`（直连）· [原文](https://help.fanruan.com/finebi/doc-view-1476.html)
+
+- `str`：文本类型，待匹配字符串。
+- `pattern`：文本类型，正则表达式。公式字符串内反斜杠需转义，例如数字模式写为 `"\\d"`；嵌在 JS/JSON 中时还需处理外层字符串转义。
+- `intNumber`：抽取独有的数值模式参数；省略使用两参重载。模式可相加，如 `1+2=3` 同时启用 UNIX 行模式和忽略大小写。
+
+| 值 | 模式 | 对匹配的影响 |
+|---|---|---|
+| 1 | UNIX_LINES | 行结束符按 UNIX 行模式识别 |
+| 2 | CASE_INSENSITIVE | 忽略大小写；默认主要针对 US-ASCII，与 64 组合启用 Unicode 大小写匹配 |
+| 4 | COMMENTS | 忽略模式中的空白及以 `#` 开始到行末的注释 |
+| 8 | MULTILINE | 启用多行模式 |
+| 16 | LITERAL | 将模式按字面字符处理，元字符/转义不再具有正则意义；2、64 仍可影响大小写匹配 |
+| 32 | DOTALL | `.` 可匹配包括行结束符在内的字符 |
+| 64 | UNICODE_CASE | 与 2 合用，按 Unicode 规则忽略大小写 |
+| 128 | CANON_EQ | 按完整规范分解判断字符等效 |
+
+直连仅给出两参形式，SAP Sybase、Microsoft SQL Server 不支持此函数。
+
+## 5. 转换、编码与格式
+
+### TOINTEGER
+
+`TOINTEGER(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1461.html)
+
+- `text`：待转整数的单个参数，允许任意类型；示例 `1.1`、`1.9` 均转为 `1`。不能把“任意类型”理解为所有内容均可成功解析，非法文本结果原文未说明。
+
+### TODOUBLE
+
+`TODOUBLE(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1466.html)
+
+- `text`：待转 Double 的单个参数，允许任意类型，如 `"123.21"` 或数值。原文部分示例显示两位小数，但未规定转换强制保留两位，业务精度另用 ROUND 明确控制。
+
+### NUMTO
+
+`NUMTO(number[, boolean])` · [原文](https://help.fanruan.com/finebi/doc-view-1456.html)
+
+- `number`：数值，需要中文表示的数字。
+- `boolean`：布尔类型，可省略，默认 `false`。`false` 按中文位值读数，如 2345 → 二千三百四十五；`true` 逐位读数，如 2345 → 二三四五。布尔字面量支持大小写。仅抽取支持。
+
+### FORMAT
+
+`FORMAT(object, format)` · [原文](https://help.fanruan.com/finebi/doc-view-1454.html)
+
+- `object`：被格式化对象。抽取允许文本、数值、日期、时间等类型；实时/直连仅支持日期类型。
+- `format`：文本格式串，必需；返回格式化后的文本。日期按注意事项使用年份 `yy/yyyy`、月份 `M/MM`、日 `d/dd`，分钟 `m/mm` 与月份大小写不同；不要把原文示例表中的大写 `YYYY` 直接替代小写年份。
+- 数值模式：`0` 缺位补零；`#` 缺位不显示；`%` 将数值乘 100 并加百分号；如 `"#,##0.00"`、`"0.000%"`、`"0.00E00"`。日期例 `"yyyy-MM-dd"`，日期时间例 `"h:mm:ss a"`。
+- 直连 Kyligence 企业版不支持。需要日期值参与后续计算时用 TODATE 解析，不能将显示文本当作日期类型。
+
+### CODE
+
+`CODE(text)` · [原文](https://help.fanruan.com/finebi/doc-view-1474.html)
+
+- `text`：一个文本参数，只取其**第一个字符**的数字代码；返回代码对应计算机使用的字符集，不能把所有输入一概限定为 ASCII。
+
+### CHAR
+
+`CHAR(number)` · [原文](https://help.fanruan.com/finebi/doc-view-1473.html)
+
+- `number`：一个数值代码，返回对应的字符文本。原文未声明编码范围或越界行为；示例 `CHAR(88)` 返回 `"X"`。
+
+### TOSTRING（实例补充）
+
+`TOSTRING(object)` 来自本项目既有 Direct 实例参考，本次官方专题未找到独立参数页。
+
+- `object`：待转换成文本的对象；具体支持类型、NULL 和格式行为必须以目标 `formula functions` 面板及校验结果确认，不推断额外重载或默认参数。

package/skills/finebi-cli-agent/references/formula-recipes-analysis.md

@@ -0,0 +1,124 @@
+# 聚合与分析模板
+
+按场景读取。所有公式为依据官方文档改写的待校验模板，字段、主题、视图维度须替换/确认。DEF 模板用于支持该能力的自助主题；标准主题按 LOD 语法选型。签名见 [函数库](formula-functions.md)，位置、过滤、窗口限制见 [使用边界](formula-help-boundaries.md)。
+
+## 1. 条件统计与比率
+
+来源：[SUM_AGG](https://help.fanruan.com/finebi/doc-view-1385.html)、[条件求和与计数](https://help.fanruan.com/finebi/doc-view-1329.html)、[TOTAL](https://help.fanruan.com/finebi/doc-view-1215.html)、[指标卡总计](https://help.fanruan.com/finebi/doc-view-1513.html)。
+
+| 口径 | 模板 |
+|---|---|
+| 当前视图中满足条件的销售额 | `SUM_AGG(IF(${省份}="北京市",${销售额},0))` |
+| 满足条件的记录数 | `SUM_AGG(IF(${状态}="已交付",1,0))` |
+| 满足条件的去重用户数 | `COUNTD_AGG(IF(${状态}="已交付",${用户ID},NULL))`；不满足条件不要返回 0，否则 0 也会算一个成员 |
+| 激活当天登录人数 | `COUNTD_AGG(IF(AND(NOT(ISNULL(${激活日期})),NOT(ISNULL(${登录时间})),DATEDIF(${激活日期},${登录时间},"D")=0),${用户ID},NULL))`；统一到业务日期粒度 |
+| 平均单价（总额/总量） | `IF(OR(ISNULL(SUM_AGG(${销量})),SUM_AGG(${销量})=0),NULL,SUM_AGG(${销售额})/SUM_AGG(${销量}))` |
+| 条件整表总额，固定口径 | `DEF(SUM_AGG(${销售额}),[],[${省份}="北京市"])`；外部过滤是否仍影响结果须明确 |
+| 全表占比 | `SUM_AGG(${销售额})/TOTAL(SUM_AGG(${销售额}),0,"sum")` |
+| 组内占比 | `SUM_AGG(${销售额})/TOTAL(SUM_AGG(${销售额}),1,"sum")` |
+| 组内累计占比 | `ACC_SUM(SUM_AGG(${销售额}),1)/TOTAL(SUM_AGG(${销售额}),1,"sum")` |
+
+比率模板应用时统一补充分母空值/零值策略。`SUM_AGG(额)/SUM_AGG(量)` 与逐行相除后汇总不同。COUNT_AGG(字段) 排除空值，记录数用 COUNT_AGG(1)。对各组 COUNTD 的结果再求和可能重复计算跨组成员，不等于全局 COUNTD；指标卡全局人数应先明确去重范围。
+
+指标卡同时展示总成本与成本最高公司时，原文用 TOTAL 计算总体，再用组件 Top 1 过滤最高公司，并对总体指标取消“二次计算”。这里公式与展示过滤共同决定结果；只复制 TOTAL 不能保证全局值在过滤后保留。
+
+## 2. 固定粒度、频次、同期群和经营对比
+
+来源：[购买频次](https://help.fanruan.com/finebi/doc-view-2043.html)、[同期群](https://help.fanruan.com/finebi/doc-view-2046.html)、[消费周期](https://help.fanruan.com/finebi/doc-view-2070.html)、[月盈利天数](https://help.fanruan.com/finebi/doc-view-2080.html)、[目标达成](https://help.fanruan.com/finebi/doc-view-2050.html)、[地区经营](https://help.fanruan.com/finebi/doc-view-2092.html)。
+
+| 场景 | 分解方式及检查点 |
+|---|---|
+| 购买次数分布 | `购买次数=DEF(COUNTD_AGG(${订单ID}),[${客户ID}])`；把购买次数作为维度，人数用 `COUNTD_AGG(${客户ID})`，避免按订单行数统计人 |
+| 首购同期群 | `首次购买=DEF(MIN_AGG(${订单日期}),[${客户ID}])`；`YEAR(${首次购买})` 为 cohort 维度，再按购买年份和 cohort 统计销售额/客户数。不是 SAME_PERIOD 的时间错位计算 |
+| 用户消费周期 | 首末日期分别用 DEF(MIN_AGG/MAX_AGG(...),[用户ID])；日期跨度除以次数。原文口径为跨度/次数；若需求是相邻购买平均间隔，分母通常为次数−1，先明确口径及单次购买处理 |
+| 月盈利天数 | 先将订单日期规范到“天”；`每日利润=DEF(SUM_AGG(${利润}),[${日期}])`；用 IF 标记高盈利/盈利/亏损；按月份、标签对日期 COUNTD，不能对明细订单行计数 |
+| 省份产品目标达成率 | 先 `DEF(SUM_AGG(${利润}),[${省份},${产品}])-DEF(SUM_AGG(${利润目标}),[${省份},${产品}])` 得差额；按省份对差额达标的产品 COUNTD，再除以省份全部产品 COUNTD。达标条件是 >0 还是 ≥0 由业务确定 |
+| 地区店均销售额 | `DEF_ADD(SUM_AGG(${销售额}),[${店名}])`，视图含地区；展示时按店粒度做平均。比较交易数、最大值、中位数时对应换 COUNT/ MAX/ MEDIAN，并核对指标实际粒度 |
+
+固定基准、类别对比（[基准年增长率](https://help.fanruan.com/finebi/doc-view-2048.html)、[销售额对比](https://help.fanruan.com/finebi/doc-view-2091.html)）：
+
+```text
+各年销售额 = DEF(SUM_AGG(${销售额}),[${年份}])
+基准销售额 = DEF(SUM_AGG(${销售额}),[],[${年份}=2013])
+增长率 = IF(OR(ISNULL(${基准销售额}),${基准销售额}=0),NULL,${各年销售额}/${基准销售额}-1)
+
+选定品类销售额 = DEF(SUM_AGG(${销售额}),[],[${品类}=${选定品类参数}])
+差额 = DEF(SUM_AGG(${销售额}),[${品类}])-${选定品类销售额}
+```
+
+日期过滤可能把基准年数据排除。只在业务要求“忽略该过滤”时对基准的 DEF 加 CLEAN/CLEAN_WIDGET，按指定范围选择。参数是组件参数，CLI 落地时按参数引用声明，不伪造数据字段。
+
+标准主题对应思路（[FIXED](https://help.fanruan.com/finebi/doc-view-2770.html)、[INCLUDE](https://help.fanruan.com/finebi/doc-view-2772.html)、[EXCLUDE](https://help.fanruan.com/finebi/doc-view-2771.html)）：
+
+- 固定客户粒度：`{FIXED ${客户ID}: COUNTD_AGG(${订单ID})}`。
+- 省份视图内增加客户粒度：`{INCLUDE ${客户ID}: SUM_AGG(${销售额})}`；店均/客均还需明确展示聚合方式。
+- 地区、分类视图中排除分类：`{EXCLUDE ${分类}: SUM_AGG(${销售额})}`。
+- LOD 的增减维度不等于清除过滤；其语法没有 DEF 的第三个过滤数组，不能逐字符替换。
+
+## 3. 窗口、错行和排名
+
+来源：[移动平均](https://help.fanruan.com/finebi/doc-view-2230.html)、[前三月销售额](https://help.fanruan.com/finebi/doc-view-2221.html)、[累计平均](https://help.fanruan.com/finebi/doc-view-606.html)、[前 n 天平均](https://help.fanruan.com/finebi/doc-view-1163.html)、[数据编辑排名](https://help.fanruan.com/finebi/doc-view-2548.html)、[错行时间差](https://help.fanruan.com/finebi/doc-view-2546.html)、[序号](https://help.fanruan.com/finebi/doc-view-1128.html)。
+
+| 场景 | 模板与视图要求 |
+|---|---|
+| 含本月的近三行平均 | `WINDOW_AVG(SUM_AGG(${销售额}),[],[${年月},"asc"],[-2,0])`；年月在分析区；连续三个月需数据连续 |
+| 前三行（不含当前）平均 | 上式窗口改为 `[-3,-1]`；窗口不足三行时明确按现有行数还是必须完整三期 |
+| 分品类的月累计 | `WINDOW_SUM(SUM_AGG(${销售额}),[${品类}],[${年月},"asc"],["first",0])` |
+| 动态维度下的月累计 | `WINDOW_SUM(SUM_AGG(${销售额}),[SUB_DIM(${年月})],[${年月},"asc"],["first",0])`；分组保留分析区其他维度 |
+| 累计平均 | `WINDOW_AVG(SUM_AGG(${销售额}),[],[${年月},"asc"],["first",0])`；明确排序，避免默认顺序造成口径漂移 |
+| 上一结果行值 | `WINDOW_SUM(SUM_AGG(${销售额}),[],[${年月},"asc"],[-1,-1])`；日历上一期应考虑 PREVIOUS_PERIOD，缺期时不假定两者等价 |
+| 地区之间密集降序排名 | `RANK_AGG([],[SUM_AGG(${销售额}),"desc"],"DENSE")`；视图每地区一行，不按地区分区；销售额 100、80、80 对应 1、2、2 |
+| 可参与计算的表格序号 | `ACC_SUM(AVG_AGG(1),0)`；明细表不支持；仅显示序号优先组件自带设置 |
+
+数据编辑需要先构建固定视图，示例：
+
+```text
+DEF(RANK_AGG([${付款类型}],[SUM_AGG(${金额}),"desc"],"UNIQUE"),[${付款类型},${合同类型}])
+```
+
+该视图每个“付款类型、合同类型”组合一行，按付款类型分区，对组内各合同类型的汇总金额排名。逐记录编号须把业务唯一键纳入 DEF 视图，并定义并列排序键。不能因 UNIQUE 名称就假定同分记录固定排序。
+
+EARLIER 是当前外层行的值，不是上一行函数。若已有唯一连续序号和毫秒时间戳，上一行日期可按以下方式计算；多用户数据还要加同用户条件：
+
+```text
+上一行毫秒 = DEF(MAX_AGG(${时间戳}),[${序号}],[${序号}+1=EARLIER(${序号})])
+上一行日期 = IF(ISNULL(${上一行毫秒}),NULL,TODATE(${上一行毫秒}))
+间隔天数 = IF(OR(ISNULL(${上一行日期}),ISNULL(${日期})),NULL,DATEDIF(${上一行日期},${日期},"D"))
+```
+
+漏斗（[DEF](https://help.fanruan.com/finebi/doc-view-1986.html)、[EARLIER](https://help.fanruan.com/finebi/doc-view-1991.html)）：先按节点求客户数，再按明确的业务步骤取上一节点；阶段转化率为当前节点人数/上一节点人数，整体留存为当前节点人数/首节点人数。缺前一步或分母为 0 时返回约定缺失值。只在人数单调且无并列、与业务阶段一致时才用人数推导顺序。
+
+Top N（[动态前 N 名](https://help.fanruan.com/finebi/doc-view-886.html)）：先确定 COMMON/DENSE/UNIQUE 及并列是否全保留，再由组件过滤 `排名<=参数N`；公式产生排名本身不隐藏行。按比例取前半数需说明 ROUND/向上/向下取整口径。
+
+## 4. 同期、环期和累计同比
+
+来源：[年累计额同比](https://help.fanruan.com/finebi/doc-view-1170.html)、[DEF 月累计同比](https://help.fanruan.com/finebi/doc-view-2085.html)、[SAME_PERIOD](https://help.fanruan.com/finebi/doc-view-1212.html)、[PREVIOUS_PERIOD](https://help.fanruan.com/finebi/doc-view-1213.html)。
+
+SAME_PERIOD 返回基期值，不直接返回增长率；Y 为上年同期，M 为上月同期。月度环比可用 PREVIOUS_PERIOD；日度上月同日使用 SAME_PERIOD(...,"M")。PERIOD_ANLS 是上期末，不能用来替代同期。
+
+累计同比必须同时保留当前年累计和去年同期累计。快速计算方案：视图按年分组、年月升序，分别计算 `ACC_SUM(SUM_AGG(${销售额}),1)` 与 `ACC_SUM(SAME_PERIOD(SUM_AGG(${销售额}),"Y"),1)`；嵌套形式需目标面板和原生校验支持。不能只放年月导致跨年连续累计。
+
+DEF 方案按原文以独立年份/月字段定位：
+
+```text
+本年月累计 = DEF_ADD(SUM_AGG(${销售额}),[],[${年份}=EARLIER(${年份}),${月份}<=EARLIER(${月份})])
+去年月累计 = DEF_ADD(SUM_AGG(${销售额}),[],[${年份}=EARLIER(${年份}-1),${月份}<=EARLIER(${月份})])
+累计同比 = IF(OR(ISNULL(${去年月累计}),${去年月累计}=0),NULL,${本年月累计}/${去年月累计}-1)
+```
+
+该模板对应原文按年、月的分析区域；新增地区/商品维度时需核对是否保持组内累计，可参考 [SUB_DIM 原文](https://help.fanruan.com/finebi/doc-view-2624.html) 的同组 EARLIER 条件。过滤掉去年数据后，公式不会自动恢复数据；窗口和表格计算也不要混写到同一公式。
+
+## 5. 动态成本和自定义合计
+
+来源：[动态层级维度成本](https://help.fanruan.com/finebi/doc-view-2643.html)、[自定义合计行](https://help.fanruan.com/finebi/doc-view-2649.html)、[FIELD_IN](https://help.fanruan.com/finebi/doc-view-2638.html)。
+
+查看员工时显示个人成本，其他层级显示公司成本：`IF(FIELD_IN(ADD_DIM(),[${员工姓名}]),${个人成本},${公司成本})`。两个成本字段须为可同级运算的性质和类型；不同表来源要有明确关联。
+
+门店行展示所有门店销售额，合计排除闭店门店：
+
+```text
+非闭店销售额 = IF(${是否闭店}="否",${销售额},NULL)
+自定义合计销售额 = IF(FIELD_IN(ADD_DIM(),[${门店名称}]),SUM_AGG(${销售额}),SUM_AGG(${非闭店销售额}))
+```
+
+前提是实际闭店状态值匹配、合计方式为“自动”，合计视图不含门店维度；改成对行值求和可能绕过上述合计分支。钻取后视图维度发生变化，FIELD_IN 的选择也会变化。验收时分别核对门店行、小计和总计。