devos/Docs/DevOS-Platform-v2/19_PLUGIN_EXTENSION_PACKAGE_RUNTIME.md

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。

正确架构应该是：

                    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 必须做到：

安装
 ↓
解析依赖
 ↓
兼容性检查
 ↓
Migration
 ↓
注册 Resource
 ↓
注册 Action
 ↓
注册 Skill
 ↓
注册 MCP
 ↓
注册 Event
 ↓
注册 UI
 ↓
注册 Config
 ↓
注册 Permission
 ↓
Health Check
 ↓
Activate

卸载：

Disable
 ↓
停止新任务
 ↓
等待 / Cancel Running Tasks
 ↓
注销 Capability
 ↓
停止 Worker
 ↓
停止 Event Subscription
 ↓
清理 Runtime
 ↓
Uninstall

---

3. Plugin、Extension、Package 的区别

这三个概念必须严格区分。

Package

Package 是代码组织单位。

例如：

@devos/plugin-seo
@devos/plugin-github
@devos/plugin-docker

Package 本身不一定是可以安装的 Plugin。

---

Extension

Extension 是某个 Runtime 的扩展。

例如：

ResourceExtension
ActionExtension
SearchExtension
UIExtension
EventExtension

---

Plugin

Plugin 是完整的可安装 DevOS 功能。

例如：

SEO Plugin
GitHub Plugin
Docker Plugin
Cloudflare Plugin
WordPress Plugin

一个 Plugin 可以包含多个 Extension。

---

4. Plugin 的完整结构

标准 Plugin：

plugin
│
├── manifest
│
├── resources
│
├── actions
│
├── skills
│
├── workflows
│
├── mcp
│
├── events
│
├── providers
│
├── config
│
├── permissions
│
├── ui
│
├── migrations
│
├── workers
│
├── health
│
└── assets

例如：

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 的唯一正式声明入口。

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<string, unknown>
}

---

6. Plugin ID

Plugin ID 必须全局唯一。

推荐：

<vendor>.<plugin>

例如：

devos.github
devos.docker
devos.cloudflare

acme.seo
acme.wordpress

禁止：

github
seo
plugin1
test

生产环境 Plugin ID 不允许随意改变。

---

7. Plugin Version

使用 SemVer：

MAJOR.MINOR.PATCH

例如：

1.0.0
1.2.0
1.2.3
2.0.0

必须与第 12 文档的版本系统统一。

---

8. Plugin API Version

Plugin 自己的版本与 DevOS Plugin API 版本分开。

例如：

apiVersion: "2026-01"
version: "2.3.1"

含义：

Plugin API = DevOS 扩展接口版本

Plugin Version = 这个 Plugin 自己的版本

---

9. Plugin Dependency

Plugin 可以依赖：

Core Runtime
其他 Plugin
Provider
Capability

定义：

export interface PluginDependency {
  id: string

  version: string

  optional?: boolean

  reason?: string
}

例如：

dependencies: [
  {
    id: "devos.github",
    version: "^2.0.0",
  },
]

---

10. Dependency Resolver

DevOS 必须提供统一 Dependency Resolver。

Plugin A
 │
 ├── Plugin B ^1.0
 │
 └── Plugin C ^2.0
       │
       └── Plugin B ^1.5

Resolver：

读取依赖
 ↓
解析 SemVer
 ↓
寻找兼容版本
 ↓
构建 Dependency Graph
 ↓
检测冲突
 ↓
检测循环依赖
 ↓
生成 Install Plan

必须支持：

direct dependency
optional dependency
peer dependency
transitive dependency
version conflict
cycle detection

不要自己重新实现 SemVer。

---

11. Dependency Graph

内部：

export interface PluginDependencyGraph {
  nodes: PluginDependencyNode[]
  edges: PluginDependencyEdge[]
}

例如：

SEO
├── browser
├── github
└── content
      └── llm

---

12. Plugin Lifecycle

Plugin 生命周期：

discovered
   ↓
installed
   ↓
validating
   ↓
migrating
   ↓
registering
   ↓
activating
   ↓
active
   │
   ├── disabling
   │      ↓
   │   disabled
   │
   └── upgrading
          ↓
       active

active
   ↓
uninstalling
   ↓
uninstalled

---

13. Plugin State

export type PluginStatus =
  | "discovered"
  | "installing"
  | "installed"
  | "validating"
  | "migration_running"
  | "registering"
  | "activating"
  | "active"
  | "degraded"
  | "disabling"
  | "disabled"
  | "upgrading"
  | "uninstalling"
  | "failed"
  | "uninstalled"

---

14. Plugin Runtime

核心：

export interface PluginRuntime {
  install(input: PluginInstallInput): Promise<PluginInstallResult>

  validate(pluginId: string): Promise<PluginValidationResult>

  activate(pluginId: string): Promise<void>

  disable(pluginId: string): Promise<void>

  upgrade(input: PluginUpgradeInput): Promise<PluginUpgradeResult>

  uninstall(pluginId: string): Promise<void>

  get(pluginId: string): Promise<PluginInstance>

  list(): Promise<PluginInstance[]>

  health(pluginId: string): Promise<PluginHealth>
}

---

15. Plugin Registry

所有 Plugin 必须注册到：

PluginRegistry

export interface PluginRegistry {
  register(plugin: PluginDefinition): Promise<void>

  unregister(pluginId: string): Promise<void>

  get(pluginId: string): PluginDefinition | undefined

  has(pluginId: string): boolean

  list(): PluginDefinition[]
}

---

16. Plugin Definition

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 不是简单：

plugin.init()

而必须执行：

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

全部成功：

ACTIVE

否则：

DEGRADED / FAILED

---

18. Registration Transaction

Plugin 注册最好具有事务性。

错误：

Resource 注册成功
Action 注册成功
Skill 注册成功
UI 注册失败

结果不能变成半激活状态。

应该：

Prepare
 ↓
Validate
 ↓
Register
 ↓
Health Check
 ↓
Commit

失败：

Rollback Registration

---

19. Capability Registration

Plugin 是 Capability 的重要来源。

Plugin
 │
 ├── Resource
 ├── Action
 ├── Skill
 ├── MCP
 ├── Workflow
 └── Provider
        ↓
Capability Registry
        ↓
Agent

这与第 06 文档完全一致。

---

20. Plugin Resource

Plugin 可以声明 Resource。

例如：

{
  id: "seo.website",
  name: "Website",
  ...
}

但必须经过：

Resource Registry

而不是 Plugin 自己维护一套 Resource Registry。

---

21. Plugin Action

Plugin Action：

{
  id: "seo.website.scan",
  resource: "seo.website",
  ...
}

执行：

Agent
 ↓
Capability
 ↓
ActionRuntime
 ↓
Plugin Action Handler

禁止：

Agent
 ↓
Plugin
 ↓
直接执行代码

---

22. Plugin Action Handler

export interface PluginActionHandler<TInput, TOutput> {
  execute(
    input: TInput,
    context: ActionContext
  ): Promise<TOutput>
}

Action Handler 可以使用：

DataRuntime
StorageRuntime
EventRuntime
TaskRuntime
ProviderRuntime
ConfigRuntime
SecretRuntime
HTTP Client

但必须通过 DevOS Runtime。

---

23. Plugin 不允许直接操作基础设施

禁止：

plugin -> prisma.user.create()
plugin -> redis.set()
plugin -> websocket.send()
plugin -> process.env.API_KEY
plugin -> fs.readFile(...)

除非这是被 DevOS 明确授权的 Runtime 内部实现。

Plugin 应该使用：

ctx.data
ctx.storage
ctx.event
ctx.task
ctx.config
ctx.secret
ctx.provider

---

24. Plugin Context

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 不应该自己建立：

plugin_settings
plugin_config
plugin_secrets

DevOS 已经有：

Configuration Runtime
Secret Runtime
Provider Runtime
Environment Runtime

因此 Plugin 只声明：

config: [...]

DevOS 负责：

存储
验证
继承
环境
权限
版本
审计
Secret
UI

---

26. Plugin Secret

Plugin：

{
  id: "github.token",
  type: "secret"
}

实际 Secret：

secret://github/default

Plugin 永远不应该：

database.query("select secret")

---

27. Plugin Permission

Plugin 可以声明自己的权限。

