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

# DevOS Developer Work OS
## Plugin Runtime / Plugin Lifecycle / Extension Platform 设计规范

Version: 1.0

---

# 1. 文档目标

本文定义 DevOS Plugin Runtime。

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

目标：

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

例如：

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

都应该可以成为 Plugin。

Plugin 可以提供：

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

最终：

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

---

# 2. Plugin 的核心定义

Plugin：

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

Plugin 不是简单的：

```text
npm package
```

也不是简单的：

```text
UI module
```

而是：

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

---

# 3. Plugin Architecture

最终：

```text
                    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。

推荐：

```ts
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 必须：

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

例如：

```text
github
browser
cloudflare
docker
kubernetes
wordpress
```

禁止：

```text
github-v2
github-2026
github-plugin-new
```

版本由：

```text
version
```

单独管理。

---

# 6. Plugin Namespace

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

例如：

```text
github.repository
github.issue
github.pull_request

github.repository.create
github.issue.create

github.code_review
```

Browser：

```text
browser.session
browser.page

browser.open
browser.navigate

browser.research
```

禁止 Plugin 创建：

```text
user
settings
task
agent
```

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

---

# 7. Plugin 类型

Plugin Runtime 支持不同类型。

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

例如：

```text
GitHub
→ integration

OpenAI
→ provider

Browser
→ automation

Docker
→ developer

SEO Analyzer
→ ai
```

大多数 Plugin 可以使用：

```text
composite
```

因为同时包含：

```text
Resource
Action
Skill
UI
MCP
```

---

# 8. Plugin Source

Plugin 来源：

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

例如：

```text
DevOS Core Plugin
→ builtin

本地开发插件
→ local

公司内部插件
→ workspace

Marketplace
→ marketplace
```

---

# 9. Plugin Installation

安装流程：

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

必须支持：

```text
Install
Uninstall
Enable
Disable
Upgrade
Rollback
```

---

# 10. Plugin 状态机

Plugin 状态：

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

状态转换：

```text
available
   ↓
installing
   ↓
installed
   ↓
enabling
   ↓
enabled
```

禁用：

```text
enabled
   ↓
disabling
   ↓
disabled
```

升级：

```text
enabled
   ↓
upgrading
   ↓
enabled
```

失败：

```text
installing
    ↓
failed
```

---

# 11. Plugin Lifecycle

Plugin 生命周期：

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

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

```ts
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 必须分离

这是非常重要的设计。

安装：

```text
Package exists
```

启用：

```text
Plugin is active
```

例如：

```text
GitHub Plugin
Status: Installed
```

但：

```text
Enabled: false
```

此时：

```text
Resource
Action
Skill
MCP
UI
```

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

---

# 13. Disable Plugin

Disable 后：

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

但是：

> Plugin 数据默认不能删除。

例如：

```text
GitHub Plugin disabled
```

以下仍然存在：

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

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

---

# 14. Uninstall Plugin

Uninstall 是更危险的操作。

默认：

```text
Uninstall
 ≠
Delete Plugin Data
```

推荐：

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

用户明确选择：

```text
Delete Plugin Data
```

才执行数据删除。

---

# 15. Plugin Data Policy

Manifest 可以定义：

```ts
interface PluginDataPolicy {
  canDeleteData: boolean;

  dataResources?: string[];

  preserveOnUninstall?: boolean;
}
```

默认：

```text
preserveOnUninstall = true
```

防止误删数据。

---

# 16. Plugin Dependencies

Plugin 可以依赖其他 Plugin。

例如：

```text
SEO Plugin
 ↓
Browser Plugin
 ↓
Browser Runtime
```

Manifest：

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

---

# 17. Dependency Types

支持：

```text
required
optional
peer
```

例如：

```text
required:
github

optional:
browser

peer:
ai provider
```

---

# 18. Dependency Resolution

安装：

```text
Install SEO Plugin
```

Runtime：

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

如果依赖缺失：

```text
Dependency missing
```

应该明确提示：

```text
SEO Plugin requires Browser Plugin >= 1.2

