dsh-crwu-workbench 0.0.10

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

@@ -0,0 +1,120 @@
+# record query — 查询记录
+
+## 命令格式
+
+```
+Usage:
+  dws aitable record query [flags]
+Example:
+  dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID>
+  dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --record-ids rec1,rec2
+  dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --query "关键词" --limit 50
+Flags:
+      --base-id string      Base ID (必填)
+      --cursor string       分页游标，首次不传
+      --field-ids string    返回字段 ID 列表，逗号分隔，单次最多 100 个
+      --filters string      结构化过滤条件 JSON
+      --query string        全文关键词搜索
+      --limit int           单次最大记录数，默认 100，最大 100
+      --record-ids string   指定记录 ID 列表，逗号分隔，单次最多 100 个
+      --sort string         排序条件 JSON 数组
+      --table-id string     Table ID (必填)
+      --all                 启用自动翻页，循环获取并合并所有记录后统一输出
+      --page-limit int      自动翻页最大页数（仅 --all 时生效）。默认 50，设为 0 表示无限制
+```
+
+两种模式: 按 ID 取（传 record-ids，忽略 filters/sort）或条件查（filters+sort+cursor 分页）。
+
+## 自动翻页（--all + --page-limit）
+
+- 传入 `--all` 启用自动翻页，CLI 自动循环获取并合并所有记录后统一输出
+- `--page-limit` 控制最大翻页次数，默认 50 页（5000 条），设为 0 表示无限制
+- 页间间隔 200ms，中途网络错误会 graceful stop 并输出已获取的数据
+- **被截断时**（达到 page-limit 但仍有数据）：输出中包含 `"hasMore": true` 和 `"cursor": "..."` 字段，可通过 `--cursor` 从断点继续拉取
+- 适用于需要一次性获取全量数据的场景（如导出、统计、批量处理）
+
+```bash
+# 默认（最多 50 页 = 5000 条）
+dws aitable record query --base-id X --table-id Y --all
+# 无限制（拉完为止）
+dws aitable record query --base-id X --table-id Y --all --page-limit 0
+# 从上次断点继续
+dws aitable record query --base-id X --table-id Y --all --cursor "上次返回的cursor"
+```
+
+## 排序参数规范
+
+`--sort` 需要传 JSON 数组，排序方向字段必须是 `direction`（`asc` 或 `desc`），不要使用 `order`。
+
+正确示例：
+```bash
+--sort '[{"fieldId":"wm8ns9bw2vmucb45xj3ix","direction":"desc"}]'
+```
+
+## filters 结构
+
+详细语法见 [aitable-filter-sort.md](./aitable-filter-sort.md)。
+
+快速模板：
+```json
+{"operator":"and","operands":[{"operator":"eq","operands":["<fieldId>","<value>"]}]}
+```
+
+> **singleSelect/multipleSelect 过滤**：filters 中可传 option id 或 option name，但建议优先用 **option id**（通过 `field get` 获取），更可靠。
+
+## 减少响应体积
+
+字段较多时，用 `--field-ids` 仅返回需要的字段，可显著减少返回数据量。
+
+## 常见错误
+
+- `--filters` 根节点直接用 `"operator":"eq"` → API 静默忽略，返回全表
+- `--sort` 用 `"order":"desc"` → 必须用 `"direction":"desc"`
+- 不加 `--field-ids` 拉全字段 → 大表响应体积过大
+- 全量拉取后在 context 里手动统计 → 应优先用 `--filters` 服务端过滤
+
+## record query-empty — 找空行
+
+`record query-empty` 是与 `record query` 平行的独立子命令，专门按表内顺序扫描出"完全没填用户字段"的空行。
+
+```bash
+dws aitable record query-empty --base-id BASE_ID --table-id TABLE_ID
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` / `--base` | 必填 |
+| `--table-id` | 必填 |
+| `--limit` | 单次**扫描预算**（不是返回数）；范围 [1, 100]，默认 100 |
+| `--cursor` | 分页游标。响应中 `nextCursor` 非空 → 用它翻页继续扫；nextCursor 为空（或不存在）→ 已扫完整表 |
+
+返回结构：
+
+```jsonc
+{ "data": { "records": [...], "nextCursor": "..." } }
+```
+
+### 关键语义
+
+1. **`--limit` 是扫描预算不是返回数**：可能扫了 100 条但全部非空，本页 `records: []`。
+2. **本页空 records ≠ 全表无空行**：必须看 `nextCursor`，nextCursor 还在就要继续翻。
+3. **空行定义**：除系统字段（recordId / 创建人 / 创建时间 / 修改人 / 修改时间）外，所有 cell 都是 null、空字符串、空集合或空 Map。一般是用户在 UI 上"插入空行"产生的。
+
+### 典型用法
+
+```bash
+# 扫一页，看本页有没有空行
+dws aitable record query-empty --base-id BASE --table-id TBL
+
+# 翻页
+dws aitable record query-empty --base-id BASE --table-id TBL --cursor <上次的nextCursor>
+
+# 把整表扫完（手动循环 cursor）
+NC=""
+while : ; do
+  R=$(dws aitable record query-empty --base-id BASE --table-id TBL ${NC:+--cursor "$NC"} --format json)
+  echo "$R" | jq '.data.records[] | .recordId'
+  NC=$(echo "$R" | jq -r '.data.nextCursor // empty')
+  [ -z "$NC" ] && break
+done
+```

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

