3585219637
Some checks failed
Backend Maven CI / backend-local (push) Has been cancelled
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3561 lines
116 KiB
YAML
3561 lines
116 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse AI API
|
||
version: 1.0.0
|
||
license:
|
||
name: Proprietary
|
||
|
||
servers:
|
||
- url: /
|
||
description: 同源 API 网关
|
||
|
||
paths:
|
||
# ====================================================================
|
||
# Admin AI 管理（设计文档 3.4）
|
||
# ====================================================================
|
||
|
||
# ---------- Prompt 管理 ----------
|
||
/admin-api/muse/ai/prompts:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: Prompt 列表
|
||
operationId: adminListPrompts
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: promptKey
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 按 promptKey 筛选
|
||
responses:
|
||
'200':
|
||
description: Prompt 分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/PromptSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/prompts/{promptKey}/versions:
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 新建 Prompt 版本
|
||
operationId: adminCreatePromptVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: promptKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: Prompt 唯一标识
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [content]
|
||
properties:
|
||
content:
|
||
type: string
|
||
description: Prompt 正文内容
|
||
variables:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [name, type]
|
||
properties:
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
enum: [string, number, boolean]
|
||
required:
|
||
type: boolean
|
||
defaultValue:
|
||
type: string
|
||
description: 模板变量定义
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: Prompt 版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
promptKey:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/prompts/{promptKey}/versions/{version}/activate:
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 激活 Prompt 版本
|
||
operationId: adminActivatePromptVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: promptKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: version
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 激活原因
|
||
responses:
|
||
'200':
|
||
description: Prompt 版本已激活
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
promptKey:
|
||
type: string
|
||
activeVersion:
|
||
type: integer
|
||
|
||
# ---------- Agent 管理（Admin） ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/agents:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: Agent 列表
|
||
operationId: adminListAgents
|
||
security:
|
||
- adminBearerAuth: []
|
||
description: |
|
||
管理端可按 scope 查看 system/user Agent 清单，用于治理、审计和排障。
|
||
该列表不赋予管理员修改用户私有智能体的权限；用户 Agent 写操作只能走 App Agent owner API。
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: scope
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [system, user, all]
|
||
description: Agent 范围筛选，默认 all
|
||
responses:
|
||
'200':
|
||
description: Agent 分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AdminAgentSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 创建系统 Agent
|
||
operationId: adminCreateAgent
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
description: |
|
||
仅创建 scope=system 的系统级 Agent。管理员不能通过该接口创建或修改用户私有 Agent；
|
||
用户 Agent 的创建、版本和配置写入由 /app-api/muse/agents owner API 承担。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, name, promptKey]
|
||
properties:
|
||
scope:
|
||
type: string
|
||
enum: [system]
|
||
default: system
|
||
description: 固定为 system；请求体如传入 scope 也只能是 system，不能创建 user scope Agent。
|
||
name:
|
||
type: string
|
||
maxLength: 100
|
||
description: Agent 名称
|
||
description:
|
||
type: string
|
||
maxLength: 1000
|
||
description: Agent 描述
|
||
promptKey:
|
||
type: string
|
||
description: 关联的 Prompt key
|
||
slotBindings:
|
||
type: object
|
||
description: 槽位绑定配置（知识库/MetaSchema/模型参数）
|
||
toolGrantIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 关联的系统级工具授权 ID 列表，必须来自 Security facade 已批准的授权。
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 系统 Agent 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/agents/{agentId}/versions:
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 新建系统 Agent 版本
|
||
operationId: adminCreateAgentVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
description: |
|
||
仅对 scope=system 的 Agent 生效。若 agentId 属于用户私有 Agent，服务端必须拒绝，
|
||
不得通过管理端为 user scope Agent 创建版本。
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: 目标 Agent ID，必须为 system scope。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, changeNote]
|
||
anyOf:
|
||
- required: [name]
|
||
- required: [description]
|
||
- required: [promptKey]
|
||
- required: [slotBindings]
|
||
- required: [toolGrantIds]
|
||
properties:
|
||
name:
|
||
type: string
|
||
maxLength: 100
|
||
description:
|
||
type: string
|
||
maxLength: 1000
|
||
promptKey:
|
||
type: string
|
||
slotBindings:
|
||
type: object
|
||
toolGrantIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 关联的系统级工具授权 ID 列表，必须来自 Security facade 已批准的授权。
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: Agent 版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
|
||
# ---------- Tool Grant 管理 ----------
|
||
/admin-api/muse/ai/tool-grants:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: Tool Grant 列表
|
||
operationId: adminListToolGrants
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending, approved, rejected, revoked]
|
||
description: 按审批状态筛选
|
||
responses:
|
||
'200':
|
||
description: Tool Grant 分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ToolGrantSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 登记 Security facade 审批后的工具授权
|
||
operationId: adminCreateOrAdjustToolGrant
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
description: |
|
||
Tool Grant 的审批权威属于 Security facade。该接口只登记或调整已通过审批的工具授权，
|
||
AI runtime 只能消费授权结果，不能通过本接口自授权或扩权。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, reason, agentId, toolType, scope, budget, outboundPolicy]
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标智能体 ID
|
||
toolType:
|
||
type: string
|
||
description: 工具类型（例如 web_search, file_read, api_call）
|
||
scope:
|
||
$ref: '#/components/schemas/ToolGrantScope'
|
||
budget:
|
||
$ref: '#/components/schemas/ToolGrantBudget'
|
||
outboundPolicy:
|
||
$ref: '#/components/schemas/ToolGrantOutboundPolicy'
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 授权/调整原因
|
||
responses:
|
||
'200':
|
||
description: Security facade 审批后的工具授权已登记或调整
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
grantId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [approved, revoked]
|
||
|
||
# ---------- AI 任务管理 ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/tasks:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: AI 任务列表
|
||
operationId: adminListAiTasks
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
description: 按任务状态筛选
|
||
- name: taskType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
description: 按任务类型筛选
|
||
responses:
|
||
'200':
|
||
description: AI 任务分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AiTaskSummary'
|
||
|
||
# ---------- 质量策略管理 ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/quality-policies:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: 质量策略列表
|
||
operationId: adminListQualityPolicies
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
responses:
|
||
'200':
|
||
description: 质量策略分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/QualityPolicySummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/quality-policies/{policyKey}/versions:
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 新建质量策略版本
|
||
operationId: adminCreateQualityPolicyVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: policyKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 质量策略唯一标识
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [dimensions]
|
||
properties:
|
||
dimensions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [name, threshold]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: 质量维度名称
|
||
threshold:
|
||
type: number
|
||
format: double
|
||
description: 通过阈值
|
||
weight:
|
||
type: number
|
||
format: double
|
||
description: 权重
|
||
description: 质量维度配置列表
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 质量策略版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
policyKey:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
|
||
# ---------- 离线评估 ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/evaluation-runs:
|
||
post:
|
||
tags: [Admin AI]
|
||
summary: 启动离线评估
|
||
operationId: adminStartEvaluationRun
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [policyKey, datasetReference]
|
||
properties:
|
||
policyKey:
|
||
type: string
|
||
description: 使用的质量策略 key
|
||
policyVersion:
|
||
type: integer
|
||
description: 使用的质量策略版本，不填则使用 active 版本
|
||
datasetReference:
|
||
type: string
|
||
description: 评估数据集引用
|
||
sampleSize:
|
||
type: integer
|
||
description: 采样数量
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'202':
|
||
description: 评估任务已提交
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
runId:
|
||
type: integer
|
||
format: int64
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/ai/evaluation-runs/{runId}:
|
||
get:
|
||
tags: [Admin AI]
|
||
summary: 查询离线评估运行
|
||
operationId: adminGetEvaluationRun
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: runId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 评估运行详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/EvaluationRun'
|
||
|
||
# ====================================================================
|
||
# Admin 任务/来源事件/审计（设计文档 3.7）
|
||
# ====================================================================
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/jobs:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询 Muse 异步任务
|
||
operationId: adminListJobs
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
- name: owner
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 按 owner 模块筛选
|
||
responses:
|
||
'200':
|
||
description: 异步任务分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/JobSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/jobs/{jobId}:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查看任务详情
|
||
operationId: adminGetJob
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/JobDetail'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/jobs/{jobId}/retry:
|
||
post:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 重试任务
|
||
operationId: adminRetryJob
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 任务已重新排队
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [queued, running]
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/jobs/{jobId}/cancel:
|
||
post:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 取消任务
|
||
operationId: adminCancelJob
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 取消原因
|
||
responses:
|
||
'200':
|
||
description: 任务已取消
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [cancelled]
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/source-events:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询来源状态事件
|
||
operationId: adminListSourceEvents
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: sourceType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 来源类型筛选
|
||
- name: sourceStatus
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [active, stale, revoked, recalled, delisted, blocked, owner_missing, unauthorized]
|
||
description: 来源状态筛选
|
||
responses:
|
||
'200':
|
||
description: 来源状态事件分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/SourceEventSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/source-events/{eventId}:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 来源事件详情
|
||
operationId: adminGetSourceEvent
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: eventId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 来源事件详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/SourceEventDetail'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/source-events/{eventId}/retry:
|
||
post:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 重试来源传播
|
||
operationId: adminRetrySourceEvent
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: eventId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 重试原因
|
||
responses:
|
||
'200':
|
||
description: 来源传播重试已提交
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/audit/api-logs:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询接口调用日志
|
||
description: |
|
||
查询系统接口调用的轻量脱敏日志，用于排障、风控和基础审计留痕。
|
||
响应不得包含请求体全文、响应体全文、token、secret、完整 header 或用户私有正文。
|
||
operationId: adminListApiAccessLogs
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: requestId
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 请求 ID 筛选
|
||
- name: actor
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 调用人摘要筛选
|
||
- name: module
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 业务模块筛选
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [success, failed, slow, sensitive, redacted]
|
||
description: 调用状态筛选
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: 接口调用日志分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ApiAccessLogSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/audit/api-logs/{logId}:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询接口调用日志详情
|
||
description: |
|
||
查询单条接口调用日志的脱敏详情。敏感详情查看本身必须写入业务审计事件。
|
||
operationId: adminGetApiAccessLog
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: logId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 接口调用日志详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ApiAccessLogDetail'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/audit/business-events:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询业务审计摘要
|
||
operationId: adminListBusinessAuditEvents
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: eventType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 审计事件类型筛选
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: 业务审计分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/BusinessAuditEventSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/audit/business-events/{eventId}:
|
||
get:
|
||
tags: [Admin Jobs & Events]
|
||
summary: 查询业务审计详情
|
||
description: |
|
||
查询高危操作、敏感读取、配置变更和治理动作的审计详情。
|
||
before/after 快照必须为脱敏摘要，审计事件 append-only，不提供修改或删除接口。
|
||
operationId: adminGetBusinessAuditEvent
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: eventId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 业务审计详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/BusinessAuditEventDetail'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
|
||
# ====================================================================
|
||
# App AI 任务与候选（设计文档 4.5）
|
||
# ====================================================================
|
||
/app-api/muse/ai/tasks:
|
||
post:
|
||
tags: [App AI]
|
||
summary: 创建生成/续写/扩写/润色/检测/规划任务
|
||
operationId: createAiTask
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
description: |
|
||
AI Orchestration 只接收任务意图和可验证上下文引用，负责排队、候选、Shadow 和评测。
|
||
来源快照与运行权限包由服务端通过 Agent BC + Security facade 生成或记录，客户端不能提交上下文事实或伪造权限。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateAiTaskRequest'
|
||
responses:
|
||
'202':
|
||
description: AI 任务已提交
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
pollUrl:
|
||
type: string
|
||
description: 轮询地址
|
||
sourceSnapshotId:
|
||
type: string
|
||
description: 服务端为本次任务创建或记录的来源快照 ID
|
||
runtimePermissionEnvelopeId:
|
||
type: string
|
||
description: 服务端生成的运行权限包 ID；客户端不可自选、跨作品拼装或伪造。
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/ai/tasks/{taskId}:
|
||
get:
|
||
tags: [App AI]
|
||
summary: 查询 AI 任务
|
||
operationId: getAiTask
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: taskId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: AI 任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AiTaskDetail'
|
||
|
||
# ---------- SSE: AI Stream（独立连接） ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/ai/tasks/{taskId}/stream:
|
||
get:
|
||
tags: [App AI]
|
||
summary: AI 任务 SSE 流
|
||
operationId: streamAiTask
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: taskId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: SSE 事件流
|
||
content:
|
||
text/event-stream:
|
||
schema:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/SSEChunkEvent'
|
||
- $ref: '#/components/schemas/SSEQualityCheckEvent'
|
||
- $ref: '#/components/schemas/SSEDoneEvent'
|
||
- $ref: '#/components/schemas/SSEErrorEvent'
|
||
|
||
# ---------- 候选(Suggestion)管理 ----------
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/works/{workId}/suggestions:
|
||
get:
|
||
tags: [App AI]
|
||
summary: 当前作品候选列表
|
||
operationId: listWorkSuggestions
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [pending, accepted, rejected]
|
||
description: 按候选状态筛选
|
||
- name: blockId
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
description: 按 Block 筛选
|
||
responses:
|
||
'200':
|
||
description: 候选列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/SuggestionSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/suggestions/{suggestionId}:
|
||
get:
|
||
tags: [App AI]
|
||
summary: 候选详情
|
||
operationId: getSuggestion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: suggestionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 候选详情（含生成内容 diff）
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/SuggestionDetail'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/suggestions/{suggestionId}/reject:
|
||
post:
|
||
tags: [App AI]
|
||
summary: 丢弃候选
|
||
operationId: rejectSuggestion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: suggestionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 拒绝原因（可选，用于改进生成质量）
|
||
responses:
|
||
'200':
|
||
description: 已丢弃
|
||
|
||
# ====================================================================
|
||
# App 智能体工作台（设计文档 4.7）
|
||
# ====================================================================
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents:
|
||
get:
|
||
tags: [App Agent]
|
||
summary: 用户可用智能体列表
|
||
operationId: listUserAgents
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: scope
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [system, mine, all]
|
||
description: 智能体范围，默认 all
|
||
responses:
|
||
'200':
|
||
description: 智能体分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 创建用户智能体
|
||
operationId: createUserAgent
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [name]
|
||
properties:
|
||
name:
|
||
type: string
|
||
maxLength: 100
|
||
description: 智能体名称
|
||
description:
|
||
type: string
|
||
maxLength: 1000
|
||
description: 智能体描述
|
||
promptTemplate:
|
||
type: string
|
||
description: 系统提示词模板
|
||
slotBindings:
|
||
type: object
|
||
description: 槽位绑定配置
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}:
|
||
put:
|
||
tags: [App Agent]
|
||
summary: 更新用户智能体
|
||
operationId: updateUserAgent
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
maxLength: 100
|
||
description:
|
||
type: string
|
||
maxLength: 1000
|
||
promptTemplate:
|
||
type: string
|
||
description: 新版本提示词模板；未传时沿用当前版本
|
||
slotBindings:
|
||
type: object
|
||
description: 新版本槽位配置；未传时沿用当前版本
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 更新成功，返回最新 Agent 摘要
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AgentSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}/archive:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 归档用户智能体
|
||
operationId: archiveUserAgent
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 归档原因
|
||
responses:
|
||
'200':
|
||
description: 归档成功，返回 Agent 摘要
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AgentSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}/versions:
|
||
get:
|
||
tags: [App Agent]
|
||
summary: 用户智能体版本列表
|
||
operationId: listUserAgentVersions
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
responses:
|
||
'200':
|
||
description: 版本分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentVersionSummary'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 新建智能体版本
|
||
operationId: createAgentVersion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
maxLength: 100
|
||
description:
|
||
type: string
|
||
maxLength: 1000
|
||
promptTemplate:
|
||
type: string
|
||
slotBindings:
|
||
type: object
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'201':
|
||
description: 版本创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}/versions/{version}/activate:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 激活用户智能体版本
|
||
operationId: activateUserAgentVersion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: version
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 激活原因
|
||
responses:
|
||
'200':
|
||
description: 激活成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}/versions/{version}/archive:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 归档用户智能体版本
|
||
operationId: archiveUserAgentVersion
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: version
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 归档原因
|
||
responses:
|
||
'200':
|
||
description: 归档成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/agents/{agentId}/test:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 试用智能体
|
||
operationId: testAgent
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: agentId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AgentTestRequest'
|
||
responses:
|
||
'200':
|
||
description: 试用结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/AgentTestResult'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/works/{workId}/agent-slots:
|
||
get:
|
||
tags: [App Agent]
|
||
summary: 作品槽位列表
|
||
operationId: listWorkAgentSlots
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 作品槽位列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentSlotSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 槽位预检
|
||
operationId: precheckAgentSlot
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: slotKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 槽位标识
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
sourceAgentId:
|
||
type: integer
|
||
format: int64
|
||
description: 来源智能体 ID；同空间绑定必填，market_agent 来源由服务端按资产解析
|
||
sourceAgentVersion:
|
||
type: integer
|
||
description: 来源智能体版本；同空间绑定必填，market_agent 来源由服务端按发布者当前 active 版本固化
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 授权快照 ID
|
||
expectedSlotRevision:
|
||
type: integer
|
||
description: 目标槽位当前 revision
|
||
sourceType:
|
||
type: string
|
||
enum: [market_agent]
|
||
description: 来源类型；market_agent 表示跨空间 handoff
|
||
handoffToken:
|
||
type: string
|
||
description: Market 一次性 handoff token，仅在 precheck 阶段提交，服务端不落明文
|
||
sourceId:
|
||
type: string
|
||
description: Market 来源资产 ID；sourceType=market_agent 时必填
|
||
sourceVersion:
|
||
type: integer
|
||
description: Market 来源资产版本；仅用于审计，不作为 AI agent version 信任源
|
||
authorizationSummaryId:
|
||
type: string
|
||
description: Market 授权摘要 ID
|
||
responses:
|
||
'200':
|
||
description: 预检通过，返回绑定凭证
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
agentSlotPrecheckId:
|
||
type: string
|
||
description: 槽位绑定预检 ID，供 bind 接口消费
|
||
expiresAt:
|
||
type: string
|
||
format: date-time
|
||
description: 预检过期时间
|
||
'409':
|
||
description: 来源状态阻断/预检过期/revision 冲突
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
/app-api/muse/works/{workId}/agent-slots/{slotKey}/bind:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 绑定槽位
|
||
operationId: bindAgentSlot
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: slotKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 槽位标识
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, agentSlotPrecheckId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
agentSlotPrecheckId:
|
||
type: string
|
||
description: 预检接口返回的绑定凭证，必须由 AI owner 原子消费
|
||
sourceAgentId:
|
||
type: integer
|
||
format: int64
|
||
description: 绑定来源智能体 ID；同空间绑定用于与预检凭据比对，market_agent 来源可为空
|
||
sourceAgentVersion:
|
||
type: integer
|
||
description: 绑定来源智能体版本；同空间绑定用于与预检凭据比对，market_agent 来源可为空
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 授权快照 ID
|
||
expectedSlotRevision:
|
||
type: integer
|
||
description: 目标槽位当前 revision；首次绑定无 active 行时可为空
|
||
responses:
|
||
'200':
|
||
description: 槽位绑定成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
slotRevision:
|
||
type: integer
|
||
description: 绑定后的新槽位 revision
|
||
sourceStatus:
|
||
type: string
|
||
description: 来源状态
|
||
'409':
|
||
description: 预检过期/revision 冲突/来源阻断
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
/app-api/muse/works/{workId}/agent-slots/{slotKey}/unbind:
|
||
post:
|
||
tags: [App Agent]
|
||
summary: 解绑槽位
|
||
operationId: unbindAgentSlot
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: workId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
- name: slotKey
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 槽位标识
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, expectedSlotRevision]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
expectedSlotRevision:
|
||
type: integer
|
||
description: 目标槽位当前 revision
|
||
responses:
|
||
'200':
|
||
description: 槽位解绑成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
slotRevision:
|
||
type: integer
|
||
description: 解绑后的新槽位 revision
|
||
sourceStatus:
|
||
type: string
|
||
enum: [unbound]
|
||
'409':
|
||
description: revision 冲突或槽位不可解绑
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ====================================================================
|
||
# App 任务和来源状态（设计文档 4.2）
|
||
# ====================================================================
|
||
|
||
/app-api/muse/jobs/{jobId}:
|
||
get:
|
||
tags: [App Jobs & Source]
|
||
summary: 查询当前用户可见任务
|
||
operationId: getUserJob
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
responses:
|
||
'200':
|
||
description: 用户可见任务详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/UserJobDetail'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/jobs/{jobId}/cancel:
|
||
post:
|
||
tags: [App Jobs & Source]
|
||
summary: 取消当前用户可取消任务
|
||
operationId: cancelUserJob
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
responses:
|
||
'200':
|
||
description: 任务已取消
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/source-status/query:
|
||
post:
|
||
tags: [App Jobs & Source]
|
||
summary: 按上下文查询来源可用状态
|
||
operationId: querySourceStatus
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SourceStatusQueryRequest'
|
||
responses:
|
||
'200':
|
||
description: 来源可用状态
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/SourceStatusResult'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/app-api/muse/source-status/recheck:
|
||
post:
|
||
tags: [App Jobs & Source]
|
||
summary: 发起来源重验
|
||
operationId: recheckSourceStatus
|
||
security:
|
||
- appBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [commandId, sourceType, sourceId, purpose, targetOwner, targetId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
sourceType:
|
||
type: string
|
||
description: 来源对象类型
|
||
sourceId:
|
||
type: integer
|
||
format: int64
|
||
description: 来源对象 ID
|
||
sourceRevision:
|
||
type: integer
|
||
description: 调用方当前持有的来源版本
|
||
purpose:
|
||
type: string
|
||
enum: [bind, generate, export, publish, confirm, install, handoff]
|
||
description: 用途
|
||
targetOwner:
|
||
type: string
|
||
enum: [content, knowledge, ai, market, account]
|
||
description: 目标 owner
|
||
targetId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标对象 ID
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 调用方当前持有的授权快照
|
||
responses:
|
||
'202':
|
||
description: 重验任务已提交
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
pollUrl:
|
||
type: string
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
components:
|
||
securitySchemes:
|
||
adminBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 管理后台认证 scheme，仅用于 /admin-api/** 接口，admin-api token 与 app-api token 不互通。
|
||
appBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 用户端认证 scheme，仅用于 /app-api/** 接口，app-api token 与 admin-api token 不互通。
|
||
schemas:
|
||
# ==================================================================
|
||
# Admin AI Schemas
|
||
# ==================================================================
|
||
|
||
PromptSummary:
|
||
type: object
|
||
required: [promptKey, activeVersion, updatedAt]
|
||
properties:
|
||
promptKey:
|
||
type: string
|
||
description: Prompt 唯一标识
|
||
name:
|
||
type: string
|
||
description: Prompt 名称
|
||
activeVersion:
|
||
type: integer
|
||
description: 当前激活版本号
|
||
latestVersion:
|
||
type: integer
|
||
description: 最新版本号
|
||
variableCount:
|
||
type: integer
|
||
description: 模板变量数量
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
AdminAgentSummary:
|
||
type: object
|
||
required: [agentId, name, scope, status, updatedAt]
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
scope:
|
||
type: string
|
||
enum: [system, user]
|
||
description: system=系统预置, user=用户创建
|
||
activeVersion:
|
||
type: integer
|
||
promptKey:
|
||
type: string
|
||
description: 关联的 Prompt key
|
||
status:
|
||
type: string
|
||
enum: [active, archived]
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
ToolGrantSummary:
|
||
type: object
|
||
required: [grantId, agentId, toolType, scope, budget, outboundPolicy, status, createdAt]
|
||
properties:
|
||
grantId:
|
||
type: integer
|
||
format: int64
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
agentName:
|
||
type: string
|
||
toolType:
|
||
type: string
|
||
description: 工具类型
|
||
scope:
|
||
$ref: '#/components/schemas/ToolGrantScope'
|
||
budget:
|
||
$ref: '#/components/schemas/ToolGrantBudget'
|
||
outboundPolicy:
|
||
$ref: '#/components/schemas/ToolGrantOutboundPolicy'
|
||
status:
|
||
type: string
|
||
enum: [pending, approved, rejected, revoked]
|
||
approvedBy:
|
||
type: string
|
||
description: 审批人
|
||
securityApprovalId:
|
||
type: string
|
||
description: Security facade 审批记录 ID
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
ToolGrantScope:
|
||
type: object
|
||
required: [scopeType, ownerType, resourceRefs]
|
||
description: Security facade 批准后的工具可用范围，AI runtime 只能按该范围消费。
|
||
properties:
|
||
scopeType:
|
||
type: string
|
||
enum: [system, work, chapter, knowledge_base, market_asset, external_endpoint]
|
||
description: 授权范围类型
|
||
ownerType:
|
||
type: string
|
||
enum: [system, user, work, knowledge, market]
|
||
description: 范围 owner 类型
|
||
resourceRefs:
|
||
type: array
|
||
minItems: 1
|
||
description: 可访问资源引用；跨作品资源必须由 Security facade 单独批准。
|
||
items:
|
||
type: object
|
||
required: [resourceType, resourceId]
|
||
properties:
|
||
resourceType:
|
||
type: string
|
||
enum: [work, chapter, block, knowledge_base, market_asset, endpoint]
|
||
resourceId:
|
||
type: string
|
||
description: 资源 ID 或受控 endpoint key
|
||
crossWorkAllowed:
|
||
type: boolean
|
||
default: false
|
||
description: 是否允许跨作品访问；只能由 Security facade 审批结果置为 true。
|
||
|
||
ToolGrantBudget:
|
||
type: object
|
||
required: [period, maxCalls]
|
||
description: Security facade 批准后的工具调用预算。
|
||
properties:
|
||
period:
|
||
type: string
|
||
enum: [per_task, daily, monthly]
|
||
description: 预算周期
|
||
maxCalls:
|
||
type: integer
|
||
minimum: 1
|
||
description: 周期内最大调用次数
|
||
maxTokens:
|
||
type: integer
|
||
minimum: 0
|
||
description: 周期内最大 token 用量；0 表示该工具不消耗 token 预算。
|
||
maxCostCents:
|
||
type: integer
|
||
minimum: 0
|
||
description: 周期内最大成本，单位为分。
|
||
|
||
ToolGrantOutboundPolicy:
|
||
type: object
|
||
required: [networkMode, allowedDestinations, dataPolicy]
|
||
description: Security facade 批准后的外发策略。
|
||
properties:
|
||
networkMode:
|
||
type: string
|
||
enum: [none, internal_only, allowlist]
|
||
description: 网络外发模式
|
||
allowedDestinations:
|
||
type: array
|
||
description: 允许访问的外部目的地 key 或域名；networkMode=allowlist 时必填非空。
|
||
items:
|
||
type: string
|
||
dataPolicy:
|
||
type: string
|
||
enum: [no_user_content, redacted_user_content, approved_context_only]
|
||
description: 用户内容外发策略
|
||
|
||
AiTaskSummary:
|
||
type: object
|
||
required: [taskId, taskType, status, createdAt]
|
||
properties:
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
taskType:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
description: 任务类型
|
||
status:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
userId:
|
||
type: string
|
||
description: 任务所属用户
|
||
workId:
|
||
type: integer
|
||
format: int64
|
||
description: 关联作品 ID
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
description: 使用的智能体 ID
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
QualityPolicySummary:
|
||
type: object
|
||
required: [policyKey, activeVersion, updatedAt]
|
||
properties:
|
||
policyKey:
|
||
type: string
|
||
description: 质量策略唯一标识
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
activeVersion:
|
||
type: integer
|
||
latestVersion:
|
||
type: integer
|
||
dimensionCount:
|
||
type: integer
|
||
description: 质量维度数量
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
EvaluationRun:
|
||
type: object
|
||
required: [runId, policyKey, status, createdAt]
|
||
properties:
|
||
runId:
|
||
type: integer
|
||
format: int64
|
||
policyKey:
|
||
type: string
|
||
policyVersion:
|
||
type: integer
|
||
datasetReference:
|
||
type: string
|
||
sampleSize:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
totalSamples:
|
||
type: integer
|
||
description: 总样本数
|
||
passedSamples:
|
||
type: integer
|
||
description: 通过样本数
|
||
failedSamples:
|
||
type: integer
|
||
description: 未通过样本数
|
||
overallScore:
|
||
type: number
|
||
format: double
|
||
description: 总体评分
|
||
dimensionScores:
|
||
type: object
|
||
description: 各维度评分
|
||
additionalProperties:
|
||
type: number
|
||
format: double
|
||
startedAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
errorMessage:
|
||
type: string
|
||
|
||
# ==================================================================
|
||
# Admin Jobs & Events Schemas
|
||
# ==================================================================
|
||
|
||
JobSummary:
|
||
type: object
|
||
required: [jobId, type, status, owner, createdAt]
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
type:
|
||
type: string
|
||
description: 任务类型（如 knowledge_extraction, export, evaluation 等）
|
||
status:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
owner:
|
||
type: string
|
||
description: owner 模块
|
||
createdBy:
|
||
type: string
|
||
description: 创建者
|
||
retryCount:
|
||
type: integer
|
||
description: 已重试次数
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
JobDetail:
|
||
type: object
|
||
required: [jobId, type, status, owner, createdAt]
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
type:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
owner:
|
||
type: string
|
||
createdBy:
|
||
type: string
|
||
input:
|
||
type: object
|
||
description: 任务输入参数
|
||
result:
|
||
type: object
|
||
description: 任务结果（完成时）
|
||
errorMessage:
|
||
type: string
|
||
description: 失败原因
|
||
failedStage:
|
||
type: string
|
||
description: 失败阶段
|
||
retryable:
|
||
type: boolean
|
||
description: 是否可重试
|
||
retryCount:
|
||
type: integer
|
||
retryGroupId:
|
||
type: string
|
||
description: 重试组 ID
|
||
correlationId:
|
||
type: string
|
||
description: 关联 ID
|
||
startedAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 建议的下一步操作
|
||
|
||
SourceEventSummary:
|
||
type: object
|
||
required: [eventId, sourceType, sourceId, sourceStatus, actionPolicy, createdAt]
|
||
properties:
|
||
eventId:
|
||
type: integer
|
||
format: int64
|
||
sourceType:
|
||
type: string
|
||
description: 来源对象类型
|
||
sourceId:
|
||
type: integer
|
||
format: int64
|
||
description: 来源对象 ID
|
||
sourceStatus:
|
||
type: string
|
||
enum: [active, stale, revoked, recalled, delisted, blocked, owner_missing, unauthorized]
|
||
actionPolicy:
|
||
type: string
|
||
enum: [allowed, read_only, blocked, needs_recheck]
|
||
affectedScope:
|
||
type: string
|
||
description: 影响范围描述
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
SourceEventDetail:
|
||
type: object
|
||
required: [eventId, sourceType, sourceId, sourceStatus, actionPolicy, reasonAttributions, createdAt]
|
||
properties:
|
||
eventId:
|
||
type: integer
|
||
format: int64
|
||
sourceType:
|
||
type: string
|
||
sourceId:
|
||
type: integer
|
||
format: int64
|
||
sourceStatus:
|
||
type: string
|
||
enum: [active, stale, revoked, recalled, delisted, blocked, owner_missing, unauthorized]
|
||
actionPolicy:
|
||
type: string
|
||
enum: [allowed, read_only, blocked, needs_recheck]
|
||
reasonAttributions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
reason:
|
||
type: string
|
||
source:
|
||
type: string
|
||
description: 原因归因列表
|
||
affectedBindings:
|
||
type: integer
|
||
description: 受影响的绑定数
|
||
affectedTasks:
|
||
type: integer
|
||
description: 受影响的任务数
|
||
propagationStatus:
|
||
type: string
|
||
description: 传播状态
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
description: 关联的传播任务 ID
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
ApiAccessLogSummary:
|
||
type: object
|
||
required: [logId, requestId, actor, method, pathSummary, status, statusCode, durationMs, createdAt]
|
||
properties:
|
||
logId:
|
||
type: integer
|
||
format: int64
|
||
requestId:
|
||
type: string
|
||
description: 请求链路 ID
|
||
actor:
|
||
type: string
|
||
description: 调用人脱敏摘要
|
||
actorType:
|
||
type: string
|
||
enum: [admin, system, user, anonymous]
|
||
module:
|
||
type: string
|
||
description: 业务模块
|
||
method:
|
||
type: string
|
||
enum: [GET, POST, PUT, PATCH, DELETE]
|
||
pathSummary:
|
||
type: string
|
||
description: 脱敏路径摘要，不能包含敏感查询参数
|
||
objectSummary:
|
||
type: string
|
||
description: 关联对象脱敏摘要
|
||
clientIp:
|
||
type: string
|
||
description: 客户端 IP 脱敏摘要
|
||
status:
|
||
type: string
|
||
enum: [success, failed, slow, sensitive, redacted]
|
||
statusCode:
|
||
type: integer
|
||
durationMs:
|
||
type: integer
|
||
description: 接口耗时毫秒数
|
||
errorCode:
|
||
type: string
|
||
errorSummary:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
ApiAccessLogDetail:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ApiAccessLogSummary'
|
||
- type: object
|
||
properties:
|
||
requestHeadersSummary:
|
||
type: object
|
||
description: 请求头脱敏摘要，不包含 token、secret、cookie 或完整 header
|
||
additionalProperties:
|
||
type: string
|
||
requestBodySummary:
|
||
type: object
|
||
description: 请求体脱敏摘要，不包含用户私有正文全文
|
||
additionalProperties: true
|
||
responseBodySummary:
|
||
type: object
|
||
description: 响应体脱敏摘要，不包含用户私有正文全文
|
||
additionalProperties: true
|
||
relatedAuditEventId:
|
||
type: integer
|
||
format: int64
|
||
description: 查看敏感调用详情时写入的业务审计事件 ID
|
||
|
||
BusinessAuditEventSummary:
|
||
type: object
|
||
required: [eventId, eventType, operator, createdAt]
|
||
properties:
|
||
eventId:
|
||
type: integer
|
||
format: int64
|
||
eventType:
|
||
type: string
|
||
description: 审计事件类型
|
||
operator:
|
||
type: string
|
||
description: 操作者
|
||
resourceType:
|
||
type: string
|
||
description: 操作资源类型
|
||
resourceId:
|
||
type: string
|
||
description: 操作资源 ID
|
||
summary:
|
||
type: string
|
||
description: 操作摘要
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
BusinessAuditEventDetail:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BusinessAuditEventSummary'
|
||
- type: object
|
||
properties:
|
||
reason:
|
||
type: string
|
||
description: 操作理由
|
||
result:
|
||
type: string
|
||
enum: [success, failed, rejected, pending_review]
|
||
description: 操作结果
|
||
beforeSnapshot:
|
||
type: object
|
||
description: 变更前脱敏快照摘要
|
||
additionalProperties: true
|
||
afterSnapshot:
|
||
type: object
|
||
description: 变更后脱敏快照摘要
|
||
additionalProperties: true
|
||
impactSummary:
|
||
type: string
|
||
description: 影响范围摘要
|
||
approvalSummary:
|
||
type: string
|
||
description: 审批或复核摘要
|
||
immutable:
|
||
type: boolean
|
||
description: 审计事件是否 append-only
|
||
|
||
# ==================================================================
|
||
# App AI Schemas
|
||
# ==================================================================
|
||
|
||
AiTaskIntent:
|
||
type: object
|
||
required: [kind]
|
||
description: 用户本次希望 AI 编排完成的任务意图，不携带上下文事实。
|
||
properties:
|
||
kind:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
description: 任务意图类型
|
||
userInstruction:
|
||
type: string
|
||
maxLength: 4000
|
||
description: 用户补充指令；只能表达意图，不能作为已授权上下文事实。
|
||
outputTarget:
|
||
type: string
|
||
enum: [suggestion, planning_candidate, evaluation_report, shadow_candidate]
|
||
default: suggestion
|
||
description: 期望输出落点，实际落点由服务端根据任务类型和权限决定。
|
||
|
||
AiContextRef:
|
||
type: object
|
||
required: [refType, refId]
|
||
description: 可验证的上下文引用；服务端按 owner、作品归属和权限重新取数。
|
||
properties:
|
||
refType:
|
||
type: string
|
||
enum: [work, chapter, block]
|
||
description: 引用类型
|
||
refId:
|
||
type: integer
|
||
format: int64
|
||
description: 引用对象 ID；chapter/block 必须属于 workId 指向的作品。
|
||
expectedRevision:
|
||
type: integer
|
||
description: 调用方看到的对象 revision，仅用于 stale 检测，不授予权限。
|
||
|
||
AgentOverrideRef:
|
||
type: object
|
||
required: [agentId, agentVersion, reason]
|
||
description: 可验证的智能体覆盖引用；服务端仍必须通过 Agent BC 和 Security facade 校验。
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
description: 覆盖使用的智能体 ID
|
||
agentVersion:
|
||
type: integer
|
||
description: 覆盖使用的智能体版本
|
||
reason:
|
||
type: string
|
||
description: 覆盖默认槽位智能体的原因
|
||
|
||
CreateAiTaskRequest:
|
||
type: object
|
||
required: [commandId, intent]
|
||
description: |
|
||
客户端只能提交任务意图、作品/章节/Block 上下文引用、agentSlotKey 或 agentOverrideRef。
|
||
服务端负责生成来源快照与 Runtime Permission Envelope；客户端不得提交上下文块数组、正文片段或授权快照。
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
intent:
|
||
$ref: '#/components/schemas/AiTaskIntent'
|
||
workId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标作品 ID；服务端以此作为上下文和权限边界。
|
||
blockId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标 Block 引用（正文生成/续写等场景必填）；服务端校验其归属 workId。
|
||
chapterId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标章节引用；服务端校验其归属 workId。
|
||
agentSlotKey:
|
||
type: string
|
||
description: 作品内智能体槽位 key，由 Agent BC 解析为具体 Agent 版本。
|
||
agentOverrideRef:
|
||
$ref: '#/components/schemas/AgentOverrideRef'
|
||
additionalContextRefs:
|
||
type: array
|
||
description: 附加上下文引用；只能传 ID/revision，不能传正文或跨作品事实。
|
||
items:
|
||
$ref: '#/components/schemas/AiContextRef'
|
||
contextScope:
|
||
type: string
|
||
enum: [none, work, chapter, block]
|
||
default: work
|
||
description: 服务端可读取的最大上下文范围；最终裁剪受 Runtime Permission Envelope 约束。
|
||
|
||
AiTaskDetail:
|
||
type: object
|
||
required: [taskId, taskType, agentId, status, createdAt]
|
||
properties:
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
taskType:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
agentName:
|
||
type: string
|
||
workId:
|
||
type: integer
|
||
format: int64
|
||
blockId:
|
||
type: integer
|
||
format: int64
|
||
status:
|
||
type: string
|
||
enum: [queued, running, streaming, completed, failed, cancelled]
|
||
suggestionId:
|
||
type: integer
|
||
format: int64
|
||
description: 任务完成后关联的候选 ID
|
||
sourceRevision:
|
||
type: integer
|
||
description: 来源版本
|
||
sourceSnapshotId:
|
||
type: string
|
||
description: 服务端记录的来源快照 ID
|
||
runtimePermissionEnvelopeId:
|
||
type: string
|
||
description: 服务端生成的运行权限包 ID
|
||
qualityScores:
|
||
type: object
|
||
description: 各质量维度评分
|
||
additionalProperties:
|
||
type: number
|
||
format: double
|
||
errorMessage:
|
||
type: string
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
SuggestionSummary:
|
||
type: object
|
||
required: [suggestionId, taskType, status, createdAt]
|
||
properties:
|
||
suggestionId:
|
||
type: integer
|
||
format: int64
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
description: 关联的 AI 任务 ID
|
||
blockId:
|
||
type: integer
|
||
format: int64
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
agentName:
|
||
type: string
|
||
taskType:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
status:
|
||
type: string
|
||
enum: [pending, accepted, rejected]
|
||
sourceRevision:
|
||
type: integer
|
||
description: 生成时的来源版本号
|
||
diffSummary:
|
||
type: string
|
||
description: 变更摘要
|
||
qualityPassed:
|
||
type: boolean
|
||
description: 质量门控是否通过
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
SuggestionDetail:
|
||
type: object
|
||
required: [suggestionId, taskId, status, sourceRevision, createdAt]
|
||
properties:
|
||
suggestionId:
|
||
type: integer
|
||
format: int64
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
blockId:
|
||
type: integer
|
||
format: int64
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
agentName:
|
||
type: string
|
||
taskType:
|
||
type: string
|
||
enum: [generation, continuation, expansion, polish, detection, planning]
|
||
status:
|
||
type: string
|
||
enum: [pending, accepted, rejected]
|
||
content:
|
||
type: string
|
||
description: 候选正文内容
|
||
diffContent:
|
||
type: string
|
||
description: 与当前 Block 正文的 diff 内容
|
||
sourceRevision:
|
||
type: integer
|
||
description: 生成时的来源版本号
|
||
sourceSnapshotId:
|
||
type: string
|
||
description: 服务端记录的来源快照 ID
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 服务端记录的授权快照 ID；不接受客户端伪造为运行权限。
|
||
qualityScores:
|
||
type: object
|
||
description: 各质量维度的评分
|
||
additionalProperties:
|
||
type: number
|
||
format: double
|
||
qualityResultVersion:
|
||
type: integer
|
||
description: 候选质量结果版本
|
||
outputComplianceResultId:
|
||
type: string
|
||
description: 输出合规结果 ID
|
||
staticCheckResultId:
|
||
type: string
|
||
description: 静态检查结果 ID
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
# ==================================================================
|
||
# App Agent Schemas
|
||
# ==================================================================
|
||
|
||
AgentSummary:
|
||
type: object
|
||
required: [agentId, name, scope, status, updatedAt]
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
scope:
|
||
type: string
|
||
enum: [system, mine]
|
||
description: system=系统预置, mine=用户自建
|
||
activeVersion:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [active, archived]
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
AgentVersionSummary:
|
||
type: object
|
||
required: [agentId, version, status, active]
|
||
properties:
|
||
agentId:
|
||
type: integer
|
||
format: int64
|
||
version:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [active, archived]
|
||
active:
|
||
type: boolean
|
||
description: 是否为当前激活版本
|
||
changeNote:
|
||
type: string
|
||
description: 版本变更说明
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
AgentTestRequest:
|
||
type: object
|
||
required: [commandId, input]
|
||
properties:
|
||
workId:
|
||
type: integer
|
||
format: int64
|
||
description: 可选，关联作品上下文；不传时使用沙箱上下文
|
||
contextScope:
|
||
type: string
|
||
enum: [none, work, chapter]
|
||
default: none
|
||
description: 决定试用时可读取的上下文范围
|
||
usagePolicy:
|
||
type: string
|
||
enum: [charge, free_trial]
|
||
default: charge
|
||
description: 决定本次试用是否计费
|
||
outputTarget:
|
||
type: string
|
||
enum: [preview_only, shadow]
|
||
default: preview_only
|
||
description: preview_only 只返回预览不落库，shadow 写入 Shadow Candidate 供后续决策
|
||
input:
|
||
type: object
|
||
required: [prompt]
|
||
properties:
|
||
prompt:
|
||
type: string
|
||
description: 试用输入提示词
|
||
description: 试用输入内容
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
|
||
AgentTestResult:
|
||
type: object
|
||
required: [trialSessionId, usageCharged, outputDestination]
|
||
properties:
|
||
trialSessionId:
|
||
type: string
|
||
description: 本次试用会话 ID，用于关联后续查询和审计
|
||
outputPreview:
|
||
type: object
|
||
description: 智能体输出预览内容
|
||
usageCharged:
|
||
type: boolean
|
||
description: 本次试用是否实际计费
|
||
outputDestination:
|
||
type: string
|
||
enum: [preview_only, shadow_candidate]
|
||
description: 输出实际落点
|
||
suggestionId:
|
||
type: integer
|
||
format: int64
|
||
description: outputDestination=shadow_candidate 时关联的候选 ID
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
description: 若异步执行，返回任务 ID 供轮询
|
||
|
||
AgentSlotSummary:
|
||
type: object
|
||
required: [slotKey, slotName, protected, revision]
|
||
properties:
|
||
slotKey:
|
||
type: string
|
||
description: 槽位标识
|
||
slotName:
|
||
type: string
|
||
description: 槽位名称
|
||
slotType:
|
||
type: string
|
||
description: 槽位类型
|
||
protected:
|
||
type: boolean
|
||
description: 是否为保护节点（保护节点不可替换）
|
||
boundAgentId:
|
||
type: integer
|
||
format: int64
|
||
description: 已绑定的智能体 ID
|
||
boundAgentName:
|
||
type: string
|
||
description: 已绑定的智能体名称
|
||
boundAgentVersion:
|
||
type: integer
|
||
description: 已绑定的智能体版本
|
||
revision:
|
||
type: integer
|
||
description: 槽位当前 revision
|
||
sourceStatus:
|
||
type: string
|
||
description: 来源状态
|
||
|
||
# ==================================================================
|
||
# App Jobs & Source Schemas
|
||
# ==================================================================
|
||
|
||
UserJobDetail:
|
||
type: object
|
||
required: [jobId, type, status, createdAt]
|
||
properties:
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
type:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [queued, running, completed, failed, cancelled]
|
||
result:
|
||
type: object
|
||
description: 任务结果（完成时）
|
||
errorMessage:
|
||
type: string
|
||
description: 失败原因
|
||
retryable:
|
||
type: boolean
|
||
description: 是否可重试
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
completedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
SourceStatusQueryRequest:
|
||
type: object
|
||
required: [sourceType, sourceId, purpose, targetOwner, targetId]
|
||
properties:
|
||
sourceType:
|
||
type: string
|
||
description: 来源对象类型
|
||
sourceId:
|
||
type: integer
|
||
format: int64
|
||
description: 来源对象 ID
|
||
purpose:
|
||
type: string
|
||
enum: [bind, generate, export, publish, confirm, install, handoff]
|
||
description: 用途
|
||
targetOwner:
|
||
type: string
|
||
enum: [content, knowledge, ai, market, account]
|
||
description: 目标 owner
|
||
targetId:
|
||
type: integer
|
||
format: int64
|
||
description: 目标对象 ID
|
||
sourceRevision:
|
||
type: integer
|
||
description: 调用方当前持有的来源版本
|
||
authorizationSnapshotId:
|
||
type: string
|
||
description: 调用方当前持有的授权快照
|
||
|
||
SourceStatusResult:
|
||
type: object
|
||
required: [sourceStatus, actionPolicy]
|
||
properties:
|
||
sourceStatus:
|
||
type: string
|
||
enum: [active, stale, revoked, recalled, delisted, blocked, owner_missing, unauthorized]
|
||
description: 来源状态
|
||
actionPolicy:
|
||
type: string
|
||
enum: [allowed, read_only, blocked, needs_recheck]
|
||
description: 动作策略
|
||
blockedReasons:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 阻断原因列表
|
||
needsRecheckReasons:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 需重验原因（ActionPolicy 层面的补充信息，说明为何 actionPolicy=needs_recheck）
|
||
reasonAttributions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
reason:
|
||
type: string
|
||
source:
|
||
type: string
|
||
description: 原因归因列表
|
||
sourceEvents:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
eventId:
|
||
type: string
|
||
eventType:
|
||
type: string
|
||
occurredAt:
|
||
type: string
|
||
format: date-time
|
||
description: 关联的来源事件
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 建议的下一步操作
|
||
currentSourceVersion:
|
||
type: integer
|
||
description: 当前来源版本
|
||
currentAuthorizationSnapshotId:
|
||
type: string
|
||
description: 当前授权快照 ID
|
||
jobId:
|
||
type: integer
|
||
format: int64
|
||
description: 可选，关联的异步任务 ID
|
||
|
||
# ==================================================================
|
||
# SSE 事件流 Schema（Fix 7: 将 SSE 流形式化为可引用 Schema）
|
||
# ==================================================================
|
||
|
||
SSEChunkEvent:
|
||
type: object
|
||
required: [event, data]
|
||
properties:
|
||
event:
|
||
type: string
|
||
enum: [chunk]
|
||
description: SSE 事件类型
|
||
data:
|
||
type: object
|
||
required: [content, sequenceNo]
|
||
properties:
|
||
content:
|
||
type: string
|
||
description: AI 生成的文本片段
|
||
sequenceNo:
|
||
type: integer
|
||
minimum: 1
|
||
description: 片段序号，从 1 递增
|
||
|
||
SSEQualityCheckEvent:
|
||
type: object
|
||
required: [event, data]
|
||
properties:
|
||
event:
|
||
type: string
|
||
enum: [quality_check]
|
||
description: SSE 事件类型
|
||
data:
|
||
type: object
|
||
required: [dimension, score, passed]
|
||
properties:
|
||
dimension:
|
||
type: string
|
||
description: 质量维度名称（如 fluency, coherence, safety）
|
||
score:
|
||
type: number
|
||
format: double
|
||
minimum: 0
|
||
maximum: 1
|
||
description: 质量评分（0-1）
|
||
passed:
|
||
type: boolean
|
||
description: 该维度是否通过阈值
|
||
|
||
SSEDoneEvent:
|
||
type: object
|
||
required: [event, data]
|
||
properties:
|
||
event:
|
||
type: string
|
||
enum: [done]
|
||
description: SSE 事件类型
|
||
data:
|
||
type: object
|
||
required: [taskId, suggestionId]
|
||
properties:
|
||
taskId:
|
||
type: integer
|
||
format: int64
|
||
description: AI 任务 ID
|
||
suggestionId:
|
||
type: integer
|
||
format: int64
|
||
description: 生成的候选 ID
|
||
summary:
|
||
type: string
|
||
description: 任务完成摘要
|
||
|
||
SSEErrorEvent:
|
||
type: object
|
||
required: [event, data]
|
||
properties:
|
||
event:
|
||
type: string
|
||
enum: [error]
|
||
description: SSE 事件类型
|
||
data:
|
||
type: object
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: 错误码，格式 MUSE-AI-XXX-XXXX
|
||
message:
|
||
type: string
|
||
description: 人类可读的错误描述
|
||
detail:
|
||
type: string
|
||
description: 详细错误信息（仅开发环境返回）
|
||
retryable:
|
||
type: boolean
|
||
description: 是否可重试
|