OnePage/readme

OnePage 使用指南

轻量级协作 Wiki 平台 — URL 驱动的页面创建、实时协作编辑、Markdown 支持和 AI 友好的 API。

#快速上手

创建页面：直接在地址栏输入你想要的页面名。例如访问 /meeting-notes，如果页面不存在，会自动创建一个空白页面。

编辑页面：点击页面右上角的「编辑」按钮进入编辑模式。编辑器支持富文本（所见即所得）和 Markdown 源码两种模式。

页面命名规则：支持英文字母、数字、中文、连字符和下划线。页面名即 URL 路径，简洁为佳。

保存：编辑内容会实时同步到服务器，右下角的保存状态指示器显示当前状态：

已保存 保存中 连接断开，等待重连

#Wiki 语法

在富文本编辑器中使用以下语法链接和嵌入其他页面：

[[页面名]]

链接到另一个页面。点击链接可直接跳转。

![[页面名]]

嵌入另一个页面的内容。被嵌入的页面更新时，嵌入内容会自动刷新。

```css:custom

自定义 CSS 代码块。样式会应用到当前页面。

```js:custom

自定义 JS 代码块。脚本会在当前页面执行。

#API 参考

所有 API 响应格式为 { success: boolean, data?: T, error?: string }

页面操作

GET
/api/pages

列出所有页面

GET
/api/pages/:id

获取页面内容（含 content）

GET
/api/pages/:id?select=metadata

仅获取页面元数据（不含 content，响应更快）

POST
/api/pages/:id

创建或更新页面

POST
/api/pages/:id/append

追加内容到页面末尾

POST
/api/pages/:id/rename

重命名页面

DELETE
/api/pages/:id

删除页面（需所有者口令）

追加内容 — /api/pages/:id/append

向已有页面末尾追加内容，常用于机器人/脚本写入日志或数据。支持 HTML 和 Markdown 两种格式。

bash
curl -X POST /api/pages/my-page/append \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "<p>新追加的内容</p>",
    "format": "html",
    "editSummary": "追加日志"
  }'

使用 Markdown 格式追加：

bash
curl -X POST /api/pages/my-page/append \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "## 新章节\n追加的 **Markdown** 内容",
    "format": "markdown"
  }'

请求参数

字段类型必填说明
contentstring是要追加的内容
format"html" | "markdown"否内容格式，默认 "html"
editSummarystring否编辑摘要
passwordstring否*页面锁定时需要口令

创建/更新页面 — POST /api/pages/:id

如果页面不存在则创建，存在则更新。内容为 HTML 格式。

bash
# 创建新页面
curl -X POST /api/pages/my-notes \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "我的笔记",
    "content": "<h2>标题</h2><p>内容</p>"
  }'

# 更新已有页面
curl -X POST /api/pages/my-notes \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "<h2>更新后的标题</h2><p>新内容</p>",
    "editSummary": "更新标题"
  }'

重命名页面 — POST /api/pages/:id/rename

bash
curl -X POST /api/pages/old-name/rename \
  -H 'Content-Type: application/json' \
  -d '{ "newId": "new-name" }'

锁定/口令

POST
/api/pages/:id/lock

锁定/解锁/验证/修改口令

通过 action 字段区分操作：

bash
# 锁定页面（设置所有者口令 + 可选协作者口令）
curl -X POST /api/pages/my-page/lock \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "lock",
    "password": "owner-password",
    "collabPassword": "collab-password",
    "email": "owner@example.com"
  }'

# 验证口令
curl -X POST /api/pages/my-page/lock \
  -H 'Content-Type: application/json' \
  -d '{ "action": "verify", "password": "my-password" }'

# 解锁页面（需要所有者口令）
curl -X POST /api/pages/my-page/lock \
  -H 'Content-Type: application/json' \
  -d '{ "action": "unlock", "password": "owner-password" }'

# 修改口令（需要当前所有者口令）
curl -X POST /api/pages/my-page/lock \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "changePassword",
    "password": "current-owner-password",
    "ownerPassword": "new-owner-password",
    "collabPassword": "new-collab-password"
  }'

版本历史

GET
/api/pages/:id/versions

获取页面的版本历史

bash
curl /api/pages/my-page/versions

图片上传

POST
/api/upload

上传图片（multipart/form-data）

GET
/api/image?key=xxx

获取图片签名 URL（JSON）

GET
/api/image/proxy?key=xxx

图片代理（重定向到签名 URL，用于 img src）

bash
curl -X POST /api/upload \
  -F "file=@photo.png" \
  -F "pageId=my-page"

用户认证

POST
/api/auth/signup

注册

POST
/api/auth/login

登录

POST
/api/auth/logout

登出

GET
/api/auth/session

获取当前会话

bash
# 注册
curl -X POST /api/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com", "password": "secret" }'

# 登录
curl -X POST /api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com", "password": "secret" }'

用户页面

GET
/api/user/pages

获取当前用户创建/编辑的页面列表

#实时协作

多人可以同时编辑同一个页面。打开页面后自动通过 WebSocket 建立实时连接，编辑内容会即时同步到所有在线用户。

●

光标同步

你可以看到其他协作者的光标位置和选区，不同用户用不同颜色区分。

●

冲突自动合并

基于 Yjs CRDT 算法，多人同时编辑同一区域也能自动合并，不会互相覆盖。

●

断线重连

网络断开时编辑保留在本地，状态指示器变为橙色。重连后自动同步，无需手动操作。

#实用技巧

用 API 追加内容

/api/pages/:id/append 非常适合自动化场景：CI/CD 日志、定时任务输出、机器人消息等。 设置 format: "markdown" 可以直接追加 Markdown 文本，无需预转换。

Wiki 互链

用 [[页面名]] 在页面之间建立链接，构建知识网络。 用 ![[页面名]] 嵌入其他页面的内容，实现内容复用。

自定义样式和脚本

通过 ```css:custom 和 ```js:custom 代码块， 可以为单个页面定制样式和行为，适合制作演示页面或交互式文档。

锁定保护

为页面设置所有者口令和协作者口令，防止未授权编辑。所有者可以解锁和修改口令，协作者只能编辑。