文档索引
raricy.com 的全部文档。分三层：guide/ 给玩家和内容创作者，bot/ 给站外机器人开发者，根下给开发与运维。
⚠️
guide/下的文件名是接口：站内 6 个页面（表里标 ★ 的）通过src/app/components/MarkdownGuide.tsx在请求时按文件名读盘渲染。 改名或移动会让页面静默变成一句「指南文档暂时无法加载。」且照样返回 200 —— 所以别改文件名，要移动就一起改MarkdownGuide.tsx的基准目录。 两道闸门盯着：tests/unit/guide-docs.test.ts（静态）与scripts/smoke.mjs§2b（线上查正文）。📖 全部 33 份在站内也有入口：
/docs（页脚那个「文档」链接）是索引页， 每份文档一页正文，读的就是本目录下的原文件 —— 与上面那 6 个 ★ 页面并存， 同一份文档因此有两个站内 URL（合并是一次独立的改动，眼下刻意没做）。 新增 / 改名 / 删除一份文档都要同步登记表src/lib/docs-catalog.ts： 漏登记 = 它在站上不出现、且不报任何错（守卫tests/unit/docs-catalog.test.ts双向对账，并盯着「表里的title与文档 H1 一致」）。正文里的相对链接照 GitHub 的 习惯写即可 —— 指向文档的会被改写成站内地址，指向源码的改写成仓库地址。
改文档时：互指怎么写
站内文档互指用反引号路径，不用 markdown 相对链接：`docs/architecture.md` §6.5。
相对链接在目录重排时会静默失效，反引号路径配 §号能同时定位到章节，也不怕搬文件 ——
本目录 33 份文档里只有一条真链接。改文档时照这个写，别自作主张加相对链接。
../指根，裸名指同目录。 从docs/下引根下的 README / CLAUDE 要写../README.md/../CLAUDE.md—— 本目录里真有一份 README， 裸名会撞车（指根还是指本目录，谁解析出来全看碰巧）。 ⚠️ 包括这一节自己的文字：讲规矩时也别把裸名写进反引号，否则连这段都会被守卫判违规。- 段号连写时归第一个路径：
`docs/architecture.md` §1/§6.1里 §1 与 §6.1 都算 architecture.md 的。链式写法只认/。 - 段号后面别写括号说明（
§8（角色阶梯））当标题用 —— 那是对那节的说明， 不是它的标题（§8 的真实标题是「关键约定」）。真要写标题就用「」，且得跟目标文档的 标题对得上。
tests/unit/docs-xref.test.ts 盯着上面几条：路径存在性、裸名歧义、段号与「」标题存在性。
它抓不到编号位移（往前面插一节，§4 还在、只是含义变了）—— 绿了不等于引用还准。
guide/ —— 玩家与内容创作者
| 文档 | 讲什么 |
|---|---|
guide/云剪贴板使用指南.md ★ |
Markdown 内容管理与复用 |
guide/图床使用指南.md ★ |
图片托管、直链与压缩 |
guide/音频床使用指南.md ★ |
音频托管（音乐与语音留言）、直链与 [@音频/ID] 引用、格式兼容性 |
guide/投票箱使用指南.md ★ |
创建投票、嵌入博客 |
guide/cattca-guide.md ★ |
Cattca 互动叙事入门（零基础） |
guide/cattca-syntax.md |
Cattca 脚本语法参考（命令逐条） |
guide/内容引用语法指南.md |
[@<内容ID>]、[@用户/用户名] 与 [@音频/<ID>] 在博客 / 评论 / 讨论里嵌入内容 |
guide/表情包使用指南.md |
[@合集/表情] 在评论 / 讨论里发表情；内置黄脸栏与站长自加素材（⚠️ 用户 与 音频 是保留合集名） |
guide/头像框使用指南.md |
头像框：怎么换、怎么用鱼干租一款、限时到期会怎样、站长怎么加一款新框与定价上架（出图规格与自查） |
guide/头像框出图规范.md |
给画师的出图规范（自包含，可整份转发）：画布与格式、8% 圆角几何、20px 判据、配色与主题、命名与交付、交付前自查 |
guide/收藏夹使用指南.md ★ |
收藏夹：私密 / 公开的区别、复制、分享、导入导出 |
guide/story-module.md |
故事模块：文件结构 / 合集嵌套 / URL |
★ = 被站内页面渲染（/clipboard/guide · /image/guide · /audio/guide · /vote/guide · /favorite/guide · /tool/cattca-guide）
开发与运维
| 文档 | 讲什么 |
|---|---|
architecture.md |
进程拓扑 / 路由 / 子系统 / 数据流 / 风险 |
deploy.md |
从零到上线：环境、.env、数据库、systemd、nginx、TLS、备份、排障 |
cli.md |
运维 CLI：交互式向导 / 命令式用法；角色、用户、内容检索与恢复、鱼干、头像框、邀请码、审计、申诉 |
oauth.md |
raricy 作为 OAuth 2.0 IdP 的完整协议与集成 |
frontend-styles.md |
SCSS 目录 / 设计令牌 / 组件约定 / 响应式 |
instance-restore.md |
从 instance.zip 还原数据目录与数据库（灾备） |
legacy-constraints.md |
历史遗留约束：哪些不能删、为什么（含「不是框架痕迹」的辨析）；再清理这类注释的口径与待决事项 |
bot/ —— 站外机器人开发者
十三份都是自包含的：站外读者不用读本站源码就能对接。也因此它们复述了限频数值
与错误码 —— 改 src/lib/rate-limit.ts 的 RULES 或接口口径时必须同步（见
../CLAUDE.md「限频」节），否则就是下一次 drift。
| 文档 | 讲什么 |
|---|---|
bot/chat-bot.md |
讨论机器人接入：接口契约 / SSE / 消息与表情 / 正在输入、已读与报到 / 限频 |
bot/comment-bot.md |
评论区机器人接入：接口契约 / 轮询 / 限频 |
bot/blog-bot.md |
博客发文机器人接入：取栏目（GET /api/categories）/ 发文与改文 / 对外可见性三档（默认仅站内，改文时不传 = 不改档）/ 每日 20 篇 / 未知字段直接 400 |
bot/vote-bot.md |
投票机器人接入：建 / 投 / 读结果；锁定与删除（创建者自己收场）/ 限频 |
bot/checkin-bot.md |
签到机器人接入：两步（签到 → 翻牌定命）/ 每人每天一次 / 跨 UTC+8 午夜的作废窗口 |
bot/like-feed-bot.md |
点赞与投喂：文章与评论点赞（切换式）/ 投喂鱼干（作者 80%、单篇累计上限 5）/ 名单 / 删自己的评论 |
bot/image-bot.md |
图床机器人接入：multipart 上传 / 部分成功的响应形状 / 配额与直链 / [@10位ID] 引用 |
bot/audio-bot.md |
音频床机器人接入：multipart 上传（一次一个）/ 内容嗅探与格式别名 / 独立配额 / Range 直链 / [@音频/ID] 引用 |
bot/clipboard-bot.md |
云剪贴板机器人接入：建 / 改 / 删 / [@8位ID] 引用；非 core 读者看不到的坑 |
bot/account-bot.md |
账号与通知：资料与开关 / 专注模式 / 通知（含批量与 SSE）/ 公开主页 / 禁言历史 / 改密与邀请码提权 |
bot/fish-bot.md |
鱼干机器人接入：只读凭据（推荐）与无状态转账 / 余额 / 流水 / 限频与重试纪律；§9 收银台；§10 收款回调（验签 + 去重） |
bot/fish-bank-example.md |
一个最小的鱼干银行（可运行的参考实现）：建号 / 建凭据 / 登记回调 / 收款 / 验签 / 提现 / 对账，整段可复制粘贴；含四条最容易亏钱的纪律 |
bot/favorite-bot.md |
收藏夹：按 6 位 ID 读公开收藏夹（按 IP 限频）；§9 站内写入（建 / 改名 / 条目 / 复制 / 导入导出，所有者限定） |
相关
../CLAUDE.md—— 给 Claude Code 的项目约定（约束与反直觉决策）../README.md—— 快速开始、命令一览、部署要点