devos/Docs/DevOS-Platform-v2/22_DEVOS_EXECUTION_ROADMAP.md

# DevOS Execution Roadmap

## DevOS 从架构设计到可执行开发的实施路线图

**文档编号：22**  
**所属体系：DevOS Platform Architecture**  
**状态：Implementation Roadmap**  
**优先级：P0**

---

# 1. 文档目标

前面的 01～21 文档已经定义了 DevOS 的总体架构。

现在最大的问题已经不是：

> “DevOS 应该有什么？”

而是：

> **“Zcode 接下来应该按照什么顺序把它真正做出来？”**

如果没有统一实施路线，很容易再次出现：

```text
开发一个功能
↓
顺便重构一个 Runtime
↓
又发现另一个 Runtime 缺失
↓
修改数据库
↓
修改 API
↓
修改 UI
↓
Agent 又需要另一套接口
↓
继续重构
```

最终变成：

```text
Architecture
    ↓
大量代码
    ↓
大量临时兼容层
    ↓
再次大规模重构
```

本文件的目标就是避免这一情况。

---

# 2. 最终实施原则

DevOS 后续开发必须遵循：

```text
先 Runtime
    ↓
再 Resource
    ↓
再 Action
    ↓
再 Task/Event
    ↓
再 Plugin/MCP/Agent
    ↓
再 UI
    ↓
最后业务 Module
```

不能反过来。

---

# 3. 当前 DevOS 的战略目标

DevOS 最终应该具备以下能力：

```text
                    DevOS
                      │
        ┌─────────────┼─────────────┐
        │             │             │
      Runtime      Platform      Extension
        │             │             │
        ▼             ▼             ▼
     Action         Auth          Plugin
     Task           RBAC          MCP
     Event          Tenant        Skill
     Data           Audit         Agent
     Storage        Config        Workflow
     Search         UI            Module
        │             │             │
        └─────────────┼─────────────┘
                      ▼
                Application
```

最终项目开发模式：

```text
DevOS
 ↓
Capabilities
 ↓
Modules
 ↓
Business Application
```

---

# 4. 开发优先级模型

所有开发任务分成四级：

```text
P0 = Foundation
P1 = Platform
P2 = Extension
P3 = Business
```

---

## P0 Foundation

没有这些，其他系统都不稳定。

包括：

```text
Runtime
Database
Configuration
Identity
Resource
Action
Execution
Error
Logging
Testing
```

---

## P1 Platform

建立完整平台能力：

```text
Task
Job
Queue
Event
Storage
Search
Notification
UI Shell
Plugin
MCP
Agent
Workflow
```

---

## P2 Extension

建立扩展生态：

```text
Skill
Provider
Connector
Integration
Module
Project Factory
SDK
CLI
```

---

## P3 Business

最后才是：

```text
SEO
CRM
DevOps
CMS
Content
Billing
其他行业模块
```

特别注意：

> SEO 不应该重新建立第二套 Agent / Task / MCP / Queue / Event 基础设施。

SEO 只是 DevOS Capability / Module。

---

# 5. Phase 0：代码审计

## 状态

```text
立即执行
```

在继续开发之前，Zcode 必须先对现有项目进行完整审计。

项目：

```text
/home/dev/bun/devos
```

---

## 审计内容

### 5.1 Repository

检查：

```text
目录结构
package.json
workspace
tsconfig
build
lint
test
docker
```

---

### 5.2 Backend

检查：

```text
Module
Controller
Service
Repository
Database
API
Auth
Queue
Worker
```

---

### 5.3 Frontend

检查：

```text
Router
Layout
Page
Component
API Client
State
Form
Table
Permission
```

---

### 5.4 Database

检查：

```text
Schema
Migration
Index
Foreign Key
Tenant Isolation
Audit
```

---

### 5.5 Existing Runtime

逐项确认：

```text
Action Runtime
Task Runtime
Event Runtime
Data Runtime
Storage Runtime
Config Runtime
Agent Runtime
MCP Runtime
Plugin Runtime
UI Runtime
```

---

# 6. 审计输出

必须生成：

```text
AUDIT.md
```

格式：

```markdown
# DevOS Implementation Audit

## Implemented

- Resource
- Action
- Auth

## Partial

- Task
- Event
- Plugin

## Missing

- Search Runtime
- Storage Runtime

## Incorrect

- Controller contains business logic
- Plugin bypasses Action Runtime

## Duplicate

- Multiple queue implementations
- Multiple notification systems

## Technical Debt

...
```

---

