dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-aitable/references/aitable/aitable-field-properties.md

@@ -0,0 +1,238 @@
+# 字段类型 config 规范（field create / table create / field update）
+
+> 适用命令：`dws aitable field create`、`dws aitable table create --fields`、`dws aitable field update --config`
+>
+> 本文件是 DWS AI 表格字段 config 的 **source of truth**。创建/更新字段时，必须严格按此规范构造 JSON。
+
+## 1. 顶层规则
+
+- `table create --fields` 和 `field create --fields` 中每个字段对象：`{"fieldName":"xxx", "type":"xxx", "config":{...}}`
+- `field create --name --type --config` 中 config 单独传 JSON 字符串
+- `field update --config` 只传 config 部分
+- 不需要 config 的类型（如 text、checkbox、attachment）可省略 config 字段
+
+## 2. 字段类型速查
+
+| type | 需要 config | config 核心字段 | 说明 |
+|------|-------------|----------------|------|
+| `text` | ❌ | — | 纯文本 |
+| `number` | 可选 | `formatter` | 数字格式 |
+| `singleSelect` | ✅ | `options` | 单选 |
+| `multipleSelect` | ✅ | `options` | 多选 |
+| `date` | 可选 | `formatter` | 日期格式 |
+| `currency` | 可选 | `currencyType`, `formatter` | 货币 |
+| `progress` | 可选 | `formatter`, `min`, `max`, `customizeRange` | 进度条 |
+| `rating` | 可选 | `min`, `max`, `icon` | 评分 |
+| `checkbox` | ❌ | — | 勾选框 |
+| `user` | 可选 | `multiple` | 人员 |
+| `department` | 可选 | `multiple` | 部门 |
+| `group` | 可选 | `multiple` | 群组 |
+| `url` | ❌ | — | 链接 |
+| `richText` | ❌ | — | 富文本 |
+| `telephone` | ❌ | — | 电话 |
+| `email` | ❌ | — | 邮箱 |
+| `attachment` | ❌ | — | 附件 |
+| `geolocation` | ❌ | — | 地理位置 |
+| `formula` | ✅ | `formula` | 公式（只读字段） |
+| `unidirectionalLink` | ✅ | `linkedTableId`, `multiple` | 单向关联 |
+| `bidirectionalLink` | ✅ | `linkedTableId`, `multiple` | 双向关联 |
+| `creator` | ❌ | — | 系统字段：创建人（只读） |
+| `lastModifier` | ❌ | — | 系统字段：最后编辑人（只读） |
+| `createdTime` | ❌ | — | 系统字段：创建时间（只读） |
+| `lastModifiedTime` | ❌ | — | 系统字段：最后编辑时间（只读） |
+
+## 3. 各类型 config 详解
+
+### 3.1 number（数字）
+
+config 字段：`formatter`
+
+可选值：
+- `INT` — 整数
+- `FLOAT_1` — 1 位小数
+- `FLOAT_2` — 2 位小数（默认）
+- `FLOAT_3` — 3 位小数
+- `FLOAT_4` — 4 位小数
+- `THOUSAND` — 千分位整数
+- `THOUSAND_FLOAT` — 千分位 + 小数
+- `PERCENT` — 百分比（整数）
+- `PERCENT_FLOAT` — 百分比（小数）
+
+```json
+{"fieldName": "工时", "type": "number", "config": {"formatter": "FLOAT_2"}}
+```
+
+```json
+{"fieldName": "完成率", "type": "number", "config": {"formatter": "PERCENT"}}
+```
+
+### 3.2 singleSelect / multipleSelect（单选 / 多选）
+
+config 字段：`options`（必填）
+
+options 结构：
+- `options` 是数组，每项至少包含 `name`
+- 创建时只传 `name`，`id` 由系统生成
+- **更新时**：已有选项必须回传原 `id`（从 `field get` 获取），新增选项不传 id
+
+```json
+{
+  "fieldName": "优先级",
+  "type": "singleSelect",
+  "config": {
+    "options": [
+      {"name": "紧急"},
+      {"name": "高"},
+      {"name": "中"},
+      {"name": "低"}
+    ]
+  }
+}
+```
+
+更新已有字段时（保留原选项 + 新增）：
+```json
+{
+  "options": [
+    {"id": "opt_existing_1", "name": "紧急"},
+    {"id": "opt_existing_2", "name": "高"},
+    {"id": "opt_existing_3", "name": "中"},
+    {"name": "极低"}
+  ]
+}
+```
+
+> 更新 options 是**全量覆盖**，不是追加！不传的旧选项会被删除，关联的单元格数据丢失。
+
+### 3.3 date（日期）
+
+config 字段：`formatter`
+
+可选值：
+- `YYYY-MM-DD`（默认）
+- `YYYY-MM-DD HH:mm`
+- `YYYY-MM-DD HH:mm:ss`
+- `YYYY/MM/DD`
+- `YYYY/MM/DD HH:mm`
+
+```json
+{"fieldName": "截止日期", "type": "date", "config": {"formatter": "YYYY-MM-DD"}}
+```
+
+```json
+{"fieldName": "创建时间", "type": "date", "config": {"formatter": "YYYY-MM-DD HH:mm"}}
+```
+
+### 3.4 currency（货币）
+
+config 字段：`currencyType`（必填）、`formatter`（可选）
+
+currencyType 可选值：
+`CNY` | `HKD` | `USD` | `EUR` | `GBP` | `MOP` | `VND` | `JPY` | `KRW` | `AED` | `AUD` | `BRL` | `CAD` | `CHF` | `INR` | `IDR` | `MXN` | `MYR` | `PHP` | `PLN` | `RUB` | `SGD` | `THB` | `TRY` | `TWD`
+
+formatter 可选值（控制小数位）：`INT` | `FLOAT_1` | `FLOAT_2`（默认）| `FLOAT_3` | `FLOAT_4`
+
+```json
+{"fieldName": "预算", "type": "currency", "config": {"currencyType": "CNY", "formatter": "FLOAT_2"}}
+```
+
+### 3.5 progress（进度）
+
+config 字段：`formatter`（固定为 `PERCENT`）、`customizeRange`、`min`、`max`
+
+- 默认范围：0~1（即 0%~100%）
+- 自定义范围时 `customizeRange` 必须为 `true`
+
+```json
+{"fieldName": "完成度", "type": "progress", "config": {"formatter": "PERCENT"}}
+```
+
+自定义范围：
+```json
+{"fieldName": "进度", "type": "progress", "config": {"formatter": "PERCENT", "customizeRange": true, "min": 0, "max": 1}}
+```
+
+### 3.6 rating（评分）
+
+config 字段：`min`、`max`、`icon`
+
+- `min`：固定为 `1`
+- `max`：1~10，默认 `5`
+- `icon`：默认 `star`
+
+```json
+{"fieldName": "满意度", "type": "rating", "config": {"min": 1, "max": 5, "icon": "star"}}
+```
+
+### 3.7 user / department / group（人员 / 部门 / 群组）
+
+config 字段：`multiple`
+
+- `multiple`：`true`（多选，默认）| `false`（单选）
+
+```json
+{"fieldName": "负责人", "type": "user", "config": {"multiple": false}}
+```
+
+```json
+{"fieldName": "协作部门", "type": "department", "config": {"multiple": true}}
+```
+
+### 3.8 formula（公式）
+
+config 字段：`formula`（必填）
+
+- 公式中引用字段使用**方括号 + 字段名**：`[字段名]`
+- 支持的函数：参考钉钉 AI 表格公式文档
+
+```json
+{"fieldName": "合计", "type": "formula", "config": {"formula": "[单价] * [数量]"}}
+```
+
+```json
+{"fieldName": "是否逾期", "type": "formula", "config": {"formula": "IF([截止日期] < NOW(), \"是\", \"否\")"}}
+```
+
+> ⚠️ formula 字段创建后为**只读**，不能通过 record create/update 写入值。
+
+### 3.9 unidirectionalLink（单向关联）
+
+config 字段：`linkedTableId`（必填）、`multiple`
+
+- `linkedTableId`：目标表的 tableId
+- `multiple`：`true`（多选，默认）| `false`（单选）
+
+```json
+{"fieldName": "关联项目", "type": "unidirectionalLink", "config": {"linkedTableId": "tblXXXXXX", "multiple": true}}
+```
+
+### 3.10 bidirectionalLink（双向关联）
+
+config 字段：`linkedTableId`（必填）、`multiple`
+
+- 与单向关联参数相同
+- 创建后系统会**自动**在被关联表创建反向字段
+
+```json
+{"fieldName": "关联任务", "type": "bidirectionalLink", "config": {"linkedTableId": "tblYYYYYY", "multiple": true}}
+```
+
+## 4. AI 字段（ai-config）
+
+AI 字段不使用 config，而使用独立的 `--ai-config` 参数。详见 [aitable-field.md](./aitable-field.md) 中的 AI 字段创建示例。
+
+核心规则：
+- `outputType` 必须与 `--type` 对应：text→text, select→singleSelect, multiSelect→multipleSelect, number→number, currency→currency, image/video→attachment
+- `prompt` 中必须至少包含一个 `fieldRef` 引用
+- 纯文本 prompt 会被后端拒绝
+
+## 5. 常见错误
+
+| 错误 | 说明 |
+|------|------|
+| options 更新时不传已有选项的 id | 会被视为新选项，旧选项被删除，关联数据丢失 |
+| options 更新时只传新增项 | 全量覆盖，旧选项全部丢失 |
+| formula 字段尝试写入值 | 只读字段，record create/update 会报错 |
+| linkedTableId 传表名而非 ID | 必须传 tableId（如 `tblXXX`），不接受表名 |
+| progress 值写入 50 表示 50% | 实际应写入 0.5（range 0~1） |
+| rating 值超出 max | 写入会报错 |

