[codex] clarify devdoc rag troubleshooting docs

README.md

@@ -492,7 +492,7 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 | Mail | `mail` | 18 | `mailbox` `message` `draft` `folder` `tag` `thread` `attachment` `user` | List mailboxes, KQL message search, read & send messages, drafts, folders, tags, threads, attachments, address-book user search |
 | Sheet | `sheet` | 23 | `range` `filter-view` (top-level: `create` `new` `list` `info` `read` `get` `update` `find` `replace` `append` `merge-cells` `unmerge-cells` `add-dimension` `insert-dimension` `delete-dimension` `move-dimension` `update-dimension` `write-image`) | Online spreadsheet (`contentType=ALIDOC`, `extension=axls`): worksheet CRUD, range read / write / append, dimension ops, cell merge / unmerge, find / replace, named filter views + sheet-level filters, image write |
 | Wiki | `wiki` | 21 | `space` `member` `node` `doc` `file` | Knowledge base management: spaces (`create` / `get` / `list` / `search`), members (`add` / `list` / `update`), node tree, docs & files |
-| DevDoc | `devdoc` | 2 | `article` `error` | Search Open Platform documentation and troubleshoot API errors |
+| DevDoc | `devdoc` | 2 | `article` `error` | Search Open Platform docs with RAG and troubleshoot API errors |
 | AI Search | `aisearch` | 3 | `person` | Enterprise people search by name / department / position / duty / supervisor / subordinate / phone / job-number (single command, multi-dimension filter) |
 | Live | `live` | 1 | `stream` | DingTalk live streaming: list my lives |
 | Raw API | `api` | 1 | — | Call any DingTalk OpenAPI directly (api / oapi dual-form), with automatic app-level token management |

README_zh.md

@@ -488,7 +488,7 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \
 | 邮箱 | `mail` | 18 | `mailbox` `message` `draft` `folder` `tag` `thread` `attachment` `user` | 邮箱地址列表、KQL 邮件搜索、读取与发送邮件、草稿、文件夹、标签、会话、附件、通讯录用户搜索 |
 | 在线电子表格 | `sheet` | 23 | `range` `filter-view`（顶层：`create` `new` `list` `info` `read` `get` `update` `find` `replace` `append` `merge-cells` `unmerge-cells` `add-dimension` `insert-dimension` `delete-dimension` `move-dimension` `update-dimension` `write-image`） | 在线电子表格（`contentType=ALIDOC`、`extension=axls`）：工作表 CRUD、区域读写/追加、行列操作、合并/取消合并、查找替换、命名筛选视图 + 表级筛选、写入图片 |
 | 知识库 | `wiki` | 21 | `space` `member` `node` `doc` `file` | 知识库管理：空间（`create` / `get` / `list` / `search`）、成员（`add` / `list` / `update`）、节点树、文档与文件 |
-| 开发者文档 | `devdoc` | 2 | `article` `error` | 搜索钉钉开放平台文档、排查开放平台调用错误 |
+| 开发者文档 | `devdoc` | 2 | `article` `error` | RAG 搜索钉钉开放平台文档、排查开放平台调用错误 |
 | AI 搜问 | `aisearch` | 3 | `person` | 企业人员搜索：按姓名 / 部门 / 职位 / 职责 / 上级 / 下级 / 手机号 / 工号 多维度过滤（单命令） |
 | 直播 | `live` | 1 | `stream` | 钉钉直播：查看我的直播列表 |
 | Raw API | `api` | 1 | — | 直接调用任意钉钉 OpenAPI（api / oapi 双形态），自动管理应用级 Token |

docs/command-index.md

@@ -186,8 +186,8 @@ _Search the DingTalk Open Platform documentation._
 
 | Command | Description | When to use |
 |---|---|---|
