# `05_PLUGIN_RUNTIME.md`

> DevOS Developer Work OS
> Plugin Runtime / Extension System / Plugin UI / Capability / Lifecycle 设计规范
> Version: 1.0

---

## 1. 文档目标

`05` 定义 DevOS 的统一 **Plugin Runtime**。

DevOS 的目标不是把所有功能都写进 Core，而是：

> **Core 提供稳定的 Runtime，业务能力通过 Plugin 扩展。**

最终结构：

```text
DevOS Core
│
├── Resource Runtime
├── Action Runtime
├── Event Runtime
├── Task Runtime
├── Execution Runtime
├── Plugin Runtime
├── MCP Runtime
├── Skill Runtime
├── Agent Runtime
└── UI Runtime
        │
        ▼
   Plugin Extensions
```

Plugin 是 DevOS 扩展能力的主要载体。

---

# 2. Plugin 的定义

Plugin 不是简单的：

```text
npm package
```

也不是简单的：

```text
一个页面
```

而是：

> **一个可以向 DevOS Runtime 注册能力、资源、动作、事件、任务、UI、MCP、Skill 的可管理扩展单元。**

例如：

```text
GitHub Plugin
Cloudflare Plugin
Docker Plugin
WordPress Plugin
SEO Plugin
Google Search Console Plugin
```

---

# 3. Plugin 的能力模型

一个 Plugin 可以包含：

```text
Plugin
│
├── Resources
│
├── Actions
│
├── Events
│
├── Tasks
│
├── Workflows
│
├── MCP Servers / Tools
│
├── Skills
│
├── Agent Capabilities
│
├── UI Pages
│
├── Navigation
│
├── Dashboard Widgets
│
├── Reports
│
├── Context Actions
│
├── Settings
│
└── Permissions
```

但：

> Plugin 不要求必须拥有所有能力。

最小 Plugin 可以只有一个 Action。

---

# 4. Plugin 与 Core 的关系

正确：

```text
DevOS Core
      ↑
      │ Extension API
      │
    Plugin
```

Plugin 可以依赖 Core：

```text
Plugin
 ↓
DevOS SDK
 ↓
DevOS Runtime
```

但 Core **不能依赖具体 Plugin**。

错误：

```text
Core
 └── github
 └── cloudflare
 └── seo
```

正确：

```text
Core
 └── Plugin Runtime

plugins/
 ├── github
 ├── cloudflare
 ├── seo
 └── docker
```

---

# 5. Namespace

每个 Plugin 必须拥有唯一 namespace。

例如：

```text
github
cloudflare
docker
wordpress
seo
```

Plugin 内部资源：

```text
github.repository
github.organization
```

Action：

```text
github.repository.sync
github.repository.create
github.repository.delete
```

Event：

```text
github.repository.updated
github.repository.deleted
```

Skill：

```text
github.repository.manage
```

---

# 6. Plugin Manifest

每个 Plugin 必须有：

```text
plugin.json
```

示例：

```json
{
  "id": "github",
  "name": "GitHub",
  "version": "1.0.0",
  "description": "GitHub integration",
  "author": "DevOS",
  "runtime": "devos",
  "apiVersion": "1",
  "permissions": [],
  "capabilities": []
}
```

---

# 7. 完整 Manifest

推荐：

```ts
interface PluginManifest {
  id: string

  name: string

  version: string

  description?: string

  author?: PluginAuthor

  homepage?: string

  icon?: string

  apiVersion: string

  runtimeVersion?: string

  entry: PluginEntry

  capabilities?: PluginCapabilities

  permissions?: PluginPermission[]

  dependencies?: PluginDependency[]

  settings?: PluginSettingDefinition[]

  ui?: PluginUIManifest
}
```

---

# 8. Plugin Entry

支持：

```text
backend
frontend
worker
mcp
```

例如：

```json
{
  "entry": {
    "server": "./dist/server.js",
    "client": "./dist/client.js"
  }
}
```

