devos/Docs/DevOS-Platform-v2/12_MIGRATION_VERSIONING_COMPATIBILITY.md

12_MIGRATION_VERSIONING_COMPATIBILITY.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

禁止：

直接覆盖
直接 ALTER
直接删除旧字段
直接升级 Plugin

导致：

Plugin 崩溃
数据丢失
Event Consumer 崩溃
旧 API 不兼容
正在执行的 Task 崩溃

---

2. 核心原则

DevOS 的版本系统分为：

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 使用：

Semantic Versioning

格式：

MAJOR.MINOR.PATCH

例如：

1.0.0
1.1.0
1.1.1
2.0.0

规则：

MAJOR = Breaking Change

MINOR = Backward Compatible Feature

PATCH = Bug Fix

---

4. Plugin Version

Plugin 同样：

MAJOR.MINOR.PATCH

例如：

devos.seo
1.2.3

Plugin Version 与 DevOS Version 独立。

---

5. API Version

DevOS Runtime API：

apiVersion = 1

例如：

Plugin API v1
Plugin API v2

Plugin Manifest：

{
  "apiVersion": "1"
}

---

6. Runtime API Compatibility

Plugin 需要声明：

{
  "apiVersion": "1",
  "devos": {
    "minVersion": "1.0.0",
    "maxVersion": "<2.0.0"
  }
}

如果当前 DevOS：

2.0.0

则 Plugin：

apiVersion 1
maxVersion < 2.0.0

必须被标记：

INCOMPATIBLE

---

7. Compatibility Matrix

实现：

interface CompatibilityResult {
  compatible: boolean

  level:
    | 'compatible'
    | 'warning'
    | 'migration_required'
    | 'incompatible'

  reasons: CompatibilityIssue[]

  migrations?: MigrationReference[]
}

---

8. Compatibility Issue

interface CompatibilityIssue {
  code: string

  type:
    | 'api'
    | 'dependency'
    | 'schema'
    | 'resource'
    | 'action'
    | 'event'
    | 'config'
    | 'runtime'

  severity:
    | 'info'
    | 'warning'
    | 'error'

  message: string
}

---

9. Migration Runtime

统一接口：

interface Migration {
  id: string

  version: string

  description?: string

  up(context: MigrationContext): Promise<void>

  down?(context: MigrationContext): Promise<void>
}

---

10. Migration Context

interface MigrationContext {
  pluginId?: string

  fromVersion: string

  toVersion: string

  logger: Logger

  database: MigrationDatabase

  config: MigrationConfig

  metadata: Record<string, unknown>
}

---

11. Migration 必须可追踪

数据库：

schema_migrations

至少：

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 必须属于：

core
plugin

例如：

core:2026_001
seo:2026_001
devops:2026_002

---

13. Migration ID

必须唯一：

core.20260901.add_task_budget

seo.20260901.add_keyword_difficulty

禁止：

001
002
003

这种全局容易冲突的 ID。

---

14. Migration 顺序

Migration 必须按照：

namespace
+
version

确定顺序。

例如：

seo.001
seo.002
seo.003

不能：

seo.003
seo.001
seo.002

---

15. Migration 不允许自动修改历史

一旦：

Migration = completed

禁止修改 Migration 文件内容。

如果发现错误：

必须创建新的 Migration：

seo.004.fix_previous_migration

---

16. Migration Checksum

系统必须计算：

checksum(Migration)

如果：

Migration Record checksum
!=
Current checksum

必须报错：

MIGRATION_CHECKSUM_MISMATCH

防止已经执行的 Migration 被偷偷修改。

---

17. Database Migration

数据库 Migration 应该使用：

Prisma Migration

或 DevOS Database Migration Adapter。

推荐：

Prisma
+
DevOS Migration Registry

DevOS Runtime 不应该重新发明完整 SQL Migration Engine。

---

18. Migration Transaction

如果数据库支持，Migration 应尽量：

BEGIN
 ↓
Migration
 ↓
COMMIT

失败：

ROLLBACK

但对于：

大型数据迁移
外部 API
文件迁移

不能强制全部放入单一 Transaction。

---

19. Large Data Migration

大型 Migration：

100万 records

禁止：

await db.updateMany(...)

一次性完成。

应该：

Batch
 ↓
1000
 ↓
1000
 ↓
