devos/Docs/DevOS-Platform-v2/03_RESOURCE_ACTION_MODEL.md — DevOS Resource & Action 模型.md

DevOS Platform v2

03 — Resource & Action Model Specification

Document Version: 2.0
Status: Architecture Specification
Parent: 01_ARCHITECTURE.md, 02_CORE_ARCHITECTURE.md
Target: DevOS Platform v2
Implementation Target: Zcode / AI Coding Agent

---

1. 文档目的

本文件定义 DevOS v2 的两个核心抽象：

Resource
Action

这两个概念是 DevOS Platform 的统一业务执行基础。

目标：

UI
REST API
CLI
MCP
Skill
Agent
Workflow
Plugin

都不能分别实现业务逻辑。

所有业务操作最终应该进入：

Action Runtime

统一执行。

---

2. 核心原则

DevOS 必须遵守：

Resource 描述“系统中有什么”，Action 描述“可以对它做什么”。

例如：

Resource:
    Website

Actions:
    create
    read
    update
    delete
    scan
    analyze
    verify
    publish

---

3. 为什么不是简单 CRUD

传统 Admin：

GET    /websites
POST   /websites
PUT    /websites/:id
DELETE /websites/:id

只能表达：

CRUD

但是现代应用需要：

scan
analyze
publish
deploy
verify
sync
retry
approve
reject
generate

因此：

CRUD

只是 Action 的一个子集。

---

4. 统一执行模型

DevOS 所有执行入口：

                    ┌──────────┐
                    │    UI    │
                    └────┬─────┘
                         │
┌──────────┐             │
│ REST API ├─────────────┤
└──────────┘             │
                         ▼
┌──────────┐       ┌──────────────┐
│   CLI    ├──────►│ Action       │
└──────────┘       │ Runtime      │
                   └──────┬───────┘
┌──────────┐              │
│   MCP    ├──────────────┤
└──────────┘              │
                          │
┌──────────┐              │
│  Agent   ├──────────────┤
└──────────┘              │
                          │
┌──────────┐              │
│ Workflow ├──────────────┘
└──────────┘

最终：

Input
 ↓
Validation
 ↓
Authorization
 ↓
Action Middleware
 ↓
Action Handler
 ↓
Result
 ↓
Audit
 ↓
Event

---

5. Resource 定义

Resource 是一个平台级对象类型。

接口：

interface ResourceDefinition<
  T = unknown
> {
  type: string

  label: string

  description?: string

  schema: Schema<T>

  actions: ActionDefinition[]

  permissions?: PermissionDefinition[]

  events?: EventDefinition[]

  ui?: ResourceUI
}

---

6. Resource Type

Resource type 必须唯一。

推荐：

<namespace>.<resource>

例如：

core.user
core.organization

project.project

seo.website
seo.keyword
seo.content

devops.server
devops.deployment

禁止使用：

website
keyword
server

作为大型平台的全局 Resource Type。

---

7. Resource ID

Resource ID 在同一 Resource Type 内唯一。

例如：

seo.website

实例：

website_01
website_02
website_03

引用：

interface ResourceRef {
  type: string
  id: string
}

示例：

{
  "type": "seo.website",
  "id": "website_123"
}

---

8. Resource Metadata

Resource 应提供机器可读 Metadata。

例如：

const websiteResource = defineResource({
  type: 'seo.website',

  label: 'Website',

  description: 'A website managed by SEO application',

  schema: WebsiteSchema,

  actions: [
    scanWebsite,
    analyzeWebsite,
    verifyWebsite
  ]
})

Metadata 可以被：

UI
CLI
MCP
Agent
Documentation
Search
Admin

使用。

---

9. Resource Schema

Resource 必须定义 Schema。

推荐：

Zod

例如：

const WebsiteSchema = z.object({
  id: z.string(),

  organizationId: z.string(),

  domain: z.string(),

  status: z.enum([
    'active',
    'paused',
    'error'
  ]),

  createdAt: z.date(),
  updatedAt: z.date()
})

Schema 的用途：

Validation
Documentation
UI Form
MCP Schema
Agent Context
API Schema

---

10. Resource 不等于 Database Table