---

# 9. Plugin 生命周期

Plugin 必须拥有生命周期。

```text
installed
   ↓
enabled
   ↓
loaded
   ↓
registered
   ↓
active
```

停止：

```text
active
 ↓
disabled
 ↓
unloaded
```

卸载：

```text
disabled
 ↓
uninstalled
```

---

# 10. Lifecycle Hooks

Plugin 可以实现：

```ts
interface Plugin {
  onInstall?(ctx: PluginContext): Promise<void>

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

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

  onStart?(ctx: PluginContext): Promise<void>

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

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

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

---

# 11. Install 与 Enable 必须分离

这是非常重要的设计。

```text
Install
```

代表：

> Plugin 已经存在于系统。

```text
Enable
```

代表：

> Plugin 当前允许运行。

因此：

```text
Installed ≠ Enabled
```

例如：

```text
GitHub Plugin
Installed: yes
Enabled: no
```

不会执行任何 GitHub Action。

---

# 12. Plugin Registry

DevOS 必须拥有全局 Plugin Registry：

```ts
interface PluginRegistry {
  register(plugin: Plugin): void

  unregister(pluginId: string): void

  get(pluginId: string): Plugin

  has(pluginId: string): boolean

  list(): Plugin[]
}
```

Registry 是 Runtime 的核心入口。

---

# 13. Plugin Runtime

Plugin Runtime 负责：

```text
发现 Plugin
安装 Plugin
验证 Plugin
加载 Plugin
启动 Plugin
注册能力
管理生命周期
卸载 Plugin
```

架构：

```text
Plugin Package
      ↓
Plugin Manager
      ↓
Plugin Validator
      ↓
Plugin Loader
      ↓
Plugin Runtime
      ↓
Registry
```

---

# 14. Plugin Manager

Plugin Manager 是管理层。

职责：

```text
install()
uninstall()
enable()
disable()
update()
reload()
get()
list()
```

API：

```ts
interface PluginManager {
  install(source: PluginSource): Promise<Plugin>

  uninstall(id: string): Promise<void>

  enable(id: string): Promise<void>

  disable(id: string): Promise<void>

  update(id: string): Promise<void>

  reload(id: string): Promise<void>
}
```

---

# 15. Plugin Source

支持：

```text
npm
git
local
url
builtin
```

例如：

```text
@devos/plugin-github
```

或者：

```text
github.com/example/devos-plugin-github
```

或者本地：

```text
./plugins/github
```

---

# 16. Built-in Plugin

部分能力可以作为 Built-in Plugin。

例如：

```text
Core
 ├── auth
 ├── settings
 └── audit
```

但推荐仍然使用 Plugin API。

这样 Core 与 Extension 的边界更清晰。

---

# 17. Plugin API

Plugin 不允许直接修改 DevOS 内部模块。

错误：

```ts
plugin.prisma.user.update(...)
```

正确：

```ts
plugin.resources.register(...)
plugin.actions.register(...)
plugin.events.subscribe(...)
```

也就是说：

> Plugin 通过公开 Runtime API 扩展系统。

---

# 18. Plugin Context

```ts
interface PluginContext {
  pluginId: string

  logger: Logger

  config: PluginConfig

  resources: ResourceRegistry

  actions: ActionRegistry

  events: EventBus

  tasks: TaskRuntime

  queue: QueueRuntime

  workflows: WorkflowRegistry

  permissions: PermissionRegistry

  ui: UIRuntime

  mcp: MCPRuntime

