# PROMPT

把提示词、参考图、分步文档和创作工具收进同一个可连接的知识库。人可以浏览瀑布流、搜索和编辑；AI 可以从同一篇 post 读取纯文本、图片与 API 说明，再调用 Studio 生成作品。

**PROMPT 是网站与项目品牌；`waterfall-wiki` 是知识库应用的内部名称。** 目录、包、CI、镜像和 Compose 服务使用内部名称，网站导航与页面标题使用 PROMPT。

线上入口：[PROMPT](http://8.211.154.134:18131/)。内容、媒体、API 与 Studio 共用登录入口。

## 从一篇 post 开始

每篇内容都有稳定的 `/explore/<id>` 地址。标题、标签、正文和封面可以修改，链接保持不变。数据库内容可以保留 24 位 public ID，内部仍使用 UUID；旧 `/p/<slug>`、`/skills/...` 等地址保留兼容跳转。

- **浏览**：首页按不同笔记的反向引用数优先排序。重复引用和自引用不重复计数，代码、图片与外站链接不冒充笔记引用。详情可以查看引用来源。
- **搜索**：标题、简介、正文、普通标签和系统标签共同匹配。支持多个关键词及双引号短语，先按相关性、再按引用数和时间排序；先筛选再分页。
- **标签**：普通标签使用 `#中国风`、`#贴纸` 等名称，可以创建、添加或移除。系统标签是固定列表，目前为“文档入口”和“参考图”，只能搜索并勾选，不能通过 `#` 创建。系统标签显示在图片角标，普通标签显示在文字区；分类页顶部按系统标签筛选。
- **编辑**：卡片与详情都能直接编辑标签；完整编辑器可以修改标题、简介、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 教程](content/studio-tools/layouts-api.md)。

其他试版工具：

- `/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+。

```sh
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](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 绑定](docs/dynamic-code-login.md) · [API](docs/api.md) · [数据模型](docs/data-model.md) · [项目结构与部署](docs/monorepo.md)。