diff --git a/README.md b/README.md index bb681b17..3bc7b20e 100644 --- a/README.md +++ b/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 | diff --git a/README_zh.md b/README_zh.md index cd08c987..085460e6 100644 --- a/README_zh.md +++ b/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 | diff --git a/docs/command-index.md b/docs/command-index.md index 64f6f956..43f725bb 100644 --- a/docs/command-index.md +++ b/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 diff --git a/skills/mono/references/intent-guide.md b/skills/mono/references/intent-guide.md index a24e6172..fa198bf8 100644 --- a/skills/mono/references/intent-guide.md +++ b/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 待办 diff --git a/skills/mono/references/products/devdoc.md b/skills/mono/references/products/devdoc.md index 862e7b1d..c1c0a995 100644 --- a/skills/mono/references/products/devdoc.md +++ b/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 ` | 最优先；`--trace-id` 是兼容别名，最终按 `requestId` 传给 MCP | +| 错误码 + 错误描述 | `dws devdoc error diagnose --error-code --error-message ""` | 错误码进 `errorCode`，错误描述合并进 `query` | +| API 名 + 失败现象 | `dws devdoc error diagnose --query "<现象>" --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 名、错误码、能力名），不要过度改写 diff --git a/skills/mono/references/products/simple.md b/skills/mono/references/products/simple.md index a4f841ee..fc31b453 100644 --- a/skills/mono/references/products/simple.md +++ b/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 | diff --git a/skills/multi/dingtalk-devdoc/SKILL.md b/skills/multi/dingtalk-devdoc/SKILL.md index 9c717654..d0d092c8 100644 --- a/skills/multi/dingtalk-devdoc/SKILL.md +++ b/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` diff --git a/skills/multi/dingtalk-devdoc/references/devdoc.md b/skills/multi/dingtalk-devdoc/references/devdoc.md index 862e7b1d..c1c0a995 100644 --- a/skills/multi/dingtalk-devdoc/references/devdoc.md +++ b/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 ` | 最优先；`--trace-id` 是兼容别名，最终按 `requestId` 传给 MCP | +| 错误码 + 错误描述 | `dws devdoc error diagnose --error-code --error-message ""` | 错误码进 `errorCode`，错误描述合并进 `query` | +| API 名 + 失败现象 | `dws devdoc error diagnose --query "<现象>" --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 名、错误码、能力名），不要过度改写 diff --git a/skills/multi/dingtalk-skill/references/skill.md b/skills/multi/dingtalk-skill/references/skill.md index 850af6da..85fe6c19 100644 --- a/skills/multi/dingtalk-skill/references/skill.md +++ b/skills/multi/dingtalk-skill/references/skill.md @@ -12,19 +12,25 @@ Usage: dws devdoc article search [flags] Example: dws devdoc article search --query "OAuth2 接入" --page 1 --size 10 --format json + 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`。 + ## live — 直播 ### 查看我的直播列表 @@ -111,6 +119,7 @@ Args: ## 意图判断 - 用户说"开发文档/API 文档/接口文档" → `devdoc article search` +- 用户说"RAG 搜开放平台文档/查字段/查 scope/查回调配置" → `devdoc article search` - 用户说"调用报错/requestId/traceId/错误码/错误描述" → `devdoc error diagnose` - 用户说"直播/我的直播" → `live stream list` - 用户说"搜索技能/找技能/安装技能/技能市场" → `skill search` / `skill install`（按步骤衔接） @@ -119,8 +128,8 @@ Args: | 操作 | 从返回中提取 | 用于 | |------|-------------|------| -| `devdoc article search` | 文档链接 | 直接展示给用户 | -| `devdoc error diagnose` | diagnosticInfo、references、materials | 排查开放平台调用错误 | +| `devdoc article search` | 标题、摘要、材料、文档链接 | 基于 RAG 命中回答开放平台文档问题 | +| `devdoc error diagnose` | diagnosticInfo、references、materials | 排查开放平台调用错误；无命中时不要编造原因 | | `skill search` | `skillId`、名称、描述 | 用户选型后传给 `skill install ` | | `skill install` | 安装成功/失败信息 | 确认目标 Agent 目录已注册 | | `skill publish` | 发布结果（成功或错误信息） | 确认企业技能库已更新 |