  skills: SkillRuntime
}
```

---

# 19. Plugin Resource

Plugin 可以注册 Resource。

例如 GitHub：

```ts
resources.register({
  type: "github.repository",

  schema: repositorySchema,

  actions: [
    "github.repository.sync",
    "github.repository.create"
  ]
})
```

这样 GitHub Repository 就进入 DevOS Resource Model。

---

# 20. Plugin Action

Plugin 可以注册 Action：

```ts
actions.register({
  id: "github.repository.sync",

  input: schema,

  mode: "async",

  handler: async (input, ctx) => {
    // ...
  }
})
```

Action 必须遵循 `03_RESOURCE_ACTION_MODEL.md`。

---

# 21. Plugin Action 不能绕过 Runtime

Plugin 内部：

```text
Plugin
 ↓
Action
 ↓
Action Runtime
```

不能：

```text
Plugin
 ↓
direct DB
```

不能：

```text
Plugin
 ↓
direct Queue
```

不能：

```text
Plugin
 ↓
bypass permission
```

---

# 22. Plugin Event

Plugin 可以发布：

```ts
events.publish({
  type: "github.repository.updated",
  resource: {
    type: "github.repository",
    id: repositoryId
  },
  data: {}
})
```

也可以订阅：

```ts
events.subscribe(
  "project.created",
  handler
)
```

---

# 23. Plugin Task

Plugin 可以注册 Task Type：

```ts
tasks.registerType({
  type: "github.repository.sync",

  action: "github.repository.sync"
})
```

这样 Scheduler / Agent / Workflow 都可以创建：

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

---

# 24. Plugin Scheduler

Plugin 可以声明默认 Schedule：

例如：

```text
每天同步 GitHub Repository
```

但是 Scheduler 仍然属于 DevOS Core。

Plugin 只是注册：

```text
Schedule Template
```

而不是创建第二个 Scheduler。

---

# 25. Plugin Workflow Node

Plugin 可以提供 Workflow Node：

```ts
workflows.registerNode({
  type: "github.create_issue"
})
```

Workflow：

```text
Scan Website
 ↓
Condition
 ↓
github.create_issue
 ↓
Notify
```

Node 内部仍然调用 Action Runtime。

---

# 26. Plugin MCP

Plugin 可以提供 MCP。

例如：

```text
GitHub Plugin
    │
    └── MCP
         ├── search_repository
         ├── create_issue
         └── create_pull_request
```

MCP Tool：

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

而不是单独实现业务执行。

---

# 27. Plugin Skill

Plugin 可以提供 Skill：

```text
github.repository.manage
```

Skill 描述：

```text
什么时候使用
需要什么 Resource
可以使用什么 Action
需要什么权限
如何完成目标
```

Skill 不应该自己执行底层操作。

```text
Skill
 ↓
Action
 ↓
Runtime
```

---

# 28. Plugin 与 Agent

Agent 可以发现 Plugin 提供的能力：

```text
Agent
 ↓
Capability Discovery
 ↓
Plugin
 ├── Action
 ├── MCP
 └── Skill
```

例如：

```text
用户：
把最新代码部署到服务器
```

Agent 发现：

```text
GitHub Plugin
Docker Plugin
Server Plugin
```

组合：

```text
github.repository.sync
        ↓
docker.build
        ↓
server.deploy
```

---

# 29. Capability Registry

因此 DevOS 需要一个统一：

```text
Capability Registry
```

它可以发现：

```text
Resource
Action
Skill
MCP Tool
Workflow Node
Task Type
```

例如：

```ts
capabilities.search({
  query: "deploy website"
})
```

返回：

```text
server.deploy
docker.build
github.repository.release
```

---

# 30. Plugin UI

这是本设计非常重要的一部分。

Plugin 不应该只是后台代码。

Plugin 可以拥有自己的 UI。

例如 GitHub Plugin：

```text
GitHub
├── Repositories
├── Issues
├── Pull Requests
├── Actions
└── Settings
```

---

# 31. Plugin Navigation

Plugin 可以注册导航：

```ts
ui.navigation.register({
  id: "github",
  label: "GitHub",
  icon: "github",
  children: [
    {
      id: "repositories",
      label: "Repositories",
      route: "/github/repositories"
    }
  ]
})
```

DevOS Shell 自动显示。

---

# 32. Plugin Page

Plugin 可以提供页面：

```ts
ui.pages.register({
  route: "/github/repositories",
  component: RepositoryPage
})
```

或者：

```text
/plugin/github/repositories
```

具体 URL 由 DevOS UI Router 决定。

Plugin 不应该强行替换整个 App Router。

---

# 33. Plugin Settings

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

例如：

```text
Settings
 └── Plugins
      └── GitHub
           ├── Token
           ├── Organization
           ├── Default Repository
           └── Webhook
