diff --git a/README.md b/README.md index 3bdc8fb..d297ca2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **跨平台、本地优先的微信 MCP 能力提供者（macOS / Windows）。** -独立运行，无需安装 [Local Bridge](https://github.com/eaopen/local-bridge)；未来可作为普通 MCP Provider 由 Local Bridge 注册和调用。微信聊天数据、实际发送和 UI 操作均由本项目负责，Bridge 不内置微信业务逻辑。 +独立运行，无需安装 [Local Bridge](https://github.com/eaopen/local-bridge)；目前也可由用户通过 Local Bridge 手动注册为本机 MCP Provider 并调用。微信聊天数据、实际发送和 UI 操作仍由本项目负责，Bridge 不内置微信业务逻辑。 ## 当前交付（v0.1.0） @@ -14,7 +14,8 @@ | Windows 4.x GUI 适配 | 🔶 对接 [pyweixin](https://github.com/Hello-Mr-Crab/pywechat)；需实机验证 | | macOS GUI 适配 | 🔶 对接 [wxauto-mac](https://github.com/PatrickHua/wxauto-mac)；需实机验证当前微信版本 | | 微信原生 SQLCipher 数据库解密与增量导入 | ❌ 尚未实现，放在独立后续任务 | -| Local Bridge 直接自动注册 | ❌ 尚未实现；MCP Server 可单独启动 | +| Local Bridge 本机手动 MCP 接入 | ✅ 已提供，见 [接入步骤](docs/LOCAL_BRIDGE.md)；**未通过真实微信 GUI 验收** | +| Local Bridge 自动注册 / 浏览器直接读写微信 | ❌ 尚未实现；MCP Server 可单独启动 | **重要：仓库提供可运行的软件骨架、SQLite 和 MCP 实现，但还没有完成真实微信账号的端到端发送验收。** 微信 4.x 的可访问性树可随账号/版本变化，不能假设任意机器可用。 @@ -93,7 +94,7 @@ wechat-provider import-jsonl /path/to/my_messages.jsonl - 数据库读取的下一阶段参考 [robbin/wechat-exporter](https://github.com/robbin/wechat-exporter)、[Wechat-MCP](https://github.com/xerlxzx/Wechat-MCP) 及 Windows 的 [wechat-local-analytics](https://github.com/davids1896/wechat-local-analytics)；先验证不同微信版本的兼容性，再接入 **只读离线快照**，不直接嵌入未经确认的解密脚本。 - **不使用 OpenRPA** 作为默认引擎；复杂 Windows 通用业务工作流有实际需求时再评估独立适配。 -见 [架构和完成条件](docs/ARCHITECTURE.md)、[2026-10-28 微信 MCP 与发送方案横向调研](docs/WECHAT_MCP_SEND_OPTIONS_2026-10-28.md)、[Local Bridge 对接边界](docs/LOCAL_BRIDGE.md) 及 [开发要求](AGENTS.md)。 +见 [架构和完成条件](docs/ARCHITECTURE.md)、[2026-10-28 微信 MCP 与发送方案横向调研](docs/WECHAT_MCP_SEND_OPTIONS_2026-10-28.md)、[Local Bridge 当前实际接入命令与边界](docs/LOCAL_BRIDGE.md) 及 [开发要求](AGENTS.md)。 ## 开发验证 diff --git a/docs/LOCAL_BRIDGE.md b/docs/LOCAL_BRIDGE.md index 31b8890..e9981c8 100644 --- a/docs/LOCAL_BRIDGE.md +++ b/docs/LOCAL_BRIDGE.md @@ -1,25 +1,63 @@ -# Integration with Local Bridge +# Integration with Local Bridge — 当前可用合同 -WeChat Provider is a standalone, locally installed communication capability. +WeChat Provider 是独立安装、独立运行的本机微信 MCP 服务。微信登录、桌面 GUI/RPA、SQLite/FTS5、本机发送任务和结果状态始终由本仓库管理；Local Bridge 只作为**可选 MCP Client** 连接已安装的 Provider。 +## 当前已实现（2026-10-28） + +- WeChat Provider 提供 `wechat-provider serve` stdio MCP 和六个工具，不依赖 Local Bridge。 +- [Local Bridge PR #13](https://github.com/eaopen/local-bridge/pull/13) 已合并：用户可以在本机主动注册固定可执行程序及参数，再通过 MCP `initialize → tools/list → tools/call` 调用已公布的工具。 +- [Local Bridge PR #14](https://github.com/eaopen/local-bridge/pull/14) 已合并：Ubuntu CI **实际安装并启动本仓库的 Python MCP Server**，由 Rust Local Bridge 完成状态、空索引搜索及拒绝未知工具的跨进程验证。 +- **尚未实现**：自动扫描微信聊天、`messages.subscribe` 事件订阅、Bridge 自动代理全部工具给浏览器/AI、实际 Windows/macOS 微信 4.x GUI 读写验收或发送送达核验。 + +## 最小本机接入 + +先按照 [README](../README.md) 安装微信 Provider 和目标操作系统对应的可选依赖；`wechat-provider serve` 是由本仓提供的**独立 MCP Server**。 + +在安装 Local Bridge 的用户本机，找到真正的 `wechat-provider` 可执行程序绝对路径，手动注册： + +```sh +local-bridge provider add wechat /absolute/path/to/wechat-provider serve +local-bridge provider list +local-bridge provider tools wechat +local-bridge provider call wechat wechat_status '{}' +local-bridge provider call wechat wechat_search '{"query":"待办","limit":10}' +``` + +如果已登录的微信 UI 可以提供相应读取，显式指定想读取的聊天： + +```sh +local-bridge provider call wechat wechat_list_chats '{"limit":5}' +local-bridge provider call wechat wechat_get_messages '{"chat_id":"文件传输助手","limit":10}' ``` -Agent / MCP client ──► wechat-provider serve (stdio) -Agent / Web client ──► Local Bridge ──► [future user-installed MCP registration] ──► Provider + +发送操作仅限用户明确从本机 CLI 发起，**不会因为注册而默认允许网页或 Agent 自动发送**： + +```sh +local-bridge provider call wechat wechat_send_message '{"chat_id":"文件传输助手","text":"受控测试","idempotency_key":"test-local-20261028-01"}' +local-bridge provider call wechat wechat_get_send_status '{"task_id":""}' ``` -## Ownership +当前 `chat_id` 是 UI **显示名称**，不是微信唯一且稳定的用户 ID。用受控的测试会话验收，发送前核对聊天对象；返回 `submitted` 只表示 UI 调用没有抛错，**绝不等于已送达**。遇到 `uncertain` 时查询原任务，不自动重复发送。该限制也适用于经 Local Bridge 代理的结果。 + +取消注册：`local-bridge provider remove wechat`。这不会删除原 Provider 的 SQLite、账号资料或安装目录。 + +## 所有权与非目标 -- **WeChat Provider:** user-authorized local chat reads, its own SQLite index, desktop RPA, recipient checks, send ledger and statuses. -- **Local Bridge:** discover/register callable capabilities, route requests within its own caller authorization model, and coordinate cross-application tasks. It does not inspect WeChat's DB schema, impersonate a WeChat user, or implement send logic. -- **Etech/other applications:** remain independently authorized; Provider must not contain Etech-specific business rules. +| 所属模块 | 职责 | +|---|---| +| WeChat Provider | 登录中的微信桌面适配、聊天 UI、消息索引、发送状态/幂等、实际响应 | +| Local Bridge | 当前 OS 用户主动安装的 MCP 连接器注册、工具发现、调用转发和结果展示 | +| Local Tool Bridge Chrome 扩展 | 独立网页上下文采集、用户主动交接；**尚未**开放浏览器直接调用微信读取或发送 | +| CloudFile/Etech | 原企业登录、业务对象/文件权限和文件版本，不因微信 Provider 接入而改变 | -**Current state:** Local Bridge 0.1.0 has a read-only MCP prototype; it does not yet offer general installed-provider registration. Thus this repository works independently today. Do not claim automatic Bridge integration is shipped. +默认可以在同一电脑同时使用个人微信和企业文件工具，不建立新的个人/企业隔离墙；每个原模块仍执行已有认证、权限与操作结果判断。消息文本是数据，不能被当作命令自动执行。 -## Future registration contract (proposal) +不硬编码 Etech、CloudFile 或 Local Bridge 的私有程序/路径到 WeChat Provider 核心，不构建新的微信协议解密/RPA，不因为出现 Bridge 就要求用户迁移原有 MCP 客户端。 -Advertise a fixed, locally installed executable and explicit stdio arguments: -`wechat-provider serve`. Announce six MCP tools and side-effecting classifications; `wechat_send_message` is a write operation. Respect the user's local connector permissions. Do not accept arbitrary execution paths or commands from a webpage or chat message. +## 待验收的真实场景 -When Local Bridge exposes actual user-approved provider registration, add a small setup example here rather than linking its runtime into this project. +- [Windows 微信 UI 验收 #1](https://github.com/eaopen/wechat-provider/issues/1) +- [macOS 微信 UI 验收 #2](https://github.com/eaopen/wechat-provider/issues/2) +- [只读离线快照导入 #3](https://github.com/eaopen/wechat-provider/issues/3) -Message send outcomes are `queued/running/submitted/uncertain/failed`; only separately evidenced receipt checks may be marked `verified`. Never automatically interpret `submitted` as delivered. +MCP 传输验证成功 ≠ GUI 兼容 ≠ 微信发送核验成功。