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

44 KiB

Raw Permalink Blame History

DevOS Developer Work OS

Plugin Runtime / Plugin Lifecycle / Extension Platform 设计规范

Version: 1.0

1. 文档目标

本文定义 DevOS Plugin Runtime。

Plugin Runtime 是 DevOS 最重要的扩展基础设施之一。

目标：

任何一个成熟能力，都应该能够以 Plugin 的形式安装到 DevOS，而不是修改 DevOS Core。

例如：

GitHub
Cloudflare
Browser
Google Search Console
Docker
Kubernetes
SSH
SMTP
WordPress
OpenAI
Anthropic

都应该可以成为 Plugin。

Plugin 可以提供：

Resource
Action
Event
Skill
MCP
Workflow
Agent Profile
UI
Navigation
Widget
Settings
Command
Context Action

最终：

Plugin
   ↓
Plugin Runtime
   ↓
Registry
   ├── Resource Registry
   ├── Action Registry
   ├── Capability Registry
   ├── Skill Registry
   ├── MCP Registry
   └── UI Registry

2. Plugin 的核心定义

Plugin：

一个拥有明确 Manifest、版本、依赖、权限、能力、生命周期和扩展点的 DevOS Extension Package。

Plugin 不是简单的：

npm package

也不是简单的：

UI module

而是：

Code
+
Manifest
+
Capabilities
+
Resources
+
Actions
+
UI
+
Configuration
+
Permissions
+
Lifecycle

3. Plugin Architecture

最终：

                    DevOS Core
                        │
                  Plugin Runtime
                        │
             ┌──────────┼──────────┐
             │          │          │
          Registry    Lifecycle   Policy
             │          │          │
             └──────────┼──────────┘
                        │
                Installed Plugins
                        │
       ┌────────────────┼────────────────┐
       │                │                │
     GitHub          Browser         Cloudflare
       │                │                │
   Resource          Resource         Resource
   Action            Action           Action
   Skill             Skill            Skill
   MCP               MCP              MCP
   UI                UI               UI

4. Plugin Manifest

每个 Plugin 必须拥有 Manifest。

推荐：

export interface PluginManifest {
  id: string;

  name: string;

  displayName?: string;

  description?: string;

  version: string;

  author?: string;

  homepage?: string;

  license?: string;

  icon?: string;

  category?: string;

  runtime: PluginRuntimeConfig;

  dependencies?: PluginDependency[];

  permissions?: PluginPermission[];

  capabilities?: PluginCapabilityRef[];

  resources?: PluginResourceRef[];

  actions?: PluginActionRef[];

  skills?: PluginSkillRef[];

  mcp?: PluginMCPConfig;

  ui?: PluginUIManifest;

  settings?: PluginSettingsManifest;

  metadata?: Record<string, unknown>;
}

5. Plugin ID

Plugin ID 必须：

全局唯一
稳定
不随版本变化
不包含版本号

例如：

github
browser
cloudflare
docker
kubernetes
wordpress

禁止：

github-v2
github-2026
github-plugin-new

版本由：

version

单独管理。

6. Plugin Namespace

所有 Plugin 产生的资源、Action、Skill 必须拥有 namespace。

例如：

github.repository
github.issue
github.pull_request

github.repository.create
github.issue.create

github.code_review

Browser：

browser.session
browser.page

browser.open
browser.navigate

browser.research

禁止 Plugin 创建：

user
settings
task
agent

这种容易与 Core 冲突的全局 ID。

7. Plugin 类型

Plugin Runtime 支持不同类型。

type PluginType =
  | "integration"
  | "provider"
  | "automation"
  | "developer"
  | "ai"
  | "storage"
  | "ui"
  | "composite";

例如：

GitHub
→ integration

OpenAI
→ provider

Browser
→ automation

Docker
→ developer

SEO Analyzer
→ ai

大多数 Plugin 可以使用：

composite

因为同时包含：

Resource
Action
Skill
UI
MCP

8. Plugin Source

Plugin 来源：

type PluginSource =
  | "builtin"
  | "local"
  | "workspace"
  | "marketplace"
  | "git"
  | "npm"
  | "url";

例如：

DevOS Core Plugin
→ builtin

本地开发插件
→ local

公司内部插件
→ workspace

Marketplace
→ marketplace

9. Plugin Installation

安装流程：

Install Plugin
      ↓
Resolve Manifest
      ↓
Check Version
      ↓
Resolve Dependencies
      ↓
Check Compatibility
      ↓
Validate Permissions
      ↓
Install Package
      ↓
Register Plugin
      ↓
Run Migration
      ↓
Initialize
      ↓
Enable

必须支持：

Install
Uninstall
Enable
Disable
Upgrade
Rollback

10. Plugin 状态机

Plugin 状态：

type PluginStatus =
  | "available"
  | "installing"
  | "installed"
  | "enabling"
  | "enabled"
  | "disabling"
  | "disabled"
  | "upgrading"
  | "failed"
  | "uninstalling";

状态转换：

available
   ↓
installing
   ↓
installed
   ↓
enabling
   ↓
enabled

禁用：

enabled
   ↓
disabling
   ↓
disabled

升级：

enabled
   ↓
upgrading
   ↓
enabled

失败：

installing
    ↓
failed

11. Plugin Lifecycle

Plugin 生命周期：

Discovery
 ↓
Install
 ↓
Validate
 ↓
Load
 ↓
Initialize
 ↓
Enable
 ↓
Running
 ↓
Disable
 ↓
Unload
 ↓
Uninstall

Plugin Runtime 必须提供生命周期 Hook：

interface PluginLifecycle {
  onInstall?(ctx: PluginContext): Promise<void>;

  onLoad?(ctx: PluginContext): Promise<void>;