1000

并支持：

progress
checkpoint
resume

---

20. Migration Task

长时间 Migration 必须进入：

Task Runtime

即：

Migration
 ↓
Task
 ↓
Job
 ↓
Worker
 ↓
Migration Action

不要阻塞 HTTP Request。

---

21. Core Migration

DevOS Core 升级：

Old Core
 ↓
Compatibility Check
 ↓
Backup
 ↓
Migration
 ↓
New Core

---

22. Plugin Migration

Plugin：

1.0.0
 ↓
1.1.0

如果 Schema 改变：

Migration Required

例如：

seo.website

新增：

healthScore

Migration：

1.0 → 1.1

---

23. Plugin Upgrade

完整流程：

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

必须先生成：

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：

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

如果：

Resource schema breaking
Action input breaking
Action output breaking
Event payload breaking
Plugin API breaking

必须：

MAJOR version

例如：

1.x.x
 ↓
2.0.0

---

27. Resource Versioning

Resource：

interface ResourceDefinition {
  id: string

  version: number

  schema: unknown

  actions: string[]

  events: string[]
}

例如：

devos.seo.website
v1

---

28. Resource Schema Evolution

允许：

新增 optional field

例如：

{
  "name": "example.com",
  "healthScore": 92
}

旧 Consumer：

只读取 name

仍然正常。

---

29. Resource Breaking Change

例如：

name

改成：

domain

这是 Breaking Change。

不能直接：

rename name → domain

应该：

v1:
name

v2:
domain

并提供 Migration。

---

30. Action Versioning

Action：

devos.seo.website.scan

必须支持：

version

例如：

devos.seo.website.scan@1
devos.seo.website.scan@2

---

31. Action Input Compatibility

新增 Optional：

compatible

删除 Required：

compatible

改变类型：

breaking

例如：

timeout: number

变成：

timeout: string

属于 Breaking。

---

32. Action Output Compatibility

同样：

新增 optional field

通常兼容。

改变字段类型：

breaking

删除字段：

breaking

---

33. Action Runtime Compatibility

Action Registry 必须能够：

resolve(actionId, version)

例如：

resolve(
  'devos.seo.website.scan',
  1
)

---

34. Action Alias

升级期间：

scan@1
scan@2

可以：

scan

默认指向：

latest compatible

但正在执行的 Task 必须锁定版本。

---

35. Task Version Lock

创建 Task：

{
  "actionId": "devos.seo.website.scan",
  "actionVersion": 1
}

这样：

Plugin 升级

不会导致：

正在运行的 Task

突然使用新版 Action。

---

36. Job Version Lock

Job 也应该保存：

actionVersion
pluginVersion

例如：

Job
 action = seo.scan
 actionVersion = 1
 pluginVersion = 1.2.0

---

37. Execution Version

Execution 必须记录：

actionVersion
pluginVersion
runtimeVersion

这样未来可以准确复盘：

当时到底运行的是什么代码？

---

38. Event Versioning

Event：

devos.seo.website.scanned

必须：

version = 1

升级：

version = 2

---

39. Event Backward Compatibility

推荐：

Producer
 ↓
Event v2

Consumer 可以：

v1
v2

短期同时支持。

---

40. Event Migration

Event 通常不应该修改历史。

历史：

event v1

保持不变。

如果需要：

v2

新 Consumer 使用 v2。

不要：

UPDATE events
SET payload = ...

批量改历史 Event。

---

41. Event Adapter

如果 Plugin 只支持：

v1

但系统产生：

v2

可以使用：

Event Adapter

例如：

v2
 ↓
Adapter
 ↓
v1
 ↓
Plugin

---

42. Skill Version

Skill：

devos.seo.audit

也必须有：

version

例如：

1.0.0
1.1.0

Skill 变化可能包括：

instructions
requiredCapabilities
inputSchema
outputSchema

---

43. Skill Compatibility

如果只是：

instruction improvement

可以 MINOR/PATCH。

如果：

input schema breaking

应该：

MAJOR

---

44. MCP Version

MCP Server / Adapter：

version

必须记录。

Execution：

mcpServerVersion

用于故障追踪。

---

45. Capability Version

Capability：

interface Capability {
  id: string

  version: number

  type: CapabilityType
}

Agent Discovery 时：

capabilityId
version

---

