mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-17 13:13:35 +08:00
84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
# Claude Code Channel 系统文档
|
||
|
||
> 通过 IM 平台远程控制 Claude Code Agent 的完整技术解析
|
||
|
||
---
|
||
|
||
## 文档目录
|
||
|
||
### [01-channel-system.md](./01-channel-system.md) — Channel 系统架构解析
|
||
|
||
从源码视角深度剖析 Claude Code Channel 系统的设计与实现，涵盖：
|
||
|
||
- **什么是 Channel**：IM 集成的核心概念、MCP 协议基础
|
||
- **整体架构**：消息流转全链路、组件关系
|
||
- **消息协议**：入站通知、XML 封装、出站工具调用
|
||
- **六层访问控制**：能力声明 → 运行时开关 → OAuth 认证 → 组织策略 → 会话白名单 → 插件审批
|
||
- **权限中继系统**：远程审批工具执行、5 字母请求 ID、多源竞争
|
||
- **插件架构**：Channel 插件清单声明、用户配置流、作用域命名
|
||
- **UI 组件**：终端消息渲染、状态通知、开发者警告对话框
|
||
- **安全设计**：防 XML 注入、marketplace 验证、信任边界分析
|
||
|
||
**适合人群**：想了解 AI Agent IM 集成架构的开发者、架构师、插件作者
|
||
|
||
---
|
||
|
||
## 配图说明
|
||
|
||
所有配图采用深色背景（#1a1a2e）+ Anthropic 品牌橙铜色（#D97757）风格。
|
||
|
||
| 图片 | 说明 | 所属文档 |
|
||
|------|------|----------|
|
||
| `01-channel-overview.png` | Channel 系统架构总览 — 组件关系全景 | 架构解析 |
|
||
| `02-message-flow.png` | 消息流转全链路 — IM → Agent → IM | 架构解析 |
|
||
| `03-access-control.png` | 六层访问控制 — 层层递进的安全门 | 架构解析 |
|
||
| `04-permission-relay.png` | 权限中继系统 — 远程审批流程 | 架构解析 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 用户
|
||
|
||
1. 阅读 [Channel 系统架构解析](./01-channel-system.md)
|
||
2. 了解如何通过 `--channels` 启动 IM 集成
|
||
3. 理解不同平台（Telegram、Feishu、Discord）的接入方式
|
||
|
||
### 插件开发者
|
||
|
||
1. 阅读架构解析中的 [插件架构](./01-channel-system.md#七、插件-channel-架构) 章节
|
||
2. 了解 `plugin.json` 中 Channel 声明格式
|
||
3. 实现 MCP Server 的 `notifications/claude/channel` 协议
|
||
4. 查看源码位置：
|
||
- `src/services/mcp/channelNotification.ts` — 核心门控与消息封装
|
||
- `src/services/mcp/channelPermissions.ts` — 权限中继系统
|
||
- `src/services/mcp/channelAllowlist.ts` — 白名单管理
|
||
- `src/utils/plugins/mcpPluginIntegration.ts` — 插件 MCP 集成
|
||
- `src/utils/plugins/schemas.ts` — 插件清单 Channel 声明 Schema
|
||
|
||
---
|
||
|
||
## 核心概念速查
|
||
|
||
| 概念 | 说明 |
|
||
|------|------|
|
||
| **Channel** | 一个声明了 `claude/channel` 能力的 MCP Server，可推送 IM 消息到 Agent |
|
||
| **Channel Entry** | `--channels` 参数解析后的条目，分 plugin 和 server 两种 |
|
||
| **Channel Gate** | 六层访问控制门，决定是否注册通知处理器 |
|
||
| **Permission Relay** | 将工具执行审批提示转发到 IM 平台的机制 |
|
||
| **Channel Plugin** | 在 `plugin.json` 中声明 `channels` 字段的插件 |
|
||
| **Scoped Name** | 插件服务器的作用域名称，格式 `plugin:{pluginName}:{serverName}` |
|
||
| **Short Request ID** | 5 字母权限请求标识符，基于 FNV-1a 哈希生成 |
|
||
| **Channel Tag** | `<channel>` XML 标签，封装来自 IM 的消息内容和元数据 |
|
||
| **Dev Channels** | 通过 `--dangerously-load-development-channels` 加载的本地开发频道 |
|
||
| **tengu_harbor** | GrowthBook 运行时特性开关，控制 Channel 功能总开关 |
|
||
|
||
---
|
||
|
||
## 相关资源
|
||
|
||
- [Claude Code Haha 主页](/)
|
||
- [Agent 框架解析](/agent/03-agent-framework)
|
||
- [Skills 系统文档](/skills/01-usage-guide)
|
||
- [GitHub Issues](https://github.com/NanmiCoder/cc-haha/issues)
|