devos/Docs/DevOS-Platform-v2/11_PLUGIN_RUNTIME.md

# DevOS Plugin Runtime

> Version: 1.0
> Status: Implementation Specification
> Target: Zcode
> Previous: 10_EVENT_AUDIT_OBSERVABILITY_RUNTIME.md
> Next: 12_*

---

# 1. 目标

DevOS Plugin Runtime 是整个 DevOS 的扩展系统。

Plugin 必须能够扩展：

- Resource
- Action
- Capability
- Skill
- MCP
- Workflow
- Event
- UI
- Navigation
- Settings
- Dashboard
- Widget
- Notification
- Scheduler
- Worker Capability

Plugin 不是简单的 npm package。

Plugin 是：

> 可以被 DevOS 安装、配置、启停、升级、卸载，并向 DevOS Runtime 注册能力和 UI 的扩展单元。

---

# 2. 核心原则

Plugin 必须运行在 DevOS Runtime 之上。

正确：

Plugin
  ↓
Plugin Runtime
  ↓
DevOS Registry
  ↓
DevOS Runtime

禁止：

Plugin
  ↓
自己的数据库
  ↓
自己的 Queue
  ↓
自己的 Auth
  ↓
自己的 EventBus
  ↓
自己的 Task System

除非明确声明为 external service，并通过标准 Adapter 接入。

---

# 3. Plugin 的本质

Plugin 是：

```text
Extension Package
+
Manifest
+
Runtime
+
Capabilities
+
UI
+
Configuration
````

例如 SEO Plugin：

```text
seo.plugin
├── Resource
│   ├── seo.website
│   ├── seo.keyword
│   └── seo.article
│
├── Action
│   ├── seo.website.scan
│   ├── seo.keyword.research
│   └── seo.article.generate
│
├── Skill
│   ├── seo-audit
│   └── content-generation
│
├── MCP
│   ├── search-engine
│   └── browser
│
├── Workflow
│   └── seo-audit-workflow
│
├── Event
│   ├── seo.website.scanned
│   └── seo.article.generated
│
└── UI
    ├── Website
    ├── Keywords
    ├── Articles
    └── Settings
```

---

# 4. Plugin Namespace

每个 Plugin 必须拥有唯一 namespace。

格式：

```text
<vendor>.<plugin>
```

例如：

```text
devos.seo
devos.devops
devos.crm
github.integration
cloudflare.integration
```

Plugin 内部 Resource：

```text
devos.seo.website
devos.seo.keyword
```

Action：

```text
devos.seo.website.scan
```

Skill：

```text
devos.seo.audit
```

禁止两个 Plugin 注册同一个 namespace。

---

# 5. Plugin ID

Plugin ID：

```ts
type PluginId = string
```

例如：

```text
devos.seo
```

必须满足：

```text
^[a-z0-9][a-z0-9._-]*$
```

---

# 6. Plugin Manifest

每个 Plugin 必须提供：

```text
plugin.json
```

推荐：

```json
{
  "id": "devos.seo",
  "name": "SEO",
  "version": "1.0.0",
  "description": "SEO automation capabilities",
  "runtime": "devos",
  "apiVersion": "1",
  "author": "DevOS",
  "license": "MIT"
}
```

---

# 7. 完整 Manifest

```ts
interface PluginManifest {
  id: string

  name: string

  version: string

  description?: string

  apiVersion: string

  runtime: 'devos'

  author?: string

  homepage?: string

  repository?: string

  license?: string

  icon?: string

  categories?: string[]

  dependencies?: PluginDependency[]

  optionalDependencies?: PluginDependency[]

  permissions?: PluginPermission[]

  capabilities?: PluginCapabilityDeclaration[]

  resources?: PluginResourceDeclaration[]

  actions?: PluginActionDeclaration[]

  skills?: PluginSkillDeclaration[]

  mcp?: PluginMCPDeclaration[]

  workflows?: PluginWorkflowDeclaration[]

  events?: PluginEventDeclaration[]

  ui?: PluginUIDeclaration[]

  settings?: PluginSettingDeclaration[]

  workers?: PluginWorkerDeclaration[]
}
```

---

# 8. Plugin 生命周期

Plugin 状态：

```text
discovered
 ↓
installing
 ↓
installed
 ↓
configuring
 ↓
enabled
 ↓
running
 ↓
disabled
 ↓
uninstalling
 ↓
uninstalled
```

异常：

```text
install_failed
activation_failed
runtime_error
upgrade_failed
```

---

# 9. Plugin Runtime 状态

```ts
type PluginStatus =
  | 'discovered'
  | 'installing'
  | 'installed'
  | 'configuring'
  | 'enabled'
  | 'running'
  | 'disabled'
  | 'uninstalling'
  | 'uninstalled'
  | 'install_failed'
  | 'activation_failed'
  | 'runtime_error'
  | 'upgrade_failed'
```

---

# 10. Plugin Resource

Plugin 本身必须成为 DevOS Resource：

```text
core.plugin
```

Plugin Resource：

```text
core.plugin.installation
```

---

# 11. Plugin Actions

至少：

```text
core.plugin.install
core.plugin.uninstall
core.plugin.enable
core.plugin.disable
core.plugin.restart
core.plugin.upgrade
core.plugin.configure
core.plugin.health
core.plugin.reload
```

---

# 12. 所有 Plugin 管理操作必须走 Action Runtime

错误：

```text
POST /plugins/:id/enable

controller:
  plugin.enable()
