zizi-al/oh-my-muse

Fork 0

zizi 8d7b47b468 提交前后端架构阶段文档

2026-05-23 23:55:00 +08:00

41 KiB

Raw Blame History

后端-05：统一 API(接口) 契约-v1

版本：v6
更新日期：2026-05-23
目标读者：前端 / 后端 / 架构 / 测试
阅读时间：35-55 分钟
边界说明：本文件只定义 Muse 在 Yudao Cloud fork 上的 API 分组、资源语义、关键命令、错误模型与异步交互。底层表结构看 后端-04，状态机看 架构-04，关键流程看 后端-03。

1. 总体原则

阶段 7 API 契约改为两类入口：

入口	调用方	语义
`/admin-api/**`	`yudao-ui-admin-vben/apps/web-antd`	管理后台接口
`/app-api/**`	`muse-studio`	普通用户端接口

Yudao 原生 system/infra/member/pay/bpm/report/mp 接口按 Yudao 约定保留，本文件不重复定义其全部内置接口。本文只定义 Muse 新增或二开的业务接口。

核心约束：

管理员接口不能替用户确认正文、知识草稿、规划候选或 AI 候选。
用户端接口不能修改系统 Prompt、系统 Agent、MetaSchema、质量策略或市场治理结果。
API 分 admin/app，不代表领域模型分 admin/app。
前端隐藏入口不是安全边界；后端必须强制鉴权、业务 owner、来源状态和状态机前置条件。
市场安装、绑定、购买或授权接口只能产生市场记录、handoff 或目标 owner 预检，不能直接写作品正文、Local KB 或正式规划。
Yudao 原生接口只通过引用和集成点使用；除 Muse 二开接口外，不在本文件复制 system、infra、pay、bpm、report、mp 的完整 API。

Muse API 分组与 owner：

分组	入口	owner module	说明
Governance	`/admin-api/muse/governance/**`	按对象回到 `content` / `ai` owner；`system` 只做权限	MetaSchema、保护节点、系统功能链路、影响预览
Content	`/admin-api/muse/content/`、`/app-api/muse/works/`	`yudao-module-content`	作品、章节、Block、导入导出、正文来源归因
Knowledge	`/admin-api/muse/knowledge/*`、`/app-api/muse/knowledge-/**`	`yudao-module-knowledge`	全局/用户/局域知识库、草稿、绑定、投影
AI / Agent	`/admin-api/muse/ai/`、`/app-api/muse/ai/`、`/app-api/muse/agents/**`	`yudao-module-ai` 二开	Prompt、Agent、任务、候选、质量门控、评估
Market	`/admin-api/muse/market/`、`/app-api/muse/marketplace/`	`yudao-module-market`	市场资产、授权、安装、handoff、发布、治理
Account	`/admin-api/muse/account/`、`/app-api/muse/account/`、`/app-api/muse/me`	逻辑 `account`	权益、配额、用量、授权/购买/发布摘要
Jobs / Events	`/admin-api/muse/jobs/`、`/app-api/muse/jobs/`、`/admin-api/muse/source-events/**`	各 owner + outbox	异步任务状态、来源事件传播和重试入口

2. 通用约定

2.1 响应格式

API 响应遵循 Yudao 风格的统一响应壳。产品语义字段可以在 data 内表达。

{
  "code": 0,
  "data": {},
  "msg": "success"
}

分页响应使用 Yudao PageResult 或等价结构：

{
  "code": 0,
  "data": {
    "list": [],
    "total": 0
  },
  "msg": "success"
}

错误响应必须包含可稳定识别的业务错误码。HTTP 状态可以按 Yudao 网关和全局异常处理约定处理，但前端不得只依赖 HTTP status 判断业务状态。

2.2 ID 契约

前端 TypeScript 统一把业务 ID 当 string 处理，避免 Long 精度、后续迁移和跨模块差异。
后端物理主键可遵循 Yudao 常规 Long id；需要公开稳定业务 ID 时，可以补 bizNo/publicId。
API 不承诺暴露数据库自增主键语义。
同一接口内 ID 类型必须稳定，不能混用数字和字符串。

2.3 认证权限

认证、会话、菜单、角色和权限基础能力复用 yudao-module-system。
/admin-api/** 需要后台权限点。
/app-api/** 需要登录身份和业务资源访问权。
系统任务或内部回调必须使用服务身份，不得复用普通用户 token。

2.4 异步任务

需要外部 AI、索引、导出、导入、评估、来源传播的操作默认异步。

命令响应至少返回：

{
  "jobId": "string",
  "status": "queued",
  "pollUrl": "/app-api/muse/jobs/{jobId}"
}

例外：Accept Suggestion 的正文写入必须在主事务内完成，响应返回 Block 新 revision 和候选归档结果；重新提取只作为 followup task 返回。

2.5 幂等

高风险命令必须带 commandId 或等价幂等键：

Accept / Reject Suggestion。
Knowledge Draft 确认/忽略。
Planning 保存、候选确认、候选丢弃。
用户知识库资料删除、重建索引、发布提交和知识绑定。
Agent Slot Binding。
市场安装、绑定、购买、发布提交。
New-API 绑定、额度请求、调用归属和配额调整。
导出创建。
来源重验。
管理员激活、回滚、治理处理。

幂等规则：

同一 actor、同一资源、同一动作、同一 commandId、同一请求语义，重复提交必须返回第一次结果或当前可恢复状态。
同一 commandId 但请求语义不同，返回 IDEMPOTENCY_CONFLICT。
预检、handoff 和下载凭证这类一次性资源必须区分“重复查询结果”和“重复消费写入”。

2.6 权限和审计

入口	必须校验	审计要求
`/admin-api/**`	后台登录、菜单/操作权限、数据范围、分权复核、高危动作理由	操作日志；高危治理进入业务审计
`/app-api/**`	登录身份、资源 owner、作品访问权、知识库授权、市场许可、来源状态	用户决策、正文写入、知识确认、导出、授权消费进入业务审计
系统任务 / 内部回调	服务身份、任务 owner、幂等键、回调签名或内部通道	任务日志、失败原因、重试组和补偿记录

管理员可见摘要不等于可见私有正文。需要查看用户私有内容时，必须另有合规访问接口、最小字段、原因、时效、分权和审计；不得用通用内容列表绕过。

3. Admin APIs

3.1 治理和元结构

方法	路径	说明
GET	`/admin-api/muse/governance/meta-schemas`	MetaSchema 列表和版本摘要
GET	`/admin-api/muse/governance/meta-schemas/{schemaKey}`	Schema 详情、当前 active 版本、灰度版本、字段继承和影响摘要
GET	`/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}`	指定版本详情、字段、校验规则、可见性策略和发布记录
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts`	保存 MetaSchema 草稿，返回 draftVersion 和校验摘要
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/validate`	校验字段类型、必填、枚举、引用、兼容性和保护节点边界
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/impact-preview`	影响预览，返回作品、规划、知识投影、AI 上下文和导出影响
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/publish`	发布版本，必须带 commandId、理由、校验结果和影响预览引用
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/activate`	激活 MetaSchema 版本，支持全量或灰度范围
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/rollback`	回滚到指定已发布版本，触发投影失效或重建任务
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/deprecate`	废弃版本或字段，必须给出替代字段、保留期和迁移提示
POST	`/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/gray-rules`	设置或调整灰度规则，返回灰度范围和回滚入口
GET	`/admin-api/muse/governance/protection-nodes`	保护节点注册表、权限点、不可替换原因和审计摘要
GET	`/admin-api/muse/governance/protection-nodes/{nodeKey}`	保护节点详情、所属链路、Shadow -> Canonical 边界和可观测指标
GET	`/admin-api/muse/governance/function-chains`	系统功能链路和开放槽位
POST	`/admin-api/muse/governance/function-chains/{chainKey}/impact-preview`	发布前影响预览
POST	`/admin-api/muse/governance/function-chains/{chainKey}/versions/{version}/activate`	激活功能链路版本

治理接口是管理后台 surface，不是独立业务 owner。MetaSchema 写入 content，保护节点、系统功能链路和质量策略写入 ai，system 只提供后台权限；这些接口不直接写用户作品事实。

MetaSchema 管理命令必须带 commandId、操作者、权限点、变更理由、expectedVersion、校验结果引用和影响预览引用。发布、激活、回滚、废弃和灰度调整都必须写操作日志和业务审计；失败时返回可恢复的 currentVersion、validationErrors、affectedProjectionCount 和 nextActions。

MetaField 可见性字段至少包含：

字段	语义
`uiVisible`	是否进入用户可见投影
`aiContext`	是否允许进入 AI 上下文组装
`userEditable`	用户端是否允许保存该动态字段
`userSearchable`	是否允许用户搜索或筛选
`exportable`	是否可被导出预检纳入

uiVisible=false 不代表不能进入 AI 上下文；aiContext=true 不代表用户可见；exportable=true 仍必须受 owner、授权、来源状态和导出许可约束。字段废弃不能删除历史数据，只能让新保存、投影、检索和导出按 FIELD_DEPRECATED 或迁移提示处理。

保护节点 API 必须显式返回权限要求、审计要求、不可替换原因和 Shadow -> Canonical 责任边界。管理员只能治理系统链路和开放槽位，不能把输入输出合规、拆分切块、入 RAG、语义安全围栏、静态检查、质量门控等保护节点降级成普通用户可替换槽位。

3.2 内容管理

方法	路径	说明
GET	`/admin-api/muse/content/works`	查询作品列表和治理摘要
GET	`/admin-api/muse/content/works/{workId}`	查看作品元信息、章节摘要、异常摘要
GET	`/admin-api/muse/content/works/{workId}/chapters`	查看章节列表
GET	`/admin-api/muse/content/import-tasks`	查询导入任务
GET	`/admin-api/muse/content/export-tasks`	查询导出任务
POST	`/admin-api/muse/content/works/{workId}/risk-actions`	异常内容治理动作

管理员内容接口默认不返回用户私有正文全文。确需查看必须另有合规访问设计、审计和最小化字段。

3.3 知识管理

方法	路径	说明
GET	`/admin-api/muse/knowledge/global-kbs`	全局知识库列表
POST	`/admin-api/muse/knowledge/global-kbs`	创建全局知识库
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}`	全局知识库详情、当前版本、授权策略、来源状态和处理摘要
PATCH	`/admin-api/muse/knowledge/global-kbs/{kbId}`	更新名称、说明、分类、可见范围和停用原因
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}/documents`	资料列表、处理状态、版本和来源摘要
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/documents`	上传或登记资料，返回 documentId 和处理任务
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}/documents/{documentId}`	资料详情、版本、解析状态和索引状态
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/documents/{documentId}/versions`	新增资料版本，触发处理任务
DELETE	`/admin-api/muse/knowledge/global-kbs/{kbId}/documents/{documentId}`	停用资料，触发来源事件和索引刷新
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}/versions`	知识库版本列表和发布摘要
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/versions/{version}/activate`	激活知识库版本
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies`	授权策略列表和 active 摘要
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies/drafts`	保存授权策略草稿
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/access-policies/drafts/{draftId}/publish`	发布授权策略，必须带 commandId 和影响预览
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/enable`	启用全局知识库
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/disable`	停用全局知识库，触发来源事件
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/impact-preview`	影响预览，返回授权、绑定、检索、导出和运行任务影响
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/reindex`	重建索引，返回处理任务
GET	`/admin-api/muse/knowledge/global-kbs/{kbId}/processing-tasks`	资料处理、索引和投影任务状态
POST	`/admin-api/muse/knowledge/global-kbs/{kbId}/source-events`	触发来源事件，传播 revoked / recalled / blocked / needs_recheck
GET	`/admin-api/muse/knowledge/source-bindings`	查询来源绑定和状态
GET	`/admin-api/muse/knowledge/drafts`	查询知识草稿治理摘要
GET	`/admin-api/muse/knowledge/projection-tasks`	查询知识投影和索引任务

管理员可治理来源、全局知识库和异常草稿，但不替普通用户确认单作品 Local KB。

全局知识库启停、版本激活、资料停用、授权策略发布和来源事件触发都必须带 commandId、操作者、原因、影响预览引用和审计字段。授权策略缺 active 版本时，全局知识库不得展示、检索、进入 AI 上下文或参与导出。

3.4 AI 管理

方法	路径	说明
GET	`/admin-api/muse/ai/prompts`	Prompt 列表
POST	`/admin-api/muse/ai/prompts/{promptKey}/versions`	新建 Prompt 版本
POST	`/admin-api/muse/ai/prompts/{promptKey}/versions/{version}/activate`	激活 Prompt 版本
GET	`/admin-api/muse/ai/agents`	Agent 列表
POST	`/admin-api/muse/ai/agents`	创建系统 Agent
POST	`/admin-api/muse/ai/agents/{agentId}/versions`	新建 Agent 版本
GET	`/admin-api/muse/ai/tool-grants`	Tool Grant 列表
POST	`/admin-api/muse/ai/tool-grants`	创建或调整工具授权
GET	`/admin-api/muse/ai/tasks`	AI 任务列表
GET	`/admin-api/muse/ai/quality-policies`	质量策略列表
POST	`/admin-api/muse/ai/quality-policies/{policyKey}/versions`	新建质量策略版本
POST	`/admin-api/muse/ai/evaluation-runs`	启动离线评估
GET	`/admin-api/muse/ai/evaluation-runs/{runId}`	查询离线评估运行

AI 管理接口不得返回 New-API token 明文、完整 Prompt/Response、私有正文全文、外部知识全文、New-API provider authority、供应商路由、供应商密钥、底层成本策略或网关调用权威日志。管理员只能配置 Muse 侧 Prompt、Agent 编排、质量策略、工具授权和评测运行；New-API 网关用户、额度请求、余额快照和调用归属只通过账户/集成接口暴露摘要。

3.5 市场管理

方法	路径	说明
GET	`/admin-api/muse/market/assets`	市场资产列表
GET	`/admin-api/muse/market/assets/{assetId}`	市场资产详情、版本、授权、安装、治理和来源摘要
GET	`/admin-api/muse/market/publish-requests`	发布申请列表
POST	`/admin-api/muse/market/publish-requests/{requestId}/approve`	审核通过
POST	`/admin-api/muse/market/publish-requests/{requestId}/reject`	审核拒绝
POST	`/admin-api/muse/market/assets/{assetId}/governance-impact`	治理影响预览，返回购买、安装、绑定、handoff、导出和个人中心影响
POST	`/admin-api/muse/market/assets/{assetId}/delist`	下架
POST	`/admin-api/muse/market/assets/{assetId}/recall`	召回
GET	`/admin-api/muse/market/appeals`	申诉列表
GET	`/admin-api/muse/market/appeals/{appealId}`	申诉详情、补充材料和处理审计
POST	`/admin-api/muse/market/appeals/{appealId}/resolve`	处理申诉

召回、下架、blocked 必须触发 Source Status Event。

3.6 账户管理

方法	路径	说明
GET	`/admin-api/muse/account/users`	用户账户摘要
GET	`/admin-api/muse/account/users/{userId}/entitlements`	权益和配额
POST	`/admin-api/muse/account/users/{userId}/quota-adjustments`	调整配额
GET	`/admin-api/muse/account/users/{userId}/quota-adjustments`	配额调整 ledger，展示调整来源、幂等键、前后快照和审计状态
GET	`/admin-api/muse/account/new-api-bindings`	网关用户绑定状态列表
POST	`/admin-api/muse/account/users/{userId}/new-api-binding`	创建或刷新 New-API 网关用户绑定
POST	`/admin-api/muse/account/users/{userId}/quota-requests`	向 New-API 发起额度配置请求，返回 requestId 和 correlationId
GET	`/admin-api/muse/account/users/{userId}/balance-snapshots`	New-API 余额和权益快照摘要
POST	`/admin-api/muse/account/call-attribution-jobs`	创建调用归属 job，绑定用户、任务、作品、智能体、知识来源或市场授权
GET	`/admin-api/muse/account/call-attribution-jobs/{jobId}`	查询调用归属状态、失败原因和补偿建议
GET	`/admin-api/muse/account/integration-calls/by-correlation/{correlationId}`	按 correlationId 查询外部调用去重、重试组和归属状态
GET	`/admin-api/muse/account/usage-records`	用量摘要
GET	`/admin-api/muse/account/purchase-records`	购买记录摘要

支付底层交易、退款和充值能力优先复用 yudao-module-pay。

Quota adjustment ledger 是账户侧 append-only 语义：每次人工调整、套餐变更、市场补偿、导出扣减回滚或 New-API 配置请求回填都必须记录 commandId、correlationId、调整原因、前后权益快照、操作者、审批或复核信息和幂等状态。ledger 不是 New-API 成本账本 authority，也不能被 AI 管理接口用来推断供应商路由或底层成本。

3.7 任务、来源事件和审计

方法	路径	说明
GET	`/admin-api/muse/jobs`	查询 Muse 异步任务
GET	`/admin-api/muse/jobs/{jobId}`	查看任务详情、失败原因和重试组
POST	`/admin-api/muse/jobs/{jobId}/retry`	有权限重试可重试任务
POST	`/admin-api/muse/jobs/{jobId}/cancel`	取消可取消任务
GET	`/admin-api/muse/source-events`	查询来源状态事件和影响范围
GET	`/admin-api/muse/source-events/{eventId}`	来源事件详情
POST	`/admin-api/muse/source-events/{eventId}/retry`	重试来源传播
GET	`/admin-api/muse/audit/business-events`	查询业务审计摘要

任务治理不能绕过 owner 边界。重试来源传播只能让受影响对象进入重验、禁用、失效或摘要刷新，不能改写已确认 Canonical。

4. App APIs

4.1 当前用户和入口

方法	路径	说明
GET	`/app-api/muse/me`	当前用户、权益摘要、默认入口、可见产品空间

/app-api/muse/me 不返回系统权限表、后台菜单、New-API token、Prompt secret 或私有审计字段。

4.2 通用任务和来源状态

方法	路径	说明
GET	`/app-api/muse/jobs/{jobId}`	查询当前用户可见任务
POST	`/app-api/muse/jobs/{jobId}/cancel`	取消当前用户可取消任务
POST	`/app-api/muse/source-status/query`	按上下文查询来源对当前用途、目标 owner 和目标对象的可用状态
POST	`/app-api/muse/source-status/recheck`	按上下文发起来源重验

用户端只能查看自己有权访问的任务和来源摘要。来源重验是任务，不直接恢复绑定、确认或导出许可。

Source Status 请求必须带业务上下文，不能只用 sourceType + sourceId 做泛查询：

字段	要求
`sourceType` / `sourceId`	来源对象
`purpose`	`bind` / `generate` / `export` / `publish` / `confirm` / `install` / `handoff` 等用途
`targetOwner`	`content` / `knowledge` / `ai` / `market` / `account`
`targetId`	目标作品、知识库、槽位、任务、发布申请或导出任务
`sourceVersion`	调用方当前持有的来源版本
`authorizationSnapshotId`	调用方当前持有的授权快照

Source Status 响应必须返回 status、allowed、blockedReasons、needsRecheckReasons、nextActions、currentSourceVersion、currentAuthorizationSnapshotId 和可选 jobId。status 只能是 allowed、blocked、needs_recheck 中的一种；needs_recheck 不等于允许继续写入，目标 owner 必须在自己的命令接口重新校验。

4.3 作品和正文

方法	路径	说明
GET	`/app-api/muse/works`	我的作品列表
POST	`/app-api/muse/works`	新建作品
GET	`/app-api/muse/works/{workId}`	作品详情
PATCH	`/app-api/muse/works/{workId}`	修改作品基础信息
GET	`/app-api/muse/works/{workId}/chapters`	章节列表
POST	`/app-api/muse/works/{workId}/chapters`	新建章节
GET	`/app-api/muse/chapters/{chapterId}/blocks`	Block 列表
POST	`/app-api/muse/chapters/{chapterId}/blocks`	新建 Block
PUT	`/app-api/muse/blocks/{blockId}`	保存 Block，必须带 expectedRevision
GET	`/app-api/muse/blocks/{blockId}/source-attribution`	查看当前 Block revision 来源归因
GET	`/app-api/muse/works/{workId}/meta-projections`	查询作品维度用户可见 MetaSchema 投影
GET	`/app-api/muse/works/{workId}/meta-projections/{projectionKey}`	查询指定投影结构、字段数据和版本
POST	`/app-api/muse/works/{workId}/dynamic-fields/validate`	校验动态字段数据，不写入
PUT	`/app-api/muse/works/{workId}/dynamic-fields/{targetType}/{targetId}`	保存动态字段数据，必须带 expectedDataRevision

作品维度可见投影不是事实源，只是 MetaSchema、用户权限、来源状态和目标对象版本计算后的 read model。投影响应至少返回：

字段	语义
`schemaVersion`	本次投影使用的 MetaSchema active 或灰度版本
`projectionVersion`	可见投影版本，用于判断前端缓存是否过期
`dataRevision`	目标对象动态字段数据 revision
`sourceSnapshot`	来源对象、来源版本、授权快照和来源状态摘要
`fields`	仅包含当前用户可见、可编辑、可搜索或可导出的字段策略

动态字段保存必须校验 schemaVersion、projectionVersion、expectedDataRevision、字段可编辑性、来源状态和目标 owner 权限。Schema 过期返回 SCHEMA_STALE；字段已废弃返回 FIELD_DEPRECATED；投影过期返回 PROJECTION_STALE，响应 data 必须带当前版本和刷新入口。

4.4 作品规划

作品规划台面向作品设定、章节大纲、世界设定、角色关系、情节节拍和文风检查。规划正式数据由用户确认后进入 content owner；AI 只能产生 Planning Candidate，不直接写正式规划。

方法	路径	说明
GET	`/app-api/muse/works/{workId}/planning`	查询当前作品可见规划结构、已确认规划数据、revision 和来源摘要
PUT	`/app-api/muse/works/{workId}/planning/{sectionKey}`	保存规划项，必须带 commandId 和 expectedRevision
POST	`/app-api/muse/works/{workId}/planning/candidates`	创建规划候选任务，支持生成、补全、整理和多组选项
GET	`/app-api/muse/works/{workId}/planning/candidates`	查询待确认、已确认和已丢弃规划候选
GET	`/app-api/muse/works/{workId}/planning/candidates/{candidateId}`	查询候选详情、来源、质量结果和 diff
POST	`/app-api/muse/works/{workId}/planning/candidates/{candidateId}/confirm`	确认候选进入正式规划，必须带 commandId 和 expectedRevision
POST	`/app-api/muse/works/{workId}/planning/candidates/{candidateId}/discard`	丢弃候选，必须带 commandId 和原因
POST	`/app-api/muse/works/{workId}/planning/style-checks`	创建文风检查任务，返回 jobId
GET	`/app-api/muse/works/{workId}/planning/style-checks/{jobId}`	查询文风检查结果、风险标记和建议入口

规划保存、候选确认和候选丢弃请求必须包含：

字段	要求
`commandId`	幂等键
`expectedRevision`	目标规划 section 或候选 revision
`sourceSnapshot`	输入正文、知识、市场资产或全局知识的来源快照摘要
`authorizationSnapshotId`	生成或确认时使用的授权快照
`sourceVersion`	调用方持有的来源版本
`auditReason`	用户确认、丢弃、覆盖或重新生成原因

Planning Candidate 是 Shadow 对象；确认时目标 owner 必须重验 work 权限、候选状态、来源状态、授权快照、质量结果和目标 revision。确认成功只写正式规划项和业务审计，不写正文或 Local KB；失败返回 REVISION_CONFLICT、SOURCE_NEEDS_RECHECK、SOURCE_BLOCKED、QUALITY_BLOCKED 或 PRECHECK_EXPIRED。

4.5 AI 候选

方法	路径	说明
POST	`/app-api/muse/ai/tasks`	创建生成、续写、扩写、润色、检测、规划任务
GET	`/app-api/muse/ai/tasks/{taskId}`	查询任务
GET	`/app-api/muse/works/{workId}/suggestions`	当前作品候选列表
GET	`/app-api/muse/suggestions/{suggestionId}`	候选详情
POST	`/app-api/muse/suggestions/{suggestionId}/accept`	接受候选
POST	`/app-api/muse/suggestions/{suggestionId}/reject`	丢弃候选

Accept 请求语义：

字段	要求
`commandId`	幂等键
`expectedRevision`	目标 Block revision
`acceptMode`	`accept_as_is` / `merge_after_edit`
`finalContent`	修改后合并时必填

Accept 响应语义：

Block 新 revision。
Suggestion 归档结果。
Knowledge Draft 结果：原样接受保持待确认；修改后合并让旧草稿失效。
followup task：投影刷新或重新提取。

4.6 知识库和知识草稿

方法	路径	说明
GET	`/app-api/muse/knowledge-bases`	用户知识库和已安装知识库
POST	`/app-api/muse/knowledge-bases`	创建用户知识库
GET	`/app-api/muse/knowledge-bases/{kbId}`	用户知识库详情、资料摘要、版本、来源状态和处理状态
PATCH	`/app-api/muse/knowledge-bases/{kbId}`	更新用户知识库基础信息
POST	`/app-api/muse/knowledge-bases/{kbId}/disable`	停用用户知识库，阻断新绑定和新检索
DELETE	`/app-api/muse/knowledge-bases/{kbId}`	删除用户知识库，按状态进入软删除或异步清理
POST	`/app-api/muse/knowledge-bases/{kbId}/restore`	恢复可恢复的用户知识库
GET	`/app-api/muse/knowledge-bases/{kbId}/documents`	资料列表、版本、处理状态和来源摘要
POST	`/app-api/muse/knowledge-bases/{kbId}/documents`	上传资料，返回 documentId 和处理任务
GET	`/app-api/muse/knowledge-bases/{kbId}/documents/{documentId}/versions`	资料版本列表
POST	`/app-api/muse/knowledge-bases/{kbId}/documents/{documentId}/versions`	上传资料新版本，触发处理任务
DELETE	`/app-api/muse/knowledge-bases/{kbId}/documents/{documentId}`	删除或停用资料，触发来源事件
GET	`/app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}`	查询资料处理、解析、切分、索引或投影任务
POST	`/app-api/muse/knowledge-bases/{kbId}/reindex`	重建索引，返回任务
GET	`/app-api/muse/installed-knowledge-bases`	已安装知识库列表、授权、来源状态和可绑定范围
POST	`/app-api/muse/installed-knowledge-bases/{installId}/disable`	停用已安装知识库
DELETE	`/app-api/muse/installed-knowledge-bases/{installId}`	删除已安装知识库记录，不删除来源市场资产
POST	`/app-api/muse/installed-knowledge-bases/{installId}/restore`	恢复已安装知识库
POST	`/app-api/muse/knowledge-bases/{kbId}/publish-prechecks`	发布准备预检，返回 marketPublishCheckId 或阻断原因
POST	`/app-api/muse/knowledge-bases/{kbId}/publish-snapshots`	生成发布快照，固化版本、授权和来源摘要
POST	`/app-api/muse/knowledge-bases/{kbId}/publish-requests`	提交发布申请，消费 marketPublishCheckId 和发布快照
GET	`/app-api/muse/works/{workId}/local-knowledge`	作品 Local KB
GET	`/app-api/muse/works/{workId}/knowledge-drafts`	待确认知识草稿
POST	`/app-api/muse/knowledge-drafts/{draftId}/confirm`	确认知识草稿
POST	`/app-api/muse/knowledge-drafts/{draftId}/ignore`	忽略知识草稿
POST	`/app-api/muse/knowledge-drafts/{draftId}/recheck`	重验来源
POST	`/app-api/muse/works/{workId}/knowledge-bindings`	绑定用户/市场知识库
DELETE	`/app-api/muse/works/{workId}/knowledge-bindings/{bindingId}`	解绑作品知识来源
POST	`/app-api/muse/knowledge-bases/{kbId}/export-tasks`	创建知识库导出任务

知识草稿确认必须重新校验来源状态、授权快照、source hash、目标版本和风险标记。

知识绑定命令必须消费 kbBindPrecheckId，并显式传入 commandId、workId、targetOwner=knowledge、targetId、sourceType、sourceId、sourceVersion、authorizationSnapshotId 和 expectedBindingRevision。市场模块只能生成或查询绑定预检；绑定写入必须由 Knowledge owner 重新校验并原子消费预检。

资料上传、删除、重建索引、停用、恢复和发布提交都必须写审计。资料处理任务失败时返回 jobId、retryable、failedStage、blockedReason 和 nextActions；删除或停用资料必须触发来源事件，让绑定、检索、生成、导出和个人中心摘要进入 blocked 或 needs_recheck。

4.7 智能体工作台

方法	路径	说明
GET	`/app-api/muse/agents`	用户可用智能体列表
POST	`/app-api/muse/agents`	创建用户智能体
POST	`/app-api/muse/agents/{agentId}/versions`	新建版本
POST	`/app-api/muse/agents/{agentId}/test`	试用
GET	`/app-api/muse/works/{workId}/agent-slots`	作品槽位
POST	`/app-api/muse/works/{workId}/agent-slots/{slotKey}/bind`	绑定槽位，消费预检

用户只能替换开放槽位，不能替换输入输出合规、拆分切块、入 RAG、语义安全围栏、静态检查、质量门控等保护节点。

槽位绑定命令必须显式声明：

字段	要求
`agentSlotPrecheckId`	市场或目标空间生成的槽位绑定预检，必须由 AI owner 原子消费
`commandId`	幂等键
`workId` / `slotKey`	目标作品和开放槽位
`targetOwner` / `targetId`	目标 owner 和目标对象，不能由前端自造 owner
`sourceAgentId` / `sourceAgentVersion`	绑定来源智能体和版本
`authorizationSnapshotId`	授权快照
`expectedSlotRevision`	目标槽位当前 revision

绑定成功只写 Agent Slot Binding、绑定来源、版本、工具授权快照和审计，不修改保护节点定义。sourceAgentVersion、授权快照、来源状态或槽位 revision 变化时必须返回 SOURCE_NEEDS_RECHECK、SOURCE_BLOCKED、PRECHECK_EXPIRED 或 REVISION_CONFLICT。

4.8 市场

方法	路径	说明
GET	`/app-api/muse/marketplace/assets`	市场资产列表
GET	`/app-api/muse/marketplace/categories`	分类曝光、推荐位、排序和可见性摘要
GET	`/app-api/muse/marketplace/assets/{assetId}`	资产详情
POST	`/app-api/muse/marketplace/assets/{assetId}/favorite`	收藏资产
DELETE	`/app-api/muse/marketplace/assets/{assetId}/favorite`	取消收藏
POST	`/app-api/muse/marketplace/assets/{assetId}/purchase`	购买或获取授权
POST	`/app-api/muse/marketplace/assets/{assetId}/install`	安装智能体或知识库
POST	`/app-api/muse/marketplace/assets/{assetId}/bind-precheck`	绑定/使用预检
POST	`/app-api/muse/marketplace/handoffs`	创建市场 handoff，只返回短期 handoff 和目标 owner 消费入口
GET	`/app-api/muse/marketplace/handoffs/{handoffId}`	查询 handoff 状态、过期时间和目标 owner
POST	`/app-api/muse/marketplace/handoffs/{handoffId}/cancel`	取消市场 handoff
POST	`/app-api/muse/marketplace/publish-drafts`	保存发布草稿
POST	`/app-api/muse/marketplace/publish-drafts/{draftId}/checks`	发布检查，生成 marketPublishCheckId
POST	`/app-api/muse/marketplace/publish-requests`	提交发布申请，消费 marketPublishCheckId 和发布快照
POST	`/app-api/muse/marketplace/publish-requests/{requestId}/withdraw`	撤回发布申请
GET	`/app-api/muse/marketplace/my-publish-records`	我的发布记录
GET	`/app-api/muse/marketplace/assets/{assetId}/governance-impact`	查看下架、召回、授权变化对本人安装、绑定、导出和任务的影响
POST	`/app-api/muse/marketplace/appeals`	提交申诉
POST	`/app-api/muse/marketplace/appeals/{appealId}/supplements`	补充申诉材料
POST	`/app-api/muse/marketplace/appeals/{appealId}/withdraw`	撤回申诉

作品资产 feature gate 未开启前，只允许阅读、收藏和授权记录，不允许模板化、参考写入或进入 AI 上下文。

市场接口的返回必须区分 licenseStatus、installStatus、bindStatus、sourceStatus 和 nextAction。购买或安装成功只表示账户可用资产变化；绑定或使用必须由目标 owner 消费预检后完成。

Market 只负责资产、授权、安装记录、发布申请、申诉、预检和 handoff 生命周期。Market API 可以生成、查询、取消 handoff，但不能写作品正文、正式规划、Local KB、Agent Slot Binding 或动态字段数据；目标 owner API 必须消费 marketPublishCheckId、kbBindPrecheckId、agentSlotPrecheckId 或 handoff，并重新校验 owner、目标对象、来源版本、授权快照、状态机和幂等键。

4.9 导入导出

方法	路径	说明
POST	`/app-api/muse/works/{workId}/import-tasks`	上传并创建导入任务
GET	`/app-api/muse/import-tasks/{taskId}`	查询导入任务
POST	`/app-api/muse/works/{workId}/parse-tasks`	创建全书解析任务
GET	`/app-api/muse/parse-tasks/{taskId}`	查询解析任务
POST	`/app-api/muse/parse-tasks/{taskId}/retry`	重试可重试解析任务或失败阶段
GET	`/app-api/muse/parse-tasks/{taskId}/chapters`	章节解析结果
POST	`/app-api/muse/parse-chapters/{chapterResultId}/confirm`	章节确认进入知识草稿处理
POST	`/app-api/muse/parse-chapters/{chapterResultId}/reject`	章节驳回，记录原因并作废对应 Shadow 结果
POST	`/app-api/muse/parse-tasks/{taskId}/chapters/batch-confirm`	批量确认章节，返回逐章成功、失败和部分失败摘要
POST	`/app-api/muse/works/{workId}/export-tasks`	创建导出任务
GET	`/app-api/muse/export-tasks/{taskId}`	查询导出任务
GET	`/app-api/muse/downloads/{credentialId}`	下载导出包

章节确认接口只表示章节解析审阅通过并进入知识草稿处理，不写正式知识。章节驳回必须写用户原因、当前 parse result revision 和审计，不删除原始导入文件。

Parse task owner 是 content：任务必须绑定 workId、发起人、导入版本、source snapshot、authorization snapshot、解析配置版本和重试组。批量确认以章节为事务边界，允许部分失败；响应必须返回 confirmedChapterIds、failedChapters、skippedChapters、partialFailure=true/false、失败错误码和下一步动作。某章失败不得回滚已成功章节，也不得把跨章节批量确认变成不可解释的单事务写入。

4.10 个人中心

方法	路径	说明
GET	`/app-api/muse/profile`	个人资料
PATCH	`/app-api/muse/profile`	修改资料
GET	`/app-api/muse/account/entitlements`	权益和配额
GET	`/app-api/muse/account/usage`	用量摘要
GET	`/app-api/muse/account/new-api-binding`	当前用户 New-API 网关用户绑定摘要
POST	`/app-api/muse/account/new-api-binding/recheck`	发起网关用户绑定重验
GET	`/app-api/muse/account/balance-snapshots`	余额和权益快照摘要
POST	`/app-api/muse/account/quota-requests`	发起本人套餐或余额同步请求，返回 requestId 和 correlationId
GET	`/app-api/muse/account/quota-requests/{requestId}`	查询额度请求状态、correlationId 和失败原因
GET	`/app-api/muse/account/integration-calls/by-correlation/{correlationId}`	查询本人外部调用去重、重试和归属状态
GET	`/app-api/muse/account/purchases`	购买记录
GET	`/app-api/muse/account/licenses`	授权记录
GET	`/app-api/muse/account/publish-records`	发布记录
GET	`/app-api/muse/account/security-events`	安全事件摘要
POST	`/app-api/muse/account/export-tasks`	创建个人资料、账户记录或安全事件导出任务
GET	`/app-api/muse/account/export-tasks/{taskId}`	查询个人中心导出任务
GET	`/app-api/muse/account/downloads/{credentialId}`	下载个人中心导出包

个人中心是 read model 和跳转入口，不拥有作品、知识、市场资产或 AI 任务事实。

个人中心账户接口只返回当前用户可见的摘要和下载凭证，不暴露 New-API token、provider authority、供应商路由、底层成本账本、完整 Prompt/Response 或私有审计字段。correlationId 查询只能查本人可见调用，重复请求必须返回同一重试组和归属状态，不能重复扣减、重复补偿或重复归属。

5. 通用错误码

错误码	语义	前端建议
`UNAUTHENTICATED`	未登录或登录失效	重新登录
`FORBIDDEN`	无接口或资源权限	展示无权限或申请授权入口
`RESOURCE_NOT_FOUND`	资源不存在或不可见	返回列表或刷新
`VALIDATION_ERROR`	请求字段不合法	定位字段并提示
`REVISION_CONFLICT`	Block revision 冲突	展示冲突恢复信息和当前 revision
`SCHEMA_STALE`	调用方持有的 MetaSchema 版本已过期	刷新 Schema 和投影后重试
`FIELD_DEPRECATED`	动态字段已废弃或不再允许保存	显示迁移提示或隐藏保存入口
`PROJECTION_STALE`	用户可见投影版本已过期	重新拉取投影和字段数据
`STATE_CONFLICT`	当前状态不允许该动作	刷新对象状态和可用动作
`SOURCE_NEEDS_RECHECK`	来源需重验	引导重验或替换来源
`SOURCE_BLOCKED`	来源 revoked / recalled / blocked / owner_missing / unauthorized	禁用确认、绑定、生成或导出动作
`QUALITY_BLOCKED`	候选质量或合规阻断	展示风险和重生成/修改入口
`FEATURE_DISABLED`	feature gate 关闭	隐藏或禁用对应入口
`PRECHECK_REQUIRED`	缺少 handoff/precheck	返回来源空间刷新预检
`PRECHECK_EXPIRED`	handoff/precheck 已过期或已消费	重新发起预检
`MARKET_HANDOFF_INVALID`	handoff 不存在、过期、已取消、已消费或目标 owner 不匹配	返回市场刷新状态并重新发起
`CORRELATION_CONFLICT`	correlationId 对应的外部调用语义不一致	阻断重复请求并展示当前归属状态
`IDEMPOTENCY_CONFLICT`	幂等键与请求语义不匹配	阻断重复提交并提示刷新
`TASK_FAILED`	异步任务失败	展示失败原因、重试或取消
`PARTIAL_FAILURE`	批量操作部分成功、部分失败	展示逐项结果和可重试项
`UPSTREAM_UNAVAILABLE`	New-API、检索、文件或通知服务不可用	展示稍后重试，不暴露密钥或内部响应

错误响应 data 可以按场景携带 currentRevision、currentState、currentSchemaVersion、currentProjectionVersion、currentDataRevision、requiredPrecheckType、sourceStatus、correlationStatus、retryable、jobId、partialResults、nextActions 等可恢复字段，但不得返回密钥、完整 Prompt/Response、私有正文全文或越权来源全文。

6. 非目标

不在本文件复制 Yudao system/infra/pay/bpm 的全部内置接口。
不使用旧版统一入口作为阶段 7 Muse API 入口。
不把管理后台和用户端合并成同一套前端 API。
不允许前端通过隐藏按钮承担安全职责。
不允许 AI 或管理员接口绕过用户主权写 Canonical。

7. 关联阅读

后端工程结构：后端-02-工程结构与模块职责.md
关键流程：后端-03-关键流程实现与接口契约.md
Schema：后端-04-统一数据库Schema-v1.md
前端工程结构：前端-01-工程结构与核心依赖.md
状态机：架构-04-状态机与约束清单.md

41 KiB Raw Blame History Unescape Escape