@dingtalk-real-ai/dingtalk-connector 0.8.22-beta.0 → 0.8.22

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.22] - 2026-05-24
+
+晋升自 `0.8.22-beta.0` 的 GA 版本，与 beta.0 内容完全一致，经过 ~3 天社区验证（无回归反馈）后正式发布。
+GA promotion of `0.8.22-beta.0` after ~3 days of community validation with no regression; functionally identical to the beta.
+
+### 升级 / Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector@0.8.22
+openclaw gateway restart
+```
+
+以下内容沿用自 `0.8.22-beta.0` 的改进 / Same improvements as `0.8.22-beta.0`：
+
 ## [0.8.22-beta.0] - 2026-05-21
 
 > **社区验证版本** — 计划 2-3 天观察期后晋升为 `v0.8.22`。详见 [Release Notes](docs/RELEASE_NOTES_V0.8.22-beta.0.md)。

package/docs/RELEASE_NOTES_V0.8.22.md

@@ -0,0 +1,95 @@
+# Release Notes - v0.8.22
+
+> **GA 正式版** — 晋升自 `0.8.22-beta.0`，经 ~3 天社区验证（无回归反馈）后正式发布。
+> **General Availability** — Promoted from `0.8.22-beta.0` after ~3 days of community validation with no regression.
+
+## 🎉 本次重点 / Highlights
+
+本版本聚焦 UX 文案与 dws onboarding 体验，与 `0.8.22-beta.0` 功能完全一致：
+
+1. 把单聊空回复兜底文案 `✅ 任务执行完成（无文本输出）` 换成口语化的 `好的 👌 有其他问题随时找我`，避免被用户误判为报错（[#599](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/599) / [PR #601](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/601)）
+2. 内置 dws CLI 从 `1.0.13` 升到 npm 最新 `1.0.30`，新装用户拿到正确的 `dws auth login --help` 文案
+3. onboarding 检测 SSH / 无头环境（`SSH_CLIENT` / `SSH_TTY` / `SSH_CONNECTION`），自动建议 `dws auth login --device`，避免 127.0.0.1 loopback 在远端无浏览器服务器上挂起（[#565](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/565) / [PR #598](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/598)）
+
+This release focuses on UX copy + dws onboarding experience. Functionally identical to `0.8.22-beta.0`:
+
+1. Replace direct-chat empty-reply fallback `✅ 任务执行完成（无文本输出）` with conversational `好的 👌 有其他问题随时找我`, so users no longer mistake it for an error (#599 / PR #601)
+2. Bump bundled dws CLI from `1.0.13` to npm latest `1.0.30`; new installs get the corrected `dws auth login --help` copy
+3. Detect SSH / headless env in onboarding and auto-suggest `dws auth login --device`, avoiding 127.0.0.1 loopback hangs on remote headless servers (#565 / PR #598)
+
+## ✨ 改进 / Improvements
+
+### 单聊空回复 UX 文案优化 ([#599](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/599) / [PR #601](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/601))
+
+**现象**：用户对一段说明回「知道了」后，机器人显示 `✅ 任务执行完成（无文本输出）`，被误判为报错。
+
+**根因**：私聊场景下模型可能因 ACK 类输入选择沉默（只走 thinking / tool_call、或纯输出空文本）。connector 的空回复兜底文案系统/技术味偏重。
+
+**改动**：
+
+- `src/utils/empty-reply.ts:23` — `DIRECT_FALLBACK_TEXT` 改为 `好的 👌 有其他问题随时找我`，保留"本轮已结束"信号但去掉技术味
+- 测试改成语义契约（不绑死字符串）：不出现报错感字样 / 以「好」开头 / 包含追问引导 / 与群聊文案不同
+- 群聊兜底文案与日志 hint 维持不变（仍是面向运维的可操作指引）
+
+### dws onboarding SSH 兼容 + 版本升级 ([#565](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/565) / [PR #598](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/598))
+
+**现象**：SSH / 无头服务器上首次 `dws auth login` 卡死——dws CLI 默认走 127.0.0.1 loopback 回调，本地浏览器无法访问远端 loopback。
+
+**根因**：connector pin 的 dws 是 `1.0.13`，此版本 `--help` 文案描述与实际行为相反，SSH 用户照着 help 跑必然踩坑。
+
+**改动**：
+
+- `bin/dingtalk-connector.js:401` — `DWS_NPM_PACKAGE` 从 `1.0.13` → `1.0.30`（npm latest，含上游 dws #226 文档修复）
+- 新增 `isSshSession()`：检测 `SSH_CLIENT` / `SSH_TTY` / `SSH_CONNECTION` 三个环境变量
+- 新增 `printDwsLoginHint()` 辅助：SSH 命中时把 `dws auth login` 换成 `dws auth login --device`，并附一句说明
+- 把"已安装/全新安装"两条路径的登录提示统一走 `printDwsLoginHint()`，避免分叉
+
+**根治方向（跨仓 follow-up）**：
+
+- [dws #327](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/issues/327) — 建议 dws 自身检测 SSH 环境自动降级到 `--device`，根治后 connector 这边的兜底逻辑可以择机删除
+- 「对话框内授权」是更大的跨仓 UX 改造，需要 dws 支持非 CLI 流程或 Web flow，本版本不涉及
+
+## 🔒 兼容性 / Compatibility
+
+- **API 无变化**、配置 schema 无变化、导出符号无变化
+- 现有用户升级无需任何配置改动
+- 群聊行为完全不变（空回复兜底文案与日志 hint 未动）
+- 仅以下两类用户感知到差异：
+  - 私聊场景看到空回复兜底文案的用户 —— 文案更友好
+  - 全新安装 / 在 SSH 环境首次 `dws auth login` 的用户 —— 自动得到正确命令建议
+
+## 🧪 验证 / Verification
+
+**Beta 社区验证（2026-05-21 ~ 2026-05-24，~3 天）**：
+- npm `beta` tag 上 `0.8.22-beta.0` 稳定可用
+- 无任何针对私聊空回复文案 / dws SSH onboarding 的回归 issue
+
+**已验证组合 / Verified combo**：
+- OpenClaw Gateway `2026.5.12` (f066dd2)
+- Connector `0.8.22-beta.0`（已晋升为 `0.8.22`）
+- 平台 macOS（darwin 23.2.0）
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector@0.8.22
+openclaw gateway restart
+```
+
+或：
+
+```bash
+npm install @dingtalk-real-ai/dingtalk-connector@latest
+```
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志 / Full Changelog](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [Beta release notes (`v0.8.22-beta.0`)](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/docs/RELEASE_NOTES_V0.8.22-beta.0.md)
+- 关联 PRs / issues：[#599](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/599) / [#601](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/601) / [#565](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues/565) / [#598](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/pull/598) / [dws #327](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/issues/327)
+
+---
+
+**发布日期 / Release Date**：2026-05-24
+**版本号 / Version**：v0.8.22
+**兼容性 / Compatibility**：OpenClaw Gateway 2026.5.7+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.22-beta.0",
+  "version": "0.8.22",
   "description": "Official OpenClaw DingTalk channel plugin | 钉钉官方 OpenClaw 插件",
   "author": "DingTalk Real Team",
   "main": "index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.22-beta.0",
+  "version": "0.8.22",
   "description": "Official OpenClaw DingTalk channel plugin | 钉钉官方 OpenClaw 插件",
   "type": "module",
   "exports": {

package/skills/dingtalk-channel-rules/SKILL.md

@@ -1,91 +0,0 @@
----
-name: dingtalk-channel-rules
-description: |
-  钉钉会话输出规则。在钉钉会话中始终生效。
-alwaysActive: true
----
-
-# 钉钉会话输出规则
-
-## 写作风格
-
-- 简洁、对话式、低仪式感 — 像同事聊天，不像操作手册
-- 简短回答优先用完整句子，不要每次都用列表
-- 直奔主题，说完就停 — 不需要每次都加总结段落
-
-## 消息格式
-
-- 钉钉支持 Markdown 消息格式（标题、加粗、链接、代码块等）
-- 单条消息长度限制 2000 字符，超长内容会自动分块发送
-- 群聊中需要 @机器人 才会触发响应（除非配置了 `requireMention: false`）
-
-## AI Card 使用约定
-
-- 流式响应通过 AI Card 实现，支持打字机效果
-- 长内容优先使用 AI Card 展示，提供更好的阅读体验
-- Card 内支持 Markdown 渲染
-
-## 目标格式
-
-- 回复当前会话：省略 `target` 参数（自动推断）
-- 指定用户：`user:userId`
-- 指定群聊：`group:conversationId`
-
-## 能力路由：Connector vs DWS
-
-> **核心原则：Connector 只负责"消息通道"，所有钉钉业务操作一律通过 `dws` CLI 实现。**
-> 当用户提到任何钉钉业务功能时，不要思考"connector 是否有这个能力"，直接走 dws。
-
-### Connector 自动处理的能力（无需你操心）
-
-以下能力由 Connector 在底层自动完成，你不需要做任何额外操作：
-
-- **消息收发**：接收用户消息、回复当前会话、AI Card 流式响应
-- **媒体处理**：接收和发送图片/语音/视频/文件附件
-- **会话管理**：多轮对话上下文保持、会话隔离
-
-### 通过 dws 实现的钉钉业务功能
-
-当用户的请求涉及以下钉钉业务功能时，**立即使用 `dws` 命令**，不要犹豫：
-
-| 用户意图关键词 | dws 产品 | 典型操作 |
-|--------------|---------|---------|
-| 文档、钉钉文档、在线文档 | `dws doc` | 创建、追加、搜索、列举钉钉文档 |
-| 日程、日历、会议、会议室、忙闲 | `dws calendar` | 创建/查询日程、自动带钉钉会议链接、DING 提醒、忙闲查询 |
-| 表格、多维表、AI表格、记录、数据表 | `dws aitable` | 创建表格、读写行数据、条件查询 |
-| 待办、TODO、任务 | `dws todo` | 创建个人/群待办、查状态、设截止时间 |
-| 日志、日报、周报 | `dws report` | 提交日报/周报、查历史日志 |
-| 文件、云盘、上传、下载 | `dws drive` | 上传/下载文件到钉钉云盘 |
-| DING、紧急消息、强提醒 | `dws ding` | 向用户/群发送强提醒 DING |
-
-### 🔑 多机器人场景：bot 凭证隔离（重要）
-
-当配置了多个钉钉机器人时，必须确保 dws 命令使用**当前对话机器人**的凭据，避免"串台"（用错误的机器人身份操作）。
-
-**当前 bot 的 clientId 获取方式：**
-
-每条用户消息的上下文中会自动包含 `[DingTalk Bot Context]` 标记，其中含有当前对话 bot 的 `clientId`。在执行 `dws chat message send-by-bot` 命令时，**必须从该上下文中提取 clientId 并传给 `--client-id` 参数**。
-
-**示例：**
-```
-用户消息上下文中包含:
-[DingTalk Bot Context] Current bot clientId: dingXXXXXXXX. ...
-
-执行命令时注入:
-dws chat message send-by-bot --client-id dingXXXXXXXX --robot-code <code> --users "userId" \
-  --title "通知" --text "消息内容" --format json
-```
-
-> ⚠️ **如果不传 `--client-id`，dws 会使用默认登录的机器人凭据，可能导致消息从错误的机器人发出。** 每次执行 `dws chat` 相关命令时都必须从上下文中获取并传入 `--client-id`。
-
-### 易混淆场景速查
-
-| 场景 | 正确选择 | 错误选择 |
-|------|---------|---------|
-| 用户说"帮我创建个文档" | `dws doc` | ~~connector 没有这个能力~~ |
-| 用户说"查一下明天的日程" | `dws calendar` | ~~connector 没有这个能力~~ |
-| 用户说"帮我创建个待办" | `dws todo` | ~~connector 没有这个能力~~ |
-| 用户说"写个日报" | `dws report` | ~~connector 没有这个能力~~ |
-| 用户说"帮我操作表格数据" | `dws aitable` | ~~connector 没有这个能力~~ |
-| 用户说"DING 一下某某" | `dws ding` | ~~connector 没有这个能力~~ |
-| 用户只是在聊天/问问题 | 直接回复（connector 自动处理） | ~~不需要调 dws~~ |

package/skills/dingtalk-troubleshoot/SKILL.md

@@ -1,93 +0,0 @@
----
-name: dingtalk-troubleshoot
-description: |
-  钉钉连接器问题排查。包含 dws CLI 常见错误处理、授权问题排查和连接故障诊断。
-  当 dws 命令执行失败、授权异常、连接中断时自动激活。
----
-
-# 钉钉连接器问题排查
-
-## ❓ 常见问题（FAQ）
-
-### dws 命令返回 "command not found"
-
-**现象**：执行 dws 命令时提示 `command not found: dws`
-
-**原因**：dws CLI 未安装或未加入 PATH。
-
-**解决步骤**：
-1. 安装 dws CLI：`npm i -g dingtalk-workspace-cli`
-2. 或使用一键安装脚本：`curl -fsSL https://github.com/open-dingtalk/dingtalk-workspace-cli/releases/latest/download/install.sh | sh`
-3. 验证安装：`dws --version`（应 >= 1.0.6）
-
-### dws 命令返回 "请先执行 dws login"
-
-**现象**：执行业务命令时提示需要先登录。
-
-**原因**：dws CLI 尚未完成 OAuth 授权。
-
-**解决步骤**：
-1. 执行 `dws auth login`
-2. 终端会显示二维码，用钉钉扫码完成授权
-3. 授权成功后重试原命令
-
-### dws 命令返回 "token expired"
-
-**现象**：命令执行失败，提示 token 已过期。
-
-**原因**：OAuth access_token 已过期。
-
-**解决步骤**：
-1. 重新执行 `dws auth login` 刷新授权
-2. 授权成功后重试原命令
-
-### dws 命令返回 "permission denied" 或 HTTP 403
-
-**现象**：命令执行失败，提示权限不足。
-
-**原因**：当前用户或应用缺少对应 API 的权限。
-
-**解决步骤**：
-1. 确认操作所需的权限范围
-2. 联系组织管理员开通对应权限
-3. 权限开通后重试原命令
-
-### 连接器扫码后机器人未上线
-
-**现象**：完成 device-auth 扫码后，钉钉中机器人未显示在线。
-
-**可能原因**：
-- clientId/clientSecret 配置错误
-- 钉钉应用未启用机器人能力
-- 网络连接问题
-
-**排查步骤**：
-1. 检查 openclaw 日志中是否有连接错误
-2. 确认钉钉开放平台中应用已启用「机器人」能力
-3. 确认 clientId 和 clientSecret 与开放平台一致
-4. 尝试重启 openclaw
-
-## 🔧 错误处理流程
-
-### Recovery 闭环
-
-当 dws 命令的 stderr 中出现 `RECOVERY_EVENT_ID=<event_id>` 时，说明 CLI 检测到可恢复的错误。
-
-**处理流程**：
-1. 提取 `RECOVERY_EVENT_ID` 的值
-2. 执行 `dws recovery execute --event-id <event_id> --format json` 获取恢复计划
-3. 按恢复计划逐步执行
-4. 执行 `dws recovery finalize --event-id <event_id>` 完成闭环
-
-详细规范见 dws-cli skill 的 [recovery-guide.md](../dws-cli/references/recovery-guide.md)。
-
-### 通用错误重试
-
-1. 首次失败：加 `--verbose` 重试，获取详细错误信息
-2. 检查 stderr 是否匹配已知错误模式（未安装/未登录/过期/权限不足/Recovery）
-3. 匹配到已知模式：按对应 FAQ 处理
-4. 未匹配：将完整错误信息报告给用户，禁止自行猜测替代方案
-
-### 错误码速查
-
-各产品高频错误码及排查流程见 dws-cli skill 的 [error-codes.md](../dws-cli/references/error-codes.md)。

package/skills/dws-cli/SKILL.md

@@ -1,129 +0,0 @@
----
-name: dws-cli
-description: |
-  在钉钉会话中通过 dws CLI 管理钉钉产品能力（AI表格/日历/通讯录/群聊与机器人/待办/审批/考勤/日志/DING消息/工作台等）。
-  当用户需要操作表格数据、管理日程会议、查询通讯录、管理群聊、机器人发消息、创建待办、提交审批、查看考勤、提交日报周报时使用。
-cli_version: ">=1.0.6"
----
-
-# 钉钉全产品 Skill（via dws CLI）
-
-通过 `dws` 命令管理钉钉产品能力。所有命令由 openclaw 在终端中执行，agent 负责生成正确的 CLI 命令。
-
-## 前置条件
-
-使用本 skill 前，需确认 dws CLI 已安装并完成授权：
-
-1. **安装检查**：执行 `dws --version`，确认版本 >= 1.0.6
-2. **授权检查**：执行 `dws auth status`，确认已登录
-3. **环境变量**：connector 运行时会自动注入以下环境变量，dws CLI 会自动读取，无需手动设置：
-   - `DWS_CHANNEL=openclaw` — 标识调用来源为 openclaw connector
-   - `DWS_CLIENT_ID=<clientId>` — 当前钉钉应用的 Client ID
-   - `DWS_CLIENT_SECRET=<clientSecret>` — 当前钉钉应用的 Client Secret
-
-如果 CLI 未安装或未授权，请引导用户完成对应操作（详见下方错误处理章节）。
-
-## 严格禁止 (NEVER DO)
-- 不要使用 dws 命令以外的方式操作（禁止 curl、HTTP API、浏览器）
-- 不要编造 UUID、ID 等标识符，必须从命令返回中提取
-- 不要猜测字段名/参数值，操作前必须先查询确认
-
-## 严格要求 (MUST DO)
-- 所有命令必须加 `--format json` 以获取可解析输出
-- 危险操作必须先向用户确认，用户同意后才加 `--yes` 执行
-- 单次批量操作不超过 30 条记录
-- 所有命令必须**严格遵循**对应产品参考文档里面规定的参数格式（如：如果有参数值，则参数和参数值之间至少用一个空格隔开）
-
-## 产品总览
-
-| 产品                | 用途                                                   | 参考文件                                                           |
-|-------------------|------------------------------------------------------|----------------------------------------------------------------|
-| `aitable`         | AI表格：表格/数据表/字段/记录增删改查/模板搜索                           | [aitable.md](./references/products/aitable.md)                 |
-| `approval`        | 审批：审批表单/发起实例/审批/撤销                                   | [simple.md](./references/products/simple.md)                   |
-| `attendance`      | 考勤：打卡记录/排班查询                                         | [attendance.md](./references/products/attendance.md)           |
-| `calendar`        | 日历：日程/参与者/会议室/闲忙查询                                   | [calendar.md](./references/products/calendar.md)               |
-| `chat`            | 群聊与机器人：搜索群/建群/群成员管理/改群名/机器人群发/单聊/撤回/Webhook/机器人搜索     | [chat.md](./references/products/chat.md)                       |
-| `contact`         | 通讯录：用户查询(当前用户/搜索/详情)/部门查询(搜索/子部门/成员列表)               | [contact.md](./references/products/contact.md)                 |
-| `devdoc`          | 开放平台文档：搜索开发文档                                        | [simple.md](./references/products/simple.md)                   |
-| `ding`            | DING消息：发送/撤回（应用内/短信/电话）                              | [ding.md](./references/products/ding.md)                       |
-| `report`          | 日志：按模版创建/收件箱/已发送/模版查看/详情/已读统计                         | [report.md](./references/products/report.md)                   |
-| `todo`            | 待办：创建(含优先级/截止时间)/查询/修改/标记完成/删除                       | [todo.md](./references/products/todo.md)                       |
-| `workbench`       | 工作台：应用管理                                             | [workbench.md](./references/products/workbench.md)             |
-
-## 意图判断决策树
-
-用户提到"表格/多维表/AI表格/记录/数据" → `aitable`
-用户提到"审批/请假/报销/出差/加班" → `oa`
-用户提到"考勤/打卡/排班" → `attendance`
-用户提到"日程/日历/会议室/约会" → `calendar`
-用户提到"群聊/建群/群成员/群管理/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → `chat`
-用户提到"通讯录/同事/部门/组织架构" → `contact`
-用户提到"开发/API/调用错误 文档" → `devdoc`
-用户提到"DING/紧急消息/电话提醒" → `ding`
-用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → `report`
-用户提到"待办/TODO/任务提醒" → `todo`
-用户提到"工作台/应用管理" → `workbench`
-
-关键区分: aitable(数据表格) vs todo(待办任务)
-关键区分: report(钉钉日志/日报周报) vs todo(待办任务)
-关键区分: chat send-by-bot(机器人身份发消息) vs send-by-webhook(自定义机器人Webhook告警)
-
-> 更多易混淆场景见 [intent-guide.md](./references/intent-guide.md)
-
-## 危险操作确认
-
-以下操作为不可逆或高影响操作，执行前**必须先向用户展示操作摘要并获得明确同意**，同意后才加 `--yes` 执行。
-
-| 产品 | 命令 | 说明 |
-|------|------|------|
-| `aitable` | `base delete` | 删除整个 AI 表格，含全部数据表和记录 |
-| `aitable` | `record delete` | 删除记录（支持批量） |
-| `calendar` | `event delete` | 删除日程，所有参与者同步取消 |
-| `calendar` | `participant delete` | 移除日程参与者 |
-| `calendar` | `room delete` | 取消会议室预定 |
-| `chat` | `group members remove` | 移除群成员 |
-| `todo` | `task delete` | 删除待办 |
-
-### 确认流程
-```
-Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围）
-Step 2 → 用户明确回复确认（如 "确认" / "好的"）
-Step 3 → 加 --yes 执行命令
-```
-
-## 核心流程
-作为一个智能助手，你的首要任务是**理解用户的真实、完整的意图**，而不是简单地执行命令。在选择 `dws` 的产品命令前，必须严格遵循以下四步流程：
-
-1. 意图分类：首先，判断用户指令的核心 动词/动作 属于哪一类。这比关注名词更重要。
-2. 歧义处理与信息追问：如果用户指令模糊或包含多个产品的关键字，严禁猜测。必须主动向用户追问以澄清意图。这是你作为智能助手而非命令执行器的核心价值。
-3. 精准产品映射：在完成前两步，意图已经清晰后，参考产品总览和意图判断决策树 来选择产品。
-4. 充分阅读产品参考文件，通过编写代码或直接调用指令实现用户意图。
-
-## 错误处理
-
-### CLI 错误信号识别与处理
-
-| 错误信号 | 识别方式 | 处理策略 |
-|---------|---------|---------|
-| CLI 未安装 | stderr 包含 "command not found: dws" | 引导用户安装：`npm i -g dingtalk-workspace-cli` 或 `curl -fsSL .../install.sh \| sh` |
-| CLI 未登录 | stderr 包含 "请先执行 dws login" 或 "dws auth login" | 引导用户执行 `dws auth login` 完成 OAuth 扫码授权 |
-| Token 过期 | stderr 包含 "token expired" | 提示用户重新执行 `dws auth login` |
-| 权限不足 | stderr 包含 "permission denied" 或 HTTP 403 | 提示用户联系管理员开通对应权限 |
-| Recovery 事件 | stderr 包含 `RECOVERY_EVENT_ID=<event_id>` | 按 [recovery-guide.md](./references/recovery-guide.md) 执行 recovery 闭环 |
-| 其他错误 | 非零退出码 + 无法识别的 stderr | 加 `--verbose` 重试一次 → 仍失败则报告完整错误信息给用户 |
-
-### 通用错误处理流程
-1. 遇到错误，加 `--verbose` 重试一次
-2. 若 stderr 出现 `RECOVERY_EVENT_ID=<event_id>`，优先按 [recovery-guide.md](./references/recovery-guide.md) 执行 recovery 闭环
-3. 仍然失败，报告完整错误信息给用户，禁止自行尝试替代方案
-4. 认证失败时，参考 [global-reference.md](./references/global-reference.md) 中的认证章节处理
-5. 各产品高频错误及排查流程见 [error-codes.md](./references/error-codes.md)
-
-## 详细参考 (按需读取)
-
-- [references/products/](./references/products/) — 各产品命令详细参考
-- [references/intent-guide.md](./references/intent-guide.md) — 意图路由指南（易混淆场景对照）
-- [references/global-reference.md](./references/global-reference.md) — 全局标志、认证、输出格式
-- [references/field-rules.md](./references/field-rules.md) — AI表格字段类型规则
-- [references/error-codes.md](./references/error-codes.md) — 错误码 + 调试流程
-- [references/recovery-guide.md](./references/recovery-guide.md) — recovery 闭环、`RECOVERY_EVENT_ID`、`execute/finalize` 规范

package/skills/dws-cli/references/error-codes.md

@@ -1,95 +0,0 @@
-# 错误码说明
-全产品错误参考 + 调试流程。Agent 遇到错误时查阅此文档。
-
-## 错误返回格式
-
-```json
-{"success": false, "code": "InvalidParameter", "message": "baseId is required"}
-{"success": false, "code": "AUTH_TOKEN_EXPIRED", "message": "Token验证失败"}
-{"success": false, "code": "PermissionDenied", "message": "无权限访问该资源"}
-```
-
-## 错误分类与 Agent 行为
-
-### 可自行修复
-- 参数缺失 / 格式错误 / ID 无效 → 检查参数后修正重试
-
-### 需用户介入
-- 权限不足 / 资源不存在 / 配额超限 → 报告完整错误信息给用户，不要自行尝试替代方案
-
-## 通用错误
-- 请求超时 — 网络慢或服务端响应慢 → `--timeout 60` 重试
-- 网络连接失败 — 无法连接 MCP Server → 用最简命令验证: `dws contact user get-self --format json`
-- stderr 出现 `RECOVERY_EVENT_ID=<event_id>` — runtime 失败已被 CLI 捕获 → 优先执行 `dws recovery execute --event-id <event_id> --format json`
-
-## Recovery 闭环
-
-- `dws recovery plan --last|--event-id <event_id> --format json`：读取失败快照并生成恢复计划
-- `dws recovery execute --last|--event-id <event_id> --format json`：生成带 `doc_search`、`probe_results`、`agent_task` 的分析包
-- `dws recovery finalize --event-id <event_id> --outcome recovered|failed|handoff --execution-file execution.json --format json`：回写恢复结果
-
-执行 `finalize` 时：
-
-- `execution-file` 至少应包含 `actions`、`attempts`、`result`、`error_summary`
-- 兼容旧格式：`action` + 数值型 `attempts`
-- 若 recovery bundle 已进入 unknown/agent 路线，不要把 `human_actions` 视为最终结论；必须结合完整 bundle 判断
-
-更多字段解释见 [recovery-guide.md](./recovery-guide.md)。
-
----
-
-## aitable 高频错误
-
-> 参数体系: `baseId / tableId / fieldId / recordId`。CLI flag 用 kebab-case（`--base-id`），JSON 内用 camelCase（`baseId`）。
-
-- 参数缺失 / 无效请求 — 还在用旧参数 `dentryUuid` / `--doc` / `--sheet` → 改用 `--base-id` / `--table-id` / `--field-id` / `--record-ids`
-- 参数传了但服务端没收到 — flag 用了 camelCase（如 `--baseId`）→ flag 用 kebab-case: `--base-id <ID>`
-- `record query --filters` 无结果 — 单选/多选过滤用了 option name 而非 id → 先 `field get` 读取 options，用 option id 过滤
-- record create/update 失败 — `cells` key 用了字段名（应为 fieldId）；特殊字段格式错误 → 先 `table get` 拿字段目录；url 传 `{"text":"..","link":".."}`
-- 更新选项后历史数据异常 — 更新 options 没传完整列表 / 没保留原 id → 先 `field get` 取完整配置，保留已有 option 的 id
-- `cannot delete the last table` — 该表是 Base 最后一张表 → 先新建表再删旧表，或用 `base delete`
-- `formula` 类型 `not supported yet` — 部分字段类型暂不支持 API 创建 → 复杂字段拆开单独创建，先建基础结构
-
-**排查链路**: `base list` → `base get`(→tableId) → `table get`(→fieldId) → `record query`(→recordId)。别跳步，别猜 ID。
-
-**批量上限**: record 100 条 / field 15 个 / table·field 详情 10 个。
-
----
-
-## approval 高频错误
-
-- approve/reject 缺少 taskId — 未先获取审批任务 → 先 `approval tasks --instance-id <ID>` 获取 taskId
-- list-initiated 缺少 processCode — 未查询审批表单 → 先 `approval list-forms` 获取 processCode
-- 撤销审批失败 — 非本人发起的审批 → `revoke` 只能撤销自己发起的审批
-
----
-
-## chat 高频错误
-
-- 参数互斥报错 — `--group` 与 `--users` 同时传入 → 群聊用 `--group`，单聊用 `--users`，二者互斥
-- 群不存在 — openConversationId 不正确 → `chat search --query "群名"` 获取正确 ID
-- 机器人无法添加到群 — 当前用户非群管理员 → 报告给用户，需群管理员操作
-- Webhook Token 无效 — token 不正确或已失效 → 确认 Webhook Token 来源正确
-- 添加/移除群成员失败 — userId 不正确或无权限 → 先 `contact user search` 确认 userId，需当前用户为群管理员
-
----
-
-## calendar 高频错误
-
-- 时间格式错误 — 未使用 ISO-8601 格式 → 标准格式: `2026-03-10T14:00:00+08:00`
-- 会议室搜索报错 / 返空 — 企业会议室超 100 条未分组查询 → 先 `room list-groups` → 按 `--group-id` 逐组搜索
-- 参与者 / 会议室添加失败 — eventId 不正确 → 先 `event list` 或 `event create` 获取正确 eventId
-
----
-
-## contact 高频错误
-
-- `dept list-children` 报错 — `--id` 传了非整数值 → deptId 必须为整数，从 `dept search` 获取
-
----
-
-## 通用排查三步法
-
-1. **确认 ID** — 从最顶层资源逐级获取，不猜 ID、不跳步
-2. **确认参数** — flag 用 kebab-case，JSON 用 camelCase；特殊字段查产品参考文档确认格式
-3. **确认限制** — 检查批量上限和已知约束（各产品注意事项见对应产品参考文档）

package/skills/dws-cli/references/field-rules.md

@@ -1,105 +0,0 @@
-# 易混淆操作与字段规则
-
-## 易混淆操作 (高风险场景必读)
-
-| 用户说的 | 正确命令 | 不是这个 |
-|---------|----------|---------|
-| "创建一个新表格 (Base)" | `base create` | 不是 `table create` |
-| "在表格里加一个数据表" | `table create` | 不是 `base create` |
-| "看看表格里有哪些表" | `base get` | 不是 `field get` |
-| "看看表里有哪些列" | `field get` / `table get` | 不是 `base get` |
-| "搜索表格" (找 Base) | `base search` | 不是 `record query` |
-| "搜索记录" (查表内数据) | `record query` | 不是 `base search` |
-| "删掉这个数据表" | `table delete` | 不是 `record delete` |
-| "删掉这条数据" | `record delete` | 不是 `table delete` |
-| "删掉这个列" | `field delete` | 不是 `record delete` |
-| "改字段类型" | 先 `field delete` 再 `field create` | `field update` **不能改类型** |
-| "移动字段/调整字段顺序" | **不支持**，需在钉钉界面手动拖拽 | 没有 `reorder`/`move` 命令 |
-
-## field 子命令总览
-
-> ⚠️ field 有且仅有以下 **4 个** 子命令，没有 `list`、`reorder`、`move`：
-
-| 子命令 | 用途 |
-|-------|------|
-| `field get` | 获取字段详情（含完整 config/options）。**不是 `field list`** |
-| `field create` | **创建字段（支持通过 config.options 设置选项）** |
-| `field update` | 更新字段名称或配置（**不能改类型**） |
-| `field delete` | 删除字段（不可逆） |
-
-## 字段创建时设置 config（重要）
-
-创建 singleSelect/multipleSelect 字段时，**必须在 `--fields` 的 `config.options` 中设置选项**：
-
-```bash
-# 创建带选项的单选字段
-dws aitable field create --base-id <BASE_ID> --table-id <TABLE_ID> \
-  --fields '[{"fieldName":"优先级","type":"singleSelect","config":{"options":[{"name":"高"},{"name":"中"},{"name":"低"}]}}]' \
-  --format json
-
-# 建表时也可以直接带选项字段
-dws aitable table create --base-id <BASE_ID> --name "任务表" \
-  --fields '[{"fieldName":"任务","type":"text"},{"fieldName":"状态","type":"singleSelect","config":{"options":[{"name":"待办"},{"name":"进行中"},{"name":"已完成"}]}}]' \
-  --format json
-```
-
-> ⚠️ **不要混淆**：
-> - **字段创建**（field create / table create 的 --fields）：通过 `config.options` 设置选项，创建时就指定
-> - **记录写入**（record create / record update 的 --records）：只能写入已存在的选项名称
-
-## 主字段约束（table create 必读）
-
-> ⚠️ `table create` 的 `--fields` 中，**第一个字段自动成为主字段**。
-> 主字段只能是 **text** 类型，不能是 attachment、checkbox、formula 等。
-
-**实际影响**：当用户要求创建的字段不适合做主字段时（如附件、复选框），必须：
-1. 先放一个 text 字段作为第一个字段（主字段）
-2. 再放用户要求的字段
-3. **告知用户**为何多了一个字段
-
-```bash
-# 例: 用户要求只创建附件字段 → 附件不能做主字段，必须先加 text 主字段
-dws aitable table create --base-id <BASE_ID> --name "产品图片" \
-  --fields '[{"fieldName":"名称","type":"text"},{"fieldName":"产品图片","type":"attachment"}]' \
-  --format json
-```
-
-## 只读字段 (不可写入)
-
-以下类型的字段不可写入, 执行 `field get` / `table get` 后识别并跳过:
-- 创建时间 / 修改时间 (系统自动)
-- 创建人 / 修改人 (系统自动)
-- 自动编号
-- 公式字段
-- 引用字段
-
-## 记录写入格式（record create / record update）
-
-> 以下是 **记录写入** 时 cells 的格式，不是字段创建的格式。
-
-| 类型 | 写入格式 | 读取返回格式 |
-|------|----------|-------------|
-| text | `"fldXXX":"文本值"` | `"fldXXX":"文本值"` |
-| number | `"fldXXX":123` | `"fldXXX":123` |
-| singleSelect | `"fldXXX":"选项名"` (必须是已存在的选项) | `"fldXXX":{"id":"x","name":"选项名"}` |
-| multipleSelect | `"fldXXX":["选项1","选项2"]` (必须是已存在的选项) | `"fldXXX":[{"id":"x","name":"选项1"}]` |
-| date | `"fldXXX":"2026-03-04"` 或 Unix ms | `"fldXXX":1709510400000` (ms) |
-| user | `"fldXXX":[{"userId":"123"}]` | `"fldXXX":{"uid":"123"}` |
-| attachment | `[{"fileToken":"<token>"}]` — 需先通过 `attachment upload` 获取，见下方 ⬇️ | `[{"url":"...","filename":"...","size":N}]` |
-
-## ⚠️ 附件上传完整流程（必读！）
-
-> **不要**使用钉盘 (drive) 上传来替代此流程！钉盘 fileId **无法**写入 attachment 字段。
-
-附件字段写入使用 `upload_attachment.py` 脚本，**2 步**完成：
-
-```bash
-# 步骤 1: 一键上传文件（脚本内部自动完成 prepare + PUT to OSS）
-python3 scripts/upload_attachment.py <BASE_ID> /path/to/photo.png
-# 输出: { "fileToken": "ft_xxx", "fileName": "photo.png", "size": 1024 }
-
-# 步骤 2: 在 record create/update 中使用 fileToken
-dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> \
-  --records '[{"cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json
-```
-