[Install Dependency]
```

而不是启动后才报错。

---

# 19. Dependency Cycle

必须检测：

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

禁止循环依赖。

安装时直接失败：

```text
PLUGIN_DEPENDENCY_CYCLE
```

---

# 20. Compatibility

Plugin Manifest 可以声明：

```ts
interface PluginRuntimeConfig {
  devosVersion?: string;

  nodeVersion?: string;

  runtimeVersion?: string;
}
```

例如：

```text
DevOS >= 1.5 < 2.0
```

如果当前版本不兼容：

```text
PLUGIN_INCOMPATIBLE
```

禁止强制启动。

---

# 21. Plugin Version

遵循 SemVer：

```text
MAJOR.MINOR.PATCH
```

例如：

```text
1.0.0
1.2.0
1.2.3
2.0.0
```

规则：

```text
PATCH
Bug fix

MINOR
Backward compatible feature

MAJOR
Breaking change
```

---

# 22. Plugin Upgrade

升级：

```text
Current:
github 1.4.0

Target:
github 1.5.0
```

流程：

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

如果失败：

```text
Rollback
```

---

# 23. Migration

Plugin 可以定义 Migration：

```ts
interface PluginMigration {
  version: string;

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

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

例如：

```text
1.0.0
 ↓
1.1.0
 ↓
1.2.0
```

执行：

```text
1.0 → 1.1
1.1 → 1.2
```

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

---

# 24. Migration 原则

Migration 必须：

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

禁止：

```text
Plugin startup
 ↓
偷偷修改 DB
```

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

---

# 25. Plugin Runtime Context

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

提供：

```ts
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：

```ts
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

必须区分：

```text
Plugin Registry
```

负责：

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

而：

```text
Capability Registry
```

负责：

```text
Plugin 提供什么能力
```

关系：

```text
Plugin Registry
      ↓
Plugin
      ↓
Capability Registry
      ↓
Capabilities
```

---

# 28. Plugin 注册 Resource

Plugin：

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

最终：

```text
Resource Registry
```

获得：

```text
github.repository
```

---

# 29. Plugin 注册 Action

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

最终：

```text
Action Registry
```

获得：

```text
github.repository.create
```

执行：

```text
Action Runtime
```

---

# 30. Plugin 注册 Skill

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

最终：

```text
Skill Registry
```

Agent 自动可以发现：

```text
github.code_review
```

无需修改 Agent Runtime。

---

# 31. Plugin 注册 MCP

Plugin 可以提供 MCP：

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

但 MCP Tool 最终必须：

```text
MCP
 ↓
Capability
 ↓
Action Runtime
```

禁止：

```text
MCP Tool
 ↓
直接 DB/API
```

---

# 32. Plugin 注册 UI

Plugin 可以注册：

```text
Route
Navigation
Widget
Settings
Command
Context Action
```

通过：

```text
UI Registry
```

而不是修改：

```text
Core React Source
```

---

# 33. Plugin Settings

每个 Plugin 可以定义：

```ts
interface PluginSettingsManifest {
  schema: JSONSchema;

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

  ui?: SettingsUIConfig;
}
```

例如 GitHub：

```text
Global:
GitHub API URL

Organization:
Default GitHub Organization

User:
OAuth Account
```

---

# 34. Configuration Scope

配置支持：

```text
Global
Organization
Project
User
Environment
```

优先级：

```text
Global
 ↓
Organization
 ↓
Project
 ↓
Environment
 ↓
User
```

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

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

---

# 35. Plugin Secrets

Plugin 需要：

```text
API Key
OAuth Token
Private Key
Webhook Secret
```

只能使用：

```text
Secret Reference
```

例如：

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

禁止在 Manifest 中保存：

```text
token: "ghp_xxx"
```

---

# 36. Credential Connection

推荐建立：

```text
Connection
```

抽象。

例如：

```text
GitHub Connection
Cloudflare Connection
OpenAI Connection
AWS Connection
```

Plugin 使用：

```ts
connectionId
```

而不是直接获取明文 Token。

---

# 37. Plugin Permissions

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

例如：

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

Manifest：

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

---

# 38. Permission Approval

安装 Plugin：

```text
GitHub Plugin requests:

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

用户/管理员：

```text
[Allow]
[Cancel]
```

对于 Organization：

```text
只有 Org Admin
```

可以批准 Organization Scope 权限。

---

# 39. Plugin Permission 不等于 User Permission

必须区分：

```text
Plugin Permission
```

与：

```text
User Permission
```

例如：

```text
Plugin:
network.outbound

User:
github.repository.read
```

两者都必须满足：

```text
Plugin allowed
+
User allowed
```

Action 才能执行。

---

# 40. Permission Chain

完整权限：

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

任何一层拒绝：

```text
DENIED
```

---

# 41. Plugin Isolation

Plugin 默认应该是：

```text
Capability Isolation
```

而不是：

```text
完全信任
```

Plugin 不应该自动获得：

```text
所有 DB
所有 Secrets
所有 Filesystem
所有 Network
所有 Actions
```

---

# 42. Plugin Storage

Plugin 如果需要自己的数据：

```text
PluginStorage
```

例如：

```text
plugin_data/github/*
plugin_data/browser/*
```

推荐：

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

而不是：

```ts
plugin
 ↓
直接 Prisma
```

---

# 43. Plugin Database

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

```text
github.repository
github.issue
```

但这些仍然必须通过：

```text
Resource Registry
```

暴露。

Plugin 内部可以使用 Prisma Repository。

但是：

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

---

# 44. Plugin Background Jobs

Plugin 可以创建：

```text
Task
Job
Scheduler
```

例如 GitHub Plugin：

```text
Every 10 minutes
 ↓
Sync Repositories
```

但是：

```text
Plugin
 ↓
Task Runtime
 ↓
Job Queue
```

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

---

# 45. Plugin Event Subscription

Plugin 可以订阅：

```text
Event Bus
```

例如：

```text
github.pull_request.created
```

或者：

```text
task.completed
```

注册：

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

---

# 46. Plugin Event 发布

Plugin 也可以发布：

```text
github.repository.synced
github.pull_request.updated
```

事件必须：

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

---

# 47. Event 与 Action

推荐：

```text
Action
 ↓
Execution
 ↓
Event
```

例如：

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

其他 Plugin 可以监听。

---

# 48. Plugin Health Check

Plugin Runtime 必须支持：

```text
Health
Status
Diagnostics
```

例如：

```text
GitHub Plugin

Status:
Healthy

Connection:
Connected

API:
OK

Last Sync:
2 min ago
```

---

# 49. Plugin Health Contract

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

  message?: string;

  checks?: HealthCheck[];
}
```

---

# 50. Plugin Diagnostics

管理员可以看到：

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

---

# 51. Plugin Logs

Plugin Logger：

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

日志必须包含：

```text
pluginId
requestId
executionId
taskId
organizationId
```

这样可以追踪：

```text
User
 ↓
Agent
 ↓
Plugin
 ↓
Action
 ↓
Execution
```

---

# 52. Plugin Metrics

Plugin 可以产生：

```text
Counters
Gauges
Histograms
```

例如：

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

统一进入：

```text
Observability Runtime
```

---

# 53. Plugin Rate Limit

Plugin Action 可以声明：

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

但真正的 Rate Limit 应由：

```text
Action Runtime
```

统一执行。

Plugin 只是声明策略。

---

# 54. Plugin Timeout

Action 可以声明：

```text
timeoutMs
```

例如：

```text
browser.navigate
timeout: 30s
```

最终由：

```text
Action Runtime
```

执行。

---

# 55. Plugin Retry

Plugin 可以声明：

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

但：

> Retry 由 Task / Action Runtime 管理。

Plugin 不应该自己写：

```text
while retry...
```

形成第二套执行系统。

---

# 56. Plugin Error Isolation

Plugin 错误：

```text
GitHub API failed
```

不能导致：

```text
DevOS Core failed
```

错误必须被包装为：

```text
PluginError
```

例如：

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

---

# 57. Plugin UI Error Isolation

前端：

```text
Plugin UI
 ↓
Error Boundary
```

如果：

```text
GitHub UI crashed
```

只能影响：

```text
GitHub UI
```

不能导致：

```text
整个 Shell 崩溃
```

具体 UI 规范见：

```text
07_UI_SHELL_APP_MODULE.md
```

---

# 58. Plugin API

Plugin Runtime 对开发者提供：

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

例如：

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

  resources: [
    repositoryResource
  ],

  actions: [
    createRepositoryAction
  ],

  skills: [
    codeReviewSkill
  ]
});
```

---

# 59. Plugin SDK

建议：

```text
packages/plugin-sdk/
```

提供：

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

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

---

# 60. Plugin SDK 原则

SDK 应该：

```text
简单
稳定
类型安全
版本化
```

Plugin 不应该依赖：

```text
packages/internal/*
```

只能依赖：

```text
@devos/plugin-sdk
```

以及明确公开的 SDK Package。

---

# 61. Plugin API Version

Plugin API 必须版本化：

```text
Plugin SDK v1
Plugin SDK v2
```

Manifest：

```ts
apiVersion: "1"
```

Core 可以同时兼容：

```text
v1
v2
```

---

# 62. Plugin Marketplace

未来可以提供：

```text
Plugin Marketplace
```

Plugin 信息：

```text
Name
Description
Version
Author
License
Downloads
Rating
Compatibility
Permissions
Dependencies
```

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

DevOS 即使完全离线：

```text
local plugin
```

也应该正常工作。

---

# 63. Plugin Signature

生产环境推荐支持：

```text
Plugin Signature
```

安装：

```text
Package
 ↓
Signature Verification
 ↓
Trusted Publisher
 ↓
Install
```

管理员可以设置：

```text
Only trusted plugins
```

---

# 64. Plugin Security Policy

Organization 可以设置：

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

例如：

```text
禁止所有 Plugin 使用 filesystem.write
```

即使 Plugin Manifest 声明：

```text
filesystem.write
```

也必须被：

```text
Organization Policy
```

拒绝。

---

# 65. Plugin Environment

Plugin 可以区分：

```text
development
staging
production
```

例如：

```text
GitHub Plugin
```

不同环境使用不同 Connection。

Plugin 不应该自己实现：

```text
if production ...
```

而使用：

```text
Environment Context
```

---

# 66. Multi-Tenant

DevOS 支持：

```text
Organization A
Organization B
```

同一个 Plugin 可以：

```text
Installed once
```

但是：

```text
Configuration
Credentials
Permissions
Resources
Tasks
```

必须支持 Organization Scope。

例如：

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

禁止跨 Organization 泄露。

---

# 67. Plugin Resource Ownership

Resource：

```text
github.repository
```

必须有：

```text
organizationId
projectId
```

或者明确的 Scope。

Resource Runtime 必须检查：

```text
Actor
+
Organization
+
Project
+
Resource
```

---

# 68. Plugin Runtime 与 Agent

Agent 不直接读取：

```text
Plugin
```

而读取：

```text
Capability Registry
```

例如：

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

Agent 无需修改。

---

# 69. Plugin Runtime 与 MCP

MCP：

```text
Plugin
 ↓
MCP Server
 ↓
Capability
 ↓
Action Runtime
```

External MCP：

```text
External MCP
 ↓
MCP Client
 ↓
Capability Adapter
 ↓
DevOS Runtime
```

统一模型。

---

# 70. Plugin Runtime 与 UI

Plugin：

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

见：

```text
07_UI_SHELL_APP_MODULE.md
```

---

# 71. Plugin Runtime 与 Task

Plugin 不创建：

```text
PluginTask
PluginQueue
PluginWorker
```

而使用：

```text
Task Runtime
Job Runtime
Queue Runtime
Worker Runtime
```

例如：

```text
GitHub Sync
 ↓
Task
 ↓
Jobs
 ↓
Workers
```

---

# 72. Plugin Runtime 与 Scheduler

Plugin 可以声明：

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

Scheduler 创建：

```text
Task
```

而不是 Plugin 自己执行。

---

# 73. Plugin Runtime 与 Audit

所有 Plugin Action 自动进入：

```text
Audit Runtime
```

例如：

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

记录：

```text
Actor
Plugin
Action
Resource
Input Summary
Result
Timestamp
Execution
```

---

# 74. Plugin Runtime 与 Observability

统一：

```text
Logs
Metrics
Traces
Audit
Execution
```

可以查询：

```text
Plugin: github
```

看到：

```text
Requests
Errors
Actions
Tasks
Executions
Latency
External API Calls
```

---

# 75. Plugin Runtime API

推荐：

```text
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 业务逻辑。

统一进入：

```text
Plugin Runtime
```

---

# 76. Plugin Service

Backend：

```text
packages/plugin/
```

推荐：

```text
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 负责：

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

禁止 Loader：

```text
直接执行任意未知代码
```

必须经过：

```text
Security Policy
```

---

# 78. Plugin Installer

Installer：

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

---

# 79. Plugin Runtime Directory

推荐：

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

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

不要将 Plugin 代码直接混入：

```text
packages/core/
```

---

# 80. Built-in Plugin

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

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

但推荐仍然遵循：

```text
Plugin Contract
```

这样：

```text
Built-in Plugin
```

与：

```text
External Plugin
```

使用相同生命周期。

---

# 81. Core Plugin 与真正 Core

Core 必须保持最小化。

真正不可替代的：

```text
Runtime
Database
Auth
Action
Resource
Task
Event
Plugin
```

属于：

```text
Core
```

可插拔功能：

```text
GitHub
Browser
Cloudflare
Docker
WordPress
```

属于：

```text
Plugin
```

---

# 82. Composite Plugin

Plugin 可以依赖多个 Plugin：

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

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

它只负责：

```text
Workflow
Skill
Agent Profile
UI
```

调用：

```text
Browser
Search
AI
```

提供的 Capability。

---

# 83. Plugin 与 App 的关系

App：

```text
产品/业务领域
```

Plugin：

```text
扩展能力
```

例如：

```text
SEO App
```

可以使用：

```text
Browser Plugin
Search Plugin
GSC Plugin
WordPress Plugin
```

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

---

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

例如：

```text
Browser Plugin
```

同时服务：

```text
SEO App
Content App
Research App
DevOps App
Agent
```

架构：

```text
Browser Plugin
      ↓
Capability Registry
      ↓
SEO
Content
Research
Agent
```

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

---

# 85. Plugin Discovery

Agent / UI / Developer 都可以发现：

```text
Installed Plugins
Available Plugins
Plugin Capabilities
```

例如：

```text
Search:
browser
```

返回：

```text
Browser Plugin

Capabilities:
browser.open
browser.navigate
browser.screenshot

Skills:
browser.research
```

---

# 86. Plugin Marketplace 不应该成为 Runtime

Marketplace：

```text
发现
下载
评分
安装
```

Plugin Runtime：

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

两者必须分离。

---

# 87. Plugin Failure Recovery

如果 Plugin 启动失败：

```text
Plugin
 ↓
Initialize
 ↓
FAILED
```

Runtime 应：

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

不要：

```text
不断自动重启
```

除非明确配置 Retry Policy。

---

# 88. Plugin Dependency Failure

例如：

```text
SEO Plugin
 ↓
Browser Plugin
 ↓
Browser failed
```

SEO Plugin 可以变成：

```text
degraded
```

而不是：

```text
整个 DevOS failed
```

---

# 89. Plugin Disable Impact

Disable Plugin 时必须计算：

```text
Dependent Plugins
```

例如：

```text
Browser Plugin
```

被使用：

```text
SEO Plugin
Research Plugin
```

系统应提示：

```text
Disabling Browser will affect:

SEO Plugin
Research Plugin

[Continue]
[Cancel]
```

---

# 90. Plugin Upgrade Impact

升级时同样检查：

```text
Dependent Plugins
```

如果：

```text
GitHub 2.0
```

不兼容：

```text
GitHub Automation Plugin
```

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

---

# 91. Plugin State Persistence

Plugin 状态必须持久化：

```text
installed
enabled
version
configuration
permissions
dependencies
health
```

DevOS 重启：

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

---

# 92. Plugin Installation Transaction

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

```text
Validate
 ↓
Install
 ↓
Migration
 ↓
Register
 ↓
Enable
```

如果中途失败：

```text
Rollback
```

避免：

```text
Package installed
+
DB migrated
+
Plugin unusable
```

---

# 93. Plugin Lock File

生产环境建议支持：

```text
devos.plugins.lock
```

记录：

```text
pluginId
version
source
integrity
dependencies
```

作用：

```text
Development
→ lock

Production
→ reproducible install
```

---

# 94. Plugin Development Mode

开发模式：

```text
devos plugin dev
```

支持：

```text
Hot Reload
Manifest Reload
UI Reload
Logs
Diagnostics
```

开发 Plugin：

```text
/home/dev/plugins/my-plugin
```

直接注册。

---

# 95. Plugin CLI

建议提供：

```text
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 必须调用：

```text
Plugin Runtime
```

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

---

# 96. Plugin Doctor

例如：

```text
devos plugin doctor github
```

输出：

```text
Plugin:
github 1.4.0

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

Health:
Healthy
```

---

# 97. Plugin Admin UI

DevOS：

```text
/settings/plugins
```

显示：

```text
Plugins

GitHub
Enabled
v1.4.0
Healthy

Browser
Enabled
v2.1.0
Healthy

Cloudflare
Disabled
v1.0.2
```

操作：

```text
Enable
Disable
Upgrade
Configure
Health
Logs
```

---

# 98. Plugin Detail UI

Plugin Detail：

```text
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 的生命周期

启用：

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

禁用：

```text
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 必须保持一致。

例如：

```text
Plugin disabled
```

不能出现：

```text
Plugin Registry:
disabled

Action Registry:
github.repository.create  ← still active
```

必须：

```text
Plugin disabled
 ↓
All Plugin-owned registrations inactive
```

---

# 101. Ownership

所有 Registry Entry 必须记录：

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

例如：

```text
Action:
github.repository.create

owner:
plugin:github
```

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

---

# 102. Registration Metadata

建议：

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

  ownerId: string;

  version?: string;

  registeredAt: string;
}
```

---

# 103. 防止 Plugin 泄漏

如果 Plugin 被卸载：

```text
所有 ownerId = github
```

的 Registry Entry 都必须被清理。

可以实现：

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

---

# 104. Plugin Runtime Golden Rule

Plugin 可以：

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

Plugin 不可以：

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

---

# 105. 最终 Plugin 执行链

标准业务：

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

Agent：

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

MCP：

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

---

# 106. 完整 Plugin Example

GitHub Plugin：

```text
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 示例

```ts
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

开发者最终应该只需要：

```text
devos plugin create github
```

得到：

```text
manifest
resources
actions
skills
ui
tests
```

然后：

```text
devos plugin dev
```

即可运行。

发布：

```text
devos plugin build
devos plugin publish
```

---

# 109. Zcode 必须实现的 Package

至少：

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

---

# 110. Zcode 必须实现的 Backend Services

至少：

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

---

# 111. Zcode 必须实现的 API

至少：

```text
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

至少：

```text
/settings/plugins

/settings/plugins/:id

/settings/plugins/:id/settings

/settings/plugins/:id/health

/settings/plugins/:id/logs
```

支持：

```text
Install
Enable
Disable
Upgrade
Uninstall
Configure
Health
Logs
```

---

# 113. Acceptance Test 01

创建：

```text
hello-plugin
```

安装。

结果：

```text
Plugin Registry
→ hello-plugin installed
```

---

# 114. Acceptance Test 02

Enable：

```text
hello-plugin
```

结果：

```text
Action Registry
→ hello.hello
```

出现。

---

# 115. Acceptance Test 03

Disable：

```text
hello-plugin
```

结果：

```text
hello.hello
```

不可执行。

同时：

```text
Navigation
Route
Widget
```

全部消失。

---

# 116. Acceptance Test 04

安装 Plugin：

```text
github
```

自动注册：

```text
Resources
Actions
Skills
MCP
UI
```

不修改 Core source。

---

# 117. Acceptance Test 05

卸载：

```text
github
```

Plugin Runtime 清理：

```text
Routes
Navigation
Widgets
Actions
Skills
MCP
Event Subscriptions
Scheduled Jobs
```

历史：

```text
Tasks
Executions
Audit
```

仍然保留。

---

# 118. Acceptance Test 06

安装：

```text
plugin-a
```

依赖：

```text
plugin-b >= 1.2
```

如果没有：

```text
Installation blocked
```

并提示：

```text
Missing dependency:
plugin-b >= 1.2
```

---

# 119. Acceptance Test 07

测试循环依赖：

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

结果：

```text
PLUGIN_DEPENDENCY_CYCLE
```

安装失败。

---

# 120. Acceptance Test 08

测试 Plugin Permission。

Plugin 请求：

```text
secret.read
```

管理员拒绝。

结果：

```text
Plugin installed
but cannot enable
```

或者：

```text
Plugin capability unavailable
```

具体策略必须统一。

---

# 121. Acceptance Test 09

测试 Multi-Tenant：

```text
Organization A
Organization B
```

GitHub Connection：

```text
A → Token A
B → Token B
```

A 的 Action：

```text
github.repository.sync
```

不能读取 B 的 Connection。

---

# 122. Acceptance Test 10

测试 Plugin Crash。

故意让：

```text
github plugin
```

初始化失败。

结果：

```text
GitHub Plugin → failed
```

但：

```text
DevOS Shell → healthy
Other Plugins → healthy
Core → healthy
```

---

# 123. Acceptance Test 11

测试 Upgrade。

```text
github 1.0.0
 ↓
github 1.1.0
```

执行：

```text
Migration
 ↓
Registry update
 ↓
Plugin enable
```

数据正常。

---

# 124. Acceptance Test 12

Migration 失败。

结果：

```text
Upgrade failed
```

系统不能进入：

```text
half-upgraded
```

状态。

必须进入：

```text
failed
```

或者：

```text
rollback
```

---

# 125. Acceptance Test 13

测试 Agent。

安装 GitHub Plugin。

输入：

```text
帮我检查这个 GitHub Repository
```

Agent 能发现：

```text
github.repository
github.repository.inspect
```

无需修改 Agent Runtime。

---

# 126. Acceptance Test 14

测试 MCP。

外部 Agent 调用：

```text
github_repository_create
```

执行链必须：

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

不能：

```text
MCP
 ↓
GitHub API
```

---

# 127. Acceptance Test 15

测试 UI。

安装 GitHub Plugin。

自动出现：

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

无需修改：

```text
Sidebar.tsx
Router.tsx
Dashboard.tsx
```

---

# 128. Acceptance Test 16

Plugin 注册 Widget：

```text
dashboard.main
```

启用 Plugin：

```text
Widget visible
```

禁用：

```text
Widget invisible
```

---

# 129. Acceptance Test 17

Plugin 注册 Context Action：

```text
github.repository
```

显示：

```text
Create Issue
```

点击：

```text
Action Runtime
```

执行。

---

# 130. Acceptance Test 18

CLI：

```text
devos plugin list
```

与 UI：

```text
/settings/plugins
```

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

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

---

# 131. 最终架构

```text
                         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 不是：

```text
一个 npm package
```

Plugin 是：

```text
DevOS 的能力扩展单元
```

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

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

并通过统一 Runtime 接入：

```text
Auth
Permission
Task
Queue
Audit
Observability
Agent
UI
```

---

# 133. 最重要的 Golden Rules

```text
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 的扩展体系形成：

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

而 Plugin 自身：

```text
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。