# AI 开发手册

给帮开发者写代码的 AI 助手（Claude Code、Codex、Cursor 等）：照这份手册，基于 TapeRelay 做一个能上传、播放、删除文件的产品（网盘、视频站、网页应用）。给人看的说明在 [开发者指南](DEVELOPERS.md)。2026-10-22（UTC+8）编写（D-340）；2026-10-23 按 D-354 改成从示例代码包开始。

> For AI agents: this runbook is in Chinese. Follow it step by step, keep the rules below, and report back to the developer in the language they used when giving you the task.

## 规矩（先读）

1. **不碰任何密钥**：不索要、不读取、不打印钱包私钥、助记词、`.env`；开发者主动发来的也不要用、不要复述。模版 A 的私钥由开发者自己放进后台的密钥文件。
2. **不替开发者发链上交易**：写发现文件、买套餐、转账都由开发者在自己的钱包里确认。
3. **权限靠容器的签名，不要做 API key**：服务器只认容器持有人的钱包和它授权的会话密钥。
4. **公开文件里不放密钥**：网页、脚本、配置、源码映射（`.map`）里都不能有。要保密的内容用加密文件。
5. **只用公开的客户端库**（示例代码包里的 `client/src/`），不要自己拼签名；规范是 `spec/SPEC.md`。

## 第 0 步：问清楚

| 项目 | 说明 |
|---|---|
| 文件记在谁的容器名下 | 开发者的（模版 A：用户不用钱包）还是用户自己的（模版 B：用户用钱包，开发者没有后台） |
| 开发者的容器地址 | `eip155:56:0x…`；模版 B 里当「应用」，只用于显示 |
| 用户怎么登录 | 模版 A：开发者自己的账号体系 |
| 每个用户多少空间、单个文件多大 | 模版 A 的额度 |
| 文件类型 | 只有图片（SVG 除外）、音频、视频、纯文本能在网页里直接放（按文件读取的网址），别的只能下载 |

## 第 1 步：从示例开始

- 下载示例代码（要 Node.js 20.19 以上）：`curl -fsSL https://taperelay.hivehubs.app/download/examples | tar -xz && cd taperelay-examples/TapeRelay && npm ci --ignore-scripts`。下面的路径都相对 `taperelay-examples/TapeRelay/`。
- 模版 A：复制 `examples/template-a/`。后台 `server.mjs`（HTTP）+ `backend.mjs`（逻辑）+ 页面 `public/`。按 `examples/template-a/README.md` 准备：开发者另开**专用钱包**当容器持有人，私钥放进 `TapeRelay/` 目录里的 `.env`（`TEMPLATE_A_WALLET_KEY`，由开发者自己写），`config.json` 写容器地址和发现文件里的 3 台服务器。
- 模版 B：复制 `examples/template-b/`。逻辑 `public/site.mjs`，界面 `public/main.mjs`，`public/site-config.json` 写应用地址和名字。`node examples/template-b/serve.mjs --out` 导出静态网站。
- 网址布局照 `examples/static.mjs`（客户端库在 `/TapeRelay/client/src/`，`@noble` 由页面里的 import map 指过去）；页面的内容安全策略写在 `<meta>` 里，不要放宽 `script-src`。

## 第 2 步：改成开发者的产品

只改这些地方，协议相关的部分（签名、上传、核对）照示例：

- 模版 A：`backend.mjs` 的 `login`、`userOf` 换成开发者的登录；`jsonStore` 换成数据库（登记、传完、恢复、释放要一个一个做）；页面随便改。
- 模版 B：`main.mjs` 的界面随便改；`SCOPES` 只要用得到的范围（`objects` 上传和列出，`pointers` 更新列表；别加 `send`、`inbox`）。
- 两种都要：给用户看按文件读取的网址时写明 `FILE_URL_NOTE`（浏览器不核对）；删除时别的文件还在用的对象不释放（示例已经这样做）。

## 第 3 步：测试

```sh
node examples/template-a/test/test-template-a.mjs    # 起三台本机测试服务器，走一遍上传、额度、删除、释放、补副本
node examples/template-b/test/test-template-b.mjs    # 起四台本机测试服务器，假链、假钱包，走一遍挑 3 家、授权、上传、删除、换服务器
```

全部通过（退出码 0）再交给开发者。测试只连本机、不读 `.env`。改了逻辑就照这两个文件的写法加测试。

## 第 4 步：上线前核对

- [ ] 模版 A 的后台只监听本机，前面有 HTTPS 反向代理；专用钱包只当这一个容器的持有人。
- [ ] 模版 B 的网站在 HTTPS 下（钱包要求）。
- [ ] 发现文件里是 3 家不同运营方，各家的空间够（`/v1/info` 的 `quota`；不够的在官方前端买）。
- [ ] 公开文件里没有密钥（`client/src/secretscan.mjs` 的 `scanForSecrets` 能查常见的写法，查不全）。

## 第 5 步：向开发者汇报

写清楚：用的哪个模版、改了哪些文件、测试结果（通过几项）、上线前还要开发者自己做的事（放私钥、写发现文件、买空间、配 HTTPS），以及[开发者指南第 7 节](DEVELOPERS.md#7-做不到的)列的做不到的几处。