```

正确：

```text
HTTP
 ↓
core.plugin.enable
 ↓
Action Runtime
 ↓
Plugin Runtime
```

CLI：

```text
devos plugin enable devos.seo
```

也必须：

```text
CLI
 ↓
Action Runtime
 ↓
core.plugin.enable
```

Agent：

```text
Agent
 ↓
core.plugin.enable
 ↓
Action Runtime
```

三者执行路径必须完全一致。

---

# 13. Plugin Installation Record

数据库：

```ts
interface PluginInstallation {
  id: string

  pluginId: string

  version: string

  status: PluginStatus

  source: PluginSource

  enabled: boolean

  installedAt: Date

  updatedAt: Date

  activatedAt?: Date

  disabledAt?: Date

  error?: string

  metadata?: Record<string, unknown>
}
```

---

# 14. Plugin Source

支持：

```ts
type PluginSource =
  | {
      type: 'builtin'
    }
  | {
      type: 'local'
      path: string
    }
  | {
      type: 'package'
      package: string
      version?: string
    }
  | {
      type: 'git'
      repository: string
      ref?: string
    }
  | {
      type: 'url'
      url: string
    }
```

第一阶段至少实现：

```text
builtin
local
package
```

Git / URL 可以作为后续扩展。

---

# 15. Built-in Plugin

DevOS 自己的功能也可以 Plugin 化。

例如：

```text
devos.core
devos.seo
devos.devops
```

但 Core Runtime 本身不能依赖 Plugin Runtime 才能启动。

即：

```text
Core Runtime
   ↓
Plugin Runtime
   ↓
Optional Plugins
```

而不是：

```text
Plugin Runtime
   ↓
Core Runtime
```

---

# 16. Plugin Registration

Plugin 激活后：

```text
Plugin
 ↓
Manifest
 ↓
Validate
 ↓
Register
 ├── Resources
 ├── Actions
 ├── Capabilities
 ├── Skills
 ├── MCP
 ├── Events
 ├── Workflows
 └── UI
```

---

# 17. Plugin Registry

实现：

```ts
interface PluginRegistry {
  register(plugin: RegisteredPlugin): Promise<void>

  unregister(pluginId: string): Promise<void>

  get(pluginId: string): RegisteredPlugin | undefined

  list(): RegisteredPlugin[]

  has(pluginId: string): boolean
}
```

---

# 18. Registered Plugin

```ts
interface RegisteredPlugin {
  manifest: PluginManifest

  status: PluginStatus

  runtime: PluginRuntime

  registeredAt: Date
}
```

---

# 19. Plugin Runtime

```ts
interface PluginRuntime {
  initialize(context: PluginContext): Promise<void>

  activate(context: PluginContext): Promise<void>

  deactivate(context: PluginContext): Promise<void>

  dispose(context: PluginContext): Promise<void>

  health(): Promise<PluginHealth>
}
```

---

# 20. Plugin Context

```ts
interface PluginContext {
  pluginId: string

  version: string

  logger: Logger

  eventBus: EventBus

  resourceRegistry: ResourceRegistry

  actionRegistry: ActionRegistry

  capabilityRegistry: CapabilityRegistry

  skillRegistry: SkillRegistry

  mcpRegistry: MCPRegistry

  config: PluginConfigService

  storage: PluginStorage

  signal: AbortSignal
}
```

Plugin 不应该直接拿：

```text
PrismaClient
RedisClient
BullMQ
```

Plugin 应该使用 DevOS 提供的抽象。

---

# 21. Plugin Storage

某些 Plugin 需要自己的持久化数据。

提供：

```ts
interface PluginStorage {
  get<T>(key: string): Promise<T | undefined>

  set<T>(key: string, value: T): Promise<void>

  delete(key: string): Promise<void>
}
```

但这是：

> Plugin Storage

不是：

> Plugin 自己拥有一套数据库系统。

---

# 22. Plugin Database

如果 Plugin 需要复杂业务数据：

必须通过 DevOS Database / ORM / Migration Runtime。

例如：

```text
packages/plugins/seo
  migrations/
  schema/
```

数据库表必须带 Plugin Namespace。

例如：

```text
seo_websites
seo_keywords
seo_articles
```

禁止 Plugin 私自建立第二个 PostgreSQL 实例。

---

# 23. Plugin Configuration

Plugin 可以声明 Settings。

例如：

```json
{
  "settings": [
    {
      "key": "defaultModel",
      "type": "string",
      "required": true
    },
    {
      "key": "apiEndpoint",
      "type": "url"
    }
  ]
}
```

---

# 24. Plugin Setting Schema

```ts
interface PluginSettingDeclaration {
  key: string

  type:
    | 'string'
    | 'number'
    | 'boolean'
    | 'secret'
    | 'url'
    | 'select'
    | 'multiselect'
    | 'json'

  label: string

  description?: string

  required?: boolean

  default?: unknown

  options?: {
    label: string
    value: string
  }[]
}
```

---

# 25. Plugin Settings Resource

Plugin 配置应该属于：

```text
core.plugin.settings
```

而不是：

```text
plugin_database_table
```

API：

```text
GET
/api/plugins/:pluginId/settings

