# 12_MIGRATION_VERSIONING_COMPATIBILITY.md ````md # DevOS Migration / Versioning / Compatibility > Version: 1.0 > Status: Implementation Specification > Target: Zcode > Previous: 11_PLUGIN_RUNTIME.md > Next: 13_* --- # 1. 目标 DevOS 必须支持长期演进。系统会不断发生： - DevOS Core 升级 - Plugin 升级 - Resource Schema 升级 - Action Schema 升级 - Event Schema 升级 - Database Migration - Configuration Migration - API Migration - Capability Migration - Skill Migration 因此必须建立统一的 Version / Migration / Compatibility Runtime。核心目标： ```text 旧版本 ↓ Compatibility Check ↓ Migration Plan ↓ Migration ↓ 新版本 ↓ Health Check ```` 禁止： ```text 直接覆盖直接 ALTER 直接删除旧字段直接升级 Plugin ``` 导致： ```text Plugin 崩溃数据丢失 Event Consumer 崩溃旧 API 不兼容正在执行的 Task 崩溃 ``` --- # 2. 核心原则 DevOS 的版本系统分为： ```text Platform Version Plugin Version Database Version API Version Resource Version Action Version Event Version Skill Version MCP Version Configuration Version ``` 这些版本不能混为一谈。 --- # 3. Platform Version DevOS Core 使用： ```text Semantic Versioning ``` 格式： ```text MAJOR.MINOR.PATCH ``` 例如： ```text 1.0.0 1.1.0 1.1.1 2.0.0 ``` 规则： ```text MAJOR = Breaking Change MINOR = Backward Compatible Feature PATCH = Bug Fix ``` --- # 4. Plugin Version Plugin 同样： ```text MAJOR.MINOR.PATCH ``` 例如： ```text devos.seo 1.2.3 ``` Plugin Version 与 DevOS Version 独立。 --- # 5. API Version DevOS Runtime API： ```text apiVersion = 1 ``` 例如： ```text Plugin API v1 Plugin API v2 ``` Plugin Manifest： ```json { "apiVersion": "1" } ``` --- # 6. Runtime API Compatibility Plugin 需要声明： ```json { "apiVersion": "1", "devos": { "minVersion": "1.0.0", "maxVersion": "<2.0.0" } } ``` 如果当前 DevOS： ```text 2.0.0 ``` 则 Plugin： ```text apiVersion 1 maxVersion < 2.0.0 ``` 必须被标记： ```text INCOMPATIBLE ``` --- # 7. Compatibility Matrix 实现： ```ts interface CompatibilityResult { compatible: boolean level: | 'compatible' | 'warning' | 'migration_required' | 'incompatible' reasons: CompatibilityIssue[] migrations?: MigrationReference[] } ``` --- # 8. Compatibility Issue ```ts interface CompatibilityIssue { code: string type: | 'api' | 'dependency' | 'schema' | 'resource' | 'action' | 'event' | 'config' | 'runtime' severity: | 'info' | 'warning' | 'error' message: string } ``` --- # 9. Migration Runtime 统一接口： ```ts interface Migration { id: string version: string description?: string up(context: MigrationContext): Promise down?(context: MigrationContext): Promise } ``` --- # 10. Migration Context ```ts interface MigrationContext { pluginId?: string fromVersion: string toVersion: string logger: Logger database: MigrationDatabase config: MigrationConfig metadata: Record } ``` --- # 11. Migration 必须可追踪数据库： ```text schema_migrations ``` 至少： ```ts interface MigrationRecord { id: string namespace: string version: string checksum: string status: | 'pending' | 'running' | 'completed' | 'failed' startedAt?: Date completedAt?: Date error?: string } ``` --- # 12. Migration Namespace Migration 必须属于： ```text core plugin ``` 例如： ```text core:2026_001 seo:2026_001 devops:2026_002 ``` --- # 13. Migration ID 必须唯一： ```text core.20260901.add_task_budget seo.20260901.add_keyword_difficulty ``` 禁止： ```text 001 002 003 ``` 这种全局容易冲突的 ID。 --- # 14. Migration 顺序 Migration 必须按照： ```text namespace + version ``` 确定顺序。例如： ```text seo.001 seo.002 seo.003 ``` 不能： ```text seo.003 seo.001 seo.002 ``` --- # 15. Migration 不允许自动修改历史一旦： ```text Migration = completed ``` 禁止修改 Migration 文件内容。如果发现错误：必须创建新的 Migration： ```text seo.004.fix_previous_migration ``` --- # 16. Migration Checksum 系统必须计算： ```text checksum(Migration) ``` 如果： ```text Migration Record checksum != Current checksum ``` 必须报错： ```text MIGRATION_CHECKSUM_MISMATCH ``` 防止已经执行的 Migration 被偷偷修改。 --- # 17. Database Migration 数据库 Migration 应该使用： ```text Prisma Migration ``` 或 DevOS Database Migration Adapter。推荐： ```text Prisma + DevOS Migration Registry ``` DevOS Runtime 不应该重新发明完整 SQL Migration Engine。 --- # 18. Migration Transaction 如果数据库支持，Migration 应尽量： ```text BEGIN ↓ Migration ↓ COMMIT ``` 失败： ```text ROLLBACK ``` 但对于： ```text 大型数据迁移外部 API 文件迁移 ``` 不能强制全部放入单一 Transaction。 --- # 19. Large Data Migration 大型 Migration： ```text 100万 records ``` 禁止： ```ts await db.updateMany(...) ``` 一次性完成。应该： ```text Batch ↓ 1000 ↓ 1000 ↓ 1000 ``` 并支持： ```text progress checkpoint resume ``` --- # 20. Migration Task 长时间 Migration 必须进入： ```text Task Runtime ``` 即： ```text Migration ↓ Task ↓ Job ↓ Worker ↓ Migration Action ``` 不要阻塞 HTTP Request。 --- # 21. Core Migration DevOS Core 升级： ```text Old Core ↓ Compatibility Check ↓ Backup ↓ Migration ↓ New Core ``` --- # 22. Plugin Migration Plugin： ```text 1.0.0 ↓ 1.1.0 ``` 如果 Schema 改变： ```text Migration Required ``` 例如： ```text seo.website ``` 新增： ```text healthScore ``` Migration： ```text 1.0 → 1.1 ``` --- # 23. Plugin Upgrade 完整流程： ```text Current Plugin ↓ Read New Manifest ↓ Validate Manifest ↓ Resolve Dependencies ↓ Compatibility Check ↓ Generate Migration Plan ↓ Backup ↓ Pause New Work ↓ Drain Running Work ↓ Migration ↓ Install New Version ↓ Register ↓ Health Check ↓ Resume ``` --- # 24. Upgrade Plan 必须先生成： ```ts interface UpgradePlan { pluginId: string fromVersion: string toVersion: string compatibility: CompatibilityResult migrations: MigrationReference[] dependencies: DependencyChange[] breakingChanges: string[] warnings: string[] requiresDowntime: boolean estimatedRisk: | 'low' | 'medium' | 'high' } ``` UI 应允许管理员在升级前查看。 --- # 25. Upgrade Preview Plugin Settings： ```text Upgrade available Current: 1.2.0 New: 1.3.0 Changes: + 3 new Actions + 2 new Resources + 1 DB migration Breaking: None Risk: Low [View Changes] [Upgrade] ``` --- # 26. Breaking Change 如果： ```text Resource schema breaking Action input breaking Action output breaking Event payload breaking Plugin API breaking ``` 必须： ```text MAJOR version ``` 例如： ```text 1.x.x ↓ 2.0.0 ``` --- # 27. Resource Versioning Resource： ```ts interface ResourceDefinition { id: string version: number schema: unknown actions: string[] events: string[] } ``` 例如： ```text devos.seo.website v1 ``` --- # 28. Resource Schema Evolution 允许： ```text 新增 optional field ``` 例如： ```json { "name": "example.com", "healthScore": 92 } ``` 旧 Consumer： ```text 只读取 name ``` 仍然正常。 --- # 29. Resource Breaking Change 例如： ```text name ``` 改成： ```text domain ``` 这是 Breaking Change。不能直接： ```text rename name → domain ``` 应该： ```text v1: name v2: domain ``` 并提供 Migration。 --- # 30. Action Versioning Action： ```text devos.seo.website.scan ``` 必须支持： ```text version ``` 例如： ```text devos.seo.website.scan@1 devos.seo.website.scan@2 ``` --- # 31. Action Input Compatibility 新增 Optional： ```text compatible ``` 删除 Required： ```text compatible ``` 改变类型： ```text breaking ``` 例如： ```text timeout: number ``` 变成： ```text timeout: string ``` 属于 Breaking。 --- # 32. Action Output Compatibility 同样： ```text 新增 optional field ``` 通常兼容。改变字段类型： ```text breaking ``` 删除字段： ```text breaking ``` --- # 33. Action Runtime Compatibility Action Registry 必须能够： ```text resolve(actionId, version) ``` 例如： ```ts resolve( 'devos.seo.website.scan', 1 ) ``` --- # 34. Action Alias 升级期间： ```text scan@1 scan@2 ``` 可以： ```text scan ``` 默认指向： ```text latest compatible ``` 但正在执行的 Task 必须锁定版本。 --- # 35. Task Version Lock 创建 Task： ```json { "actionId": "devos.seo.website.scan", "actionVersion": 1 } ``` 这样： ```text Plugin 升级 ``` 不会导致： ```text 正在运行的 Task ``` 突然使用新版 Action。 --- # 36. Job Version Lock Job 也应该保存： ```text actionVersion pluginVersion ``` 例如： ```text Job action = seo.scan actionVersion = 1 pluginVersion = 1.2.0 ``` --- # 37. Execution Version Execution 必须记录： ```text actionVersion pluginVersion runtimeVersion ``` 这样未来可以准确复盘： > 当时到底运行的是什么代码？ --- # 38. Event Versioning Event： ```text devos.seo.website.scanned ``` 必须： ```text version = 1 ``` 升级： ```text version = 2 ``` --- # 39. Event Backward Compatibility 推荐： ```text Producer ↓ Event v2 ``` Consumer 可以： ```text v1 v2 ``` 短期同时支持。 --- # 40. Event Migration Event 通常不应该修改历史。历史： ```text event v1 ``` 保持不变。如果需要： ```text v2 ``` 新 Consumer 使用 v2。不要： ```text UPDATE events SET payload = ... ``` 批量改历史 Event。 --- # 41. Event Adapter 如果 Plugin 只支持： ```text v1 ``` 但系统产生： ```text v2 ``` 可以使用： ```text Event Adapter ``` 例如： ```text v2 ↓ Adapter ↓ v1 ↓ Plugin ``` --- # 42. Skill Version Skill： ```text devos.seo.audit ``` 也必须有： ```text version ``` 例如： ```text 1.0.0 1.1.0 ``` Skill 变化可能包括： ```text instructions requiredCapabilities inputSchema outputSchema ``` --- # 43. Skill Compatibility 如果只是： ```text instruction improvement ``` 可以 MINOR/PATCH。如果： ```text input schema breaking ``` 应该： ```text MAJOR ``` --- # 44. MCP Version MCP Server / Adapter： ```text version ``` 必须记录。 Execution： ```text mcpServerVersion ``` 用于故障追踪。 --- # 45. Capability Version Capability： ```ts interface Capability { id: string version: number type: CapabilityType } ``` Agent Discovery 时： ```text capabilityId version ``` --- # 46. Capability Compatibility Agent Plan 创建后：必须锁定： ```text capabilityVersion actionVersion ``` 否则： ```text Agent Plan ``` 可能在执行过程中因为 Plugin 升级而产生不同结果。 --- # 47. Agent Plan Version Lock 例如： ```json { "steps": [ { "capability": "devos.seo.website.scan", "capabilityVersion": 1, "actionVersion": 1 } ] } ``` 这样 Plan 是可复现的。 --- # 48. Agent Replan 如果执行时发现： ```text Action v1 unavailable ``` Agent 可以： ```text Observation ↓ Compatibility Failure ↓ Replan ↓ Action v2 ``` 但是必须记录： ```text originalVersion newVersion reason ``` --- # 49. Configuration Version Plugin Settings 也必须版本化： ```ts interface ConfigurationVersion { namespace: string version: number schema: unknown } ``` 例如： ```text devos.seo.config v1 ``` --- # 50. Configuration Migration 例如：旧： ```json { "model": "gpt-x" } ``` 新： ```json { "ai": { "model": "gpt-x" } } ``` Migration： ```text v1 → v2 ``` --- # 51. Config Migration 必须可重复检测如果： ```text configVersion = 2 ``` 再次启动：不能再次执行： ```text v1 → v2 ``` --- # 52. Plugin State Migration Plugin 状态： ```text installed enabled disabled ``` 升级过程中必须有明确状态： ```text upgrading migration_running activating health_check ``` --- # 53. Upgrade Lock 同一个 Plugin： ```text 只能同时进行一次 Upgrade ``` 必须使用： ```text Distributed Lock ``` 例如： ```text lock: plugin:devos.seo ``` 防止： ```text Admin A upgrade Admin B upgrade ``` 同时发生。 --- # 54. Migration Lock 同一个 Migration Namespace： ```text core seo devops ``` 不能并发执行。 --- # 55. Upgrade Concurrency 不同 Plugin 可以： ```text Plugin A upgrade Plugin B upgrade ``` 并行。但： ```text 同一个 Plugin ``` 必须串行。 --- # 56. Running Task During Upgrade Plugin 升级时： ```text New Jobs ``` 默认： ```text pause ``` Running Jobs： ```text drain ``` 如果无法 drain： ```text 等待 ``` 超过： ```text grace period ``` 再按照 Plugin Shutdown Policy： ```text cancel checkpoint force stop ``` --- # 57. Task Compatibility Task 必须保存： ```text pluginVersion actionVersion runtimeVersion ``` 如果升级后仍然可以执行：继续。否则： ```text blocked ``` 并产生： ```text task.compatibility_failed ``` --- # 58. Job Compatibility Job 创建后： ```text job.actionVersion ``` 固定。 Worker 执行： ```text Action Registry ↓ Resolve exact version ``` 而不是： ```text latest ``` --- # 59. Execution Reproducibility Execution Detail 页面必须显示： ```text DevOS: 1.8.2 Plugin: devos.seo 1.4.0 Action: seo.website.scan v2 Skill: seo.audit v1 MCP: browser v3 ``` 这对于 Debug 非常重要。 --- # 60. Database Backup 高风险 Migration 前必须支持： ```text Backup ``` 但不要强制 DevOS 自己实现 PostgreSQL Backup Engine。提供： ```ts interface BackupProvider { createBackup(scope?: BackupScope): Promise } ``` 可以接： ```text pg_dump cloud snapshot managed database backup ``` --- # 61. Backup Policy Migration 可以声明： ```ts interface MigrationPolicy { requiresBackup: boolean allowDestructive: boolean maxDowntimeSeconds?: number } ``` --- # 62. Destructive Migration 例如： ```text DROP COLUMN DROP TABLE DELETE DATA ``` 必须： ```text destructive = true ``` 并需要： ```text explicit approval ``` --- # 63. Production Migration 生产环境： ```text destructive migration ``` 必须： ```text Preview + Backup + Approval ``` --- # 64. Zero Downtime 支持： ```text Expand ↓ Migrate ↓ Contract ``` 例如字段改名：错误： ```text DROP name ADD domain ``` 推荐： ```text Phase 1: ADD domain Phase 2: write both Phase 3: backfill Phase 4: read domain Phase 5: remove name ``` --- # 65. Expand / Contract 这是 DevOS 推荐的生产数据库演进方式。 ```text Old ↓ Expand ↓ Dual Read/Write ↓ Backfill ↓ Switch ↓ Contract ``` --- # 66. Plugin Upgrade Rollout 未来支持： ```text Canary ``` 例如： ```text 10% Organization ↓ Health ↓ 50% ↓ Health ↓ 100% ``` 第一阶段可以不实现 UI，但 Runtime 数据模型预留： ```text rolloutStrategy ``` --- # 67. Plugin Rollback Rollback： ```text Current 1.3.0 ↓ Rollback ↓ 1.2.0 ``` 但是必须先检查： ```text Database Schema Data Migration Action Compatibility Event Compatibility Task Compatibility ``` --- # 68. Rollback 不等于 Git Checkout 禁止简单： ```text npm install plugin@old ``` 然后认为已经 Rollback。如果： ```text DB schema = v3 ``` 而旧 Plugin 只支持： ```text DB schema = v2 ``` 必须： ```text Compatibility Check ``` --- # 69. Failed Upgrade Recovery 如果升级失败： ```text Upgrade ↓ Failure ``` 必须记录： ```text upgrade_failed ``` 包含： ```text fromVersion toVersion failedStep migration error timestamp ``` --- # 70. Recovery State Plugin 状态： ```text upgrade_failed ``` 不能继续正常运行。管理员看到： ```text Plugin upgrade failed Current state: Recovery required [View Error] [Retry] [Rollback] ``` --- # 71. Migration Events Migration 必须产生： ```text migration.started migration.completed migration.failed migration.rolled_back ``` Plugin： ```text plugin.upgrade.started plugin.upgrade.completed plugin.upgrade.failed plugin.rollback.completed ``` --- # 72. Migration Audit 所有 Migration： ```text Audit ``` 例如： ```text Admin Alice ↓ core.plugin.upgrade ↓ devos.seo 1.2.0 → 1.3.0 ↓ SUCCESS ``` --- # 73. Migration Logs 必须使用： ```text Logger ``` 自动带： ```text migrationId pluginId fromVersion toVersion ``` --- # 74. Migration Metrics 至少： ```text devos_migration_total devos_migration_success_total devos_migration_failed_total devos_migration_duration_ms ``` --- # 75. Version Registry 实现： ```ts interface VersionRegistry { register(component: VersionedComponent): void get(id: string): VersionedComponent[] resolve( id: string, version?: string ): VersionedComponent | undefined } ``` --- # 76. Versioned Component ```ts interface VersionedComponent { id: string version: string type: | 'plugin' | 'resource' | 'action' | 'skill' | 'mcp' | 'event' | 'api' } ``` --- # 77. Compatibility Registry 实现： ```ts interface CompatibilityRegistry { check( from: VersionedComponent, to: VersionedComponent ): CompatibilityResult } ``` --- # 78. Version Resolver 解析： ```text ^1.2.0 >=1.0.0 <2.0.0 1.4.2 ``` 推荐使用成熟 SemVer Library。不要自行实现 SemVer Parser。 --- # 79. Dependency Resolver Plugin Dependency： ```text A ↓ B ^1.2.0 ``` Resolver 必须： ```text find compatible version ``` 如果： ```text B installed = 2.0.0 ``` 则： ```text INCOMPATIBLE ``` --- # 80. Dependency Upgrade 如果： ```text A → B ^1 C → B ^2 ``` 不能简单升级 B。必须检测： ```text dependency conflict ``` 第一阶段：允许多个版本仅在 Runtime 明确支持的情况下存在。否则： ```text reject ``` --- # 81. Plugin Lock File DevOS 项目应该支持： ```text devos.lock ``` 例如： ```yaml plugins: devos.seo: version: 1.4.0 checksum: abc123 devos.browser: version: 2.1.0 checksum: def456 ``` 用于： ```text production CI/CD clone deployment ``` 保证环境一致。 --- # 82. Environment Reproducibility 开发： ```text devos.lock ``` 生产： ```text devos.lock ``` 必须得到相同 Plugin Version。 --- # 83. Plugin Installation Modes 支持： ```text development staging production ``` Development： ```text local plugin hot reload ``` Production： ```text immutable version checksum ``` --- # 84. Immutable Production Plugin 生产环境禁止： ```text latest ``` 必须： ```text exact version + checksum ``` 例如： ```text devos.seo@1.4.0 sha256=... ``` --- # 85. Core Upgrade DevOS Core 升级也必须产生： ```text Upgrade Plan Migration Plan Compatibility Report ``` 例如： ```text DevOS 1.8.0 → 1.9.0 Database: 3 migrations API: compatible Plugins: 12 compatible 1 warning 1 incompatible ``` --- # 86. Preflight Check 升级前： ```text devos upgrade check ``` 输出： ```text Core: compatible Database: ready Plugins: 12 OK 1 warning 1 incompatible Running Tasks: 3 Backup: available Result: NOT READY ``` --- # 87. Upgrade CLI 至少： ```text devos version devos upgrade check devos upgrade plan devos upgrade devos migrate status devos migrate run ``` CLI 必须进入： ```text Action Runtime ``` 如果这些操作属于改变系统状态。 --- # 88. Upgrade API 提供： ```http GET /api/system/version GET /api/system/upgrade/check GET /api/system/upgrade/plan POST /api/system/upgrade ``` --- # 89. Migration API ```http GET /api/migrations GET /api/migrations/:id POST /api/migrations/:id/run ``` Production 中： ```text run ``` 必须进行： ```text Permission Approval ``` --- # 90. UI：System Upgrade DevOS Settings： ```text System ├── Version ├── Updates ├── Migrations └── Compatibility ``` --- # 91. UI：Plugin Upgrade Plugin Settings： ```text Version 1.2.0 Update available: 1.3.0 Compatibility: ✓ API ✓ Database ✓ Dependencies ⚠ Running tasks Migration: 2 steps [View Plan] [Upgrade] ``` --- # 92. UI：Migration Detail 显示： ```text Migration ID: seo.20260901.add_health_score From: 1.2.0 To: 1.3.0 Status: Completed Duration: 4.2s Records: 12,381 ``` --- # 93. Migration Dry Run 支持： ```text dryRun = true ``` 例如： ```text devos migrate plan ``` 输出： ```text Will: ADD column health_score BACKFILL 12,381 rows Will NOT: DELETE data ``` --- # 94. Migration Validation Migration 前： ```text validate() ``` Migration 后： ```text verify() ``` 例如： ```ts interface Migration { validate?(): Promise up(): Promise verify?(): Promise } ``` --- # 95. Data Integrity Migration 必须能够验证： ```text row count foreign key unique constraint required field data format ``` --- # 96. Migration Checkpoint 大型 Migration： ```ts interface MigrationCheckpoint { migrationId: string cursor?: string processed: number total?: number updatedAt: Date } ``` Worker Crash： ```text Resume ``` 而不是： ```text 从 0 开始 ``` --- # 97. Migration 与 Queue 大型 Migration 应该： ```text Task ↓ Job ↓ Worker ``` 例如： ```text Migration Task ├── Batch Job 1 ├── Batch Job 2 ├── Batch Job 3 └── Batch Job N ``` --- # 98. Migration 与 Event Migration 大量修改数据时：默认不要产生： ```text 100000 business events ``` 例如： ```text backfill website.healthScore ``` 不应该自动发送： ```text website.updated ``` 100000 次。 Migration 可以声明： ```ts emitEvents: false ``` --- # 99. Migration Event Policy 支持： ```text none summary full ``` 例如： ```text none: 不产生业务 Event summary: 产生 migration.completed full: 产生每条业务 Event ``` 默认： ```text summary ``` --- # 100. Final Architecture 完成本规范后： ```text DevOS │ Version Registry │ ┌──────────────┼──────────────┐ ↓ ↓ ↓ Core Plugin API Version Version Version │ │ │ └──────────────┼──────────────┘ ↓ Compatibility Runtime │ Upgrade Planner │ ┌────────┴────────┐ ↓ ↓ Migration Dependency Runtime Resolver │ ↓ Task Runtime │ ↓ Job │ ↓ Worker │ ↓ Database │ ↓ Event │ ↓ Observability ``` --- # 101. 完整版本链 DevOS 最终必须能够回答： > 这个结果到底是哪个版本产生的？例如： ```text User ↓ Agent ↓ Goal ↓ Skill v2 ↓ Capability v3 ↓ Plugin devos.seo v1.8.2 ↓ Action seo.website.scan v2 ↓ Task ↓ Job ↓ Execution ↓ MCP browser v4 ↓ Event v2 ↓ Result ``` 所有关键节点都可追踪。 --- # 102. Acceptance Criteria ## Version * [ ] Core Version * [ ] Plugin Version * [ ] API Version * [ ] Resource Version * [ ] Action Version * [ ] Skill Version * [ ] MCP Version * [ ] Event Version * [ ] Configuration Version ## Migration * [ ] Migration Registry * [ ] Migration Record * [ ] Migration Checksum * [ ] Migration Ordering * [ ] Migration Transaction * [ ] Migration Dry Run * [ ] Migration Validation * [ ] Migration Verification * [ ] Migration Checkpoint * [ ] Large Data Migration * [ ] Migration Retry ## Compatibility * [ ] Compatibility Check * [ ] Dependency Resolver * [ ] API Compatibility * [ ] Resource Compatibility * [ ] Action Compatibility * [ ] Event Compatibility * [ ] Plugin Compatibility * [ ] Configuration Compatibility ## Upgrade * [ ] Upgrade Check * [ ] Upgrade Plan * [ ] Upgrade Preview * [ ] Backup * [ ] Upgrade Lock * [ ] Running Task Drain * [ ] Migration * [ ] Health Check * [ ] Rollback Strategy * [ ] Upgrade Failure Recovery ## Reproducibility * [ ] devos.lock * [ ] Plugin checksum * [ ] Exact Action Version * [ ] Exact Plugin Version * [ ] Exact MCP Version * [ ] Execution Version Metadata ## UI * [ ] System Version * [ ] Upgrade Check * [ ] Upgrade Plan * [ ] Migration List * [ ] Migration Detail * [ ] Plugin Upgrade * [ ] Compatibility Report --- # 103. Integration Tests 必须测试： ## Test 1 ```text Plugin 1.0 ↓ Upgrade ↓ Plugin 1.1 ↓ Migration ↓ Success ``` --- ## Test 2 Migration 修改数据库失败： ```text Migration ↓ Error ↓ Rollback ``` 数据库必须保持一致。 --- ## Test 3 Migration Checksum： ```text Executed Migration ↓ Modify Migration File ↓ Startup ↓ CHECKSUM_MISMATCH ``` --- ## Test 4 Action Version： ```text Task created actionVersion = 1 Plugin upgraded Task executes ↓ Action v1 ``` 不能自动变成 v2。 --- ## Test 5 Agent Plan： ```text Plan ↓ Capability v1 ↓ Plugin upgrade ↓ Execution ``` 必须仍然按照 Plan 锁定的版本执行，或者明确触发 Replan。 --- ## Test 6 Event Version： ```text Event v1 Event v2 ``` 两个 Consumer 可以分别消费。 --- ## Test 7 Plugin Dependency： ```text A → B ^1 B = 2 ``` 必须： ```text INCOMPATIBLE ``` --- ## Test 8 Production Plugin： ```text plugin@latest ``` 必须拒绝。必须使用： ```text exact version + checksum ``` --- ## Test 9 Concurrent Upgrade： ```text Admin A → upgrade SEO Admin B → upgrade SEO ``` 只能允许一个执行。 --- ## Test 10 Large Migration： ```text 1,000,000 records ``` Worker Crash： ```text 50% ↓ restart ↓ resume ``` 不能重新处理全部数据。 --- # 104. Zcode Implementation Rules Zcode 实现时必须遵守： ```text 1. 不自行发明完整 SemVer。 2. 不自行发明完整 Database Migration Engine。 3. 不修改已经执行的 Migration。 4. 不直接修改历史 Event。 5. 不让 Task 使用 latest Action。 6. 不让 Execution 使用 latest Plugin。 7. 不在升级过程中破坏 Running Task。 8. 不允许两个相同 Plugin 同时 Upgrade。 9. Production 禁止使用 latest Plugin。 10. Production Plugin 必须有 checksum。 11. Breaking Change 必须明确版本升级。 12. 长时间 Migration 必须使用 Task/Job/Worker。 13. Migration 必须产生 Audit。 14. Migration 必须产生 Observability 数据。 15. Upgrade 必须有 Compatibility Check。 16. Plugin Upgrade 必须有 Upgrade Plan。 17. Destructive Migration 必须显式批准。 18. Event Schema 必须版本化。 19. Action Schema 必须版本化。 20. Agent Plan 必须记录能力版本。 21. Execution 必须记录实际运行版本。 22. Rollback 必须经过 Compatibility Check。 23. Plugin 卸载不能默认删除业务数据。 24. Core Runtime 必须能够在 Plugin 升级失败时继续运行。 ``` --- # 105. 最终 Golden Rule DevOS 必须做到： ```text Never ask: "现在安装的是什么版本？" 而应该能够回答： "这个 Execution 当时运行的准确版本是什么？" ``` 因此最终 Execution 必须至少保存： ```text runtimeVersion pluginVersion actionVersion skillVersion mcpVersion eventVersion ``` 形成： ```text Execution │ ┌─────────────┼─────────────┐ ↓ ↓ ↓ Runtime Plugin Action Version Version Version │ │ │ └─────────────┼─────────────┘ ↓ Skill Version ↓ MCP Version ↓ Event Version ``` **这套 Version Lock 是 DevOS 能够真正作为长期运行的 Developer Work OS，而不是“一次性后台项目”的关键基础设施。**