zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/design-docs/后端-05-统一API契约-v1.md
zizi 2124a79312 docs(design): 补知识效用缺环——新增专题-07 消费契约与质量闭环 + 七册配套拍板 
第一性原理结论：知识的价值只在被选中并改善产出的那一刻兑现；此前 SoT 钉死了治理
（谁能读什么），缺消费选择（该读哪几条）与输入侧质量（什么算好知识、怎么测）。

- 新增 专题-07 v1（唯一 owner）：术语桥（卡↔SoT 载体）、按用途默认消费合同与注入
  视图两档、知识质量三性（可命中/可行动/可持续+口径）、回放评测（参考书=标准答案，
  三评测线+两道合规闸+知识策略对象与上线门禁）、长线进度三期消费、实验台实证附录、
  验收清单 8 条
- 专题-06 v4：拍板双层型判定（craft 1326 条实测无损→不拆，判据不变）；新增 §6.4
  参照作品面（参考书实体演变=系统侧证据资产，蒸馏成叙事域成长曲线范式才入 Global）；
  世界域六型登记演变历程元素；读取器 purpose 枚举 parse→extraction
- 架构-02 v11：aiContext 值域升级为布尔或用途集（实验台字段级用途裁剪实证反哺）
- 专题-03 v3 / 专题-04 v2（补 .md 改名+离线评估允许样本第 5 类）/ 后端-05 v11 /
  前端-03 v7 / 产品-01·02、前端-02、后端-03 断链修复 / 大纲 v10 / 映射表 v8
- prototypes/ 新增四页签开发者总览

依据：设计文档全库横切取证 + 实验台 9 批实拆实证（活卡 8587、消费端 0 实现、升格
卡向量 0%、p50 实例数 1）。经 codex 与 opus 双独立评审，必修项全部落实。
2026-07-18 00:02:51 +08:00

806 lines
60 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 后端-05：统一 API(接口) 契约-v1
- 版本：v11
- 更新日期：2026-07-17
- 目标读者：前端 / 后端 / 架构 / 测试
- 阅读时间：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 上下文组装（布尔或用途集，值域权威见 `架构-02` §9） |
| `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、Dify API Key、RAGFlow token 明文、完整 Prompt/Response、私有正文全文、外部知识全文、New-API provider authority、供应商路由、供应商密钥、底层成本策略或网关调用权威日志。管理员只能配置 Muse 侧 Prompt、Agent 编排、质量策略、工具授权、外部运行时 provider 引用和评测运行；New-API 网关用户、额度请求、余额快照和调用归属只通过账户/集成接口暴露摘要。
系统 Agent 版本契约补充：
| 字段 | 位置 | 要求 |
|---|---|---|
| `runtimeProvider` | 创建系统 Agent 版本请求 / 版本详情摘要 | 新建、复制、发布必须显式提交；取值 `new-api` / `dify`，预留 `agentscope`；历史版本缺失仅运行时兼容为 `new-api` |
| `providerRef.dify.appType` | 创建系统 Agent 版本请求 / 版本详情摘要 | `agent` / `workflow` |
| `providerRef.dify.appId` | 创建系统 Agent 版本请求 / 版本详情摘要 | `appType=agent` 必填；仅保存引用，不保存密钥 |
| `providerRef.dify.workflowId` | 创建系统 Agent 版本请求 / 版本详情摘要 | `appType=workflow` 必填；仅保存引用，不保存密钥 |
| `providerRef.dify.credentialRef` | 创建系统 Agent 版本请求 / 版本详情摘要 | Dify 必填，值为后端安全配置引用名；不允许空值默认 |
| `providerRef.dify.consoleUrl` | 响应只读 | 后端按 Dify baseUrl allowlist 拼装；前端请求不得提交任意 URL |
| `outputContract.traceabilityPolicy` | 创建系统 Agent 版本请求 / 运行摘要 | 要求 Muse source refs 时，Dify 不可追溯输出必须 fail-closed；允许 Dify 内部知识时标记 `untraceable_provider_context` |
系统 Agent 版本发布校验错误至少覆盖：`AI_AGENT_PROVIDER_REQUIRED`、`AI_AGENT_PROVIDER_UNSUPPORTED`、`AI_AGENT_DIFY_REF_INVALID`、`AI_AGENT_DIFY_CREDENTIAL_REQUIRED`、`AI_AGENT_DIFY_CONSOLE_URL_REJECTED`。试运行失败分类至少覆盖：`auth_failed`、`provider_bad_request`、`provider_bad_response`、`network_timeout`、`rate_limited`、`runtime_unavailable`。所有失败响应只能返回脱敏消息、`correlationId`、`providerRequestId` 摘要和可恢复建议，不能返回 Authorization header、API Key 或 provider 原始响应体。
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`，不能继续下载。
下载与导入预检的契约姿态（行为与决策见 `后端-03` §6/§9 和 `架构-03` ADR-019；模型不变式见 `架构-02` Download Credential / Export Package）：
- `GET /downloads/{credentialId}` 是后端字节代理：以凭证解析出的稳定存储路径取流并回传字节，不返回对象存储签名 URL；存储对象按租户/用户命名空间隔离，凭证只解析 owner 范围内的路径。字节代理后端不可用时返回 `UPSTREAM_UNAVAILABLE`。
- 导入预检以服务端权威 `scanStatus` 为准（失败关闭）；扫描器接入前 `scanStatus=scan_blocked`，对应导入任务停在终态、不创建 Parse Job。外部来源命中 SSRF 白名单外目标时按 `VALIDATION_ERROR` 拒绝，不发起回源。
### 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` 查询只能查本人可见调用，重复请求必须返回同一重试组和归属状态，不能重复扣减、重复补偿或重复归属。
账户导出在 Account BC 内组装本人数据并按脱敏级别(`standard` / `strict`)处理后落包，脱敏级别未知按 `strict` 失败关闭；`GET /app-api/muse/account/downloads/{credentialId}` 与作品导出一致，走后端字节代理、以稳定存储路径取流，不签发签名 URL（行为见 `后端-03` §9，决策见 `架构-03` ADR-019）。
安全事件详情接口（`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、检索、文件或通知服务不可用 | 展示稍后重试，不暴露密钥或内部响应 |
| `AI_AGENT_PROVIDER_REQUIRED` | 新系统 Agent 版本缺少 runtimeProvider | 定位系统 Agent 版本配置并要求选择 provider |
| `AI_AGENT_PROVIDER_UNSUPPORTED` | runtimeProvider 未被后端支持 | 展示 provider 不支持，不允许发布 |
| `AI_AGENT_DIFY_REF_INVALID` | Dify app/workflow 引用不完整或不符合 appType | 定位 Dify 引用字段并提示修正 |
| `AI_AGENT_DIFY_CREDENTIAL_REQUIRED` | Dify provider 缺少 credentialRef 或安全配置不可用 | 要求选择有效 credentialRef，不展示密钥 |
| `AI_AGENT_DIFY_CONSOLE_URL_REJECTED` | Dify console 跳转不在 allowlist 或携带敏感 query | 阻断跳转并提示联系管理员 |
| `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`
Reference in New Issue View Git Blame Copy Permalink