PUT
/api/plugins/:pluginId/settings
```

但是最终执行：

```text
core.plugin.configure
```

---

# 26. Secret Settings

例如：

```text
OpenAI API Key
Cloudflare API Token
GitHub Token
SMTP Password
```

必须使用：

```text
type = secret
```

数据库不得明文保存。

推荐：

```text
Encryption at Rest
```

读取时默认：

```text
********
```

只有真正执行需要时才能在 Runtime 内解密。

---

# 27. Plugin Settings 权限

必须区分：

```text
plugin.view
plugin.configure
plugin.install
plugin.uninstall
plugin.enable
plugin.disable
```

普通用户：

```text
plugin.view
```

管理员：

```text
plugin.configure
```

系统管理员：

```text
plugin.install
plugin.uninstall
```

具体策略由 RBAC / Policy Runtime 控制。

---

# 28. Plugin UI

Plugin 可以提供自己的页面。

例如：

```text
SEO
├── Overview
├── Websites
├── Keywords
├── Articles
├── Tasks
└── Settings
```

Plugin UI 不是独立 SPA。

必须挂载到：

```text
DevOS UI Shell
```

---

# 29. Plugin UI Manifest

```ts
interface PluginUIDeclaration {
  routes?: PluginRoute[]

  navigation?: PluginNavigationItem[]

  dashboards?: PluginDashboard[]

  widgets?: PluginWidget[]

  settingsPage?: boolean
}
```

---

# 30. Plugin Route

```ts
interface PluginRoute {
  id: string

  path: string

  title: string

  component: string

  icon?: string

  permissions?: string[]
}
```

例如：

```json
{
  "id": "seo-websites",
  "path": "/seo/websites",
  "title": "Websites",
  "component": "SeoWebsitesPage",
  "permissions": [
    "devos.seo.website.read"
  ]
}
```

---

# 31. Plugin Navigation

Plugin 可以向左侧导航注册：

```text
SEO
  Overview
  Websites
  Keywords
  Articles
  Tasks
```

但不能直接修改 DevOS Shell。

必须：

```text
Plugin
 ↓
Navigation Registry
 ↓
UI Shell
```

---

# 32. Navigation Registry

```ts
interface NavigationRegistry {
  register(item: NavigationItem): void

  unregister(pluginId: string): void

  list(context: NavigationContext): NavigationItem[]
}
```

必须根据：

```text
permission
organization
project
plugin enabled
```

动态过滤。

---

# 33. Plugin Dashboard

Plugin 可以提供 Dashboard：

```text
SEO Overview

Websites: 127
Keywords: 3,821
Articles: 1,240
Tasks Running: 17
Errors: 3
```

Dashboard 只负责：

```text
展示
查询
触发 Action
```

不能在 UI 内实现业务逻辑。

---

# 34. Plugin Widget

Plugin 可以注册：

```text
Dashboard Widget
Chat Widget
Task Widget
Resource Widget
Report Widget
```

例如：

```text
SEO Health Score
```

Widget 可以声明：

```ts
interface PluginWidget {
  id: string

  title: string

  component: string

  size: 'small' | 'medium' | 'large'

  permissions?: string[]
}
```

---

# 35. Plugin Page 与 Action Runtime

页面：

```text
按钮：Scan Website
```

不能：

```ts
fetch('/seo/scan')
```

应该：

```text
UI
 ↓
Action Client
 ↓
devos.seo.website.scan
 ↓
Action Runtime
```

---

# 36. Plugin Resource UI

如果 Plugin 注册：

```text
seo.website
```

可以自动获得：

```text
List
Detail
Create
Edit
Delete
```

如果 Resource 声明：

```text
ui.list
ui.detail
```

DevOS Generic UI 可以自动生成。

Plugin 只需要实现复杂页面。

---

# 37. Plugin Actions

Plugin Action：

```ts
interface PluginActionDeclaration {
  id: string

  name: string

  description?: string

  inputSchema: unknown

  outputSchema: unknown

  mode: 'sync' | 'async' | 'stream'

  permissions: string[]

  requiresApproval?: boolean
}
```

Action 最终进入：

```text
Action Registry
```

---

# 38. Plugin Capability

Plugin Action 自动成为 Capability。

例如：

```text
devos.seo.website.scan
```

注册：

```text
Capability
 type = action
 source = plugin
```

Agent 就能够发现。

---

# 39. Plugin Skill

Plugin 可以注册 Skill：

```ts
interface PluginSkillDeclaration {
  id: string

  name: string

  description: string

  version: string

  instructions: string

  requiredCapabilities: string[]

  inputSchema?: unknown

  outputSchema?: unknown
}
```

---

# 40. Plugin 与 Agent

例如：

```text
SEO Plugin
  ↓
Skill:
seo.audit
  ↓
Capabilities:
seo.website.scan
seo.keyword.research
seo.article.generate
  ↓
Agent
```

Agent 不需要知道：

```text
这个能力来自哪个数据库
哪个 Controller
哪个 Plugin 文件
```

只看到：

```text
Capability
```

---

# 41. Plugin MCP

Plugin 可以声明 MCP：

```ts
interface PluginMCPDeclaration {
  id: string

  name: string

  transport:
    | 'stdio'
    | 'http'
    | 'sse'

  endpoint?: string

  command?: string

  args?: string[]
}
```

但是：

**MCP 仍然必须通过 MCP Runtime + Action Runtime。**

---

# 42. Plugin Event

Plugin 可以声明 Event：

```text
devos.seo.website.scanned
devos.seo.article.generated
```

Event 进入：

```text
Event Registry
```

并可以被：

```text
Agent
Workflow
Notification
Webhook
Plugin
```

消费。

---

# 43. Plugin Event Handler

Plugin Handler：

```text
Event
 ↓
