WaiNao.AI

主题

文档操作 ​

文档运行、内容读写、协同感知、协作状态管理和复制等操作。

源码: apps/backend/src/routes/documents.ts、apps/backend/src/routes/document-edit.ts、apps/backend/src/routes/document-awareness.ts

GET /documents/:documentId/content ​

获取文档的 JSON 内容和内容哈希（content_hash）。哈希用于后续编辑时的乐观并发控制。

认证方式 ​

JWT Token / API Key / Agent Token（combinedAuth），或持有 documents:read Scope 的 OAuth access token；OAuth 请求仍需通过文档所在 Project 的读权限校验。

请求参数 ​

Path 参数 ​

参数类型必填说明
documentIdstring是文档 UUID

Query 参数 ​

参数类型必填说明
format"markdown-ir"否返回 Markdown IR 文本而不是 ProseMirror JSON
keep_comments"1" | "true"否仅 format=markdown-ir 时有效；保留 // 注释行。Agent Token 会忽略该参数

响应格式 ​

状态码: 200

json
{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "codeBlock",
        "attrs": { "id": "block-uuid", "name": "代码块" },
        "content": [{ "type": "text", "text": "console.log('hello')" }]
      }
    ]
  },
  "content_hash": "a1b2c3d4",
  "content_sync_seq": 42,
  "title": "文档标题",
  "updated_at": "2026-03-12T10:00:00.000Z"
}
字段类型说明
contentProsekitDocumentProseMirror 格式的文档内容
content_hashstringFNV-1a 哈希（8 字符 hex），用作 base_version
content_sync_seqnumberflow/skill checkpoint 的内部单调序号；不是用户版本号
titlestring | null文档标题
updated_atstring最后更新时间

错误码 ​

状态码说明
404文档不存在或无权访问

POST /documents/:documentId/smart-edit ​

推荐：统一的 flow/skill Yjs 编辑入口。content 与 commands 都转换为 Yjs transaction，经过显式协作同步屏障和数据库 CAS checkpoint；不再按 content_source 切换 REST/协作权威。

支持 doc_type='flow' 与 doc_type='skill' 文档（其他类型返回 400 并说明支持范围）。 content_format=markdown-ir 按 doc_type 分支：flow 校验 title/description/inputsOrTrigger 骨架； skill 归一并校验 title/description/allowTools 骨架（与编辑器 schema、Native Write 工具同语义）。

源码: apps/backend/src/routes/document-smart-edit.ts

链接地址安全：写入的内容（json、markdown-ir、commands 的 write / insert / replace，以及创建文档）里，协议不是 http(s)、mailto、tel、doc 的链接（如 javascript:、data:）会被去掉链接、只保留文字，请求本身照常成功；读回时看到的就是清理后的内容。无协议的相对地址保留。

认证方式 ​

JWT Token / Agent Token（combinedAuth）

请求体 ​

json
{
  "mode": "content",
  "content_format": "markdown-ir",
  "content": "# 标题\n\n> 描述\n\n...",
  "base_version": "a1b2c3d4"
}
字段类型必填说明
mode"content" | "commands"是编辑模式
contentstring | objectmode=content 时必填文档内容
content_format"json" | "markdown-ir"否内容格式（默认 json）；markdown-ir 仅支持 flow/skill 文档
commandsarraymode=commands 时必填编辑命令数组
base_versionstringmode=content 时必填全量替换必须以当前 content_hash 为基线；commands 可选，提供时同样执行基线校验

Markdown IR 中以 // 开头的正文行会保存为用户注释，执行时不会进入 AI prompt。 如果 Agent Token 编辑的目标文档已包含注释，mode: "content" 全量替换会返回 409 comment_preservation_required，需要改用 commands 模式避免删除用户注释。

Markdown IR 的变量引用使用 @{blockName.path}。Block name 是公开引用名，全文档内必须唯一，也不能与另一 Block 的 id 相同。服务端按完整名称的字面边界恢复内部 mention:<blockId>，保留完整字段路径，因此前向引用可绑定，引用统计、API schema 与发布校验使用稳定 Block id。

内部 ID 不能作为正文引用的名称别名。例如 Input id=input_x, name=message 应写 @{message}，JSON mention 保存 id=mention:input_x, value=@message。已有绑定的显示名称必须指向同一块；名称不一致时不会静默改绑。含中文、空格、点号、>、前导 @ 与正则特殊字符的名字按完整字面名处理，无绑定表达式若有多个名称/路径解释则拒绝。

活动的裸内部 ID、未知名称、悬空或冲突绑定在写入前被拒绝。删除目标产生的 variable-invalid 可保留、保存和撤销恢复，运行仅保留字面文本。历史异常文档仍可读取修正；读取/checkpoint 不会为修复引用而静默改写已有 Yjs 状态。ValueSource 数组、Structure/Output 绑定和 commands 的 blockId 仍是合法内部 ID 协议。

引用校验失败返回 400，不重试同一份错误内容：Markdown IR 解析路径使用 error: "workflow_reference_invalid"；JSON/Yjs 写入候选使用 error: "validation_error"。两者的 details 都是引用诊断数组，包含 code、reference、path，适用时带 blockId、nearBlockId。诊断 code 为 internal-id-reference、unknown-reference、ambiguous-reference、missing-bound-block、binding-name-mismatch 或 invalid-reference。这些校验拒绝不属于协作存储暂时故障，也不返回可重试的 503。

文档引用（编辑器 # 引用）在 Markdown IR 中表示为 [label](doc:documentId)。读写两侧均按此映射还原为 doc-ref mention（label 原样保留，空 documentId 回退普通链接）；执行器 Edit 工具的整块替换、skill 导入同样走该还原。历史数据恢复边界：仅保留完整 doc:<id> 的链接在再次经过 Markdown 序列化/解析并写回后恢复为引用；正常打开文档（Yjs/JSON 路径）不触发 Markdown 解析，不会自动修复已退化的历史内容；已丢失 documentId 的引用（如退化为 @{...} 变量形态）不在可恢复范围。

写入语义 ​

  1. 服务端先要求所有持有该文档的活跃协作实例把内存 Y.Doc durable flush，并等待每个实例的明确 ACK
  2. 把 content/commands 应用到 canonical Yjs state，再以 content_sync_seq 做有限次 CAS merge
  3. 同一事务更新 yjs_state、JSON projection、content_hash 与 content_sync_seq
  4. 只有 durable checkpoint 已提交才返回 2xx；同步屏障或数据库暂时失败时返回可重试的 503，不会返回假成功
  5. 写入候选先校验 Block id/name 唯一性及活动引用绑定；冲突、歧义和非法引用不会进入持久化，旧文档只读路径不做引用修复

响应 200 ​

json
{
  "success": true,
  "mode": "yjs",
  "version": "new-hash",
  "content_hash": "new-hash",
  "content_sync_seq": 43
}

错误码 ​

状态码说明
400请求参数错误
409版本冲突；或 Agent 对含注释文档发起全量替换
403权限不足
404文档不存在
503collab_not_synchronized、CAS 重试耗尽或 checkpoint 暂时失败；响应含 retryable: true

DELETE /documents/:documentId ​

软删除文档。设置 deleted_at 时间戳，文档不再出现在列表中但数据保留。同时从项目文件树（filesFolder）中递归移除对应节点。

源码: apps/backend/src/routes/document-edit.ts

认证方式 ​

JWT Token / API Key / Agent Token（combinedAuth），需要文档写入权限。此删除端点不接受 OAuth access token。

请求参数 ​

Path 参数 ​

参数类型必填说明
documentIdstring是文档 UUID

响应 200 ​

json
{
  "success": true
}

错误码 ​

状态码说明
403无写入权限
404文档不存在或已删除（幂等：重复删除返回 404）
500删除操作失败

POST /documents/:documentId/edit ​

写入内容同样会去掉危险协议的链接（只保留文字），规则见上方 smart-edit 的「链接地址安全」说明。

命令式或全量编辑文档内容，支持乐观并发控制。

认证方式 ​

JWT Token / API Key / Agent Token（combinedAuth），或持有 documents:write Scope 的 OAuth access token；均需要文档所在 Project 的写入权限。

并发控制机制 ​

  1. 调用方先通过 GET /documents/:documentId/content 获取 content_hash
  2. 编辑时将此值作为 base_version 传入
  3. 服务端把 content/commands 应用为 Yjs transaction 并用 seq CAS 提交
  4. 若文档在此期间被修改，返回 409 Conflict + 最新 hash/seq；活跃协作不再要求进程内锁

请求参数 ​

Path 参数 ​

参数类型必填说明
documentIdstring是文档 UUID

Body 参数 ​

参数类型必填说明
base_versionstring是当前持有的 content_hash
mode"commands" | "content"是编辑模式
commandsCommand[]mode=commands 时必填命令列表
contentProsekitDocumentmode=content 时必填全量替换的文档内容
content_format"json" | "markdown-ir"否内容格式（默认 json）；markdown-ir 仅支持 flow/skill 文档，其他 doc_type 返回 415
titlestring否与正文 Yjs projection 在同一事务提交，最长 200 字符

编辑模式 ​

全量替换模式 (mode: "content") ​

直接替换整个文档内容：

json
{
  "base_version": "a1b2c3d4",
  "mode": "content",
  "content": {
    "type": "doc",
    "content": [...]
  }
}

Agent Token 对含 // 注释行的文档不能使用全量替换模式；后端会返回 409 comment_preservation_required，以避免注释在 Agent 看不见的情况下被覆盖删除。

命令式编辑模式 (mode: "commands") ​

通过命令序列精细操作文档中的 Block：

json
{
  "base_version": "a1b2c3d4",
  "mode": "commands",
  "commands": [
    { "op": "list" },
    { "op": "read", "blockId": "block-uuid" },
    { "op": "write", "blockId": "block-uuid", "content": { "type": "paragraph", "content": [...] } },
    { "op": "insert", "after": "block-uuid", "block": { "type": "codeBlock", "attrs": { "id": "new-uuid" }, "content": [...] } },
    { "op": "delete", "blockId": "block-uuid" },
    { "op": "replace", "blockId": "block-uuid", "block": { ... } },
    { "op": "move", "blockId": "block-uuid", "after": "target-uuid" },
    { "op": "str_replace", "blockId": "block-uuid", "old_str": "旧文本", "new_str": "新文本" }
  ]
}

支持的命令：

命令参数说明
list-列出所有顶层 Block 的 id、type、name、index
readblockId读取指定 Block 的完整内容
read_rangefrom, to读取两个 Block 之间（含）的所有 Block
writeblockId, content替换指定 Block 的 content（保留 type 和 attrs）
insertblock, after?在指定 Block 之后插入新 Block（after=null 则插入开头）
deleteblockId删除指定 Block
replaceblockId, block整体替换指定 Block（包括 type 和 attrs）
moveblockId, after?将 Block 移动到指定位置（after=null 则移到开头）
str_replaceblockId, old_str, new_str在 Block 内做唯一文本替换（匹配数不为 1 则报错）

响应格式 ​

成功 200：

json
{
  "success": true,
  "mode": "yjs",
  "version": "e5f6g7h8",
  "content_hash": "e5f6g7h8",
  "content_sync_seq": 43,
  "results": [
    { "op": "list", "success": true, "data": [...] },
    { "op": "write", "success": true }
  ]
}

版本冲突 409：

json
{
  "error": "version_conflict",
  "message": "文档已被修改，请重新获取最新内容",
  "current_version": "new-hash",
  "current_content": { "type": "doc", "content": [...] }
}

错误码 ​

状态码错误说明
400无效请求base_version 缺失、mode 无效、commands 为空、flow/skill 结构校验失败等
403无写入权限用户缺少 write 权限
404文档不存在或无权访问文档不存在或用户无权限
415格式不支持content_format=markdown-ir 仅支持 flow/skill 文档
409version_conflict文档在读取后已被修改
503collab_not_synchronized / checkpoint 失败活跃实例未完成 durable flush、CAS 重试耗尽或数据库暂时不可用；可按 retryable 重试

GET /documents/:documentId/awareness ​

获取文档的在线协作者信息，包括用户身份、光标位置和所在 Block。

认证方式 ​

JWT Token / API Key / Agent Token（combinedAuth）

请求参数 ​

Path 参数 ​

参数类型必填说明
documentIdstring是文档 UUID

响应格式 ​

状态码: 200

json
{
  "collaborators": [
    {
      "clientId": 1234,
      "userId": "user-uuid",
      "name": "张三",
      "color": "#ff6b6b",
      "cursor": { "anchor": 42, "head": 42 },
      "selection": {
        "blockId": "block-uuid",
        "blockType": "codeBlock",
        "text": null
      }
    }
  ],
  "active_connections": 1,
  "scope": "local"
}
字段类型说明
collaboratorsarray在线协作者列表
collaborators[].clientIdnumberYjs 客户端 ID
collaborators[].userIdstring | null用户 ID
collaborators[].namestring | null用户名
collaborators[].colorstring | null光标颜色
collaborators[].cursorobject | nullProseMirror 光标位置
collaborators[].selectionobject | null光标所在的 Block 信息
collaborators[].selection.blockIdstringBlock ID
collaborators[].selection.blockTypestringBlock 类型
collaborators[].selection.textstring | undefined选区文本（有选区时）
active_connectionsnumber活跃连接数
scopestring固定为 "local"（仅当前进程）

scope 说明：当前仅覆盖本进程的协同连接。多实例部署时，协作连接可能分布在不同实例上。

错误码 ​

状态码说明
404文档不存在或无权访问

POST /documents/:documentId/run ​

运行文档（调试模式）。支持三种响应模式：SSE 流式、NDJSON 流式、JSON 一次性。

认证方式 ​

JWT Token（仅支持 JWT，combinedAuth）

请求参数 ​

Path 参数 ​

参数类型必填说明
documentIdstring是文档 UUID

Body 参数 ​

json
{
  "inputs": { "inputName": "值" },
  "stream": true,
  "format": "sse",
  "timeout": 60
}
参数类型默认值说明
inputsobject{}Input Block 的输入值（key 为 Input Block 名称）
streambooleantrue是否使用流式响应
format"sse" | "ndjson""sse"流式响应格式（仅 stream=true 时生效）
timeoutnumber-超时时间（秒），不超过管理后台配置的最大值

允许空 body（使用默认值）。

运行前服务端会先完成一次 durable workflow checkpoint，并只执行该 checkpoint 返回的 canonical snapshot。请求体中的额外 JSON content 字段不会覆盖或绕过数据库内容。无正文变化的 checkpoint 仍可能推进 content_sync_seq 与 updated_at；客户端不得仅凭时间戳显示远程更新，应以 authoritative content_hash 判定正文是否变化，同时比较事件携带的 title/description/deleted_at，避免把正文不变但元数据改变的 checkpoint 静默吞掉。

取得 checkpoint 后先校验活动引用；无效时在输入校验、计费、受理和打开流之前返回 JSON 400 { error: "workflow_reference_invalid", message, details }。details 为引用诊断数组，定位需要修正的文档内容；SSE、NDJSON 与一次性 JSON 请求均采用该响应。

响应格式 ​

SSE 流式响应（默认） ​

Content-Type: text/event-stream

事件类型：

事件数据字段说明
run_startrunId, documentId运行开始
block_startblockId, blockType, blockNameBlock 开始执行
block_chunkblockId, deltaBlock 输出片段（流式输出）
block_completeblockId, outputBlock 执行完成
block_endblockIdBlock 生命周期结束
block_errorblockId, errorBlock 执行出错
tool_startblockId, toolCallId, toolName工具调用开始
tool_resultblockId, toolCallId, result工具调用结果
run_errorrunId, error, message运行失败或超时；失败时唯一的运行终态
run_completerunId, globalCtx, sessions, completedBlocks, duration, timedOut运行成功时唯一的运行终态

run_error 与 run_complete 互斥。运行失败或超时时不会再发送 run_complete；客户端收到任一事件后都应结束等待并关闭本次事件流。

NDJSON 流式响应 ​

Content-Type: application/x-ndjson

每行一个 JSON 对象，包含 type 字段标识事件类型，字段与 SSE 事件一致。

JSON 一次性响应（stream: false） ​

状态码: 200

json
{
  "runId": "uuid",
  "documentId": "uuid",
  "globalCtx": [...],
  "sessions": [
    {
      "blockId": "uuid",
      "blockType": "code",
      "blockName": "代码块",
      "status": "completed",
      "output": "输出内容"
    }
  ],
  "duration": 1234,
  "timedOut": false
}

错误码 ​

状态码错误说明
400输入参数验证失败inputs 不符合 Input Block 的 schema 定义
400workflow_reference_invalidcheckpoint 中的活动引用无效；响应带 message/details，在受理、计费和打开流之前拒绝
400no_team_associated文档没有关联团队
402insufficient_credits积分余额不足
403调试模式仅支持 JWT 认证使用了非 JWT 认证
403无运行权限，请联系项目管理员授权用户缺少 execute 权限
404文档不存在或无权访问文档不存在或用户无权限
409checkpoint 非重试型错误canonical state 不一致或内容校验失败
503collab_not_synchronized / checkpoint 暂时失败活跃实例未完成 durable flush 或数据库暂时不可用，可按 retryable 重试
500balance_check_failed余额查询异常

POST /documents/:projectId/duplicate ​

复制文件或文件夹节点（包含其下所有文档）。

认证方式 ​

JWT Token（仅支持 JWT，combinedAuth）

请求参数 ​

Path 参数 ​

参数类型必填说明
projectIdstring是项目 UUID

Body 参数 ​

json
{
  "nodeKey": "document-uuid-or-folder-key",
  "nodeType": "file"
}
参数类型必填说明
nodeKeystring是目标节点的 key（文档 ID 或文件夹 key）
nodeType"file" | "folder"是节点类型

响应格式 ​

状态码: 200

json
{
  "success": true,
  "node": {
    "key": "new-uuid",
    "label": "[Copy]原文档名",
    "type": "file",
    "docType": "workflow",
    "isLeaf": true
  }
}
字段类型说明
successboolean是否成功
nodeFolderNode新创建的节点信息

复制命名规则：

  • "文档A" -> "[Copy]文档A"
  • "[Copy]文档A" -> "[Copy-2]文档A"

错误码 ​

状态码错误说明
400nodeKey and nodeType are required缺少必填参数
400nodeType must be "file" or "folder"nodeType 不是合法枚举值
400Node type mismatch: ...nodeType 与目标节点实际类型不一致
400Cannot duplicate an empty folder: no documents to copy目标是空文件夹，无可复制文档
403仅支持 JWT 认证使用了非 JWT 认证
403Permission denied非项目所有者且非团队成员
404Project not found项目不存在
404Node not found in filesFolder节点在文件树中不存在
409Some documents are missing or deleted部分待复制文档已被删除
500Failed to update project config复制事务失败（文档插入或文件树更新任一步失败）
500Internal server error内部错误

补充端点 ​

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

POST /documents ​

创建/编辑文档（document-edit root）

认证：JWT Bearer Token、API Key、Agent Token，或持有 documents:write Scope 的 OAuth access token；OAuth 请求还需通过目标 Project 的写权限校验。 请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/runs/:runId/resume ​

恢复运行（Ask 打断后继续）

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID
runId运行记录 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/ui-annotations ​

保存文档 UI 预览中的标注信息，供前端编辑器和审阅流程复用。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/ui-pending-changes ​

提交 UI 预览待应用变更，等待用户确认后写入文档。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/ui-preview-state ​

保存 UI 预览状态，包括当前 screen、视口或渲染状态。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/ui-save ​

保存 UI 编辑器产物并写回对应文档。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

PATCH /documents/:documentId/ui-thumbnail ​

更新文档的 UI 缩略图，用于列表、发布和预览页面展示。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /documents/:documentId/versions ​

列出文档历史版本，用于回溯、对比或选择回滚目标。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /documents/:documentId/version-context ​

解析通用 Document Version G1 的只读上下文。该端点由 DOCUMENT_VERSIONING_READ_ENABLED 控制，默认关闭；关闭时返回 404 document_versioning_disabled。G1 不开放 commit、branch 或 publish 写动作。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。调用者必须拥有 Document 读权限。

Query 参数

参数类型必填说明
branchUUID否稳定 branch ID；不传则解析 active default branch
versionmajor.minor.patch否精确 revision；不传则解析 branch latest

响应 200

json
{
  "document_id": "uuid",
  "branch": {
    "id": "uuid",
    "name": "main",
    "status": "active",
    "head_revision_id": "uuid"
  },
  "mode": "latest",
  "latest_snapshot": {
    "id": "uuid",
    "content_sha256": "64-char lowercase hex",
    "content_schema": "prosemirror-json",
    "content_schema_version": 1
  },
  "head_revision": { "id": "uuid", "content_snapshot_id": "uuid" },
  "revision": { "id": "uuid", "content_snapshot_id": "uuid" },
  "display_version": "1.2.3",
  "dirty": false,
  "readonly": true,
  "can_commit": false,
  "can_branch": false,
  "can_publish": false
}

branch 或 version 非法返回 400 invalid_version_selector；branch/revision 不存在返回 404，且不会回退 latest；无权限返回 403。

GET /documents/:documentId/versions/:versionId ​

读取指定文档版本详情。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID
versionId版本 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:documentId/versions/:versionId/rollback ​

将文档内容回滚到指定历史版本。

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID
versionId版本 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

文档修订（Revisions） ​

不可变修订（immutable revision）是文档版本化的正式机制：冻结当前草稿为不可变修订、按修订恢复、 按修订发布。端点均位于 /documents/:documentId 下，并要求对所属项目有相应读/写权限。 修订列表与详情还支持 OAuth documents:read，创建修订还支持 OAuth releases:publish；恢复、按修订部署、差异和修订部署列表等其他端点仍使用 combinedAuth（JWT / API Key / Agent Token），不因持有这些 OAuth Scope 而开放。 读接口由 DOCUMENT_VERSIONING_READ_ENABLED 控制，未启用时返回 404 document_versioning_disabled；写接口由独立的 DOCUMENT_VERSIONING_WRITE_ENABLED 控制，未启用时返回 404 document_versioning_write_disabled。两个开关默认均关闭，具体部署是否启用应以该环境配置与接口返回为准。

源码：apps/backend/src/routes/document-versions.ts

GET /documents/:documentId/revisions ​

分页列出文档修订。按创建时间倒序返回，支持游标翻页。

查询参数

参数类型说明
branchUUID（可选）按分支过滤；当前仅支持默认分支（传其它分支返回 g2_default_branch_only 类错误）
cursorISO 时间（可选）游标（上一页最后一条的创建时间）
limitinteger（可选）每页数量，默认 20，必须 ≥1

响应 200：{ revisions: [...], next_cursor? }。

常见错误：400 invalid_branch_id / invalid_revision_cursor / invalid_revision_limit。

POST /documents/:documentId/revisions ​

冻结当前草稿为不可变修订（commit）。仅支持 flow / skill / ui 类型文档；写权限校验通过后， 服务端先强制把当前协作快照落库，再在默认分支上冻结修订。

认证支持 JWT / API Key / Agent Token，或持有 releases:publish Scope 的 OAuth access token；关闭版本化写功能时返回 404 document_versioning_write_disabled，不是授权失败。

请求体

json
{
  "summary": "本次修订说明（1-1000 字符，可为 null）",
  "expected_head_revision_id": "uuid 或 null（乐观并发，可选）",
  "expected_latest_snapshot_id": "uuid（可选）",
  "request_id": "uuid（可选，幂等键）"
}

幂等键也可用请求头 Idempotency-Key 传递；两处都传时必须一致。

响应：新建成功 201 { revision }；同 request_id 幂等重放 200 { revision }（revision.idempotentReplay 为 true）。 并发冲突（head/snapshot 不匹配）返回 409。

GET /documents/:documentId/revisions/:revisionId ​

修订详情与精确内容（含该修订冻结的完整快照引用）。

路径参数：documentId、revisionId（均为 UUID）。

常见错误：400 invalid_revision_id；修订不存在返回 404。

POST /documents/:documentId/revisions/:revisionId/restore ​

把历史修订内容恢复为新修订（不改写历史）。需要项目写权限。

请求体：{ "summary": "可选说明（1-1000 字符或 null）", "request_id": "uuid（可选）" }，幂等键规则同上。

响应：新建成功 201 { revision }，幂等重放 200。

POST /documents/:documentId/revisions/:revisionId/deploy ​

发布指定不可变修订。需要项目发布权限。visibility 取 public 或 private（默认 private）， 放在请求体 { "visibility": "private" }。

  • flow / skill 文档：创建常规部署，响应 201 { deployment }。
  • ui 文档：创建 UI 修订部署，响应 201 附加访问路径：
json
{
  "deployment": { "id": "..." },
  "page_path": "/ui-pages/<deploymentId>",
  "latest_path": "/ui-pages/d/<documentId>/latest"
}

常见错误：400 invalid_revision_id / invalid_visibility / unsupported_document_type、403 Permission denied、409 deployment_failed。

GET /documents/:documentId/diff ​

对比两个修订的内容差异。

查询参数：from、to（均为必填修订 UUID）。

响应 200：差异结构（按块/组件组织的变更列表）。

常见错误：400 from_and_to_revision_ids_required；任一修订不存在返回 404。

GET /documents/:documentId/revision-deployments ​

列出该文档按不可变修订发布的部署记录（最多 100 条，按版本号倒序）。

响应 200

json
{
  "deployments": [
    {
      "id": "uuid",
      "revision_id": "uuid",
      "version_major": 1,
      "version_minor": 2,
      "version_patch": 0,
      "visibility": "public",
      "created_at": "2026-08-29T00:00:00Z"
    }
  ]
}

常见错误：500 deployment_query_failed（数据库查询失败）。

POST /documents/:documentId/ui-deploy ​

发布 UI Document V2：从 content.source.html inline authority 生成不可变快照（含资产清单物化），原子分配版本号（首次 1.0，之后 minor 递增）并挂公开稳定地址；同时在版本历史写入 source='deploy' 行。legacy 原件禁止新发布，但已有 deployment 继续可访问。权限：项目写权限

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID（必须为 UI 文档）

请求体

参数类型必填说明
expectedContentHashstring是最近一次保存返回的 content_hash，用于阻止发布未保存态

响应 201

json
{
  "deployment": { "id": "uuid", "version_major": 1, "version_minor": 2, "created_at": "..." },
  "version_number": 8,
  "page_path": "/ui-pages/<deploymentId>",
  "latest_path": "/ui-pages/d/<documentId>/latest"
}

常见错误：400 非 UI 文档、缺 expectedContentHash（EXPECTED_CONTENT_HASH_REQUIRED）或无可发布内容（EMPTY_UI_HTML），403 无写入权限，409 包括 legacy 原件只读（LEGACY_UI_READONLY）、存在未保存修改（UNSAVED_CHANGES）或内容与上一发布版本相同（CONTENT_UNCHANGED）。

GET /documents/:documentId/ui-deployments ​

UI 文档发布历史列表（按版本倒序），每条含版本号、时间与公开页路径。权限：项目读权限

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
documentId文档 ID（必须为 UI 文档）

响应：{ "deployments": [{ "id", "version_major", "version_minor", "created_at", "page_path" }] }

GET /ui-pages/:deploymentId ​

已发布 UI 页面（不可变快照），返回 text/html。权限：公开（无需认证）

非 UI 类型 / 非公开 / 不存在 / 已删除一律 404（fail-closed）。响应带 CSP（sandbox）与安全头；HTML 在输出前经服务端二次清洗。

GET /ui-pages/:deploymentId/assets/:fileId ​

已发布 UI 页面的资产代理，按该 deployment 快照内的资产清单授权——清单外的文件一律 404。资产不可变，长缓存。权限：公开（无需认证）

GET /ui-pages/d/:documentId/latest ​

302 跳转到该文档最新发布版本，适合「始终最新」的分享场景。无发布版本时 404。权限：公开（无需认证）

POST /documents/:id/collab/edit ​

协同编辑操作

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
id资源 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:id/collab/join ​

加入协同编辑

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
id资源 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /documents/:id/collab/leave ​

离开协同编辑

认证：JWT Bearer Token、API Key 或 Agent Token（combinedAuth）。 路径参数

参数说明
id资源 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

UI 源码与检查点 ​

以下接口使用用户会话认证，并校验调用方对文档所属项目的访问权限。

GET /documents/:documentId/source ​

读取 UI 文档当前源码、版本及相关元数据。

PUT /documents/:documentId/source ​

替换 UI 文档源码。请求体包含源码内容及可选的并发控制信息；版本冲突时拒绝覆盖。

POST /documents/:documentId/checkpoint ​

按文档类型分流：

  • flow/skill：请求体接受可选的 update（非空 base64 Yjs update，解码后最多 512 KiB）与可选 title（0–200 字符，空字符串用于清空标题），不接受 JSON content。无 update 时仍执行同步屏障与 durable checkpoint。响应包含 mode: "yjs"、content_hash、content_sync_seq、yjs_state_vector 和 committed_at；只有 durable CAS 成功才返回 2xx。
  • ui：为当前 UI 源码创建命名检查点，供历史恢复与部署前留档。

浏览器保存状态必须以该响应为准。成功后客户端应分别推进本地正文投影 baseline，以及响应中的 authoritative content_hash/content_sync_seq revision baseline；两套 hash 不得交叉比较。WebSocket 已同步但 checkpoint 失败时，页面仍保持“未持久化”并允许重试。

运行快照契约 ​

编辑态运行接口会忽略请求体里的额外 JSON content，在创建 run 前取得 workflow checkpoint。run envelope 固化正文 snapshot、hash 与 seq；inline、worker 和 resume 均使用原 snapshot，不会在消费或恢复时重读已变化的文档。

草稿运行失败返回（#1575） ​

草稿作者运行接口失败时，JSON 根节点默认带脱敏 error，已执行的 sessions 输出保持原结构，失败 session 原位置带独立 error。SSE/NDJSON 的 run_error 同样保留已有 sessions/globalCtx；不返回或枚举后续未运行步骤。成功终态和原有文档权限不变，错误摘要遵循运行接口的500字符脱敏规则。

AI Workflow Editor

Copyright 2024-present WaiNao.AI