package/skills/dws/dingtalk-aitable/references/aitable/aitable-field.md

@@ -0,0 +1,186 @@
+# field — 字段管理
+
+仅在 AI 字段、关联字段、lookup/filterUp 或其他复杂 config 结构不确定时读取。普通 text/number/date/singleSelect/currency 字段的 create/update/delete 使用根 Skill 次级直达。
+
+本文是字段复杂配置的终点；命令参数已覆盖时，不再读取其他 AITable Reference 或 Help。
+
+## field get — 获取字段详情
+
+```
+Usage:
+  dws aitable field get [flags]
+Example:
+  dws aitable field get --base-id <BASE_ID> --table-id <TABLE_ID>
+  dws aitable field get --base-id <BASE_ID> --table-id <TABLE_ID> --field-ids fld1,fld2
+Flags:
+      --base-id string     Base ID (必填)
+      --field-ids string   字段 ID 列表，逗号分隔，单次最多 10 个
+      --table-id string    Table ID (必填)
+```
+
+返回字段的完整配置（含 options 等）。不要假设未指定 `--table-ids` 的 `table get` 枚举结果含字段；字段目录和配置以 `field get` 返回为准。
+
+## field create — 创建字段
+
+```
+Usage:
+  dws aitable field create [flags]
+Example:
+  dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+    --name "状态" --type "singleSelect" --config '{"options":[{"name":"待办"},{"name":"进行中"},{"name":"已完成"}]}'
+
+  # 或者使用批量创建模式:
+  dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+    --fields '[{"fieldName":"状态","type":"singleSelect","config":{"options":[{"name":"待办"}]}}]'
+Flags:
+      --base-id string    Base ID (必填)
+      --name string       要创建的单字段名称（与 --type 配合使用，替代 --fields）
+      --type string       要创建的单字段类型（需要配合 --name，参考 table create 的内置类型）
+      --config string     单字段配置 JSON（需要配合 --name/--type，结构参考 table create）
+      --ai-config string  单字段 AI 配置 JSON（需要配合 --name/--type）
+      --fields string     批量新增字段 JSON 数组，单次最多 15 个；每个字段的配置写在其 config/aiConfig 内
+      --table-id string   Table ID (必填)
+```
+
+`field create` 有且只有两种输入模式：
+
+- 单字段模式：必须同时传 `--name` 和 `--type`；`--config`、`--ai-config` 只作为该字段的附加配置。
+- 批量模式：只传 `--fields`；字段配置写在数组内各对象的 `config` / `aiConfig` 中。
+
+两种模式严格互斥。`--fields` 不能与 `--name`、`--type`、`--config` 或 `--ai-config` 混用；单独传 `--config` 也会报错，不会被静默忽略。
+
+例如创建单选字段时，单字段模式的 `--config` 是一个配置对象；批量模式则把同一对象放入对应字段元素的 `config`：
+
+```bash
+# 单字段模式
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "部门" --type singleSelect \
+  --config '{"options":[{"name":"技术部"},{"name":"产品部"}]}'
+
+# 批量模式
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --fields '[{"fieldName":"部门","type":"singleSelect","config":{"options":[{"name":"技术部"},{"name":"产品部"}]}}]'
+```
+
+人民币货币字段使用真实 `currency` 枚举和配置，不使用 `select` 或 `config.symbol`：
+
+```bash
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "预计成交额" --type currency \
+  --config '{"currencyType":"CNY","formatter":"FLOAT_2"}' --format json
+```
+
+允许部分成功，返回结果逐项标明成功/失败状态。
+
+### AI 字段创建示例
+
+```bash
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "AI摘要" --type text \
+  --ai-config '{
+    "outputType":"text",
+    "prompt":[
+      {"type":"text","value":"请将下面内容总结成不超过80字的中文摘要："},
+      {"type":"fieldRef","fieldId":"fld_content"}
+    ],
+    "autoRecompute":true,
+    "enableWebSearch":false,
+    "enableThinking":true
+  }' --format json
+```
+
+说明：
+- `outputType` 与字段类型需一致（如 `outputType=text` 配 `--type text`）
+- `prompt` 里通过 `fieldRef` 引用已有字段
+- `autoRecompute=true` 表示引用字段变化后自动重算
+- **AI 字段的 prompt 必须至少包含一个 `fieldRef` 引用**，纯文本 prompt 会被后端拒绝
+
+### 关联字段与跨表引用字段
+
+创建 `lookup`（关联引用）和 `filterUp`（查找引用）字段时，config 格式有严格要求：
+
+#### bidirectionalLink / unidirectionalLink（关联字段）
+
+```bash
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "关联客户" --type bidirectionalLink \
+  --config '{"linkedTableId":"<目标表tableId>","multiple":true}' --format json
+```
+
+#### lookup（关联引用，通过已有关联字段取值）
+
+**前置条件**：本表必须已有一个 bidirectionalLink 或 unidirectionalLink 类型的关联字段。
+
+```bash
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "客户城市" --type lookup \
+  --config '{"associateField":"<本表关联字段的fieldId>","valuesField":"<关联目标表中要取值的字段fieldId>","aggregator":"CONCATENATE"}' --format json
+```
+
+config 必填字段：
+- `associateField`：**本表中**已有的关联字段（bidirectionalLink/unidirectionalLink）的 fieldId
+- `valuesField`：**关联目标表中**要取值的字段 fieldId
+- `aggregator`：聚合方式，可选 `SUM`|`AVERAGE`|`COUNT`|`MAX`|`MIN`|`CONCATENATE`
+
+> 常见错误：`associateField` 不是目标表的 tableId，也不是目标表的字段 ID，而是**本表中关联字段自身的 fieldId**。
+
+#### filterUp（查找引用，无需关联字段，直接跨表取值）
+
+```bash
+# 基本用法：字段对常量匹配
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "客户总金额" --type filterUp \
+  --config '{"targetSheet":"<目标表tableId>","filters":[{"fieldId":"<目标表字段Id>","operator":"equal","value":"匹配值","link":"AND"}],"valuesField":"<目标表中要取值的字段Id>","aggregator":"SUM"}' --format json
+
+# 进阶用法：字段对字段动态匹配（currentSheetFieldId）
+dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --name "本城市订单金额" --type filterUp \
+  --config '{"targetSheet":"<目标表tableId>","filters":[{"fieldId":"<目标表字段Id>","operator":"equal","currentSheetFieldId":"<本表字段Id>","link":"AND"}],"valuesField":"<目标表中要取值的字段Id>","aggregator":"SUM"}' --format json
+```
+
+config 必填字段：
+- `targetSheet`：目标表的 tableId
+- `filters`：至少一条筛选规则
+  - `fieldId`：目标表中用于匹配的字段 fieldId
+  - `operator`：仅支持 `equal`、`contain`（不支持 not_equal/not_contain）
+  - `value`：常量匹配值（与 `currentSheetFieldId` 二选一）
+  - `currentSheetFieldId`：本表中用于动态匹配的字段 fieldId（与 `value` 二选一，实现每行按本表字段值去目标表筛选）
+  - `link`：多条件时的逻辑关系，`AND` 或 `OR`（单条件时可省略，多条件时建议显式指定；所有 filter 的 link 必须统一）
+- `valuesField`：目标表中要取值的字段 fieldId
+- `aggregator`：聚合方式，可选 `SUM`|`AVERAGE`|`COUNT`|`MAX`|`MIN`|`CONCATENATE`
+
+## field update — 更新字段
+
+```
+Usage:
+  dws aitable field update [flags]
+Example:
+  dws aitable field update --base-id <BASE_ID> --table-id <TABLE_ID> --field-id <FIELD_ID> --name "新字段名"
+  dws aitable field update --base-id <BASE_ID> --table-id <TABLE_ID> --field-id <FIELD_ID> --config '{"options":[{"name":"A"},{"name":"B"}]}'
+Flags:
+      --base-id string    Base ID (必填)
+      --config string     字段配置 JSON (不修改时省略)
+      --ai-config string  AI 配置 JSON (不修改时省略)
+      --field-id string   Field ID (必填)
+      --name string       新字段名称 (不修改时省略)
+      --table-id string   Table ID (必填)
+```
+
+- 不可变更字段类型
+- 更新 singleSelect/multipleSelect 的 options 时需传入完整列表，已有选项应回传原 id
+- `--name` / `--config` / `--ai-config` 至少传一个
+
+## field delete — 删除字段
+
+```
+Usage:
+  dws aitable field delete [flags]
+Example:
+  dws aitable field delete --base-id <BASE_ID> --table-id <TABLE_ID> --field-id <FIELD_ID> --yes
+Flags:
+      --base-id string    Base ID (必填)
+      --field-id string   待删除字段 ID (必填)
+      --table-id string   Table ID (必填)
+```
+
+不可逆。禁止删除主字段和最后一个字段。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-filter-sort.md

