# DevOS Developer Work OS ## Plugin Runtime / Plugin Lifecycle / Extension Platform 设计规范 Version: 1.0 --- # 1. 文档目标 本文定义 DevOS Plugin Runtime。 Plugin Runtime 是 DevOS 最重要的扩展基础设施之一。 目标： > 任何一个成熟能力，都应该能够以 Plugin 的形式安装到 DevOS，而不是修改 DevOS Core。 例如： ```text GitHub Cloudflare Browser Google Search Console Docker Kubernetes SSH SMTP WordPress OpenAI Anthropic ``` 都应该可以成为 Plugin。 Plugin 可以提供： ```text Resource Action Event Skill MCP Workflow Agent Profile UI Navigation Widget Settings Command Context Action ``` 最终： ```text Plugin ↓ Plugin Runtime ↓ Registry ├── Resource Registry ├── Action Registry ├── Capability Registry ├── Skill Registry ├── MCP Registry └── UI Registry ``` --- # 2. Plugin 的核心定义 Plugin： > 一个拥有明确 Manifest、版本、依赖、权限、能力、生命周期和扩展点的 DevOS Extension Package。 Plugin 不是简单的： ```text npm package ``` 也不是简单的： ```text UI module ``` 而是： ```text Code + Manifest + Capabilities + Resources + Actions + UI + Configuration + Permissions + Lifecycle ``` --- # 3. Plugin Architecture 最终： ```text DevOS Core │ Plugin Runtime │ ┌──────────┼──────────┐ │ │ │ Registry Lifecycle Policy │ │ │ └──────────┼──────────┘ │ Installed Plugins │ ┌────────────────┼────────────────┐ │ │ │ GitHub Browser Cloudflare │ │ │ Resource Resource Resource Action Action Action Skill Skill Skill MCP MCP MCP UI UI UI ``` --- # 4. Plugin Manifest 每个 Plugin 必须拥有 Manifest。 推荐： ```ts export interface PluginManifest { id: string; name: string; displayName?: string; description?: string; version: string; author?: string; homepage?: string; license?: string; icon?: string; category?: string; runtime: PluginRuntimeConfig; dependencies?: PluginDependency[]; permissions?: PluginPermission[]; capabilities?: PluginCapabilityRef[]; resources?: PluginResourceRef[]; actions?: PluginActionRef[]; skills?: PluginSkillRef[]; mcp?: PluginMCPConfig; ui?: PluginUIManifest; settings?: PluginSettingsManifest; metadata?: Record; } ``` --- # 5. Plugin ID Plugin ID 必须： - 全局唯一 - 稳定 - 不随版本变化 - 不包含版本号 例如： ```text github browser cloudflare docker kubernetes wordpress ``` 禁止： ```text github-v2 github-2026 github-plugin-new ``` 版本由： ```text version ``` 单独管理。 --- # 6. Plugin Namespace 所有 Plugin 产生的资源、Action、Skill 必须拥有 namespace。 例如： ```text github.repository github.issue github.pull_request github.repository.create github.issue.create github.code_review ``` Browser： ```text browser.session browser.page browser.open browser.navigate browser.research ``` 禁止 Plugin 创建： ```text user settings task agent ``` 这种容易与 Core 冲突的全局 ID。 --- # 7. Plugin 类型 Plugin Runtime 支持不同类型。 ```ts type PluginType = | "integration" | "provider" | "automation" | "developer" | "ai" | "storage" | "ui" | "composite"; ``` 例如： ```text GitHub → integration OpenAI → provider Browser → automation Docker → developer SEO Analyzer → ai ``` 大多数 Plugin 可以使用： ```text composite ``` 因为同时包含： ```text Resource Action Skill UI MCP ``` --- # 8. Plugin Source Plugin 来源： ```ts type PluginSource = | "builtin" | "local" | "workspace" | "marketplace" | "git" | "npm" | "url"; ``` 例如： ```text DevOS Core Plugin → builtin 本地开发插件 → local 公司内部插件 → workspace Marketplace → marketplace ``` --- # 9. Plugin Installation 安装流程： ```text Install Plugin ↓ Resolve Manifest ↓ Check Version ↓ Resolve Dependencies ↓ Check Compatibility ↓ Validate Permissions ↓ Install Package ↓ Register Plugin ↓ Run Migration ↓ Initialize ↓ Enable ``` 必须支持： ```text Install Uninstall Enable Disable Upgrade Rollback ``` --- # 10. Plugin 状态机 Plugin 状态： ```ts type PluginStatus = | "available" | "installing" | "installed" | "enabling" | "enabled" | "disabling" | "disabled" | "upgrading" | "failed" | "uninstalling"; ``` 状态转换： ```text available ↓ installing ↓ installed ↓ enabling ↓ enabled ``` 禁用： ```text enabled ↓ disabling ↓ disabled ``` 升级： ```text enabled ↓ upgrading ↓ enabled ``` 失败： ```text installing ↓ failed ``` --- # 11. Plugin Lifecycle Plugin 生命周期： ```text Discovery ↓ Install ↓ Validate ↓ Load ↓ Initialize ↓ Enable ↓ Running ↓ Disable ↓ Unload ↓ Uninstall ``` Plugin Runtime 必须提供生命周期 Hook： ```ts interface PluginLifecycle { onInstall?(ctx: PluginContext): Promise; onLoad?(ctx: PluginContext): Promise; onInitialize?(ctx: PluginContext): Promise; onEnable?(ctx: PluginContext): Promise; onDisable?(ctx: PluginContext): Promise; onUnload?(ctx: PluginContext): Promise; onUninstall?(ctx: PluginContext): Promise; } ``` --- # 12. Install 与 Enable 必须分离 这是非常重要的设计。 安装： ```text Package exists ``` 启用： ```text Plugin is active ``` 例如： ```text GitHub Plugin Status: Installed ``` 但： ```text Enabled: false ``` 此时： ```text Resource Action Skill MCP UI ``` 都不应该正常提供运行能力。 --- # 13. Disable Plugin Disable 后： ```text Plugin ↓ Unregister Runtime Capabilities ↓ Unregister UI ↓ Stop Background Jobs ↓ Stop Event Subscriptions ↓ Close Connections ``` 但是： > Plugin 数据默认不能删除。 例如： ```text GitHub Plugin disabled ``` 以下仍然存在： ```text github.repository github.issue historical executions audit logs settings credentials references ``` 只是新的运行能力不可用。 --- # 14. Uninstall Plugin Uninstall 是更危险的操作。 默认： ```text Uninstall ≠ Delete Plugin Data ``` 推荐： ```text Uninstall Plugin ↓ Disable ↓ Unload ↓ Remove Runtime ↓ Keep Data ``` 用户明确选择： ```text Delete Plugin Data ``` 才执行数据删除。 --- # 15. Plugin Data Policy Manifest 可以定义： ```ts interface PluginDataPolicy { canDeleteData: boolean; dataResources?: string[]; preserveOnUninstall?: boolean; } ``` 默认： ```text preserveOnUninstall = true ``` 防止误删数据。 --- # 16. Plugin Dependencies Plugin 可以依赖其他 Plugin。 例如： ```text SEO Plugin ↓ Browser Plugin ↓ Browser Runtime ``` Manifest： ```ts { dependencies: [ { pluginId: "browser", version: "^1.0.0", optional: true } ] } ``` --- # 17. Dependency Types 支持： ```text required optional peer ``` 例如： ```text required: github optional: browser peer: ai provider ``` --- # 18. Dependency Resolution 安装： ```text Install SEO Plugin ``` Runtime： ```text SEO ↓ Browser >= 1.2 ↓ AI Provider >= 2.0 ``` 如果依赖缺失： ```text Dependency missing ``` 应该明确提示： ```text SEO Plugin requires Browser Plugin >= 1.2 [Install Dependency] ``` 而不是启动后才报错。 --- # 19. Dependency Cycle 必须检测： ```text Plugin A ↓ Plugin B ↓ Plugin A ``` 禁止循环依赖。 安装时直接失败： ```text PLUGIN_DEPENDENCY_CYCLE ``` --- # 20. Compatibility Plugin Manifest 可以声明： ```ts interface PluginRuntimeConfig { devosVersion?: string; nodeVersion?: string; runtimeVersion?: string; } ``` 例如： ```text DevOS >= 1.5 < 2.0 ``` 如果当前版本不兼容： ```text PLUGIN_INCOMPATIBLE ``` 禁止强制启动。 --- # 21. Plugin Version 遵循 SemVer： ```text MAJOR.MINOR.PATCH ``` 例如： ```text 1.0.0 1.2.0 1.2.3 2.0.0 ``` 规则： ```text PATCH Bug fix MINOR Backward compatible feature MAJOR Breaking change ``` --- # 22. Plugin Upgrade 升级： ```text Current: github 1.4.0 Target: github 1.5.0 ``` 流程： ```text Check ↓ Backup Metadata ↓ Disable ↓ Migration ↓ Load New Version ↓ Validate ↓ Enable ``` 如果失败： ```text Rollback ``` --- # 23. Migration Plugin 可以定义 Migration： ```ts interface PluginMigration { version: string; up(ctx: MigrationContext): Promise; down?(ctx: MigrationContext): Promise; } ``` 例如： ```text 1.0.0 ↓ 1.1.0 ↓ 1.2.0 ``` 执行： ```text 1.0 → 1.1 1.1 → 1.2 ``` 而不是直接假设数据库已经是最新状态。 --- # 24. Migration 原则 Migration 必须： - 可追踪 - 幂等 - 有版本 - 有日志 - 可失败恢复 - 不直接依赖 UI 禁止： ```text Plugin startup ↓ 偷偷修改 DB ``` 所有结构变化必须通过 Migration。 --- # 25. Plugin Runtime Context Plugin 不应该直接访问整个 DevOS Runtime。 提供： ```ts interface PluginContext { pluginId: string; version: string; logger: Logger; config: PluginConfigService; registry: PluginRegistry; events: EventBus; actions: ActionRuntime; resources: ResourceRuntime; tasks: TaskRuntime; secrets: SecretReferenceService; storage: PluginStorage; permissions: PermissionService; } ``` --- # 26. Plugin Registry Plugin Registry： ```ts interface PluginRegistry { register(plugin: Plugin): Promise; unregister(pluginId: string): Promise; get(pluginId: string): Plugin | undefined; list(): Plugin[]; enable(pluginId: string): Promise; disable(pluginId: string): Promise; } ``` --- # 27. Plugin Registry 不等于 Capability Registry 必须区分： ```text Plugin Registry ``` 负责： ```text Plugin 是否安装 Plugin 是否启用 Plugin 版本 Plugin 状态 Plugin 依赖 ``` 而： ```text Capability Registry ``` 负责： ```text Plugin 提供什么能力 ``` 关系： ```text Plugin Registry ↓ Plugin ↓ Capability Registry ↓ Capabilities ``` --- # 28. Plugin 注册 Resource Plugin： ```ts registerResource({ id: "github.repository" }); ``` 最终： ```text Resource Registry ``` 获得： ```text github.repository ``` --- # 29. Plugin 注册 Action ```ts registerAction({ id: "github.repository.create" }); ``` 最终： ```text Action Registry ``` 获得： ```text github.repository.create ``` 执行： ```text Action Runtime ``` --- # 30. Plugin 注册 Skill ```ts registerSkill({ id: "github.code_review" }); ``` 最终： ```text Skill Registry ``` Agent 自动可以发现： ```text github.code_review ``` 无需修改 Agent Runtime。 --- # 31. Plugin 注册 MCP Plugin 可以提供 MCP： ```ts mcp.registerServer({ id: "github", tools: [...] }); ``` 但 MCP Tool 最终必须： ```text MCP ↓ Capability ↓ Action Runtime ``` 禁止： ```text MCP Tool ↓ 直接 DB/API ``` --- # 32. Plugin 注册 UI Plugin 可以注册： ```text Route Navigation Widget Settings Command Context Action ``` 通过： ```text UI Registry ``` 而不是修改： ```text Core React Source ``` --- # 33. Plugin Settings 每个 Plugin 可以定义： ```ts interface PluginSettingsManifest { schema: JSONSchema; scopes?: ( | "global" | "organization" | "project" | "user" )[]; ui?: SettingsUIConfig; } ``` 例如 GitHub： ```text Global: GitHub API URL Organization: Default GitHub Organization User: OAuth Account ``` --- # 34. Configuration Scope 配置支持： ```text Global Organization Project User Environment ``` 优先级： ```text Global ↓ Organization ↓ Project ↓ Environment ↓ User ``` 具体优先级必须由配置系统统一定义。 Plugin 不应该自己实现一套配置优先级。 --- # 35. Plugin Secrets Plugin 需要： ```text API Key OAuth Token Private Key Webhook Secret ``` 只能使用： ```text Secret Reference ``` 例如： ```ts { githubToken: { secretRef: "secret://github/token" } } ``` 禁止在 Manifest 中保存： ```text token: "ghp_xxx" ``` --- # 36. Credential Connection 推荐建立： ```text Connection ``` 抽象。 例如： ```text GitHub Connection Cloudflare Connection OpenAI Connection AWS Connection ``` Plugin 使用： ```ts connectionId ``` 而不是直接获取明文 Token。 --- # 37. Plugin Permissions Plugin 本身必须声明需要什么权限。 例如： ```text github.repository.read github.repository.write network.outbound secret.read filesystem.read ``` Manifest： ```ts permissions: [ "network.outbound", "secret.read" ] ``` --- # 38. Permission Approval 安装 Plugin： ```text GitHub Plugin requests: ✓ Network Access ✓ Secret Access ✓ Repository Read ✓ Repository Write ``` 用户/管理员： ```text [Allow] [Cancel] ``` 对于 Organization： ```text 只有 Org Admin ``` 可以批准 Organization Scope 权限。 --- # 39. Plugin Permission 不等于 User Permission 必须区分： ```text Plugin Permission ``` 与： ```text User Permission ``` 例如： ```text Plugin: network.outbound User: github.repository.read ``` 两者都必须满足： ```text Plugin allowed + User allowed ``` Action 才能执行。 --- # 40. Permission Chain 完整权限： ```text User ↓ Organization Policy ↓ Plugin Permission ↓ Action Permission ↓ Resource Scope ↓ Action Runtime ``` 任何一层拒绝： ```text DENIED ``` --- # 41. Plugin Isolation Plugin 默认应该是： ```text Capability Isolation ``` 而不是： ```text 完全信任 ``` Plugin 不应该自动获得： ```text 所有 DB 所有 Secrets 所有 Filesystem 所有 Network 所有 Actions ``` --- # 42. Plugin Storage Plugin 如果需要自己的数据： ```text PluginStorage ``` 例如： ```text plugin_data/github/* plugin_data/browser/* ``` 推荐： ```ts storage.get() storage.set() storage.delete() storage.query() ``` 而不是： ```ts plugin ↓ 直接 Prisma ``` --- # 43. Plugin Database 对于大型 Plugin，可以声明自己的数据库模型： ```text github.repository github.issue ``` 但这些仍然必须通过： ```text Resource Registry ``` 暴露。 Plugin 内部可以使用 Prisma Repository。 但是： > UI / Agent / MCP / API 不允许绕过 Resource/Action Runtime。 --- # 44. Plugin Background Jobs Plugin 可以创建： ```text Task Job Scheduler ``` 例如 GitHub Plugin： ```text Every 10 minutes ↓ Sync Repositories ``` 但是： ```text Plugin ↓ Task Runtime ↓ Job Queue ``` 禁止自己偷偷创建第二套 Queue。 --- # 45. Plugin Event Subscription Plugin 可以订阅： ```text Event Bus ``` 例如： ```text github.pull_request.created ``` 或者： ```text task.completed ``` 注册： ```ts events.subscribe( "task.completed", handler ); ``` --- # 46. Plugin Event 发布 Plugin 也可以发布： ```text github.repository.synced github.pull_request.updated ``` 事件必须： ```ts { id, type, source, timestamp, actor, organizationId, projectId, payload } ``` --- # 47. Event 与 Action 推荐： ```text Action ↓ Execution ↓ Event ``` 例如： ```text github.repository.sync ↓ Execution completed ↓ github.repository.synced ``` 其他 Plugin 可以监听。 --- # 48. Plugin Health Check Plugin Runtime 必须支持： ```text Health Status Diagnostics ``` 例如： ```text GitHub Plugin Status: Healthy Connection: Connected API: OK Last Sync: 2 min ago ``` --- # 49. Plugin Health Contract ```ts interface PluginHealth { status: | "healthy" | "degraded" | "unhealthy" | "unknown"; message?: string; checks?: HealthCheck[]; } ``` --- # 50. Plugin Diagnostics 管理员可以看到： ```text Plugin ├── Version ├── Status ├── Dependencies ├── Permissions ├── Configuration ├── Connections ├── Health ├── Events ├── Tasks ├── Errors └── Logs ``` --- # 51. Plugin Logs Plugin Logger： ```ts logger.info(...) logger.warn(...) logger.error(...) logger.debug(...) ``` 日志必须包含： ```text pluginId requestId executionId taskId organizationId ``` 这样可以追踪： ```text User ↓ Agent ↓ Plugin ↓ Action ↓ Execution ``` --- # 52. Plugin Metrics Plugin 可以产生： ```text Counters Gauges Histograms ``` 例如： ```text github.api.requests github.api.errors github.sync.duration github.repositories.synced ``` 统一进入： ```text Observability Runtime ``` --- # 53. Plugin Rate Limit Plugin Action 可以声明： ```ts rateLimit: { requests: 100, window: "1m" } ``` 但真正的 Rate Limit 应由： ```text Action Runtime ``` 统一执行。 Plugin 只是声明策略。 --- # 54. Plugin Timeout Action 可以声明： ```text timeoutMs ``` 例如： ```text browser.navigate timeout: 30s ``` 最终由： ```text Action Runtime ``` 执行。 --- # 55. Plugin Retry Plugin 可以声明： ```ts retry: { maxAttempts: 3, backoff: "exponential" } ``` 但： > Retry 由 Task / Action Runtime 管理。 Plugin 不应该自己写： ```text while retry... ``` 形成第二套执行系统。 --- # 56. Plugin Error Isolation Plugin 错误： ```text GitHub API failed ``` 不能导致： ```text DevOS Core failed ``` 错误必须被包装为： ```text PluginError ``` 例如： ```ts { code: "GITHUB_API_RATE_LIMIT", pluginId: "github", retryable: true } ``` --- # 57. Plugin UI Error Isolation 前端： ```text Plugin UI ↓ Error Boundary ``` 如果： ```text GitHub UI crashed ``` 只能影响： ```text GitHub UI ``` 不能导致： ```text 整个 Shell 崩溃 ``` 具体 UI 规范见： ```text 07_UI_SHELL_APP_MODULE.md ``` --- # 58. Plugin API Plugin Runtime 对开发者提供： ```ts definePlugin({ manifest, lifecycle, resources, actions, skills, mcp, ui, settings }); ``` 例如： ```ts export default definePlugin({ manifest: { id: "github", name: "GitHub", version: "1.0.0" }, resources: [ repositoryResource ], actions: [ createRepositoryAction ], skills: [ codeReviewSkill ] }); ``` --- # 59. Plugin SDK 建议： ```text packages/plugin-sdk/ ``` 提供： ```text definePlugin() defineResource() defineAction() defineSkill() defineWidget() definePage() defineCommand() defineContextAction() defineSettings() defineMCP() ``` Plugin 开发者不需要知道 DevOS 内部实现。 --- # 60. Plugin SDK 原则 SDK 应该： ```text 简单 稳定 类型安全 版本化 ``` Plugin 不应该依赖： ```text packages/internal/* ``` 只能依赖： ```text @devos/plugin-sdk ``` 以及明确公开的 SDK Package。 --- # 61. Plugin API Version Plugin API 必须版本化： ```text Plugin SDK v1 Plugin SDK v2 ``` Manifest： ```ts apiVersion: "1" ``` Core 可以同时兼容： ```text v1 v2 ``` --- # 62. Plugin Marketplace 未来可以提供： ```text Plugin Marketplace ``` Plugin 信息： ```text Name Description Version Author License Downloads Rating Compatibility Permissions Dependencies ``` 但 Marketplace 不是 Plugin Runtime 的必要依赖。 DevOS 即使完全离线： ```text local plugin ``` 也应该正常工作。 --- # 63. Plugin Signature 生产环境推荐支持： ```text Plugin Signature ``` 安装： ```text Package ↓ Signature Verification ↓ Trusted Publisher ↓ Install ``` 管理员可以设置： ```text Only trusted plugins ``` --- # 64. Plugin Security Policy Organization 可以设置： ```text Allowed Plugins Denied Plugins Allowed Publishers Required Signature Required Approval Allowed Permissions ``` 例如： ```text 禁止所有 Plugin 使用 filesystem.write ``` 即使 Plugin Manifest 声明： ```text filesystem.write ``` 也必须被： ```text Organization Policy ``` 拒绝。 --- # 65. Plugin Environment Plugin 可以区分： ```text development staging production ``` 例如： ```text GitHub Plugin ``` 不同环境使用不同 Connection。 Plugin 不应该自己实现： ```text if production ... ``` 而使用： ```text Environment Context ``` --- # 66. Multi-Tenant DevOS 支持： ```text Organization A Organization B ``` 同一个 Plugin 可以： ```text Installed once ``` 但是： ```text Configuration Credentials Permissions Resources Tasks ``` 必须支持 Organization Scope。 例如： ```text GitHub Plugin ├── Org A │ └── GitHub Connection A │ └── Org B └── GitHub Connection B ``` 禁止跨 Organization 泄露。 --- # 67. Plugin Resource Ownership Resource： ```text github.repository ``` 必须有： ```text organizationId projectId ``` 或者明确的 Scope。 Resource Runtime 必须检查： ```text Actor + Organization + Project + Resource ``` --- # 68. Plugin Runtime 与 Agent Agent 不直接读取： ```text Plugin ``` 而读取： ```text Capability Registry ``` 例如： ```text Install GitHub Plugin ↓ github.repository.create ↓ Capability Registry ↓ Agent Discovery ``` Agent 无需修改。 --- # 69. Plugin Runtime 与 MCP MCP： ```text Plugin ↓ MCP Server ↓ Capability ↓ Action Runtime ``` External MCP： ```text External MCP ↓ MCP Client ↓ Capability Adapter ↓ DevOS Runtime ``` 统一模型。 --- # 70. Plugin Runtime 与 UI Plugin： ```text Plugin Manifest ↓ UI Manifest ↓ UI Registry ↓ Route Navigation Widget Settings Command Context Action ``` 见： ```text 07_UI_SHELL_APP_MODULE.md ``` --- # 71. Plugin Runtime 与 Task Plugin 不创建： ```text PluginTask PluginQueue PluginWorker ``` 而使用： ```text Task Runtime Job Runtime Queue Runtime Worker Runtime ``` 例如： ```text GitHub Sync ↓ Task ↓ Jobs ↓ Workers ``` --- # 72. Plugin Runtime 与 Scheduler Plugin 可以声明： ```ts schedule({ id: "github.sync", cron: "*/10 * * * *", actionId: "github.repository.sync" }); ``` Scheduler 创建： ```text Task ``` 而不是 Plugin 自己执行。 --- # 73. Plugin Runtime 与 Audit 所有 Plugin Action 自动进入： ```text Audit Runtime ``` 例如： ```text User ↓ Agent ↓ github.repository.delete ↓ Action Runtime ↓ Audit ``` 记录： ```text Actor Plugin Action Resource Input Summary Result Timestamp Execution ``` --- # 74. Plugin Runtime 与 Observability 统一： ```text Logs Metrics Traces Audit Execution ``` 可以查询： ```text Plugin: github ``` 看到： ```text Requests Errors Actions Tasks Executions Latency External API Calls ``` --- # 75. Plugin Runtime API 推荐： ```text POST /api/plugins/install POST /api/plugins/:id/enable POST /api/plugins/:id/disable POST /api/plugins/:id/upgrade DELETE /api/plugins/:id GET /api/plugins GET /api/plugins/:id GET /api/plugins/:id/health GET /api/plugins/:id/logs GET /api/plugins/:id/metrics ``` 但是 Controller 不实现 Plugin 业务逻辑。 统一进入： ```text Plugin Runtime ``` --- # 76. Plugin Service Backend： ```text packages/plugin/ ``` 推荐： ```text plugin/ ├── plugin-registry.ts ├── plugin-loader.ts ├── plugin-installer.ts ├── plugin-lifecycle.ts ├── plugin-validator.ts ├── plugin-dependency.ts ├── plugin-migration.ts ├── plugin-config.ts ├── plugin-permission.ts ├── plugin-health.ts ├── plugin-storage.ts ├── plugin-security.ts └── plugin-runtime.ts ``` --- # 77. Plugin Loader Loader 负责： ```text Locate Package ↓ Load Manifest ↓ Validate Manifest ↓ Load Module ↓ Verify SDK Version ↓ Create Plugin Context ``` 禁止 Loader： ```text 直接执行任意未知代码 ``` 必须经过： ```text Security Policy ``` --- # 78. Plugin Installer Installer： ```text Resolve Source ↓ Download / Copy ↓ Verify Signature ↓ Verify Integrity ↓ Resolve Dependencies ↓ Install ↓ Migration ``` --- # 79. Plugin Runtime Directory 推荐： ```text plugins/ ├── installed/ │ ├── github/ │ ├── browser/ │ └── cloudflare/ │ ├── cache/ │ └── manifests/ ``` 具体路径可由部署环境配置。 不要将 Plugin 代码直接混入： ```text packages/core/ ``` --- # 80. Built-in Plugin 部分 Plugin 可以随 DevOS 一起发布： ```text Core ├── identity ├── notification ├── task ├── agent └── audit ``` 但推荐仍然遵循： ```text Plugin Contract ``` 这样： ```text Built-in Plugin ``` 与： ```text External Plugin ``` 使用相同生命周期。 --- # 81. Core Plugin 与真正 Core Core 必须保持最小化。 真正不可替代的： ```text Runtime Database Auth Action Resource Task Event Plugin ``` 属于： ```text Core ``` 可插拔功能： ```text GitHub Browser Cloudflare Docker WordPress ``` 属于： ```text Plugin ``` --- # 82. Composite Plugin Plugin 可以依赖多个 Plugin： ```text SEO Automation Plugin ├── Browser Plugin ├── Search Plugin └── AI Plugin ``` 但 Composite Plugin 不应该复制这些能力。 它只负责： ```text Workflow Skill Agent Profile UI ``` 调用： ```text Browser Search AI ``` 提供的 Capability。 --- # 83. Plugin 与 App 的关系 App： ```text 产品/业务领域 ``` Plugin： ```text 扩展能力 ``` 例如： ```text SEO App ``` 可以使用： ```text Browser Plugin Search Plugin GSC Plugin WordPress Plugin ``` App 不应该把这些功能复制进自己代码。 --- # 84. 一个 Plugin 可以服务多个 App 例如： ```text Browser Plugin ``` 同时服务： ```text SEO App Content App Research App DevOps App Agent ``` 架构： ```text Browser Plugin ↓ Capability Registry ↓ SEO Content Research Agent ``` 这也是 DevOS 最重要的复用价值之一。 --- # 85. Plugin Discovery Agent / UI / Developer 都可以发现： ```text Installed Plugins Available Plugins Plugin Capabilities ``` 例如： ```text Search: browser ``` 返回： ```text Browser Plugin Capabilities: browser.open browser.navigate browser.screenshot Skills: browser.research ``` --- # 86. Plugin Marketplace 不应该成为 Runtime Marketplace： ```text 发现 下载 评分 安装 ``` Plugin Runtime： ```text 加载 运行 启停 配置 权限 生命周期 ``` 两者必须分离。 --- # 87. Plugin Failure Recovery 如果 Plugin 启动失败： ```text Plugin ↓ Initialize ↓ FAILED ``` Runtime 应： ```text Mark failed ↓ Unregister capabilities ↓ Stop background tasks ↓ Record error ↓ Notify administrator ``` 不要： ```text 不断自动重启 ``` 除非明确配置 Retry Policy。 --- # 88. Plugin Dependency Failure 例如： ```text SEO Plugin ↓ Browser Plugin ↓ Browser failed ``` SEO Plugin 可以变成： ```text degraded ``` 而不是： ```text 整个 DevOS failed ``` --- # 89. Plugin Disable Impact Disable Plugin 时必须计算： ```text Dependent Plugins ``` 例如： ```text Browser Plugin ``` 被使用： ```text SEO Plugin Research Plugin ``` 系统应提示： ```text Disabling Browser will affect: SEO Plugin Research Plugin [Continue] [Cancel] ``` --- # 90. Plugin Upgrade Impact 升级时同样检查： ```text Dependent Plugins ``` 如果： ```text GitHub 2.0 ``` 不兼容： ```text GitHub Automation Plugin ``` 必须阻止升级或进入兼容升级流程。 --- # 91. Plugin State Persistence Plugin 状态必须持久化： ```text installed enabled version configuration permissions dependencies health ``` DevOS 重启： ```text Database ↓ Plugin Registry ↓ Restore Plugin State ↓ Load ↓ Enable ``` --- # 92. Plugin Installation Transaction 安装过程应该尽量具有事务语义： ```text Validate ↓ Install ↓ Migration ↓ Register ↓ Enable ``` 如果中途失败： ```text Rollback ``` 避免： ```text Package installed + DB migrated + Plugin unusable ``` --- # 93. Plugin Lock File 生产环境建议支持： ```text devos.plugins.lock ``` 记录： ```text pluginId version source integrity dependencies ``` 作用： ```text Development → lock Production → reproducible install ``` --- # 94. Plugin Development Mode 开发模式： ```text devos plugin dev ``` 支持： ```text Hot Reload Manifest Reload UI Reload Logs Diagnostics ``` 开发 Plugin： ```text /home/dev/plugins/my-plugin ``` 直接注册。 --- # 95. Plugin CLI 建议提供： ```text devos plugin list devos plugin install github devos plugin uninstall github devos plugin enable github devos plugin disable github devos plugin upgrade github devos plugin doctor github devos plugin create my-plugin ``` CLI 必须调用： ```text Plugin Runtime ``` 不能实现另一套 Plugin 管理逻辑。 --- # 96. Plugin Doctor 例如： ```text devos plugin doctor github ``` 输出： ```text Plugin: github 1.4.0 ✓ Manifest ✓ DevOS compatibility ✓ Dependencies ✓ Permissions ✓ Database ✓ Configuration ✓ Connection Health: Healthy ``` --- # 97. Plugin Admin UI DevOS： ```text /settings/plugins ``` 显示： ```text Plugins GitHub Enabled v1.4.0 Healthy Browser Enabled v2.1.0 Healthy Cloudflare Disabled v1.0.2 ``` 操作： ```text Enable Disable Upgrade Configure Health Logs ``` --- # 98. Plugin Detail UI Plugin Detail： ```text GitHub Plugin ──────────────────────── Version 1.4.0 Status Enabled Health Healthy Capabilities 18 Resources 5 Actions 11 Skills 2 MCP 1 Permissions 4 Dependencies 1 [Disable] [Upgrade] [Settings] ``` --- # 99. Plugin Runtime 与 UI Registry 的生命周期 启用： ```text Plugin Enable ↓ Register Resource ↓ Register Action ↓ Register Skill ↓ Register MCP ↓ Register Route ↓ Register Navigation ↓ Register Widget ↓ Register Command ↓ Register Context Action ``` 禁用： ```text Plugin Disable ↓ Stop Jobs ↓ Unsubscribe Events ↓ Close Connections ↓ Unregister UI ↓ Unregister MCP ↓ Unregister Skills ↓ Unregister Actions ↓ Unregister Resources ``` --- # 100. Plugin Registry Consistency Plugin Registry 与其他 Registry 必须保持一致。 例如： ```text Plugin disabled ``` 不能出现： ```text Plugin Registry: disabled Action Registry: github.repository.create ← still active ``` 必须： ```text Plugin disabled ↓ All Plugin-owned registrations inactive ``` --- # 101. Ownership 所有 Registry Entry 必须记录： ```ts { ownerType: "plugin", ownerId: "github" } ``` 例如： ```text Action: github.repository.create owner: plugin:github ``` 这样 Plugin Disable 时可以准确卸载。 --- # 102. Registration Metadata 建议： ```ts interface RegistrationMetadata { ownerType: | "core" | "app" | "module" | "plugin"; ownerId: string; version?: string; registeredAt: string; } ``` --- # 103. 防止 Plugin 泄漏 如果 Plugin 被卸载： ```text 所有 ownerId = github ``` 的 Registry Entry 都必须被清理。 可以实现： ```ts registry.unregisterByOwner({ ownerType: "plugin", ownerId: "github" }); ``` --- # 104. Plugin Runtime Golden Rule Plugin 可以： ```text 提供能力 注册能力 消费能力 扩展 UI 监听 Event 创建 Task ``` Plugin 不可以： ```text 绕过 Runtime 绕过 Permission 绕过 Audit 绕过 Task Runtime 绕过 Action Runtime 直接修改 Core Registry 直接修改用户数据 ``` --- # 105. 最终 Plugin 执行链 标准业务： ```text User ↓ UI ↓ Action ↓ Action Runtime ↓ Plugin Action ↓ External API ↓ Execution ↓ Event ↓ UI / Agent ``` Agent： ```text User Goal ↓ Agent ↓ Capability Discovery ↓ Plugin Capability ↓ Action ↓ Action Runtime ↓ Plugin ↓ External System ``` MCP： ```text External Agent ↓ MCP Server ↓ Capability ↓ Action Runtime ↓ Plugin ``` --- # 106. 完整 Plugin Example GitHub Plugin： ```text github/ ├── manifest.ts ├── index.ts │ ├── resources/ │ ├── repository.ts │ ├── issue.ts │ └── pull-request.ts │ ├── actions/ │ ├── repository-create.ts │ ├── repository-sync.ts │ ├── issue-create.ts │ └── pull-request-merge.ts │ ├── skills/ │ └── code-review.ts │ ├── mcp/ │ └── server.ts │ ├── ui/ │ ├── repositories.tsx │ ├── issues.tsx │ ├── settings.tsx │ └── widgets/ │ ├── migrations/ │ ├── 1.1.0.ts │ └── 1.2.0.ts │ └── tests/ ``` --- # 107. GitHub Manifest 示例 ```ts export default { id: "github", name: "GitHub", version: "1.0.0", apiVersion: "1", runtime: { devosVersion: ">=1.0.0" }, permissions: [ "network.outbound", "secret.read" ], dependencies: [], resources: [ "github.repository", "github.issue", "github.pull_request" ], actions: [ "github.repository.create", "github.repository.sync", "github.issue.create", "github.pull_request.merge" ], skills: [ "github.code_review" ] }; ``` --- # 108. Plugin Developer Experience 开发者最终应该只需要： ```text devos plugin create github ``` 得到： ```text manifest resources actions skills ui tests ``` 然后： ```text devos plugin dev ``` 即可运行。 发布： ```text devos plugin build devos plugin publish ``` --- # 109. Zcode 必须实现的 Package 至少： ```text packages/plugin/ ├── types/ ├── registry/ ├── runtime/ ├── loader/ ├── installer/ ├── lifecycle/ ├── dependency/ ├── migration/ ├── config/ ├── permissions/ ├── storage/ ├── health/ ├── security/ └── sdk/ ``` --- # 110. Zcode 必须实现的 Backend Services 至少： ```text PluginService PluginRegistry PluginLoader PluginInstaller PluginLifecycleService PluginDependencyService PluginMigrationService PluginConfigService PluginPermissionService PluginHealthService PluginSecurityService PluginStorageService ``` --- # 111. Zcode 必须实现的 API 至少： ```text GET /api/plugins GET /api/plugins/:id POST /api/plugins/install POST /api/plugins/:id/enable POST /api/plugins/:id/disable POST /api/plugins/:id/upgrade DELETE /api/plugins/:id GET /api/plugins/:id/health GET /api/plugins/:id/logs GET /api/plugins/:id/metrics ``` --- # 112. Zcode 必须实现的 UI 至少： ```text /settings/plugins /settings/plugins/:id /settings/plugins/:id/settings /settings/plugins/:id/health /settings/plugins/:id/logs ``` 支持： ```text Install Enable Disable Upgrade Uninstall Configure Health Logs ``` --- # 113. Acceptance Test 01 创建： ```text hello-plugin ``` 安装。 结果： ```text Plugin Registry → hello-plugin installed ``` --- # 114. Acceptance Test 02 Enable： ```text hello-plugin ``` 结果： ```text Action Registry → hello.hello ``` 出现。 --- # 115. Acceptance Test 03 Disable： ```text hello-plugin ``` 结果： ```text hello.hello ``` 不可执行。 同时： ```text Navigation Route Widget ``` 全部消失。 --- # 116. Acceptance Test 04 安装 Plugin： ```text github ``` 自动注册： ```text Resources Actions Skills MCP UI ``` 不修改 Core source。 --- # 117. Acceptance Test 05 卸载： ```text github ``` Plugin Runtime 清理： ```text Routes Navigation Widgets Actions Skills MCP Event Subscriptions Scheduled Jobs ``` 历史： ```text Tasks Executions Audit ``` 仍然保留。 --- # 118. Acceptance Test 06 安装： ```text plugin-a ``` 依赖： ```text plugin-b >= 1.2 ``` 如果没有： ```text Installation blocked ``` 并提示： ```text Missing dependency: plugin-b >= 1.2 ``` --- # 119. Acceptance Test 07 测试循环依赖： ```text A → B B → A ``` 结果： ```text PLUGIN_DEPENDENCY_CYCLE ``` 安装失败。 --- # 120. Acceptance Test 08 测试 Plugin Permission。 Plugin 请求： ```text secret.read ``` 管理员拒绝。 结果： ```text Plugin installed but cannot enable ``` 或者： ```text Plugin capability unavailable ``` 具体策略必须统一。 --- # 121. Acceptance Test 09 测试 Multi-Tenant： ```text Organization A Organization B ``` GitHub Connection： ```text A → Token A B → Token B ``` A 的 Action： ```text github.repository.sync ``` 不能读取 B 的 Connection。 --- # 122. Acceptance Test 10 测试 Plugin Crash。 故意让： ```text github plugin ``` 初始化失败。 结果： ```text GitHub Plugin → failed ``` 但： ```text DevOS Shell → healthy Other Plugins → healthy Core → healthy ``` --- # 123. Acceptance Test 11 测试 Upgrade。 ```text github 1.0.0 ↓ github 1.1.0 ``` 执行： ```text Migration ↓ Registry update ↓ Plugin enable ``` 数据正常。 --- # 124. Acceptance Test 12 Migration 失败。 结果： ```text Upgrade failed ``` 系统不能进入： ```text half-upgraded ``` 状态。 必须进入： ```text failed ``` 或者： ```text rollback ``` --- # 125. Acceptance Test 13 测试 Agent。 安装 GitHub Plugin。 输入： ```text 帮我检查这个 GitHub Repository ``` Agent 能发现： ```text github.repository github.repository.inspect ``` 无需修改 Agent Runtime。 --- # 126. Acceptance Test 14 测试 MCP。 外部 Agent 调用： ```text github_repository_create ``` 执行链必须： ```text MCP ↓ Capability ↓ Action Runtime ↓ Permission ↓ Plugin ↓ GitHub API ↓ Audit ``` 不能： ```text MCP ↓ GitHub API ``` --- # 127. Acceptance Test 15 测试 UI。 安装 GitHub Plugin。 自动出现： ```text Plugins └── GitHub ├── Repositories ├── Issues └── Settings ``` 无需修改： ```text Sidebar.tsx Router.tsx Dashboard.tsx ``` --- # 128. Acceptance Test 16 Plugin 注册 Widget： ```text dashboard.main ``` 启用 Plugin： ```text Widget visible ``` 禁用： ```text Widget invisible ``` --- # 129. Acceptance Test 17 Plugin 注册 Context Action： ```text github.repository ``` 显示： ```text Create Issue ``` 点击： ```text Action Runtime ``` 执行。 --- # 130. Acceptance Test 18 CLI： ```text devos plugin list ``` 与 UI： ```text /settings/plugins ``` 显示完全一致的 Plugin Registry 数据。 CLI 和 UI 不得各自维护状态。 --- # 131. 最终架构 ```text DevOS Core │ Plugin Runtime │ ┌──────────────────────┼──────────────────────┐ │ │ │ Lifecycle Security Registry │ │ │ Install/Enable Permission Plugin Registry Disable/Upgrade Isolation Capability Registry Migration Secrets UI Registry │ │ │ └──────────────────────┼──────────────────────┘ │ Plugin SDK │ ┌──────────────┬───────┼────────┬──────────────┐ │ │ │ │ │ Resource Action Skill MCP UI │ │ │ │ │ └──────────────┴───────┼────────┴──────────────┘ │ DevOS Runtime │ ┌──────────────┬───────┼────────┬──────────────┐ │ │ │ │ │ Resource Action Task Event Agent Runtime Runtime Runtime Bus Runtime ``` --- # 132. Plugin 的最终定位 Plugin 不是： ```text 一个 npm package ``` Plugin 是： ```text DevOS 的能力扩展单元 ``` 一个完整 Plugin 可以同时提供： ```text Resource + Action + Skill + MCP + Workflow + UI + Settings + Widget + Event ``` 并通过统一 Runtime 接入： ```text Auth Permission Task Queue Audit Observability Agent UI ``` --- # 133. 最重要的 Golden Rules ```text 1. Plugin 不修改 Core。 2. Plugin 必须拥有 Manifest。 3. Plugin 必须拥有稳定 ID。 4. Plugin 必须拥有版本。 5. Plugin 必须拥有生命周期。 6. Install ≠ Enable。 7. Disable ≠ Uninstall。 8. Uninstall 默认不删除业务数据。 9. Plugin 必须声明 Dependencies。 10. Plugin 必须声明 Permissions。 11. Plugin Action 必须进入 Action Runtime。 12. Plugin Task 必须进入 Task Runtime。 13. Plugin Event 必须进入 Event Bus。 14. Plugin UI 必须进入 UI Registry。 15. Plugin MCP 不得绕过 Action Runtime。 16. Agent 不直接调用 Plugin。 17. Agent 通过 Capability Registry 使用 Plugin 能力。 18. Plugin 不应该创建自己的 Queue。 19. Plugin 不应该创建自己的权限系统。 20. Plugin 不应该创建自己的 Audit 系统。 21. Plugin 不应该创建自己的 Scheduler。 22. Plugin 不应该创建自己的 Notification 系统。 23. Plugin 不应该直接操作其他 Plugin 的数据。 24. Plugin 必须支持 Organization Scope。 25. Plugin 必须能够被独立禁用。 26. 单个 Plugin 崩溃不能导致 DevOS 崩溃。 27. Core 不应该知道具体 Plugin。 28. App 不应该复制 Plugin 能力。 29. Plugin 应该尽量提供 Capability，而不是绑定某个 App。 30. DevOS 的所有扩展最终都应该回到统一 Runtime。 ``` --- # 134. 最终 DevOS 扩展模型 至此，DevOS 的扩展体系形成： ```text DevOS Core │ ┌───────────────┼────────────────┐ │ │ │ App Plugin Agent │ │ │ Module Capability Goal │ │ │ └───────────────┼────────────────┘ │ Resource / Action │ Action Runtime │ ┌───────────────┼────────────────┐ │ │ │ Task Event Audit │ │ │ Queue Event Bus Observability │ Worker ``` 而 Plugin 自身： ```text Plugin ├── Manifest ├── Resources ├── Actions ├── Skills ├── MCP ├── Workflows ├── Agent Profiles ├── UI ├── Settings ├── Widgets ├── Commands ├── Context Actions ├── Events ├── Migrations ├── Permissions ├── Dependencies └── Configuration ``` 最终实现： > **DevOS Core 负责平台，App 负责业务领域，Plugin 负责可复用能力，Agent 负责动态决策，而所有执行统一经过 Runtime。** 这使 DevOS 真正成为一个可以持续扩展的 **Developer Work OS / Agent Platform**，而不是一个越来越臃肿的 Admin Dashboard。