  onInitialize?(ctx: PluginContext): Promise<void>;

  onEnable?(ctx: PluginContext): Promise<void>;

  onDisable?(ctx: PluginContext): Promise<void>;

  onUnload?(ctx: PluginContext): Promise<void>;

  onUninstall?(ctx: PluginContext): Promise<void>;
}

12. Install 与 Enable 必须分离

这是非常重要的设计。

安装：

Package exists

启用：

Plugin is active

例如：

GitHub Plugin
Status: Installed

但：

Enabled: false

此时：

Resource
Action
Skill
MCP
UI

都不应该正常提供运行能力。

13. Disable Plugin

Disable 后：

Plugin
 ↓
Unregister Runtime Capabilities
 ↓
Unregister UI
 ↓
Stop Background Jobs
 ↓
Stop Event Subscriptions
 ↓
Close Connections

但是：

Plugin 数据默认不能删除。

例如：

GitHub Plugin disabled

以下仍然存在：

github.repository
github.issue
historical executions
audit logs
settings
credentials references

只是新的运行能力不可用。

14. Uninstall Plugin

Uninstall 是更危险的操作。

默认：

Uninstall
 ≠
Delete Plugin Data

推荐：

Uninstall Plugin
 ↓
Disable
 ↓
Unload
 ↓
Remove Runtime
 ↓
Keep Data

用户明确选择：

Delete Plugin Data

才执行数据删除。

15. Plugin Data Policy

Manifest 可以定义：

interface PluginDataPolicy {
  canDeleteData: boolean;

  dataResources?: string[];

  preserveOnUninstall?: boolean;
}

默认：

preserveOnUninstall = true

防止误删数据。

16. Plugin Dependencies

Plugin 可以依赖其他 Plugin。

例如：

SEO Plugin
 ↓
Browser Plugin
 ↓
Browser Runtime

Manifest：

{
  dependencies: [
    {
      pluginId: "browser",
      version: "^1.0.0",
      optional: true
    }
  ]
}

17. Dependency Types

支持：

required
optional
peer

例如：

required:
github

optional:
browser

peer:
ai provider

18. Dependency Resolution

安装：

Install SEO Plugin

Runtime：

SEO
 ↓
Browser >= 1.2
 ↓
AI Provider >= 2.0

如果依赖缺失：

Dependency missing

应该明确提示：

SEO Plugin requires Browser Plugin >= 1.2

[Install Dependency]

而不是启动后才报错。

19. Dependency Cycle

必须检测：

Plugin A
 ↓
Plugin B
 ↓
Plugin A

禁止循环依赖。

安装时直接失败：

PLUGIN_DEPENDENCY_CYCLE

20. Compatibility

Plugin Manifest 可以声明：

interface PluginRuntimeConfig {
  devosVersion?: string;

  nodeVersion?: string;

  runtimeVersion?: string;
}

例如：

DevOS >= 1.5 < 2.0

如果当前版本不兼容：

PLUGIN_INCOMPATIBLE

禁止强制启动。

21. Plugin Version

遵循 SemVer：

MAJOR.MINOR.PATCH

例如：

1.0.0
1.2.0
1.2.3
2.0.0

规则：

PATCH
Bug fix

MINOR
Backward compatible feature

MAJOR
Breaking change

22. Plugin Upgrade

升级：

Current:
github 1.4.0

Target:
github 1.5.0

流程：

Check
 ↓
Backup Metadata
 ↓
Disable
 ↓
Migration
 ↓
Load New Version
 ↓
Validate
 ↓
Enable

如果失败：

Rollback

23. Migration

Plugin 可以定义 Migration：

interface PluginMigration {
  version: string;

  up(ctx: MigrationContext): Promise<void>;

  down?(ctx: MigrationContext): Promise<void>;
}

例如：

1.0.0
 ↓
1.1.0
 ↓
1.2.0

执行：

1.0 → 1.1
1.1 → 1.2

而不是直接假设数据库已经是最新状态。

24. Migration 原则

Migration 必须：

可追踪
幂等
有版本
有日志
可失败恢复
不直接依赖 UI

禁止：

Plugin startup
 ↓
偷偷修改 DB

所有结构变化必须通过 Migration。

25. Plugin Runtime Context

Plugin 不应该直接访问整个 DevOS Runtime。

提供：

interface PluginContext {
  pluginId: string;

  version: string;

  logger: Logger;

  config: PluginConfigService;

  registry: PluginRegistry;

  events: EventBus;

  actions: ActionRuntime;

  resources: ResourceRuntime;

  tasks: TaskRuntime;

  secrets: SecretReferenceService;

  storage: PluginStorage;

  permissions: PermissionService;
}

26. Plugin Registry

Plugin Registry：

interface PluginRegistry {
  register(plugin: Plugin): Promise<void>;

  unregister(pluginId: string): Promise<void>;

  get(pluginId: string): Plugin | undefined;

  list(): Plugin[];

  enable(pluginId: string): Promise<void>;

  disable(pluginId: string): Promise<void>;
}

27. Plugin Registry 不等于 Capability Registry

必须区分：

Plugin Registry

负责：

Plugin 是否安装
Plugin 是否启用
Plugin 版本
Plugin 状态
Plugin 依赖

而：

Capability Registry

负责：

Plugin 提供什么能力

关系：

Plugin Registry
      ↓
Plugin
      ↓
Capability Registry
      ↓
Capabilities

28. Plugin 注册 Resource

Plugin：

registerResource({
  id: "github.repository"
});

最终：

Resource Registry

获得：

github.repository

29. Plugin 注册 Action

registerAction({
  id: "github.repository.create"
});

最终：

Action Registry

获得：

github.repository.create

执行：

Action Runtime

30. Plugin 注册 Skill