@@ -0,0 +1,54 @@
+# 行记录分享链接（record share-url）
+
+按 recordId 批量获取记录的分享链接，把某行单独发给同事查看。
+
+## 命令
+
+```
+dws aitable record share-url \
+  --base-id BASE_ID --table-id TABLE_ID \
+  --record-ids rec1,rec2,rec3 \
+  [--view-id VIEW_ID]
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 所属 Base ID（必填，可用 `--base` 别名） |
+| `--table-id` | 所属 Table ID（必填） |
+| `--record-ids` | 目标 Record ID 列表，CSV 逗号分隔，**单次最多 20 条**（必填） |
+| `--view-id` | 视图 ID（可选）。带上后链接打开会落在该视图上下文里 |
+
+## 返回结构
+
+```jsonc
+{
+  "data": {
+    "items": [
+      { "recordId": "rec1", "shareUrl": "https://..." },
+      { "recordId": "rec2", "shareUrl": "https://..." }
+    ]
+  }
+}
+```
+
+`shareUrl` 为 null 表示该条获取失败（不影响其他条目）。
+
+## 典型用法
+
+```bash
+# 一次拿一条记录的链接
+dws aitable record share-url --base-id BASE --table-id TBL --record-ids rec1
+
+# 批量拿，配合 jq 过滤出 url
+dws aitable record share-url --base-id BASE --table-id TBL --record-ids rec1,rec2,rec3 --format json \
+  | jq '.data.items[] | {recordId, shareUrl}'
+
+# 带视图上下文（链接打开时落在指定视图）
+dws aitable record share-url --base-id BASE --table-id TBL --record-ids rec1 --view-id viw_VIP
+```
+
+## 注意事项
+
+- **单次最多 20 条**，超出请客户端拆批。
+- 该链接是分享链接（不是源文档链接），打开后看到的是该 record 的只读详情页。
+- 取消单条分享 / 关闭整表分享当前 CLI 不支持，需要在 AI 表格 Web 端操作。

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

@@ -0,0 +1,59 @@
+# record stats / group-stats — 服务端聚合统计
+
+统计任务优先使用服务端聚合，不要先用 `record query --all` 下载全表再计算。
+
+## 命令选择
+
+| 需求 | 命令 | 底层接口 |
+|------|------|----------|
+| 总数、求和、平均值、最大/最小值、中位数、完整率等标量统计 | `record stats` | `query_records_stats` |
+| 按字段分组统计 | `record group-stats` + `--group` | `query_stats` |
+| 满足条件的唯一门店/客户/商品数量 | `record group-stats` + `distinct`，不传 `--group` | `query_stats` |
+
+## 不分组统计
+
+```bash
+dws aitable record stats \
+  --base-id <BASE_ID> \
+  --table-id <TABLE_ID> \
+  --stats '[{"fieldId":"<FIELD_ID>","statsType":"COUNT"}]' \
+  --format json
+```
+
+- `statsType` 必须大写。
+- `--stats` 单次最多 20 项，同一 `fieldId` 不得重复；同字段多个指标拆成多次调用。
+- 支持基础类型 `COUNT`、`COUNT_COLUMN`、`SUM`、`AVG`、`MAX`、`MIN`，以及运行时支持的 `MEDIAN`、`STANDARD_DEVIATION`、`RANGE`、`DISTINCT`、`DISTINCT_RATIO`、完整率、勾选率和日期统计类型。
+- 统计全部匹配记录时省略 `--limit`；传入 limit 会改变统计范围。
+- 可选参数：`--filters`、`--sort`、`--keyword`、`--search-field-ids`、`--data-version`。
+
+## 分组或去重统计
+
+```bash
+dws aitable record group-stats \
+  --base-id <BASE_ID> \
+  --table-id <TABLE_ID> \
+  --group '[{"fieldId":"<GROUP_FIELD_ID>","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' \
+  --stats '[{"fieldId":"<VALUE_FIELD_ID>","statsType":"avg"}]' \
+  --limit 1000 \
+  --format json
+```
+
+- `statsType` 必须小写；基础类型为 `sum`、`avg`、`count`、`max`、`min`，后端还可能支持 `median`、`distinct`、`distinct_ratio` 等高级类型。
+- `--group` 和 `--sort` 都是 JSON 数组编码后的字符串，CLI 会原样映射到 MCP 的 `group` / `sortDsl`。
+- 分组结果最多 1000 行。不要依赖服务端 limit 选择 Top N；应在基数不超过 1000 时取完整分组结果后排序。
+- 条件唯一实体计数不传 `--group`，对实体字段使用 `distinct`。
+
+## 过滤条件
+
+```bash
+--filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}'
+```
+
+- 根节点必须是 `and` / `or`。
+- `lt`、`gt`、`lte`、`gte` 的值必须是 JSON 数字，不能写成数字字符串。
+- 单选/多选字段建议使用 `field get` 返回的 option ID。
+- 所有 Base、table、field 和 option ID 都必须从当前目标 Base 的实时元数据取得，不能复用示例或历史 ID。
+
+## 降级边界
+
+只有用户要求记录明细、少量校验样本、精确分位数输入，或聚合接口明确失败时，才使用 `record query`。需要先逐行运算再聚合的指标必须依赖表内已有且可直接聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能遍历全表本地二次计算。

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

@@ -0,0 +1,66 @@
+# record update — 更新记录
+
+## 命令格式
+
+```
+Usage:
+  dws aitable record update [flags]
+Example:
+  dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+    --records '[{"recordId":"recXXX","cells":{"fldStatusId":"已完成"}}]'
+Flags:
+      --base-id string        Base ID (必填)
+      --records string        待更新记录 JSON 数组，单次最多 100 条；cells key 支持 fieldId 或当前表内唯一字段名，推荐 fieldId (必填，与 --records-file 二选一)
+      --records-file string   从文件读取 records JSON（替代 --records，适合超长数据或 Windows 环境）
+      --table-id string       Table ID (必填)
+```
+
+只需传入需修改的字段，未传入的保持原值。每条记录必须含 recordId 和 cells。
+
+## cells key：优先使用 fieldId，也支持唯一字段名
+
+`cells` 的 key 有两种写法：
+
+- fieldId（推荐）：不受字段重命名或重名影响，通过 `field get` 获取。
+- 当前表内唯一的字段名：按名称精确匹配；如果存在同名字段，必须改用 fieldId。
+
+同一字段同时通过 fieldId 和字段名传入时，fieldId 对应的值优先。
+
+```bash
+# 推荐：fieldId
+dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"recordId":"recXXX","cells":{"fldStatusId":"已完成"}}]' --format json
+
+# 便捷写法：当前表内唯一字段名
+dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"recordId":"recXXX","cells":{"状态":"已完成"}}]' --format json
+```
+
+## 推荐参数形式
+
+公开、稳定的批量入口是 `--records`（或 `--records-file`），格式为 JSON 数组；即使只改一条记录，推荐也包在数组里。CLI 仍保留隐藏的 `--record-id` + `--cells` 兼容入口，但它不会出现在常规帮助中，自动化脚本应优先使用 `--records`。
+
+| 不推荐或无效写法 | 推荐写法 |
+|---|---|
+| `--record-id recXXX --cells '{"fldX":"值"}'`（隐藏兼容入口） | `--records '[{"recordId":"recXXX","cells":{"fldX":"值"}}]'` |
+| `--id recXXX --data '{"fldX":"值"}'` | 同上 |
+| `--record-id recXXX --field fldX --value "新值"` | 同上 |
+
+## 单条更新模板（直接复制）
+
+```bash
+dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"recordId":"<RECORD_ID>","cells":{"<FIELD_ID>":"新值"}}]' --format json
+
+# 从更新响应的 data.recordIds[] 提取成功记录 ID，并回读确认真实值
+dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --record-ids <RECORD_ID> --format json
+```
+
+更新响应不返回“受影响字段”；以 `data.recordIds[]` 确定成功记录，再用查询回读验证。
+
+## 引号转义提示
+
+- Linux/macOS：外层用单引号 `'[...]'`，内部 JSON 用双引号即可
+- Windows PowerShell：外层用双引号 `"[...]"`，内部双引号需转义为 `\"`
+- 或将 JSON 写入临时文件，用 `--records-file ./records.json` 规避转义

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

