devos/Docs/DevOS-Platform-v2/01_ARCHITECTURE.md — DevOS Platform v2 总体架构.md

# DevOS Platform v2
## 01 — Overall Architecture Specification

**Document Version:** 2.0  
**Status:** Architecture Specification  
**Target:** DevOS Platform  
**Implementation Target:** Zcode / AI Coding Agent

---

# 1. 文档目的

DevOS v2 不再被定义为单一的后台管理系统，而定义为：

> 一个可以承载多个 Application、Plugin、MCP、Skill、Agent 和 Workflow 的可扩展应用运行平台。

DevOS 的目标不是让每一个项目都重新开发：

- 登录
- 用户
- 权限
- 菜单
- Dashboard
- 文件
- 通知
- Task
- Job
- Event
- API
- Audit
- Agent
- MCP
- Plugin
- Settings

而是将这些能力沉淀为 DevOS Platform 的公共基础能力。

未来新产品原则：

```text
New Product
    ↓
Reuse DevOS Core
    ↓
Reuse DevOS Runtime
    ↓
Reuse DevOS UI
    ↓
Implement Business Domain
```

---

# 2. 核心目标

DevOS v2 必须解决以下问题。

## 2.1 多项目复用

多个产品共享：

```text
Authentication
Authorization
Users
Organizations
Roles
Permissions
Resources
Actions
Events
Tasks
Jobs
Files
Storage
Notifications
Audit
Settings
Search
API
UI
Agent Runtime
Plugin Runtime
MCP Runtime
Skill Runtime
```

---

## 2.2 应用可插拔

一个业务应用应该能够被安装到 DevOS，而不是修改 DevOS Core。

例如：

```text
DevOS
├── SEO
├── DevOps
├── Monitoring
├── CRM
└── Project Management
```

这些都应该是 App，而不是 Core。

---

## 2.3 能力可扩展

业务能力应该能够通过 Plugin 扩展。

例如：

```text
SEO App
├── Keyword Plugin
├── Content Plugin
├── Backlink Plugin
├── Search Console Plugin
└── Analytics Plugin
```

---

## 2.4 AI 原生

DevOS v2 必须从架构层面支持：

```text
Agent
Skill
MCP
Tool
Action
Context
Workflow
Memory
Event
```

Agent 不应该拥有一套独立的业务 API。

Agent 应该调用 DevOS 的统一 Action 系统。

---

# 3. 总体架构

DevOS v2 采用五层结构：

```text
┌─────────────────────────────────────────────┐
│                  Applications               │
│                                             │
│   SEO / DevOps / CRM / Monitoring / ...    │
├─────────────────────────────────────────────┤
│                  Extensions                 │
│                                             │
│ Plugin / MCP / Skill / Widget / Integration│
├─────────────────────────────────────────────┤
│                    Runtime                  │
│                                             │
│ App Runtime / Agent / Workflow / Scheduler │
├─────────────────────────────────────────────┤
│                     Core                   │
│                                             │
│ Auth / User / Permission / Resource /      │
│ Action / Event / Task / File / Audit       │
├─────────────────────────────────────────────┤
│                Infrastructure               │
│                                             │
│ PostgreSQL / Redis / Object Storage / Queue│
└─────────────────────────────────────────────┘
```

---

# 4. Architecture Principles

## 4.1 Core First

Core 只提供平台级能力。

Core 不允许包含具体业务领域。

允许：

```text
User
Role
Permission
Resource
Action
Task
Event
File
Audit
```

不允许：

```text
SEOKeyword
Backlink
CRMLead
Invoice
Campaign
```

这些属于 Application。

---

# 5. Core

DevOS Core 是所有 Application 共用的基础。

建议模块：

```text
core/
├── identity/
├── auth/
├── organization/
├── user/
├── role/
├── permission/
├── resource/
├── action/
├── event/
├── task/
├── job/
├── file/
├── storage/
├── notification/
├── audit/
├── settings/
├── search/
└── api/
```