-| `dws devdoc article search` | Search the DingTalk Open Platform documentation by keyword. | When the agent needs authoritative API reference or guides to answer a developer question. |
-| `dws devdoc error diagnose` | Troubleshoot an Open Platform API failure by requestId, error code, error message, or context. | When the agent has a requestId, traceId, error code, or failure description and needs diagnostic facts plus references. |
+| `dws devdoc article search` | Search DingTalk Open Platform documentation with the docs RAG tool. | When the agent needs authoritative API references, fields, scopes, callbacks, quotas, or guides to answer a developer question. |
+| `dws devdoc error diagnose` | Troubleshoot an Open Platform API failure with the error-code RAG tool by requestId, error code, error message, or context. | When the agent has a requestId, traceId, error code, or failure description and needs diagnostic facts plus references. |
 
 ## `dws ding` — DING Messages
 

skills/mono/references/intent-guide.md

@@ -46,10 +46,13 @@
 - "API 调用报错 403 怎么解决" — 走 `devdoc error diagnose`
 - "requestId 15r6h45w0muec 为什么失败" — 走 `devdoc error diagnose --request-id ...`
 - "搜一下 OAuth2 接入文档" — 开放平台技术文档
-- "CLI 命令出错了怎么办" — CLI 使用错误
+- "RAG 查一下机器人回调字段" — 走开放平台文档 RAG 搜索
+- "CLI 命令出错了怎么办" — 不属于 devdoc；按 CLI 错误处理或查本仓库文档
 - 用户提到"开发"、"API"、"接口文档" → `devdoc article search`
 - 用户提到"调用错误"、"错误码"、"requestId"、"traceId" → `devdoc error diagnose`
 
+**判断关键**：devdoc 面向钉钉开放平台开发者资料。文档问答走 `search_open_platform_docs_rag`；开放平台调用错误排查走 `search_open_error_code_rag`。不要把企业内文档、业务数据或 CLI 本身报错路由到 devdoc。
+
 ---
 
 ### 3. report vs todo — 日志 vs 待办

skills/mono/references/products/devdoc.md

@@ -20,6 +20,17 @@ Flags:
       --size int         分页大小 (默认 10)
 ```
 
+### RAG 检索能力
+
+`dws devdoc article search` 调用开放平台文档 RAG 工具 `search_open_platform_docs_rag`，适合查官方开发文档、OpenAPI 入参/出参、字段含义、鉴权流程、回调配置、配额限制和 SDK 接入说明。
+
+使用原则:
+- 保留用户原话中的精确标识：API 名、OpenAPI 路径、字段名、errcode、scope、事件名、回调名
+- 用户问题很宽泛时，先用场景 + 能力名检索；命中太多再加 API 名、错误码或字段名缩小范围
+- 返回结果是 RAG 命中的标题、摘要、材料和链接；优先引用高相关结果，不要把摘要改写成未验证的官方结论
+- 如果第一页结果弱相关，先换更精确关键词；需要更多候选时再调整 `--page` / `--size`
+- devdoc 只查开放平台开发者资料，不查企业内文档、业务数据或用户自己的钉钉云文档
+
 ### 错误排查
 ```
 Usage:
@@ -50,10 +61,21 @@ Flags:
 用户已经提供 requestId / traceId / 错误码 / 错误描述 / 失败上下文:
 - 走 `devdoc error diagnose`，优先传 `--request-id`，没有 requestId 时传 `--error-code`、`--error-message`、`--query` 或 `--context`
 
+错误排查输入优先级:
+
+| 已知信息 | 推荐命令 | 说明 |
+|----------|----------|------|
+| requestId / traceId | `dws devdoc error diagnose --request-id <ID>` | 最优先；`--trace-id` 是兼容别名，最终按 `requestId` 传给 MCP |
+| 错误码 + 错误描述 | `dws devdoc error diagnose --error-code <CODE> --error-message "<MSG>"` | 错误码进 `errorCode`，错误描述合并进 `query` |
+| API 名 + 失败现象 | `dws devdoc error diagnose --query "<现象>" --api "<API名>" --context "<上下文>"` | `--api` 只补充检索词，不能单独发起排查 |
+| 只有宽泛描述 | `dws devdoc error diagnose --query "<用户原话>"` | 保留原始报错文本，必要时让用户补 requestId 或错误码 |
+
 关键区分:
 - devdoc(钉钉**开放平台**开发者文档，面向研发) vs doc(钉钉在线文档，面向普通用户内容)
 - devdoc 只做搜索，不做读取；命中条目返回标题、摘要、文档链接，由 Agent 引用链接或进一步浏览
