# 后端-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` 内表达。

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

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

```json
{
  "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、索引、导出、导入、评估、来源传播的操作默认异步。

命令响应至少返回：

```json
{
  "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`