dsh-crwu-workbench 0.0.10

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

@@ -0,0 +1,130 @@
+# form — 表单管理
+
+## 命令一览
+
+| 命令 | 用途 |
+|------|------|
+| `form list` | 列出数据表下所有表单视图 |
+| `form get` | 按 viewId 取单个表单详情（list_form_views + viewIds 过滤） |
+| `form create` | 创建表单视图（等价于 `view create --view-type FormDesigner`） |
+| `form update` | 更新表单标题或描述 |
+| `form delete` | 删除表单视图（不可逆） |
+| `form field list` | 列出表单可见字段 |
+| `form field update` | 更新字段必填/描述 |
+| `form field hide` | 在表单中隐藏/显示字段（不影响底层数据表字段） |
+| `form share get` | 获取分享配置 |
+| `form share update` | 开启/关闭分享 |
+| `form questions create` | 添加题目（等价于 `field create`，命令位置上的别名） |
+| `form questions delete` | 删除题目（等价于 `field delete`，命令位置上的别名） |
+
+## 建议操作顺序
+
+```bash
+# 1) 列出数据表下的表单视图
+dws aitable form list --base-id BASE_ID --table-id TABLE_ID --format json
+
+# 2) 查看单个表单详情
+dws aitable form get --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+
+# 3) 查看表单字段配置
+dws aitable form field list --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+
+# 4) 查看分享配置
+dws aitable form share get --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+```
+
+开启并取得可发送链接的最短闭环使用 canonical shortcut：
+
+```bash
+dws aitable form create --base-id BASE_ID --table-id TABLE_ID --name "表单名" --format json
+dws aitable +form-share-update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --enabled true --format json
+dws aitable +form-share-get --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+```
+
+从最后一次返回直接读取 `data.shareFormUuid`，分享地址为 `https://alidocs.dingtalk.com/i/form/{shareFormUuid}`。字段已存在时不要再调用 Help、Catalog、`form get`，也不要换 `--verbose`、`raw`、`pretty` 重复请求。用户还要求发送时，把该完整 URL 交给 Chat 的发送命令并检查真实发送回执。
+
+## 要点
+
+- **创建表单**有两种等价方式：
+  - `form create --name "表单名"`（推荐，语义清晰）
+  - `view create --view-type FormDesigner --name "表单名"`（底层一致）
+- `form update` 支持 `--title` 与 `--name` 两个等价参数；至少需传一项
+- `form field update` 必须传 `--required` 或 `--field-description` 至少一项
+- `form field hide` 仅控制字段在表单中的可见性，不影响底层数据表字段
+- **题目管理**与字段管理本质相同（题目 = 表格字段）：
+  - `form questions create` 与 `field create` 入参完全一致（`--fields` JSON 或 `--name --type`）
+  - `form questions delete` 与 `field delete` 入参完全一致（必传 `--field-id`）
+  - 设置必填要在 create 后用 `form field update --required true` 单独调一次
+
+## form 子命令
+
+| 命令 | 用途 | 必填参数 | 说明 |
+|------|------|----------|------|
+| `form list` | 列出表单视图 | `--base-id` `--table-id` | 返回 viewId/name/title/createdAt |
+| `form get` | 按 viewId 取单个表单 | `--base-id` `--table-id` `--view-id` | 内部基于 list_form_views 过滤 |
+| `form create` | 创建表单视图 | `--base-id` `--table-id` `--name` | viewType=FormDesigner |
+| `form update` | 更新表单 | `--base-id` `--table-id` `--view-id` | `--title`/`--name`（等价）和 `--description` 至少传一项；同时传 title/name 时 title 优先 |
+| `form delete` | 删除表单 | `--base-id` `--table-id` `--view-id` `--yes` | 不可逆 |
+
+## form field 子命令
+
+| 命令 | 用途 | 必填参数 | 说明 |
+|------|------|----------|------|
+| `form field list` | 列出表单字段 | `--base-id` `--table-id` `--view-id` | 返回 fieldId/name/type/required/hidden/description（hidden=true 的字段不在此返回） |
+| `form field update` | 更新表单字段 | `--base-id` `--table-id` `--view-id` `--field-id` | `--required` 或 `--field-description` 至少一项 |
+| `form field hide` | 切换字段隐藏 | `--base-id` `--table-id` `--view-id` `--field-id` `--hidden` | `--hidden true` 隐藏 / `--hidden false` 显示 |
+
+## form questions 子命令
+
+`form questions create/delete` 与 `field create/delete` 入参、行为完全一致，只是命令位置归属于 `form` 命令组，方便从表单视角操作题目。
+
+| 命令 | 用途 | 必填参数 | 说明 |
+|------|------|----------|------|
+| `form questions create` | 添加题目 | `--base-id` `--table-id` + (`--fields` 或 `--name --type`) | 入参与 `field create` 完全一致 |
+| `form questions delete` | 删除题目 | `--base-id` `--table-id` `--field-id` `--yes` | 入参与 `field delete` 完全一致；不可逆；批量需多次调用 |
+
+## form share 子命令
+
+| 命令 | 用途 | 必填参数 | 说明 |
+|------|------|----------|------|
+| `form share get` | 获取分享配置 | `--base-id` `--table-id` `--view-id` | 返回 enabled/status/shareFormUuid |
+| `form share update` | 开启/关闭分享 | `--base-id` `--table-id` `--view-id` `--enabled` | `--enabled true` 开启 / `--enabled false` 关闭。注意：UI 上"发布并分享"按钮是另一概念，本命令只切换内部 enabled 标志，开启后需在 UI 刷新页面才会看到分享面板 |
+
+## 完整工作流示例
+
+> **占位符约定**：
+> - `BASE_ID` 来自 `dws aitable base list` / `base search` 返回的 `data.bases[].baseId`
+> - `TABLE_ID` 来自 `dws aitable base get --base-id BASE_ID` 返回的 `data.tables[].tableId`
+> - `VIEW_ID` 来自步骤 1 `form create` 返回的 `data.viewId`
+> - `FIELD_ID` 来自步骤 2 `form questions create` 返回的 `data.results[].fieldId`
+
+```bash
+# 1) 创建表单 → 取返回的 data.viewId 作为 VIEW_ID
+dws aitable form create --base-id BASE_ID --table-id TABLE_ID --name "员工信息收集" --format json
+
+# 2) 添加题目 → 取返回的 data.results[].fieldId 作为 FIELD_ID
+dws aitable form questions create --base-id BASE_ID --table-id TABLE_ID \
+  --fields '[{"fieldName":"姓名","type":"text"},{"fieldName":"邮箱","type":"text"}]' --format json
+
+# 3) 配置表单标题与描述
+dws aitable form update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID \
+  --title "员工信息收集" --description "请填写您的基本信息" --format json
+
+# 4) 设置题目必填（FIELD_ID 来自步骤 2）
+dws aitable form field update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID \
+  --field-id FIELD_ID --required true --format json
+
+# 5) 隐藏不需要的题目
+dws aitable form field hide --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID \
+  --field-id FIELD_ID --hidden true --format json
+
+# 6) 开启分享（注意：开启后需 UI 刷新页面才会看到分享面板）
+dws aitable form share update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID \
+  --enabled true --format json
+```
+
+## 返回结构补充
+
+- `form list` 返回 `data.formViews[]`，**每条仅含** `viewId/name/title/createdAt`；`shareFormUuid` 不在此返回，请用 `form share get` 单独获取。
+- `form get` 返回结构与 `form list` 完全一致（`data.formViews[]`），仅含一条记录（与请求 viewId 一致）。Agent 提取时仍走 `data.formViews[0]`。
+- `form field list` 仅返回**未隐藏**的字段；`hidden=true` 的字段不在此返回，如需查看全部字段请用 `field get`。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-formula-guide.md

