# 19_PLUGIN_EXTENSION_PACKAGE_RUNTIME.md # DevOS Plugin / Extension / Package Runtime > **版本：v1.0** > **目标：让 DevOS 成为真正可扩展的 Developer Work OS，而不是一个越做越大的单体应用。** > > 本文是 DevOS 第 19 个核心架构升级文档。 > 本文重点解决： > > * Plugin > * Extension > * Package > * Capability > * Resource > * Action > * Skill > * MCP > * UI > * Config > * Event > * Migration > * Permission > * Lifecycle > * Install / Upgrade / Disable / Uninstall > * Plugin Marketplace > * Plugin Sandbox > * Plugin Dependency > * Plugin Version > > **Zcode 必须按照本文实现。** --- # 1. Plugin Runtime 的定位 DevOS 不能把所有功能都放进 Core。 正确架构应该是： ```text DevOS Core │ ┌───────────────┼────────────────┐ │ │ │ Runtime Runtime Runtime │ │ │ Resource Action Event │ │ │ Plugin Runtime / Extension Runtime │ ┌────────────────┼─────────────────┐ │ │ │ Plugin Package MCP │ ┌─────┼──────┬───────┬───────┬─────────┐ │ │ │ │ │ │ Res Action Skill UI Workflow MCP │ │ │ │ │ │ └─────┴──────┴───────┴───────┴─────────┘ ``` Plugin 不是一个简单的 npm package。 Plugin 是 DevOS 中的： > **可安装、可配置、可启停、可升级、可卸载、可审计、可授权、可发现的功能单元。** --- # 2. Plugin 的核心目标 Plugin 必须做到： ```text 安装 ↓ 解析依赖 ↓ 兼容性检查 ↓ Migration ↓ 注册 Resource ↓ 注册 Action ↓ 注册 Skill ↓ 注册 MCP ↓ 注册 Event ↓ 注册 UI ↓ 注册 Config ↓ 注册 Permission ↓ Health Check ↓ Activate ``` 卸载： ```text Disable ↓ 停止新任务 ↓ 等待 / Cancel Running Tasks ↓ 注销 Capability ↓ 停止 Worker ↓ 停止 Event Subscription ↓ 清理 Runtime ↓ Uninstall ``` --- # 3. Plugin、Extension、Package 的区别 这三个概念必须严格区分。 ## Package Package 是代码组织单位。 例如： ```text @devos/plugin-seo @devos/plugin-github @devos/plugin-docker ``` Package 本身不一定是可以安装的 Plugin。 --- ## Extension Extension 是某个 Runtime 的扩展。 例如： ```text ResourceExtension ActionExtension SearchExtension UIExtension EventExtension ``` --- ## Plugin Plugin 是完整的可安装 DevOS 功能。 例如： ```text SEO Plugin GitHub Plugin Docker Plugin Cloudflare Plugin WordPress Plugin ``` 一个 Plugin 可以包含多个 Extension。 --- # 4. Plugin 的完整结构 标准 Plugin： ```text plugin │ ├── manifest │ ├── resources │ ├── actions │ ├── skills │ ├── workflows │ ├── mcp │ ├── events │ ├── providers │ ├── config │ ├── permissions │ ├── ui │ ├── migrations │ ├── workers │ ├── health │ └── assets ``` 例如： ```text plugins/ └── seo/ ├── manifest.ts ├── resources/ │ ├── website.ts │ ├── keyword.ts │ └── backlink.ts │ ├── actions/ │ ├── scan.ts │ ├── analyze.ts │ └── publish.ts │ ├── skills/ │ ├── seo-audit.ts │ └── backlink-building.ts │ ├── mcp/ │ └── server.ts │ ├── workflows/ │ └── content-campaign.ts │ ├── events/ │ └── handlers.ts │ ├── config/ │ └── config.ts │ ├── ui/ │ ├── pages/ │ └── widgets/ │ ├── migrations/ │ └── index.ts ``` --- # 5. Plugin Manifest Manifest 是 Plugin 的唯一正式声明入口。 ```ts export interface PluginManifest { id: string name: string displayName: string version: string apiVersion: string description?: string author?: { name: string url?: string } license?: string devos: { minVersion?: string maxVersion?: string } dependencies?: PluginDependency[] capabilities?: PluginCapabilities config?: ConfigDefinition[] permissions?: PermissionDefinition[] ui?: PluginUIManifest workers?: WorkerDefinition[] metadata?: Record } ``` --- # 6. Plugin ID Plugin ID 必须全局唯一。 推荐： ```text . ``` 例如： ```text devos.github devos.docker devos.cloudflare acme.seo acme.wordpress ``` 禁止： ```text github seo plugin1 test ``` 生产环境 Plugin ID 不允许随意改变。 --- # 7. Plugin Version 使用 SemVer： ```text MAJOR.MINOR.PATCH ``` 例如： ```text 1.0.0 1.2.0 1.2.3 2.0.0 ``` 必须与第 12 文档的版本系统统一。 --- # 8. Plugin API Version Plugin 自己的版本与 DevOS Plugin API 版本分开。 例如： ```ts apiVersion: "2026-01" version: "2.3.1" ``` 含义： ```text Plugin API = DevOS 扩展接口版本 Plugin Version = 这个 Plugin 自己的版本 ``` --- # 9. Plugin Dependency Plugin 可以依赖： ```text Core Runtime 其他 Plugin Provider Capability ``` 定义： ```ts export interface PluginDependency { id: string version: string optional?: boolean reason?: string } ``` 例如： ```ts dependencies: [ { id: "devos.github", version: "^2.0.0", }, ] ``` --- # 10. Dependency Resolver DevOS 必须提供统一 Dependency Resolver。 ```text Plugin A │ ├── Plugin B ^1.0 │ └── Plugin C ^2.0 │ └── Plugin B ^1.5 ``` Resolver： ```text 读取依赖 ↓ 解析 SemVer ↓ 寻找兼容版本 ↓ 构建 Dependency Graph ↓ 检测冲突 ↓ 检测循环依赖 ↓ 生成 Install Plan ``` 必须支持： ```text direct dependency optional dependency peer dependency transitive dependency version conflict cycle detection ``` 不要自己重新实现 SemVer。 --- # 11. Dependency Graph 内部： ```ts export interface PluginDependencyGraph { nodes: PluginDependencyNode[] edges: PluginDependencyEdge[] } ``` 例如： ```text SEO ├── browser ├── github └── content └── llm ``` --- # 12. Plugin Lifecycle Plugin 生命周期： ```text discovered ↓ installed ↓ validating ↓ migrating ↓ registering ↓ activating ↓ active │ ├── disabling │ ↓ │ disabled │ └── upgrading ↓ active active ↓ uninstalling ↓ uninstalled ``` --- # 13. Plugin State ```ts export type PluginStatus = | "discovered" | "installing" | "installed" | "validating" | "migration_running" | "registering" | "activating" | "active" | "degraded" | "disabling" | "disabled" | "upgrading" | "uninstalling" | "failed" | "uninstalled" ``` --- # 14. Plugin Runtime 核心： ```ts export interface PluginRuntime { install(input: PluginInstallInput): Promise validate(pluginId: string): Promise activate(pluginId: string): Promise disable(pluginId: string): Promise upgrade(input: PluginUpgradeInput): Promise uninstall(pluginId: string): Promise get(pluginId: string): Promise list(): Promise health(pluginId: string): Promise } ``` --- # 15. Plugin Registry 所有 Plugin 必须注册到： ```ts PluginRegistry ``` ```ts export interface PluginRegistry { register(plugin: PluginDefinition): Promise unregister(pluginId: string): Promise get(pluginId: string): PluginDefinition | undefined has(pluginId: string): boolean list(): PluginDefinition[] } ``` --- # 16. Plugin Definition ```ts export interface PluginDefinition { manifest: PluginManifest resources?: ResourceDefinition[] actions?: ActionDefinition[] skills?: SkillDefinition[] workflows?: WorkflowDefinition[] mcp?: MCPDefinition[] events?: EventDefinition[] providers?: ProviderDefinition[] config?: ConfigDefinition[] ui?: PluginUIDefinition workers?: WorkerDefinition[] migrations?: MigrationDefinition[] permissions?: PermissionDefinition[] } ``` --- # 17. Plugin Activation Activation 不是简单： ```ts plugin.init() ``` 而必须执行： ```text Plugin Activation │ ├── dependency check │ ├── compatibility check │ ├── config validation │ ├── permission registration │ ├── resource registration │ ├── action registration │ ├── skill registration │ ├── MCP registration │ ├── event registration │ ├── provider registration │ ├── UI registration │ ├── worker registration │ └── health check ``` 全部成功： ```text ACTIVE ``` 否则： ```text DEGRADED / FAILED ``` --- # 18. Registration Transaction Plugin 注册最好具有事务性。 错误： ```text Resource 注册成功 Action 注册成功 Skill 注册成功 UI 注册失败 ``` 结果不能变成半激活状态。 应该： ```text Prepare ↓ Validate ↓ Register ↓ Health Check ↓ Commit ``` 失败： ```text Rollback Registration ``` --- # 19. Capability Registration Plugin 是 Capability 的重要来源。 ```text Plugin │ ├── Resource ├── Action ├── Skill ├── MCP ├── Workflow └── Provider ↓ Capability Registry ↓ Agent ``` 这与第 06 文档完全一致。 --- # 20. Plugin Resource Plugin 可以声明 Resource。 例如： ```ts { id: "seo.website", name: "Website", ... } ``` 但必须经过： ```text Resource Registry ``` 而不是 Plugin 自己维护一套 Resource Registry。 --- # 21. Plugin Action Plugin Action： ```ts { id: "seo.website.scan", resource: "seo.website", ... } ``` 执行： ```text Agent ↓ Capability ↓ ActionRuntime ↓ Plugin Action Handler ``` 禁止： ```text Agent ↓ Plugin ↓ 直接执行代码 ``` --- # 22. Plugin Action Handler ```ts export interface PluginActionHandler { execute( input: TInput, context: ActionContext ): Promise } ``` Action Handler 可以使用： ```text DataRuntime StorageRuntime EventRuntime TaskRuntime ProviderRuntime ConfigRuntime SecretRuntime HTTP Client ``` 但必须通过 DevOS Runtime。 --- # 23. Plugin 不允许直接操作基础设施 禁止： ```ts plugin -> prisma.user.create() plugin -> redis.set() plugin -> websocket.send() plugin -> process.env.API_KEY plugin -> fs.readFile(...) ``` 除非这是被 DevOS 明确授权的 Runtime 内部实现。 Plugin 应该使用： ```ts ctx.data ctx.storage ctx.event ctx.task ctx.config ctx.secret ctx.provider ``` --- # 24. Plugin Context ```ts export interface PluginContext { pluginId: string runtimeVersion: string config: ConfigRuntime data: DataRuntime storage: StorageRuntime events: EventRuntime tasks: TaskRuntime actions: ActionRuntime search: SearchRuntime providers: ProviderRuntime logger: Logger metrics: MetricsRuntime tracing: TracingRuntime } ``` --- # 25. Plugin Config Plugin 不应该自己建立： ```text plugin_settings plugin_config plugin_secrets ``` DevOS 已经有： ```text Configuration Runtime Secret Runtime Provider Runtime Environment Runtime ``` 因此 Plugin 只声明： ```ts config: [...] ``` DevOS 负责： ```text 存储 验证 继承 环境 权限 版本 审计 Secret UI ``` --- # 26. Plugin Secret Plugin： ```ts { id: "github.token", type: "secret" } ``` 实际 Secret： ```text secret://github/default ``` Plugin 永远不应该： ```ts database.query("select secret") ``` --- # 27. Plugin Permission Plugin 可以声明自己的权限。 例如： ```ts permissions: [ { id: "seo.website.read", description: "Read SEO websites" }, { id: "seo.website.scan", description: "Run website scan" }, { id: "seo.website.delete", description: "Delete website" } ] ``` 最终进入统一： ```text Permission Registry ``` --- # 28. Permission Namespace 必须使用 Plugin namespace： ```text seo.website.read seo.website.scan seo.website.delete github.repository.read github.repository.create docker.container.read docker.container.restart ``` 禁止： ```text read write admin scan ``` 这种全局模糊权限。 --- # 29. Plugin UI Plugin 可以拥有自己的页面。 这是 DevOS 非常重要的能力。 例如： ```text SEO ├── Dashboard ├── Websites ├── Keywords ├── Backlinks ├── Content ├── Tasks └── Settings ``` Plugin manifest： ```ts export interface PluginUIManifest { navigation?: NavigationItem[] pages?: PluginPage[] widgets?: PluginWidget[] settings?: PluginSettingsPage[] dashboards?: PluginDashboard[] } ``` --- # 30. Navigation Plugin 可以注册： ```ts { id: "seo", label: "SEO", icon: "Search", path: "/seo" } ``` 子页面： ```text SEO ├── Overview ├── Websites ├── Keywords ├── Backlinks ├── Content └── Settings ``` 但是： > Plugin 不应该修改主 Shell。 Plugin 只能向 UI Shell 注册扩展点。 --- # 31. UI Extension Point DevOS UI Shell 提供： ```text sidebar topbar dashboard resource-list resource-detail resource-actions settings task-detail agent-chat global-search command-palette ``` Plugin 可以注册： ```ts ui.registerExtension({ slot: "resource.detail.sidebar", resource: "seo.website", component: WebsiteHealthWidget }) ``` --- # 32. Plugin Page Plugin 页面： ```ts export interface PluginPage { id: string path: string title: string component: string permission?: string icon?: string layout?: string } ``` 例如： ```text /seo/websites /seo/keywords /seo/backlinks ``` --- # 33. Plugin Widget ```ts export interface PluginWidget { id: string slot: string title?: string component: string priority?: number permission?: string } ``` 例如： ```text dashboard.main task.sidebar agent.context resource.detail ``` --- # 34. Plugin Settings 每个 Plugin 都可以拥有自己的 Settings 页面。 例如： ```text Settings └── Plugins └── SEO ├── General ├── Providers ├── Limits ├── Automation └── Advanced ``` 但是数据仍然来自： ```text Configuration Runtime ``` 而不是 Plugin 自己存储。 --- # 35. Plugin Dashboard Plugin 可以注册 Dashboard。 例如 SEO： ```text SEO Dashboard Websites 128 Keywords 32,420 Backlinks 1,248 Tasks 37 Errors 4 ``` Dashboard 数据必须走： ```text Query / Search / Metrics Runtime ``` 禁止 UI 直接 SQL。 --- # 36. Plugin Event Plugin 可以订阅事件。 例如： ```ts events: [ { type: "seo.website.updated", handler: "..." } ] ``` 或者： ```text core.task.completed core.execution.failed core.file.created ``` Event 统一进入第 16 文档定义的 Event Runtime。 --- # 37. Plugin Event Handler ```ts export interface PluginEventHandler { handle( event: DevOSEvent, context: EventHandlerContext ): Promise } ``` 必须： ```text idempotent retryable audited observable ``` --- # 38. Plugin Worker Plugin 可以提供 Worker。 例如： ```text SEO crawler worker Content processing worker GitHub sync worker ``` 但 Worker 必须注册到： ```text Worker Runtime ``` 而不是 Plugin 自己启动： ```ts setInterval(...) ``` 禁止。 --- # 39. Plugin Scheduler Plugin 可以注册 Schedule： ```text SEO website scan 每天 03:00 ``` 但 Schedule 必须进入： ```text Scheduler Runtime ``` 流程： ```text Scheduler ↓ Task ↓ Job ↓ Queue ↓ Worker ↓ Action ``` Plugin 不允许自己创建 cron daemon。 --- # 40. Plugin Workflow Plugin 可以提供 Workflow Template： ```text SEO Audit ``` 例如： ```text Scan Website ↓ Analyze Technical SEO ↓ Analyze Content ↓ Analyze Backlinks ↓ Generate Report ``` Workflow 使用： ```text Action Runtime Task Runtime Event Runtime ``` --- # 41. Plugin Skill Plugin 可以提供 Skill： ```text seo.audit seo.keyword.research seo.backlink.strategy ``` Skill： ```text Skill ↓ Capability Discovery ↓ Action ``` Plugin 不应该自己实现 Agent Loop。 Agent Runtime 负责 Agent。 --- # 42. Plugin MCP Plugin 可以提供 MCP。 例如： ```text SEO MCP GitHub MCP Docker MCP Cloudflare MCP ``` 但： > MCP 不是第二套执行系统。 MCP 最终： ```text MCP ↓ Capability ↓ Action Runtime ``` --- # 43. Plugin MCP Server ```ts export interface PluginMCPDefinition { id: string name: string version: string tools: MCPToolDefinition[] resources?: MCPResourceDefinition[] } ``` MCP Tool 最终必须映射： ```text MCP Tool ↓ Action ID ↓ Action Runtime ``` --- # 44. Plugin Provider Plugin 可以提供 Provider。 例如： ```text GitHub ├── GitHub API └── GitHub OAuth Cloudflare └── Cloudflare API OpenAI └── OpenAI API ``` Provider 进入： ```text Provider Registry ``` Credential： ```text Credential Runtime ``` Secret： ```text Secret Runtime ``` --- # 45. Plugin External API Plugin 调用第三方 API 时： ```text Plugin Action ↓ Provider Runtime ↓ Credential Resolver ↓ Secret Runtime ↓ HTTP Client ↓ External API ``` 而不是： ```text Plugin ↓ fetch() ↓ process.env.API_KEY ``` --- # 46. Plugin Health 每个 Plugin 必须提供 Health Check。 ```ts export interface PluginHealth { status: "healthy" | "degraded" | "unhealthy" checks: HealthCheckResult[] timestamp: string } ``` 检查： ```text Database Provider Credential External API Worker Queue MCP Configuration ``` --- # 47. Plugin Health 与 Activation Plugin： ```text installed ↓ health check ↓ active ``` 如果 Provider 无法使用： ```text active + degraded ``` 不要因为一个可选 Provider 失败就让整个 Plugin 崩溃。 --- # 48. Optional Capability Plugin 可以声明： ```ts { id: "cloudflare", optional: true } ``` 例如： ```text SEO Plugin ├── Core SEO required ├── OpenAI optional ├── Ahrefs optional └── Semrush optional ``` 没有 Ahrefs： ```text SEO = active Ahrefs capability = unavailable ``` Agent Capability Registry 必须知道： ```text available unavailable degraded ``` --- # 49. Plugin Availability Capability Registry： ```ts export type CapabilityAvailability = | "available" | "unavailable" | "degraded" | "disabled" | "permission_denied" ``` Agent 搜索 Capability 时必须过滤。 --- # 50. Plugin Installation 安装流程： ```text Upload / Marketplace / Git / Package ↓ Read Manifest ↓ Verify Signature ↓ Verify Checksum ↓ Resolve Dependencies ↓ Check DevOS Compatibility ↓ Generate Plan ↓ User Approval ↓ Install ↓ Migration ↓ Registration ↓ Health Check ↓ Activate ``` --- # 51. Install Source 支持： ```text Marketplace Local package Git repository OCI registry Private registry Uploaded archive ``` 生产环境推荐： ```text Immutable package + exact version + checksum ``` --- # 52. Plugin Package 推荐 Plugin Package： ```text devos-plugin-seo-2.3.1.tgz ``` 内部： ```text manifest.json dist/ assets/ migrations/ package metadata checksum signature ``` --- # 53. Plugin Signature 生产环境建议： ```text Package ↓ SHA-256 ↓ Signature ↓ Trusted Publisher ``` Plugin Instance 保存： ```ts interface PluginArtifact { source: string version: string checksum: string signature?: string publisher?: string installedAt: string } ``` --- # 54. Plugin Trust Plugin Trust Level： ```ts export type PluginTrustLevel = | "core" | "official" | "verified" | "community" | "local" | "untrusted" ``` 生产环境可以设置： ```text allow: core official verified deny: untrusted ``` --- # 55. Plugin Sandbox 不能假设所有 Plugin 都可信。 因此 Runtime 必须区分： ```text Trusted Plugin Untrusted Plugin ``` 对于高风险 Plugin，可以限制： ```text filesystem network process child_process environment native modules ``` --- # 56. 推荐的 Plugin 执行模式 第一阶段： ```text Trusted Plugin = same process ``` 优点： ```text 简单 性能高 开发方便 ``` 第二阶段： ```text Sandbox Plugin = isolated process / container ``` 架构： ```text DevOS ↓ Plugin Host ↓ IPC / RPC ↓ Sandbox ``` 不要一开始就为所有 Plugin 强制容器化，否则系统复杂度会大幅增加。 --- # 57. Plugin API Boundary Sandbox Plugin 只能访问： ```text Plugin SDK ↓ RPC ↓ DevOS Runtime ``` 例如： ```text plugin.data.query() plugin.action.execute() plugin.storage.put() plugin.event.publish() plugin.config.get() ``` 而不能： ```text 直接访问 DevOS PostgreSQL 直接访问 Redis 直接读取 Secret ``` --- # 58. Plugin SDK 建议： ```text @devos/plugin-sdk ``` 提供： ```ts createPlugin() defineResource() defineAction() defineSkill() defineWorkflow() defineMCP() defineProvider() defineConfig() definePermission() definePage() defineWidget() defineEventHandler() ``` --- # 59. Plugin SDK 示例 ```ts import { definePlugin, defineResource, defineAction, } from "@devos/plugin-sdk" export default definePlugin({ manifest: { id: "acme.seo", name: "seo", displayName: "SEO", version: "1.0.0", apiVersion: "2026-01", }, resources: [ defineResource({ id: "seo.website", ... }), ], actions: [ defineAction({ id: "seo.website.scan", ... }), ], }) ``` --- # 60. Plugin Bootstrap 统一： ```ts export default definePlugin(...) ``` 不要允许： ```text plugin/index.ts plugin/init.ts plugin/bootstrap.ts plugin/register.ts ``` 同时成为多个入口。 唯一入口： ```text Plugin Manifest + Plugin Definition ``` --- # 61. Plugin Runtime Loading ```text Plugin Discovery ↓ Load Package ↓ Load Manifest ↓ Validate ↓ Load Definition ↓ Dependency Check ↓ Registration ``` --- # 62. Dynamic Loading DevOS 应支持： ```text install plugin ↓ activate ``` 无需修改 Core。 例如安装： ```text Cloudflare Plugin ``` Core 不需要重新编译。 --- # 63. Plugin Registry Persistence 数据库： ```text plugins ``` 建议： ```sql plugins --------- id version api_version status trust_level source checksum signature manifest installed_at updated_at activated_at disabled_at error metadata ``` --- # 64. Plugin Instance ```ts export interface PluginInstance { id: string version: string apiVersion: string status: PluginStatus trustLevel: PluginTrustLevel source: PluginSource checksum: string installedAt: string activatedAt?: string metadata: Record } ``` --- # 65. Plugin State 不等于 Plugin Definition 必须区分： ```text Plugin Definition = 代码定义 Plugin Instance = 当前安装状态 ``` 例如： ```text Plugin Definition: seo@2.3.1 Plugin Instance: installed active configured ``` --- # 66. Plugin Config State Plugin 的配置属于： ```text Configuration Runtime ``` 而 Plugin Instance 只保存： ```text pluginId version status ``` 不要： ```text plugins.config JSON ``` 承载全部配置。 --- # 67. Plugin Migration Plugin 可以拥有自己的 Migration。 例如： ```text seo@1.0 ↓ seo@2.0 ``` Migration： ```text 001_add_keywords 002_add_backlinks 003_rebuild_index ``` 统一进入： ```text Migration Runtime ``` --- # 68. Plugin Migration Namespace 推荐： ```text plugin.seo.001 plugin.seo.002 ``` 或者： ```text seo.20260901 seo.20260910 ``` 不能与 Core Migration 冲突。 --- # 69. Plugin Upgrade 完整流程： ```text Current Plugin │ ↓ Read New Manifest │ ↓ Compatibility Check │ ↓ Dependency Resolution │ ↓ Generate Upgrade Plan │ ↓ Backup / Snapshot │ ↓ Pause New Work │ ↓ Drain Running Jobs │ ↓ Migration │ ↓ Register New Definition │ ↓ Health Check │ ↓ Activate │ ↓ Resume ``` 与第 12 文档统一。 --- # 70. Plugin Upgrade Lock 同一 Plugin 不允许并发升级。 ```text plugin:seo ↓ Distributed Lock ``` 如果已有升级： ```text 409 PluginUpgradeInProgress ``` --- # 71. Plugin Uninstall 卸载不能直接： ```text delete plugin ``` 必须： ```text disable ↓ check running tasks ↓ check dependencies ↓ check resources ↓ check data retention ↓ remove subscriptions ↓ remove workers ↓ remove capabilities ↓ remove UI registration ↓ optional data cleanup ↓ uninstall ``` --- # 72. Dependency Protection 如果： ```text Plugin A ↓ depends on B ``` 则不能直接卸载 B。 必须： ```text A disabled/uninstalled ``` 或者： ```text B dependency no longer required ``` --- # 73. Plugin Data Policy 卸载 Plugin 时，数据不能默认删除。 必须区分： ```text Plugin Code Plugin Configuration Plugin Data Plugin Files Plugin Artifacts Plugin Tasks Plugin Audit ``` 默认： ```text Uninstall Plugin ≠ Delete Business Data ``` --- # 74. Data Retention Plugin Manifest 可以声明： ```ts dataPolicy: { retainDataOnUninstall: true } ``` 用户可以选择： ```text Keep Data Delete Data Export Data ``` 危险删除必须： ```text Approval + Audit ``` --- # 75. Plugin Resource Cleanup 卸载时需要检查： ```text Resources Tasks Jobs Files Artifacts Schedules Webhooks Event subscriptions Credentials Providers ``` 不能留下大量 orphan records。 --- # 76. Orphan Resource Plugin 被删除后，如果业务数据还保留： ```text plugin_id = "seo" status = "orphaned" ``` UI： ```text SEO Plugin unavailable Data retained: 128 websites 32,420 keywords 1,248 backlinks ``` 用户重新安装即可恢复。 --- # 77. Plugin Reinstall 支持： ```text uninstall ↓ reinstall same version ↓ detect existing data ↓ migrate ↓ reattach resources ``` 不能重新创建一套重复数据。 --- # 78. Plugin Capability Discovery Plugin 安装之后自动注册： ```text Resource Action Skill MCP Workflow Provider ``` 进入： ```text Capability Registry ``` 因此： ```text 安装 Plugin ``` 等于： ```text 系统获得新的 Capability ``` --- # 79. Agent Plugin Integration Agent 不应该知道： ```text Plugin 内部代码 ``` Agent 只看到： ```text Capabilities ``` 例如： ```text seo.website.scan seo.keyword.research seo.backlink.find ``` --- # 80. Agent 不直接依赖 Plugin 错误： ```text Agent ↓ SEOPlugin ``` 正确： ```text Agent ↓ Capability Registry ↓ seo.website.scan ↓ Action Runtime ↓ SEO Plugin ``` --- # 81. Plugin 与 Skill Plugin： ```text 提供能力 ``` Skill： ```text 告诉 Agent 怎么使用能力 ``` 例如： ```text Plugin: seo.website.scan Skill: seo.audit ``` Skill 可以组合： ```text seo.website.scan seo.keyword.research seo.content.analyze ``` --- # 82. Plugin 与 MCP Plugin 可以暴露 MCP： ```text SEO Plugin ↓ MCP ↓ Capability Registry ``` 但外部 MCP 同样可以使用 DevOS Capability： ```text External MCP ↓ MCP Gateway ↓ Capability Registry ↓ Action Runtime ``` 因此： > Plugin MCP 与 External MCP 使用同一 Runtime。 --- # 83. Plugin Event Integration Plugin 可以： ```text 发布 Event ``` 例如： ```text seo.audit.completed ``` 也可以： ```text 订阅 Event ``` 例如： ```text core.task.completed ``` 全部走： ```text Event Runtime ``` --- # 84. Plugin Task Integration Plugin 创建异步任务： ```ts await ctx.tasks.create({ type: "seo.bulk_scan", ... }) ``` 然后： ```text Task ↓ Job ↓ Queue ↓ Worker ↓ Action ``` Plugin 禁止自己维护： ```text seo_jobs seo_queue seo_workers ``` 除非这些只是业务 Resource，而不是替代 DevOS Task Runtime。 --- # 85. Plugin Storage Integration Plugin 文件： ```text SEO Report ``` 使用： ```ts ctx.storage ``` 产生： ```text File Artifact ``` 而不是： ```text seo/uploads/ ``` 自己管理一套 Storage Runtime。 --- # 86. Plugin Search Integration Plugin Resource 可以声明： ```ts search: { enabled: true, fields: [...] } ``` DevOS 自动： ```text Resource ↓ Search Index ``` Plugin 不应该自行部署： ```text seo-elasticsearch ``` --- # 87. Plugin Data Integration Plugin Resource： ```text seo.website seo.keyword ``` 使用： ```text Data Runtime ``` 自动获得： ```text Query Pagination Filter Sort Search Permission Scope Export Import Audit ``` --- # 88. Plugin Observability Plugin 自动获得： ```text Logger Metrics Tracing Audit Error Runtime Health Usage Alerts ``` 例如： ```ts ctx.logger.info(...) ctx.metrics.counter(...) ctx.tracing.span(...) ``` 禁止 Plugin 创建： ```text seo_logger seo_metrics seo_audit ``` --- # 89. Plugin Audit 例如： ```text Actor: user:123 Plugin: seo Action: seo.website.scan Resource: website:456 Result: success ``` 统一进入： ```text Audit Runtime ``` --- # 90. Plugin Error Plugin 错误必须使用 DevOS Error Runtime： ```ts throw new DevOSError({ code: "SEO_PROVIDER_UNAVAILABLE", message: "SEO provider is unavailable", retryable: true, }) ``` 不要： ```ts throw new Error("oops") ``` 作为正式业务错误模型。 --- # 91. Plugin API 系统 API： ```text GET /api/plugins GET /api/plugins/:id POST /api/plugins/install POST /api/plugins/:id/activate POST /api/plugins/:id/disable POST /api/plugins/:id/upgrade DELETE /api/plugins/:id GET /api/plugins/:id/health GET /api/plugins/:id/capabilities GET /api/plugins/:id/dependencies GET /api/plugins/:id/config ``` --- # 92. Plugin Install API ```http POST /api/plugins/install ``` Input： ```ts interface PluginInstallInput { source: PluginSource version?: string activate?: boolean config?: Record } ``` 返回： ```ts interface PluginInstallResult { pluginId: string version: string status: PluginStatus plan: UpgradePlan } ``` --- # 93. Plugin Upgrade API ```http POST /api/plugins/:id/upgrade ``` Input： ```ts { version: "2.4.0", dryRun: false } ``` 支持： ```text dry-run plan execute rollback ``` --- # 94. Plugin CLI 必须提供： ```bash devos plugin list devos plugin info seo devos plugin install acme.seo@1.2.0 devos plugin enable acme.seo devos plugin disable acme.seo devos plugin upgrade acme.seo devos plugin uninstall acme.seo devos plugin health acme.seo devos plugin capabilities acme.seo ``` --- # 95. Plugin Developer CLI 建议： ```bash devos plugin create seo devos plugin dev devos plugin build devos plugin validate devos plugin test devos plugin package devos plugin publish ``` --- # 96. Plugin Validate ```bash devos plugin validate ``` 检查： ```text manifest ID version API version dependencies permissions resources actions skills mcp config UI migration ``` --- # 97. Plugin Test Plugin 测试应该可以使用 DevOS Test Runtime： ```text Plugin ↓ Test Runtime ↓ Mock Provider Mock Storage Mock Event Mock Queue Mock Config ``` --- # 98. Plugin Contract Test 所有 Plugin 必须通过： ```text Manifest Contract Resource Contract Action Contract Permission Contract Config Contract Event Contract UI Contract Migration Contract Health Contract ``` --- # 99. Plugin Compatibility Test 例如： ```text Plugin SEO 2.4 against DevOS Core 2026.09 ``` 自动检查： ```text API Resource Action Event Config MCP UI Migration ``` --- # 100. Plugin Marketplace DevOS 可以建立 Marketplace。 结构： ```text Marketplace │ ├── Official ├── Verified ├── Community └── Private ``` Plugin 页面： ```text SEO Version: 2.3.1 Publisher: ACME Trust: Verified Capabilities: 12 Actions 4 Skills 2 MCP 8 Resources Dependencies: Browser LLM ``` --- # 101. Marketplace 不负责 Runtime Marketplace 只是： ```text 发现 搜索 查看 下载 安装 ``` 真正安装： ```text Plugin Runtime ``` --- # 102. Marketplace Search 使用： ```text Search Runtime ``` 可以搜索： ```text SEO GitHub Docker Cloudflare WordPress CRM ``` Plugin Metadata 应可被 Global Search 搜索。 --- # 103. Plugin Rating 可以提供： ```text rating downloads version lastUpdated publisher trust compatibility ``` 但这些不是 Runtime 核心依赖。 --- # 104. Plugin Quality Score 可选： ```text Compatibility Security Test Coverage Update Frequency Health Popularity ``` Agent 选择 Capability 时，也可以把： ```text quality score ``` 作为 ranking 因素。 --- # 105. Plugin Version Pinning 生产环境： ```text seo@2.3.1 ``` 而不是： ```text seo@latest ``` 使用： ```text devos.lock ``` 例如： ```yaml plugins: acme.seo: version: 2.3.1 checksum: sha256:... ``` --- # 106. Plugin Lockfile Lockfile 用于： ```text Production CI/CD Deployment Rollback Reproducibility ``` 必须记录： ```text Plugin Version Checksum Dependencies API Version ``` --- # 107. Plugin Environment 允许： ```text Development Staging Production ``` 分别启用不同 Plugin。 例如： ```text Development: devos.debug devos.mock Production: devos.monitoring devos.cloudflare ``` --- # 108. Plugin Environment Policy Production Plugin： ```text 必须签名 必须锁版本 必须 checksum 必须 compatibility pass 必须 migration pass ``` --- # 109. Plugin Feature Flag Plugin 可以定义 Feature： ```text seo.new-crawler seo.ai-content seo.semantic-analysis ``` 但 Feature Flag 应由： ```text Configuration / Policy Runtime ``` 控制。 不要自己实现： ```text seo_feature_flags ``` --- # 110. Plugin Disable Disable 后： ```text Capability unavailable UI hidden New Tasks rejected Scheduled Tasks paused Workers drained MCP disabled Event handlers disabled ``` 已有数据： ```text 保留 ``` --- # 111. Disable 与 Uninstall 的区别 ```text Disable = 暂时不运行 Uninstall = 移除 Plugin Code / Runtime ``` 因此： ```text Disable 可以快速恢复 Uninstall 需要完整清理流程 ``` --- # 112. Plugin Recovery Plugin 启动失败： ```text failed ``` 系统应保存： ```text error stack trace plugin version runtime version migration dependency health check ``` 然后 UI 提供： ```text Retry Disable Rollback View Diagnostics ``` --- # 113. Plugin Rollback Rollback： ```text 2.4.0 ↓ 2.3.1 ``` 必须检查： ```text Migration compatibility Data compatibility Config compatibility Action version Event version Task version ``` 不能假设： ```text rollback = install old package ``` --- # 114. Plugin Upgrade Canary 未来可支持： ```text 5% Organization ↓ 20% ↓ 50% ↓ 100% ``` 观察： ```text error rate latency task failures provider failures ``` 异常： ```text stop rollout ``` --- # 115. Plugin Security 必须防止： ```text RCE SSRF Secret exfiltration Privilege escalation Path traversal Prototype pollution Malicious dependency Supply-chain attack ``` --- # 116. Plugin Network Policy Plugin 可以声明： ```ts network: { domains: [ "api.github.com", "api.cloudflare.com" ] } ``` Sandbox 模式下： ```text allowlist ``` 优先于： ```text allow all ``` --- # 117. Plugin Secret Permission 即使 Plugin 有： ```text provider.read ``` 也不能自动获得： ```text secret.read ``` Credential 与 Secret 必须分离。 --- # 118. Agent Plugin Security Agent 使用 Plugin Capability 时： ```text User ↓ Agent ↓ Policy ↓ Capability ↓ Permission ↓ Action ``` Plugin 不能因为 Agent 调用而绕过： ```text User permission Organization scope Project scope Approval policy ``` --- # 119. Dangerous Plugin Actions 例如： ```text server.delete dns.change production.deploy database.drop ``` 必须支持： ```ts requiresApproval: true ``` 进入： ```text Approval Runtime ``` --- # 120. Plugin UI Security Plugin UI 不能直接： ```text 读取 Secret 访问数据库 调用内部 API ``` 必须： ```text UI ↓ DevOS API ↓ Permission ↓ Action / Query ``` --- # 121. Plugin Frontend Bundle 推荐： ```text Plugin UI ↓ ESM / Module Federation / Dynamic Import ``` 具体实现可以根据当前前端架构决定。 第一阶段不必引入复杂 Module Federation。 可以： ```text dynamic import() ``` --- # 122. Plugin UI Manifest 例如： ```ts ui: { navigation: [ { id: "seo", path: "/seo", label: "SEO", icon: "search" } ], pages: [ { id: "seo.dashboard", path: "/seo", component: "SeoDashboard" } ] } ``` --- # 123. Plugin Asset 支持： ```text icon logo images frontend chunks styles ``` 统一： ```text Plugin Asset Runtime ``` 或者 Storage Runtime。 禁止 Plugin 任意写： ```text public/ ``` --- # 124. Plugin Namespace Isolation Plugin 所有资源： ```text seo.* ``` 配置： ```text plugin.seo.* ``` 权限： ```text seo.* ``` 事件： ```text seo.* ``` Skill： ```text seo.* ``` 避免命名冲突。 --- # 125. Plugin Database Namespace 推荐数据库表： ```text resource tables ``` Plugin 可以使用： ```text seo_websites seo_keywords ``` 但 Schema / Migration 必须属于： ```text plugin namespace ``` 如果未来支持 PostgreSQL schema： ```text plugin_seo ``` 也必须通过 Migration Runtime 创建。 --- # 126. 不要让 Plugin 自己创建数据库连接 错误： ```ts const db = new PrismaClient() ``` 正确： ```ts ctx.data ``` 如果 Plugin 确实需要特殊 Provider： ```text Data Provider Runtime ``` 由 DevOS 管理。 --- # 127. Plugin API Client 推荐 Plugin 使用： ```text @devos/runtime-sdk ``` 统一获得： ```ts context.data context.actions context.events context.tasks context.storage context.providers context.config ``` --- # 128. Plugin Runtime API ```ts export interface DevOSPluginRuntime { resource: ResourceRegistry action: ActionRegistry capability: CapabilityRegistry skill: SkillRegistry mcp: MCPRegistry workflow: WorkflowRegistry event: EventRuntime task: TaskRuntime data: DataRuntime search: SearchRuntime storage: StorageRuntime config: ConfigRuntime provider: ProviderRuntime audit: AuditRuntime observability: ObservabilityRuntime } ``` --- # 129. Plugin Registry Relationship ```text Plugin Registry │ ├── Resource Registry ├── Action Registry ├── Capability Registry ├── Skill Registry ├── MCP Registry ├── Workflow Registry ├── Provider Registry ├── Event Registry └── UI Registry ``` Plugin Registry 本身不是所有东西的替代品。 它负责： > Plugin 生命周期与所有权。 --- # 130. Ownership 每个 Extension 必须记录： ```ts ownerPluginId?: string ``` 例如： ```text Resource: seo.website ownerPlugin: acme.seo ``` 这样系统可以知道： ```text 这个 Resource 来自哪个 Plugin ``` --- # 131. Capability Ownership ```ts interface Capability { id: string source: CapabilitySource ownerPluginId?: string } ``` 例如： ```text seo.website.scan source = plugin ownerPluginId = acme.seo ``` --- # 132. Plugin Uninstall Impact Analysis 卸载前必须生成： ```text Impact Report ``` 例如： ```text Plugin: acme.seo Resources: 128 Actions: 12 Skills: 4 Tasks: 37 Schedules: 8 Files: 1,248 Artifacts: 532 Dependencies: none Dependents: content-agent ``` 然后： ```text Confirm Uninstall ``` --- # 133. Plugin Upgrade Impact Analysis 升级前： ```text Current: 2.3.1 Target: 2.4.0 ``` 显示： ```text Breaking changes Migration Config changes Action changes Event changes Dependency changes UI changes Risk Estimated downtime ``` --- # 134. Plugin Admin UI 建议： ```text System └── Plugins ├── Installed ├── Marketplace ├── Updates ├── Disabled └── Diagnostics ``` Plugin Detail： ```text Overview Capabilities Configuration Dependencies Health Tasks Events Workers Migrations Audit Versions ``` --- # 135. Plugin Detail Dashboard 显示： ```text Status Version Health Last activation Last upgrade Tasks Errors Actions Workers Events Usage ``` --- # 136. Plugin Capability UI 例如： ```text SEO Resources 8 Actions 21 Skills 5 MCP Tools 13 Workflows 4 ``` 可以直接查看： ```text Permission Schema Input Output Availability Cost ``` 这同时服务于： ```text Human Agent Developer ``` --- # 137. Plugin Logs Plugin Detail： ```text Observability ├── Logs ├── Metrics ├── Traces ├── Errors └── Audit ``` 数据来自第 17 文档。 --- # 138. Plugin Tasks Plugin Detail： ```text Tasks ``` 显示： ```text running completed failed cancelled ``` 统一来自： ```text Task Runtime ``` 而不是 Plugin Task DB。 --- # 139. Plugin Event Explorer 可以查看： ```text seo.website.scanned seo.audit.completed ``` 统一来自： ```text Event Runtime ``` --- # 140. Plugin Worker Monitor 显示： ```text Workers seo-crawler-01 seo-crawler-02 Concurrency Queue Throughput Error Rate Heartbeat ``` 统一 Worker Runtime。 --- # 141. Plugin Package Architecture 推荐： ```text packages/ ├── plugin-core/ ├── plugin-runtime/ ├── plugin-registry/ ├── plugin-loader/ ├── plugin-installer/ ├── plugin-resolver/ ├── plugin-sdk/ ├── plugin-security/ ├── plugin-marketplace/ └── plugin-ui/ ``` --- # 142. 推荐最终结构 ```text packages/ │ ├── core/ ├── resource/ ├── action/ ├── capability/ ├── agent/ ├── skill/ ├── mcp/ │ ├── task/ ├── job/ ├── queue/ ├── worker/ ├── scheduler/ │ ├── data/ ├── search/ ├── storage/ │ ├── event/ ├── notification/ ├── realtime/ │ ├── observability/ ├── audit/ ├── error/ │ ├── config/ ├── secret/ ├── credential/ ├── provider/ ├── environment/ │ └── plugin/ ├── core/ ├── runtime/ ├── registry/ ├── loader/ ├── installer/ ├── resolver/ ├── sdk/ ├── security/ ├── marketplace/ └── ui/ ``` --- # 143. Plugin Core Package ```text packages/plugin/core ``` 负责： ```text types manifest definition status dependency source artifact ``` 不负责： ```text install database UI queue ``` --- # 144. Plugin Registry Package ```text packages/plugin/registry ``` 负责： ```text Plugin Registry Resource Registration Action Registration Capability Registration Skill Registration MCP Registration Workflow Registration Provider Registration UI Registration Event Registration ``` --- # 145. Plugin Runtime Package ```text packages/plugin/runtime ``` 负责： ```text activate disable health lifecycle context ownership ``` --- # 146. Plugin Loader ```text packages/plugin/loader ``` 负责： ```text load package load manifest load module validate export ``` --- # 147. Plugin Installer ```text packages/plugin/installer ``` 负责： ```text download verify extract install migration activation ``` --- # 148. Plugin Resolver ```text packages/plugin/resolver ``` 负责： ```text SemVer dependency graph conflict cycle compatibility ``` --- # 149. Plugin Security ```text packages/plugin/security ``` 负责： ```text signature checksum trust sandbox network policy permissions package validation ``` --- # 150. Plugin SDK ```text packages/plugin/sdk ``` 供第三方开发： ```text @devos/plugin-sdk ``` SDK 不应该依赖： ```text NestJS Prisma React Redis ``` 过深。 否则 Plugin 会与 Core 实现强耦合。 --- # 151. Plugin SDK Compatibility Plugin SDK： ```text v1 v2 ``` 必须与： ```text Plugin API ``` 关联。 例如： ```text @devos/plugin-sdk@3 supports: DevOS Plugin API 2026-01 ``` --- # 152. Plugin Development Template 提供： ```bash devos plugin create my-plugin ``` 生成： ```text my-plugin/ ├── package.json ├── devos.plugin.ts ├── src/ │ ├── index.ts │ ├── resources/ │ ├── actions/ │ ├── skills/ │ └── ui/ ├── migrations/ ├── tests/ └── README.md ``` --- # 153. 最小 Plugin 最简单 Plugin： ```ts export default definePlugin({ manifest: { id: "acme.hello", name: "hello", displayName: "Hello", version: "1.0.0", apiVersion: "2026-01", }, }) ``` 安装即可： ```text installed active ``` --- # 154. Resource Plugin ```text Plugin ↓ Resource ↓ Generic CRUD ↓ Data Runtime ``` 只定义： ```text Schema Permission Actions UI Metadata ``` DevOS 自动提供： ```text List Detail Create Edit Delete Search Filter Sort Pagination ``` --- # 155. Action Plugin Plugin 只定义： ```text Action Handler Schema Permission ``` DevOS 自动提供： ```text API Audit Execution Task Error Metrics Tracing ``` --- # 156. Agent Plugin Plugin： ```text Skill Capability ``` Agent： ```text Goal Plan Execution Observation ``` Plugin 不实现 Agent。 --- # 157. Full Plugin Example 例如： ```text acme.seo ``` 提供： ```text Resources: seo.website seo.keyword seo.backlink Actions: seo.website.scan seo.website.audit seo.keyword.research seo.backlink.find Skills: seo.audit seo.content.strategy seo.backlink.strategy MCP: seo Workflows: seo.full-audit Providers: google ahrefs semrush UI: /seo /seo/websites /seo/keywords /seo/backlinks Events: seo.scan.completed seo.audit.completed ``` 这才是完整 Plugin。 --- # 158. Plugin 与 Core 边界 Core： ```text Identity Permission Resource Action Task Job Queue Worker Event Data Search Storage Config Secret Provider Observability UI Shell Plugin Runtime ``` Plugin： ```text Business Domain ``` 例如： ```text SEO GitHub Docker Cloudflare CRM WordPress ``` --- # 159. 什么应该进入 Core 只有满足： ```text 多个 Plugin 都需要 且 不属于具体业务领域 ``` 才进入 Core。 例如： ```text Task File Audit Search Permission Provider ``` 应该进入 Core。 --- # 160. 什么不能进入 Core 不要因为某个 Plugin 需要： ```text SEO backlink GitHub repository Docker container ``` 就把这些放入 Core。 否则： ```text Core ↓ 越来越大 ↓ 越来越难升级 ↓ 失去 Plugin 架构意义 ``` --- # 161. Plugin Architecture Golden Boundary 最终： ```text DEVOS CORE ────────────────────────────────────────── Identity Permission Resource Action Capability Agent Skill Runtime MCP Runtime Task Job Queue Worker Data Search Storage Event Config Secret Provider Observability UI Shell Plugin Runtime ────────────────────────────────────────── ↓ PLUGIN SYSTEM ↓ ────────────────────────────────────────── SEO GitHub Docker Cloudflare WordPress CRM Content DevOps ... ────────────────────────────────────────── ``` --- # 162. Plugin 不应该成为“第二个 DevOS” 绝对禁止： ```text Plugin ├── own DB Runtime ├── own Queue ├── own EventBus ├── own Auth ├── own Permission ├── own Scheduler ├── own Storage ├── own Search └── own Agent ``` 否则 Plugin 只是： > 一个被安装的微型单体应用。 这违背 DevOS 的目标。 --- # 163. Plugin 的正确哲学 Plugin 应该是： ```text Domain Extension ``` 而不是： ```text Mini Application ``` 因此： ```text DevOS = Platform Plugin = Domain App = Composition ``` --- # 164. App 与 Plugin 的关系 例如： ```text DevOS │ ├── SEO Plugin ├── GitHub Plugin ├── Docker Plugin ├── Cloudflare Plugin └── Content Plugin ↓ App ``` App 只是： ```text Plugin Composition + Configuration + Navigation + Workflow + Agent ``` --- # 165. SEO App 不要： ```text SEO Core SEO Infra SEO Agent Platform ``` 应该： ```text DevOS Core ↓ SEO Plugin ↓ SEO Skills ↓ SEO Agents ↓ SEO App ``` SEO 的基础设施能力由： ```text Data Task Queue Storage Event Provider Search ``` 提供。 --- # 166. Plugin Composition 例如一个 DevOps App： ```text GitHub Plugin + Docker Plugin + Cloudflare Plugin + SSH Provider + Agent Skill + Workflow ``` 不需要开发新的 Backend Core。 --- # 167. Plugin + Agent 例如： ```text Goal: 部署项目到生产环境 ``` Agent： ```text GitHub Plugin ↓ build action Docker Plugin ↓ image action SSH Provider ↓ server action Cloudflare Plugin ↓ dns action ``` 全部统一 Action Runtime。 --- # 168. Plugin + Workflow 固定流程： ```text Build ↓ Test ↓ Deploy ↓ Health Check ↓ DNS ``` Workflow。 动态决策： ```text 如果部署失败 ↓ 分析日志 ↓ 决定 rollback ``` Agent。 Plugin 只提供： ```text Capabilities ``` --- # 169. Plugin + MCP 用户可以： ```text Chat ↓ Agent ↓ SEO Skill ↓ SEO Plugin Action ``` 外部 AI Client 也可以： ```text Claude / Cursor / Other Agent ↓ MCP ↓ DevOS Capability Gateway ↓ SEO Plugin Action ``` 两者最终进入： ```text Action Runtime ``` --- # 170. Plugin + Global Search 用户输入： ```text Cloudflare production ``` Global Search 可以返回： ```text Cloudflare Account Cloudflare Zone DNS Record Deployments Tasks ``` 这些来自不同 Plugin。 --- # 171. Plugin + Global Command Command Palette： ```text Scan Website Deploy Production Restart Container Create GitHub Repository ``` Command 来自： ```text Action Registry ``` Plugin 安装之后自动出现。 --- # 172. Plugin + Universal Resource UI 如果 Plugin 定义： ```text seo.website ``` 并提供： ```text schema fields relations actions ``` DevOS 可以自动生成： ```text List Detail Search Filter Create Edit Bulk Actions ``` 因此 Plugin 开发成本极低。 --- # 173. Plugin + Generic UI 这意味着： ```text 80% CRUD Plugin ``` 可能只需要： ```text Resource Schema Action ``` 而不是： ```text Controller Service Repository DTO CRUD UI Table Form ``` 全部手写。 --- # 174. Plugin UI 的自由度 对于复杂 UI： ```text Plugin ↓ Custom React Components ``` 对于简单 UI： ```text Resource Schema ↓ Generic UI ``` 两种模式必须同时支持。 --- # 175. Plugin API Extension Plugin 可以增加： ```text REST endpoint ``` 但推荐： ```text Action ↓ Generic Action API ``` 只有特殊协议才允许： ```text Custom API Adapter ``` --- # 176. Plugin Webhook Plugin 可以声明 Webhook： ```text POST /api/plugins/seo/webhook/google ``` 但进入： ```text Webhook Runtime ``` 然后： ```text Webhook ↓ Event ↓ Task ↓ Action ``` --- # 177. Plugin OAuth OAuth 不应该自己存 Token。 流程： ```text Plugin Provider ↓ Credential Runtime ↓ OAuth ↓ Credential ↓ Secret ``` --- # 178. Plugin External Resource 例如 GitHub： ```text github.repository ``` 可以是： ```text External Resource ``` 由： ```text External Resource Provider ``` 负责同步。 Plugin 只定义： ```text Schema Provider Actions ``` --- # 179. Plugin Sync 例如： ```text GitHub Repository ↓ Sync ↓ DevOS Resource ``` 同步： ```text Scheduler ↓ Task ↓ Job ↓ Action ``` 而不是： ```text Plugin setInterval() ``` --- # 180. Plugin Cache Plugin 不应该直接： ```text redis.set("seo:...") ``` 使用： ```text CacheRuntime ``` 支持： ```text namespace TTL invalidation serialization scope ``` --- # 181. Plugin Rate Limit 例如 GitHub API： ```text 5000 req/hour ``` Plugin 使用： ```text Provider Rate Limit ``` 统一 Runtime 负责： ```text queue retry backoff concurrency ``` --- # 182. Plugin Cost Tracking Plugin 调用： ```text OpenAI Ahrefs Google Cloudflare ``` 都应该记录： ```text provider action task job execution cost ``` 进入： ```text Usage / Cost Runtime ``` --- # 183. Plugin Billing 如果未来支持 SaaS： ```text Plugin Usage ↓ Usage Runtime ↓ Billing ``` Plugin 不自己计费。 --- # 184. Plugin Resource Scope Plugin Resource 自动继承： ```text Organization Project Environment User ``` 例如： ```text seo.website ``` 自动支持： ```text organizationId projectId environmentId ``` 由 Resource/Scope Runtime 实现。 --- # 185. Plugin Multi-Tenant Plugin 不允许自己： ```text tenant_id ``` 重新实现多租户隔离逻辑。 应该使用： ```text ScopeProvider ``` 统一注入。 --- # 186. Plugin Permission Discovery Agent 搜索 Plugin Capability 时： ```text Capability ↓ Permission Check ↓ Scope Check ↓ Policy Check ↓ Availability ``` 只有可用 Capability 才返回。 --- # 187. Plugin Installation Permission 安装 Plugin 本身属于高权限 Action： ```text system.plugin.install ``` 升级： ```text system.plugin.upgrade ``` 卸载： ```text system.plugin.uninstall ``` 启停： ```text system.plugin.activate system.plugin.disable ``` 全部进入 Action Runtime。 --- # 188. Plugin Admin Permissions 建议： ```text system.plugin.read system.plugin.install system.plugin.activate system.plugin.disable system.plugin.upgrade system.plugin.uninstall system.plugin.configure system.plugin.diagnostics ``` --- # 189. Plugin Config Permission Plugin 配置： ```text plugin.seo.config.read plugin.seo.config.write ``` Secret： ```text secret.read ``` 严格分离。 --- # 190. Plugin UI Permission Navigation 可以声明： ```ts permission: "seo.website.read" ``` 用户无权限： ```text 隐藏 ``` 或者： ```text disabled ``` 由 UI Shell 统一处理。 --- # 191. Plugin Version Matrix 系统必须能够展示： ```text Plugin: acme.seo 2.4.0 DevOS: 2026.09 API: 2026-01 Dependencies: github >=2.0 browser >=1.5 ``` --- # 192. Plugin Compatibility Registry 统一： ```ts CompatibilityRegistry ``` 检查： ```text Core Plugin SDK Resource Action Event MCP Skill Config ``` 与第 12 文档整合。 --- # 193. Plugin Diagnostics 插件异常时： ```text Plugin Diagnostics ``` 输出： ```text Plugin Version Runtime Version API Version Dependencies Config Status Provider Status Credential Status Migration Status Worker Status Queue Status Event Status Recent Errors ``` --- # 194. Plugin Export 可以导出： ```text Plugin Configuration Plugin Metadata Plugin Resources Plugin Workflows Plugin Skills ``` 但： ```text Secret plaintext ``` 绝对不能导出。 --- # 195. Plugin Import 导入： ```text Config Workflow Skill Resource mapping ``` Secret： ```text 重新绑定 ``` 而不是跨环境复制 Secret。 --- # 196. Plugin Backup Backup 应覆盖： ```text Plugin Version Plugin Config Plugin Migration State Plugin Data Plugin Metadata ``` Secret： ```text 只保存 Secret Reference ``` --- # 197. Plugin Disaster Recovery 恢复： ```text DevOS Core ↓ Plugin Lockfile ↓ Plugin Packages ↓ Database ↓ Plugin Migrations ↓ Config ↓ Provider Binding ↓ Health Check ``` --- # 198. Plugin Cold Start 系统启动： ```text Load Core ↓ Load Plugin Registry ↓ Resolve Dependencies ↓ Load Active Plugins ↓ Register Capabilities ↓ Start Workers ↓ Start Event Handlers ↓ Health Check ``` --- # 199. Plugin Startup Failure 如果某个 Plugin 启动失败： ```text Core ↓ 继续启动 ``` 而不是： ```text 一个 Plugin ↓ 整个 DevOS 无法启动 ``` 除非 Manifest 声明： ```text requiredForBoot: true ``` 这种能力应极少使用。 --- # 200. Core Plugin 有些基础能力可以采用 Plugin 形式： ```text Core Plugin ``` 例如： ```text devos.github devos.docker ``` 虽然是官方 Plugin，但仍然遵守 Plugin Runtime。 --- # 201. Core 与 Official Plugin 区别： ```text Core = 系统不可缺少基础设施 Official Plugin = 官方维护的业务能力 ``` 例如： ```text Auth Task Storage Event ``` 属于 Core。 ```text GitHub Cloudflare Docker ``` 可以是 Official Plugin。 --- # 202. Plugin API Stability Plugin API 应尽可能稳定。 推荐： ```text apiVersion = date/version ``` 例如： ```text 2026-01 ``` Breaking Change： ```text 2027-01 ``` 而不是频繁： ```text 2026.01.01 2026.01.02 ``` --- # 203. Plugin Deprecation 某个 API： ```text Action API v1 ``` 准备删除： ```text deprecated ``` 生命周期： ```text active ↓ deprecated ↓ removed ``` 至少提供： ```text warning migration guide replacement ``` --- # 204. Plugin Action Version Plugin Action： ```text seo.website.scan@1 seo.website.scan@2 ``` 不要直接破坏旧 Action。 与第 12 文档统一。 --- # 205. Plugin Event Version 事件： ```text seo.scan.completed@1 seo.scan.completed@2 ``` 旧事件不能因为 Plugin 升级而改变 payload 语义。 --- # 206. Plugin Skill Version Skill： ```text seo.audit@1 seo.audit@2 ``` Agent Plan 必须记录 Skill Version。 --- # 207. Plugin MCP Version MCP Capability： ```text seo.mcp@1 ``` 升级时： ```text Capability Registry ``` 记录： ```text mcpVersion ``` --- # 208. Reproducibility 任何 Execution 都应该可以追溯： ```text DevOS Version Plugin Version Action Version Skill Version MCP Version Config Version Provider Version ``` 与第 12、17、18 文档统一。 --- # 209. Plugin Execution Trace 例如： ```text User ↓ Agent Run ↓ Skill seo.audit@2 ↓ Capability seo.website.scan@3 ↓ Plugin acme.seo@2.4.0 ↓ Task ↓ Job ↓ Execution ↓ Provider google@1 ``` 这才是完整可追踪链。 --- # 210. Plugin API Error Model 统一： ```ts interface PluginError { code: string pluginId: string pluginVersion: string category: | "configuration" | "dependency" | "provider" | "runtime" | "migration" | "permission" | "network" retryable: boolean } ``` --- # 211. Plugin Rate Control Plugin 可以声明： ```ts limits: { maxConcurrentTasks: 10, maxRequestsPerMinute: 100, } ``` 最终进入： ```text Task Runtime Provider Runtime RateLimit Runtime ``` --- # 212. Plugin Resource Group 例如： ```text seo.crawler ``` 限制： ```text maxConcurrent = 5 ``` 用于： ```text CPU Browser External API Server ``` 统一资源组机制。 --- # 213. Plugin Backpressure 当： ```text SEO Task ``` 大量增加： ```text 10000 jobs ``` 系统应该： ```text Queue ↓ Backpressure ↓ Concurrency Limit ↓ Provider Rate Limit ``` Plugin 不自己实现队列。 --- # 214. Plugin Cleanup Worker Plugin 可以声明 Cleanup Job： ```text temporary crawl data ``` 但仍然： ```text Scheduler ↓ Task ↓ Job ↓ Worker ``` --- # 215. Plugin Retention Plugin 可以声明： ```ts retention: { crawlArtifacts: "30d", logs: "7d" } ``` 实际执行由： ```text Retention Runtime ``` 完成。 --- # 216. Plugin Event Replay 如果 Plugin 被禁用： ```text Event ``` 可以： ```text replay ``` 但必须检查： ```text version schema idempotency ``` --- # 217. Plugin Event Subscription Lifecycle ```text Plugin Activate ↓ Subscribe ↓ Active Plugin Disable ↓ Unsubscribe Plugin Upgrade ↓ Drain ↓ Update Handler ↓ Subscribe ``` --- # 218. Plugin MCP Lifecycle ```text Activate ↓ Register MCP ↓ Capability Available Disable ↓ MCP Unavailable ``` 外部 Client 看到： ```text capability unavailable ``` 而不是： ```text 500 random error ``` --- # 219. Plugin UI Lifecycle ```text Plugin Activate ↓ UI Registration Plugin Disable ↓ UI Hidden ``` 已经打开页面： ```text 显示 Plugin Disabled ``` 而不是整个 SPA 崩溃。 --- # 220. Plugin Data Lifecycle ```text Install ↓ Create/Sync ↓ Active ↓ Disable ↓ Data retained ↓ Uninstall ↓ Data retained or deleted by explicit policy ``` --- # 221. Plugin Package Lifecycle ```text Discover ↓ Download ↓ Verify ↓ Install ↓ Activate ↓ Upgrade ↓ Disable ↓ Uninstall ``` --- # 222. Plugin Runtime 与 Deployment Plugin 最终应该能通过： ```text DevOS Deployment Runtime ``` 部署。 例如： ```text Production ↓ devos.lock ↓ Plugin Packages ↓ Install ↓ Migrate ↓ Activate ``` 保证环境一致。 --- # 223. Plugin CI/CD CI： ```text lint typecheck test contract test build package checksum signature ``` CD： ```text publish ↓ compatibility ↓ canary ↓ rollout ``` --- # 224. Plugin Build 建议： ```bash devos plugin build ``` 输出： ```text dist/ plugin.tgz manifest.json checksum ``` --- # 225. Plugin Publish ```bash devos plugin publish ``` 发布前自动： ```text validate test compatibility security package sign ``` --- # 226. Plugin Quality Gate 生产发布必须至少： ```text TypeScript compile Unit tests Integration tests Contract tests Migration tests Security scan Dependency scan Manifest validation Compatibility validation ``` --- # 227. Plugin Acceptance Test 每个 Plugin 最少测试： ### Manifest ```text ID Version API Dependency ``` ### Runtime ```text Install Activate Disable Upgrade Uninstall ``` ### Resource ```text CRUD Query Permission Scope ``` ### Action ```text Input Output Error Retry Audit ``` ### Config ```text Read Write Environment Secret Reference ``` ### Event ```text Publish Subscribe Retry Idempotency ``` ### Task ```text Create Execute Cancel Retry ``` --- # 228. Plugin Security Acceptance 必须测试： ```text Unauthorized install Unauthorized activate Unauthorized config Unauthorized action Secret leakage SSRF Path traversal Package tampering Checksum mismatch Signature mismatch Dependency attack ``` --- # 229. Plugin Upgrade Acceptance 测试： ```text 2.3 → 2.4 2.4 → 3.0 incompatible upgrade migration failure rollback dependency conflict running task checksum mismatch concurrent upgrade ``` --- # 230. Plugin Failure Acceptance 模拟： ```text Provider unavailable Database unavailable Queue unavailable Migration failure UI registration failure Worker crash Event handler crash ``` 系统必须： ```text degrade gracefully ``` --- # 231. Plugin Agent Acceptance 测试： ```text Agent finds Plugin Capability ↓ Permission filtering ↓ Skill selection ↓ Action execution ↓ Task ↓ Execution ↓ Event ↓ Observation ``` --- # 232. Plugin MCP Acceptance 测试： ```text MCP Tool discovery Permission Scope Action mapping Execution Error Audit ``` --- # 233. Plugin UI Acceptance 测试： ```text Install ↓ Navigation appears Disable ↓ Navigation disappears Enable ↓ Navigation returns ``` 以及： ```text permission denied ``` 时正确隐藏/禁止。 --- # 234. Plugin Developer Experience 目标： > 一个成熟开发者应该可以在几十分钟内写出一个基本 Plugin。 最少步骤： ```bash devos plugin create hello cd hello devos plugin dev ``` 定义： ```text Resource Action Page ``` 即可看到： ```text UI API Agent Capability ``` --- # 235. Plugin 代码量目标 一个简单 CRUD Plugin： ```text Resource Schema Action Manifest ``` 约： ```text 100~300 lines ``` 而不是： ```text Controller Service Repository DTO React Page React Table React Form API Client ``` 几千行。 --- # 236. Plugin Scaffold 推荐生成： ```text src/ ├── manifest.ts ├── resources/ ├── actions/ ├── skills/ ├── config/ ├── ui/ └── index.ts ``` --- # 237. Plugin SDK Example ```ts export const website = defineResource({ id: "seo.website", fields: { domain: { type: "string", required: true, searchable: true, }, status: { type: "enum", values: [ "active", "paused", ], }, }, actions: { scan: defineAction({ id: "seo.website.scan", input: z.object({ depth: z.number().max(10), }), handler: async (input, ctx) => { // domain business logic }, }), }, }) ``` --- # 238. Plugin Generic UI 只要定义： ```text fields relations actions ``` DevOS 自动： ```text Table Form Detail Search Filter Actions ``` --- # 239. Plugin Custom UI 复杂业务： ```text SEO Site Audit Graph Backlink Graph Deployment Console Container Logs ``` 允许： ```text Custom React Component ``` 但是数据访问仍： ```text DevOS API ``` --- # 240. Plugin UI SDK 建议： ```text @devos/plugin-ui ``` 提供： ```ts useResource() useQuery() useAction() useTask() useEvent() useConfig() useCapability() useAgent() ``` --- # 241. Plugin Agent UI Plugin 可以注册： ```text Agent Context Widget ``` 例如： ```text 用户正在查看： example.com Agent Context: SEO Score 83 Issues 12 Backlinks 1200 ``` Agent 可以直接使用当前 Resource Context。 --- # 242. Plugin Context Provider UI： ```text Resource Detail ↓ Plugin Widget ↓ Context ↓ Agent ``` 例如： ```text Agent: 分析这个网站 ``` 自动绑定： ```text resourceId = seo.website:123 ``` --- # 243. Plugin Command Palette Plugin 可以注册： ```text Scan Website Analyze Keywords Deploy Container Restart Server ``` 统一进入： ```text Action Registry ``` --- # 244. Plugin Global Search Provider Plugin 可以声明： ```ts searchProvider: { resources: [ "seo.website", "seo.keyword" ] } ``` Global Search 自动索引。 --- # 245. Plugin Notification Plugin 可以触发： ```text Notification ``` 例如： ```text SEO Audit Completed ``` 统一： ```text Notification Runtime ``` 支持： ```text in-app email webhook push ``` --- # 246. Plugin Webhook Plugin 可以提供： ```text Webhook Endpoint ``` 但必须通过： ```text Webhook Runtime ``` 自动获得： ```text signature retry SSRF protection audit event ``` --- # 247. Plugin External Webhook Plugin 也可以向外部发送： ```text Webhook Action ``` 同样： ```text Provider Event Task Action ``` 统一执行。 --- # 248. Plugin Import/Export Plugin 可以声明： ```text Import schema Export schema ``` 使用： ```text Import Runtime Export Runtime ``` 支持： ```text CSV JSON JSONL Excel ``` --- # 249. Plugin Bulk Actions 例如： ```text 100 websites ↓ Bulk Scan ``` 必须： ```text 1 Task 100 Jobs ``` 而不是： ```text 100 Agent Runs ``` --- # 250. Plugin Batch API Action： ```text seo.website.bulkScan ``` 内部： ```text Task ↓ Job Factory ↓ 100 Jobs ↓ Queue ``` --- # 251. Plugin Performance Plugin 不应该： ```text 一次加载 10000 Resources ``` 使用： ```text Query Pagination Cursor Search Batch DataLoader ``` --- # 252. Plugin Query Security Plugin Query 自动经过： ```text Permission Scope Field Permission Cost Limit Timeout ``` --- # 253. Plugin Cache Security Cache Key 必须包含： ```text organization project environment resource ``` 防止： ```text Tenant A ↓ Cache ↓ Tenant B ``` 数据泄漏。 --- # 254. Plugin Resource Naming 统一： ```text . ``` 例如： ```text github.repository github.issue docker.container docker.image seo.website seo.keyword ``` --- # 255. Plugin Action Naming 统一： ```text .. ``` 例如： ```text github.repository.create github.repository.sync docker.container.restart seo.website.scan ``` --- # 256. Plugin Event Naming 统一： ```text .. ``` 例如： ```text seo.website.scanned seo.audit.completed github.repository.synced ``` --- # 257. Plugin Skill Naming ```text . ``` 例如： ```text seo.audit seo.content.strategy github.issue.triage ``` --- # 258. Plugin Workflow Naming ```text . ``` 例如： ```text seo.full_audit github.release docker.deploy ``` --- # 259. Plugin MCP Naming ```text .mcp ``` 例如： ```text seo.mcp github.mcp ``` --- # 260. Plugin Provider Naming ```text . ``` 例如： ```text github.api cloudflare.api ``` --- # 261. Plugin Configuration Naming ```text plugin.. ``` 例如： ```text plugin.seo.crawler.maxDepth plugin.seo.content.language ``` --- # 262. Plugin Permission Naming ```text .. ``` 例如： ```text seo.website.read seo.website.scan seo.website.delete ``` --- # 263. Plugin UI Route Naming 推荐： ```text / // ``` 例如： ```text /seo /seo/websites /seo/keywords ``` 不要： ```text /plugin/acme.seo/page1 ``` 用户看到的应该是业务路径。 --- # 264. Plugin Internal Route 如果需要内部页面： ```text /_plugins//... ``` 可以保留，但不作为主要用户 URL。 --- # 265. Plugin API Namespace 业务 API： ```text /api/actions/seo.website.scan ``` 或者： ```text /api/resources/seo.website ``` 而不是每个 Plugin 自己： ```text /api/seo/* ``` 这样统一 API Runtime。 --- # 266. Plugin Graph DevOS 可以维护： ```text Plugin Graph ``` 例如： ```text SEO ├── GitHub ├── Browser ├── OpenAI └── Storage ``` 用于： ```text Dependency Capability Health Impact Upgrade ``` --- # 267. Plugin Graph UI Plugin Detail： ```text Dependencies ↓ SEO ↓ Capabilities ↓ Actions / Skills / MCP ``` 非常适合诊断。 --- # 268. Plugin Marketplace 与 Dependency Marketplace 安装： ```text SEO ``` 自动显示： ```text Required: Browser Optional: Ahrefs OpenAI GitHub ``` 然后生成： ```text Install Plan ``` --- # 269. Install Plan ```ts interface PluginInstallPlan { plugins: PluginPlanItem[] dependencies: DependencyChange[] migrations: MigrationPlan[] configChanges: ConfigChange[] risks: Risk[] warnings: string[] } ``` --- # 270. Plugin Upgrade Plan 与第 12 文档： ```text UpgradePlan ``` 统一。 不要建立第二个完全不同的 Upgrade Plan。 --- # 271. Plugin Runtime 与 Migration Runtime Plugin Runtime： ```text 负责什么时候升级 ``` Migration Runtime： ```text 负责怎么迁移 ``` 边界： ```text Plugin Runtime ↓ Migration Runtime ↓ Database ``` --- # 272. Plugin Runtime 与 Config Runtime Plugin Runtime： ```text Plugin 生命周期 ``` Config Runtime： ```text Plugin 配置 ``` Plugin 只能： ```ts ctx.config.get(...) ``` --- # 273. Plugin Runtime 与 Secret Runtime Plugin Runtime： ```text 生命周期 ``` Secret Runtime： ```text Secret ``` Plugin 只能： ```text credential reference ``` 而不是： ```text secret database ``` --- # 274. Plugin Runtime 与 Event Runtime Plugin： ```text declare event subscribe event publish event ``` Event Runtime： ```text delivery retry ordering replay DLQ ``` --- # 275. Plugin Runtime 与 Task Runtime Plugin： ```text create Task ``` Task Runtime： ```text Task → Job → Queue → Worker ``` --- # 276. Plugin Runtime 与 Agent Runtime Plugin： ```text 提供 Capability / Skill ``` Agent Runtime： ```text Goal → Plan → Execute ``` --- # 277. Plugin Runtime 与 UI Shell Plugin： ```text 注册 UI ``` UI Shell： ```text 渲染 UI 导航 权限 布局 ``` --- # 278. Plugin Runtime 与 Storage Plugin： ```text File / Artifact ``` Storage： ```text Blob ``` --- # 279. Plugin Runtime 与 Data Plugin： ```text Resource Schema ``` Data Runtime： ```text Query Repository Provider ``` --- # 280. Plugin Runtime 与 Search Plugin： ```text Search Definition ``` Search Runtime： ```text Index Query Ranking Embedding ``` --- # 281. Plugin Runtime 与 Observability Plugin： ```text Logger Metric Trace Audit ``` Observability： ```text collection storage query dashboard alert ``` --- # 282. Plugin API Golden Rule 任何 Plugin 对外暴露： ```text Resource Action Event Capability Skill MCP UI ``` 必须注册到： ```text DevOS Registry ``` 不能建立自己的： ```text parallel registry ``` --- # 283. Plugin Execution Golden Rule 所有执行： ```text Plugin Action Plugin Worker Plugin Workflow Plugin MCP Plugin Skill Plugin Webhook Plugin Scheduler ``` 最终必须进入： ```text Action Runtime ``` 或者： ```text Task Runtime ``` 不能绕过。 --- # 284. Plugin Data Golden Rule 所有数据： ```text Plugin Resource ``` 必须通过： ```text Data Runtime ``` 所有 Blob： ```text Storage Runtime ``` 所有 Secret： ```text Secret Runtime ``` --- # 285. Plugin Event Golden Rule 所有事件： ```text Plugin Event ``` 必须进入： ```text Event Runtime ``` 所有 Notification： ```text Notification Runtime ``` --- # 286. Plugin UI Golden Rule Plugin UI： ```text Plugin UI ↓ UI Shell ↓ DevOS API ↓ Runtime ``` 禁止： ```text Plugin UI ↓ Direct DB ``` --- # 287. Plugin Agent Golden Rule ```text Agent ↓ Capability Registry ↓ Plugin Capability ↓ Action Runtime ``` 不要： ```text Agent ↓ Plugin internals ``` --- # 288. Plugin Security Golden Rule Plugin： ```text Permission Scope Policy Approval ``` 必须继承 DevOS Security Runtime。 --- # 289. Plugin Version Golden Rule 任何 Plugin Execution 都必须记录： ```text pluginVersion apiVersion actionVersion skillVersion mcpVersion configVersion ``` 保证： ```text reproducibility auditability rollback ``` --- # 290. Plugin Architecture Final Diagram 最终完整结构： ```text ┌──────────────────────┐ │ DevOS Core │ │ │ │ Identity │ │ Permission │ │ Resource │ │ Action │ │ Capability │ │ Task / Job / Queue │ │ Data / Search │ │ Storage │ │ Event │ │ Config / Secret │ │ Provider │ │ Observability │ │ UI Shell │ └──────────┬───────────┘ │ Plugin Runtime │ ┌──────────────────────┼─────────────────────┐ │ │ │ Plugin A Plugin B Plugin C │ │ │ ┌──────┼──────┐ ┌──────┼──────┐ ┌─────┼─────┐ │ │ │ │ │ │ │ │ │ Res Action Skill Res Action MCP Res Skill UI │ │ │ │ │ │ │ └──────┴──────┴────────┴──────┴──────┴───────┘ │ Capability Registry │ ┌───────┴────────┐ │ │ Agent Human UI │ │ └───────┬────────┘ │ Action Runtime │ Task / Execution │ Event ``` --- # 291. Zcode 必须实现的核心模块 Zcode 必须至少新增： ```text packages/plugin/core packages/plugin/runtime packages/plugin/registry packages/plugin/loader packages/plugin/installer packages/plugin/resolver packages/plugin/sdk packages/plugin/security packages/plugin/ui ``` 如果 Marketplace 当前不做： ```text packages/plugin/marketplace ``` 可以先预留接口。 --- # 292. Zcode 必须实现的数据库 至少： ```text plugins plugin_versions plugin_dependencies plugin_installations plugin_artifacts plugin_migrations plugin_health plugin_locks ``` 如果 Capability Registry 已有持久化模型，不重复创建 Capability 表。 --- # 293. Zcode 禁止新增的重复系统 禁止 Plugin Runtime 创建： ```text plugin_tasks plugin_jobs plugin_queue plugin_events plugin_notifications plugin_users plugin_roles plugin_secrets plugin_storage plugin_search plugin_scheduler ``` 如果业务确实需要这些概念： ```text 使用 DevOS Runtime ``` --- # 294. Zcode 实现优先级 ## P0 必须完成： ```text Plugin Manifest Plugin Registry Plugin Lifecycle Plugin Install Plugin Activate Plugin Disable Plugin Dependency Plugin Version Plugin Compatibility Plugin Resource Registration Plugin Action Registration Plugin Capability Registration Plugin Config Registration Plugin Permission Registration ``` --- ## P1 然后： ```text Plugin UI Plugin Skill Plugin MCP Plugin Event Plugin Worker Plugin Health Plugin Migration Plugin Upgrade Plugin Uninstall ``` --- ## P2 最后： ```text Marketplace Signature Sandbox Canary Private Registry Advanced Plugin Graph ``` --- # 295. Zcode 第一阶段验收 执行： ```bash devos plugin create hello ``` 应该生成 Plugin。 然后： ```bash devos plugin build devos plugin validate devos plugin install devos plugin enable ``` 系统应该出现： ```text Plugin: Hello Status: Active ``` --- # 296. Zcode 第二阶段验收 Plugin 定义： ```text Resource: hello.message Action: hello.message.create hello.message.delete ``` 安装后自动得到： ```text Resource UI Action API Permission Audit Search ``` --- # 297. Zcode 第三阶段验收 Plugin 增加： ```text Skill: hello.greeting ``` Agent： ```text Goal: 创建一条 Hello Message ``` Agent 必须自动发现： ```text hello.greeting ``` 并调用： ```text hello.message.create ``` --- # 298. Zcode 第四阶段验收 Plugin 增加： ```text MCP ``` 外部 MCP Client： ```text discover ↓ hello.message.create ↓ Action Runtime ``` 必须成功。 --- # 299. Zcode 第五阶段验收 Plugin 增加： ```text Config Provider Secret Event Task Worker UI ``` 全部必须仍然使用 DevOS Runtime。 --- # 300. Zcode 最终验收 完整 Plugin： ```text Install ↓ Dependency ↓ Compatibility ↓ Migration ↓ Register ↓ Config ↓ Provider ↓ Resource ↓ Action ↓ Skill ↓ MCP ↓ Event ↓ Worker ↓ UI ↓ Health ↓ Active ``` 然后： ```text Upgrade ↓ Migration ↓ Health ↓ Active ``` 最后： ```text Disable ↓ Uninstall ↓ Data Retained ``` 整个生命周期必须可观测、可审计、可恢复。 --- # 301. 最重要的架构原则 DevOS 最终不是： ```text 一个巨大的 Backend ``` 也不是： ```text 一个巨大的 Admin Panel ``` 更不是： ```text 一个 AI Chatbot ``` 而是： ```text DevOS │ ┌──────────┴──────────┐ │ │ Platform Plugins │ │ Runtime / Agent Domain Logic │ │ └──────────┬──────────┘ │ Apps ``` --- # 302. Plugin 的最终定义 > **Plugin 是 DevOS 中可以独立安装、配置、授权、升级、禁用、卸载，并向 DevOS 注册 Resource、Action、Capability、Skill、MCP、Workflow、Event、Provider 和 UI 的领域扩展单元。** --- # 303. 最终 Golden Rule ```text PLUGIN │ ┌──────────────┼──────────────┐ │ │ │ Resource Action Capability │ │ │ │ ↓ │ │ Action Runtime │ │ │ │ │ Task / Job │ │ │ │ └──────────────┼──────────────┘ │ DevOS Runtime │ ┌────────────────┼────────────────┐ │ │ │ Data Event Storage │ │ │ Search Agent Notification │ │ │ └────────────────┼────────────────┘ │ UI Shell ``` ### 最终原则： ```text Plugin 提供业务能力 DevOS 提供运行时能力 Plugin 定义 What Runtime 决定 How Plugin 不拥有基础设施 Runtime 不拥有业务领域 Agent 使用 Capability Human 使用 UI MCP 使用 Gateway 但最终： 所有执行 → Action Runtime 所有异步 → Task Runtime 所有数据 → Data Runtime 所有文件 → Storage Runtime 所有事件 → Event Runtime 所有配置 → Config Runtime 所有 Secret → Secret Runtime 所有权限 → Security Runtime 所有观测 → Observability Runtime ```