这是非常重要的规则。

Resource：

Platform Concept

Database Table：

Storage Implementation

二者不要求一一对应。

例如：

Resource:
seo.website

可以由：

seo_websites
seo_domains
seo_settings

多个表组成。

因此：

Resource 是业务对象抽象，而不是数据库表抽象。

---

11. Resource Registry

DevOS 必须提供全局 Resource Registry。

interface ResourceRegistry {
  register(
    resource: ResourceDefinition
  ): void

  get(
    type: string
  ): ResourceDefinition | undefined

  has(
    type: string
  ): boolean

  list(): ResourceDefinition[]
}

启动阶段：

Core
 ↓
Apps
 ↓
Plugins
 ↓
Register Resources

---

12. Resource Registration

Core：

registerResource(userResource)
registerResource(organizationResource)

SEO App：

registerResource(websiteResource)
registerResource(keywordResource)

Plugin：

registerResource(backlinkResource)

最终：

Resource Registry
├── core.user
├── core.organization
├── seo.website
├── seo.keyword
├── seo.content
└── seo.backlink

---

13. Action 定义

Action 表示一个可执行操作。

interface ActionDefinition<
  TInput = unknown,
  TOutput = unknown
> {
  id: string

  resource?: string

  name: string

  description?: string

  inputSchema?: Schema<TInput>

  outputSchema?: Schema<TOutput>

  permission?: string

  mode?: ActionMode

  execute(
    context: ActionContext,
    input: TInput
  ): Promise<TOutput>
}

---

14. Action ID

Action ID 必须全局唯一。

推荐：

<resource>.<action>

例如：

core.user.create
core.user.update

seo.website.scan
seo.website.analyze
seo.website.publish

devops.server.deploy

---

15. Action 类型

Action 至少分为：

query
command
job
workflow

Query

读取数据：

website.get
keyword.list

Command

修改状态：

website.update
website.publish

Job

后台执行：

website.scan
content.generate

Workflow

多个 Action 编排：

website.fullAudit

---

16. ActionMode

建议：

type ActionMode =
  | 'sync'
  | 'async'
  | 'stream'

Sync：

立即返回结果

Async：

返回 Execution / Job

Stream：

持续输出进度

---

17. Action Input

所有 Action 都必须定义 Input Contract。

例如：

const ScanWebsiteInput = z.object({
  websiteId: z.string(),

  depth: z.number()
    .int()
    .min(1)
    .max(10)
})

调用：

{
  "websiteId": "website_123",
  "depth": 3
}

---

18. Action Output

Output 同样必须定义 Schema。

const ScanWebsiteOutput = z.object({
  executionId: z.string(),

  pagesScanned: z.number(),

  errors: z.number(),

  score: z.number()
})

这使：

UI
Agent
MCP
CLI

都可以理解结果。

---

19. Action Context

Action 永远不能只接受：

input

必须同时接收：

context

定义：

interface ActionContext {
  requestId: string

  executionId: string

  actor: ActorContext

  organizationId?: string

  permissions: string[]

  signal?: AbortSignal

  metadata: Record<string, unknown>
}

---

20. Actor

Action 必须知道是谁执行的。

Actor 类型：

type ActorContext =
  | UserActor
  | AgentActor
  | ServiceActor
  | SystemActor

例如：

{
  type: 'user',
  id: 'user_123'
}

或者：

{
  type: 'agent',
  id: 'seo-agent'
}

---

21. Human 与 Agent 必须统一

用户：

User
 ↓
Action

Agent：

Agent
 ↓
Action

因此 Action 不允许写：

if (isAgent) {
  bypassPermission()
}

禁止 Agent 绕过权限。

---

22. Authorization

Action 执行前必须检查 Permission。

例如：

seo.website.scan

对应：

seo.website.scan

或者：

seo.website.execute

由 Permission Policy 决定。

---

23. Authorization 顺序

标准执行流程：

Request
 ↓
Resolve Action
 ↓
Validate Input
 ↓
Resolve Resource
 ↓
Resolve Actor
 ↓
Authorization
 ↓
Middleware
 ↓
Execute

任何一步失败：

STOP

---