@@ -0,0 +1,224 @@
+# AI 表格公式字段指南
+
+> 当用户要创建 formula 类型字段、编写表内计算公式、做派生指标时，必须先读本文档。
+
+## 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` 表达式，系统会自动重新计算所有记录。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-primary-doc.md

@@ -0,0 +1,58 @@
+# 主键文档管理
+
+## 适用场景
+
+当需要为 AI 表格中的记录创建或查询关联的主键文档时使用。主键文档是 primaryDoc 类型字段对应的钉钉在线文档，可通过 `dws doc` 进行内容读写。
+
+若任务包含创建或关联主键文档，必须在首次建表前读取本文件，并把 `primaryDoc` 直接作为新表首字段；不要先以普通 `text` 首字段建表，再删除表、字段或记录重建。
+
+## 命令
+
+### 查询主键文档
+
+```bash
+dws aitable +record-primary-doc-get --base-id BASE_ID --table-id TABLE_ID --record-id RECORD_ID
+```
+
+**参数：**
+- `--base-id`（必填）：Base ID
+- `--table-id`（必填）：Table ID
+- `--record-id`（必填）：Record ID
+
+**返回：** `data.nodeId` — 主键文档的 nodeId，可直接传给 `dws doc read/update` 的 `--node` 参数。若该记录尚未创建主键文档，`nodeId` 为 null。
+
+### 创建主键文档
+
+```bash
+dws aitable +record-primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID
+```
+
+**参数：**
+- `--base-id`（必填）：Base ID
+- `--table-id`（必填）：Table ID
+- `--field-id`（必填）：主键字段 ID，必须是 primaryDoc 类型（通过 `dws aitable field get` 查看字段类型）
+- `--record-id`（必填）：Record ID
+
+**返回：** `data.nodeId` — 创建或已存在的主键文档 nodeId。
+
+**幂等性：** 若该记录已有主键文档，直接返回已有文档的 nodeId，不会重复创建。
+
+## 注意事项
+
+- `fieldId` 必须是 primaryDoc 类型，否则返回 `INVALID_FIELD_TYPE` 错误
+- `primaryDoc` 是建表时的首字段能力，不能在已有普通首字段之后补建，也不能把普通字段改成 primaryDoc。需要该能力时应新建以 primaryDoc 为首字段的数据表并迁移数据；未经用户明确授权不要自动迁移。
+- 传入不存在的 `recordId` 会返回 `RECORD_NOT_FOUND` 错误
+- 创建后可通过 `dws doc update --node <nodeId>` 写入文档内容，或 `dws doc read --node <nodeId>` 读取
+
+## 典型工作流
+
+```bash
+# 1. 查询字段目录，拿到 primaryDoc 字段的 fieldId
+dws aitable field get --base-id BASE_ID --table-id TABLE_ID
+
+# 2. 为记录创建主键文档
+dws aitable +record-primary-doc-create --base-id BASE_ID --table-id TABLE_ID --field-id FIELD_ID --record-id RECORD_ID
+
+# 3. 拿到返回的 nodeId，用 dws doc 写入内容
+dws doc update --node <data.nodeId> --content "# 项目方案\n\n文档正文内容..."
+```