@@ -0,0 +1,89 @@
+# 行记录 Upsert（record upsert）
+
+按 `recordId` 是否存在，自动把入参拆分到 update 链路或 create 链路：批次混合"已存在改 + 新出现建"时用，省掉客户端按 ID 分批的逻辑。
+
+## 命令
+
+```
+dws aitable record upsert \
+  --base-id BASE_ID --table-id TABLE_ID \
+  --records '[{"recordId":"<可选>","cells":{...}}, ...]'
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 必填（可用 `--base` 别名） |
+| `--table-id` | 必填 |
+| `--records` | 待 upsert 的记录 JSON 数组，**单次最多 100 条**（必填）|
+| `--records-file` | 从文件读入（命令行 JSON 太长时用），与 `--records` 互斥优先级更高 |
+
+## --records 结构
+
+每项 JSON：
+
+```jsonc
+{
+  "recordId": "rec1",                  // 可选；带 → update，缺省 → create
+  "cells": {                            // 必填；key 是 fieldId，value 按字段类型
+    "fldTitleId": "新标题",
+    "fldNumberId": 42
+  }
+}
+```
+
+`cells` 写入格式与 `record create` / `record update` **完全一致**（key 必须是 fieldId 不是字段名；按字段类型见 [aitable-cell-value.md](./aitable-cell-value.md)）。
+
+## 返回结构
+
+```jsonc
+{
+  "data": {
+    "createdRecordIds": ["recX", "recY"],   // 不带 recordId 的项产出
+    "updatedRecordIds": ["recA", "recB"]    // 带 recordId 的项产出
+  }
+}
+```
+
+`createdRecordIds` 顺序对应入参里**不带 recordId**的项（按出现顺序汇总），同理 `updatedRecordIds` 对应**带 recordId**的项。
+
+## 典型用法
+
+```bash
+# 1) 全部新建：所有项都不带 recordId
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"cells":{"fldTitleId":"任务1","fldStatusId":"待办"}},
+  {"cells":{"fldTitleId":"任务2","fldStatusId":"待办"}}
+]'
+
+# 2) 全部更新：所有项都带 recordId
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
+  {"recordId":"rec2","cells":{"fldStatusId":"已完成"}}
+]'
+
+# 3) 混合：第 1 条更新（带 recordId），第 2 条创建（不带）
+dws aitable record upsert --base-id BASE --table-id TBL --records '[
+  {"recordId":"rec1","cells":{"fldStatusId":"已完成"}},
+  {"cells":{"fldTitleId":"新增任务","fldStatusId":"待办"}}
+]'
+
+# 4) 长 JSON 用文件
+dws aitable record upsert --base-id BASE --table-id TBL --records-file ./batch.json
+```
+
+## 与 record create / record update 的关系
+
+| 场景 | 命令 |
+|------|------|
+| 确定全是新增 | `record create` |
+| 确定全是更新（每条独立 cells） | `record update` |
+| 确定全是更新（共享同一 cells） | `record batch-update` |
+| **不确定有没有，按 recordId 自动分流** | `record upsert`（本命令） |
+
+`record upsert` 的 `--records` 入参格式与 `record update` 完全相同，唯一差别是 `recordId` 字段在 upsert 里是可选的。如果批次确定全是更新或全是新建，用专用命令更清晰；批次混合时（典型场景：定时同步外部数据，源里既有已存在的也有新出现的），用 upsert。
+
+## 注意事项
+
+- **单次最多 100 条**（创建 + 更新合计），超出请客户端拆批。
+- `cells` 的 key 必须是 fieldId 不是字段名（先用 `record query` 或 `field get` 拿 fieldId）。
+- 只读字段（formula / lookup / 系统字段）不能写入 — upsert 链路与 update 链路同样限制。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-view-config.md

@@ -0,0 +1,140 @@
+# 视图布局与条件配置
+
+仅在任务涉及 filter/sort/group、列顺序、列宽或重命名时读取。本文自包含这些通用属性；Kanban/Gallery card、Gantt timebar、Grid aggregate 以及 lock/frozen-cols/row-height/fill-color-rule/duplicate 均由根 Skill 直接路由到各自 reference，不要连读多个视图 reference。
+
+按属性局部读/写视图配置；向后兼容的 `view update --config '{...}'` 仅用于一次写多个通用属性。
+
+## viewType × 支持矩阵
+
+| viewType | filter / sort / group | visible-fields | field-widths | name |
+|---|:---:|:---:|:---:|:---:|
+| Grid     | ✅ | ✅ | ✅ | ✅ |
+| Kanban   | ✅ | ✅ |    | ✅ |
+| Gallery  | ✅ | ✅ |    | ✅ |
+| Gantt    | ✅ | ✅ |    | ✅ |
+| Calendar | ✅ | ✅ |    | ✅ |
+| FormDesigner | （走 `form` 系列命令） | | | |
+
+## 创建：view create
+
+`--view-type` 支持 `Grid`、`Kanban`、`Gantt`、`Calendar`、`Gallery`、`FormDesigner`。创建时通过 `--config` JSON 设置可见字段：
+
+```bash
+# --config JSON：可同时配置可见字段、筛选、排序和分组；主字段必须排第一
+dws aitable view create --base-id BASE_ID --table-id TABLE_ID \
+  --view-type Grid --name "任务视图" \
+  --config '{"visibleFieldIds":["fldPrimary","fldStatus","fldOwner"],"sort":[{"fieldId":"fldStatus","direction":"asc"}]}'
+```
+
+创建阶段的 `--config` 是 JSON 对象，并且只接受以下 4 个 key：
+
+| key | 类型 | 说明 |
+|---|---|---|
+| `visibleFieldIds` | `string[]` | fieldId 数组，不接受字段名；至少一个，主字段必须排第一 |
+| `filter` | `object[]` | 筛选规则数组；兼容单个 object，CLI 会自动包装为数组 |
+| `sort` | `object[]` | 排序规则数组；兼容单个 object，CLI 会自动包装为数组 |
+| `group` | `object[]` | 分组规则数组；兼容单个 object，CLI 会自动包装为数组 |
+
+描述使用独立的 `--desc '{"content":[]}'`；`description`、`fieldWidths`、`aggregate`、`kanbanCard`、`ganttTimebar`、`galleryCard` 等其他 key 会在调用服务端前被拒绝，并提示对应的 `view update` 子命令。
+
+## 读取：view get <attr>
+
+所有 `view get <attr>` 共用 `--base-id` / `--table-id` / `--view-id`，输出是该属性子块的 JSON（不存在时输出 `{}`）。viewType 不匹配会报错并指明应该选哪种视图。
+
+```bash
+dws aitable view get filter --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json          # 所有
+dws aitable view get sort --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+dws aitable view get group --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+dws aitable view get visible-fields --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+dws aitable view get field-widths --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json    # Grid
+```
+
+## 写入：view update <attr>
+
+所有 `view update <attr>` 共用 `--base-id` / `--table-id` / `--view-id`。
+**typed flag + `--json` 可混用**；冲突时 typed flag 优先并 stderr 提示。
+
+### view update field-widths（仅 Grid）
+
+| flag | 类型 |
+|------|------|
+| `--field-id` + `--width` | string + int（单字段） |
+| `--json` | `{fldId: width, ...}` |
+
+```bash
+dws aitable view update field-widths --base-id BASE_ID --table-id TABLE_ID --view-id GRID_ID --field-id fldX --width 200
+dws aitable view update field-widths --base-id BASE_ID --table-id TABLE_ID --view-id GRID_ID --json '{"fldA":120,"fldB":200}'
+```
+
+### view update visible-fields（通用）
+
+整组替换可见字段列表与顺序。`field get` 返回的第一个字段是系统行索引/主字段；无论它显示为 text 还是 primaryDoc，都必须保留在数组第一位，且不能隐藏。不要仅凭字段类型猜主字段。
+
+> ⚠️ 注意：服务端**只接受 reorder，不接受真"隐藏字段"**——如果传入的列表比当前 columns 短，缺失的字段不会被隐藏。需要真正隐藏字段请到 AI 表格 Web UI。
+
+| flag | 类型 |
+|------|------|
+| `--field-ids` | string (CSV) |
+| `--json` | string 数组 JSON（与 `--field-ids` 同传时 `--json` 优先） |
+
+```bash
+dws aitable view update visible-fields --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --field-ids fldPrimary,fldA,fldB
+dws aitable view update visible-fields --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --json '["fldPrimary","fldA","fldB"]'
+```
+
+### 列顺序最短闭环
+
+用户说“客户名称最左、状态在金额前”时，不要用通用 `+view-update --config` 探索：
+
+1. `dws aitable field get --base-id <B> --table-id <T> --format json` 取字段有序列表；第一个 fieldId 固定为数组第 1 项。目标 viewId 从真实上下文或 `view get` 返回中取得。
+2. `dws aitable view get visible-fields --base-id <B> --table-id <T> --view-id <V> --format json` 取当前完整列数组；必须保留全部现有字段，因为该接口只支持 reorder，不是真隐藏。
+3. 只重排目标：`[主字段, 客户名称, ..., 状态, 金额, ...]`，其他字段保持相对顺序；一次执行 `view update visible-fields`。
+4. 再次 `view get visible-fields`，数组完全一致才算完成。遇到 `PRIMARY_FIELD_CANNOT_BE_MOVED/HIDDEN` 立即停止，重新按步骤 1 构造一次；禁止继续猜排列。
+
+“固定/冻结左侧列”与“放到最左边”不是同一操作。只有 Grid 支持冻结；若要冻结主字段后的目标列，需要冻结前 N 列（例如目标位于第 2 列则 count=2）：
+
+```bash
+dws aitable +view-set-frozen-cols --base-id <B> --table-id <T> --view-id <V> --count <N>
+dws aitable +view-get-frozen-cols --base-id <B> --table-id <T> --view-id <V>
+```
+
+Kanban/Gallery 等视图只调整列顺序，不尝试冻结。
+
+### view update filter / sort / group（通用，纯 --json）
+
+```bash
+dws aitable view update filter --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --json '[{"operator":"eq","operands":["fldX","value"]}]'
+dws aitable view update sort --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'
+dws aitable view update group --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'
+```
+
+> filter/sort/group 入参格式与 `record query --filters`（对象格式）**不同**：view config 这边外层必须是数组。传对象 CLI 会自动 wrap，建议直接用数组。详见 [aitable-filter-sort.md](./aitable-filter-sort.md)。
+
+### view update name（重命名）
+
+```bash
+dws aitable view update name --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --name "新视图名"
+```
+
+等价于 `dws aitable view update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --name "新视图名"`，无 `config` 参数。
+
+## 服务端字段速查（与 dws CLI 关系）
+
+| dws 子命令 | 服务端 `update_view.config` 子键 | 服务端 Java 模型 |
+|---|---|---|
+| `view update visible-fields` | `visibleFieldIds` | `List<String>` |
+| `view update filter / sort / group` | `filter` / `sort` / `group` | `List<Object>` |
+| `view update field-widths` | `fieldWidths` | `Map<String, Object>` |
+| `view update name` | （不在 config 内）`newViewName` 顶层 | — |
+
+## 典型工作流
+
+### 一次性多属性更新（仍走 legacy --config）
+
+```bash
+dws aitable view update --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --config '{
+  "visibleFieldIds":["fldPrimary","fldA","fldB"],
+  "filter":[{"operator":"eq","operands":["fldA","value"]}],
+  "sort":[{"fieldId":"fldA","direction":"asc"}]
+}'
+```