24. Resource-level Authorization

Action 不应该只检查：

permission exists

还需要检查：

resource scope

例如：

user has:
seo.website.update

但：

website.organizationId

必须属于：

context.organizationId

否则拒绝。

---

25. Policy

复杂权限使用 Policy。

例如：

const WebsiteUpdatePolicy = definePolicy({
  resource: 'seo.website',

  action: 'update',

  check: async ({
    actor,
    resource
  }) => {
    return resource.organizationId
      === actor.organizationId
  }
})

---

26. Validation

Action Input：

Schema Validation

Resource：

Resource Validation

Output：

Output Validation

流程：

Input
 ↓
Input Schema
 ↓
Policy
 ↓
Handler
 ↓
Output Schema

---

27. Action Middleware

Action 支持 Middleware。

例如：

Authorization
Audit
Transaction
RateLimit
Idempotency
Logging
Metrics
Tracing

执行：

Action
 ↓
Middleware 1
 ↓
Middleware 2
 ↓
Middleware 3
 ↓
Handler

---

28. Middleware 顺序

推荐：

Request ID
 ↓
Authentication
 ↓
Authorization
 ↓
Validation
 ↓
Rate Limit
 ↓
Idempotency
 ↓
Audit Start
 ↓
Transaction
 ↓
Handler
 ↓
Audit Result
 ↓
Event

---

29. Action Result

统一返回：

interface ActionResult<T> {
  success: boolean

  data?: T

  error?: DevError

  executionId: string

  requestId: string
}

---

30. Action Error

统一错误：

ACTION_NOT_FOUND
ACTION_INVALID
ACTION_UNAUTHORIZED
ACTION_FORBIDDEN
RESOURCE_NOT_FOUND
RESOURCE_INVALID
ACTION_TIMEOUT
ACTION_CANCELLED
ACTION_CONFLICT
ACTION_RATE_LIMITED
ACTION_FAILED

---

31. Action Execution

Action Runtime 创建 Execution。

interface ActionExecution {
  id: string

  actionId: string

  actor: ActorRef

  resource?: ResourceRef

  status:
    | 'pending'
    | 'running'
    | 'completed'
    | 'failed'
    | 'cancelled'

  startedAt?: Date

  completedAt?: Date

  error?: DevError
}

---

32. Execution ID

每一次 Action 执行必须拥有唯一：

executionId

例如：

exec_01J...

用于：

Logs
Audit
Events
Tracing
Job
Agent
Workflow

---

33. Request ID vs Execution ID

两者必须区分。

requestId

表示一次外部请求。

executionId

表示一次 Action 执行。

例如：

HTTP Request
  requestId = req_123
      ↓
Action
  executionId = exec_456
      ↓
Job
  executionId = exec_456

---

34. Idempotency

重要 Action 支持：

idempotencyKey

例如：

Idempotency-Key: xxx

防止：

重复支付
重复发布
重复部署
重复创建任务

Action 定义：

{
  idempotent: true
}

---

35. Transaction

需要数据库一致性的 Action 可以声明：

{
  transaction: true
}

Runtime：

Begin Transaction
 ↓
Action
 ↓
Commit

失败：

Rollback

---

36. Async Action

例如：

seo.website.scan

可能需要 30 分钟。

调用：

Action
 ↓
Execution
 ↓
Job
 ↓
Worker

API 不等待 30 分钟。

返回：

{
  "executionId": "exec_123",
  "status": "pending"
}

---

37. Action Progress

Async Action 可以提供 Progress：

interface ExecutionProgress {
  current: number
  total?: number

  percentage?: number

  message?: string
}

例如：

Scanning website
127 / 500 pages
25%

UI 可以实时显示。

---

38. Action Cancellation

Action 应支持：

context.signal

例如：

User
 ↓
Cancel
 ↓
AbortSignal
 ↓
Action
 ↓
Worker

特别适用于：

Crawler
Agent
Generation
Deployment
Sync

---

39. Retry

Async Action 支持：

retry

配置：

{
  retry: {
    maxAttempts: 3,
    backoff: 'exponential'
  }
}

但不是所有 Action 都允许 Retry。

例如：

createPayment