---

# 6. Identity

Identity 管理：

```text
User
Organization
Membership
Session
Account
Identity Provider
```

支持：

```text
Email
Password
OAuth
OIDC
API Key
Service Account
Agent Identity
```

---

# 7. Authorization

DevOS v2 不使用单纯的：

```text
user -> role -> permission
```

而采用：

```text
Subject
    ↓
Permission
    ↓
Resource
    ↓
Action
    ↓
Scope
```

统一模型：

```text
Permission =
    subject
    + resource
    + action
    + scope
```

例如：

```text
seo.website.read
seo.website.update
seo.website.scan
seo.website.publish
```

---

# 8. Resource Model

Resource 是 DevOS 的核心抽象。

所有可管理对象都应该可以注册为 Resource。

例如：

```text
User
Website
Project
Keyword
Content
Backlink
Server
Deployment
Report
```

Resource 定义：

```ts
interface ResourceDefinition {
  name: string
  label: string

  schema: unknown

  actions: ActionDefinition[]

  permissions: PermissionDefinition[]

  ui?: ResourceUI

  events?: EventDefinition[]
}
```

---

# 9. Action Model

Resource 不只是 CRUD。

每个 Resource 可以拥有多个 Action。

例如：

```text
Website

read
create
update
delete
scan
analyze
verify
deploy
backup
```

Action：

```ts
interface ActionDefinition {
  name: string
  resource: string

  inputSchema?: unknown
  outputSchema?: unknown

  permission?: string

  execute(context, input): Promise<unknown>
}
```

---

# 10. Human 与 Agent 统一执行模型

这是 DevOS v2 最重要的设计之一。

UI：

```text
User
 ↓
UI
 ↓
Action
 ↓
Resource
```

Agent：

```text
Agent
 ↓
Skill
 ↓
Action
 ↓
Resource
```

MCP：

```text
MCP
 ↓
Action
 ↓
Resource
```

API：

```text
API
 ↓
Action
 ↓
Resource
```

最终全部进入：

```text
Action Runtime
```

因此业务逻辑不能写在：

```text
React Component
REST Controller
Agent
MCP Server
```

而应该写在：

```text
Action
```

---

# 11. Event Model

所有重要状态变化都应该产生 Event。

例如：

```text
website.created
website.updated
website.scan.started
website.scan.completed

content.created
content.published

backlink.created
backlink.lost
```

事件模型：

```ts
interface DevEvent {
  id: string
  type: string

  actor: Actor
  resource?: ResourceRef

  payload: unknown

  createdAt: Date
}
```

Event 可以触发：

```text
Notification
Task
Workflow
Agent
Plugin
Webhook
Audit
```

---

# 12. Task / Job

DevOS 区分：

```text
Task
Job
Workflow
```

### Task

用户或 Agent 需要完成的工作。

```text
Analyze Website
Generate Article
Review Backlinks
```

### Job

后台执行单元。

```text
crawlWebsite()
generateEmbedding()
syncSearchConsole()
```

### Workflow

多个 Action / Job 的组合。

```text
Scan Website
 ↓
Analyze SEO
 ↓
Generate Report
 ↓
Create Tasks
 ↓
Notify User
```

---

# 13. Plugin Architecture

Plugin 是 DevOS 扩展能力的基本单位。

Plugin 可以提供：

```text
Backend
Frontend
Routes
Pages
Navigation
Resources
Actions
Events
Workers
Tasks
Settings
Permissions
Widgets
MCP
Skills
```

Plugin Manifest：

```ts
interface PluginManifest {
  id: string
  name: string
  version: string

  permissions?: string[]

  resources?: string[]
  actions?: string[]

  routes?: RouteDefinition[]
  navigation?: NavigationDefinition[]

  settings?: SettingDefinition[]

  capabilities?: CapabilityDefinition[]
}
```

---

# 14. Plugin 生命周期

Plugin 必须支持：

```text
discover
install
validate
enable
disable
configure
update
uninstall
```

