skillhub/openspec/changes/add-suite-bundle-publishing/proposal.md

Why

PR #828 已经完成 Suite 版本模型、套件专区搜索和原子安装，但创建或更新包含多个本地 Skill 的 Suite 时，维护者仍需逐个创建或上传 Skill，再手工把 Suite 固定到对应版本。Suite 还可能引用 维护者并不拥有的公开 Skill，因此 Bundle 发布必须区分“操作者有权创建或发布的包内容”和 “操作者只能复用的外部精确引用”。

What Changes

• 为创建和更新 Suite 增加共用的两阶段导入：通过一个 ZIP，或受支持浏览器选择的一个根目录， 一次提交多个 Skill 文件夹；先预览成员与发布动作，再明确确认。确认前不得创建 Skill、 SkillVersion、Suite、SuiteVersion、扫描或审核任务。
• Manifest 使用两种成员形式描述完整的目标 Suite 快照：一种是操作者有权发布的已有 Skill 包， 或操作者有权在目标 Namespace 创建的新 Skill 包；另一种是不修改、也不要求归 Suite 维护者 所有的精确 PUBLISHED SkillVersion 引用。
• Bundle 先校验唯一 Manifest、成员目录边界和文件归属，再将每个目录独立还原为以 SKILL.md 为根的普通 Skill 包，复用现有路径、大小、扩展名、内容签名、YAML、元数据和合规校验。任一成员 存在阻塞错误时不得确认，也不得通过猜测目录或静默选择冲突字段继续。
• 新增持久化 Bundle 发布操作。只有具备独立创建或发布权限且携带包的成员进入现有校验、扫描和 审核流程；所有包版本均为 PUBLISHED 且全部引用仍然有效后，才原子创建新 Suite 及首个草稿， 或为已有 Suite 创建 DRAFT SuiteVersion。
• Bundle 确认后进入独立发布任务详情；“我的套件”以“技能套件/发布任务”页签分离结果和过程， 发布任务按“需要处理/进行中/最近完成”分层。停止创建 Suite 后保留任务、已创建的 SkillVersion 和审核任务，并继续提供成员版本与审核入口。
• 未变化成员继续使用原精确版本，不创建版本、扫描或审核；支持添加、移除、调整顺序和显式重新 固定引用成员版本。
• 任意成员 Skill 均可展示当前用户可见的所属 Suite，不再只支持 Entry Skill。
• 技能市场（/search）与套件专区（/suites）保持独立。#828 已经交付的套件专区和类型化 Suite 搜索无需替换。
• 新 SuiteVersion 提交或发布前必须具备非空摘要和 Markdown 概述；不完整的 DRAFT 仍可保存， 已发布历史数据仍可读取。
• Suite 可以配置自己的 Label，并复用 Registry 的 Label 定义和权限类型，用于套件专区筛选。 Suite Label 不向成员 Skill 级联。Skill Tag 仍是指向 PUBLISHED SkillVersion 的版本别名，不引入 Suite。
• 暂不支持覆盖无权管理的已有 Skill、批量迁移 Namespace、按成员关键词提升 Suite 排名、CLI 上传 Bundle、嵌套 Suite 和跨 Registry 成员。

相对 Issue #847 的需求取舍