必须非常谨慎。

---

40. Action Event

Action 完成后可以产生：

action.started
action.completed
action.failed
action.cancelled

以及业务 Event。

例如：

seo.website.scan.completed

---

41. Audit

每次敏感 Action 必须记录：

actor
action
resource
input
result
executionId
requestId
timestamp

敏感 Input 必须支持脱敏。

例如：

password
token
secret
apiKey

禁止写入 Audit。

---

42. Action Visibility

Action 可以声明：

visibility:
  | 'public'
  | 'internal'
  | 'agent'
  | 'admin'

例如：

public

允许：

UI
API
CLI
Agent

而：

internal

只能内部调用。

---

43. Action Capability

Action 可以声明 Capability：

capabilities: [
  'network.http',
  'filesystem.read'
]

Runtime 必须检查。

这对于：

Plugin
MCP
Agent

尤其重要。

---

44. Action 与 Plugin

Plugin 注册：

defineAction({
  id: 'seo.website.scan',
  resource: 'seo.website',

  inputSchema: ScanInput,

  outputSchema: ScanOutput,

  execute: scanWebsite
})

DevOS Runtime 自动：

Register
 ↓
Validate
 ↓
Permission
 ↓
Expose

---

45. Action 与 MCP

MCP 不应该自己实现：

scanWebsite()

而应该：

MCP Tool
 ↓
Action Invocation
 ↓
seo.website.scan

MCP Tool Schema 可以自动从 Action Schema 生成。

因此：

Action Input Schema
        ↓
MCP Tool Schema

避免维护两套定义。

---

46. Action 与 Agent

Agent Tool 可以自动映射：

seo.website.scan

Agent 获得：

name
description
inputSchema
permission

Agent：

Tool Call
 ↓
Action Runtime

而不是：

Agent
 ↓
direct database

---

47. Action 与 CLI

CLI：

devos action seo.website.scan \
  --website-id website_123

CLI：

parse arguments
 ↓
Action Input
 ↓
Action Runtime

同一 Action。

---

48. Action 与 REST

REST Adapter：

POST /api/actions/seo.website.scan

Body：

{
  "websiteId": "website_123"
}

最终：

REST
 ↓
Action Invocation

---

49. Action 与 UI

UI：

await actions.execute(
  'seo.website.scan',
  {
    websiteId
  }
)

UI 不需要知道：

API URL
Database
Queue
Worker

---

50. Action Client SDK

SDK：

actions.execute(
  actionId,
  input
)

返回：

Promise<ActionResult<T>>

异步：

actions.executeAsync(
  actionId,
  input
)

---

51. Action Discovery

Action 必须可发现。

actionRegistry.list()

返回：

[
  {
    "id": "seo.website.scan",
    "resource": "seo.website",
    "description": "Scan a website",
    "mode": "async"
  }
]

Agent / MCP 可以利用这一能力。

---

52. Action Metadata

建议：

interface ActionMetadata {
  id: string

  resource?: string

  name: string

  description: string

  inputSchema?: unknown

  outputSchema?: unknown

  mode: ActionMode

  permission?: string

  dangerous?: boolean

  requiresApproval?: boolean

  idempotent?: boolean

  capabilities?: string[]
}

---

53. Dangerous Action

危险操作必须明确声明：

dangerous: true

例如：

server.delete
deployment.rollback
website.publish
database.reset

Agent 执行危险 Action 时可以要求：

Human Approval

---

54. Approval

Action 可以声明：

requiresApproval: true

执行：

Agent
 ↓
Action
 ↓
Approval Required
 ↓
User Approval
 ↓
Action Execute

Approval 本身应该成为平台资源：

core.approval

---

55. Resource Action Matrix

Resource 可以生成 Action Matrix。

例如：

Website

               User   Editor   Admin   Agent
------------------------------------------------
read            ✓       ✓       ✓       ✓
update          -       ✓       ✓       ✓
scan            -       ✓       ✓       ✓
publish         -       -       ✓       approval
delete          -       -       ✓       -

这可以成为：

Permission UI
Policy Engine
Agent Capability

的数据来源。

---

56. Action Composition

Action 可以调用另一个 Action。

