Files

T

phptits b1f17cf637 v2 platform foundation (docs 01/02/03): Action Runtime + Registry + unified API

- v2 foundation: ActionResult/DevError/ActorContext/ResourceRef/Execution types
- ActionRegistry + ResourceRegistry (namespaced types, FAIL FAST on duplicates)
- ActionRuntime pipeline: validate -> authorize -> middleware -> handler ->
  output validation -> audit -> event -> execution persisted (devos_action_executions)
- Legacy bridge: v1 services registered as devops.*/core.* resources & actions (47 actions, 9 resources)
- Unified Action API: POST /api/v2/actions/:actionId, GET discovery (actions/resources)
- 10 v2 unit tests (registry fail-fast, validation, authz, failure audit, events)

2026-09-10 21:09:44 +00:00

42 KiB

Raw Permalink Blame History

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

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

例如 SEO Plugin：

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。

格式：

<vendor>.<plugin>

例如：

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

Plugin 内部 Resource：

devos.seo.website
devos.seo.keyword

Action：

devos.seo.website.scan

Skill：

devos.seo.audit

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

5. Plugin ID

Plugin ID：

type PluginId = string

例如：

devos.seo

必须满足：

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

6. Plugin Manifest

每个 Plugin 必须提供：

plugin.json

推荐：

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

7. 完整 Manifest

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 状态：

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

异常：

install_failed
activation_failed
runtime_error
upgrade_failed

9. Plugin Runtime 状态

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：

core.plugin

Plugin Resource：

core.plugin.installation

11. Plugin Actions

至少：

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

错误：

POST /plugins/:id/enable

controller:
  plugin.enable()

正确：

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

CLI：

devos plugin enable devos.seo

也必须：

CLI
 ↓
Action Runtime
 ↓
core.plugin.enable

Agent：

Agent
 ↓
core.plugin.enable
 ↓
Action Runtime

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

13. Plugin Installation Record

数据库：

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

支持：

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

第一阶段至少实现：

builtin
local
package

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

15. Built-in Plugin

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

例如：

devos.core
devos.seo
devos.devops

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

即：

Core Runtime
   ↓
Plugin Runtime
   ↓
Optional Plugins

而不是：

Plugin Runtime
   ↓
Core Runtime

16. Plugin Registration

Plugin 激活后：

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

17. Plugin Registry

实现：

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

interface RegisteredPlugin {
  manifest: PluginManifest

  status: PluginStatus

  runtime: PluginRuntime

  registeredAt: Date
}

19. Plugin Runtime

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

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 不应该直接拿：

PrismaClient
RedisClient
BullMQ

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

21. Plugin Storage

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

提供：

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。

例如：

packages/plugins/seo
  migrations/
  schema/

数据库表必须带 Plugin Namespace。

例如：

seo_websites
seo_keywords
seo_articles

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

23. Plugin Configuration

Plugin 可以声明 Settings。

例如：

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

24. Plugin Setting Schema

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 配置应该属于：

core.plugin.settings

而不是：

plugin_database_table

API：

GET
/api/plugins/:pluginId/settings

PUT
/api/plugins/:pluginId/settings

但是最终执行：

core.plugin.configure

26. Secret Settings

例如：

OpenAI API Key
Cloudflare API Token
GitHub Token
SMTP Password

必须使用：

type = secret

数据库不得明文保存。

推荐：

Encryption at Rest

读取时默认：

********

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

27. Plugin Settings 权限

必须区分：

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

普通用户：

plugin.view

管理员：

plugin.configure

系统管理员：

plugin.install
plugin.uninstall

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

28. Plugin UI

Plugin 可以提供自己的页面。

例如：

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

Plugin UI 不是独立 SPA。

必须挂载到：

DevOS UI Shell

29. Plugin UI Manifest

interface PluginUIDeclaration {
  routes?: PluginRoute[]

  navigation?: PluginNavigationItem[]

  dashboards?: PluginDashboard[]

