docs(sheets): mirror unified AI() formula docs from spec

Sync the lark-sheets AI formula skill from sheet-skill-spec (SoT) after
the product change that merges all AI formulas into one AI() function:

- formula-translation reference: single =AI(prompt, [range]) function with
  syntax (incl. variadic =AI(part1, part2, ...) concatenation), per-case
  usage table (translate / sentiment / classify / extract / summarize /
  rewrite / generate / cleanup / keywords / multi-cell prompt), and
  prompt best practices
- formula-verify reference + --ai-only flag def: unified AI() wording
- flag_defs_gen.go regenerated from flag-defs.json
- lark_sheet_formula_verify.go: drop stale AI_WRITE / AI_CLASSIFY names
  in the ai_only comment, reference the unified AI() function

Co-authored-by: TRAE CLI <noreply@bytedance.com>

shortcuts/sheets/data/flag-defs.json

@@ -51,6 +51,13 @@
         "type": "bool",
         "required": "optional",
         "desc": "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."
+      },
+      {
+        "name": "ai-only",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "Only verify AI formulas (the unified =AI(prompt, [range]) function that drives translation / classification / sentiment / extraction / summary / rewrite via natural language), skipping the 7 Excel-error scan of ordinary formulas. AI formulas compute asynchronously: small batches settle quickly, while a larger batch legitimately returns some pending (still computing) - re-check later."
       }
     ]
   },

shortcuts/sheets/flag_defs_gen.go

@@ -654,6 +654,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "range", Kind: "own", Type: "string_slice", Required: "optional", Desc: "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."},
 			{Name: "max-locations", Kind: "own", Type: "int", Required: "optional", Desc: "Max locations / samples per error type; default 20.", Default: "20"},
 			{Name: "exit-on-error", Kind: "own", Type: "bool", Required: "optional", Desc: "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."},
+			{Name: "ai-only", Kind: "own", Type: "bool", Required: "optional", Desc: "Only verify AI formulas (the unified =AI(prompt, [range]) function that drives translation / classification / sentiment / extraction / summary / rewrite via natural language), skipping the 7 Excel-error scan of ordinary formulas. AI formulas compute asynchronously: small batches settle quickly, while a larger batch legitimately returns some pending (still computing) - re-check later."},
 		},
 	},
 	"+history-list": {

shortcuts/sheets/lark_sheet_formula_verify.go

@@ -27,7 +27,7 @@ import (
 var FormulaVerify = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+formula-verify",
-	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial).",
+	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial). Use --ai-only to poll AI-formula compute status only.",
 	Risk:        "read",
 	Scopes:      []string{"sheets:spreadsheet:read"},
 	AuthTypes:   []string{"user", "bot"},
@@ -136,6 +136,15 @@ func formulaVerifyInput(runtime *common.RuntimeContext, token string) map[string
 	if runtime.Changed("max-locations") {
 		input["max_locations_per_error"] = runtime.Int("max-locations")
 	}
+	// ai_only routes verify_formula to the AI-formula-only branch (BE-1): the
+	// backend skips the ordinary 7-Excel-error worksheet scan and only reads AI
+	// formula compute status (the unified =AI(prompt, [range]) function) via the
+	// container-layer AIManager. AI formulas compute asynchronously, so this is a
+	// polling probe — one call returns current status, callers re-invoke until
+	// pending clears.
+	if runtime.Bool("ai-only") {
+		input["ai_only"] = true
+	}
 	return input
 }
 

shortcuts/sheets/lark_sheet_formula_verify_test.go

@@ -62,6 +62,23 @@ func TestFormulaVerify_DryRun(t *testing.T) {
 				"max_locations_per_error": float64(5),
 			},
 		},