但推荐通过 Runtime：

Action A
 ↓
Action Runtime
 ↓
Action B

而不是直接：

actionB.execute(...)

这样能够保留：

Authorization
Audit
Execution
Tracing
Events

---

57. Workflow 与 Action

Workflow 不是特殊的业务逻辑系统。

Workflow 由 Action 组成：

Workflow
 ├── Action A
 ├── Action B
 ├── Action C
 └── Action D

例如：

Website Audit

scan
 ↓
analyze
 ↓
generateReport
 ↓
createTasks
 ↓
notify

---

58. Action Context Propagation

Workflow：

Execution A
 ↓
Execution B
 ↓
Execution C

必须传播：

requestId
rootExecutionId
actor
organizationId
traceId

这样可以追踪完整执行链。

---

59. Root Execution

复杂 Agent / Workflow 应支持：

rootExecutionId
parentExecutionId
executionId

例如：

root
 │
 ├── skill execution
 │    │
 │    ├── action A
 │    └── action B
 │
 └── action C

---

60. Action Observability

每个 Action 必须可以统计：

execution count
success rate
failure rate
duration
queue time
retry count

例如：

seo.website.scan

Executions: 1,238
Success: 97.2%
Average: 38s
P95: 91s

---

61. Action Rate Limit

Action 可以定义：

rateLimit: {
  requests: 100,
  window: '1m'
}

Scope：

user
organization
ip
agent
plugin
global

---

62. Action Timeout

可以定义：

timeout: 30000

超时：

ACTION_TIMEOUT

Async Job 可以拥有独立 Timeout。

---

63. Resource Lifecycle

Resource 可以定义：

created
updated
deleted
archived
restored

Action 负责状态改变：

create
update
delete
archive
restore

Event 负责传播变化：

resource.created
resource.updated

---

64. Soft Delete

Resource 可以支持：

active
archived
deleted

是否 Soft Delete 由 Resource 定义。

Core 不强制所有 Resource 使用 Soft Delete。

---

65. Resource Ownership

Resource 可以声明：

ownership: {
  organization: true
}

表示：

Resource
 ↓
Organization

Authorization 自动使用 Organization Scope。

---

66. Resource Parent

支持：

Project
 ↓
Website
 ↓
Page

通过 ResourceRef：

parent?: ResourceRef

例如：

{
  "type": "seo.page",
  "id": "page_123",
  "parent": {
    "type": "seo.website",
    "id": "website_456"
  }
}

---

67. Resource Relationships

Resource 可以声明：

belongsTo
hasMany
references

例如：

Website
 ├── Keywords
 ├── Pages
 ├── Backlinks
 └── Reports

这些关系可以用于：

UI
Search
Agent Context
API

---

68. Resource UI Metadata

Resource 可以声明 UI Metadata：

ui: {
  icon: 'Globe',

  list: {
    columns: [...]
  },

  detail: {
    sections: [...]
  }
}

这样通用 DevOS UI 可以自动生成部分页面。

---

69. Resource Auto CRUD

对于简单 Resource：

create
read
update
delete

可以通过 Generic CRUD Engine 自动生成。

例如：

Resource Schema
      ↓
Generic CRUD
      ↓
API
      ↓
UI

但是复杂 Action 必须由业务实现。

---

70. 不允许 Auto CRUD 替代业务 Action

错误：

Website Scan

通过：

update({ status: 'scanning' })

模拟。

正确：

seo.website.scan

因为 Scan 是真正的业务 Action。

---

71. Action Naming

Action 命名应该：

resource.verb

例如：

website.create
website.update
website.delete
website.scan
website.verify
website.publish

不要：

website.doScanThing
website.handleWebsite
website.process

---

72. Action 原子性

Action 应尽可能表达一个清晰操作。

好：

website.scan

不好：

website.doEverything

复杂业务应该使用 Workflow。

---

73. Workflow 与“大 Action”

如果一个操作包含：

10+ steps

优先考虑：

Workflow

而不是：

巨大 Action Handler

---

74. Action Contract First

开发业务功能时：

第一步：

Define Resource

第二步：

Define Action Contract

第三步：

