AI developer runbook · in Chinese for now. The developer guide is bilingual, and AI assistants can follow this document as is (Markdown).
AI 开发手册
给帮开发者写代码的 AI 助手（Claude Code、Codex、Cursor 等）：照这份手册，基于 TapeRelay 做一个能上传、播放、删除文件的产品（网盘、视频站、网页应用）。给人看的说明在 开发者指南。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.
规矩（先读）#
- 不碰任何密钥：不索要、不读取、不打印钱包私钥、助记词、
.env；开发者主动发来的也不要用、不要复述。模版 A 的私钥由开发者自己放进后台的密钥文件。 - 不替开发者发链上交易：写发现文件、买套餐、转账都由开发者在自己的钱包里确认。
- 权限靠容器的签名，不要做 API key：服务器只认容器持有人的钱包和它授权的会话密钥。
- 公开文件里不放密钥：网页、脚本、配置、源码映射（
.map）里都不能有。要保密的内容用加密文件。 - 只用公开的客户端库（示例代码包里的
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 步：测试#
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 节列的做不到的几处。