生命周期：

```text
Plugin Package
      ↓
Discover
      ↓
Install
      ↓
Migration
      ↓
Register
      ↓
Enable
      ↓
Running
```

---

# 15. MCP Architecture

MCP 被视为外部能力连接层。

MCP 不应该直接修改业务数据库。

推荐：

```text
MCP Tool
   ↓
DevOS Action
   ↓
Resource
```

而不是：

```text
MCP
 ↓
Database
```

这样可以统一：

```text
Permission
Validation
Audit
Event
Rate Limit
Transaction
```

---

# 16. Skill Architecture

Skill 是 Agent 能力编排层。

例如：

```text
seo.website.audit
seo.keyword.research
seo.content.generate
seo.backlink.analyze
```

Skill 可以调用：

```text
Action
MCP
Plugin
Workflow
Other Skill
```

结构：

```text
Skill
 ├── Context
 ├── Instructions
 ├── Inputs
 ├── Actions
 ├── MCP
 ├── Outputs
 └── Validation
```

---

# 17. Agent Architecture

Agent 不应该直接访问数据库。

Agent：

```text
Agent
 ↓
Context
 ↓
Skill
 ↓
Action / MCP
 ↓
Resource
```

Agent Runtime 负责：

```text
Planning
Tool Selection
Skill Selection
Execution
Observation
Retry
Approval
Memory
Context
```

---

# 18. Application Architecture

Application 是业务产品。

例如：

```text
apps/
├── seo/
├── devops/
├── monitoring/
└── crm/
```

每个 App 应该只负责：

```text
Business Domain
Business UI
Business Resources
Business Actions
Business Workflows
```

而不应该重新实现：

```text
Auth
User
Permission
Task
Notification
File
Audit
Agent Runtime
Plugin Runtime
```

---

# 19. App Manifest

每个 App 应该拥有：

```ts
interface AppManifest {
  id: string
  name: string
  version: string

  description?: string

  dependencies?: string[]

  permissions?: string[]

  resources?: string[]
  actions?: string[]

  navigation?: NavigationDefinition[]

  dashboard?: DashboardDefinition
}
```

---

# 20. Application Shell

DevOS 提供统一 Application Shell：

```text
┌───────────────────────────────────────────┐
│ DevOS Header                              │
├────────────┬──────────────────────────────┤
│            │                              │
│ Navigation │ Application                  │
│            │                              │
│            │                              │
│            │                              │
├────────────┴──────────────────────────────┤
│ Status / Notifications / Tasks             │
└───────────────────────────────────────────┘
```

App 不需要重新开发：

```text
Header
Sidebar
User Menu
Notification
Command Palette
Theme
Permission Guard
```

---

# 21. Navigation

Navigation 应由 App / Plugin 注册。

例如：

```ts
registerNavigation({
  id: 'seo',
  label: 'SEO',
  icon: 'Search',
  children: [
    {
      id: 'websites',
      label: 'Websites',
      path: '/seo/websites',
    },
    {
      id: 'keywords',
      label: 'Keywords',
      path: '/seo/keywords',
    },
  ],
})
```

DevOS Shell 自动合并。

最终：

```text
DevOS
├── Dashboard
├── Projects
├── SEO
│   ├── Websites
│   ├── Keywords
│   ├── Content
│   └── Backlinks
├── DevOps
└── Settings
```

---

# 22. UI Architecture

建立：

```text
@devos/ui
```

提供统一组件：

```text
DevLayout
DevPage
DevTable
DevForm
DevDrawer
DevModal
DevDetail
DevResource
DevAction
DevTask
DevStatus
DevTimeline
DevDashboard
DevWidget
DevAgentChat
DevCommandPalette
```

业务 App 不应该重复实现基础管理 UI。

---

# 23. SDK

DevOS 必须提供官方 SDK。

建议：

```text
@devos/sdk
@devos/plugin-sdk
@devos/app-sdk
@devos/mcp-sdk
@devos/skill-sdk
@devos/agent-sdk
```

