# 企业微信插件 3.0

“收到消息”只接收企业微信新消息，不预设群聊、发送者或消息类型。筛选使用系统“条件分支”或“多路选择”；插件不再提供企微专用筛选节点。群机器人 `xfe.wecom.send` 保持兼容，插件中心仍只显示一个“企业微信”卡片。

## 使用

1. 在插件中心展开“本机企业微信”，点击“连接客户端”。多个客户端时填写进程 ID，0 表示自动选择；无需选择群聊或成员，连接不发送消息。
2. 从节点库“触发器”分类拖入企业微信的“收到消息”，或点击插件中心的“新建消息接收工作流”。模板只有接收和结束，不预设筛选、回复内容或自动开启。
3. 把 `next` 执行线连接系统“条件分支”。例如 `senderId` 连接条件的 `left`，比较选择 `eq`，`right` 填完整发送者 ID；`true` 连接下一步，`false` 可连接结束。群聊用 `groupId`，类型用 `kind`（`Text` / `MergedForward` / `Unknown`）。
4. 允许多个发送者时，拖入“数组常量”，选择文本类型，用加号逐项添加完整 ID；接收的执行线先经过数组常量再连接系统条件 `contains`。数组 `value` 连接条件 `left`，`senderId` 连接 `right`。多个条件可以串联，自行安排判断顺序和分支。
5. 需要回复时，接收节点的 `message` 消息引用直接连接普通/引用回复的 `message` 输入；满足条件的执行线连接回复节点。正文、群和发送者等分别输出，不用把整个事件对象当成文本。
6. 保存后在工作流列表开启。托盘驻留期间继续监听，关闭工作流释放其订阅。多个工作流共享一个消息源并按优先级依次接收；一个流程回复后，其他新版流程仍能收到同一事件并自行判断，实际发送保持持久化去重。

接收输出：`message`、`content`、`hasContent`、`messageId`、`groupId`、`groupName`、`senderId`、`senderName`、`kind`、`createdAtUtc`、`receivedAtUtc`、`ageSeconds`、`dryRun`。`event` 保留为 `message` 的兼容别名。[端口与类型转换](typed-ports.md)。

## 条件与旧流程迁移

已填写三个指定 ID 的[引用回复 1 模板](../samples/workflows/wecom-three-contacts-array-auto-reply.xfeworkflow)可直接导入。数组包含 `1688854960759986`、`1688855640887649`、`1688858019818846` 三个文本单元，使用系统条件精确匹配，原消息引用直接连到回复节点；导入默认关闭，不限定群聊。[数组编辑与使用教程](typed-values.md)。

系统条件支持相等、不等、大小比较、集合/文本包含、`containsAny` / `containsAll`、布尔判断，可选忽略空白/全半角差异与大小写。`conditions` 数组可组合比较，每项包含 `left`、`operator`、`right`，支持 `$node`、`$input` 等绑定；`matchAll` 决定全部或任意成立。数组留空时仍使用普通比较。输出 `matched` 布尔值，执行出口为 `true` / `false`。

已有工作流保持版本锁定，不自动扩大监听范围。旧企微节点属性的“升级企微 · 将旧筛选转为系统条件”会将原群聊、成员、类型、有效期和专用筛选转换为显式系统条件，保留消息引用连线；升级后关闭工作流供检查。旧监听使用默认群/成员时，在插件中心“旧版兼容”填写默认 ID，或使用连接后解析的默认 ID。这些默认值不筛选新版消息。动态筛选参数、手写 C# 等无法确定等价含义时会拒绝升级，保留原流程。

原 WeChatAutoReplySystem 的 Receive、Group、Sender、MessageType、Keyword、Reply、Log、Stop 映射为收到消息、系统条件分支、企微回复、XFE 日志和结束。支持工作流 JSON、单 Workflow 配置或 Workflows 库；默认群/成员仅在旧条件需要时解析，Match / NoMatch 转为 true / false。导入后默认关闭，不在接收节点隐藏增加群或成员过滤。

“联系人 ID”查询、复制客户端已缓存联系人；“读取缓存群聊”提供已加载群信息。这些缓存不是完整通讯录或群成员名单，名称可能为空，建议用完整 ID 判断身份。连接设置由 AutoConfig 保存；应用重启后重新连接，已开启的工作流恢复监听。

## 遍历联系人

[下载可导入工作流](../samples/workflows/wecom-contacts-foreach-log.xfeworkflow)；[查看 JSON](../samples/workflows/wecom-contacts-foreach-log.json)。需要企业微信插件 **3.0.0**，导入默认关闭自动调度，有手动入口。模板只读取和输出，不发送消息。

