Skip to content

14-skill-lifecycle.md

Latest commit

 

History

History
155 lines (105 loc) · 5.09 KB

14-skill-lifecycle.md

File metadata and controls

155 lines (105 loc) · 5.09 KB
Raw

Skill Lifecycle

Date: 2026-03-18 Status: current code-aligned reference

本文件是 skill 生命周期的单一规范入口。结论以当前代码实现为准，并已经同步到领域模型、业务流程、API、前端、搜索和兼容层文档。

1. 设计原则

  • skill 生命周期不再被建模为一个混杂状态机，而是拆分为容器状态、版本状态、审核工作流状态和可见性覆盖层
  • 前端不再从 status + hidden + latestVersionStatus + viewingVersionStatus 拼装状态，而统一消费后端 lifecycle projection
  • destructive action 和 reversible action 必须分离；withdraw-review 只表示撤回提审，不表示删除版本
  • 对外仍可保留 latest 协议词汇，但内部语义必须严格等价于 latest published

2. 状态模型

2.1 Skill 容器状态

  • ACTIVE
  • ARCHIVED

说明：

  • hidden 是独立治理覆盖层，不属于 Skill.status
  • SkillStatus.HIDDEN 不再视为有效生命周期语义

2.2 SkillVersion 版本状态

  • DRAFT
  • PENDING_REVIEW
  • PUBLISHED
  • REJECTED
  • YANKED

状态含义：

  • DRAFT：可再次提交审核或删除的非公开版本
  • PENDING_REVIEW：冻结待审版本
  • PUBLISHED：当前可分发版本
  • REJECTED：审核拒绝后保留的版本
  • YANKED：曾发布、现已撤回分发的版本

2.3 ReviewTask 审核工作流状态

  • PENDING
  • APPROVED
  • REJECTED

ReviewTask 仅表达审核流程，不再被前端当作展示态来源。

3. 核心语义

3.1 Latest

  • Skill.latestVersionId 的唯一语义是 latest published pointer
  • 它只能指向 PUBLISHED 版本
  • 若 skill 没有任何已发布版本，则允许为 null
  • latest 系统保留标签自动跟随该指针

3.2 Lifecycle Projection

详情页、我的技能、我的收藏、搜索等读模型统一基于以下 projection：

  • headlineVersion：当前页面主展示版本
  • publishedVersion：最新已发布版本
  • ownerPreviewVersion：owner / namespace 管理者可见的待审核预览版本
  • resolutionMode：PUBLISHED / OWNER_PREVIEW / NONE

约束：

  • 公开浏览、安装、下载、搜索只认 publishedVersion
  • owner 详情页只有在不存在 publishedVersion 时，才允许 headlineVersion = ownerPreviewVersion
  • promotion、compat latest、默认下载等公开分发行为都只能绑定 publishedVersion

4. 代码实际链路

4.1 首次上传

  • 普通用户上传后直接创建 PENDING_REVIEW 版本
  • 同时创建 PENDING review task
  • 不会创建初始 DRAFT
  • 不会更新 latestVersionId

4.2 审核通过

  • PENDING_REVIEW -> PUBLISHED
  • review task 标记为 APPROVED
  • Skill.latestVersionId 指向该版本
  • skill 展示元数据从发布版本刷新

4.3 审核拒绝

  • PENDING_REVIEW -> REJECTED
  • review task 标记为 REJECTED
  • 版本保留，可后续删除

4.4 撤回审核

  • withdraw-review 的统一语义是 PENDING_REVIEW -> DRAFT
  • 同时删除关联的 PENDING review_task
  • 该操作是可逆、非破坏性的
  • 当前代码只允许提交人本人撤回

4.5 重传新版本

  • 若发现旧的 PENDING_REVIEW 版本，会先把旧版本自动降回 DRAFT
  • 然后创建新的待审版本
  • 自动撤回与手动撤回必须保持同一语义

4.6 已发布版本重发

  • rerelease 当前本质上是从已发布版本复制并重新走发布流程
  • 当前实现允许特权路径直接产出新 PUBLISHED 版本
  • 该能力应被理解为发布路径特例，不是生命周期展示态

4.7 隐藏 / 恢复 / 归档 / 撤回已发布版本

  • 隐藏：只改 hidden=true
  • 恢复：只改 hidden=false
  • 归档：Skill.status = ARCHIVED
  • 取消归档：Skill.status = ACTIVE
  • yank：PUBLISHED -> YANKED

4.8 Yank 后指针修正

  • yank 已发布版本时，若命中当前 latestVersionId，必须重算 latest published pointer
  • 若仍有其他 PUBLISHED 版本，则指向最新一个
  • 若已无任何 PUBLISHED 版本，则 latestVersionId = null

5. 对外协议约束

5.1 Public / Search / Compat

  • 对外协议可以继续暴露 latestVersion、latest、默认下载等概念
  • 但它们都必须严格表示“最新已发布版本”
  • compat 层内部实现必须从统一 lifecycle projection 的 publishedVersion 映射，不允许自行推导“当前版本”

5.2 Frontend

  • 页面状态展示统一消费 projection
  • 不再新增旧兼容字段依赖
  • hidden 仅作为治理标记展示，不参与版本状态拼装

6. 权限边界

  • withdraw-review：仅提交人本人
  • 删除版本：owner 或 namespace 管理者，且仅限 DRAFT / REJECTED
  • 归档 / 取消归档：owner 或 namespace 管理者
  • 隐藏 / 恢复技能、撤回已发布版本：平台技能治理权限

7. 当前最终约束

  • 一个 skill 生命周期的唯一规范入口就是本文件
  • 其它文档如 02-domain-model、05-business-flows、06-api-design、08-frontend-architecture 必须与本文件保持一致
  • 若后续代码再次改变生命周期语义，应先修改代码，再同步更新本文件和相关子文档