zcode/devos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
851ccf1d7fb46cd97707e7034ac333575bdb108d
devos/Docs/DevOS-Platform-v2/11_PLUGIN_RUNTIME.md
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

3500 lines
42 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DevOS Plugin Runtime
> Version: 1.0
> Status: Implementation Specification
> Target: Zcode
> Previous: 10_EVENT_AUDIT_OBSERVABILITY_RUNTIME.md
> Next: 12_*
---
# 1. 目标
DevOS Plugin Runtime 是整个 DevOS 的扩展系统。
Plugin 必须能够扩展：
- Resource
- Action
- Capability
- Skill
- MCP
- Workflow
- Event
- UI
- Navigation
- Settings
- Dashboard
- Widget
- Notification
- Scheduler
- Worker Capability
Plugin 不是简单的 npm package。
Plugin 是：
> 可以被 DevOS 安装、配置、启停、升级、卸载，并向 DevOS Runtime 注册能力和 UI 的扩展单元。
---
# 2. 核心原则
Plugin 必须运行在 DevOS Runtime 之上。
正确：
Plugin
↓
Plugin Runtime
↓
DevOS Registry
↓
DevOS Runtime
禁止：
Plugin
↓
自己的数据库
↓
自己的 Queue
↓
自己的 Auth
↓
自己的 EventBus
↓
自己的 Task System
除非明确声明为 external service，并通过标准 Adapter 接入。
---
# 3. Plugin 的本质
Plugin 是：
```text
Extension Package
+
Manifest
+
Runtime
+
Capabilities
+
UI
+
Configuration
````
例如 SEO Plugin：
```text
seo.plugin
├── Resource
│ ├── seo.website
│ ├── seo.keyword
│ └── seo.article
│
├── Action
│ ├── seo.website.scan
│ ├── seo.keyword.research
│ └── seo.article.generate
│
├── Skill
│ ├── seo-audit
│ └── content-generation
│
├── MCP
│ ├── search-engine
│ └── browser
│
├── Workflow
│ └── seo-audit-workflow
│
├── Event
│ ├── seo.website.scanned
│ └── seo.article.generated
│
└── UI
├── Website
├── Keywords
├── Articles
└── Settings
```
---
# 4. Plugin Namespace
每个 Plugin 必须拥有唯一 namespace。
格式：
```text
<vendor>.<plugin>
```
例如：
```text
devos.seo
devos.devops
devos.crm
github.integration
cloudflare.integration
```
Plugin 内部 Resource：
```text
devos.seo.website
devos.seo.keyword
```
Action：
```text
devos.seo.website.scan
```
Skill：
```text
devos.seo.audit
```
禁止两个 Plugin 注册同一个 namespace。
---
# 5. Plugin ID
Plugin ID：
```ts
type PluginId = string
```
例如：
```text
devos.seo
```
必须满足：
```text
^[a-z0-9][a-z0-9._-]*$
```
---
# 6. Plugin Manifest
每个 Plugin 必须提供：
```text
plugin.json
```
推荐：
```json
{
"id": "devos.seo",
"name": "SEO",
"version": "1.0.0",
"description": "SEO automation capabilities",
"runtime": "devos",
"apiVersion": "1",
"author": "DevOS",
"license": "MIT"
}
```
---
# 7. 完整 Manifest
```ts
interface PluginManifest {
id: string
name: string
version: string
description?: string
apiVersion: string
runtime: 'devos'
author?: string
homepage?: string
repository?: string
license?: string
icon?: string
categories?: string[]
dependencies?: PluginDependency[]
optionalDependencies?: PluginDependency[]
permissions?: PluginPermission[]
capabilities?: PluginCapabilityDeclaration[]
resources?: PluginResourceDeclaration[]
actions?: PluginActionDeclaration[]
skills?: PluginSkillDeclaration[]
mcp?: PluginMCPDeclaration[]
workflows?: PluginWorkflowDeclaration[]
events?: PluginEventDeclaration[]
ui?: PluginUIDeclaration[]
settings?: PluginSettingDeclaration[]
workers?: PluginWorkerDeclaration[]
}
```
---
# 8. Plugin 生命周期
Plugin 状态：
```text
discovered
↓
installing
↓
installed
↓
configuring
↓
enabled
↓
running
↓
disabled
↓
uninstalling
↓
uninstalled
```
异常：
```text
install_failed
activation_failed
runtime_error
upgrade_failed
```
---
# 9. Plugin Runtime 状态
```ts
type PluginStatus =
| 'discovered'
| 'installing'
| 'installed'
| 'configuring'
| 'enabled'
| 'running'
| 'disabled'
| 'uninstalling'
| 'uninstalled'
| 'install_failed'
| 'activation_failed'
| 'runtime_error'
| 'upgrade_failed'
```
---
# 10. Plugin Resource
Plugin 本身必须成为 DevOS Resource：
```text
core.plugin
```
Plugin Resource：
```text
core.plugin.installation
```
---
# 11. Plugin Actions
至少：
```text
core.plugin.install
core.plugin.uninstall
core.plugin.enable
core.plugin.disable
core.plugin.restart
core.plugin.upgrade
core.plugin.configure
core.plugin.health
core.plugin.reload
```
---
# 12. 所有 Plugin 管理操作必须走 Action Runtime
错误：
```text
POST /plugins/:id/enable
controller:
plugin.enable()
```
正确：
```text
HTTP
↓
core.plugin.enable
↓
Action Runtime
↓
Plugin Runtime
```
CLI：
```text
devos plugin enable devos.seo
```
也必须：
```text
CLI
↓
Action Runtime
↓
core.plugin.enable
```
Agent：
```text
Agent
↓
core.plugin.enable
↓
Action Runtime
```
三者执行路径必须完全一致。
---
# 13. Plugin Installation Record
数据库：
```ts
interface PluginInstallation {
id: string
pluginId: string
version: string
status: PluginStatus
source: PluginSource
enabled: boolean
installedAt: Date
updatedAt: Date
activatedAt?: Date
disabledAt?: Date
error?: string
metadata?: Record<string, unknown>
}
```
---
# 14. Plugin Source
支持：
```ts
type PluginSource =
| {
type: 'builtin'
}
| {
type: 'local'
path: string
}
| {
type: 'package'
package: string
version?: string
}
| {
type: 'git'
repository: string
ref?: string
}
| {
type: 'url'
url: string
}
```
第一阶段至少实现：
```text
builtin
local
package
```
Git / URL 可以作为后续扩展。
---
# 15. Built-in Plugin
DevOS 自己的功能也可以 Plugin 化。
例如：
```text
devos.core
devos.seo
devos.devops
```
但 Core Runtime 本身不能依赖 Plugin Runtime 才能启动。
即：
```text
Core Runtime
↓
Plugin Runtime
↓
Optional Plugins
```
而不是：
```text
Plugin Runtime
↓
Core Runtime
```
---
# 16. Plugin Registration
Plugin 激活后：
```text
Plugin
↓
Manifest
↓
Validate
↓
Register
├── Resources
├── Actions
├── Capabilities
├── Skills
├── MCP
├── Events
├── Workflows
└── UI
```
---
# 17. Plugin Registry
实现：
```ts
interface PluginRegistry {
register(plugin: RegisteredPlugin): Promise<void>
unregister(pluginId: string): Promise<void>
get(pluginId: string): RegisteredPlugin | undefined
list(): RegisteredPlugin[]
has(pluginId: string): boolean
}
```
---
# 18. Registered Plugin
```ts
interface RegisteredPlugin {
manifest: PluginManifest
status: PluginStatus
runtime: PluginRuntime
registeredAt: Date
}
```
---
# 19. Plugin Runtime
```ts
interface PluginRuntime {
initialize(context: PluginContext): Promise<void>
activate(context: PluginContext): Promise<void>
deactivate(context: PluginContext): Promise<void>
dispose(context: PluginContext): Promise<void>
health(): Promise<PluginHealth>
}
```
---
# 20. Plugin Context
```ts
interface PluginContext {
pluginId: string
version: string
logger: Logger
eventBus: EventBus
resourceRegistry: ResourceRegistry
actionRegistry: ActionRegistry
capabilityRegistry: CapabilityRegistry
skillRegistry: SkillRegistry
mcpRegistry: MCPRegistry
config: PluginConfigService
storage: PluginStorage
signal: AbortSignal
}
```
Plugin 不应该直接拿：
```text
PrismaClient
RedisClient
BullMQ
```
Plugin 应该使用 DevOS 提供的抽象。
---
# 21. Plugin Storage
某些 Plugin 需要自己的持久化数据。
提供：
```ts
interface PluginStorage {
get<T>(key: string): Promise<T | undefined>
set<T>(key: string, value: T): Promise<void>
delete(key: string): Promise<void>
}
```
但这是：
> Plugin Storage
不是：
> Plugin 自己拥有一套数据库系统。
---
# 22. Plugin Database
如果 Plugin 需要复杂业务数据：
必须通过 DevOS Database / ORM / Migration Runtime。
例如：
```text
packages/plugins/seo
migrations/
schema/
```
数据库表必须带 Plugin Namespace。
例如：
```text
seo_websites
seo_keywords
seo_articles
```
禁止 Plugin 私自建立第二个 PostgreSQL 实例。
---
# 23. Plugin Configuration
Plugin 可以声明 Settings。
例如：
```json
{
"settings": [
{
"key": "defaultModel",
"type": "string",
"required": true
},
{
"key": "apiEndpoint",
"type": "url"
}
]
}
```
---
# 24. Plugin Setting Schema
```ts
interface PluginSettingDeclaration {
key: string
type:
| 'string'
| 'number'
| 'boolean'
| 'secret'
| 'url'
| 'select'
| 'multiselect'
| 'json'
label: string
description?: string
required?: boolean
default?: unknown
options?: {
label: string
value: string
}[]
}
```
---
# 25. Plugin Settings Resource
Plugin 配置应该属于：
```text
core.plugin.settings
```
而不是：
```text
plugin_database_table
```
API：
```text
GET
/api/plugins/:pluginId/settings
PUT
/api/plugins/:pluginId/settings
```
但是最终执行：
```text
core.plugin.configure
```
---
# 26. Secret Settings
例如：
```text
OpenAI API Key
Cloudflare API Token
GitHub Token
SMTP Password
```
必须使用：
```text
type = secret
```
数据库不得明文保存。
推荐：
```text
Encryption at Rest
```
读取时默认：
```text
********
```
只有真正执行需要时才能在 Runtime 内解密。
---
# 27. Plugin Settings 权限
必须区分：
```text
plugin.view
plugin.configure
plugin.install
plugin.uninstall
plugin.enable
plugin.disable
```
普通用户：
```text
plugin.view
```
管理员：
```text
plugin.configure
```
系统管理员：
```text
plugin.install
plugin.uninstall
```
具体策略由 RBAC / Policy Runtime 控制。
---
# 28. Plugin UI
Plugin 可以提供自己的页面。
例如：
```text
SEO
├── Overview
├── Websites
├── Keywords
├── Articles
├── Tasks
└── Settings
```
Plugin UI 不是独立 SPA。
必须挂载到：
```text
DevOS UI Shell
```
---
# 29. Plugin UI Manifest
```ts
interface PluginUIDeclaration {
routes?: PluginRoute[]
navigation?: PluginNavigationItem[]
dashboards?: PluginDashboard[]
widgets?: PluginWidget[]
settingsPage?: boolean
}
```
---
# 30. Plugin Route
```ts
interface PluginRoute {
id: string
path: string
title: string
component: string
icon?: string
permissions?: string[]
}
```
例如：
```json
{
"id": "seo-websites",
"path": "/seo/websites",
"title": "Websites",
"component": "SeoWebsitesPage",
"permissions": [
"devos.seo.website.read"
]
}
```
---
# 31. Plugin Navigation
Plugin 可以向左侧导航注册：
```text
SEO
Overview
Websites
Keywords
Articles
Tasks
```
但不能直接修改 DevOS Shell。
必须：
```text
Plugin
↓
Navigation Registry
↓
UI Shell
```
---
# 32. Navigation Registry
```ts
interface NavigationRegistry {
register(item: NavigationItem): void
unregister(pluginId: string): void
list(context: NavigationContext): NavigationItem[]
}
```
必须根据：
```text
permission
organization
project
plugin enabled
```
动态过滤。
---
# 33. Plugin Dashboard
Plugin 可以提供 Dashboard：
```text
SEO Overview
Websites: 127
Keywords: 3,821
Articles: 1,240
Tasks Running: 17
Errors: 3
```
Dashboard 只负责：
```text
展示
查询
触发 Action
```
不能在 UI 内实现业务逻辑。
---
# 34. Plugin Widget
Plugin 可以注册：
```text
Dashboard Widget
Chat Widget
Task Widget
Resource Widget
Report Widget
```
例如：
```text
SEO Health Score
```
Widget 可以声明：
```ts
interface PluginWidget {
id: string
title: string
component: string
size: 'small' | 'medium' | 'large'
permissions?: string[]
}
```
---
# 35. Plugin Page 与 Action Runtime
页面：
```text
按钮：Scan Website
```
不能：
```ts
fetch('/seo/scan')
```
应该：
```text
UI
↓
Action Client
↓
devos.seo.website.scan
↓
Action Runtime
```
---
# 36. Plugin Resource UI
如果 Plugin 注册：
```text
seo.website
```
可以自动获得：
```text
List
Detail
Create
Edit
Delete
```
如果 Resource 声明：
```text
ui.list
ui.detail
```
DevOS Generic UI 可以自动生成。
Plugin 只需要实现复杂页面。
---
# 37. Plugin Actions
Plugin Action：
```ts
interface PluginActionDeclaration {
id: string
name: string
description?: string
inputSchema: unknown
outputSchema: unknown
mode: 'sync' | 'async' | 'stream'
permissions: string[]
requiresApproval?: boolean
}
```
Action 最终进入：
```text
Action Registry
```
---
# 38. Plugin Capability
Plugin Action 自动成为 Capability。
例如：
```text
devos.seo.website.scan
```
注册：
```text
Capability
type = action
source = plugin
```
Agent 就能够发现。
---
# 39. Plugin Skill
Plugin 可以注册 Skill：
```ts
interface PluginSkillDeclaration {
id: string
name: string
description: string
version: string
instructions: string
requiredCapabilities: string[]
inputSchema?: unknown
outputSchema?: unknown
}
```
---
# 40. Plugin 与 Agent
例如：
```text
SEO Plugin
↓
Skill:
seo.audit
↓
Capabilities:
seo.website.scan
seo.keyword.research
seo.article.generate
↓
Agent
```
Agent 不需要知道：
```text
这个能力来自哪个数据库
哪个 Controller
哪个 Plugin 文件
```
只看到：
```text
Capability
```
---
# 41. Plugin MCP
Plugin 可以声明 MCP：
```ts
interface PluginMCPDeclaration {
id: string
name: string
transport:
| 'stdio'
| 'http'
| 'sse'
endpoint?: string
command?: string
args?: string[]
}
```
但是：
**MCP 仍然必须通过 MCP Runtime + Action Runtime。**
---
# 42. Plugin Event
Plugin 可以声明 Event：
```text
devos.seo.website.scanned
devos.seo.article.generated
```
Event 进入：
```text
Event Registry
```
并可以被：
```text
Agent
Workflow
Notification
Webhook
Plugin
```
消费。
---
# 43. Plugin Event Handler
Plugin Handler：
```text
Event
↓
Plugin Handler
↓
Action Runtime
```
禁止：
```text
Event
↓
Plugin Handler
↓
直接 DB mutation
```
---
# 44. Plugin Workflow
Plugin 可以提供 Workflow：
```text
seo.full.audit
```
例如：
```text
scan website
↓
collect keywords
↓
analyze pages
↓
generate report
```
Workflow 由：
```text
Action
Task
Job
```
组成。
---
# 45. Plugin Scheduler
Plugin 可以注册 Schedule Definition。
例如：
```text
SEO daily scan
Every day at 03:00
```
最终还是：
```text
Scheduler
↓
Task
↓
Action
```
Plugin 不得自己运行：
```text
setInterval()
```
或：
```text
node-cron
```
来承担业务调度。
---
# 46. Plugin Worker
某些 Plugin 可能需要特殊 Worker。
例如：
```text
browser
ffmpeg
docker
ssh
```
Plugin 可以声明 Worker Capability：
```ts
interface PluginWorkerDeclaration {
id: string
queues: string[]
capabilities: string[]
concurrency?: number
}
```
最终由：
```text
Worker Runtime
```
管理。
---
# 47. Plugin Dependencies
例如：
```json
{
"dependencies": [
{
"id": "devos.browser",
"version": "^1.0.0"
}
]
}
```
安装时：
```text
Plugin A
↓
Dependency Resolver
↓
Plugin B
↓
Install
```
---
# 48. Dependency Version
必须支持：
```text
exact
range
```
例如：
```text
1.2.3
^1.2.0
>=1.0.0 <2.0.0
```
---
# 49. Dependency Graph
Plugin Runtime 必须检测：
```text
A → B
B → C
C → A
```
发现：
```text
circular dependency
```
直接拒绝安装。
---
# 50. Plugin API Version
Plugin 必须声明：
```text
apiVersion
```
例如：
```text
apiVersion = 1
```
DevOS Runtime 升级：
```text
API v1
API v2
```
可以兼容旧 Plugin。
---
# 51. Plugin Compatibility
安装之前必须执行：
```text
Manifest
↓
API Compatibility
↓
Dependency Compatibility
↓
Permission Validation
↓
Resource Conflict Check
↓
Action Conflict Check
↓
Install
```
---
# 52. Resource Conflict
例如：
Plugin A：
```text
seo.website
```
Plugin B：
```text
seo.website
```
必须拒绝：
```text
RESOURCE_NAMESPACE_CONFLICT
```
除非明确声明：
```text
override
```
第一阶段：
**禁止 Override。**
---
# 53. Action Conflict
同样：
```text
seo.website.scan
```
只能由一个 Plugin 注册。
---
# 54. Capability Conflict
Capability ID 也必须唯一。
---
# 55. Plugin Enable
Enable：
```text
core.plugin.enable
↓
Load Plugin
↓
Validate
↓
Register
↓
Activate
↓
Health Check
↓
enabled
```
如果失败：
```text
activation_failed
```
不得标记为 enabled。
---
# 56. Plugin Disable
Disable：
```text
core.plugin.disable
↓
Stop accepting new work
↓
Drain active work
↓
Deactivate
↓
Unregister runtime capabilities
↓
disabled
```
已经运行中的 Task：
```text
默认继续完成
```
除非 Plugin 声明：
```text
shutdownPolicy = cancel
```
---
# 57. Plugin Uninstall
不能直接删除。
必须：
```text
Disable
↓
Check Running Tasks
↓
Check Dependencies
↓
Check Data Policy
↓
Unregister
↓
Remove
```
---
# 58. Plugin Data Policy
Manifest 可以声明：
```ts
dataPolicy: {
preserveOnDisable: boolean
preserveOnUninstall: boolean
destructiveUninstall: boolean
}
```
默认：
```text
preserveOnUninstall = true
```
即：
**卸载 Plugin 默认不删除业务数据。**
---
# 59. Plugin Upgrade
升级流程：
```text
Current Plugin
↓
Read New Manifest
↓
Compatibility Check
↓
Dependency Check
↓
Migration Plan
↓
Backup / Safety Check
↓
Disable
↓
Migration
↓
Install New Version
↓
Register
↓
Activate
↓
Health Check
```
---
# 60. Migration
Plugin Migration：
```ts
interface PluginMigration {
from: string
to: string
up(): Promise<void>
down?(): Promise<void>
}
```
Migration 必须支持：
```text
version history
```
---
# 61. Upgrade Failure
升级失败必须：
```text
upgrade_failed
```
并尽可能：
```text
Rollback
```
但不要假设所有 Migration 都可以自动 Rollback。
因此：
```text
backup
+
forward migration
+
recovery procedure
```
必须存在。
---
# 62. Plugin Isolation
Plugin 必须受到：
```text
Permission
Namespace
Resource Scope
Action Scope
```
限制。
Plugin 不应该默认拥有：
```text
root filesystem
all environment variables
all secrets
all database tables
```
---
# 63. Plugin Permission Declaration
Manifest：
```json
{
"permissions": [
"network:http",
"storage:plugin",
"secret:seo-api",
"resource:seo.website"
]
}
```
Permission 必须经过用户/管理员批准。
---
# 64. Permission 分类
至少：
```text
resource
action
network
storage
secret
filesystem
process
worker
mcp
```
---
# 65. Network Permission
Plugin 不应该默认访问任意互联网地址。
推荐：
```text
network:http
network:https
```
未来可以限制：
```text
network:domain:api.example.com
```
---
# 66. Secret Permission
Plugin 请求：
```text
secret:openai
```
只能访问：
```text
OpenAI Credential
```
不能读取：
```text
Cloudflare Credential
GitHub Credential
```
---
# 67. Plugin Credential
统一使用：
```text
Credential Runtime
```
例如：
```text
core.credential
```
Plugin：
```text
Credential Request
↓
Permission
↓
Credential Runtime
↓
Secret
```
Plugin 不应该直接读取 `.env`。
---
# 68. Plugin Environment
Plugin 可以获得：
```ts
interface PluginEnvironment {
devosVersion: string
pluginId: string
pluginVersion: string
environment: 'development' | 'test' | 'production'
}
```
禁止直接依赖大量 DevOS 内部环境变量。
---
# 69. Plugin Logging
Plugin 必须使用：
```ts
context.logger
```
例如：
```ts
context.logger.info(
'SEO scan started',
{
websiteId
}
)
```
日志自动获得：
```text
pluginId
correlationId
executionId
taskId
```
---
# 70. Plugin Events
Plugin 必须使用：
```ts
context.eventBus.publish(...)
```
Event 自动补充：
```text
pluginId
```
---
# 71. Plugin Health
```ts
interface PluginHealth {
status:
| 'healthy'
| 'degraded'
| 'unhealthy'
message?: string
checks?: HealthCheck[]
}
```
例如：
```text
SEO Plugin
├── Database healthy
├── Search API healthy
├── Browser MCP degraded
└── AI Provider healthy
```
---
# 72. Plugin Health Event
自动产生：
```text
plugin.health.changed
plugin.health.failed
plugin.health.recovered
```
---
# 73. Plugin Observability
Plugin 的：
```text
Action
Task
Job
Execution
Event
Log
Audit
Trace
Metric
```
全部自动带：
```text
pluginId
```
这样可以统计：
```text
Plugin usage
Plugin errors
Plugin latency
Plugin cost
Plugin health
```
---
# 74. Plugin Metrics
自动生成：
```text
devos_plugin_action_total
devos_plugin_error_total
devos_plugin_execution_duration_ms
devos_plugin_task_total
devos_plugin_mcp_request_total
devos_plugin_cost_total
```
---
# 75. Plugin Audit
例如：
```text
plugin.installed
plugin.enabled
plugin.disabled
plugin.upgraded
plugin.uninstalled
plugin.configured
```
都必须产生 Audit。
例如：
```text
Admin Alice
↓
core.plugin.enable
↓
devos.seo
↓
SUCCESS
```
---
# 76. Plugin UI Permission
Plugin 页面不能因为已经加载就绕过权限。
例如：
```text
SEO Settings
```
必须：
```text
plugin.view
+
plugin.configure
```
---
# 77. Plugin Dynamic UI
前端需要：
```text
Plugin Manifest
↓
UI Registry
↓
Route Registry
↓
Navigation Registry
↓
Dynamic Module
```
---
# 78. Frontend Plugin Package
推荐：
```text
packages/plugins/seo/
├── manifest.ts
├── backend/
│ ├── index.ts
│ ├── resources/
│ ├── actions/
│ ├── skills/
│ ├── mcp/
│ └── migrations/
│
└── frontend/
├── index.ts
├── routes/
├── pages/
├── widgets/
└── components/
```
---
# 79. Plugin Frontend Contract
Plugin Frontend 不应该：
```text
import backend database
import Prisma
import Redis
```
只能使用：
```text
Action Client
Resource API
Query Client
UI SDK
```
---
# 80. Plugin UI SDK
DevOS 应提供：
```ts
interface DevOSPluginUI {
registerRoute(...)
registerNavigation(...)
registerWidget(...)
registerDashboard(...)
registerSettings(...)
}
```
---
# 81. Plugin Action Client
前端：
```ts
await devos.actions.execute(
'devos.seo.website.scan',
{
websiteId
}
)
```
而不是：
```ts
fetch('/api/seo/scan')
```
---
# 82. Plugin Resource Client
```ts
const websites =
await devos.resources.list(
'devos.seo.website'
)
```
---
# 83. Plugin Task UI
异步 Action 返回：
```ts
{
taskId: 'task_123'
}
```
前端自动进入：
```text
Task Detail
```
可以显示：
```text
Progress
Jobs
Logs
Events
Execution
Result
```
---
# 84. Plugin Chat Integration
Plugin 可以向 Agent Chat 注册：
```text
context action
```
例如用户打开：
```text
Website: example.com
```
Chat：
```text
Ask Agent about this website
```
Agent 自动获得：
```text
resource = devos.seo.website
resourceId = website_123
```
---
# 85. Plugin Context Provider
```ts
interface PluginContextProvider {
getContext(
resource: ResourceReference
): Promise<AgentContextData>
}
```
这样 Agent 可以理解：
```text
当前页面
当前 Resource
当前 Project
当前 Task
```
---
# 86. Plugin Report
Plugin 可以注册 Report：
```text
SEO Audit Report
Server Deployment Report
CRM Customer Report
```
Report 应该：
```text
Task
↓
Action
↓
Artifact
↓
Report
```
---
# 87. Plugin Artifact
Plugin 可以生成：
```text
PDF
CSV
JSON
HTML
Markdown
Image
Archive
```
统一进入：
```text
core.artifact
```
而不是 Plugin 自己管理下载系统。
---
# 88. Plugin API
Plugin 可以提供 API，但 API 只是入口。
例如：
```http
POST /api/plugins/seo/scan
```
内部：
```text
HTTP
↓
Action Resolver
↓
devos.seo.website.scan
↓
Action Runtime
```
不能：
```text
Controller
↓
Plugin Handler
↓
DB
```
---
# 89. Plugin Webhook
Plugin 可以声明：
```text
incoming webhook
```
例如：
```text
POST /api/plugins/github/webhook
```
流程：
```text
Webhook
↓
Verify
↓
Normalize
↓
Event
↓
Task / Action
```
---
# 90. Plugin Export / Import
Plugin 配置可以导出：
```json
{
"pluginId": "devos.seo",
"version": "1.2.0",
"settings": {
"defaultModel": "..."
}
}
```
Secret 不得导出明文。
---
# 91. Plugin Backup
升级 / 卸载前可以：
```text
Plugin Data
Plugin Settings
Plugin Metadata
```
生成：
```text
core.artifact
```
作为恢复点。
---
# 92. Plugin Marketplace
未来可以实现：
```text
Plugin Marketplace
```
但 Marketplace 不是 Runtime。
Runtime 只负责：
```text
Discover
Install
Verify
Load
Activate
Disable
Upgrade
Uninstall
```
Marketplace 负责：
```text
Search
Rating
Description
Version
Download
```
---
# 93. Plugin Signature
未来 Plugin 可以支持：
```text
package signature
```
安装流程：
```text
Download
↓
Verify Signature
↓
Verify Checksum
↓
Compatibility
↓
Install
```
第一阶段可以先实现：
```text
checksum
```
---
# 94. Plugin Trust Level
定义：
```ts
type PluginTrust =
| 'builtin'
| 'trusted'
| 'verified'
| 'community'
| 'untrusted'
```
不同 Trust Level 可以有不同权限。
---
# 95. Plugin Sandbox
第一阶段：
```text
Process-level isolation
```
高级版本：
```text
Container
Worker
Sandbox
```
但不应该一开始为了“安全”把所有 Plugin 都设计成复杂微服务。
优先保证：
```text
Permission
Credential Isolation
Namespace Isolation
Runtime Isolation
```
---
# 96. Plugin Crash Isolation
Plugin 激活失败：
```text
devos.seo
↓
activation_failed
```
不能导致：
```text
DevOS Core
```
整体无法启动。
启动策略：
```text
Core starts
↓
Load Plugins
↓
Plugin A success
Plugin B failed
Plugin C success
↓
DevOS remains available
```
---
# 97. Plugin Startup
启动：
```text
DevOS Boot
↓
Core Runtime
↓
Database
↓
Redis
↓
Event Runtime
↓
Task Runtime
↓
Action Runtime
↓
Plugin Runtime
↓
Load Plugins
↓
Health Checks
↓
Ready
```
---
# 98. Plugin Shutdown
关闭：
```text
Stop accepting new requests
↓
Scheduler pause
↓
Plugin workers drain
↓
Plugin tasks finish
↓
Deactivate plugins
↓
Close Event subscriptions
↓
Close connections
↓
Shutdown Core
```
---
# 99. Plugin Dependency Startup
如果：
```text
A → B
```
启动顺序：
```text
B
↓
A
```
关闭：
```text
A
↓
B
```
Dependency Resolver 必须负责排序。
---
# 100. Plugin Registry 与其他 Registry
最终：
```text
Plugin Registry
│
├── Resource Registry
├── Action Registry
├── Capability Registry
├── Skill Registry
├── MCP Registry
├── Event Registry
├── Navigation Registry
├── Widget Registry
└── Workflow Registry
```
Plugin 是：
> Registry 的扩展来源。
不是：
> Registry 的替代品。
---
# 101. Plugin 完整模型
最终：
```text
Plugin
│
├── Manifest
│
├── Resources
│
├── Actions
│
├── Capabilities
│
├── Skills
│
├── MCP
│
├── Workflows
│
├── Events
│
├── Scheduler
│
├── Workers
│
├── Settings
│
├── Credentials
│
├── UI
│ ├── Routes
│ ├── Navigation
│ ├── Dashboard
│ └── Widgets
│
└── Runtime
├── Lifecycle
├── Health
├── Logging
├── Metrics
└── Tracing
```
---
# 102. Plugin Runtime 与 DevOS 的最终关系
```text
DevOS
│
┌───────┴────────┐
│ │
Core Runtime Plugin Runtime
│
┌──────────────────────┼─────────────────────┐
↓ ↓ ↓
Plugin A Plugin B Plugin C
│ │ │
Resource Resource Resource
Action Action Action
Skill Skill Skill
MCP MCP MCP
UI UI UI
```
所有 Plugin 最终进入：
```text
DevOS Runtime
```
---
# 103. SEO Plugin 示例
SEO 不应该成为第二套系统。
应该：
```text
DevOS
│
└── Plugin: devos.seo
```
提供：
```text
Resources:
devos.seo.website
devos.seo.keyword
devos.seo.article
devos.seo.backlink
devos.seo.campaign
Actions:
devos.seo.website.scan
devos.seo.keyword.research
devos.seo.article.generate
devos.seo.backlink.find
devos.seo.campaign.run
Skills:
devos.seo.audit
devos.seo.content
devos.seo.link-building
MCP:
search
browser
cms
backlink providers
UI:
SEO Dashboard
Websites
Keywords
Content
Backlinks
Campaigns
Settings
```
---
# 104. Agent 使用 Plugin
用户：
> 给 example.com 做完整 SEO 审计。
Agent：
```text
Goal
↓
Capability Discovery
↓
devos.seo.audit Skill
↓
Capabilities
├── website.scan
├── keyword.research
├── page.analyze
└── report.generate
↓
Task
↓
Jobs
↓
Actions
↓
Execution
↓
Events
↓
Agent Observation
```
Agent 不需要直接知道：
```text
SEO Plugin 内部代码
```
---
# 105. Plugin 与独立 Backend
DevOS 必须支持两种模式。
## Mode A
```text
DevOS
↓
Plugin
↓
Domain
```
推荐用于：
```text
SEO
CRM
Content
Marketing
DevOps
```
---
## Mode B
```text
DevOS Minimal Core
↓
Fork
↓
Independent Application
```
例如：
```text
DevOS Starter
↓
Fork
↓
Custom Product
```
独立项目仍然可以保留：
```text
Identity
RBAC
Resource
Action
Task
Event
Audit
Observability
```
但删除不需要的 Plugin。
---
# 106. Plugin 不等于 Microservice
不要把：
```text
Plugin
```
自动理解成：
```text
Microservice
```
默认：
```text
Plugin = In-process Extension
```
只有明确需要：
```text
isolation
resource-heavy worker
different runtime
different deployment lifecycle
```
才使用：
```text
External Service
```
---
# 107. External Plugin
未来支持：
```text
DevOS
↓
External Plugin Adapter
↓
HTTP / gRPC / MCP
↓
External Service
```
但外部 Plugin 仍然暴露：
```text
Resource
Action
Capability
Skill
Event
UI
```
给 DevOS。
---
# 108. Plugin Adapter
```ts
interface PluginAdapter {
install(): Promise<void>
enable(): Promise<void>
disable(): Promise<void>
uninstall(): Promise<void>
health(): Promise<PluginHealth>
}
```
---
# 109. Plugin Runtime API
建议统一：
```ts
interface DevOSPlugin {
manifest: PluginManifest
initialize(context: PluginContext): Promise<void>
activate(context: PluginContext): Promise<void>
deactivate(context: PluginContext): Promise<void>
dispose(context: PluginContext): Promise<void>
}
```
---
# 110. Package Architecture
Zcode 必须实现：
```text
packages/
└── plugin/
├── types/
│ ├── manifest.ts
│ ├── lifecycle.ts
│ └── permission.ts
│
├── registry/
│ └── plugin-registry.ts
│
├── runtime/
│ ├── plugin-runtime.ts
│ ├── lifecycle.ts
│ ├── loader.ts
│ ├── activator.ts
│ └── disposer.ts
│
├── installer/
│ ├── installer.ts
│ ├── resolver.ts
│ ├── validator.ts
│ └── checksum.ts
│
├── configuration/
│ ├── config-service.ts
│ └── secret-service.ts
│
├── isolation/
│ ├── permissions.ts
│ └── credentials.ts
│
├── health/
│ └── health-service.ts
│
└── ui/
├── route-registry.ts
├── navigation-registry.ts
├── widget-registry.ts
└── dashboard-registry.ts
```
---
# 111. Backend Plugin Example
```text
plugins/
└── seo/
├── plugin.json
├── index.ts
│
├── resources/
│ ├── website.ts
│ ├── keyword.ts
│ └── article.ts
│
├── actions/
│ ├── scan.ts
│ ├── research.ts
│ └── generate.ts
│
├── skills/
│ ├── seo-audit.ts
│ └── content.ts
│
├── mcp/
│ └── browser.ts
│
├── events/
│ └── definitions.ts
│
├── workflows/
│ └── audit.ts
│
├── migrations/
│
└── frontend/
├── routes/
├── pages/
├── widgets/
└── index.ts
```
---
# 112. Plugin Test
每个 Plugin 必须提供：
```text
manifest test
lifecycle test
registration test
permission test
configuration test
action test
event test
health test
ui registration test
upgrade test
uninstall test
```
---
# 113. Acceptance Criteria
## Plugin Lifecycle
* [ ] Discover
* [ ] Install
* [ ] Configure
* [ ] Enable
* [ ] Disable
* [ ] Restart
* [ ] Upgrade
* [ ] Uninstall
* [ ] Health
## Registry
* [ ] Plugin Registry
* [ ] Resource registration
* [ ] Action registration
* [ ] Capability registration
* [ ] Skill registration
* [ ] MCP registration
* [ ] Event registration
* [ ] Workflow registration
* [ ] UI registration
## Security
* [ ] Permission declaration
* [ ] Permission approval
* [ ] Credential isolation
* [ ] Secret isolation
* [ ] Namespace isolation
* [ ] Network policy
* [ ] Sensitive data redaction
## UI
* [ ] Dynamic routes
* [ ] Navigation
* [ ] Settings page
* [ ] Dashboard
* [ ] Widgets
* [ ] Resource pages
* [ ] Action buttons
* [ ] Task integration
## Runtime
* [ ] Logger
* [ ] Metrics
* [ ] Trace
* [ ] Event
* [ ] Health
* [ ] Task
* [ ] Worker
* [ ] Scheduler
---
# 114. Integration Test
必须测试：
```text
Install Plugin
↓
Manifest Validation
↓
Register Resource
↓
Register Action
↓
Register Skill
↓
Register MCP
↓
Register Event
↓
Register UI
↓
Enable
↓
Health Check
```
最终：
```text
Plugin = healthy
```
---
# 115. Disable Test
```text
Plugin enabled
↓
Task running
↓
Disable
↓
Drain
↓
Deactivate
↓
Unregister
↓
Plugin disabled
```
验证：
```text
Existing Task
```
不会被无故破坏。
---
# 116. Permission Test
Plugin 尝试：
```text
read secret:github
```
但只有：
```text
secret:openai
```
必须：
```text
ACCESS_DENIED
```
---
# 117. Conflict Test
安装：
```text
Plugin A
resource = foo.bar
```
然后：
```text
Plugin B
resource = foo.bar
```
必须：
```text
RESOURCE_NAMESPACE_CONFLICT
```
---
# 118. Dependency Test
```text
Plugin A
↓
Plugin B
```
安装 A 时：
```text
B not installed
```
应该：
```text
Install B
↓
Install A
```
---
# 119. Failure Test
Plugin activation：
```text
throw Error
```
必须：
```text
Plugin = activation_failed
```
同时：
```text
DevOS = healthy
```
---
# 120. Final Golden Rules
```text
1. Plugin 是扩展，不是第二个 DevOS。
2. Plugin 必须通过 DevOS Runtime 执行业务。
3. Plugin 不创建第二套 Auth。
4. Plugin 不创建第二套 Task。
5. Plugin 不创建第二套 Queue。
6. Plugin 不创建第二套 EventBus。
7. Plugin 不绕过 Action Runtime。
8. Plugin 不绕过 Permission。
9. Plugin 不直接读取 Secret。
10. Plugin UI 不直接执行业务逻辑。
11. Plugin 的 Resource 必须注册到 Resource Registry。
12. Plugin 的 Action 必须注册到 Action Registry。
13. Plugin 的 Capability 必须注册到 Capability Registry。
14. Plugin 的 Skill 必须注册到 Skill Registry。
15. Plugin 的 MCP 必须注册到 MCP Runtime。
16. Plugin 的 Event 必须进入 Event Runtime。
17. Plugin 的 Task 必须进入 Task Runtime。
18. Plugin 的日志必须进入 DevOS Logging Runtime。
19. Plugin 的审计必须进入 DevOS Audit Runtime。
20. Plugin 必须可以独立启停。
21. Plugin 崩溃不能拖垮 DevOS Core。
22. Plugin 卸载默认不删除业务数据。
23. Plugin 升级必须进行兼容性检查。
24. Plugin 必须拥有唯一 Namespace。
25. Agent 看到的是 Capability，而不是 Plugin 内部实现。
26. MCP 是能力接入方式，不是第二套业务 Runtime。
27. SEO / DevOps / CRM 等领域都应该优先实现为 Plugin。
28. 真正需要独立 Backend 的项目，应从 DevOS Minimal Core Fork。
```
---
# 121. DevOS Plugin 最终模型
最终 DevOS 应该达到：
```text
DevOS
│
┌──────────────────┴──────────────────┐
│ │
Core Runtime Plugin Runtime
│ │
│ ┌────────────────┼────────────────┐
│ │ │ │
│ SEO Plugin DevOps Plugin CRM Plugin
│ │ │ │
│ Resource Resource Resource
│ Action Action Action
│ Skill Skill Skill
│ MCP MCP MCP
│ Workflow Workflow Workflow
│ Event Event Event
│ UI UI UI
│ │ │ │
└────────────────────┴────────────────┴────────────────┘
│
Capability Registry
│
Agent
│
Goal
```
DevOS 的真正扩展方式最终就是：
```text
Core
+
Plugin
+
Capability
+
Agent
```
而不是：
```text
Core
+
SEO Backend
+
SEO Queue
+
SEO Agent
+
SEO MCP
+
SEO EventBus
```
**这一点必须作为 Zcode 后续所有领域模块开发的架构约束。**
Reference in New Issue View Git Blame Copy Permalink