例如：

permissions: [
  {
    id: "seo.website.read",
    description: "Read SEO websites"
  },
  {
    id: "seo.website.scan",
    description: "Run website scan"
  },
  {
    id: "seo.website.delete",
    description: "Delete website"
  }
]

最终进入统一：

Permission Registry

---

28. Permission Namespace

必须使用 Plugin namespace：

seo.website.read
seo.website.scan
seo.website.delete

github.repository.read
github.repository.create

docker.container.read
docker.container.restart

禁止：

read
write
admin
scan

这种全局模糊权限。

---

29. Plugin UI

Plugin 可以拥有自己的页面。

这是 DevOS 非常重要的能力。

例如：

SEO
├── Dashboard
├── Websites
├── Keywords
├── Backlinks
├── Content
├── Tasks
└── Settings

Plugin manifest：

export interface PluginUIManifest {
  navigation?: NavigationItem[]

  pages?: PluginPage[]

  widgets?: PluginWidget[]

  settings?: PluginSettingsPage[]

  dashboards?: PluginDashboard[]
}

---

30. Navigation

Plugin 可以注册：

{
  id: "seo",
  label: "SEO",
  icon: "Search",
  path: "/seo"
}

子页面：

SEO
├── Overview
├── Websites
├── Keywords
├── Backlinks
├── Content
└── Settings

但是：

Plugin 不应该修改主 Shell。

Plugin 只能向 UI Shell 注册扩展点。

---

31. UI Extension Point

DevOS UI Shell 提供：

sidebar
topbar
dashboard
resource-list
resource-detail
resource-actions
settings
task-detail
agent-chat
global-search
command-palette

Plugin 可以注册：

ui.registerExtension({
  slot: "resource.detail.sidebar",
  resource: "seo.website",
  component: WebsiteHealthWidget
})

---

32. Plugin Page

Plugin 页面：

export interface PluginPage {
  id: string

  path: string

  title: string

  component: string

  permission?: string

  icon?: string

  layout?: string
}

例如：

/seo/websites
/seo/keywords
/seo/backlinks

---

33. Plugin Widget

export interface PluginWidget {
  id: string

  slot: string

  title?: string

  component: string

  priority?: number

  permission?: string
}

例如：

dashboard.main
task.sidebar
agent.context
resource.detail

---

34. Plugin Settings

每个 Plugin 都可以拥有自己的 Settings 页面。

例如：

Settings
└── Plugins
    └── SEO
        ├── General
        ├── Providers
        ├── Limits
        ├── Automation
        └── Advanced

但是数据仍然来自：

Configuration Runtime

而不是 Plugin 自己存储。

---

35. Plugin Dashboard

Plugin 可以注册 Dashboard。

例如 SEO：

SEO Dashboard

Websites       128
Keywords       32,420
Backlinks      1,248
Tasks          37
Errors         4

Dashboard 数据必须走：

Query / Search / Metrics Runtime

禁止 UI 直接 SQL。

---

36. Plugin Event

Plugin 可以订阅事件。

例如：

events: [
  {
    type: "seo.website.updated",
    handler: "..."
  }
]

或者：

core.task.completed
core.execution.failed
core.file.created

Event 统一进入第 16 文档定义的 Event Runtime。

---

37. Plugin Event Handler

export interface PluginEventHandler {
  handle(
    event: DevOSEvent,
    context: EventHandlerContext
  ): Promise<void>
}

必须：

idempotent
retryable
audited
observable

---

38. Plugin Worker

Plugin 可以提供 Worker。

例如：

SEO crawler worker
Content processing worker
GitHub sync worker

但 Worker 必须注册到：

Worker Runtime

而不是 Plugin 自己启动：

setInterval(...)

禁止。

---

39. Plugin Scheduler

Plugin 可以注册 Schedule：

SEO website scan
每天 03:00

但 Schedule 必须进入：

Scheduler Runtime

流程：

Scheduler
 ↓
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action

Plugin 不允许自己创建 cron daemon。

---

40. Plugin Workflow

Plugin 可以提供 Workflow Template：

SEO Audit

例如：

Scan Website
 ↓
Analyze Technical SEO
 ↓
Analyze Content
 ↓
Analyze Backlinks
 ↓
Generate Report

Workflow 使用：

Action Runtime
Task Runtime
Event Runtime

---

41. Plugin Skill

Plugin 可以提供 Skill：

seo.audit
seo.keyword.research
seo.backlink.strategy

Skill：

Skill
 ↓
Capability Discovery
 ↓
Action

Plugin 不应该自己实现 Agent Loop。

Agent Runtime 负责 Agent。

---

42. Plugin MCP

Plugin 可以提供 MCP。

例如：

SEO MCP
GitHub MCP
Docker MCP
Cloudflare MCP

但：

MCP 不是第二套执行系统。

MCP 最终：

MCP
 ↓
Capability
 ↓
Action Runtime

---

43. Plugin MCP Server

export interface PluginMCPDefinition {
  id: string

  name: string

  version: string

  tools: MCPToolDefinition[]

  resources?: MCPResourceDefinition[]
}

MCP Tool 最终必须映射：

MCP Tool
 ↓
Action ID
 ↓
Action Runtime

---

44. Plugin Provider

Plugin 可以提供 Provider。

例如：

GitHub
 ├── GitHub API
 └── GitHub OAuth

Cloudflare
 └── Cloudflare API

OpenAI
 └── OpenAI API

Provider 进入：

Provider Registry

Credential：

Credential Runtime

Secret：

Secret Runtime

---

45. Plugin External API

Plugin 调用第三方 API 时：

Plugin Action
 ↓
Provider Runtime
 ↓
Credential Resolver
 ↓
Secret Runtime
 ↓
HTTP Client
 ↓
External API

而不是：

Plugin
 ↓
fetch()
 ↓
process.env.API_KEY

---

46. Plugin Health

每个 Plugin 必须提供 Health Check。

export interface PluginHealth {
  status: "healthy" | "degraded" | "unhealthy"

  checks: HealthCheckResult[]

  timestamp: string
}

检查：

Database
Provider
Credential
External API
Worker
Queue
MCP
Configuration

---

47. Plugin Health 与 Activation

Plugin：

installed
 ↓
health check
 ↓
active

如果 Provider 无法使用：

active + degraded

不要因为一个可选 Provider 失败就让整个 Plugin 崩溃。

---

48. Optional Capability

Plugin 可以声明：

{
  id: "cloudflare",
  optional: true
}

例如：

SEO Plugin
 ├── Core SEO       required
 ├── OpenAI         optional
 ├── Ahrefs         optional
 └── Semrush        optional

没有 Ahrefs：

SEO = active
Ahrefs capability = unavailable

Agent Capability Registry 必须知道：

available
unavailable
degraded

---

49. Plugin Availability

Capability Registry：

export type CapabilityAvailability =
  | "available"
  | "unavailable"
  | "degraded"
  | "disabled"
  | "permission_denied"

Agent 搜索 Capability 时必须过滤。

---

50. Plugin Installation

安装流程：

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

支持：

Marketplace
Local package
Git repository
OCI registry
Private registry
Uploaded archive

生产环境推荐：

Immutable package
+ exact version
+ checksum

---

52. Plugin Package

推荐 Plugin Package：

devos-plugin-seo-2.3.1.tgz

内部：

manifest.json
dist/
assets/
migrations/
package metadata
checksum
signature

---

53. Plugin Signature

生产环境建议：

Package
 ↓
SHA-256
 ↓
Signature
 ↓
Trusted Publisher

Plugin Instance 保存：

interface PluginArtifact {
  source: string

  version: string

  checksum: string

  signature?: string

  publisher?: string

  installedAt: string
}

---

54. Plugin Trust

Plugin Trust Level：

export type PluginTrustLevel =
  | "core"
  | "official"
  | "verified"
  | "community"
  | "local"
  | "untrusted"

生产环境可以设置：

allow:
core
official
verified

deny:
untrusted

---

55. Plugin Sandbox

不能假设所有 Plugin 都可信。

因此 Runtime 必须区分：

Trusted Plugin
Untrusted Plugin

对于高风险 Plugin，可以限制：

filesystem
network
process
child_process
environment
native modules

---

56. 推荐的 Plugin 执行模式

第一阶段：