SDK 用于：

```text
注册 Resource
注册 Action
注册 Event
注册 Page
注册 Navigation
注册 Plugin
注册 MCP
注册 Skill
注册 Agent
```

---

# 24. CLI

DevOS CLI：

```bash
devos create
devos dev
devos build
devos validate
devos install
devos plugin
devos app
devos mcp
devos skill
devos migrate
devos doctor
```

创建项目：

```bash
devos create app my-app
```

创建 Plugin：

```bash
devos create plugin my-plugin
```

创建 MCP：

```bash
devos create mcp my-mcp
```

创建 Skill：

```bash
devos create skill my-skill
```

创建独立产品：

```bash
devos create standalone my-product
```

---

# 25. Standalone Fork

DevOS 必须支持 Fork 模式。

提供：

```text
DevOS Base
    ↓
Standalone Template
    ↓
Independent Product
```

Standalone Product 默认拥有：

```text
Auth
User
Organization
Role
Permission
Resource
Action
Event
Task
Job
File
Notification
Audit
Plugin Runtime
MCP Runtime
Skill Runtime
Agent Runtime
UI
CLI
```

之后可以自由删除不需要的模块。

---

# 26. Monorepo

建议使用 Monorepo。

基础结构：

```text
devos/
│
├── apps/
│   ├── shell/
│   ├── api/
│   └── worker/
│
├── packages/
│   ├── core/
│   ├── runtime/
│   ├── sdk/
│   ├── ui/
│   ├── plugin-sdk/
│   ├── app-sdk/
│   ├── mcp-sdk/
│   ├── skill-sdk/
│   └── agent-sdk/
│
├── plugins/
│
├── applications/
│
├── templates/
│
├── cli/
│
└── docs/
```

---

# 27. Dependency Rules

依赖方向必须严格控制：

```text
Application
    ↓
Runtime
    ↓
Core
    ↓
Infrastructure
```

禁止：

```text
Core → Application
Core → Plugin
Core → SEO
```

禁止业务反向污染 Core。

---

# 28. Core 与 Runtime 的边界

Core：

```text
稳定
基础
通用
长期存在
```

Runtime：

```text
执行
扩展
编排
动态加载
```

Application：

```text
业务
产品
用户价值
```

Plugin：

```text
可选能力
第三方集成
业务扩展
```

---

# 29. 数据库原则

Core 数据库表使用统一命名空间。

例如：

```text
devos_users
devos_organizations
devos_roles
devos_permissions
devos_sessions
devos_events
devos_tasks
devos_jobs
devos_audit_logs
```

App 数据表独立命名。

例如 SEO：

```text
seo_websites
seo_keywords
seo_content
seo_backlinks
seo_campaigns
```

Plugin：

```text
plugin_xxx_*
```

禁止 Plugin 随意修改 Core 表。

---

# 30. API 原则

API 分为：

```text
Core API
Runtime API
App API
Plugin API
```

但是最终业务执行应该尽量统一到：

```text
Action API
```

例如：

```http
POST /api/actions/seo.website.scan
```

而不是为同一个业务逻辑维护：

```text
REST
GraphQL
Agent API
MCP API
Internal API
```

五套不同实现。

---

# 31. Audit

所有敏感 Action 自动记录：

```text
actor
action
resource
input
result
ip
userAgent
timestamp
requestId
```

例如：

```text
user:123
seo.website.publish
website:456
success
```

Agent 执行同样记录。

例如：

```text
agent:seo-agent
seo.website.scan
website:456
success
```

这样 Human 与 AI 的行为可以统一审计。

---

# 32. Observability

DevOS 必须内置：

```text
Logging
Metrics
Tracing
Audit
Health Check
Error Tracking
```

所有 Runtime 执行应该拥有：

```text
requestId
traceId
executionId
```

例如：

```text
Agent Execution
      │
      ├── Skill Execution
      │      │
      │      ├── Action
      │      ├── MCP
      │      └── Action
      │
      └── Workflow
```

