# 微博私信接入指南

本文档介绍如何将 **cc-connect** 接入微博私信，让你可以通过微博私信远程调用 AI 编程 Agent。

## 前置要求

- 微博账号
- 一台可运行 cc-connect 的设备（无需公网 IP）
- AI 编程 Agent（Claude Code、Codex 等）已安装并配置完成

> 💡 **优势**：使用 WebSocket 长连接，无需公网 IP、无需域名、无需反向代理

---

## 第一步：注册微博开放平台应用

### 1.1 进入微博开放平台

访问 [微博开放平台](https://open.weibo.com/)，通过微博龙虾助手注册应用。

### 1.2 创建应用

按照平台指引创建一个新的应用，获取 Open IM 的 `app_id` 和 `app_secret`。

> ⚠️ **重要**：请妥善保存这两个凭证，后续配置 cc-connect 时需要用到。

---

## 第二步：配置 cc-connect

### 2.1 编辑配置文件

将凭证配置到 cc-connect 的 `config.toml` 中：

```toml
[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"

[[projects.platforms]]
type = "weibo"

[projects.platforms.options]
app_id = "your-weibo-app-id"
app_secret = "your-weibo-app-secret"
```

### 2.2 使用 CLI 引导配置（推荐）

也可以使用交互式 CLI 来配置：

```bash
cc-connect new
# 选择 weibo 平台，按提示输入 app_id 和 app_secret
```

### 2.3 可选配置项

```toml
[projects.platforms.options]
app_id = "your-weibo-app-id"
app_secret = "your-weibo-app-secret"
# allow_from = "*"           # 允许的微博用户 ID，逗号分隔；"*" 表示所有（默认）
# token_endpoint = ""        # 自定义 token 接口地址（默认：https://open-im.api.weibo.com/open/auth/ws_token）
# ws_endpoint = ""           # 自定义 WebSocket 地址（默认：ws://open-im.api.weibo.com/ws/stream）
```

---

## 第三步：启动 cc-connect

### 3.1 启动服务

```bash
cc-connect
# 或指定配置文件
cc-connect -config /path/to/config.toml
```

### 3.2 验证连接

启动后，cc-connect 会自动与微博建立 WebSocket 长连接。你会在日志中看到：

```
level=INFO msg="weibo: authenticated" uid=1234567890
level=INFO msg="weibo: websocket connected"
level=INFO msg="platform started" project=my-project platform=weibo
level=INFO msg="cc-connect is running" projects=1
```

---

## 第四步：开始使用

### 4.1 发送私信

在微博中给你的应用账号发送私信，即可与 AI Agent 对话：

```
用户: 帮我分析一下当前项目的结构

cc-connect: 🤔 思考中...
cc-connect: 🔧 执行: Bash(ls -la)
cc-connect: ✅ 这是一个 Go 项目，包含以下模块...
```

### 4.2 使用命令

所有 cc-connect 命令均可在微博私信中使用：

| 命令 | 功能 |
|------|------|
| `/status` | 查看 Agent 状态 |
| `/new` | 新建会话 |
| `/list` | 查看会话列表 |
| `/stop` | 停止当前会话 |
| `/help` | 查看帮助 |

---

## 连接方式说明

微博私信平台使用 WebSocket 长连接：

```
┌─────────────────────────────────────────────────────────────┐
│                      微博 Open IM                           │
│                                                              │
│   用户私信 ──→ open-im.api.weibo.com ──→ WebSocket Stream   │
│                                              │               │
└──────────────────────────────────────────────┼───────────────┘
                                               │
                                               │ WebSocket 长连接
                                               │ (无需公网IP)
                                               ▼
┌─────────────────────────────────────────────────────────────┐
│                      你的本地环境                            │
│                                                              │
│   cc-connect ◄──► AI Agent CLI ◄──► 你的项目代码            │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

| 特性 | 说明 |
|------|------|
| ✅ 无需公网 IP | 内网环境也能接入 |
| ✅ 无需域名 | 不需要配置域名 |
| ✅ 自动重连 | 断线后自动重连（指数退避） |
| ✅ 心跳保活 | 30 秒心跳间隔，40 秒超时检测 |
| ✅ Token 自动刷新 | 过期前自动续期 |

---

## 技术细节

### 消息长度限制

微博私信文本限制约 2000 字符。cc-connect 会自动将超长消息分块发送，接收端会按顺序收到完整内容。

### Token 管理

- 首次启动时通过 `app_id` + `app_secret` 获取 WebSocket Token
- Token 过期前 60 秒自动刷新
- WebSocket 断开时（code 4002 / invalid token）自动清除并重新获取

### 安全建议

- 使用 `allow_from` 限制允许使用的微博用户 ID
- 发送 `/whoami` 获取你的用户 ID
- 不要将 `app_secret` 提交到代码仓库

---

## 常见问题

### Q: 连接后收不到消息？

检查以下项目：
1. cc-connect 服务是否正常运行
2. WebSocket 连接是否建立成功（查看日志）
3. `app_id` 和 `app_secret` 是否正确

### Q: 长连接断开怎么办？

cc-connect 内置了自动重连机制（指数退避，最大 10 秒间隔），断开后会自动尝试重新连接。

### Q: 提示 Token 无效？

- Token 过期后会自动刷新，一般无需手动干预
- 如果持续失败，检查 `app_secret` 是否有效

### Q: 消息发送后显示不完整？

微博私信有约 2000 字符的限制，cc-connect 会自动分块发送。如果仍有问题，检查网络连接。

---

## 下一步

- [接入飞书](./feishu.md)
- [接入钉钉](./dingtalk.md)
- [接入 Telegram](./telegram.md)
- [接入 Discord](./discord.md)
- [接入 Slack](./slack.md)
- [返回首页](../README.md)