```

Settings Schema：

```ts
interface PluginSettingDefinition {
  key: string

  type:
    | "string"
    | "number"
    | "boolean"
    | "select"
    | "secret"
    | "json"

  label: string

  description?: string

  default?: unknown

  required?: boolean
}
```

---

# 34. Secret Settings

Token / API Key 等：

```text
type = secret
```

不能：

```text
GET /plugin/settings
```

直接返回明文。

UI：

```text
GitHub Token
************

[Update]
```

后端使用：

```text
Secret Store
```

存储。

---

# 35. Plugin Dashboard Widget

Plugin 可以注册 Dashboard Widget。

例如：

```text
GitHub
 ├── Open PRs: 12
 ├── Issues: 31
 └── Failed Actions: 2
```

注册：

```ts
ui.dashboard.registerWidget({
  id: "github.stats",
  title: "GitHub",
  component: GitHubStatsWidget
})
```

---

# 36. Context Action

Plugin 可以向 Resource 增加上下文操作。

例如用户打开：

```text
github.repository
```

出现：

```text
[Sync]
[Open GitHub]
[Create Issue]
[Deploy]
```

但 Context Action 本质仍然是：

```text
Action
```

因此：

```text
UI Context Action
 ↓
Action Runtime
```

---

# 37. Report

Plugin 可以注册 Report：

```text
SEO Report
GitHub Activity
Server Health
Deployment Report
```

例如：

```ts
ui.reports.register({
  id: "github.activity",
  resource: "github.repository"
})
```

Report 数据应该通过 Action / Query Runtime 获取。

---

# 38. Query 与 Action

需要区分：

```text
Query
=
读取数据
```

```text
Action
=
改变状态 / 执行行为
```

Plugin 可以注册：

```text
Query
Action
```

但 Query 也必须经过：

```text
Permission
Tenant Scope
Audit / Observability
```

---

# 39. Plugin Permission

每个 Plugin 必须声明权限。

例如：

```json
{
  "permissions": [
    "github.repositories.read",
    "github.repositories.write",
    "github.issues.write"
  ]
}
```

Permission 必须经过：

```text
User
 ↓
Role
 ↓
Permission
 ↓
Plugin Capability
 ↓
Action
```

---

# 40. Plugin Scope

权限还必须支持 Scope。

例如：

```text
github.repositories.write
```

不能代表：

```text
所有 Repository
```

可能限定：

```text
organization = xxx
repository = xxx
```

因此：

```ts
scope: {
  organizationId,
  resourceId
}
```

---

# 41. Plugin Multi-Tenant

DevOS 是多组织系统时：

```text
Organization A
 └── GitHub Config A

Organization B
 └── GitHub Config B
```

Plugin 配置不能默认全局共享。

配置应该有 Scope：

```text
system
organization
project
user
```

---

# 42. Plugin Config

```ts
interface PluginConfig {
  pluginId: string

  scope: "system" | "organization" | "project" | "user"

  scopeId?: string

  values: Record<string, unknown>
}
```

例如：

```text
GitHub Token

Organization:
acme

Token:
xxx
```

---

# 43. Plugin Dependency

Plugin 可以依赖其他 Plugin：

```json
{
  "dependencies": {
    "docker": "^1.0.0"
  }
}
```

例如：

```text
deployment-plugin
       ↓
docker-plugin
       ↓