  widgets?: PluginWidget[]

  settingsPage?: boolean
}

30. Plugin Route

interface PluginRoute {
  id: string

  path: string

  title: string

  component: string

  icon?: string

  permissions?: string[]
}

例如：

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

Plugin 可以向左侧导航注册：

SEO
  Overview
  Websites
  Keywords
  Articles
  Tasks

但不能直接修改 DevOS Shell。

必须：

Plugin
 ↓
Navigation Registry
 ↓
UI Shell

interface NavigationRegistry {
  register(item: NavigationItem): void

  unregister(pluginId: string): void

  list(context: NavigationContext): NavigationItem[]
}

必须根据：

permission
organization
project
plugin enabled

动态过滤。

33. Plugin Dashboard

Plugin 可以提供 Dashboard：

SEO Overview

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

Dashboard 只负责：

展示
查询
触发 Action

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

Plugin 可以注册：

Dashboard Widget
Chat Widget
Task Widget
Resource Widget
Report Widget

例如：

SEO Health Score

Widget 可以声明：

interface PluginWidget {
  id: string

  title: string

  component: string

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

  permissions?: string[]
}

35. Plugin Page 与 Action Runtime

页面：

按钮：Scan Website

不能：

fetch('/seo/scan')

应该：

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

36. Plugin Resource UI

如果 Plugin 注册：

seo.website

可以自动获得：

List
Detail
Create
Edit
Delete

如果 Resource 声明：

ui.list
ui.detail

DevOS Generic UI 可以自动生成。

Plugin 只需要实现复杂页面。

37. Plugin Actions

Plugin Action：

interface PluginActionDeclaration {
  id: string

  name: string

  description?: string

  inputSchema: unknown

  outputSchema: unknown

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

  permissions: string[]

  requiresApproval?: boolean
}

Action 最终进入：

Action Registry

38. Plugin Capability

Plugin Action 自动成为 Capability。

例如：

devos.seo.website.scan

Capability
 type = action
 source = plugin

Agent 就能够发现。

39. Plugin Skill

Plugin 可以注册 Skill：

interface PluginSkillDeclaration {
  id: string

  name: string

  description: string

  version: string

  instructions: string

  requiredCapabilities: string[]

  inputSchema?: unknown

  outputSchema?: unknown
}

40. Plugin 与 Agent

例如：

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

Agent 不需要知道：

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

只看到：

Capability

41. Plugin MCP

Plugin 可以声明 MCP：

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：

devos.seo.website.scanned
devos.seo.article.generated

Event 进入：

Event Registry

并可以被：

Agent
Workflow
Notification
Webhook
Plugin

消费。

43. Plugin Event Handler

Plugin Handler：

Event
 ↓
Plugin Handler
 ↓
Action Runtime

禁止：

Event
 ↓
Plugin Handler
 ↓
直接 DB mutation

44. Plugin Workflow

Plugin 可以提供 Workflow：

seo.full.audit

例如：

scan website
 ↓
collect keywords
 ↓
analyze pages
 ↓
generate report

Workflow 由：

Action
Task
Job

组成。

45. Plugin Scheduler

Plugin 可以注册 Schedule Definition。

例如：

SEO daily scan
Every day at 03:00

最终还是：

Scheduler
 ↓
Task
 ↓
Action

Plugin 不得自己运行：

setInterval()

或：

node-cron

来承担业务调度。

46. Plugin Worker

某些 Plugin 可能需要特殊 Worker。

例如：

browser
ffmpeg
docker
ssh

Plugin 可以声明 Worker Capability：

interface PluginWorkerDeclaration {
  id: string

  queues: string[]

  capabilities: string[]

  concurrency?: number
}

最终由：

Worker Runtime

管理。

47. Plugin Dependencies

例如：

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

安装时：

Plugin A
 ↓
Dependency Resolver
 ↓
Plugin B
 ↓
Install

48. Dependency Version

必须支持：

exact
range

例如：