registerSkill({
  id: "github.code_review"
});

最终：

Skill Registry

Agent 自动可以发现：

github.code_review

无需修改 Agent Runtime。

31. Plugin 注册 MCP

Plugin 可以提供 MCP：

mcp.registerServer({
  id: "github",
  tools: [...]
});

但 MCP Tool 最终必须：

MCP
 ↓
Capability
 ↓
Action Runtime

禁止：

MCP Tool
 ↓
直接 DB/API

32. Plugin 注册 UI

Plugin 可以注册：

Route
Navigation
Widget
Settings
Command
Context Action

通过：

UI Registry

而不是修改：

Core React Source

33. Plugin Settings

每个 Plugin 可以定义：

interface PluginSettingsManifest {
  schema: JSONSchema;

  scopes?: (
    | "global"
    | "organization"
    | "project"
    | "user"
  )[];

  ui?: SettingsUIConfig;
}

例如 GitHub：

Global:
GitHub API URL

Organization:
Default GitHub Organization

User:
OAuth Account

34. Configuration Scope

配置支持：

Global
Organization
Project
User
Environment

优先级：

Global
 ↓
Organization
 ↓
Project
 ↓
Environment
 ↓
User

具体优先级必须由配置系统统一定义。

Plugin 不应该自己实现一套配置优先级。

35. Plugin Secrets

Plugin 需要：

API Key
OAuth Token
Private Key
Webhook Secret

只能使用：

Secret Reference

例如：

{
  githubToken: {
    secretRef: "secret://github/token"
  }
}

禁止在 Manifest 中保存：

token: "ghp_xxx"

36. Credential Connection

推荐建立：

Connection

抽象。

例如：

GitHub Connection
Cloudflare Connection
OpenAI Connection
AWS Connection

Plugin 使用：

connectionId

而不是直接获取明文 Token。

37. Plugin Permissions

Plugin 本身必须声明需要什么权限。

例如：

github.repository.read
github.repository.write
network.outbound
secret.read
filesystem.read

Manifest：

permissions: [
  "network.outbound",
  "secret.read"
]

38. Permission Approval

安装 Plugin：

GitHub Plugin requests:

✓ Network Access
✓ Secret Access
✓ Repository Read
✓ Repository Write

用户/管理员：

[Allow]
[Cancel]

对于 Organization：

只有 Org Admin

可以批准 Organization Scope 权限。

39. Plugin Permission 不等于 User Permission

必须区分：

Plugin Permission

与：

User Permission

例如：

Plugin:
network.outbound

User:
github.repository.read

两者都必须满足：

Plugin allowed
+
User allowed

Action 才能执行。

40. Permission Chain

完整权限：

User
 ↓
Organization Policy
 ↓
Plugin Permission
 ↓
Action Permission
 ↓
Resource Scope
 ↓
Action Runtime

任何一层拒绝：

DENIED

41. Plugin Isolation

Plugin 默认应该是：

Capability Isolation

而不是：

完全信任

Plugin 不应该自动获得：

所有 DB
所有 Secrets
所有 Filesystem
所有 Network
所有 Actions

42. Plugin Storage

Plugin 如果需要自己的数据：

PluginStorage

例如：