# 7. Phase 1：Foundation Runtime

这是整个项目最重要的阶段。

目标：

> **建立所有 Runtime 的共同执行基础。**

优先实现：

```text
Core Runtime
Resource Registry
Action Registry
Action Runtime
Execution
Error Runtime
Context
Permission
Audit
Observability
```

---

# 8. Phase 1 Package

建议：

```text
packages/
├── core/
├── runtime/
├── resource/
├── action/
├── execution/
├── permission/
├── identity/
├── error/
├── logging/
├── audit/
└── observability/
```

---

# 9. 第一条必须打通的链路

Zcode 首先必须完成：

```text
HTTP
 ↓
Controller
 ↓
Action Runtime
 ↓
Action
 ↓
Execution
 ↓
Event
 ↓
Audit
 ↓
Response
```

不能先做复杂 UI。

必须先让后端形成：

```text
统一执行入口
```

---

# 10. Phase 1 Acceptance

必须实现：

```text
Action Registry
Action Definition
Action Context
Action Runtime
Execution
Permission
Audit
Error
Logging
```

并且至少存在：

```text
core.health.check
core.user.create
core.user.list
```

三个真实 Action。

---

# 11. Phase 2：Identity Platform

目标：

```text
User
Organization
Project
Environment
Role
Permission
Session
API Key
Service Account
```

关系：

```text
User
 │
 ├── Organization
 │       │
 │       └── Project
 │               │
 │               └── Environment
 │
 └── Role
```

---

# 12. Identity 实施顺序

```text
User
 ↓
Session
 ↓
Organization
 ↓
Membership
 ↓
Role
 ↓
Permission
 ↓
Project
 ↓
Environment
```

---

# 13. Phase 2 Acceptance

必须做到：

```text
登录
退出
Session
用户
组织
角色
权限
Project
Environment
```

并且所有 Action 都能取得：

```ts
ActionContext.actor
ActionContext.organizationId
ActionContext.projectId
ActionContext.environmentId
```

---

# 14. Phase 3：Data Runtime

目标：

> 让所有业务模块不再自己发明 Repository / Query / Filter / Pagination。

实现：

```text
Schema
Field Definition
Repository
Query
Filter
Sort
Pagination
Relation
Scope
Search
Cache
```

---

# 15. Data Runtime 顺序

```text
Schema
 ↓
Repository
 ↓
Query
 ↓
Permission
 ↓
Scope
 ↓
Pagination
 ↓
Relation
```

然后：

```text
Search
 ↓
Index
 ↓
Cache
```

---

# 16. Data Runtime Acceptance

至少完成：

```text
core.user
core.organization
core.project
core.role
core.permission
```

全部迁移到统一 Data Runtime。

如果旧代码存在：

```ts
prisma.user.findMany()
```

业务 Service 中直接访问数据库：

必须逐步改成：

```ts
repository.query(...)
```

写入必须：

```text
Action
 ↓
Action Runtime
 ↓
Data Runtime
```

---

# 17. Phase 4：Configuration Runtime

实现：

```text
Configuration
Environment
Secret
Provider
Credential
Variable
```

顺序：

```text
Environment
 ↓
Config Definition
 ↓
Config Value
 ↓
Config Resolver
 ↓
Provider
 ↓
Credential
 ↓
Secret
```

---

# 18. Phase 4 Acceptance

必须实现：

```text
Global Config
Organization Config
Project Config
Environment Config
Plugin Config
Secret Reference
Provider
Credential
```

并确保：

```text
业务代码不能直接 process.env
```

---

# 19. Phase 5：Task / Job / Queue

这是 DevOS 能够真正运行 Agent / Automation 的关键。

实现：

```text
Task
Job
Queue
Worker
Execution
Scheduler
Retry
Lease
Heartbeat
Progress
Cancellation
```

---

# 20. Task Runtime 第一条链路

必须实现：

```text
Action
 ↓
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action Runtime
 ↓
Execution
```

例如：

```text
seo.website.scan
```

如果是异步 Action：

```text
Task
  └── Job
       └── Execution
```

---

# 21. Phase 5 Acceptance

必须测试：

```text
Queue
Worker
Retry
Timeout
Cancellation
Heartbeat
Crash Recovery
Dead Letter Queue
Idempotency
Concurrency
```

至少完成：

```text
1000 Jobs
10 Workers
```

的基本压力测试。

---

# 22. Phase 6：Event Runtime

实现：

```text
Event
Event Store
Event Bus
Outbox
Inbox
Subscription
Handler
Webhook
Notification
Realtime
```