server-plugin
```

Plugin Manager 必须检查依赖。

---

# 44. Dependency Graph

安装时：

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

必须确保：

```text
C installed
B installed
A installed
```

卸载时反向：

```text
A
 ↓
B
 ↓
C
```

如果其他 Plugin 仍然依赖 C：

```text
❌ Cannot uninstall C
```

---

# 45. Version Compatibility

Manifest：

```json
{
  "apiVersion": "1",
  "runtimeVersion": ">=1.0.0 <2.0.0"
}
```

Plugin Manager 必须检查。

避免：

```text
DevOS 2.x
 ↓
Old Plugin
 ↓
Runtime crash
```

---

# 46. Plugin Migration

Plugin 升级可能有：

```text
1.0
 ↓
1.1
 ↓
2.0
```

支持：

```ts
migrations: [
  "1.1.0",
  "2.0.0"
]
```

升级：

```text
backup
 ↓
migration
 ↓
load
 ↓
health check
```

失败：

```text
rollback
```

---

# 47. Plugin Health Check

每个 Plugin 可以实现：

```ts
healthCheck(): Promise<PluginHealth>
```

结果：

```text
healthy
degraded
unhealthy
```

例如：

```text
GitHub Plugin

Status: Healthy

API: Connected
Token: Valid
Rate Limit: 4921
```

---

# 48. Plugin Status

Plugin UI：

```text
Plugin
────────────────────

GitHub

Version:
1.4.2

Status:
● Enabled

Health:
● Healthy

Actions:
12

Resources:
3

MCP Tools:
8

Skills:
4

[Settings]
[Disable]
[Update]
[Uninstall]
```

---

# 49. Plugin Logs

Plugin 必须拥有：

```text
plugin logger
```

例如：

```ts
ctx.logger.info("Repository synced", {
  repositoryId
})
```

日志必须带：

```text
pluginId
requestId
taskId
executionId
```

---

# 50. Plugin Isolation

第一版不要过度复杂。

推荐：

```text
Trusted Plugin
```

运行在：

```text
同一 Node.js Runtime
```

但是：

```text
API boundary
permission boundary
config boundary
logging boundary
```

必须存在。

---

# 51. Untrusted Plugin

未来如果允许第三方 Plugin：

```text
Untrusted Plugin
```

建议独立：

```text
Process
Container
Sandbox
```

例如：

```text
DevOS
 │
 ├── Core
 │
 └── Plugin Worker
       └── Container
```

第一版不要为了 Sandbox 把架构搞得过度复杂。

但 API 必须预留这个能力。

---

# 52. Plugin Security

Plugin 默认：

```text
不能访问任意文件
不能直接访问数据库
不能绕过 Permission
不能读取其他 Plugin Secret
不能修改 Core
```

允许的能力：

```text
Runtime API
Plugin API
Declared Permission
Declared Secret
```

---

# 53. Plugin UI Security

Plugin Frontend 不能默认：

```ts
window.__DEVOS_INTERNAL__
```

直接访问 Core 内部对象。

应该：

```text
Plugin UI
 ↓
DevOS SDK
 ↓
API
```

---

# 54. Plugin SDK

开发 Plugin 时：

```ts
import {
  definePlugin,
  defineResource,
  defineAction
} from "@devos/sdk"
```

例如：

```ts
export default definePlugin({
  id: "github",

  setup(ctx) {
    ctx.resources.register(...)
    ctx.actions.register(...)
    ctx.ui.navigation.register(...)
  }
})
```

---

# 55. Plugin SDK 的目标

Plugin 开发者不需要知道：

```text
Prisma
BullMQ
Redis
NestJS internals
React Router internals
```

只需要使用：

```text
DevOS SDK
```

这也是 DevOS 成为真正“自己的开发框架”的关键。

---

# 56. Plugin Package

推荐结构：

```text
plugins/
└── github/
    ├── plugin.json
    ├── package.json
    ├── src/
    │   ├── index.ts
    │   ├── manifest.ts
    │   ├── resources/
    │   ├── actions/
    │   ├── events/
    │   ├── tasks/
    │   ├── workflows/
    │   ├── mcp/
    │   ├── skills/
    │   ├── ui/
    │   │   ├── pages/
    │   │   ├── widgets/
    │   │   └── navigation/
    │   └── settings/
    └── migrations/