plugin_data/github/*
plugin_data/browser/*

推荐：

storage.get()
storage.set()
storage.delete()
storage.query()

而不是：

plugin
 ↓
直接 Prisma

43. Plugin Database

对于大型 Plugin，可以声明自己的数据库模型：

github.repository
github.issue

但这些仍然必须通过：

Resource Registry

暴露。

Plugin 内部可以使用 Prisma Repository。

但是：

UI / Agent / MCP / API 不允许绕过 Resource/Action Runtime。

44. Plugin Background Jobs

Plugin 可以创建：

Task
Job
Scheduler

例如 GitHub Plugin：

Every 10 minutes
 ↓
Sync Repositories

但是：

Plugin
 ↓
Task Runtime
 ↓
Job Queue

禁止自己偷偷创建第二套 Queue。

45. Plugin Event Subscription

Plugin 可以订阅：

Event Bus

例如：

github.pull_request.created

或者：

task.completed

events.subscribe(
  "task.completed",
  handler
);

46. Plugin Event 发布

Plugin 也可以发布：

github.repository.synced
github.pull_request.updated

事件必须：

{
  id,
  type,
  source,
  timestamp,
  actor,
  organizationId,
  projectId,
  payload
}

47. Event 与 Action

推荐：

Action
 ↓
Execution
 ↓
Event

例如：

github.repository.sync
 ↓
Execution completed
 ↓
github.repository.synced

其他 Plugin 可以监听。

48. Plugin Health Check

Plugin Runtime 必须支持：

Health
Status
Diagnostics

例如：

GitHub Plugin

Status:
Healthy

Connection:
Connected

API:
OK

Last Sync:
2 min ago

49. Plugin Health Contract

interface PluginHealth {
  status:
    | "healthy"
    | "degraded"
    | "unhealthy"
    | "unknown";

  message?: string;

  checks?: HealthCheck[];
}

50. Plugin Diagnostics

管理员可以看到：

Plugin
├── Version
├── Status
├── Dependencies
├── Permissions
├── Configuration
├── Connections
├── Health
├── Events
├── Tasks
├── Errors
└── Logs

51. Plugin Logs

Plugin Logger：

logger.info(...)
logger.warn(...)
logger.error(...)
logger.debug(...)

日志必须包含：

pluginId
requestId
executionId
taskId
organizationId

这样可以追踪：

User
 ↓
Agent
 ↓
Plugin
 ↓
Action
 ↓
Execution

52. Plugin Metrics

Plugin 可以产生：

Counters
Gauges
Histograms

例如：

github.api.requests
github.api.errors
github.sync.duration
github.repositories.synced

统一进入：

Observability Runtime

53. Plugin Rate Limit

Plugin Action 可以声明：

rateLimit: {
  requests: 100,
  window: "1m"
}

但真正的 Rate Limit 应由：

Action Runtime

统一执行。

Plugin 只是声明策略。

54. Plugin Timeout

Action 可以声明：

timeoutMs

例如：

browser.navigate
timeout: 30s

最终由：

Action Runtime

执行。

55. Plugin Retry

Plugin 可以声明：

retry: {
  maxAttempts: 3,
  backoff: "exponential"
}

但：

Retry 由 Task / Action Runtime 管理。

Plugin 不应该自己写：

while retry...

形成第二套执行系统。

56. Plugin Error Isolation

Plugin 错误：

GitHub API failed

不能导致：

DevOS Core failed

错误必须被包装为：

PluginError

例如：

{
  code: "GITHUB_API_RATE_LIMIT",
  pluginId: "github",
  retryable: true
}

57. Plugin UI Error Isolation

前端：

Plugin UI
 ↓
Error Boundary

如果：

GitHub UI crashed

只能影响：

GitHub UI

不能导致：

整个 Shell 崩溃

具体 UI 规范见：

07_UI_SHELL_APP_MODULE.md

58. Plugin API

Plugin Runtime 对开发者提供：

definePlugin({
  manifest,
  lifecycle,
  resources,
  actions,
  skills,
  mcp,
  ui,
  settings
});

例如：

export default definePlugin({
  manifest: {
    id: "github",
    name: "GitHub",
    version: "1.0.0"
  },

  resources: [
    repositoryResource
  ],

  actions: [
    createRepositoryAction
  ],

  skills: [
    codeReviewSkill
  ]
});

59. Plugin SDK

建议：

packages/plugin-sdk/

提供：

definePlugin()
defineResource()
defineAction()
defineSkill()
defineWidget()
definePage()
defineCommand()
defineContextAction()
defineSettings()
defineMCP()

Plugin 开发者不需要知道 DevOS 内部实现。

60. Plugin SDK 原则

SDK 应该：

简单
稳定
类型安全
版本化

Plugin 不应该依赖：

packages/internal/*

只能依赖：

@devos/plugin-sdk

以及明确公开的 SDK Package。

61. Plugin API Version

Plugin API 必须版本化：

Plugin SDK v1
Plugin SDK v2

Manifest：

apiVersion: "1"

Core 可以同时兼容：

v1
v2

62. Plugin Marketplace

未来可以提供：

Plugin Marketplace

Plugin 信息：

Name
Description
Version
Author
License
Downloads
Rating
Compatibility
Permissions
Dependencies

但 Marketplace 不是 Plugin Runtime 的必要依赖。

DevOS 即使完全离线：

local plugin

也应该正常工作。

63. Plugin Signature

生产环境推荐支持：

Plugin Signature

安装：

Package
 ↓
Signature Verification
 ↓
Trusted Publisher
 ↓
Install

管理员可以设置：

Only trusted plugins

64. Plugin Security Policy

Organization 可以设置：

Allowed Plugins
Denied Plugins
Allowed Publishers
Required Signature
Required Approval
Allowed Permissions

例如：

禁止所有 Plugin 使用 filesystem.write

即使 Plugin Manifest 声明：

filesystem.write

也必须被：

Organization Policy

拒绝。

65. Plugin Environment

Plugin 可以区分：

development
staging
production

例如：

GitHub Plugin

不同环境使用不同 Connection。

Plugin 不应该自己实现：

if production ...

而使用：

Environment Context

66. Multi-Tenant

DevOS 支持：

Organization A
Organization B

同一个 Plugin 可以：

Installed once

但是：

Configuration
Credentials
Permissions
Resources
Tasks

必须支持 Organization Scope。

例如：

GitHub Plugin
├── Org A
│   └── GitHub Connection A
│
└── Org B
    └── GitHub Connection B

禁止跨 Organization 泄露。

67. Plugin Resource Ownership

Resource：

github.repository

必须有：

organizationId
projectId

或者明确的 Scope。

Resource Runtime 必须检查：

Actor
+
Organization
+
Project
+
Resource

68. Plugin Runtime 与 Agent

Agent 不直接读取：

Plugin

而读取：

Capability Registry

例如：

Install GitHub Plugin
 ↓
github.repository.create
 ↓
Capability Registry
 ↓
Agent Discovery

Agent 无需修改。

69. Plugin Runtime 与 MCP

MCP：

Plugin
 ↓
MCP Server
 ↓
Capability
 ↓
Action Runtime

External MCP：

External MCP
 ↓
MCP Client
 ↓
Capability Adapter
 ↓
DevOS Runtime

统一模型。

70. Plugin Runtime 与 UI

Plugin：

Plugin Manifest
 ↓
UI Manifest
 ↓
UI Registry
 ↓
Route
Navigation
Widget
Settings
Command
Context Action

见：

07_UI_SHELL_APP_MODULE.md

71. Plugin Runtime 与 Task

Plugin 不创建：

PluginTask
PluginQueue
PluginWorker

而使用：

Task Runtime
Job Runtime
Queue Runtime
Worker Runtime

例如：

GitHub Sync
 ↓
Task
 ↓
Jobs
 ↓
Workers

72. Plugin Runtime 与 Scheduler

Plugin 可以声明：

schedule({
  id: "github.sync",
  cron: "*/10 * * * *",
  actionId: "github.repository.sync"
});

Scheduler 创建：

Task

而不是 Plugin 自己执行。

73. Plugin Runtime 与 Audit

所有 Plugin Action 自动进入：

Audit Runtime

例如：

User
 ↓
Agent
 ↓
github.repository.delete
 ↓