Trusted Plugin
=
same process

优点：

简单
性能高
开发方便

第二阶段：

Sandbox Plugin
=
isolated process / container

架构：

DevOS
 ↓
Plugin Host
 ↓
IPC / RPC
 ↓
Sandbox

不要一开始就为所有 Plugin 强制容器化，否则系统复杂度会大幅增加。

---

57. Plugin API Boundary

Sandbox Plugin 只能访问：

Plugin SDK
 ↓
RPC
 ↓
DevOS Runtime

例如：

plugin.data.query()
plugin.action.execute()
plugin.storage.put()
plugin.event.publish()
plugin.config.get()

而不能：

直接访问 DevOS PostgreSQL
直接访问 Redis
直接读取 Secret

---

58. Plugin SDK

建议：

@devos/plugin-sdk

提供：

createPlugin()

defineResource()

defineAction()

defineSkill()

defineWorkflow()

defineMCP()

defineProvider()

defineConfig()

definePermission()

definePage()

defineWidget()

defineEventHandler()

---

59. Plugin SDK 示例

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

统一：

export default definePlugin(...)

不要允许：

plugin/index.ts
plugin/init.ts
plugin/bootstrap.ts
plugin/register.ts

同时成为多个入口。

唯一入口：

Plugin Manifest + Plugin Definition

---

61. Plugin Runtime Loading

Plugin Discovery
 ↓
Load Package
 ↓
Load Manifest
 ↓
Validate
 ↓
Load Definition
 ↓
Dependency Check
 ↓
Registration

---

62. Dynamic Loading

DevOS 应支持：

install plugin
 ↓
activate

无需修改 Core。

例如安装：

Cloudflare Plugin

Core 不需要重新编译。

---

63. Plugin Registry Persistence

数据库：

plugins

建议：

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

export interface PluginInstance {
  id: string

  version: string

  apiVersion: string

  status: PluginStatus

  trustLevel: PluginTrustLevel

  source: PluginSource

  checksum: string

  installedAt: string

  activatedAt?: string

  metadata: Record<string, unknown>
}

---

65. Plugin State 不等于 Plugin Definition

必须区分：

Plugin Definition
=
代码定义

Plugin Instance
=
当前安装状态

例如：

Plugin Definition:
seo@2.3.1

Plugin Instance:
installed
active
configured

---

66. Plugin Config State

Plugin 的配置属于：

Configuration Runtime

而 Plugin Instance 只保存：

pluginId
version
status

不要：

plugins.config JSON

承载全部配置。

---

67. Plugin Migration

Plugin 可以拥有自己的 Migration。

例如：

seo@1.0
 ↓
seo@2.0

Migration：

001_add_keywords
002_add_backlinks
003_rebuild_index

统一进入：

Migration Runtime

---

68. Plugin Migration Namespace

推荐：

plugin.seo.001
plugin.seo.002

或者：

seo.20260901
seo.20260910

不能与 Core Migration 冲突。

---

69. Plugin Upgrade

完整流程：

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 不允许并发升级。

plugin:seo
      ↓
Distributed Lock

如果已有升级：

409 PluginUpgradeInProgress

---

71. Plugin Uninstall

卸载不能直接：

delete plugin

必须：

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

如果：

Plugin A
 ↓
depends on B

则不能直接卸载 B。

必须：

A disabled/uninstalled

或者：

B dependency no longer required

---

73. Plugin Data Policy

卸载 Plugin 时，数据不能默认删除。

必须区分：

Plugin Code
Plugin Configuration
Plugin Data
Plugin Files
Plugin Artifacts
Plugin Tasks
Plugin Audit

默认：

Uninstall Plugin
≠ Delete Business Data

---

74. Data Retention

Plugin Manifest 可以声明：

dataPolicy: {
  retainDataOnUninstall: true
}

用户可以选择：

Keep Data
Delete Data
Export Data

危险删除必须：

Approval
+
Audit

---

75. Plugin Resource Cleanup

卸载时需要检查：

Resources
Tasks
Jobs
Files
Artifacts
Schedules
Webhooks
Event subscriptions
Credentials
Providers

不能留下大量 orphan records。

---

76. Orphan Resource

Plugin 被删除后，如果业务数据还保留：

plugin_id = "seo"
status = "orphaned"

UI：

SEO Plugin unavailable

Data retained:
128 websites
32,420 keywords
1,248 backlinks

用户重新安装即可恢复。

---

77. Plugin Reinstall

支持：

uninstall
 ↓
reinstall same version
 ↓
detect existing data
 ↓
migrate
 ↓
reattach resources

不能重新创建一套重复数据。

---

78. Plugin Capability Discovery

Plugin 安装之后自动注册：

Resource
Action
Skill
MCP
Workflow
Provider

进入：

Capability Registry

因此：

安装 Plugin

等于：

系统获得新的 Capability

---

79. Agent Plugin Integration

Agent 不应该知道：

Plugin 内部代码

Agent 只看到：

Capabilities

例如：

seo.website.scan
seo.keyword.research
seo.backlink.find

---

80. Agent 不直接依赖 Plugin

错误：

Agent
 ↓
SEOPlugin

正确：

Agent
 ↓
Capability Registry
 ↓
seo.website.scan
 ↓
Action Runtime
 ↓
SEO Plugin

---

81. Plugin 与 Skill

Plugin：

提供能力

Skill：

告诉 Agent 怎么使用能力

例如：

Plugin:
seo.website.scan

Skill:
seo.audit

Skill 可以组合：

seo.website.scan
seo.keyword.research
seo.content.analyze

---

82. Plugin 与 MCP

Plugin 可以暴露 MCP：

SEO Plugin
 ↓
MCP
 ↓
Capability Registry

但外部 MCP 同样可以使用 DevOS Capability：

External MCP
 ↓
MCP Gateway
 ↓
Capability Registry
 ↓
Action Runtime

因此：

Plugin MCP 与 External MCP 使用同一 Runtime。

---

83. Plugin Event Integration

Plugin 可以：

发布 Event

例如：

seo.audit.completed

也可以：

订阅 Event

例如：

core.task.completed

全部走：

Event Runtime

---

84. Plugin Task Integration

Plugin 创建异步任务：

await ctx.tasks.create({
  type: "seo.bulk_scan",
  ...
})

然后：

Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action

Plugin 禁止自己维护：

seo_jobs
seo_queue
seo_workers

除非这些只是业务 Resource，而不是替代 DevOS Task Runtime。

---

85. Plugin Storage Integration

Plugin 文件：

SEO Report

使用：

ctx.storage

产生：

File
Artifact

而不是：

seo/uploads/

自己管理一套 Storage Runtime。

---

86. Plugin Search Integration

Plugin Resource 可以声明：

search: {
  enabled: true,
  fields: [...]
}

DevOS 自动：

Resource
 ↓
Search Index

Plugin 不应该自行部署：

seo-elasticsearch

---

87. Plugin Data Integration

Plugin Resource：

seo.website
seo.keyword

使用：

Data Runtime

自动获得：

Query
Pagination
Filter
Sort
Search
Permission
Scope
Export
Import
Audit

---

88. Plugin Observability

Plugin 自动获得：

Logger
Metrics
Tracing
Audit
Error Runtime
Health
Usage
Alerts

例如：

ctx.logger.info(...)
ctx.metrics.counter(...)
ctx.tracing.span(...)

禁止 Plugin 创建：

seo_logger
seo_metrics
seo_audit

---

89. Plugin Audit

例如：

Actor: user:123
Plugin: seo
Action: seo.website.scan
Resource: website:456
Result: success

统一进入：

Audit Runtime

---

90. Plugin Error

Plugin 错误必须使用 DevOS Error Runtime：

throw new DevOSError({
  code: "SEO_PROVIDER_UNAVAILABLE",
  message: "SEO provider is unavailable",
  retryable: true,
})

不要：

throw new Error("oops")

作为正式业务错误模型。

---

91. Plugin API

系统 API：

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

POST /api/plugins/install

Input：

interface PluginInstallInput {
  source: PluginSource

  version?: string

  activate?: boolean

  config?: Record<string, unknown>
}

返回：

interface PluginInstallResult {
  pluginId: string
  version: string
  status: PluginStatus
  plan: UpgradePlan
}

---

