dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-aitable/references/aitable/aitable-cell-value.md

@@ -0,0 +1,346 @@
+# cells 写入/读取格式规范（cellValue 数据结构）
+
+> 适用命令：`dws aitable record create --records`、`dws aitable record update --records`、`dws aitable record query` 返回
+>
+> 本文件是 DWS AI 表格 cellValue 的 **source of truth**。写入记录时，必须严格按此格式构造 cells 对象。
+
+## 顶层规则
+
+- cells 的 key **必须是 fieldId**（如 `fldXXX`），不是字段名称
+- fieldId 必须从 `field get` 返回中获取
+- 不同字段类型的 value 格式不同，混用会报错
+- 系统只读字段（creator/lastModifier/createdTime/lastModifiedTime/formula）不可写入
+
+## 各字段类型详解
+
+### text（文本）
+
+**写入**：字符串
+```json
+{"fldTextId": "这是一段文本"}
+```
+
+**读取**：字符串
+```json
+{"fldTextId": "这是一段文本"}
+```
+
+---
+
+### number（数字）
+
+**写入**：数字或数字字符串
+```json
+{"fldNumId": 123.45}
+{"fldNumId": "123.45"}
+```
+
+**读取**：字符串形式的数字
+```json
+{"fldNumId": "123.45"}
+```
+
+---
+
+### singleSelect（单选）
+
+**写入**：选项名称字符串（推荐），或对象形式 `{id, name}`
+```json
+{"fldSelectId": "进行中"}
+{"fldSelectId": {"id": "opt_xxx", "name": "进行中"}}
+```
+
+> 写入不存在的选项名称时，系统会自动创建该选项。
+> 对象写入时 id 为准，服务端会校验 id 是否存在。
+
+**读取**：对象 `{id, name}`
+```json
+{"fldSelectId": {"id": "opt_abc123", "name": "进行中"}}
+```
+
+---
+
+### multipleSelect（多选）
+
+**写入**：选项名称数组（推荐），或对象数组
+```json
+{"fldMultiId": ["标签A", "标签B"]}
+{"fldMultiId": [{"id": "opt_a", "name": "标签A"}, {"id": "opt_b", "name": "标签B"}]}
+```
+
+> 写入时每项需带 id（对象模式）或直接传 name 字符串。不存在的 name 会自动补入选项配置。
+
+**读取**：对象数组
+```json
+{"fldMultiId": [{"id": "opt_a", "name": "标签A"}, {"id": "opt_b", "name": "标签B"}]}
+```
+
+---
+
+### date（日期）
+
+**写入**：日期字符串、RFC3339 字符串、或毫秒时间戳
+```json
+{"fldDateId": "2026-03-15"}
+{"fldDateId": "2026-03-15 09:00"}
+{"fldDateId": "2026-03-15T09:00+08:00"}
+```
+
+**读取**：RFC3339 字符串（带时区）
+```json
+{"fldDateId": "2026-03-15T09:00:00+08:00"}
+```
+
+**过滤**（`record query --filters`）：日期字段**只能用日期专用操作符** `date_eq` / `before` / `after` / `not_before` / `not_after` / `exist` / `un_exist`，比较值用日期字符串（如 `"2026-03-15"`）。
+- ❌ 通用 `eq` / `ne` / `gt` / `gte` / `lt` / `lte` / `contain` 对日期字段无效，会静默返回 0 条；
+- ❌ 不支持区间 `date_between` 与相对 `from_now`（CLI 会直接拒绝），范围查询用 `not_before` + `not_after` 组合。
+- 详见 [aitable-filter-sort.md](./aitable-filter-sort.md) §日期字段过滤。
+
+---
+
+### currency（货币）
+
+**写入**：数字（与 number 相同）
+```json
+{"fldCurrencyId": 99.5}
+```
+
+**读取**：字符串形式的数字（小数位数取决于 formatter 配置）
+```json
+{"fldCurrencyId": "99.5"}
+```
+
+---
+
+### progress（进度）
+
+**写入**：0~1 之间的浮点数（0 表示 0%，1 表示 100%）
+```json
+{"fldProgressId": 0.75}
+```
+
+> ⚠️ **常见错误**：写入 75 不会报错，但会被存储为 7500%（因为系统将其理解为 75 倍）。
+> 正确做法：75% 应写入 0.75。API 不会拒绝超出 [0,1] 的值，但显示会异常。
+> 如果字段配置了 `customizeRange`，则按自定义范围传值。
+
+**读取**：字符串形式的数字
+```json
+{"fldProgressId": "0.75"}
+```
+
+---
+
+### rating（评分）
+
+**写入**：整数，必须在字段配置的 min~max 范围内
+```json
+{"fldRatingId": 4}
+```
+
+> ⚠️ 超出 max 范围的值（如 max=5 时写入 6）会被服务端拒绝并返回错误。
+
+**读取**：数字（字符串形式）
+```json
+{"fldRatingId": "4"}
+```
+
+---
+
+### checkbox（勾选）
+
+**写入**：布尔值
+```json
+{"fldCheckId": true}
+{"fldCheckId": false}
+```
+
+**读取**：布尔值
+```json
+{"fldCheckId": true}
+```
+
+---
+
+### user（人员）
+
+**写入**：对象数组，每项必须含 `userId` 和 `corpId`
+```json
+{"fldUserId": [{"userId": "staff_001", "corpId": "dingxxxxxxxx"}]}
+```
+
+> 单选字段（`multiple=false`）也必须传数组，只是数组长度为 1。
+> 如果目标用户不在当前请求组织内，回退为 `[{"userRef": "ur_0AaZ19"}]`。
+
+**读取**：对象数组
+```json
+{"fldUserId": [{"userId": "staff_001", "corpId": "dingxxxxxxxx"}]}
+```
+
+---
+
+### department（部门）
+
+**写入**：对象数组，每项含 `deptId`
+```json
+{"fldDeptId": [{"deptId": "52528700"}]}
+```
+
+**读取**：对象数组
+```json
+{"fldDeptId": [{"deptId": "52528700"}]}
+```
+
+---
+
+### group（群组）
+
+**写入**：对象数组，每项含 `cid`
+```json
+{"fldGroupId": [{"cid": "74577067501"}]}
+```
+
+> ⚠️ key 是 **`cid`**，不是 `openConversationId`
+
+**读取**：对象数组
+```json
+{"fldGroupId": [{"cid": "74577067501"}]}
+```
+
+---
+
+### url（链接）
+
+**写入**：对象 `{text, link}` 或纯 URL 字符串
+```json
+{"fldUrlId": {"text": "钉钉官网", "link": "https://dingtalk.com"}}
+{"fldUrlId": "https://dingtalk.com"}
+```
+
+> 纯字符串写入时，服务端自动补齐为 `{"text":"原字符串","link":"原字符串"}`
+
+**读取**：对象 `{text, link}`
+```json
+{"fldUrlId": {"text": "钉钉官网", "link": "https://dingtalk.com"}}
+```
+
+---
+
+### richText（富文本）
+
+**写入**：对象 `{markdown: "..."}`
+```json
+{"fldRichId": {"markdown": "**加粗**\n普通文字\n"}}
+```
+
+**读取**：对象 `{markdown: "..."}`（有损，颜色/@人等信息可能丢失）
+```json
+{"fldRichId": {"markdown": "**加粗**\n普通文字\n"}}
+```
+
+---
+
+### attachment（附件）
+
+**写入**：对象数组，**必须使用 `fileToken`**
+
+```json
+{"fldAttachId": [{"fileToken": "ft_xxx"}]}
+```
+
+> ⚠️ **必须先通过 [attachment upload 流程](./aitable-attachment.md) 上传文件获取 `fileToken`，再将 `fileToken` 写入 cells。**
+> ❌ **严禁直接传 `{"url": "https://..."}` 形式写入附件/图片字段** — 服务端会同步下载图片，10 条记录即触发 TIMEOUT_ERROR 超时。
+> 写入会**整体覆盖**原附件列表，不是追加。
+
+**读取**：对象数组（含下载链接、文件名、大小）
+```json
+{"fldAttachId": [{"url": "https://...", "filename": "report.pdf", "size": 204800}]}
+```
+
+---
+
+### telephone / email / barcode / idCard（电话/邮箱/条码/身份证）
+
+**写入**：字符串
+```json
+{"fldPhoneId": "13800138000"}
+{"fldEmailId": "test@example.com"}
+{"fldBarcodeId": "978-3-16-148410-0"}
+{"fldIdCardId": "520402196001067498"}
+```
+
+> idCard 必须是后端认可的合法身份证号格式
+
+**读取**：字符串
+```json
+{"fldPhoneId": "13800138000"}
+```
+
+---
+
+### geolocation（地理位置）
+
+**写入**：对象，包含 `address`、`name`、`location`
+```json
+{
+  "fldGeoId": {
+    "address": "浙江省杭州市思凯路与爱橙街交叉口东南200米",
+    "name": "阿里中心·未科D1幢",
+    "location": ["120.007852", "30.271194"]
+  }
+}
+```
+
+> `location` 按 **[经度, 纬度]** 传**字符串数组**
+
+**读取**：对象（含额外的 `fullAddress` 字段，由服务端自动拼接）
+```json
+{
+  "fldGeoId": {
+    "address": "浙江省杭州市",
+    "fullAddress": "阿里中心-浙江省杭州市",
+    "name": "阿里中心",
+    "location": ["120.007852", "30.271194"]
+  }
+}
+```
+
+---
+
+### unidirectionalLink / bidirectionalLink（关联字段）
+
+**写入**：对象 `{linkedRecordIds: [...]}`
+```json
+{"fldLinkId": {"linkedRecordIds": ["recXXX", "recYYY"]}}
+```
+
+**读取**：对象 `{linkedRecordIds: [...]}`
+```json
+{"fldLinkId": {"linkedRecordIds": ["recXXX", "recYYY"]}}
+```
+
+---
+
+### 只读字段（禁止写入）
+
+以下字段类型由系统自动填充，`record create/update` 时**禁止传入**：
+
+| 类型 | 说明 |
+|------|------|
+| `creator` | 创建人 |
+| `lastModifier` | 最后编辑人 |
+| `createdTime` | 创建时间 |
+| `lastModifiedTime` | 最后编辑时间 |
+| `formula` | 公式字段（系统计算） |
+| AI 字段 | 由 AI 自动计算 |
+
+## 常见错误速查
+
+| 错误 | 正确做法 |
+|------|----------|
+| cells key 用字段名称 `"课程名称"` | 用 fieldId `"fldXXX"` |
+| progress 写入 `75` | 写入 `0.75`（范围 0~1） |
+| attachment 直接传文件路径或图片 URL | 必须先 `attachment upload` 获取 fileToken，再用 fileToken 写入（直传 URL 会超时） |
+| user 字段传用户名字符串 | 传对象数组 `[{"userId":"...", "corpId":"..."}]` |
+| group 字段用 `openConversationId` | 用 `cid` |
+| singleSelect 传 option id 字符串 | 传 name 字符串或 `{"id":"...", "name":"..."}` 对象 |
+| 对只读字段写入值 | 不传该字段，由系统自动填充 |

