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

# 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<void>

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

---

# 10. Migration Context

```ts
interface MigrationContext {
  pluginId?: string

  fromVersion: string

  toVersion: string

  logger: Logger

  database: MigrationDatabase

  config: MigrationConfig

  metadata: Record<string, unknown>
}
```

---

# 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<BackupReference>
}
```

可以接：

```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<void>

  up(): Promise<void>

  verify?(): Promise<void>
}
```

---

# 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，而不是“一次性后台项目”的关键基础设施。**