diff --git a/docs/api-contracts/market/openapi.yaml b/docs/api-contracts/market/openapi.yaml index 7170ce82..69f79648 100644 --- a/docs/api-contracts/market/openapi.yaml +++ b/docs/api-contracts/market/openapi.yaml @@ -2,210 +2,1240 @@ openapi: 3.0.3 info: title: Muse Market API version: 1.0.0 + description: | + Muse 市场模块全量 API 契约,覆盖用户端市场发现、购买/授权、安装绑定、 + Handoff 跳转、发布提交、治理结果与申诉,以及管理端资产审核、下架召回、 + 申诉处置和治理影响预览。 + 设计依据:产品-02F(市场功能规格)、产品-02B(管理员控制台·市场治理)、前端-04(市场与个人中心交互)。 paths: - # ========== 用户端: 市场浏览 ========== - /app-api/market/assets: + # ================================================================ + # 用户端: 市场发现与分类推荐 + # ================================================================ + + /app-api/muse/marketplace/assets: get: - tags: [Market] - summary: 浏览市场资产 - operationId: listAssets + tags: [MarketDiscovery] + summary: 市场资产列表 + description: | + 搜索和筛选市场资产。支持按资产类型、分类、关键词和排序方式查询。 + 未登录用户只能浏览公开摘要;登录后按账户授权、地区和合规状态展示可见资产。 + operationId: listMarketplaceAssets parameters: - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - - name: type - in: query - schema: - type: string - enum: [agent, prompt_template, knowledge_source, metaschema] - - name: keyword - in: query - schema: - type: string - description: 搜索关键词 - name: sortBy in: query + description: 排序方式 schema: type: string - enum: [popular, newest, rating] + enum: [popular, newest, rating, relevance] default: popular + - name: assetType + in: query + description: 资产类型筛选 + schema: + type: string + enum: [work, agent, knowledge_base] + - name: category + in: query + description: 分类 ID 筛选 + schema: + type: string + format: uuid + - name: keyword + in: query + description: 搜索关键词 + schema: + type: string + maxLength: 200 + - name: licenseType + in: query + description: 许可类型筛选 + schema: + type: string + - name: status + in: query + description: 可用状态筛选(如 listed / delisted / recalled) + schema: + type: string 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/MarketAssetCard' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' - /app-api/market/assets/{assetId}: + /app-api/muse/marketplace/categories: get: - tags: [Market] - summary: 获取资产详情 - operationId: getAsset + tags: [MarketDiscovery] + summary: 分类曝光、推荐位、排序和可见性摘要 + description: | + 获取市场分类树、专题、推荐位和发布者可见曝光摘要。 + 发布者只能查看自己资产的脱敏曝光聚合,不看全站策略或其他资产精确数据。 + operationId: listMarketplaceCategories parameters: - - name: assetId - in: path - required: true + - name: includeExposureSummary + in: query + description: 是否包含发布者曝光摘要(仅发布者角色有效) + schema: + type: boolean + default: false + responses: + '200': + description: 分类与推荐位信息 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/MarketplaceCategoriesResponse' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + + /app-api/muse/marketplace/recommendations: + get: + tags: [MarketDiscovery] + summary: 个性化推荐资产列表 + description: | + 基于用户上下文返回个性化推荐资产。支持指定推荐场景、参考资产和关联作品。 + 推荐加载失败时不阻断主列表渲染。 + operationId: listMarketplaceRecommendations + parameters: + - name: recommendationContext + in: query + description: 推荐场景上下文(如首页、详情页相关、跨空间选择) + schema: + type: string + enum: [home, detail_related, cross_space_select] + default: home + - name: referenceAssetId + in: query + description: 参考资产 ID(用于"相似资产"推荐) schema: type: string format: uuid + - name: workId + in: query + description: 关联作品 ID(用于跨空间场景下按作品槽位推荐) + schema: + type: string + format: uuid + - name: limit + in: query + description: 返回数量上限 + schema: + type: integer + minimum: 1 + maximum: 50 + default: 10 + 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/MarketAssetCard' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + + # ================================================================ + # 用户端: 资产详情与可信信息 + # ================================================================ + + /app-api/muse/marketplace/assets/{assetId}: + get: + tags: [MarketAsset] + summary: 资产详情 + description: | + 获取单个市场资产的能力、来源、版本、许可、限制、治理状态和当前用户可用动作。 + 按资产类型(作品/智能体/知识库)展示不同可信信息面板。 + operationId: getMarketplaceAsset + parameters: + - $ref: '#/components/parameters/assetId' responses: '200': description: 资产详情 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/MarketAssetDetail' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' - # ========== 用户端: 安装与绑定 ========== - /app-api/market/assets/{assetId}/install: + # ================================================================ + # 用户端: 收藏 + # ================================================================ + + /app-api/muse/marketplace/assets/{assetId}/favorite: post: - tags: [Market] - summary: 安装资产到我的工作区 - operationId: installAsset + tags: [MarketFavorite] + summary: 收藏资产 + description: 收藏市场资产,需登录。收藏不影响授权或安装状态。 + operationId: favoriteAsset parameters: - - name: assetId - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/assetId' responses: - '201': + '200': + description: 收藏成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + delete: + tags: [MarketFavorite] + summary: 取消收藏 + description: 取消已收藏的市场资产。 + operationId: unfavoriteAsset + parameters: + - $ref: '#/components/parameters/assetId' + responses: + '200': + description: 取消收藏成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + + # ================================================================ + # 用户端: 授权获取 + # ================================================================ + + /app-api/muse/marketplace/assets/{assetId}/purchase: + post: + tags: [MarketLicense] + summary: 购买或获取授权 + description: | + 在确认许可、权益和限制后获取资产使用权。获取只产生授权记录, + 不等于安装、绑定或写作品事实。需携带幂等键防止重复提交。 + operationId: purchaseAsset + parameters: + - $ref: '#/components/parameters/assetId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [commandId] + properties: + commandId: + type: string + format: uuid + description: 幂等键,前端生成 UUID + licenseType: + type: string + description: 许可类型选择 + externalOrderRef: + type: string + description: 外部订单或授权引用标识 + responses: + '200': + description: 授权获取成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/MarketLicenseResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + # ================================================================ + # 用户端: 安装 + # ================================================================ + + /app-api/muse/marketplace/assets/{assetId}/install: + post: + tags: [MarketInstall] + summary: 安装智能体或知识库 + description: | + 把已授权的智能体或知识库安装到账户可用列表。安装只表示资产进入账户可用资产列表, + 不等于作品关联或绑定。作品资产不走安装流程。需携带幂等键。 + operationId: installMarketplaceAsset + parameters: + - $ref: '#/components/parameters/assetId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [commandId] + properties: + commandId: + type: string + format: uuid + description: 幂等键,前端生成 UUID + versionId: + type: string + format: uuid + description: 指定安装的版本 ID(不指定则安装当前版本) + pinVersion: + type: boolean + default: false + description: 是否固定版本(固定后不随资产升级自动更新) + responses: + '200': description: 安装成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/MarketInstallResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' - /app-api/market/installations: - get: - tags: [Market] - summary: 获取我的已安装资产 - operationId: listInstallations - responses: - '200': - description: 已安装资产列表 + # ================================================================ + # 用户端: Handoff 跳转授权 + # ================================================================ - /app-api/market/installations/{installationId}/bindings: + /app-api/muse/marketplace/assets/{assetId}/bind-precheck: post: - tags: [Market] - summary: 绑定已安装资产到作品 - operationId: bindInstallation + tags: [MarketHandoff] + summary: 创建来源侧授权摘要和 handoff 准备 + description: | + 在安装后发起绑定预检,生成来源侧授权摘要(如智能体槽位兼容声明、知识库用途与外发范围、 + 作品资产许可快照)。预检结果供后续 handoff 创建时携带。市场只生成预检快照, + 不写入目标 owner 空间。 + operationId: createBindPrecheck parameters: - - name: installationId - in: path - required: true - schema: - type: string - format: uuid + - $ref: '#/components/parameters/assetId' requestBody: required: true content: application/json: schema: type: object - required: [workId] + required: [targetOwner, targetAction, commandId] properties: - workId: + targetOwner: + type: string + enum: [agent, knowledge, content] + description: 目标 owner 空间 + targetAction: + type: string + enum: [slot_bind, bind, asset_use] + description: 目标动作 + targetWorkId: type: string format: uuid - slotConfig: - type: object - description: 槽位配置 - responses: - '201': - description: 绑定成功 - get: - tags: [Market] - summary: 获取资产的作品绑定列表 - operationId: listBindings - parameters: - - name: installationId - in: path - required: true - schema: - type: string - format: uuid + description: 目标作品 ID + commandId: + type: string + format: uuid + description: 幂等键 responses: '200': - description: 绑定列表 + description: 预检快照生成成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/BindPrecheckResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' - # ========== 用户端: 资产发布 ========== - /app-api/market/publish: + /app-api/muse/marketplace/handoffs: post: - tags: [Market] - summary: 发布资产到市场 - operationId: publishAsset + tags: [MarketHandoff] + summary: 创建市场 handoff + description: | + 创建跨空间 handoff token,携带授权快照和预检 ID 跳转到目标 owner 空间。 + 目标空间落地后消费 token 获取 handoff session,基于 session 执行 owner 预检和确认。 + 市场只生成跳转授权,不替换绑定、不解绑、不降权、不改作品事实。 + operationId: createMarketplaceHandoff requestBody: required: true content: application/json: schema: type: object - required: [name, type, sourceId] + required: [assetId, targetOwner, targetAction, returnUrl, commandId] properties: - name: - type: string - maxLength: 200 - description: - type: string - maxLength: 5000 - type: - type: string - enum: [agent, prompt_template, knowledge_source, metaschema] - sourceId: + assetId: type: string format: uuid - description: 来源对象 ID - tags: - type: array - items: - type: string - coverImageUrl: + description: 来源资产 ID + targetOwner: + type: string + enum: [agent, knowledge, content] + description: 目标 owner 空间 + targetAction: + type: string + enum: [slot_bind, bind, asset_use, governance_handle] + description: 目标动作 + targetWorkId: + type: string + format: uuid + description: 目标作品 ID + precheckId: + type: string + format: uuid + description: 绑定预检 ID(来自 bind-precheck) + returnUrl: type: string format: uri + description: 完成后返回市场的 URL + commandId: + type: string + format: uuid + description: 幂等键 responses: - '201': - description: 发布申请已提交,待审核 + '200': + description: handoff 创建成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/HandoffCreateResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' - # ========== 管理端: 资产审核 ========== - /admin-api/market/reviews: + /app-api/muse/marketplace/handoffs/{handoffToken}: get: - tags: [Market] - summary: 获取待审核资产列表 - operationId: adminListReviews + tags: [MarketHandoff] + summary: 查询 handoff 状态 + description: | + 查询 handoff token 的当前状态和 session 信息。目标空间落地后调用此接口消费 token。 + 用于轮询确认目标 owner 是否已完成处理。 + operationId: getHandoffStatus + parameters: + - name: handoffToken + in: path + required: true + schema: + type: string + description: handoff token + responses: + '200': + description: handoff 状态 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/HandoffStatusResult' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' + + /app-api/muse/marketplace/handoffs/{handoffToken}/cancel: + post: + tags: [MarketHandoff] + summary: 取消市场 handoff + description: | + 取消未完成的 handoff。取消后 token 失效,目标空间无法继续消费。 + 已被目标 owner 确认的 handoff 不可取消。 + operationId: cancelHandoff + parameters: + - name: handoffToken + in: path + required: true + schema: + type: string + description: handoff token + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reason] + properties: + reason: + type: string + description: 取消原因 + responses: + '200': + description: 取消成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + # ================================================================ + # 用户端: 发布提交 + # ================================================================ + + /app-api/muse/marketplace/publish-drafts: + post: + tags: [MarketPublish] + summary: 保存发布草稿 + description: | + 保存发布材料草稿。保存不提交审核、不上架。发布者可反复编辑保存。 + 作品资产 02C owner 未闭合前只能保存为"仅阅读/收藏/授权记录"草稿。 + operationId: savePublishDraft + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PublishDraftRequest' + responses: + '200': + description: 草稿保存成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/PublishDraftResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + + /app-api/muse/marketplace/publish-drafts/{draftId}/checks: + post: + tags: [MarketPublish] + summary: 发布检查 + description: | + 运行发布检查,验证权利、隐私、密钥、许可完整性和敏感内容。 + 检查通过只表示可提交审核,不直接上架。检查结果有有效期, + 过期或草稿变化后需重新检查。提交发布申请必须消费未过期的检查结果。 + operationId: runPublishCheck + parameters: + - name: draftId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: 发布检查完成 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/PublishCheckResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + + /app-api/muse/marketplace/publish-requests: + post: + tags: [MarketPublish] + summary: 提交发布申请 + description: | + 将发布检查通过的草稿提交审核。必须原子消费未过期且匹配资产版本、草稿版本和材料 + hash 的发布检查结果。提交后进入审核队列,审核结论由管理端产生。 + operationId: submitPublishRequest + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [draftId, marketPublishCheckId, commandId] + properties: + draftId: + type: string + format: uuid + description: 发布草稿 ID + marketPublishCheckId: + type: string + format: uuid + description: 发布检查结果 ID(消费检查快照) + commandId: + type: string + format: uuid + description: 幂等键 + responses: + '200': + description: 提交成功,进入审核中 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/PublishRequestResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + /app-api/muse/marketplace/publish-requests/{requestId}/withdraw: + post: + tags: [MarketPublish] + summary: 撤回发布申请 + description: | + 撤回未审核的发布申请。撤回后草稿保留,不影响已有上架版本。 + 已审核终态的申请不可撤回。 + operationId: withdrawPublishRequest + parameters: + - name: requestId + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reason] + properties: + reason: + type: string + description: 撤回原因 + responses: + '200': + description: 撤回成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + /app-api/muse/marketplace/my-publish-records: + get: + tags: [MarketPublish] + summary: 我的发布记录 + description: | + 查询当前用户作为发布者的所有发布记录,包括草稿、已提交、审核中、 + 已上架、已下架和召回中的资产及状态。 + operationId: listMyPublishRecords parameters: - $ref: '../openapi-base.yaml#/components/parameters/pageNo' - $ref: '../openapi-base.yaml#/components/parameters/pageSize' - - name: status + - name: assetType in: query + description: 资产类型筛选 schema: type: string - enum: [pending, approved, rejected] + enum: [work, agent, knowledge_base] + - name: status + in: query + description: 发布状态筛选 + schema: + type: string + enum: [draft, submitted, reviewing, needs_supplement, approved, rejected, listed, delisted, recalled] responses: '200': - description: 审核列表 + 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/PublishRecordItem' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' - /admin-api/market/reviews/{reviewId}/approve: - post: - tags: [Market] - summary: 审核通过 - operationId: adminApproveAsset + # ================================================================ + # 用户端: 治理结果与申诉 + # ================================================================ + + /app-api/muse/marketplace/assets/{assetId}/governance-impact: + get: + tags: [MarketGovernance] + summary: 查看下架/召回影响 + description: | + 查看资产治理结果对当前用户授权、安装、绑定、运行中任务、Shadow 候选、 + 知识草稿和导出限制的影响范围。发布者看完整结果;使用者只看自身影响。 + operationId: getGovernanceImpact parameters: - - name: reviewId + - $ref: '#/components/parameters/assetId' + responses: + '200': + description: 治理影响范围 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/GovernanceImpactResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' + + /app-api/muse/marketplace/appeals: + post: + tags: [MarketAppeal] + summary: 提交申诉 + description: | + 对审核驳回、下架、召回或撤权提出申诉。申诉只提交给管理员控制台处理。 + 需在申诉期限内提交,且申诉人须与治理结果有关联。 + operationId: submitAppeal + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [assetId, appealType, reason, commandId] + properties: + assetId: + type: string + format: uuid + description: 申诉对象资产 ID + appealType: + type: string + enum: [review_rejection, delist, recall, license_revocation, usage_impact] + description: 申诉类型 + reason: + type: string + maxLength: 5000 + description: 申诉理由 + evidenceMaterials: + type: array + items: + type: string + description: 证据材料标识列表 + commandId: + type: string + format: uuid + description: 幂等键 + responses: + '200': + description: 申诉提交成功 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/AppealSubmitResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + /app-api/muse/marketplace/appeals/{appealId}/supplements: + post: + tags: [MarketAppeal] + summary: 补充申诉材料 + description: | + 按管理员要求补充申诉证据。补充后申诉状态更新为"已补充"。 + 已关闭的申诉不可补充。材料脱敏后提交,禁止上传密钥和无关正文全文。 + operationId: supplementAppeal + parameters: + - name: appealId in: path required: true schema: type: string format: uuid requestBody: + required: true content: application/json: schema: type: object + required: [description, commandId] + properties: + description: + type: string + maxLength: 5000 + description: 补充说明 + attachmentIds: + type: array + items: + type: string + description: 附件标识列表 + privacyConfirmed: + type: boolean + description: 是否已确认隐私处理 + commandId: + type: string + format: uuid + description: 幂等键 + responses: + '200': + description: 补充材料提交成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + /app-api/muse/marketplace/appeals/{appealId}/withdraw: + post: + tags: [MarketAppeal] + summary: 撤回申诉 + description: | + 撤回未终态的申诉或影响反馈。撤回不改变已生效的治理结果,不删除已提交材料 + (法律/合规/审计留存由 02B 决定)。 + operationId: withdrawAppeal + parameters: + - name: appealId + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reason, commandId] + properties: + reason: + type: string + description: 撤回原因 + commandId: + type: string + format: uuid + description: 幂等键 + responses: + '200': + description: 撤回成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + # ================================================================ + # 管理端: 市场资产管理 + # ================================================================ + + /admin-api/muse/market/assets: + get: + tags: [AdminMarket] + summary: 市场资产列表 + description: | + 管理员查看所有市场资产和治理摘要。支持按资产类型、上架状态、发布者和治理状态筛选。 + 不展示用户私有副本正文。 + operationId: adminListMarketAssets + parameters: + - $ref: '../openapi-base.yaml#/components/parameters/pageNo' + - $ref: '../openapi-base.yaml#/components/parameters/pageSize' + - name: assetType + in: query + description: 资产类型筛选 + schema: + type: string + enum: [work, agent, knowledge_base] + - name: listingStatus + in: query + description: 上架/治理状态筛选 + schema: + type: string + enum: [not_listed, listed, stop_new_acquire, stop_new_install, stop_new_bind, stop_generation, delisted, recalled] + - name: publisherId + in: query + description: 发布者 ID + schema: + type: string + format: uuid + - name: keyword + in: query + description: 资产名称搜索 + schema: + type: string + 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/AdminMarketAssetSummary' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + + /admin-api/muse/market/assets/{assetId}: + get: + tags: [AdminMarket] + summary: 市场资产详情、版本、授权、安装、治理和来源摘要 + description: | + 管理员查看单个资产的完整治理信息,包括版本历史、授权范围、安装绑定数量、 + 申诉记录、治理历史和来源引用摘要。不展示用户私有副本正文。 + operationId: adminGetMarketAsset + parameters: + - $ref: '#/components/parameters/assetId' + responses: + '200': + description: 资产治理详情 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/AdminMarketAssetDetail' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' + + /admin-api/muse/market/assets/{assetId}/governance-impact: + post: + tags: [AdminMarket] + summary: 治理影响预览 + description: | + 管理员在下架、召回或撤权前预览影响范围,包括受影响的授权、安装、绑定、 + 运行中任务、Shadow 候选、知识草稿和导出限制。预览结果可关联到后续处置操作。 + operationId: adminPreviewGovernanceImpact + parameters: + - $ref: '#/components/parameters/assetId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [actionType] + properties: + actionType: + type: string + enum: [delist, recall, revoke_license, stop_generation] + description: 拟执行的治理动作类型 + scope: + type: string + enum: [stop_new_acquire, stop_new_install, stop_new_bind, stop_generation, full_recall] + description: 治理范围 + responses: + '200': + description: 影响预览结果 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/AdminGovernanceImpactPreview' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + + /admin-api/muse/market/assets/{assetId}/delist: + post: + tags: [AdminMarket] + summary: 下架 + description: | + 下架市场资产,停止新获取、新安装或新绑定。下架后已授权用户可按治理结果 + 保留旧授权或停用安装。需要市场治理权限和影响预览。 + operationId: adminDelistAsset + parameters: + - $ref: '#/components/parameters/assetId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reason, scope] + properties: + reason: + type: string + maxLength: 5000 + description: 下架原因 + scope: + type: string + enum: [stop_new_acquire, stop_new_install, stop_new_bind, stop_generation, full_delist] + description: 下架范围 + previewId: + type: string + format: uuid + description: 关联的治理影响预览 ID + responses: + '200': + description: 下架成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + /admin-api/muse/market/assets/{assetId}/recall: + post: + tags: [AdminMarket] + summary: 召回 + description: | + 追溯召回市场资产,阻断后续生成使用、标记来源不可用。召回需要合规管理员权限和双人控制。 + 召回后运行中任务需重验或取消,Shadow 候选和知识草稿标记来源已失效。 + 已确认作品事实保留来源异常标记,不自动回滚。 + operationId: adminRecallAsset + parameters: + - $ref: '#/components/parameters/assetId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [reason, basis, scope, previewId] + properties: + reason: + type: string + maxLength: 5000 + description: 召回原因 + basis: + type: string + maxLength: 5000 + description: 召回依据(法律/合规/安全) + scope: + type: string + enum: [stop_generation, full_recall] + description: 召回范围 + previewId: + type: string + format: uuid + description: 关联的治理影响预览 ID + exportPreservation: + type: boolean + default: false + description: 是否启动法务保全限制(限制导出和复制) + responses: + '200': + description: 召回成功 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + + # ================================================================ + # 管理端: 发布申请审核 + # ================================================================ + + /admin-api/muse/market/publish-requests: + get: + tags: [AdminMarketReview] + summary: 发布申请列表 + description: | + 管理员查看待审核的发布申请队列。支持按资产类型、审核状态、风险标签和发布者筛选。 + 市场审核是发布硬门槛,不能降级成简单开关。 + operationId: adminListPublishRequests + parameters: + - $ref: '../openapi-base.yaml#/components/parameters/pageNo' + - $ref: '../openapi-base.yaml#/components/parameters/pageSize' + - name: assetType + in: query + description: 资产类型筛选 + schema: + type: string + enum: [work, agent, knowledge_base] + - name: status + in: query + description: 审核状态筛选 + schema: + type: string + enum: [pending, reviewing, needs_supplement, approved, rejected, compliance_blocked] + - name: riskTag + in: query + description: 风险标签筛选 + schema: + type: string + - name: publisherId + in: query + description: 发布者 ID + schema: + type: string + format: uuid + 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/AdminPublishRequestSummary' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + + /admin-api/muse/market/publish-requests/{requestId}/approve: + post: + tags: [AdminMarketReview] + summary: 审核通过 + description: | + 审核通过发布申请,资产进入上架状态。通过需确认审核材料完整, + 审核理由和证据将被记录。通知发布者审核通过。 + operationId: adminApprovePublishRequest + parameters: + - name: requestId + in: path + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [note] properties: note: type: string + maxLength: 5000 + description: 审核通过说明 + evidenceTags: + type: array + items: + type: string + description: 审核证据标签 responses: '200': - description: 已上架 + description: 审核通过,已上架 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' - /admin-api/market/reviews/{reviewId}/reject: + /admin-api/muse/market/publish-requests/{requestId}/reject: post: - tags: [Market] - summary: 审核驳回 - operationId: adminRejectAsset + tags: [AdminMarketReview] + summary: 审核拒绝 + description: | + 驳回发布申请,资产不进入上架状态。必须提供驳回理由。 + 发布者可对驳回结果提出申诉。 + operationId: adminRejectPublishRequest parameters: - - name: reviewId + - name: requestId in: path required: true schema: @@ -221,43 +1251,142 @@ paths: properties: reason: type: string + maxLength: 5000 + description: 驳回理由 + evidenceTags: + type: array + items: + type: string + description: 审核证据标签 + requireSupplement: + type: boolean + default: false + description: 是否要求发布者补充材料后可重新提交 + supplementItems: + type: array + items: + type: string + description: 需要补充的项目列表 responses: '200': - description: 已驳回 + description: 审核驳回 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' - /admin-api/market/assets/{assetId}/delist: - post: - tags: [Market] - summary: 下架资产 - operationId: adminDelistAsset + # ================================================================ + # 管理端: 申诉处理 + # ================================================================ + + /admin-api/muse/market/appeals: + get: + tags: [AdminMarketAppeal] + summary: 申诉列表 + description: | + 管理员查看所有申诉列表。支持按申诉人、资产、申诉状态和处理人筛选。 + operationId: adminListAppeals parameters: + - $ref: '../openapi-base.yaml#/components/parameters/pageNo' + - $ref: '../openapi-base.yaml#/components/parameters/pageSize' + - name: appealType + in: query + description: 申诉类型筛选 + schema: + type: string + enum: [review_rejection, delist, recall, license_revocation, usage_impact] + - name: status + in: query + description: 申诉状态筛选 + schema: + type: string + enum: [pending, reviewing, supplementing, maintained, restored, closed] + - name: appellantId + in: query + description: 申诉人 ID + schema: + type: string + format: uuid - name: assetId - in: path - required: true + in: query + description: 关联资产 ID schema: type: string format: uuid - requestBody: - required: true - content: - application/json: - schema: - type: object - required: [reason] - properties: - reason: - type: string responses: '200': - description: 已下架 + 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/AdminAppealSummary' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' - /admin-api/market/assets/{assetId}/recall: - post: - tags: [Market] - summary: 召回已安装资产 - operationId: adminRecallAsset + /admin-api/muse/market/appeals/{appealId}: + get: + tags: [AdminMarketAppeal] + summary: 申诉详情 + description: | + 管理员查看申诉详情,包括申诉材料、证据摘要、原治理结果、处理历史和补充材料记录。 + 只看申诉材料和发布资产,不读取用户私有副本。 + operationId: adminGetAppeal parameters: - - name: assetId + - name: appealId + in: path + required: true + schema: + type: string + format: uuid + responses: + '200': + description: 申诉详情 + content: + application/json: + schema: + allOf: + - $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/AdminAppealDetail' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '404': + $ref: '../openapi-base.yaml#/components/responses/NotFound' + + /admin-api/muse/market/appeals/{appealId}/resolve: + post: + tags: [AdminMarketAppeal] + summary: 处理申诉 + description: | + 处理申诉,给出维持、恢复或关闭结论。恢复上架需重新预览影响范围。 + 处理结论和证据将被记录。可能触发来源状态传播。 + operationId: adminResolveAppeal + parameters: + - name: appealId in: path required: true schema: @@ -269,10 +1398,1255 @@ paths: application/json: schema: type: object - required: [reason] + required: [resolution, reason] properties: + resolution: + type: string + enum: [maintained, restored, partially_restored, closed] + description: 处理结论 reason: type: string + maxLength: 5000 + description: 处理理由 + evidenceTags: + type: array + items: + type: string + description: 处理证据标签 + previewId: + type: string + format: uuid + description: 恢复时的关联影响预览 ID + requireSupplement: + type: boolean + default: false + description: 是否要求申诉人补充材料 + supplementItems: + type: array + items: + type: string + description: 需要补充的项目列表 responses: '200': - description: 已触发召回 \ No newline at end of file + description: 申诉处理完成 + content: + application/json: + schema: + $ref: '../openapi-base.yaml#/components/schemas/CommonResult' + '401': + $ref: '../openapi-base.yaml#/components/responses/Unauthorized' + '403': + $ref: '../openapi-base.yaml#/components/responses/Forbidden' + '409': + $ref: '../openapi-base.yaml#/components/responses/Conflict' + +# ================================================================== +# Components +# ================================================================== + +components: + parameters: + assetId: + name: assetId + in: path + required: true + schema: + type: string + format: uuid + description: 市场资产 ID + + schemas: + # ------------------------------------------------------------------ + # 市场发现 + # ------------------------------------------------------------------ + + MarketAssetCard: + type: object + description: 市场资产卡片(列表项) + required: [assetId, name, assetType, publisherName, version, listingStatus] + properties: + assetId: + type: string + format: uuid + name: + type: string + maxLength: 200 + assetType: + type: string + enum: [work, agent, knowledge_base] + description: 资产类型 + publisherName: + type: string + description: 发布者名称 + version: + type: string + description: 当前版本号 + summary: + type: string + maxLength: 500 + description: 资产摘要 + licenseSummary: + type: string + description: 许可摘要 + listingStatus: + type: string + enum: [listed, delisted, recalled, not_listed] + description: 上架状态 + isAcquired: + type: boolean + description: 当前用户是否已获取授权 + isInstalled: + type: boolean + description: 当前用户是否已安装 + isFavorite: + type: boolean + description: 当前用户是否已收藏 + coverImageUrl: + type: string + format: uri + recommendationReason: + type: string + description: 推荐理由(仅推荐位返回) + governanceAlert: + type: string + description: 下架/召回提示文案 + + MarketplaceCategoriesResponse: + type: object + description: 分类、推荐位和曝光摘要 + properties: + categories: + type: array + items: + $ref: '#/components/schemas/MarketplaceCategory' + topics: + type: array + items: + $ref: '#/components/schemas/MarketplaceTopic' + recommendationSlots: + type: array + items: + $ref: '#/components/schemas/RecommendationSlot' + exposureSummary: + $ref: '#/components/schemas/PublisherExposureSummary' + + MarketplaceCategory: + type: object + description: 市场分类 + required: [categoryId, name] + properties: + categoryId: + type: string + format: uuid + name: + type: string + description: + type: string + sortOrder: + type: integer + assetCount: + type: integer + description: 该分类下的资产数量 + + MarketplaceTopic: + type: object + description: 市场专题 + required: [topicId, title] + properties: + topicId: + type: string + format: uuid + title: + type: string + description: + type: string + assetIds: + type: array + items: + type: string + format: uuid + + RecommendationSlot: + type: object + description: 推荐位 + required: [slotId, name] + properties: + slotId: + type: string + name: + type: string + description: + type: string + assetIds: + type: array + items: + type: string + format: uuid + + PublisherExposureSummary: + type: object + description: 发布者曝光摘要(脱敏聚合) + properties: + totalExposureRange: + type: string + description: 总曝光次数区间(如 "1K-5K") + totalClickRange: + type: string + description: 总点击次数区间 + totalAcquireRange: + type: string + description: 总获取次数区间 + blockedReason: + type: string + description: 下架屏蔽原因(如有) + + # ------------------------------------------------------------------ + # 资产详情 + # ------------------------------------------------------------------ + + MarketAssetDetail: + type: object + description: 市场资产详情 + required: [assetId, name, assetType, publisherName, version, listingStatus, licenseInfo] + properties: + assetId: + type: string + format: uuid + name: + type: string + maxLength: 200 + assetType: + type: string + enum: [work, agent, knowledge_base] + publisherName: + type: string + publisherId: + type: string + format: uuid + version: + type: string + versionId: + type: string + format: uuid + updatedAt: + type: string + format: date-time + summary: + type: string + maxLength: 500 + description: + type: string + maxLength: 5000 + licenseInfo: + $ref: '#/components/schemas/LicenseInfo' + coverImageUrl: + type: string + format: uri + tags: + type: array + items: + type: string + categoryId: + type: string + format: uuid + # 用户授权与可用动作 + userActions: + $ref: '#/components/schemas/AssetUserActions' + # 治理状态 + governanceStatus: + $ref: '#/components/schemas/GovernanceStatus' + # 分型可信信息(按资产类型不同) + typeSpecificInfo: + $ref: '#/components/schemas/TypeSpecificInfo' + + LicenseInfo: + type: object + description: 许可信息 + required: [licenseType, allowedUses, prohibitedUses] + properties: + licenseType: + type: string + description: 许可类型 + allowedUses: + type: array + items: + type: string + description: 允许用途 + prohibitedUses: + type: array + items: + type: string + description: 禁止用途(如禁止再分发、禁止训练复用) + validityPeriod: + type: string + description: 有效期说明 + priceDisplay: + type: string + description: 价格或权益展示文案 + externalOrderRef: + type: string + description: 外部订单或授权引用 + + AssetUserActions: + type: object + description: 当前用户对资产的可用动作 + properties: + canAcquire: + type: boolean + description: 是否可获取授权 + canInstall: + type: boolean + description: 是否可安装(仅智能体/知识库) + canBind: + type: boolean + description: 是否可绑定到作品 + canFavorite: + type: boolean + description: 是否可收藏 + isAcquired: + type: boolean + isInstalled: + type: boolean + isFavorite: + type: boolean + unavailableReason: + type: string + description: 不可用原因(如需登录、已下架、授权失效) + + GovernanceStatus: + type: object + description: 治理状态 + properties: + listingStatus: + type: string + enum: [listed, delisted, recalled, not_listed] + delistReason: + type: string + recallReason: + type: string + appealStatus: + type: string + enum: [none, pending, reviewing, maintained, restored, closed] + appealDeadline: + type: string + format: date-time + description: 申诉截止时间 + + TypeSpecificInfo: + type: object + description: 分型可信信息(按资产类型展示不同面板) + properties: + # 作品资产 + workInfo: + $ref: '#/components/schemas/WorkAssetInfo' + # 智能体资产 + agentInfo: + $ref: '#/components/schemas/AgentAssetInfo' + # 知识库资产 + knowledgeBaseInfo: + $ref: '#/components/schemas/KnowledgeBaseAssetInfo' + + WorkAssetInfo: + type: object + description: 作品资产可信信息 + properties: + readableScope: + type: string + description: 可阅读范围 + canFavorite: + type: boolean + authorizationRecordAvailable: + type: boolean + publicBoundary: + type: string + description: 正文/设定/片段的公开边界说明 + sourceTrackingSummary: + type: string + description: 来源追踪摘要 + futureUseGateStatus: + type: string + description: 后续使用能力(模板化/参考写入/AI上下文)是否未开放及原因 + + AgentAssetInfo: + type: object + description: 智能体资产可信信息 + properties: + capabilityCategory: + type: string + description: 能力类别 + slotCompatibility: + type: string + description: 开放槽位兼容性 + inputOutputContract: + type: string + description: 输入输出合同摘要 + toolAuthorizations: + type: array + items: + type: string + description: 可使用工具列表 + outboundScope: + type: string + description: 外发范围说明 + containsPrivatePromptSummary: + type: boolean + description: 是否含私有 Prompt 摘要 + trialLimitation: + type: string + description: 试用限制说明 + cannotReplaceSystemProtection: + type: boolean + description: 不可替换系统保护节点说明 + + KnowledgeBaseAssetInfo: + type: object + description: 知识库资产可信信息 + properties: + materialScopeSummary: + type: string + description: 资料范围摘要 + processingStatus: + type: string + description: 处理状态 + searchable: + type: boolean + description: 是否可检索 + generatable: + type: boolean + description: 是否可生成 + allowedInModelContext: + type: boolean + description: 是否允许进入模型上下文 + outboundScope: + type: string + description: 外发范围 + versionPinningAvailable: + type: boolean + description: 是否支持版本固定 + sourceDelistedOrRevoked: + type: boolean + description: 来源是否下架/撤权 + + # ------------------------------------------------------------------ + # 授权获取 + # ------------------------------------------------------------------ + + MarketLicenseResult: + type: object + description: 授权获取结果 + required: [licenseId, assetId, status] + properties: + licenseId: + type: string + format: uuid + description: 授权记录 ID + assetId: + type: string + format: uuid + status: + type: string + enum: [active, expired, revoked] + nextStep: + type: string + description: 下一步操作提示(如"可前往安装") + licenseSnapshot: + type: string + description: 授权快照摘要 + + # ------------------------------------------------------------------ + # 安装 + # ------------------------------------------------------------------ + + MarketInstallResult: + type: object + description: 安装结果 + required: [installationId, assetId, status] + properties: + installationId: + type: string + format: uuid + description: 安装记录 ID + assetId: + type: string + format: uuid + versionId: + type: string + format: uuid + status: + type: string + enum: [installed, disabled, upgradable] + canUpgrade: + type: boolean + canBindTarget: + type: boolean + description: 是否有可绑定目标 + bindTargetSummary: + type: string + description: 可绑定目标摘要 + + # ------------------------------------------------------------------ + # Handoff + # ------------------------------------------------------------------ + + BindPrecheckResult: + type: object + description: 绑定预检结果 + required: [precheckId, assetId, targetOwner, targetAction, expiresAt] + properties: + precheckId: + type: string + format: uuid + description: 预检快照 ID(agentSlotPrecheckId / kbBindPrecheckId / workAssetUsePrecheckId) + assetId: + type: string + format: uuid + targetOwner: + type: string + enum: [agent, knowledge, content] + targetAction: + type: string + enum: [slot_bind, bind, asset_use] + targetWorkId: + type: string + format: uuid + authorizationSnapshot: + type: string + description: 授权快照摘要 + compatibilityResult: + type: string + description: 兼容性校验结果 + expiresAt: + type: string + format: date-time + description: 预检过期时间 + + HandoffCreateResult: + type: object + description: Handoff 创建结果 + required: [handoffToken, targetPage, expiresAt] + properties: + handoffToken: + type: string + description: 一次性 handoff token + targetPage: + type: string + format: uri + description: 目标 owner 空间落地页 URL + precheckIdSummary: + type: string + description: 关联的预检 ID 摘要 + expiresAt: + type: string + format: date-time + description: token 过期时间 + + HandoffStatusResult: + type: object + description: Handoff 状态 + required: [handoffToken, status] + properties: + handoffToken: + type: string + status: + type: string + enum: [pending, consumed, completed, expired, cancelled] + targetOwner: + type: string + targetAction: + type: string + assetId: + type: string + format: uuid + targetWorkId: + type: string + format: uuid + returnUrl: + type: string + format: uri + ownerConfirmResult: + type: string + description: 目标 owner 确认结果摘要 + expiresAt: + type: string + format: date-time + + # ------------------------------------------------------------------ + # 发布提交 + # ------------------------------------------------------------------ + + PublishDraftRequest: + type: object + description: 发布草稿请求 + required: [assetType, sourceId, name] + properties: + assetType: + type: string + enum: [work, agent, knowledge_base] + description: 资产类型 + sourceId: + type: string + format: uuid + description: 来源对象 ID(作品/智能体/知识库) + name: + type: string + maxLength: 200 + description: 市场展示标题 + summary: + type: string + maxLength: 500 + description: 市场展示摘要 + description: + type: string + maxLength: 5000 + categoryId: + type: string + format: uuid + licenseType: + type: string + description: 许可类型 + allowedUses: + type: array + items: + type: string + prohibitedUses: + type: array + items: + type: string + coverImageUrl: + type: string + format: uri + tags: + type: array + items: + type: string + rightsDeclaration: + type: string + description: 权利声明 + externalOrderRef: + type: string + description: 外部订单引用规则 + # 作品资产特有:02C owner 未闭合时只能标为仅阅读/收藏/授权记录 + workAssetMode: + type: string + enum: [full, read_only_favorite_license] + default: full + description: 作品资产发布模式(02C 未闭合时只能选 read_only_favorite_license) + + PublishDraftResult: + type: object + description: 发布草稿保存结果 + required: [draftId, status, missingItems] + properties: + draftId: + type: string + format: uuid + status: + type: string + enum: [draft, unchecked, check_failed, submittable] + missingItems: + type: array + items: + type: string + description: 缺失项列表 + + PublishCheckResult: + type: object + description: 发布检查结果 + required: [marketPublishCheckId, status, canSubmit, expiresAt] + properties: + marketPublishCheckId: + type: string + format: uuid + description: 检查结果 ID(提交审核时消费) + status: + type: string + enum: [running, passed, failed, expired] + blockers: + type: array + items: + $ref: '#/components/schemas/PublishCheckItem' + description: 阻断项 + warnings: + type: array + items: + $ref: '#/components/schemas/PublishCheckItem' + description: 警告项 + canSubmit: + type: boolean + description: 检查通过是否可提交审核 + expiresAt: + type: string + format: date-time + description: 检查结果过期时间 + + PublishCheckItem: + type: object + description: 发布检查条目 + required: [category, message] + properties: + category: + type: string + enum: [rights, privacy, key_exposure, copyright, license_completeness, sensitive_content, owner_precheck_lineage, processing_status, outbound_scope, redistribution_restriction] + description: 检查类别 + message: + type: string + description: 检查信息 + severity: + type: string + enum: [blocker, warning] + description: 严重性 + + PublishRequestResult: + type: object + description: 发布申请提交结果 + required: [requestId, status] + properties: + requestId: + type: string + format: uuid + description: 发布申请 ID + status: + type: string + enum: [submitted, reviewing] + description: 申请状态 + + PublishRecordItem: + type: object + description: 发布记录条目 + required: [assetId, assetName, assetType, status] + properties: + assetId: + type: string + format: uuid + assetName: + type: string + assetType: + type: string + enum: [work, agent, knowledge_base] + version: + type: string + status: + type: string + enum: [draft, submitted, reviewing, needs_supplement, approved, rejected, listed, delisted, recalled] + nextAction: + type: string + description: 下一步操作提示 + governanceStatus: + type: string + appealStatus: + type: string + exposureRange: + type: string + description: 曝光区间摘要 + + # ------------------------------------------------------------------ + # 治理结果 + # ------------------------------------------------------------------ + + GovernanceImpactResult: + type: object + description: 治理影响范围 + properties: + assetId: + type: string + format: uuid + governanceResult: + $ref: '#/components/schemas/GovernanceResultSummary' + affectedAuthorizations: + type: array + items: + $ref: '#/components/schemas/AffectedAuthorization' + description: 受影响的授权记录 + affectedInstallations: + type: array + items: + $ref: '#/components/schemas/AffectedInstallation' + description: 受影响的安装记录 + affectedBindings: + type: array + items: + $ref: '#/components/schemas/AffectedBinding' + description: 受影响的作品绑定 + affectedTasks: + type: array + items: + $ref: '#/components/schemas/AffectedTask' + description: 受影响的运行中任务 + affectedCandidates: + type: array + items: + $ref: '#/components/schemas/AffectedCandidate' + description: 受影响的 Shadow 候选和知识草稿 + exportRestrictions: + type: array + items: + type: string + description: 导出限制说明 + suggestedActions: + type: array + items: + type: string + description: 建议动作 + + GovernanceResultSummary: + type: object + description: 治理结果摘要 + properties: + resultType: + type: string + enum: [delist, recall, revoke, appeal] + description: 结果类型 + reason: + type: string + description: 原因摘要 + effectiveAt: + type: string + format: date-time + description: 生效时间 + scope: + type: string + description: 影响范围说明 + newAcquireStopped: + type: boolean + newInstallStopped: + type: boolean + newBindStopped: + type: boolean + generationUseStopped: + type: boolean + + AffectedAuthorization: + type: object + properties: + licenseId: + type: string + format: uuid + status: + type: string + description: 当前授权状态 + impact: + type: string + description: 影响说明 + + AffectedInstallation: + type: object + properties: + installationId: + type: string + format: uuid + status: + type: string + impact: + type: string + suggestedAction: + type: string + + AffectedBinding: + type: object + properties: + bindingId: + type: string + format: uuid + workId: + type: string + format: uuid + workName: + type: string + description: 脱敏作品名 + bindingType: + type: string + impact: + type: string + + AffectedTask: + type: object + properties: + taskId: + type: string + format: uuid + taskType: + type: string + status: + type: string + impact: + type: string + + AffectedCandidate: + type: object + properties: + candidateId: + type: string + format: uuid + candidateType: + type: string + enum: [shadow_candidate, knowledge_draft] + impact: + type: string + suggestedAction: + type: string + + # ------------------------------------------------------------------ + # 申诉 + # ------------------------------------------------------------------ + + AppealSubmitResult: + type: object + description: 申诉提交结果 + required: [appealId, status, processingDeadline] + properties: + appealId: + type: string + format: uuid + status: + type: string + enum: [pending, reviewing] + processingDeadline: + type: string + description: 预计处理周期 + supplementEntryAvailable: + type: boolean + description: 是否可补充材料 + + # ------------------------------------------------------------------ + # 管理端: 资产 + # ------------------------------------------------------------------ + + AdminMarketAssetSummary: + type: object + description: 管理端资产列表摘要 + required: [assetId, name, assetType, publisherName, listingStatus, reviewStatus] + properties: + assetId: + type: string + format: uuid + name: + type: string + assetType: + type: string + enum: [work, agent, knowledge_base] + publisherId: + type: string + format: uuid + publisherName: + type: string + version: + type: string + listingStatus: + type: string + enum: [not_listed, listed, stop_new_acquire, stop_new_install, stop_new_bind, stop_generation, delisted, recalled] + reviewStatus: + type: string + enum: [pending, reviewing, needs_supplement, approved, rejected, compliance_blocked] + installCount: + type: integer + description: 安装数量 + bindCount: + type: integer + description: 绑定数量 + appealCount: + type: integer + description: 申诉数量 + sourceStatus: + type: string + description: 来源状态 + + AdminMarketAssetDetail: + type: object + description: 管理端资产治理详情 + required: [assetId, name, assetType, listingStatus, reviewStatus] + properties: + assetId: + type: string + format: uuid + name: + type: string + assetType: + type: string + enum: [work, agent, knowledge_base] + publisherId: + type: string + format: uuid + publisherName: + type: string + version: + type: string + listingStatus: + type: string + enum: [not_listed, listed, stop_new_acquire, stop_new_install, stop_new_bind, stop_generation, delisted, recalled] + reviewStatus: + type: string + enum: [pending, reviewing, needs_supplement, approved, rejected, compliance_blocked] + licenseInfo: + $ref: '#/components/schemas/LicenseInfo' + installCount: + type: integer + bindCount: + type: integer + affectedTaskCount: + type: integer + sourceReferenceSummary: + type: string + description: 来源引用摘要 + governanceHistory: + type: array + items: + $ref: '#/components/schemas/AdminGovernanceHistoryItem' + appeals: + type: array + items: + $ref: '#/components/schemas/AdminAppealSummary' + + AdminGovernanceHistoryItem: + type: object + description: 治理历史条目 + properties: + action: + type: string + description: 治理动作(如 delist / recall / restore) + reason: + type: string + operatorId: + type: string + format: uuid + operatedAt: + type: string + format: date-time + scope: + type: string + + # ------------------------------------------------------------------ + # 管理端: 治理影响预览 + # ------------------------------------------------------------------ + + AdminGovernanceImpactPreview: + type: object + description: 管理端治理影响预览 + required: [previewId, actionType, scope, affectedCounts] + properties: + previewId: + type: string + format: uuid + description: 预览 ID(关联到后续下架/召回操作) + actionType: + type: string + enum: [delist, recall, revoke_license, stop_generation] + scope: + type: string + affectedCounts: + $ref: '#/components/schemas/AffectedCounts' + sourceReferenceSummary: + type: string + description: 来源引用摘要 + notificationScope: + type: string + description: 通知范围说明 + alternativeAssets: + type: array + items: + type: string + description: 可替代资产建议 + + AffectedCounts: + type: object + description: 受影响数量聚合 + properties: + authorizationCount: + type: integer + installationCount: + type: integer + bindingCount: + type: integer + runningTaskCount: + type: integer + shadowCandidateCount: + type: integer + knowledgeDraftCount: + type: integer + + # ------------------------------------------------------------------ + # 管理端: 发布审核 + # ------------------------------------------------------------------ + + AdminPublishRequestSummary: + type: object + description: 管理端发布申请摘要 + required: [requestId, assetId, assetName, assetType, status] + properties: + requestId: + type: string + format: uuid + assetId: + type: string + format: uuid + assetName: + type: string + assetType: + type: string + enum: [work, agent, knowledge_base] + publisherId: + type: string + format: uuid + publisherName: + type: string + version: + type: string + status: + type: string + enum: [pending, reviewing, needs_supplement, approved, rejected, compliance_blocked] + riskTags: + type: array + items: + type: string + submittedAt: + type: string + format: date-time + rightsDeclaration: + type: string + privacyCheckResult: + type: string + description: 隐私/密钥检查结果 + + # ------------------------------------------------------------------ + # 管理端: 申诉 + # ------------------------------------------------------------------ + + AdminAppealSummary: + type: object + description: 管理端申诉摘要 + required: [appealId, appealType, status, assetId] + properties: + appealId: + type: string + format: uuid + appealType: + type: string + enum: [review_rejection, delist, recall, license_revocation, usage_impact] + status: + type: string + enum: [pending, reviewing, supplementing, maintained, restored, closed] + appellantId: + type: string + format: uuid + appellantName: + type: string + assetId: + type: string + format: uuid + assetName: + type: string + submittedAt: + type: string + format: date-time + processorId: + type: string + format: uuid + + AdminAppealDetail: + type: object + description: 管理端申诉详情 + required: [appealId, appealType, status, assetId, reason] + properties: + appealId: + type: string + format: uuid + appealType: + type: string + enum: [review_rejection, delist, recall, license_revocation, usage_impact] + status: + type: string + enum: [pending, reviewing, supplementing, maintained, restored, closed] + appellantId: + type: string + format: uuid + appellantName: + type: string + assetId: + type: string + format: uuid + assetName: + type: string + assetVersion: + type: string + reason: + type: string + description: 申诉理由 + evidenceMaterials: + type: array + items: + type: string + description: 证据材料标识列表 + currentGovernanceStatus: + type: string + description: 当前治理状态 + originalResult: + type: string + description: 原审核/下架/召回结论 + processingHistory: + type: array + items: + $ref: '#/components/schemas/AppealProcessingHistoryItem' + supplementRecords: + type: array + items: + $ref: '#/components/schemas/AppealSupplementRecord' + + AppealProcessingHistoryItem: + type: object + description: 申诉处理历史条目 + properties: + action: + type: string + processorId: + type: string + format: uuid + processedAt: + type: string + format: date-time + reason: + type: string + + AppealSupplementRecord: + type: object + description: 申诉补充材料记录 + properties: + supplementId: + type: string + format: uuid + submittedBy: + type: string + format: uuid + submittedAt: + type: string + format: date-time + description: + type: string + attachmentIds: + type: array + items: + type: string + +tags: + - name: MarketDiscovery + description: 市场发现与分类推荐 + - name: MarketAsset + description: 资产详情与可信信息 + - name: MarketFavorite + description: 收藏 + - name: MarketLicense + description: 授权获取 + - name: MarketInstall + description: 安装 + - name: MarketHandoff + description: 跨空间 Handoff 跳转授权 + - name: MarketPublish + description: 发布提交 + - name: MarketGovernance + description: 治理结果展示 + - name: MarketAppeal + description: 申诉 + - name: AdminMarket + description: 管理端市场资产管理 + - name: AdminMarketReview + description: 管理端发布申请审核 + - name: AdminMarketAppeal + description: 管理端申诉处理