package/skills/dws/dingtalk-aitable/references/aitable/aitable-dashboard-chart.md

@@ -0,0 +1,46 @@
+# dashboard & chart — 专项配置
+
+仅在 Chart 创建/更新缺少 config，或 Dashboard 明确需要完整 config/自动布局时读取。普通 Dashboard 按名称创建、读取、改名或删除走根 Skill 直达，不读取本文。
+
+本文是 Dashboard/Chart 专项配置的终点；命令和参数已覆盖时直接执行，不再读取其他 AITable Reference 或 Help。
+
+## 专项配置最短路径
+
+```bash
+# Dashboard 完整 config 缺少结构时，只读取 Dashboard 模板
+dws aitable dashboard config-example --format json
+
+# Chart config 缺少结构时，只读取 Chart 模板
+dws aitable +chart-widgets-example --format json
+
+# 已有真实 ID 时按需读取详情
+dws aitable dashboard get --base-id <BASE_ID> --dashboard-id <DASHBOARD_ID> --format json
+dws aitable chart get --base-id <BASE_ID> --dashboard-id <DASHBOARD_ID> --chart-id <CHART_ID> --format json
+```
+
+## 要点
+
+- `dashboard get` 返回的 `charts[].chartId` 可直接给 `chart get` 使用
+- `chart share get` 可正常返回 `enabled/shareUrl`，用于分享状态判断
+- Dashboard 普通 CRUD 不在本文重新维护；需要完整配置时才读取 `dashboard config-example`
+
+## Dashboard 专项命令
+
+| 命令 | 用途 | 必填参数 | 说明 |
+|------|------|----------|------|
+| `dashboard config-example` | 查看完整仪表盘配置模板 | 无 | 仅在完整 config 结构缺失时调用一次 |
+| `dashboard arrange` | 自动重排图表布局 | `--base-id` `--dashboard-id` | 把图表按行铺满网格，避免某行只占半幅、留下大片空白；返回 `{totalColumns, layout, alignedChartCount}` |
+
+## chart 子命令
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `chart get` | 获取图表详情 | `--base-id` `--dashboard-id` `--chart-id` |
+| `chart create` | 创建图表 | `--base-id` `--dashboard-id` `--config` `--layout` |
+| `chart update` | 更新图表配置 | `--base-id` `--dashboard-id` `--chart-id` `--config` |
+| `chart delete` | 删除图表 | `--base-id` `--dashboard-id` `--chart-id` | 不可逆；由 Runtime 请求确认，Reference 不携带确认绕过参数 |
+| `+chart-widgets-example` | 查看所有图表类型的 widgets 模板 | 无 |
+
+## 配置获取流程
+
+已有符合当前 leaf Schema 的合法 config 时直接创建/更新，不读取模板。只有 Chart config 缺少结构时调用一次 `+chart-widgets-example`；该命令当前返回所有图表类型示例，随后只使用目标类型，并按真实 tableId/fieldId 填充后执行。Dashboard 完整 config 缺少结构时只调用一次 `dashboard config-example`，不要同时读取两个模板。

