Files

T

phptits b1f17cf637 v2 platform foundation (docs 01/02/03): Action Runtime + Registry + unified API

- v2 foundation: ActionResult/DevError/ActorContext/ResourceRef/Execution types
- ActionRegistry + ResourceRegistry (namespaced types, FAIL FAST on duplicates)
- ActionRuntime pipeline: validate -> authorize -> middleware -> handler ->
  output validation -> audit -> event -> execution persisted (devos_action_executions)
- Legacy bridge: v1 services registered as devops.*/core.* resources & actions (47 actions, 9 resources)
- Unified Action API: POST /api/v2/actions/:actionId, GET discovery (actions/resources)
- 10 v2 unit tests (registry fail-fast, validation, authz, failure audit, events)

2026-09-10 21:09:44 +00:00

23 KiB

Raw Blame History

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 的公共基础能力。

未来新产品原则：

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

2. 核心目标

DevOS v2 必须解决以下问题。

2.1 多项目复用

多个产品共享：

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。

例如：

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

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

2.3 能力可扩展

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

例如：

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

2.4 AI 原生

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

Agent
Skill
MCP
Tool
Action
Context
Workflow
Memory
Event

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

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

3. 总体架构

DevOS v2 采用五层结构：

┌─────────────────────────────────────────────┐
│                  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 不允许包含具体业务领域。

允许：

User
Role
Permission
Resource
Action
Task
Event
File
Audit

不允许：

SEOKeyword
Backlink
CRMLead
Invoice
Campaign

这些属于 Application。

5. Core

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

建议模块：

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

6. Identity

Identity 管理：

User
Organization
Membership
Session
Account
Identity Provider

支持：

Email
Password
OAuth
OIDC
API Key
Service Account
Agent Identity

7. Authorization

DevOS v2 不使用单纯的：

user -> role -> permission

而采用：

Subject
    ↓
Permission
    ↓
Resource
    ↓
Action
    ↓
Scope

统一模型：

Permission =
    subject
    + resource
    + action
    + scope

例如：

seo.website.read
seo.website.update
seo.website.scan
seo.website.publish

8. Resource Model

Resource 是 DevOS 的核心抽象。

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

例如：

User
Website
Project
Keyword
Content
Backlink
Server
Deployment
Report

Resource 定义：

interface ResourceDefinition {
  name: string
  label: string

  schema: unknown

  actions: ActionDefinition[]

  permissions: PermissionDefinition[]

  ui?: ResourceUI

  events?: EventDefinition[]
}

9. Action Model

Resource 不只是 CRUD。

每个 Resource 可以拥有多个 Action。

例如：

Website

read
create
update
delete
scan
analyze
verify
deploy
backup

Action：

interface ActionDefinition {
  name: string
  resource: string

  inputSchema?: unknown
  outputSchema?: unknown

  permission?: string

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

10. Human 与 Agent 统一执行模型

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

UI：

User
 ↓
UI
 ↓
Action
 ↓
Resource

Agent：

Agent
 ↓
Skill
 ↓
Action
 ↓
Resource

MCP：

MCP
 ↓
Action
 ↓
Resource

API：

API
 ↓
Action
 ↓
Resource

最终全部进入：

Action Runtime

因此业务逻辑不能写在：

React Component
REST Controller
Agent
MCP Server

而应该写在：

Action

11. Event Model

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

例如：

website.created
website.updated
website.scan.started
website.scan.completed

content.created
content.published

backlink.created
backlink.lost

事件模型：

interface DevEvent {
  id: string
  type: string

  actor: Actor
  resource?: ResourceRef

  payload: unknown