46. Capability Compatibility

Agent Plan 创建后：

必须锁定：

capabilityVersion
actionVersion

否则：

Agent Plan

可能在执行过程中因为 Plugin 升级而产生不同结果。

---

47. Agent Plan Version Lock

例如：

{
  "steps": [
    {
      "capability": "devos.seo.website.scan",
      "capabilityVersion": 1,
      "actionVersion": 1
    }
  ]
}

这样 Plan 是可复现的。

---

48. Agent Replan

如果执行时发现：

Action v1 unavailable

Agent 可以：

Observation
 ↓
Compatibility Failure
 ↓
Replan
 ↓
Action v2

但是必须记录：

originalVersion
newVersion
reason

---

49. Configuration Version

Plugin Settings 也必须版本化：

interface ConfigurationVersion {
  namespace: string

  version: number

  schema: unknown
}

例如：

devos.seo.config
v1

---

50. Configuration Migration

例如：

旧：

{
  "model": "gpt-x"
}

新：

{
  "ai": {
    "model": "gpt-x"
  }
}

Migration：

v1 → v2

---

51. Config Migration 必须可重复检测

如果：

configVersion = 2

再次启动：

不能再次执行：

v1 → v2

---

52. Plugin State Migration

Plugin 状态：

installed
enabled
disabled

升级过程中必须有明确状态：

upgrading
migration_running
activating
health_check

---

53. Upgrade Lock

同一个 Plugin：

只能同时进行一次 Upgrade

必须使用：

Distributed Lock

例如：

lock:
plugin:devos.seo

防止：

Admin A upgrade
Admin B upgrade

同时发生。

---

54. Migration Lock

同一个 Migration Namespace：

core
seo
devops

不能并发执行。

---

55. Upgrade Concurrency

不同 Plugin 可以：

Plugin A upgrade
Plugin B upgrade

并行。

但：

同一个 Plugin

必须串行。

---

56. Running Task During Upgrade

Plugin 升级时：

New Jobs

默认：

pause

Running Jobs：

drain

如果无法 drain：

等待

超过：

grace period

再按照 Plugin Shutdown Policy：

cancel
checkpoint
force stop

---

57. Task Compatibility

Task 必须保存：

pluginVersion
actionVersion
runtimeVersion

如果升级后仍然可以执行：

继续。

否则：

blocked

并产生：

task.compatibility_failed

---

58. Job Compatibility

Job 创建后：

job.actionVersion

固定。

Worker 执行：

Action Registry
 ↓
Resolve exact version

而不是：

latest

---

59. Execution Reproducibility

Execution Detail 页面必须显示：

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 前必须支持：

Backup

但不要强制 DevOS 自己实现 PostgreSQL Backup Engine。

提供：

interface BackupProvider {
  createBackup(scope?: BackupScope): Promise<BackupReference>
}

可以接：

pg_dump
cloud snapshot
managed database backup

---

61. Backup Policy

Migration 可以声明：

interface MigrationPolicy {
  requiresBackup: boolean

  allowDestructive: boolean

  maxDowntimeSeconds?: number
}

---

62. Destructive Migration

例如：

DROP COLUMN
DROP TABLE
DELETE DATA

必须：

destructive = true

并需要：

explicit approval

---

63. Production Migration

生产环境：

destructive migration

必须：

Preview
+
Backup
+
Approval

---

64. Zero Downtime

支持：

Expand
 ↓
Migrate
 ↓
Contract

例如字段改名：

错误：

DROP name
ADD domain

推荐：

Phase 1:
ADD domain

Phase 2:
write both

Phase 3:
backfill

Phase 4:
read domain

Phase 5:
remove name

---

65. Expand / Contract

这是 DevOS 推荐的生产数据库演进方式。

Old
 ↓
Expand
 ↓
Dual Read/Write
 ↓
Backfill
 ↓
Switch
 ↓
Contract

---

66. Plugin Upgrade Rollout

未来支持：

Canary

例如：

10% Organization
 ↓
Health
 ↓
50%
 ↓
Health
 ↓
100%

第一阶段可以不实现 UI，但 Runtime 数据模型预留：

rolloutStrategy

---

67. Plugin Rollback

Rollback：

Current 1.3.0
 ↓
Rollback
 ↓
1.2.0

但是必须先检查：

