Metadata-Version: 2.5
Name: ides_adapter_weixin
Version: 0.1.4
Summary: 微信（WeChat iLink Bot）adapter for IDES channel——通过 channel_ingest/emit 让微信消息驱动 IDES
Author-email: "tckm.rush" <rush@tachikoma.dev>
License: MIT
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: segno>=1.6
Description-Content-Type: text/markdown

# ides_adapter_weixin

微信（WeChat iLink Bot）adapter for IDES channel——让微信消息驱动 IDES agent。

按 IDES 的 **外挂配置哲学**：这是一个独立的 Python 进程，通过 MCP（stdio）接入 IDES，用 `channel` 机制收发消息。底座（Rust）不碰微信协议，翻译全在这。

---

## Quick Start（给 agent 看：怎么装、怎么连）

### 1. 注册 MCP server

IDES 通过 `mcp/*.toml` 注册 MCP server。在 IDES_HOME 的 `mcp/` 目录下放 `weixin.toml`：

```toml
name = "weixin"
transport = "stdio"
command = "uvx"
args = ["ides-adapter-weixin"]
enabled = true
exclude = []

[env]
IDES_HOME = "<你的 IDES_HOME>"
WEIXIN_ACCOUNT_ID = "default"
```

> **本地开发版**（还在迭代不想发布）：把 `command` 换成 `uv`，`args` 换成 `["run", "--with", "<项目路径>", "ides-adapter-weixin"]`。

> **agent 也可以用 `mcp_manager` 工具自动注册**（mcp_manager add weixin ...），不用手改 toml。

### 2. 连接

IDES 启动时自动拉起 MCP server（stdio）。注册后，IDES 会暴露 4 个工具，命名 `mcp_weixin_<tool>`：

| 工具 | 作用 |
|------|------|
| `mcp_weixin_weixin_qrcode_login` | **登录（拿二维码）**：只 fetch 二维码秒回，不轮询 |
| `mcp_weixin_weixin_poll_status` | **登录（查状态）**：单次查询扫码状态，confirmed 时自动存 token |
| `mcp_weixin_channel_ingest` | **收消息**：增量拉微信消息 |
| `mcp_weixin_channel_emit` | **发消息**：回微信用户 |

### 3. 登录（必须做，否则收不到消息）

agent 调 `weixin_qrcode_login` **拿二维码**（秒回，不轮询）：

```text
mcp_weixin_weixin_qrcode_login
```

返回一个二维码（`qrcode` hex + `qr_image_path` 图片路径 + `qrcode_url` 完整 liteapp URL + `qr_scan_data`）。**agent 自行决定展示方式**——转成图片给用户扫 / 直接给 URL / 命令行渲染，都行。

> 二维码会自动渲染到**唯一临时文件**（`qr_image_path` 路径每次随机，如系统 temp 目录的 `weixin-qr-xxxx.png`），agent 直接展示这张图即可。路径随机让 webview 缓存天然失效，不会显示旧二维码。

**然后反复调 `weixin_poll_status` 循环查扫码状态**（用户扫了没、确认了没）：

```text
mcp_weixin_weixin_poll_status  qrcode="<上一步的 qrcode hex>"
```

返回 `{"status": "wait|scaned|scaned_but_redirect|confirmed|expired", ...}`。**查到 `confirmed` 时 token 已自动保存**，agent 无需再手动存，直接调 `channel_ingest` 即可。

> ⚠️ 为什么拆成两个工具：微信扫码是人肉动作，可能要等几十秒。如果 `weixin_qrcode_login` 内部阻塞长轮询等确认，**会撞 MCP read timeout**（单次 tool 调用有超时，等不到扫码就被掐断，token 永远存不下来）。拆开后 agent 控制轮询节奏，单次调用都是秒回。

### 4. 收发消息

登录成功后：

- **收**：调 `mcp_weixin_channel_ingest`，返回 `{"messages":[{"msg_id","from","text","timestamp"}]}`。未登录时返回 `{"messages":[]}`（零打扰，感知层自动过滤）。
- **发**：调 `mcp_weixin_channel_emit`，传 `text`（要发的文本）+ `to_user_id`（收件人，用消息里的 `from`）。

---

## 环境变量

| 变量 | 作用 | 默认 |
|------|------|------|
| `IDES_HOME` | 存 token / 游标的目录 | 环境变量或当前目录 |
| `WEIXIN_ACCOUNT_ID` | 账号标识 | `default` |

> 单账号即可，不用多账号（微信 iLink Bot 本身不支持多 claw 绑定）。

---

## 实现参考

核心 API 参考 hermes-agent 的 `gateway/platforms/weixin.py`（已验证的 iLink Bot API），按 IDES channel 契约精简重做，不依赖 hermes-agent 生态。

## License

MIT