  createdAt: Date
}

Event 可以触发：

Notification
Task
Workflow
Agent
Plugin
Webhook
Audit

12. Task / Job

DevOS 区分：

Task
Job
Workflow

Task

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

Analyze Website
Generate Article
Review Backlinks

Job

后台执行单元。

crawlWebsite()
generateEmbedding()
syncSearchConsole()

Workflow

多个 Action / Job 的组合。

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

13. Plugin Architecture

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

Plugin 可以提供：

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

Plugin Manifest：

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

discover
install
validate
enable
disable
configure
update
uninstall

生命周期：

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

15. MCP Architecture

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

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

16. Skill Architecture

Skill 是 Agent 能力编排层。

例如：

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

Skill 可以调用：

Action
MCP
Plugin
Workflow
Other Skill

结构：

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

17. Agent Architecture

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

Agent：

Agent
 ↓
Context
 ↓
Skill
 ↓
Action / MCP
 ↓
Resource

Agent Runtime 负责：

Planning
Tool Selection
Skill Selection
Execution
Observation
Retry
Approval
Memory
Context

18. Application Architecture

Application 是业务产品。

例如：

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

每个 App 应该只负责：

Business Domain
Business UI
Business Resources
Business Actions
Business Workflows

而不应该重新实现：

Auth
User
Permission
Task
Notification
File
Audit
Agent Runtime
Plugin Runtime

19. App Manifest

每个 App 应该拥有：

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：

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

App 不需要重新开发：

Header
Sidebar
User Menu
Notification
Command Palette
Theme
Permission Guard

Navigation 应由 App / Plugin 注册。

例如：

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

DevOS Shell 自动合并。

最终：

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

22. UI Architecture

建立：

@devos/ui

提供统一组件：

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

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

23. SDK

DevOS 必须提供官方 SDK。

建议：

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

SDK 用于：

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

24. CLI

DevOS CLI：

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

创建项目：

devos create app my-app

创建 Plugin：

devos create plugin my-plugin

创建 MCP：

devos create mcp my-mcp

创建 Skill：

devos create skill my-skill

创建独立产品：

devos create standalone my-product

25. Standalone Fork

DevOS 必须支持 Fork 模式。

提供：

DevOS Base
    ↓
Standalone Template
    ↓
Independent Product

Standalone Product 默认拥有：

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。

基础结构：

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

依赖方向必须严格控制：

Application
    ↓
Runtime
    ↓
Core
    ↓
Infrastructure

禁止：

Core → Application
Core → Plugin
Core → SEO

禁止业务反向污染 Core。

28. Core 与 Runtime 的边界

Core：

稳定
基础
通用
长期存在

Runtime：

执行
扩展
编排
动态加载

Application：

业务
产品
用户价值

Plugin：

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

29. 数据库原则

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

例如：

devos_users
devos_organizations
devos_roles
devos_permissions
devos_sessions
devos_events
devos_tasks
devos_jobs
devos_audit_logs

App 数据表独立命名。

例如 SEO：

seo_websites
seo_keywords
seo_content
seo_backlinks
seo_campaigns

Plugin：

plugin_xxx_*

禁止 Plugin 随意修改 Core 表。

30. API 原则

API 分为：

Core API
Runtime API
App API
Plugin API

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

Action API

例如：

POST /api/actions/seo.website.scan

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

REST
GraphQL
Agent API
MCP API
Internal API

五套不同实现。

31. Audit

所有敏感 Action 自动记录：

actor
action
resource
input
result
ip
userAgent
timestamp
requestId

例如：

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

Agent 执行同样记录。

例如：

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

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

32. Observability

DevOS 必须内置：

Logging
Metrics
Tracing
Audit
Health Check
Error Tracking

所有 Runtime 执行应该拥有：

requestId
traceId
executionId

例如：

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

整个链路必须可以追踪。

33. Security

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

Plugin：

declared permissions

MCP：

declared tools
declared permissions

Skill：

declared actions

Agent：

declared capabilities

默认：

DENY

而不是：

ALLOW

34. Extension Isolation

Plugin 不允许默认获得：

Database Full Access
Filesystem Full Access
Shell Access
Network Full Access

必须通过 Capability：

database.read
database.write

filesystem.read
filesystem.write

network.http

process.execute

并经过权限检查。

35. Configuration

配置分为：

Platform Config
App Config
Plugin Config
User Config
Organization Config
Environment Config

统一 Configuration API。

例如：

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

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

36. Storage

DevOS 提供统一 Storage API：

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

底层可以使用：

Local
S3
Cloudflare R2
MinIO

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

37. Queue

统一 Queue：

@devos/queue

支持：

Job
Retry
Delay
Priority
Concurrency
Dead Letter
Cancellation
Progress

业务只提交 Job：

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

不直接依赖 Redis 实现。

38. Scheduler

统一 Scheduler：

schedule.every()
schedule.cron()
schedule.once()

例如：

Every 6 hours
    ↓
Search Console Sync

Every day
    ↓
SEO Audit

Every week
    ↓
Report Generation

39. Search

建立统一 Search abstraction：

search.index()
search.query()
search.remove()

未来可以使用：

PostgreSQL
Meilisearch
OpenSearch
Elasticsearch

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

40. Notification

统一 Notification：

In-App
Email
Webhook
Push
Slack
Discord

例如：

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

41. DevOS Application Lifecycle

App：

discover
install
migrate
register
enable
disable
update
uninstall

启动：

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 中存在四种主要扩展单位：

App
Plugin
MCP
Skill

它们关系：

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

43. SEO App 示例

未来 AI SEO 应该表现为：

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 本身不负责：

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

44. 新项目开发原则

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

Q1

这是：

Plugin
App
Standalone

哪一种？

Q2

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

如果存在：

REUSE

禁止重复实现。

Q3

这个能力是否属于 Runtime？

如果属于：

EXTEND RUNTIME

Q4

是否属于业务领域？

如果是：

APP MODULE

Q5

是否可以独立复用？

如果可以：

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

不应该重新实现：

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

开发者只需要：

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

47. 最终目标

DevOS 的最终形态：

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

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

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

48. 实施原则

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

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

49. 下一阶段

本文件只定义总体架构。

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

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 实际代码改造阶段。

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

23 KiB Raw Blame History Unescape Escape

DevOS Platform v2

01 — Overall Architecture Specification

1. 文档目的

2. 核心目标

2.1 多项目复用

2.2 应用可插拔

2.3 能力可扩展

2.4 AI 原生

3. 总体架构

4. Architecture Principles

4.1 Core First

5. Core

6. Identity

7. Authorization

8. Resource Model

9. Action Model

10. Human 与 Agent 统一执行模型

11. Event Model

12. Task / Job

Task

Job

Workflow

13. Plugin Architecture

14. Plugin 生命周期

15. MCP Architecture

16. Skill Architecture

17. Agent Architecture

18. Application Architecture

19. App Manifest

20. Application Shell

21. Navigation

22. UI Architecture

23. SDK

24. CLI

25. Standalone Fork

26. Monorepo

27. Dependency Rules

28. Core 与 Runtime 的边界

29. 数据库原则

30. API 原则

31. Audit

32. Observability

33. Security

34. Extension Isolation

35. Configuration

36. Storage

37. Queue

38. Scheduler

39. Search

40. Notification

41. DevOS Application Lifecycle

42. DevOS 的最终产品模型

43. SEO App 示例

44. 新项目开发原则

Q1

Q2

Q3

Q4

Q5

45. Golden Rule

46. 成功标准

47. 最终目标

48. 实施原则

49. 下一阶段

23 KiB

Raw Blame History