From 6607b133643cf4eeb9e37e8c31691632712885ab Mon Sep 17 00:00:00 2001
From: 1111 <11111@asd.c>
Date: Sun, 19 Apr 2026 14:40:30 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=BE=AE=E4=BF=A1=20?=
 =?UTF-8?q?channel=20=E6=8E=A5=E5=85=A5=E8=AE=A1=E5=88=92=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 wx_channel.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 248 insertions(+)
 create mode 100644 wx_channel.md

diff --git a/wx_channel.md b/wx_channel.md
new file mode 100644
index 000000000..0c420b239
--- /dev/null
+++ b/wx_channel.md
@@ -0,0 +1,248 @@
+# WeChat Channel 接入计划
+
+## 目标
+
+将 `E:\claude-code\cc-weixin` 迁入本仓库，作为 **built-in plugin + built-in stdio MCP channel server** 接入，支持：
+
+- 微信消息推送到 Claude Code 会话
+- Claude Code 通过 MCP 工具回复微信消息
+- 使用 `--channels plugin:weixin@builtin` 在会话级启用
+
+MVP 初版曾暂不包含远程工具审批（permission relay），但当前实现已将该能力补齐。
+
+## 进度更新
+
+### 2026-04-19（最新）
+
+当前落地状态：
+
+- built-in weixin plugin 已完成接入
+- `ccb weixin serve|login|access pair` CLI 链路已完成
+- weixin MCP stdio server、消息轮询、`reply` / `send_typing` 已完成
+- `--channels plugin:weixin@builtin` 启用链路已完成
+- ChannelsNotice 对 builtin plugin 的误报修复已完成
+- permission relay 已完成并通过闭环验证：
+  - server 声明 `experimental["claude/channel/permission"]`
+  - 接收 `notifications/claude/channel/permission_request`
+  - 通过微信发送审批提示
+  - 解析 `yes/no <request_id>`
+  - 回发 `notifications/claude/channel/permission`
+- permission relay 的关键路由与 capability 判定问题已修复并验证通过：
+  - 不再把权限请求盲发给“最后活跃聊天”，而是携带当前会话最近 channel 消息的 `chat_id/source_server` 作为路由提示
+  - `claude/channel/permission` 的 capability 判定已统一为 truthy 语义
+
+当前验证状态：
+
+- `bun run typecheck` 已通过
+- `bun run build` 已通过
+- weixin 相关定向测试已通过
+- 手工 E2E 已通过
+- 微信端审批提示与 allow/deny 闭环已在真实会话中验证通过
+
+当前结论：
+
+- 本计划的 MVP 范围已完成并达到验收标准
+- 后续如有新增工作，主要为体验优化、补充文档细节或扩展能力，不再属于当前 MVP 阻塞项
+
+### 2026-04-19 14:11:18 +08:00
+
+当前落地状态：
+
+- 已创建分支：`feat/wx-channel`
+- 已完成 built-in weixin plugin 接入
+- 已完成 `ccb weixin serve|login|access pair` CLI 链路
+- 已完成 weixin MCP stdio server、消息轮询、`reply` / `send_typing`
+- 已完成 `--channels plugin:weixin@builtin` 启用链路
+- 已完成 ChannelsNotice 对 builtin plugin 的误报修复
+- 已完成 permission relay：
+  - server 声明 `experimental["claude/channel/permission"]`
+  - 接收 `notifications/claude/channel/permission_request`
+  - 通过微信发送审批提示
+  - 解析 `yes/no <request_id>`
+  - 回发 `notifications/claude/channel/permission`
+- 已修复 permission relay 的两个关键问题：
+  - 不再把权限请求盲发给“最后活跃聊天”，而是携带当前会话最近 channel 消息的 `chat_id/source_server` 作为路由提示
+  - `claude/channel/permission` 的 capability 判定已统一为 truthy 语义
+
+当前验证状态：
+
+- `bun run typecheck` 已通过
+- `bun run build` 已通过
+- weixin 相关定向测试已通过
+- 当前剩余工作主要是继续做手工 E2E，确认微信端审批提示与 allow/deny 闭环在真实会话里稳定可用
+
+## 架构决策
+
+### 采用 built-in plugin，而不是外部 marketplace 插件
+
+原因：
+
+- 本仓库已有内建插件注册链路：`src/plugins/builtinPlugins.ts`、`src/plugins/bundled/index.ts`
+- 本仓库已有 channels 协议与 gate：`src/services/mcp/channelNotification.ts`、`src/services/mcp/useManageMCPConnections.ts`
+- `cc-weixin` 已具备 `experimental["claude/channel"]` 能力与 `notifications/claude/channel` 通道契约
+- 内建插件更容易跨平台启动内部 MCP server，不依赖 `${CLAUDE_PLUGIN_ROOT}` 或 `/bin/sh`
+
+### MVP 范围
+
+包含：
+
+- 微信登录与状态管理
+- 微信消息轮询与入站推送
+- `reply` / `send_typing` 工具
+- `--channels plugin:weixin@builtin` 启用链路
+- 微信端 permission relay（审批提示 + yes/no 回复）
+- 文档与测试补齐
+
+不包含：
+
+- 通用 plugin userConfig 面板化
+
+## 主仓库新增文件
+
+建议新增目录：`src/services/weixin/`
+
+新增文件：
+
+- `src/services/weixin/types.ts`
+- `src/services/weixin/accounts.ts`
+- `src/services/weixin/api.ts`
+- `src/services/weixin/login.ts`
+- `src/services/weixin/cliLogin.ts`
+- `src/services/weixin/media.ts`
+- `src/services/weixin/monitor.ts`
+- `src/services/weixin/pairing.ts`
+- `src/services/weixin/send.ts`
+- `src/services/weixin/server.ts`
+- `src/plugins/bundled/weixin.ts`
+- `src/types/qrcode-terminal.d.ts`（如需要）
+
+## 主仓库需修改文件
+
+- `package.json`
+  - 添加 `qrcode-terminal`
+- `src/plugins/bundled/index.ts`
+  - 注册 built-in weixin plugin
+- `src/main.tsx`
+  - 增加内部 server 启动入口（建议 `weixin serve`）
+- `src/services/mcp/channelAllowlist.ts`
+  - 让 `weixin@builtin` 能通过内建来源校验
+- `src/services/mcp/__tests__/channelNotification.test.ts`
+  - 增加 builtin weixin 场景
+- `README.md`
+- `docs/features/channels.md`
+  - 补微信启用说明
+
+## 从 cc-weixin 迁入的文件来源
+
+优先迁入：
+
+- `plugins/weixin/src/types.ts`
+- `plugins/weixin/src/accounts.ts`
+- `plugins/weixin/src/api.ts`
+- `plugins/weixin/src/login.ts`
+- `plugins/weixin/src/media.ts`
+- `plugins/weixin/src/monitor.ts`
+- `plugins/weixin/src/pairing.ts`
+- `plugins/weixin/src/send.ts`
+
+需改造后迁入：
+
+- `plugins/weixin/server.ts`
+- `plugins/weixin/src/cli-login.ts`
+
+不直接迁入：
+
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.mcp.json`
+
+## Capability 与协议
+
+### MVP 必需
+
+在 weixin MCP server 中保留：
+
+```ts
+capabilities.experimental["claude/channel"] = {}
+```
+
+支持的协议：
+
+- 入站推送：`notifications/claude/channel`
+- 工具：`reply`、`send_typing`
+
+### 当前已实现的增强
+
+当前 weixin MCP server 已实现：
+
+```ts
+capabilities.experimental["claude/channel/permission"] = {}
+```
+
+并已补齐：
+
+- `notifications/claude/channel/permission_request`
+- `notifications/claude/channel/permission`
+
+## 用户侧启用方式
+
+1. 在 `/plugin` 启用 built-in `weixin`
+2. 运行 weixin 登录/配置 skill
+3. 启动会话时传入：
+
+```bash
+ccb --channels plugin:weixin@builtin
+```
+
+## 实施顺序
+
+1. 迁入 `src/services/weixin/*` 业务层
+2. 改造 `server.ts` 为主仓库内部 MCP server
+3. 在 `src/main.tsx` 增加 `weixin serve`
+4. 注册 `src/plugins/bundled/weixin.ts`
+5. 修改 `channelAllowlist.ts`
+6. 补登录 skill / 文档 / 测试
+7. 手工 E2E 验证
+
+## 测试计划
+
+### 单元测试
+
+- `accounts.test.ts`
+- `pairing.test.ts`
+- `media.test.ts`
+- `send.test.ts`
+- `monitor.test.ts`
+- `server.test.ts`
+
+### 集成测试
+
+- built-in plugin 注册与启用
+- `--channels plugin:weixin@builtin` gate 流程
+- headless / print 路径的 channel 可见性
+
+### 手工 E2E
+
+1. 启用 built-in `weixin`
+2. 微信扫码登录
+3. 启动 `ccb --channels plugin:weixin@builtin`
+4. 微信发消息
+5. Claude 会话收到 channel 消息
+6. 模型调用 `reply`
+7. 微信收到回复
+
+## 风险点
+
+1. `channelAllowlist.ts` 当前偏向 marketplace plugin，需要对 `builtin` 来源做兼容
+2. built-in plugin 需要稳定的内部 server 启动入口，不能依赖外部插件目录
+3. Windows 下不能复用 `/bin/sh` 启动链路
+4. `qrcode-terminal` 需要补类型与依赖
+5. 登录状态目录若继续使用 `~/.claude/channels/weixin/`，需确认是否接受
+
+## 验收标准
+
+- `weixin` 能作为 built-in plugin 出现在本仓库插件体系中
+- `ccb --channels plugin:weixin@builtin` 可注册 channel
+- 微信消息能进入 Claude Code 会话
+- `reply` 工具能把消息发回微信
+- 类型检查与相关测试通过