Plugin Handler
 ↓
Action Runtime
```

禁止：

```text
Event
 ↓
Plugin Handler
 ↓
直接 DB mutation
```

---

# 44. Plugin Workflow

Plugin 可以提供 Workflow：

```text
seo.full.audit
```

例如：

```text
scan website
 ↓
collect keywords
 ↓
analyze pages
 ↓
generate report
```

Workflow 由：

```text
Action
Task
Job
```

组成。

---

# 45. Plugin Scheduler

Plugin 可以注册 Schedule Definition。

例如：

```text
SEO daily scan
Every day at 03:00
```

最终还是：

```text
Scheduler
 ↓
Task
 ↓
Action
```

Plugin 不得自己运行：

```text
setInterval()
```

或：

```text
node-cron
```

来承担业务调度。

---

# 46. Plugin Worker

某些 Plugin 可能需要特殊 Worker。

例如：

```text
browser
ffmpeg
docker
ssh
```

Plugin 可以声明 Worker Capability：

```ts
interface PluginWorkerDeclaration {
  id: string

  queues: string[]

  capabilities: string[]

  concurrency?: number
}
```

最终由：

```text
Worker Runtime
```

管理。

---

# 47. Plugin Dependencies

例如：

```json
{
  "dependencies": [
    {
      "id": "devos.browser",
      "version": "^1.0.0"
    }
  ]
}
```

安装时：

```text
Plugin A
 ↓
Dependency Resolver
 ↓
Plugin B
 ↓
Install
```

---

# 48. Dependency Version

必须支持：

```text
exact
range
```

例如：

```text
1.2.3
^1.2.0
>=1.0.0 <2.0.0
```

---

# 49. Dependency Graph

Plugin Runtime 必须检测：

```text
A → B
B → C
C → A
```

发现：

```text
circular dependency
```

直接拒绝安装。

---

# 50. Plugin API Version

Plugin 必须声明：

```text
apiVersion
```

例如：

```text
apiVersion = 1
```

DevOS Runtime 升级：

```text
API v1
API v2
```

可以兼容旧 Plugin。

---

# 51. Plugin Compatibility

安装之前必须执行：

```text
Manifest
 ↓
API Compatibility
 ↓
Dependency Compatibility
 ↓
Permission Validation
 ↓
Resource Conflict Check
 ↓
Action Conflict Check
 ↓
Install
```

---

# 52. Resource Conflict

例如：

Plugin A：

```text
seo.website
```

Plugin B：

```text
seo.website
```

必须拒绝：

```text
RESOURCE_NAMESPACE_CONFLICT
```

除非明确声明：

```text
override
```

第一阶段：

**禁止 Override。**

---

# 53. Action Conflict

同样：

```text
seo.website.scan
```

只能由一个 Plugin 注册。

---

# 54. Capability Conflict

Capability ID 也必须唯一。

---

# 55. Plugin Enable

Enable：

```text
core.plugin.enable
 ↓
Load Plugin
 ↓
Validate
 ↓
Register
 ↓
Activate
 ↓
Health Check
 ↓
enabled
```

如果失败：

```text
activation_failed
```

不得标记为 enabled。

---

# 56. Plugin Disable

Disable：

```text
core.plugin.disable
 ↓
Stop accepting new work
 ↓
Drain active work
 ↓
Deactivate
 ↓
Unregister runtime capabilities
 ↓
disabled
```

已经运行中的 Task：

```text
默认继续完成
```

除非 Plugin 声明：

```text
shutdownPolicy = cancel
```

---

# 57. Plugin Uninstall

不能直接删除。

必须：

```text
Disable
 ↓
Check Running Tasks
 ↓
Check Dependencies
 ↓
Check Data Policy
 ↓
Unregister
 ↓
Remove
```

---

# 58. Plugin Data Policy

Manifest 可以声明：

```ts
dataPolicy: {
  preserveOnDisable: boolean

  preserveOnUninstall: boolean

  destructiveUninstall: boolean
}
```

默认：

```text
preserveOnUninstall = true
```

即：

**卸载 Plugin 默认不删除业务数据。**

---

# 59. Plugin Upgrade

升级流程：

```text
Current Plugin
 ↓
Read New Manifest
 ↓
Compatibility Check
 ↓
Dependency Check
 ↓
Migration Plan
 ↓
Backup / Safety Check
 ↓
Disable
 ↓
Migration
 ↓
Install New Version
 ↓
Register
 ↓
Activate
 ↓
Health Check
```

---

# 60. Migration

Plugin Migration：

```ts
interface PluginMigration {
  from: string

  to: string

  up(): Promise<void>

  down?(): Promise<void>
}
```

Migration 必须支持：

```text
version history
```

---

# 61. Upgrade Failure

升级失败必须：

```text
upgrade_failed
```

并尽可能：

```text
Rollback
```

但不要假设所有 Migration 都可以自动 Rollback。

因此：

```text
backup
+
forward migration
+
recovery procedure
```

必须存在。

---

# 62. Plugin Isolation

Plugin 必须受到：

```text
Permission
Namespace
Resource Scope
Action Scope
```

限制。

Plugin 不应该默认拥有：

```text
root filesystem
all environment variables
all secrets
all database tables
```

---

# 63. Plugin Permission Declaration

Manifest：

```json
{
  "permissions": [
    "network:http",
    "storage:plugin",
    "secret:seo-api",
    "resource:seo.website"
  ]
}
```

Permission 必须经过用户/管理员批准。

---

# 64. Permission 分类

至少：

```text
resource
action
network
storage
secret
filesystem
process
worker
mcp
```

---

# 65. Network Permission

Plugin 不应该默认访问任意互联网地址。

推荐：

```text
network:http
network:https
```

未来可以限制：

```text
network:domain:api.example.com
```

---

# 66. Secret Permission

Plugin 请求：

```text
secret:openai
```

只能访问：

```text
OpenAI Credential
```

不能读取：

```text
Cloudflare Credential
GitHub Credential
```

---

# 67. Plugin Credential

统一使用：

```text
Credential Runtime
```

例如：

```text
core.credential
```

Plugin：

```text
Credential Request
 ↓
