dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/sheet/sheet-write-data.md

@@ -0,0 +1,93 @@
+# Sheet 写入数据
+
+## 进入本阶段的条件
+
+仅在任务需要富文本、单元格超链接、数据验证、per-cell 样式、结构化 table 写入，或需要在 csv-put / range update / append 之间选择时读取本文件。普通二维值写入优先遵循上层 sheet.md。
+
+## 选择最短写入路径
+
+| 目标 | 命令 | 关键边界 |
+|---|---|---|
+| 超过 5 行或 20 个单元格的纯值/公式 | dws sheet csv-put | stdin 优先；最多 2M 字符、30000 单元格；覆盖已有内容必须显式 --allow-overwrite |
+| 少量值、富文本、链接、数据验证、逐格样式 | dws sheet range update | --values 必须与目标范围行列数完全一致 |
+| 末尾追加同构记录 | dws sheet append | 每一行列数一致；不要先读取并手算最后一行 |
+| columns/data/dtypes/formats 协议 | dws sheet table-put | 多工作表用 --sheets；总单元格数含表头不超过 30000 |
+
+所有既有工作表写入都必须使用真实 sheetId。当前上下文没有时只调用一次：
+
+    dws sheet +list-sheets --node <NODE_ID> --format json
+
+按完整标题唯一匹配；禁止猜 Sheet1、0、default。后续阶段复用同一个 nodeId、sheetId 和 profile。
+
+## 小范围与富格式写入
+
+    dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B2" --values '[[{"type":"text","text":"名称"},{"type":"text","text":"链接"}],[{"type":"text","text":"项目"},{"type":"text","text":"详情","hyperlink":{"type":"path","link":"https://example.com"}}]]' --format json
+
+硬约束：
+
+- 二维数组中的每格必须是 JSON object，不能直接传 string/number/boolean/null。写值时 type 只取 text 或 richText，数字和布尔值也按 text 字符串传递；只改 hyperlink/dataValidation/cellStyles 时可以省略 type，以保留原值。
+- 用 {} 跳过单元格并保留原值；清空单个格传 {"type":"text","text":""}，清空整片范围用 range clear。
+- 单元格级 hyperlink 与 richText 片段链接不要混用。取消整格链接使用 `hyperlink:{"type":"none"}`；不传 hyperlink 表示保留原链接，不能用 null 猜测清除语义。
+- richText 仅在确实需要多片段样式、片段链接、附件或图片时使用；媒体 resourceId/resourceUrl 必须来自本任务 media-upload 的真实返回。
+- dataValidation 是三态：不传表示保留原规则；传 `{"dataValidation":{"type":"none"}}` 表示清除；传 `dropdown` 或 `checkbox` 表示写入新规则。dropdown 的 `options` 与 `sourceRange` 必须且只能传一个；sourceRange 使用 `{"sheetId":"真实ID","a1Notation":"A1:A3"}`，不能传猜测名称。
+- cellStyles 适合“写值时顺带给少量格设置样式”，也可单独传 `{"cellStyles":{...}}` 只改样式并保留原值；整片统一样式进入 sheet-style-format 阶段。
+- 公式以 = 开头；需要字面量等号时前加单引号。
+- 单次建议不超过 1000 行、5000 个单元格；总量不得超过当前命令契约的 30000 单元格。超出时按连续不重叠范围拆分，每块分别回读。
+- 目标范围与 mergedRanges 冲突时，range update 会返回 `MERGED_CELLS_CONFLICT`。先用 info 定位冲突范围，必要时经用户同意取消合并，写入后再按原意恢复；不能把错误当成空结果。
+- SourceRange 下拉在结构移动后必须回读 `sourceRangeStatus`。同一 cell 的值/样式可能已写入，但下拉创建失败时服务端仍可能返回 success=true 并把失败写在 message；必须同时检查 message 和 range read 的 dataValidation。
+
+## 大块纯值写入
+
+优先 stdin，避免大 JSON 和 shell 转义：
+
+    dws sheet csv-put       --node <NODE_ID> --sheet-id <SHEET_ID> --start-cell A1       --csv - --format json
+
+先比较目标范围是否已有内容。只有用户授权覆盖，或该范围由本任务新建且尚未交付时，才加 --allow-overwrite。达到 30000 单元格上限时按不重叠连续块分批，每块写后只回读该块；不要把截断或部分写入称为成功。
+
+CSV 必须使用 ASCII 英文逗号 `,`；中文逗号 `，` 不会分列，会把整行写进一个单元格。目标区域含合并单元格时 csv-put 会打散合并并写入，这与 range update 的冲突失败语义不同；需要保留合并时先记录 mergedRanges，写完再恢复。csv-put 只承载值和公式，不承载样式、超链接、richText 或 dataValidation。
+
+### 自动类型转换与文本保真
+
+普通 CSV 写入沿用默认自动类型转换，示例省略该 flag：
+
+```bash
+dws sheet csv-put --node <NODE_ID> --sheet-id <SHEET_ID> --start-cell A1 \
+    --csv 'name,score\nAlice,95\nBob,87'
+```
+
+用户明确要求“保留前导零 / 不要转日期 / 按文本原样导入 / 禁止类型推断”时才添加 `--auto-convert=false`：
+
+```bash
+dws sheet csv-put --node <NODE_ID> --sheet-id <SHEET_ID> --start-cell A1 \
+    --auto-convert=false \
+    --csv $'id,date,total\n001,2026/8/1,"=SUM(1,2)"'
+```
+
+`--auto-convert=false` 只关闭非公式字段的类型推断：`001`、`12.10`、`1E3`、`2026/8/1`、`85%`、`TRUE` 都按原始文本写入；RFC 4180 解码后首字符为 `=` 的字段仍是公式，`'=...` 则作为普通文本保留前置单引号。用户希望识别数字、日期、百分比或布尔时，省略 `--auto-convert`，使用默认 `true`；不要给所有 `csv-put` 无条件添加该参数。有明确列类型要求时改用 `table-put` 的 `dtypes` / `formats`。
+
+## 结构化 table 写入
+
+    dws sheet table-put --node <NODE_ID> --sheets '{"name":"订单","columns":["订单号","金额"],"data":[["9007199254740993",12.5]],"dtypes":{"订单号":"object","金额":"float64"},"formats":{"订单号":"@","金额":"0.00"}}' --format json
+
+table-put 只有 --sheets 数据入口，接受单个 spec、spec 数组或 `{ "sheets": [...] }`，也可用 @文件和 stdin；不要发明 --columns/--data 等顶层 flag。table-put 不放入 batch-update。
+
+单个 sheet spec 的最小契约：
+
+- name 与 sheetId 二选一；name 不存在时创建同名工作表，sheetId 优先且不得猜测。
+- columns 必填、非空、列名去空白后非空且不重复；data 默认空数组，每行宽度必须等于 columns 长度。
+- startCell 默认 A1；mode 取 overwrite（默认）或 append。header 在 overwrite 默认 true、append 默认 false；append 到空表且未显式设置时写表头。
+- allowOverwrite 默认 true；需要保护已有值时显式 false。不要把 csv-put 的默认 false 套到 table-put。
+- dtypes、formats 的键必须来自 columns；单元格值只用 string/number/boolean/null。复用 table-get 时，data 中 `{}` 按空位/null 处理。
+- 单表最多 30000 单元格，包含表头。table-put 不支持 dataValidation、hyperlink、richText、附件或单元格图片；这些能力改用 range update/write-image。
+
+商品 ID、订单号、手机号、工号以及超过 2^53-1 的整数必须以 JSON 字符串传入，并在 dtypes/formats 中按列名声明 object 与 @，避免精度损失。写完用 table-get 验证 columns/data/dtypes/formats；table-get 不返回 cellStyles，样式另用 range read 验证。
+
+## 写后验证
+
+写命令成功只证明请求已接收。必须读回最小受影响范围：
+
+    dws sheet csv-get       --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:B2"       --format json
+
+检查 returnedRange、hasMore、truncationReasons 和关键值。公式先用 value-render-option=formula 确认公式文本，再在需要时用 raw_value 或 formula-verify 验证计算结果。富文本、链接或数据验证使用 range read 获取 per-cell 结构；样式与合并用对应对象读命令。
+
+对“写成功后立即读为空”的一致性延迟，只重试只读校验，采用 0ms、250ms、500ms、1s 的有界退避；不得重放非幂等写入。四次仍不一致则明确失败，不把空结果伪装成成功。

