浏览：首页按不同笔记的反向引用数优先排序。重复引用和自引用不重复计数，代码、图片与外站链接不冒充笔记引用。详情可以查看引用来源。
搜索：标题、简介、正文、普通标签和系统标签共同匹配。支持多个关键词及双引号短语，先按相关性、再按引用数和时间排序；先筛选再分页。
标签：普通标签使用 #中国风、#贴纸 等名称，可以创建、添加或移除。系统标签是固定列表，目前为“文档入口”和“参考图”，只能搜索并勾选，不能通过 # 创建。系统标签显示在图片角标，普通标签显示在文字区；分类页顶部按系统标签筛选。
编辑：卡片与详情都能直接编辑标签；完整编辑器可以修改标题、简介、Markdown。保存使用 revision 检测并发冲突，避免旧窗口覆盖新修改。
素材：原件和加工结果都是普通资产，可被多篇 post 引用。文档封面与实际参考素材分开，子文档可以有自己的封面，同时保留原参考图。

给 AI 的入口

在同一个 post 地址加 ?agent_mode=True 可以读取纯文本正文和媒体链接。业务 API 的相同参数会先返回接口说明；已有查询参数时使用 &agent_mode=True。这些入口同样需要登录或有效 Bearer JWT。

地址	用途
`/explore/<id>`	人看的 post；加 `?agent_mode=True` 读纯文本
`/api?agent_mode=True`	业务 API 目录
`/api/explore-feed`	统一搜索、系统/普通标签筛选与分页
`/api/notes/<id>`	GET 读取；PUT 编辑全文；PATCH 仅更新标签
`/api/tags`	GET 查看普通/系统标签；POST 创建或复用普通标签
`/api/upload`	上传媒体；`assetOnly=true` 独立保存，不创建 post
`/api/posts`	用正文和已有资产创建普通 post
`/api/media/<id>`	媒体原件与衍生文件，支持 Range
`/api/preview`	有尺寸上限的 WebP 预览，不接受任意远程 URL

标签 PATCH 请求为 { "tags": ["标签 UUID"], "revision": "GET 返回的 revision" }。它不会要求用户重输正文。Tag 对象的 kind 为 normal 或 system；系统标签还有稳定的 system_key。普通创建接口不允许提交 kind 或 system_key。

Wiki 中的教程是普通 post 与媒体数据，不需要为每份资料增加专用网页路由、JSON 文件端点或代码注册。

Studio：从教程进入工具

Studio 负责交互式排版与无状态渲染，知识库负责教程、来源和入口。/studio 返回 PROMPT 首页；请从对应 post 打开具体工具。

27 套排版工具：/studio/layouts/ref-01 至 /studio/layouts/ref-27，每套对应原图 T/I/D 构件。目录与参数 API 为 /studio/api/layouts 和 /studio/api/layouts/<id>；POST 参数生成 SVG。效果通过 /api/studio/designs 存入 Wiki 现有 PostgreSQL，返回独立 ID，/studio/designs/<id> 可再次打开；PATCH 携带 revision 更新同一效果。Studio 不需要数据库连接或第二套数据库。详见 27 套排版 API 教程。

其他试版工具：

/studio/ideas/learning-skills-template：ref-17 同一母版的四张占位封面。
/studio/ideas/layout-selection：ref-01、ref-07、ref-26 三种构图；可修改文字与配色，核对构件边界。
/studio/api/export/<slug>：GET 读取方案或初始 SVG；POST 校验自定义参数并生成 SVG/JSON。详细说明读取该地址的 ?agent_mode=True。

渲染不自动保存作品，也不自动发布 post。需要保留的结果应下载后再通过普通媒体和 post API 发布。原图的 T/I/D 构件、画板比例与来源保留为可读取数据；文字替换和矢量重建的范围应在教程中明确。

仓库结构