核心链：

```text
Action
 ↓
Execution
 ↓
Event
 ↓
Event Bus
 ↓
Handler
```

---

# 23. Event Acceptance

至少完成：

```text
resource.created
resource.updated
resource.deleted
task.progress
task.completed
task.failed
```

同时实现：

```text
WebSocket
SSE
Notification Center
Webhook
```

---

# 24. Phase 7：Storage Runtime

实现：

```text
File
Blob
Artifact
Attachment
Storage Provider
Upload Session
Signed URL
File Processing
```

链路：

```text
Upload
 ↓
File
 ↓
Storage Runtime
 ↓
Provider
 ↓
Blob
```

Task：

```text
Task
 ↓
Artifact
 ↓
File
```

---

# 25. Phase 8：Search Runtime

实现：

```text
Search Runtime
Index Runtime
Search Definition
Global Search
Semantic Search
Hybrid Search
```

第一阶段建议：

```text
PostgreSQL FTS
+
pgvector
```

不要第一版就引入：

```text
Elasticsearch
OpenSearch
```

除非实际规模证明需要。

---

# 26. Phase 9：UI Shell

后端 Runtime 稳定后，开始建设：

```text
UI Shell
Router
Navigation
Resource UI
Action UI
Task UI
Search UI
Settings
Notification
Realtime
```

UI 必须读取：

```text
Resource Schema
Action Schema
Permission
Task
Event
```

而不是自己维护第二套业务定义。

---

# 27. Phase 10：Plugin Runtime

这是 DevOS 从“框架”变成“平台”的关键。

实现：

```text
Plugin Manifest
Plugin Registry
Plugin Lifecycle
Plugin Dependency
Plugin Configuration
Plugin UI
Plugin Resource
Plugin Action
Plugin Skill
Plugin MCP
Plugin Workflow
```

生命周期：

```text
discover
 ↓
install
 ↓
validate
 ↓
configure
 ↓
register
 ↓
activate
 ↓
health check
```

---

# 28. Plugin Acceptance

一个测试插件必须可以：

```text
注册 Resource
注册 Action
注册 UI Page
注册 Navigation
注册 Setting
注册 Skill
注册 MCP
```

然后：

```text
Install Plugin
 ↓
Capability Registry
 ↓
UI Registry
 ↓
Action Registry
```

全部自动完成。

---

# 29. Phase 11：MCP Runtime

实现：

```text
MCP Client
MCP Server
MCP Gateway
Tool Registry
Resource Registry
Adapter
Policy
```

关键原则：

```text
MCP Tool
 ↓
Capability
 ↓
Action Runtime
```

禁止：

```text
MCP Tool
 ↓
Database
```

---

# 30. Phase 12：Skill Runtime

Skill 负责：

> **告诉 Agent 如何解决问题。**

实现：

```text
Skill Registry
Skill Manifest
Skill Version
Skill Scope
Skill Discovery
Skill Instruction
```

例如：

```text
seo.content.production
seo.link.building
devops.deploy
crm.lead.followup
```

Skill 不执行数据库操作。

---

# 31. Phase 13：Agent Runtime

这是 DevOS AI 层。

实现：

```text
Goal
Context
Memory
Capability Discovery
Planning
Execution
Observation
Evaluation
Replanning
Budget
Approval
```

核心：

```text
Goal
 ↓
Agent
 ↓
Skill
 ↓
Capability
 ↓
Action
 ↓
Task
 ↓
Execution
 ↓
Event
 ↓
Observation
 ↓
Agent
```

---

# 32. Agent 第一版不要做什么

第一版禁止：

```text
复杂长期记忆
自动写代码并直接执行
无限自主 Agent
无限工具
无限循环
任意 Shell
任意文件系统
```

先实现：

```text
Goal
Plan
Action
Task
Observation
Replan
```

---

# 33. Phase 14：Workflow Runtime

Workflow 与 Agent 必须分开。

```text
Workflow
=
固定流程
```

例如：

```text
Webhook
 ↓
Validate
 ↓
Create Task
 ↓
Send Email
 ↓
Wait
 ↓
Approval
 ↓
Deploy
```

Agent：

```text
Goal
 ↓
动态规划
```

---

# 34. Workflow 必须支持

```text
Trigger
Condition
Action
Task
Delay
Wait
Approval
Parallel
Join
Retry
Timeout
Compensation
DAG
Subflow
```

---

# 35. Phase 15：Notification Runtime

统一：

```text
In-App
Email
Webhook
Push
```