整个链路必须可以追踪。

---

# 33. Security

所有 Extension 必须拥有明确权限。

Plugin：

```text
declared permissions
```

MCP：

```text
declared tools
declared permissions
```

Skill：

```text
declared actions
```

Agent：

```text
declared capabilities
```

默认：

```text
DENY
```

而不是：

```text
ALLOW
```

---

# 34. Extension Isolation

Plugin 不允许默认获得：

```text
Database Full Access
Filesystem Full Access
Shell Access
Network Full Access
```

必须通过 Capability：

```text
database.read
database.write

filesystem.read
filesystem.write

network.http

process.execute
```

并经过权限检查。

---

# 35. Configuration

配置分为：

```text
Platform Config
App Config
Plugin Config
User Config
Organization Config
Environment Config
```

统一 Configuration API。

例如：

```ts
config.get('seo.crawler.maxConcurrency')
```

而不是每个项目自己实现 Settings。

---

# 36. Storage

DevOS 提供统一 Storage API：

```ts
storage.put()
storage.get()
storage.delete()
storage.exists()
storage.url()
```

底层可以使用：

```text
Local
S3
Cloudflare R2
MinIO
```

Application 不应该直接依赖具体 Storage Provider。

---

# 37. Queue

统一 Queue：

```text
@devos/queue
```

支持：

```text
Job
Retry
Delay
Priority
Concurrency
Dead Letter
Cancellation
Progress
```

业务只提交 Job：

```ts
queue.dispatch('seo.scan', payload)
```

不直接依赖 Redis 实现。

---

# 38. Scheduler

统一 Scheduler：

```text
schedule.every()
schedule.cron()
schedule.once()
```

例如：

```text
Every 6 hours
    ↓
Search Console Sync

Every day
    ↓
SEO Audit

Every week
    ↓
Report Generation
```

---

# 39. Search

建立统一 Search abstraction：

```text
search.index()
search.query()
search.remove()
```

未来可以使用：

```text
PostgreSQL
Meilisearch
OpenSearch
Elasticsearch
```

Application 不直接绑定具体搜索引擎。

---

# 40. Notification

统一 Notification：

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

例如：

```ts
notification.send({
  userId,
  type: 'task.completed',
})
```

---

# 41. DevOS Application Lifecycle

App：

```text
discover
install
migrate
register
enable
disable
update
uninstall
```

启动：

```text
Load Core
    ↓
Load Runtime
    ↓
Discover Apps
    ↓
Validate Manifest
    ↓
Load Dependencies
    ↓
Register Resources
    ↓
Register Actions
    ↓
Register Events
    ↓
Register Routes
    ↓
Register Navigation
    ↓
Application Ready
```

---

# 42. DevOS 的最终产品模型

DevOS 中存在四种主要扩展单位：

```text
App
Plugin
MCP
Skill
```

它们关系：

```text
App
 ├── Plugin
 │    ├── Resource
 │    ├── Action
 │    └── UI
 │
 ├── MCP
 │
 ├── Skill
 │
 └── Agent
```

---

# 43. SEO App 示例

未来 AI SEO 应该表现为：

```text
applications/
└── seo/
    ├── manifest.ts
    │
    ├── resources/
    │   ├── website.ts
    │   ├── keyword.ts
    │   ├── content.ts
    │   └── backlink.ts
    │
    ├── actions/
    │   ├── scan.ts
    │   ├── analyze.ts
    │   ├── generate.ts
    │   └── publish.ts
    │
    ├── pages/
    │
    ├── workflows/
    │
    └── dashboard/
```

SEO 本身不负责：

```text
Auth
User
Permission
Task Engine
Queue
Notification
Agent Runtime
MCP Runtime
Plugin Runtime
```

---

# 44. 新项目开发原则

未来创建新项目时，必须首先回答：

### Q1

这是：

```text
Plugin
App
Standalone
```