package/skills/dws/dingtalk-misc/references/sheet-conventions.md

@@ -0,0 +1,44 @@
+# 业务域通用规范
+
+> 仅服务本 skill 已迁入的行动指南。安全门控、危险操作确认、`--format json` 等已在本 skill 的 `SKILL.md` 中定义，此处不重复。
+
+## 批量查询规范
+
+| # | 规范 |
+|---|------|
+| 1 | **并行查详情**：拿到多个 ID 后，用 `&` 合并到同一条 Shell 命令并行执行 + `wait`，**严禁逐条串行** |
+| 2 | **翻页**：分页接口须拉全直至无更多 |
+| 3 | **优先批量 API**：有批量接口则用批量；无则按 #1 并行 |
+| 4 | **群消息**：必须先 `chat search --query` 得 `openConversationId`，再 `chat message list --group <openConversationId> --time "<yyyy-MM-dd HH:mm:ss>" --direction older`；多群同条命令并行 |
+| 5 | **列表少轮次**：带条件搜索/列表 → 一次采全详情；**禁止**无新参数时重复同一 `list` / `search` |
+
+## 多源并行采集（公共模式）
+
+> recipe 引用方式：`按「多源并行采集」执行（关键词=<X>，时间=<Y>至<Z>）`。
+
+- 同条 Shell：`&` 并行 + `wait`；分页须采全。
+- 只保留与主题相关的数据，无关丢弃。
+- 有批量详情接口优先；否则并行拉详情（见上表 #1）。
+- 具体采哪些产品列表由对应 **行动指南 recipe** 与当前产品参考决定；不要引入本文档未覆盖的产品路线。
+
+## 字段术语与 ID 传递
+
+> list 返回 JSON 后，必须提取下表字段传给后续命令。**禁止用其他字段替代。**
+
+| 字段 | 来源 | 传递给 |
+|------|------|--------|
+| `taskUuid` | `minutes list` | `minutes get summary/info/batch --id(s)` |
+| `userId` | `aisearch person` / `contact user search` / `contact dept list-members` | `contact user get --ids`、`todo --executors`、`calendar --users` |
+| `deptId` | `contact dept search` | `contact dept list-members --ids <deptId1,deptId2...>`；多子部门时对每个子部门分别 `dept search` 取 id |
+| `nodeId` | `drive search` / `wiki node search` | `doc read/update --node`、`drive copy/move/rename/delete --node` |
+| `nodeId` | `wiki node list` 中的 folder 类型节点 / `wiki node create --type folder` | `wiki node list --folder`、`wiki node create --folder`、`drive upload --folder`、`drive copy/move --folder` |
+| `eventId` | `calendar event list` | `calendar event get/update --id` |
+| `processInstanceId` | `oa approval list-*` | `oa approval detail/approve --instance-id` |
+| `openConversationId` | `chat search` | `chat message list/send --group` |
+| `todoTaskId` | `todo task list` | `todo task update/done --task-id` |
+| `reportId` | `report inbox list` / `report outbox list` | `report entry get/stats --report-id` |
+| `baseId` / `tableId` | `aitable base search` | `aitable record query --base-id --table-id` |
+| `dentryUuid` | `drive list` / `drive mkdir` | `drive info/download/copy/move/rename/delete --node`、`drive list/mkdir/upload/copy/move --folder` |
+| `dentryId` | `drive info` 的数字字段 | 仅用于 `chat message send --dentry-id` |
+
+**ID 边界硬约束**：`dentryId` 通常是纯数字，只表示聊天文件消息需要的钉盘条目数字 ID；它不是父目录 ID。遇到 `drive --node/--folder`、`doc --node`、`wiki node --folder` 时，只能使用 `dentryUuid` / `nodeId` / 文档 URL。若当前上下文只有数字型 `dentryId`，必须先重新 `drive list` / `drive search` / `wiki node list` 获取正确 ID，不能把该数字直接代入后续命令。