路径	职责
`apps/waterfall-wiki`	Next.js Pages Router 知识库、搜索、标签、媒体 API、认证与后台视频加工
`apps/studio`	独立 Next.js 创作工具与封面渲染 API
`apps/python`	按需运行的 PNG/视频导出 CLI，没有常驻网络服务
`content`	本地作者资料、教程及排版源图，不打入 Wiki 运行镜像
`scripts`	CI 部署、运维、API 发布与作者工具
`docs`	数据模型、接口、认证与部署说明

两个 JavaScript 应用分别维护冻结的 pnpm 锁文件。根 Dockerfile 是 waterfall-wiki 的构建入口；应用目录的 Dockerfile 与它保持一致。

环境与检查

运行环境：Node.js 24、pnpm 11.25.0、PostgreSQL 17、S3 兼容对象存储；视频处理使用 FFmpeg，部分导出使用 Chromium。Python 工具需要 Python 3.12+。

pnpm install
pnpm --dir apps/waterfall-wiki typecheck
pnpm --dir apps/waterfall-wiki test
pnpm --dir apps/studio typecheck
bash -n scripts/deploy.sh scripts/integration.sh scripts/deploy-studio.sh

完整集成测试只针对显式隔离的数据库、对象存储和生产容器运行，覆盖存储、视频加工、编辑冲突、真实搜索与引用、标签规则和登录保护。不要把生产存储配置拿来运行集成测试。

本项目以指定服务器为唯一网页运行与验收入口：先推送，再等待 ces-control CI/CD，最后直接检查服务器。不要启动本地网页预览，不用 localhost 页面作为视觉验收或交付入口。具体约定见 AGENTS.md。

部署与持久化

Web 应用由 waterfall-wiki.yml 统一发布，两个应用的路径都能触发它：先检查并构建 Studio，再完成 Wiki 的类型检查、单元测试、生产构建、冒烟及隔离 PostgreSQL/S3 集成测试并部署 Wiki，随后部署 Studio，最后在指定服务器验收。顺序在同一个 ces-control 作业内保证，避免独立作业互相等待。PR 检查也运行隔离集成测试，但不部署。Python 检查仍由 python.yml 承担；文档与作者数据本身不触发应用部署。

服务	入口/端口
`waterfall-wiki`	公网 `18131`，也是 Studio 的统一入口
PostgreSQL	`127.0.0.1:18132`
对象存储	`127.0.0.1:18133`
Studio	`127.0.0.1:18134`；编辑器公网入口为 `/graphic`、`/infinite_canvas`，资源和 API 保留 `/studio` 代理
Python	无网络端口，按需运行

生产 Compose 项目仍为 prompt，部署根目录仍为 /opt/prompt。既有 prompt_postgres_data、prompt_objects、prompt_auth_data 卷与数据库身份保留；应用更名不会重新创建一套空存储。Compose 应用服务改为 waterfall-wiki 和 waterfall-wiki-worker，镜像参数为 WATERFALL_WIKI_IMAGE / WATERFALL_WIKI_TEST_IMAGE。

部署在停止写入后备份数据库，再运行迁移和启动新版。失败时恢复兼容旧镜像的备份并回滚服务。生产不执行 down -v，也不清空对象文件。早期合集验证会遍历分页，不假定旧文章一定在第一页。

登录与自动化

共享验证器的 6 位 TOTP 动态码登录，JWT 保存在 HttpOnly Cookie 中；这属于单因素动态码登录，不是 2FA。密钥保存在服务器认证卷，不进入 Git、镜像或 HTTP 二维码接口。

服务器管理员在交互式 SSH 终端运行 sudo /opt/prompt/auth qr 绑定验证器。不要把二维码、动态密钥或 JWT 粘贴到聊天、日志和仓库。服务端自动化可使用 node auth-cli.cjs run <脚本>，在进程内为本机 API 请求附加短期凭据，不输出令牌。

更多说明：登录与 SSH 绑定 · API · 数据模型 · 项目结构与部署。

README.md Unescape Escape

PROMPT

从一篇 post 开始