1.2.3
^1.2.0
>=1.0.0 <2.0.0

49. Dependency Graph

Plugin Runtime 必须检测：

A → B
B → C
C → A

发现：

circular dependency

直接拒绝安装。

50. Plugin API Version

Plugin 必须声明：

apiVersion

例如：

apiVersion = 1

DevOS Runtime 升级：

API v1
API v2

可以兼容旧 Plugin。

51. Plugin Compatibility

安装之前必须执行：

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

52. Resource Conflict

例如：

Plugin A：

seo.website

Plugin B：

seo.website

必须拒绝：

RESOURCE_NAMESPACE_CONFLICT

除非明确声明：

override

第一阶段：

禁止 Override。

53. Action Conflict

同样：

seo.website.scan

只能由一个 Plugin 注册。

54. Capability Conflict

Capability ID 也必须唯一。

55. Plugin Enable

Enable：

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

如果失败：

activation_failed

不得标记为 enabled。

56. Plugin Disable

Disable：

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

已经运行中的 Task：

默认继续完成

除非 Plugin 声明：

shutdownPolicy = cancel

57. Plugin Uninstall

不能直接删除。

必须：

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

58. Plugin Data Policy

Manifest 可以声明：

dataPolicy: {
  preserveOnDisable: boolean

  preserveOnUninstall: boolean

  destructiveUninstall: boolean
}

默认：

preserveOnUninstall = true

即：

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

59. Plugin Upgrade

升级流程：

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：

interface PluginMigration {
  from: string

  to: string

  up(): Promise<void>

  down?(): Promise<void>
}

Migration 必须支持：

version history

61. Upgrade Failure

升级失败必须：

upgrade_failed

并尽可能：

Rollback

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

因此：

backup
+
forward migration
+
recovery procedure

必须存在。

62. Plugin Isolation

Plugin 必须受到：

Permission
Namespace
Resource Scope
Action Scope

限制。

Plugin 不应该默认拥有：

root filesystem
all environment variables
all secrets
all database tables

63. Plugin Permission Declaration

Manifest：

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

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

64. Permission 分类

至少：

resource
action
network
storage
secret
filesystem
process
worker
mcp

65. Network Permission

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

推荐：

network:http
network:https

未来可以限制：

network:domain:api.example.com

66. Secret Permission

Plugin 请求：

secret:openai

只能访问：

OpenAI Credential

不能读取：

Cloudflare Credential
GitHub Credential

67. Plugin Credential

统一使用：

Credential Runtime

例如：

core.credential

Plugin：

Credential Request
 ↓
Permission
 ↓
Credential Runtime
 ↓
Secret

Plugin 不应该直接读取 .env。

68. Plugin Environment

Plugin 可以获得：

interface PluginEnvironment {
  devosVersion: string

  pluginId: string

  pluginVersion: string

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

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

69. Plugin Logging

Plugin 必须使用：

context.logger

例如：

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

日志自动获得：

pluginId
correlationId
executionId
taskId

70. Plugin Events

Plugin 必须使用：

context.eventBus.publish(...)

Event 自动补充：

pluginId

71. Plugin Health

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

  message?: string

  checks?: HealthCheck[]
}

例如：

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

72. Plugin Health Event

自动产生：

plugin.health.changed
plugin.health.failed
plugin.health.recovered

73. Plugin Observability

Plugin 的：

Action
Task
Job
Execution
Event
Log
Audit
Trace
Metric

全部自动带：

pluginId

这样可以统计：

Plugin usage
Plugin errors
Plugin latency
Plugin cost
Plugin health

74. Plugin Metrics

自动生成：

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

例如：

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

都必须产生 Audit。

例如：

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

76. Plugin UI Permission

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

例如：

SEO Settings

必须：

plugin.view
+
plugin.configure

77. Plugin Dynamic UI

前端需要：

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

78. Frontend Plugin Package

推荐：

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

import backend database
import Prisma
import Redis

只能使用：