Permission
 ↓
Credential Runtime
 ↓
Secret
```

Plugin 不应该直接读取 `.env`。

---

# 68. Plugin Environment

Plugin 可以获得：

```ts
interface PluginEnvironment {
  devosVersion: string

  pluginId: string

  pluginVersion: string

  environment: 'development' | 'test' | 'production'
}
```

禁止直接依赖大量 DevOS 内部环境变量。

---

# 69. Plugin Logging

Plugin 必须使用：

```ts
context.logger
```

例如：

```ts
context.logger.info(
  'SEO scan started',
  {
    websiteId
  }
)
```

日志自动获得：

```text
pluginId
correlationId
executionId
taskId
```

---

# 70. Plugin Events

Plugin 必须使用：

```ts
context.eventBus.publish(...)
```

Event 自动补充：

```text
pluginId
```

---

# 71. Plugin Health

```ts
interface PluginHealth {
  status:
    | 'healthy'
    | 'degraded'
    | 'unhealthy'

  message?: string

  checks?: HealthCheck[]
}
```

例如：

```text
SEO Plugin
 ├── Database       healthy
 ├── Search API     healthy
 ├── Browser MCP    degraded
 └── AI Provider    healthy
```

---

# 72. Plugin Health Event

自动产生：

```text
plugin.health.changed
plugin.health.failed
plugin.health.recovered
```

---

# 73. Plugin Observability

Plugin 的：

```text
Action
Task
Job
Execution
Event
Log
Audit
Trace
Metric
```

全部自动带：

```text
pluginId
```

这样可以统计：

```text
Plugin usage
Plugin errors
Plugin latency
Plugin cost
Plugin health
```

---

# 74. Plugin Metrics

自动生成：

```text
devos_plugin_action_total
devos_plugin_error_total
devos_plugin_execution_duration_ms
devos_plugin_task_total
devos_plugin_mcp_request_total
devos_plugin_cost_total
```

---

# 75. Plugin Audit

例如：

```text
plugin.installed
plugin.enabled
plugin.disabled
plugin.upgraded
plugin.uninstalled
plugin.configured
```

都必须产生 Audit。

例如：

```text
Admin Alice
 ↓
core.plugin.enable
 ↓
devos.seo
 ↓
SUCCESS
```

---

# 76. Plugin UI Permission

Plugin 页面不能因为已经加载就绕过权限。

例如：

```text
SEO Settings
```

必须：

```text
plugin.view
+
plugin.configure
```

---

# 77. Plugin Dynamic UI

前端需要：

```text
Plugin Manifest
 ↓
UI Registry
 ↓
Route Registry
 ↓
Navigation Registry
 ↓
Dynamic Module
```

---

# 78. Frontend Plugin Package

推荐：

```text
packages/plugins/seo/
├── manifest.ts
├── backend/
│   ├── index.ts
│   ├── resources/
│   ├── actions/
│   ├── skills/
│   ├── mcp/
│   └── migrations/
│
└── frontend/
    ├── index.ts
    ├── routes/
    ├── pages/
    ├── widgets/
    └── components/
```

---

# 79. Plugin Frontend Contract

Plugin Frontend 不应该：

```text
import backend database
import Prisma
import Redis
```

只能使用：

```text
Action Client
Resource API
Query Client
UI SDK
```

---

# 80. Plugin UI SDK

DevOS 应提供：

```ts
interface DevOSPluginUI {
  registerRoute(...)

  registerNavigation(...)

  registerWidget(...)

  registerDashboard(...)

  registerSettings(...)
}
```

---

# 81. Plugin Action Client

前端：

```ts
await devos.actions.execute(
  'devos.seo.website.scan',
  {
    websiteId
  }
)
```

而不是：

```ts
fetch('/api/seo/scan')
```

---

# 82. Plugin Resource Client

```ts
const websites =
  await devos.resources.list(
    'devos.seo.website'
  )
```

---

# 83. Plugin Task UI

异步 Action 返回：

```ts
{
  taskId: 'task_123'
}
```

前端自动进入：

```text
Task Detail
```

可以显示：

```text
Progress
Jobs
Logs
Events
Execution
Result
```

---

# 84. Plugin Chat Integration

Plugin 可以向 Agent Chat 注册：

```text
context action
```

例如用户打开：

```text
Website: example.com
```

Chat：

```text
Ask Agent about this website
```

Agent 自动获得：

```text
resource = devos.seo.website
resourceId = website_123
```

---

# 85. Plugin Context Provider

```ts
interface PluginContextProvider {
  getContext(
    resource: ResourceReference
  ): Promise<AgentContextData>
}
```

这样 Agent 可以理解：

```text
当前页面
当前 Resource
当前 Project
当前 Task
```

---

# 86. Plugin Report

Plugin 可以注册 Report：

```text
SEO Audit Report
Server Deployment Report
CRM Customer Report
```

Report 应该：

```text
Task
 ↓