Action Runtime
 ↓
Audit

记录：

Actor
Plugin
Action
Resource
Input Summary
Result
Timestamp
Execution

74. Plugin Runtime 与 Observability

统一：

Logs
Metrics
Traces
Audit
Execution

可以查询：

Plugin: github

看到：

Requests
Errors
Actions
Tasks
Executions
Latency
External API Calls

75. Plugin Runtime API

推荐：

POST   /api/plugins/install
POST   /api/plugins/:id/enable
POST   /api/plugins/:id/disable
POST   /api/plugins/:id/upgrade
DELETE /api/plugins/:id

GET    /api/plugins
GET    /api/plugins/:id
GET    /api/plugins/:id/health
GET    /api/plugins/:id/logs
GET    /api/plugins/:id/metrics

但是 Controller 不实现 Plugin 业务逻辑。

统一进入：

Plugin Runtime

76. Plugin Service

Backend：

packages/plugin/

推荐：

plugin/
├── plugin-registry.ts
├── plugin-loader.ts
├── plugin-installer.ts
├── plugin-lifecycle.ts
├── plugin-validator.ts
├── plugin-dependency.ts
├── plugin-migration.ts
├── plugin-config.ts
├── plugin-permission.ts
├── plugin-health.ts
├── plugin-storage.ts
├── plugin-security.ts
└── plugin-runtime.ts

77. Plugin Loader

Loader 负责：

Locate Package
 ↓
Load Manifest
 ↓
Validate Manifest
 ↓
Load Module
 ↓
Verify SDK Version
 ↓
Create Plugin Context

禁止 Loader：

直接执行任意未知代码

必须经过：

Security Policy

78. Plugin Installer

Installer：

Resolve Source
 ↓
Download / Copy
 ↓
Verify Signature
 ↓
Verify Integrity
 ↓
Resolve Dependencies
 ↓
Install
 ↓
Migration

79. Plugin Runtime Directory

推荐：

plugins/
├── installed/
│   ├── github/
│   ├── browser/
│   └── cloudflare/
│
├── cache/
│
└── manifests/

具体路径可由部署环境配置。

不要将 Plugin 代码直接混入：

packages/core/

80. Built-in Plugin

部分 Plugin 可以随 DevOS 一起发布：

Core
├── identity
├── notification
├── task
├── agent
└── audit

但推荐仍然遵循：

Plugin Contract

这样：

Built-in Plugin

与：

External Plugin

使用相同生命周期。

81. Core Plugin 与真正 Core

Core 必须保持最小化。

真正不可替代的：

Runtime
Database
Auth
Action
Resource
Task
Event
Plugin

属于：

Core

可插拔功能：

GitHub
Browser
Cloudflare
Docker
WordPress

属于：

Plugin

82. Composite Plugin

Plugin 可以依赖多个 Plugin：

SEO Automation Plugin
├── Browser Plugin
├── Search Plugin
└── AI Plugin

但 Composite Plugin 不应该复制这些能力。

它只负责：

Workflow
Skill
Agent Profile
UI

调用：

Browser
Search
AI

提供的 Capability。

83. Plugin 与 App 的关系

App：

产品/业务领域

Plugin：

扩展能力

例如：

SEO App

可以使用：

Browser Plugin
Search Plugin
GSC Plugin
WordPress Plugin

App 不应该把这些功能复制进自己代码。

84. 一个 Plugin 可以服务多个 App

例如：

Browser Plugin

同时服务：

SEO App
Content App
Research App
DevOps App
Agent

架构：

Browser Plugin
      ↓
Capability Registry
      ↓
SEO
Content
Research
Agent

这也是 DevOS 最重要的复用价值之一。

85. Plugin Discovery

Agent / UI / Developer 都可以发现：

Installed Plugins
Available Plugins
Plugin Capabilities

例如：

Search:
browser

Browser Plugin

Capabilities:
browser.open
browser.navigate
browser.screenshot

Skills:
browser.research

86. Plugin Marketplace 不应该成为 Runtime

Marketplace：

发现
下载
评分
安装

Plugin Runtime：

加载
运行
启停
配置
权限
生命周期

两者必须分离。

87. Plugin Failure Recovery

如果 Plugin 启动失败：

Plugin
 ↓
Initialize
 ↓
FAILED

Runtime 应：

Mark failed
 ↓
Unregister capabilities
 ↓
Stop background tasks
 ↓
Record error
 ↓
Notify administrator

不要：

不断自动重启

除非明确配置 Retry Policy。

88. Plugin Dependency Failure

例如：

SEO Plugin
 ↓
Browser Plugin
 ↓
Browser failed

SEO Plugin 可以变成：

degraded

而不是：

整个 DevOS failed

89. Plugin Disable Impact

Disable Plugin 时必须计算：

Dependent Plugins

例如：

Browser Plugin

被使用：

SEO Plugin
Research Plugin

系统应提示：

Disabling Browser will affect:

SEO Plugin
Research Plugin

[Continue]
[Cancel]

90. Plugin Upgrade Impact

升级时同样检查：

Dependent Plugins

如果：

GitHub 2.0

不兼容：

GitHub Automation Plugin

必须阻止升级或进入兼容升级流程。

91. Plugin State Persistence

Plugin 状态必须持久化：

installed
enabled
version
configuration
permissions
dependencies
health

DevOS 重启：

Database
 ↓
Plugin Registry
 ↓
Restore Plugin State
 ↓
Load
 ↓
Enable

92. Plugin Installation Transaction

安装过程应该尽量具有事务语义：

Validate
 ↓
Install
 ↓
Migration
 ↓
Register
 ↓
Enable

如果中途失败：

Rollback

避免：

Package installed
+
DB migrated
+
Plugin unusable

93. Plugin Lock File

