内容
# Piumy 🦉
一款适用于 ARM64 板卡的分布式、可移植的 WhatsApp 助手。一个小板卡
**路由和存储**（交换中心）；大脑（AI）通过 **MCP**
从具有 RAM 的机器连接。所有特定硬件的内容都位于**可配置适配器**后面，因此相同的代码可以在任何 ARM64 板卡上运行。
> ## (⌐■_■) pwnagotchi has pwned hehehe
> Piumy 的电子纸面部是对 **[pwnagotchi](https://github.com/evilsocket/pwnagotchi)**
> 由 [@evilsocket](https://github.com/evilsocket) 的致敬。表情灵感来自其
> 电子墨水面部——原始代码，借来的感情。 🫡
## 想法
```
WhatsApp（专用号码）
│
▼
交换中心（Go，小板卡） ── 电子纸（Python 适配器）→ 面部
· 接收 / 存储（SQLite） └ 读取 status.json
· 每聊模式：自动 | 高级
· 防封治理 · 白名单
· 暴露 MCP ──────────────┐
│ 自动 │ 高级（队列，拉取）
▼ ▼
廉价 API 代理通过 MCP（另一台具有 RAM 的机器）
（可选） Claude / Opus / OpenCode + 工具
```
**交换中心不会回复 — 它路由和存储。** 回复来自
谁通过 MCP 连接。缝隙是 **数据合约**：`status.json`
（核心 ↔ 显示）和 MCP/HTTP（核心 ↔ 代理）。
## 面部 — 真正的 pwnagotchi kaomoji
真正的 pwnagotchi **kaomoji** 面部（不是矢量图），在电子纸上以 1 位渲染
大眼睛实际上 **环顾四周** — 三种眼睛样式在一个凝视循环中旋转 — 眨眼，并对正在发生的事情做出反应（新消息，代理
连接，电池耗尽）。它在有东西需要反应时会移动，并在安静时进入平静、低功耗的空闲状态。
## 电池智能
一个 **自我校准** 的燃油表（CW2015 通过 I2C）：读取原始电池电压，
从实际放电中学习 *此* 包的真实满→空范围，并报告一个
**均匀、线性级别**（电压本身以跳跃方式变化）具有自适应
时间剩余。每分钟放电日志使电压随时间可追踪。
## 仪表板
一个轻量级网页仪表板，由同一个 Go 二进制文件（仅限局域网，登录）提供：**实时面部**，
电池图表（原始 vs. 线性 + 充电带），WhatsApp
链接/二维码，防封静音，每个聊天规则，速率限制和路由器/白名单。
## 堆栈
- **核心（交换中心）：** Go — [`whatsmeow`](https://github.com/tulir/whatsmeow) （MPL-2.0）+ `mcp-go` （MIT）+ SQLite。单个、轻量级二进制文件。
- **显示适配器：** Python + Pillow。后端：`file` （PNG，开发）· `epaper-waveshare` · `none`。
- **电源适配器：** Python — CW2015 通过 I2C。后端：`cw2015-i2c` · `none`。
- **大脑：** 任何通过 MCP 的代理（它不生活在板卡上）。
## 现在试试吧（无需硬件，无需 WhatsApp）— 合约 #001
核心写入 `status.json`；`file` 适配器将其绘制为面部。
```bash
# 1) 核心（Go）写入状态
cd core && go run . responding
# 2) 渲染面部
cd ../adapters/display/file
pip install -r requirements.txt
python render.py # -> 生成 display.png
```
有效状态：`idle thinking responding sleeping working alert error qr`。
## 连接大脑（MCP）
MCP 端点（`：8081`）是 **故障关闭**：它拒绝每个请求
直到配置了令牌 — 一个开放的 MCP 端点根本没有信任边界
（任何工具，包括所有者范围的工具，都可以被 LAN 上的任何人访问）。
在真正的安装中，`install.sh` 自动运行此操作并打印令牌一次。要手动执行（或旋转现有的令牌）：
```bash
sudo /opt/pimywa/pimywa auth setup # 生成 + 保存一个令牌（幂等）
sudo /opt/pimywa/pimywa auth rotate # 始终生成一个新的令牌，使旧令牌失效
```
两者都打印确切的客户端配置以粘贴到您的 MCP 客户端
（Claude Code / OpenCode 的 `.mcp.json`）：
```json
{"mcpServers": {"piumy": {"url": "http://<host>:8081/mcp",
"headers": {"Authorization": "Bearer <token>"}}}}
```
令牌仅显示 **一次** — 保存它（密码管理器，或将其交给
运行代理的人）。它存储在 `/opt/pimywa/pimywa.env` 中
作为 `PIMYWA_MCP_KEY`，永远不会提交到 git。重启 `pimywa-core`
后，新的令牌生效。
## 可移植性
硬件仅通过通用 Linux 接口（`spidev` / `libgpiod` /
`i2c-dev`）触及，从不通过供应商锁定的库。要移植到另一个 ARM64 板卡，
请参见 [`HARDWARE.md`](HARDWARE.md)。
## 状态
**MVP 功能完整** 并在树莓派 Zero 2 W 上运行：核心交换中心
（WhatsApp 网关，路由器，防封治理，MCP 服务器），电子纸 kaomoji
面部 + 眼睛引擎，自我校准电池智能，网页仪表板，
MCP **令牌身份验证**，以及客户端 [技能](skill/piumy/SKILL.md)。查看完整
功能地图 — 已完成 / 进行中 / 计划 — 在 **[`ROUTEMAP.md`](ROUTEMAP.md)** 中。
## 支持
Piumy 是免费且开源的 — **捐款是维持其发展的基石**。WhatsApp 只是一个起点；计划是一个安全的个人网关供每个人使用。如果它对您有用，请随意捐赠（即使是 $0）：
**[♥ 捐赠 — 随意捐赠](https://clevercat.lemonsqueezy.com/checkout/buy/3e2ebe37-5116-4e2a-9400-2246c1199c8d)**
## 构建
Piumy 依赖于优秀的开源工作 — Go 核心大部分是围绕这些工作的：
- **[whatsmeow](https://github.com/tulir/whatsmeow)** 由 Tulir Asikainen — WhatsApp Web 多设备库（MPL-2.0），实际上与 WhatsApp 对话。
- **[mcp-go](https://github.com/mark3labs/mcp-go)** 由 mark3labs — 模型上下文协议服务器（MIT），大脑通过它连接。
- **[modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)** 由 Jan Mercl（cznic）— 纯 Go SQLite（BSD-3），因此核心可以交叉编译为 ARM 且无 CGO。
- **[go-qrcode](https://github.com/skip2/go-qrcode)** 由 skip2 — 连接您手机的二维码（MIT）。
- **[golang.org/x/crypto](https://pkg.go.dev/golang.org/x/crypto)** & **[google.golang.org/protobuf](https://pkg.go.dev/google.golang.org/protobuf)** 由 Go 作者和 Google（BSD-3）。
…以及它们的传递依赖。谢谢。 🙏
## 许可证
**[AGPL-3.0](LICENSE)** （网络 copyleft）。您可以自由使用、修改和
分发；您的版本 — 即使您将其作为服务运行 — 也必须为 AGPL-3.0。
**商业许可证 / 双重许可证：** 想要在闭源产品中使用 Piumy，
无需 AGPL 义务？作者可以授予商业许可证 —
[打开一个问题](../../issues) 以协调。
---
由 **Camilo Brossard** · [clever.cat](https://clever.cat) 🐱 · 社区： [r/Piumy](https://www.reddit.com/r/Piumy/)