package/skills/dws/dingtalk-aitable/references/aitable/aitable-data-analysis-sop.md

@@ -0,0 +1,131 @@
+# AI 表格数据分析 SOP
+
+> 当用户诉求涉及查询、筛选、排序、统计、Top/Bottom N、分组聚合、判断全局结论时，必须先读本文档再执行。
+
+## 1. 查询决策树
+
+```
+用户要做什么？
+│
+├─ 查看/导出原始记录明细
+│   → record query [--filters] [--sort] [--field-ids] [--limit]
+│
+├─ 按条件筛选记录（如"状态=进行中的记录"）
+│   → record query --filters '{"operator":"and","operands":[...]}'
+│
+├─ 取 Top N / Bottom N（如"销售额最高的5条"）
+│   → record query --sort '[{"fieldId":"xxx","direction":"desc"}]' --limit 5
+│
+├─ 全量统计（如"一共多少条"、"所有记录的总销售额"）
+│   → record stats --stats '[{"fieldId":"...","statsType":"COUNT|SUM|AVG|..."}]'
+│
+├─ 分组统计（如"每个状态各有多少条"）
+│   → record group-stats --group '[...]' --stats '[{"fieldId":"...","statsType":"count"}]'
+│
+├─ 条件唯一实体数（如"有索赔单的门店共有多少家"）
+│   → record group-stats --filters '{...}' --stats '[{"fieldId":"<实体字段>","statsType":"distinct"}]'
+│
+└─ 判断全局结论（如"是否所有记录都满足条件"）
+    → record stats 对反向过滤结果 COUNT；只有需要行级证据时再 record query
+```
+
+## 2. 核心规则
+
+### 2.1 禁止基于默认分页下全局结论
+
+`record query` 默认返回 100 条。如果返回 JSON 中 `data.nextCursor` 非空，表示还有后续数据，当前结果**不是全量**。
+
+```json
+{"data": {"nextCursor": "3hf5MtLbLZ", "records": [...]}}
+```
+
+- ❌ 错误：只查了默认 100 条就说"共 100 条记录"
+- ✅ 正确：使用 `--all` 自动翻页拿全量，再统计
+
+### 2.2 能在服务端过滤的，不要拉到本地再过滤
+
+| 需求 | 正确做法 | 错误做法 |
+|------|---------|---------|
+| 筛选"状态=已完成" | `--filters '{"operator":"and","operands":[{"operator":"eq","operands":["fldXXX","已完成"]}]}'` | `--all` 拉全量再本地 filter |
+| 按日期降序取最新5条 | `--sort '[...]' --limit 5` | `--all` 拉全量再本地 sort + slice |
+| 模糊搜索标题含"Q1" | `--filters` 用 `contain` 操作符 | 全量拉取再本地 grep |
+
+### 2.3 聚合必须优先在服务端完成
+
+以下场景均有服务端聚合入口，不得先用 `record query --all` 下载全表计算：
+
+- `record stats`：不分组的 COUNT / SUM / AVG / MAX / MIN / MEDIAN / DISTINCT / 完整率等
+- `record group-stats`：分组统计，以及不带 group 的条件 DISTINCT 唯一计数
+- 任意条件比率：分别聚合分子与分母，再对齐范围和 `dataVersion` 计算
+
+只有用户要求记录明细、少量样本校验、精确分位数输入，或聚合接口明确返回不支持/错误时，才允许使用 `record query`。需要先逐行运算再聚合的指标（例如两个日期相减）必须使用表内已有且可聚合的公式字段；没有该字段时停止并请用户先在 AI 表格页面创建，不能下载全表本地二次计算。
+
+### 2.4 --all 使用注意
+
+```bash
+dws aitable record query \
+  --base-id <baseId> \
+  --table-id <tableId> \
+  --all \
+  --field-ids <只取需要的字段> \
+  --format json
+```
+
+- **必须配合 `--field-ids`** 限制返回字段，减少数据量
+- 对于大表（>1000条），先告知用户可能耗时
+- `--all` 会自动处理分页，无需手动翻页
+
+## 3. filters 快速参考
+
+详细语法见 [aitable-filter-sort.md](./aitable-filter-sort.md)。
+
+### 常用操作符速查
+
+| 操作符 | 适用类型 | 含义 | 示例 operands |
+|--------|---------|------|-------------|
+| `eq` | 通用 | 等于 | `["fldXXX", "值"]` |
+| `ne` | 通用 | 不等于 | `["fldXXX", "值"]` |
+| `gt` / `lt` | 数值/日期 | 大于/小于 | `["fldXXX", "25"]` |
+| `gte` / `lte` | 数值/日期 | 大于等于/小于等于 | `["fldXXX", "100"]` |
+| `contain` | 文本 | 包含 | `["fldXXX", "关键词"]` |
+| `exist` / `un_exist` | 通用 | 有值/为空 | `["fldXXX"]`（无第二参数） |
+| `any_of` | 多选 | 包含任一 | `["fldXXX", "选项A"]` |
+
+### filters 结构模板
+
+```json
+{
+  "operator": "and",
+  "operands": [
+    {"operator": "eq", "operands": ["<fieldId>", "<值>"]},
+    {"operator": "gt", "operands": ["<fieldId>", "<数值>"]}
+  ]
+}
+```
+
+## 4. 分析结果呈现规范
+
+### 4.1 必须包含的信息
+
+- **数据范围**：基于哪个表、哪些筛选条件、查询了多少条记录
+- **计算方法**：用了什么聚合方式（sum/count/avg 等）
+- **结果值**：精确到合理小数位
+
+### 4.2 示例
+
+> 基于「销售数据」表，筛选条件：日期 ≥ 2026-01-01，共查询到 342 条记录。
+> - 总销售额：¥1,234,567.89（SUM）
+> - 平均单价：¥3,610.46（AVG）
+> - 最大单笔：¥89,000.00（MAX）
+
+## 5. 任务选路心智模型
+
+| 用户诉求 | 优先方案 | 不要误走 |
+|---------|---------|---------|
+| 一次性标量统计 | `record stats` | 不要 `record query --all` 后本地聚合 |
+| 分组/去重统计 | `record group-stats` | 不要下载全表 groupby / 去重 |
+| 长期展示派生指标 | 创建 formula 字段（见 [formula-guide](./aitable-formula-guide.md)） | 不要每次手算再手动写入 |
+| 按条件筛选记录 | `record query --filters` | 不要 `--all` 拉全量再本地 filter |
+| 取最新/最大/前N | `--sort + --limit` | 不要 `--all` 再本地排序取前N |
+| 关键词检索 | `record query --filters` 用 `contain` | 不要把表格当搜索引擎全文检索 |
+| 验证"是否全部满足" | 反向 filters（筛不满足的），看是否有结果 | 不要 `--all` 逐条遍历 |