生产环境建议支持：

devos.plugins.lock

记录：

pluginId
version
source
integrity
dependencies

作用：

Development
→ lock

Production
→ reproducible install

94. Plugin Development Mode

开发模式：

devos plugin dev

支持：

Hot Reload
Manifest Reload
UI Reload
Logs
Diagnostics

开发 Plugin：

/home/dev/plugins/my-plugin

直接注册。

95. Plugin CLI

建议提供：

devos plugin list

devos plugin install github

devos plugin uninstall github

devos plugin enable github

devos plugin disable github

devos plugin upgrade github

devos plugin doctor github

devos plugin create my-plugin

CLI 必须调用：

Plugin Runtime

不能实现另一套 Plugin 管理逻辑。

96. Plugin Doctor

例如：

devos plugin doctor github

输出：

Plugin:
github 1.4.0

✓ Manifest
✓ DevOS compatibility
✓ Dependencies
✓ Permissions
✓ Database
✓ Configuration
✓ Connection

Health:
Healthy

97. Plugin Admin UI

DevOS：

/settings/plugins

显示：

Plugins

GitHub
Enabled
v1.4.0
Healthy

Browser
Enabled
v2.1.0
Healthy

Cloudflare
Disabled
v1.0.2

操作：

Enable
Disable
Upgrade
Configure
Health
Logs

98. Plugin Detail UI

Plugin Detail：

GitHub Plugin
────────────────────────

Version
1.4.0

Status
Enabled

Health
Healthy

Capabilities
18

Resources
5

Actions
11

Skills
2

MCP
1

Permissions
4

Dependencies
1

[Disable]
[Upgrade]
[Settings]

99. Plugin Runtime 与 UI Registry 的生命周期

启用：

Plugin Enable
 ↓
Register Resource
 ↓
Register Action
 ↓
Register Skill
 ↓
Register MCP
 ↓
Register Route
 ↓
Register Navigation
 ↓
Register Widget
 ↓
Register Command
 ↓
Register Context Action

禁用：

Plugin Disable
 ↓
Stop Jobs
 ↓
Unsubscribe Events
 ↓
Close Connections
 ↓
Unregister UI
 ↓
Unregister MCP
 ↓
Unregister Skills
 ↓
Unregister Actions
 ↓
Unregister Resources

100. Plugin Registry Consistency

Plugin Registry 与其他 Registry 必须保持一致。

例如：

Plugin disabled

不能出现：

Plugin Registry:
disabled

Action Registry:
github.repository.create  ← still active

必须：

Plugin disabled
 ↓
All Plugin-owned registrations inactive

101. Ownership

所有 Registry Entry 必须记录：

{
  ownerType: "plugin",
  ownerId: "github"
}

例如：

Action:
github.repository.create

owner:
plugin:github

这样 Plugin Disable 时可以准确卸载。

102. Registration Metadata

建议：

interface RegistrationMetadata {
  ownerType:
    | "core"
    | "app"
    | "module"
    | "plugin";

  ownerId: string;

  version?: string;

  registeredAt: string;
}

103. 防止 Plugin 泄漏

如果 Plugin 被卸载：

所有 ownerId = github

的 Registry Entry 都必须被清理。

可以实现：

registry.unregisterByOwner({
  ownerType: "plugin",
  ownerId: "github"
});

104. Plugin Runtime Golden Rule

Plugin 可以：

提供能力
注册能力
消费能力
扩展 UI
监听 Event
创建 Task

Plugin 不可以：

绕过 Runtime
绕过 Permission
绕过 Audit
绕过 Task Runtime
绕过 Action Runtime
直接修改 Core Registry
直接修改用户数据

105. 最终 Plugin 执行链

标准业务：

User
 ↓
UI
 ↓
Action
 ↓
Action Runtime
 ↓
Plugin Action
 ↓
External API
 ↓
Execution
 ↓
Event
 ↓
UI / Agent

Agent：

User Goal
 ↓
Agent
 ↓
Capability Discovery
 ↓
Plugin Capability
 ↓
Action
 ↓
Action Runtime
 ↓
Plugin
 ↓
External System

MCP：

External Agent
 ↓
MCP Server
 ↓
Capability
 ↓
Action Runtime
 ↓
Plugin

106. 完整 Plugin Example

GitHub Plugin：

github/
├── manifest.ts
├── index.ts
│
├── resources/
│   ├── repository.ts
│   ├── issue.ts
│   └── pull-request.ts
│
├── actions/
│   ├── repository-create.ts
│   ├── repository-sync.ts
│   ├── issue-create.ts
│   └── pull-request-merge.ts
│
├── skills/
│   └── code-review.ts
│
├── mcp/
│   └── server.ts
│
├── ui/
│   ├── repositories.tsx
│   ├── issues.tsx
│   ├── settings.tsx
│   └── widgets/
│
├── migrations/
│   ├── 1.1.0.ts
│   └── 1.2.0.ts
│
└── tests/

107. GitHub Manifest 示例

export default {
  id: "github",

  name: "GitHub",

  version: "1.0.0",

  apiVersion: "1",

  runtime: {
    devosVersion: ">=1.0.0"
  },

  permissions: [
    "network.outbound",
    "secret.read"
  ],

  dependencies: [],

  resources: [
    "github.repository",
    "github.issue",
    "github.pull_request"
  ],

  actions: [
    "github.repository.create",
    "github.repository.sync",
    "github.issue.create",
    "github.pull_request.merge"
  ],

  skills: [
    "github.code_review"
  ]
};

108. Plugin Developer Experience

开发者最终应该只需要：

devos plugin create github

得到：

manifest
resources
actions
skills
ui
tests

然后：

devos plugin dev

即可运行。

发布：

devos plugin build
devos plugin publish