Issue 原提议	结论	OpenSpec 决策
上传一个多 Skill 归档	保留	归档只上传一次；预览使用不占位且有期限的 PreviewSession，确认后才创建并占位的 ExecutionOperation。
每个 Suite 成员都必须在归档中有目录	调整	只有需要发布内容的成员才提供包目录；纯引用成员在 Manifest 中填写精确已发布版本。
被引用 Skill 必须属于 Suite 维护者	拒绝	Suite 可以引用其他人发布的合规公开 Skill；引用权限与发布权限相互独立。
通过 fingerprint 判断包内容变化	保留并澄清	携带包的成员使用现有 Skill 规范化 fingerprint；纯引用成员比较精确 SkillVersion 身份。
未变化的包不升版、不重新扫描	保留	继续引用当前精确 SkillVersion。
变化的包沿用现有 Skill 发布流程	保留	仅限操作者已经具备该 Skill 的独立发布权限。
包成员变化后立刻创建 SuiteVersion	调整	等全部包版本 PUBLISHED、全部引用仍有效后，再创建一个 DRAFT SuiteVersion；创建模式同时原子创建 Suite 容器。
消除 N 次上传和 N 个审核任务	调整	消除 N 次人工上传，但变化 Skill 仍独立审核，Suite 仍保留自身审核。
Bundle 自动创建不存在的 Skill	保留并收紧	仅允许在操作者具备 Skill 创建权限的 Namespace 中创建；坐标冲突、越权或 Namespace 不可写时阻塞整个预览。
批量设置 labels/tags	调整	为 Suite 自身配置 Label，不向成员 Skill 扩散；Suite 不支持 SkillVersion Tag。
把 Suite 结果并入技能市场	拒绝	技能市场与套件专区保持分开；/suites 已提供 Suite 搜索和卡片。
成员关键词提升 Suite 排名	延后	相关性和隐私安全索引需要单独提案。
任意成员展示所属 Suite	保留	仅返回最新、可见、ACTIVE、非隐藏、PUBLISHED 的 Suite 引用，并标明是否为 Entry。
Suite 摘要或概述为空	调整	DRAFT 可暂时不完整，但新提交或直接发布必须同时具备摘要和概述，发布页不能用泛化文案冒充。
保留 #828 精确引用模型	保持不变	SuiteVersion 仍只引用精确 PUBLISHED SkillVersion，发布后保持不可变。

Capabilities

New Capabilities

• suite-bundle-publishing：从一个归档或根目录预览、确认、跟踪、恢复并完成 Suite 创建或更新， 同时严格区分有权创建/发布的包内容与非本人所有的精确版本引用。
• suite-member-discovery：保持技能市场与套件专区独立，同时让任意成员 Skill 展示经过隐私过滤的 所属 Suite。
• suite-metadata：要求 Suite 具备有效展示内容并支持 Suite 自有 Label，不修改成员 Skill 元数据 或 SkillVersion Tag。

Modified Capabilities

无。现有 add-skill-suites 变更尚未归档为主 OpenSpec capability；这些增量 capability 依赖它， 但不修改其精确引用和生命周期要求。

Impact

• 领域与持久化：新增 Bundle 操作、目标坐标占用、成员结果和 Suite-to-Label 关联；不增加 SkillVersion 或 SuiteVersion 生命周期状态。
• API / OpenAPI：新增预览、确认、状态、取消、重试和 Suite Label 接口；扩展 Skill 详情中的 Suite 引用和套件专区标签筛选；技能与套件发现 API 继续分开。
• 对象存储：按操作临时保存一个上传归档，支持过期和补偿清理；日志不得保存归档内容。
• 安全与治理：复用包校验、Scanner、Namespace 权限、单 Skill 审核、Suite 审核和审计规则； 管理 Suite 不会获得被引用 Skill 的发布权限。
• 性能：每个携带包成员只解压和计算一次 hash；批量读取引用与权限；未变化成员不扫描；限制 归档和成员规模；反向引用不得产生 N+1 查询。
• Web：在“创建 Suite”和“创建新版本”中增加手工组合/本地导入选择，新增 Bundle 差异预览、 权限提示和进度页；增加所属 Suite、发布信息校验、Suite Label，以及按需展开的 Entry Skill 固定版本说明。技能市场与套件专区导航保持不变。
• 兼容性：现有单 Skill 发布、单 Skill Label/Tag 管理、Suite 管理和安装 API、旧客户端以及 已发布 SuiteVersion 快照保持不变。

分阶段交付

OpenSpec 保留完整产品方向，但实现和 PR 按以下边界拆分，后续阶段不得绕过第一阶段建立的权限、 生命周期和性能约束：

1. Suite 创建/更新 Bundle、成员格式验证、权限重检、生命周期协调和 Web 进度闭环。
2. 基于 Suite 当前 latestVersionId 的任意成员反向发现。
3. Suite Label、展示信息发布校验、概述模板和 Entry Skill 固定版本说明。