mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-09-05 17:03:49 +08:00
feat: 新增企业微信助手 Agent，并修正 wecom-cli 条目 ref 漂移 (#112)
## 概述 / Overview 两件事：新增「企业微信助手」Agent（自带 15 个技能），并修正 `wecom-cli` 条目钉在 6 月快照的 ref 漂移。 Two changes: adds the **WeCom Assistant** agent (bundling 15 skills), and fixes the `wecom-cli` entry whose pinned ref was stuck on a June snapshot. ## 1. 新增企业微信助手 Agent 覆盖企业微信 **14 类服务、95 个方法**：消息、群聊历史、通讯录、日程、会议、待办、邮件、在线文档、在线表格、智能表格、智能文档、文档管理、微盘、媒体文件。 **采用内联形态 + 自带私有技能**：Agent 安装对 `agents/<id>/` 整目录递归复制且 `skills/` 不在排除集合里，因此装 Agent 即带全部技能，用户无需再单独获取技能合集。 ### 技能集（15 个，约 5000 行） - 基于上游 [wecom-cli](https://github.com/WecomTeam/wecom-cli) 官方 Skill（MIT，© WecomTeam）改写，每个技能末尾保留归属声明 - **新增 `wecom-chat`**：补齐上游零覆盖的群聊历史读取 - 补齐上游未覆盖的 `message.send`、`doc.create`，方法覆盖达 **95/95** - 修正上游三处文档漂移：邮件能力描述与实际相反、会议室参数名已过时、`title_highlight` 字段不存在 ### 相对上游的核心增量：风险治理 - 26 个对外可见或不可逆的方法逐个写明**执行前确认要求** - 4 个条件升级方法给出**参数级判据**，而非按方法名一刀切 - 文档权限扩散两项加重处理，涉及**企业外可见**时单独再确认一次 - 内部标识禁止外露，不因用户索要而放宽 - 拒绝导出可识别到具体自然人的隐私字段 ### 三条真机实测得出、上游未覆盖的硬约束 1. 机器人**只能写入/修改自己创建的数据**，真人创建的只能读 2. 每次响应携带的 `extra_identity_context` **禁止透露给用户** 3. 权限错误（`850002`/`851008`/`853006`）**不得重试**，须将 `help_message` **逐字原样**转给用户 ## 2. 修正 wecom-cli 条目 ref 漂移 `source.ref` 原钉在 2026-06-28 的 `72e14f7`，该快照只有 7 个子技能且用已废弃的旧命名（`msg`/`schedule`）。上游 v1.2.0 已扩展到 **14 个**技能。按旧 ref 安装的用户拿到的是三个月前的快照。 - `source.ref` → `78c514b2afee7c0d3d7be715628478421f37ee63` - `children` 由 `scripts/gen-collection-children.py` 重新生成，**7 → 14** - sidecar 同步 `provenance.content.ref`、`childCount` 与 `children` ## 验证 / Verification **静态** - 215 条示例命令追加 `--dry-run` 实跑，**215/215 退出码 0** - 未知方法 0、未知参数 0、`--json` 未知字段 0、枚举违规 0 - 15 个 `SKILL.md` 的 frontmatter 经客户端 `skillFrontmatterSchema` 校验全部通过 - `validate_catalog_metadata.py --require-complete` 与 `gen-collection-children.py`：**0 error** **真机（在真实企业微信账号上端到端）** - **待办域 6/6 方法全通**（含 2 个 write-high），`items` 必填的隐蔽坑实测证实 - **日程域 5 个方法全通**（含 3 个 write-high） - 消息发送、通讯录解析、微盘列表、邮件搜索、文档搜索、会议列表、智能表格创建均已实测通过 - 测试数据已全部清理，未污染真实账号 **尚未实测**：群聊历史（机器人未开通该品类）。相关文档已明确标注验证状态，未实测的能力不写「实际效果」段落。
This commit is contained in:
GitHub
159
agents/wecom-assistant/docs/README.md
Normal file
159
agents/wecom-assistant/docs/README.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# 企业微信助手 · 使用文档
|
||||
|
||||
企业微信助手把企业微信的日常办公搬进对话框。你用日常语言说出意图——「今天有什么会」「把周报发到项目群」
|
||||
「记个待办」——它替你在企业微信里把事情办成，再用可读的话汇报结果。不用打开企业微信客户端，不用记接口，
|
||||
不用自己敲命令。
|
||||
|
||||
本文档写给使用者，不写给开发者。每一篇都回答同一个问题：**我说什么，它能做什么，做不到什么。**
|
||||
|
||||
---
|
||||
|
||||
## 先读这个
|
||||
|
||||
| 文档 | 讲什么 |
|
||||
|---|---|
|
||||
| [01 快速开始](01-快速开始.md) | 装什么、怎么授权、第一次对话该说什么 |
|
||||
| [99 风险与确认](99-风险与确认.md) | 哪些操作会先问你、怎么算「同意」、哪些不问 |
|
||||
|
||||
---
|
||||
|
||||
## 按能力查
|
||||
|
||||
| 能力 | 你会怎么说 | 文档 |
|
||||
|---|---|---|
|
||||
| 通讯录 | 「张三是谁」「李四在哪个部门」 | [02 通讯录](02-通讯录.md) |
|
||||
| 消息与会话 | 「给张三发条消息」「把这个文件发到项目群」 | [03 消息与会话](03-消息与会话.md) |
|
||||
| 群聊历史 | 「项目群这两天聊了什么」「群里发的那个文件」 | [04 群聊历史](04-群聊历史.md) |
|
||||
| 日程 | 「明天有什么安排」「约个日程」「订个会议室」 | [05 日程](05-日程.md) |
|
||||
| 会议 | 「开个视频会议」「这个会讲了啥」「把会上原话发我」 | [06 会议](06-会议.md) |
|
||||
| 待办 | 「记个待办」「我有哪些待办」「这条完成了」 | [07 待办](07-待办.md) |
|
||||
| 邮件 | 「发封邮件给张三」「回一下这封」「邮箱里搜一下」 | [08 邮件](08-邮件.md) |
|
||||
| 在线文档 | 「建个 Word 文档写周报」「把这份 docx 传上去」 | [09 在线文档](09-在线文档.md) |
|
||||
| 在线表格 | 「建个在线表格」「把这个 Excel 传到企微」 | [10 在线表格](10-在线表格.md) |
|
||||
| 智能表格 | 「建个项目管理表」「加一列」「统计各部门多少条」 | [11 智能表格](11-智能表格.md) |
|
||||
| 智能文档 | 「写份周报」「整理成文档」「做个数据看板页」 | [12 智能文档](12-智能文档.md) |
|
||||
| 文档管理 | 「找一下那个文档」「改个名」「把张三加进来」 | [13 文档管理](13-文档管理.md) |
|
||||
| 微盘 | 「微盘里搜一下」「传到微盘」「下载那个文件」 | [14 微盘](14-微盘.md) |
|
||||
|
||||
还有一篇 [15 媒体文件](15-媒体文件.md)。它是纯搬运能力（本地文件 ↔ 企业微信），
|
||||
**通常由上面的能力在流程中间自动调用**，你一般不会直接点名它。想知道「为什么发图片比发文字慢一步」时可以看看。
|
||||
|
||||
---
|
||||
|
||||
## 它能做到什么程度
|
||||
|
||||
- **读你的企业微信数据**：日程、会议、待办、邮件、文档、表格、微盘文件、通讯录里你有权限看到的人。
|
||||
- **替你写入**：建文档 / 表格 / 日程 / 会议 / 待办，往文档里追加内容，发消息、发邮件、传文件。
|
||||
- **替你确认**：凡是对外发出去、改权限、覆盖或删除的动作，执行前会把影响复述给你，等你点头。
|
||||
- **说人话**：回复里用姓名、群名、文档标题，不甩内部编号和原始 JSON。
|
||||
- **办不成就说办不成**：会告诉你卡在哪一步、需要什么，不假装成功。
|
||||
|
||||
## 它做不到什么
|
||||
|
||||
- **不能改你自己建的东西**（见下一节第 1 条）。
|
||||
- **不能撤回**：消息、邮件发出去就收不回；删掉的待办、覆盖掉的文档正文都没有恢复接口。
|
||||
- **不做周期性日程与会议**：创建、修改、取消重复日程/会议都不支持，要去企业微信客户端。
|
||||
- **不做 RSVP**：接受 / 拒绝 / 待定别人的邀请，只能你自己在客户端点。
|
||||
- **不做邮件的已读未读、删除、草稿、标签写入、撤回**。
|
||||
- **不做全量通讯录导出**：搜到的只是你有权限看到的人，且结果会被截断。
|
||||
- **不监听变化**：不会「有新消息 / 新文件就告诉你」，需要你来问。
|
||||
- **不做因果分析与预测**：能算「各部门各多少条」，不回答「为什么这么多」「下月会怎样」。
|
||||
- **超出企业微信的事一概不接**：订机票、查天气这类，它会直接说不在能力范围内。
|
||||
|
||||
---
|
||||
|
||||
## 三条适用于所有能力的边界
|
||||
|
||||
这三条不是免责声明，是每天都会碰到的实际约束。
|
||||
|
||||
**1. 它只能改「它自己建的」东西。**
|
||||
读是全的——你的文档、日程、待办、邮件它都能读；写是窄的——**只能修改机器人自己创建的内容**。
|
||||
你自己在企业微信里建的那份文档、那条日程、那条待办，助手改不了。碰到这种请求，它会说明这条边界，
|
||||
并给替代方案（比如「我另建一份新的」，或「这个得你在企业微信里改」）。
|
||||
|
||||
**2. 能力是按品类逐项开通的。**
|
||||
机器人不是开箱全能。某一类能力（通讯录、文档、微盘、会议、邮件、群聊……）没开通时，企业微信会返回一段
|
||||
官方的开通指引，助手会把那段指引**原样转给你**（包括其中的链接），然后停下——**不会换个方法绕、也不会反复重试**，
|
||||
因为那是权限问题，重试不会变好。本文档里标着「未开通」的能力就是这么来的。
|
||||
|
||||
**3. 危险动作会先问你。**
|
||||
对外发送（消息、邮件）、对外通知（建改删日程与会议）、改文档权限、覆盖或删除内容——执行前会复述
|
||||
「对谁、做什么、内容是什么、能不能撤回」，等你明确同意。含糊的「嗯」「你看着办」不算同意。
|
||||
完整清单和判定规则见 [99 风险与确认](99-风险与确认.md)。
|
||||
|
||||
---
|
||||
|
||||
## 各能力的验证进度
|
||||
|
||||
这套助手在一个**真实企业微信账号**上做过实测。下表如实说明每个能力验到了哪一步。
|
||||
每篇文档里还有更细的「验证状态」一节。
|
||||
|
||||
**两个层次要分清**：
|
||||
|
||||
- **命令层**——人工在真实账号上直接执行企业微信官方命令行工具，看真实返回。下表说的就是这一层。
|
||||
- **完整链路**——「你说一句话 → 助手自己选对能力 → 真的执行 → 汇报」。这一层**全域都未完成端到端实测**
|
||||
（本机内存不足导致实例反复启动失败，且界面里的 AI 审批未配置，自动审批被拒）。
|
||||
界面内单独验过的是：助手能正常创建与对话、15 个技能全部被发现、授权引导步骤正确、
|
||||
以及日程/会议消歧的固定问法逐字正确。
|
||||
|
||||
### 已完整实测（命令层）
|
||||
|
||||
| 能力 | 验到哪一步 | 详见 |
|
||||
|---|---|---|
|
||||
| 待办 | 6 个方法全通：建、列、查、改、完成、删除 | [07](07-待办.md) |
|
||||
| 日程 | 5 个方法全通：建 → 列 → 查 → 改期 → 取消（会议室与忙闲查询未测） | [05](05-日程.md) |
|
||||
| 在线文档 | 创建 → 追加 → 读回，内容完全一致（导入与覆盖未测） | [09](09-在线文档.md) |
|
||||
|
||||
### 已实测关键路径（命令层）
|
||||
|
||||
| 能力 | 验到哪一步 | 详见 |
|
||||
|---|---|---|
|
||||
| 消息与会话 | 查会话列表通过；**以机器人身份发消息真实发送成功** | [03](03-消息与会话.md) |
|
||||
| 通讯录 | 按姓名搜索，解析出真人及其部门 | [02](02-通讯录.md) |
|
||||
| 智能表格 | 创建通过；读子表结构通过（记录、字段、视图、图表未测） | [11](11-智能表格.md) |
|
||||
| 文档管理 | 重命名通过（搜索、加成员、改加入规则未测） | [13](13-文档管理.md) |
|
||||
| 微盘 | 列出文件返回了真实文件（上传、下载、改名、建文件夹未测） | [14](14-微盘.md) |
|
||||
| 邮件 | 搜索通过（返回 0 封匹配）；**发送、回复、转发、读正文均未测** | [08](08-邮件.md) |
|
||||
| 会议 | 列表通过（返回 0 场）；**创建、改期、取消、纪要、转写均未测** | [06](06-会议.md) |
|
||||
|
||||
### 只验到「创建」
|
||||
|
||||
| 能力 | 验到哪一步 | 详见 |
|
||||
|---|---|---|
|
||||
| 在线表格 | 只验证了「能建出一张在线表格」，读写数据、增删子表都没测 | [10](10-在线表格.md) |
|
||||
| 智能文档 | 只验证了「能建出一份智能文档」，页面读写、结构调整都没测 | [12](12-智能文档.md) |
|
||||
|
||||
### 完全未实测
|
||||
|
||||
| 能力 | 卡在哪 | 详见 |
|
||||
|---|---|---|
|
||||
| 群聊历史 | 机器人**未开通「群聊会话」品类**，第一步就被拒，后续全部无法验证 | [04](04-群聊历史.md) |
|
||||
| 媒体文件 | 没有单独验证；它总是被别的能力顺带调用，未做独立实测 | [15](15-媒体文件.md) |
|
||||
|
||||
---
|
||||
|
||||
## 关于本文档
|
||||
|
||||
**文档的准确性有一条侧面证据。** 实测过程中，操作者五次凭常识手写参数，五次都写错，
|
||||
而助手所依据的技能文档五次都是对的：
|
||||
|
||||
| 凭常识写的 | 实际要求 |
|
||||
|---|---|
|
||||
| 待办条目用 `content` 装标题 | 要用 `title` |
|
||||
| 日程主题用 `summary` | 要用 `subject` |
|
||||
| 时间传数字时间戳 | 要传 `"2026-09-01 14:00:00"` 这样的字符串日期 |
|
||||
| 参数嵌一层 `{"schedule": {...}}` | 要顶层平铺 |
|
||||
| 建智能表格用 `doc_name` 指定名称 | 要用 `name` |
|
||||
|
||||
这说明技能里的参数不是从别处抄来的，是真能跑通的。仅此而已——它证明的是参数写得对，
|
||||
**不证明每条链路都验过**。哪些验过、哪些没验，以上面的「验证进度」和各篇的「验证状态」为准。
|
||||
|
||||
**声明：本文档不含任何编造的运行记录。** 所有标注「实测」的命令与返回，都来自真实企业微信账号上
|
||||
实际执行的记录；未执行过的一律标注为「未实测」，不写「实际效果」，也不虚构对话与返回值。
|
||||
|
||||
---
|
||||
|
||||
## 授权与依赖
|
||||
|
||||
需要 Node.js 18+ 与一个企业微信账号。首次使用时助手会引导你安装官方命令行工具并用企业微信扫码授权，
|
||||
**整个环境只需要授权一次**。步骤见 [01 快速开始](01-快速开始.md)。
|
||||
Reference in New Issue
Block a user