109. Zcode 必须实现的 Package

至少：

packages/plugin/
├── types/
├── registry/
├── runtime/
├── loader/
├── installer/
├── lifecycle/
├── dependency/
├── migration/
├── config/
├── permissions/
├── storage/
├── health/
├── security/
└── sdk/

110. Zcode 必须实现的 Backend Services

至少：

PluginService
PluginRegistry
PluginLoader
PluginInstaller
PluginLifecycleService
PluginDependencyService
PluginMigrationService
PluginConfigService
PluginPermissionService
PluginHealthService
PluginSecurityService
PluginStorageService

111. Zcode 必须实现的 API

至少：

GET    /api/plugins

GET    /api/plugins/:id

POST   /api/plugins/install

POST   /api/plugins/:id/enable

POST   /api/plugins/:id/disable

POST   /api/plugins/:id/upgrade

DELETE /api/plugins/:id

GET    /api/plugins/:id/health

GET    /api/plugins/:id/logs

GET    /api/plugins/:id/metrics

112. Zcode 必须实现的 UI

至少：

/settings/plugins

/settings/plugins/:id

/settings/plugins/:id/settings

/settings/plugins/:id/health

/settings/plugins/:id/logs

支持：

Install
Enable
Disable
Upgrade
Uninstall
Configure
Health
Logs

113. Acceptance Test 01

创建：

hello-plugin

安装。

结果：

Plugin Registry
→ hello-plugin installed

114. Acceptance Test 02

Enable：

hello-plugin

结果：

Action Registry
→ hello.hello

出现。

115. Acceptance Test 03

Disable：

hello-plugin

结果：

hello.hello

不可执行。

同时：

Navigation
Route
Widget

全部消失。

116. Acceptance Test 04

安装 Plugin：

github

自动注册：

Resources
Actions
Skills
MCP
UI

不修改 Core source。

117. Acceptance Test 05

卸载：

github

Plugin Runtime 清理：

Routes
Navigation
Widgets
Actions
Skills
MCP
Event Subscriptions
Scheduled Jobs

历史：

Tasks
Executions
Audit

仍然保留。

118. Acceptance Test 06

安装：

plugin-a

依赖：

plugin-b >= 1.2

如果没有：

Installation blocked

并提示：

Missing dependency:
plugin-b >= 1.2

119. Acceptance Test 07

测试循环依赖：

A → B
B → A

结果：

PLUGIN_DEPENDENCY_CYCLE

安装失败。

120. Acceptance Test 08

测试 Plugin Permission。

Plugin 请求：

secret.read

管理员拒绝。

结果：

Plugin installed
but cannot enable

或者：

Plugin capability unavailable

具体策略必须统一。

121. Acceptance Test 09

测试 Multi-Tenant：

Organization A
Organization B

GitHub Connection：

A → Token A
B → Token B

A 的 Action：

github.repository.sync

不能读取 B 的 Connection。

122. Acceptance Test 10

测试 Plugin Crash。

故意让：

github plugin

初始化失败。

结果：

GitHub Plugin → failed

但：

DevOS Shell → healthy
Other Plugins → healthy
Core → healthy

123. Acceptance Test 11

测试 Upgrade。

github 1.0.0
 ↓
github 1.1.0

执行：

Migration
 ↓
Registry update
 ↓
Plugin enable

数据正常。

124. Acceptance Test 12

Migration 失败。

结果：

Upgrade failed

系统不能进入：

half-upgraded

状态。

必须进入：

failed

或者：

rollback

125. Acceptance Test 13

测试 Agent。

安装 GitHub Plugin。

输入：

帮我检查这个 GitHub Repository

Agent 能发现：

github.repository
github.repository.inspect

无需修改 Agent Runtime。

126. Acceptance Test 14

测试 MCP。

外部 Agent 调用：

github_repository_create

执行链必须：

MCP
 ↓
Capability
 ↓
Action Runtime
 ↓
Permission
 ↓
Plugin
 ↓
GitHub API
 ↓
Audit

不能：

MCP
 ↓
GitHub API

127. Acceptance Test 15

测试 UI。

安装 GitHub Plugin。

自动出现：

Plugins
└── GitHub
    ├── Repositories
    ├── Issues
    └── Settings

无需修改：

Sidebar.tsx
Router.tsx
Dashboard.tsx

128. Acceptance Test 16

Plugin 注册 Widget：

dashboard.main

启用 Plugin：

Widget visible

禁用：

Widget invisible

129. Acceptance Test 17

Plugin 注册 Context Action：

github.repository

显示：

Create Issue

点击：

Action Runtime

执行。

130. Acceptance Test 18

CLI：

devos plugin list

与 UI：

/settings/plugins

显示完全一致的 Plugin Registry 数据。

CLI 和 UI 不得各自维护状态。

131. 最终架构

                         DevOS Core
                              │
                       Plugin Runtime
                              │
       ┌──────────────────────┼──────────────────────┐
       │                      │                      │
    Lifecycle              Security              Registry
       │                      │                      │
 Install/Enable          Permission             Plugin Registry
 Disable/Upgrade         Isolation               Capability Registry
 Migration               Secrets                 UI Registry
       │                      │                      │
       └──────────────────────┼──────────────────────┘
                              │
                         Plugin SDK
                              │
       ┌──────────────┬───────┼────────┬──────────────┐
       │              │       │        │              │
    Resource        Action  Skill     MCP             UI
       │              │       │        │              │
       └──────────────┴───────┼────────┴──────────────┘
                              │
                       DevOS Runtime
                              │
       ┌──────────────┬───────┼────────┬──────────────┐
       │              │       │        │              │
    Resource       Action   Task     Event          Agent
    Runtime        Runtime  Runtime  Bus            Runtime