93. Plugin Upgrade API

POST /api/plugins/:id/upgrade

Input：

{
  version: "2.4.0",
  dryRun: false
}

支持：

dry-run
plan
execute
rollback

---

94. Plugin CLI

必须提供：

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

建议：

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

devos plugin validate

检查：

manifest
ID
version
API version
dependencies
permissions
resources
actions
skills
mcp
config
UI
migration

---

97. Plugin Test

Plugin 测试应该可以使用 DevOS Test Runtime：

Plugin
 ↓
Test Runtime
 ↓
Mock Provider
Mock Storage
Mock Event
Mock Queue
Mock Config

---

98. Plugin Contract Test

所有 Plugin 必须通过：

Manifest Contract
Resource Contract
Action Contract
Permission Contract
Config Contract
Event Contract
UI Contract
Migration Contract
Health Contract

---

99. Plugin Compatibility Test

例如：

Plugin SEO 2.4
against
DevOS Core 2026.09

自动检查：

API
Resource
Action
Event
Config
MCP
UI
Migration

---

100. Plugin Marketplace

DevOS 可以建立 Marketplace。

结构：

Marketplace
│
├── Official
├── Verified
├── Community
└── Private

Plugin 页面：

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 只是：

发现
搜索
查看
下载
安装

真正安装：

Plugin Runtime

---

102. Marketplace Search

使用：

Search Runtime

可以搜索：

SEO
GitHub
Docker
Cloudflare
WordPress
CRM

Plugin Metadata 应可被 Global Search 搜索。

---

103. Plugin Rating

可以提供：

rating
downloads
version
lastUpdated
publisher
trust
compatibility

但这些不是 Runtime 核心依赖。

---

104. Plugin Quality Score

可选：

Compatibility
Security
Test Coverage
Update Frequency
Health
Popularity

Agent 选择 Capability 时，也可以把：

quality score

作为 ranking 因素。

---

105. Plugin Version Pinning

生产环境：

seo@2.3.1

而不是：

seo@latest

使用：

devos.lock

例如：

plugins:
  acme.seo:
    version: 2.3.1
    checksum: sha256:...

---

106. Plugin Lockfile

Lockfile 用于：

Production
CI/CD
Deployment
Rollback
Reproducibility

必须记录：

Plugin
Version
Checksum
Dependencies
API Version

---

107. Plugin Environment

允许：

Development
Staging
Production

分别启用不同 Plugin。

例如：

Development:
  devos.debug
  devos.mock

Production:
  devos.monitoring
  devos.cloudflare

---

108. Plugin Environment Policy

Production Plugin：

必须签名
必须锁版本
必须 checksum
必须 compatibility pass
必须 migration pass

---

109. Plugin Feature Flag

Plugin 可以定义 Feature：

seo.new-crawler
seo.ai-content
seo.semantic-analysis

但 Feature Flag 应由：

Configuration / Policy Runtime

控制。

不要自己实现：

seo_feature_flags

---

110. Plugin Disable

Disable 后：

Capability unavailable
UI hidden
New Tasks rejected
Scheduled Tasks paused
Workers drained
MCP disabled
Event handlers disabled

已有数据：

保留

---

111. Disable 与 Uninstall 的区别

Disable
=
暂时不运行

Uninstall
=
移除 Plugin Code / Runtime

因此：

Disable
可以快速恢复

Uninstall
需要完整清理流程

---

112. Plugin Recovery

Plugin 启动失败：

failed

系统应保存：

error
stack trace
plugin version
runtime version
migration
dependency
health check

然后 UI 提供：

Retry
Disable
Rollback
View Diagnostics

---

113. Plugin Rollback

Rollback：

2.4.0
 ↓
2.3.1

必须检查：

Migration compatibility
Data compatibility
Config compatibility
Action version
Event version
Task version

不能假设：

rollback = install old package

---

114. Plugin Upgrade Canary

未来可支持：

5% Organization
 ↓
20%
 ↓
50%
 ↓
100%

观察：

error rate
latency
task failures
provider failures

异常：

stop rollout

---

115. Plugin Security

必须防止：

RCE
SSRF
Secret exfiltration
Privilege escalation
Path traversal
Prototype pollution
Malicious dependency
Supply-chain attack

---

116. Plugin Network Policy

Plugin 可以声明：

network: {
  domains: [
    "api.github.com",
    "api.cloudflare.com"
  ]
}

Sandbox 模式下：

allowlist

优先于：

allow all

---

117. Plugin Secret Permission

即使 Plugin 有：

provider.read

也不能自动获得：

secret.read

Credential 与 Secret 必须分离。

---

118. Agent Plugin Security

Agent 使用 Plugin Capability 时：

User
 ↓
Agent
 ↓
Policy
 ↓
Capability
 ↓
Permission
 ↓
Action

Plugin 不能因为 Agent 调用而绕过：

User permission
Organization scope
Project scope
Approval policy

---

119. Dangerous Plugin Actions

例如：

server.delete
dns.change
production.deploy
database.drop

必须支持：

requiresApproval: true

进入：

Approval Runtime

---

120. Plugin UI Security

Plugin UI 不能直接：

读取 Secret
访问数据库
调用内部 API

必须：

UI
 ↓
DevOS API
 ↓
Permission
 ↓
Action / Query

---

121. Plugin Frontend Bundle

推荐：

Plugin UI
 ↓
ESM / Module Federation / Dynamic Import

具体实现可以根据当前前端架构决定。

第一阶段不必引入复杂 Module Federation。

可以：

dynamic import()

---

122. Plugin UI Manifest

例如：

ui: {
  navigation: [
    {
      id: "seo",
      path: "/seo",
      label: "SEO",
      icon: "search"
    }
  ],

  pages: [
    {
      id: "seo.dashboard",
      path: "/seo",
      component: "SeoDashboard"
    }
  ]
}

---

123. Plugin Asset

支持：

icon
logo
images
frontend chunks
styles

统一：

Plugin Asset Runtime

或者 Storage Runtime。

禁止 Plugin 任意写：

public/

---

124. Plugin Namespace Isolation

Plugin 所有资源：

seo.*

配置：

plugin.seo.*

权限：

seo.*

事件：

seo.*

Skill：

seo.*

避免命名冲突。

---

125. Plugin Database Namespace

推荐数据库表：

resource tables

Plugin 可以使用：

seo_websites
seo_keywords

但 Schema / Migration 必须属于：

plugin namespace

如果未来支持 PostgreSQL schema：

plugin_seo

也必须通过 Migration Runtime 创建。

---

126. 不要让 Plugin 自己创建数据库连接

错误：

const db = new PrismaClient()

正确：

ctx.data

如果 Plugin 确实需要特殊 Provider：

Data Provider Runtime

由 DevOS 管理。

---

127. Plugin API Client

推荐 Plugin 使用：

@devos/runtime-sdk

统一获得：

context.data
context.actions
context.events
context.tasks
context.storage
context.providers
context.config

---

128. Plugin Runtime API

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

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 必须记录：

ownerPluginId?: string

例如：

Resource:
seo.website

ownerPlugin:
acme.seo

这样系统可以知道：

这个 Resource 来自哪个 Plugin

---

131. Capability Ownership

interface Capability {
  id: string
  source: CapabilitySource
  ownerPluginId?: string
}

例如：

seo.website.scan
source = plugin
ownerPluginId = acme.seo

---

132. Plugin Uninstall Impact Analysis

卸载前必须生成：

Impact Report

例如：

Plugin: acme.seo

Resources:
  128

Actions:
  12

Skills:
  4

Tasks:
  37

Schedules:
  8

Files:
  1,248

Artifacts:
  532

Dependencies:
  none

Dependents:
  content-agent

然后：

Confirm Uninstall

---

133. Plugin Upgrade Impact Analysis

升级前：

Current:
2.3.1

Target:
2.4.0

显示：

Breaking changes
Migration
Config changes
Action changes
Event changes
Dependency changes
UI changes
Risk
Estimated downtime

---

134. Plugin Admin UI

建议：

System
└── Plugins
    ├── Installed
    ├── Marketplace
    ├── Updates
    ├── Disabled
    └── Diagnostics

Plugin Detail：

Overview
Capabilities
Configuration
Dependencies
Health
Tasks
Events
Workers
Migrations
Audit
Versions