Action
 ↓
Artifact
 ↓
Report
```

---

# 87. Plugin Artifact

Plugin 可以生成：

```text
PDF
CSV
JSON
HTML
Markdown
Image
Archive
```

统一进入：

```text
core.artifact
```

而不是 Plugin 自己管理下载系统。

---

# 88. Plugin API

Plugin 可以提供 API，但 API 只是入口。

例如：

```http
POST /api/plugins/seo/scan
```

内部：

```text
HTTP
 ↓
Action Resolver
 ↓
devos.seo.website.scan
 ↓
Action Runtime
```

不能：

```text
Controller
 ↓
Plugin Handler
 ↓
DB
```

---

# 89. Plugin Webhook

Plugin 可以声明：

```text
incoming webhook
```

例如：

```text
POST /api/plugins/github/webhook
```

流程：

```text
Webhook
 ↓
Verify
 ↓
Normalize
 ↓
Event
 ↓
Task / Action
```

---

# 90. Plugin Export / Import

Plugin 配置可以导出：

```json
{
  "pluginId": "devos.seo",
  "version": "1.2.0",
  "settings": {
    "defaultModel": "..."
  }
}
```

Secret 不得导出明文。

---

# 91. Plugin Backup

升级 / 卸载前可以：

```text
Plugin Data
Plugin Settings
Plugin Metadata
```

生成：

```text
core.artifact
```

作为恢复点。

---

# 92. Plugin Marketplace

未来可以实现：

```text
Plugin Marketplace
```

但 Marketplace 不是 Runtime。

Runtime 只负责：

```text
Discover
Install
Verify
Load
Activate
Disable
Upgrade
Uninstall
```

Marketplace 负责：

```text
Search
Rating
Description
Version
Download
```

---

# 93. Plugin Signature

未来 Plugin 可以支持：

```text
package signature
```

安装流程：

```text
Download
 ↓
Verify Signature
 ↓
Verify Checksum
 ↓
Compatibility
 ↓
Install
```

第一阶段可以先实现：

```text
checksum
```

---

# 94. Plugin Trust Level

定义：

```ts
type PluginTrust =
  | 'builtin'
  | 'trusted'
  | 'verified'
  | 'community'
  | 'untrusted'
```

不同 Trust Level 可以有不同权限。

---

# 95. Plugin Sandbox

第一阶段：

```text
Process-level isolation
```

高级版本：

```text
Container
Worker
Sandbox
```

但不应该一开始为了“安全”把所有 Plugin 都设计成复杂微服务。

优先保证：

```text
Permission
Credential Isolation
Namespace Isolation
Runtime Isolation
```

---

# 96. Plugin Crash Isolation

Plugin 激活失败：

```text
devos.seo
 ↓
activation_failed
```

不能导致：

```text
DevOS Core
```

整体无法启动。

启动策略：

```text
Core starts
 ↓
Load Plugins
 ↓
Plugin A success
Plugin B failed
Plugin C success
 ↓
DevOS remains available
```

---

# 97. Plugin Startup

启动：

```text
DevOS Boot
 ↓
Core Runtime
 ↓
Database
 ↓
Redis
 ↓
Event Runtime
 ↓
Task Runtime
 ↓
Action Runtime
 ↓
Plugin Runtime
 ↓
Load Plugins
 ↓
Health Checks
 ↓
Ready
```

---

# 98. Plugin Shutdown

关闭：

```text
Stop accepting new requests
 ↓
Scheduler pause
 ↓
Plugin workers drain
 ↓
Plugin tasks finish
 ↓
Deactivate plugins
 ↓
Close Event subscriptions
 ↓
Close connections
 ↓
Shutdown Core
```

---

# 99. Plugin Dependency Startup

如果：

```text
A → B
```

启动顺序：

```text
B
 ↓
A
```

关闭：

```text
A
 ↓
B
```

Dependency Resolver 必须负责排序。

---

# 100. Plugin Registry 与其他 Registry

最终：

```text
Plugin Registry
       │
       ├── Resource Registry
       ├── Action Registry
       ├── Capability Registry
       ├── Skill Registry
       ├── MCP Registry
       ├── Event Registry
       ├── Navigation Registry
       ├── Widget Registry
       └── Workflow Registry
```

Plugin 是：

> Registry 的扩展来源。

不是：

> Registry 的替代品。

---

# 101. Plugin 完整模型

最终：

```text
Plugin
│
├── Manifest
│
├── Resources
│
├── Actions
│
├── Capabilities
│
├── Skills
│
├── MCP
│
├── Workflows
│
├── Events
│
├── Scheduler
│
├── Workers
│
├── Settings
│
├── Credentials
│
├── UI
│   ├── Routes
│   ├── Navigation
│   ├── Dashboard
│   └── Widgets
│
└── Runtime
    ├── Lifecycle
    ├── Health
    ├── Logging
    ├── Metrics
    └── Tracing
```

---

# 102. Plugin Runtime 与 DevOS 的最终关系

```text
                    DevOS
                      │
              ┌───────┴────────┐
              │                │
          Core Runtime     Plugin Runtime
                               │
        ┌──────────────────────┼─────────────────────┐
        ↓                      ↓                     ↓
      Plugin A              Plugin B              Plugin C
        │                      │                     │
     Resource              Resource              Resource
     Action                Action                Action
     Skill                 Skill                 Skill
     MCP                   MCP                   MCP
     UI                    UI                    UI
