Marketplace Package Lifecycle: 端到端补全与实现任务清单

[hotlong]

ObjectStack Marketplace Package Lifecycle — 补全与实现任务清单

背景

基于 Issue #766 的协议任务梳理，当前 Marketplace Package 生命周期设计��完成 67%。要实现完整的包安装、升级、分发、依赖解析、命名空间防冲突等能力，不仅需要补全协议，还要开发多端运行时包、工具与 API。此 issue 汇总所有必须开发的细节，分为协议补全/测试，CLI 工具，核心运行时，API 服务，Studio 集成，云端服务六大类。

---

1. 协议层任务补全与测试

• 补全 Storage & Distribution 协议：在 marketplace.zod.ts 增加 ArtifactReferenceSchema，关联到 MarketplaceListingSchema 的 version 记录。定义产物下载URL（url）、SHA256（sha256）、文件大小（size）、上传时间（uploadedAt）等字段。
• 补全 Namespace Collision 协议：在 package-registry.zod.ts 添加 NamespaceRegistryEntrySchema、NamespaceConflictErrorSchema、InstalledPackageSchema.registeredNamespaces。
• 新增协议测试文件：补全每个新建 Schema 的测试文件：
  • package-artifact.test.ts
  • dependency-resolution.test.ts
  • package-upgrade.test.ts（如尚无）
  • marketplace.test.ts（产物分发）
  • package-registry.test.ts（命名空间检测）
• index.ts 注册新协议：将 package-artifact.zod.ts、dependency-resolution.zod.ts 导出到 kernel/index.ts.
• 更新协议文档：补全所有新增字段的说明至 docs/references/kernel/*.mdx。

---

2. CLI 工具开发

• os plugin build：按 PackageArtifactSchema 规范生成 .tgz 包，包含 manifest、metadata、assets、data、locales、checksums、signature。
• os plugin validate：校验 .tgz 文件结构与完整性、数字签名与 SHA256。
• os plugin publish：上传产物到 marketplace（REST API），生成/校验 ArtifactReferenceSchema。支持 SHA256, RSA 签名校验。

---

3. Core/Runtime 功能实现

• 包依赖解析与平台兼容检测：在 package 安装流程中消费 DependencyResolutionResultSchema 和 manifest engine 字段，阻止不兼容平台版本的包。
• 命名空间冲突检测：安装包时注册/检查 namespace 是否冲突，支持 NamespaceConflictErrorSchema。
• 包升级流程（全生命周期）：支持 package-upgrade.zod.ts 描述的升级计划、快照、回滚能力。升级前后提供 impact 分析、依赖升级、migration 脚本执行。

---

4. REST API 服务

• Marketplace API：产物分发/安装/升级
  • /api/v1/packages/install：支持 InstallPackageRequestSchema，校验依赖、版本、命名空间、产物完整性。
  • /api/v1/packages/upgrade：支持 UpgradePackageRequestSchema，消费升级计划与回滚。
  • /api/v1/packages/resolve-dependencies：支持 DependencyResolutionResultSchema，返回拓扑排序、解决冲突。
  • /api/v1/packages/upload：支持 package artifact 上传/验证。

---

5. Studio Package Manager 集成

• Marketplace UI 集成：
  • 浏览/搜索 marketplace 列表（消费 MarketplaceListingSchema）
  • 安装包：展示依赖、平台版本要求、命名空间判冲突，消费 REST API
  • 执行升级：展示 impact 分析、依赖升级、migration 记录、回滚
  • 包卸载/切换/多包 workspace 支持

---

6. 云端 Marketplace 服务

• Artifact 存储分发与托管服务（新建 cloud-service）：
  • 产物上传/下载/URL生成
  • SHA256 校验与安全扫描
  • 产物数据结构校验与解包
  • 用户、包、版本管理
  • REST API 与 Studio/CLI 对接

---

验收标准

• 所有协议新增字段都有 .describe()，且是 .optional() 以保证兼容
• 所有新建协议文件都有对应 .test.ts
• index.ts 导出所有新协议
• ROADMAP.md、docs/references/kernel/*.mdx 文档同步更新
• CLI 工具可生成/校验/上传 .tgz 并对接 REST API
• 运行时可安装、依赖解析、升级、回滚包
• REST API 端点全部上线
• Studio UI 集成并实现完整包生命周期管理
• 云服务上线产物存储与下载