@@ -0,0 +1,135 @@
+# 记录筛选与排序语法
+
+仅在记录查询或按条件批改明确涉及 AND/OR、日期或比较操作符时读取。本文件只负责 `record query --filters` / `--sort` 的记录级语法；视图的 filter/sort/group 由根 Skill 直接路由到视图布局 reference。选中本文后不要再加载视图 reference。
+
+## filters 结构规范
+
+### 强制规则
+
+1. **根节点必须是逻辑操作符**：`"operator"` 必须是 `"and"` 或 `"or"`，不能是 `"eq"` 等比较操作符
+2. 比较操作必须放在根节点的 `"operands"` 数组内的对象中
+3. `singleSelect` 和 `multipleSelect` 字段，推荐使用 **选项的 exact String 名称 (name)** 作为比较值
+4. fieldId 必须通过 `field get` 获取，不能直接用字段名称
+
+### 精简防呆模板
+
+CLI 同时兼容两种子条件写法（推荐格式 A）：
+
+**格式 A（operands 数组，推荐）：**
+```json
+{
+  "operator": "and",
+  "operands": [
+    {"operator": "eq", "operands": ["fld_state", "进行中"]}
+  ]
+}
+```
+
+**格式 B（fieldId/value 对象，CLI 自动转换）：**
+```json
+{
+  "operator": "and",
+  "operands": [
+    {"fieldId": "fld_state", "operator": "eq", "value": "进行中"}
+  ]
+}
+```
+
+4 种衍生：
+- **OR 查询**：根节点 `"operator"` 改为 `"or"`
+- **多条件 AND**：在 `"operands"` 数组中增加对象
+- **文本包含**：内层 `"operator"` 改为 `"contain"`
+- **为空判断**：`"operator":"un_exist"`，operands 只需 `["fieldId"]`
+
+### 支持的操作符（已验证完整列表）
+
+| 操作符 | 含义 | operands 格式 |
+|--------|------|--------------|
+| `eq` / `ne` | 等于 / 不等于 | `["fieldId", "value"]` |
+| `contain` / `exclusive` | 包含 / 不包含（文本模糊） | `["fieldId", "value"]` |
+| `gt` / `gte` / `lt` / `lte` | 大于 / ≥ / 小于 / ≤ | `["fieldId", "numStr"]` |
+| `exist` / `un_exist` | 有值 / 为空 | `["fieldId"]`（无需第二项） |
+| `any_of` / `none_of` / `all_of` | 包含任一 / 不包含任一 / 全包含（多选字段） | `["fieldId", "optionName"]` |
+| `date_eq` / `before` / `after` | 日期等于 / 早于 / 晚于 | `["fieldId", "dateStr"]` |
+| `not_before` / `not_after` | 不早于（≥） / 不晚于（≤） | `["fieldId", "2026-05-22"]` |
+
+> **操作符拼写必须严格匹配上表**，CLI 会在调用前校验，错误拼写会被拒绝。
+>
+> **没有 `date_between`（区间）操作符**，也**不支持 `from_now`**——date 字段不支持区间/相对过滤，传了会被 CLI 拒绝。范围查询用 `not_before` + `not_after` 组合，见下方专节。
+
+### 日期字段过滤（date / 创建时间 / 修改时间）
+
+日期类字段的过滤规则与其它字段**不同**，是线上反馈最高频的踩坑点。**经集成测试实测**确认的规则：
+
+1. **只能用日期专用操作符**：`date_eq` / `before` / `after` / `not_before` / `not_after` / `exist` / `un_exist`（与前端筛选 UI 的「等于 / 早于 / 晚于 / 早于或等于 / 晚于或等于 / 不为空 / 为空」一一对应）。
+2. **比较值用日期字符串**，如 `"2026-05-22"`（也接受 RFC3339 / 毫秒时间戳，内部统一转成毫秒比较）。读取返回的是带时区 RFC3339（如 `"2026-05-22T00:00:00+08:00"`）。
+3. **通用操作符 `eq` / `ne` / `gt` / `gte` / `lt` / `lte` / `contain` 对 date 字段无效**——无论传 ISO 字符串还是毫秒时间戳，都会**静默返回 0 条**。这是后端 date 字段的比较规则，不是 bug，CLI 也无法在本地拦截（不知道字段类型），务必用对操作符。
+4. **没有区间操作符 `date_between`**，也**不支持 `from_now`（相对天数）**——均会静默返回 0 条，CLI 已直接拒绝。范围查询用 `not_before`（≥起点）+ `not_after`（≤终点）两个条件 `and` 组合。
+
+| 需求 | 操作符 | 示例 operands |
+|------|--------|--------------|
+| 等于某天 | `date_eq` | `["fldDate", "2026-05-22"]` |
+| 早于 / 晚于（不含当天） | `before` / `after` | `["fldDate", "2026-05-22"]` |
+| 不早于（≥） / 不晚于（≤） | `not_before` / `not_after` | `["fldDate", "2026-05-22"]` |
+| 有值 / 为空 | `exist` / `un_exist` | `["fldDate"]` |
+
+**日期区间查询（替代 between）**——查 `2026-05-01 ~ 2026-05-31`（含端点）：
+
+```bash
+dws aitable record query --base-id X --table-id Y \
+  --filters '{"operator":"and","operands":[{"operator":"not_before","operands":["fldDate","2026-05-01"]},{"operator":"not_after","operands":["fldDate","2026-05-31"]}]}'
+```
+
+### 常见错误拼写（CLI 会自动提示纠正）
+
+| 错误写法 | 正确写法 | 说明 |
+|------------|-----------|------|
+| `equal` / `equals` / `is` / `==` | `eq` | 等于 |
+| `neq` / `not_eq` / `not_equal` / `not_equals` / `is_not` / `!=` | `ne` | 不等于；CLI 会提示使用规范操作符 `ne` |
+| `like` / `contains` / `include` | `contain` | 文本包含 |
+| `greater_than` | `gt` | 大于 |
+| `less_than` | `lt` | 小于 |
+| `not_contain` / `is_empty` | `exclusive` / `un_exist` | 其他易混淆 |
+
+### 错误示例
+
+❌ **缺失根节点 and/or**（API 将忽略该 filter，返回全表）：
+```json
+{"operator":"eq","operands":["fldXXX","本科"]}
+```
+
+❌ **传入选项 ID 而非名称**（可能导致匹配不到 0 记录）：
+```json
+{"operator":"and","operands":[{"operator":"eq","operands":["fldXXX","CXzrOHK9JI"]}]}
+```
+
+### 完整示例
+
+单条件：
+```bash
+dws aitable record query --base-id X --table-id Y \
+  --filters '{"operator":"and","operands":[{"operator":"eq","operands":["fldStatusId","进行中"]}]}'
+```
+
+多条件 AND：
+```bash
+dws aitable record query --base-id X --table-id Y \
+  --filters '{"operator":"and","operands":[{"operator":"eq","operands":["fldStatusId","进行中"]},{"operator":"gt","operands":["fldStockId","0"]}]}'
+```
+
+分页时只透传服务端真实 `nextCursor`。出现 `pagination_cursor_cycle`、相同 cursor 或重复页时，保留已取记录并立即停止；不要用相同参数重跑，也不要切换到其他查询命令把不完整结果误报为完整。
+
+若写入已返回真实 recordId，但同一 Base/Table 的无筛选查询也无法读到该记录，问题已不属于 filters/sort 语法。保留写入返回和查询证据并停止；不要更换操作符、加载其他 AITable Reference 或 Help、重建表，也不要重放写入。
+
+## sort 结构规范
+
+`--sort` 传 JSON 数组，排序方向字段**必须是 `direction`**，不要使用 `order`。
+
+```bash
+--sort '[{"fieldId":"fldXXX","direction":"desc"}]'
+```
+
+多字段排序：
+```bash
+--sort '[{"fieldId":"fldPriority","direction":"desc"},{"fieldId":"fldCreatedAt","direction":"asc"}]'
+```