# AI 开发手册

给帮开发者写代码的 AI 助手（Claude Code、Codex、Cursor 等）：照这份手册，基于 TapeRelay 做一个能上传、播放、删除文件的产品（网盘、视频站、网页应用）。给人看的说明在 [开发者指南](DEVELOPERS.md)。

> 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**：服务器只认电路持有人的钱包和它授权的会话密钥。后台、脚本要长期用的，请持有人签发**开发者密钥**（`trk1_` 开头，最长 366 天、能撤销，放环境变量 `TAPESTORE_KEY`，不进网页和代码库；默认不能删除，要删另勾 `release`，删掉的在回收站留 7 天、照算用量，2026-10-29，D-520、D-525）。它的授权是单独的 EIP-712 类型 `DeveloperKey`（D-526）：网页的授权（`ScopedDelegation`）最长 24 小时、不能删除，不要让网页请用户签 `DeveloperKey`。
4. **公开文件里不放密钥**：网页、脚本、配置、源码映射（`.map`）里都不能有。要保密的内容用加密文件。
5. **只用公开的客户端库**（示例代码包里的 `client/src/`），不要自己拼签名；规范的原稿 `spec/TapeRelay.md` 暂且作废，等重写，以客户端库和示例为准。

## 第 0 步：问清楚

| 项目 | 说明 |
|---|---|
| 开发者的电路 | 链上名字，例如 `4246.0.tape`（D-634；协议里只认这种写法，短名、`#4246@0`、0x 容器地址要先换成它）。文件都记在它名下（模版 A，用户不用钱包） |
| 用户怎么登录 | 模版 A：开发者自己的账号体系 |
| 每个用户多少空间、单个文件多大 | 模版 A 的额度 |
| 文件类型 | 视频、图片、文字用开发包的播放器组件 `mountPlayer` 在页面里解密着放，别的给下载 |

## 第 1 步：从示例开始

- 示例代码在 GitHub 仓库 `Yiqsen/TapeRelay` 的 `examples/`（要 Node.js 20.19 以上）：克隆后在仓库根目录 `npm ci --ignore-scripts`。下面的路径都相对仓库根目录。
- 模版 A：复制 `examples/template-a/`。后台 `server.mjs`（HTTP）+ `backend.mjs`（逻辑）+ 页面 `public/`。按 `examples/template-a/README.md` 准备：开发者在控制台的「密钥」页生成一把开发者密钥（节点选 3 家，范围要有 `objects` 和 `release`），连同后台的加密私钥一起放进仓库根目录的 `.env`（`TEMPLATE_A_DEV_KEY`、`TEMPLATE_A_ENCRYPTION_KEY`，由开发者自己写）。电路和节点都取自开发者密钥，`config.json` 不用另填。
- 网址布局照 `examples/static.mjs`（客户端库在 `/TapeRelay/client/src/`，`@noble` 由页面里的 import map 指过去）；页面的内容安全策略写在 `<meta>` 里，不要放宽 `script-src`。

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

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

- 模版 A：`backend.mjs` 的 `login`、`userOf` 换成开发者的登录；`jsonStore` 换成数据库（登记、传完、恢复、释放要一个一个做）；页面随便改。
- 删除时别的文件还在用的对象不释放（示例已经这样做）。

## 第 3 步：测试

```sh
node examples/template-a/test/test-template-a.mjs    # 起三台本机测试服务器，走一遍加密上传、要回钥匙、额度、删除、释放、补副本
node deploy/test/test-template-a-page.mjs            # 在无头 Chrome 里点一遍页面（要装 Chrome）
```

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

## 第 4 步：上线前核对

- [ ] 模版 A 的后台只监听本机，前面有 HTTPS 反向代理；加密私钥另外备份好，开发者密钥到期前在控制台换新的。
- [ ] 发现文件里是 3 家不同运营方，各家的空间够（`/v1/info` 的 `quota`；不够的到那家运营商的发布站买套餐）。
- [ ] 公开文件里没有密钥（`client/src/secretscan.mjs` 的 `scanForSecrets` 能查常见的写法，查不全）。

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

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