---

135. Plugin Detail Dashboard

显示：

Status
Version
Health
Last activation
Last upgrade
Tasks
Errors
Actions
Workers
Events
Usage

---

136. Plugin Capability UI

例如：

SEO

Resources
  8

Actions
  21

Skills
  5

MCP Tools
  13

Workflows
  4

可以直接查看：

Permission
Schema
Input
Output
Availability
Cost

这同时服务于：

Human
Agent
Developer

---

137. Plugin Logs

Plugin Detail：

Observability
 ├── Logs
 ├── Metrics
 ├── Traces
 ├── Errors
 └── Audit

数据来自第 17 文档。

---

138. Plugin Tasks

Plugin Detail：

Tasks

显示：

running
completed
failed
cancelled

统一来自：

Task Runtime

而不是 Plugin Task DB。

---

139. Plugin Event Explorer

可以查看：

seo.website.scanned
seo.audit.completed

统一来自：

Event Runtime

---

140. Plugin Worker Monitor

显示：

Workers
  seo-crawler-01
  seo-crawler-02

Concurrency
Queue
Throughput
Error Rate
Heartbeat

统一 Worker Runtime。

---

141. Plugin Package Architecture

推荐：

packages/
├── plugin-core/
├── plugin-runtime/
├── plugin-registry/
├── plugin-loader/
├── plugin-installer/
├── plugin-resolver/
├── plugin-sdk/
├── plugin-security/
├── plugin-marketplace/
└── plugin-ui/

---

142. 推荐最终结构

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

packages/plugin/core

负责：

types
manifest
definition
status
dependency
source
artifact

不负责：

install
database
UI
queue

---

144. Plugin Registry Package

packages/plugin/registry

负责：

Plugin Registry
Resource Registration
Action Registration
Capability Registration
Skill Registration
MCP Registration
Workflow Registration
Provider Registration
UI Registration
Event Registration

---

145. Plugin Runtime Package

packages/plugin/runtime

负责：

activate
disable
health
lifecycle
context
ownership

---

146. Plugin Loader

packages/plugin/loader

负责：

load package
load manifest
load module
validate export

---

147. Plugin Installer

packages/plugin/installer

负责：

download
verify
extract
install
migration
activation

---

148. Plugin Resolver

packages/plugin/resolver

负责：

SemVer
dependency graph
conflict
cycle
compatibility

---

149. Plugin Security

packages/plugin/security

负责：

signature
checksum
trust
sandbox
network policy
permissions
package validation

---

150. Plugin SDK

packages/plugin/sdk

供第三方开发：

@devos/plugin-sdk

SDK 不应该依赖：

NestJS
Prisma
React
Redis

过深。

否则 Plugin 会与 Core 实现强耦合。

---

151. Plugin SDK Compatibility

Plugin SDK：

v1
v2

必须与：

Plugin API

关联。

例如：

@devos/plugin-sdk@3
supports:
DevOS Plugin API 2026-01

---

152. Plugin Development Template

提供：

devos plugin create my-plugin

生成：

my-plugin/
├── package.json
├── devos.plugin.ts
├── src/
│   ├── index.ts
│   ├── resources/
│   ├── actions/
│   ├── skills/
│   └── ui/
├── migrations/
├── tests/
└── README.md

---

153. 最小 Plugin

最简单 Plugin：

export default definePlugin({
  manifest: {
    id: "acme.hello",
    name: "hello",
    displayName: "Hello",
    version: "1.0.0",
    apiVersion: "2026-01",
  },
})

安装即可：

installed
active

---

154. Resource Plugin

Plugin
 ↓
Resource
 ↓
Generic CRUD
 ↓
Data Runtime

只定义：

Schema
Permission
Actions
UI Metadata

DevOS 自动提供：

List
Detail
Create
Edit
Delete
Search
Filter
Sort
Pagination

---

155. Action Plugin

Plugin 只定义：

Action
Handler
Schema
Permission

DevOS 自动提供：

API
Audit
Execution
Task
Error
Metrics
Tracing

---

156. Agent Plugin

Plugin：

Skill
Capability

Agent：

Goal
Plan
Execution
Observation

Plugin 不实现 Agent。

---

157. Full Plugin Example

例如：

acme.seo

提供：

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：

Identity
Permission
Resource
Action
Task
Job
Queue
Worker
Event
Data
Search
Storage
Config
Secret
Provider
Observability
UI Shell
Plugin Runtime

Plugin：

Business Domain

例如：

SEO
GitHub
Docker
Cloudflare
CRM
WordPress

---

159. 什么应该进入 Core

只有满足：

多个 Plugin 都需要
且
不属于具体业务领域

才进入 Core。

例如：

Task
File
Audit
Search
Permission
Provider

应该进入 Core。

---

160. 什么不能进入 Core

不要因为某个 Plugin 需要：

SEO backlink
GitHub repository
Docker container

就把这些放入 Core。

否则：

Core
 ↓
越来越大
 ↓
越来越难升级
 ↓
失去 Plugin 架构意义

---

161. Plugin Architecture Golden Boundary

最终：

                    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”

绝对禁止：

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 应该是：

Domain Extension

而不是：

Mini Application

因此：

DevOS = Platform

Plugin = Domain

App = Composition

---

164. App 与 Plugin 的关系

例如：

DevOS
 │
 ├── SEO Plugin
 ├── GitHub Plugin
 ├── Docker Plugin
 ├── Cloudflare Plugin
 └── Content Plugin
        ↓
       App

App 只是：

Plugin Composition
+
Configuration
+
Navigation
+
Workflow
+
Agent

---

165. SEO App

不要：

SEO Core
SEO Infra
SEO Agent Platform

应该：

DevOS Core
 ↓
SEO Plugin
 ↓
SEO Skills
 ↓
SEO Agents
 ↓
SEO App

SEO 的基础设施能力由：

Data
Task
Queue
Storage
Event
Provider
Search

提供。

---

166. Plugin Composition

例如一个 DevOps App：

GitHub Plugin
+
Docker Plugin
+
Cloudflare Plugin
+
SSH Provider
+
Agent Skill
+
Workflow

不需要开发新的 Backend Core。

---

167. Plugin + Agent

例如：

Goal:
部署项目到生产环境

Agent：

GitHub Plugin
 ↓
build action

Docker Plugin
 ↓
image action

SSH Provider
 ↓
server action

Cloudflare Plugin
 ↓
dns action

全部统一 Action Runtime。

---

168. Plugin + Workflow

固定流程：

Build
 ↓
Test
 ↓
Deploy
 ↓
Health Check
 ↓
DNS

Workflow。

动态决策：

如果部署失败
 ↓
分析日志
 ↓
决定 rollback

Agent。

Plugin 只提供：

Capabilities

---

169. Plugin + MCP

用户可以：

Chat
 ↓
Agent
 ↓
SEO Skill
 ↓
SEO Plugin Action

外部 AI Client 也可以：

Claude / Cursor / Other Agent
 ↓
MCP
 ↓
DevOS Capability Gateway
 ↓
SEO Plugin Action

两者最终进入：

Action Runtime

---

170. Plugin + Global Search

用户输入：

Cloudflare production

Global Search 可以返回：

Cloudflare Account
Cloudflare Zone
DNS Record
Deployments
Tasks

这些来自不同 Plugin。

---

171. Plugin + Global Command

Command Palette：

Scan Website
Deploy Production
Restart Container
Create GitHub Repository

Command 来自：

Action Registry

Plugin 安装之后自动出现。

---

172. Plugin + Universal Resource UI

如果 Plugin 定义：

seo.website

并提供：

schema
fields
relations
actions

DevOS 可以自动生成：

List
Detail
Search
Filter
Create
Edit
Bulk Actions

因此 Plugin 开发成本极低。

---

173. Plugin + Generic UI

这意味着：

80% CRUD Plugin

可能只需要：

Resource Schema
Action

而不是：

Controller
Service
Repository
DTO
CRUD UI
Table
Form

全部手写。

---

174. Plugin UI 的自由度

对于复杂 UI：

Plugin
 ↓
Custom React Components

对于简单 UI：

Resource Schema
 ↓
Generic UI

两种模式必须同时支持。

---

175. Plugin API Extension

Plugin 可以增加：

REST endpoint