-- `devdoc error diagnose` 只返回诊断事实、参考资料和链接，不生成 AI 分析结论
+- `devdoc article search` 底层工具是 `search_open_platform_docs_rag`；`devdoc error diagnose` 底层工具是 `search_open_error_code_rag`
+- `devdoc error diagnose` 只返回诊断事实、参考资料和链接；CLI 本身不生成 AI 分析结论
+- `devdoc error troubleshoot` 是 `devdoc error diagnose` 的别名，行为一致
 - `--api`、`--error-message`、`--context` 是 CLI 侧易用参数，调用 MCP 时会合并到 `query`；MCP 入参只发送 `query`、`requestId`、`errorCode`、`page`、`size`
 
 ## 核心工作流
@@ -71,6 +93,9 @@ dws devdoc article search --query "消息卡片" --page 2 --size 5 --format json
 # 查错误码 / 字段含义
 dws devdoc article search --query "errcode 40078" --format json
 
+# 查 RAG 能力材料，保留精确字段名
+dws devdoc article search --query "openConversationId 群消息回调" --format json
+
 # 已经有 requestId 时排查
 dws devdoc error diagnose --request-id 15r6h45w0muec --format json
 
@@ -79,8 +104,18 @@ dws devdoc error diagnose --trace-id 15r6h45w0muec --api "创建日程" --format
 
 # 只有错误码和错误描述时排查
 dws devdoc error diagnose --error-code 33012 --error-message "missing scope" --format json
+
+# 现象 + API + 运行上下文一起排查
+dws devdoc error troubleshoot --query "机器人回调失败" --api "消息回调" --context "HTTP 403" --format json
 ```
 
+## 返回结果处理
+
+- 面向用户回答时，先说结论置信度，再列出命中的官方参考链接；如果结果只提供参考材料，应明确这是基于 RAG 命中材料的判断
+- 遇到 requestId 查询无结果，不要编造服务端原因；请用户补充错误码、接口名、调用时间、请求参数摘要，或改用错误码/现象继续查
+- 遇到权限、scope、回调、签名、IP 白名单、频控类问题，优先把官方材料里的检查项整理成可执行排查清单
+- 不要因为一次无命中就反复调用同一查询；最多换 1-2 个更精确关键词，仍无结果则如实说明未找到可靠材料
+
 ## 注意事项
 
 - 关键词必填；可用位置参数、`--query` 或兼容别名 `--keyword`。建议传用户原话里的关键名词（API 名、错误码、能力名），不要过度改写

skills/mono/references/products/simple.md

@@ -12,19 +12,25 @@ Usage:
   dws devdoc article search [flags]
 Example:
   dws devdoc article search --query "OAuth2 接入" --page 1 --size 10
+  dws devdoc article search "openConversationId 群消息回调" --format json
 Flags:
       --query string   搜索关键词 (必填)
       --page string    页码 (默认 1)
       --size string    每页数量 (默认 10)
 ```
 
+能力: `article search` 调用 `search_open_platform_docs_rag`，用于 RAG 检索开放平台官方开发文档。保留 API 名、字段名、scope、errcode、事件名等精确关键词；返回标题、摘要、材料和链接。
+
 ### 错误排查
 ```
 Usage:
   dws devdoc error diagnose [flags]
+  dws devdoc error troubleshoot [flags]
 Example:
   dws devdoc error diagnose --request-id 15r6h45w0muec --format json
+  dws devdoc error diagnose --trace-id 15r6h45w0muec --api "创建日程" --format json
   dws devdoc error diagnose --error-code 33012 --error-message "missing scope" --format json
+  dws devdoc error troubleshoot --query "机器人回调失败" --context "HTTP 403" --format json
 Flags:
       --query string           原始排查问题
       --request-id string      开放平台 requestId
@@ -37,6 +43,8 @@ Flags:
       --size int               分页大小 (默认 10)
 ```
 