```

---

# 57. 推荐 Monorepo

最终：

```text
devos/
│
├── apps/
│   ├── api/
│   ├── web/
│   ├── worker/
│   └── scheduler/
│
├── packages/
│   ├── core/
│   ├── sdk/
│   ├── resource/
│   ├── action/
│   ├── task/
│   ├── execution/
│   ├── event/
│   ├── queue/
│   ├── workflow/
│   ├── plugin/
│   ├── mcp/
│   ├── skill/
│   └── agent/
│
└── plugins/
    ├── github/
    ├── docker/
    ├── cloudflare/
    └── seo/
```

---

# 58. Plugin 不应该直接属于 Apps

错误：

```text
apps/api/src/plugins/github
```

这样 Plugin 很快会和 API 强耦合。

正确：

```text
plugins/github
```

Plugin 是独立一级模块。

---

# 59. Plugin UI 加载

建议：

```text
DevOS Shell
     │
     ├── Core UI
     │
     ├── Plugin Manifest
     │
     └── Plugin UI Module
```

插件可以动态贡献：

```text
Routes
Navigation
Widgets
Settings
Context Actions
```

---

# 60. Plugin 页面不能破坏 Shell

Plugin 页面必须运行在 DevOS Shell：

```text
┌─────────────────────────────────────┐
│ DevOS Header                        │
├──────────┬──────────────────────────┤
│ Sidebar  │ Plugin Page              │
│          │                          │
│ GitHub   │ Repository               │
│ Docker   │                          │
│ SEO      │                          │
│          │                          │
└──────────┴──────────────────────────┘
```

Plugin 只负责：

```text
Content
```

Shell 仍然属于 Core。

---

# 61. Plugin Settings 页面

Core 提供通用 Settings Shell：

```text
Settings
│
├── General
├── Security
├── Users
│
└── Plugins
     ├── GitHub
     ├── Docker
     ├── Cloudflare
     └── SEO
```

Plugin 只需要提供：

```text
Settings Schema
Settings UI
```

---

# 62. Plugin Install UI

DevOS 应提供：

```text
Plugin Marketplace
```

但 Marketplace 不是 Plugin Runtime 本身。

可以：

```text
Marketplace
 ↓
Plugin Package
 ↓
Plugin Manager
```

未来可以支持：

```text
Official
Community
Private
Local
Git
NPM
```

---

# 63. Plugin Marketplace

Plugin 页面：

```text
GitHub
────────────────────

Official

Version 1.4.2

★ 4.9

Resources: 3
Actions: 12
MCP: 8
Skills: 4

[Install]
```

安装后：

```text
[Enable]
```

---

# 64. Plugin Manifest 与 Marketplace Metadata

必须分离。

Manifest：

```text
Runtime required data
```

Marketplace metadata：

```text
Description
Screenshots
README
Author
Rating
Downloads
Documentation
```

不要让 Runtime 依赖 Marketplace。

---

# 65. Plugin Registry 数据库

建议：

```text
plugins
plugin_versions
plugin_configs
plugin_permissions
plugin_dependencies
plugin_migrations
```

---

# 66. Plugin 表

```sql
plugins
-------
id
name
version
status
enabled
source
manifest
installed_at
updated_at
```

---

# 67. Plugin Config 表

```sql
plugin_configs
--------------
id
plugin_id
scope
scope_id
config
created_at
updated_at
```

Secret 不应该直接以普通 JSON 保存。

---

# 68. Plugin Permission 表

```sql
plugin_permissions
------------------
id
plugin_id
permission
scope
created_at
```

---

# 69. Plugin Event

Plugin 生命周期本身也应该发布 Event：

```text
plugin.installed
plugin.enabled
plugin.disabled
plugin.updated
plugin.uninstalled
plugin.failed
```

这样其他模块可以监听。

---

# 70. Plugin Failure

Plugin 启动失败：

```text
Plugin
 ↓
