# DevOS Plugin Runtime > Version: 1.0 > Status: Implementation Specification > Target: Zcode > Previous: 10_EVENT_AUDIT_OBSERVABILITY_RUNTIME.md > Next: 12_* --- # 1. 目标 DevOS Plugin Runtime 是整个 DevOS 的扩展系统。 Plugin 必须能够扩展： - Resource - Action - Capability - Skill - MCP - Workflow - Event - UI - Navigation - Settings - Dashboard - Widget - Notification - Scheduler - Worker Capability Plugin 不是简单的 npm package。 Plugin 是： > 可以被 DevOS 安装、配置、启停、升级、卸载，并向 DevOS Runtime 注册能力和 UI 的扩展单元。 --- # 2. 核心原则 Plugin 必须运行在 DevOS Runtime 之上。 正确： Plugin ↓ Plugin Runtime ↓ DevOS Registry ↓ DevOS Runtime 禁止： Plugin ↓ 自己的数据库 ↓ 自己的 Queue ↓ 自己的 Auth ↓ 自己的 EventBus ↓ 自己的 Task System 除非明确声明为 external service，并通过标准 Adapter 接入。 --- # 3. Plugin 的本质 Plugin 是： ```text Extension Package + Manifest + Runtime + Capabilities + UI + Configuration ```` 例如 SEO Plugin： ```text seo.plugin ├── Resource │ ├── seo.website │ ├── seo.keyword │ └── seo.article │ ├── Action │ ├── seo.website.scan │ ├── seo.keyword.research │ └── seo.article.generate │ ├── Skill │ ├── seo-audit │ └── content-generation │ ├── MCP │ ├── search-engine │ └── browser │ ├── Workflow │ └── seo-audit-workflow │ ├── Event │ ├── seo.website.scanned │ └── seo.article.generated │ └── UI ├── Website ├── Keywords ├── Articles └── Settings ``` --- # 4. Plugin Namespace 每个 Plugin 必须拥有唯一 namespace。 格式： ```text . ``` 例如： ```text devos.seo devos.devops devos.crm github.integration cloudflare.integration ``` Plugin 内部 Resource： ```text devos.seo.website devos.seo.keyword ``` Action： ```text devos.seo.website.scan ``` Skill： ```text devos.seo.audit ``` 禁止两个 Plugin 注册同一个 namespace。 --- # 5. Plugin ID Plugin ID： ```ts type PluginId = string ``` 例如： ```text devos.seo ``` 必须满足： ```text ^[a-z0-9][a-z0-9._-]*$ ``` --- # 6. Plugin Manifest 每个 Plugin 必须提供： ```text plugin.json ``` 推荐： ```json { "id": "devos.seo", "name": "SEO", "version": "1.0.0", "description": "SEO automation capabilities", "runtime": "devos", "apiVersion": "1", "author": "DevOS", "license": "MIT" } ``` --- # 7. 完整 Manifest ```ts interface PluginManifest { id: string name: string version: string description?: string apiVersion: string runtime: 'devos' author?: string homepage?: string repository?: string license?: string icon?: string categories?: string[] dependencies?: PluginDependency[] optionalDependencies?: PluginDependency[] permissions?: PluginPermission[] capabilities?: PluginCapabilityDeclaration[] resources?: PluginResourceDeclaration[] actions?: PluginActionDeclaration[] skills?: PluginSkillDeclaration[] mcp?: PluginMCPDeclaration[] workflows?: PluginWorkflowDeclaration[] events?: PluginEventDeclaration[] ui?: PluginUIDeclaration[] settings?: PluginSettingDeclaration[] workers?: PluginWorkerDeclaration[] } ``` --- # 8. Plugin 生命周期 Plugin 状态： ```text discovered ↓ installing ↓ installed ↓ configuring ↓ enabled ↓ running ↓ disabled ↓ uninstalling ↓ uninstalled ``` 异常： ```text install_failed activation_failed runtime_error upgrade_failed ``` --- # 9. Plugin Runtime 状态 ```ts type PluginStatus = | 'discovered' | 'installing' | 'installed' | 'configuring' | 'enabled' | 'running' | 'disabled' | 'uninstalling' | 'uninstalled' | 'install_failed' | 'activation_failed' | 'runtime_error' | 'upgrade_failed' ``` --- # 10. Plugin Resource Plugin 本身必须成为 DevOS Resource： ```text core.plugin ``` Plugin Resource： ```text core.plugin.installation ``` --- # 11. Plugin Actions 至少： ```text core.plugin.install core.plugin.uninstall core.plugin.enable core.plugin.disable core.plugin.restart core.plugin.upgrade core.plugin.configure core.plugin.health core.plugin.reload ``` --- # 12. 所有 Plugin 管理操作必须走 Action Runtime 错误： ```text POST /plugins/:id/enable controller: plugin.enable() ``` 正确： ```text HTTP ↓ core.plugin.enable ↓ Action Runtime ↓ Plugin Runtime ``` CLI： ```text devos plugin enable devos.seo ``` 也必须： ```text CLI ↓ Action Runtime ↓ core.plugin.enable ``` Agent： ```text Agent ↓ core.plugin.enable ↓ Action Runtime ``` 三者执行路径必须完全一致。 --- # 13. Plugin Installation Record 数据库： ```ts interface PluginInstallation { id: string pluginId: string version: string status: PluginStatus source: PluginSource enabled: boolean installedAt: Date updatedAt: Date activatedAt?: Date disabledAt?: Date error?: string metadata?: Record } ``` --- # 14. Plugin Source 支持： ```ts type PluginSource = | { type: 'builtin' } | { type: 'local' path: string } | { type: 'package' package: string version?: string } | { type: 'git' repository: string ref?: string } | { type: 'url' url: string } ``` 第一阶段至少实现： ```text builtin local package ``` Git / URL 可以作为后续扩展。 --- # 15. Built-in Plugin DevOS 自己的功能也可以 Plugin 化。 例如： ```text devos.core devos.seo devos.devops ``` 但 Core Runtime 本身不能依赖 Plugin Runtime 才能启动。 即： ```text Core Runtime ↓ Plugin Runtime ↓ Optional Plugins ``` 而不是： ```text Plugin Runtime ↓ Core Runtime ``` --- # 16. Plugin Registration Plugin 激活后： ```text Plugin ↓ Manifest ↓ Validate ↓ Register ├── Resources ├── Actions ├── Capabilities ├── Skills ├── MCP ├── Events ├── Workflows └── UI ``` --- # 17. Plugin Registry 实现： ```ts interface PluginRegistry { register(plugin: RegisteredPlugin): Promise unregister(pluginId: string): Promise get(pluginId: string): RegisteredPlugin | undefined list(): RegisteredPlugin[] has(pluginId: string): boolean } ``` --- # 18. Registered Plugin ```ts interface RegisteredPlugin { manifest: PluginManifest status: PluginStatus runtime: PluginRuntime registeredAt: Date } ``` --- # 19. Plugin Runtime ```ts interface PluginRuntime { initialize(context: PluginContext): Promise activate(context: PluginContext): Promise deactivate(context: PluginContext): Promise dispose(context: PluginContext): Promise health(): Promise } ``` --- # 20. Plugin Context ```ts interface PluginContext { pluginId: string version: string logger: Logger eventBus: EventBus resourceRegistry: ResourceRegistry actionRegistry: ActionRegistry capabilityRegistry: CapabilityRegistry skillRegistry: SkillRegistry mcpRegistry: MCPRegistry config: PluginConfigService storage: PluginStorage signal: AbortSignal } ``` Plugin 不应该直接拿： ```text PrismaClient RedisClient BullMQ ``` Plugin 应该使用 DevOS 提供的抽象。 --- # 21. Plugin Storage 某些 Plugin 需要自己的持久化数据。 提供： ```ts interface PluginStorage { get(key: string): Promise set(key: string, value: T): Promise delete(key: string): Promise } ``` 但这是： > Plugin Storage 不是： > Plugin 自己拥有一套数据库系统。 --- # 22. Plugin Database 如果 Plugin 需要复杂业务数据： 必须通过 DevOS Database / ORM / Migration Runtime。 例如： ```text packages/plugins/seo migrations/ schema/ ``` 数据库表必须带 Plugin Namespace。 例如： ```text seo_websites seo_keywords seo_articles ``` 禁止 Plugin 私自建立第二个 PostgreSQL 实例。 --- # 23. Plugin Configuration Plugin 可以声明 Settings。 例如： ```json { "settings": [ { "key": "defaultModel", "type": "string", "required": true }, { "key": "apiEndpoint", "type": "url" } ] } ``` --- # 24. Plugin Setting Schema ```ts interface PluginSettingDeclaration { key: string type: | 'string' | 'number' | 'boolean' | 'secret' | 'url' | 'select' | 'multiselect' | 'json' label: string description?: string required?: boolean default?: unknown options?: { label: string value: string }[] } ``` --- # 25. Plugin Settings Resource Plugin 配置应该属于： ```text core.plugin.settings ``` 而不是： ```text plugin_database_table ``` API： ```text GET /api/plugins/:pluginId/settings PUT /api/plugins/:pluginId/settings ``` 但是最终执行： ```text core.plugin.configure ``` --- # 26. Secret Settings 例如： ```text OpenAI API Key Cloudflare API Token GitHub Token SMTP Password ``` 必须使用： ```text type = secret ``` 数据库不得明文保存。 推荐： ```text Encryption at Rest ``` 读取时默认： ```text ******** ``` 只有真正执行需要时才能在 Runtime 内解密。 --- # 27. Plugin Settings 权限 必须区分： ```text plugin.view plugin.configure plugin.install plugin.uninstall plugin.enable plugin.disable ``` 普通用户： ```text plugin.view ``` 管理员： ```text plugin.configure ``` 系统管理员： ```text plugin.install plugin.uninstall ``` 具体策略由 RBAC / Policy Runtime 控制。 --- # 28. Plugin UI Plugin 可以提供自己的页面。 例如： ```text SEO ├── Overview ├── Websites ├── Keywords ├── Articles ├── Tasks └── Settings ``` Plugin UI 不是独立 SPA。 必须挂载到： ```text DevOS UI Shell ``` --- # 29. Plugin UI Manifest ```ts interface PluginUIDeclaration { routes?: PluginRoute[] navigation?: PluginNavigationItem[] dashboards?: PluginDashboard[] widgets?: PluginWidget[] settingsPage?: boolean } ``` --- # 30. Plugin Route ```ts interface PluginRoute { id: string path: string title: string component: string icon?: string permissions?: string[] } ``` 例如： ```json { "id": "seo-websites", "path": "/seo/websites", "title": "Websites", "component": "SeoWebsitesPage", "permissions": [ "devos.seo.website.read" ] } ``` --- # 31. Plugin Navigation Plugin 可以向左侧导航注册： ```text SEO Overview Websites Keywords Articles Tasks ``` 但不能直接修改 DevOS Shell。 必须： ```text Plugin ↓ Navigation Registry ↓ UI Shell ``` --- # 32. Navigation Registry ```ts interface NavigationRegistry { register(item: NavigationItem): void unregister(pluginId: string): void list(context: NavigationContext): NavigationItem[] } ``` 必须根据： ```text permission organization project plugin enabled ``` 动态过滤。 --- # 33. Plugin Dashboard Plugin 可以提供 Dashboard： ```text SEO Overview Websites: 127 Keywords: 3,821 Articles: 1,240 Tasks Running: 17 Errors: 3 ``` Dashboard 只负责： ```text 展示 查询 触发 Action ``` 不能在 UI 内实现业务逻辑。 --- # 34. Plugin Widget Plugin 可以注册： ```text Dashboard Widget Chat Widget Task Widget Resource Widget Report Widget ``` 例如： ```text SEO Health Score ``` Widget 可以声明： ```ts interface PluginWidget { id: string title: string component: string size: 'small' | 'medium' | 'large' permissions?: string[] } ``` --- # 35. Plugin Page 与 Action Runtime 页面： ```text 按钮：Scan Website ``` 不能： ```ts fetch('/seo/scan') ``` 应该： ```text UI ↓ Action Client ↓ devos.seo.website.scan ↓ Action Runtime ``` --- # 36. Plugin Resource UI 如果 Plugin 注册： ```text seo.website ``` 可以自动获得： ```text List Detail Create Edit Delete ``` 如果 Resource 声明： ```text ui.list ui.detail ``` DevOS Generic UI 可以自动生成。 Plugin 只需要实现复杂页面。 --- # 37. Plugin Actions Plugin Action： ```ts interface PluginActionDeclaration { id: string name: string description?: string inputSchema: unknown outputSchema: unknown mode: 'sync' | 'async' | 'stream' permissions: string[] requiresApproval?: boolean } ``` Action 最终进入： ```text Action Registry ``` --- # 38. Plugin Capability Plugin Action 自动成为 Capability。 例如： ```text devos.seo.website.scan ``` 注册： ```text Capability type = action source = plugin ``` Agent 就能够发现。 --- # 39. Plugin Skill Plugin 可以注册 Skill： ```ts interface PluginSkillDeclaration { id: string name: string description: string version: string instructions: string requiredCapabilities: string[] inputSchema?: unknown outputSchema?: unknown } ``` --- # 40. Plugin 与 Agent 例如： ```text SEO Plugin ↓ Skill: seo.audit ↓ Capabilities: seo.website.scan seo.keyword.research seo.article.generate ↓ Agent ``` Agent 不需要知道： ```text 这个能力来自哪个数据库 哪个 Controller 哪个 Plugin 文件 ``` 只看到： ```text Capability ``` --- # 41. Plugin MCP Plugin 可以声明 MCP： ```ts interface PluginMCPDeclaration { id: string name: string transport: | 'stdio' | 'http' | 'sse' endpoint?: string command?: string args?: string[] } ``` 但是： **MCP 仍然必须通过 MCP Runtime + Action Runtime。** --- # 42. Plugin Event Plugin 可以声明 Event： ```text devos.seo.website.scanned devos.seo.article.generated ``` Event 进入： ```text Event Registry ``` 并可以被： ```text Agent Workflow Notification Webhook Plugin ``` 消费。 --- # 43. Plugin Event Handler Plugin Handler： ```text Event ↓ Plugin Handler ↓ Action Runtime ``` 禁止： ```text Event ↓ Plugin Handler ↓ 直接 DB mutation ``` --- # 44. Plugin Workflow Plugin 可以提供 Workflow： ```text seo.full.audit ``` 例如： ```text scan website ↓ collect keywords ↓ analyze pages ↓ generate report ``` Workflow 由： ```text Action Task Job ``` 组成。 --- # 45. Plugin Scheduler Plugin 可以注册 Schedule Definition。 例如： ```text SEO daily scan Every day at 03:00 ``` 最终还是： ```text Scheduler ↓ Task ↓ Action ``` Plugin 不得自己运行： ```text setInterval() ``` 或： ```text node-cron ``` 来承担业务调度。 --- # 46. Plugin Worker 某些 Plugin 可能需要特殊 Worker。 例如： ```text browser ffmpeg docker ssh ``` Plugin 可以声明 Worker Capability： ```ts interface PluginWorkerDeclaration { id: string queues: string[] capabilities: string[] concurrency?: number } ``` 最终由： ```text Worker Runtime ``` 管理。 --- # 47. Plugin Dependencies 例如： ```json { "dependencies": [ { "id": "devos.browser", "version": "^1.0.0" } ] } ``` 安装时： ```text Plugin A ↓ Dependency Resolver ↓ Plugin B ↓ Install ``` --- # 48. Dependency Version 必须支持： ```text exact range ``` 例如： ```text 1.2.3 ^1.2.0 >=1.0.0 <2.0.0 ``` --- # 49. Dependency Graph Plugin Runtime 必须检测： ```text A → B B → C C → A ``` 发现： ```text circular dependency ``` 直接拒绝安装。 --- # 50. Plugin API Version Plugin 必须声明： ```text apiVersion ``` 例如： ```text apiVersion = 1 ``` DevOS Runtime 升级： ```text API v1 API v2 ``` 可以兼容旧 Plugin。 --- # 51. Plugin Compatibility 安装之前必须执行： ```text Manifest ↓ API Compatibility ↓ Dependency Compatibility ↓ Permission Validation ↓ Resource Conflict Check ↓ Action Conflict Check ↓ Install ``` --- # 52. Resource Conflict 例如： Plugin A： ```text seo.website ``` Plugin B： ```text seo.website ``` 必须拒绝： ```text RESOURCE_NAMESPACE_CONFLICT ``` 除非明确声明： ```text override ``` 第一阶段： **禁止 Override。** --- # 53. Action Conflict 同样： ```text seo.website.scan ``` 只能由一个 Plugin 注册。 --- # 54. Capability Conflict Capability ID 也必须唯一。 --- # 55. Plugin Enable Enable： ```text core.plugin.enable ↓ Load Plugin ↓ Validate ↓ Register ↓ Activate ↓ Health Check ↓ enabled ``` 如果失败： ```text activation_failed ``` 不得标记为 enabled。 --- # 56. Plugin Disable Disable： ```text core.plugin.disable ↓ Stop accepting new work ↓ Drain active work ↓ Deactivate ↓ Unregister runtime capabilities ↓ disabled ``` 已经运行中的 Task： ```text 默认继续完成 ``` 除非 Plugin 声明： ```text shutdownPolicy = cancel ``` --- # 57. Plugin Uninstall 不能直接删除。 必须： ```text Disable ↓ Check Running Tasks ↓ Check Dependencies ↓ Check Data Policy ↓ Unregister ↓ Remove ``` --- # 58. Plugin Data Policy Manifest 可以声明： ```ts dataPolicy: { preserveOnDisable: boolean preserveOnUninstall: boolean destructiveUninstall: boolean } ``` 默认： ```text preserveOnUninstall = true ``` 即： **卸载 Plugin 默认不删除业务数据。** --- # 59. Plugin Upgrade 升级流程： ```text Current Plugin ↓ Read New Manifest ↓ Compatibility Check ↓ Dependency Check ↓ Migration Plan ↓ Backup / Safety Check ↓ Disable ↓ Migration ↓ Install New Version ↓ Register ↓ Activate ↓ Health Check ``` --- # 60. Migration Plugin Migration： ```ts interface PluginMigration { from: string to: string up(): Promise down?(): Promise } ``` Migration 必须支持： ```text version history ``` --- # 61. Upgrade Failure 升级失败必须： ```text upgrade_failed ``` 并尽可能： ```text Rollback ``` 但不要假设所有 Migration 都可以自动 Rollback。 因此： ```text backup + forward migration + recovery procedure ``` 必须存在。 --- # 62. Plugin Isolation Plugin 必须受到： ```text Permission Namespace Resource Scope Action Scope ``` 限制。 Plugin 不应该默认拥有： ```text root filesystem all environment variables all secrets all database tables ``` --- # 63. Plugin Permission Declaration Manifest： ```json { "permissions": [ "network:http", "storage:plugin", "secret:seo-api", "resource:seo.website" ] } ``` Permission 必须经过用户/管理员批准。 --- # 64. Permission 分类 至少： ```text resource action network storage secret filesystem process worker mcp ``` --- # 65. Network Permission Plugin 不应该默认访问任意互联网地址。 推荐： ```text network:http network:https ``` 未来可以限制： ```text network:domain:api.example.com ``` --- # 66. Secret Permission Plugin 请求： ```text secret:openai ``` 只能访问： ```text OpenAI Credential ``` 不能读取： ```text Cloudflare Credential GitHub Credential ``` --- # 67. Plugin Credential 统一使用： ```text Credential Runtime ``` 例如： ```text core.credential ``` Plugin： ```text Credential Request ↓ Permission ↓ Credential Runtime ↓ Secret ``` Plugin 不应该直接读取 `.env`。 --- # 68. Plugin Environment Plugin 可以获得： ```ts interface PluginEnvironment { devosVersion: string pluginId: string pluginVersion: string environment: 'development' | 'test' | 'production' } ``` 禁止直接依赖大量 DevOS 内部环境变量。 --- # 69. Plugin Logging Plugin 必须使用： ```ts context.logger ``` 例如： ```ts context.logger.info( 'SEO scan started', { websiteId } ) ``` 日志自动获得： ```text pluginId correlationId executionId taskId ``` --- # 70. Plugin Events Plugin 必须使用： ```ts context.eventBus.publish(...) ``` Event 自动补充： ```text pluginId ``` --- # 71. Plugin Health ```ts interface PluginHealth { status: | 'healthy' | 'degraded' | 'unhealthy' message?: string checks?: HealthCheck[] } ``` 例如： ```text SEO Plugin ├── Database healthy ├── Search API healthy ├── Browser MCP degraded └── AI Provider healthy ``` --- # 72. Plugin Health Event 自动产生： ```text plugin.health.changed plugin.health.failed plugin.health.recovered ``` --- # 73. Plugin Observability Plugin 的： ```text Action Task Job Execution Event Log Audit Trace Metric ``` 全部自动带： ```text pluginId ``` 这样可以统计： ```text Plugin usage Plugin errors Plugin latency Plugin cost Plugin health ``` --- # 74. Plugin Metrics 自动生成： ```text devos_plugin_action_total devos_plugin_error_total devos_plugin_execution_duration_ms devos_plugin_task_total devos_plugin_mcp_request_total devos_plugin_cost_total ``` --- # 75. Plugin Audit 例如： ```text plugin.installed plugin.enabled plugin.disabled plugin.upgraded plugin.uninstalled plugin.configured ``` 都必须产生 Audit。 例如： ```text Admin Alice ↓ core.plugin.enable ↓ devos.seo ↓ SUCCESS ``` --- # 76. Plugin UI Permission Plugin 页面不能因为已经加载就绕过权限。 例如： ```text SEO Settings ``` 必须： ```text plugin.view + plugin.configure ``` --- # 77. Plugin Dynamic UI 前端需要： ```text Plugin Manifest ↓ UI Registry ↓ Route Registry ↓ Navigation Registry ↓ Dynamic Module ``` --- # 78. Frontend Plugin Package 推荐： ```text packages/plugins/seo/ ├── manifest.ts ├── backend/ │ ├── index.ts │ ├── resources/ │ ├── actions/ │ ├── skills/ │ ├── mcp/ │ └── migrations/ │ └── frontend/ ├── index.ts ├── routes/ ├── pages/ ├── widgets/ └── components/ ``` --- # 79. Plugin Frontend Contract Plugin Frontend 不应该： ```text import backend database import Prisma import Redis ``` 只能使用： ```text Action Client Resource API Query Client UI SDK ``` --- # 80. Plugin UI SDK DevOS 应提供： ```ts interface DevOSPluginUI { registerRoute(...) registerNavigation(...) registerWidget(...) registerDashboard(...) registerSettings(...) } ``` --- # 81. Plugin Action Client 前端： ```ts await devos.actions.execute( 'devos.seo.website.scan', { websiteId } ) ``` 而不是： ```ts fetch('/api/seo/scan') ``` --- # 82. Plugin Resource Client ```ts const websites = await devos.resources.list( 'devos.seo.website' ) ``` --- # 83. Plugin Task UI 异步 Action 返回： ```ts { taskId: 'task_123' } ``` 前端自动进入： ```text Task Detail ``` 可以显示： ```text Progress Jobs Logs Events Execution Result ``` --- # 84. Plugin Chat Integration Plugin 可以向 Agent Chat 注册： ```text context action ``` 例如用户打开： ```text Website: example.com ``` Chat： ```text Ask Agent about this website ``` Agent 自动获得： ```text resource = devos.seo.website resourceId = website_123 ``` --- # 85. Plugin Context Provider ```ts interface PluginContextProvider { getContext( resource: ResourceReference ): Promise } ``` 这样 Agent 可以理解： ```text 当前页面 当前 Resource 当前 Project 当前 Task ``` --- # 86. Plugin Report Plugin 可以注册 Report： ```text SEO Audit Report Server Deployment Report CRM Customer Report ``` Report 应该： ```text Task ↓ Action ↓ Artifact ↓ Report ``` --- # 87. Plugin Artifact Plugin 可以生成： ```text PDF CSV JSON HTML Markdown Image Archive ``` 统一进入： ```text core.artifact ``` 而不是 Plugin 自己管理下载系统。 --- # 88. Plugin API Plugin 可以提供 API，但 API 只是入口。 例如： ```http POST /api/plugins/seo/scan ``` 内部： ```text HTTP ↓ Action Resolver ↓ devos.seo.website.scan ↓ Action Runtime ``` 不能： ```text Controller ↓ Plugin Handler ↓ DB ``` --- # 89. Plugin Webhook Plugin 可以声明： ```text incoming webhook ``` 例如： ```text POST /api/plugins/github/webhook ``` 流程： ```text Webhook ↓ Verify ↓ Normalize ↓ Event ↓ Task / Action ``` --- # 90. Plugin Export / Import Plugin 配置可以导出： ```json { "pluginId": "devos.seo", "version": "1.2.0", "settings": { "defaultModel": "..." } } ``` Secret 不得导出明文。 --- # 91. Plugin Backup 升级 / 卸载前可以： ```text Plugin Data Plugin Settings Plugin Metadata ``` 生成： ```text core.artifact ``` 作为恢复点。 --- # 92. Plugin Marketplace 未来可以实现： ```text Plugin Marketplace ``` 但 Marketplace 不是 Runtime。 Runtime 只负责： ```text Discover Install Verify Load Activate Disable Upgrade Uninstall ``` Marketplace 负责： ```text Search Rating Description Version Download ``` --- # 93. Plugin Signature 未来 Plugin 可以支持： ```text package signature ``` 安装流程： ```text Download ↓ Verify Signature ↓ Verify Checksum ↓ Compatibility ↓ Install ``` 第一阶段可以先实现： ```text checksum ``` --- # 94. Plugin Trust Level 定义： ```ts type PluginTrust = | 'builtin' | 'trusted' | 'verified' | 'community' | 'untrusted' ``` 不同 Trust Level 可以有不同权限。 --- # 95. Plugin Sandbox 第一阶段： ```text Process-level isolation ``` 高级版本： ```text Container Worker Sandbox ``` 但不应该一开始为了“安全”把所有 Plugin 都设计成复杂微服务。 优先保证： ```text Permission Credential Isolation Namespace Isolation Runtime Isolation ``` --- # 96. Plugin Crash Isolation Plugin 激活失败： ```text devos.seo ↓ activation_failed ``` 不能导致： ```text DevOS Core ``` 整体无法启动。 启动策略： ```text Core starts ↓ Load Plugins ↓ Plugin A success Plugin B failed Plugin C success ↓ DevOS remains available ``` --- # 97. Plugin Startup 启动： ```text DevOS Boot ↓ Core Runtime ↓ Database ↓ Redis ↓ Event Runtime ↓ Task Runtime ↓ Action Runtime ↓ Plugin Runtime ↓ Load Plugins ↓ Health Checks ↓ Ready ``` --- # 98. Plugin Shutdown 关闭： ```text Stop accepting new requests ↓ Scheduler pause ↓ Plugin workers drain ↓ Plugin tasks finish ↓ Deactivate plugins ↓ Close Event subscriptions ↓ Close connections ↓ Shutdown Core ``` --- # 99. Plugin Dependency Startup 如果： ```text A → B ``` 启动顺序： ```text B ↓ A ``` 关闭： ```text A ↓ B ``` Dependency Resolver 必须负责排序。 --- # 100. Plugin Registry 与其他 Registry 最终： ```text Plugin Registry │ ├── Resource Registry ├── Action Registry ├── Capability Registry ├── Skill Registry ├── MCP Registry ├── Event Registry ├── Navigation Registry ├── Widget Registry └── Workflow Registry ``` Plugin 是： > Registry 的扩展来源。 不是： > Registry 的替代品。 --- # 101. Plugin 完整模型 最终： ```text Plugin │ ├── Manifest │ ├── Resources │ ├── Actions │ ├── Capabilities │ ├── Skills │ ├── MCP │ ├── Workflows │ ├── Events │ ├── Scheduler │ ├── Workers │ ├── Settings │ ├── Credentials │ ├── UI │ ├── Routes │ ├── Navigation │ ├── Dashboard │ └── Widgets │ └── Runtime ├── Lifecycle ├── Health ├── Logging ├── Metrics └── Tracing ``` --- # 102. Plugin Runtime 与 DevOS 的最终关系 ```text DevOS │ ┌───────┴────────┐ │ │ Core Runtime Plugin Runtime │ ┌──────────────────────┼─────────────────────┐ ↓ ↓ ↓ Plugin A Plugin B Plugin C │ │ │ Resource Resource Resource Action Action Action Skill Skill Skill MCP MCP MCP UI UI UI ``` 所有 Plugin 最终进入： ```text DevOS Runtime ``` --- # 103. SEO Plugin 示例 SEO 不应该成为第二套系统。 应该： ```text DevOS │ └── Plugin: devos.seo ``` 提供： ```text Resources: devos.seo.website devos.seo.keyword devos.seo.article devos.seo.backlink devos.seo.campaign Actions: devos.seo.website.scan devos.seo.keyword.research devos.seo.article.generate devos.seo.backlink.find devos.seo.campaign.run Skills: devos.seo.audit devos.seo.content devos.seo.link-building MCP: search browser cms backlink providers UI: SEO Dashboard Websites Keywords Content Backlinks Campaigns Settings ``` --- # 104. Agent 使用 Plugin 用户： > 给 example.com 做完整 SEO 审计。 Agent： ```text Goal ↓ Capability Discovery ↓ devos.seo.audit Skill ↓ Capabilities ├── website.scan ├── keyword.research ├── page.analyze └── report.generate ↓ Task ↓ Jobs ↓ Actions ↓ Execution ↓ Events ↓ Agent Observation ``` Agent 不需要直接知道： ```text SEO Plugin 内部代码 ``` --- # 105. Plugin 与独立 Backend DevOS 必须支持两种模式。 ## Mode A ```text DevOS ↓ Plugin ↓ Domain ``` 推荐用于： ```text SEO CRM Content Marketing DevOps ``` --- ## Mode B ```text DevOS Minimal Core ↓ Fork ↓ Independent Application ``` 例如： ```text DevOS Starter ↓ Fork ↓ Custom Product ``` 独立项目仍然可以保留： ```text Identity RBAC Resource Action Task Event Audit Observability ``` 但删除不需要的 Plugin。 --- # 106. Plugin 不等于 Microservice 不要把： ```text Plugin ``` 自动理解成： ```text Microservice ``` 默认： ```text Plugin = In-process Extension ``` 只有明确需要： ```text isolation resource-heavy worker different runtime different deployment lifecycle ``` 才使用： ```text External Service ``` --- # 107. External Plugin 未来支持： ```text DevOS ↓ External Plugin Adapter ↓ HTTP / gRPC / MCP ↓ External Service ``` 但外部 Plugin 仍然暴露： ```text Resource Action Capability Skill Event UI ``` 给 DevOS。 --- # 108. Plugin Adapter ```ts interface PluginAdapter { install(): Promise enable(): Promise disable(): Promise uninstall(): Promise health(): Promise } ``` --- # 109. Plugin Runtime API 建议统一： ```ts interface DevOSPlugin { manifest: PluginManifest initialize(context: PluginContext): Promise activate(context: PluginContext): Promise deactivate(context: PluginContext): Promise dispose(context: PluginContext): Promise } ``` --- # 110. Package Architecture Zcode 必须实现： ```text packages/ └── plugin/ ├── types/ │ ├── manifest.ts │ ├── lifecycle.ts │ └── permission.ts │ ├── registry/ │ └── plugin-registry.ts │ ├── runtime/ │ ├── plugin-runtime.ts │ ├── lifecycle.ts │ ├── loader.ts │ ├── activator.ts │ └── disposer.ts │ ├── installer/ │ ├── installer.ts │ ├── resolver.ts │ ├── validator.ts │ └── checksum.ts │ ├── configuration/ │ ├── config-service.ts │ └── secret-service.ts │ ├── isolation/ │ ├── permissions.ts │ └── credentials.ts │ ├── health/ │ └── health-service.ts │ └── ui/ ├── route-registry.ts ├── navigation-registry.ts ├── widget-registry.ts └── dashboard-registry.ts ``` --- # 111. Backend Plugin Example ```text plugins/ └── seo/ ├── plugin.json ├── index.ts │ ├── resources/ │ ├── website.ts │ ├── keyword.ts │ └── article.ts │ ├── actions/ │ ├── scan.ts │ ├── research.ts │ └── generate.ts │ ├── skills/ │ ├── seo-audit.ts │ └── content.ts │ ├── mcp/ │ └── browser.ts │ ├── events/ │ └── definitions.ts │ ├── workflows/ │ └── audit.ts │ ├── migrations/ │ └── frontend/ ├── routes/ ├── pages/ ├── widgets/ └── index.ts ``` --- # 112. Plugin Test 每个 Plugin 必须提供： ```text manifest test lifecycle test registration test permission test configuration test action test event test health test ui registration test upgrade test uninstall test ``` --- # 113. Acceptance Criteria ## Plugin Lifecycle * [ ] Discover * [ ] Install * [ ] Configure * [ ] Enable * [ ] Disable * [ ] Restart * [ ] Upgrade * [ ] Uninstall * [ ] Health ## Registry * [ ] Plugin Registry * [ ] Resource registration * [ ] Action registration * [ ] Capability registration * [ ] Skill registration * [ ] MCP registration * [ ] Event registration * [ ] Workflow registration * [ ] UI registration ## Security * [ ] Permission declaration * [ ] Permission approval * [ ] Credential isolation * [ ] Secret isolation * [ ] Namespace isolation * [ ] Network policy * [ ] Sensitive data redaction ## UI * [ ] Dynamic routes * [ ] Navigation * [ ] Settings page * [ ] Dashboard * [ ] Widgets * [ ] Resource pages * [ ] Action buttons * [ ] Task integration ## Runtime * [ ] Logger * [ ] Metrics * [ ] Trace * [ ] Event * [ ] Health * [ ] Task * [ ] Worker * [ ] Scheduler --- # 114. Integration Test 必须测试： ```text Install Plugin ↓ Manifest Validation ↓ Register Resource ↓ Register Action ↓ Register Skill ↓ Register MCP ↓ Register Event ↓ Register UI ↓ Enable ↓ Health Check ``` 最终： ```text Plugin = healthy ``` --- # 115. Disable Test ```text Plugin enabled ↓ Task running ↓ Disable ↓ Drain ↓ Deactivate ↓ Unregister ↓ Plugin disabled ``` 验证： ```text Existing Task ``` 不会被无故破坏。 --- # 116. Permission Test Plugin 尝试： ```text read secret:github ``` 但只有： ```text secret:openai ``` 必须： ```text ACCESS_DENIED ``` --- # 117. Conflict Test 安装： ```text Plugin A resource = foo.bar ``` 然后： ```text Plugin B resource = foo.bar ``` 必须： ```text RESOURCE_NAMESPACE_CONFLICT ``` --- # 118. Dependency Test ```text Plugin A ↓ Plugin B ``` 安装 A 时： ```text B not installed ``` 应该： ```text Install B ↓ Install A ``` --- # 119. Failure Test Plugin activation： ```text throw Error ``` 必须： ```text Plugin = activation_failed ``` 同时： ```text DevOS = healthy ``` --- # 120. Final Golden Rules ```text 1. Plugin 是扩展，不是第二个 DevOS。 2. Plugin 必须通过 DevOS Runtime 执行业务。 3. Plugin 不创建第二套 Auth。 4. Plugin 不创建第二套 Task。 5. Plugin 不创建第二套 Queue。 6. Plugin 不创建第二套 EventBus。 7. Plugin 不绕过 Action Runtime。 8. Plugin 不绕过 Permission。 9. Plugin 不直接读取 Secret。 10. Plugin UI 不直接执行业务逻辑。 11. Plugin 的 Resource 必须注册到 Resource Registry。 12. Plugin 的 Action 必须注册到 Action Registry。 13. Plugin 的 Capability 必须注册到 Capability Registry。 14. Plugin 的 Skill 必须注册到 Skill Registry。 15. Plugin 的 MCP 必须注册到 MCP Runtime。 16. Plugin 的 Event 必须进入 Event Runtime。 17. Plugin 的 Task 必须进入 Task Runtime。 18. Plugin 的日志必须进入 DevOS Logging Runtime。 19. Plugin 的审计必须进入 DevOS Audit Runtime。 20. Plugin 必须可以独立启停。 21. Plugin 崩溃不能拖垮 DevOS Core。 22. Plugin 卸载默认不删除业务数据。 23. Plugin 升级必须进行兼容性检查。 24. Plugin 必须拥有唯一 Namespace。 25. Agent 看到的是 Capability，而不是 Plugin 内部实现。 26. MCP 是能力接入方式，不是第二套业务 Runtime。 27. SEO / DevOps / CRM 等领域都应该优先实现为 Plugin。 28. 真正需要独立 Backend 的项目，应从 DevOS Minimal Core Fork。 ``` --- # 121. DevOS Plugin 最终模型 最终 DevOS 应该达到： ```text DevOS │ ┌──────────────────┴──────────────────┐ │ │ Core Runtime Plugin Runtime │ │ │ ┌────────────────┼────────────────┐ │ │ │ │ │ SEO Plugin DevOps Plugin CRM Plugin │ │ │ │ │ Resource Resource Resource │ Action Action Action │ Skill Skill Skill │ MCP MCP MCP │ Workflow Workflow Workflow │ Event Event Event │ UI UI UI │ │ │ │ └────────────────────┴────────────────┴────────────────┘ │ Capability Registry │ Agent │ Goal ``` DevOS 的真正扩展方式最终就是： ```text Core + Plugin + Capability + Agent ``` 而不是： ```text Core + SEO Backend + SEO Queue + SEO Agent + SEO MCP + SEO EventBus ``` **这一点必须作为 Zcode 后续所有领域模块开发的架构约束。**