+排查规则: `error diagnose` 调用 `search_open_error_code_rag`，优先传 requestId / traceId，其次传错误码、错误描述、API 名和上下文。`--api` 只作为补充检索词，不能单独发起排查；`--error-message`、`--api`、`--context` 会合并进 `query`。
+
 ---
 
 ## oa — 审批
@@ -118,6 +126,7 @@ Example:
 ## 意图判断
 
 - 用户说"开发文档/API 文档/接口文档" → `devdoc article search`
+- 用户说"RAG 搜开放平台文档/查字段/查 scope/查回调配置" → `devdoc article search`
 - 用户说"调用报错/requestId/traceId/错误码/错误描述" → `devdoc error diagnose`
 - 用户说"审批/请假/报销/出差" → `oa approval`
 - 用户说"同意审批/批准" → `oa approval approve`
@@ -130,8 +139,8 @@ Example:
 
 | 操作 | 从返回中提取 | 用于 |
 |------|-------------|------|
-| `devdoc article search` | 文档链接 | 直接展示给用户 |
-| `devdoc error diagnose` | diagnosticInfo、references、materials | 排查开放平台调用错误 |
+| `devdoc article search` | 标题、摘要、材料、文档链接 | 基于 RAG 命中回答开放平台文档问题 |
+| `devdoc error diagnose` | diagnosticInfo、references、materials | 排查开放平台调用错误；无命中时不要编造原因 |
 | `oa approval list-forms` | processCode | detail / records 等 |
 | `oa approval tasks` | taskId, instanceId | approve / reject |
 | `oa approval list-pending` | instanceId | detail / approve / reject |

skills/multi/dingtalk-devdoc/SKILL.md

@@ -28,11 +28,19 @@ metadata:
 | 用户说 | 命令 |
 |--------|------|
 | "查 OAuth2 接入文档" | `dws devdoc article search --query "OAuth2 接入"` |
+| "RAG 查一下群消息回调字段" | `dws devdoc article search --query "群消息回调 字段"` |
 | "API 调用报错怎么办" | `dws devdoc error diagnose --query "<报错关键词>"` |
 | "requestId 15r6h45w0muec 为什么失败" | `dws devdoc error diagnose --request-id 15r6h45w0muec` |
 | "错误码 33012" | `dws devdoc error diagnose --error-code 33012` |
 | "开放接口文档" | `dws devdoc article search --query "<接口名或场景>"` |
 
+## 调用规则
+
+- 文档问答走 `article search`，底层是 `search_open_platform_docs_rag`；保留 API 名、字段名、scope、errcode 等精确关键词
+- 开放平台调用失败走 `error diagnose`，底层是 `search_open_error_code_rag`；优先传 `--request-id` / `--trace-id`，其次传 `--error-code` 和报错上下文
+- `--api`、`--error-message`、`--context` 会合并进 `query`；`--api` 不能单独发起排查
+- `error troubleshoot` 是 `error diagnose` 的别名
+
 ## 跨产品协作
 
 - 钉钉云文档（个人 / 企业内文档）→ 切到 `dingtalk-doc`

skills/multi/dingtalk-devdoc/references/devdoc.md

@@ -20,6 +20,17 @@ Flags:
       --size int         分页大小 (默认 10)
 ```
 
+### RAG 检索能力
+
+`dws devdoc article search` 调用开放平台文档 RAG 工具 `search_open_platform_docs_rag`，适合查官方开发文档、OpenAPI 入参/出参、字段含义、鉴权流程、回调配置、配额限制和 SDK 接入说明。
+
+使用原则:
+- 保留用户原话中的精确标识：API 名、OpenAPI 路径、字段名、errcode、scope、事件名、回调名
+- 用户问题很宽泛时，先用场景 + 能力名检索；命中太多再加 API 名、错误码或字段名缩小范围
+- 返回结果是 RAG 命中的标题、摘要、材料和链接；优先引用高相关结果，不要把摘要改写成未验证的官方结论
+- 如果第一页结果弱相关，先换更精确关键词；需要更多候选时再调整 `--page` / `--size`
+- devdoc 只查开放平台开发者资料，不查企业内文档、业务数据或用户自己的钉钉云文档
+
 ### 错误排查
 ```
 Usage:
