mirror of https://github.com/iflytek/skillhub.git synced 2026-10-16 04:28:39 +00:00

Raymond 2bdb83bdb6 feat(publish): support metadata display names independent of skill slugs

Use optional metadata.display-name for skill titles while preserving stable
slugs and URLs. Keep published titles unchanged until review approval, and
cover localized title display and search with generic example fixtures.

Restore the fallback version title and summary when yanking the latest
published version, with regression coverage for the lifecycle boundaries.

Document the metadata field and retain existing behavior when it is absent.

Signed-off-by: Raymond <21071287+raymondtc@users.noreply.github.com>

2026-10-15 09:49:27 +08:00

5.8 KiB

Raw Blame History

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，并从回退版本的 metadata 恢复展示名和摘要
若仍有其他 PUBLISHED 版本，则指向最新一个
若已无任何 PUBLISHED 版本，则 latestVersionId = null

5. 对外协议约束

5.1 Public / Search / Compat

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

5.2 Frontend

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

5.3 提升更新与撤销

提升先要求团队来源版本 PUBLISHED，再单独进入平台提升审核；后续更新同一全局 Skill 时为它新增不可变的已发布版本。
全局 Skill 也可独立上传并审核。提升更新与独立上传使用相同版本号时不能互相覆盖；不同号版本分别发布，latest 指向最后通过审核的版本，不按版本字符串大小排序。
撤销提升不同于归档或隐藏：平台审核通过后移除全局派生 Skill 的公众入口及记录，保留来源团队 Skill、提升和撤销审计，并保护共用对象存储文件。重新提升形成新的全局 Skill ID。

6. 权限边界

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

7. 当前最终约束

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

5.8 KiB Raw Blame History Unescape Escape