不能让 Plugin 自己建立：

```text
email system
notification system
webhook system
```

全部进入：

```text
Notification Runtime
```

---

# 36. Phase 16：Observability

完整实现：

```text
Logging
Metrics
Tracing
Audit
Error
Health
Diagnostics
Usage
Cost
Alert
SLO
```

所有执行至少关联：

```text
requestId
correlationId
traceId
executionId
taskId
jobId
actor
```

---

# 37. Phase 17：Migration / Versioning

实现：

```text
Platform Version
Plugin Version
Resource Version
Action Version
Event Version
Skill Version
MCP Version
Configuration Version
```

然后：

```text
Migration Registry
Compatibility Registry
Upgrade Plan
Rollback
```

---

# 38. Phase 18：Project Factory

最后建设：

```text
devos create
devos add
devos remove
devos upgrade
devos doctor
```

支持：

```text
Preset
Capability
Module
Template
Project Manifest
```

例如：

```bash
devos create ai-saas my-app
```

---

# 39. Phase 19：Official Modules

平台稳定后再建立官方 Module：

```text
modules/
├── ai
├── billing
├── notification
├── workflow
├── knowledge
├── crm
├── devops
└── seo
```

注意：

```text
SEO
```

只允许存在：

```text
一个 AI SEO 产品 / Module
```

SEO 使用：

```text
Agent
Skill
MCP
Plugin
Workflow
Task
Search
Storage
```

但不重新实现这些基础设施。

---

# 40. Phase 20：Business Applications

这时候才开始：

```text
SEO
CRM
CMS
DevOps
Content
Analytics
```

因为此时基础设施已经成熟。

例如 SEO：

```text
SEO Module
    │
    ├── Website Resource
    ├── Keyword Resource
    ├── Backlink Resource
    ├── Content Resource
    │
    ├── SEO Actions
    ├── SEO Skills
    ├── SEO MCP
    ├── SEO Workflows
    └── SEO Agent Profiles
```

基础设施全部来自 DevOS。

---

# 41. 推荐完整 Phase

最终顺序：

```text
Phase 0
Audit
   ↓
Phase 1
Foundation Runtime
   ↓
Phase 2
Identity
   ↓
Phase 3
Data
   ↓
Phase 4
Configuration
   ↓
Phase 5
Task / Job / Queue
   ↓
Phase 6
Event
   ↓
Phase 7
Storage
   ↓
Phase 8
Search
   ↓
Phase 9
UI Shell
   ↓
Phase 10
Plugin
   ↓
Phase 11
MCP
   ↓
Phase 12
Skill
   ↓
Phase 13
Agent
   ↓
Phase 14
Workflow
   ↓
Phase 15
Notification
   ↓
Phase 16
Observability
   ↓
Phase 17
Versioning
   ↓
Phase 18
Project Factory
   ↓
Phase 19
Official Modules
   ↓
Phase 20
Business Applications
```

---

# 42. 不允许的开发顺序

以下方式禁止：

```text
先做 SEO UI
↓
再补 SEO API
↓
再补 Agent
↓
再补 Task
↓
再补 Queue
↓
再重构
```

也禁止：

```text
先做漂亮 Dashboard
```

然后发现：

```text
没有统一 Resource
没有 Action
没有 Task
没有 Event
```

最终 UI 全部需要重写。

---

# 43. Zcode 每阶段执行规则

Zcode 每次开始开发前必须读取：

```text
ARCHITECTURE.md
```

以及相关：

```text
XX_*.md
```

然后输出：

```text
Implementation Plan
```

包括：

```text
1. Existing code
2. Required changes
3. New packages
4. Database changes
5. API changes
6. UI changes
7. Migration
8. Tests
9. Compatibility
10. Acceptance
```

---

# 44. 禁止“顺手重构”

Zcode 不允许因为一个功能：

```text
顺手重构整个项目
```

必须遵循：

```text
Task Scope
```

例如：

```text
Implement Task Runtime
```

不能顺便：

```text
Rewrite UI
Rewrite Auth
Rewrite Plugin
Rewrite Database
```

除非依赖关系明确证明必要。

---

# 45. Vertical Slice 验证

每个 Runtime 不能只实现 Interface。

必须做：

```text
Vertical Slice
```

例如 Action Runtime：

```text
API
 ↓
Action
 ↓
Permission
 ↓
Execution
 ↓
Audit
 ↓
Event
 ↓
DB
```

全部真实跑通后才能标记：

```text
Implemented
```

而不是：