Load
 ↓
Error
 ↓
status = failed
```

不能导致整个 DevOS Crash。

理想：

```text
Core        → Running
GitHub      → Failed
Docker      → Running
SEO         → Running
```

---

# 71. Plugin Reload

开发环境支持：

```text
Hot Reload
```

生产环境建议：

```text
Disable
 ↓
Unload
 ↓
Update
 ↓
Load
 ↓
Enable
```

避免运行中的状态污染。

---

# 72. Plugin Development Mode

开发者可以：

```bash
devos plugin dev ./plugins/github
```

支持：

```text
watch
reload
logs
inspect
```

---

# 73. Plugin CLI

DevOS 应提供：

```bash
devos plugin list
devos plugin install github
devos plugin enable github
devos plugin disable github
devos plugin update github
devos plugin remove github
devos plugin inspect github
```

---

# 74. Plugin Generator

这对“自己的开发框架”非常重要。

提供：

```bash
devos create plugin github
```

自动生成：

```text
plugin.json
package.json
src/index.ts
src/actions/
src/resources/
src/events/
src/ui/
src/mcp/
src/skills/
```

这样未来开发任何项目都可以快速扩展。

---

# 75. Plugin 类型

建议定义：

```text
integration
domain
developer
ui
agent
infrastructure
```

但这些只是 metadata。

不要为每种类型建立不同 Runtime。

---

# 76. Domain Plugin

例如：

```text
SEO Plugin
CRM Plugin
Content Plugin
```

可以拥有：

```text
Resource
Action
Task
Workflow
UI
Skill
MCP
```

因此 SEO 不需要变成：

```text
seo-infra
seo-backend
seo-agent
seo-mcp
```

而可以是：

```text
seo plugin
```

运行在 DevOS Runtime 上。

---

# 77. 一个完整 Plugin 示例

```text
seo
│
├── Resources
│   ├── seo.website
│   ├── seo.keyword
│   ├── seo.content
│   └── seo.backlink
│
├── Actions
│   ├── seo.website.scan
│   ├── seo.keyword.research
│   ├── seo.content.generate
│   └── seo.backlink.submit
│
├── Tasks
│   ├── seo.website.audit
│   └── seo.campaign.execute
│
├── Workflows
│   └── seo.campaign
│
├── MCP
│   └── seo tools
│
├── Skills
│   ├── seo.audit
│   └── seo.campaign
│
└── UI
    ├── Dashboard
    ├── Websites
    ├── Keywords
    ├── Content
    ├── Backlinks
    └── Reports
```

这就是：

> **一个产品能力，而不是多个产品。**

---

# 78. Plugin 与 Fork

DevOS 必须同时支持两种模式。

## Extension Mode

```text
DevOS
 └── Plugin
```

适合：

```text
SEO
GitHub
Docker
Cloudflare
Monitoring
```

---

## Fork Mode

```text
DevOS Starter
      ↓
Fork
      ↓
独立 App
```

适合：

```text
完全独立 SaaS
不同业务模型
不同部署生命周期
不同数据库
不同团队
```

这两个模式必须从架构层面同时支持。

---

# 79. Core / Plugin / App 三层

最终：

```text
┌──────────────────────────────┐
│            App               │
│                              │
│   Product-specific logic     │
└───────────────┬──────────────┘
                │
┌───────────────▼──────────────┐
│          Plugins             │
│                              │
│   Domain / Integration       │
└───────────────┬──────────────┘
                │
