# DevOS Final Architecture Specification **Document:** `35_DEVOS_FINAL_ARCHITECTURE_SPEC.md` **Status:** FINAL ARCHITECTURE SPECIFICATION **Audience:** Zcode / AI Coding Agent / DevOS Core Team / Plugin Developers **Project Root:** `/home/dev/bun/devos` **Version:** `1.0.0` --- # 1. 文档目的 本文档是 DevOS 架构系列 `01–34` 的最终收敛规范。 前面的文档分别定义了： - Foundation Runtime - Resource / Action Runtime - Identity / Security / Tenancy - Data / Query / Search - Configuration / Secret / Provider - Task / Job / Queue / Worker - Event / Notification / Realtime - Storage / Artifact - Observability / Audit - API / SDK - Plugin Runtime / Marketplace - MCP Runtime - Skill Runtime - Agent Runtime - Agent Memory / Context - Model / AI Provider - Workflow - Project Factory - Generator - Deployment / Infrastructure - Plugin Developer Platform - Testing / Quality Gate - Migration / Versioning / Compatibility 本文档的任务不是重新设计这些系统，而是定义： > **这些系统最终如何组合成一个统一的 DevOS。** 从本文件开始，Zcode 不应该再因为“缺少某个基础 Runtime”而随意新增第二套架构。 --- # 2. DevOS 最终定位 DevOS 不是： - 一个后台管理模板 - 一个 SEO 系统 - 一个 CMS - 一个 AI Chat App - 一个 Workflow Engine - 一个 MCP Server - 一个 Plugin Marketplace - 一个 DevOps 平台 - 一个 Agent Framework - 一个数据库 ORM - 一个 Kubernetes 平台 DevOS 是： > **一个可扩展的 Application Runtime + Agent Runtime + Capability Platform + Project Factory。** 最终目标： ```text DevOS │ ┌───────────┴───────────┐ │ │ Application Runtime Agent Runtime │ │ └───────────┬───────────┘ │ Capability Runtime │ ┌───────────┼───────────┐ │ │ │ Resource Action Event │ │ │ └───────────┼───────────┘ │ Core Runtime │ ┌────────────┼────────────┐ │ │ │ Data Security Config │ │ │ Storage Identity Provider │ Task/Job/Queue │ Worker ``` DevOS 最终应该能够： ```text 定义能力 ↓ 注册能力 ↓ 授权能力 ↓ 组合能力 ↓ Agent / Workflow / UI / API 调用能力 ↓ 统一执行 ↓ 产生 Execution ↓ 产生 Event ↓ 进入 Task / Notification / Realtime / Audit / Observability ``` --- # 3. DevOS 的核心抽象 整个系统最终只需要牢牢围绕以下核心对象： ```text Resource Action Query Execution Task Job Event Capability Plugin Skill Agent Project Artifact ``` 以及支撑这些对象运行的 Runtime： ```text Security Identity Data Config Secret Provider Storage Task Event Search Notification Communication Observability Migration API UI ``` --- # 4. 最核心的六个概念 DevOS 最重要的不是具体技术，而是以下六个概念。 ## 4.1 Resource 回答： > 系统中“有什么东西”？ 例如： ```text core.user core.organization core.project devops.server devops.deployment seo.website seo.keyword seo.backlink content.article content.document ``` Resource 定义： - schema - fields - relations - permissions - scope - search metadata - UI metadata - lifecycle --- # 5. Action 回答： > 对 Resource 可以做什么？ 例如： ```text core.user.create core.user.update core.user.delete devops.server.connect devops.server.execute seo.website.scan seo.website.analyze content.article.generate content.article.publish ``` Action 是 DevOS 的统一业务执行单位。 任何业务执行都必须最终进入： ```text Action ↓ Authorization ↓ Action Runtime ↓ Execution ``` --- # 6. Query Query 专门负责读取。 ```text Resource ↓ Query ↓ Authorization ↓ Scope ↓ Data Runtime ↓ Database / Search ``` 规则： > Query 可以读取数据；Action 负责业务写入。 禁止： ```text Controller → Prisma Plugin → Prisma Agent → Prisma MCP → Prisma UI → Prisma Skill → Prisma ``` --- # 7. Execution Execution 是 DevOS 最重要的运行时事实。 它代表： > 某一次 Action 实际执行发生了什么。 Execution 必须能够追踪： ```text requestId correlationId traceId executionId actor organization project environment action actionVersion plugin pluginVersion skill skillVersion mcp mcpVersion agent task job runtimeVersion startedAt completedAt status error result ``` 最终目标： > **任何重要行为都必须可以被追溯。** --- # 8. Task / Job Task： > 用户或 Agent 认为的一项工作。 Job： > Worker 实际需要执行的一项工作。 关系： ```text Task ↓ Job ↓ Queue ↓ Worker ↓ Action ↓ Execution ``` 例如： ```text Task: “生成100篇文章并发布” Jobs: article-001 article-002 ... article-100 ``` Agent 不应该直接创建 100 个外部 API 调用。 --- # 9. Event Event 回答： > 系统发生了什么？ 例如： ```text user.created article.published deployment.failed task.completed agent.memory.created plugin.installed ``` 核心： ```text Action ↓ Execution ↓ Event ``` 然后 Event 可以驱动： ```text Notification Webhook Realtime Workflow Agent Task Audit Integration ``` --- # 10. Capability Capability 是 Agent / Plugin / Skill / MCP / UI / API 可以发现和使用的能力。 Capability 可以由： ```text Resource Action Query Provider Plugin Skill MCP ``` 共同构成。 最终： ```text Capability Registry ``` 是 DevOS 的统一能力目录。 --- # 11. 最终 Runtime 总图 DevOS 最终架构： ```text ┌─────────────────────────────────────────────────────────────┐ │ DEVOS UI │ │ │ │ Dashboard / Resource / Action / Task / Agent / Plugin │ │ Search / Command / Settings / Notification / Realtime │ └──────────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ │ API RUNTIME │ │ REST / SSE / WebSocket / SDK / CLI / Webhook │ └──────────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ │ SECURITY RUNTIME │ │ Authentication / Authorization / Policy / Scope / Tenant │ └──────────────────────────────┬──────────────────────────────┘ │ ┌─────────────▼─────────────┐ │ CAPABILITY REGISTRY │ │ Resource / Action / Query │ │ Provider / Skill / MCP │ └─────────────┬─────────────┘ │ ┌──────────────────────────────▼──────────────────────────────┐ │ ACTION RUNTIME │ │ Validation / Auth / Policy / Transaction / Idempotency │ │ Audit / Metrics / Trace / Execution / Error │ └──────────────────────────────┬──────────────────────────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ Data Runtime Task Runtime Event Runtime │ │ │ ▼ ▼ ▼ PostgreSQL Queue/Worker Event Bus │ │ │ │ ▼ ├── Notification │ Action ├── Webhook │ ├── Realtime │ └── Workflow │ ┌──────┴────────┐ ▼ ▼ Search Storage pgvector S3 ``` --- # 12. Agent Runtime Agent 是 DevOS 上层的智能决策系统。 Agent 不拥有基础设施。 正确关系： ```text User Goal ↓ Agent ↓ Context Runtime ↓ Memory / Knowledge / Task / Project ↓ Skill ↓ Capability ↓ Action ↓ Action Runtime ``` Agent 不允许： ```text Agent → DB Agent → Redis Agent → Queue Agent → Storage Agent → Secret Agent → Provider SDK ``` Agent 必须通过 Capability / Action。 --- # 13. Skill Runtime Skill 回答： > 如何解决某一类问题？ 例如： ```text seo-content-generation seo-backlink-analysis server-deployment github-release website-audit ``` Skill： - 提供方法 - 提供流程知识 - 声明 Capability 需求 - 指导 Agent Skill 不应该自己直接执行基础设施。 正确： ```text Agent ↓ Skill ↓ Capability ↓ Action ``` --- # 14. MCP Runtime MCP 是： > 外部能力访问协议 / Transport / Adapter。 MCP 不是第二套业务 Runtime。 正确： ```text MCP ↓ Capability ↓ Action Runtime ``` 禁止： ```text MCP → 独立业务 Service MCP → Prisma MCP → Redis MCP → Secret DB ``` MCP 必须继承： - Security - Permission - Scope - Audit - Rate Limit - Observability --- # 15. Plugin Runtime Plugin 是： > DevOS 的扩展单元。 Plugin 可以提供： ```text Resource Action Query Provider Skill MCP Event Notification UI Search Integration ``` 但是： > Plugin 不拥有 Runtime。 Plugin 不应该创建： ```text 自己的 Auth 自己的 RBAC 自己的 Queue 自己的 EventBus 自己的 Secret Store 自己的 Router 自己的 Storage Runtime 自己的 Agent Runtime ``` 正确： ```text Plugin ↓ Plugin SDK ↓ DevOS Runtime ``` --- # 16. Plugin SDK Plugin SDK 是插件开发者唯一推荐入口。 例如： ```ts import { definePlugin } from '@devos/plugin-sdk'; export default definePlugin({ manifest, setup(ctx) { ctx.resources.register(...); ctx.actions.register(...); ctx.providers.register(...); }, }); ``` Plugin SDK 应隐藏： - Prisma - Redis - Queue - Event Bus - Secret Storage - Internal Runtime implementation - HTTP internals 这样 DevOS 才能未来替换底层实现。 --- # 17. UI Runtime UI 不是业务执行系统。 UI 只是 Runtime 的可视化入口。 正确： ```text UI ↓ API ↓ Action Runtime ``` 读取： ```text UI ↓ Query API ↓ Data Runtime ``` 异步： ```text UI ↓ Action ↓ Task ↓ Job ↓ Worker ``` 实时： ```text Event ↓ Realtime ↓ UI ``` --- # 18. UI Plugin Extension 插件可以贡献： ```text Page Navigation Widget Resource View Action View Settings Command Search Provider Dashboard ``` 但是不能拥有： ```text Router Layout Auth Permission Global Store 独立 Query Runtime ``` 最终： ```text DevOS UI Shell ↓ Plugin UI Extension ``` --- # 19. Data Runtime PostgreSQL 是初始核心数据源。 推荐： ```text PostgreSQL + Prisma + pgvector ``` Data Runtime 负责： - Repository - Query - Filter - Sort - Pagination - Relations - Authorization - Scope - Transactions - Data access policy 业务代码不能散落： ```ts prisma.xxx.findMany() ``` 而应该： ```ts ctx.query.execute(...) ``` 或： ```ts repository.find(...) ``` --- # 20. Search Runtime Search 是 Data 的衍生能力。 初期： ```text PostgreSQL FTS + pgvector ``` 支持： ```text Keyword Search Full Text Search Semantic Search Hybrid Search Reranking ``` 未来可以接： ```text OpenSearch Elasticsearch Meilisearch Typesense ``` 但是： > Search Provider 可以替换，Search Runtime 不能被插件重复实现。 --- # 21. Storage Runtime 文件体系： ```text File ↓ File Metadata ↓ Storage Runtime ↓ Storage Provider ↓ Blob ``` 推荐： ```text Local S3 S3-compatible ``` 业务代码不能： ```text fs.writeFile(...) ``` 插件不能： ```text 直接操作 uploads/ ``` Agent 也不能直接访问服务器文件系统。 --- # 22. Artifact Artifact 是可追踪的输出。 例如： ```text Generated Article Deployment Package SEO Report Backup Screenshot CSV Export AI Generated Document ``` Artifact 应记录： ```text creator source task job execution version checksum storageObject createdAt ``` 因此： ```text Agent → Artifact Task → Artifact Plugin → Artifact Workflow → Artifact ``` 最终都进入 Storage Runtime。 --- # 23. Configuration Runtime 所有配置统一进入： ```text Config Runtime ``` 配置层级： ```text Global ↓ Organization ↓ Project ↓ Environment ↓ Plugin ↓ Resource ↓ Runtime Override ``` 业务代码禁止直接依赖： ```ts process.env ``` 应： ```ts config.get(...) ``` --- # 24. Secret Runtime Secret 与 Config 必须严格分离。 Secret： ```text API Key Password OAuth Secret SMTP Password Provider Credential Private Key ``` 原则： ```text Secret Reference ↓ Secret Runtime ↓ Credential ↓ Provider ``` 禁止： ```text Agent → Secret plaintext Plugin → Secret DB Log → Secret Event → Secret Audit → Secret Redis → plaintext secret ``` --- # 25. Provider Runtime 所有外部服务统一 Provider 化。 例如： ```text Model Provider Email Provider SMS Provider Git Provider Cloud Provider DNS Provider Storage Provider Search Provider Payment Provider ``` 业务系统只依赖： ```text Provider Interface ``` 而不是： ```text OpenAI SDK AWS SDK GitHub SDK SMTP library ``` Provider Runtime 统一处理： - credential - timeout - retry - circuit breaker - health - rate limit - failover - cost - usage - observability --- # 26. Model Runtime AI 模型必须通过 Model Runtime。 最终： ```text Agent ↓ Model Runtime ↓ Model Policy ↓ Model Provider ↓ External Model ``` 支持： ```text Chat Completion Structured Output Tool Calling Streaming Embedding Reranking Vision Audio ``` 业务代码不允许硬编码： ```text OpenAI Anthropic Gemini ``` --- # 27. Agent Context Runtime Context： > Agent 当前需要看到什么。 Memory： > 什么信息应该长期保存。 Knowledge： > 外部事实来源。 Conversation： > 对话记录。 Artifact： > 文件/输出。 最终： ```text Goal ↓ Context Runtime ├── Session ├── Task ├── Project ├── Knowledge ├── Memory ├── Conversation └── Artifact ↓ Retrieve ↓ Rank ↓ Filter ↓ Compress ↓ Budget ↓ Model ``` --- # 28. Memory Runtime Memory 不能成为业务数据库。 类型： ```text Working Episodic Semantic Procedural Preference ``` 所有 Memory： - 有 Scope - 有 Provenance - 有 Confidence - 有 Version - 有 Lifecycle - 有 Retention - 有 Security Policy 禁止： > 自动把所有聊天记录永久保存成 Memory。 --- # 29. Workflow Runtime Workflow 是： > 已知流程的确定性执行。 Agent 是： > 不确定目标下的动态决策。 因此： ```text Workflow = Deterministic Agent = Dynamic Skill = Method Action = Execution ``` 例如： ```text Workflow: 发布文章 → 审核 → 转换 → 上传 → 发布 → 通知 ``` Agent： ```text 目标： “让这个网站提升自然流量” Agent 自己决定： 分析 → 搜索 → 计划 → 执行 → 验证 → 调整 ``` --- # 30. Task Runtime 所有长期运行工作都必须 Task 化。 例如： ```text Agent Goal Workflow Import Export Migration Plugin Install Plugin Upgrade Batch Generation Index Rebuild Notification Digest ``` 都进入： ```text Task ``` --- # 31. Queue / Worker Queue 只负责： ```text 排序 等待 分发 重试 延迟 优先级 ``` Worker 负责： ```text 领取 Job ↓ 执行 Action ↓ 更新 Execution ↓ 产生 Event ``` 禁止 Worker 直接实现另一套业务系统。 --- # 32. Event Runtime 所有 Runtime 都通过 Event 连接。 例如： ```text Action ↓ Execution ↓ Event ``` Event 可以触发： ```text Workflow Notification Webhook Agent Task Realtime Integration ``` 最终形成： ```text DevOS Event Mesh ``` 但初期不需要 Kafka。 优先： ```text PostgreSQL Outbox + Redis ``` 未来有规模需求再替换底层。 --- # 33. Notification Runtime 业务只描述： > 发生了什么，需要通知谁。 Notification Runtime 决定： ```text Recipient Template Channel Provider Timing Retry Dedup Preference ``` 最终： ```text Event ↓ Notification ↓ Message ↓ Delivery ↓ Communication Provider ``` 禁止业务模块直接： ```text SMTP Twilio Slack API ``` --- # 34. Communication Runtime Communication 是实际发送层。 支持： ```text In-App Email Webhook Push SMS Chat ``` Provider： ```text SMTP Generic Webhook FCM APNs Twilio Slack Discord Teams Telegram ``` Provider 可替换。 --- # 35. Security Runtime 安全是所有 Runtime 的横向基础。 统一： ```text Authentication ↓ Authorization ↓ Scope ↓ Policy ↓ Action Runtime ``` 所有 Actor： ```text User Agent Plugin MCP Workflow Scheduler Service CLI API System ``` 必须进入同一套 Security Context。 --- # 36. Agent 不是超级用户 这是 DevOS 的硬规则。 Agent 权限： ```text User Permission ∩ Agent Policy ∩ Project Scope ∩ Action Policy ``` 而不是： ```text Agent = admin ``` 高风险操作： ```text Delete Production Deploy Send Mass Email Change DNS Rotate Credential Destroy Infrastructure ``` 可以要求： ```text Approval ``` --- # 37. Multi-Tenancy 最终层级： ```text Organization ↓ Project ↓ Environment ↓ Resource ``` 例如： ```text Organization: Acme Project: SEO Platform ├── development ├── staging └── production ``` 任何 Query / Action / Task / Event / File / Memory 都必须带正确 Scope。 --- # 38. Environment 至少： ```text development staging production ``` Production 必须拥有更严格的： - Permission - Approval - Secret - Deployment - Network - Destructive Action - Audit --- # 39. API Runtime API 是 Runtime 的 Transport。 最终： ```text REST SDK CLI Webhook MCP UI ``` 都只是入口。 所有入口最终： ```text Security ↓ Capability ↓ Action / Query / Task ↓ Runtime ``` 因此不能出现： ```text REST business logic SDK business logic CLI business logic MCP business logic UI business logic ``` --- # 40. SDK 官方 SDK： ```text @devos/sdk ``` 插件 SDK： ```text @devos/plugin-sdk ``` Server SDK： ```text @devos/server-sdk ``` SDK 应尽可能： ```text typed generated versioned backward compatible ``` --- # 41. CLI 官方 CLI： ```bash devos ``` 核心命令： ```bash devos project devos plugin devos task devos agent devos workflow devos migration devos doctor devos upgrade ``` CLI 不直接访问数据库。 正确： ```text CLI ↓ SDK ↓ API ↓ Runtime ``` --- # 42. Observability 每一个重要 Execution 都应能够关联： ```text requestId correlationId traceId executionId taskId jobId actorId organizationId projectId pluginId agentId ``` 统一： ```text Logs Metrics Traces Audit Usage Cost Health Diagnostics Alerts ``` --- # 43. Audit Audit 与 Log 不一样。 Log： > 系统发生了什么技术信息。 Audit： > 谁，在什么权限下，对什么对象做了什么。 例如： ```text Actor: user_123 Action: server.delete Target: server_456 Reason: cleanup Approval: approval_789 Before: ... After: ... ``` Audit 应具备更高的完整性和保留级别。 --- # 44. Error Runtime 所有 Runtime 使用统一 Error Contract。 例如： ```text DEVOS_AUTH_REQUIRED DEVOS_PERMISSION_DENIED DEVOS_SCOPE_DENIED DEVOS_RESOURCE_NOT_FOUND DEVOS_VALIDATION_FAILED DEVOS_RATE_LIMITED DEVOS_PROVIDER_TIMEOUT DEVOS_PROVIDER_UNAVAILABLE DEVOS_TASK_FAILED DEVOS_ACTION_CONFLICT DEVOS_APPROVAL_REQUIRED ``` Error 应区分： ```text User Message Internal Message Error Code Retryable Severity Fingerprint ``` 禁止将： ```text stack trace secret credential internal SQL ``` 直接返回给用户。 --- # 45. Migration / Versioning DevOS 必须承认版本是系统的一等公民。 需要版本化： ```text Platform Plugin Database API Resource Action Event Skill MCP Configuration Model ``` 生产 Execution 最终应该能够回答： ```text Runtime Version Plugin Version Action Version Skill Version MCP Version Event Version Config Version ``` --- # 46. Plugin Compatibility Plugin Manifest 至少声明： ```yaml id: acme.example version: 1.4.0 apiVersion: "1" devos: minVersion: "1.0.0" maxVersion: "2.x" ``` 生产环境必须锁定： ```text plugin version checksum ``` 禁止生产： ```text latest ``` --- # 47. Project Factory Project Factory 是 DevOS 最终的生产能力。 目标： > DevOS 不只是运行项目，还应该能够生成项目。 输入： ```text 需求 ``` 经过： ```text Requirement ↓ Capability Resolver ↓ Dependency Resolver ↓ Project Manifest ↓ Generator ↓ Template ↓ Project ``` --- # 48. Project Manifest 例如： ```yaml name: my-ai-app type: ai-app capabilities: - auth - organization - project - agent - memory - storage - notification modules: - content plugins: - github deployment: profile: docker ``` Manifest 是项目的 Source of Truth。 --- # 49. Project 类型 至少支持： ```text platform-app admin-app saas-app ai-app website api-service worker-service agent-service mcp-server automation-service plugin module extension library ``` --- # 50. DevOS 三种复用方式 ## 50.1 Platform Extension 直接运行在 DevOS。 ```text DevOS └── Plugin / Module ``` 适合： ```text SEO CRM Content DevOps ``` --- ## 50.2 Generated Project 由 Project Factory 生成。 ```text DevOS ↓ Generator ↓ New Project ``` --- ## 50.3 Forked Base 需要高度独立时： ```text devos-base ↓ Custom Product ``` 但是： > Fork 是最后手段。 --- # 51. SEO 在最终架构中的位置 SEO 不应该再成为第二套基础架构。 正确： ```text DevOS Core ↓ Agent Runtime ↓ Skill Runtime ↓ SEO Plugin / Module ↓ SEO Resource / Action / Provider ``` 例如： ```text seo.website seo.keyword seo.backlink seo.article seo.audit ``` SEO 只是 DevOS 的一个 Domain Extension。 --- # 52. 一个完整 Agent 场景 用户： > 10 天内让 example.com 增加 100 篇文章并获得 200 个 DR。 系统： ```text User Goal ↓ Agent ↓ Context Runtime ↓ Memory / Project / SEO Data ↓ Skill Discovery ↓ SEO Skills ↓ Capability Discovery ↓ Plan ``` 然后： ```text Task ├── Keyword Research ├── Content Generation ├── Content Review ├── Publishing ├── Backlink Discovery ├── Outreach └── Verification ``` 每个任务： ```text Task ↓ Job ↓ Queue ↓ Worker ↓ Action ↓ Execution ↓ Event ``` Event： ```text article.published backlink.created task.failed ``` 然后： ```text Notification Realtime Audit Observability Agent Observation ``` Agent 根据结果： ```text Evaluate ↓ Continue / Replan / Finish ``` 这就是 DevOS 最终希望实现的： > **Goal → Agent → Skill → Capability → Action → Execution → Event → Task → Result → Agent。** --- # 53. 最终依赖方向 依赖方向必须严格控制。 推荐： ```text Domain ↓ Capability ↓ Runtime ↓ Infrastructure ``` 更具体： ```text UI ↓ API ↓ Security ↓ Capability ↓ Action Runtime ↓ Domain Action ↓ Data / Task / Event / Storage ↓ PostgreSQL / Redis / Object Storage ``` 禁止反向： ```text Infrastructure → Domain Database → Agent Redis → UI Plugin → Core internals UI → Prisma ``` --- # 54. Package Architecture 最终建议： ```text packages/ │ ├── core/ ├── runtime/ │ ├── identity/ ├── security/ ├── authorization/ ├── tenancy/ ├── policy/ ├── approval/ │ ├── resource/ ├── action/ ├── execution/ ├── capability/ │ ├── data/ ├── schema/ ├── search/ ├── cache/ │ ├── config/ ├── secret/ ├── credential/ ├── provider/ ├── environment/ │ ├── task/ ├── job/ ├── queue/ ├── worker/ ├── scheduler/ │ ├── event/ ├── notification/ ├── communication/ ├── realtime/ ├── webhook/ │ ├── storage/ ├── file/ ├── artifact/ ├── workspace/ │ ├── agent/ ├── agent-context/ ├── agent-memory/ ├── agent-session/ ├── agent-retrieval/ ├── skill/ ├── mcp/ ├── model/ │ ├── workflow/ │ ├── observability/ ├── logging/ ├── metrics/ ├── tracing/ ├── audit/ ├── health/ ├── diagnostics/ ├── usage/ ├── alerts/ │ ├── migration/ ├── versioning/ ├── compatibility/ │ ├── api/ ├── openapi/ ├── sdk/ ├── cli/ │ ├── plugin-runtime/ ├── plugin-sdk/ ├── plugin-cli/ ├── plugin-testing/ ├── plugin-registry/ ├── plugin-marketplace/ ├── plugin-certification/ ├── plugin-sandbox/ │ ├── ui/ ├── ui-shell/ ├── ui-runtime/ ├── ui-resource/ ├── ui-action/ ├── ui-task/ ├── ui-agent/ ├── ui-plugin/ ├── ui-settings/ ├── ui-search/ ├── ui-command/ ├── ui-realtime/ │ ├── project/ ├── project-factory/ ├── generator/ └── templates/ ``` 实际项目可以合并部分 package。 重要的是： > **逻辑边界必须存在，文件数量不是目的。** --- # 55. 最终 Repository 推荐： ```text /devos │ ├── apps/ │ ├── api/ │ ├── web/ │ ├── worker/ │ └── cli/ │ ├── packages/ │ └── ... │ ├── plugins/ │ ├── official/ │ └── community/ │ ├── modules/ │ ├── seo/ │ ├── content/ │ ├── devops/ │ └── ... │ ├── projects/ │ ├── templates/ │ ├── docs/ │ ├── tests/ │ ├── scripts/ │ ├── docker/ │ ├── devos.project.yaml ├── package.json ├── pnpm-workspace.yaml └── turbo.json ``` 具体采用 pnpm / Bun / Turborepo / Nx 可以根据现有项目实际情况决定。 不要为了“理论完美”强行迁移整个仓库。 --- # 56. 技术栈最终建议 ## Frontend ```text React TypeScript Vite React Router TanStack Query Zustand React Hook Form Zod Ant Design ProComponents TipTap ECharts Monaco React Markdown ``` --- ## Backend ```text NestJS Fastify TypeScript ``` --- ## Database ```text PostgreSQL Prisma pgvector ``` --- ## Coordination ```text Redis ``` --- ## Storage ```text S3-compatible ``` --- ## Runtime ```text Node.js / Bun Docker ``` --- # 57. 不要过早引入的技术 除非实际规模证明必要，否则不要第一阶段引入： ```text Kafka Kubernetes Elasticsearch OpenSearch Temporal Ray 复杂 Service Mesh 复杂 Event Sourcing 多数据库分片 复杂微服务体系 ``` 正确原则： > **先建立正确抽象，再替换基础设施。** 例如： ```text Event Runtime ``` 未来可以： ```text PostgreSQL → Kafka ``` 但上层业务不应该改变。 --- # 58. DevOS 的 Runtime Replacement 原则 任何基础设施都应该可替换： ```text Database Queue Search Storage Model Email Cloud Git ``` 因此： ```text Business ↓ Runtime Interface ↓ Provider ↓ Infrastructure ``` 而不是： ```text Business ↓ Infrastructure SDK ``` --- # 59. Runtime 不应该互相重复 这是 DevOS 最重要的架构纪律之一。 系统中： ```text 只有一个 Action Runtime 只有一个 Task Runtime 只有一个 Event Runtime 只有一个 Storage Runtime 只有一个 Security Runtime 只有一个 Config Runtime 只有一个 Notification Runtime 只有一个 Agent Runtime 只有一个 Plugin Runtime ``` 插件不能创建： ```text PluginActionRuntime PluginTaskRuntime PluginEventBus PluginSecretManager ``` 业务模块同样不能创建： ```text SeoQueue SeoEventBus SeoTaskManager ``` 如果发现类似代码： > 优先考虑复用 Runtime，而不是增加 Runtime。 --- # 60. Runtime Contract 每一个 Runtime 都应该具有统一 Contract： ```ts interface Runtime { initialize(): Promise; health(): Promise; shutdown(): Promise; } ``` 并具备： ```text Context Authorization Scope Audit Observability Error Contract Version ``` --- # 61. Context Contract 所有 Runtime Context 最终应共享： ```ts interface RuntimeContext { requestId: string; correlationId: string; traceId?: string; actor: Actor; organizationId?: string; projectId?: string; environmentId?: string; permissions: Permission[]; scopes: Scope[]; metadata: Record; } ``` 不同 Runtime 可以扩展： ```ts ActionContext TaskContext AgentContext PluginContext ProviderContext ``` 但不要重新定义完全不同的身份/权限模型。 --- # 62. Action Contract 建议： ```ts interface ActionDefinition { id: string; version: string; input: Schema; output: Schema; permissions: string[]; riskLevel: RiskLevel; mode: 'sync' | 'async' | 'stream'; idempotency?: IdempotencyPolicy; approval?: ApprovalPolicy; handler(ctx: ActionContext, input: I): Promise; } ``` --- # 63. Resource Contract 建议： ```ts interface ResourceDefinition { id: string; version: string; schema: ResourceSchema; permissions: ResourcePermissions; scope: ScopeDefinition; relations?: RelationDefinition[]; search?: SearchDefinition; ui?: ResourceUI; } ``` --- # 64. Event Contract ```ts interface EventDefinition { type: string; version: string; schema: Schema; visibility: EventVisibility; retention?: RetentionPolicy; } ``` Event 必须具有： ```text eventId eventType eventVersion occurredAt actor scope correlationId causationId executionId payload ``` --- # 65. Plugin Contract ```ts interface DevOSPlugin { manifest: PluginManifest; setup(ctx: PluginContext): Promise; } ``` PluginContext 通过 SDK 暴露： ```text actions resources queries events tasks storage search config secrets providers capabilities ui logger ``` 但不是： ```text prisma redis filesystem root shell docker socket master key ``` --- # 66. Agent Contract Agent 不直接依赖具体业务。 ```ts interface Agent { run(goal: AgentGoal): Promise; } ``` Agent Runtime 负责： ```text Context Planning Capability Discovery Execution Observation Evaluation Retry Replan Budget Approval Memory ``` --- # 67. Skill Contract ```ts interface Skill { id: string; version: string; description: string; requiredCapabilities: string[]; instructions: SkillInstructions; } ``` Skill 不应该： ```text 直接操作数据库 直接调用外部 API 直接写文件 直接发送邮件 ``` --- # 68. Project Contract ```ts interface ProjectManifest { name: string; type: ProjectType; capabilities: string[]; modules?: string[]; plugins?: string[]; deployment?: DeploymentProfile; } ``` Project Factory 根据它生成项目。 --- # 69. Deployment Runtime Deployment 也必须 Runtime 化： ```text Project ↓ Deployment Plan ↓ Deployment Task ↓ Job ↓ Provider ↓ Execution ↓ Event ``` 未来可以支持： ```text Docker VM Cloud VM Kubernetes Serverless Bare Metal ``` 但业务不应该直接依赖 Kubernetes SDK。 --- # 70. Deployment Profile 例如： ```yaml deployment: profile: docker ``` 或者： ```yaml deployment: profile: cloud-vm ``` Project Factory 负责： ```text Project ↓ Deployment Profile ↓ Infrastructure Provider ``` --- # 71. DevOS Doctor 最终必须提供： ```bash devos doctor ``` 检查： ```text Database Redis Storage Config Secrets Providers Plugins Migrations Queues Workers Events Search Model Providers Security Environment Version Compatibility ``` 输出： ```text PASS WARN FAIL ``` 并提供： ```text diagnostic code suggested remediation ``` --- # 72. DevOS Health Model 至少： ```text Liveness Readiness Dependency Health Provider Health Plugin Health Worker Health Queue Health Storage Health Database Health ``` 最终： ```text /devos/health /devos/ready ``` 内部 UI： ```text System → Health ``` --- # 73. DevOS Admin UI 最终 UI 应围绕 Runtime，而不是传统后台菜单。 核心： ```text Home Projects Tasks Agents Resources Plugins Search Notifications Settings System ``` System： ```text Health Observability Audit Events Migrations Versions Providers Security ``` --- # 74. Agent UI Agent UI 应显示： ```text Goal Status Plan Summary Current Step Actions Tasks Observations Artifacts Approvals Errors Final Result ``` 不要显示： ```text Hidden Chain of Thought ``` 只展示： ```text Decision Summary Action Reason Summary Result ``` --- # 75. Task UI Task 页面： ```text Task ├── Overview ├── Jobs ├── Executions ├── Logs ├── Events ├── Artifacts └── Timeline ``` 用户应该能够回答： > “这个任务现在做到哪里了？” --- # 76. Plugin UI Plugin 页面： ```text Plugin ├── Overview ├── Capabilities ├── Settings ├── Credentials ├── Health ├── Tasks ├── Logs ├── Events └── About ``` Plugin 可以注册自己的页面，但由 DevOS UI Shell 承载。 --- # 77. Global Search Global Search 最终应该能够搜索： ```text Resources Tasks Projects Plugins Agents Artifacts Events Documents Knowledge ``` 但搜索结果必须经过： ```text Security Scope Field Permission ``` 不能通过搜索泄露用户无权访问的数据。 --- # 78. Command Palette 统一命令： ```text Create Project Create Task Run Action Install Plugin Run Agent Search Open Resource Open Settings ``` 命令最终仍然进入： ```text Action Runtime ``` --- # 79. Plugin Marketplace Marketplace 是分发层。 插件状态： ```text Official Verified Community Private Unverified ``` 插件发布包含： ```text Manifest Version Checksum Signature Permissions Dependencies Screenshots Documentation Changelog Certification ``` --- # 80. Plugin Certification 至少： ```text Basic Runtime Safe Secure Marketplace Verified Official ``` Certification 检查： ```text Manifest API Compatibility Permission Security Runtime Boundary Migration Tests UI Performance Observability ``` --- # 81. Plugin Sandbox 最终支持： ```text Trusted In-Process Restricted Isolated Container ``` 初期： ```text Official Plugin → Trusted ``` 社区插件： ```text Restricted / Isolated ``` 具体隔离程度由风险决定。 --- # 82. Security Defaults DevOS 默认安全策略： ```text DENY PRIVATE SCOPED AUDITED SHORT-LIVED LEAST-PRIVILEGE ``` 即： > 默认拒绝、默认私有、默认有 Scope、默认审计、默认短生命周期、默认最小权限。 --- # 83. Zcode 禁止事项 Zcode 在开发 DevOS 时禁止： ### 禁止 1 新增第二套 Runtime。 ### 禁止 2 UI 直接访问数据库。 ### 禁止 3 Agent 直接访问数据库。 ### 禁止 4 Plugin 直接访问数据库。 ### 禁止 5 MCP 绕过 Action Runtime。 ### 禁止 6 Skill 自己实现执行系统。 ### 禁止 7 业务模块自己实现 Queue。 ### 禁止 8 业务模块自己实现 EventBus。 ### 禁止 9 业务模块自己实现 Secret Manager。 ### 禁止 10 业务代码直接使用 `process.env`。 ### 禁止 11 生产环境使用 `latest` Plugin。 ### 禁止 12 持久化 Hidden Chain-of-Thought。 ### 禁止 13 自动保存全部 Conversation 为 Memory。 ### 禁止 14 把 Memory 当业务数据库。 ### 禁止 15 把 Plugin 做成独立 DevOS。 --- # 84. Zcode 架构决策优先级 如果代码、旧文档、临时需求产生冲突： ```text 1. Security 2. This Final Architecture Spec 3. Runtime Contract 4. 01–34 Architecture Documents 5. Existing Tests 6. Existing Implementation 7. Local Convenience ``` 但是： > 如果当前实现已经与架构严重冲突，不允许盲目大规模重写。 必须： ```text Audit ↓ Plan ↓ Migration ↓ Vertical Slice ↓ Test ↓ Commit ``` --- # 85. Zcode 实现原则 Zcode 每次修改必须回答： ```text 1. 这个功能属于哪个 Runtime？ 2. 是否已经存在对应 Runtime？ 3. 是否存在重复实现？ 4. Resource 是什么？ 5. Action 是什么？ 6. Query 是什么？ 7. Permission 是什么？ 8. Scope 是什么？ 9. Sync 还是 Async？ 10. 是否需要 Task？ 11. 是否产生 Event？ 12. 是否需要 Audit？ 13. 是否需要 Observability？ 14. 是否涉及 Secret？ 15. 是否涉及 Storage？ 16. 是否需要 Plugin？ 17. 是否需要 Skill？ 18. 是否需要 Agent？ 19. 是否需要 Migration？ 20. 如何测试？ ``` --- # 86. Vertical Slice 不要一次重构整个 DevOS。 应该： ```text 一个 Resource + 一个 Action + 一个 Query + 一个 UI + 一个 Task + 一个 Event + 一个 Audit + 一个 E2E ``` 先打通完整链路。 例如： ```text core.project.create ``` 完整实现： ```text UI ↓ API ↓ Security ↓ Action ↓ Action Runtime ↓ Execution ↓ Data ↓ Event ↓ Realtime ↓ Audit ``` 然后复制这一模式。 --- # 87. Definition of Done 任何 Runtime 功能只有满足以下条件才能认为完成： ```text [ ] Architecture boundary correct [ ] Type definitions [ ] Runtime implementation [ ] Authorization [ ] Scope [ ] Validation [ ] Error contract [ ] Audit [ ] Logging [ ] Metrics [ ] Tracing [ ] Unit tests [ ] Integration tests [ ] Contract tests [ ] E2E where appropriate [ ] Migration [ ] Documentation [ ] UI where required [ ] API/OpenAPI where required [ ] SDK where required [ ] Plugin boundary tested [ ] Agent/MCP boundary tested ``` --- # 88. Architecture Tests 必须自动阻止： ```text UI → Prisma Agent → Prisma Plugin → Prisma MCP → Prisma UI → Redis Agent → Redis Plugin → Redis Plugin → Master Secret Agent → Master Secret Business → process.env Business → private queue Business → private event bus ``` 推荐使用： ```text ESLint dependency-cruiser madge custom architecture tests TypeScript project references ``` --- # 89. Golden Contract 所有入口： ```text UI API SDK CLI Webhook Plugin MCP Skill Agent Workflow Scheduler ``` 最终都必须进入： ```text Security Context ↓ Capability ↓ Action / Query / Task ↓ DevOS Runtime ``` --- # 90. 最终业务架构 未来任何业务都应该： ```text Business Module │ ├── Resource ├── Action ├── Query ├── Event ├── Skill ├── UI └── Plugin │ ▼ DevOS Runtime ``` 而不是： ```text Business Module ├── Controller ├── Service ├── Repository ├── Queue ├── EventBus ├── Mailer ├── SecretManager ├── Agent └── MCP ``` 后者会重新制造一个巨型单体。 --- # 91. 最终 DevOS 数据流 ## 普通请求 ```text User ↓ UI/API/CLI ↓ Security ↓ Action ↓ Action Runtime ↓ Execution ↓ Data ↓ Event ↓ Audit / Realtime / Notification ``` --- # 92. Agent 请求 ```text User ↓ Goal ↓ Agent ↓ Context ↓ Memory / Knowledge ↓ Skill ↓ Capability ↓ Action ↓ Action Runtime ↓ Execution ↓ Task / Job ↓ Worker ↓ Event ↓ Observation ↓ Agent ``` --- # 93. Plugin 请求 ```text Plugin ↓ Plugin SDK ↓ Plugin Context ↓ Capability ↓ Action Runtime ↓ Execution ↓ Event ``` --- # 94. MCP 请求 ```text MCP Client ↓ MCP Gateway ↓ Authentication ↓ Authorization ↓ Capability ↓ Action Runtime ↓ Execution ``` --- # 95. Workflow ```text Trigger ↓ Workflow ↓ Action ↓ Task ↓ Job ↓ Worker ↓ Execution ↓ Event ↓ Next Step ``` --- # 96. Notification ```text Event ↓ Notification Rule ↓ Recipient ↓ Template ↓ Message ↓ Communication Runtime ↓ Provider ↓ Delivery ``` --- # 97. File ```text Action ↓ Storage Runtime ↓ File ↓ Artifact ↓ Object Storage ``` --- # 98. Search ```text Resource ↓ Data ↓ Index ↓ Search Runtime ↓ Security Filter ↓ Query Result ``` --- # 99. Memory ```text Agent ↓ Memory Policy ↓ Memory Candidate ↓ Security / Privacy ↓ Memory Runtime ↓ PostgreSQL ↓ pgvector ``` --- # 100. Project Factory ```text Natural Language Requirement ↓ Capability Resolver ↓ Dependency Resolver ↓ Project Manifest ↓ Generator ↓ Template ↓ Project ↓ DevOS Runtime ``` --- # 101. DevOS 最终产品形态 DevOS 最终不是一个单独 App。 它应该形成： ```text DEVOS PLATFORM │ ┌──────────────┼──────────────┐ │ │ │ Runtime Capability Factory │ │ │ │ Plugin/Skill │ │ MCP/Provider │ │ │ └──────────────┬──────────────┘ │ Applications │ ┌────────────┼────────────┐ │ │ │ SEO CRM DevOps │ │ │ Content Sales Servers ``` --- # 102. DevOS 的真正竞争力 不是： ```text 页面数量 代码行数 CRUD 数量 ``` 而是： ```text Capability Reuse Runtime Reuse Agent Automation Plugin Ecosystem Project Generation Traceability Security Upgradeability Developer Velocity ``` 最重要的指标： ### 1. 新业务需要新增多少代码？ 越少越好。 ### 2. 新业务可以复用多少 Runtime？ 越多越好。 ### 3. 新插件开发需要多少时间？ 越短越好。 ### 4. Agent 能够调用多少能力？ 越多越好，但必须受权限控制。 ### 5. 一个 Execution 能追溯到多少上下文？ 越完整越好。 ### 6. 一个 DevOS Runtime 升级会影响多少业务？ 越少越好。 --- # 103. 最终开发顺序 如果当前项目尚未完成全部架构，最终实施顺序保持： ```text Foundation ↓ Identity ↓ Security ↓ Data ↓ Config ↓ Task ↓ Event ↓ Storage ↓ Search ↓ UI Shell ↓ Plugin ↓ MCP ↓ Skill ↓ Model ↓ Agent ↓ Memory / Context ↓ Workflow ↓ Notification ↓ Observability ↓ Migration / Versioning ↓ Project Factory ↓ Modules ↓ Business Applications ``` --- # 104. 不允许的开发顺序 不要： ```text SEO UI ↓ SEO API ↓ SEO Service ↓ SEO Queue ↓ SEO Agent ↓ SEO MCP ↓ SEO Plugin ``` 这样会产生： > 一个 SEO 专用 DevOS。 正确： ```text DevOS Runtime ↓ Plugin / Module ↓ SEO ``` --- # 105. 最终架构闭环 DevOS 最终形成： ```text USER │ ▼ GOAL │ ▼ AGENT │ ┌───────┴───────┐ ▼ ▼ CONTEXT SKILL │ │ └───────┬───────┘ ▼ CAPABILITY │ ▼ ACTION │ ▼ SECURITY RUNTIME │ ▼ ACTION RUNTIME │ ▼ EXECUTION │ ┌──────────┼──────────┐ ▼ ▼ ▼ TASK EVENT DATA │ │ │ ▼ ▼ ▼ JOB NOTIFICATION SEARCH │ │ ▼ ▼ WORKER COMMUNICATION │ │ └─────┬────┘ ▼ RESULT │ ▼ ARTIFACT │ ▼ OBSERVATION │ ▼ AGENT │ ┌─────┴─────┐ ▼ ▼ CONTINUE REPLAN │ │ └─────┬─────┘ ▼ GOAL ``` --- # 106. DevOS 最终四层模型 如果未来所有复杂架构都必须压缩成四层，只保留： ```text Layer 1 — Foundation Security Identity Data Config Storage Provider Layer 2 — Runtime Resource Action Query Execution Task Event Layer 3 — Intelligence Capability Skill MCP Model Agent Memory Context Workflow Layer 4 — Product Plugin Module UI Project Application Project Factory ``` --- # 107. 最终三条铁律 ## 铁律一 > **所有执行必须进入 Action Runtime。** --- ## 铁律二 > **所有扩展必须使用 DevOS Runtime，而不是创建第二套 Runtime。** --- ## 铁律三 > **Agent、Plugin、MCP、UI、API、CLI 都只是不同入口，不是不同业务执行系统。** --- # 108. DevOS Architecture Mantra 整个项目只需要记住： ```text Resource = What exists Query = What can be read Action = What can be done Execution = What actually happened Task = What work is required Job = What worker executes Event = What happened Capability = What can be used Skill = How to solve Agent = How to decide Plugin = How to extend MCP = How to expose/access Provider = How to connect Context = What Agent needs now Memory = What may persist Knowledge = Source of truth Artifact = Durable output Project = Product composition Factory = How products are generated ``` --- # 109. DevOS 最终黄金链 整个 DevOS 可以最终压缩成： ```text USER ↓ GOAL ↓ AGENT ↓ CONTEXT / MEMORY ↓ SKILL ↓ CAPABILITY ↓ ACTION ↓ SECURITY ↓ ACTION RUNTIME ↓ EXECUTION ↓ TASK / JOB / WORKER + EVENT / BUS ↓ RESULT / ARTIFACT ↓ OBSERVABILITY / AUDIT ↓ AGENT OBSERVATION ↓ CONTINUE / REPLAN / FINISH ``` --- # 110. DevOS 平台黄金链 而从平台角度： ```text RESOURCE ↓ ACTION ↓ RUNTIME ↓ PLUGIN ↓ CAPABILITY ↓ AGENT ↓ PROJECT ↓ APPLICATION ``` --- # 111. 最终 Zcode Master Rule 将以下内容视为 Zcode 开发 `/home/dev/bun/devos` 时的最高级工程规则之一： ```text DEVOS IS A RUNTIME PLATFORM, NOT A BUSINESS APPLICATION. Never create a second Runtime when an existing DevOS Runtime can be reused. Every business operation must have: Resource / Action / Query / Permission / Scope / Execution. Every external entry point must converge into the same Runtime: UI API SDK CLI Webhook Plugin MCP Skill Agent Workflow Scheduler must NOT implement independent business execution. They must converge to: Security Context → Capability → Action / Query / Task → DevOS Runtime → Execution → Event / Task / Artifact / Audit / Observability. Agents do not bypass authorization. Plugins do not bypass Runtime. MCP does not bypass Runtime. Skills do not execute infrastructure directly. UI does not contain business logic. Business modules do not own infrastructure. Secrets never enter logs, events, prompts, memory, or source code. Memory never becomes the source of truth for business data. Knowledge remains source-of-truth data. Production versions must be pinned. All important executions must be traceable. Prefer existing mature infrastructure over custom infrastructure. Prefer abstraction before infrastructure replacement. Prefer vertical slices over giant rewrites. Prefer reuse over duplication. Prefer capability composition over business-specific frameworks. Build the platform first. Build reusable capabilities second. Build products third. ``` --- # 112. 最终结论 DevOS 的最终目标不是： > “把所有功能都做进一个系统。” 而是： > **让未来的新系统尽可能不需要重新建设基础设施。** 理想状态： 开发一个新的业务： ```text 新需求 ↓ 选择 Resource ↓ 选择 Capability ↓ 选择 Plugin ↓ 选择 Skill ↓ 配置 Project Manifest ↓ Project Factory ↓ 生成项目 ``` 而不是重新开发： ```text Auth RBAC Database Queue Worker EventBus Storage Search Notification AI Agent MCP Plugin UI Shell Observability Audit Migration ``` 这才是 DevOS 的真正价值。 最终： ```text ┌──────────────────────┐ │ DevOS │ │ │ │ Runtime Platform │ │ Capability System │ │ Agent Platform │ │ Plugin Platform │ │ Project Factory │ └──────────┬───────────┘ │ ┌──────────────┼──────────────┐ │ │ │ SEO CRM DevOps │ │ │ Content Sales Infra │ │ │ └──────────────┼──────────────┘ │ Future Apps ``` **DevOS 最终不是“一个应用”。** **DevOS 是生产应用的基础平台。** --- # 113. FINAL GOLDEN RULE > **DevOS = Resource + Action + Event + Capability + Runtime + Agent + Plugin + Project Factory** 并且： > **Plugin 提供能力，Skill 提供方法，Agent 负责决策，Action 负责执行，Runtime 负责治理，Event 负责连接，Project Factory 负责生产应用。** 最终所有东西都必须回到： ```text GOAL ↓ CAPABILITY ↓ ACTION ↓ RUNTIME ↓ EXECUTION ↓ RESULT ``` **这就是 DevOS 的最终架构。** # END OF FINAL ARCHITECTURE SPECIFICATION