```text
Interface exists
```

---

# 46. Definition of Done

一个 Runtime 只有满足以下条件才算完成：

```text
[ ] TypeScript API
[ ] Runtime implementation
[ ] Database schema
[ ] Migration
[ ] Permission
[ ] Audit
[ ] Error handling
[ ] Logging
[ ] Metrics
[ ] Tests
[ ] Integration test
[ ] API
[ ] UI
[ ] Documentation
[ ] CLI if applicable
[ ] Plugin integration
[ ] Agent integration if applicable
```

---

# 47. 每阶段必须有 Demo

例如：

## Action Runtime Demo

```text
Create User
```

完整执行：

```text
HTTP
 ↓
Auth
 ↓
Permission
 ↓
Action
 ↓
Execution
 ↓
DB
 ↓
Audit
 ↓
Event
```

---

## Task Runtime Demo

```text
Generate 100 Articles
```

执行：

```text
Task
 ├── Job 1
 ├── Job 2
 ├── ...
 └── Job 100
```

---

## Agent Demo

```text
Goal:
Analyze website
```

：

```text
Agent
 ↓
Skill
 ↓
Capability Search
 ↓
Plan
 ↓
Task
 ↓
Jobs
 ↓
Actions
 ↓
Events
 ↓
Observation
 ↓
Report
```

---

# 48. 自动化测试金字塔

必须建立：

```text
              E2E
             /   \
        Integration
          /       \
       Runtime   API
        /           \
     Unit -------- Schema
```

建议：

```text
Unit Tests
大量

Integration Tests
核心 Runtime 必须覆盖

E2E
核心用户流程覆盖
```

---

# 49. Contract Tests

所有 Runtime 都必须有 Contract Test。

例如：

```text
ActionRuntimeContract
TaskRuntimeContract
EventRuntimeContract
StorageRuntimeContract
SearchRuntimeContract
PluginRuntimeContract
MCPRuntimeContract
AgentRuntimeContract
```

这样未来替换内部实现时：

```text
Contract
 ↓
Implementation
```

不会破坏上层。

---

# 50. CI Pipeline

建议：

```text
Pull Request
      ↓
Lint
      ↓
Type Check
      ↓
Unit Test
      ↓
Integration Test
      ↓
Build
      ↓
Migration Check
      ↓
Plugin Contract Test
      ↓
E2E
```

---

# 51. Release Pipeline

```text
Development
 ↓
Canary
 ↓
Staging
 ↓
Production
```

Production 必须记录：

```text
DevOS Version
Plugin Versions
Module Versions
Migration Version
Git Commit
Build ID
```

---

# 52. 技术债务处理原则

技术债务分成：

```text
P0 Blocking
P1 Architectural
P2 Quality
P3 Cosmetic
```

P0：

```text
Security
Data corruption
Permission bypass
Runtime bypass
```

必须立即修复。

P1：

```text
Duplicate Runtime
Direct DB Access
Plugin bypass
```

必须进入近期架构迁移。

P2：

```text
Refactoring
Performance
Test coverage
```

持续处理。

P3：

```text
UI cleanup
Naming
Minor DX
```

最后处理。

---

# 53. Direct Database Access Migration

这是 Zcode 后续审计的重点。

搜索：

```text
prisma.
db.
redis.
```

然后分类：

```text
Infrastructure
Runtime
Business
Plugin
Controller
Agent
Worker
```

规则：

```text
Infrastructure
可以

Runtime
可以

Business
必须通过 Runtime

Plugin
必须通过 Runtime

Agent
禁止

Controller
禁止

UI
禁止
```

---

# 54. Direct Queue Access Migration

搜索：

```text
queue.add()
worker.process()
redis.lpush()
```

业务层必须改为：

```text
Task Runtime
```

即：

```text
Business
 ↓
Task
 ↓
Job
 ↓
Queue
```

---

# 55. Direct Event Migration

搜索：

```text
emit()
publish()
webhook()
notify()
```

统一进入：

```text
Event Runtime
```

而不是每个模块自己建立事件机制。

---

# 56. Direct Secret Migration

搜索：

```text
process.env
```

逐步迁移：

```text
process.env
     ↓
Configuration Runtime
     ↓
Secret / Provider Runtime
```

---

# 57. Plugin Migration

所有已有 Plugin 必须检查：

```text
[ ] Resource
[ ] Action
[ ] Permission
[ ] Config
[ ] UI
[ ] Task
[ ] Event
[ ] Skill
[ ] MCP
```

任何 Plugin 如果自己实现：

