# 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 的两个核心抽象： ```text Resource Action ``` 这两个概念是 DevOS Platform 的统一业务执行基础。 目标： ```text UI REST API CLI MCP Skill Agent Workflow Plugin ``` 都不能分别实现业务逻辑。 所有业务操作最终应该进入： ```text Action Runtime ``` 统一执行。 --- # 2. 核心原则 DevOS 必须遵守： > **Resource 描述“系统中有什么”，Action 描述“可以对它做什么”。** 例如： ```text Resource: Website Actions: create read update delete scan analyze verify publish ``` --- # 3. 为什么不是简单 CRUD 传统 Admin： ```text GET /websites POST /websites PUT /websites/:id DELETE /websites/:id ``` 只能表达： ```text CRUD ``` 但是现代应用需要： ```text scan analyze publish deploy verify sync retry approve reject generate ``` 因此： ```text CRUD ``` 只是 Action 的一个子集。 --- # 4. 统一执行模型 DevOS 所有执行入口： ```text ┌──────────┐ │ UI │ └────┬─────┘ │ ┌──────────┐ │ │ REST API ├─────────────┤ └──────────┘ │ ▼ ┌──────────┐ ┌──────────────┐ │ CLI ├──────►│ Action │ └──────────┘ │ Runtime │ └──────┬───────┘ ┌──────────┐ │ │ MCP ├──────────────┤ └──────────┘ │ │ ┌──────────┐ │ │ Agent ├──────────────┤ └──────────┘ │ │ ┌──────────┐ │ │ Workflow ├──────────────┘ └──────────┘ ``` 最终： ```text Input ↓ Validation ↓ Authorization ↓ Action Middleware ↓ Action Handler ↓ Result ↓ Audit ↓ Event ``` --- # 5. Resource 定义 Resource 是一个平台级对象类型。 接口： ```ts interface ResourceDefinition< T = unknown > { type: string label: string description?: string schema: Schema actions: ActionDefinition[] permissions?: PermissionDefinition[] events?: EventDefinition[] ui?: ResourceUI } ``` --- # 6. Resource Type Resource type 必须唯一。 推荐： ```text . ``` 例如： ```text core.user core.organization project.project seo.website seo.keyword seo.content devops.server devops.deployment ``` 禁止使用： ```text website keyword server ``` 作为大型平台的全局 Resource Type。 --- # 7. Resource ID Resource ID 在同一 Resource Type 内唯一。 例如： ```text seo.website ``` 实例： ```text website_01 website_02 website_03 ``` 引用： ```ts interface ResourceRef { type: string id: string } ``` 示例： ```json { "type": "seo.website", "id": "website_123" } ``` --- # 8. Resource Metadata Resource 应提供机器可读 Metadata。 例如： ```ts const websiteResource = defineResource({ type: 'seo.website', label: 'Website', description: 'A website managed by SEO application', schema: WebsiteSchema, actions: [ scanWebsite, analyzeWebsite, verifyWebsite ] }) ``` Metadata 可以被： ```text UI CLI MCP Agent Documentation Search Admin ``` 使用。 --- # 9. Resource Schema Resource 必须定义 Schema。 推荐： ```text Zod ``` 例如： ```ts 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 的用途： ```text Validation Documentation UI Form MCP Schema Agent Context API Schema ``` --- # 10. Resource 不等于 Database Table 这是非常重要的规则。 Resource： ```text Platform Concept ``` Database Table： ```text Storage Implementation ``` 二者不要求一一对应。 例如： ```text Resource: seo.website ``` 可以由： ```text seo_websites seo_domains seo_settings ``` 多个表组成。 因此： > Resource 是业务对象抽象，而不是数据库表抽象。 --- # 11. Resource Registry DevOS 必须提供全局 Resource Registry。 ```ts interface ResourceRegistry { register( resource: ResourceDefinition ): void get( type: string ): ResourceDefinition | undefined has( type: string ): boolean list(): ResourceDefinition[] } ``` 启动阶段： ```text Core ↓ Apps ↓ Plugins ↓ Register Resources ``` --- # 12. Resource Registration Core： ```ts registerResource(userResource) registerResource(organizationResource) ``` SEO App： ```ts registerResource(websiteResource) registerResource(keywordResource) ``` Plugin： ```ts registerResource(backlinkResource) ``` 最终： ```text Resource Registry ├── core.user ├── core.organization ├── seo.website ├── seo.keyword ├── seo.content └── seo.backlink ``` --- # 13. Action 定义 Action 表示一个可执行操作。 ```ts interface ActionDefinition< TInput = unknown, TOutput = unknown > { id: string resource?: string name: string description?: string inputSchema?: Schema outputSchema?: Schema permission?: string mode?: ActionMode execute( context: ActionContext, input: TInput ): Promise } ``` --- # 14. Action ID Action ID 必须全局唯一。 推荐： ```text . ``` 例如： ```text core.user.create core.user.update seo.website.scan seo.website.analyze seo.website.publish devops.server.deploy ``` --- # 15. Action 类型 Action 至少分为： ```text query command job workflow ``` ### Query 读取数据： ```text website.get keyword.list ``` ### Command 修改状态： ```text website.update website.publish ``` ### Job 后台执行： ```text website.scan content.generate ``` ### Workflow 多个 Action 编排： ```text website.fullAudit ``` --- # 16. ActionMode 建议： ```ts type ActionMode = | 'sync' | 'async' | 'stream' ``` Sync： ```text 立即返回结果 ``` Async： ```text 返回 Execution / Job ``` Stream： ```text 持续输出进度 ``` --- # 17. Action Input 所有 Action 都必须定义 Input Contract。 例如： ```ts const ScanWebsiteInput = z.object({ websiteId: z.string(), depth: z.number() .int() .min(1) .max(10) }) ``` 调用： ```json { "websiteId": "website_123", "depth": 3 } ``` --- # 18. Action Output Output 同样必须定义 Schema。 ```ts const ScanWebsiteOutput = z.object({ executionId: z.string(), pagesScanned: z.number(), errors: z.number(), score: z.number() }) ``` 这使： ```text UI Agent MCP CLI ``` 都可以理解结果。 --- # 19. Action Context Action 永远不能只接受： ```ts input ``` 必须同时接收： ```ts context ``` 定义： ```ts interface ActionContext { requestId: string executionId: string actor: ActorContext organizationId?: string permissions: string[] signal?: AbortSignal metadata: Record } ``` --- # 20. Actor Action 必须知道是谁执行的。 Actor 类型： ```ts type ActorContext = | UserActor | AgentActor | ServiceActor | SystemActor ``` 例如： ```ts { type: 'user', id: 'user_123' } ``` 或者： ```ts { type: 'agent', id: 'seo-agent' } ``` --- # 21. Human 与 Agent 必须统一 用户： ```text User ↓ Action ``` Agent： ```text Agent ↓ Action ``` 因此 Action 不允许写： ```ts if (isAgent) { bypassPermission() } ``` 禁止 Agent 绕过权限。 --- # 22. Authorization Action 执行前必须检查 Permission。 例如： ```text seo.website.scan ``` 对应： ```text seo.website.scan ``` 或者： ```text seo.website.execute ``` 由 Permission Policy 决定。 --- # 23. Authorization 顺序 标准执行流程： ```text Request ↓ Resolve Action ↓ Validate Input ↓ Resolve Resource ↓ Resolve Actor ↓ Authorization ↓ Middleware ↓ Execute ``` 任何一步失败： ```text STOP ``` --- # 24. Resource-level Authorization Action 不应该只检查： ```text permission exists ``` 还需要检查： ```text resource scope ``` 例如： ```text user has: seo.website.update ``` 但： ```text website.organizationId ``` 必须属于： ```text context.organizationId ``` 否则拒绝。 --- # 25. Policy 复杂权限使用 Policy。 例如： ```ts const WebsiteUpdatePolicy = definePolicy({ resource: 'seo.website', action: 'update', check: async ({ actor, resource }) => { return resource.organizationId === actor.organizationId } }) ``` --- # 26. Validation Action Input： ```text Schema Validation ``` Resource： ```text Resource Validation ``` Output： ```text Output Validation ``` 流程： ```text Input ↓ Input Schema ↓ Policy ↓ Handler ↓ Output Schema ``` --- # 27. Action Middleware Action 支持 Middleware。 例如： ```text Authorization Audit Transaction RateLimit Idempotency Logging Metrics Tracing ``` 执行： ```text Action ↓ Middleware 1 ↓ Middleware 2 ↓ Middleware 3 ↓ Handler ``` --- # 28. Middleware 顺序 推荐： ```text Request ID ↓ Authentication ↓ Authorization ↓ Validation ↓ Rate Limit ↓ Idempotency ↓ Audit Start ↓ Transaction ↓ Handler ↓ Audit Result ↓ Event ``` --- # 29. Action Result 统一返回： ```ts interface ActionResult { success: boolean data?: T error?: DevError executionId: string requestId: string } ``` --- # 30. Action Error 统一错误： ```text 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。 ```ts 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 执行必须拥有唯一： ```text executionId ``` 例如： ```text exec_01J... ``` 用于： ```text Logs Audit Events Tracing Job Agent Workflow ``` --- # 33. Request ID vs Execution ID 两者必须区分。 ```text requestId ``` 表示一次外部请求。 ```text executionId ``` 表示一次 Action 执行。 例如： ```text HTTP Request requestId = req_123 ↓ Action executionId = exec_456 ↓ Job executionId = exec_456 ``` --- # 34. Idempotency 重要 Action 支持： ```text idempotencyKey ``` 例如： ```http Idempotency-Key: xxx ``` 防止： ```text 重复支付 重复发布 重复部署 重复创建任务 ``` Action 定义： ```ts { idempotent: true } ``` --- # 35. Transaction 需要数据库一致性的 Action 可以声明： ```ts { transaction: true } ``` Runtime： ```text Begin Transaction ↓ Action ↓ Commit ``` 失败： ```text Rollback ``` --- # 36. Async Action 例如： ```text seo.website.scan ``` 可能需要 30 分钟。 调用： ```text Action ↓ Execution ↓ Job ↓ Worker ``` API 不等待 30 分钟。 返回： ```json { "executionId": "exec_123", "status": "pending" } ``` --- # 37. Action Progress Async Action 可以提供 Progress： ```ts interface ExecutionProgress { current: number total?: number percentage?: number message?: string } ``` 例如： ```text Scanning website 127 / 500 pages 25% ``` UI 可以实时显示。 --- # 38. Action Cancellation Action 应支持： ```ts context.signal ``` 例如： ```text User ↓ Cancel ↓ AbortSignal ↓ Action ↓ Worker ``` 特别适用于： ```text Crawler Agent Generation Deployment Sync ``` --- # 39. Retry Async Action 支持： ```text retry ``` 配置： ```ts { retry: { maxAttempts: 3, backoff: 'exponential' } } ``` 但不是所有 Action 都允许 Retry。 例如： ```text createPayment ``` 必须非常谨慎。 --- # 40. Action Event Action 完成后可以产生： ```text action.started action.completed action.failed action.cancelled ``` 以及业务 Event。 例如： ```text seo.website.scan.completed ``` --- # 41. Audit 每次敏感 Action 必须记录： ```text actor action resource input result executionId requestId timestamp ``` 敏感 Input 必须支持脱敏。 例如： ```text password token secret apiKey ``` 禁止写入 Audit。 --- # 42. Action Visibility Action 可以声明： ```ts visibility: | 'public' | 'internal' | 'agent' | 'admin' ``` 例如： ```text public ``` 允许： ```text UI API CLI Agent ``` 而： ```text internal ``` 只能内部调用。 --- # 43. Action Capability Action 可以声明 Capability： ```ts capabilities: [ 'network.http', 'filesystem.read' ] ``` Runtime 必须检查。 这对于： ```text Plugin MCP Agent ``` 尤其重要。 --- # 44. Action 与 Plugin Plugin 注册： ```ts defineAction({ id: 'seo.website.scan', resource: 'seo.website', inputSchema: ScanInput, outputSchema: ScanOutput, execute: scanWebsite }) ``` DevOS Runtime 自动： ```text Register ↓ Validate ↓ Permission ↓ Expose ``` --- # 45. Action 与 MCP MCP 不应该自己实现： ```text scanWebsite() ``` 而应该： ```text MCP Tool ↓ Action Invocation ↓ seo.website.scan ``` MCP Tool Schema 可以自动从 Action Schema 生成。 因此： ```text Action Input Schema ↓ MCP Tool Schema ``` 避免维护两套定义。 --- # 46. Action 与 Agent Agent Tool 可以自动映射： ```text seo.website.scan ``` Agent 获得： ```text name description inputSchema permission ``` Agent： ```text Tool Call ↓ Action Runtime ``` 而不是： ```text Agent ↓ direct database ``` --- # 47. Action 与 CLI CLI： ```bash devos action seo.website.scan \ --website-id website_123 ``` CLI： ```text parse arguments ↓ Action Input ↓ Action Runtime ``` 同一 Action。 --- # 48. Action 与 REST REST Adapter： ```http POST /api/actions/seo.website.scan ``` Body： ```json { "websiteId": "website_123" } ``` 最终： ```text REST ↓ Action Invocation ``` --- # 49. Action 与 UI UI： ```tsx await actions.execute( 'seo.website.scan', { websiteId } ) ``` UI 不需要知道： ```text API URL Database Queue Worker ``` --- # 50. Action Client SDK SDK： ```ts actions.execute( actionId, input ) ``` 返回： ```ts Promise> ``` 异步： ```ts actions.executeAsync( actionId, input ) ``` --- # 51. Action Discovery Action 必须可发现。 ```ts actionRegistry.list() ``` 返回： ```json [ { "id": "seo.website.scan", "resource": "seo.website", "description": "Scan a website", "mode": "async" } ] ``` Agent / MCP 可以利用这一能力。 --- # 52. Action Metadata 建议： ```ts 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 危险操作必须明确声明： ```ts dangerous: true ``` 例如： ```text server.delete deployment.rollback website.publish database.reset ``` Agent 执行危险 Action 时可以要求： ```text Human Approval ``` --- # 54. Approval Action 可以声明： ```ts requiresApproval: true ``` 执行： ```text Agent ↓ Action ↓ Approval Required ↓ User Approval ↓ Action Execute ``` Approval 本身应该成为平台资源： ```text core.approval ``` --- # 55. Resource Action Matrix Resource 可以生成 Action Matrix。 例如： ```text Website User Editor Admin Agent ------------------------------------------------ read ✓ ✓ ✓ ✓ update - ✓ ✓ ✓ scan - ✓ ✓ ✓ publish - - ✓ approval delete - - ✓ - ``` 这可以成为： ```text Permission UI Policy Engine Agent Capability ``` 的数据来源。 --- # 56. Action Composition Action 可以调用另一个 Action。 但推荐通过 Runtime： ```text Action A ↓ Action Runtime ↓ Action B ``` 而不是直接： ```ts actionB.execute(...) ``` 这样能够保留： ```text Authorization Audit Execution Tracing Events ``` --- # 57. Workflow 与 Action Workflow 不是特殊的业务逻辑系统。 Workflow 由 Action 组成： ```text Workflow ├── Action A ├── Action B ├── Action C └── Action D ``` 例如： ```text Website Audit scan ↓ analyze ↓ generateReport ↓ createTasks ↓ notify ``` --- # 58. Action Context Propagation Workflow： ```text Execution A ↓ Execution B ↓ Execution C ``` 必须传播： ```text requestId rootExecutionId actor organizationId traceId ``` 这样可以追踪完整执行链。 --- # 59. Root Execution 复杂 Agent / Workflow 应支持： ```text rootExecutionId parentExecutionId executionId ``` 例如： ```text root │ ├── skill execution │ │ │ ├── action A │ └── action B │ └── action C ``` --- # 60. Action Observability 每个 Action 必须可以统计： ```text execution count success rate failure rate duration queue time retry count ``` 例如： ```text seo.website.scan Executions: 1,238 Success: 97.2% Average: 38s P95: 91s ``` --- # 61. Action Rate Limit Action 可以定义： ```ts rateLimit: { requests: 100, window: '1m' } ``` Scope： ```text user organization ip agent plugin global ``` --- # 62. Action Timeout 可以定义： ```ts timeout: 30000 ``` 超时： ```text ACTION_TIMEOUT ``` Async Job 可以拥有独立 Timeout。 --- # 63. Resource Lifecycle Resource 可以定义： ```text created updated deleted archived restored ``` Action 负责状态改变： ```text create update delete archive restore ``` Event 负责传播变化： ```text resource.created resource.updated ``` --- # 64. Soft Delete Resource 可以支持： ```text active archived deleted ``` 是否 Soft Delete 由 Resource 定义。 Core 不强制所有 Resource 使用 Soft Delete。 --- # 65. Resource Ownership Resource 可以声明： ```ts ownership: { organization: true } ``` 表示： ```text Resource ↓ Organization ``` Authorization 自动使用 Organization Scope。 --- # 66. Resource Parent 支持： ```text Project ↓ Website ↓ Page ``` 通过 ResourceRef： ```ts parent?: ResourceRef ``` 例如： ```json { "type": "seo.page", "id": "page_123", "parent": { "type": "seo.website", "id": "website_456" } } ``` --- # 67. Resource Relationships Resource 可以声明： ```text belongsTo hasMany references ``` 例如： ```text Website ├── Keywords ├── Pages ├── Backlinks └── Reports ``` 这些关系可以用于： ```text UI Search Agent Context API ``` --- # 68. Resource UI Metadata Resource 可以声明 UI Metadata： ```ts ui: { icon: 'Globe', list: { columns: [...] }, detail: { sections: [...] } } ``` 这样通用 DevOS UI 可以自动生成部分页面。 --- # 69. Resource Auto CRUD 对于简单 Resource： ```text create read update delete ``` 可以通过 Generic CRUD Engine 自动生成。 例如： ```text Resource Schema ↓ Generic CRUD ↓ API ↓ UI ``` 但是复杂 Action 必须由业务实现。 --- # 70. 不允许 Auto CRUD 替代业务 Action 错误： ```text Website Scan ``` 通过： ```text update({ status: 'scanning' }) ``` 模拟。 正确： ```text seo.website.scan ``` 因为 Scan 是真正的业务 Action。 --- # 71. Action Naming Action 命名应该： ```text resource.verb ``` 例如： ```text website.create website.update website.delete website.scan website.verify website.publish ``` 不要： ```text website.doScanThing website.handleWebsite website.process ``` --- # 72. Action 原子性 Action 应尽可能表达一个清晰操作。 好： ```text website.scan ``` 不好： ```text website.doEverything ``` 复杂业务应该使用 Workflow。 --- # 73. Workflow 与“大 Action” 如果一个操作包含： ```text 10+ steps ``` 优先考虑： ```text Workflow ``` 而不是： ```text 巨大 Action Handler ``` --- # 74. Action Contract First 开发业务功能时： 第一步： ```text Define Resource ``` 第二步： ```text Define Action Contract ``` 第三步： ```text Implement Handler ``` 第四步： ```text Expose UI/API/MCP/Agent ``` 而不是先写： ```text React Controller Database ``` --- # 75. Recommended Development Flow 新功能： ```text Requirement ↓ Resource ↓ Action ↓ Permission ↓ Schema ↓ Handler ↓ Event ↓ UI ↓ API ↓ Agent/MCP ``` --- # 76. Example：SEO Website Scan 定义： ```ts 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 ```ts await actions.execute( 'seo.website.scan', { websiteId: 'website_123', depth: 3 } ) ``` --- # 78. 调用方式二：REST ```http POST /api/actions/seo.website.scan ``` ```json { "websiteId": "website_123", "depth": 3 } ``` --- # 79. 调用方式三：MCP MCP 自动暴露： ```text seo.website.scan ``` Input Schema： ```json { "websiteId": "string", "depth": "number" } ``` MCP 不实现 Scan。 --- # 80. 调用方式四：Agent Agent： ```text I need to scan website_123 ``` Agent 选择： ```text seo.website.scan ``` 然后： ```text Action Runtime ``` --- # 81. 调用方式五：CLI ```bash devos action seo.website.scan \ --websiteId website_123 \ --depth 3 ``` --- # 82. 调用方式六：Workflow ```text seo.website.scan ↓ seo.website.analyze ↓ seo.report.generate ``` --- # 83. 六种入口，一个实现 最终： ```text UI │ REST ───────────────┤ │ CLI ────────────────┤ ▼ MCP ───────────► ACTION RUNTIME ▲ Agent ─────────────┤ │ Workflow ──────────┘ │ ▼ Business Handler ``` **绝对禁止维护六套业务实现。** --- # 84. Action Security Boundary 所有 Action 必须经过： ```text Authentication Authorization Validation Capability Check Audit ``` 即使调用来自： ```text internal agent mcp system ``` 也不能默认绕过。 只有明确标记： ```text trusted internal ``` 的内部 Action 才可以减少部分检查。 --- # 85. System Action Core 可以拥有 System Action： ```text system.cache.clear system.job.retry system.plugin.reload ``` 这些 Action 必须： ```text admin-only audit dangerous ``` --- # 86. Action Registration Error 启动时发现： ```text duplicate action id invalid schema missing permission missing resource invalid dependency ``` 必须： ```text FAIL FAST ``` 对于严重配置错误： ```text Application 不得进入 Ready 状态。 ``` --- # 87. Resource Registration Error 同样： ```text duplicate resource type invalid schema invalid action ``` 必须阻止对应 Extension 启动。 --- # 88. Extension Isolation Plugin 注册： ```text resource action event ``` 只能拥有自己的 namespace。 例如： ```text plugin.github.* plugin.cloudflare.* ``` 不得覆盖： ```text core.* seo.* ``` 除非通过明确的 Extension Override Contract。 --- # 89. Override 默认： ```text Override = Forbidden ``` 未来如需要： ```text explicit override version constraint compatibility check ``` 避免 Plugin 悄悄修改核心行为。 --- # 90. Resource Discovery API 提供： ```http GET /api/resources ``` 以及： ```http GET /api/resources/:type ``` 用于： ```text Admin Developer Tools Agent MCP Documentation ``` --- # 91. Action Discovery API 提供： ```http GET /api/actions ``` 以及： ```http GET /api/actions/:id ``` 可以返回： ```json { "id": "seo.website.scan", "resource": "seo.website", "mode": "async", "permission": "seo.website.scan", "inputSchema": {}, "outputSchema": {} } ``` --- # 92. Agent Discovery Agent 默认不能看到所有 Action。 必须根据： ```text Agent Permissions Organization Resource Scope Capabilities ``` 过滤。 最终： ```text Available Actions ``` 是： ```text All Actions ∩ Permission ∩ Capability ∩ Scope ``` --- # 93. MCP Discovery MCP 也不能默认暴露全部 Action。 必须配置： ```text Allowed Actions ``` 例如： ```text MCP Browser ↓ network.* browser.* ``` 而不能： ```text * ``` --- # 94. Action Approval Model 危险 Action： ```text dangerous = true ``` 可以进一步： ```text approvalPolicy: always agent organization none ``` 例如： ```text server.delete ``` 默认： ```text always ``` --- # 95. Action Audit Privacy Audit 必须支持： ```text redact hash omit ``` 例如： ```ts input: { apiKey: '[REDACTED]' } ``` 而不是记录真实 Secret。 --- # 96. Action Metrics 每个 Action 自动产生： ```text devos_action_total devos_action_success devos_action_failure devos_action_duration devos_action_queue_duration ``` 标签： ```text actionId status app plugin ``` 避免将高基数： ```text userId resourceId ``` 直接作为 Metrics Label。 --- # 97. Action Logging Log 自动包含： ```text requestId executionId actionId actorId organizationId ``` 业务代码不需要手动重复加入。 --- # 98. Action Testing 每个 Action 必须至少拥有： ```text Input Validation Test Authorization Test Success Test Failure Test Audit Test Event Test ``` Async Action 额外： ```text Job Dispatch Test Retry Test Cancellation Test ``` --- # 99. Resource Testing 每个 Resource 至少： ```text Schema Test Registration Test Permission Test Action Registration Test ``` --- # 100. Golden Rule DevOS v2 必须始终保持： ```text Resource ↓ Action ↓ Action Runtime ``` 这是整个 DevOS 的业务执行主干。 --- # 101. 最终架构 ```text ┌──────────────┐ │ Resource │ └──────┬───────┘ │ ┌──────▼───────┐ │ Action │ └──────┬───────┘ │ ┌──────▼───────┐ │ Action │ │ Runtime │ └──────┬───────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ Validation Authorization Policy │ │ │ └─────────────────┼─────────────────┘ │ ┌──────▼───────┐ │ Middleware │ └──────┬───────┘ │ ┌──────▼───────┐ │ Handler │ └──────┬───────┘ │ ┌───────────────┼───────────────┐ │ │ │ Audit Event Execution │ │ │ └───────────────┼───────────────┘ │ ┌──────▼───────┐ │ Result │ └──────────────┘ ``` --- # 102. 最重要的设计结论 以后开发 DevOS App 时： **不要问：** > “我要做一个 API。” 而应该问： > “我要创建什么 Resource？它有哪些 Action？” 然后： ```text Resource + Action + Permission + Schema + Handler ``` 自然生成： ```text 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. 与后续模块的关系 本规范之后： ```text 04_EVENT_TASK_JOB.md ``` 定义： ```text Event Task Job Execution Queue Scheduler Workflow ``` 然后： ```text 05_PLUGIN_SYSTEM.md ``` 将定义 Plugin 如何注册： ```text Resource Action Event Page Navigation Settings Widget MCP Skill ``` 最终形成： ```text Plugin ↓ Resource ↓ Action ↓ Runtime ``` 这将成为 DevOS v2 的标准扩展路径。