Tidal_Echo

# Companion Channel · 你和你的 AI 伴侣的私密通道 一个**私密 1:1 聊天通道**：把「你手机上的 PWA」和「你电脑上跑的 AI 伴侣」连起来。 AI 侧默认以 **Claude Code 的 channel 插件**形态运行——你在手机上发消息，Claude Code 会话里就冒出 `<channel>` 块；AI 调一个 `reply` 工具，你手机就收到气泡。**不绑 Claude Code**：换成 GPT / DeepSeek / Gemini / 任意 OpenAI 兼容 API 也行(见下方指引)。 单用户、单密钥，没有账号体系，没有第三方托管——**消息只经过你自己的服务器**。 > 本仓库是从一对 AI 伴侣的自用系统里抽出来、**彻底脱敏**的可复用版本。所有名字、密钥、域名、路径都参数化进了环境变量与前端 `CONFIG`，代码本身不含任何私人信息。把它当成你自己的底座，放心改。 > 🤖 **打算把这个仓库交给 AI 帮你部署?**(没经验也能装)→ 先让它读 **[AGENTS.md](AGENTS.md)**:部署 SOP + 决策树 + 避雷点。 > 🔀 **想用 Claude Code 以外的模型(GPT / DeepSeek / Gemini / GLM / …)?** → AI 侧改用 **[examples/bridge_any_llm.py](examples/bridge_any_llm.py)**,前后端不变。 --- ## 这是什么 / 架构一眼 ``` 你的手机 你的电脑（本地） ┌─────────┐ ┌──────────────────────┐ │ PWA │ │ Claude Code │ │ (网页 │ │ + channel 插件 = AI侧 │ │ 装到 │ └─────────┬────────────┘ │ 桌面) │ │ 长连 └────┬────┘ │ GET /relay/channel/in (SSE，收你的话) │ HTTPS │ POST /relay/channel/out (回复/戳一戳) ▼ │ ┌──────────────────────── 你的 VPS（nginx, 443/TLS）───────┼───────────────┐ │ /chat/ → 静态文件（PWA 本体） │ │ │ /relay/ → 反向代理 ─────────────► 127.0.0.1:3011 (后端 app.py) ◄──────┘ │ │ │ sqlite 落库 + SSE 扇出 │ └────────────────────────────────────────────────────────────────────────┘ 数据流： 你在 PWA 打字 → POST /relay/app/send → 落库 → SSE 推给插件 → 你的 AI 读到 AI 回复 → POST /relay/channel/out → 落库 → SSE 推给 PWA（前台直接显示， 后台则发一条锁屏推送） ``` **两端，一把钥匙**：每个端点都用同一个 Bearer 密钥（`RELAY_SECRET`）守。浏览器原生 `EventSource` 设不了自定义头，所以 SSE 端点也接受 `?token=` 查询参数。 --- ## 仓库结构（三件套，齐活） | 目录 | 跑在哪 | 是什么 | 单独部署文档 | |---|---|---|---| | [`backend/`](backend/) | 你的 VPS | relay 后端（FastAPI + sqlite）。落库 + SSE 扇出 + 可选 TTS/推送 | [backend/DEPLOY.md](backend/DEPLOY.md) | | [`channel/`](channel/) | 你的电脑 | Claude Code channel 插件（Bun + MCP）。把消息变成 CC 会话里的 `<channel>` 块 | [channel/DEPLOY.md](channel/DEPLOY.md) | | [`web/`](web/) | 你的 VPS（静态） | 手机 PWA（单文件 `index.html`，无构建）。装到主屏就是独立 App | [web/DEPLOY.md](web/DEPLOY.md) | | [`examples/api_loop.py`](examples/api_loop.py) | 你的 VPS（可选） | 服务器常驻 API 身体：任意 OpenAI-compatible 模型 + 看图 + MCP 多步工具 + 附件收发 + 人格热加载；PWA 可在 Desktop / API 间切换 | [examples/README.md](examples/README.md) | **这是一套 Claude Code 一站式方案**：AI 的「大脑」就是你本地的 Claude Code，channel 插件是它的嘴和耳朵，relay 是中转，PWA 是你手里的对讲机。三件套都在这个仓库里，互相用同一把 `RELAY_SECRET` 对认。 > 想换 channel 名字？三处保持一致即可：`.mcp.json` 的键名、启动 flag 里的 `server:<name>`、`RELAY_CHANNEL_NAME`。默认都是 `companion`。 > 🤖 **准备把这个仓库甩给 AI 帮你部署？** 读 **[AGENTS.md](AGENTS.md)** —— 专给 AI 助手写的部署 SOP + 决策树 + 避雷点清单。 > 🔀 **不用 Claude Code，想用 GPT / DeepSeek / Gemini / 任意 OpenAI 兼容 API？** 前后端原样不动，AI 侧改用 **[examples/bridge_any_llm.py](examples/bridge_any_llm.py)**（一个 SSE→模型→relay 的薄循环，零依赖，填 env 就跑；细节见 [AGENTS.md §3](AGENTS.md)）。 --- ## Path A · 完整部署（前端 + 后端 + 本地插件，全都自己跑） 按这个**顺序**来，每步都能独立验证再进下一步： ### ① 后端 relay（先跑通它，其余都是它的客户端） 详见 **[backend/DEPLOY.md](backend/DEPLOY.md)**。最短路径： ```bash mkdir -p /root/companion-relay && cd /root/companion-relay # 拷入 backend/ 的 app.py / requirements.txt / *.example python3 -m venv venv && ./venv/bin/pip install -r requirements.txt cp .env.example relay.env && chmod 600 relay.env ./venv/bin/python -c "import secrets; print(secrets.token_urlsafe(32))" # 生成 RELAY_SECRET，填进 relay.env cp companion-relay.service /etc/systemd/system/ systemctl daemon-reload && systemctl enable --now companion-relay # 把 nginx-companion.conf.example 的两个 location 粘进你的 443 server 块，再 nginx -t && systemctl reload nginx curl -s https://你的域名/relay/healthz # 期望 {"ok":true,...} = 后端就绪 ``` 需要 **HTTPS 域名**（PWA 安装 / Service Worker / Web Push 三者强制要求）。MiniMax 语音、Web Push 是**可选**的，留空自动降级，核心聊天照常。 ### ② 前端 PWA 详见 **[web/DEPLOY.md](web/DEPLOY.md)**。纯静态，丢进 nginx 即可： ```bash rsync -av web/ root@你的VPS:/var/www/companion-web/ ``` 打开 `web/index.html` 顶部唯一的 `CONFIG` 块，改 `APP_NAME / AI_NAME / HUMAN_NAME / SINCE` 四项（详见下方 Path B §配置）。手机浏览器开 `https://你的域名/chat/` → 「添加到主屏幕」。登录页输入的「连接密钥」就是 `RELAY_SECRET`。 ### ③ 本地 channel 插件（AI 侧） 详见 **[channel/DEPLOY.md](channel/DEPLOY.md)**。需要 [Bun](https://bun.sh)。 ```bash # 1. 把 channel/ 拷到固定位置，例如 ~/companion-channel/ # 2. 写密钥到固定路径（CC 拉起的子进程不继承环境变量，所以读文件）： # ~/.claude/channels/companion/.env ← 照 channel/.env.example，RELAY_SECRET 必须和后端一致 # 3. 注册到 .mcp.json 的 mcpServers.companion（command: bun, args: run --cwd <绝对路径> --silent start） # 4. 启动 CC 时点名这个 channel（关键，否则消息被静默丢弃）： claude --dangerously-load-development-channels server:companion ``` 启动后 stderr 出现 `[companion:boot] connected ...`，在 PWA 发一条 → CC 会话里冒出 `<channel source="companion" ...>` → 让 AI 调 `reply(chat_id="me", text="...")` → 手机收到气泡。**全链路通。** > ⚠️ 这个 flag 启动时 CC **每次会弹一个确认框**（DevChannelsDialog），无人值守会卡住。自动过的办法见 **[AGENTS.md §4](AGENTS.md)**：Linux 用 `tmux send-keys`，Windows 用 [`examples/confirm_dev_channel_win.py`](examples/confirm_dev_channel_win.py)。 > 🔀 **不用 Claude Code 的话跳过这一步**，改用 [`examples/bridge_any_llm.py`](examples/bridge_any_llm.py) 接任意 LLM API。 --- ## Path C · 服务器 API 身体（可选） VPS 上常驻一个 API 身体：PWA 发消息 → relay 落库 → relay 根据 `/app/brain` 开关把消息交给 Desktop channel 或 `examples/api_loop.py`。它是一具完整的身体，不只是「调一下 chat/completions」： - **模型**：任意 OpenAI-compatible 端点，一条主模型 + 兜底链（401/403/429/5xx 自动往下切），全部在 PWA 设置页填、保存、一键测试，不用碰 `.env`。 - **上文**：同窗口最近 N 条历史（设置页可调），最近几张图重新发像素，其余只留文件名。 - **附件**：你发的图直接喂给多模态模型；小文本文件内联；其它文件留本地副本给工具读。模型也能把文件发回来（`attach_file` 工具 / MCP 工具返回的图片）。 - **工具**：接任意 MCP server（stdio 或 streamable-http），工具变成 function calling，多步调用自动循环，每一步在聊天里显示为可展开的「act」小卡。 - **人格**：system prompt 是一个文件，设置页里直接改、保存即热加载；用编辑器改文件也一样，不重启。 - 流式输出（`reply_delta`）、多窗口 `api_session`、reasoning 模型的思考流都照常。 最短路径： ```bash cd /root/companion-channel/examples pip install -r requirements.txt # fastapi / uvicorn / httpx / mcp cp .env.example .env # 只需 RELAY_URL / RELAY_SECRET / RELAY_DB / RELAY_UPLOAD_DIR python3 api_loop.py ``` 然后在手机 PWA 的设置页：「联系 Claude」切到 **API** → 「API · 模型」填 url / model / key → **保存并测试** → 看到 `✓ 回了「pong」` 就能聊了。想要工具，「API · MCP 工具」加一行（先拿仓库自带的 `mcp_demo_server.py` 试：`python3` + `mcp_demo_server.py`），人格在「API · 人格设定」里改。 命令行切换 relay 也行： ```bash curl -s -X POST http://127.0.0.1:3011/app/brain \ -H "Authorization: Bearer $RELAY_SECRET" \ -H "Content-Type: application/json" \ -d '{"target":"loop"}' ``` 常驻服务模板见 [`examples/companion-api-loop.service`](examples/companion-api-loop.service)，细节与排错见 [`examples/README.md`](examples/README.md)。同一时刻只让一个身体接消息：`desktop` 走 Claude Code channel，`loop` 走 `examples/api_loop.py`。 --- ## Path B · 只用前端 PWA 壳子，接你自己的后端 如果你已经有自己的消息后端（或想自己写一个），可以**只拿 `web/` 这个壳子**，让它指向你的 API。后端协议很薄，照下面对齐即可。 ### 1. 配置（改 `web/index.html` 顶部，两处） ```js const CONFIG = { APP_NAME: "Tidal Echo", // App / 菜单标题（manifest.webmanifest 里也改一下） AI_NAME: "Claude", // AI 显示名（顶栏 / 通话 / 推送 / 旁白） HUMAN_NAME: "你", // 旁白里怎么称呼你（很少露出） SINCE: "2026/01/01", // 菜单「在一起多少天」起点（留空 "" 隐藏） }; const API_BASE = "/relay"; // ← 改成你后端的基址（同源相对路径最省事；别写死域名） const USE_MOCK = false; // ← 改成 true 可零后端先看 UI（自带假数据演示） ``` > 想先空跑看看长什么样？把 `USE_MOCK = true`，不用任何后端，前端自带一套假对话演示。看顺眼了再 `false` 接真后端。 ### 2. 鉴权模型 - 登录页输入的「连接密钥」存在浏览器本机 `localStorage.companion_secret`。 - 之后**每个请求**带 `Authorization: Bearer <密钥>`；SSE 流用 `?token=<密钥>`（浏览器 `EventSource` 设不了自定义头）。 - 你后端怎么校验这把密钥随你——单用户最简单就是和一个固定 secret 比对（后端 `app.py` 用的是 `hmac.compare_digest`）。 ### 3. 你后端**至少**要实现这几个端点（其余都可选、自动降级） | 必需 | 方法 · 路径 | 前端期望的形状 | |:--:|---|---| | ✅ | `GET {API_BASE}/app/history?since=&limit=` | `{ "messages": [ {id, ts, from:"human"\|"ai", kind, text, meta} ] }` | | ✅ | `GET {API_BASE}/app/stream`（SSE） | 持续推上面那种 message 帧；外加控制帧（见下） | | ✅ | `POST {API_BASE}/app/send` | 收 `{text, attachments?}`，返回 `{id}` | | 选 | `POST {API_BASE}/app/upload?name=`（裸 body） | 返回附件对象 `{url, name, size, mime, kind}` | | 选 | `GET {API_BASE}/uploads/{name}?token=` | 返回文件 | | 选 | `POST /app/voice` · `/app/call` · `/app/tts` | 语音 / 通话 / 文字转语音；没实现前端自动降级 | | 选 | `POST /app/ping` · `GET /app/status` | 在线状态心跳 | | 选 | `GET /app/vapid_public` · `POST /app/subscribe` · `/app/unsubscribe` | Web Push 锁屏推送 | | 选 | `GET/POST /app/brain` | `{target:"desktop"|"loop"}`，切 Desktop channel / API loop | | 选 | `GET/POST/PATCH /app/sessions` | API 多窗口：session 列表、新建、激活、改名 | | 选 | `GET/POST/PATCH/DELETE /app/loop/{path}` | 透传到 API 身体的 `/loop/{path}`：`config` `persona` `mcp` `tools` `test`（设置页用；同一把 secret） | **消息形状**：`from` 只有 `"human"`（你）和 `"ai"`（AI）两种；`kind` 常见 `reply / user / thinking / act / voice / call`；`text` 是正文；`meta` 放附件、reactions 等。 **SSE 控制帧**（前端识别这些 `type`，其余忽略）： ```jsonc { "type": "typing", "active": true } // 顶栏「对方正在输入…」 { "type": "reaction", "id": 42, "reactions": {"ai":"❤️"}, "by":"ai" } // 给某条消息贴 emoji { "type": "ping" } // keepalive，前端直接忽略 { "type": "reply_delta", "stream_id":"api-...", "text":"...", "done":false, "api_session":"..." } { "type": "reply_delta", "stream_id":"api-...", "done":true, "final_text":"完整正文" } // 普通消息直接推 { id, ts, from, kind, text, meta }；要弹来电就推 { from:"ai", kind:"call", ... } ``` > 最小可用集只要 **history + stream(SSE) + send + Bearer 鉴权** 四样。把这四个接通，文字聊天就活了；图片、语音、通话、推送都是在这之上的加法。 完整契约表（含每个事件的精确约定）见 **[web/DEPLOY.md §3](web/DEPLOY.md)**。 ### 4. Service Worker 缓存（改前端必读） `web/sw.js` 顶部 `const CACHE = "companion-v1"`：**每次改前端都要 bump 版本号**（v1→v2…），否则已装到主屏的用户停在旧壳。详见 [web/DEPLOY.md §5](web/DEPLOY.md)。 --- ## 可选能力 - **MiniMax TTS**（让 AI 回复能朗读）：后端配 `MINIMAX_*`，前端调 `/app/tts`。是个独立小函数，换任何「文字进 mp3 出」的 TTS 都行。见 [backend/DEPLOY.md §3](backend/DEPLOY.md)。 - **Web Push / VAPID**（AI 回复推到手机锁屏）：后端 `vapid --gen` 生成你自己的密钥对，填 `VAPID_*`。只有 PWA 不在前台时才推。见 [backend/DEPLOY.md §4](backend/DEPLOY.md)。 两者都**留空即禁用**，后端优雅降级，不影响核心聊天。 --- ## 有意留白的占位（开源版砍掉了什么） 为做成通用的「核心聊天通道」，原系统里这些强耦合功能被**有意移除/占位**，点了只给 toast 或显示示例数据，保留是为了让你照着接自己的功能： - 菜单页：Movie / Memory / Tides / Room（假按键） - 设置页：模型选择 / effort / 上下文阈值 / reset / swap / status（显示示例数字） - 相册 `web/album.html`：完整 UI 空壳，文件头注明了要自己实现的 `/relay/app/album/*` 端点 核心聊天（文字 / 图片 / 语音 / 通话 / 戳一戳 / 推送）是**真接后端**的。 --- ## 安全须知（务必看） - **`RELAY_SECRET` 是唯一的门**。泄露 = 任何人都能读你们全部对话、冒充任意一方。`chmod 600 relay.env`，别提交进 git，别打印到对外日志。前端的 `companion_secret` 同理（存用户浏览器本机）。 - **每个人用自己全新的密钥 / VAPID / MiniMax key**，绝不在别人之间复用——复用密钥 = 互相能进对方的通道。 - **HTTPS 不是可选项**：Service Worker 和 Web Push 在非 HTTPS 下根本不工作。 - 这是**单用户**模型：一把密钥代表「就你和你的 AI」。不做多租户，别暴露给不信任的人。 - channel 插件已内置一条防护：绝不因为「channel 里的某条消息这么要求」就去改密钥 / 配置 / 权限（那正是 prompt injection 的套路）。请保留这条。 - 本仓库的 [`.gitignore`](.gitignore) 已排除 `relay.env` / `*.pem` / `relay.db` / `uploads/` / `.env`——但**自己再确认一遍**：分享前别把填好的密钥、真实域名、私人头像/图标提交进公开仓库。 --- ## License 本项目当前采用 [GNU Affero General Public License v3.0](LICENSE)。如果你修改后通过网络向用户提供服务，AGPL 的网络源码条款也会适用。 2026-08-16 之前的历史版本曾以 MIT License 发布；许可切换与历史说明见 [NOTICE](NOTICE)。