```text
Queue
EventBus
Auth
Permission
Notification
Secret
Storage
```

都必须迁移。

---

# 58. Agent Migration

所有已有 AI 功能必须检查：

```text
是否直接访问 DB？
是否直接调用 API？
是否直接执行 Shell？
是否直接控制 Queue？
是否绕过 Permission？
是否自己保存 Task？
```

全部必须迁移到：

```text
Agent
 ↓
Capability
 ↓
Action Runtime
```

---

# 59. Runtime Dependency Rule

Runtime 依赖必须尽量单向：

```text
Core
 ↓
Identity
 ↓
Resource
 ↓
Action
 ↓
Execution
 ↓
Task
 ↓
Event
 ↓
Extension
 ↓
UI
```

禁止循环依赖：

```text
UI → Agent → UI
```

或：

```text
Plugin → UI → Plugin
```

---

# 60. Package Dependency Rule

推荐：

```text
@devos/core
    ↑
@devos/resource
    ↑
@devos/action
    ↑
@devos/task
    ↑
@devos/plugin
    ↑
@devos/agent
```

业务：

```text
@devos/seo
```

依赖平台：

```text
@devos/core
@devos/resource
@devos/action
@devos/task
@devos/search
@devos/agent
```

而不是反过来。

---

# 61. Monorepo 最终结构

```text
devos/
│
├── apps/
│   ├── api/
│   ├── web/
│   ├── worker/
│   └── cli/
│
├── packages/
│   ├── core/
│   ├── identity/
│   ├── resource/
│   ├── action/
│   ├── execution/
│   ├── data/
│   ├── task/
│   ├── queue/
│   ├── worker/
│   ├── event/
│   ├── storage/
│   ├── search/
│   ├── config/
│   ├── secret/
│   ├── provider/
│   ├── plugin/
│   ├── mcp/
│   ├── skill/
│   ├── agent/
│   ├── workflow/
│   ├── notification/
│   ├── observability/
│   ├── migration/
│   └── frontend-runtime/
│
├── modules/
│   ├── ai/
│   ├── billing/
│   ├── workflow/
│   ├── knowledge/
│   └── seo/
│
├── templates/
│
├── docs/
│
└── devos.project.yaml
```

---

# 62. 数据库演进策略

数据库必须跟随 Runtime 演进。

推荐：

```text
Prisma Schema
       ↓
Prisma Migration
       ↓
DevOS Migration Registry
       ↓
Application Migration
```

不要建立第二套 SQL Migration Engine。

---

# 63. Redis 使用边界

Redis 默认用于：

```text
Queue
Cache
Lock
Lease
Heartbeat
Realtime coordination
Rate Limit
Temporary state
```

不能作为：

```text
Primary Database
```

除非明确的特殊场景。

---

# 64. PostgreSQL 使用边界

PostgreSQL：

```text
Resource
Task
Job
Execution
Event
Audit
Config
User
Plugin
Agent Run
Workflow
```

全部作为持久事实来源。

---

# 65. Storage 使用边界

对象存储：

```text
Blob
File Content
Artifact
Large Export
Build Artifact
Agent Output
```

PostgreSQL 只保存：

```text
Metadata
Reference
Checksum
Provider
Key
```

---

# 66. 第一阶段不要过度工程化

DevOS 不应该第一版就同时引入：

```text
Kafka
Kubernetes
Elasticsearch
Temporal
NATS
ClickHouse
复杂 Service Mesh
```

优先：

```text
PostgreSQL
Redis
Object Storage
Docker
```

建立 Runtime Abstraction。

未来需要时：

```text
Provider
```

替换实现。

---

# 67. Provider Strategy

例如 Queue：

```ts
interface QueueProvider {}
```

第一实现：

```text
Redis Queue
```

未来：

```text
RabbitMQ
NATS
Kafka
SQS
```

同理：

```text
StorageProvider
SearchProvider
SecretProvider
NotificationProvider
ModelProvider
```

---

# 68. Agent Model Provider

Agent 不允许绑定：

```text
OpenAI
```

必须：

```text
ModelProvider
```

支持：

```text
OpenAI
Anthropic
Google
Local
Compatible API
```

并通过：

```text
Model Registry
Model Policy
```

选择。

---

# 69. 版本锁定

Production 必须：

```text
@devos/core@1.4.2
```

不能：

```text
@devos/core@latest
```

Plugin 同样：

```text
plugin.version
plugin.checksum
```

必须进入：

```text
devos.lock
```

---