Action Client
Resource API
Query Client
UI SDK

80. Plugin UI SDK

DevOS 应提供：

interface DevOSPluginUI {
  registerRoute(...)

  registerNavigation(...)

  registerWidget(...)

  registerDashboard(...)

  registerSettings(...)
}

81. Plugin Action Client

前端：

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

而不是：

fetch('/api/seo/scan')

82. Plugin Resource Client

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

83. Plugin Task UI

异步 Action 返回：

{
  taskId: 'task_123'
}

前端自动进入：

Task Detail

可以显示：

Progress
Jobs
Logs
Events
Execution
Result

84. Plugin Chat Integration

Plugin 可以向 Agent Chat 注册：

context action

例如用户打开：

Website: example.com

Chat：

Ask Agent about this website

Agent 自动获得：

resource = devos.seo.website
resourceId = website_123

85. Plugin Context Provider

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

这样 Agent 可以理解：

当前页面
当前 Resource
当前 Project
当前 Task

86. Plugin Report

Plugin 可以注册 Report：

SEO Audit Report
Server Deployment Report
CRM Customer Report

Report 应该：

Task
 ↓
Action
 ↓
Artifact
 ↓
Report

87. Plugin Artifact

Plugin 可以生成：

PDF
CSV
JSON
HTML
Markdown
Image
Archive

统一进入：

core.artifact

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

88. Plugin API

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

例如：

POST /api/plugins/seo/scan

内部：

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

不能：

Controller
 ↓
Plugin Handler
 ↓
DB

89. Plugin Webhook

Plugin 可以声明：

incoming webhook

例如：

POST /api/plugins/github/webhook

流程：

Webhook
 ↓
Verify
 ↓
Normalize
 ↓
Event
 ↓
Task / Action

90. Plugin Export / Import

Plugin 配置可以导出：

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

Secret 不得导出明文。

91. Plugin Backup

升级 / 卸载前可以：

Plugin Data
Plugin Settings
Plugin Metadata

生成：

core.artifact

作为恢复点。

92. Plugin Marketplace

未来可以实现：

Plugin Marketplace

但 Marketplace 不是 Runtime。

Runtime 只负责：

Discover
Install
Verify
Load
Activate
Disable
Upgrade
Uninstall

Marketplace 负责：

Search
Rating
Description
Version
Download

93. Plugin Signature

未来 Plugin 可以支持：

package signature

安装流程：

Download
 ↓
Verify Signature
 ↓
Verify Checksum
 ↓
Compatibility
 ↓
Install

第一阶段可以先实现：

checksum

94. Plugin Trust Level

定义：

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

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

95. Plugin Sandbox

第一阶段：

Process-level isolation

高级版本：

Container
Worker
Sandbox

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

优先保证：

Permission
Credential Isolation
Namespace Isolation
Runtime Isolation

96. Plugin Crash Isolation

Plugin 激活失败：

devos.seo
 ↓
activation_failed

不能导致：

DevOS Core

整体无法启动。

启动策略：

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

97. Plugin Startup

启动：

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

98. Plugin Shutdown

关闭：

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

如果：

A → B

启动顺序：

B
 ↓
A

关闭：

A
 ↓
B

Dependency Resolver 必须负责排序。

100. Plugin Registry 与其他 Registry

最终：

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 完整模型

最终：

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 的最终关系

                    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 最终进入：

DevOS Runtime

103. SEO Plugin 示例

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

应该：

DevOS
  │
  └── Plugin: devos.seo

提供：

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：

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

Agent 不需要直接知道：

SEO Plugin 内部代码

105. Plugin 与独立 Backend

DevOS 必须支持两种模式。

Mode A

DevOS
 ↓
Plugin
 ↓
Domain

推荐用于：

SEO
CRM
Content
Marketing
DevOps

Mode B

DevOS Minimal Core
 ↓
Fork
 ↓
Independent Application

例如：

DevOS Starter
 ↓
Fork
 ↓
Custom Product