Implement Handler

第四步：

Expose UI/API/MCP/Agent

而不是先写：

React
Controller
Database

---

75. Recommended Development Flow

新功能：

Requirement
 ↓
Resource
 ↓
Action
 ↓
Permission
 ↓
Schema
 ↓
Handler
 ↓
Event
 ↓
UI
 ↓
API
 ↓
Agent/MCP

---

76. Example：SEO Website Scan

定义：

const scanWebsite = defineAction({
  id: 'seo.website.scan',

  resource: 'seo.website',

  mode: 'async',

  inputSchema: z.object({
    websiteId: z.string(),
    depth: z.number().default(3)
  }),

  outputSchema: z.object({
    executionId: z.string()
  }),

  permission: 'seo.website.scan',

  execute: async (ctx, input) => {
    // Business implementation
  }
})

---

77. 调用方式一：UI

await actions.execute(
  'seo.website.scan',
  {
    websiteId: 'website_123',
    depth: 3
  }
)

---

78. 调用方式二：REST

POST /api/actions/seo.website.scan

{
  "websiteId": "website_123",
  "depth": 3
}

---

79. 调用方式三：MCP

MCP 自动暴露：

seo.website.scan

Input Schema：

{
  "websiteId": "string",
  "depth": "number"
}

MCP 不实现 Scan。

---

80. 调用方式四：Agent

Agent：

I need to scan website_123

Agent 选择：

seo.website.scan

然后：

Action Runtime

---

81. 调用方式五：CLI

devos action seo.website.scan \
  --websiteId website_123 \
  --depth 3

---

82. 调用方式六：Workflow

seo.website.scan
 ↓
seo.website.analyze
 ↓
seo.report.generate

---

83. 六种入口，一个实现

最终：

                   UI
                    │
REST ───────────────┤
                    │
CLI ────────────────┤
                    ▼
MCP ───────────► ACTION RUNTIME
                    ▲
Agent ─────────────┤
                    │
Workflow ──────────┘
                    │
                    ▼
             Business Handler

绝对禁止维护六套业务实现。

---

84. Action Security Boundary

所有 Action 必须经过：

Authentication
Authorization
Validation
Capability Check
Audit

即使调用来自：

internal
agent
mcp
system

也不能默认绕过。

只有明确标记：

trusted internal

的内部 Action 才可以减少部分检查。

---

85. System Action

Core 可以拥有 System Action：

system.cache.clear
system.job.retry
system.plugin.reload

这些 Action 必须：

admin-only
audit
dangerous

---

86. Action Registration Error

启动时发现：

duplicate action id
invalid schema
missing permission
missing resource
invalid dependency

必须：

FAIL FAST

对于严重配置错误：

Application 不得进入 Ready 状态。

---

87. Resource Registration Error

同样：

duplicate resource type
invalid schema
invalid action

必须阻止对应 Extension 启动。

---

88. Extension Isolation

Plugin 注册：

resource
action
event

只能拥有自己的 namespace。

例如：

plugin.github.*
plugin.cloudflare.*

不得覆盖：

core.*
seo.*

除非通过明确的 Extension Override Contract。

---

89. Override

默认：

Override = Forbidden

未来如需要：

explicit override
version constraint
compatibility check

避免 Plugin 悄悄修改核心行为。

---

90. Resource Discovery API

提供：

GET /api/resources

以及：

GET /api/resources/:type

用于：

Admin
Developer Tools
Agent
MCP
Documentation

---

91. Action Discovery API

提供：

GET /api/actions

以及：

GET /api/actions/:id

可以返回：

{
  "id": "seo.website.scan",
  "resource": "seo.website",
  "mode": "async",
  "permission": "seo.website.scan",
  "inputSchema": {},
  "outputSchema": {}
}

---

92. Agent Discovery

Agent 默认不能看到所有 Action。

必须根据：

Agent Permissions
Organization
Resource Scope
Capabilities

过滤。

最终：

Available Actions

是：

All Actions
∩
Permission
∩
Capability
∩
Scope

---

93. MCP Discovery

MCP 也不能默认暴露全部 Action。

必须配置：

Allowed Actions

例如：

