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）

请求参数 ​

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

认证方式 ​

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 相同；冲突写入返回校验错误，不会在多个候选之间猜测。服务端会在解析完成后通过唯一 name 恢复内部 mention:<blockId>，因此前向引用可用，且引用统计、API schema 与发布校验会得到稳定 Block id。

写入语义 ​

  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. checkpoint 前校验 Block id/name 的全文档唯一性；重复 name 或跨块 id/name 冲突会 fail closed，不会进入运行时产生后写覆盖

响应 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），需要文档写入权限。

请求参数 ​

Path 参数 ​

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

响应 200 ​

json
{
  "success": true
}

错误码 ​

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

POST /documents/:documentId/edit ​

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

认证方式 ​

JWT Token / API Key / Agent Token（combinedAuth），需要文档写入权限。

并发控制机制 ​

  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 静默吞掉。

响应格式 ​

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 定义
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（combinedAuth）。 请求：请求体为 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。

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，不会在消费或恢复时重读已变化的文档。

AI Workflow Editor

Copyright 2024-present WaiNao.AI