package/skills/dws/dingtalk-aitable/references/aitable/aitable-record-create.md

@@ -0,0 +1,52 @@
+# record create — 新增记录
+
+## 命令格式
+
+```
+Usage:
+  dws aitable record create [flags]
+Example:
+  dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> \
+    --records '[{"cells":{"fldTextId":"文本内容","fldNumId":123}}]'
+Flags:
+      --base-id string        Base ID (必填)
+      --records string        记录列表 JSON 数组，单次最多 100 条 (必填，与 --records-file 二选一)
+      --records-file string   从文件读取 records JSON（替代 --records，适合超长数据或 Windows 环境）
+      --table-id string       Table ID (必填)
+```
+
+## Windows / 超长 JSON 推荐
+
+将 records JSON 写入文件，用 `--records-file ./records.json` 传入，避免命令行截断和引号转义问题。
+
+## 常见错误（严格避免）
+
+| 错误 | 说明 |
+|------|------|
+| 参数名用 `--data` | ❌ 参数名是 `--records`，不是 `--data` |
+| cells key 用字段名 | ❌ cells key 必须是 fieldId（如 `fldXXX`），不是字段名称（如 `"课程名称"`） |
+| 不先获取 fieldId | ❌ 必须先 `field get` 获取 fieldId，再写入记录 |
+| 单次超 100 条 | ❌ 单次最多 100 条，超过需分批 |
+| 附件/图片字段直传 URL | ❌ 严禁 `{"url":"https://..."}` — 会触发 TIMEOUT_ERROR。必须先 `attachment upload` 获取 `fileToken`，再用 `{"fileToken":"ft_xxx"}` 写入。详见 [aitable-attachment.md](./aitable-attachment.md) |
+
+## 正确流程
+
+```bash
+# 先获取 fieldId
+dws aitable field get --base-id <BASE_ID> --table-id <TABLE_ID> --format json
+# 从返回中提取 fieldId（如 fldABC123）
+
+# 再用 fieldId 写入记录
+dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"cells":{"fldABC123":"Python入门"}}]' --format json
+
+# 从创建响应的 data.newRecordIds[] 提取新 ID，并回读确认真实写入值
+dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --record-ids <NEW_RECORD_ID> --format json
+```
+
+创建成功以 `data.newRecordIds[]` 为 ID 来源；不要把整个 `data` 当作单个 recordId，也不要只以退出码作为写入成功证据。
+
+## cells 写入格式
+
+各字段类型的写入格式见 [aitable-cell-value.md](./aitable-cell-value.md)。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-record-delete.md

