Marketplace Package Lifecycle: 必须开发的协议清单

[hotlong]

背景

基于 Git-based 开发模式，ObjectStack 的包分发链路为：

开发者本地 Git 开发 → 打包上传市场 → 用户在系统内下载安装/升级/卸载

经过与 Salesforce Packages 和 Power Apps Solutions 的深度对比分析，当前协议层（manifest.zod.ts、package-registry.zod.ts、marketplace.zod.ts）已经覆盖了包定义、命名空间、依赖声明、生命周期钩子、市场发布流程等核心能力。

但仍有 6 项关键缺失 阻塞整条链路的完整运行。以下按优先级分为 P0（阻塞链路）和 P1（阻塞升级场景）两组。

---

P0 — 阻塞整条链路（必须先完成）

任务 1: 包构建产物规范 (Package Artifact Format Spec)

问题: marketplace-publishing.md 提到 os plugin build 产生 .tgz，但没有定义产物内部结构的 Schema。市场无法校验、存储、分发一个没有标准格式的产物。

具体任务:

• 在 packages/spec/src/kernel/ 下创建 package-artifact.zod.ts
• 定义 PackageArtifactSchema，规范 .tgz 内部结构：

  ├── manifest.json          ← ManifestSchema 序列化
  ├── metadata/              ← 30+ metadata 类型的 JSON 序列化
  │   ├── objects/            ← *.object.json
  │   ├── views/              ← *.view.json
  │   ├── pages/              ← *.page.json
  │   ├── flows/              ← *.flow.json
  │   ├── dashboards/         ← *.dashboard.json
  │   ├── permissions/        ← *.permission.json
  │   ├── agents/             ← *.agent.json
  │   └── ...                 ← 其他 metadata 类型
  ├── assets/                ← 静态资源
  │   ├── icon.svg
  │   └── screenshots/
  ├── data/                  ← Seed data (DatasetSchema 序列化)
  ├── locales/               ← i18n 翻译文件
  ├── checksums.json         ← 每个文件的 SHA256 校验
  └── signature.sig          ← RSA-SHA256 包签名
  

• 定义 ArtifactChecksumSchema：文件路径 → SHA256 映射
• 定义 ArtifactSignatureSchema：签名算法、公钥引用、签名值
• 创建对应测试文件 package-artifact.test.ts
• 在 stack.zod.ts 的导出中注册

影响文件: 新建 packages/spec/src/kernel/package-artifact.zod.ts

---

任务 2: 平台版本兼容性声明 (Platform Version Compatibility)

问题: 当前 ManifestSchema 缺少平台最低版本要求字段。用户安装包时，系统无法判断"这个包能不能在当前版本的平台上运行"。

具体任务:

• 在 ManifestSchema（manifest.zod.ts）中增加字段：

  /** 最低平台版本要求 */
  engine: z.object({
    objectstack: z.string()
      .regex(/^[><=~^]*\d+\.\d+\.\d+/)
      .describe('ObjectStack platform version requirement (SemVer range, e.g. ">=3.0.0")'),
  }).optional().describe('Platform compatibility requirements'),

• 在 package-registry.zod.ts 的 InstallPackageRequestSchema 中增加兼容性校验逻辑的字段说明
• 更新现有测试 manifest.test.ts 增加新字段的测试用例
• 更新文档 content/docs/references/kernel/manifest.mdx

影响文件: 修改 packages/spec/src/kernel/manifest.zod.ts

---

任务 3: 产物存储与分发协议 (Artifact Storage & Distribution)

问题: 用户点击"安装"时，系统需要知道去哪里下载包产物。当前 MarketplaceListingSchema 没有定义产物的下载地址和完整性校验。

具体任务:

• 在 marketplace.zod.ts 中增加 ArtifactReferenceSchema：

  const ArtifactReferenceSchema = z.object({
    /** 产物下载 URL */
    url: z.string().url().describe('Artifact download URL'),
    /** SHA256 完整性校验 */
    sha256: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA256 checksum'),
    /** 文件大小 (bytes) */
    size: z.number().int().positive().describe('Artifact size in bytes'),
    /** 产物格式 */
    format: z.enum(['tgz', 'zip']).default('tgz').describe('Artifact format'),
    /** 上传时间 */
    uploadedAt: z.string().datetime().describe('Upload timestamp'),
  });

• 在 MarketplaceListingSchema 的 version 记录中关联 ArtifactReferenceSchema
• 在 InstallPackageRequestSchema 中增加 artifactUrl 或 artifactRef 字段
• 定义 ArtifactDownloadResponseSchema（用于 REST API）
• 更新测试和文档

影响文件: 修改 packages/spec/src/cloud/marketplace.zod.ts

---

P1 — 阻塞升级场景（安装跑通后必须完成）

任务 4: 升级版本迁移上下文 (Upgrade Migration Context)

问题: PluginLifecycleSchema 中 onUpgrade 钩子存在，但缺少版本上下文参数。开发者无法在升级钩子中编写"从 v1 到 v2 需要做什么迁移"的逻辑。

具体任务:

• 在 plugin.zod.ts 中定义 UpgradeContextSchema：

  const UpgradeContextSchema = z.object({
    /** 升级前版本 */
    previousVersion: z.string().describe('Version before upgrade'),
    /** 升级后版本 */
    newVersion: z.string().describe('Version after upgrade'),
    /** 是否为大版本升级 */
    isMajorUpgrade: z.boolean().describe('Whether this is a major version bump'),
    /** 已注册的 metadata 快照 (升级前) */
    previousMetadata: z.record(z.string(), z.unknown()).optional()
      .describe('Metadata snapshot before upgrade'),
  });

• 修改 PluginLifecycleSchema 中 onUpgrade 的签名描述，明确接收 UpgradeContext
• 在 package-registry.zod.ts 的升级流程中增加版本迁移记录：

  upgradeHistory: z.array(z.object({
    fromVersion: z.string(),
    toVersion: z.string(),
    upgradedAt: z.string().datetime(),
    status: z.enum(['success', 'failed', 'rolled_back']),
    migrationLog: z.array(z.string()).optional(),
  })).optional(),

• 更新测试

影响文件: 修改 packages/spec/src/kernel/plugin.zod.ts, package-registry.zod.ts

---

任务 5: 运行时依赖解析协议 (Dependency Resolution Protocol)

问题: ManifestSchema 声明了 dependencies，但缺少运行时依赖解析的结果 Schema。当安装 A 需要 B@^2.0，但已安装的 B 是 1.x 时，系统需要标准化的方式表达冲突和解决方案。

具体任务:

• 在 packages/spec/src/kernel/ 下创建 dependency-resolution.zod.ts
• 定义核心 Schema：

  /** 单个依赖的解析结果 */
  const ResolvedDependencySchema = z.object({
    packageId: z.string(),
    requiredRange: z.string().describe('SemVer range required (e.g. "^2.0.0")'),
    resolvedVersion: z.string().optional().describe('Actual version resolved'),
    status: z.enum([
      'satisfied',        // 已安装且版本兼容
      'needs_install',    // 未安装，需要安装
      'needs_upgrade',    // 已安装但版本不兼容，需要升级
      'conflict',         // 与其他包的依赖冲突
    ]),
  });
  
  /** 依赖解析总结果 */
  const DependencyResolutionResultSchema = z.object({
    /** 所有依赖的解析结果 */
    dependencies: z.array(ResolvedDependencySchema),
    /** 是否可以继续安装 */
    canProceed: z.boolean(),
    /** 需要用户确认的操作 */
    requiredActions: z.array(z.object({
      type: z.enum(['install', 'upgrade', 'confirm_conflict']),
      packageId: z.string(),
      description: z.string(),
    })),
    /** 安装顺序 (拓扑排序) */
    installOrder: z.array(z.string()).describe('Topologically sorted package IDs'),
    /** 检测到的循环依赖 */
    circularDependencies: z.array(z.array(z.string())).optional(),
  });

• 在 InstallPackageResponseSchema 中关联依赖解析结果
• 创建对应测试文件
• 在 kernel 导出中注册

影响文件: 新建 packages/spec/src/kernel/dependency-resolution.zod.ts

---

任务 6: 命名空间冲突检测协议 (Namespace Collision Detection)

问题: namespace 要求实例内唯一，但安装时缺少冲突检测和解决的标准化协议。

具体任务:

• 在 package-registry.zod.ts 中增加命名空间注册表概念：

  /** 命名空间注册项 */
  const NamespaceRegistryEntrySchema = z.object({
    namespace: z.string(),
    packageId: z.string().describe('Owning package ID'),
    registeredAt: z.string().datetime(),
    status: z.enum(['active', 'disabled', 'reserved']),
  });

• 在 InstallPackageResponseSchema 中增加命名空间冲突错误：

  const NamespaceConflictErrorSchema = z.object({
    type: z.literal('namespace_conflict'),
    requestedNamespace: z.string(),
    conflictingPackageId: z.string(),
    conflictingPackageName: z.string(),
    suggestion: z.string().optional()
      .describe('Suggested alternative namespace'),
  });

• 在 InstalledPackageSchema 中增加 registeredNamespaces 字段，追踪每个包占用了哪些命名空间
• 更新测试

影响文件: 修改 packages/spec/src/kernel/package-registry.zod.ts

---

实施顺序建议

Week 1:  任务 2 (platformVersion) + 任务 1 (Artifact Spec)
Week 2:  任务 3 (Storage & Distribution) + 任务 6 (Namespace Collision)
Week 3:  任务 5 (Dependency Resolution) + 任务 4 (Upgrade Context)
Week 3+: 运行 test suite，更新 roadmap 文档

验收标准

• 所有新建的 .zod.ts 文件都有对应的 .test.ts
• 所有新增字段都有 .describe() 注解
• 所有修改已有 Schema 的字段都是 .optional()（向后兼容）
• 文档站 (content/docs/references/kernel/) 中对应的 .mdx 文件已更新
• ROADMAP.md 和 ENTERPRISE_ASSESSMENT.md 中的相关条目已更新状态

参考文件

• packages/spec/src/kernel/manifest.zod.ts — 包定义
• packages/spec/src/kernel/package-registry.zod.ts — 包注册表
• packages/spec/src/cloud/marketplace.zod.ts — 市场协议
• packages/spec/src/kernel/plugin.zod.ts — 插件生命周期
• docs/design/marketplace-publishing.md — 市场发布设计文档
• docs/ENTERPRISE_ASSESSMENT.md — 企业能力评估