```

所有 Plugin 最终进入：

```text
DevOS Runtime
```

---

# 103. SEO Plugin 示例

SEO 不应该成为第二套系统。

应该：

```text
DevOS
  │
  └── Plugin: devos.seo
```

提供：

```text
Resources:
  devos.seo.website
  devos.seo.keyword
  devos.seo.article
  devos.seo.backlink
  devos.seo.campaign

Actions:
  devos.seo.website.scan
  devos.seo.keyword.research
  devos.seo.article.generate
  devos.seo.backlink.find
  devos.seo.campaign.run

Skills:
  devos.seo.audit
  devos.seo.content
  devos.seo.link-building

MCP:
  search
  browser
  cms
  backlink providers

UI:
  SEO Dashboard
  Websites
  Keywords
  Content
  Backlinks
  Campaigns
  Settings
```

---

# 104. Agent 使用 Plugin

用户：

> 给 example.com 做完整 SEO 审计。

Agent：

```text
Goal
 ↓
Capability Discovery
 ↓
devos.seo.audit Skill
 ↓
Capabilities
 ├── website.scan
 ├── keyword.research
 ├── page.analyze
 └── report.generate
 ↓
Task
 ↓
Jobs
 ↓
Actions
 ↓
Execution
 ↓
Events
 ↓
Agent Observation
```

Agent 不需要直接知道：

```text
SEO Plugin 内部代码
```

---

# 105. Plugin 与独立 Backend

DevOS 必须支持两种模式。

## Mode A

```text
DevOS
 ↓
Plugin
 ↓
Domain
```

推荐用于：

```text
SEO
CRM
Content
Marketing
DevOps
```

---

## Mode B

```text
DevOS Minimal Core
 ↓
Fork
 ↓
Independent Application
```

例如：

```text
DevOS Starter
 ↓
Fork
 ↓
Custom Product
```

独立项目仍然可以保留：

```text
Identity
RBAC
Resource
Action
Task
Event
Audit
Observability
```

但删除不需要的 Plugin。

---

# 106. Plugin 不等于 Microservice

不要把：

```text
Plugin
```

自动理解成：

```text
Microservice
```

默认：

```text
Plugin = In-process Extension
```

只有明确需要：

```text
isolation
resource-heavy worker
different runtime
different deployment lifecycle
```

才使用：

```text
External Service
```

---

# 107. External Plugin

未来支持：

```text
DevOS
 ↓
External Plugin Adapter
 ↓
HTTP / gRPC / MCP
 ↓
External Service
```

但外部 Plugin 仍然暴露：

```text
Resource
Action
Capability
Skill
Event
UI
```

给 DevOS。

---

# 108. Plugin Adapter

```ts
interface PluginAdapter {
  install(): Promise<void>

  enable(): Promise<void>

  disable(): Promise<void>

  uninstall(): Promise<void>

  health(): Promise<PluginHealth>
}
```

---

# 109. Plugin Runtime API

建议统一：

```ts
interface DevOSPlugin {
  manifest: PluginManifest

  initialize(context: PluginContext): Promise<void>

  activate(context: PluginContext): Promise<void>

  deactivate(context: PluginContext): Promise<void>

  dispose(context: PluginContext): Promise<void>
}
```

---

# 110. Package Architecture

Zcode 必须实现：

```text
packages/
└── plugin/
    ├── types/
    │   ├── manifest.ts
    │   ├── lifecycle.ts
    │   └── permission.ts
    │
    ├── registry/
    │   └── plugin-registry.ts
    │
    ├── runtime/
    │   ├── plugin-runtime.ts
    │   ├── lifecycle.ts
    │   ├── loader.ts
    │   ├── activator.ts
    │   └── disposer.ts
    │
    ├── installer/
    │   ├── installer.ts
    │   ├── resolver.ts
    │   ├── validator.ts
    │   └── checksum.ts
    │
    ├── configuration/
    │   ├── config-service.ts
    │   └── secret-service.ts
    │
    ├── isolation/
    │   ├── permissions.ts
    │   └── credentials.ts
    │
    ├── health/
    │   └── health-service.ts
    │
    └── ui/
        ├── route-registry.ts
        ├── navigation-registry.ts
        ├── widget-registry.ts
        └── dashboard-registry.ts
```

---

# 111. Backend Plugin Example

```text
plugins/
└── seo/
    ├── plugin.json
    ├── index.ts
    │
    ├── resources/
    │   ├── website.ts
    │   ├── keyword.ts
    │   └── article.ts
    │
    ├── actions/
    │   ├── scan.ts
    │   ├── research.ts
    │   └── generate.ts
    │
    ├── skills/
    │   ├── seo-audit.ts
    │   └── content.ts
    │
    ├── mcp/
    │   └── browser.ts
    │
    ├── events/
    │   └── definitions.ts
    │
    ├── workflows/
    │   └── audit.ts
    │
    ├── migrations/
    │
    └── frontend/
        ├── routes/
        ├── pages/
        ├── widgets/
        └── index.ts