但推荐：

Action
 ↓
Generic Action API

只有特殊协议才允许：

Custom API Adapter

---

176. Plugin Webhook

Plugin 可以声明 Webhook：

POST /api/plugins/seo/webhook/google

但进入：

Webhook Runtime

然后：

Webhook
 ↓
Event
 ↓
Task
 ↓
Action

---

177. Plugin OAuth

OAuth 不应该自己存 Token。

流程：

Plugin Provider
 ↓
Credential Runtime
 ↓
OAuth
 ↓
Credential
 ↓
Secret

---

178. Plugin External Resource

例如 GitHub：

github.repository

可以是：

External Resource

由：

External Resource Provider

负责同步。

Plugin 只定义：

Schema
Provider
Actions

---

179. Plugin Sync

例如：

GitHub Repository
 ↓
Sync
 ↓
DevOS Resource

同步：

Scheduler
 ↓
Task
 ↓
Job
 ↓
Action

而不是：

Plugin setInterval()

---

180. Plugin Cache

Plugin 不应该直接：

redis.set("seo:...")

使用：

CacheRuntime

支持：

namespace
TTL
invalidation
serialization
scope

---

181. Plugin Rate Limit

例如 GitHub API：

5000 req/hour

Plugin 使用：

Provider Rate Limit

统一 Runtime 负责：

queue
retry
backoff
concurrency

---

182. Plugin Cost Tracking

Plugin 调用：

OpenAI
Ahrefs
Google
Cloudflare

都应该记录：

provider
action
task
job
execution
cost

进入：

Usage / Cost Runtime

---

183. Plugin Billing

如果未来支持 SaaS：

Plugin Usage
 ↓
Usage Runtime
 ↓
Billing

Plugin 不自己计费。

---

184. Plugin Resource Scope

Plugin Resource 自动继承：

Organization
Project
Environment
User

例如：

seo.website

自动支持：

organizationId
projectId
environmentId

由 Resource/Scope Runtime 实现。

---

185. Plugin Multi-Tenant

Plugin 不允许自己：

tenant_id

重新实现多租户隔离逻辑。

应该使用：

ScopeProvider

统一注入。

---

186. Plugin Permission Discovery

Agent 搜索 Plugin Capability 时：

Capability
 ↓
Permission Check
 ↓
Scope Check
 ↓
Policy Check
 ↓
Availability

只有可用 Capability 才返回。

---

187. Plugin Installation Permission

安装 Plugin 本身属于高权限 Action：

system.plugin.install

升级：

system.plugin.upgrade

卸载：

system.plugin.uninstall

启停：

system.plugin.activate
system.plugin.disable

全部进入 Action Runtime。

---

188. Plugin Admin Permissions

建议：

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 配置：

plugin.seo.config.read
plugin.seo.config.write

Secret：

secret.read

严格分离。

---

190. Plugin UI Permission

Navigation 可以声明：

permission: "seo.website.read"

用户无权限：

隐藏

或者：

disabled

由 UI Shell 统一处理。

---

191. Plugin Version Matrix

系统必须能够展示：

Plugin:
acme.seo 2.4.0

DevOS:
2026.09

API:
2026-01

Dependencies:
github >=2.0
browser >=1.5

---

192. Plugin Compatibility Registry

统一：

CompatibilityRegistry

检查：

Core
Plugin
SDK
Resource
Action
Event
MCP
Skill
Config

与第 12 文档整合。

---

193. Plugin Diagnostics

插件异常时：

Plugin Diagnostics

输出：

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

可以导出：

Plugin Configuration
Plugin Metadata
Plugin Resources
Plugin Workflows
Plugin Skills

但：

Secret plaintext

绝对不能导出。

---

195. Plugin Import

导入：

Config
Workflow
Skill
Resource mapping

Secret：

重新绑定

而不是跨环境复制 Secret。

---

196. Plugin Backup

Backup 应覆盖：

Plugin Version
Plugin Config
Plugin Migration State
Plugin Data
Plugin Metadata

Secret：

只保存 Secret Reference

---

197. Plugin Disaster Recovery

恢复：

DevOS Core
 ↓
Plugin Lockfile
 ↓
Plugin Packages
 ↓
Database
 ↓
Plugin Migrations
 ↓
Config
 ↓
Provider Binding
 ↓
Health Check

---

198. Plugin Cold Start

系统启动：

Load Core
 ↓
Load Plugin Registry
 ↓
Resolve Dependencies
 ↓
Load Active Plugins
 ↓
Register Capabilities
 ↓
Start Workers
 ↓
Start Event Handlers
 ↓
Health Check

---

199. Plugin Startup Failure

如果某个 Plugin 启动失败：

Core
  ↓
继续启动

而不是：

一个 Plugin
 ↓
整个 DevOS 无法启动

除非 Manifest 声明：

requiredForBoot: true

这种能力应极少使用。

---

200. Core Plugin

有些基础能力可以采用 Plugin 形式：

Core Plugin

例如：

devos.github
devos.docker

虽然是官方 Plugin，但仍然遵守 Plugin Runtime。

---

201. Core 与 Official Plugin

区别：

Core
=
系统不可缺少基础设施

Official Plugin
=
官方维护的业务能力

例如：

Auth
Task
Storage
Event

属于 Core。

GitHub
Cloudflare
Docker

可以是 Official Plugin。

---

202. Plugin API Stability

Plugin API 应尽可能稳定。

推荐：

apiVersion = date/version

例如：

2026-01

Breaking Change：

2027-01

而不是频繁：

2026.01.01
2026.01.02

---

203. Plugin Deprecation

某个 API：

Action API v1

准备删除：

deprecated

生命周期：

active
 ↓
deprecated
 ↓
removed

至少提供：

warning
migration guide
replacement

---

204. Plugin Action Version

Plugin Action：

seo.website.scan@1
seo.website.scan@2

不要直接破坏旧 Action。

与第 12 文档统一。

---

205. Plugin Event Version

事件：

seo.scan.completed@1
seo.scan.completed@2

旧事件不能因为 Plugin 升级而改变 payload 语义。

---

206. Plugin Skill Version

Skill：

seo.audit@1
seo.audit@2

Agent Plan 必须记录 Skill Version。

---

207. Plugin MCP Version

MCP Capability：

seo.mcp@1

升级时：

Capability Registry

记录：

mcpVersion

---

208. Reproducibility

任何 Execution 都应该可以追溯：

DevOS Version
Plugin Version
Action Version
Skill Version
MCP Version
Config Version
Provider Version

与第 12、17、18 文档统一。

---

209. Plugin Execution Trace

例如：

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

统一：

interface PluginError {
  code: string

  pluginId: string

  pluginVersion: string

  category:
    | "configuration"
    | "dependency"
    | "provider"
    | "runtime"
    | "migration"
    | "permission"
    | "network"

  retryable: boolean
}

---

211. Plugin Rate Control

Plugin 可以声明：

limits: {
  maxConcurrentTasks: 10,
  maxRequestsPerMinute: 100,
}

最终进入：

Task Runtime
Provider Runtime
RateLimit Runtime

---

212. Plugin Resource Group

例如：

seo.crawler

限制：

maxConcurrent = 5

用于：

CPU
Browser
External API
Server

统一资源组机制。

---

213. Plugin Backpressure

当：

SEO Task

大量增加：

10000 jobs

系统应该：

Queue
 ↓
Backpressure
 ↓
Concurrency Limit
 ↓
Provider Rate Limit

Plugin 不自己实现队列。

---

214. Plugin Cleanup Worker

Plugin 可以声明 Cleanup Job：

temporary crawl data

但仍然：

Scheduler
 ↓
Task
 ↓
Job
 ↓
Worker

---

215. Plugin Retention

Plugin 可以声明：

retention: {
  crawlArtifacts: "30d",
  logs: "7d"
}

实际执行由：

Retention Runtime

完成。

---

216. Plugin Event Replay

如果 Plugin 被禁用：

Event

可以：

replay

但必须检查：

version
schema
idempotency

---

217. Plugin Event Subscription Lifecycle

Plugin Activate
 ↓
Subscribe
 ↓
Active

Plugin Disable
 ↓
Unsubscribe

Plugin Upgrade
 ↓
Drain
 ↓
Update Handler
 ↓