# 70. 每次 Agent Execution 必须可追踪

最终任意 Agent 运行，都应该回答：

```text
哪个用户？
哪个 Agent？
哪个 Skill？
哪个 Plugin？
哪个 Action？
哪个版本？
哪个 Task？
哪个 Job？
哪个 Execution？
使用哪个 Model？
消耗多少 Token？
产生什么 Artifact？
发生了什么 Event？
```

这将是 DevOS 的核心可观测性能力。

---

# 71. 最终核心链

整个 DevOS 最终可以收敛成：

```text
                 USER
                   │
                   ▼
                  GOAL
                   │
             ┌─────▼─────┐
             │   AGENT   │
             └─────┬─────┘
                   │
                 SKILL
                   │
             CAPABILITY
                   │
                 ACTION
                   │
            ACTION RUNTIME
                   │
               EXECUTION
                   │
          ┌────────┴────────┐
          ▼                 ▼
        TASK              EVENT
          │                 │
        JOB             EVENT BUS
          │                 │
        QUEUE          NOTIFICATION
          │                 │
       WORKER            REALTIME
          │
        ACTION
          │
       DATABASE
          │
        STORAGE
          │
        SEARCH
```

---

# 72. DevOS 最终开发模型

未来开发者面对一个需求：

```text
“我要增加一个功能”
```

第一反应不能是：

```text
创建 Controller
创建 Service
创建 Repository
创建 Table
```

而必须问：

```text
这是 Resource 吗？
这是 Action 吗？
这是 Task 吗？
这是 Event 吗？
这是 Capability 吗？
这是 Skill 吗？
这是 Plugin 吗？
这是 Workflow 吗？
这是业务 Module 吗？
```

然后进入正确 Runtime。

---

# 73. Zcode 每个任务的标准输出

以后给 Zcode 的任务，建议统一使用：

```text
Task
├── Objective
├── Scope
├── Existing Architecture
├── Required Changes
├── Packages
├── Database
├── API
├── UI
├── Runtime Integration
├── Migration
├── Tests
├── Acceptance Criteria
└── Non-Goals
```

其中：

```text
Non-Goals
```

非常重要。

明确：

> 这次不做什么。

防止 AI 无限扩张修改范围。

---

# 74. 第一轮实施任务

现在不要一次让 Zcode 实现全部 21 份文档。

第一轮只执行：

```text
01 Audit
02 Foundation
03 Identity
04 Action
05 Execution
```

完成后再进入：

```text
Data
Task
Event
Storage
Search
```

---

# 75. 第一轮成功标准

必须做到：

```text
User
 ↓
Login
 ↓
Permission
 ↓
Resource
 ↓
Action
 ↓
Execution
 ↓
Audit
 ↓
Event
```

完整跑通。

然后：

```text
Action
 ↓
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Execution
```

再跑通。

这两条链打通以后，DevOS 才真正开始拥有：

> **统一 Runtime。**

---

# 76. 第二轮实施

完成：

```text
Data
Configuration
Storage
Search
Event
Notification
Realtime
```

目标：

```text
完整 Platform Runtime
```

---

# 77. 第三轮实施

完成：

```text
Plugin
MCP
Skill
Agent
Workflow
```

目标：

```text
Agent Platform
```

---

# 78. 第四轮实施

完成：

```text
UI Shell
Project Factory
CLI
SDK
Versioning
Migration
```

目标：

```text
Developer Platform
```

---

# 79. 第五轮实施

完成：

```text
AI
SEO
CRM
DevOps
Knowledge
Billing
```

目标：

```text
Application Ecosystem
```

---

# 80. 最终 Roadmap

```text
                    DevOS
                      │
                      ▼
               FOUNDATION
                      │
        ┌─────────────┴─────────────┐
        ▼                           ▼
    PLATFORM                     RUNTIME
        │                           │
        └─────────────┬─────────────┘
                      ▼
                  EXTENSION
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
      Plugin          MCP          Agent
        │             │             │
        └─────────────┼─────────────┘
                      ▼
                   MODULE
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
       SEO           CRM          DevOps
                      │
                      ▼
                  PROJECT
                      │
                      ▼
               PROJECT FACTORY
```

---

# 81. 最重要的验收指标

DevOS 第一阶段不要以：

```text
代码行数
页面数量
API 数量
```

作为主要成功指标。

真正指标应该是：

### Architecture

```text
多少业务代码进入统一 Runtime？
```

### Reuse

```text
多少功能可以跨项目复用？
```

### Extension

```text
Plugin 能否无需修改 Core 扩展？
```