132. Plugin 的最终定位

Plugin 不是：

一个 npm package

Plugin 是：

DevOS 的能力扩展单元

一个完整 Plugin 可以同时提供：

Resource
+
Action
+
Skill
+
MCP
+
Workflow
+
UI
+
Settings
+
Widget
+
Event

并通过统一 Runtime 接入：

Auth
Permission
Task
Queue
Audit
Observability
Agent
UI

133. 最重要的 Golden Rules

1. Plugin 不修改 Core。

2. Plugin 必须拥有 Manifest。

3. Plugin 必须拥有稳定 ID。

4. Plugin 必须拥有版本。

5. Plugin 必须拥有生命周期。

6. Install ≠ Enable。

7. Disable ≠ Uninstall。

8. Uninstall 默认不删除业务数据。

9. Plugin 必须声明 Dependencies。

10. Plugin 必须声明 Permissions。

11. Plugin Action 必须进入 Action Runtime。

12. Plugin Task 必须进入 Task Runtime。

13. Plugin Event 必须进入 Event Bus。

14. Plugin UI 必须进入 UI Registry。

15. Plugin MCP 不得绕过 Action Runtime。

16. Agent 不直接调用 Plugin。

17. Agent 通过 Capability Registry 使用 Plugin 能力。

18. Plugin 不应该创建自己的 Queue。

19. Plugin 不应该创建自己的权限系统。

20. Plugin 不应该创建自己的 Audit 系统。

21. Plugin 不应该创建自己的 Scheduler。

22. Plugin 不应该创建自己的 Notification 系统。

23. Plugin 不应该直接操作其他 Plugin 的数据。

24. Plugin 必须支持 Organization Scope。

25. Plugin 必须能够被独立禁用。

26. 单个 Plugin 崩溃不能导致 DevOS 崩溃。

27. Core 不应该知道具体 Plugin。

28. App 不应该复制 Plugin 能力。

29. Plugin 应该尽量提供 Capability，而不是绑定某个 App。

30. DevOS 的所有扩展最终都应该回到统一 Runtime。

134. 最终 DevOS 扩展模型

至此，DevOS 的扩展体系形成：

                    DevOS Core
                        │
        ┌───────────────┼────────────────┐
        │               │                │
      App            Plugin            Agent
        │               │                │
     Module          Capability         Goal
        │               │                │
        └───────────────┼────────────────┘
                        │
                 Resource / Action
                        │
                  Action Runtime
                        │
        ┌───────────────┼────────────────┐
        │               │                │
      Task            Event             Audit
        │               │                │
      Queue          Event Bus       Observability
        │
      Worker

而 Plugin 自身：

Plugin
├── Manifest
├── Resources
├── Actions
├── Skills
├── MCP
├── Workflows
├── Agent Profiles
├── UI
├── Settings
├── Widgets
├── Commands
├── Context Actions
├── Events
├── Migrations
├── Permissions
├── Dependencies
└── Configuration

最终实现：

DevOS Core 负责平台，App 负责业务领域，Plugin 负责可复用能力，Agent 负责动态决策，而所有执行统一经过 Runtime。

这使 DevOS 真正成为一个可以持续扩展的 Developer Work OS / Agent Platform，而不是一个越来越臃肿的 Admin Dashboard。

44 KiB Raw Permalink Blame History Unescape Escape

DevOS Developer Work OS

Plugin Runtime / Plugin Lifecycle / Extension Platform 设计规范

1. 文档目标

2. Plugin 的核心定义

3. Plugin Architecture

4. Plugin Manifest

5. Plugin ID

6. Plugin Namespace

7. Plugin 类型

8. Plugin Source

9. Plugin Installation

10. Plugin 状态机

11. Plugin Lifecycle

12. Install 与 Enable 必须分离

13. Disable Plugin

14. Uninstall Plugin

15. Plugin Data Policy

16. Plugin Dependencies

17. Dependency Types

18. Dependency Resolution

19. Dependency Cycle

20. Compatibility

21. Plugin Version

22. Plugin Upgrade

23. Migration

24. Migration 原则

25. Plugin Runtime Context

26. Plugin Registry

27. Plugin Registry 不等于 Capability Registry

28. Plugin 注册 Resource

29. Plugin 注册 Action

30. Plugin 注册 Skill

31. Plugin 注册 MCP

32. Plugin 注册 UI

33. Plugin Settings

34. Configuration Scope

35. Plugin Secrets

36. Credential Connection

37. Plugin Permissions

38. Permission Approval

39. Plugin Permission 不等于 User Permission

40. Permission Chain

41. Plugin Isolation

42. Plugin Storage

43. Plugin Database

44. Plugin Background Jobs

45. Plugin Event Subscription

46. Plugin Event 发布

47. Event 与 Action

48. Plugin Health Check

49. Plugin Health Contract

50. Plugin Diagnostics

51. Plugin Logs

52. Plugin Metrics

53. Plugin Rate Limit

54. Plugin Timeout

55. Plugin Retry

56. Plugin Error Isolation

57. Plugin UI Error Isolation

58. Plugin API

59. Plugin SDK

60. Plugin SDK 原则

61. Plugin API Version

62. Plugin Marketplace

63. Plugin Signature

64. Plugin Security Policy

65. Plugin Environment

66. Multi-Tenant

67. Plugin Resource Ownership

68. Plugin Runtime 与 Agent

69. Plugin Runtime 与 MCP

70. Plugin Runtime 与 UI

71. Plugin Runtime 与 Task

72. Plugin Runtime 与 Scheduler

73. Plugin Runtime 与 Audit

74. Plugin Runtime 与 Observability

75. Plugin Runtime API

76. Plugin Service

77. Plugin Loader

44 KiB

Raw Permalink Blame History