package/skills/dws/dingtalk-misc/references/sheet-intent-guide.md

@@ -0,0 +1,12 @@
+# sheet 局部意图消歧
+
+本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。
+
+| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 |
+|---|---|---|---|---|
+| "帮我建一个项目跟踪表" | 创建数据表格 | `aitable` | `doc` / `sheet` | 涉及结构化数据/行列操作，不是富文本文档或电子表格 |
+| "创建一个电子表格" | 创建表格文档 | `sheet` | `aitable` | Excel 式表格/单元格操作，不是多维表记录 |
+| "帮我读一下表格 A1:D10 的数据" | 读取单元格数据 | `sheet` | `aitable` | 按单元格区域读写，不是按记录查询 |
+| "这个 alidocs 表格链接帮我看下"（粘贴原始 URL） | 先 probe 节点类型 | `dws drive info --node` → 按 `extension` 路由 | 直接调 `sheet` | `alidocs/i/nodes/{id}` 可能是文档/axls/able/xlsx 等，禁止凭 URL 猜类型 |
+| "读一下这个 xlsx 的数据" / xlsx 节点链接 | 下载本地表格文件 | `dws drive download --node` | `sheet range read` | xlsx / xls / xlsm / csv 是上传的本地文件（`contentType=DOCUMENT`），sheet 命令只支持在线表格，必须下载后本地解析 |
+| "把这个在线表格导出为 xlsx 文件" | 在线表格格式转换 | `dws sheet export` | `dws drive download` | `export` 是 axls → xlsx 的导出转换；`download` 只能下载已有的 xlsx 节点 |

package/skills/dws/dingtalk-misc/references/sheet.md

@@ -0,0 +1,166 @@
+# 电子表格（Sheet）
+
+> 本文件是 Sheet 常见任务的唯一必读 reference，已经覆盖创建、定位、读写、验证、导出和清理。复杂任务按执行阶段加载精确子 reference：每个阶段最多一份，真正进入下一阶段时才允许继续加载；不要批量预读 `sheet/`、`dingtalk-shared` 或 Drive 文档。
+
+<!-- DWS_RUNTIME_CONTRACT_START -->
+## 最小 DWS 执行契约
+
+- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。
+- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
+- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。
+- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。
+<!-- DWS_RUNTIME_CONTRACT_END -->
+
+Sheet 操作先读必要范围、做最小修改，再用匹配读命令回读；已有原生命令时不要用本地脚本或多次客户端读写模拟。
+
+## 产品边界
+
+| 用户或资源 | 路由 |
+|---|---|
+| 明确说“在线电子表格/工作表/单元格/A1/公式/图表/透视表/版本” | `dws sheet`，即使用户同时说“结构化整理”“表头”“记录”也不要改走 AITable |
+| 明确说 Base/多维表/字段类型/记录视图，且没有 Sheet 原生操作 | `dws aitable` |
+| 在线富文本文档 | `dws doc` |
+| 本地 xlsx/xls，用户要转换为在线表格 | `dws sheet import create`；当前只支持 xlsx/xls |
+| Drive 中的 xlsx/xls，用户要转换为在线表格 | 先用 `dws drive download` 下载到本地相对路径，再执行 `dws sheet import create`；不要把二进制节点传给工作表命令 |
+| 只做本地分析，或文件是 xlsm/csv | 留在本地处理；当前 `sheet import` 不支持 xlsm/csv |
+
+`sheet` 仅支持在线电子表格（`contentType=ALIDOC`、`extension=axls`）。只有用户给出未知类型 URL/ID 时才调用一次 `dws drive info --node <URL_OR_ID> --format json` 探测；刚由 `sheet create` 返回的资源无需再次 probe。`spreadsheetv2` URL 原样传入 `--node`，不要截短。
+
+只有运行时仍无法识别 URL 形态时才按需查看 [链接规范](../../dingtalk-shared/references/url-patterns.md)；只有上表无法判定的低频产品歧义才查看 [局部意图消歧](sheet-intent-guide.md)。这两份都不是冷启动必读项。
+
+## 常用闭环
+
+### 1. 创建
+
+| 目标 | 命令 |
+|---|---|
+| 只建空表格 | `dws sheet create --name <NAME> --format json` |
+| 新建并写入初始二维数据 | `dws sheet create-with-data --name <NAME> --values '<2D_JSON>' --format json` |
+| 新建多个 typed 工作表 | `dws sheet create-with-data --name <NAME> --sheets '<SPECS_JSON>' --format json` |
+| 浏览当前可用模板 | `dws sheet template list --format json` |
+| 按关键词搜索模板 | `dws sheet template search --query <TEXT> --format json` |
+| 用模板创建在线表格 | `dws sheet template apply --template-id <TEMPLATE_ID> --name <NAME> --format json` |
+
+有初始数据时优先 `create-with-data`，它会创建、定位默认工作表、写入并读回，减少独立调用。空表才用 `create`。后续始终复用返回的真实 `nodeId`；不要从 URL 文本或历史会话猜 ID。
+
+模板意图先用 `list` 或 `search` 取得唯一的真实 `templateId`；零个或多个候选时停止并消歧，不能把模板名称猜成 ID。`apply` 会新建在线表格，后续复用其返回的节点信息；不要再执行一次普通 `sheet create`。
+
+### 2. 定位工作表
+
+- 后续命令不要求 `sheet-id` 时不要为了“保险”调用 `list`。
+- 需要 `sheet-id` 且当前结果没有返回时，用 `dws sheet +list-sheets --node <NODE_ID> --format json`；按完整标题唯一匹配，不猜 `Sheet1`、`0`、`default`。
+- 合并、冻结、行列尺寸/隐藏/分组等结构信息用 `dws sheet info --node <NODE_ID> --sheet-id <SHEET_ID> --format json`，不要从 CSV 空值推断。
+
+### 3. 读写选择
+
+| 目标 | 首选命令 | 说明 |
+|---|---|---|
+| Agent 快速读值 | `dws sheet csv-get --node <NODE_ID> --sheet-id <SHEET_ID> --range <A1> --format json` | token 最低；关注 `hasMore`、`returnedRange`、`truncationReasons` |
+| 严格完整读取范围 | `dws sheet +read --node <NODE_ID> --sheet-id <SHEET_ID> --range <A1> --format json` | 截断失败关闭 |
+| typed table/dataframe | `dws sheet table-get` / `table-put` | 用于 columns/data/dtypes/formats；不塞进 `batch-update` |
+| 少量值、富文本、链接、数据验证 | `dws sheet range update --node <NODE_ID> --sheet-id <SHEET_ID> --range <A1> --values '<2D_JSON>' --format json` | `--values` 维度必须与范围一致 |
+| 超过 5 行或 20 单元格的纯值/公式 | `dws sheet csv-put --node <NODE_ID> --sheet-id <SHEET_ID> --start-cell A1 --csv - --format json` | stdin 优先；覆盖已有数据时显式 `--allow-overwrite` |
+| 末尾追加记录 | `dws sheet append --node <NODE_ID> --sheet-id <SHEET_ID> --values '<2D_JSON>' --format json` | 不手算最后一行 |
+
+长数字 ID、订单号、手机号及超过 `9007199254740991` 的整数按文本写入，避免 JSON number 精度损失。公式以 `=` 开头；需要字面量 `=` 时前加单引号。
+
+用户明确要求“保留前导零、不要转日期、按文本原样导入或禁止类型推断”时，`csv-put` 添加 `--auto-convert=false`；它只关闭非公式字段的自动类型转换，公式仍按上述规则处理。其余场景省略该 flag，沿用默认自动转换。
+
+### 4. 最小验证
+
+- 值写入：只回读受影响范围，优先 `csv-get`；需要公式文本用 `--value-render-option formula`，需要真实计算值用 `raw_value`。
+- 公式任务：写后先确认公式文本，再执行 `formula-verify`；只有 `status=success`、`hasMore=false`、`totalErrors=0` 才能说目标范围未发现公式错误，这仍不等于业务数值一定正确。
+- 结构修改：用 `sheet info` 或对应对象 `list/get`；图表、透视表、筛选、评论、条件格式等不能只凭写响应断言完成。
+- 多个相互依赖的修改尽量使用服务端原子 `batch-update`；不支持的对象按依赖顺序执行，并在最后合并验证，避免每一步都全表回读。
+
+### 5. 本地交付与清理
+
+| 用户要的文件 | 正确命令 | 不要做 |
+|---|---|---|
+| 单个工作表的纯 RFC4180 CSV | `dws sheet export-csv --node <NODE_ID> --sheet-id <SHEET_ID> --output ./data.csv` | 不要给 `sheet export` 猜 `--format csv`；不要把带 `[row=N]` 的 `csv-get` 输出冒充纯 CSV |
+| 整个工作簿 xlsx | `dws sheet export --node <NODE_ID> --output ./result.xlsx` | 不要自行重复提交或轮询导出任务 |
+| 只供 Agent 阅读 | `dws sheet csv-get ...` | 不需要落盘 |
+
+`export-csv` 默认遇到截断就失败且不覆盖已有文件；只有用户明确接受不完整 CSV 时才加 `--allow-truncated`。先根据命令回执确认目标文件成功落盘且非空，再做清理。
+
+清理不是 `finally`：只有导出命令成功，且已验证本地文件存在、非空、可交付后，才进入清理步骤。导出失败或本地文件不可验证时保留在线节点并报告失败。
+
+用户要求清理时，只能针对本任务创建且 ID 已确认的在线节点。是否需要确认以 `drive +delete` 的 Runtime gate/Schema 为准；需要确认时先向用户说明节点、动作和不可见影响，取得明确确认后，才在下面这条已核对命令上追加 `--yes`：
+
+```bash
+dws drive +delete --node <NODE_ID> --format json
+```
+
+不要把原请求中的“导出后删除”自动等同于 Runtime 确认，也不要在存储示例中预置 `--yes`。命令和参数已明确时无需读取 Drive reference 或 Help；只有安全语义仍不确定时读取一次该 leaf 的 compact Schema。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "sheet +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws sheet <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service sheet --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws sheet +list-sheets` | read | 严格列出在线电子表格的工作表，并可按完整标题精确筛选 |
+| `dws sheet +read` | read | 完整读取并严格校验在线电子表格范围；截断结果失败关闭 |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 复杂操作：按阶段加载 reference
+
+先用本文件完成路由。只有执行即将进入一个复杂阶段时，才读取该阶段对应的一份子 reference；完成阶段后保留 `nodeId`、`sheetId`、对象 ID、已验证范围和 revision，再进入下一阶段。一个任务可以顺序读取多份，但禁止冷启动并行预读、重复读取已经加载的文件，或因“可能用到”提前加载。常规任务最多三个复杂阶段；超过时应先合并同类操作并复用已加载契约。
+
+| 当前执行阶段 | 本阶段唯一子 reference | 原生命令族 |
+|---|---|---|
+| 浏览、搜索或应用模板 | 本文件创建闭环（无需子 reference） | `template list/search/apply` |
+| 工作表增删改、冻结、合并边界、网格线 | [sheet-workbook](sheet/sheet-workbook.md) | `new` / `update` / `copy` / `delete-sheet` / `info` |
+| 读取元数据、分页、大范围值 | [sheet-read-data](sheet/sheet-read-data.md) | `csv-get` / `table-get` / `range read` |
+| 富格式值、超链接、数据验证、typed 写入 | [sheet-write-data](sheet/sheet-write-data.md) | `range update` / `csv-put` / `table-put` / `append` |
+| 公式写入、文本回读、错误扫描 | [sheet-formula](sheet/sheet-formula.md) | `range update` / `formula-verify` |
+| 查找或替换 | [sheet-search-replace](sheet/sheet-search-replace.md) | `find` / `replace` |
+| 清空、排序、填充、复制/移动区域 | [sheet-range-operations](sheet/sheet-range-operations.md) | `range clear/sort/fill/copy-to/move-to` |
+| 多个原子写组合 | [sheet-batch-operations](sheet/sheet-batch-operations.md) | `batch-update` / `range batch-clear` |
+| 行列插删、尺寸、隐藏、移动、分组 | [sheet-dimension-operations](sheet/sheet-dimension-operations.md) | dimension 命令族 |
+| 样式、数字格式、合并 | [sheet-style-format](sheet/sheet-style-format.md) | `range set-style` / `merge-cells` |
+| 下拉选项 | [sheet-dropdown](sheet/sheet-dropdown.md) | dropdown 命令族 |
+| 筛选 | [sheet-filter](sheet/sheet-filter.md) | `filter` 命令族 |
+| 个人筛选视图 | [sheet-filter-view](sheet/sheet-filter-view.md) | `filter-view` 命令族 |
+| 条件高亮、色阶、数据条 | [sheet-conditional-format](sheet/sheet-conditional-format.md) | `cond-format` 命令族 |
+| 图表 | [sheet-chart](sheet/sheet-chart.md) | `chart` 命令族 |
+| 透视表 | [sheet-pivot-table](sheet/sheet-pivot-table.md) | `pivot-table` 命令族 |
+| 评论、回复、更新、删除评论 | [sheet-comment](sheet/sheet-comment.md) | `comment` 命令族 |
+| 图片与附件 | [sheet-media-image](sheet/sheet-media-image.md) | `write-image` / float-image 命令族 |
+| 在线历史版本保存、列表、恢复 | [sheet-version](sheet/sheet-version.md) | `version save/list/revert` |
+| 当前 revision 与编辑审计 | [sheet-revision-changeset](sheet/sheet-revision-changeset.md) | `revision-get` / `changeset-get` |
+| 导入或导出边界/失败恢复 | [sheet-export](sheet/sheet-export.md) 或 [sheet-import](sheet/sheet-import.md) 中与意图匹配的一份 | `export` / `export-csv` / `import create/get` |
+
+例如“写公式 → 设置样式 → 创建图表”可在进入三个阶段时依次加载 `sheet-formula`、`sheet-style-format`、`sheet-chart`，但每一阶段只读一份，且下一份必须等上一阶段写入/验证完成后再读。若当前 reference 已能完成后续动作，不再加载；契约错误恢复仍只补读与报错 leaf 精确对应的一份。
+
+## 版本与 revision 边界
+
+- 在线 Sheet 历史版本只用 `dws sheet version save/list/revert`。恢复是破坏性操作，必须确认精确目标版本；不要用 Doc 的 version 命令。
+- `revision-get` / `changeset-get` 是编辑审计和前向语义变化，不是可恢复的历史快照，也不保证是当前最终值。
+- 不要用 AITable schema snapshot 冒充 Sheet 历史版本。用户明确要求在线电子表格版本时，产品边界优先于“结构化”措辞。
+- 恢复或审计后仍需回读当前目标范围；changeset 不能代替最终值。
+
+## 完成检查
+
+在最终答复前只做一次紧凑检查：
+
+- 资源类型和 profile 正确，所有 ID 来自本任务真实返回。
+- 创建/修改、对象存在性与关键值已有匹配读回；公式没有被普通值回读误判。
+- 用户要求的本地 CSV/xlsx 已成功导出，格式与扩展名一致。
+- 若要求清理，本任务创建的精确在线节点已移入回收站；本地交付物仍保留。
+- 最终答复附上真实在线链接或本地路径，只报告证据支持的行数、对象数、公式状态和清理状态。
+
+## 最短错误恢复
+
+- 参数校验失败：只修正错误指出的 leaf 参数后重试一次；不要改读父级 Help。
+- `hasMore=true` / 截断：按 `returnedRange` 分块续读；不得把部分结果声称为完整。CSV 落盘默认失败关闭。
+- 导出 xlsx 失败或超时：不要重复提交 `sheet export`；保留在线文档并报告。
+- `create-with-data` 在 create / write / style 间不是原子事务。若错误 `details.status` 为 `unknown` 或 `partial_success`，复用 `details.nodeId` / `details.sheetId` 读回现状，只补失败步骤；不得整体重跑 `create-with-data`，也不得自动删除已写数据。
+- 写入部分成功：先读回确定真实状态，再续做缺失部分；不要盲目重放非幂等创建。
+- 权限或认证失败：停止业务重试并报告；不要切换产品绕过权限。

package/skills/dws/dingtalk-misc/references/skill.md

@@ -0,0 +1,98 @@
+# skill — DWS 技能管理
+
+> 这是元能力：只管理 dws 平台上的技能资源。Distinct from `dingtalk-shared`（钉钉产品路由入口）、其他 `dingtalk-*` 产品 skill（执行具体业务能力）、本地 Codex skill 开发。命令前缀：`dws skill`。
+
+## 意图表
+
+| 用户说 | 命令 |
+|---|---|
+| "搜索技能 / 找技能" | `dws skill search --query "<关键词>" [--source DingtalkMarket\|OrgInternal]` |
+| "下载技能包" | `dws skill get --skill-id <skillId>` |
+| "安装市场技能" | `dws skill install <skillId> <target>` |
+| "安装 DWS mono/multi skills" | `dws skill setup --mode <mono\|multi> --target <target>` |
+
+## 约束
+
+- `skillId` 必须来自 `skill search` 返回，不能用名称代替。
+- `skill install` 的 `skillId` 与 `target` 是位置参数，不是 `--skill-id` flag。
+- `skill setup --mode multi` 可用 `--skill/-s` 只装指定产品，或用 `--exclude/-x` 排除产品，两者不能同时使用。
+- 搜索结果中的 `securityStatus` 需要如实展示；状态异常时不要把安装描述为已通过安全检测。
+- 开源 CLI 不提供技能发布/上传命令；发布需求应转到对应的技能市场发布流程。
+
+## 兼容提示
+
+- `dws skill find` → `dws skill search --query <关键词>`
+- `dws skill add` → `dws skill install <skillId> <target>`
+
+---
+
+## 命令参考
+
+### 搜索技能
+
+```
+Usage:
+  dws skill search [flags]
+Example:
+  dws skill search --query "周报"
+  dws skill search --query "日报" --source OrgInternal
+Flags:
+      --query string    搜索关键词 (必填)
+      --source string   查询范围：DingtalkMarket / OrgInternal；空格分隔
+```
+
+从返回中提取真实 `skillId`、名称、版本、来源与 `securityStatus`。兼容入口 `skill find` 只会提示改用 `search`。
+
+### 下载技能包
+
+```
+Usage:
+  dws skill get --skill-id <skillId>
+Flags:
+      --skill-id string   技能 ID (必填)
+```
+
+成功后返回本地临时目录路径，供检查或后续安装使用。
+
+### 安装市场技能
+
+```
+Usage:
+  dws skill install <skillId> <target>
+Example:
+  dws skill install skill-123 claude
+  dws skill install skill-123 qoder
+  dws skill install skill-123 .
+```
+
+`skillId` 来自搜索结果；`target` 使用 `skill install --help` 列出的 Agent 名称，或用 `.` 安装到当前目录。两个值均为位置参数。
+
+### 部署 DWS 内置技能
+
+```
+Usage:
+  dws skill setup [flags]
+Example:
+  dws skill setup --mode mono
+  dws skill setup --mode multi --target qoder
+  dws skill setup --mode multi -s aitable -s calendar --target qoder
+  dws skill setup --mode multi -x live -x devdoc --target qoder
+Flags:
+      --mode string       mono | multi
+      --target string     目标 Agent，默认 all
+      --source string     显式 skill 源目录
+  -s, --skill strings     multi 模式只安装指定子 skill
+  -x, --exclude strings   multi 模式排除指定子 skill
+      --yes               仅脚本使用：跳过确认（删除仍先备份）
+```
+
+`--skill` 与 `--exclude` 互斥。未指定 `--source` 时使用当前二进制内置的 skill 版本。setup 会清理对面模式残留与不在 bundle 内的过期 skill；这些目录在确认前逐条列出，删除前先备份到 `~/.dws/skill-backups/`，备份失败的目录保留原样。代用户执行时不要附加 `--yes` 绕过确认。
+
+## 上下文传递
+
+| 操作 | 从返回中提取 | 用于 |
+|---|---|---|
+| `skill search` | `skillId`、版本、来源、安全状态 | 下载或安装 |
+| `skill get` | 临时目录 | 本地检查 |
+| `skill install` | 安装目标与结果 | 确认指定 Agent 已安装 |
+| `skill setup` | 已安装/保留/跳过的 skill 列表 | 验证 mono/multi 部署 |

package/skills/dws/dingtalk-misc/references/unsupported-scripts.md

@@ -0,0 +1,49 @@
+# 未产品化 / 半悬空脚本清单
+
+以下脚本位于 `dingtalk-misc/scripts/`，**没有**对应的稳定产品 reference 与路由行。
+它们不是当前 Agent 默认能力面的一部分。
+
+## 使用规则
+
+1. **默认不要调用**这些脚本完成用户任务；优先公开 `dws` 命令 / Shortcut。
+2. 仅当用户**明确点名**某脚本文件名，或明确要求「跑仓库里的 yida/finance/aiapp 辅助脚本」时才考虑。
+3. 调用前用 `--help` / 脚本头注释确认参数；写操作仍遵守 [confirmation.md](../../dingtalk-shared/references/confirmation.md)。
+4. 若脚本依赖的 `dws <product>` 子命令在当前二进制不存在，向用户说明能力未暴露，不要改用 HTTP/curl 绕过。
+
+## AI 应用（aiapp）
+
+| 脚本 | 说明 |
+|---|---|
+| `aiapp_create_and_poll.py` | 创建 AI 应用并轮询；**无** `references/aiapp.md`，mono 产品表历史死链已移除 |
+
+## 宜搭（yida）
+
+| 脚本 | 说明 |
+|---|---|
+| `yida_form_builder.py` | 表单 schema 构造 |
+| `yida_form_fields.py` | 表单字段构造 |
+| `yida_form_inspector.py` | 表单检查 |
+| `yida_form_update.py` | 表单 schema 更新编排 |
+| `yida_custom_page_update.py` | 自定义页 schema 更新编排 |
+| `yida_jsx_pipeline.py` | JSX transform / lint 流水线 |
+| `yida_page_compiler.py` | 自定义页编译 |
+| `yida_page_generate.py` | 自定义页生成 |
+| `yida_page_schema.py` | 页面 schema 处理 |
+| `yida_page_self_check.py` | 页面自检 |
+| `yida_process_flow.py` | 流程辅助 |
+| `yida_process_update.py` | 流程保存/发布编排 |
+| `yida_report_builder.py` | 报表 schema 构造 |
+| `yida_report_charts.py` | 报表图表组件 |
+| `yida_report_update.py` | 报表 schema 更新编排 |
+| `yida_schema_common.py` | schema 公共工具 |
+
+`routing.md` 可将「宜搭」粗分到 `dingtalk-misc`，但**产品索引表无宜搭正式产品行**；在补齐正式 reference 前，宜搭请求应向用户说明「仅有未产品化脚本，无稳定命令面」。
+
+## 财务辅助（finance）
+
+| 脚本 | 说明 |
+|---|---|
+| `finance_daily_cashflow.py` | 日现金流辅助 |
+| `finance_expense_flow.py` | 费用流辅助 |
+
+无独立 finance CLI 产品面时，不要把这些脚本宣传为正式 CLI 能力。

package/skills/dws/dingtalk-misc/references/url-patterns.md

@@ -0,0 +1,144 @@
+# URL 格式与处理规范
+
+## 路由第 0 步：意图直达（优先级高于 URL 探测）
+
+用户已经明确表达某产品的内容意图时，直接进入对应产品场域，不要先做 URL 类型
+探测。尤其：
+
+- 明确提到 Markdown / `.md` 文件的读取或修改，按普通文件走 `drive` 场域：
+  先 `dws drive download` 下载到本地处理，再用 `dws drive upload` 回传。
+- 明确“读这篇文档 / 编辑文档正文”进入 `doc`；明确“看这个在线表格数据”进入
+  `sheet`。
+
+仅当用户只粘贴 URL、没有明确产品意图，或意图与链接类型可能冲突时，才执行下方
+类型探测。
+
+## alidocs URL 分流决策（意图不明确时执行）
+
+收到 `alidocs.dingtalk.com` URL 且无法从指令判断产品时，必须按以下顺序判断：
+
+1. URL 路径含 `/i/p/` → **分享短链**，禁止调用 `dws doc` 任何子命令 → 按下方 [分享短链处理](#分享短链处理) 执行
+2. URL 路径含 `/i/nodes/` → **节点链接**，需探测类型 → 按下方 [alidocs URL 类型探测流程](#alidocs-url-类型探测流程) 执行
+3. URL 路径含 `/spreadsheetv2/` → **电子表格直链**，直接路由到 `sheet`，将完整 URL 原样传给 `--node` 参数
+4. URL 路径含 `/document/edit` 或 `/document/preview` 且 query 参数包含 `dentryKey` → **文档链接**，直接路由到 `doc`，将完整 URL 原样传给 `--node` 参数（URL 中不一定有 `type=d`，只需匹配路径和 `dentryKey` 参数即可）
+5. 其他 alidocs URL 格式 → 告知用户当前暂不支持该链接格式
+
+---
+
+## 已知 URL 格式
+
+需要自行拼接链接时，只能使用以下模板：
+
+| 产品 | 用途 | URL 格式 | ID 来源 |
+|------|------|----------|---------|
+| `aitable` | AI表格 Base 链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}` | `base list/search/create/get` 返回的 `baseId` |
+| `aitable` | AI表格指定数据表链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}` | `baseId` + `table create/get` 或 `base get` 返回的 `tableId` |
+| `aitable` | AI表格指定数据表+视图链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}%26viewId%3D{viewId}` | `baseId` + `tableId` + `view create/get` 返回的 `viewId` |
+| `aitable` | AI表格模板预览 | `https://docs.dingtalk.com/table/template/{templateId}` | `template search` 返回的 `templateId` |
+| `doc` | 文档链接 | `https://alidocs.dingtalk.com/i/nodes/{dentryUuid}` | `doc` 命令返回的 `dentryUuid` |
+| `sheet` | 电子表格链接 | `https://alidocs.dingtalk.com/i/nodes/{dentryUuid}` | `sheet create` 返回的 `dentryUuid` |
+| `sheet` | 电子表格直链 | `https://alidocs.dingtalk.com/spreadsheetv2/{key}/...?dentryKey={key}&type=s` | 用户提供的完整 URL，直接传给 `--node` |
+| `doc` | 文档链接（edit/preview） | `https://alidocs.dingtalk.com/document/{edit\|preview}?...&dentryKey={key}` | 用户提供的完整 URL，直接传给 `--node` |
+| `minutes` | 听记链接 | `https://shanji.dingtalk.com/app/transcribes/{taskUuid}` | `list mine/shared` 返回的 `taskUuid` |
+
+不在此表中的产品，禁止自行拼接 URL。命令返回中包含完整链接时直接使用，否则告知用户无法提供。
+
+## 分享短链处理
+
+`alidocs.dingtalk.com/i/p/{shortKey}` 是钉钉文档的**对外分享短链**，`dws doc` 命令无法解析此格式。
+
+### 识别规则
+
+URL 路径中包含 `/i/p/` 即为分享短链（无论后面是否还有子路径），例如：
+- `https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2`
+- `https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7`
+- `https://alidocs.dingtalk.com/i/p/AbCdEfGh1234`
+- `https://alidocs.dingtalk.com/i/p/AbCdEfGh1234/sheets/XYZ789`
+
+> **关键**：只要 URL 中出现 `/i/p/`，无论后面跟什么子路径（`/docs/...`、`/sheets/...` 等），都属于分享短链，一律禁止调用 `dws doc`。
+
+### 处理方式
+
+**不要调用 `dws doc` 任何子命令**（包括 `doc info`、`doc read` 等），`dws` 无法解析此格式。
+
+- **需要获取文档内容时**：使用 `read_url` 工具直接读取该链接
+- **其他操作（如移动、复制、权限管理等）**：告知用户此链接为分享短链，无法直接执行复制、移动、权限管理等操作。如需保存该文档内容，建议用户在钉钉客户端中打开该页面，手动复制文本内容，然后可通过 `dws doc create` 创建一篇新文档并将内容写入
+
+```
+# 需要读取文档内容时（无论 /i/p/ 后面有没有子路径，都用 read_url）
+read_url("https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2")
+read_url("https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7")
+
+# 禁止（以下全部会失败，dws 无法解析任何含 /i/p/ 的 URL）
+dws doc info --node "https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2" --format json
+dws doc read --node "https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7" --format json
+```
+
+### 当 `read_url` 返回内容不完整时
+
+钉钉文档分享页是动态渲染的，`read_url` 可能只能获取到页面标题等有限信息，无法获取文档正文。此时**禁止猜测原因**（如"权限不足""文档为空""文档已删除"等），**禁止建议用户"提供 `/i/nodes/` 格式链接"**（分享短链和节点链接是不同体系，普通用户无法自行转换）。应直接告知用户：
+
+> 这个链接是钉钉文档的分享短链，由于页面是动态渲染的，我无法通过该链接直接获取文档的完整正文内容。
+>
+> 你可以：
+> 1. 在钉钉客户端中打开该文档，将正文内容复制粘贴给我
+> 2. 如果文档已保存在你的文档空间中，可以告诉我文档名称，我通过 `dws drive search` 搜索后再读取
+
+---
+
+## alidocs URL 类型探测流程
+
+`alidocs.dingtalk.com/i/nodes/{id}` 是钉钉文档空间的统一 URL，可能指向**文档、电子表格、多维表、文件、文件夹**等不同类型。**禁止仅凭 URL 就假定为文档**，必须先探测类型再路由到正确的产品。
+
+### 探测步骤
+
+```
+Step 1 → dws drive info --node "<URL>" --format json
+Step 2 → 从返回中提取 extension、nodeType 字段
+Step 3 → 按下方路由规则映射到对应产品
+```
+
+> 路由依据是 `extension`，不是 `contentType`。`drive info` 检测到
+> `adoc` / `axls` / `able` 时会自动补充在线文档信息。
+
+### 路由映射表
+
+| 条件 | 路由到产品 | 后续操作 |
+|------|-----------|---------|
+| `extension=adoc` | `doc` | 加载 `dingtalk-doc` 操作内容 |
+| `extension=axls` | `sheet` | 加载本包 `references/sheet.md` 操作（仅 `axls` 在线电子表格） |
+| `extension=able` | `aitable` | 将 nodeId 作为 baseId，加载 `dingtalk-aitable` 操作 |
+| `extension=xlsx` / `xls` / `xlsm` / `csv` | `drive` | 必须用 `dws drive download` 下载到本地处理，禁止走 `sheet` |
+| `nodeType=file`（非在线文档扩展名，含 `md`） | `drive` | 下载用 `dws drive download --node <ID> --output <PATH> --format json`；上传/覆盖用 `dws drive upload` |
+| `nodeType=folder` | `drive` / `wiki` | 调用 `dws drive list --workspace <WS_ID>` 或 `dws wiki node list` 列出子节点 |
+| 以上均不匹配 | — | 告知用户当前暂不支持该类型 |
+
+> axls vs xlsx 关键区分：
+> - `axls`（钉钉在线电子表格，`contentType=ALIDOC`）→ 走 `sheet` 产品线（读/写/筛选/导出等服务端原子操作）
+> - `xlsx` / `xls` / `xlsm` / `csv`（上传到文档空间的本地表格文件，`contentType=DOCUMENT`）→ 必须走 `dws drive download` 下载到本地后再解析处理，严禁错误路由到 `sheet` 产品线（sheet 命令只支持在线表格，调用 xlsx 节点会直接报错）
+> - 用户想把在线表格导出为 xlsx 文件 → 用 `dws sheet export`（输入是 `axls`，输出是 xlsx，这是 axls → xlsx 的格式转换，不属于 xlsx 读取场景）
+
+### 示例
+
+```bash
+# 用户传入: https://alidocs.dingtalk.com/i/nodes/abc123
+dws drive info --node "https://alidocs.dingtalk.com/i/nodes/abc123" --format json
+
+# 返回 extension=axls → 在线电子表格，路由到 sheet
+dws sheet list --node "https://alidocs.dingtalk.com/i/nodes/abc123" --format json
+
+# 返回 extension=xlsx/xls/csv → 本地表格文件，必须下载处理（禁止走 sheet）
+dws drive download --node "https://alidocs.dingtalk.com/i/nodes/xlsx456" --output <PATH> --format json
+
+# 返回 nodeType=file → 普通文件，下载
+dws drive download --node "https://alidocs.dingtalk.com/i/nodes/def456" --output <PATH> --format json
+
+# 返回 nodeType=folder → 文件夹，列出子节点
+dws drive list --workspace <WS_ID> --format json
+```
+
+### 何时可跳过探测
+
+当用户指令中已明确指定产品（如"帮我读这个文档"、"看下这个表格的数据"），可结合用户意图**跳过探测**直接路由。仅在以下情况**必须执行探测**：
+- 用户只粘贴 URL，无其他上下文
+- 用户指令与 URL 实际类型可能不一致（如说"文档"但实际是表格）