内容
# W 代理
[](https://github.com/Chessing234/w-agent/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org/)
[](https://pnpm.io/)
[](https://github.com/Chessing234/w-agent/releases)
**W 代理：你的 WhatsApp，拥有智慧。**
一个自我托管的桥梁，为 AI 代理提供持续、可搜索的 WhatsApp 聊天上下文，并允许其代表你回复，确保安全。
W 代理将你的存档存储在 **你的** Postgres 中，每条 outbound 草稿都需要批准（除非你选择自动发送到某个聊天），并为 Claude Desktop 和其他 MCP 客户端提供相同的上下文。WhatsApp 传输可更换：用于个人伴侣的非官方 Baileys，或用于商业消息传递的官方 Meta Cloud API。
> **运行警告。** 默认桥梁使用 Baileys（非官方多设备协议），存在 **账户封禁/限制风险**。请优先使用专用号码。对于商业工作负载，请设置 `WHATSAPP_PROVIDER=meta`。参见 [docs/security.md](docs/security.md) 和 [docs/providers.md](docs/providers.md)。
<!-- 可选：添加一个 ~60 秒的屏幕截图到 docs/assets/demo.gif
-->
## 功能
- **提供者适配 WhatsApp 桥梁** — Baileys（个人/多设备）或 Meta Cloud API
- **持久摄入** — 入站消息 → BullMQ → Postgres（联系人、聊天、消息、媒体）
- **历史同步和回填** — Baileys 历史片段和按需逐聊回填
- **混合搜索** — OpenAI 嵌入 + pgvector 与 Postgres 全文搜索合并
- **滚动聊天摘要** — 基于消息节奏的廉价模型内存
- **互动引擎** — 允许列表、群组 @提及、选择加入/退出、所有者 `/agent` 命令
- **安全栈** — 注入启发式（+可选 LLM 分类器）、出站聊天锁定、机密信息删除
- **审批出站** — 草稿通知所有者；在仪表板中审批（或逐聊自动发送）
- **发送卫生** — 配额、静默时间、打字延迟、指数级 WhatsApp 速率限制冷却
- **MCP 服务器** — stdio + HTTP/SSE 工具、资源和提示
- **操作** — 监视狗、`/healthz`、原子身份验证持久性、混沌 + 红队脚本
## 架构
```mermaid
flowchart TB
subgraph clients [客户端]
WA[WhatsApp]
Dash[仪表板]
MCPC[MCP 客户端<br/>Claude / ChatGPT / 自定义]
end
subgraph bridge [桥梁]
Prov["WhatsApp 提供者<br/>baileys | meta"]
end
subgraph queues [队列 - Redis / BullMQ]
IngestQ[摄入]
EmbedQ[嵌入]
SumQ[摘要]
Outbox[出站发送]
end
subgraph storage [存储]
PG[(Postgres + pgvector)]
Auth[(身份验证/媒体卷)]
end
subgraph agent [代理 + 安全]
Engage[互动]
Guard[注入防护]
Loop[代理循环 + 工具]
Draft[草稿 + 所有者通知]
end
subgraph mcp [MCP]
Stdio[stdio]
HTTPMCP[HTTP + SSE]
end
WA <--> Prov
Prov -->|提供者消息| IngestQ
IngestQ --> PG
IngestQ --> EmbedQ
EmbedQ --> PG
IngestQ --> SumQ
SumQ --> PG
Prov --> Auth
PG --> Engage
Engage --> Guard
Guard --> Loop
Loop --> Draft
Draft --> PG
Dash --> PG
Dash -->|批准| Outbox
Outbox --> Prov
MCPC --> Stdio
MCPC --> HTTPMCP
Stdio --> PG
HTTPMCP --> PG
Stdio --> Draft
HTTPMCP --> Draft
```
层详情：[docs/architecture.md](docs/architecture.md)。提供者权衡：[docs/providers.md](docs/providers.md)。
## 快速开始
需要 **Docker**、**Node.js 22+** 和 **pnpm 9+**。
```bash
git clone https://github.com/Chessing234/w-agent.git
cd w-agent
cp .env.example .env
# 必需：OPENAI_API_KEY
# 推荐：DASHBOARD_TOKEN（长随机密钥）
docker compose up -d --build
pnpm install && pnpm migrate
# 配对：应用程序日志或仪表板中的二维码
docker compose logs -f app
# — 或 —
# DASHBOARD_TOKEN=… pnpm dashboard:dev → http://localhost:3200/pairing
```
打开 WhatsApp → **链接设备** → 扫描二维码。当会话显示已连接时，您已完成默认 Baileys 路径。
```bash
curl -sS "http://127.0.0.1:3099/healthz"
```
仅限本地 Postgres/Redis（主机运行代理）：`make up-dev` — 参见 [examples/docker-compose.override.yml](examples/docker-compose.override.yml)。
## 文档
| 文档 | 内容 |
| -------- | -------- |
| [docs/architecture.md](docs/architecture.md) | 桥梁、队列、存储、代理、MCP；提供者适配器原理 |
| [docs/security.md](docs/security.md) | 注入威胁模型、审批管道、封禁风险、数据本地性 |
| [SECURITY.md](SECURITY.md) | 责任披露 |
| [docs/mcp-clients.md](docs/mcp-clients.md) | Claude Desktop & ChatGPT MCP 代码片段 |
| [docs/providers.md](docs/providers.md) | Baileys vs Meta Cloud API |
| [examples/demo.md](examples/demo.md) | 演示流程、红队、备份/恢复 |
| [CHANGELOG.md](CHANGELOG.md) | 发布说明 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发设置、测试、PR 期望 |
## 仪表板
```bash
pnpm dashboard:dev # http://localhost:3200 — token: DASHBOARD_TOKEN
```
路由：`/pairing`、`/chats`、`/approvals`、`/health`。
## MCP
| 传输 | 命令 | 身份验证 |
| --------- | ------- | ---- |
| stdio | `pnpm mcp` | 本地进程（Claude Desktop） |
| HTTP + SSE | 当设置 `MCP_AUTH_TOKEN` 时的应用，或 `pnpm mcp:http` | Bearer / `X-MCP-Token` / `?token=` |
完整客户端设置：[docs/mcp-clients.md](docs/mcp-clients.md)。
## 开发
```bash
pnpm install && cp .env.example .env
make up-dev && pnpm migrate
pnpm dev
pnpm dashboard:dev
pnpm lint && pnpm typecheck
pnpm test # 需要 Docker（testcontainers Postgres）
pnpm test:coverage # src/safety + src/agent 上 ≥80%
pnpm redteam # 10 个预设注入有效载荷
pnpm backup # Postgres + auth → backups/*.tar.gz
```
CI（`.github/workflows/ci.yml`）：lint、typecheck、Node 22 上的覆盖率测试，带有 Redis；Postgres 通过 testcontainers。
## 配置
在 `src/config.ts`（Zod）中验证。完整列表：[`.env.example`](.env.example)。
| 变量 | 目的 |
| -------- | ------- |
| `OPENAI_API_KEY` | 嵌入、摘要、代理、选定分类器 |
| `DATABASE_URL` / `REDIS_URL` | Postgres + Redis |
| `WHATSAPP_PROVIDER` | `baileys`（默认）\| `meta` \| `evolution`（保留） |
| `WHATSAPP_AUTH_DIR` / `MEDIA_DIR` | Baileys 身份验证 + 入站媒体 |
| `DASHBOARD_TOKEN` / `MCP_AUTH_TOKEN` | 仪表板/远程 MCP 机密 |
| `HEALTHZ_PORT` | 聚合 `/healthz` |
| `OWNER_TIMEZONE` / `QUIET_HOURS_*` / `SEND_*` | 自动发送安全 |
## 许可证
[MIT](LICENSE) © W 代理贡献者