Database Schema
Data Migration
Action Compatibility
Event Compatibility
Task Compatibility

---

68. Rollback 不等于 Git Checkout

禁止简单：

npm install plugin@old

然后认为已经 Rollback。

如果：

DB schema = v3

而旧 Plugin 只支持：

DB schema = v2

必须：

Compatibility Check

---

69. Failed Upgrade Recovery

如果升级失败：

Upgrade
 ↓
Failure

必须记录：

upgrade_failed

包含：

fromVersion
toVersion
failedStep
migration
error
timestamp

---

70. Recovery State

Plugin 状态：

upgrade_failed

不能继续正常运行。

管理员看到：

Plugin upgrade failed

Current state:
Recovery required

[View Error]
[Retry]
[Rollback]

---

71. Migration Events

Migration 必须产生：

migration.started
migration.completed
migration.failed
migration.rolled_back

Plugin：

plugin.upgrade.started
plugin.upgrade.completed
plugin.upgrade.failed
plugin.rollback.completed

---

72. Migration Audit

所有 Migration：

Audit

例如：

Admin Alice
 ↓
core.plugin.upgrade
 ↓
devos.seo
1.2.0 → 1.3.0
 ↓
SUCCESS

---

73. Migration Logs

必须使用：

Logger

自动带：

migrationId
pluginId
fromVersion
toVersion

---

74. Migration Metrics

至少：

devos_migration_total

devos_migration_success_total

devos_migration_failed_total

devos_migration_duration_ms

---

75. Version Registry

实现：

interface VersionRegistry {
  register(component: VersionedComponent): void

  get(id: string): VersionedComponent[]

  resolve(
    id: string,
    version?: string
  ): VersionedComponent | undefined
}

---

76. Versioned Component

interface VersionedComponent {
  id: string

  version: string

  type:
    | 'plugin'
    | 'resource'
    | 'action'
    | 'skill'
    | 'mcp'
    | 'event'
    | 'api'
}

---

77. Compatibility Registry

实现：

interface CompatibilityRegistry {
  check(
    from: VersionedComponent,
    to: VersionedComponent
  ): CompatibilityResult
}

---

78. Version Resolver

解析：

^1.2.0
>=1.0.0 <2.0.0
1.4.2

推荐使用成熟 SemVer Library。

不要自行实现 SemVer Parser。

---

79. Dependency Resolver

Plugin Dependency：

A
 ↓
B ^1.2.0

Resolver 必须：

find compatible version

如果：

B installed = 2.0.0

则：

INCOMPATIBLE

---

80. Dependency Upgrade

如果：

A → B ^1
C → B ^2

不能简单升级 B。

必须检测：

dependency conflict

第一阶段：

允许多个版本仅在 Runtime 明确支持的情况下存在。

否则：

reject

---

81. Plugin Lock File

DevOS 项目应该支持：

devos.lock

例如：

plugins:
  devos.seo:
    version: 1.4.0
    checksum: abc123

  devos.browser:
    version: 2.1.0
    checksum: def456

用于：

production
CI/CD
clone
deployment

保证环境一致。

---

82. Environment Reproducibility

开发：

devos.lock

生产：

devos.lock

必须得到相同 Plugin Version。

---

83. Plugin Installation Modes

支持：

development
staging
production

Development：

local plugin
hot reload

Production：

immutable version
checksum

---

84. Immutable Production Plugin

生产环境禁止：

latest

必须：

exact version
+
checksum

例如：

devos.seo@1.4.0
sha256=...

---

85. Core Upgrade

DevOS Core 升级也必须产生：

Upgrade Plan
Migration Plan
Compatibility Report

例如：

DevOS 1.8.0 → 1.9.0

Database:
3 migrations

API:
compatible

Plugins:
12 compatible
1 warning
1 incompatible

---

86. Preflight Check

升级前：

devos upgrade check

输出：

Core:
compatible

Database:
ready

Plugins:
12 OK
1 warning
1 incompatible

Running Tasks:
3

Backup:
available

Result:
NOT READY

---

87. Upgrade CLI

至少：

devos version

devos upgrade check

devos upgrade plan

devos upgrade

devos migrate status

devos migrate run

CLI 必须进入：

Action Runtime

如果这些操作属于改变系统状态。

---

88. Upgrade API

提供：

GET  /api/system/version