### Agent

```text
Agent 是否使用与人相同的 Action Runtime？
```

### Operations

```text
Task / Job / Execution 是否完整可追踪？
```

### Upgrade

```text
DevOS 升级是否不会破坏项目？
```

### Project Factory

```text
新项目能否在分钟级获得完整基础设施？
```

---

# 82. 最终 Definition of DevOS

如果最终所有阶段完成，DevOS 应该能够做到：

```text
开发者：
    我要创建一个 SaaS
          ↓
DevOS Project Factory
          ↓
选择能力
          ↓
生成项目
          ↓
自动获得
    Auth
    RBAC
    Tenant
    Config
    Task
    Event
    Storage
    Search
    Notification
    Agent
    Workflow
    Plugin
    MCP
    UI
          ↓
开发者只编写 Business Domain
```

AI：

```text
User Goal
   ↓
Agent
   ↓
Skill
   ↓
Capability
   ↓
Action
   ↓
Task
   ↓
Execution
   ↓
Event
   ↓
Observation
   ↓
Result
```

最终：

> **DevOS 把“开发应用”本身变成了一种可组合、可自动化、可复用、可升级的能力。**

---

# 83. Zcode 最终执行铁律

### Rule 1

```text
先审计，再编码。
```

### Rule 2

```text
先 Runtime，再 UI。
```

### Rule 3

```text
先通 Vertical Slice，再扩功能。
```

### Rule 4

```text
不要重复造 Runtime。
```

### Rule 5

```text
不要让 Plugin 绕过 Runtime。
```

### Rule 6

```text
不要让 Agent 绕过 Action Runtime。
```

### Rule 7

```text
不要让 UI 承担业务逻辑。
```

### Rule 8

```text
不要让 Business 代码直接访问基础设施。
```

### Rule 9

```text
不要无边界重构。
```

### Rule 10

```text
每个阶段必须有测试和可运行 Demo。
```

### Rule 11

```text
每个 Runtime 必须拥有 Contract Test。
```

### Rule 12

```text
每个 Execution 必须可追踪。
```

### Rule 13

```text
每个 Plugin 必须可卸载、升级和禁用。
```

### Rule 14

```text
每个 Project 必须知道自己依赖哪些 DevOS Capability。
```

### Rule 15

```text
业务创新速度必须越来越快，而不是平台复杂度越来越高。
```

---

# 84. Golden Rule

DevOS 的整个实施路线最终收敛为：

```text
                    PLATFORM
                       │
                       ▼
                   RESOURCE
                       │
                       ▼
                    ACTION
                       │
                       ▼
                 ACTION RUNTIME
                       │
                       ▼
                   EXECUTION
                       │
             ┌─────────┴─────────┐
             ▼                   ▼
           TASK                EVENT
             │                   │
       JOB → QUEUE             BUS
             │                   │
          WORKER          NOTIFICATION
             │                   │
             └─────────┬─────────┘
                       ▼
                    AGENT
                       │
                 SKILL / MCP
                       │
                       ▼
                   PLUGIN
                       │
                       ▼
                    MODULE
                       │
                       ▼
                   PROJECT
                       │
                       ▼
              PROJECT FACTORY
```

最终原则：

> **DevOS 不应该越来越像一个“大型业务项目”，而应该越来越像一个“可以不断生产大型业务项目的平台”。**

因此未来每增加一个能力，都必须首先考虑：

```text
它能否成为 Capability？
它能否成为 Module？
它能否被 Plugin 扩展？
它能否被 Agent 调用？
它能否被 Project Factory 复用？
```

如果答案是“可以”，就应该进入 DevOS 平台体系。

如果只是某个业务的特殊规则，则应该留在：

```text
Business Module
```

而不是污染 Core。

---

# 85. 结论

前 01～21 份文档定义了：

```text
DevOS 应该是什么
```

本文件定义：

```text
DevOS 应该怎么做出来
```

真正实施时，必须坚持：

```text
Audit
 ↓
Foundation
 ↓
Runtime
 ↓
Platform
 ↓
Extension
 ↓
Agent
 ↓
Developer Platform
 ↓
Business Modules
 ↓
Project Factory
```

而不是：

```text
Feature
Feature
Feature
Feature
Feature
↓
最终重构
```

**DevOS 的最终成功标准不是“自己拥有多少功能”，而是：**

> **未来任何新项目，都能以越来越少的代码、越来越少的重复工作，获得越来越完整的平台能力。**

这才是 DevOS 存在的核心价值。