@@ -0,0 +1,20 @@
+# record delete — 删除记录
+
+## 命令格式
+
+```
+Usage:
+  dws aitable record delete [flags]
+Example:
+  dws aitable record delete --base-id <BASE_ID> --table-id <TABLE_ID> --record-ids rec1,rec2 --yes
+Flags:
+      --base-id string      Base ID (必填)
+      --record-ids string   待删除记录 ID 列表，逗号分隔，最多 100 条 (必填)
+      --table-id string     Table ID (必填)
+```
+
+## 注意事项
+
+- **不可逆操作**，调用前建议先 `record query` 确认目标记录
+- 需要先通过 `record query` 获取 recordId
+- 单次最多删除 100 条记录

package/skills/dws/dingtalk-aitable/references/aitable/aitable-record-history.md

@@ -0,0 +1,97 @@
+# 行记录变更历史（record history-list）
+
+按 recordId 查询单条记录的全部变更历史，用于审计、回溯字段变更、定位操作人。
+
+## 命令
+
+```
+dws aitable record history-list \
+  --base-id BASE_ID --table-id TABLE_ID --record-id REC_ID \
+  [--offset N] [--limit M]
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 所属 Base ID（必填，可用 `--base` 别名） |
+| `--table-id` | 所属 Table ID（必填） |
+| `--record-id` | 目标记录 ID（必填，单条；不支持批量） |
+| `--offset` | 分页偏移量，默认 0 |
+| `--limit` | 每页返回数量，范围 [1, 50]，默认 20 |
+
+## 返回结构
+
+```jsonc
+{
+  "data": {
+    "histories": [
+      {
+        "type": "field_change",           // 变更类型
+        "action": "update",               // 操作动作: create / update / delete
+        "newValue": "{\"...\":\"...\"}",  // 变更后的值（JSON 字符串）
+        "oldValue": "{\"...\":\"...\"}",  // 变更前的值（JSON 字符串）
+        "operateTime": 1733123456789,     // 操作时间（毫秒级时间戳）
+        "typeChangedFields": "{...}",     // 类型变更的字段信息（JSON 字符串）
+        "version": 7                      // 版本号（单调递增）
+      }
+    ]
+  }
+}
+```
+
+`newValue` / `oldValue` / `typeChangedFields` 是 JSON 字符串（不是 JSON 对象），需要二次 `JSON.parse` 才能拿到结构化值。
+
+## 字段含义速查
+
+| 字段 | 用途 |
+|------|------|
+| `type` | 高层分类：`record_create` / `field_change` / `record_delete` 等。先按 type 过滤大类。 |
+| `action` | 三态：`create` / `update` / `delete`。比 type 粗，但便于按"动作"统计。 |
+| `version` | 单调递增整数；同一 record 越新值越大。**用作"上一条 vs 这一条"的稳定排序键**。 |
+| `operateTime` | 毫秒时间戳；可格式化成可读时间。多条同 version 的极端场景用 operateTime 兜底排序。 |
+
+## 典型用法
+
+### 1. 看一条记录被改过几次
+
+```bash
+dws aitable record history-list --base-id BASE --table-id TBL --record-id REC --format json \
+  | jq '.data.histories[] | {version, action, operateTime}'
+```
+
+### 2. 翻页拉全量历史
+
+```bash
+# 第 1 页（最新 20 条）
+dws aitable record history-list --base-id BASE --table-id TBL --record-id REC --limit 50 --offset 0
+
+# 第 2 页
+dws aitable record history-list --base-id BASE --table-id TBL --record-id REC --limit 50 --offset 50
+```
+
+`limit` 上限 50，需要更多请增加 `offset` 翻页。
+
+### 3. 回溯某字段最近一次值
+
+```bash
+dws aitable record history-list --base-id BASE --table-id TBL --record-id REC --limit 50 --format json \
+  | jq '[.data.histories[] | select(.action == "update")][0].oldValue'
+```
+
+### 4. 找出删除事件（如果存在 delete history）
+
+```bash
+dws aitable record history-list --base-id BASE --table-id TBL --record-id REC --format json \
+  | jq '.data.histories[] | select(.action == "delete") | {version, operateTime}'
+```
+
+## 注意事项
+
+- 一次只能查一条 record；如需批量审计多条记录请循环调用。
+- 仅返回**字段值变更**与**记录生命周期事件**；视图、字段定义、表结构变更不在此 history 里。
+- 历史保留时长由 server 决定，过老的记录可能不再返回。
+
+## 与其他 record 命令的关系
+
+- 想看记录"现在长什么样" → `record query` / `record get`
+- 想看记录"过去长什么样、什么时候改的" → `record history-list`（本命令）
+- 想看"这张表整体改过什么" → 当前 CLI 不支持表级 history；只能逐 record 查

package/skills/dws/dingtalk-aitable/references/aitable/aitable-record-name-key.md

@@ -0,0 +1,47 @@
+# 行命名规则枚举键（recordNameKey）映射
+
+`dws aitable table update --record-name-key <枚举键>` 用于设置数据表的"行命名规则"——卡片/详情页里"行"的展示别名。**取值是固定枚举，不是字段 ID**；传非法值服务端返回 `INVALID_RECORD_NAME_KEY`。
+
+## 中文 → 枚举键（按 UI 下拉顺序）
+
+| 用户说 | --record-name-key | 用户说 | --record-name-key |
+|---|---|---|---|
+| 记录 | `ji_lu`（默认） | 项目 | `project` |
+| 任务 | `task` | 事件 | `event` |
+| 请求 | `request` | 活动 | `campaign` |
+| 目标 | `objective` | 交付物 | `deliverable` |
+| 资产 | `asset` | 客户 | `customer` |
+| 订单 | `order` | 联系人 | `contact` |
+| 物料/物品 | `item` | 问题 | `question` 或 `issue` |
+| 工单 | `ticket` | 候选人 | `candidate` |
+| 商机/机会 | `opportunity` | 会议 | `meeting` |
+| 成员 | `member` | OKR | `okr` |
+
+## 其他常用键（按场景分组）
+
+- **业务流程**：`approval` / `application` / `case` / `decision` / `delivery` / `payment` / `purchase_order` / `quote` / `release`
+- **HR / 财务**：`employee` / `expense` / `budget` / `invoice`
+- **产品 / 研发**：`feature` / `feedback` / `idea` / `bug` / `requirement` / `risk` / `sprint` / `story` / `subtask` / `epic`
+- **CRM**：`account` / `lead` / `prospect` / `deal`
+- **运营 / 支持**：`note` / `report` / `topic` / `session` / `service`
+- **资源 / 通用**：`file` / `document` / `product` / `team` / `user` / `vendor` / `key_result` / `metric`
+
+完整集合较大（共 273 个），服务端校验；以上未列出的合法键也可直接传（如 `goal` / `okr` / `pillar` / `phase` / `milestone` 等）。
+
+## 使用示例
+
+```bash
+# 用户说"把这张表的行叫'任务'吧" → 传 task
+dws aitable table update --base-id BASE --table-id TBL --record-name-key task
+
+# 用户说"换成项目" → 传 project
+dws aitable table update --base-id BASE --table-id TBL --record-name-key project
+
+# 用户说"恢复成默认（记录）" → 传 ji_lu
+dws aitable table update --base-id BASE --table-id TBL --record-name-key ji_lu
+```
+
+## 注意
+
+- recordNameKey **不会在 `table get` 响应里回显**（`get_tables` DTO 设计上不暴露该字段）；写入是否成功以 `table update` 的 set response 是否回填 `recordNameKey` 字段为准。
+- 中文别名是 server 内置 i18n，UI 显示用户对应的国际化文案，CLI 必须传英文枚举键。