claude-code/wx_channel.md

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 中保留：

capabilities.experimental["claude/channel"] = {}

支持的协议：

• 入站推送：notifications/claude/channel
• 工具：reply、send_typing

当前已实现的增强

当前 weixin MCP server 已实现：

capabilities.experimental["claude/channel/permission"] = {}

并已补齐：

• notifications/claude/channel/permission_request
• notifications/claude/channel/permission

用户侧启用方式

1. 在 /plugin 启用 built-in weixin
2. 运行 weixin 登录/配置 skill
3. 启动会话时传入：

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 工具能把消息发回微信
• 类型检查与相关测试通过