From 6e91b2d1429de66a7e9aaf966a7292adefa0b43d Mon Sep 17 00:00:00 2001 From: audanye-sudo Date: Sun, 29 Mar 2026 23:33:41 +0800 Subject: [PATCH] docs: improve agent skill references and intent guide clarity - Enhance product skill docs with clearer examples and descriptions - Update intent-guide with better routing patterns - Expand simple.md with comprehensive onboarding examples - Fix inconsistent command references across skill docs --- skills/SKILL.md | 2 +- skills/references/global-reference.md | 18 +++-- skills/references/intent-guide.md | 6 +- skills/references/products/aitable.md | 4 +- skills/references/products/chat.md | 12 ++-- skills/references/products/contact.md | 16 ++--- skills/references/products/report.md | 2 +- skills/references/products/simple.md | 96 ++++++++++++++++++++++----- skills/references/products/todo.md | 10 +-- 9 files changed, 115 insertions(+), 51 deletions(-) diff --git a/skills/SKILL.md b/skills/SKILL.md index 2c7ec60e..9b2fb0a3 100644 --- a/skills/SKILL.md +++ b/skills/SKILL.md @@ -39,7 +39,7 @@ cli_version: ">=1.1.0" ## 意图判断决策树 用户提到"表格/多维表/AI表格/记录/数据" → `aitable` -用户提到"审批/请假/报销/出差/加班" → `approval` +用户提到"审批/请假/报销/出差/加班" → `oa` 用户提到"考勤/打卡/排班" → `attendance` 用户提到"日程/日历/会议室/约会" → `calendar` 用户提到"群聊/建群/群成员/群管理/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → `chat` diff --git a/skills/references/global-reference.md b/skills/references/global-reference.md index c25ca155..b74e5d21 100644 --- a/skills/references/global-reference.md +++ b/skills/references/global-reference.md @@ -3,7 +3,7 @@ ## 认证 ```bash -# 首次: 扫码登录 (浏览器自动打开) +# 首次: OAuth 设备流登录 (钉钉扫码授权) dws auth login # 查看状态 @@ -11,6 +11,9 @@ dws auth status # 退出 dws auth logout + +# 重置本地凭证 (Token 解密失败时使用) +dws auth reset ``` 登录后自动管理 token 刷新，日常使用无需重复登录。 @@ -28,11 +31,13 @@ dws auth logout ### Headless 环境 (CI/CD) ```bash -# 桌面: 导出凭证 -dws auth import credentials.json +# 通过环境变量配置认证（无需交互式登录） +export DWS_CLIENT_ID= +export DWS_CLIENT_SECRET= +dws auth login -# 服务器: 导入凭证 -dws auth import credentials.json +# 或使用 --device 设备流登录（远程服务器/Docker） +dws auth login --device ``` refresh_token 单设备独占，远程刷新后源设备凭证失效。 @@ -59,12 +64,13 @@ dws recovery finalize --event-id --outcome recovered|failed|handoff - | 标志 | 短名 | 说明 | 默认 | |------|:---:|------|------| | `--format` | `-f` | 输出格式: json / table / raw | json | +| `--jq` | | jq 表达式过滤输出 (如: `.items[] \| .name`) | 无 | +| `--fields` | | 筛选输出字段 (逗号分隔, 如: name,id,status) | 无 | | `--verbose` | `-v` | 详细日志 | false | | `--debug` | | 调试日志 | false | | `--yes` | `-y` | 跳过确认提示 | false | | `--dry-run` | | 预览操作不执行 | false | | `--timeout` | | HTTP 超时 (秒) | 30 | -| `--token` | | API Token (覆盖配置) | 无 | | `--mock` | | Mock 数据 (开发用) | false | | `--client-id` | | 覆盖 OAuth Client ID | 无 | | `--client-secret` | | 覆盖 OAuth Client Secret | 无 | diff --git a/skills/references/intent-guide.md b/skills/references/intent-guide.md index 5c134863..410a85d7 100644 --- a/skills/references/intent-guide.md +++ b/skills/references/intent-guide.md @@ -12,7 +12,7 @@ | "帮我建一个明天下午的日程" | 日历日程 | `calendar` | — | 日历日程管理（可含参与者/会议室）| | "帮我看看收到的日报" | 日志收件箱 | `report` | `todo` | 钉钉日志系统（日报/周报），不是待办 | | "帮我创建一个待办提醒" | 个人待办 | `todo` | `report` | 个人任务提醒，不是日志汇报 | -| "帮我提交请假审批" | 发起审批 | `approval` | — | 审批流程，不是待办或日志 | +| "帮我提交请假审批" | 发起审批 | `oa` | — | 审批流程，不是待办或日志 | | "帮我建一个项目群" | 创建群聊 | `chat group create` | — | 群聊管理，不是日历日程 | | "把张三拉进群" | 添加群成员 | `chat group members add` | — | 先查 userId，再添加 | | "让机器人在群里发个通知" | 机器人群发 | `chat message send-by-bot` | `chat message send-by-webhook` | 企业内部机器人发消息，需 robotCode | @@ -91,7 +91,7 @@ ```bash # 1. 搜索同事 userId -dws contact user search --query "张三" --format json +dws contact user search --keyword "张三" --format json # 2. 创建日程 dws calendar event create --title "会议" \ @@ -107,7 +107,7 @@ dws calendar participant add --event --users --format json ```bash # 1. 搜索同事 userId -dws contact user search --query "张三" --format json +dws contact user search --keyword "张三" --format json # 2. 创建待办 dws todo task create --title "任务内容" --executors --format json diff --git a/skills/references/products/aitable.md b/skills/references/products/aitable.md index ad4f0fa9..86c8ac87 100644 --- a/skills/references/products/aitable.md +++ b/skills/references/products/aitable.md @@ -236,13 +236,13 @@ Usage: Example: dws aitable record query --base-id --table-id dws aitable record query --base-id --table-id --record-ids rec1,rec2 - dws aitable record query --base-id --table-id --query "关键词" --limit 50 + dws aitable record query --base-id --table-id --keyword "关键词" --limit 50 Flags: --base-id string Base ID (必填) --cursor string 分页游标，首次不传 --field-ids string 返回字段 ID 列表，逗号分隔，单次最多 100 个 --filters string 结构化过滤条件 JSON - --query string 全文关键词搜索 + --keyword string 全文关键词搜索 --limit int 单次最大记录数，默认 100，最大 100 --record-ids string 指定记录 ID 列表，逗号分隔，单次最多 100 个 --sort string 排序条件 JSON 数组 diff --git a/skills/references/products/chat.md b/skills/references/products/chat.md index 5d0fc22b..91b2c2c5 100644 --- a/skills/references/products/chat.md +++ b/skills/references/products/chat.md @@ -6,7 +6,7 @@ |-------|------| | `search` | 搜索群聊 | | `group create` | 创建群 | -| `group members` | 查看群成员列表 | +| `group members list` | 查看群成员列表 | | `group members add` | 添加群成员 | | `group members remove` | 移除群成员（⚠️ 危险操作） | | `group members add-bot` | 添加机器人到群 | @@ -48,13 +48,13 @@ Flags: --- -## group members — 查看群成员列表 +## group members list — 查看群成员列表 ``` Usage: - dws chat group members [flags] + dws chat group members list [flags] Example: - dws chat group members --id --format json + dws chat group members list --id --format json Flags: --id string 群会话 ID (必填) --cursor string 分页游标 @@ -226,7 +226,7 @@ Flags: - 用户说"搜索一个群" → `search` - 用户说"帮我建个群" → `group create` -- 用户说"看看群里有谁" → `group members` +- 用户说"看看群里有谁" → `group members list` - 用户说"把张三拉进群" → 先 `contact user search` 获取 userId，再 `group members add` - 用户说"把张三移出群" → 先 `contact user search` 获取 userId，再 `group members remove`（⚠️ 需确认） - 用户说"改一下群名" → `group rename` @@ -245,7 +245,7 @@ Flags: # ── 工作流: 建群并添加机器人 ── # 1. 搜索同事 userId -dws contact user search --query "张三" --format json +dws contact user search --keyword "张三" --format json # 2. 创建群 dws chat group create --name "项目群" --users , --format json diff --git a/skills/references/products/contact.md b/skills/references/products/contact.md index d3629c55..4f00a6d2 100644 --- a/skills/references/products/contact.md +++ b/skills/references/products/contact.md @@ -17,9 +17,9 @@ Example: Usage: dws contact user search [flags] Example: - dws contact user search --query "张三" + dws contact user search --keyword "张三" Flags: - --query string 搜索关键词 (必填) + --keyword string 搜索关键词 (必填) ``` #### 按手机号搜索用户 @@ -49,9 +49,9 @@ Flags: Usage: dws contact dept search [flags] Example: - dws contact dept search --query "技术部" + dws contact dept search --keyword "技术部" Flags: - --query string 搜索关键词 (必填) + --keyword string 搜索关键词 (必填) ``` #### 查看部门成员 @@ -79,10 +79,10 @@ Flags: dws contact user get-self --format json # 2. 按名字搜索同事 — 提取 userId -dws contact user search --query "张三" --format json +dws contact user search --keyword "张三" --format json # 3. 查看部门结构 — 提取 deptId -dws contact dept search --query "技术部" --format json +dws contact dept search --keyword "技术部" --format json # 4. 查看部门成员 dws contact dept list-members --ids --format json @@ -94,7 +94,7 @@ dws contact dept list-members --ids --format json |------|------|------| | `user get-self/search` | `userId` | 其他产品中的 --users/--executor 参数 | | `user get-self/search` | `orgAuthEmail` | mail message send 的 --to/--cc (跨产品) | -| `dept search/list-children` | `deptId` | dept list-children/list-members 的 --id/--ids | +| `dept search` | `deptId` | dept list-members 的 --ids | ## 注意事项 @@ -105,4 +105,4 @@ dws contact dept list-members --ids --format json | 脚本 | 场景 | 用法 | |------|------|------| -| [contact_dept_members.py](../../scripts/contact_dept_members.py) | 按部门名称搜索并列出所有成员 | `python contact_dept_members.py --query "技术部"` | +| [contact_dept_members.py](../../scripts/contact_dept_members.py) | 按部门名称搜索并列出所有成员 | `python contact_dept_members.py --keyword "技术部"` | diff --git a/skills/references/products/report.md b/skills/references/products/report.md index e99fe9bf..72bff5b8 100644 --- a/skills/references/products/report.md +++ b/skills/references/products/report.md @@ -35,7 +35,7 @@ Flags: --template-id string 日志模版 ID (必填)，从 template list 返回中取 --contents string 日志内容 JSON 数组 (必填)，每项须含 key/sort/content/contentType/type --dd-from string 创建来源标识 (默认 dws) - --to-chat 是否发送到日志接收人单聊 (默认 false，传本 flag 则为 true) + --to-chat string 是否发送到日志接收人单聊 (传 "true" 发送) --to-user-ids string 接收人 userId，逗号分隔 (可选) ``` diff --git a/skills/references/products/simple.md b/skills/references/products/simple.md index 8a135721..f463210b 100644 --- a/skills/references/products/simple.md +++ b/skills/references/products/simple.md @@ -18,32 +18,90 @@ Flags: --size string 每页数量 (默认 10) ``` ---- - -## approval — 审批 - -### 查询审批表单 +### 搜索错误码 ``` Usage: - dws approval list-forms [flags] + dws devdoc article search-error [flags] Example: - dws approval list-forms --format json + dws devdoc article search-error --keyword "403" --format json +Flags: + --keyword string 错误码或关键词 (必填) +``` + +--- + +## oa — 审批 + +### 查询可见审批流程 +``` +Usage: + dws oa approval list-forms [flags] +Example: + dws oa approval list-forms --format json ``` ### 查询审批实例详情 ``` Usage: - dws approval detail --instance-id [flags] + dws oa approval detail --instance-id [flags] Example: - dws approval detail --instance-id --format json + dws oa approval detail --instance-id --format json ``` -### 查询审批任务 +### 查询审批记录 ``` Usage: - dws approval tasks --instance-id [flags] + dws oa approval records --instance-id [flags] Example: - dws approval tasks --instance-id --format json + dws oa approval records --instance-id --format json +``` + +### 查询待我审批的任务 +``` +Usage: + dws oa approval tasks [flags] +Example: + dws oa approval tasks --format json +``` + +### 查询待我处理的审批 +``` +Usage: + dws oa approval pending [flags] +Example: + dws oa approval pending --format json +``` + +### 查询我发起的审批 +``` +Usage: + dws oa approval initiated [flags] +Example: + dws oa approval initiated --format json +``` + +### 同意审批 +``` +Usage: + dws oa approval approve --instance-id --task-id [flags] +Example: + dws oa approval approve --instance-id --task-id --format json +``` + +### 拒绝审批 +``` +Usage: + dws oa approval reject --instance-id --task-id [flags] +Example: + dws oa approval reject --instance-id --task-id --remark "不符合要求" --format json +``` + +### 撤销审批 +``` +Usage: + dws oa approval revoke --instance-id [flags] +Example: + dws oa approval revoke --instance-id --format json ``` --- @@ -51,12 +109,20 @@ Example: ## 意图判断 - 用户说"开发文档/API 文档/接口文档" → `devdoc article search` -- 用户说"审批/请假/报销/出差" → `approval` +- 用户说"API 报错/错误码" → `devdoc article search-error` +- 用户说"审批/请假/报销/出差" → `oa approval` +- 用户说"同意审批/批准" → `oa approval approve` +- 用户说"拒绝审批/驳回" → `oa approval reject` +- 用户说"撤销审批/撤回" → `oa approval revoke` +- 用户说"待我审批/我要审批的" → `oa approval pending` 或 `oa approval tasks` +- 用户说"我发起的审批" → `oa approval initiated` ## 上下文传递表 | 操作 | 从返回中提取 | 用于 | |------|-------------|------| | `devdoc article search` | 文档链接 | 直接展示给用户 | -| `approval list-forms` | processCode | `approval detail` / `approval tasks` 等 | -| `approval tasks` | taskId | `approval approve` / `approval reject` | +| `oa approval list-forms` | processCode | detail / records 等 | +| `oa approval tasks` | taskId, instanceId | approve / reject | +| `oa approval pending` | instanceId | detail / approve / reject | +| `oa approval initiated` | instanceId | detail / revoke | diff --git a/skills/references/products/todo.md b/skills/references/products/todo.md index 17e7c7f8..fa9c526b 100644 --- a/skills/references/products/todo.md +++ b/skills/references/products/todo.md @@ -8,12 +8,11 @@ Usage: dws todo task create [flags] Example: dws todo task create --title "修复线上Bug" --executors , --priority 40 - dws todo task create --title "每日站会" --executors --due "2026-03-20T10:00:00+08:00" --recurrence "DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1" + dws todo task create --title "提交报告" --executors --due "2026-03-20T10:00:00+08:00" Flags: --due string 截止时间 ISO-8601 (如 2026-03-10T18:00:00+08:00) --executors string 执行者 userId 列表 (必填) --priority string 优先级: 10低/20普通/30较高/40紧急 - --recurrence string 循环待办 (需先设置 --due); 仅支持按天循环，格式见下方说明 --title string 待办标题 (必填) ``` @@ -81,7 +80,6 @@ Flags: ## 意图判断 用户说"加个待办/记一下/TODO" → `task create` -用户说"每天重复/循环待办/按天重复" → `task create`（需 `--due` + `--recurrence`） 用户说"看看待办/我有啥要做" → `task list` 用户说"改个待办/修改待办标题/改优先级" → `task update` 用户说"做完了/完成待办/标记完成" → `task done` @@ -97,11 +95,6 @@ Flags: dws todo task create --title "修复线上Bug" --executors userId1,userId2 \ --priority 40 --due "2026-03-10T18:00:00+08:00" --format json -# 1b. 创建按天循环的待办（必须先有 --due；recurrence 与 MCP create_personal_todo 一致） -dws todo task create --title "每日站会" --executors userId1 \ - --due "2026-03-20T10:00:00+08:00" \ - --recurrence "DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1" --format json - # 2. 查看未完成待办 dws todo task list --page 1 --size 20 --status false --format json @@ -129,7 +122,6 @@ dws todo task delete --task-id --yes --format json - 优先级值: 10=低, 20=普通, 30=较高, 40=紧急 - `--due` 截止时间使用 ISO-8601 格式（如 2026-03-10T18:00:00+08:00） -- `--recurrence`：仅在与 `--due` 同时设置时有效；当前仅支持按天循环。字符串内需含换行，示例：`DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1`（DTSTART 表示首次截止时间，需与业务约定一致） - `task list` 的 `--status` 对应 MCP `get_user_todos_in_current_org` 的 `todoStatus` 参数 - todo 是个人待办管理产品 - `task update` 可同时修改标题/优先级/截止时间/完成状态