GET  /api/system/upgrade/check

GET  /api/system/upgrade/plan

POST /api/system/upgrade

---

89. Migration API

GET /api/migrations
GET /api/migrations/:id
POST /api/migrations/:id/run

Production 中：

run

必须进行：

Permission
Approval

---

90. UI：System Upgrade

DevOS Settings：

System
 ├── Version
 ├── Updates
 ├── Migrations
 └── Compatibility

---

91. UI：Plugin Upgrade

Plugin Settings：

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

显示：

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

支持：

dryRun = true

例如：

devos migrate plan

输出：

Will:
ADD column health_score
BACKFILL 12,381 rows

Will NOT:
DELETE data

---

94. Migration Validation

Migration 前：

validate()

Migration 后：

verify()

例如：

interface Migration {
  validate?(): Promise<void>

  up(): Promise<void>

  verify?(): Promise<void>
}

---

95. Data Integrity

Migration 必须能够验证：

row count
foreign key
unique constraint
required field
data format

---

96. Migration Checkpoint

大型 Migration：

interface MigrationCheckpoint {
  migrationId: string

  cursor?: string

  processed: number

  total?: number

  updatedAt: Date
}

Worker Crash：

Resume

而不是：

从 0 开始

---

97. Migration 与 Queue

大型 Migration 应该：

Task
 ↓
Job
 ↓
Worker

例如：

Migration Task
 ├── Batch Job 1
 ├── Batch Job 2
 ├── Batch Job 3
 └── Batch Job N

---

98. Migration 与 Event

Migration 大量修改数据时：

默认不要产生：

100000 business events

例如：

backfill website.healthScore

不应该自动发送：

website.updated

100000 次。

Migration 可以声明：

emitEvents: false

---

99. Migration Event Policy

支持：

none
summary
full

例如：

none:
不产生业务 Event

summary:
产生 migration.completed

full:
产生每条业务 Event

默认：

summary

---

100. Final Architecture

完成本规范后：

                     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 最终必须能够回答：

这个结果到底是哪个版本产生的？

例如：

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

Plugin 1.0
 ↓
Upgrade
 ↓
Plugin 1.1
 ↓
Migration
 ↓
Success

---

Test 2

Migration 修改数据库失败：

Migration
 ↓
Error
 ↓
Rollback

数据库必须保持一致。

---

Test 3

Migration Checksum：

Executed Migration
 ↓
Modify Migration File
 ↓
Startup
 ↓
CHECKSUM_MISMATCH

---

Test 4

Action Version：

Task created
actionVersion = 1

Plugin upgraded

Task executes
 ↓
Action v1

不能自动变成 v2。

---

Test 5

Agent Plan：

Plan
 ↓
Capability v1
 ↓
Plugin upgrade
 ↓
Execution

必须仍然按照 Plan 锁定的版本执行，或者明确触发 Replan。

---

Test 6

Event Version：

Event v1
Event v2

两个 Consumer 可以分别消费。

---

Test 7

Plugin Dependency：

A → B ^1
B = 2

必须：

INCOMPATIBLE

---

Test 8

Production Plugin：

plugin@latest

必须拒绝。

必须使用：

exact version
+
checksum

---

Test 9

Concurrent Upgrade：

Admin A → upgrade SEO
Admin B → upgrade SEO

只能允许一个执行。

---

Test 10

Large Migration：

1,000,000 records

Worker Crash：

50%
 ↓
restart
 ↓
resume

不能重新处理全部数据。

---

104. Zcode Implementation Rules

Zcode 实现时必须遵守：

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 必须做到：

Never ask:

"现在安装的是什么版本？"

而应该能够回答：

"这个 Execution 当时运行的准确版本是什么？"

因此最终 Execution 必须至少保存：

runtimeVersion
pluginVersion
actionVersion
skillVersion
mcpVersion
eventVersion

形成：

                  Execution
                      │
        ┌─────────────┼─────────────┐
        ↓             ↓             ↓
     Runtime        Plugin        Action
      Version        Version       Version
        │             │             │
        └─────────────┼─────────────┘
                      ↓
                  Skill Version
                      ↓
                  MCP Version
                      ↓
                  Event Version

这套 Version Lock 是 DevOS 能够真正作为长期运行的 Developer Work OS，而不是“一次性后台项目”的关键基础设施。