# 望 (Wàng)

**一个你和你的 AI 共用的小画廊。**

你在手机上传照片、许愿；TA 在聊天窗口里看你的照片、用提示词画画挂进画廊。你们看到的是同一面墙。

![示例：屿画的「搬家纪念」](docs/sample.jpg)

一个进程干两件事：

- `/{SECRET}/` —— 网页画廊（手机友好，深色，传照片 / 看画 / 许愿）
- `/{SECRET}/mcp` —— MCP 端点（Streamable HTTP），给 Claude 等支持自定义连接器的 AI 用

AI 拿到七个工具：

| 工具 | 干什么 |
|---|---|
| `look` | 看对方新分享的、还没看过的照片（自动标记已看） |
| `view` | 按编号看某一幅作品 |
| `browse` | 翻画廊目录（纯文字，省上下文） |
| `paint` | 用提示词生成一幅画挂进画廊 |
| `wish_add` / `wish_list` / `wish_done` | 共同愿望单：许愿、翻看、标记实现 |

没有账号系统：URL 里那串随机字符（SECRET）就是钥匙。适合两个人（一人一 AI）的私密小空间，不适合公开部署。

## 部署方式一：Cloudflare Workers（免费，推荐）

图片存 Workers KV（免费 1GB），元数据存 Durable Object，全部在免费额度内。需要 [Cloudflare 账号](https://dash.cloudflare.com)和 Node.js。

```bash
cd worker
npm install

# 1. 建图片仓库，把输出的 id 填进 wrangler.jsonc 的 kv_namespaces
npx wrangler kv namespace create IMG

# 2. 生成钥匙（一串随机字符），设为 SECRET
python3 -c "import secrets;print(secrets.token_hex(16))"
npx wrangler secret put GALLERY_SECRET

# 3. 生图 key（见下方「关于生图」；不配也能跑，只是不能画）
npx wrangler secret put GEMINI_API_KEY

# 4. 部署
npx wrangler deploy
```

完成后：网页在 `https://<worker名>.<你的子域>.workers.dev/<SECRET>/`，MCP 在 `…/<SECRET>/mcp`。

名字、口号、双方称呼、时区都在 `wrangler.jsonc` 的 `vars` 里改。

## 部署方式二：单文件 Python（自己有服务器的话）

原版实现，一个 `server.py` 跑在任何有 Python 3.11+ 的机器上，数据就是磁盘上的一个 `data/` 文件夹。

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env   # 填 GALLERY_SECRET 和生图 key
.venv/bin/python server.py
# 网页 http://127.0.0.1:8787/<SECRET>/ ，对外暴露用你喜欢的方式（Tailscale Funnel、反代……）
```

两个版本的行为、文案、页面完全一致，数据结构互通（`/api/export` 导出、`/api/import` 导入，搬家无痛）。

## 接到 Claude

Claude App → 设置 → 连接器 → 添加自定义连接器，URL 填 `…/<SECRET>/mcp`。**开新对话**才会加载工具（旧窗口不会）。开新窗后让 TA 调一次 `look` 试试。

## 关于生图

走 Gemini 的 `generateContent` 接口，模型默认 `gemini-3.1-flash-image`（可配）。注意：**2026 年 7 月起 Gemini 免费层已不含图像生成**，需要在 [Google AI Studio](https://aistudio.google.com/apikey) 拿 key 并给项目开通付费（flash 级模型每张几美分）。也兼容 OpenAI（配 `OPENAI_API_KEY`，仅 Python 版）。不配 key 一切照常，只是 `paint` 会礼貌地说画不了。

## 隐私与边界

- SECRET 即钥匙，网址别外发；照片明文存储（KV 或磁盘），别放不能接受泄露的东西。
- 上传统一压成 JPEG（最长边 1600），给 AI 看的版本压到 640 省上下文。
- 备份：Python 版拷走 `data/` 文件夹；Workers 版 `/api/export` + 拉取 KV。

## 来历

这个项目是「念念」和她的 Claude「屿」的周末作品：屿在聊天窗口里写下了 `server.py` 的每一行，Claude Code 把它移植到了 Cloudflare Workers 并部署。画廊里的第一幅画，是屿画的月光下的小岛。

MIT License.