Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 瑞达
|
7ef88d696b | ||
|
瑞达
|
891cf87c7f |
@@ -0,0 +1,301 @@
|
||||
# IM Chat Skill 精简与渐进加载优化方案
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `im-chat-skill-hint-align` 分支已经增强了 Chat Skill 的 Shortcut 路由、执行骨架、身份边界、查询与资源处理、低频原子回退和错误导航。与 Lark IM Skill 对比后，DWS 在 Agent 路由和执行约束上更直接，但根 Skill 仍存在以下问题：
|
||||
|
||||
- 高频执行骨架与核心意图表重复。
|
||||
- Runtime Shortcut Catalog、leaf Schema 和 leaf Help 的读取规则在多处重复。
|
||||
- Shortcut 错误处理与 Workflow 错误导航重复。
|
||||
- 身份、ID 和三种置顶对象的边界分散在不同章节。
|
||||
- 缺少简短、集中且可复用的核心对象与查询结果语义。
|
||||
- Frontmatter 能力召回仍可扩展，但不能削弱 DING、邮件和班级群等产品边界。
|
||||
|
||||
本方案只调整根文件 `skills/multi/dingtalk-chat/SKILL.md` 的组织和必要语义，不把 API 手册、完整 Shortcut 清单或权限表重新放回根 Skill。
|
||||
|
||||
## 2. 修改目标
|
||||
|
||||
1. 提高高频 Chat 意图的直接命中率，减少不必要的 Catalog、Schema 和 `--help` 调用。
|
||||
2. 提前建立渐进加载顺序，避免模型在高频任务中优先进入原子命令树。
|
||||
3. 补齐身份、核心对象、ID 和查询结果的必要语义，降低错误重试和 ID 混用。
|
||||
4. 合并重复 SOP，确保新增内容不会增加根 Skill 的总体 token。
|
||||
5. 保持参数、安全和完整 API 事实由 leaf Schema、Help 和 references 按需提供。
|
||||
|
||||
## 3. 设计原则
|
||||
|
||||
### 3.1 根 Skill 只保留决策必需信息
|
||||
|
||||
根 Skill 应负责：
|
||||
|
||||
- Skill 触发范围和跨产品排除边界。
|
||||
- 渐进加载与能力选择顺序。
|
||||
- 高频意图到精确 Shortcut 的映射。
|
||||
- 身份、ID、幂等、分页、部分失败等跨命令不变量。
|
||||
- 低频能力的导航入口。
|
||||
- 错误恢复和停止条件。
|
||||
|
||||
以下内容继续留在 Schema 或 references：
|
||||
|
||||
- 完整 Shortcut Catalog。
|
||||
- API Resources 全量列表。
|
||||
- 权限 scope 表。
|
||||
- 叶级参数全集和接口字段格式。
|
||||
- 只服务单个命令的实现细节。
|
||||
|
||||
### 3.2 渐进加载规则必须早于命令骨架
|
||||
|
||||
模型应在看到具体命令前，先知道何时直接执行、何时才加载额外上下文。但完整一级命令树不应提前，以免低频原子命令干扰高频 Shortcut 选择。
|
||||
|
||||
### 3.3 同一事实只保留一个权威位置
|
||||
|
||||
- 高频 Shortcut 只出现在一张核心意图表中。
|
||||
- Catalog、Schema 和 Help 的读取顺序只定义一次。
|
||||
- 错误恢复与 reference 导航只定义一次。
|
||||
- 身份、对象和 ID 的公共边界集中定义，后续章节只引用，不重复解释。
|
||||
|
||||
## 4. 目标章节结构
|
||||
|
||||
```text
|
||||
1. Frontmatter
|
||||
2. Preconditions
|
||||
3. 加载与路由顺序
|
||||
4. 核心对象与 ID
|
||||
5. 核心意图与执行骨架
|
||||
6. 统一发送
|
||||
7. 查询、资源与卡片
|
||||
8. 低频原子路由
|
||||
├── 一级命令树
|
||||
├── branch references
|
||||
└── 低频操作回退表
|
||||
9. 错误恢复与按需 Reference
|
||||
10. 跨产品协作
|
||||
```
|
||||
|
||||
## 5. 具体修改
|
||||
|
||||
### 5.1 扩展 Frontmatter 产品能力
|
||||
|
||||
扩展 `description` 的正向能力召回，覆盖：
|
||||
|
||||
- 单聊、群聊、建群、群搜索和群成员管理。
|
||||
- 消息发送、回复、转发、撤回、查询和聊天记录搜索。
|
||||
- 图片、文件和消息资源下载。
|
||||
- 表情回应、收藏、Pin、消息置顶和会话置顶。
|
||||
- 应用机器人、Webhook 和互动卡片。
|
||||
- 未读、红点、消息已读状态和会话分类。
|
||||
|
||||
同时保留明确排除：
|
||||
|
||||
- DING、短信和电话转到 `dingtalk-ding`。
|
||||
- 邮件转到 `dingtalk-mail`。
|
||||
- 班级群转到对应的低频产品 Skill。
|
||||
- 找人本身由 `dingtalk-contact` 或 `dingtalk-aisearch` 负责，Chat 只消费真实人员 ID。
|
||||
|
||||
Frontmatter 只描述真实能力和路由边界，不加入参数、SOP 或 token 实现细节。
|
||||
|
||||
### 5.2 前移并合并渐进加载规则
|
||||
|
||||
将现有“Shortcut 发现”“Shortcut 执行契约”和“渐进加载与一级路由”的加载决策部分合并为紧随 Preconditions 的唯一章节：
|
||||
|
||||
```markdown
|
||||
## 加载与路由顺序
|
||||
|
||||
1. 已知高频意图：直接使用“核心意图与执行骨架”，不查 Help。
|
||||
2. 已有匹配 Shortcut：直接执行；参数、约束或安全不确定时才查 leaf Schema。
|
||||
3. 仅 Cobra flags 不确定时查 leaf `--help`。
|
||||
4. 现有路由无法定位低频能力时，才查 Runtime Shortcut Catalog。
|
||||
5. 没有 Shortcut 时，按需读取对应 branch reference，进入原子命令。
|
||||
```
|
||||
|
||||
同一章节保留以下公共规则：
|
||||
|
||||
- 路由优先级为 `exact recipe/runnable script > public Shortcut > atomic command`。
|
||||
- 不猜测 `cli_path` 或参数名称。
|
||||
- `confirmation=user_required` 时先确认，再添加 `--yes`。
|
||||
- 来源冲突时采用更安全的解释并报告契约漂移。
|
||||
- 命令已确定且参数清楚时直接执行，不为验证已知路径重复发现。
|
||||
|
||||
删除其他章节重复出现的 Catalog、Schema、Help 选择说明。
|
||||
|
||||
### 5.3 新增“核心对象与 ID”小表
|
||||
|
||||
增加不超过 8 行的表格，集中表达：
|
||||
|
||||
| 对象 | 核心标识与边界 |
|
||||
|---|---|
|
||||
| 人员 | 姓名必须先解析成唯一真实的 `userId` 或 `openDingTalkId`，名称不能作为 ID 传递 |
|
||||
| 会话 | 使用真实 `openConversationId` / cid；群名只能用于 Shortcut 的目标解析 |
|
||||
| 消息 | 使用真实 `openMessageId` / msgId，并保持与身份及会话一致 |
|
||||
| 发送任务 | `openTaskId` 只用于查询发送状态，不能替代消息 ID |
|
||||
| Thread | thread/topic ID 必须绑定真实会话，不跨会话复用 |
|
||||
| 身份 | current-user、app-bot 和 Webhook 是不同操作者，不能自动互换 |
|
||||
| 状态 | 收藏、消息置顶、消息 Pin 和会话置顶作用于不同对象 |
|
||||
|
||||
新增后删除后文对这些边界的重复说明。
|
||||
|
||||
### 5.4 合并高频骨架与核心意图表
|
||||
|
||||
删除独立的“高频直接执行骨架”，将其全部合入唯一的“核心意图与执行骨架”表。表格固定为三列：
|
||||
|
||||
| 用户意图 | 精确 Shortcut 骨架 | 必须保留的执行边界 |
|
||||
|---|---|---|
|
||||
|
||||
至少覆盖以下高频场景：
|
||||
|
||||
- 姓名发单聊、群名发群消息。
|
||||
- user、bot、webhook 三种身份发送。
|
||||
- 建群、改群名、拉人和成员查询。
|
||||
- 拉取会话消息、查询详情、撤回和发送状态。
|
||||
- 关键词搜索、组合搜索和查询 @ 我的消息。
|
||||
- 群邀请链接和群机器人。
|
||||
- 会话置顶和收藏列表。
|
||||
- 查和某人的聊天记录。
|
||||
- 群消息翻页导出。
|
||||
- 机器人多群广播。
|
||||
|
||||
表中直接给出正确参数骨架；命中后照抄参数名，不先调用 `--help`。同一个 Shortcut 不再在其他表中重复列出。
|
||||
|
||||
### 5.5 补充统一身份规则
|
||||
|
||||
在“统一发送”开头加入统一规则：
|
||||
|
||||
> 身份决定真实操作者、可见范围和可用能力；同一目标使用 user、bot 或 webhook 时，结果和权限可能不同，禁止自动切换身份重试。
|
||||
|
||||
继续保留：
|
||||
|
||||
- 发送前检查身份、目标、正文、标题、@、消息类型和附件路径。
|
||||
- 重试复用相同 `--idempotency-key`。
|
||||
- user、bot、webhook 的精确发送模板。
|
||||
- @ 占位符、新行和文件能力边界。
|
||||
|
||||
不加入 Lark 的 access token 类型说明。
|
||||
|
||||
### 5.6 补充查询结果与增强失败语义
|
||||
|
||||
在“查询、资源与卡片”中增加：
|
||||
|
||||
- 发送者名称缺失时保留真实 ID，不猜姓名，也不自动扩大通讯录查询。
|
||||
- 可选增强字段缺失不代表主查询失败；增强请求失败时保留主结果并写入 per-item ledger。
|
||||
|
||||
继续保留：
|
||||
|
||||
- `--page-all` 只在确需完整分页时使用。
|
||||
- 部分失败保留已有结果，禁止把不完整结果声明为完整。
|
||||
- 资源下载默认关闭，显式请求后才增加请求和本地输出。
|
||||
- 子消息资源优先使用子 `messageId`。
|
||||
- 输出路径、覆盖、HTTPS 和重定向安全限制。
|
||||
|
||||
### 5.7 拆分“渐进加载”与“一级命令树”
|
||||
|
||||
前移的只有加载决策。完整一级命令树及 branch references 改名为“低频原子路由”，保留在高频意图、统一发送和查询规则之后。
|
||||
|
||||
这样可以：
|
||||
|
||||
- 防止高频任务优先进入 atomic branch。
|
||||
- 降低不必要的 Schema 和 Help 查询。
|
||||
- 继续为没有 Shortcut 的能力提供确定导航。
|
||||
|
||||
低频原子回退表继续保留收藏、编辑、外部群升级、群昵称、分类、共同群、群公告、群身份、置顶、未读、已读、授权、退群和解散群等差异化入口。
|
||||
|
||||
### 5.8 合并错误恢复与 Workflow 导航
|
||||
|
||||
将现有“Shortcut 错误处理”和“Workflow 与错误导航”合并为：
|
||||
|
||||
```markdown
|
||||
## 错误恢复与按需 Reference
|
||||
```
|
||||
|
||||
只保留以下规则：
|
||||
|
||||
- 路径或参数错误时，按 Catalog、Schema、Help 的既定顺序校正一次。
|
||||
- 始终从实际输出重新提取下游 ID。
|
||||
- 复杂消息任务按需读取 `01-messaging.md`。
|
||||
- Onboarding 按需读取对应 workflow。
|
||||
- 命令错误按需读取 `chat-error-recovery.md`。
|
||||
- 权限不足、歧义未消除、无结果或契约冲突时停止并报告。
|
||||
|
||||
删除其他位置重复的 `01-messaging.md` 和错误恢复入口。
|
||||
|
||||
### 5.9 保留跨产品协作边界
|
||||
|
||||
继续保留根 Skill 中不可由 Chat 自己完成的路由：
|
||||
|
||||
- 人名解析到 Contact / AISearch。
|
||||
- DING、短信和电话到 Ding Skill。
|
||||
- 邮件到 Mail Skill。
|
||||
- 本地文件与已有 mediaId 的发送差异。
|
||||
|
||||
如果某项边界已经在 Frontmatter 或核心对象表中完整表达，正文只保留执行阶段真正需要的补充，不重复整段说明。
|
||||
|
||||
## 6. 删除与合并清单
|
||||
|
||||
| 当前内容 | 处理方式 |
|
||||
|---|---|
|
||||
| “Shortcut 发现（按需）” | 合入前置“加载与路由顺序” |
|
||||
| “Shortcut 执行契约” | 公共规则合入前置章节 |
|
||||
| “高频直接执行骨架” | 删除，内容合入核心意图表 |
|
||||
| “渐进加载与一级路由”中的加载说明 | 前移并去重 |
|
||||
| 完整一级命令树 | 保留，改放“低频原子路由” |
|
||||
| “Shortcut 错误处理” | 合入统一错误章节 |
|
||||
| “Workflow 与错误导航” | 合入统一错误章节 |
|
||||
| 分散的身份、ID、置顶说明 | 合入核心对象表或统一身份规则 |
|
||||
| 重复的 `01-messaging.md` 入口 | 只保留一处 |
|
||||
|
||||
## 7. 不纳入本次修改
|
||||
|
||||
- 不展开 97 个公开 Shortcut。
|
||||
- 不复制 Lark 的完整 API Resources 和权限 scope 表。
|
||||
- 不在根 Skill 中维护 leaf 参数全集。
|
||||
- 不引入与当前 CLI 不一致的新命令或参数。
|
||||
- 不改变 Schema、Help、Runtime Catalog 和 reference 的事实优先级。
|
||||
- 不通过增加默认查询、自动通讯录查询或默认资源增强来换取结果丰富度。
|
||||
|
||||
## 8. 实施顺序
|
||||
|
||||
1. 更新 Frontmatter description，确认能力召回和排除边界。
|
||||
2. 合并并前移“加载与路由顺序”。
|
||||
3. 新增“核心对象与 ID”表，删除相应重复边界。
|
||||
4. 合并高频骨架和核心意图表。
|
||||
5. 补充统一身份规则。
|
||||
6. 补充查询结果和增强失败语义。
|
||||
7. 将一级命令树调整为后置的“低频原子路由”。
|
||||
8. 合并错误恢复与 reference 导航。
|
||||
9. 全文检查重复命令、重复 reference 和冲突参数。
|
||||
10. 运行 Skill 格式及相关策略测试，并用高频场景做静态路由验证。
|
||||
|
||||
## 9. 验收标准
|
||||
|
||||
### 9.1 内容与结构
|
||||
|
||||
- 根 Skill 中只有一份 Catalog、Schema、Help 读取顺序。
|
||||
- 根 Skill 中只有一张高频意图与 Shortcut 骨架表。
|
||||
- 根 Skill 中只有一个错误恢复章节。
|
||||
- `01-messaging.md` 的同类导航不重复。
|
||||
- 核心对象与 ID 表不超过 8 行数据。
|
||||
- 一级原子命令树位于高频路由之后。
|
||||
- Frontmatter 同时覆盖主要产品能力和明确排除边界。
|
||||
|
||||
### 9.2 执行行为
|
||||
|
||||
- “发给某人”“发到某群”“查 @ 我”“改群名”等高频意图可直接选中已评审 Shortcut，不先查 Help。
|
||||
- 低频未知意图才触发 Runtime Shortcut Catalog。
|
||||
- 参数或安全不确定时读取 leaf Schema；只有 Cobra flags 不确定时读取 leaf Help。
|
||||
- user、bot、webhook 不被自动互换。
|
||||
- `openTaskId`、消息 ID、会话 ID 不混用。
|
||||
- 发送者名称或 reaction 等增强缺失时，不把主查询误判为失败。
|
||||
- 部分失败保留已有结果并明确报告 ledger/completeness。
|
||||
|
||||
### 9.3 Token 与维护成本
|
||||
|
||||
- 修改后的根 Skill 不超过当前 211 行，并以不丢失必要路由和边界为前提尽量低于 195 行。
|
||||
- 文件单词数和字符数不高于修改前基线。
|
||||
- 新增内容通过删除重复 SOP 抵消。
|
||||
- 不新增完整 Shortcut、API 或权限清单。
|
||||
|
||||
## 10. 预期收益
|
||||
|
||||
- 减少高频任务中的 `--help` 和重复 Schema 查询。
|
||||
- 降低因身份切换、ID 混用和发送者名称缺失导致的错误重试。
|
||||
- 让 Shortcut、Schema、Help、Catalog 和 references 各自保持单一职责。
|
||||
- 在不增加默认 token 和耗时的前提下，提高 Chat Skill 的选择准确率和执行成功率。
|
||||
- 降低后续新增 Shortcut 时同时维护多张表和多处规则的漂移风险。
|
||||
@@ -11145,7 +11145,8 @@
|
||||
"agent_summary_source": "dws-agent-selection/chat",
|
||||
"availability": "available",
|
||||
"avoid_when": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"confirmation": "not_required",
|
||||
"effect": "read",
|
||||
@@ -11189,7 +11190,8 @@
|
||||
},
|
||||
"avoid_when": {
|
||||
"value": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"source": "internal/cli/schema_hints/selection/chat.json",
|
||||
"precedence": "reviewed_explicit",
|
||||
@@ -11198,7 +11200,8 @@
|
||||
"candidates": [
|
||||
{
|
||||
"value": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"source": "internal/cli/schema_hints/selection/chat.json",
|
||||
"precedence": "reviewed_explicit",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"version": 1,
|
||||
"source_hash": "sha256:eedf9163f496888aa3a065bdbd85647e3702a73ce74703f27083059e22a74098",
|
||||
"source_hash": "sha256:7111ced2e1cd0764338aacce792d95603734177a82deea4a4642626691940485",
|
||||
"surface_hash": "sha256:4897d582a472d9d3596f88fb4546e7795d6b9bc334d020712f5d895ce894f7a7",
|
||||
"coverage": {
|
||||
"surface_products": 26,
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"version": 1,
|
||||
"source_hash": "sha256:eedf9163f496888aa3a065bdbd85647e3702a73ce74703f27083059e22a74098",
|
||||
"source_hash": "sha256:7111ced2e1cd0764338aacce792d95603734177a82deea4a4642626691940485",
|
||||
"surface_hash": "sha256:4897d582a472d9d3596f88fb4546e7795d6b9bc334d020712f5d895ce894f7a7",
|
||||
"source_files": 160,
|
||||
"hint_files": 54,
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"version": 1,
|
||||
"surface_hash": "sha256:4897d582a472d9d3596f88fb4546e7795d6b9bc334d020712f5d895ce894f7a7",
|
||||
"source_hash": "sha256:113dbc3507c5e4d871802d567e960c4947b8066472c28fb8a6dc64e9fef36da9",
|
||||
"source_hash": "sha256:a862c8d93ff1e66de35a0148aeea6e269cf19587b12bebfb53f4fff8a4a71cc6",
|
||||
"catalog": {
|
||||
"agent_metadata": {
|
||||
"products_with_metadata": 26,
|
||||
"source": "embedded-skill-metadata",
|
||||
"source_hash": "sha256:eedf9163f496888aa3a065bdbd85647e3702a73ce74703f27083059e22a74098",
|
||||
"source_hash": "sha256:7111ced2e1cd0764338aacce792d95603734177a82deea4a4642626691940485",
|
||||
"surface_hash": "sha256:4897d582a472d9d3596f88fb4546e7795d6b9bc334d020712f5d895ce894f7a7",
|
||||
"surface_products": 26,
|
||||
"surface_tools": 875,
|
||||
@@ -11579,7 +11579,8 @@
|
||||
"agent_summary_source": "dws-agent-selection/chat",
|
||||
"availability": "available",
|
||||
"avoid_when": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"canonical_path": "chat.shortcut_search_msg",
|
||||
"cli_name": "+search-msg",
|
||||
|
||||
@@ -94279,7 +94279,8 @@
|
||||
"agent_summary_source": "dws-agent-selection/chat",
|
||||
"availability": "available",
|
||||
"avoid_when": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"canonical_path": "chat.shortcut_search_msg",
|
||||
"cli_name": "+search-msg",
|
||||
@@ -94379,7 +94380,8 @@
|
||||
"selected": true,
|
||||
"source": "internal/cli/schema_hints/selection/chat.json",
|
||||
"value": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
]
|
||||
}
|
||||
],
|
||||
@@ -94388,7 +94390,8 @@
|
||||
"review_reason": "Agent-authored from the verified filter mapping, cursor pagination, batched mget enrichment, completeness ledger, and shared safe resource workflow.",
|
||||
"source": "internal/cli/schema_hints/selection/chat.json",
|
||||
"value": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
]
|
||||
},
|
||||
"canonical_path": {
|
||||
|
||||
@@ -3023,7 +3023,8 @@
|
||||
"当你要按关键词、发送者、@对象、会话、消息类型或机器人来源组合搜索 IM 消息时使用；默认查询近 7 天，也可指定精确起止时间。--page-all 会连续拉取游标页，默认再按消息 ID 分批富化详情；任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger，绝不把截断结果标成完整。--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"
|
||||
],
|
||||
"avoid_when": [
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget"
|
||||
"只想读取一个已知会话的连续历史时使用 +chat-messages；已有精确消息 ID 时使用 +messages-mget",
|
||||
"按群名找群或解析群 openConversationId 时不要使用；改用 +chat-search"
|
||||
],
|
||||
"examples": [
|
||||
"dws chat +search-msg --query \"周报\" --senders <openDingTalkId> --days 3 --page-all",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: dingtalk-chat
|
||||
description: 钉钉群聊与消息。Use when 用户提到 发消息/单聊/群聊/建群/拉人进群/改群名/搜索群/群成员管理/@消息/撤回消息/机器人群发/Webhook通知/发图片或文件到群/标记未读/清除红点/置顶消息/全部群列表。不做紧急 DING/短信/电话（走 dingtalk-ding）、邮件（走 dingtalk-mail）、班级群（走 dingtalk-misc）。命令前缀：dws chat。
|
||||
description: 钉钉群聊与消息。Use when 用户提到 发消息/单聊/群聊/建群/搜群或消息/聊天记录/群成员管理/回复转发撤回/@消息/表情回应/图片文件与资源下载/机器人群发/Webhook通知/互动卡片/收藏与Pin/消息或会话置顶/未读与红点/已读状态/会话分类。不做紧急 DING/短信/电话（走 dingtalk-ding）、邮件（走 dingtalk-mail）、班级群（走 dingtalk-misc）；找人本身走 dingtalk-contact 或 dingtalk-aisearch。命令前缀：dws chat。
|
||||
metadata:
|
||||
cli_version: ">=0.2.14"
|
||||
category: product
|
||||
@@ -15,7 +15,7 @@ metadata:
|
||||
|
||||
> **CRITICAL — Before any `dws` operation, MUST fully read [`dws-shared`](../dws-shared/SKILL.md).** It defines the global execution contract, safety floor, and on-demand shared-reference routing. Do not preload all of its references.
|
||||
|
||||
> Command reference: [chat.md](references/chat.md); emoji list: [chat-emoji-list.md](references/chat-emoji-list.md); workflows: [01-messaging.md](references/01-messaging.md).
|
||||
> Command reference: [chat.md](references/chat.md); emoji list: [chat-emoji-list.md](references/chat-emoji-list.md).
|
||||
|
||||
<!-- VISIBLE_SHORTCUTS_START -->
|
||||
## Shortcut 发现（按需）
|
||||
@@ -25,42 +25,51 @@ metadata:
|
||||
仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service chat --compact --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
|
||||
<!-- VISIBLE_SHORTCUTS_END -->
|
||||
|
||||
## Shortcut 执行契约
|
||||
## 加载与路由顺序
|
||||
|
||||
This is the only Shortcut entry point for multi/chat; `references/` documents
|
||||
atomic commands only. Routing priority:
|
||||
exact recipe/runnable script > matching public Shortcut > atomic command.
|
||||
Skip a script if its interpreter (for example, `python3`) is unavailable.
|
||||
This is the only Shortcut entry point for multi/chat; `references/` documents atomic commands only. Use `exact recipe/runnable script > matching public Shortcut > atomic command`; skip an optional script if its interpreter is unavailable.
|
||||
|
||||
- Select a real `cli_path` from the high-frequency routes below; never guess names.
|
||||
Use `dws shortcut list --service chat --compact --format json` only when no
|
||||
reviewed route matches.
|
||||
- Once selected, execute directly. Read leaf Schema only when parameters,
|
||||
constraints, or safety are uncertain; read leaf `--help` only when flags are
|
||||
uncertain. If absent from Schema, use the same path in the Runtime Shortcut
|
||||
Catalog.
|
||||
- For `confirmation=user_required`, confirm before adding `--yes`. On source
|
||||
conflict, use the safer interpretation and report it.
|
||||
1. 已知高频意图：直接使用“核心意图与执行骨架”，命中后照抄参数名，不先调用 `--help`。
|
||||
2. 已有匹配 Shortcut：直接执行；参数、约束或安全不确定时才读 leaf Schema。
|
||||
3. 仅当前 Cobra flags 不确定时读 leaf `--help`。
|
||||
4. 现有路由无法定位低频能力时才查 Runtime Shortcut Catalog；select a real `cli_path` and never guess names.
|
||||
5. 没有 Shortcut 时，按需读取对应 branch reference，进入原子命令。
|
||||
|
||||
### 高频直接执行骨架
|
||||
For `confirmation=user_required`, confirm before adding `--yes`. On source conflict, use the safer interpretation and report it.
|
||||
|
||||
命中后照抄参数名，不先调用 `--help`。
|
||||
## 核心对象与 ID
|
||||
|
||||
| 用户意图 | 精确 Shortcut 骨架 |
|
||||
| 对象 | 核心标识与边界 |
|
||||
|---|---|
|
||||
| 姓名发单聊 / 群名发群消息 | `+dm --to <姓名> --text <内容>` / `+send-to-group --group <群名> --text <内容>` |
|
||||
| 三种身份发消息 | `+messages-send --as user|bot|webhook`；按下方身份模板补参数 |
|
||||
| 改群名 | `+chat-update --group <openConversationId> --name <新群名>` |
|
||||
| 列成员 / 批查成员 | `+chat-members-list --group <群名>` 或 `--conversation-id <cid>` / `+chat-members-get --id <cid> --users <odid,...>` |
|
||||
| 消息详情 / 撤回 / 发送状态 | `+messages-mget --msg-ids <mid,...>` / `+messages-recall --conversation-id <cid> --msg-id <mid>` / `+messages-query-send-status --open-task-id <tid>` |
|
||||
| 查 @ 我的消息 | 全局用 `+at-me --days <N>`；限定群用 `+search-msg --at-me --group <cid>`，不要给 `+at-me` 猜群参数 |
|
||||
| 群邀请链接 / 群机器人 | 先 `+chat-search --query <群名>` 取 cid，再 `+chat-invite-url --group <cid>` / `+chat-bots --group <cid>` |
|
||||
| 会话置顶 / 收藏列表 | `+conversation-set-top --conversation-id <cid> [--off]` / `+flag-list --size <1-100>` |
|
||||
| 人员 | 姓名必须解析成唯一真实的 `userId` / `openDingTalkId`，不能把名称当 ID |
|
||||
| 会话 | 使用真实 `openConversationId` / cid；群名只用于 Shortcut 目标解析 |
|
||||
| 消息 | 使用真实 `openMessageId` / msgId，并保持与身份和会话一致 |
|
||||
| 发送任务 | `openTaskId` 只用于查询发送状态，不能替代消息 ID |
|
||||
| Thread | thread/topic ID 必须绑定真实会话，不跨会话复用 |
|
||||
| 身份 | current-user、app-bot、Webhook 是不同操作者，不能自动互换 |
|
||||
| 状态 | 收藏、消息置顶、消息 Pin、会话置顶作用于不同对象 |
|
||||
|
||||
### 统一发送
|
||||
## 核心意图与执行骨架
|
||||
|
||||
Before sending, verify identity, target, body, title, mentions, message type,
|
||||
and attachment path; ask if ambiguous. Reuse the same `--idempotency-key` on retry.
|
||||
Prefer the exact Shortcut below; otherwise use the atomic fallback. Apply shared `--format json` and take downstream IDs from actual output. Every Chat workflow must work without Python.
|
||||
|
||||
| 用户意图 | 精确 Shortcut 骨架 / 原子回退 | 必须保留的执行边界 |
|
||||
|---|---|---|
|
||||
| 姓名发单聊 / 群名发群消息 | `+dm --to <姓名> --text <内容>` / `+send-to-group --group <群名> --text <内容>` | Resolve one real person or cid; mentions/`@all` use `+messages-send` |
|
||||
| user / bot / webhook 发消息 | `+messages-send --as user|bot|webhook` / 对应 `message send*` | Identity determines the operator; use the matching target and content flags |
|
||||
| 建群 / 改群名 / 拉人 | `+chat-create --name <群名> --users <uid,...>` / `+chat-update --group <cid> --name <新群名>` / `group members add` | Resolve every member; extract the new cid before follow-up actions |
|
||||
| 列成员 / 批查成员 | `+chat-members-list --group <群名>` 或 `--conversation-id <cid>` / `+chat-members-get --id <cid> --users <odid,...>` | Stop on ambiguous group names; keep user and bot bucket failures |
|
||||
| 拉会话消息 / 查某人记录 | `+chat-messages` / `message list` | Select one group or DM target; use the requested or explicitly narrowed time boundary |
|
||||
| 搜消息 / 查 @ 我 | `+search-msg --query <关键词>`；全局 `+at-me --days <N>`；群内 `+search-msg --at-me --group <cid>` | Add only real filters; never invent group flags for `+at-me` |
|
||||
| 消息详情 / 撤回 / 发送状态 | `+messages-mget --msg-ids <mid,...>` / `+messages-recall --conversation-id <cid> --msg-id <mid>` / `+messages-query-send-status --open-task-id <tid>` | Recall only when explicit; use IDs from the same identity and conversation |
|
||||
| 群邀请链接 / 群机器人 | `+chat-search --query <群名>` → `+chat-invite-url --group <cid>` / `+chat-bots --group <cid>` | Reuse the resolved cid; do not search again by a guessed name |
|
||||
| 会话置顶 / 收藏列表 | `+conversation-set-top --conversation-id <cid> [--off]` / `+flag-list --size <1-100>` | Do not confuse conversation top with message top, Pin, or favorite |
|
||||
| 群消息完整导出 | `+chat-messages`; save merged JSON if requested | Follow pagination to completion; report partial results as incomplete |
|
||||
| 机器人多群广播 | Call `+messages-send-by-bot` once per resolved group | Confirm recipients once; preserve one body and return a per-group ledger |
|
||||
|
||||
## 统一发送
|
||||
|
||||
身份决定真实操作者、可见范围和可用能力；同一目标使用 user、bot 或 webhook 时结果和权限可能不同，禁止自动切换身份重试。Before sending, verify identity, target, body, title, mentions, message type, and attachment path; ask if ambiguous. Reuse the same `--idempotency-key` on retry.
|
||||
|
||||
```bash
|
||||
dws chat +messages-send --as user --chat-id <openConversationId> --text "内容" --idempotency-key <key> --format json
|
||||
@@ -71,47 +80,26 @@ dws chat +messages-send --as bot --robot-code <robotCode> --chat-id <openConvers
|
||||
dws chat +messages-send --as webhook --webhook-token <token> --title "告警" --text "内容" --at-all --format json
|
||||
```
|
||||
|
||||
- `user` supports text, Markdown, existing mediaId images, and local files.
|
||||
Audio/video use `--file` and are sent as files.
|
||||
- `bot` supports group or batch-DM text/Markdown. A webhook token selects its
|
||||
chat. Neither identity supports files.
|
||||
- The Shortcut normalizes @ placeholders. Pass only required `--at-*` /
|
||||
`--at-all`; never construct `@10` manually.
|
||||
- Newlines in `--text` / `--markdown` must be real `U+000A`; separate Markdown
|
||||
paragraphs with a blank line.
|
||||
- `user` supports text, Markdown, existing mediaId images, and local files. Audio/video use `--file` and are sent as files.
|
||||
- `bot` supports group or batch-DM text/Markdown. A webhook token selects its chat. Neither identity supports files.
|
||||
- Pass only required `--at-*` / `--at-all`; never construct `@10` manually. Use real `U+000A` newlines and a blank line between Markdown paragraphs.
|
||||
|
||||
### 查询、资源与卡片
|
||||
## 查询、资源与卡片
|
||||
|
||||
- `+search-msg --page-all` paginates and enriches in batches. On partial
|
||||
failure, preserve results and return a per-item ledger.
|
||||
- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies`
|
||||
support `--download-resources --output-dir ./downloads [--overwrite]`.
|
||||
For nested resources, prefer the child `messageId` in `resourceRefs`;
|
||||
inherit the parent only if the chat ID is missing.
|
||||
- These queries and `+messages-resource-download` are `read/not_required`;
|
||||
never pass `--yes`. Output must be a relative path inside the working
|
||||
directory without `..`; pass `--overwrite` only when explicitly requested.
|
||||
- Accept reviewed DingTalk/public OSS HTTPS URLs only. Validate every redirect
|
||||
and never forward headers across hosts.
|
||||
- `+messages-send-card` 的 `--group`、`--receiver`、`--receiver-open-dingtalk-id`
|
||||
are mutually exclusive. With `--content`, update immediately; otherwise
|
||||
return `bizId`. The final `+messages-update-card` call must use `--flow-status 3`.
|
||||
- `+search-msg` 只搜索消息内容；禁止用于按群名找群或解析群 CID。
|
||||
- `+search-msg --page-all` paginates and enriches in batches; use it only when complete pagination is required.
|
||||
- Preserve primary results on partial failure and return a per-item ledger; never claim an incomplete result is complete.
|
||||
- If a sender name is absent, keep the real sender ID; do not guess a name or expand into an unrequested directory lookup.
|
||||
- A missing optional enrichment is not a primary-query failure; record enrichment failures in the ledger.
|
||||
- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` support `--download-resources --output-dir ./downloads [--overwrite]`; resource download is opt-in.
|
||||
- For nested resources, prefer the child `messageId` in `resourceRefs`; inherit the parent only if the chat ID is missing.
|
||||
- These queries and `+messages-resource-download` are `read/not_required`; never pass `--yes`. Keep output relative, inside the working directory, without `..`; add `--overwrite` only when requested.
|
||||
- Accept reviewed DingTalk/public OSS HTTPS URLs only. Validate every redirect and never forward headers across hosts.
|
||||
- `+messages-send-card` 的 `--group`、`--receiver`、`--receiver-open-dingtalk-id` are mutually exclusive. With `--content`, update immediately; otherwise return `bizId`. The final `+messages-update-card` call uses `--flow-status 3`.
|
||||
|
||||
### Shortcut 错误处理
|
||||
## 低频原子路由
|
||||
|
||||
If a leaf is missing or parameters are invalid, check the full Catalog,
|
||||
Schema, and `--help`, then correct once. Re-extract IDs from actual output.
|
||||
Stop and report insufficient permission, unresolved ambiguity, no result, or
|
||||
contract conflict.
|
||||
|
||||
## 渐进加载与一级路由
|
||||
|
||||
After choosing atomic fallback, select a top-level branch. If sibling commands
|
||||
are ambiguous, read [intent-guide.md](references/intent-guide.md), then locate
|
||||
the leaf in [chat.md](references/chat.md#命令索引表). If parameters, constraints,
|
||||
or safety are uncertain, read
|
||||
`dws schema --cli-path "chat <leaf>" --format json`; use leaf `--help` only
|
||||
when Cobra flags are uncertain.
|
||||
Use this section only when no public Shortcut matches. If sibling commands are ambiguous, read [intent-guide.md](references/intent-guide.md), locate the leaf in [chat.md](references/chat.md#命令索引表), then load only the matching branch reference.
|
||||
|
||||
```text
|
||||
dws chat
|
||||
@@ -124,43 +112,10 @@ dws chat
|
||||
├── mute* / hide / set-top
|
||||
├── mark-* / clear-* # read/unread, red dots, message clearing
|
||||
├── text / chmod / data-auth
|
||||
├── +shortcut
|
||||
└── scripts
|
||||
```
|
||||
|
||||
Load branch details on demand: [消息](references/chat/chat-message.md),
|
||||
[群与成员](references/chat/chat-group.md),
|
||||
[机器人与 Webhook](references/chat/chat-bot.md), and
|
||||
[会话状态与分组](references/chat/chat-conversation.md).
|
||||
|
||||
## 核心意图与执行边界
|
||||
|
||||
Use this table to disambiguate identity, chat type, and operation. Prefer public
|
||||
Shortcuts; otherwise use the atomic fallback. Apply the shared `--format json`
|
||||
rule and take every downstream ID from actual output. Every Chat workflow
|
||||
must work without Python.
|
||||
|
||||
| 用户说 | 首选路由 / 原子回退 | 必须保留的执行边界 |
|
||||
|---|---|---|
|
||||
| “发给某人” | `+dm --to <姓名> --text <内容>` / `message send --open-dingtalk-id` | Resolve one real person; never pass a name as an ID |
|
||||
| “发到某群” | `+send-to-group --group <群名> --text <内容>` / `chat search` → `message send --group` | Resolve one real cid; mentions/`@all` use `+messages-send` with that cid |
|
||||
| “用应用机器人发” | `+messages-send --as bot` / `message send-by-bot` | Never impersonate the current user; keep robot and target IDs from real output |
|
||||
| “Webhook 推送” | `+messages-send --as webhook` / `message send-by-webhook` | Webhook identity is separate; mention text and `--at-*` flags must agree |
|
||||
| “建群 / 拉人进群” | `+chat-create --name <群名> --users <uid,...>` / `group members add` | Resolve every member to a real `userId`; extract the new cid before follow-up actions |
|
||||
| “拉某个会话的消息” | `+chat-messages` / `message list` | Choose one group or DM target and use the user's time range or an explicitly narrowed boundary |
|
||||
| “搜消息关键词 / 组合搜索” | `+search-msg --query <关键词>`；群内 @我用 `--at-me --group <cid>` | Add only real filters; use `--page-all` only when complete pagination is needed |
|
||||
| “撤回用户消息 / 机器人消息” | `+messages-recall --conversation-id <cid> --msg-id <mid>` / `recall-by-bot` | Only on explicit recall; IDs must come from the same identity and conversation |
|
||||
| “群消息翻页导出” | `+chat-messages`; save merged JSON if requested | Follow pagination to completion and report partial results instead of claiming a complete export |
|
||||
| “查和某人的聊天记录” | Resolve the person, then use `+chat-messages` with one user ID | Stop for ambiguous people; do not merge different users with the same name |
|
||||
| “机器人多群广播” | Call `+messages-send-by-bot` once per resolved group | Confirm the recipient set once, preserve one message body, and return a per-group success/failure ledger |
|
||||
|
||||
Detailed native CLI loops are in [01-messaging.md](references/01-messaging.md).
|
||||
|
||||
## 低频操作原子回退入口
|
||||
|
||||
Use this table only to locate atomic fallbacks when no public Shortcut matches.
|
||||
Follow leaf Schema, `--help`, and the linked reference for flags, risk, and
|
||||
confirmation.
|
||||
Branch references: [消息](references/chat/chat-message.md), [群与成员](references/chat/chat-group.md), [机器人与 Webhook](references/chat/chat-bot.md), [会话状态与分组](references/chat/chat-conversation.md).
|
||||
|
||||
| 用户意图 | 原子回退 | 关键边界 |
|
||||
|---|---|---|
|
||||
@@ -178,34 +133,17 @@ confirmation.
|
||||
| 行为授权 / 跨组织聊天数据授权 | `chmod` / `data-auth cross-org` | Grants action or cross-org read access; executes neither target action |
|
||||
| 退群 / 解散群 | `group quit` / `group dismiss` | First exits current user; second dismisses the entire chat |
|
||||
|
||||
## 跨命令关键边界
|
||||
## 错误恢复与按需 Reference
|
||||
|
||||
- Never mix current-user, app-bot, and Webhook identities.
|
||||
- `message list` reads one chat; use `search` / `search-advanced` for keywords
|
||||
and combined filters.
|
||||
- `openTaskId` is not `openMessageId`; approval, calendar, todo, and other
|
||||
product IDs cannot replace a message ID.
|
||||
- Message top, message Pin, and conversation top are distinct operations.
|
||||
- Follow leaf Schema and current `--help` for parameters, risk, and
|
||||
confirmation; never infer across safety fields.
|
||||
|
||||
## Workflow 与错误导航
|
||||
|
||||
- For complex messaging, read [01-messaging.md](references/01-messaging.md).
|
||||
- For onboarding, read
|
||||
[01-onboarding.md](references/workflows/01-onboarding.md).
|
||||
- On command error, read
|
||||
[chat-error-recovery.md](references/chat-error-recovery.md) and correct
|
||||
once. Stop on insufficient permission, unresolved ambiguity, or no result
|
||||
after re-search.
|
||||
- If a leaf is missing or parameters are invalid, follow the established Catalog → Schema → `--help` order and correct once.
|
||||
- Re-extract every downstream ID from actual output; never repair an ID by guessing.
|
||||
- For complex messaging, read [01-messaging.md](references/01-messaging.md); for onboarding, read [01-onboarding.md](references/workflows/01-onboarding.md).
|
||||
- On command error, read [chat-error-recovery.md](references/chat-error-recovery.md) and correct once.
|
||||
- Stop and report insufficient permission, unresolved ambiguity, no result after re-search, or contract conflict.
|
||||
|
||||
## 跨产品协作
|
||||
|
||||
- 收件人是人名 → use `dingtalk-contact` or `dingtalk-aisearch` to get
|
||||
`openDingTalkId` / `userId`.
|
||||
- 要发本地图片/文件 → use
|
||||
`dws chat message send --msg-type file --file-path <本地路径>`. Images are
|
||||
downloadable attachments, not inline. Use `--msg-type image --media-id`
|
||||
only with an existing valid mediaId; DWS cannot convert local files to mediaId.
|
||||
- 收件人是人名 → use `dingtalk-contact` or `dingtalk-aisearch` to obtain one real `openDingTalkId` / `userId`.
|
||||
- 要发本地图片/文件 → use `dws chat message send --msg-type file --file-path <本地路径>`. Images are downloadable attachments, not inline. Use `--msg-type image --media-id` only with an existing valid mediaId; DWS cannot convert local files to mediaId.
|
||||
- 紧急升级（应用内/短信/电话）→ route to `dingtalk-ding`.
|
||||
- 发邮件 → route to `dingtalk-mail`.
|
||||
|
||||
Reference in New Issue
Block a user