+		{
+			name: "ai_only — AI-formula-only polling probe",
+			args: []string{"--url", testURL, "--ai-only"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"ai_only":  true,
+			},
+		},
+		{
+			name: "ai_only coexists with range selector",
+			args: []string{"--url", testURL, "--ai-only", "--range", "A1:Z200"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"ai_only":  true,
+				"ranges":   []interface{}{"A1:Z200"},
+			},
+		},
 	}
 
 	for _, tt := range tests {

skills/lark-sheets/references/lark-sheets-formula-translation.md

@@ -29,6 +29,63 @@
 2. 公式一旦落表，就默认进入 `lark-sheets-formula-verify` 的收尾阶段。
 3. 最终必须跑 `+formula-verify` 收敛到 `status='success'`；`errors_found` / `partial` 都不算完成。
 
+## AI 公式（`AI` 函数）
+
+飞书表格提供一个统一的 **`AI` 公式**：用自然语言描述需求，AI 返回文本结果。AI 公式的**写入方式与普通公式完全一致**（复用 `lark-sheets-write-cells` 的 `+cells-set` / `set_cell_range`，无需特殊接口），只是计算是**异步**的——写入后要等 AI 算完才有结果。
+
+### 语法
+
+```
+=AI(prompt)
+=AI(prompt, range)
+=AI(part1, part2, ...)
+```
+
+- `prompt`：提示词，说明要 AI 做什么（可以是字符串常量，也可以引用单元格）。
+- `range`：可选，交给 AI 处理的输入数据。可以是单个单元格（如 `A2`），也可以是一段单元格（如整行 `A2:G2` 或几列 `A2:C2`）——这段单元格会作为**这一次计算的输入上下文**一并喂给 AI，公式返回**一个**结果。具体写法见下方「常见用途」。
+- **多参数拼接**：`AI` 接受多个参数，会按顺序把字符串常量与单元格 / 区域引用拼成一段完整提示词。可用来把散落在不同位置的值组进一句话，例如 `=AI("结合", A2, "和", A4, "的描述，总结3个关键词")`。
+
+### 常见用途（同一个函数，靠提示词区分）
+
+`range` 既可以是单个单元格，也可以引用整行 / 多列作为一次计算的输入上下文；也可以用多个参数把不同位置的值拼进同一句提示词：
+
+| 场景 | 示例 |
+|---|---|
+| 翻译 | `=AI("翻译成日语", A2)` |
+| 情感分析 | `=AI("判断客户情绪，只返回 Positive、Neutral、Negative", A2)` |
+| 分类打标签 | `=AI("判断这封邮件是不是垃圾邮件", D2)`；结合多列辅助信息判断：`=AI("把餐厅归类到它所属的纽约市行政区，可参考街区信息", A2:C2)` |
+| 信息提取 | `=AI("提取邮箱", A2)` / `=AI("提取手机号", A2)` |
+| 总结 | `=AI("为这位客户的反馈写一句话总结", A2:D2)`；`=AI("用要点列出这段书籍摘要的主要主题", D2)` |
+| 多值拼接 | `=AI("结合", A2, "和", A4, "的描述，总结3个关键词")` |
+| 润色改写 | `=AI("改写得更正式", A2)` |
+| 生成文案 | `=AI("用 10 个字以内为活动生成一句宣传语", A2)`；引用整行回应具体内容：`=AI("给评审写一封邮件，针对评审意见中的具体条目逐条回应", A2:G2)`；`=AI("根据这段岗位职责摘要，为该职位生成一组关键词", A2:C2)` |
+| 数据清洗 / 标准化 | `=AI("统一公司名称写法", A2)` |
+| 关键词提取 | `=AI("提取 5 个关键词，用逗号分隔", A2)` |
+
+### 提示词最佳实践（写对提示词是结果稳定的关键）
+
+AI 公式的质量高度依赖提示词。推荐：
+
+1. **明确输出格式**：与其写"分析一下"，不如写"判断情绪，只返回 Positive / Neutral / Negative"。限定可选值能让结果可机读、可再计算。
+2. **指定语言**：写"翻译成中文"比只写"翻译"更稳定。
+3. **指定长度**：如"总结成一句话""30 字以内"。
+4. **需要结构化时明确要 JSON**：如提示"返回 JSON：{category:'', score:0-100}"，AI 能较稳定地输出结构化结果。
+
+### 与普通公式组合
+
+`AI` 可以像普通函数一样嵌进公式链，引用单元格或区域：
+
+```
+=IF(B2>90, AI("夸奖一下这位员工"), "")
+=TEXTJOIN(",", TRUE, AI("提取关键词", A2:A10))
+```
+
+### 用 CLI 对一列逐行处理
+
+对整列逐行跑 AI，推荐**模板单元格 + `--copy-to-range` 向下扩展**：在种子单元格写 `=AI("<提示词>", A2)`，再用 `--copy-to-range` 扩展到整列，相对引用会随行自增（`A2` → `A3` → …）。这样每行独立计算、行为可预测，比依赖单条公式一次铺开整列更稳。
+
+**写完 AI 公式后的校验**：AI 公式异步计算，少量公式通常很快就能算出结果；一次批量写入较多公式时，部分公式在校验时仍处于计算中（pending）属于正常现象。写完后用 `lark-sheets-formula-verify` 的 `+formula-verify --ai-only` 查看 AI 公式计算状态，直到不再有 pending 即算完成。细节见 `lark-sheets-formula-verify`。
+
 ## 决策流程
 
 1. 最终结果是**标量**（单值）→ 通常不需要 `ARRAYFORMULA`

skills/lark-sheets/references/lark-sheets-formula-verify.md

@@ -24,6 +24,7 @@
 | `--range` | 限定 A1 范围；省略则用各 sheet 的 `current_region` |
 | `--max-locations` | 每类错误样本上限，默认 20 |
 | `--exit-on-error` | `status='errors_found'` 时返回非 0 退出码（CI 网关用） |
+| `--ai-only` | 只校验 AI 公式（见「AI 公式校验」），跳过普通公式的 7 类 Excel 错误扫描；写完 AI 公式后查看计算状态用 |
 
 返回核心字段：
 
@@ -67,6 +68,26 @@
 - 同 sheet 内按 `--range` 切片（如先 `A1:Z200` 再 `AA1:AZ200`），逐块自检。
 - 每块都跑到 `has_more=false` 且 `status='success'` 才算通过。
 
+## AI 公式校验（`--ai-only`）
+
+飞书表格提供一个统一的 **`AI` 公式**（`=AI(prompt, [range])`，用自然语言驱动翻译 / 分类 / 情感分析 / 信息提取 / 总结 / 润色等，写法与清单见 `lark-sheets-formula-translation`）。AI 公式的写入与普通公式一致（复用 `+cells-set` / `set_cell_range`，无需特殊接口），但**计算是异步的**：写入后要等 AI 算完才有结果。普通的 `+formula-verify` 只扫本地单元格值（7 类 Excel 错误），看不到 AI 公式的计算状态。
+
+`--ai-only` 让 `+formula-verify` 只校验 AI 公式、跳过普通公式的 Excel 错误扫描，专用于「写完 AI 公式后确认是否都算完」：
+
+- **返回当前计算状态**：`+formula-verify --ai-only` 返回本次调用时 AI 公式的**当前**计算状态快照。
+- **收敛预期**：少量 AI 公式通常写完后很快就能算出结果，短时间内再查一次即可看到收敛；一次写入较多 AI 公式时，计算需要更长时间，校验返回部分公式仍处于 `pending`（计算中）属于**正常现象**，稍后再查即可，不代表出错。
+- **状态三态**：至少能区分「完成」/「进行中（仍在计算）」/「失败或不支持」。仍有「进行中」时，间隔一段时间后再查一次。
+- **`--exit-on-error` 兼容**：`--ai-only --exit-on-error` 时，若仍有 AI 公式处于失败态，返回非 0 退出码，便于脚本 / CI 收敛。
+- 可与 `--sheet-id` / `--sheet-name` / `--range` 共存，表示「只在指定范围里校验 AI 公式」。
+
+典型用法：
+
+```bash
+# 写入一批 AI 公式后，查看 AI 公式计算状态
+lark-cli sheets +formula-verify --url <表URL> --ai-only
+# 若仍有 pending，稍后再查一次；直到不再有 pending 即算完成
+```
+
 ## 常见陷阱
 
 | 坑 | 应对 |