oh-my-muse/design-docs/后端-05-统一API契约-v1.md

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

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

1. 总体原则

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

入口	调用方	语义
/admin-api/**	muse-admin/	管理后台接口
/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 token 和跳转审计；目标 owner precheck/session 必须由目标 owner 自己生成和消费，Market 不能直接写作品正文、Local KB 或正式规划。
• Yudao 原生接口只通过引用和集成点使用；除 Muse 二开接口外，不在本文件复制 system、infra、pay、bpm、report、mp 的完整 API。

Muse API 分组与 owner：

分组	入口	owner module	说明
Governance	/admin-api/muse/governance/**	Admin/Governance 逻辑 owner；物理表按对象落到 content / ai；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	yudao-module-member（已决策：member 模块实现 account API 路径）	权益、配额、用量、授权/购买/发布摘要
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、幂等键、回调签名或内部通道	任务日志、失败原因、重试组和补偿记录

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

2.7 API 版本策略

API 版本通过 HTTP Header 传递，路由路径不变：

项目	说明
Header	X-API-Version: 1（当前版本为 1）
默认行为	未传 header 时使用最新稳定版本
版本影响范围	响应结构和字段语义；不影响路由路径和认证方式
Deprecation Policy	旧版本至少保留 6 个月；期间响应头返回 Deprecation: true 和 Sunset: <date> 提示迁移
到期行为	到期后返回 API_VERSION_DEPRECATED 错误码，HTTP 410 Gone
版本变更触发条件	响应字段删除、字段语义不兼容变更、枚举值语义变化
非破坏性变更	新增可选字段、新增枚举值、新增接口不触发版本升级

客户端集成要求：

• 前端 SDK 和 API 客户端必须显式传递 X-API-Version header。
• 后端网关层解析 header 并注入请求上下文，各模块 controller 按版本返回对应响应结构。
• 版本不匹配或已废弃时，响应 body 必须包含 currentVersion、supportedVersions 和 migrationGuide 字段。

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，也是 MetaSchema、系统链路和保护节点的逻辑 owner。MetaSchema 物理表可以落在 content，保护节点、系统功能链路和质量策略物理表可以落在 ai，但写入必须经 Governance/Admin facade、影响预览、版本发布和审计；Content 或 AI 的 app/admin 业务接口不能绕过治理 facade 修改结构或保护节点。这些接口不直接写用户作品事实。

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	触发来源事件，传播 SourceEventType、SourceStatus、SourceActionPolicy 和原因归因
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 网关用户、额度请求、余额快照和调用归属只通过账户/集成接口暴露摘要。

Tool Grant 写入必须经 Governance / Security facade 校验审批、用途、外发策略、预算、来源和审计要求；AI 管理接口只能展示或提交待审授权草稿，不能让 yudao-module-ai、Prompt、模型输出或用户智能体自授工具、上下文、外发和预算权限。运行时权限以 Runtime Permission Envelope 为准，前端传入的权限声明只作请求意图。

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

Pay callback、refund、套餐撤销和市场补偿必须通过 account entitlement 可变表 + 审计日志幂等传播：以支付订单、退款单、市场授权或调额请求作为 sourceOwner/sourceId，以回调或补偿事件作为 idempotencyKey。重复回调返回同一处理结果；退款和撤销使用反向变更更新可变表并写审计日志。

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 响应必须返回 sourceStatus、actionPolicy、blockedReasons、needsRecheckReasons（注：needsRecheckReasons 是 ActionPolicy 层面的补充信息，说明为何 actionPolicy=needs_recheck，不是 SourceStatus 枚举值）、reasonAttributions、sourceEvents、nextActions、currentSourceVersion、currentAuthorizationSnapshotId 和可选 jobId。sourceStatus 使用 SourceStatus：active、stale、revoked、recalled、delisted、blocked、owner_missing、unauthorized；actionPolicy 使用 SourceActionPolicy：allowed、read_only、blocked、needs_recheck。API 不能只返回一个 blocked=true，必须保留 revoked / recalled / delisted / unauthorized / processing_failed 等原因和归因；read_only 只允许历史查看或授权记录展示，不允许写入、绑定、生成、接受候选或受限导出；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 来源归因

Block 保存（PUT /blocks/{blockId}）响应除返回新 revision 外，可包含 followupTasks 字段：

字段	类型	说明
revision	int	保存成功后的新 revision
wordCount	int	当前字数
followupTasks	array	可选，保存后触发的异步任务摘要列表，例如知识提取任务

followupTasks 数组元素结构：

字段	类型	说明
taskType	enum	knowledge_extraction / source_recheck / projection_refresh
jobId	string	异步任务 ID，可用于轮询
status	enum	queued / skipped
reason	string	若 skipped，说明跳过原因（例如无变更、策略未启用）

前端可基于 followupTasks 展示知识提取进度提示或刷新知识草稿列表。followupTasks 为空或不返回时表示无后续异步任务。

| 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 | 校验动态字段数据，不写入 |

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

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

动态字段没有跨 owner 的通用写接口。/dynamic-fields/validate 只做校验和路由建议，不写入任何 Canonical fact；正式写入必须回到目标 owner API，例如规划写 PUT /works/{workId}/planning/{sectionKey}，正文写 PUT /blocks/{blockId}，知识写 Knowledge Draft / Local KB 命令，Agent 写 Agent 配置命令。Owner 命令必须校验 schemaVersion、projectionVersion、expectedDataRevision、字段 allowlist、来源状态和目标 owner 权限。Schema 过期返回 SCHEMA_STALE；字段已废弃返回 FIELD_DEPRECATED；投影过期返回 PROJECTION_STALE；字段试图写 Canonical fact 但没有 owner 命令时返回 FORBIDDEN 或 FEATURE_DISABLED。

各 owner 命令版本校验要求：

Owner 命令	expectedSchemaVersion	expectedProjectionVersion	expectedDataRevision	说明
PUT /blocks/{blockId}	可选（正文保存不依赖动态字段 Schema）	不要求	必须（即 expectedRevision）	正文保存以 Block revision 为乐观锁
PUT /works/{workId}/planning/{sectionKey}	必须	必须	必须	规划保存必须确保 Schema 和投影未过期
POST /knowledge-drafts/{draftId}/confirm	可选	不要求	必须（即 draft version）	知识确认以 draft 状态和来源为准
POST /works/{workId}/agent-slots/{slotKey}/bind	不要求	不要求	必须（即 expectedSlotRevision）	槽位绑定以 slot revision 为乐观锁
PATCH /works/{workId}	必须（若修改动态字段）	必须（若修改动态字段）	必须	作品基础信息修改涉及动态字段时校验
POST /agents/{agentId}/versions	不要求	不要求	不要求	Agent 版本创建不涉及动态字段

规则：

• 涉及 MetaSchema 管控的动态字段写入时，expectedSchemaVersion 和 expectedProjectionVersion 必须校验；不匹配时分别返回 SCHEMA_STALE 和 PROJECTION_STALE。
• 所有写入命令必须校验目标对象的 expectedDataRevision（或等价乐观锁字段）；不匹配时返回 REVISION_CONFLICT 或 DATA_REVISION_CONFLICT。
• 不涉及动态字段的纯正文或纯配置命令可以不要求 expectedSchemaVersion，但必须保留 expectedRevision 乐观锁。

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/ai/tasks/{taskId}/stream	AI 任务 SSE 流式事件（生成增量、质检、结束、错误）
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	丢弃候选

AI 任务流（GET .../ai/tasks/{taskId}/stream）按 SSE 规范发送：event: 行为事件名，data: 行为该事件 payload JSON，id: 行为可续传的事件序号；无事件时发 SSE comment 作为 keepalive。事件契约：

event	data 字段	说明
chunk	content、sequenceNo	Token 级增量文本
quality_check	dimension、score、passed	影子层质检结果
done	taskId、suggestionId（可选 summary）	终态：生成完成；suggestionId 缺失则不发 done
error	code、message	终态：已脱敏错误

待确认（类型不一致）：当前后端实现把 done 的 taskId / suggestionId 按 Long 序列化为 JSON 数字，与本契约中候选/任务 ID 采用的 uuid 字符串（见候选详情等资源）不一致。需后端统一为 uuid 字符串或全局改判；统一前，前端已在 SSE 解析边界将其归一为字符串以保证类型稳定。

Accept 请求语义：

字段	要求
commandId / idempotencyKey	幂等键；二者只允许一个作为稳定业务幂等键，重复请求必须返回同一结果
expectedRevision	目标 Block revision
acceptMode	accept_as_is / merge_after_edit
finalContent	修改后合并时必填
qualityResultVersion	候选质量结果版本
outputComplianceResultId	输出合规结果
staticCheckResultId	静态检查结果
sourceSnapshotId / sourceVersion	候选来源快照和来源版本；接受时实时对比当前来源版本
authorizationSnapshotId	接受时使用的授权快照
workAssetUsePrecheckId	使用市场作品资产作为参考或上下文时必填；feature gate 未开启默认返回 FEATURE_DISABLED
auditReason	用户接受、修改后合并或覆盖原因

Accept 响应语义：

• Block 新 revision。
• Suggestion 归档结果。
• Candidate Decision Archive 引用。
• Block Source Attribution 写入结果，包含 source status、authorization snapshot、lineage 和许可限制。
• Knowledge Draft 结果：原样接受保持待确认；修改后合并让旧草稿失效。
• followup task：投影刷新或重新提取。

Accept / Merge 失败必须返回 blockedReasons、sourceStatusReasons、reasonAttributions、blockSourceAttributionPreview、currentRevision、currentQualityResultVersion、currentAuthorizationSnapshotId、requiredPrecheckType 和 nextActions。后端不得让 stale、revoked、recalled、blocked、owner_missing 或 unauthorized 来源进入 Canonical；也不得把质量版本不匹配、输出合规失败、静态检查失败、市场 feature gate 关闭压缩成普通 STATE_CONFLICT。

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/prechecks	目标 owner 绑定预检，消费市场 handoff 或授权摘要，返回 kbBindPrecheckId
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、目标版本和风险标记。

知识绑定预检和绑定写入都属于 Knowledge owner。Market 只能提供来源侧 handoff token、授权摘要和跳转审计；Knowledge 预检接口必须重新校验 work owner、目标对象、来源版本、授权快照、来源状态、许可范围和幂等键，生成 kbBindPrecheckId 或签名消费凭证。知识绑定命令必须消费 kbBindPrecheckId，并显式传入 commandId、workId、targetOwner=knowledge、targetId、sourceType、sourceId、sourceVersion、authorizationSnapshotId 和 expectedBindingRevision。

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

资料上传必须带 owner、用途、文件名、大小、MIME、hash 和幂等键；服务端必须写扫描状态、存储引用、保留期和清理策略。扫描 blocked / failed 或 MIME、大小、扩展名不匹配时，资料不得进入切块、索引、AI 上下文或市场发布。

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}/prechecks	目标 owner 槽位预检，消费市场 handoff 或授权摘要，返回 agentSlotPrecheckId
POST	/app-api/muse/works/{workId}/agent-slots/{slotKey}/bind	绑定槽位，消费预检

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

智能体试用接口（POST /app-api/muse/agents/{agentId}/test）详情：

试用请求字段：

字段	类型	要求
workId	string	可选，关联作品上下文；不传时使用沙箱上下文
contextScope	enum	none / work / chapter；决定试用时可读取的上下文范围
usagePolicy	enum	charge / free_trial；决定本次试用是否计费
outputTarget	enum	preview_only / shadow；preview_only 只返回预览不落库，shadow 写入 Shadow Candidate 供后续决策
input	object	试用输入内容，包含 prompt 或指令
commandId	string	幂等键

试用响应字段：

字段	类型	说明
trialSessionId	string	本次试用会话 ID，用于关联后续查询和审计
outputPreview	object	智能体输出预览内容
usageCharged	boolean	本次试用是否实际计费
outputDestination	string	输出实际落点：preview_only / shadow_candidate
jobId	string	若异步执行，返回任务 ID 供轮询

约束：

• contextScope=work 或 chapter 时，必须校验用户对 workId 的访问权限。
• usagePolicy=free_trial 受账户免费试用额度限制；额度耗尽时返回 QUOTA_EXCEEDED。
• outputTarget=shadow 时，输出进入 Shadow Candidate 状态，用户可后续接受或丢弃。
• 试用不写正文 Canonical、Local KB 或正式规划。
• Runtime Permission Envelope 由服务端按试用场景生成，scope 受限于试用上下文。

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

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

绑定成功只写 Agent Slot Binding、绑定来源、版本、工具授权快照和审计，不修改保护节点定义。Market 只能提供来源侧 handoff token 和授权摘要，不能写 agentSlotPrecheckId 或槽位事实。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/recommendations	个性化推荐资产列表
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	创建来源侧授权摘要和 handoff 准备，不返回目标 owner 写入凭证
POST	/app-api/muse/marketplace/handoffs	创建市场 handoff，只返回短期 handoff 和目标 owner 消费入口
GET	/app-api/muse/marketplace/handoffs/{handoffToken}	查询 handoff 状态、过期时间和目标 owner
POST	/app-api/muse/marketplace/handoffs/{handoffToken}/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 上下文；相关 target owner 预检和绑定/使用命令默认返回 FEATURE_DISABLED，直到 Content / AI owner、API、Schema、lineage 和导出限制闭合。

市场资产列表查询（GET /app-api/muse/marketplace/assets）排序和筛选参数：

参数	类型	说明
sortBy	enum	popularity / newest / rating / relevance；默认 relevance
assetType	enum	work / agent / knowledge_base；可选筛选
category	string	分类筛选
keyword	string	关键词搜索
pageNo / pageSize	int	分页参数

个性化推荐接口（GET /app-api/muse/marketplace/recommendations）参数：

参数	类型	说明
recommendationContext	enum	可选，home / after_install / similar_to_asset / work_context；决定推荐策略
referenceAssetId	string	可选，similar_to_asset 时必填，基于该资产推荐相似资产
workId	string	可选，work_context 时可填，基于作品上下文推荐适配的智能体或知识库
limit	int	推荐数量上限，默认 10

推荐响应返回 assets 列表和 recommendationId（用于后续点击归因和推荐效果追踪）。推荐不暴露用户私有正文或知识内容作为推荐依据。

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

Market 只负责资产、授权、安装记录、发布申请、申诉、来源侧授权摘要、handoff token 和跳转审计。Market API 可以生成、查询、取消 handoff，但不能写作品正文、正式规划、Local KB、Agent Slot Binding、目标 precheck/session 或动态字段数据；目标 owner API 必须基于 handoff token 或授权摘要自行生成并消费 kbBindPrecheckId、agentSlotPrecheckId、workAssetUsePrecheckId 或签名消费凭证，并重新校验 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-jobs	创建 AI 全书解析任务，读取 Content 导入文件或章节上下文
GET	/app-api/muse/parse-jobs/{jobId}	查询 AI 解析任务
POST	/app-api/muse/parse-jobs/{jobId}/retry	重试可重试解析任务或失败阶段
GET	/app-api/muse/parse-jobs/{jobId}/chapters	AI 章节解析结果
POST	/app-api/muse/chapter-parse-results/{resultId}/confirm	章节审阅确认，通知 Knowledge 生成或刷新知识草稿
POST	/app-api/muse/chapter-parse-results/{resultId}/reject	章节驳回，记录原因并作废对应 AI Shadow 结果
POST	/app-api/muse/parse-jobs/{jobId}/chapters/batch-confirm	批量确认章节，返回逐章成功、失败和部分失败摘要
POST	/app-api/muse/works/{workId}/export-tasks	创建导出任务
GET	/app-api/muse/export-tasks/{taskId}	查询导出任务
GET	/app-api/muse/downloads/{credentialId}	下载导出包

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

Import task、import file 和 chapter context owner 是 content；Parse Job 和 Chapter Parse Result owner 是 ai；Knowledge Draft owner 是 knowledge。Parse Job 必须绑定 workId、发起人、Content 上下文引用、source snapshot、authorization snapshot、解析配置版本、Runtime Permission Envelope 和重试组。批量确认以章节为事务边界，允许部分失败；响应必须返回 confirmedChapterResultIds、createdDraftIds、failedChapters、skippedChapters、partialFailure=true/false、失败错误码和下一步动作。某章失败不得回滚已成功章节，也不得把跨章节批量确认变成不可解释的单事务写入。

导入上传必须绑定 owner、用途、大小、MIME、hash、扫描状态、source snapshot、authorization snapshot、保留期和清理策略；扫描 blocked / failed 的文件不得创建 Parse Job。下载凭证必须携带来源传播版本和授权快照，来源 revoked / recalled / blocked / unauthorized 或授权过期时返回 SOURCE_BLOCKED、SOURCE_NEEDS_RECHECK 或 PRECHECK_EXPIRED，不能继续下载。

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	安全事件摘要
GET	/app-api/muse/account/security-events/{eventId}	安全事件详情，返回事件类型、发生时间、来源 IP、设备信息、影响范围和处理建议
POST	/app-api/muse/account/security-events/{eventId}/acknowledge	确认/处理安全事件，标记用户已知晓或已采取措施
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 查询只能查本人可见调用，重复请求必须返回同一重试组和归属状态，不能重复扣减、重复补偿或重复归属。

安全事件详情接口（GET /app-api/muse/account/security-events/{eventId}）响应字段：

字段	类型	说明
eventId	string	安全事件 ID
eventType	enum	login_anomaly / credential_expired / sensitive_export / access_denied_burst / device_change / permission_escalation
severity	enum	info / warning / critical
occurredAt	datetime	事件发生时间
sourceIp	string	来源 IP 地址
deviceInfo	object	设备信息摘要（UA、平台、地理位置）
affectedScope	string	影响范围描述
description	string	事件描述
suggestedActions	array	建议处理措施列表
acknowledgedAt	datetime	用户确认时间，未确认为空
acknowledgedAction	string	用户确认时选择的处理措施

安全事件确认接口（POST /app-api/muse/account/security-events/{eventId}/acknowledge）请求字段：

字段	类型	要求
commandId	string	幂等键
action	enum	acknowledged / password_changed / session_revoked / false_positive
note	string	可选，用户备注

约束：

• 安全事件只能由事件所属用户查看和确认。
• 确认操作是 append-only，不删除安全事件记录。
• action=session_revoked 时，后端应联动 session 管理服务使相关会话失效。
• 安全事件确认写审计。

5. 通用错误码

错误码	语义	前端建议
UNAUTHENTICATED	未登录或登录失效	重新登录
FORBIDDEN	无接口或资源权限	展示无权限或申请授权入口
RESOURCE_NOT_FOUND	资源不存在或不可见	返回列表或刷新
VALIDATION_ERROR	请求字段不合法	定位字段并提示
REVISION_CONFLICT	Block revision 冲突	展示冲突恢复信息和当前 revision
DATA_REVISION_CONFLICT	动态字段数据 revision 冲突（expectedDataRevision 不匹配），语义覆盖所有 owner 命令中的 expectedRevision / expectedDataRevision 冲突场景	展示当前 dataRevision 和冲突字段，引导用户刷新后重试
QUOTA_EXCEEDED	账户配额已用尽，例如 AI 调用次数、存储空间、知识库数量等	展示当前配额和升级/购买入口
BUDGET_EXCEEDED	单次任务或会话预算超限，例如 token 预算、调用次数预算	展示预算限制和调整建议
SCHEMA_STALE	调用方持有的 MetaSchema 版本已过期	刷新 Schema 和投影后重试
FIELD_DEPRECATED	动态字段已废弃或不再允许保存	显示迁移提示或隐藏保存入口
PROJECTION_STALE	用户可见投影版本已过期	重新拉取投影和字段数据
STATE_CONFLICT	当前状态不允许该动作	刷新对象状态和可用动作
SOURCE_NEEDS_RECHECK	来源需重验	引导重验或替换来源
SOURCE_BLOCKED	来源 actionPolicy 为 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、检索、文件或通知服务不可用	展示稍后重试，不暴露密钥或内部响应
API_VERSION_DEPRECATED	请求的 API 版本已废弃（X-API-Version header 指定的版本已过期）	展示迁移指引，升级到最新版本

错误响应 data 可以按场景携带 currentRevision、currentState、currentSchemaVersion、currentProjectionVersion、currentDataRevision、requiredPrecheckType、sourceStatus、actionPolicy、reasonAttributions、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