Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws
dws
Unverified【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
references/products/aitable/aitable-formula-guide.md
View on GitHub# AI 表格公式字段指南
> 当用户要创建 formula 类型字段、编写表内计算公式、做派生指标时,必须先读本文档。
> 当前生产契约边界(2026-09-23):`create_fields` / `update_field` 的工具 Schema 尚未显式列出 `config.formula`;下方语法和示例不是该生产入口已可用的保证。先核对服务端契约与发布状态,未确认时不要试写;不得改用建表绕过原有目标。已返回 fieldId 但 `verificationStatus=pending` 或读回 `FIELD_NOT_FOUND` 时保留原回执,只读核对,不重新创建。`--wait` 仅验证字段结构可读,不证明公式计算结果已完成。
## 1. 何时使用 formula 字段
| 场景 | 用 formula | 不用 formula |
|------|-----------|-------------|
| 长期展示在表中的派生值(如"总价=单价×数量") | ✅ | |
| 条件标记(如"超期=IF(截止日期<TODAY(),'是','否')") | ✅ | |
| 文本拼接(如"全名=姓&名") | ✅ | |
| 一次性统计分析(如"本月总销售额") | | ✅ 用 record stats 服务端聚合 |
| 跨表查找引用 | | ✅ 用 lookup 字段(见下方说明) |
## 2. 创建 formula 字段
```bash
dws aitable field create \
--base-id <baseId> \
--table-id <tableId> \
--name "总价" \
--type formula \
--config '{"formula": "[单价] * [数量]"}' \
--format json
```
### config 结构
```json
{
"formula": "<公式表达式>"
}
```
- `formula` 是唯一必填字段
- 表达式中引用字段使用 **方括号 + 字段名**:`[字段名]`
- 字段名必须精确匹配(含空格、大小写)
## 3. 公式语法
### 3.1 引用规则
| 引用方式 | 语法 | 说明 |
|---------|------|------|
| 引用本表字段 | `[字段名]` | 字段名必须精确匹配 |
| 引用关联表字段 | 不支持 | 需要用 lookup 字段 |
### 3.2 常用函数分类
#### 数值计算
| 函数 | 用途 | 示例 |
|------|------|------|
| `+` `-` `*` `/` | 四则运算 | `[单价] * [数量]` |
| `SUM(...)` | 求和 | `SUM([Q1], [Q2], [Q3], [Q4])` |
| `ROUND(value, digits)` | 四舍五入 | `ROUND([金额] * 0.1, 2)` |
| `ABS(value)` | 绝对值 | `ABS([差额])` |
| `MAX(a, b, ...)` | 最大值 | `MAX([成绩1], [成绩2])` |
| `MIN(a, b, ...)` | 最小值 | `MIN([报价1], [报价2])` |
#### 文本处理
| 函数 | 用途 | 示例 |
|------|------|------|
| `&` | 文本拼接 | `[姓] & [名]` |
| `CONCATENATE(...)` | 拼接多个值 | `CONCATENATE([城市], "-", [区])` |
| `LEFT(text, n)` | 取左侧 n 字符 | `LEFT([编号], 4)` |
| `RIGHT(text, n)` | 取右侧 n 字符 | `RIGHT([手机], 4)` |
| `LEN(text)` | 文本长度 | `LEN([备注])` |
| `UPPER(text)` / `LOWER(text)` | 大小写转换 | `UPPER([代码])` |
#### 逻辑判断
| 函数 | 用途 | 示例 |
|------|------|------|
| `IF(条件, 真值, 假值)` | 条件判断 | `IF([金额] > 1000, "大额", "普通")` |
| `AND(a, b, ...)` | 逻辑与 | `IF(AND([状态]="完成", [评分]>=4), "优秀", "")` |
| `OR(a, b, ...)` | 逻辑或 | `IF(OR([等级]="A", [等级]="B"), "通过", "未通过")` |
| `NOT(expr)` | 逻辑非 | `NOT([已归档])` |
| `SWITCH(expr, v1, r1, v2, r2, ..., default)` | 多条件匹配 | `SWITCH([状态], "待办","🔴", "进行中","🟡", "完成","🟢", "")` |
#### 日期函数
| 函数 | 用途 | 示例 |
|------|------|------|
| `TODAY()` | 当前日期 | `IF([截止日期] < TODAY(), "已逾期", "正常")` |
| `NOW()` | 当前时间 | `NOW()` |
| `YEAR(date)` / `MONTH(date)` / `DAY(date)` | 提取年/月/日 | `YEAR([创建时间])` |
| `DATEDIF(start, end, unit)` | 日期差 | `DATEDIF([开始], [结束], "d")` 返回天数 |
| `DATEADD(date, count, unit)` | 日期加减 | `DATEADD([创建时间], 7, "d")` |
> `DATEDIF` 的 unit 参数:`"y"`=年, `"m"`=月, `"d"`=天
#### 空值处理
| 函数 | 用途 | 示例 |
|------|------|------|
| `BLANK()` | 空值常量 | `IF([备注] = BLANK(), "无", [备注])` |
| `IF(field, ...)` | 字段为空时视为 false | `IF([评分], [评分], 0)` |
## 4. 常见公式模板
### 4.1 计算类
```
// 含税价格
[不含税价] * (1 + [税率])
// 完成率百分比
[已完成数] / [总数]
// 折扣后价格
[原价] * (1 - [折扣率])
```
### 4.2 状态标记类
```
// 逾期标记
IF([截止日期] < TODAY(), "⚠️ 已逾期", "正常")
// 优先级标签
SWITCH([优先级], "紧急","🔴P0", "高","🟠P1", "中","🟡P2", "低","🟢P3", "")
// 进度状态
IF([进度] >= 1, "✅ 已完成", IF([进度] > 0, "🔄 进行中", "⏳ 未开始"))
```
### 4.3 文本拼接类
```
// 编号生成
"PRJ-" & [项目编码] & "-" & [序号]
// 地址拼接
[省] & [市] & [区] & [详细地址]
```
## 5. 注意事项与限制
### 5.1 formula 字段是只读的
- formula 字段的值由系统自动计算,**不能通过 `record create/update` 写入**
- 如果用户要"设置某个计算结果",应引导其修改源字段
### 5.2 字段名必须精确
- 公式中的 `[字段名]` 必须与表中实际字段名完全一致
- 创建 formula 字段前,先通过 `field get` 确认字段名
### 5.3 循环引用
- formula 字段不能引用自身
- 不能形成 A→B→A 的循环引用
### 5.4 与跨表引用字段的区别
钉钉 AI 表格有两种跨表取值方式:`lookup`(关联引用)和 `filterUp`(查找引用)。
| 维度 | formula | lookup (关联引用) | filterUp (查找引用) |
|------|---------|-----------------|-------------------|
| 字段类型 | `formula` | `lookup` | `filterUp` |
| 数据来源 | 本表字段 | 通过已有关联字段(bidirectionalLink/unidirectionalLink)取关联表字段 | 直接指定目标表 + 筛选条件取值 |
| 前置条件 | 无 | 必须先有关联字段 | 无需关联字段 |
| 适用场景 | 本表内计算、条件判断 | "我关联了某条记录,取它的某个字段值" | "在另一张表里按条件查找记录并聚合取值" |
#### lookup config(已验证)
```json
{
"associateField": "<本表中的关联字段 fieldId(bidirectionalLink/unidirectionalLink 类型)>",
"valuesField": "<关联目标表中要取值的字段 fieldId>",
"aggregator": "SUM|AVERAGE|COUNT|MAX|MIN|CONCATENATE"
}
```
创建示例:
```bash
dws aitable field create --base-id <baseId> --table-id <tableId> \
--name "关联名称" --type lookup \
--config '{"associateField":"<linkFieldId>","valuesField":"<targetFieldId>","aggregator":"CONCATENATE"}'
```
#### filterUp config(已验证)
```json
{
"targetSheet": "<目标表 tableId>",
"filters": [
{
"fieldId": "<目标表字段Id>",
"operator": "equal|contain",
"value": "<匹配值>",
"link": "AND"
}
],
"valuesField": "<目标表中要取值的字段Id>",
"aggregator": "SUM|AVERAGE|COUNT|MAX|MIN|CONCATENATE"
}
```
> `filters` 必须非空(至少一条筛选规则)。
> `filters[].operator` 仅支持:`equal`、`contain`(`not_equal`/`not_contain`/`is_empty` 等均不支持)。
> `filters[].link` 统一为 `"AND"` 或 `"OR"`。
### 5.5 创建前检查清单
1. 已通过 `field get` 确认所有引用字段的精确名称
2. 引用字段不包含 formula/lookup 等只读字段(可能导致二次计算延迟)
3. 公式语法正确(括号匹配、函数名正确)
4. 字段类型兼容(数值运算的字段确实是 number 类型)
## 6. 更新 formula 字段
```bash
dws aitable field update \
--base-id <baseId> \
--table-id <tableId> \
--field-id <fieldId> \
--config '{"formula": "[新字段A] + [新字段B]"}' \
--format json
```
更新时只需传新的 `formula` 表达式,但 mutation 成功不等于历史记录已经完成计算。先用 `field get` 核对表达式,再用 `record query --field-ids <输入字段ID,结果字段ID>` 对少量已知输入同时投影输入和结果;省略结果 fieldId 后的缺值不能判为计算失败。
公式结果持续为空或 `null` 时,先用页面、计算状态或等价只读路径交叉验证。不得通过更新业务记录来“触发重算”;配置正确但仍无法证明结果时,标记为 MCP 查询链路或平台计算问题。lookup/filterUp 同样需要用已知关联/筛选命中的小样本验证实际值,COUNT 必须与相同条件的真实记录数核对,不自动换字段规避错误。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |