feat(skills): add self-contained dingtalk-open-platform doc skill

DingTalk open-platform documentation skill as an agent execution manual (discover -> auth -> call -> verify -> recover), fully self-contained (no cross-skill references; dws is only a reference tool), with a built-in doc index llm.md of verified open.dingtalk.com/document links. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-15 15:38:21 +08:00
1 parent 3adeffb09d
commit 2c51774150
@@ -0,0 +1,110 @@
+---
+name: dingtalk-open-platform
+description: >-
+  指导 AI Agent 发现、鉴权、调用、验证并排错钉钉开放平台 OpenAPI / CLI / 应用能力的执行手册。
+  Use when 用户要 调钉钉开放平台接口 / OpenAPI、建企业内部或第三方应用、拿 access_token、申请权限 scope、
+  订阅事件、查开发文档或错误码、用 dws 调接口。给出 base URL、Header、应用类型选型、分步工作流与校验清单。
+  Distinct from 单纯的应用增删改管理 与 钉钉云文档内容读写。
+  Do NOT use for 钉钉客户端 UI 设计、后台人工运营、未开放的内部能力。
+  口语同义词：开放平台、开发者后台、open api、调接口、接口怎么调。
+cli_version: ">=1.0.15"
+metadata:
+  category: developer-platform
+  api_base: "https://api.dingtalk.com"
+  legacy_api_base: "https://oapi.dingtalk.com"
+  doc_base: "https://open.dingtalk.com/document"
+---
+
+# 钉钉开放平台 Skill（AI Agent 执行手册）
+
+每一步都回答「你下一步敲什么」。不得凭记忆猜 endpoint / 参数 / scope / ID；先查 [llm.md](llm.md) 文档大目录或官方文档，再执行。
+
+## 1. Product summary
+
+钉钉开放平台是 REST OpenAPI，覆盖通讯录 / 消息 / 机器人 / 文档 / 钉盘 / 表格 / AI 表格 / 日历 / 审批 / 应用管理 / 事件订阅 / JSAPI / 小程序 / 三方应用。
+
+| 项 | 值 |
+| --- | --- |
+| 新版 Base URL | `https://api.dingtalk.com`（路径 `/v1.0`、`/v2.0`；token 走 Header）|
+| 旧版 Base URL | `https://oapi.dingtalk.com`（路径 `/topapi/...`；token 走 query `access_token`）|
+| 鉴权 Header（新版）| `x-acs-dingtalk-access-token: <ACCESS_TOKEN>` + `Content-Type: application/json` |
+| 鉴权类型 | 应用身份（appKey/appSecret 换 token）/ 用户身份（OAuth 授权码）/ JSAPI 免登 |
+| 文档站 | `https://open.dingtalk.com/document`；全量有效链接见 [llm.md](llm.md) |
+| 访问方式 | `dws` CLI（本仓库）、MCP、原始 HTTPS |
+
+## 2. 约束 (NEVER DO)
+
+- 不要编造 endpoint / 参数 / scopeValue / ID / URL / 错误码；ID 从返回值提取，链接来自 [llm.md](llm.md) 或官方文档。
+- 不要把 `appSecret` / `clientSecret` / `accessToken` / `refreshToken` / JSAPI ticket / Cookie 写进对话、日志或 prompt。
+- 不要混用新版与旧版鉴权；不要把「权限名称」当 `scopeValue`；不要默认拥有全员数据范围。
+- **[危险]** 写 / 删 / 撤回 / 发消息 / 发布 / 加权限 等操作：先 `--dry-run` 展示摘要，**获用户当前轮确认**后才加 `--yes`。
+- **Harmness**：不输出诱导有害内容；不教唆越权 / 绕过审批 / 绕过安全边界 / 泄露凭证；越权请求一律拒绝并说明原因。
+
+## 3. When to use
+
+调用 OpenAPI；读写协作资源；建/管应用、权限、机器人、版本；拿 access_token；订阅事件；查开发文档 / 字段 / 错误码 / requestId；安装与使用 `dws`。
+
+不要用：钉钉客户端 UI 设计、后台人工运营、未公开开放的内部能力 → 直接告知不支持。
+
+## 4. Quick reference
+
+- **应用类型选型** → [references/quick-reference.md](references/quick-reference.md#应用类型)（企业内部 / 第三方企业 / 第三方个人 / 移动接入）。
+- **核心能力域 + 代表端点**（链接 `https://open.dingtalk.com/document/development/<slug>`；全量 8 域 1513 条见 [llm.md](llm.md) / [references/api-catalog.md](references/api-catalog.md)）：
+  - 通讯录：[新增或修改限制查看通讯录设置](https://open.dingtalk.com/document/development/add-or-modify-visibility-settings-for-address-book-restrictions)
+  - 消息/IM：[添加互通群成员](https://open.dingtalk.com/document/development/add-a-group-member-1) · 机器人：[批量撤回机器人消息](https://open.dingtalk.com/document/development/batch-message-recall-chat)
+  - 日历：[预定会议室](https://open.dingtalk.com/document/development/add-a-meeting-room) · 待办：[创建钉钉待办任务](https://open.dingtalk.com/document/development/add-dingtalk-to-do-task)
+  - 审批：[归档审批实例](https://open.dingtalk.com/document/development/api-archiveprocessinstance) · 文档：[添加知识库成员](https://open.dingtalk.com/document/development/add-permissions-for-team-space-members)
+  - 考勤：[添加假期规则](https://open.dingtalk.com/document/development/add-holiday-rules) · 互动卡片：[更新卡片场域信息](https://open.dingtalk.com/document/development/add-field-interface)
+  - 鉴权：[获取企业内部应用 accessToken](https://open.dingtalk.com/document/development/obtain-the-access-token-of-an-internal-app) · 调用规范：[服务端 API 怎么调](https://open.dingtalk.com/document/development/how-to-call-apis)
+- **必需 Header / 限流 / 分页 / 大小** → [references/quick-reference.md](references/quick-reference.md#header限流分页)。
+- **dws CLI 速查**（可选工具，等价于直接发 HTTP 的一种调用/发现方式；命令均 `--help` 核验）：
+```bash
+dws auth status --format json                  # 看登录态
+dws auth login --device                        # 无头环境扫码登录
+dws devdoc article search "<关键词>" --format json   # 查开发文档
+dws api GET /v1.0/contact/users/me --format json     # 原始调用（自有应用凭证）
+dws devapp list --name <应用名> --format json        # 开放平台应用 CRUD / 凭证 / 权限
+```
+
+## 5. Decision guidance
+
+| 选择题 | 用哪个 | 依据 |
+| --- | --- | --- |
+| 应用类型 | 单企业自建→企业内部应用；多企业 ISV→第三方企业应用；面向个人→第三方个人应用；端内免登→移动接入 | [quick-reference.md](references/quick-reference.md#应用类型) |
+| 新版 vs 旧版 | 优先新版 `api.dingtalk.com`（Header token）；仅旧接口用 `oapi.dingtalk.com`（query token） | [api-invocation.md](references/api-invocation.md) |
+| token 类型 | 组织服务端能力→应用 accessToken；个人数据/免登→用户身份；端内→JSAPI | [auth.md](references/auth.md) |
+| 轮询 vs 事件订阅 | 一次性结果→同步调用；持续变更→事件订阅（`configure-event-subcription`）| [reference.md](references/reference.md) |
+| 访问方式 | 有产品糖命令→`dws <product>`；只有 HTTP 契约→`dws api`；CLI 缺失→HTTPS | [api-invocation.md](references/api-invocation.md) |
+
+## 6. Workflow
+
+发现 → 前置 → 调用 → 验证 → 恢复，每步真实命令见 [references/workflow.md](references/workflow.md)：
+
+1. **发现**：[llm.md](llm.md) 定位能力域→接口；运行态 `dws devdoc article search "<关键词>" --format json`。
+2. **建应用 / 拿凭证**：`dws devapp create ...`（[危险]，先 dry-run）→ `dws devapp credentials get --unified-app-id <ID> --format json`（凭证敏感，不回显）。
+3. **申请权限 scope**：`dws devapp permission add --unified-app-id <ID> --permissions <scopeValue> --dry-run --format json` → 确认 → `--yes`。
+4. **拿 access_token**：`POST https://api.dingtalk.com/v1.0/oauth2/accessToken` body `{"appKey","appSecret"}`；token 必须缓存，禁止每请求重换。
+5. **首次调用**：`dws api {METHOD} {PATH} --data '{...}' --format json`（Header token 由 dws 注入）。
+6. **readback 校验**：成功(2xx+业务字段) / `needs_permission` / `needs_resource`；写接口走 setup→target→verify→cleanup。
+7. **错误排查**：`dws devdoc error diagnose --error-code <code> | --request-id <id> --query "..." --format json`，保留 `requestId`。
+8. **清理**：测试资源用完回收（删除/取消属 [危险]，需确认）。
+
+## 7. Common gotchas
+
+- MCP 默认凭证 ≠ raw API 凭证：`dws api` 只认自有应用 `--client-id/--client-secret`，MCP 加密 token 不支持 raw 调用。
+- scope 未开通就调用 → 403/无权限：先 `dws devapp permission add` 申请并发版。
+- 新旧 path / token 混用（Header token 配 `oapi` query 接口）→ 鉴权失败。
+- token 类型用错（用应用 token 调个人数据接口）→ 无权限。
+- devdoc 运行态网关 Forbidden / `PARAM_ERROR - 未找到指定工具` → 记 `needs_gateway_tool_registration`，降级 [llm.md](llm.md)。
+- 多候选默认选第一个 / 写操作未 dry-run / 丢失 requestId / 高频刷新 token → 见 [references/gotchas.md](references/gotchas.md)。
+
+## 8. Verification checklist
+
+上线前逐项核对（详见 [references/checklist.md](references/checklist.md)）：已查 llm.md 或官方文档；已解析稳定 ID；已确认 token 类型 + scope + 数据范围；Header 正确；限流 / 分页已处理；写操作已 dry-run + 确认；错误处理覆盖鉴权/权限/限流/参数；能回读则已回读；保留 operation/requestId。
+
+## 9. Resources
+
+- [llm.md](llm.md)：开放平台文档大目录（`development/<slug>` 全量有效链接，按 8 能力域归类）。
+- [references/api-catalog.md](references/api-catalog.md)：同源全量有效链接目录（skill 内离线）。
+- `https://open.dingtalk.com/document`：官方文档站。
+- 细节参考：[auth.md](references/auth.md) · [quick-reference.md](references/quick-reference.md) · [api-invocation.md](references/api-invocation.md) · [workflow.md](references/workflow.md) · [reference.md](references/reference.md) · [gotchas.md](references/gotchas.md) · [checklist.md](references/checklist.md) · [discovery.md](references/discovery.md)
@@ -0,0 +1,57 @@
+# API 调用层（Invocation）— HTTP 契约 1:1 映射
+
+文档里的 HTTP 主契约（Method + Path + Body）可直接落成 `dws` 命令或原始 HTTPS 请求，无需猜 SDK。`dws` 是可选 CLI，与直接发 HTTP 等价。
+
+## 1. 原始直通：dws api
+
+```bash
+# api.dingtalk.com：token 走 Header (x-acs-dingtalk-access-token)，路径 /v1.0|/v2.0
+dws api GET /v1.0/contact/users/me --format json
+dws api POST /v1.0/contact/users/search \
+  --data '{"queryWord":"张三","offset":0,"size":10}' --format json
+
+# oapi.dingtalk.com：token 走 URL 参数 (access_token)，路径 /topapi/...
+dws api POST /topapi/v2/user/get --data '{"userid":"<USER_ID>"}' --format json
+```
+
+| 域名 | token 传递 | 路径形态 |
+| --- | --- | --- |
+| `api.dingtalk.com` | Header `x-acs-dingtalk-access-token` | `/v1.0/xxx`、`/v2.0/xxx` |
+| `oapi.dingtalk.com` | URL 参数 `access_token` | `/topapi/...` 或完整 URL |
+
+- raw api 仅限自有应用凭证（见 [auth.md](auth.md)）。
+
+## 2. 从文档契约到命令（1:1）
+
+| 文档字段 | 命令位置 |
+| --- | --- |
+| Method | `dws api {METHOD}` |
+| URL Path | `dws api {METHOD} {PATH}` |
+| Body (JSON) | `--data '{...}'`（保持嵌套，不要展平）|
+| Header token | 由 `dws` 注入，不要手填 |
+| 输出解析 | `--format json` + 可选 `--jq` |
+
+## 3. 产品糖命令优先
+
+高频能力可用 `dws <product> ...` 糖命令（自带翻页/轮询/校验），而非手搓 `dws api`，命令树与 flag 以 `dws <product> --help` 为准：
+
+- 应用管理 → `dws devapp ...`（开放平台应用 CRUD / 凭证 / 权限 / 机器人 / 版本）
+- 通讯录 / 日历 / 审批 / 消息等 → `dws contact|calendar|oa|chat ...`
+
+`dws api` 用于：糖命令未覆盖、或文档明确给 HTTP 契约要 1:1 复现时。
+
+## 4. 命令发现（事实源）
+
+```bash
+dws <command-path> --help                 # 人读：Usage / Example / Flags
+dws schema                                # 机读：所有产品与工具
+dws schema <product>.<canonical_name>     # 单工具 JSON Schema
+dws schema <path> --jq '.tool.required'   # 只看必填字段
+```
+
+> 参考文档里的 flag 列表是便于理解，不是契约。冲突时**以 `--help` / `dws schema` 为准**。
+
+## 5. 写操作铁律
+
+- 写/删/发/审批类先 `--dry-run --format json` 展示摘要 → 用户确认 → 加 `--yes`（详见 [workflow.md](workflow.md)）。
+- 单次批量 ≤ 30 条。
@@ -0,0 +1,71 @@
+# 鉴权与凭证（Auth & Credentials）— 前置必读
+
+调用前先把鉴权与凭证准备好；凭证视为敏感，绝不外泄。
+
+## 1. 登录与 token 状态
+
+```bash
+dws auth status --format json      # 查看当前登录态与身份
+dws auth login                     # 扫码 / Device Flow 登录，自动刷新 token
+dws auth logout                    # 清除认证信息
+dws auth reset                     # 重置认证（清本地 token，触发重新授权）
+```
+
+| 子命令 | 用途 |
+| --- | --- |
+| `status` | 调用前确认是否已登录、token 是否有效 |
+| `login` | 未登录 / `token is illegal` / 401 时执行 |
+| `export` / `import` | 迁移认证包（跨机器） |
+
+- token 过期或 `token is illegal`：执行 `dws auth login`，**不要**把 token 贴进对话或日志。
+
+## 1b. access_token 端点（HTTP 原始换取）
+
+```http
+# 新版（推荐）：token 用于业务请求 Header x-acs-dingtalk-access-token
+POST https://api.dingtalk.com/v1.0/oauth2/accessToken
+Content-Type: application/json
+
+{"appKey":"<APP_KEY>","appSecret":"<APP_SECRET>"}
+```
+```http
+# 旧版：token 用于业务请求 query ?access_token=
+GET https://oapi.dingtalk.com/gettoken?appkey=<APP_KEY>&appsecret=<APP_SECRET>
+```
+
+- token 必须缓存复用，禁止每请求重换（高频换取会触发限流）。
+- 文档：[获取企业内部应用 accessToken](https://open.dingtalk.com/document/development/obtain-the-access-token-of-an-internal-app) · [获取第三方应用授权企业 accessToken](https://open.dingtalk.com/document/development/obtain-the-access-token-of-the-authorized-enterprise-1)。
+- 用 dws 时一般无需手动换取，`dws api` 用自有应用凭证登录后自动注入；凭证读取见 §3。
+
+## 2. token 类型
+
+| 类型 | 主体 | 典型用途 |
+| --- | --- | --- |
+| `app` / `tenant` | 企业自建应用 | 大多数服务端 OpenAPI |
+| `user` | 用户授权 | 读当前用户数据、网页授权 |
+| `isv` | 第三方应用 | ISV 套件场景 |
+
+> 应用类型（企业自建 vs 第三方）查询 API 缺失是高频凭证混淆来源（gap #4），不确定时先 `dws devapp get` 看应用属性。
+
+## 3. 应用凭证读取（敏感）
+
+```bash
+dws devapp credentials get --unified-app-id UNIFIED_APP_ID --format json
+```
+
+- 返回含 `clientId` / `clientSecret`(=`appSecret`)，**按敏感凭证处理**：仅用于构造 `dws api` 的 `--client-id/--client-secret`，不回显、不写文件。
+- 不能用 `dws devapp get` 代替（`get` 不返回完整 secret）。
+- `unifiedAppId` 来自 `dws devapp list --name X --format json`，多条命中先让用户指定。
+
+## 4. raw API 调用的凭证约束
+
+- `dws api` 仅限**自有应用凭证**（`--client-id/--client-secret` 登录后）使用。
+- 通过 MCP 默认凭证登录获取的加密 token **不支持** raw API 调用 → 改用对应产品糖命令或先用自有应用登录。
+
+## 常见错误
+
+| 现象 | 应对 |
+| --- | --- |
+| `token is illegal` / 401 | `dws auth status` → `dws auth login` |
+| raw api 报 token 不支持 | 用 `--client-id/--client-secret` 自有应用凭证 |
+| 凭证泄露风险 | 只走 `credentials get`，输出不回显 secret |
@@ -0,0 +1,27 @@
+# Verification Checklist — 调用 / 上线前勾选
+
+每次开放平台调用或交付前逐项核对，任一不过则停止并补齐。
+
+## 发现 / 契约
+- [ ] 已在 [llm.md](../llm.md) 或官方文档定位到目标接口（method / path / 文档链接）。
+- [ ] 已解析稳定资源 ID（unifiedAppId / userId / unionId / nodeId 等），来自返回值，非编造。
+
+## 鉴权 / 权限
+- [ ] 已确认 token 类型（应用 / 用户 / JSAPI）与 base URL（新版 Header / 旧版 query）匹配。
+- [ ] 已确认所需 `scopeValue` 已授权（`dws devapp permission list`）；缺则已申请并发版。
+- [ ] 已确认数据范围（data_range），未默认全员。
+- [ ] 凭证未出现在对话 / 日志 / prompt。
+
+## 调用 / Header / 限流
+- [ ] 必需 Header 正确（`x-acs-dingtalk-access-token` + `Content-Type`）。
+- [ ] 分页 / 批量大小符合接口约定；限流退避已考虑。
+- [ ] token 已缓存复用，未每请求重换。
+
+## 写操作 / 安全
+- [ ] 写 / 删 / 发 / 发布 / 撤回 已先 `--dry-run` 展示摘要并经用户当前轮确认（[危险]）。
+- [ ] 不可逆操作目标精确（无批量误伤）。
+
+## 验证 / 错误处理
+- [ ] readback 三态明确：成功 / needs_permission / needs_resource。
+- [ ] 错误处理覆盖鉴权 / 权限 / 限流 / 参数 / 平台错误；保留 `requestId`。
+- [ ] 能回读则已回读校验；不一致字段已报告。
@@ -0,0 +1,43 @@
+# 发现层（Discovery）— 找到接口与文档
+
+先从文档目录定位能力域与接口，再下钻到单接口官方文档页。
+
+## 发现优先级
+
+1. **文档目录（首选，离线可用）**：[llm.md](../llm.md) ＝ [api-catalog.md](api-catalog.md) 同源 — 全量**有效**官方文档链接（经内容长度校验，按 8 能力域 + 功能子类归类），URL 模板 `https://open.dingtalk.com/document/development/<slug>`。
+2. **运行态搜索**：`dws devdoc article search`（命中即返回标题/摘要/文档链接）。
+3. **官方文档站**：`https://open.dingtalk.com/document`。
+
+## devdoc article search
+
+```bash
+dws devdoc article search "MCP" --format json
+dws devdoc article search --query "OAuth2 接入" --format json
+dws devdoc article search --query "消息卡片" --page 2 --size 5 --format json
+```
+
+| flag | 说明 |
+| --- | --- |
+| 位置参数 / `--query` / `--keyword` | 搜索关键词（必填，建议传用户原话里的 API 名/能力名/错误码）|
+| `--page` | 页码，从 1 开始，默认 1 |
+| `--size` | 每页条数，默认 10 |
+
+- 只做**搜索**，不做读取；命中条目返回标题、摘要、`doc_link`，由 Agent 引用链接或进一步浏览。
+- devdoc 查的是**开放平台开发者文档**（面向研发），不要拿它查业务数据（那是 doc / aitable / report）。
+
+## 运行态风险与降级
+
+- 真实调用若返回 `PARAM_ERROR - 未找到指定工具` / Forbidden（pre-mcp-gw）：这是**网关/工具注册未闭环**，不是用户参数问题。
+- 处理：标记 `needs_gateway_tool_registration`，降级到 [llm.md](../llm.md) 本地目录或已挂载的逐页 Markdown。
+- `--help` / `--dry-run` 只证明 CLI 命令面与映射存在，**不**证明后端工具已注册。
+
+## 上线/注入验收（六步门禁）
+
+```bash
+dws devdoc --help
+dws devdoc article search --query "OAuth2 接入" --dry-run --format json
+dws devdoc error diagnose --error-code "40014" --query "access_token" --dry-run --format json
+dws schema devdoc.search_open_platform_docs --format json || true
+dws schema devdoc.search_open_error_code_rag --format json || true
+# real call：未注册则记录 needs_gateway_tool_registration
+```
@@ -0,0 +1,17 @@
+# Common Gotchas — 钉钉开放平台真实坑
+
+钉钉开放平台调用高频踩坑，来自线上失败归因与排错沉淀。格式：错 → 对 → 后果。
+
+| 坑 | 错误做法 | 正确做法 | 后果 |
+| --- | --- | --- | --- |
+| 凭证混用 | 用 MCP 默认（加密）token 调 `dws api` raw 接口 | `dws api` 用自有应用 `--client-id/--client-secret` 登录 | raw 调用被拒 |
+| scope 未开通 | 直接调用未授权接口 | 先 `dws devapp permission add` 申请并发版 | 403 / 无权限 |
+| 新旧 path 混用 | Header token 配 `oapi` query 接口（或反之）| 新版走 `api.dingtalk.com` Header；旧版走 `oapi` query | 鉴权失败 |
+| token 类型用错 | 用应用 token 调个人数据 / 免登接口 | 个人数据用用户身份，端内用 JSAPI | 无权限 |
+| 权限名当 scope | `--permissions 机器人发消息` | 只传 `scopeValue`（如 `qyapi_robot_sendmsg`）| 申请失败 |
+| 数据范围默认全员 | 假设拥有全员可见范围 | 显式确认 data_range，按授权范围调用 | 越权 / 空数据 |
+| 多候选选第一个 | 名称命中多条直接取第一条 | 展示候选，停止写操作，等用户指定 | 操作错对象 |
+| 写操作未 dry-run | 直接 `--yes` 执行写/删/发 | 先 `--dry-run` 展示摘要 → 确认 → `--yes` | 不可逆误操作 |
+| 丢失 requestId | 报错后不留痕 | 保留 `requestId` 交 `devdoc error diagnose` | 无法链路定位 |
+| 高频刷新 token | 每请求重新换 token | token 必须缓存复用 | 触发限流 |
+| devdoc 网关未注册 | 把 `PARAM_ERROR - 未找到指定工具` 当用户参数错 | 记 `needs_gateway_tool_registration`，降级 [llm.md](../llm.md) | 误判阻塞原因 |
@@ -0,0 +1,51 @@
+# Quick Reference — 应用类型 / Header / 限流 / CLI
+
+## 应用类型
+
+来自各接口「权限」表（企业内部应用 / 第三方企业应用 / 第三方个人应用）与端内能力实测。
+
+| 应用类型 | 适用 | 鉴权 / 身份 | 典型场景 |
+| --- | --- | --- | --- |
+| 企业内部应用 | 单企业自建 | 企业内部应用 `accessToken`（appKey/appSecret 换取） | 服务端调组织数据、机器人、文档 |
+| 第三方企业应用 | ISV 多企业 | 授权企业 `accessToken`（suiteTicket / 授权码换取） | 上架应用市场、跨企业服务 |
+| 第三方个人应用 | 面向个人用户 | 个人授权（OAuth） | 个人维度能力（部分接口标「暂不支持」）|
+| 移动接入应用 | 钉钉端内 H5 / 小程序 / 酷应用 | JSAPI 免登 ticket / 免登 code | 端内免登、容器 JSAPI 能力 |
+
+> 选型见 [SKILL.md](../SKILL.md) §5 Decision guidance；应用增删改管理用 `dws devapp ...`（以 `dws devapp --help` 为准）。
+
+## Header / 限流 / 分页 {#header限流分页}
+
+### 必需 Header
+
+| 域名 | token 传递 | 其它 |
+| --- | --- | --- |
+| `api.dingtalk.com`（新版）| Header `x-acs-dingtalk-access-token: <ACCESS_TOKEN>` | `Content-Type: application/json` |
+| `oapi.dingtalk.com`（旧版）| query `?access_token=<ACCESS_TOKEN>` | 路径 `/topapi/...` |
+
+### 限流
+
+- 每接口有 `maxQps`（官方文档 / API Explorer 标注，部分接口 `doc_open_api.extension.maxQps` 可查）。
+- 触发限流返回 429 / 限流码：遵守 `Retry-After`，指数退避，单命令重试 ≤ 3 次。
+- 幂等键无平台级统一约定 → 写接口自动重试前优先 readback 确认，避免重复写。
+
+### 分页 / 大小
+
+- 分页两类：`offset`/`size` 偏移式；`nextToken`/`maxResults` 游标式（以接口文档为准）。
+- 批量大小遵循各接口文档上限；dws 侧批量操作建议单次 ≤ 30 条。
+
+## dws CLI 速查（均 `--help` 核验）
+
+```bash
+dws --help                                     # 顶层产品与 utility 命令
+dws auth status --format json                  # 登录态 / 当前身份
+dws auth login [--device]                      # 扫码 / 设备流登录
+dws schema [<product>.<tool>]                  # MCP 工具 JSON Schema（必填字段 / flag 别名）
+dws devdoc article search "<关键词>" --format json          # 查开发文档
+dws devdoc error diagnose --error-code <code> --query "..." --format json  # 错误排查
+dws api <METHOD> <PATH> --data '<JSON>' --format json       # 原始 OpenAPI 直通
+dws devapp list --name <应用名> --format json               # 开放平台应用 CRUD / 凭证 / 权限
+dws doc read --node <URL_OR_NODE_ID> --content-format markdown --format json  # 读钉钉文档
+```
+
+- `dws api` 仅认自有应用凭证（`--client-id/--client-secret` 登录），MCP 默认加密 token 不支持 raw 调用。
+- 命令事实源以 `dws <path> --help` / `dws schema` 为准；参考文档与之冲突时以 `--help` 为准。
@@ -0,0 +1,61 @@
+# 一等公民：错误码 / 状态码 / 限流 / 版本化
+
+把 Status codes / Request limits / Versioning / Webhooks 作为一等公民单列，调用前明确契约边界。
+
+## 1. 错误诊断：devdoc error diagnose
+
+```bash
+dws devdoc error diagnose --error-code "40014" --query "获取用户信息 access_token" --format json
+dws devdoc error diagnose --request-id "<REQUEST_ID>" --query "接口调用失败" --format json
+dws devdoc error diagnose --error-message "token is illegal" --api "获取用户信息" --format json
+```
+
+| flag | 说明 |
+| --- | --- |
+| `--query` | 原始排查问题（必填语义）|
+| `--error-code` | 错误码 |
+| `--error-message` | 错误描述，合并进问题 |
+| `--api` | API 名称，合并进问题 |
+| `--request-id` | 开放平台 requestId（不是所有接口都返回）|
+| `--context` | 额外排查上下文 |
+
+- 后端返回 `PARAM_ERROR - 未找到指定工具` / `unknown tool` → 记 `needs_gateway_tool_registration`，降级 `devdoc article search` 或本 skill 的 [llm.md](../llm.md) 目录。
+
+## 2. 错误码三元组（自恢复）
+
+每个错误码应能回答：**触发原因 / 排查路径 / next_action**；未知错误码写 `源文档未提供`，不要编造。
+
+| 错误码 | 触发原因 | next_action |
+| --- | --- | --- |
+| `40014` | access_token 无效/过期 | `dws auth login`，自有应用重取凭证 |
+| `token is illegal` | 未登录 / token 失效 | `dws auth status` → `dws auth login` |
+| `PARAM_ERROR - 未找到指定工具` | 网关工具未注册 | 记 `needs_gateway_tool_registration`，降级本地索引 |
+| `ServiceResult.success=false` | 业务校验失败 | 透传 `errorCode/errorMsg`，按总表排查 |
+
+> 未知错误码写 `源文档未提供`，不要编造原因或 next_action（gap #3：错误码总表数据仍在增量建设）。
+
+## 3. 状态码 / HTTP 语义
+
+| HTTP | 含义 | 处理 |
+| --- | --- | --- |
+| 2xx | 成功 | 校验业务成功字段后继续 |
+| 401 / 403 | 鉴权 / 权限不足 | `auth login` 或 `devapp permission add` |
+| 429 | 限流 | 退避重试（见限流）|
+| 5xx | 平台错误 | 附 requestId 回流，不反复变通 |
+
+## 4. 限流（Request limits）
+
+- 每接口 `maxQps` 写在 `doc_open_api.extension`（如 `{"maxQps":100}`）；批量调用前先看 QPS。
+- 429 / 限流：指数退避重试，单命令重试 ≤ 3 次；超限停止并报告。
+- 幂等键无平台级统一约定（gap #10）→ 写接口自动重试需谨慎，优先 readback 确认而非盲目重发。
+
+## 5. 版本化（Versioning）
+
+- 路径版本：`/v1.0/` 与 `/v2.0/` 并存；旧 `dingtalk.oapi.*` 与 `/topapi/*` 为老接口面。
+- `dws upgrade`：能力缺失 / 新接口未注册时，先升级 dws 再试（新能力先在新版本上线）。
+- 应用版本发布走 `dws devapp version ...`（命令树以 `dws devapp version --help` 为准）。
+
+## 6. 事件 / 回调（Webhooks）
+
+- 事件订阅 `dws devapp event ...` 为**待实现能力**（后端待发布）→ 标 `TODO(待验证)`，不要当可用。
+- 企业回调相关接口见本 skill [llm.md](../llm.md) 的相应能力域。
@@ -0,0 +1,84 @@
+# 端到端工作流（发现 → 前置 → 调用 → 验证 → 恢复）
+
+把运行闭环固化为可复制步骤。所有 dws 命令均 `--help` 核验；dws 仅为可选 CLI，与直接发 HTTP 等价。
+
+## 0. 拿 access_token（调用前置）
+
+```http
+# 新版（推荐）：token 走业务请求 Header
+POST https://api.dingtalk.com/v1.0/oauth2/accessToken
+Content-Type: application/json
+
+{"appKey":"<APP_KEY>","appSecret":"<APP_SECRET>"}
+```
+```http
+# 旧版：token 走 query access_token
+GET https://oapi.dingtalk.com/gettoken?appkey=<APP_KEY>&appsecret=<APP_SECRET>
+```
+- token 必须缓存，禁止每请求重换；日志只记 token hash / operation / path / errcode / requestId。
+- 用 dws 时凭证读取走 `dws devapp credentials get --unified-app-id <ID> --format json`（敏感，不回显）。
+
+## 1. 只读接口（最常见）
+
+```bash
+# 发现：先查 llm.md 定位文档，运行态可用时：
+dws devdoc article search --query "获取用户信息" --format json
+# 前置：未登录则 dws auth login（无头环境 dws auth login --device）
+dws auth status --format json
+# 调用：
+dws api GET /v1.0/contact/users/me --format json
+# 验证：HTTP 2xx + 业务字段；失败转 §4
+```
+
+## 2. 写接口（setup → target → verify → cleanup）
+
+```bash
+dws devapp permission list --unified-app-id ID --status UNAUTHED --format json
+dws devapp permission add --unified-app-id ID --permissions qyapi_robot_sendmsg --dry-run --format json
+#   → 展示摘要 → 用户当前轮确认 → 加 --yes
+dws devapp permission add --unified-app-id ID --permissions qyapi_robot_sendmsg --yes --format json
+dws devapp permission list --unified-app-id ID --scope qyapi_robot_sendmsg --format json   # verify
+# cleanup：测试资源用完回收（取消权限 / 删除测试应用属 [危险]，需确认）
+```
+
+## 3. readback 三态
+
+| 态 | 判据 | 下一步 |
+| --- | --- | --- |
+| 成功 | HTTP 2xx + 业务成功字段 | 继续后续动作 |
+| `needs_permission` | 401/403 / 权限未授 | `dws devapp permission add`（→ §2）|
+| `needs_resource` | 缺前置 ID / 资源 | 按文档 `resource_requirements` 用 `dws ...` 获取 |
+
+## 4. 恢复与回流
+
+1. 失败先加 `--verbose` 重试**一次**。
+2. 有 requestId → `dws devdoc error diagnose --request-id <ID> --query "..." --format json`（[reference.md](reference.md)）。
+3. 按错误码三元组取 next_action 自恢复；网关未注册记 `needs_gateway_tool_registration`。
+4. 同一命令重试 **≤ 3 次**；仍失败 → 停止，附完整错误与 requestId 报告。
+
+## 5. 危险操作确认清单（[危险]，必须用户确认）
+
+| 产品域 | 命令 | 影响 |
+| --- | --- | --- |
+| devapp | `delete` | 删除应用（异步生效，不可逆）|
+| devapp | `inactive` | 停用应用 |
+| devapp | `permission remove` | 取消已授权限 |
+| devapp | `version publish` | 发布版本（含高敏权限需 `--confirm-sensitive`）|
+| devapp | `member remove` | 移除应用成员 |
+| devapp | `robot offline` | 下线机器人 |
+| api | 任意 `POST/PUT/PATCH/DELETE` 写接口 | 按接口 side_effect 评估，先 `--dry-run` |
+
+确认流程：`Step 1 展示摘要（操作+目标+影响）→ Step 2 用户明确确认 → Step 3 加 --yes 执行`。
+
+## 6. 完整示例（创建机器人应用）
+
+```text
+devapp create --dry-run → 确认 → create --yes
+  → devapp get 确认 unifiedAppId
+  → credentials get（敏感，不回显）
+  → permission add（机器人发消息，dry-run → 确认 → --yes）
+  → robot create（dry-run → 确认 → --yes）
+  → version create → check-approval → publish（确认）→ status 验证
+```
+
+> 应用管理每步 flag 细节以 `dws devapp <子命令> --help` 为准。