openapi: 3.0.3 info: title: Muse Content API version: 1.0.0 license: name: Proprietary servers: - url: / description: 同源 API 网关 paths: # ========== 作品(Work) ========== /app-api/muse/works: get: tags: [Content] summary: 获取作品列表 operationId: listWorks security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - name: status in: query schema: type: string enum: [draft, active, archived] description: 作品状态过滤 responses: '200': description: 作品分页列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: allOf: - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult' - type: object properties: list: type: array items: $ref: '#/components/schemas/WorkSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' post: tags: [Content] summary: 创建新作品 operationId: createWork security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' requestBody: required: true content: application/json: schema: type: object required: [title] properties: title: type: string minLength: 1 maxLength: 200 description: type: string maxLength: 2000 genre: type: string coverImageUrl: type: string format: uri responses: '201': description: 作品创建成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/Work' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}: get: tags: [Content] summary: 获取作品详情 operationId: getWork security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 作品详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/Work' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' put: tags: [Content] summary: 更新作品 operationId: updateWork security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object properties: title: type: string maxLength: 200 description: type: string maxLength: 2000 genre: type: string coverImageUrl: type: string format: uri status: type: string enum: [draft, active, archived] responses: '200': description: 更新成功 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/CommonResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' delete: tags: [Content] summary: 删除作品 operationId: deleteWork security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 删除成功 '404': $ref: '../openapi-base.yaml#/components/responses/NotFound' # ========== 章节(Chapter) ========== /app-api/muse/works/{workId}/chapters: get: tags: [Content] summary: 获取作品章节列表 operationId: listChapters security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 章节列表（按 sortOrder 排序） content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Chapter' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' post: tags: [Content] summary: 创建章节 operationId: createChapter security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: [title] properties: title: type: string minLength: 1 maxLength: 500 sortOrder: type: integer description: 插入位置，默认追加到末尾 responses: '201': description: 创建成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/Chapter' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/chapters/{chapterId}: get: tags: [Content] summary: 获取章节详情 description: 必须先校验调用方拥有 workId 权限，并校验 chapterId 属于该 workId。 operationId: getChapter security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 responses: '200': description: 章节详情（含 Block 列表） content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ChapterDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' put: tags: [Content] summary: 更新章节 description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision 乐观锁。 operationId: updateChapter security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateChapterRequest' responses: '200': description: 更新成功 '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' delete: tags: [Content] summary: 删除章节 description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision 乐观锁。 operationId: deleteChapter security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteChapterRequest' responses: '200': description: 删除成功 '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/chapters/{chapterId}/reorder: put: tags: [Content] summary: 调整章节排序 description: 必须校验 work owner、章节从属关系、commandId 幂等、expectedRevision 和重排源快照。 operationId: reorderChapters security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReorderChapterRequest' responses: '200': description: 排序更新成功 # ========== Block ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/chapters/{chapterId}/blocks: get: tags: [Content] summary: 获取章节 Block 列表 description: 必须先校验调用方拥有 workId 权限，并校验 chapterId 属于该 workId。 operationId: listBlocks security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 responses: '200': description: Block 列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/Block' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' post: tags: [Content] summary: 创建 Block description: 必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedChapterRevision。 operationId: createBlock security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: chapterId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBlockRequest' responses: '201': description: 创建成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/Block' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/blocks/{blockId}: get: tags: [Content] summary: 获取 Block 详情 description: 必须先校验调用方拥有 workId 权限，并校验 blockId 属于该 workId。 operationId: getBlock security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 responses: '200': description: Block 详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/Block' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' put: tags: [Content] summary: 保存 Block 正文 description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 乐观锁和 sourceSnapshot。 operationId: saveBlock security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SaveBlockRequest' responses: '200': description: 保存成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: object properties: revision: type: integer description: 保存后的新 Block revision '409': description: 版本冲突，需客户端处理 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse' delete: tags: [Content] summary: 删除 Block description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 operationId: deleteBlock security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteBlockRequest' responses: '200': description: 删除成功 '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/blocks/{blockId}/revisions: get: tags: [Content] summary: 查询 Block 正文版本历史 description: | 返回指定 Block 已进入 Canonical 的正文 revision 快照，最新 revision 在前。 仅包含 Content owner 内部写入的正文快照；不提供恢复写入能力，避免绕过当前 Block 的乐观锁与来源归因。 operationId: listBlockRevisions security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 responses: '200': description: Block 正文版本历史 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/BlockRevision' '404': $ref: '../openapi-base.yaml#/components/responses/NotFound' /app-api/muse/works/{workId}/blocks/{blockId}/split: post: tags: [Content] summary: 分割 Block description: 必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 operationId: splitBlock security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SplitBlockRequest' responses: '200': description: 分割成功，返回两个新 Block '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/blocks/{blockId}/merge: post: tags: [Content] summary: 合并 Block description: 必须校验 work owner、blockId 从属关系、目标相邻 Block、commandId 幂等、expectedRevision 和 sourceSnapshot。 operationId: mergeBlocks security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 description: 与下一个 Block 合并 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MergeBlockRequest' responses: '200': description: 合并成功 # ========== 导出（旧版保留） ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/export: post: tags: [Content] summary: 导出作品 operationId: exportWork security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: [format] properties: format: type: string enum: [txt, epub, docx] includeChapters: type: array items: type: integer format: int64 description: 指定导出章节，空数组表示导出全部 responses: '200': description: 导出任务已创建，返回任务 ID 供轮询 '202': description: 导出文件二进制流（小文件直接返回） # ================================================================ # 以下为 Phase 0 新增接口 # ================================================================ # ========== Admin 内容管理 (Section 3.2) ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/works: get: tags: [Content-Admin] summary: 查询作品列表和治理摘要 description: | 管理员查询作品列表，返回治理摘要信息。 默认不返回用户私有正文全文，确需查看必须另有合规访问设计。 operationId: adminListWorks security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - name: status in: query schema: type: string enum: [draft, active, archived] description: 作品状态过滤 - name: keyword in: query schema: type: string description: 标题关键词搜索 - name: riskFlag in: query schema: type: boolean description: 是否只返回有异常标记的作品 responses: '200': description: 作品列表与治理摘要 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: allOf: - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult' - type: object properties: list: type: array items: $ref: '#/components/schemas/AdminWorkSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/works/{workId}: get: tags: [Content-Admin] summary: 查看作品元信息、章节摘要、异常摘要 description: | 管理员查看作品元信息。默认不返回用户私有正文全文， 确需查看必须另有合规访问设计、审计和最小化字段。 operationId: adminGetWork security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 作品元信息、章节摘要、异常摘要 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/AdminWorkDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/works/{workId}/chapters: get: tags: [Content-Admin] summary: 查看章节列表 description: 管理员查看作品的章节列表，不含正文全文。 operationId: adminListChapters security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 章节列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/AdminChapterSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/import-tasks: get: tags: [Content-Admin] summary: 查询导入任务 operationId: adminListImportTasks security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - name: status in: query schema: type: string enum: [queued, processing, completed, failed] description: 任务状态过滤 - name: workId in: query schema: type: integer format: int64 description: 按作品过滤 responses: '200': description: 导入任务列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: allOf: - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult' - type: object properties: list: type: array items: $ref: '#/components/schemas/ImportTaskSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/export-tasks: get: tags: [Content-Admin] summary: 查询导出任务 operationId: adminListExportTasks security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - name: status in: query schema: type: string enum: [queued, processing, completed, failed] description: 任务状态过滤 - name: workId in: query schema: type: integer format: int64 description: 按作品过滤 responses: '200': description: 导出任务列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: allOf: - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult' - type: object properties: list: type: array items: $ref: '#/components/schemas/ExportTaskSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /admin-api/muse/content/works/{workId}/risk-actions: post: tags: [Content-Admin] summary: 异常内容治理动作 description: | 管理员对异常内容执行治理动作。必须带 commandId、操作者、权限点、变更理由和审计字段。 高危治理进入业务审计。 operationId: adminRiskAction security: - adminBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RiskActionRequest' responses: '200': description: 治理动作执行成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/RiskActionResult' # ========== App 来源归因 (Section 4.3) ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/blocks/{blockId}/source-attribution: get: tags: [Content] summary: 查看当前 Block revision 来源归因 description: | 返回 Block 当前 revision 的来源归因信息，包含来源对象、来源版本、 授权快照和许可限制。前端可据此展示内容来源标签和合规提示。 必须先校验调用方拥有 workId 权限，并校验 blockId 属于该 workId。 operationId: getBlockSourceAttribution security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 responses: '200': description: Block 来源归因信息 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/SourceAttribution' '404': $ref: '../openapi-base.yaml#/components/responses/NotFound' /app-api/muse/works/{workId}/blocks/{blockId}/suggestion-merges: post: tags: [Content] summary: 接受或修改后合并 AI 候选到 Canonical Block description: | Content/Work owner 的最终写入命令，用于承接 AI Orchestration 产生的 suggestion 投影并写入 Canonical Block。 AI Orchestration 仍拥有候选运行事实；Content 只在提交时查询/校验 suggestionId、来源状态、授权快照、 质量结果版本、输出合规结果、静态检查结果、work owner、blockId 从属关系、expectedBlockRevision 和 commandId 幂等。 operationId: mergeBlockSuggestion security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: blockId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MergeBlockSuggestionRequest' responses: '200': description: 候选已写入 Canonical Block content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/MergeBlockSuggestionResult' '409': description: 目标 Block revision、候选版本、来源状态或授权快照已变化 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse' # ========== App Meta 投影 (Section 4.3) ========== /app-api/muse/works/{workId}/meta-projections: get: tags: [Content-Meta] summary: 查询作品维度用户可见 MetaSchema 投影 description: | 返回作品维度用户可见的 MetaSchema 投影列表。 投影不是事实源，只是 MetaSchema、用户权限、来源状态和目标对象版本计算后的 read model。 operationId: listMetaProjections security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 作品维度 MetaSchema 投影列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/MetaProjectionSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/meta-projections/{projectionKey}: get: tags: [Content-Meta] summary: 查询指定投影结构、字段数据和版本 description: | 返回指定投影的结构、字段数据和版本信息。 包含 schemaVersion、projectionVersion、dataRevision、sourceSnapshot 和可见字段列表。 operationId: getMetaProjection security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: projectionKey in: path required: true schema: type: string description: 投影标识，如 setting、worldview、character 等 responses: '200': description: 投影详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/MetaProjectionDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/dynamic-fields/validate: post: tags: [Content-Meta] summary: 校验动态字段数据，不写入 description: | 只做校验和路由建议，不写入任何 Canonical fact。 正式写入必须回到目标 owner API。Schema 过期返回 SCHEMA_STALE； 字段已废弃返回 FIELD_DEPRECATED；投影过期返回 PROJECTION_STALE。 operationId: validateDynamicFields security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DynamicFieldValidationRequest' responses: '200': description: 校验结果 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/DynamicFieldValidationResult' # ========== App 作品规划 (Section 4.4) ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning: get: tags: [Content-Planning] summary: 查询当前作品可见规划结构 description: | 返回作品可见规划结构、已确认规划数据、revision 和来源摘要。 规划正式数据由用户确认后进入 content owner；AI 只能产生 Planning Candidate，不直接写正式规划。 operationId: getPlanning security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 responses: '200': description: 作品规划结构 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/PlanningStructure' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/{sectionKey}: put: tags: [Content-Planning] summary: 保存规划项 description: | 保存规划项，必须带 commandId 和 expectedRevision。 涉及 MetaSchema 管控的动态字段写入时，expectedSchemaVersion 和 expectedProjectionVersion 必须校验。 operationId: savePlanningItem security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: sectionKey in: path required: true schema: type: string description: 规划项标识，如 setting、worldview、character、plot-beat 等 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SavePlanningItemRequest' responses: '200': description: 保存成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/PlanningItemSaveResult' '409': description: 版本冲突或 Schema/投影过期 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse' /app-api/muse/works/{workId}/planning/candidates: post: tags: [Content-Planning] summary: 请求 AI 生成规划候选 description: | 通过 Content/Work 上下文请求 AI Orchestration 生成规划候选，支持生成、补全、整理和多组选项。 AI Orchestration 拥有生成任务、候选运行事实和评测结果；Content 只提供 work 上下文引用， 并在用户确认时把候选内容写入 Canonical 规划。 operationId: createPlanningCandidate security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePlanningCandidateRequest' responses: '202': description: 规划候选任务已创建 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: object properties: jobId: type: string description: 异步任务 ID，供轮询 status: type: string enum: [queued, processing] pollUrl: type: string description: 轮询地址 '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' get: tags: [Content-Planning] summary: 查询规划候选 description: 查询 AI Orchestration owner 提供的规划候选投影；Content 不拥有候选运行事实。 operationId: listPlanningCandidates security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: status in: query schema: type: string enum: [pending, confirmed, discarded] description: 候选状态过滤 - name: sectionKey in: query schema: type: string description: 按规划项过滤 responses: '200': description: 规划候选列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/PlanningCandidateSummary' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/candidates/{candidateId}: get: tags: [Content-Planning] summary: 查询候选详情 description: 返回 AI Orchestration owner 提供的候选详情、来源、质量结果和 diff 投影。 operationId: getPlanningCandidate security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: candidateId in: path required: true schema: type: integer format: int64 responses: '200': description: 规划候选详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/PlanningCandidateDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/candidates/{candidateId}/confirm: post: tags: [Content-Planning] summary: 确认候选进入正式规划 description: | Content/Work owner 的最终写入命令：确认 AI 候选进入正式规划，必须带 commandId 和 expectedRevision。 确认时目标 owner 必须重验 work 权限、候选状态、来源状态、授权快照、 质量结果和目标 revision。确认成功只写正式规划项和业务审计， 不写正文或 Local KB，也不接管 AI 候选运行事实。 operationId: confirmPlanningCandidate security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: candidateId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfirmPlanningCandidateRequest' responses: '200': description: 确认成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/PlanningCandidateDecisionResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/candidates/{candidateId}/discard: post: tags: [Content-Planning] summary: 丢弃候选 description: 丢弃候选，必须带 commandId 和原因。 operationId: discardPlanningCandidate security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: candidateId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DiscardPlanningCandidateRequest' responses: '200': description: 丢弃成功 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/CommonResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/style-checks: post: tags: [Content-Planning] summary: 请求 AI 文风检查 description: | 通过 Content/Work 上下文请求 AI Orchestration 执行文风检查，返回 jobId 供轮询。 AI Orchestration 拥有运行事实和评测结果；Content 只暴露作品维度结果投影。 operationId: createStyleCheck security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStyleCheckRequest' responses: '202': description: 文风检查任务已创建 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: object properties: jobId: type: string description: 异步任务 ID status: type: string enum: [queued, processing] pollUrl: type: string '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/planning/style-checks/{jobId}: get: tags: [Content-Planning] summary: 查询文风检查结果 description: 查询 AI Orchestration owner 提供的文风检查结果、风险标记和建议入口投影。 operationId: getStyleCheckResult security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 - name: jobId in: path required: true schema: type: integer format: int64 responses: '200': description: 文风检查结果 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/StyleCheckResult' # ========== App 导入导出 (Section 4.9) ========== '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/import-tasks: post: tags: [Content-ImportExport] summary: 上传并创建导入任务 description: | 创建导入任务。外部上传模式必须绑定 owner、用途、大小、MIME、hash、 扫描状态、source snapshot、authorization snapshot、保留期和清理策略； 扫描 blocked/failed 的文件不得创建 Parse Job。本地文本导入模式使用 contentText， 仅支持 txt/markdown，并由 Content 在同一事务内初始化 Canonical 正文。 operationId: createImportTask security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateImportTaskRequest' responses: '202': description: 导入任务已创建 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ImportTaskDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/import-tasks/{taskId}: get: tags: [Content-ImportExport] summary: 查询导入任务 operationId: getImportTask security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: taskId in: path required: true schema: type: integer format: int64 responses: '200': description: 导入任务详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ImportTaskDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/parse-jobs: post: tags: [Content-ImportExport] summary: 请求 AI 全书解析任务 description: | 基于 Content 拥有的导入任务/导入上下文引用，请求 AI Orchestration 创建全书解析任务。 AI Orchestration 拥有 Parse Job、章节解析结果、评测和重试运行事实；Content 只保存导入上下文引用、 导入文件安全状态和最终被确认写入 Canonical 的结果。 Parse Job 必须绑定 workId、发起人、Content 上下文引用、source snapshot、 authorization snapshot、解析配置版本、Runtime Permission Envelope 和重试组。 operationId: createParseJob security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateParseJobRequest' responses: '202': description: AI 解析任务已创建 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ParseJobDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/parse-jobs/{jobId}: get: tags: [Content-ImportExport] summary: 查询 AI 解析任务投影 description: Content 只查询 AI Orchestration owner 的 Parse Job 投影，不拥有解析运行事实。 operationId: getParseJob security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: jobId in: path required: true schema: type: integer format: int64 responses: '200': description: AI 解析任务详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ParseJobDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/parse-jobs/{jobId}/retry: post: tags: [Content-ImportExport] summary: 重试解析任务 description: 通过 Content 导入上下文引用向 AI Orchestration 请求重试；重试状态和运行事实仍由 AI owner 负责。 operationId: retryParseJob security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: jobId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: [commandId] properties: commandId: type: string description: 幂等键 retryStage: type: string description: 指定重试的失败阶段，不传则重试整个任务 responses: '200': description: 重试已发起 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: object properties: jobId: type: string status: type: string enum: [queued, processing] pollUrl: type: string '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/parse-jobs/{jobId}/chapters: get: tags: [Content-ImportExport] summary: AI 章节解析结果 description: 返回 AI Orchestration owner 在 Parse Job 下产生的章节解析结果投影。 operationId: listParseJobChapters security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: jobId in: path required: true schema: type: integer format: int64 responses: '200': description: 章节解析结果列表 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: array items: $ref: '#/components/schemas/ChapterParseResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/chapter-parse-results/{resultId}/confirm: post: tags: [Content-ImportExport] summary: 章节审阅确认 description: | 章节审阅确认是对 AI Orchestration owner 章节解析结果的用户决策投影确认。 Content 不拥有 Chapter Parse Result 或 Review 运行事实；确认后只把导入上下文引用和用户决策交给 Knowledge owner 生成或刷新 Knowledge Draft，不写正式知识。 operationId: confirmChapterParseResult security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: resultId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfirmChapterParseResultRequest' responses: '200': description: 确认成功 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: type: object properties: draftId: type: string description: 生成的知识草稿 ID status: type: string enum: [confirmed, draft_created] '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/chapter-parse-results/{resultId}/reject: post: tags: [Content-ImportExport] summary: 章节驳回 description: | 章节驳回是对 AI Orchestration owner 章节解析结果的用户决策。 Content 不拥有或删除 AI Shadow 运行事实，只传递驳回原因和导入上下文引用。 不删除原始导入文件。 operationId: rejectChapterParseResult security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: resultId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RejectChapterParseResultRequest' responses: '200': description: 驳回成功 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/CommonResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/parse-jobs/{jobId}/chapters/batch-confirm: post: tags: [Content-ImportExport] summary: 批量确认章节 description: | 批量确认 AI Orchestration owner 的章节解析结果投影，返回逐章成功、失败和部分失败摘要。 以章节为事务边界，允许部分失败；某章失败不得回滚已成功章节。 Content 只保存导入上下文和最终进入 Canonical 的结果引用，不拥有 AI 解析运行事实。 operationId: batchConfirmChapters security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: jobId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchConfirmChaptersRequest' responses: '200': description: 批量确认结果 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/BatchConfirmChaptersResult' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/works/{workId}/export-tasks: post: tags: [Content-ImportExport] summary: 创建导出任务 description: | 创建导出任务，必须带 commandId 幂等键。 下载凭证必须携带来源传播版本和授权快照。 operationId: createExportTask security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: workId in: path required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExportTaskRequest' responses: '202': description: 导出任务已创建 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ExportTaskDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/export-tasks/{taskId}: get: tags: [Content-ImportExport] summary: 查询导出任务 operationId: getExportTask security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: taskId in: path required: true schema: type: integer format: int64 responses: '200': description: 导出任务详情 content: application/json: schema: allOf: - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' - type: object properties: data: $ref: '#/components/schemas/ExportTaskDetail' '400': $ref: '../openapi-base.yaml#/components/responses/BadRequest' '401': $ref: '../openapi-base.yaml#/components/responses/Unauthorized' '403': $ref: '../openapi-base.yaml#/components/responses/Forbidden' /app-api/muse/downloads/{credentialId}: get: tags: [Content-ImportExport] summary: 下载导出包 description: | 使用下载凭证下载导出包。来源 revoked/recalled/blocked/unauthorized 或授权过期时返回 SOURCE_BLOCKED、SOURCE_NEEDS_RECHECK 或 PRECHECK_EXPIRED， 不能继续下载。 operationId: downloadExportPackage security: - appBearerAuth: [] parameters: - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion' - name: credentialId in: path required: true schema: type: string description: 下载凭证 ID responses: '200': description: 导出文件二进制流 content: application/octet-stream: schema: type: string format: binary '404': $ref: '../openapi-base.yaml#/components/responses/NotFound' '410': description: 下载凭证已过期或已消费 content: application/json: schema: $ref: '../openapi-base.yaml#/components/schemas/ErrorResponse' components: securitySchemes: adminBearerAuth: type: http scheme: bearer bearerFormat: JWT description: 管理后台认证 scheme，仅用于 /admin-api/** 接口，admin-api token 与 app-api token 不互通。 appBearerAuth: type: http scheme: bearer bearerFormat: JWT description: 用户端认证 scheme，仅用于 /app-api/** 接口，app-api token 与 admin-api token 不互通。 schemas: # ========== 原有 Schema ========== Work: type: object required: [id, title, status, createdAt, updatedAt] properties: id: type: integer format: int64 title: type: string description: type: string genre: type: string coverImageUrl: type: string format: uri status: type: string enum: [draft, active, archived] wordCount: type: integer description: 总字数 chapterCount: type: integer description: 章节数 createdAt: type: string format: date-time updatedAt: type: string format: date-time WorkSummary: type: object required: [id, title, status, updatedAt] properties: id: type: integer format: int64 title: type: string genre: type: string status: type: string enum: [draft, active, archived] wordCount: type: integer chapterCount: type: integer updatedAt: type: string format: date-time Chapter: type: object required: [id, workId, title, sortOrder, status, createdAt, updatedAt] properties: id: type: integer format: int64 workId: type: integer format: int64 title: type: string sortOrder: type: integer status: type: string enum: [draft, completed] wordCount: type: integer blockCount: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time ChapterDetail: allOf: - $ref: '#/components/schemas/Chapter' - type: object properties: blocks: type: array items: $ref: '#/components/schemas/Block' Block: type: object required: [id, workId, chapterId, blockType, content, sortOrder, revision, createdAt, updatedAt] properties: id: type: integer format: int64 workId: type: integer format: int64 chapterId: type: integer format: int64 blockType: type: string enum: [scene, section, note] title: type: string content: type: string description: ProseMirror JSON 格式的正文内容 sortOrder: type: integer revision: type: integer description: 乐观锁版本号，每次保存 +1 wordCount: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time ContentSourceSnapshot: type: object description: | Content/Work 写命令的来源快照。用于在写入 Canonical 前校验调用方看到的内容版本、 来源状态、授权快照和目标 owner 边界，避免只凭 chapterId/blockId 裸写。 properties: sourceType: type: string description: 来源类型，如 user_original、ai_suggestion、imported_content sourceId: type: string description: 来源对象 ID sourceVersion: type: integer description: 调用方看到的来源版本 authorizationSnapshotId: type: string description: 授权快照 ID contentRevision: type: integer description: 调用方看到的目标内容 revision BlockRevision: type: object required: [blockId, revision, content, wordCount, commandId, commandType, createdAt] properties: blockId: type: integer format: int64 revision: type: integer description: Block revision content: type: string description: 该 revision 的正文快照 wordCount: type: integer description: 该 revision 的字数 commandId: type: string description: 触发该 revision 的命令 ID commandType: type: string enum: [save_block, mergeBlockSuggestion] description: 触发该 revision 的命令类型 sourceType: type: string description: 来源类型 sourceId: type: string description: 来源对象 ID sourceVersion: type: integer description: 来源对象版本 sourceStatus: type: string description: 来源状态 authorizationSnapshotId: type: string description: 授权快照 ID auditReason: type: string description: 审计原因 createdAt: type: string format: date-time UpdateChapterRequest: type: object description: 更新章节请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision。 required: [commandId, expectedRevision] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 章节当前 revision（乐观锁） title: type: string maxLength: 500 sortOrder: type: integer status: type: string enum: [draft, completed] sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' auditReason: type: string description: 用户修改原因 DeleteChapterRequest: type: object description: 删除章节请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedRevision。 required: [commandId, expectedRevision] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 章节当前 revision（乐观锁） sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' reason: type: string description: 删除原因 ReorderChapterRequest: type: object description: 章节重排请求；服务端必须校验 work owner、章节从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 required: [commandId, expectedRevision, newSortOrder, sourceSnapshot] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 作品章节排序 revision 或目标章节 revision（乐观锁） newSortOrder: type: integer minimum: 0 sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' CreateBlockRequest: type: object description: 创建 Block 请求；服务端必须校验 work owner、chapterId 从属关系、commandId 幂等和 expectedChapterRevision。 required: [commandId, content, blockType, expectedChapterRevision] properties: commandId: type: string description: 幂等键 content: type: string description: Block 正文内容（JSON 格式的 ProseMirror 文档） blockType: type: string enum: [scene, section, note] description: Block 类型 expectedChapterRevision: type: integer description: 章节当前 revision（乐观锁） sortOrder: type: integer title: type: string maxLength: 500 sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' SaveBlockRequest: type: object description: 保存 Block 正文请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 required: [commandId, content, expectedRevision, sourceSnapshot] properties: commandId: type: string description: 幂等键 content: type: string description: Block 正文（ProseMirror JSON） expectedRevision: type: integer description: Block 当前 revision（乐观锁） sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' auditReason: type: string description: 用户保存或覆盖原因 DeleteBlockRequest: type: object description: 删除 Block 请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 required: [commandId, expectedRevision, sourceSnapshot] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: Block 当前 revision（乐观锁） sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' reason: type: string description: 删除原因 SplitBlockRequest: type: object description: 分割 Block 请求；服务端必须校验 work owner、blockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 required: [commandId, splitPosition, expectedRevision, sourceSnapshot] properties: commandId: type: string description: 幂等键 splitPosition: type: integer description: 分割位置（字符偏移量） expectedRevision: type: integer description: Block 当前 revision（乐观锁） sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' MergeBlockRequest: type: object description: 合并 Block 请求；服务端必须校验 work owner、blockId/targetBlockId 从属关系、commandId 幂等、expectedRevision 和 sourceSnapshot。 required: [commandId, expectedRevision, sourceSnapshot] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 源 Block 当前 revision（乐观锁） targetBlockId: type: integer format: int64 description: 目标相邻 Block ID；不传时默认与下一个 Block 合并 sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' MergeBlockSuggestionRequest: type: object description: | 接受或修改后合并 AI suggestion 的 Content owner 写入请求。 服务端必须实时查询/校验 AI owner 的 suggestion 投影和来源状态，再写 Canonical Block。 required: [suggestionId, commandId, expectedBlockRevision, decisionType, mergeMode, sourceSnapshot] properties: suggestionId: type: integer format: int64 description: AI Orchestration owner 产生的候选 ID commandId: type: string description: 幂等键 expectedBlockRevision: type: integer description: 目标 Block 当前 revision（乐观锁） decisionType: type: string enum: [accept, modify_then_merge] description: 用户决策类型 mergeMode: type: string enum: [accept_as_is, merge_after_edit] description: 写入方式：原样接受或修改后合并 finalContent: type: string description: 修改后合并时的最终 Block 正文（mergeMode=merge_after_edit 时必填） qualityResultVersion: type: integer description: 候选质量结果版本 outputComplianceResultId: type: string description: 输出合规结果 ID staticCheckResultId: type: string description: 静态检查结果 ID sourceSnapshot: $ref: '#/components/schemas/ContentSourceSnapshot' auditReason: type: string description: 用户接受或修改合并原因 MergeBlockSuggestionResult: type: object description: AI suggestion 写入 Canonical Block 的结果 required: [blockId, suggestionId, newRevision, decisionType] properties: blockId: type: integer format: int64 suggestionId: type: integer format: int64 newRevision: type: integer description: Block 保存成功后的新 revision decisionType: type: string enum: [accept, modify_then_merge] sourceAttribution: $ref: '#/components/schemas/SourceAttribution' # ========== Admin 内容管理 Schema ========== AdminWorkSummary: type: object description: 管理员视角的作品列表项，含治理摘要 required: [id, title, status, ownerId, updatedAt] properties: id: type: integer format: int64 title: type: string genre: type: string status: type: string enum: [draft, active, archived] ownerId: type: string description: 作品所有者用户 ID wordCount: type: integer chapterCount: type: integer riskFlags: type: array description: 异常标记列表 items: type: object properties: riskType: type: string description: 异常类型，如 content_violation、copyright_issue severity: type: string enum: [low, medium, high, critical] description: type: string description: 异常描述摘要 lastGovernanceActionAt: type: string format: date-time description: 最近一次治理动作时间 createdAt: type: string format: date-time updatedAt: type: string format: date-time AdminWorkDetail: type: object description: 管理员视角的作品详情，含章节摘要和异常摘要 required: [id, title, status, ownerId, createdAt, updatedAt] properties: id: type: integer format: int64 title: type: string description: type: string genre: type: string status: type: string enum: [draft, active, archived] ownerId: type: string description: 作品所有者用户 ID wordCount: type: integer chapterCount: type: integer chapterSummaries: type: array description: 章节摘要列表（不含正文全文） items: $ref: '#/components/schemas/AdminChapterSummary' exceptionSummary: type: object description: 异常摘要 properties: totalRiskFlags: type: integer description: 总异常标记数 criticalCount: type: integer description: 严重异常数 activeGovernanceActions: type: integer description: 进行中的治理动作数 latestRiskType: type: string description: 最近异常类型 governanceHistory: type: array description: 治理操作历史摘要 items: type: object properties: action: type: string description: 治理动作类型 operatorId: type: string description: 操作者 ID reason: type: string operatedAt: type: string format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time AdminChapterSummary: type: object description: 管理员视角的章节摘要，不含正文全文 required: [id, title, sortOrder, status] properties: id: type: integer format: int64 title: type: string sortOrder: type: integer status: type: string enum: [draft, completed] wordCount: type: integer blockCount: type: integer riskFlags: type: array items: type: object properties: riskType: type: string severity: type: string enum: [low, medium, high, critical] RiskActionRequest: type: object description: 异常内容治理动作请求 required: [commandId, action, reason, expectedVersion] properties: commandId: type: string description: 幂等键 action: type: string enum: [warn, restrict, block_content, force_archive, notify_owner] description: | 治理动作类型： warn - 发出警告通知 restrict - 限制部分功能 block_content - 阻断内容访问 force_archive - 强制归档作品 notify_owner - 通知作品所有者 reason: type: string description: 治理原因，必须填写 targetScope: type: string enum: [work, chapter, block] description: 治理范围粒度，默认 work targetIds: type: array items: type: integer format: int64 description: 指定治理的章节或 Block ID（粒度非 work 时必填） expectedVersion: type: integer description: 作品当前版本号，用于乐观锁 duration: type: string description: 限制时长，如 P7D（7 天），仅 restrict 动作适用 RiskActionResult: type: object description: 治理动作执行结果 properties: actionId: type: string description: 治理动作记录 ID status: type: string enum: [executed, pending_notification] affectedScope: type: string description: 实际影响的范围描述 auditLogId: type: string description: 审计日志 ID ImportTaskSummary: type: object description: 导入任务摘要（管理端列表用） required: [id, workId, status, createdAt] properties: id: type: integer format: int64 workId: type: integer format: int64 workTitle: type: string fileName: type: string fileSize: type: integer format: int64 format: type: string enum: [txt, epub, docx, markdown] status: type: string enum: [queued, processing, completed, failed] ownerId: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time ExportTaskSummary: type: object description: 导出任务摘要（管理端列表用） required: [id, workId, status, createdAt] properties: id: type: integer format: int64 workId: type: integer format: int64 workTitle: type: string format: type: string enum: [txt, epub, docx] status: type: string enum: [queued, processing, completed, failed] ownerId: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time # ========== 来源归因 Schema ========== SourceAttribution: type: object description: Block 当前 revision 的来源归因信息 required: [blockId, revision] properties: blockId: type: integer format: int64 revision: type: integer description: Block 当前 revision 号 sources: type: array description: 来源归因列表 items: type: object required: [sourceType, sourceId, contributionType] properties: sourceType: type: string enum: [user_original, ai_suggestion, knowledge_reference, market_asset, imported_content] description: 来源类型 sourceId: type: string description: 来源对象 ID sourceName: type: string description: 来源对象名称 contributionType: type: string enum: [full, partial, reference, context] description: 贡献类型 authorizationSnapshotId: type: string description: 授权快照 ID sourceVersion: type: integer description: 来源版本号 licenseRestrictions: type: array description: 许可限制列表 items: type: string lineage: type: object description: 来源谱系信息 properties: parentSuggestionId: type: string description: 关联的 AI 候选 ID acceptedAt: type: string format: date-time acceptMode: type: string enum: [accept_as_is, merge_after_edit] # ========== Meta 投影 Schema ========== MetaProjectionSummary: type: object description: 作品维度 MetaSchema 投影摘要 required: [projectionKey, schemaVersion, projectionVersion] properties: projectionKey: type: string description: 投影标识，如 setting、worldview、character projectionName: type: string description: 投影名称 schemaVersion: type: integer description: 本次投影使用的 MetaSchema 版本 projectionVersion: type: integer description: 可见投影版本，用于判断前端缓存是否过期 dataRevision: type: integer description: 目标对象动态字段数据 revision fieldCount: type: integer description: 可见字段数量 MetaProjectionDetail: type: object description: 投影详情，含结构和字段数据 required: [projectionKey, schemaVersion, projectionVersion, dataRevision, fields] properties: projectionKey: type: string projectionName: type: string schemaVersion: type: integer description: 使用的 MetaSchema active 或灰度版本 projectionVersion: type: integer description: 可见投影版本 dataRevision: type: integer description: 目标对象动态字段数据 revision sourceSnapshot: type: object description: 来源对象、来源版本、授权快照和来源状态摘要 properties: sourceType: type: string sourceId: type: string sourceVersion: type: integer authorizationSnapshotId: type: string sourceStatus: type: string enum: [active, stale, revoked, recalled, blocked, owner_missing, unauthorized] fields: type: array description: 仅包含当前用户可见、可编辑、可搜索或可导出的字段 items: type: object required: [fieldKey, fieldType, uiVisible] properties: fieldKey: type: string fieldName: type: string fieldType: type: string enum: [text, number, boolean, enum, reference, structured, date] required: type: boolean uiVisible: type: boolean description: 是否进入用户可见投影 aiContext: type: boolean description: 是否允许进入 AI 上下文组装 userEditable: type: boolean description: 用户端是否允许保存该动态字段 userSearchable: type: boolean description: 是否允许用户搜索或筛选 exportable: type: boolean description: 是否可被导出预检纳入 deprecated: type: boolean description: 字段是否已废弃 migrationHint: type: string description: 废弃时的迁移提示 writeOwner: type: string description: 写入 owner 标识 ownerCommand: type: string description: owner 写入命令路径 value: description: 当前字段值 enumValues: type: array description: 枚举可选值（fieldType=enum 时） items: type: string DynamicFieldValidationRequest: type: object description: 动态字段校验请求 required: [fields, schemaVersion, projectionVersion] properties: fields: type: array description: 待校验的动态字段数据 items: type: object required: [fieldKey, value] properties: fieldKey: type: string value: description: 字段值 schemaVersion: type: integer description: 调用方持有的 MetaSchema 版本 projectionVersion: type: integer description: 调用方持有的投影版本 dataRevision: type: integer description: 调用方持有的数据 revision DynamicFieldValidationResult: type: object description: 动态字段校验结果 properties: valid: type: boolean description: 整体是否合法 fieldResults: type: array items: type: object properties: fieldKey: type: string valid: type: boolean errors: type: array items: type: object properties: errorCode: type: string enum: [REQUIRED_MISSING, TYPE_MISMATCH, ENUM_INVALID, REFERENCE_INVALID, FIELD_DEPRECATED, VALUE_OUT_OF_RANGE] message: type: string schemaStale: type: boolean description: Schema 是否已过期 projectionStale: type: boolean description: 投影是否已过期 currentSchemaVersion: type: integer currentProjectionVersion: type: integer currentDataRevision: type: integer routeSuggestions: type: array description: 写入路由建议，指引前端到正确的 owner 命令 items: type: object properties: fieldKey: type: string writeOwner: type: string ownerCommand: type: string description: 建议的 owner 命令路径 # ========== 规划 Schema ========== PlanningStructure: type: object description: 作品规划结构 required: [workId, revision] properties: workId: type: integer format: int64 revision: type: integer description: 规划数据 revision sections: type: array description: 已确认的规划项列表 items: $ref: '#/components/schemas/PlanningSection' sourceSnapshot: type: object description: 来源摘要 properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string PlanningSection: type: object description: 规划项数据 required: [sectionKey, revision] properties: sectionKey: type: string description: 规划项标识，如 setting、worldview、character、plot-beat sectionName: type: string content: type: object description: 规划项内容（结构化 JSON） revision: type: integer description: 该规划项的 revision schemaVersion: type: integer description: 使用的 MetaSchema 版本 projectionVersion: type: integer description: 使用的投影版本 updatedAt: type: string format: date-time SavePlanningItemRequest: type: object description: 保存规划项请求 required: [commandId, content, expectedRevision] properties: commandId: type: string description: 幂等键 content: type: object description: 规划项内容（结构化 JSON） expectedRevision: type: integer description: 目标规划 section 的当前 revision expectedSchemaVersion: type: integer description: 调用方持有的 MetaSchema 版本（涉及动态字段时必须） expectedProjectionVersion: type: integer description: 调用方持有的投影版本（涉及动态字段时必须） sourceSnapshot: type: object description: 来源快照摘要 properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string auditReason: type: string description: 用户保存或覆盖原因 PlanningItemSaveResult: type: object description: 规划项保存结果 properties: sectionKey: type: string newRevision: type: integer updatedAt: type: string format: date-time CreatePlanningCandidateRequest: type: object description: 请求 AI Orchestration 生成规划候选的上下文引用；Content 不拥有候选运行事实。 required: [sectionKey, taskType] properties: sectionKey: type: string description: 目标规划项标识 taskType: type: string enum: [generate, supplement, organize, multi_option] description: | 任务类型： generate - 生成新内容 supplement - 补全已有内容 organize - 整理已有内容 multi_option - 生成多组选项 context: type: object description: 生成上下文，如已有规划内容、用户指令等 commandId: type: string description: 幂等键 sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string PlanningCandidateSummary: type: object description: AI Orchestration owner 提供给 Content/Work 的规划候选投影摘要 required: [id, sectionKey, status, createdAt] properties: id: type: integer format: int64 sectionKey: type: string taskType: type: string enum: [generate, supplement, organize, multi_option] status: type: string enum: [pending, confirmed, discarded] revision: type: integer qualityScore: type: number description: 质量评分 createdAt: type: string format: date-time confirmedAt: type: string format: date-time PlanningCandidateDetail: type: object description: AI Orchestration owner 提供给 Content/Work 的规划候选详情投影 required: [id, sectionKey, status, content, revision, createdAt] properties: id: type: integer format: int64 sectionKey: type: string taskType: type: string enum: [generate, supplement, organize, multi_option] status: type: string enum: [pending, confirmed, discarded] content: type: object description: 候选内容（结构化 JSON） revision: type: integer qualityResult: type: object description: 质量检查结果 properties: score: type: number passed: type: boolean issues: type: array items: type: object properties: severity: type: string enum: [info, warning, critical] code: type: string message: type: string diff: type: object description: 与当前正式规划的差异 properties: hasChanges: type: boolean summary: type: string additions: type: integer deletions: type: integer modifications: type: integer sourceSnapshot: type: object properties: sourceType: type: string sourceId: type: string sourceVersion: type: integer authorizationSnapshotId: type: string createdAt: type: string format: date-time confirmedAt: type: string format: date-time ConfirmPlanningCandidateRequest: type: object description: 确认规划候选请求 required: [commandId, expectedRevision] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 目标规划 section 的当前 revision expectedSchemaVersion: type: integer description: MetaSchema 版本（涉及动态字段时必须） expectedProjectionVersion: type: integer description: 投影版本（涉及动态字段时必须） sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string auditReason: type: string description: 用户确认原因 PlanningCandidateDecisionResult: type: object description: 候选确认结果 properties: candidateId: type: string newRevision: type: integer description: 规划项新 revision sectionKey: type: string auditLogId: type: string DiscardPlanningCandidateRequest: type: object description: 丢弃规划候选请求 required: [commandId, reason] properties: commandId: type: string description: 幂等键 reason: type: string description: 丢弃原因 CreateStyleCheckRequest: type: object description: 请求 AI Orchestration 执行文风检查的作品上下文引用 required: [commandId] properties: commandId: type: string description: 幂等键 checkScope: type: string enum: [full_work, selected_chapters, selected_blocks] description: 检查范围，默认 full_work targetIds: type: array items: type: integer format: int64 description: 指定检查的章节或 Block ID（checkScope 非 full_work 时必填） styleRules: type: object description: 自定义文风规则（可选，不传则使用作品设定） sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string StyleCheckResult: type: object description: AI Orchestration owner 提供给 Content/Work 的文风检查结果投影 required: [jobId, status] properties: jobId: type: integer format: int64 status: type: string enum: [queued, processing, completed, failed] riskMarkers: type: array description: 风险标记列表 items: type: object properties: markerType: type: string enum: [consistency, tone_shift, pacing, vocabulary, repetition] severity: type: string enum: [info, warning, critical] location: type: object properties: chapterId: type: string blockId: type: string position: type: string description: type: string summary: type: object properties: overallScore: type: number consistencyScore: type: number checkedWordCount: type: integer markerCount: type: integer suggestions: type: array description: 建议入口 items: type: object properties: suggestionType: type: string enum: [rewrite, adjust, review] targetSectionKey: type: string description: type: string completedAt: type: string format: date-time # ========== 导入导出 Schema ========== CreateImportTaskRequest: type: object description: 创建导入任务请求。uploadUrl 与 contentText 二选一；uploadUrl 当前为 infra 稳定存储 path，contentText 模式会直接初始化 Canonical 正文。 required: [commandId, fileName, fileSize, fileHash, format] properties: commandId: type: string description: 幂等键 fileName: type: string description: 文件名 fileSize: type: integer format: int64 description: 文件大小（字节） fileHash: type: string description: 文件哈希值 mimeType: type: string description: 文件 MIME 类型 format: type: string enum: [txt, epub, docx, markdown] description: 导入文件格式 uploadUrl: type: string description: 已上传文件的存储引用；外部上传模式必填。当前后端只接受 infra 稳定存储 path，不接受客户端任意外链 URL。 contentText: type: string maxLength: 500000 description: 本地文本导入正文；仅 txt/markdown 支持，服务端不会把原文写入导入任务快照 sourceSnapshot: type: object description: 来源快照 properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string ImportTaskDetail: type: object description: 导入任务详情 required: [id, workId, status, createdAt] properties: id: type: integer format: int64 workId: type: integer format: int64 fileName: type: string fileSize: type: integer format: int64 format: type: string enum: [txt, epub, docx, markdown] status: type: string enum: [queued, processing, completed, failed] scanStatus: type: string enum: [pending, passed, blocked, failed] description: 文件扫描状态 progress: type: integer description: 处理进度百分比（0-100） errorMessage: type: string description: 失败时的错误信息 failedStage: type: string description: 失败阶段 retryable: type: boolean description: 是否可重试 nextActions: type: array description: 下一步建议动作 items: type: string sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time CreateParseJobRequest: type: object description: 基于 Content 导入上下文请求 AI Orchestration 创建全书解析任务；Content 不拥有 Parse Job 运行事实。 required: [commandId, importTaskId] properties: commandId: type: string description: 幂等键 importTaskId: type: integer format: int64 description: 关联的导入任务 ID parseConfig: type: object description: 解析配置 properties: chapterDetectionMode: type: string enum: [auto, manual_outline, hybrid] description: 章节检测模式 languageHint: type: string description: 语言提示 customInstructions: type: string description: 自定义解析指令 sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string ParseJobDetail: type: object description: AI Orchestration owner 提供给 Content/Work 的解析任务投影 required: [id, workId, status, createdAt] properties: id: type: integer format: int64 workId: type: integer format: int64 importTaskId: type: integer format: int64 status: type: string enum: [queued, processing, completed, failed] progress: type: integer description: 处理进度百分比（0-100） totalChapters: type: integer description: 检测到的总章节数 confirmedChapters: type: integer description: 已确认章节数 pendingChapters: type: integer description: 待审阅章节数 errorMessage: type: string failedStage: type: string retryable: type: boolean nextActions: type: array items: type: string parseConfigVersion: type: integer description: 解析配置版本 sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time ChapterParseResult: type: object description: AI Orchestration owner 提供给 Content/Work 的章节解析结果投影 required: [id, jobId, title, status, revision] properties: id: type: integer format: int64 jobId: type: integer format: int64 title: type: string description: AI 检测到的章节标题 sortOrder: type: integer contentPreview: type: string description: 内容预览（截取摘要，非全文） wordCount: type: integer status: type: string enum: [pending_review, confirmed, rejected] description: | 审阅状态： pending_review - 待审阅 confirmed - 已确认 rejected - 已驳回 revision: type: integer qualityResult: type: object properties: score: type: number issues: type: array items: type: object properties: severity: type: string code: type: string message: type: string ConfirmChapterParseResultRequest: type: object description: 章节解析结果投影确认请求；AI 运行事实仍归 AI Orchestration。 required: [commandId, expectedRevision] properties: commandId: type: string description: 幂等键 expectedRevision: type: integer description: 当前 parse result revision RejectChapterParseResultRequest: type: object description: 章节解析结果投影驳回请求；AI 运行事实仍归 AI Orchestration。 required: [commandId, reason] properties: commandId: type: string description: 幂等键 reason: type: string description: 驳回原因 expectedRevision: type: integer description: 当前 parse result revision BatchConfirmChaptersRequest: type: object description: 批量确认章节解析结果投影请求；Content 只传递导入上下文和用户决策。 required: [commandId, resultIds, expectedRevisions] properties: commandId: type: string description: 幂等键 resultIds: type: array description: 待确认的 chapter parse result ID 列表 items: type: integer format: int64 expectedRevisions: type: object description: 每个解析结果对应的期望 revision，key 为 resultId additionalProperties: type: integer BatchConfirmChaptersResult: type: object description: 批量确认章节结果 properties: confirmedChapterResultIds: type: array description: 成功确认的章节 result ID 列表 items: type: integer format: int64 createdDraftIds: type: array description: 生成的知识草稿 ID 列表 items: type: integer format: int64 failedChapters: type: array description: 失败章节列表 items: type: object properties: resultId: type: integer format: int64 errorCode: type: string errorMessage: type: string skippedChapters: type: array description: 跳过章节列表 items: type: object properties: resultId: type: integer format: int64 reason: type: string partialFailure: type: boolean description: 是否存在部分失败 CreateExportTaskRequest: type: object description: 创建导出任务请求 required: [commandId, format] properties: commandId: type: string description: 幂等键 format: type: string enum: [txt, epub, docx] description: 导出格式 includeChapters: type: array description: 指定导出章节 ID，空数组表示导出全部 items: type: integer format: int64 includeMetadata: type: boolean default: true description: 是否包含元数据 includePlanning: type: boolean default: false description: 是否包含规划数据 sourceSnapshot: type: object description: 来源快照 properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string ExportTaskDetail: type: object description: 导出任务详情 required: [id, workId, format, status, createdAt] properties: id: type: integer format: int64 workId: type: integer format: int64 format: type: string enum: [txt, epub, docx] status: type: string enum: [queued, processing, completed, failed] progress: type: integer description: 处理进度百分比（0-100） downloadCredentialId: type: string description: 完成后的下载凭证 ID downloadExpiresAt: type: string format: date-time description: 下载凭证过期时间 errorMessage: type: string sourceSnapshot: type: object properties: sourceType: type: string sourceVersion: type: integer authorizationSnapshotId: type: string createdAt: type: string format: date-time completedAt: type: string format: date-time