┌───────────────▼──────────────┐
│          DevOS Core          │
│                              │
│ Resource / Action / Task      │
│ Event / Queue / Agent / MCP   │
└──────────────────────────────┘
```

---

# 80. 黄金规则

### Rule 1

```text
Plugin 是扩展，不是 Core
```

### Rule 2

```text
Plugin 不允许直接修改 Core
```

### Rule 3

```text
Plugin 所有业务操作必须经过 Action Runtime
```

### Rule 4

```text
Plugin 所有异步操作必须经过 Task Runtime
```

### Rule 5

```text
Plugin 不允许创建自己的 Queue / Worker / Scheduler
```

### Rule 6

```text
Plugin UI 必须运行在 DevOS Shell
```

### Rule 7

```text
Plugin MCP 必须映射到 Action / Capability
```

### Rule 8

```text
Plugin Skill 不执行底层业务
```

### Rule 9

```text
Plugin 配置必须支持 scope
```

### Rule 10

```text
Plugin Secret 必须进入 Secret Store
```

### Rule 11

```text
Plugin 必须声明权限
```

### Rule 12

```text
Plugin 生命周期必须由 Plugin Manager 管理
```

---

# 81. Zcode 实现要求

下一阶段必须实现：

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

至少包含：

```text
PluginManager
PluginRegistry
PluginLoader
PluginValidator
PluginLifecycle
PluginConfig
PluginPermission
PluginHealth
```

---

## Plugin API

```text
POST   /plugins/install
POST   /plugins/:id/enable
POST   /plugins/:id/disable
POST   /plugins/:id/update
DELETE /plugins/:id

GET    /plugins
GET    /plugins/:id
GET    /plugins/:id/health
GET    /plugins/:id/settings
PATCH  /plugins/:id/settings
```

---

## Plugin UI

至少实现：

```text
/ plugins
/ plugins/:id
/ plugins/:id/settings
```

并支持：

```text
Install
Enable
Disable
Update
Uninstall
Health
Settings
```

---

# 82. 关键验收标准

Zcode 完成 `05` 后，必须可以演示：

### Demo 1

安装 Plugin：

```text
Install GitHub Plugin
```

### Demo 2

启用：

```text
Enable GitHub
```

### Demo 3

Plugin 自动出现：

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

### Demo 4

Repository 页面：

```text
[Sync]
```

点击：

```text
UI
 ↓
Action
 ↓
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Execution
```

### Demo 5

MCP：

```text
Agent
 ↓
GitHub MCP
 ↓
github.repository.sync
 ↓
Action Runtime
```

### Demo 6

Agent：

```text
Agent
 ↓
Discover Capability
 ↓
GitHub Skill
 ↓
GitHub Action
```

### Demo 7

Plugin 禁用：

```text
Disable GitHub
```

之后：

```text
GitHub Actions
GitHub MCP
GitHub Skills
GitHub UI
```

全部进入 Disabled 状态。

---

# 83. 最终 Plugin 架构

完成 `05` 后，DevOS 的结构应该变成：

```text
                           DevOS
                             │
              ┌──────────────┴──────────────┐
              │                             │
          Core Runtime                 Plugin Runtime
              │                             │
      ┌───────┼────────┐          ┌─────────┼─────────┐
      │       │        │          │         │         │
   Resource Action   Event      Plugin    Plugin    Plugin
      │       │        │          │         │         │
      └───────┼────────┘        GitHub    Docker     SEO
              │
         Task Runtime
              │
         Execution
              │
          Queue/Worker
              │
        ┌─────┴─────┐
        │           │
       MCP        Agent
        │           │
        └─────┬─────┘
              │
         Capability
              │
           Skills
```

最终形成一个非常关键的原则：

> **DevOS Core 不负责“拥有所有功能”，而负责“让任何功能都能以统一方式进入系统”。**

这才是 DevOS 从一个项目逐渐成为你自己的**通用开发框架 / Application Runtime / Agent Platform**的关键。