# 23 — Zcode Implementation Protocol > **文件名：`23_ZCODE_IMPLEMENTATION_PROTOCOL.md`** > > 本文是 DevOS 项目对 Zcode / AI Coding Agent 的**强制实施协议**。 > > 前 01–22 文档定义“DevOS 是什么、应该具备什么能力”。 > > 本文定义： > > **Zcode 应该如何读取这些规范、如何审计现有代码、如何实施、如何测试、如何控制变更范围，以及什么情况下绝对不能自行修改架构。** --- # 1. Document Status ```yaml document: id: 23 name: ZCODE_IMPLEMENTATION_PROTOCOL status: mandatory applies_to: - Zcode - AI Coding Agent - Human-assisted AI coding - Automated implementation workflows project: name: DevOS root: /home/dev/bun/devos priority: architecture_docs: highest this_protocol: implementation_policy existing_code: subject_to_migration ``` 本文不是建议。 本文属于： > **Implementation Contract** 如果 Zcode 与本文冲突，Zcode 不得自行选择。 必须停止并报告冲突。 --- # 2. Core Objective Zcode 的目标不是： > “把当前项目改得更漂亮。” 也不是： > “尽可能多写代码。” 更不是： > “把现有功能全部保留下来。” 真正目标： ```text 将现有 DevOS ↓ 逐步迁移 ↓ 成为 01–22 定义的 DevOS Platform ``` 最终形成： ```text DevOS Core Runtime ↓ Resource ↓ Action ↓ Execution ↓ Task / Job / Event ↓ Capability ↓ Plugin / MCP / Skill / Agent ↓ UI ↓ Project Factory ↓ Business Applications ``` --- # 3. Zcode 的第一原则 ## 3.1 不允许直接开始编码 任何非 trivial 任务，第一步必须： ```text READ ↓ AUDIT ↓ CLASSIFY ↓ PLAN ↓ IMPLEMENT ↓ TEST ↓ VERIFY ↓ REPORT ``` 而不是： ```text READ ↓ CODE ↓ CODE ↓ CODE ↓ 发现架构不对 ↓ 大规模重构 ↓ 项目失控 ``` --- # 4. Architecture Documents Are the Source of Truth Zcode 必须首先读取 DevOS Architecture Documents。 推荐： ```text 01_*.md 02_*.md ... 23_ZCODE_IMPLEMENTATION_PROTOCOL.md ``` 读取顺序： ```text Foundation ↓ Runtime ↓ Resource / Action ↓ Identity ↓ Data ↓ Config ↓ Task ↓ Event ↓ Storage ↓ Search ↓ UI ↓ Plugin ↓ MCP ↓ Skill ↓ Agent ↓ Workflow ↓ Notification ↓ Observability ↓ Versioning ↓ Project Factory ↓ Implementation Protocol ``` --- # 5. Document Priority 当不同文档之间出现冲突时，Zcode 必须按照以下优先级处理： ```text 1. Explicit user requirement 2. Latest architecture decision explicitly approved by user 3. This implementation protocol 4. Latest architecture document 5. Earlier architecture document 6. Existing code 7. Zcode's own assumptions ``` 尤其重要： > **Existing code 永远不是架构真相。** 旧代码只是： ```text Legacy Implementation ``` 不能因为： ```text 现在代码是这样 ``` 就反推： ```text DevOS 应该就是这样 ``` --- # 6. Architecture Conflict Protocol 如果 Zcode 发现： ```text Document A: Action Runtime Existing Code: Controller → Service → Database ``` 不得自行判断： > “Service 其实也可以。” 必须按照： ```text Architecture Requirement ↓ Identify Legacy ↓ Plan Migration ↓ Implement Adapter / Refactor ↓ Remove Legacy Path ``` --- # 7. Absolute Architecture Rule 如果出现以下情况： ```text 现有代码与新架构冲突 ``` 默认选择： ```text 新架构 ``` 但不能立即删除旧代码。 必须： ```text Classify ↓ Migrate ↓ Verify ↓ Delete ``` --- # 8. Existing Code Classification Zcode 在每个模块改造前必须将现有代码分类为四种： ```text REUSE REFACTOR REPLACE DELETE ``` --- ## 8.1 REUSE 满足： ```text 接口正确 职责正确 依赖方向正确 安全模型正确 测试可复用 ``` 则： ```text REUSE ``` --- ## 8.2 REFACTOR 功能有价值，但架构不符合要求： ```text REFACTOR ``` 例如： ```text 旧： Controller ↓ Service ↓ DB 新： Controller ↓ Action Runtime ↓ Action ↓ Data Runtime ↓ DB ``` --- ## 8.3 REPLACE 旧实现无法合理迁移： ```text REPLACE ``` 例如： ```text 旧 Queue 旧 EventBus 旧 Plugin Runtime 旧 Agent Runtime ``` 如果与统一 Runtime 冲突，应替换。 --- ## 8.4 DELETE 满足以下条件之一： ```text 重复 Runtime 无调用 死代码 过时 API 安全风险 架构冲突且无法兼容 重复业务实现 ``` 才能： ```text DELETE ``` --- # 9. Mandatory Audit Before Coding 每个大模块开始之前，Zcode 必须产生： ```text MODULE_AUDIT.md ``` 至少包含： ```yaml module: current_files: current_entrypoints: current_dependencies: current_database_tables: current_api: current_ui: current_runtime: current_tests: reuse: refactor: replace: delete: architecture_gaps: security_gaps: test_gaps: migration_risk: target_architecture: implementation_steps: ``` --- # 10. Audit Is Not Optional 禁止： ```text “我大概看过项目了。” ``` 必须能够回答： ```text 当前入口在哪里？ 谁调用它？ 数据从哪里来？ 谁执行副作用？ 有没有绕过 Runtime？ 有没有重复 Runtime？ 有没有旧 API？ 有没有测试？ 有没有数据库依赖？ 有没有 Plugin / MCP / Agent 依赖？ 有没有 UI 直接调用基础设施？ ``` --- # 11. No Autonomous Architecture Changes Zcode 不允许因为实现困难而自行改变核心架构。 禁止： ```text “Action Runtime 太复杂，所以直接 Service。” “Queue 不方便，所以 Worker 直接执行。” “Agent 调数据库更快。” “MCP 自己执行一套逻辑。” “Plugin 自己维护 EventBus。” “UI 自己做权限。” “Secret 直接放 config。” ``` 这些都属于： > Architecture Violation --- # 12. Architecture Change Request 如果确实需要改变架构，必须创建： ```text docs/architecture/ADR-XXXX-*.md ``` 格式： ```md # ADR-XXXX ## Problem ## Current Architecture ## Proposed Change ## Why Existing Architecture Is Insufficient ## Alternatives ## Impact ## Migration Plan ## Rollback Plan ## Security Impact ## Performance Impact ## Compatibility Impact ## Decision ``` 然后： ```text STOP ``` 等待架构决策。 --- # 13. Do Not Continue After Architecture Block 如果某个任务依赖未经批准的架构变化： ```text STOP IMPLEMENTATION ``` 不得： ```text 先偷偷实现 之后再说 ``` --- # 14. Task Decomposition Zcode 必须将大任务拆成： ```text P0 P1 P2 ``` --- ## P0 阻塞系统运行或架构正确性的内容： ```text Core Runtime Action Runtime Resource Registry Permission Identity Data Runtime Task Runtime Event Runtime ``` --- ## P1 平台核心能力： ```text Storage Search UI Shell Plugin MCP Skill Agent Workflow Notification Observability Versioning ``` --- ## P2 扩展能力： ```text Project Factory Official Modules SEO DevOps CRM Content Business Applications ``` --- # 15. Never Implement the Whole Roadmap at Once 禁止： ```text “现在一次把 Plugin + MCP + Agent + UI + SEO 全部完成。” ``` 正确方式： ```text Core Runtime ↓ Vertical Slice ↓ Tests ↓ Next Runtime ↓ Vertical Slice ↓ Tests ``` --- # 16. Vertical Slice Rule 每个阶段至少完成一个真正可运行的 Vertical Slice。 例如： ```text User ↓ Permission ↓ Resource ↓ Action ↓ Action Runtime ↓ Execution ↓ Audit ↓ UI ``` 而不是： ```text 只写 100 个 interface ``` --- # 17. First Golden Vertical Slice DevOS 第一条完整 Vertical Slice 应为： ```text User ↓ Session ↓ Permission ↓ Resource ↓ Action ↓ Action Runtime ↓ Execution ↓ Audit ↓ Event ↓ Task ↓ UI ``` 建议使用： ```text core.user ``` 实现： ```text core.user.create core.user.get core.user.update core.user.delete ``` --- # 18. Runtime Before UI 如果一个功能还没有 Runtime： ```text 禁止先写复杂 UI。 ``` 错误： ```text UI ↓ fetch("/api/xxx") ↓ Controller ↓ DB ``` 正确： ```text UI ↓ Action Client ↓ Action Runtime ↓ Action ↓ Data Runtime ↓ DB ``` --- # 19. Unified Action Runtime 所有副作用必须最终经过： ```ts ActionRuntime.execute(...) ``` 包括： ```text REST GraphQL CLI UI MCP Plugin Skill Agent Workflow Scheduler Webhook System Job ``` --- # 20. No Duplicate Runtime Zcode 必须主动搜索重复实现。 重点搜索： ```text *Service *Manager *Executor *Runner *Engine *Runtime *Worker *Queue *Bus *Scheduler *Agent *PluginManager *MCP* ``` 但不是所有这些名字都必须删除。 必须检查： > 是否存在两个承担同一职责的 Runtime？ 例如： ```text packages/action-runtime/ src/services/action-executor/ src/core/executor/ ``` 如果三者实际上都执行 Action： ```text Architecture Violation ``` --- # 21. Runtime Ownership 每种职责只能有一个正式 Runtime。 | Capability | Owner | |---|---| | Action Execution | Action Runtime | | Data Access | Data Runtime | | Async Work | Task Runtime | | Queue | Queue Runtime | | Events | Event Runtime | | Files | Storage Runtime | | Search | Search Runtime | | Config | Configuration Runtime | | Secrets | Secret Runtime | | Agents | Agent Runtime | | MCP | MCP Runtime | | Plugins | Plugin Runtime | | Notifications | Notification Runtime | | Observability | Observability Runtime | --- # 22. UI Boundary UI 禁止： ```ts db.query() redis.get() queue.add() fs.readFile() secret.get() worker.execute() ``` UI 只能： ```text Query Action Task Search Realtime Agent ``` --- # 23. Agent Boundary Agent 禁止： ```ts db.query() redis.get() queue.add() fs.readFile() process.env.SECRET ``` Agent 只能： ```text Goal ↓ Capability Discovery ↓ Skill ↓ Plan ↓ Action / Task ``` --- # 24. Plugin Boundary Plugin 可以定义： ```text Resource Action Skill MCP Workflow UI Config Provider ``` Plugin 不可以创建： ```text 自己的 Auth 自己的 RBAC 自己的 Action Runtime 自己的 Queue 自己的 EventBus 自己的 Secret Store 自己的 Notification Runtime 自己的 Task Runtime 自己的 Router ``` --- # 25. MCP Boundary MCP 是： ```text Capability Access / Transport ``` 不是： ```text Second Business Runtime ``` 正确： ```text MCP ↓ Capability ↓ Action Runtime ``` 禁止： ```text MCP ↓ Direct DB ``` 或者： ```text MCP ↓ Private Service ↓ Private Permission ``` --- # 26. Skill Boundary Skill 描述： ```text 怎么解决问题 ``` 而不是： ```text 直接执行数据库操作 ``` Skill 可以定义： ```text requiredCapabilities instructions examples workflow guidance ``` 不能直接： ```text SQL Redis Filesystem Secret ``` --- # 27. Agent Must Not Persist Chain-of-Thought 禁止保存： ```text hidden reasoning chain of thought private internal reasoning ``` 可以保存： ```text decision summary plan action action input summary action result summary observation error reason code ``` 例如： ```json { "decisionSummary": "选择使用网站扫描能力检查技术 SEO", "capability": "seo.website.scan", "result": "发现 12 个高优先级问题" } ``` --- # 28. Database Access Rule Business code 不得随意： ```ts prisma.user.findMany() ``` 必须： ```text Data Runtime ↓ Repository / Query ``` 写操作： ```text Action ↓ Action Runtime ↓ Data Runtime ``` --- # 29. Redis Rule Redis 只能由对应 Runtime 使用。 例如： ```text Queue Runtime Cache Runtime Realtime Runtime Lock Runtime ``` 业务 Plugin 不得： ```ts redis.set(...) ``` 然后自行实现状态机。 --- # 30. Secret Rule 禁止： ```ts process.env.OPENAI_API_KEY ``` 出现在业务代码中。 必须： ```text Configuration Runtime ↓ Provider Runtime ↓ Credential Runtime ↓ Secret Runtime ``` --- # 31. Storage Rule 禁止： ```ts fs.writeFile(...) ``` 作为业务文件存储机制。 必须： ```text Storage Runtime ↓ Storage Provider ``` Agent 工作文件同样如此。 --- # 32. Queue Rule 禁止： ```text Plugin → Redis → 自己消费 ``` 必须： ```text Task ↓ Job ↓ Queue ↓ Worker ↓ Action Runtime ``` --- # 33. Event Rule 禁止： ```text Plugin A ↓ 自己的 EventEmitter Plugin B ↓ 自己的 WebSocket Plugin C ↓ 自己的 PubSub ``` 必须： ```text Action ↓ Execution ↓ Event Runtime ``` --- # 34. API Rule Controller 只能负责： ```text HTTP parsing validation authentication context response mapping ``` 不能承担： ```text business logic transaction logic queue logic agent logic database workflow ``` --- # 35. Service Rule `Service` 不是架构层。 如果存在： ```text UserService SeoService AgentService PluginService ``` 必须明确它属于： ```text Application Service Domain Service Runtime Adapter Repository Policy ``` 否则容易重新形成： ```text God Service ``` --- # 36. Package Dependency Direction 推荐： ```text apps ↓ modules ↓ runtime ↓ contracts ``` 禁止： ```text core ↓ business module ``` 禁止： ```text runtime ↓ SEO ``` 禁止： ```text Action Runtime ↓ Plugin UI ``` --- # 37. Recommended Package Structure Zcode 应逐步形成： ```text packages/ ├── contracts/ ├── core/ ├── identity/ ├── permission/ ├── resource/ ├── action/ ├── execution/ ├── data/ ├── config/ ├── secret/ ├── credential/ ├── provider/ ├── environment/ ├── task/ ├── job/ ├── queue/ ├── worker/ ├── scheduler/ ├── event/ ├── notification/ ├── storage/ ├── artifact/ ├── search/ ├── plugin/ ├── mcp/ ├── capability/ ├── skill/ ├── agent/ ├── workflow/ ├── observability/ ├── audit/ ├── migration/ ├── project/ └── sdk/ ``` 前端： ```text packages/ ├── api-client/ ├── ui/ ├── frontend-runtime/ ├── ui-shell/ ├── ui-router/ ├── ui-navigation/ ├── ui-resource/ ├── ui-action/ ├── ui-task/ ├── ui-agent/ ├── ui-plugin/ ├── ui-settings/ ├── ui-search/ ├── ui-command/ ├── ui-notification/ └── ui-realtime/ ``` --- # 38. Code Ownership 每个 Runtime 必须有明确 Owner。 例如： ```text packages/action/ README.md package.json src/ tests/ ``` 其中： ```text README.md ``` 必须说明： ```text Responsibility Public API Dependencies Forbidden Dependencies Integration Tests ``` --- # 39. Forbidden Dependencies 例如： ```text packages/action-runtime ``` 不得依赖： ```text seo crm content business modules plugin UI agent profile ``` 可以依赖： ```text contracts resource permission execution observability audit ``` --- # 40. Code Generation Boundary Zcode 生成代码时必须区分： ```text GENERATED HANDWRITTEN MIGRATED ``` 推荐： ```text src/generated/ src/core/ src/modules/ src/business/ ``` 禁止把所有代码都标记成： ```text generated ``` 否则后续无法安全升级。 --- # 41. Generated Code Rule 如果文件明确： ```text AUTO-GENERATED ``` Zcode 不应该手工修改。 应该修改： ```text generator template schema manifest ``` 然后重新生成。 --- # 42. Business Code Boundary 推荐： ```text packages/business/ modules/ apps/ ``` 业务代码不得进入： ```text packages/core/ packages/action/ packages/task/ packages/event/ ``` 例如： ```text seo.website ``` 应该属于： ```text modules/seo/ ``` 而不是： ```text packages/core/src/seo/ ``` --- # 43. Migration Protocol 任何数据库结构变化必须： ```text Migration ``` 禁止： ```text 启动时自动 ALTER TABLE ``` 禁止： ```text 代码发现字段不存在就自动创建 ``` --- # 44. Database Migration Rules 使用： ```text Prisma Migration + DevOS Migration Registry ``` 而不是重新发明 Migration Engine。 每个 Migration： ```text version namespace checksum status ``` --- # 45. Expand / Contract 生产环境数据库变更优先： ```text Expand ↓ Deploy ↓ Migrate Data ↓ Switch Read/Write ↓ Contract ``` 不要： ```text 删除字段 ↓ 马上部署新代码 ``` --- # 46. Destructive Migration 以下操作必须特别标记： ```text DROP TABLE DROP COLUMN 数据覆盖 数据删除 不可逆转换 ``` 要求： ```text backup impact analysis rollback strategy approval ``` --- # 47. Runtime Contract Tests 每个 Runtime 必须拥有 Contract Test。 例如： ```text Action Runtime Contract Task Runtime Contract Event Runtime Contract Storage Runtime Contract Search Runtime Contract Plugin Runtime Contract Agent Runtime Contract ``` --- # 48. Action Runtime Contract 至少测试： ```text registration discovery permission scope validation execution sync async error timeout cancellation idempotency audit event observability ``` --- # 49. Task Runtime Contract 至少测试： ```text Task creation Job creation Queue Worker Lease Heartbeat Retry Cancellation Progress Dependency Batch Dead Letter Recovery ``` --- # 50. Plugin Contract Plugin 必须测试： ```text install manifest validation dependency resolution registration resource registration action registration capability registration UI registration config registration enable disable upgrade migration health check uninstall ``` --- # 51. MCP Contract 必须测试： ```text connect authenticate capability discovery schema permission filtering scope filtering action execution timeout error mapping audit disconnect ``` --- # 52. Agent Contract 必须测试： ```text goal context capability discovery permission planning action execution task creation observation replan retry budget approval completion failure ``` --- # 53. Integration Tests Runtime Contract Test 不够。 还必须有： ```text Integration Tests ``` 例如： ```text User ↓ Action ↓ Task ↓ Job ↓ Worker ↓ Execution ↓ Event ↓ Notification ``` --- # 54. E2E Tests 核心 Vertical Slice 必须有 E2E。 至少： ```text Login ↓ Create Resource ↓ Execute Action ↓ Observe Task ↓ Receive Event ↓ View Audit ``` --- # 55. CI Required Checks 推荐 CI： ```text 1. Typecheck 2. Lint 3. Unit Test 4. Runtime Contract Test 5. Integration Test 6. Migration Check 7. Architecture Dependency Check 8. Security Check 9. Build 10. E2E ``` --- # 56. Architecture Lint 建议建立： ```text scripts/check-architecture.ts ``` 检查： ```text business → core UI → DB Agent → DB Plugin → Redis MCP → DB business → process.env business → fs duplicate runtime forbidden dependency ``` --- # 57. Example Architecture Rules ```ts const rules = [ { name: "ui-no-db", from: ["apps/web", "packages/ui-*"], forbidden: ["@prisma/client"] }, { name: "agent-no-db", from: ["packages/agent"], forbidden: ["@prisma/client", "ioredis"] }, { name: "business-no-secret", from: ["modules/*"], forbidden: ["process.env"] } ]; ``` --- # 58. Change Budget 每一个任务必须定义： ```yaml changeBudget: files: 30 packages: 3 migrations: 2 architectureChanges: 0 ``` 默认： ```text architectureChanges = 0 ``` 如果超过： ```text STOP ``` 重新拆任务。 --- # 59. Scope Creep Prevention 如果任务是： ```text 实现 Action Runtime ``` Zcode 不应该顺手： ```text 重写 UI 重写 Agent 重写 Plugin 更换数据库 更换 ORM 重写全部 API ``` 即使这些东西“顺便更好”。 --- # 60. Allowed Opportunistic Refactoring 只有以下情况可以顺手修： ```text 安全漏洞 编译错误 阻塞当前 Runtime 明显重复代码 直接违反本架构的代码 ``` 而且必须记录： ```text Why Impact Files Tests ``` --- # 61. Legacy Compatibility 迁移期间允许： ```text Legacy Adapter ``` 例如： ```text OldService ↓ Legacy Adapter ↓ Action Runtime ``` 但必须： ```yaml legacy: owner: migration status: temporary removalTarget: "phase-X" ``` --- # 62. Legacy Code Must Have Exit Strategy 禁止永久： ```text new architecture + legacy architecture ``` 最终必须： ```text Legacy ↓ Adapter ↓ Migration ↓ Delete ``` --- # 63. Feature Flags 大型迁移允许： ```text legacy path new path ``` 通过： ```text Feature Flag ``` 控制。 例如： ```text devos.actionRuntime.v2 ``` 迁移完成： ```text 100% new path ↓ remove flag ↓ delete old path ``` --- # 64. Rollback Strategy 每个重大任务必须说明： ```text What can fail? How to detect? How to rollback? What data changes? Can rollback be automatic? ``` --- # 65. Code Rollback 代码问题： ```text git revert ``` 或： ```text feature flag off ``` --- # 66. Database Rollback 不要假设： ```text 所有 migration 都能 down。 ``` 生产数据库优先： ```text forward-compatible migration + backup + compensating migration ``` --- # 67. Failed Implementation Recovery 如果 Zcode 连续出现： ```text compile failure test failure architecture violation ``` 不得继续堆代码。 必须： ```text STOP ↓ Diagnose ↓ Restore last known good state ↓ Re-plan ``` --- # 68. Three-Failure Rule 同一任务连续三次修复仍失败： ```text STOP IMPLEMENTATION ``` 输出： ```text Failure Analysis Root Cause Current State Options Recommended Plan ``` 不得无限循环。 --- # 69. Test-First for Runtime Contracts 对于核心 Runtime： ```text Contract ↓ Test ↓ Implementation ``` 优先于： ```text Implementation ↓ 猜测测试 ``` --- # 70. Definition of Done 一个 Runtime 不允许以： ```text “代码写完了” ``` 作为完成标准。 必须： ```text Architecture ✓ API ✓ Implementation ✓ Unit Test ✓ Contract Test ✓ Integration Test ✓ Observability ✓ Audit ✓ Permission ✓ Error Handling ✓ Documentation ✓ Migration ✓ UI / CLI demo ✓ ``` --- # 71. Runtime Definition of Done 每个 Runtime 至少回答： ```text 谁调用？ 怎么调用？ 权限在哪里？ 错误在哪里？ 审计在哪里？ 事件在哪里？ 指标在哪里？ 取消在哪里？ 超时在哪里？ 重试在哪里？ 版本在哪里？ 测试在哪里？ ``` --- # 72. Action Definition of Done 每个 Action： ```ts { id, version, description, inputSchema, outputSchema, permissions, handler, mode, timeout, idempotency, audit, events } ``` 必须能够： ```text discover authorize execute observe audit ``` --- # 73. Agent Definition of Done Agent 不只是： ```text chat UI ``` 必须： ```text Goal Context Capability Discovery Plan Execution Task Observation Replan Budget Approval Audit Result ``` --- # 74. Plugin Definition of Done Plugin 不只是： ```text npm package ``` 而是： ```text Manifest ↓ Dependency ↓ Resource ↓ Action ↓ Capability ↓ Config ↓ UI ↓ Health ↓ Lifecycle ``` --- # 75. Project Factory Definition of Done Project Factory 不只是： ```text copy template ``` 必须： ```text Requirement ↓ Project Type ↓ Capabilities ↓ Dependency Resolution ↓ Manifest ↓ Template ↓ Generate ↓ Validate ↓ Run ``` --- # 76. Zcode Working Loop 每个任务严格执行： ```text ┌───────────────┐ │ Read Docs │ └───────┬───────┘ ↓ ┌───────────────┐ │ Audit Code │ └───────┬───────┘ ↓ ┌───────────────┐ │ Classify │ └───────┬───────┘ ↓ ┌───────────────┐ │ Plan │ └───────┬───────┘ ↓ ┌───────────────┐ │ Implement │ └───────┬───────┘ ↓ ┌───────────────┐ │ Test │ └───────┬───────┘ ↓ ┌───────────────┐ │ Verify │ └───────┬───────┘ ↓ ┌───────────────┐ │ Report │ └───────┬───────┘ ↓ Next Slice ``` --- # 77. Required Task Plan Zcode 开始任务时应该先产生： ```md # Implementation Plan ## Objective ## Relevant Architecture Documents ## Current Code ## Reuse ## Refactor ## Replace ## Delete ## Target Architecture ## Files To Change ## Files To Create ## Files Not To Touch ## Tests ## Migration ## Risks ## Rollback ## Acceptance Criteria ``` --- # 78. Files Not To Touch 这是非常重要的保护机制。 如果任务是： ```text Action Runtime ``` 可以： ```text packages/action/* packages/execution/* packages/permission/* ``` 但： ```text modules/seo/* apps/business/* ``` 默认： ```text DO NOT TOUCH ``` 除非确实需要集成测试。 --- # 79. Implementation Report 任务结束后必须生成： ```md # Implementation Report ## Summary ## Architecture Implemented ## Files Created ## Files Modified ## Files Deleted ## Legacy Code Migrated ## Tests ## Database Changes ## Runtime Changes ## API Changes ## Security ## Performance ## Known Limitations ## Remaining Work ## Rollback ## Acceptance Criteria ## Final Status ``` --- # 80. Final Status 只能使用： ```text PASS PARTIAL BLOCKED FAILED ``` 不能使用： ```text almost done mostly done should work looks good ``` --- # 81. Acceptance Criteria 每个任务必须有明确： ```text AC-001 AC-002 AC-003 ``` 例如： ```text AC-001 Action 可以注册 AC-002 Action 可以发现 AC-003 Permission 生效 AC-004 Action 可以执行 AC-005 Execution 可以查询 AC-006 Audit 正确记录 AC-007 Event 正确发布 AC-008 UI 可以调用 AC-009 Contract Test 通过 AC-010 Integration Test 通过 ``` --- # 82. No Fake Completion 以下行为属于失败： ```text TODO placeholder mock implementation fake success return {} return true empty handler console.log("implemented") ``` 除非明确标记： ```text prototype stub not production-ready ``` --- # 83. No Silent Simplification 如果需求是： ```text retry ``` 不能实现成： ```text 一次执行 ``` 然后说： > “基础版本已经支持。” 如果需求是： ```text permission ``` 不能： ```text if (user) ``` 如果需求是： ```text Agent budget ``` 不能： ```text hardcoded 100 ``` --- # 84. No Fake Architecture 禁止仅创建： ```text interfaces folders empty classes ``` 然后声称： ```text Runtime implemented ``` Runtime 必须能够： ```text execute real operation ``` 并通过： ```text Contract Test ``` --- # 85. Progressive Implementation 如果完整 Runtime 太大： ```text Phase A Contract + minimal implementation Phase B Production implementation Phase C Advanced features ``` 但必须明确状态。 例如： ```yaml status: registration: complete execution: complete retry: partial distributed: pending ``` --- # 86. CLI Verification 核心能力应该可以通过 CLI 验证。 推荐： ```bash devos doctor devos version devos status devos resource list devos action list devos action inspect core.user.create devos task list devos task inspect devos plugin list devos capability list devos agent run ``` --- # 87. Doctor Command 最终： ```bash devos doctor ``` 至少检查： ```text Database Redis Migrations Runtime Registry Action Registry Plugin Registry Capability Registry Event Runtime Task Runtime Storage Configuration Secrets Workers ``` 输出： ```text PASS WARN FAIL ``` --- # 88. Runtime Health 每个 Runtime 都应该支持： ```ts interface RuntimeHealth { name: string; status: "healthy" | "degraded" | "unhealthy"; version: string; dependencies: RuntimeDependencyHealth[]; } ``` --- # 89. Observability Requirement 每个 Execution 至少可以追踪： ```text requestId correlationId traceId executionId taskId jobId actor organizationId projectId environmentId ``` --- # 90. Version Traceability 任何执行必须能够回答： ```text Runtime Version? Plugin Version? Action Version? Skill Version? MCP Version? Event Version? ``` --- # 91. Security Verification Zcode 每个阶段必须主动检查： ```text Auth Permission Scope Tenant isolation Secret leakage Audit SSRF Path traversal XSS Injection Privilege escalation ``` 尤其是： ```text Plugin MCP Agent Webhook File Storage Provider ``` --- # 92. Performance Verification 核心 Runtime 必须考虑： ```text latency throughput concurrency memory queue depth database queries N+1 external API calls token usage ``` 不要求一开始极致优化。 但是： > 不允许架构上明显制造不可扩展路径。 --- # 93. Agent Cost Control Agent Runtime 必须支持： ```text maxTokens maxIterations maxExecutionTimeMs maxTasks maxMoney maxExternalCalls ``` 并记录： ```text actual usage ``` --- # 94. Task Scaling Rule 例如： ```text 生成 100 篇文章 ``` 禁止： ```text Agent ↓ 100 次直接 Action ``` 应该： ```text Agent ↓ Task ↓ 100 Jobs ↓ Queue ↓ Workers ``` --- # 95. Event Scaling Rule 禁止： ```text 同步调用所有订阅者 ``` 应该支持： ```text Event ↓ Bus ↓ Handlers ``` 必要时： ```text Event ↓ Queue ↓ Handler Worker ``` --- # 96. UI Scaling Rule 禁止： ```text 一个页面加载所有数据 ``` 必须： ```text Query Pagination Cursor Virtualization Lazy loading Realtime incremental update ``` --- # 97. Search Scaling Rule 不要默认： ```text ElasticSearch ``` 一开始可以： ```text PostgreSQL FTS + pgvector ``` 只有确实需要时再： ```text OpenSearch ElasticSearch Meilisearch Typesense ``` --- # 98. Infrastructure Pragmatism Zcode 不允许因为“平台架构”而无意义增加基础设施。 例如： ```text Kafka Kubernetes Elasticsearch NATS Temporal ClickHouse ``` 都不是默认必选。 先建立： ```text Provider Abstraction ``` 再根据规模替换。 --- # 99. Prefer Mature Components 如果成熟方案已经满足需求： ```text Prisma Migration Redis BullMQ / compatible queue abstraction OpenTelemetry Zod React Router TanStack Query Ant Design ``` 优先复用。 不要： ```text 重新发明 ORM 重新发明 Migration 重新发明 Queue 重新发明 Schema Validator 重新发明 Tracing ``` --- # 100. But Avoid Vendor Lock-in 复用成熟组件不意味着： ```text 业务代码直接绑定 Provider ``` 应该： ```text DevOS Runtime ↓ Provider Interface ↓ Implementation ``` --- # 101. Provider Rule 例如： ```ts interface SearchProvider {} interface StorageProvider {} interface ModelProvider {} interface QueueProvider {} interface EventProvider {} ``` 业务模块不应该直接依赖： ```text OpenAI SDK S3 SDK Redis API Elastic SDK ``` 除非它是对应 Provider Implementation。 --- # 102. Plugin Installation Flow 最终必须： ```text Plugin Package ↓ Manifest ↓ Compatibility ↓ Dependencies ↓ Migration ↓ Registration ↓ Capability Registry ↓ UI Registry ↓ Health Check ↓ Enabled ``` --- # 103. Plugin Removal 必须检查： ```text running tasks resources data artifacts dependencies actions skills mcp ui config ``` 然后： ```text disable ↓ drain ↓ migrate/archive ↓ unregister ↓ remove ``` --- # 104. Agent Capability Discovery Zcode 实现 Agent 时必须采用： ```text summary ↓ schema ↓ instructions ↓ execution ``` 而不是一次将全部： ```text Action MCP Plugin Skill ``` 完整 schema 发给模型。 --- # 105. Capability Ranking 至少考虑： ```text relevance permission scope availability quality cost latency risk ``` --- # 106. Human Approval 危险操作必须： ```text requiresApproval ``` 例如： ```text delete production deploy production send bulk email modify DNS rotate critical credential delete storage ``` Agent 不能绕过。 --- # 107. Audit Chain Agent 操作应该形成： ```text Human ↓ Agent Goal ↓ Agent Plan ↓ Action ↓ Execution ↓ Audit ``` 不能只记录： ```text Agent did something. ``` --- # 108. Correlation 跨 Runtime 必须传递： ```text correlationId causationId requestId executionId taskId jobId ``` 例如： ```text Agent ↓ correlationId Task ↓ correlationId Job ↓ correlationId Execution ↓ correlationId Event ↓ correlationId Notification ``` --- # 109. No Context Loss Zcode 不允许在 Runtime 之间重新创建： ```text actor organization project environment permission ``` 必须通过： ```ts ActionContext TaskContext ExecutionContext ``` 传递。 --- # 110. Testing Pyramid 推荐： ```text E2E / \ Integration / \ Contract Tests / \ Unit Tests ``` Runtime 越底层： ```text Unit + Contract ``` 越重要。 --- # 111. Test Naming 建议： ```text action-runtime.contract.spec.ts task-runtime.contract.spec.ts plugin-runtime.contract.spec.ts agent-runtime.contract.spec.ts ``` 而不是： ```text test1.ts test2.ts ``` --- # 112. Repository Quality 每个 package 至少： ```text README.md package.json src/ tests/ ``` 核心 Runtime： ```text architecture.md contracts/ integration-tests/ ``` --- # 113. Documentation Is Part of Implementation 如果 API 改变： ```text API docs ``` 必须同步。 如果 Resource 改变： ```text Resource schema ``` 必须同步。 如果 Action 改变： ```text Action contract ``` 必须同步。 --- # 114. No Stale Documentation 如果 Zcode 改了： ```text runtime architecture ``` 但文档仍写旧架构： ```text FAIL ``` --- # 115. Git Commit Strategy 建议按 Vertical Slice 提交： ```text feat(resource): add resource registry feat(action): add action registry feat(runtime): add action execution runtime test(action): add runtime contract tests feat(task): add task runtime ``` 不要： ```text feat: massive devos rewrite ``` --- # 116. Small Commits 一个 Commit 应该回答： ```text 为什么？ 改了什么？ 如何验证？ ``` --- # 117. Migration Commits 数据库迁移建议： ```text migration code backfill cleanup ``` 分开。 --- # 118. Zcode Must Preserve Buildability 任何阶段结束： ```bash bun install bun run typecheck bun run lint bun run test bun run build ``` 至少必须保证： ```text project remains buildable ``` --- # 119. Broken Main Branch Is Not Acceptable 禁止： ```text “后面会修。” ``` 如果当前任务确实必须暂时破坏： ```text feature branch ``` 并且不能合并。 --- # 120. No Massive Blind Rewrite 禁止： ```text 删除整个 src 重新生成项目 ``` 除非： ```text 明确架构决策 明确迁移计划 明确 rollback ``` --- # 121. Refactor Strategy 优先： ```text Strangler Pattern ``` 即： ```text Legacy ↓ Adapter ↓ New Runtime ↓ New Path ↓ Delete Legacy ``` 而不是： ```text Big Bang Rewrite ``` --- # 122. Runtime Migration Example 旧： ```text POST /users ↓ UserController ↓ UserService ↓ Prisma ``` 迁移： ```text POST /users ↓ UserController ↓ Action Runtime ↓ core.user.create ↓ Data Runtime ↓ Prisma ``` 最后： ```text UserService ``` 删除。 --- # 123. Agent Migration Example 旧： ```text Agent ↓ OpenAI ↓ custom tool ↓ custom API ``` 新： ```text Agent Runtime ↓ Capability Registry ↓ Skill ↓ Action ↓ Action Runtime ``` --- # 124. Plugin Migration Example 旧： ```text Plugin ↓ PluginService ↓ Plugin DB ``` 新： ```text Plugin Runtime ↓ Manifest ↓ Registry ↓ Resource / Action / Capability ``` --- # 125. MCP Migration Example 旧： ```text MCP Server ↓ business service ``` 新： ```text MCP ↓ MCP Adapter ↓ Capability ↓ Action Runtime ``` --- # 126. UI Migration Example 旧： ```text React ↓ fetch ↓ business API ``` 新： ```text React ↓ API Client ↓ Action / Query ↓ Runtime ``` --- # 127. Required Architecture Inventory Zcode 应维护： ```text docs/ARCHITECTURE_INVENTORY.md ``` 至少： ```text Runtime Package Owner Status Dependencies Public APIs Tests ``` 例如： ```md | Runtime | Package | Status | |---|---|---| | Action | packages/action | DONE | | Task | packages/task | PARTIAL | | Event | packages/event | TODO | ``` --- # 128. Capability Inventory 维护： ```text docs/CAPABILITY_INVENTORY.md ``` 记录： ```text Capability Type Provider Permission Action Plugin Skill MCP Status ``` 这样 Agent 不会重复创建能力。 --- # 129. Duplicate Capability Prevention 新增能力前： ```text Search Capability Registry ``` 如果已有： ```text seo.website.scan ``` 禁止再创建： ```text seo.scanWebsite website.seoScanner seo.auditWebsite ``` 除非它们语义不同。 --- # 130. Duplicate Resource Prevention 新增： ```text Resource ``` 之前必须搜索： ```text Resource Registry ``` 避免： ```text user core.user users account.user ``` 同时存在。 --- # 131. Duplicate Action Prevention 新增 Action 前： ```text Action Registry ``` 检查： ```text name namespace semantic meaning input output ``` --- # 132. Naming Rule 统一： ```text namespace.resource.action ``` 例如： ```text core.user.create core.task.cancel storage.file.upload seo.website.scan devops.server.deploy ``` --- # 133. Version Rule 可变 Action 使用： ```text action@1 action@2 ``` 而不是偷偷改变： ```text action ``` 的语义。 --- # 134. Agent Plan Lock Agent 产生 Plan 后： ```text Capability Version Action Version Skill Version Plugin Version ``` 应该锁定。 执行过程中如果版本发生变化： ```text detect ↓ replan ↓ record reason ``` --- # 135. Production Reproducibility 生产执行必须能够恢复： ```text what happened ``` 必须记录： ```text Runtime Version Plugin Version Action Version Skill Version MCP Version Config Snapshot Environment ``` --- # 136. Config Snapshot 长时间运行 Task 推荐： ```text Pinned Configuration ``` 而不是执行到一半突然： ```text API key model provider behavior ``` 全部改变。 --- # 137. No Secret in Snapshot 配置 Snapshot： ```text secret reference ``` 而不是： ```text secret plaintext ``` --- # 138. Zcode Security Stop Conditions 遇到： ```text secret leak permission bypass tenant isolation failure arbitrary filesystem access SSRF RCE risk SQL injection unsafe plugin execution Agent privilege escalation ``` 必须： ```text STOP ``` 优先修复。 --- # 139. Production Destructive Actions Zcode 不应该让 Agent 自动执行： ```text production destructive migration ``` 除非： ```text explicit approval ``` --- # 140. Definition of Platform Complete DevOS 不能因为： ```text 页面很多 ``` 就认为完成。 平台完成的判断是： ```text 新业务可以快速创建 ``` 例如： ```text 创建 CRM ``` 不应该重新实现： ```text Auth RBAC Organization Task Queue Event File Search Notification Agent Plugin Settings Audit Observability ``` 而应该： ```text devos create crm ``` 然后添加业务模块。 --- # 141. Final Project Test 最终必须验证： ```text 能否从 DevOS 创建一个全新项目？ ``` 例如： ```bash devos create test-app --preset saas ``` 然后： ```text Login Organization Project Resource Action Task File Search Notification Agent Plugin ``` 全部可以使用平台能力。 --- # 142. Zcode Master Prompt 以下内容可以直接作为： ```text Zcode Master Prompt ``` 放入： ```text ZCODE_MASTER_PROMPT.md ``` 或者每次任务开始时提供给 Zcode。 --- # 143. MASTER PROMPT ```text You are the primary implementation agent for the DevOS project. Project root: /home/dev/bun/devos Your job is NOT to invent a new architecture. Your job is to implement the architecture defined by the DevOS architecture documents. ================================================== 1. SOURCE OF TRUTH ================================================== Before implementing any non-trivial task: 1. Read the relevant DevOS architecture documents. 2. Read 23_ZCODE_IMPLEMENTATION_PROTOCOL.md. 3. Inspect the current repository. 4. Audit the existing implementation. 5. Classify existing code: - REUSE - REFACTOR - REPLACE - DELETE 6. Produce an implementation plan. 7. Only then modify code. Do not infer architecture from legacy code. Architecture documents have priority over existing implementation. If architecture documents conflict, stop and report the conflict. Do not invent architecture silently. ================================================== 2. CORE ARCHITECTURE ================================================== DevOS is based on: Resource Action Event Agent Core execution rule: Resource ↓ Action ↓ Action Runtime ↓ Execution Asynchronous work: Task ↓ Job ↓ Queue ↓ Worker ↓ Action Runtime ↓ Execution Events: Action ↓ Execution ↓ Event Runtime ↓ Event ↓ Handlers / Notification / Realtime / Agent Agent: Goal ↓ Agent Runtime ↓ Skill / Capability Discovery ↓ Plan ↓ Action / Task ↓ Execution ↓ Observation ↓ Replan / Complete ================================================== 3. ABSOLUTE RULE ================================================== Never create a second runtime for an existing responsibility. There must be one authoritative runtime for: Action Data Task Job Queue Worker Event Storage Search Configuration Secret Provider Plugin MCP Capability Skill Agent Workflow Notification Observability If you discover an existing duplicate runtime: DO NOT create another one. Instead: Audit Classify Migrate Remove duplicate ================================================== 4. NO DIRECT INFRASTRUCTURE ACCESS ================================================== UI must not directly access: Database Redis Queue Worker Filesystem Secret store Storage provider Agent must not directly access: Database Redis Queue Filesystem Secret store Plugin business code must not directly access: Database Redis Queue Filesystem Secret store MCP must not bypass: Permission Scope Action Runtime Audit Business code must not directly use: process.env raw Prisma raw Redis raw filesystem raw storage provider Use the appropriate DevOS Runtime. ================================================== 5. ACTION RULE ================================================== All business writes must eventually execute through: Action Runtime This includes: REST UI CLI Plugin MCP Skill Agent Workflow Scheduler Webhook System jobs Do not implement a parallel execution path. ================================================== 6. UI RULE ================================================== UI is a visualization layer. UI must not own business logic. UI: reads through Query / Search writes through: Action → Action Runtime async work through: Task → Job realtime through: Event → Realtime ================================================== 7. AGENT RULE ================================================== Agent decides WHAT should happen. Agent does not directly manipulate infrastructure. Agent must use: Goal Context Capability Discovery Skill Plan Action Task Observation Budget Approval Never persist or expose hidden chain-of-thought. Persist only: decision summary plan action result observation error metadata ================================================== 8. PLUGIN RULE ================================================== Plugin may provide: Resource Action Skill MCP Workflow UI Configuration Provider Plugin must use DevOS runtimes. Plugin must not create: Auth RBAC Task Runtime Queue Runtime Event Runtime Secret Runtime Notification Runtime Router Action Runtime ================================================== 9. MCP RULE ================================================== MCP is a capability access layer. MCP is NOT a second business runtime. Correct: MCP ↓ Capability ↓ Action Runtime Never: MCP ↓ Direct DB ================================================== 10. DATABASE RULE ================================================== Reads: Query / Repository ↓ Data Runtime Writes: Action ↓ Action Runtime ↓ Data Runtime ↓ Database Use Prisma as implementation where appropriate. Do not invent another ORM. Database changes must use migrations. ================================================== 11. ASYNC RULE ================================================== Long-running work must use: Task ↓ Job ↓ Queue ↓ Worker Do not implement ad-hoc background execution. Agent must create normal DevOS Tasks. ================================================== 12. EVENT RULE ================================================== All durable domain/system events go through Event Runtime. Use: Outbox Event Store Event Bus Subscriptions Handlers Replay Audit Realtime Do not create plugin-specific event systems. ================================================== 13. SECURITY RULE ================================================== Every operation must respect: Authentication Authorization Resource permission Scope Tenant isolation Environment policy Audit Never assume frontend permission is security. Never expose secrets. Never log secret plaintext. ================================================== 14. SCOPE CONTROL ================================================== Implement one vertical slice at a time. Do not rewrite unrelated modules. Do not change architecture to make implementation easier. Default: architectureChanges = 0 If architecture change is required: STOP. Create an ADR. Wait for approval. ================================================== 15. LEGACY CODE ================================================== Legacy code may be: REUSE REFACTOR REPLACE DELETE Prefer: Legacy ↓ Adapter ↓ New Runtime ↓ Migration ↓ Delete Legacy Do not perform a blind big-bang rewrite. ================================================== 16. TESTING ================================================== Every core Runtime requires: Unit Tests Contract Tests Integration Tests Important user-facing flows require: E2E Tests Before reporting completion: typecheck lint unit tests contract tests integration tests build E2E when applicable ================================================== 17. ACCEPTANCE ================================================== Never say: "almost done" "mostly done" "should work" Final status must be: PASS PARTIAL BLOCKED FAILED Every task must have explicit acceptance criteria. ================================================== 18. FAILURE HANDLING ================================================== If the same implementation problem fails three times: STOP. Do not keep patching blindly. Produce: Root Cause Current State Failed Attempts Options Recommended Plan Restore the last known good state when necessary. ================================================== 19. IMPLEMENTATION REPORT ================================================== At the end of every major task report: Summary Architecture Implemented Files Created Files Modified Files Deleted Legacy Migrated Tests Database Changes API Changes Security Performance Known Limitations Remaining Work Rollback Acceptance Criteria Final Status ================================================== 20. FINAL PRINCIPLE ================================================== Do not optimize for lines of code. Do not optimize for number of pages. Do not optimize for speed of typing. Optimize for: Architecture correctness Runtime reuse Security Traceability Testability Upgradeability Extensibility Project creation speed DevOS is a platform, not a giant business application. The goal is to make future applications cheap to build. Every implementation decision must move the repository closer to that goal. ``` --- # 144. Zcode Pre-Implementation Checklist 开始任务前： ```text [ ] Read relevant architecture docs [ ] Read protocol [ ] Inspect repository [ ] Audit current implementation [ ] Identify existing Runtime [ ] Identify duplicate Runtime [ ] Identify dependencies [ ] Identify DB changes [ ] Identify security impact [ ] Define vertical slice [ ] Define acceptance criteria [ ] Define change budget [ ] Define rollback ``` --- # 145. Zcode Post-Implementation Checklist 完成任务后： ```text [ ] Typecheck [ ] Lint [ ] Unit tests [ ] Contract tests [ ] Integration tests [ ] E2E if required [ ] Migration check [ ] Architecture check [ ] Security check [ ] No duplicate Runtime [ ] No direct infrastructure access [ ] Audit works [ ] Events work [ ] Observability works [ ] Documentation updated [ ] Acceptance criteria passed [ ] Implementation report written ``` --- # 146. Architecture Violation Checklist 如果发现： ```text [ ] UI → DB [ ] Agent → DB [ ] Plugin → DB [ ] MCP → DB [ ] Business → Redis [ ] Business → process.env [ ] Business → filesystem [ ] Plugin → own queue [ ] Plugin → own EventBus [ ] Agent → own task system [ ] MCP → own execution engine [ ] duplicate Action Runtime [ ] duplicate Task Runtime [ ] duplicate Event Runtime [ ] duplicate Secret Runtime ``` 则： ```text ARCHITECTURE VIOLATION ``` 必须修复或创建迁移计划。 --- # 147. What Zcode Must Never Do ```text ❌ Blind rewrite ❌ Invent architecture ❌ Duplicate Runtime ❌ Create parallel task system ❌ Create parallel event system ❌ Create plugin-specific auth ❌ Bypass Action Runtime ❌ Bypass permission ❌ Bypass secret runtime ❌ Bypass storage runtime ❌ Persist hidden CoT ❌ Put business logic into UI ❌ Put business logic into MCP ❌ Put business logic into Skill ❌ Use process.env in business modules ❌ Modify production destructively without approval ❌ Hide incomplete implementation ❌ Declare TODO implementation as complete ``` --- # 148. What Zcode Should Do ```text ✓ Read ✓ Audit ✓ Classify ✓ Plan ✓ Implement ✓ Test ✓ Verify ✓ Migrate ✓ Document ✓ Report ``` 并且： ```text Prefer reuse over rewrite. Prefer runtime over custom implementation. Prefer adapter over duplication. Prefer incremental migration over big-bang rewrite. Prefer mature infrastructure over reinventing infrastructure. Prefer explicit architecture decisions over autonomous guesses. ``` --- # 149. Final DevOS Implementation Chain Zcode 最终必须将代码实现成： ```text USER │ ▼ GOAL │ ▼ AGENT │ ┌─────────┴─────────┐ ▼ ▼ SKILL CAPABILITY │ │ └─────────┬─────────┘ ▼ ACTION │ ▼ ACTION RUNTIME │ ▼ EXECUTION │ ┌────────────┼────────────┐ ▼ ▼ ▼ TASK EVENT AUDIT │ │ │ ▼ ▼ ▼ JOB/QUEUE BUS/REALTIME OBSERVABILITY │ ▼ WORKER │ ▼ ACTION RUNTIME │ ▼ DATA / STORAGE / SEARCH │ ▼ PLUGIN / MODULE │ ▼ PROJECT │ ▼ PROJECT FACTORY ``` --- # 150. Final Golden Rule > **Zcode 不是 DevOS 的架构设计者。** > > **Zcode 是 DevOS 架构的实施者。** 它的职责不是： ```text “我认为应该这样设计。” ``` 而是： ```text 读取规范 ↓ 理解规范 ↓ 审计现状 ↓ 找出差距 ↓ 按规范实施 ↓ 测试 ↓ 验证 ↓ 报告 ``` 最终必须保证： ```text ONE RESOURCE MODEL ONE ACTION MODEL ONE ACTION RUNTIME ONE DATA RUNTIME ONE TASK RUNTIME ONE EVENT RUNTIME ONE STORAGE RUNTIME ONE SEARCH RUNTIME ONE CONFIGURATION RUNTIME ONE SECRET RUNTIME ONE PLUGIN RUNTIME ONE MCP RUNTIME ONE CAPABILITY REGISTRY ONE SKILL RUNTIME ONE AGENT RUNTIME ONE UI RUNTIME ``` 而不是： ```text Core Runtime + Plugin Runtime + Agent Runtime + SEO Runtime + MCP Runtime + UI Runtime + Old Service Runtime + Legacy Runtime + 某个新模块自己的 Runtime ``` --- # 151. The Real Goal DevOS 最终成功的标准不是： ```text 代码量增加 页面增加 API 增加 ``` 而是： ```text 新项目开发成本下降 新能力可以复用 插件可以安装 MCP 可以接入 Agent 可以调用 Task 可以执行 Event 可以传播 UI 可以自动生成 项目可以快速创建 旧项目可以升级 业务模块不会污染 Core ``` 最终： ```text Build DevOS once ↓ Reuse everywhere ↓ Extend through Capability ↓ Compose through Project Factory ↓ Let Agents operate the platform ↓ Build new businesses faster ``` > **DevOS 的终点不是“完成一个大型后台”。** > > **终点是让开发者以后不再从零开始造后台、Auth、RBAC、Task、Queue、Event、Storage、Search、Agent、Plugin、Settings 和项目基础设施。** > > **Zcode 的任务，就是把这个目标一步一步真正落成代码。**