Subscribe

---

218. Plugin MCP Lifecycle

Activate
 ↓
Register MCP
 ↓
Capability Available

Disable
 ↓
MCP Unavailable

外部 Client 看到：

capability unavailable

而不是：

500 random error

---

219. Plugin UI Lifecycle

Plugin Activate
 ↓
UI Registration

Plugin Disable
 ↓
UI Hidden

已经打开页面：

显示 Plugin Disabled

而不是整个 SPA 崩溃。

---

220. Plugin Data Lifecycle

Install
 ↓
Create/Sync
 ↓
Active
 ↓
Disable
 ↓
Data retained
 ↓
Uninstall
 ↓
Data retained or deleted by explicit policy

---

221. Plugin Package Lifecycle

Discover
 ↓
Download
 ↓
Verify
 ↓
Install
 ↓
Activate
 ↓
Upgrade
 ↓
Disable
 ↓
Uninstall

---

222. Plugin Runtime 与 Deployment

Plugin 最终应该能通过：

DevOS Deployment Runtime

部署。

例如：

Production
 ↓
devos.lock
 ↓
Plugin Packages
 ↓
Install
 ↓
Migrate
 ↓
Activate

保证环境一致。

---

223. Plugin CI/CD

CI：

lint
typecheck
test
contract test
build
package
checksum
signature

CD：

publish
 ↓
compatibility
 ↓
canary
 ↓
rollout

---

224. Plugin Build

建议：

devos plugin build

输出：

dist/
plugin.tgz
manifest.json
checksum

---

225. Plugin Publish

devos plugin publish

发布前自动：

validate
test
compatibility
security
package
sign

---

226. Plugin Quality Gate

生产发布必须至少：

TypeScript compile
Unit tests
Integration tests
Contract tests
Migration tests
Security scan
Dependency scan
Manifest validation
Compatibility validation

---

227. Plugin Acceptance Test

每个 Plugin 最少测试：

Manifest

ID
Version
API
Dependency

Runtime

Install
Activate
Disable
Upgrade
Uninstall

Resource

CRUD
Query
Permission
Scope

Action

Input
Output
Error
Retry
Audit

Config

Read
Write
Environment
Secret Reference

Event

Publish
Subscribe
Retry
Idempotency

Task

Create
Execute
Cancel
Retry

---

228. Plugin Security Acceptance

必须测试：

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

测试：

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

模拟：

Provider unavailable
Database unavailable
Queue unavailable
Migration failure
UI registration failure
Worker crash
Event handler crash

系统必须：

degrade gracefully

---

231. Plugin Agent Acceptance

测试：

Agent finds Plugin Capability
 ↓
Permission filtering
 ↓
Skill selection
 ↓
Action execution
 ↓
Task
 ↓
Execution
 ↓
Event
 ↓
Observation

---

232. Plugin MCP Acceptance

测试：

MCP Tool discovery
Permission
Scope
Action mapping
Execution
Error
Audit

---

233. Plugin UI Acceptance

测试：

Install
 ↓
Navigation appears

Disable
 ↓
Navigation disappears

Enable
 ↓
Navigation returns

以及：

permission denied

时正确隐藏/禁止。

---

234. Plugin Developer Experience

目标：

一个成熟开发者应该可以在几十分钟内写出一个基本 Plugin。

最少步骤：

devos plugin create hello
cd hello
devos plugin dev

定义：

Resource
Action
Page

即可看到：

UI
API
Agent Capability

---

235. Plugin 代码量目标

一个简单 CRUD Plugin：

Resource Schema
Action
Manifest

约：

100~300 lines

而不是：

Controller
Service
Repository
DTO
React Page
React Table
React Form
API Client

几千行。

---

236. Plugin Scaffold

推荐生成：

src/
├── manifest.ts
├── resources/
├── actions/
├── skills/
├── config/
├── ui/
└── index.ts

---

237. Plugin SDK Example

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

只要定义：

fields
relations
actions

DevOS 自动：

Table
Form
Detail
Search
Filter
Actions

---

239. Plugin Custom UI

复杂业务：

SEO Site Audit Graph
Backlink Graph
Deployment Console
Container Logs

允许：

Custom React Component

但是数据访问仍：

DevOS API

---

240. Plugin UI SDK

建议：

@devos/plugin-ui

提供：

useResource()
useQuery()
useAction()
useTask()
useEvent()
useConfig()
useCapability()
useAgent()

---

241. Plugin Agent UI

Plugin 可以注册：

Agent Context Widget

例如：

用户正在查看：
example.com

Agent Context:
SEO Score 83
Issues 12
Backlinks 1200

Agent 可以直接使用当前 Resource Context。

---

242. Plugin Context Provider

UI：

Resource Detail
 ↓
Plugin Widget
 ↓
Context
 ↓
Agent

例如：

Agent:
分析这个网站

自动绑定：

resourceId = seo.website:123

---

243. Plugin Command Palette

Plugin 可以注册：

Scan Website
Analyze Keywords
Deploy Container
Restart Server

统一进入：

Action Registry

---

244. Plugin Global Search Provider

Plugin 可以声明：

searchProvider: {
  resources: [
    "seo.website",
    "seo.keyword"
  ]
}

Global Search 自动索引。

---

245. Plugin Notification

Plugin 可以触发：

Notification

例如：

SEO Audit Completed

统一：

Notification Runtime

支持：

in-app
email
webhook
push

---

246. Plugin Webhook

Plugin 可以提供：

Webhook Endpoint

但必须通过：

Webhook Runtime

自动获得：

signature
retry
SSRF protection
audit
event

---

247. Plugin External Webhook

Plugin 也可以向外部发送：

Webhook Action

同样：

Provider
Event
Task
Action

统一执行。

---

248. Plugin Import/Export

Plugin 可以声明：

Import schema
Export schema

使用：

Import Runtime
Export Runtime

支持：

CSV
JSON
JSONL
Excel

---

249. Plugin Bulk Actions

例如：

100 websites
 ↓
Bulk Scan

必须：

1 Task
100 Jobs

而不是：

100 Agent Runs

---

250. Plugin Batch API

Action：

seo.website.bulkScan

内部：

Task
 ↓
Job Factory
 ↓
100 Jobs
 ↓
Queue

---

251. Plugin Performance

Plugin 不应该：

一次加载 10000 Resources

使用：

Query
Pagination
Cursor
Search
Batch
DataLoader

---

252. Plugin Query Security

Plugin Query 自动经过：

Permission
Scope
Field Permission
Cost Limit
Timeout

---

253. Plugin Cache Security

Cache Key 必须包含：

organization
project
environment
resource

防止：

Tenant A
 ↓
Cache
 ↓
Tenant B

数据泄漏。

---

254. Plugin Resource Naming

统一：

<plugin>.<resource>

例如：

github.repository
github.issue

docker.container
docker.image

seo.website
seo.keyword

---

255. Plugin Action Naming

统一：

<plugin>.<resource>.<verb>

例如：

github.repository.create
github.repository.sync

docker.container.restart

seo.website.scan

---

256. Plugin Event Naming

统一：

<plugin>.<resource>.<event>

例如：

seo.website.scanned
seo.audit.completed
github.repository.synced

---

257. Plugin Skill Naming

<plugin>.<skill>

例如：

seo.audit
seo.content.strategy

github.issue.triage

---

258. Plugin Workflow Naming

<plugin>.<workflow>

例如：

seo.full_audit
github.release
docker.deploy

---

259. Plugin MCP Naming

<plugin>.mcp

例如：

seo.mcp
github.mcp

---

260. Plugin Provider Naming

<plugin>.<provider>

例如：

github.api
cloudflare.api

---

261. Plugin Configuration Naming

plugin.<pluginId>.<key>

例如：

plugin.seo.crawler.maxDepth
plugin.seo.content.language

---

262. Plugin Permission Naming

<plugin>.<resource>.<action>

例如：

seo.website.read
seo.website.scan
seo.website.delete

---

263. Plugin UI Route Naming

推荐：

/<plugin>
/<plugin>/<resource>

例如：

/seo
/seo/websites
/seo/keywords

不要：

/plugin/acme.seo/page1

用户看到的应该是业务路径。

---

264. Plugin Internal Route

如果需要内部页面：

/_plugins/<pluginId>/...