MCP Browser
    ↓
network.*
browser.*

而不能：

*

---

94. Action Approval Model

危险 Action：

dangerous = true

可以进一步：

approvalPolicy:
  always
  agent
  organization
  none

例如：

server.delete

默认：

always

---

95. Action Audit Privacy

Audit 必须支持：

redact
hash
omit

例如：

input: {
  apiKey: '[REDACTED]'
}

而不是记录真实 Secret。

---

96. Action Metrics

每个 Action 自动产生：

devos_action_total
devos_action_success
devos_action_failure
devos_action_duration
devos_action_queue_duration

标签：

actionId
status
app
plugin

避免将高基数：

userId
resourceId

直接作为 Metrics Label。

---

97. Action Logging

Log 自动包含：

requestId
executionId
actionId
actorId
organizationId

业务代码不需要手动重复加入。

---

98. Action Testing

每个 Action 必须至少拥有：

Input Validation Test
Authorization Test
Success Test
Failure Test
Audit Test
Event Test

Async Action 额外：

Job Dispatch Test
Retry Test
Cancellation Test

---

99. Resource Testing

每个 Resource 至少：

Schema Test
Registration Test
Permission Test
Action Registration Test

---

100. Golden Rule

DevOS v2 必须始终保持：

Resource
    ↓
Action
    ↓
Action Runtime

这是整个 DevOS 的业务执行主干。

---

101. 最终架构

                         ┌──────────────┐
                         │   Resource   │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │    Action    │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │ Action       │
                         │ Runtime      │
                         └──────┬───────┘
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
          Validation       Authorization        Policy
              │                 │                 │
              └─────────────────┼─────────────────┘
                                │
                         ┌──────▼───────┐
                         │  Middleware  │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │   Handler    │
                         └──────┬───────┘
                                │
                ┌───────────────┼───────────────┐
                │               │               │
              Audit           Event          Execution
                │               │               │
                └───────────────┼───────────────┘
                                │
                         ┌──────▼───────┐
                         │    Result    │
                         └──────────────┘

---

102. 最重要的设计结论

以后开发 DevOS App 时：

不要问：

“我要做一个 API。”

而应该问：

“我要创建什么 Resource？它有哪些 Action？”

然后：

Resource
+
Action
+
Permission
+
Schema
+
Handler

自然生成：

API
UI
MCP
Agent Tool
CLI
Workflow
Audit
Events
Metrics

这就是 DevOS v2 与普通 Admin Framework 最大的区别。

---

103. Implementation Rule for Zcode

Zcode 实施本规范时：

1. 不得为 UI 单独实现业务逻辑。
2. 不得为 REST Controller 单独实现业务逻辑。
3. 不得为 MCP Tool 单独实现业务逻辑。
4. 不得为 Agent Tool 单独实现业务逻辑。
5. 不得为 CLI 单独实现业务逻辑。
6. 所有业务执行必须进入 Action Runtime。
7. Action 必须拥有唯一 ID。
8. Action Input / Output 必须 Schema 化。
9. Action 必须经过 Authorization。
10. 敏感 Action 必须 Audit。
11. Async Action 必须支持 Execution。
12. Action 必须支持统一错误模型。
13. Resource 必须通过 Registry 注册。
14. App / Plugin 必须使用 namespace。
15. 禁止直接修改其他 Extension 的 Resource / Action。
16. Agent 与 Human 必须使用相同 Action。
17. MCP 与 API 必须使用相同 Action。
18. 复杂多步骤逻辑必须优先使用 Workflow。
19. Core 不允许依赖业务 Resource。
20. 任何绕过 Action Runtime 的业务执行代码都应视为架构违规。

---

104. 与后续模块的关系

本规范之后：

04_EVENT_TASK_JOB.md

定义：

Event
Task
Job
Execution
Queue
Scheduler
Workflow

然后：

05_PLUGIN_SYSTEM.md

将定义 Plugin 如何注册：

Resource
Action
Event
Page
Navigation
Settings
Widget
MCP
Skill

最终形成：

Plugin
   ↓
Resource
   ↓
Action
   ↓
Runtime

这将成为 DevOS v2 的标准扩展路径。