内容
# hw-sw-bridge
两台笔记本电脑上的两个 Claude Code 代理通过加密的 Tailscale 隧道交换消息，以便硬件端代理（Windows + Vivado + FPGA 板）可以在跨平台嵌入式项目中与软件端代理（macOS + Xcode + iOS 应用）进行协调。
## 架构
```
┌─────────────── Windows 笔记本电脑 ───────────────┐ ┌─────────────── MacBook ─────────────────┐
│ │ │ │
│ Claude Code ──stdio──► MCP 服务器 ─┐ │ │ ┌─ MCP 服务器 ◄──stdio── Claude Code │
│ ▼ │ │ ▼ │
│ WebSocket :8765 │◄────►│:8765 WebSocket │
│ │ │ │
└──────────────────────▲───────────────────────┘ └──────────────────────▲──────────────────┘
│ │
└──────── Tailscale WireGuard 隧道 ─────────────────┘
（加密，任意网络，自动发现）
```
## MCP 工具
| 工具 | 描述 |
|---|---|
| `send_message(文本)` | 向对等方发送文本消息 |
| `wait_for_message(超时时间)` | 阻塞直到消息到达 |
## 设置
1. 在两台笔记本电脑上安装 Tailscale，使用相同的帐户登录
2. `tailscale status` 显示两台对等方具有 `100.x.y.z` IP 地址
3. 将此仓库克隆到两台笔记本电脑上
4. 在每台笔记本电脑上：`pip install -e .`
5. 在每台笔记本电脑上注册 MCP 服务器：
**Windows 笔记本电脑** （对等方 = Mac 的 Tailscale IP 地址）：
```
claude mcp add --scope user hw-sw-bridge \
--env HW_SW_PEER=100.114.22.33 \
-- python -m hw_sw_bridge.server
```
**Mac 笔记本电脑** （对等方 = Windows 笔记本电脑的 Tailscale IP 地址）：
```
claude mcp add --scope user hw-sw-bridge \
--env HW_SW_PEER=100.77.62.85 \
-- python -m hw_sw_bridge.server
```
6. 在每台笔记本电脑上的 Claude Code 中验证：`/mcp` 应该将 `hw-sw-bridge` 列为已连接。
7. 安装协调技能，以便每方的 Claude 知道 **何时** 使用这些工具：
**Windows：**
```
copy skills\hw-sw-bridge\SKILL.md %USERPROFILE%\.claude\skills\hw-sw-bridge\SKILL.md
```
（如果需要，请先创建目录）
**macOS：**
```
mkdir -p ~/.claude/skills/hw-sw-bridge
cp skills/hw-sw-bridge/SKILL.md ~/.claude/skills/hw-sw-bridge/SKILL.md
```
重启 Claude Code 以加载技能。
## 快速烟雾测试（无 Claude）
在笔记本电脑 B（接收器）上：
```
HW_SW_PEER=<A-tailscale-ip> python -c "import asyncio, hw_sw_bridge.peer as p; q=asyncio.Queue(); asyncio.run(p.serve_inbox(q, 8765))"
```
在笔记本电脑 A（发送器）上，在另一个终端中：
```
python -c "import asyncio; from hw_sw_bridge.peer import send; print(asyncio.run(send('<B-tailscale-ip>', 8765, 'hello')))"
```
笔记本电脑 B 的终端应该显示消息出现在其队列中（添加打印语句到 `serve_inbox` 以查看它）。
## 设计决策
- **Tailscale 而非原始 WebSocket + TLS** — WireGuard 处理加密、身份验证、NAT 穿透等在一个安装包中。无需管理证书。
- **对等方到对等方而非中心代理** — 无需第三方机器，无单点故障。
- **Python + `mcp` SDK** — 最小的跨平台运行栈（Windows + macOS）。