可以保留，但不作为主要用户 URL。

---

265. Plugin API Namespace

业务 API：

/api/actions/seo.website.scan

或者：

/api/resources/seo.website

而不是每个 Plugin 自己：

/api/seo/*

这样统一 API Runtime。

---

266. Plugin Graph

DevOS 可以维护：

Plugin Graph

例如：

SEO
├── GitHub
├── Browser
├── OpenAI
└── Storage

用于：

Dependency
Capability
Health
Impact
Upgrade

---

267. Plugin Graph UI

Plugin Detail：

Dependencies
       ↓
      SEO
       ↓
Capabilities
       ↓
Actions / Skills / MCP

非常适合诊断。

---

268. Plugin Marketplace 与 Dependency

Marketplace 安装：

SEO

自动显示：

Required:
Browser

Optional:
Ahrefs
OpenAI
GitHub

然后生成：

Install Plan

---

269. Install Plan

interface PluginInstallPlan {
  plugins: PluginPlanItem[]

  dependencies: DependencyChange[]

  migrations: MigrationPlan[]

  configChanges: ConfigChange[]

  risks: Risk[]

  warnings: string[]
}

---

270. Plugin Upgrade Plan

与第 12 文档：

UpgradePlan

统一。

不要建立第二个完全不同的 Upgrade Plan。

---

271. Plugin Runtime 与 Migration Runtime

Plugin Runtime：

负责什么时候升级

Migration Runtime：

负责怎么迁移

边界：

Plugin Runtime
 ↓
Migration Runtime
 ↓
Database

---

272. Plugin Runtime 与 Config Runtime

Plugin Runtime：

Plugin 生命周期

Config Runtime：

Plugin 配置

Plugin 只能：

ctx.config.get(...)

---

273. Plugin Runtime 与 Secret Runtime

Plugin Runtime：

生命周期

Secret Runtime：

Secret

Plugin 只能：

credential reference

而不是：

secret database

---

274. Plugin Runtime 与 Event Runtime

Plugin：

declare event
subscribe event
publish event

Event Runtime：

delivery
retry
ordering
replay
DLQ

---

275. Plugin Runtime 与 Task Runtime

Plugin：

create Task

Task Runtime：

Task → Job → Queue → Worker

---

276. Plugin Runtime 与 Agent Runtime

Plugin：

提供 Capability / Skill

Agent Runtime：

Goal → Plan → Execute

---

277. Plugin Runtime 与 UI Shell

Plugin：

注册 UI

UI Shell：

渲染 UI
导航
权限
布局

---

278. Plugin Runtime 与 Storage

Plugin：

File / Artifact

Storage：

Blob

---

279. Plugin Runtime 与 Data

Plugin：

Resource Schema

Data Runtime：

Query
Repository
Provider

---

280. Plugin Runtime 与 Search

Plugin：

Search Definition

Search Runtime：

Index
Query
Ranking
Embedding

---

281. Plugin Runtime 与 Observability

Plugin：

Logger
Metric
Trace
Audit

Observability：

collection
storage
query
dashboard
alert

---

282. Plugin API Golden Rule

任何 Plugin 对外暴露：

Resource
Action
Event
Capability
Skill
MCP
UI

必须注册到：

DevOS Registry

不能建立自己的：

parallel registry

---

283. Plugin Execution Golden Rule

所有执行：

Plugin Action
Plugin Worker
Plugin Workflow
Plugin MCP
Plugin Skill
Plugin Webhook
Plugin Scheduler

最终必须进入：

Action Runtime

或者：

Task Runtime

不能绕过。

---

284. Plugin Data Golden Rule

所有数据：

Plugin Resource

必须通过：

Data Runtime

所有 Blob：

Storage Runtime

所有 Secret：

Secret Runtime

---

285. Plugin Event Golden Rule

所有事件：

Plugin Event

必须进入：

Event Runtime

所有 Notification：

Notification Runtime

---

286. Plugin UI Golden Rule

Plugin UI：

Plugin UI
 ↓
UI Shell
 ↓
DevOS API
 ↓
Runtime

禁止：

Plugin UI
 ↓
Direct DB

---

287. Plugin Agent Golden Rule

Agent
 ↓
Capability Registry
 ↓
Plugin Capability
 ↓
Action Runtime

不要：

Agent
 ↓
Plugin internals

---

288. Plugin Security Golden Rule

Plugin：

Permission
Scope
Policy
Approval

必须继承 DevOS Security Runtime。

---

289. Plugin Version Golden Rule

任何 Plugin Execution 都必须记录：

pluginVersion
apiVersion
actionVersion
skillVersion
mcpVersion
configVersion

保证：

reproducibility
auditability
rollback

---

290. Plugin Architecture Final Diagram

最终完整结构：

                         ┌──────────────────────┐
                         │      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 必须至少新增：

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 当前不做：

packages/plugin/marketplace

可以先预留接口。

---

292. Zcode 必须实现的数据库

至少：

plugins
plugin_versions
plugin_dependencies
plugin_installations
plugin_artifacts
plugin_migrations
plugin_health
plugin_locks

如果 Capability Registry 已有持久化模型，不重复创建 Capability 表。

---

293. Zcode 禁止新增的重复系统

禁止 Plugin Runtime 创建：

plugin_tasks
plugin_jobs
plugin_queue
plugin_events
plugin_notifications
plugin_users
plugin_roles
plugin_secrets
plugin_storage
plugin_search
plugin_scheduler

如果业务确实需要这些概念：

使用 DevOS Runtime

---

294. Zcode 实现优先级

P0

必须完成：

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

然后：

Plugin UI
Plugin Skill
Plugin MCP
Plugin Event
Plugin Worker
Plugin Health
Plugin Migration
Plugin Upgrade
Plugin Uninstall

---

P2

最后：

Marketplace
Signature
Sandbox
Canary
Private Registry
Advanced Plugin Graph

---

295. Zcode 第一阶段验收

执行：

devos plugin create hello

应该生成 Plugin。

然后：

devos plugin build
devos plugin validate
devos plugin install
devos plugin enable

系统应该出现：

Plugin:
Hello

Status:
Active

---

296. Zcode 第二阶段验收

Plugin 定义：

Resource:
hello.message

Action:
hello.message.create
hello.message.delete

安装后自动得到：

Resource UI
Action API
Permission
Audit
Search

---

297. Zcode 第三阶段验收

Plugin 增加：

Skill:
hello.greeting

Agent：

Goal:
创建一条 Hello Message

Agent 必须自动发现：

hello.greeting

并调用：

hello.message.create

---

298. Zcode 第四阶段验收

Plugin 增加：

MCP

外部 MCP Client：

discover
 ↓
hello.message.create
 ↓
Action Runtime

必须成功。

---

299. Zcode 第五阶段验收

Plugin 增加：

Config
Provider
Secret
Event
Task
Worker
UI

全部必须仍然使用 DevOS Runtime。

---

300. Zcode 最终验收

完整 Plugin：

Install
 ↓
Dependency
 ↓
Compatibility
 ↓
Migration
 ↓
Register
 ↓
Config
 ↓
Provider
 ↓
Resource
 ↓
Action
 ↓
Skill
 ↓
MCP
 ↓
Event
 ↓
Worker
 ↓
UI
 ↓
Health
 ↓
Active

然后：

Upgrade
 ↓
Migration
 ↓
Health
 ↓
Active

最后：

Disable
 ↓
Uninstall
 ↓
Data Retained

整个生命周期必须可观测、可审计、可恢复。

---

301. 最重要的架构原则

DevOS 最终不是：

一个巨大的 Backend

也不是：

一个巨大的 Admin Panel

更不是：

一个 AI Chatbot

而是：

                 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

                    PLUGIN
                       │
        ┌──────────────┼──────────────┐
        │              │              │
     Resource        Action        Capability
        │              │              │
        │              ↓              │
        │        Action Runtime       │
        │              │              │
        │          Task / Job         │
        │              │              │
        └──────────────┼──────────────┘
                       │
                 DevOS Runtime
                       │
      ┌────────────────┼────────────────┐
      │                │                │
     Data            Event           Storage
      │                │                │
    Search          Agent          Notification
      │                │                │
      └────────────────┼────────────────┘
                       │
                    UI Shell

最终原则：

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