@@ -50,10 +61,21 @@ Flags:
 用户已经提供 requestId / traceId / 错误码 / 错误描述 / 失败上下文:
 - 走 `devdoc error diagnose`，优先传 `--request-id`，没有 requestId 时传 `--error-code`、`--error-message`、`--query` 或 `--context`
 
+错误排查输入优先级:
+
+| 已知信息 | 推荐命令 | 说明 |
+|----------|----------|------|
+| requestId / traceId | `dws devdoc error diagnose --request-id <ID>` | 最优先；`--trace-id` 是兼容别名，最终按 `requestId` 传给 MCP |
+| 错误码 + 错误描述 | `dws devdoc error diagnose --error-code <CODE> --error-message "<MSG>"` | 错误码进 `errorCode`，错误描述合并进 `query` |
+| API 名 + 失败现象 | `dws devdoc error diagnose --query "<现象>" --api "<API名>" --context "<上下文>"` | `--api` 只补充检索词，不能单独发起排查 |
+| 只有宽泛描述 | `dws devdoc error diagnose --query "<用户原话>"` | 保留原始报错文本，必要时让用户补 requestId 或错误码 |
+
 关键区分:
 - devdoc(钉钉**开放平台**开发者文档，面向研发) vs doc(钉钉在线文档，面向普通用户内容)
 - devdoc 只做搜索，不做读取；命中条目返回标题、摘要、文档链接，由 Agent 引用链接或进一步浏览
-- `devdoc error diagnose` 只返回诊断事实、参考资料和链接，不生成 AI 分析结论
+- `devdoc article search` 底层工具是 `search_open_platform_docs_rag`；`devdoc error diagnose` 底层工具是 `search_open_error_code_rag`
+- `devdoc error diagnose` 只返回诊断事实、参考资料和链接；CLI 本身不生成 AI 分析结论
+- `devdoc error troubleshoot` 是 `devdoc error diagnose` 的别名，行为一致
 - `--api`、`--error-message`、`--context` 是 CLI 侧易用参数，调用 MCP 时会合并到 `query`；MCP 入参只发送 `query`、`requestId`、`errorCode`、`page`、`size`
 
 ## 核心工作流
@@ -71,6 +93,9 @@ dws devdoc article search --query "消息卡片" --page 2 --size 5 --format json
 # 查错误码 / 字段含义
 dws devdoc article search --query "errcode 40078" --format json
 
+# 查 RAG 能力材料，保留精确字段名
+dws devdoc article search --query "openConversationId 群消息回调" --format json
+
 # 已经有 requestId 时排查
 dws devdoc error diagnose --request-id 15r6h45w0muec --format json
 
@@ -79,8 +104,18 @@ dws devdoc error diagnose --trace-id 15r6h45w0muec --api "创建日程" --format
 
 # 只有错误码和错误描述时排查
 dws devdoc error diagnose --error-code 33012 --error-message "missing scope" --format json
+
+# 现象 + API + 运行上下文一起排查
+dws devdoc error troubleshoot --query "机器人回调失败" --api "消息回调" --context "HTTP 403" --format json
 ```
 
+## 返回结果处理
+
+- 面向用户回答时，先说结论置信度，再列出命中的官方参考链接；如果结果只提供参考材料，应明确这是基于 RAG 命中材料的判断
+- 遇到 requestId 查询无结果，不要编造服务端原因；请用户补充错误码、接口名、调用时间、请求参数摘要，或改用错误码/现象继续查
+- 遇到权限、scope、回调、签名、IP 白名单、频控类问题，优先把官方材料里的检查项整理成可执行排查清单
+- 不要因为一次无命中就反复调用同一查询；最多换 1-2 个更精确关键词，仍无结果则如实说明未找到可靠材料
+
 ## 注意事项
 
 - 关键词必填；可用位置参数、`--query` 或兼容别名 `--keyword`。建议传用户原话里的关键名词（API 名、错误码、能力名），不要过度改写