```

---

# 112. Plugin Test

每个 Plugin 必须提供：

```text
manifest test
lifecycle test
registration test
permission test
configuration test
action test
event test
health test
ui registration test
upgrade test
uninstall test
```

---

# 113. Acceptance Criteria

## Plugin Lifecycle

* [ ] Discover
* [ ] Install
* [ ] Configure
* [ ] Enable
* [ ] Disable
* [ ] Restart
* [ ] Upgrade
* [ ] Uninstall
* [ ] Health

## Registry

* [ ] Plugin Registry
* [ ] Resource registration
* [ ] Action registration
* [ ] Capability registration
* [ ] Skill registration
* [ ] MCP registration
* [ ] Event registration
* [ ] Workflow registration
* [ ] UI registration

## Security

* [ ] Permission declaration
* [ ] Permission approval
* [ ] Credential isolation
* [ ] Secret isolation
* [ ] Namespace isolation
* [ ] Network policy
* [ ] Sensitive data redaction

## UI

* [ ] Dynamic routes
* [ ] Navigation
* [ ] Settings page
* [ ] Dashboard
* [ ] Widgets
* [ ] Resource pages
* [ ] Action buttons
* [ ] Task integration

## Runtime

* [ ] Logger
* [ ] Metrics
* [ ] Trace
* [ ] Event
* [ ] Health
* [ ] Task
* [ ] Worker
* [ ] Scheduler

---

# 114. Integration Test

必须测试：

```text
Install Plugin
 ↓
Manifest Validation
 ↓
Register Resource
 ↓
Register Action
 ↓
Register Skill
 ↓
Register MCP
 ↓
Register Event
 ↓
Register UI
 ↓
Enable
 ↓
Health Check
```

最终：

```text
Plugin = healthy
```

---

# 115. Disable Test

```text
Plugin enabled
 ↓
Task running
 ↓
Disable
 ↓
Drain
 ↓
Deactivate
 ↓
Unregister
 ↓
Plugin disabled
```

验证：

```text
Existing Task
```

不会被无故破坏。

---

# 116. Permission Test

Plugin 尝试：

```text
read secret:github
```

但只有：

```text
secret:openai
```

必须：

```text
ACCESS_DENIED
```

---

# 117. Conflict Test

安装：

```text
Plugin A
resource = foo.bar
```

然后：

```text
Plugin B
resource = foo.bar
```

必须：

```text
RESOURCE_NAMESPACE_CONFLICT
```

---

# 118. Dependency Test

```text
Plugin A
 ↓
Plugin B
```

安装 A 时：

```text
B not installed
```

应该：

```text
Install B
 ↓
Install A
```

---

# 119. Failure Test

Plugin activation：

```text
throw Error
```

必须：

```text
Plugin = activation_failed
```

同时：

```text
DevOS = healthy
```

---

# 120. Final Golden Rules

```text
1. Plugin 是扩展，不是第二个 DevOS。

2. Plugin 必须通过 DevOS Runtime 执行业务。

3. Plugin 不创建第二套 Auth。

4. Plugin 不创建第二套 Task。

5. Plugin 不创建第二套 Queue。

6. Plugin 不创建第二套 EventBus。

7. Plugin 不绕过 Action Runtime。

8. Plugin 不绕过 Permission。

9. Plugin 不直接读取 Secret。

10. Plugin UI 不直接执行业务逻辑。

11. Plugin 的 Resource 必须注册到 Resource Registry。

12. Plugin 的 Action 必须注册到 Action Registry。

13. Plugin 的 Capability 必须注册到 Capability Registry。

14. Plugin 的 Skill 必须注册到 Skill Registry。

15. Plugin 的 MCP 必须注册到 MCP Runtime。

16. Plugin 的 Event 必须进入 Event Runtime。

17. Plugin 的 Task 必须进入 Task Runtime。

18. Plugin 的日志必须进入 DevOS Logging Runtime。

19. Plugin 的审计必须进入 DevOS Audit Runtime。

20. Plugin 必须可以独立启停。

21. Plugin 崩溃不能拖垮 DevOS Core。

22. Plugin 卸载默认不删除业务数据。

23. Plugin 升级必须进行兼容性检查。

24. Plugin 必须拥有唯一 Namespace。

25. Agent 看到的是 Capability，而不是 Plugin 内部实现。

26. MCP 是能力接入方式，不是第二套业务 Runtime。

27. SEO / DevOps / CRM 等领域都应该优先实现为 Plugin。

28. 真正需要独立 Backend 的项目，应从 DevOS Minimal Core Fork。
```

---

# 121. DevOS Plugin 最终模型

最终 DevOS 应该达到：

```text
                         DevOS
                           │
        ┌──────────────────┴──────────────────┐
        │                                     │
   Core Runtime                         Plugin Runtime
        │                                     │
        │                    ┌────────────────┼────────────────┐
        │                    │                │                │
        │                 SEO Plugin      DevOps Plugin     CRM Plugin
        │                    │                │                │
        │                 Resource         Resource         Resource
        │                 Action           Action           Action
        │                 Skill            Skill            Skill
        │                 MCP              MCP              MCP
        │                 Workflow         Workflow         Workflow
        │                 Event            Event            Event
        │                 UI               UI               UI
        │                    │                │                │
        └────────────────────┴────────────────┴────────────────┘
                           │
                    Capability Registry
                           │
                        Agent
                           │
                          Goal
```

DevOS 的真正扩展方式最终就是：

```text
Core
+
Plugin
+
Capability
+
Agent
```

而不是：

```text
Core
+
SEO Backend
+
SEO Queue
+
SEO Agent
+
SEO MCP
+
SEO EventBus
```

**这一点必须作为 Zcode 后续所有领域模块开发的架构约束。**