1. 先在“插件中心 → 企业微信 → 本机企业微信”连接已登录的受支持客户端。
2. 在编辑器选择“文件 → 导入工作流”，导入 `wecom-contacts-foreach-log.xfeworkflow`，按 F5 运行。
3. 主图为“开始 → 读取本机缓存联系人 → 逐个遍历联系人 → 返回全部迭代结果”。`contacts` 数组连接遍历的 `items`。
4. 选中遍历节点，点击“编辑子图：body”。执行顺序为“本轮开始 → 当前联系人 → 输出原始联系人 → 返回当前联系人”。“当前联系人”就是内置的“当前循环项”节点，它的 `item` 已直接连到日志的 `message` 和结束的 `result`；**不填写或修改消息参数，不插入变量表达式，不重组联系人字段**。
5. 每轮日志记录完整的原始联系人对象；ID、名称以及接口返回的其他字段都保留。`index` 输出从 0 开始的数字序号，需要时连接到接受数字或通用值的输入。将每个联系人要执行的操作放入 `body`，通过数据连线传值；F9 设置节点断点检查数据。完整用法见[数组遍历](array-iteration.md)和[节点调试](debugging.md)。

“读取本机缓存联系人”的 `query` 留空读取全部当前缓存；可填写名字或完整 ID 搜索。当前原生接口只能读取企业微信本机已加载的联系人缓存，**不保证是完整通讯录**，名称可能为空。返回 `completeRoster=false`；空缓存返回 `[]`，循环体不执行，也没有逐项日志。模板最终 `result` 按顺序包含每轮的 `{"result":联系人对象}`，`completeRoster` 单独返回。

## 单独读取联系人 ID 与名称

导入[联系人字段模板](../samples/workflows/wecom-contacts-fields-log.xfeworkflow)（[JSON](../samples/workflows/wecom-contacts-fields-log.json)），在遍历的 `body` 中通过两个内置“读取对象字段”节点分别读取 `id`、`displayName`。字段经过“转换为文本”后连接日志 `message`，也可连接其他节点的文本输入。日志固定参数为空，每位联系人输出两条原始字段值，完整对象仍作为本轮结果返回；不在消息中写表达式，不发送消息。

名称中的中文和表情直接显示，包括组合表情、肤色与旗帜。需要嵌套字段、数组元素、字段存在判断或离线验证时，见[对象字段教程与无需插件模板](object-fields.md)。

## 适配范围

- 本机原生接口支持 Windows x64 宿主和企业微信 **5.0.11.6029 x86**，目标 SHA256 为 `F46DBFB0059D4527B76B8DD3DFCD1DD45604C5BA257AF80C064E4896E02CF50E`。位数、哈希、类型或原生入口不匹配时拒绝连接；x86 / ARM64 宿主仍可用群机器人。
- 原生通知与内存增量读取覆盖所有可观察会话、发送者和类型，不再绑定单群。跳过历史、自发、重复和超过 300 秒的事件，发送前再次检查有效期；更短有效期可把 `ageSeconds` 连接系统条件。未加载的瞬时消息仍可能漏收。
- 当前只提供元数据，**不提供正文**，`hasContent=false`。判断正文前先检查 `hasContent`；旧关键词条件导入时保留此检查，没有正文时不会假装匹配。
- 引用回复保留原消息本地 ID、消息 ID 与发送者 ID；无效引用会停止。普通/引用回复限制 1–256 字符，无换行或控制字符；群机器人继续支持 text / markdown。
- 按账号、会话、消息 ID 持久化发送预约，跨工作流、重连和重启去重。失败与不确定预约保留；结果不确定会停止监听，需重新连接。没有自动重发。
- `Accepted` 表示客户端内部受理，不表示服务器送达。文件传输助手自测需显式点击；试运行在回复节点配置，不发送也不占用持久化预约。
- 插件 3.0 要求宿主 SDK 1.5，防止旧宿主仍按旧筛选协议执行。

## 验证

WeComTests 使用模拟适配器和真实 Runner 验证跨群/成员/类型接收、多流程分发、用户条件、旧版锁定、显式升级、导入、启停、引用身份与去重。ConditionTests 覆盖条件组、关键词集合、类型和完整字符串 ID。`node tools/Test-WeComAgent.mjs` 以模拟内存运行真实监听脚本，检查接收范围、消息基线、自发过滤与会话级去重，不连接真实客户端。WinUI 冒烟检查验证单一插件卡片、模板、无筛选参数的表单和节点发现。真实客户端收发仍需在受支持版本手动验收。