企业微信接入主线：把企微做成团队上下文的完整 IO 接口¶

本页一条线讲清：为什么这么做、分几层、每层做什么、已经到哪、还需要谁配合开通什么。给团队成员了解整体逻辑链与后续要配合申请的权限。

状态图例：✅ 已实现 · 🔨 开发中/代码就绪 · ⬜ 待开发 · 🔑 开发前需人工开通

0. 一句话目标¶

把企业微信做成 VariAI / Harness 的一个完整 IO 接口：

输入（读）：把团队在企微里产生的上下文——消息、文档、智能表格、微盘文件、日程、汇报——汇成可沉淀的 Evidence / Knowledge。
输出（写）：把系统产物——待办、知识卡、提醒、报告——发回企微的私聊、群聊、文档、智能表格、各个界面。

下面解释：实现这个 IO 要分哪几层、为什么、每层的前置条件。

1. 为什么要 Bot、Bot 又不够 —— 入口分层的逻辑链¶

1.1 第一层：智能机器人 Bot —— 人机交互入口 ✅¶

干什么：成员私聊 Bot、群里 @Bot、转发给 Bot；Bot 被动 / 主动回复。这是“人主动把要沉淀的东西交给系统”的入口。
现状：✅ Bot 长连接（WS）已打通；知识抽取闭环已 demo 验证（模糊“发哥”→ 反问 → @ 确认 → 登记待办）。
Bot 的局限（这就是为什么还不够）：
只收被 @ 的消息；群里没 @Bot 的普通聊天读不到
读不了历史消息
不是企业系统集成入口——读不了通讯录 / 组织架构，读写不了文档 / 表格 / 微盘，发不了应用消息

1.2 第二层：自建应用 —— 补 Bot 干不了的（企业系统集成）🔨 / 🔑¶

Bot 的局限，正好靠自建应用补上：

能补什么：读通讯录 / 组织架构 / 群成员，读写企微文档 / 智能表格 / 微盘，主动发应用消息，接收企业事件回调。
🔑 需要人工开通的前置：
子域名 + HTTPS（备案主体 = 本公司）—— 企微硬性要求（可信域名 / 回调 URL 都卡在它后面）
可信 IP（把服务器出口 IP 加白名单）
应用的 Token / EncodingAESKey、通讯录 / 文档 / 微盘 / 应用消息等权限
现状：🔑 人工前置【已开通】——子域名 专用子域名 + HTTPS 证书就绪、企微「可信域名(OAuth)」归属认证通过、企业可信 IP 已加入服务器出口 企业可信出口 IP（值见内部 connector-status，不公开）、gettoken 实测 errcode=0，通讯录最小字段与应用消息发送 smoke 也曾 errcode=0（原"唯一总闸=子域名"已解除）。🔨 开发方框架下游【已就绪并入 main、含 synthetic 单测】：自建应用回调服务 + 回调事件 → 知识管线桥（framework/connectors/wecom/callback_pipeline.py，回调服务带默认关闭的转发开关 WECOM_CALLBACK_FORWARD_PIPELINE，ack 之后于守护线程转发、不拖慢 ack）、通讯录 → owner-registry 映射（directory.py）、出站应用消息发送（app_message.py）、access_token 缓存 provider（access_token.py）。⬜ 剩 live 端到端：回调服务需恢复常驻（当前内部端口未监听、公网 GET /wecom/callback 返回 502），起来并打开转发开关后验真实链路。

1.3 第三层：会话内容存档 —— 连“没 @ 的普通聊天”都要 ⬜¶

做完前两层会发现：群里没 @Bot 的日常聊天、历史消息、媒体，前两层都拿不到。要“不 @ 也全量采集”，只能上会话内容存档：

🔑 单独开通：申请开通（范围 / 付费 / 审批）、生成 RSA 公私钥、部署 WeWorkFinanceSdk、配可信 IP
🔑 合规前置（HR / 法务）：员工告知 / 同意（尤其外部联系人）、制度公告、留存 / 删除 / 审计策略
现状：⬜ 增强项，不是 MVP 前置，排在主线之后。

2. 输出侧 —— 把产物发回企微¶

同一套 Bot + 自建应用能力，反向用于输出：

发消息到私聊 / 群聊（Bot 回复 / 应用消息）🔨 框架发送已就绪（app_message.send_text_app_message）/ 待 live access_token + 端到端
写企微文档 / 智能表格 / 微盘（企微原生，同一套 API）⬜ / 🔑 等权限
主动提醒 / 报告（应用消息）🔨 同上（框架发送 + access_token provider 已就绪）

3. 企微作为完整 IO 接口 —— 总表¶

能力	入口	状态	需人工开通
私聊 / 群 @ 消息（输入）	Bot	✅ 已通	—
主动回复 / 消息（输出）	Bot / 自建应用	🔨 框架发送就绪，待 live	✅ 域名/可信 IP 已开
通讯录 / 组织 / 群成员（输入）	自建应用	🔨 映射就绪，待 live 拉取	✅ 域名/可信 IP 已开
企微文档 / 智能表格 / 微盘读写（I/O）	自建应用	⬜	🔑 权限
日程 / 汇报（输入）	自建应用	⬜	🔑 权限
企业事件回调（输入）	自建应用回调	🔨 回调→知识桥就绪，待 live 常驻	✅ 域名已开
不 @ 的普通 / 历史聊天（输入）	会话内容存档	⬜ 增强项	🔑 单独开通 + 合规

一个重要澄清：企微原生的文档 / 智能表格 / 微盘 / 日程 / 会议，都是同一套企微服务端 API（不是“另一套平台”）；工作台里真正“各自接”的是第三方应用（北森 iTalent / TAPD / 豆包 / 康通自有系统）。所以核心协作数据一套 API 打通，只有第三方系统要单独接。

4. 我现在该分别干什么¶

用户 / 同事侧（开通 / live-ops，按优先级）：

✅ 子域名 / 可信域名 / 可信 IP【已开通】—— 原"唯一总闸"已解除。
🔧 live-ops（当前最优先）：恢复回调服务常驻 —— 修 .env.wecom.local → 服务器受限凭据路径 的组读权限、起服务（WECOM_CALLBACK_PORT=内部端口 WECOM_CALLBACK_PATH=/wecom/callback）、固化为常驻（systemd/nohup）、回企微后台过 URL 验证。当前内部端口未监听、公网 502。
🔑 定日报 / 文档载体（企微文档？智能表格？微盘？OA 汇报？）—— 决定 P3 接哪个。
🔑 逐项确认飞书对标能力（文档评论 / reaction / 邮件 / 日历 / 任务等，待官方 / 后台核对）。
🔑（后置）会话内容存档开通 + 合规。

开发方（我们）侧（框架 IO 骨架已就绪，synthetic 单测）：

✅ Bot WS 知识管线 · ✅ Claude 抽取组件 · ✅ 自建应用回调服务 + 回调 → 知识桥（默认关闭转发开关）· ✅ 通讯录映射 · ✅ 出站应用消息发送 · ✅ access_token 缓存 provider。
live 一恢复：打开 WECOM_CALLBACK_FORWARD_PIPELINE 验真实回调→知识；通讯录 live 拉取喂映射；出站用 provider token 发应用消息。逐层点亮 → 接 P3 文档 / 微盘。