独立项目仍然可以保留：

Identity
RBAC
Resource
Action
Task
Event
Audit
Observability

但删除不需要的 Plugin。

106. Plugin 不等于 Microservice

不要把：

Plugin

自动理解成：

Microservice

默认：

Plugin = In-process Extension

只有明确需要：

isolation
resource-heavy worker
different runtime
different deployment lifecycle

才使用：

External Service

107. External Plugin

未来支持：

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

但外部 Plugin 仍然暴露：

Resource
Action
Capability
Skill
Event
UI

给 DevOS。

108. Plugin Adapter

interface PluginAdapter {
  install(): Promise<void>

  enable(): Promise<void>

  disable(): Promise<void>

  uninstall(): Promise<void>

  health(): Promise<PluginHealth>
}

109. Plugin Runtime API

建议统一：

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 必须实现：

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

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 必须提供：

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

必须测试：

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

最终：

Plugin = healthy

115. Disable Test

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

验证：

Existing Task

不会被无故破坏。

116. Permission Test

Plugin 尝试：

read secret:github

但只有：

secret:openai

必须：

ACCESS_DENIED

117. Conflict Test

安装：

Plugin A
resource = foo.bar

然后：

Plugin B
resource = foo.bar

必须：

RESOURCE_NAMESPACE_CONFLICT

118. Dependency Test

Plugin A
 ↓
Plugin B

安装 A 时：

B not installed

应该：

Install B
 ↓
Install A

119. Failure Test

Plugin activation：

throw Error

必须：

Plugin = activation_failed

同时：

DevOS = healthy

120. Final Golden Rules

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 应该达到：

                         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 的真正扩展方式最终就是：

Core
+
Plugin
+
Capability
+
Agent

而不是：

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

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

42 KiB Raw Permalink Blame History Unescape Escape

DevOS Plugin Runtime

1. 目标

2. 核心原则

3. Plugin 的本质

4. Plugin Namespace

5. Plugin ID

6. Plugin Manifest

7. 完整 Manifest

8. Plugin 生命周期

9. Plugin Runtime 状态

10. Plugin Resource

11. Plugin Actions

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

13. Plugin Installation Record

14. Plugin Source

15. Built-in Plugin

16. Plugin Registration

17. Plugin Registry

18. Registered Plugin

19. Plugin Runtime

20. Plugin Context

21. Plugin Storage

22. Plugin Database

23. Plugin Configuration

24. Plugin Setting Schema

25. Plugin Settings Resource

26. Secret Settings

27. Plugin Settings 权限

28. Plugin UI

29. Plugin UI Manifest

30. Plugin Route

31. Plugin Navigation

32. Navigation Registry

33. Plugin Dashboard

34. Plugin Widget

35. Plugin Page 与 Action Runtime

36. Plugin Resource UI

37. Plugin Actions

38. Plugin Capability

39. Plugin Skill

40. Plugin 与 Agent

41. Plugin MCP

42. Plugin Event

43. Plugin Event Handler

44. Plugin Workflow

45. Plugin Scheduler

46. Plugin Worker

47. Plugin Dependencies

48. Dependency Version

49. Dependency Graph

50. Plugin API Version

51. Plugin Compatibility

52. Resource Conflict

53. Action Conflict

54. Capability Conflict

55. Plugin Enable

56. Plugin Disable

57. Plugin Uninstall

58. Plugin Data Policy

59. Plugin Upgrade

60. Migration

61. Upgrade Failure

62. Plugin Isolation

63. Plugin Permission Declaration

64. Permission 分类

65. Network Permission

66. Secret Permission

67. Plugin Credential

68. Plugin Environment

69. Plugin Logging

70. Plugin Events

71. Plugin Health

72. Plugin Health Event

73. Plugin Observability

74. Plugin Metrics

75. Plugin Audit

76. Plugin UI Permission

77. Plugin Dynamic UI

78. Frontend Plugin Package

42 KiB

Raw Permalink Blame History