哪一种？

---

### Q2

这个能力是否已经存在于 DevOS Core？

如果存在：

```text
REUSE
```

禁止重复实现。

---

### Q3

这个能力是否属于 Runtime？

如果属于：

```text
EXTEND RUNTIME
```

---

### Q4

是否属于业务领域？

如果是：

```text
APP MODULE
```

---

### Q5

是否可以独立复用？

如果可以：

```text
PLUGIN
```

---

# 45. Golden Rule

DevOS v2 必须遵守：

> **Build Once, Reuse Everywhere.**

以及：

> **Business Logic Lives in Actions.**

以及：

> **AI Uses the Same Actions as Humans.**

以及：

> **Core Must Never Depend on Business Applications.**

以及：

> **Everything Extensible Must Have a Manifest.**

---

# 46. 成功标准

DevOS v2 完成后，创建一个新的普通 SaaS 应用：

不应该重新实现：

```text
Login
Register
User
Organization
Role
Permission
Navigation
Layout
Notification
File
Storage
Task
Job
Audit
Search
Settings
API
Agent
MCP
Plugin
```

开发者只需要：

```text
1. Define App Manifest
2. Define Resources
3. Define Actions
4. Define Pages
5. Define Workflows
6. Add Plugins
```

---

# 47. 最终目标

DevOS 的最终形态：

```text
                    DEVOS PLATFORM
                           │
       ┌───────────────────┼───────────────────┐
       │                   │                   │
      Core               Runtime              UI
       │                   │                   │
       │          ┌────────┼────────┐          │
       │          │        │        │          │
       │        Agent    Plugin    MCP        │
       │          │        │        │          │
       └──────────┴────────┴────────┴──────────┘
                           │
                    Application Layer
                           │
             ┌─────────────┼─────────────┐
             │             │             │
            SEO          DevOps         CRM
             │             │             │
          Plugins       Plugins       Plugins
```

DevOS 本身不是最终业务产品。

**DevOS 是生产这些业务产品的平台。**

---

# 48. 实施原则

Zcode 在实施 DevOS v2 时必须遵循：

1. 不破坏现有可工作的 DevOS 功能。
2. 优先重构边界，而不是增加重复功能。
3. Core 与 Application 必须严格分离。
4. 新功能优先考虑是否应该成为 Plugin。
5. 所有可执行业务操作优先进入 Action Runtime。
6. Agent / MCP / UI / API 尽量共享 Action。
7. 不允许业务代码反向进入 Core。
8. 不允许每个 App 自建 Auth / Permission / Task 等基础设施。
9. 所有 Extension 必须 Manifest 化。
10. 所有重大执行必须可 Audit。
11. 所有后台 Job 必须进入统一 Job Runtime。
12. 所有异步事件必须进入统一 Event System。
13. 新架构必须支持未来 Standalone Fork。
14. API、SDK、CLI 必须围绕同一 Runtime 模型设计。
15. 不为了架构漂亮而进行没有实际价值的微服务拆分。

---

# 49. 下一阶段

本文件只定义总体架构。

后续文档应继续详细定义：

```text
02_CORE_ARCHITECTURE.md
03_RESOURCE_ACTION_MODEL.md
04_EVENT_TASK_JOB.md
05_PLUGIN_SYSTEM.md
06_APP_RUNTIME.md
07_MCP_RUNTIME.md
08_SKILL_RUNTIME.md
09_AGENT_RUNTIME.md
10_PERMISSION_SECURITY.md
11_UI_DESIGN_SYSTEM.md
12_SDK.md
13_CLI.md
14_DATABASE.md
15_API.md
16_PROJECT_TEMPLATES.md
17_STANDALONE_FORK.md
18_MIGRATION.md
19_IMPLEMENTATION_PLAN.md
20_ACCEPTANCE_TESTS.md
```

这些文档完成后，再进入 Zcode 实际代码改造阶段。

**禁止在总体架构未确定之前大规模修改现有业务代码。**