Files

T

phptits 851ccf1d7f v2 platform runtime (docs 22 Phase 2/4/7 + 17): Project/Environment + Config + Storage + Observability

- Project/Environment model with default environments (dev/staging/prod)
- Config Runtime: cascade resolution (platform→org→project→env), secrets via vault
- Storage Runtime: local provider, sha256 dedup, integrity check, file list/upload/delete
- Observability: execution query, per-action summary (success rate, avg, p95), health
- Realtime SSE: workspace event stream endpoint (GET /api/v1/v2/realtime/events)
- Phase 1 acceptance: core.health.check, core.user.create, core.user.list
- Actions: core.project.*, core.config.*, core.file.*, core.user.* (62 total)

2026-09-11 21:11:07 +00:00

53 KiB

Raw Blame History

DevOS Plugin SDK & Developer Platform

Version: 1.0
Status: Architecture Specification
Scope: DevOS Plugin SDK / CLI / Manifest / Developer Platform
Depends On: 01–31
Project: /home/dev/bun/devos

1. 文档目标

本文定义 DevOS Plugin Developer Platform。

前面的：

27_PLUGIN_RUNTIME_AND_MARKETPLACE.md

解决的是：

DevOS 如何运行、安装、升级、禁用、卸载和管理 Plugin。

本文进一步解决：

开发者如何真正开发一个 DevOS Plugin。

最终目标：

Developer
    ↓
Plugin SDK
    ↓
Plugin CLI
    ↓
Plugin Manifest
    ↓
Plugin Runtime Contract
    ↓
DevOS Runtime
    ↓
Resource / Action / Query / Event / Task / Provider
    ↓
UI / Skill / MCP

Plugin 开发者不应该理解 DevOS 内部所有基础设施。

开发者只需要理解：

Resource
Action
Query
Event
Provider
Task
Skill
MCP
UI
Configuration

其余能力由 DevOS Runtime 提供。

2. 核心定位

DevOS Plugin SDK 不是一个普通的 Node.js SDK。

它实际上是：

DevOS Extension Programming Model。

也就是说：

Plugin Runtime
    =
平台负责“怎么运行”

Plugin SDK
    =
开发者负责“提供什么能力”

Plugin CLI
    =
开发者负责“怎么开发”

Plugin Manifest
    =
Plugin 负责“声明什么”

Marketplace
    =
Plugin 负责“怎么分发”

四者关系：

             Plugin Developer
                    │
       ┌────────────┼────────────┐
       ↓            ↓            ↓
   Plugin SDK    Plugin CLI   Manifest
       │            │            │
       └────────────┼────────────┘
                    ↓
             Plugin Package
                    ↓
             Plugin Registry
                    ↓
             Plugin Runtime
                    ↓
             DevOS Runtime

3. 最重要的设计原则

DevOS Plugin 必须遵守：

Plugin 提供能力，DevOS 提供 Runtime。

因此 Plugin：

可以：

注册 Resource
注册 Action
注册 Query
注册 Event
注册 Provider
注册 Skill
注册 MCP Capability
注册 Notification Type
注册 UI
注册配置
注册 Migration

不能：

自己创建 Auth Runtime
自己创建 RBAC
自己创建 Action Runtime
自己创建 Queue
自己创建 Worker Runtime
自己创建 Event Bus
自己创建 Secret Runtime
自己创建 Storage Runtime
自己创建 Router Runtime
自己直接操作 PostgreSQL
自己直接操作 Redis
自己读取 Master Secret
自己绕过 Security Runtime

4. Developer Experience

DevOS Plugin 的标准开发流程：

devos plugin create

↓

devos plugin dev

↓

devos plugin validate

↓

devos plugin test

↓

devos plugin pack

↓

devos plugin sign

↓

devos plugin publish

↓

devos plugin install

完整生命周期：

Create
  ↓
Develop
  ↓
Run
  ↓
Validate
  ↓
Test
  ↓
Build
  ↓
Pack
  ↓
Sign
  ↓
Publish
  ↓
Install
  ↓
Enable
  ↓
Upgrade

5. SDK Package

推荐：

@devos/plugin-sdk

可以进一步拆分：

@devos/plugin-sdk
@devos/plugin-server
@devos/plugin-ui
@devos/plugin-testing
@devos/plugin-cli

但第一阶段不应该过度拆包。

推荐初始结构：

packages/
├── plugin-sdk/
├── plugin-cli/
├── plugin-manifest/
├── plugin-testing/
├── plugin-runtime/
├── plugin-registry/
├── plugin-marketplace/
├── plugin-certification/
└── plugin-sandbox/

6. Plugin SDK API

Plugin SDK 应该提供：

export interface PluginContext {
  manifest: PluginManifest;

  logger: Logger;

  config: ConfigClient;

  secrets: SecretClient;

  actions: ActionClient;

  resources: ResourceClient;

  queries: QueryClient;

  events: EventClient;

  tasks: TaskClient;

  storage: StorageClient;

  search: SearchClient;

  providers: ProviderClient;

  capabilities: CapabilityClient;

  notifications: NotificationClient;
}

开发者通过这些接口使用 DevOS。

例如：

const result = await ctx.actions.execute(
  "github.repository.sync",
  {
    repositoryId,
  }
);

而不是：

await prisma.githubRepository.update(...)

7. Plugin Context

PluginContext 必须携带完整 Runtime Context。

例如：

interface PluginContext {
  manifest: PluginManifest;

  security: SecurityContext;

  organization: OrganizationContext;

  project?: ProjectContext;

  environment?: EnvironmentContext;

  requestId: string;

  correlationId: string;

  pluginId: string;

  logger: Logger;

  config: ConfigClient;

  secrets: SecretClient;

  actions: ActionClient;

  resources: ResourceClient;

  queries: QueryClient;

  events: EventClient;

  tasks: TaskClient;

  storage: StorageClient;

  search: SearchClient;

  providers: ProviderClient;

  notifications: NotificationClient;

  capabilities: CapabilityClient;
}

Plugin 不应该自行构造 SecurityContext。

SecurityContext 由 DevOS Runtime 注入。

8. Plugin Manifest

Manifest 是 Plugin 的核心声明文件。

推荐：

devos.plugin.yaml

示例：

id: acme.github

name: GitHub Integration

description: GitHub integration for DevOS

version: 1.0.0

apiVersion: "1"

devos:
  minVersion: "1.0.0"
  maxVersion: "<2.0.0"

runtime:
  type: node
  nodeVersion: ">=20"

capabilities:
  - resources
  - actions
  - queries
  - events
  - providers
  - ui
  - skills
  - mcp

permissions:
  - github.repository.read
  - github.repository.write

scopes:
  - organization
  - project

entrypoints:
  server: dist/server.js
  ui: dist/ui.js

resources:
  - github.repository

actions:
  - github.repository.sync
  - github.repository.create

queries:
  - github.repository.search

providers:
  - github

events:
  - github.repository.updated

skills:
  - github.repository.management

mcp:
  - github.repository

dependencies: []

config:
  schema: config/schema.json

migrations:
  path: migrations/

9. Manifest 必须是声明式的

Plugin Runtime 不应该通过执行 Plugin 代码之后才知道 Plugin 提供什么。

因此：

Manifest
    ↓
Static Capability Discovery
    ↓
Compatibility
    ↓
Permission Review
    ↓
Dependency Resolution
    ↓
Install

而不是：

启动 Plugin
    ↓
执行代码
    ↓
看看 Plugin 想干什么

这样可以提高：

安全性
安装速度
Marketplace 审核能力
Capability Discovery
Agent 能力发现
权限审核
版本兼容性判断

10. Resource SDK

Plugin 可以注册 Resource。

例如：

plugin.resources.register({
  id: "github.repository",

  label: "GitHub Repository",

  fields: {
    id: {
      type: "string",
      readable: true,
    },

    name: {
      type: "string",
      readable: true,
      searchable: true,
    },

    url: {
      type: "url",
      readable: true,
    },
  },

  relations: {
    organization: {
      resource: "core.organization",
    },
  },
});

Resource Schema 应兼容：

Data Runtime
Query Runtime
Search Runtime
UI Resource Runtime
Permission Runtime
Action Runtime

因此 Plugin 不应该另外定义一套 Resource Model。

11. Resource Namespace

每个 Plugin 必须拥有自己的 namespace。

例如：

github.repository
github.organization
github.issue
github.pull_request

禁止：

user
project
settings

这种容易污染 Core Namespace 的 ID。

Plugin 必须遵守：

<pluginId>.<resource>

或者：

<vendor>.<domain>.<resource>

12. Action SDK

Action 是 Plugin 最重要的扩展能力。

例如：

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

  description: "Synchronize a GitHub repository",

  input: z.object({
    repositoryId: z.string(),
  }),

  output: z.object({
    synced: z.boolean(),
  }),

  mode: "async",

  permission: "github.repository.write",

  risk: "medium",

  handler: async (input, ctx) => {
    // Plugin logic
  },
});

注意：

handler 是能力实现。

Action Runtime 才是执行控制中心。

13. Action Handler 不拥有 Runtime

错误：

handler() {
  prisma.repository.update(...);

  redis.lpush(...);

  sendEmail(...);
}

正确：

handler(input, ctx) {
  const repo = await ctx.resources.get(
    "github.repository",
    input.repositoryId
  );

  const result = await githubProvider.sync(repo);

  return result;
}

更复杂的任务：

Action
 ↓
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action

Plugin 不创建自己的队列。

14. Action Metadata

每个 Action 至少应该定义：

interface PluginActionDefinition {
  id: string;

  description: string;

  input: Schema;

  output: Schema;

  mode: "sync" | "async" | "stream";

  permission: string;

  risk?: "low" | "medium" | "high" | "critical";

  idempotent?: boolean;

  timeout?: number;

  retry?: RetryPolicy;

  approval?: ApprovalPolicy;

  scopes?: ScopeDefinition[];
}

这样 Action 可以被：

UI
API
SDK
CLI
Workflow
Skill
Agent
MCP

统一调用。

15. Query SDK

Plugin 可以注册 Query。

例如：

plugin.queries.register({
  id: "github.repository.search",

  resource: "github.repository",

  input: SearchQuerySchema,

  handler: async (query, ctx) => {
    return ctx.queries.searchResource(
      "github.repository",
      query
    );
  },
});

Query 必须经过：

Authentication
 ↓
Authorization
 ↓
Scope
 ↓
Field Permission
 ↓
Query Validation
 ↓
Data Runtime

Plugin 不能通过 Query 绕过权限。

16. Event SDK

Plugin 可以注册 Event：

plugin.events.register({
  type: "github.repository.updated",

  version: "1",

  schema: RepositoryUpdatedSchema,
});

发布：

await ctx.events.publish({
  type: "github.repository.updated",
  version: "1",
  payload: {
    repositoryId,
  },
});

事件最终进入：

Event Runtime
 ↓
Event Store
 ↓
Event Bus
 ↓
Handlers
 ↓
Notification / Task / Agent / Webhook

Plugin 不拥有自己的 Event Bus。

17. Event Subscription

Plugin 可以订阅平台事件：

plugin.events.subscribe({
  event: "core.project.created",

  handler: async (event, ctx) => {
    // ...
  },
});

但订阅必须声明：

subscriptions:
  - event: core.project.created

并经过：

Permission
Scope
Compatibility
Security Policy

18. Provider SDK

大量 Plugin 的本质不是业务资源，而是：

External Provider Integration。

例如：

GitHub
Google
Slack
Cloudflare
AWS
OpenAI
SMTP
Telegram

Plugin 可以注册 Provider：

plugin.providers.register({
  id: "github",

  capabilities: [
    "repository.read",
    "repository.write",
    "issue.read",
  ],

  credentials: {
    type: "oauth2",
  },

  healthCheck: async ctx => {
    return true;
  },
});

19. Provider 不管理 Credential

错误：

process.env.GITHUB_TOKEN

正确：

const credential =
  await ctx.providers.getCredential("github");

Credential 最终由：

Credential Runtime
 ↓
Secret Runtime
 ↓
Provider Runtime

管理。

Plugin 永远不接触 Master Secret。

20. Provider Runtime Contract

Provider 应支持：

capabilities
health
timeout
retry
rate limit
circuit breaker
failover
cost
region
observability

Plugin 只实现 Provider Adapter。

例如：

const githubProvider = {
  async repositories.list() {},

  async repositories.get() {},

  async repositories.create() {},
};

Provider Runtime 负责：

Credential
Timeout
Retry
Rate Limit
Tracing
Metrics
Error Normalization

21. Storage SDK

Plugin 不允许：

fs.writeFile(...)

用于业务文件。

也不应该：

s3.putObject(...)

正确：

await ctx.storage.createFile(...);

或者：

await ctx.storage.createArtifact(...);

最终：

Plugin
 ↓
Storage Client
 ↓
Storage Runtime
 ↓
S3 / Local / Object Storage

22. Configuration SDK

Plugin 配置：

config:
  github.defaultOrganization:
    type: string

  github.syncInterval:
    type: duration

  github.enableIssues:
    type: boolean

Plugin 使用：

const interval =
  await ctx.config.get("github.syncInterval");

禁止：

process.env.GITHUB_INTERVAL

23. Secret SDK

Plugin 使用：

ctx.secrets.resolve(
  "github.default"
);

而不是：

database.secrets.find(...)

更不允许：

console.log(secret);

Secret Runtime 应自动防止：

日志泄漏
Trace 泄漏
Event 泄漏
Error 泄漏
Audit 泄漏

24. Task SDK

Plugin 可以创建 Task：

await ctx.tasks.create({
  type: "github.repository.sync",
  input: {
    repositoryId,
  },
});

然后：

Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action Runtime

Plugin 不允许：

new Worker(...)

或者：

new Queue(...)

创建第二套任务系统。

25. Skill SDK

Plugin 可以提供 Skill。

例如：

skills:
  - id: github.repository.management
    description: Manage GitHub repositories
    requiredCapabilities:
      - github.repository.search
      - github.repository.sync

Skill：

Skill
 ↓
Capability Discovery
 ↓
Action
 ↓
Action Runtime

Skill 不直接执行基础设施。

26. Skill 与 Plugin 的关系

Plugin：

提供能力。

Skill：

描述如何组合能力解决问题。

例如：

GitHub Plugin
 ├── repository.search
 ├── repository.sync
 ├── issue.create
 └── pull_request.list

GitHub Repository Management Skill
 ├── search repository
 ├── inspect status
 ├── sync
 └── report

这样 Agent 才能使用 Plugin。

27. MCP Extension

Plugin 可以提供 MCP Capability。

例如：

mcp:
  - github.repository

但是：

Plugin
 ↓
MCP Capability
 ↓
MCP Gateway
 ↓
Security
 ↓
Action Runtime

不能：

MCP
 ↓
Plugin
 ↓
直接数据库

MCP 是 Transport / Access Layer。

不是新的业务 Runtime。

28. MCP Tool Registration

示例：

plugin.mcp.register({
  name: "github_repository_search",

  description: "Search GitHub repositories",

  input: SearchRepositorySchema,

  action: "github.repository.search",
});

注意这里：

MCP Tool
      ↓
Action ID

而不是：

MCP Tool
      ↓
独立 Handler

这样可以确保 MCP 与 UI/API/Agent 使用相同业务执行逻辑。

29. UI SDK

Plugin UI 是 DevOS UI Shell 的扩展。

Plugin 可以贡献：

Page
Navigation
Widget
Resource View
Action View
Settings
Command
Search Provider
Dashboard

例如：

plugin.ui.registerPage({
  id: "github.repositories",

  path: "/plugins/github/repositories",

  component: RepositoryPage,
});

30. Plugin UI 禁止事项

Plugin UI 不允许创建：

Router
Layout
Auth
Permission
Global QueryClient
Global Store
Theme Runtime
Notification Runtime

禁止：

<BrowserRouter>

禁止：

new QueryClient()

禁止：

axios.post("/internal/database")

正确：

devos.actions.execute(...)

31. UI Extension Contract

Plugin UI 应该通过：

PluginUIContext

访问平台：

interface PluginUIContext {
  api: DevOSApiClient;

  actions: ActionClient;

  resources: ResourceClient;

  queries: QueryClient;

  tasks: TaskClient;

  notifications: NotificationClient;

  navigation: NavigationClient;

  settings: SettingsClient;
}

Manifest：

ui:
  navigation:
    - id: github
      label: GitHub
      icon: github
      children:
        - id: repositories
          label: Repositories

平台负责：

权限
路由
菜单
Visibility
Layout
Breadcrumb
Active state

Plugin 只提供声明。

33. Settings UI

Plugin 可以声明：

settings:
  - github

DevOS 自动生成：

Settings
 └── Plugins
      └── GitHub
           ├── General
           ├── Credentials
           ├── Sync
           └── Advanced

配置通过：

Config Runtime
Secret Runtime
Credential Runtime

管理。

34. Resource UI

Resource Schema 可以携带 UI Metadata：

{
  id: "github.repository",

  ui: {
    icon: "github",

    list: {
      columns: [
        "name",
        "url",
        "updatedAt",
      ],
    },

    detail: {
      sections: [
        "overview",
        "statistics",
        "activity",
      ],
    },
  },
}

最终：

Resource Schema
 ↓
Resource UI Runtime
 ↓
Table / Detail / Form

避免每个 Plugin 重复开发 CRUD UI。

35. Action UI

Action 可以声明：

ui: {
  label: "Sync Repository",

  confirm: true,

  form: {
    fields: [
      "repositoryId",
    ],
  },
}

UI Runtime 自动处理：

Button
 ↓
Form
 ↓
Validation
 ↓
Permission
 ↓
Action
 ↓
Task
 ↓
Realtime Progress

36. Plugin Testing SDK

推荐：

@devos/plugin-testing

提供：

createPluginTestContext()
createMockActionRuntime()
createMockEventRuntime()
createMockStorageRuntime()
createMockProvider()
createTestSecurityContext()

例如：

const ctx = createPluginTestContext({
  permissions: [
    "github.repository.read",
  ],
});

测试：

const result =
  await plugin.actions.execute(
    "github.repository.sync",
    {
      repositoryId: "repo_1",
    }
  );

37. Plugin Contract Tests

每个 Plugin 至少必须通过：

Manifest Validation
Capability Validation
Permission Validation
Action Contract
Resource Contract
Query Contract
Event Contract
Provider Contract
Config Contract
UI Contract
Security Contract
Migration Contract

38. Plugin Security Tests

必须测试：

权限绕过

No Permission
→ Action rejected

Scope 越权

Project A
→ Cannot access Project B

Secret 泄漏

Secret
→ no log
→ no event
→ no audit payload
→ no error payload

IDOR

Resource ID
→ scope check

SSRF

External URL
→ Network Policy

文件访问

File ID
→ Storage Authorization

39. Plugin Local Development

推荐：

devos plugin dev

执行：

Manifest Watch
Server Watch
UI HMR
Mock Runtime
Mock Providers
Test Database
Test Redis
Realtime
Logs

开发环境应该自动生成：

Development Organization
Development Project
Development Environment

40. Dev Mode

Plugin 开发模式：

Development
    ↓
Plugin Sandbox
    ↓
Mock/Local Runtime

不应该直接连接 Production。

尤其：

Production Secrets
Production Database
Production Storage
Production Provider

默认禁止。

41. Plugin CLI

推荐：

devos plugin create
devos plugin dev
devos plugin validate
devos plugin test
devos plugin build
devos plugin pack
devos plugin sign
devos plugin publish
devos plugin install
devos plugin enable
devos plugin disable
devos plugin upgrade
devos plugin doctor

42. Create

例如：

devos plugin create github

生成：

github/
├── devos.plugin.yaml
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── resources/
│   ├── actions/
│   ├── queries/
│   ├── events/
│   ├── providers/
│   ├── skills/
│   └── mcp/
├── ui/
│   ├── index.ts
│   ├── pages/
│   ├── widgets/
│   └── settings/
├── migrations/
├── tests/
└── README.md

43. Plugin Build

devos plugin build

执行：

TypeScript
 ↓
Server Build
 ↓
UI Build
 ↓
Manifest Validation
 ↓
Capability Extraction
 ↓
Dependency Check
 ↓
Artifact Generation

44. Plugin Package

最终生成：

github-1.0.0.devos-plugin

45. Checksum

Package 必须计算：

SHA-256

例如：

{
  "algorithm": "sha256",
  "value": "..."
}

安装时：

Download
 ↓
Checksum Verify
 ↓
Signature Verify
 ↓
Manifest Verify
 ↓
Compatibility Verify

46. Plugin Signing

推荐：

Ed25519

签名内容至少包括：

Package Hash
Plugin ID
Plugin Version
Manifest Hash
Signer ID
Timestamp

示例：

{
  "algorithm": "ed25519",
  "pluginId": "acme.github",
  "version": "1.0.0",
  "checksum": "...",
  "signer": "acme",
  "signature": "..."
}

47. Trust Level

Plugin Trust：

Official
Verified
Community
Private
Unverified

安装策略可以：

Production
→ Official / Verified

开发环境：

Development
→ Community / Private / Unverified

但必须显式允许。

48. Marketplace Metadata

Marketplace Plugin 至少需要：

id:
name:
description:
version:
author:
license:
homepage:
repository:
documentation:
screenshots:
permissions:
dependencies:
devosCompatibility:
changelog:
trustLevel:

Marketplace 不应该隐藏 Plugin 的权限。

用户安装前必须看到：

Plugin
Permissions
Scopes
Network Access
Storage Access
Secrets
Dependencies

49. Permission Diff

升级 Plugin 时：

Version 1
Permissions:
  github.repository.read

Version 2
Permissions:
  github.repository.read
  github.repository.write
  github.webhook.manage

DevOS 必须显示：

+ github.repository.write
+ github.webhook.manage

并根据安全策略：

自动批准

或：

要求管理员重新批准

50. Dependency Resolution

Plugin 可以依赖：

dependencies:
  - id: devos.github
    version: "^1.0.0"

  - id: devos.notification
    version: "^1.2.0"

Resolver 必须检查：

Version
Compatibility
Conflict
Permission
Capability
Dependency Cycle

禁止：

A → B
B → C
C → A

51. Plugin-to-Plugin Communication

Plugin 不应该：

import "../other-plugin/internal";

也不应该：

query otherPluginTable;

正确：

Plugin A
 ↓
Public Capability
 ↓
Capability Registry
 ↓
Plugin B

例如：

ctx.capabilities.execute(
  "github.repository.read",
  input
);

52. Public Contract

Plugin 可以暴露：

Public Resource
Public Action
Public Query
Public Event
Public Provider
Public Skill
Public MCP Capability

但这些必须是稳定 Contract。

内部实现：

private

不应该被其他 Plugin 依赖。

53. Version Compatibility

Plugin Manifest：

version: 2.3.0

apiVersion: "1"

devos:
  minVersion: "1.5.0"
  maxVersion: "<2.0.0"

同时需要：

Plugin Version
SDK Version
API Version
Capability Version
Resource Version
Action Version
Event Version
Skill Version
MCP Version

54. SemVer

Plugin：

MAJOR.MINOR.PATCH

规则：

PATCH
Bug Fix

MINOR
Backward Compatible Feature

MAJOR
Breaking Change

不能因为：

内部代码重构

就随意升级 Major。

55. Deprecated API

Plugin API 必须支持：

deprecated: {
  since: "1.5.0",
  removal: "2.0.0",
  replacement: "github.repository.sync"
}

Runtime 可以产生：

Plugin API Deprecated

而不是突然删除。

56. Migration

Plugin Migration：

Plugin Upgrade
 ↓
Compatibility
 ↓
Migration Plan
 ↓
Backup
 ↓
Drain
 ↓
Migration
 ↓
Install New Version
 ↓
Health Check
 ↓
Enable

Migration 必须通过：

Migration Runtime

不能自己：

ALTER TABLE

57. Plugin Data Ownership

Plugin 数据必须 namespace 化。

例如：

plugin_github_repository
plugin_github_account

或者统一 Resource Schema：

github.repository
github.account

但数据生命周期由 Plugin 声明。

卸载 Plugin 时：

Keep Data

默认优先。

不要：

uninstall
→ delete everything

58. Plugin Uninstall

卸载流程：

Check Dependencies
 ↓
Check Running Tasks
 ↓
Check Resources
 ↓
Check Data
 ↓
Disable
 ↓
Unregister Capabilities
 ↓
Remove Runtime

默认：

Keep Data

只有用户明确要求：

Delete Plugin Data

才执行删除。

59. Plugin Sandbox

建议支持：

Level 1
Trusted In-Process

Level 2
Restricted Runtime

Level 3
Isolated Process

Level 4
Container Sandbox

第一阶段：

Official Plugin
→ Trusted

第三方：

Community
→ Restricted / Isolated

高风险 Plugin：

Container

60. Plugin Network Policy

Plugin Manifest 可以声明：

network:
  outbound:
    - api.github.com
    - github.com

而不是默认：

0.0.0.0/0

Runtime 可以执行：

Allowlist
DNS Policy
HTTP Timeout
SSRF Protection
Rate Limit
Audit

61. Plugin Resource Limits

Plugin 可以受到：

CPU
Memory
Execution Time
Task Count
Concurrent Actions
Network
Storage
API Calls
Cost

限制。

例如：

limits:
  maxConcurrentActions: 10
  maxTasks: 100
  maxExecutionTime: 300s

62. Observability

所有 Plugin 日志必须包含：

pluginId
pluginVersion
requestId
correlationId
traceId
executionId
taskId
jobId
actor
organizationId
projectId
environmentId

例如：

{
  "pluginId": "acme.github",
  "pluginVersion": "1.2.0",
  "action": "github.repository.sync",
  "executionId": "...",
  "status": "completed"
}

63. Plugin Health

Plugin 可以提供：

plugin.health.register({
  check: async ctx => {
    return {
      status: "healthy",
    };
  },
});

Runtime 汇总：

Plugin Health
Provider Health
Action Health
Dependency Health
Migration Health
UI Health

64. Plugin Doctor

CLI：

devos plugin doctor github

检查：

Manifest
Compatibility
Dependencies
Permissions
Configuration
Credentials
Providers
Database
Migrations
Actions
Events
UI
Health
Security

最终：

✓ Manifest
✓ Compatibility
✓ Dependencies
✓ Credentials
✓ Provider
✓ Actions
✓ Events
✓ UI

Plugin is healthy.

65. Plugin Certification

建议：

Level 0
Basic

Level 1
Runtime Safe

Level 2
Secure

Level 3
Marketplace Verified

Level 4
Official

66. Basic

必须：

Manifest Valid
Package Valid
Installable
Enable/Disable

67. Runtime Safe

必须：

No direct DB
No direct Redis
No direct Queue
No direct Secret
No Runtime bypass
Action Contract
Task Contract

68. Secure

增加：

Permission Test
Scope Test
Secret Leak Test
SSRF Test
File Security
Network Policy
Sandbox
Audit

69. Marketplace Verified

增加：

Compatibility
Upgrade
Migration
Rollback
Performance
Documentation
License
Security Review

70. Official

Official Plugin 由 DevOS 官方维护。

可以获得：

Official Signature
Official Support
Highest Trust
Production Default

71. Documentation

Plugin SDK 必须支持自动生成文档：

Manifest
Resources
Actions
Queries
Events
Providers
Skills
MCP
Config
Permissions

例如：

GitHub Plugin
 ├── Resources
 ├── Actions
 ├── Queries
 ├── Events
 ├── Providers
 ├── Skills
 ├── MCP
 ├── Configuration
 └── Permissions

文档最好从：

TypeScript Types
Manifest
Schema
OpenAPI

自动生成。

72. Developer Portal

未来可以提供：

DevOS Developer Portal

包括：

Plugin Dashboard
Plugin Projects
Builds
Versions
Security
Permissions
Certification
Marketplace
Downloads
Analytics
Crash Reports

但 Developer Portal 本身仍然使用：

DevOS API

而不是建立第二套后端。

73. Plugin Analytics

Marketplace 可以统计：

Installations
Active Installations
Uninstalls
Version Distribution
Action Usage
Errors
Provider Errors
Task Failures
Performance

但必须注意：

Analytics ≠ Runtime

Analytics 使用：

Event
Observability
Usage Runtime

生成。

74. Plugin API

平台 API 可以提供：

GET    /v1/plugins
GET    /v1/plugins/:id
POST   /v1/plugins/:id/install
POST   /v1/plugins/:id/enable
POST   /v1/plugins/:id/disable
POST   /v1/plugins/:id/upgrade
DELETE /v1/plugins/:id
GET    /v1/plugins/:id/health
GET    /v1/plugins/:id/capabilities

这些 API 最终仍然进入：

Security
 ↓
Action Runtime
 ↓
Plugin Runtime

75. CLI 不是第二套业务逻辑

错误：

CLI
 ↓
Plugin Database

正确：

CLI
 ↓
SDK
 ↓
API
 ↓
Action Runtime

因此：

UI
CLI
API
Agent
MCP

最终都应该执行相同 Action。

76. Project Factory Integration

Plugin 必须成为 Project Factory 的 Capability Source。

例如：

capabilities:
  - github
  - notification
  - storage

Project Factory：

Requirement
 ↓
Capability Resolver
 ↓
Plugin Resolver
 ↓
Dependency Resolver
 ↓
Project Manifest

例如用户：

创建一个 GitHub 自动化 Agent。

可以自动选择：

GitHub Plugin
Agent Runtime
Task Runtime
Notification Runtime

77. Plugin Template

推荐官方提供：

plugin-basic
plugin-provider
plugin-resource
plugin-agent-tool
plugin-ui
plugin-mcp
plugin-notification

例如：

devos plugin create \
  --template provider \
  github

生成 Provider Plugin。

78. 推荐 Plugin Project Structure

my-plugin/
│
├── devos.plugin.yaml
├── package.json
├── tsconfig.json
│
├── src/
│   ├── index.ts
│   │
│   ├── resources/
│   ├── actions/
│   ├── queries/
│   ├── events/
│   ├── providers/
│   ├── skills/
│   ├── mcp/
│   └── notifications/
│
├── ui/
│   ├── index.ts
│   ├── pages/
│   ├── widgets/
│   ├── resources/
│   └── settings/
│
├── migrations/
│
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── contract/
│   ├── security/
│   └── e2e/
│
├── docs/
│
├── assets/
│
└── README.md

79. 推荐 packages

DevOS 内部：

packages/
├── plugin-sdk/
├── plugin-runtime/
├── plugin-manifest/
├── plugin-cli/
├── plugin-testing/
├── plugin-registry/
├── plugin-marketplace/
├── plugin-certification/
└── plugin-sandbox/

依赖关系：

plugin-cli
   ↓
plugin-sdk
   ↓
plugin-runtime
   ↓
DevOS Runtime

而不是：

plugin-runtime
 ↓
plugin-cli

Runtime 不依赖 CLI。

80. SDK Dependency Rule

Plugin SDK 应尽量保持轻量。

Plugin 开发者不应该被迫安装：

Prisma
Redis Client
BullMQ
Kafka Client
S3 SDK
SMTP SDK

除非 Plugin 本身是 Provider Adapter，并且该依赖已经被平台允许。

默认：

Plugin
 ↓
DevOS SDK

81. Forbidden Imports

架构 Lint 应禁止 Plugin：

@prisma/client
ioredis
bullmq
kafkajs
node:child_process
node:fs

是否绝对禁止 fs 要根据 Sandbox 层级决定。

默认业务 Plugin：

禁止直接使用

特殊 build/runtime 工具除外。

82. Forbidden Runtime Duplication

以下代码属于架构违规：

new Queue(...)
new Worker(...)
new Redis(...)
new WebSocketServer(...)
new PrismaClient(...)

Plugin 应使用：

ctx.tasks
ctx.events
ctx.storage
ctx.queries
ctx.actions
ctx.realtime

83. Plugin Security Boundary

最终边界：

Plugin Code
    ↓
Plugin SDK
    ↓
Plugin Context
    ↓
Security Context
    ↓
DevOS Runtime

Plugin 不能：

Plugin Code
    ↓
Database

也不能：

Plugin Code
    ↓
Master Secret

84. Agent 与 Plugin

Agent 不应该直接理解 Plugin 内部代码。

Agent 只看到：

Capability
Skill
Action
Resource

例如：

Agent
 ↓
Skill: github.repository.management
 ↓
Capabilities
 ↓
github.repository.search
github.repository.sync
github.issue.create

这样 Plugin 可以不断增加能力，而不需要修改 Agent Runtime。

85. MCP 与 Plugin

MCP 同样：

MCP
 ↓
Capability
 ↓
Action

Plugin 可以：

提供 MCP Capability

但：

MCP Runtime

仍然属于 DevOS Core。

86. Workflow 与 Plugin

Workflow 可以使用：

Plugin Action
Plugin Event
Plugin Resource
Plugin Query

例如：

GitHub Push Event
 ↓
Workflow
 ↓
Run Repository Scan
 ↓
Create Task
 ↓
Notification

整个链路不需要 Plugin 创建 Workflow Engine。

87. Notification 与 Plugin

Plugin 可以定义：

notifications:
  - github.sync.failed

但实际发送：

Plugin Event
 ↓
Notification Runtime
 ↓
Communication Runtime
 ↓
Provider

Plugin 不直接：

sendMail(...)

88. Storage 与 Plugin

Plugin 的大型输出：

Plugin
 ↓
Artifact Runtime
 ↓
Storage Runtime

例如：

GitHub Export
 ↓
Artifact
 ↓
Object Storage

Plugin 只保存：

artifactId

而不是：

blob

89. Plugin Configuration UI

配置 Schema：

const config = {
  github: {
    type: "object",

    fields: {
      defaultOrganization: {
        type: "string",
      },

      syncInterval: {
        type: "duration",
      },
    },
  },
};

UI Runtime 可以自动生成：

TextInput
Select
Switch
DurationInput
SecretInput
ProviderSelector

这样 Plugin 无需重复编写配置表单。

90. Plugin Lifecycle Hooks

允许：

plugin.lifecycle.onInstall(...)
plugin.lifecycle.onEnable(...)
plugin.lifecycle.onDisable(...)
plugin.lifecycle.onUpgrade(...)
plugin.lifecycle.onUninstall(...)

但生命周期 Hook 必须：

短
可重试
可恢复
幂等
可审计

禁止在：

onEnable

中执行几十分钟业务任务。

长任务必须：

Task

91. Plugin Startup

启动：

Load Manifest
 ↓
Verify
 ↓
Compatibility
 ↓
Create Context
 ↓
Register Capabilities
 ↓
Health Check
 ↓
Active

Plugin 不应该在 import 时执行业务操作。

禁止：

await database.sync();

出现在 module initialization 中。

92. Plugin Failure

如果 Plugin 启动失败：

Plugin
 ↓
failed

而不是：

整个 DevOS
 ↓
crash

Runtime 应支持：

Plugin Isolation
Plugin Quarantine
Plugin Restart
Plugin Disable

93. Quarantine

如果 Plugin 出现：

Repeated Crash
Security Violation
Excessive Resource Usage
Signature Failure
Unexpected Network Access

可以：

active
 ↓
quarantined

Quarantine：

停止执行
保留数据
保留日志
保留审计
等待管理员处理

94. Runtime Contract

所有 Plugin 都必须遵守：

Plugin
 ↓
SDK
 ↓
Runtime

Contract 测试必须验证：

No bypass
No direct infrastructure
Permission enforced
Scope enforced
Audit generated
Execution trace generated
Retry correct
Idempotency correct

95. Plugin Certification CI

Marketplace CI：

1. manifest validate
2. dependency audit
3. build
4. unit test
5. contract test
6. integration test
7. security test
8. migration test
9. install test
10. upgrade test
11. rollback test
12. package integrity
13. signature

任何关键阶段失败：

Publish Blocked

96. CI Architecture

推荐：

Pull Request
    ↓
Lint
    ↓
Type Check
    ↓
Unit Test
    ↓
Contract Test
    ↓
Security Test
    ↓
Integration Test
    ↓
Build
    ↓
Package
    ↓
Certification

97. Plugin SDK Version

开发者依赖：

{
  "dependencies": {
    "@devos/plugin-sdk": "^1.5.0"
  }
}

但发布 Package 时：

Plugin Manifest
 ↓
SDK Compatibility
 ↓
DevOS Compatibility

最终锁定实际兼容范围。

98. devos.lock

生产环境必须支持：

plugins:
  acme.github:
    version: 1.2.3
    checksum: sha256:...
    signature: ...

不要：

version: latest

这样才能实现：

Reproducible Deployment

99. Plugin Upgrade

标准升级：

Current Plugin
 ↓
Compatibility Check
 ↓
Dependency Check
 ↓
Permission Diff
 ↓
Migration Plan
 ↓
Backup
 ↓
Drain
 ↓
Upgrade
 ↓
Health Check
 ↓
Enable

失败：

Rollback

100. Backward Compatibility

Plugin API 必须优先：

Additive Change

例如增加：

github.repository.archive

而不是修改：

github.repository.sync

的输入语义。

Breaking Change：

github.repository.sync.v2

或者 Action Version：

version: 2

101. Plugin Event Compatibility

Event Schema 必须版本化：

github.repository.updated.v1
github.repository.updated.v2

消费者可以：

subscribe v1
subscribe v2

Event Runtime 负责兼容期。

102. Plugin Capability Discovery

Agent / UI / Workflow 不应该加载整个 Plugin。

例如：

Capability Summary
 ↓
Capability Schema
 ↓
Action Schema
 ↓
Execution

这和 Agent Runtime 的 Progressive Disclosure 保持一致。

103. Token Efficiency

Plugin 能力很多时：

错误：

把 300 个 Action 全部发送给 Agent

正确：

Goal
 ↓
Capability Search
 ↓
Top Relevant Capabilities
 ↓
Schema
 ↓
Execute

Plugin SDK 的 Manifest 应支持：

description
tags
category
keywords
capability metadata

方便 Capability Search。

104. Plugin Semantic Metadata

例如：

actions:
  - id: github.repository.sync
    description: Synchronize repository metadata
    category: repository
    tags:
      - github
      - repository
      - sync
      - metadata

Agent 可以进行：

Semantic Capability Search

而不是遍历所有 Plugin。

105. Plugin Documentation Contract

每个公开 Action 至少：

Description
Input
Output
Permission
Risk
Examples
Errors
Side Effects
Idempotency
Async Behavior

例如：

github.repository.sync

Description:
Synchronize repository metadata.

Permission:
github.repository.write

Risk:
medium

Mode:
async

Idempotent:
yes

106. Plugin Error Contract

Plugin 不应该返回：

throw new Error("something failed");

然后让 Runtime 猜。

应该使用：

throw new DevOSPluginError({
  code: "GITHUB_RATE_LIMIT",
  message: "GitHub API rate limit exceeded",
  retryable: true,
});

Runtime 再统一处理：

Retry
Audit
Metrics
User Message
Agent Observation

107. Plugin Observability Contract

Plugin Action：

Action
 ↓
Execution
 ↓
Trace
 ↓
Metrics
 ↓
Logs
 ↓
Audit

Plugin 不应该自行创建：

OpenTelemetry SDK
Prometheus Registry
ELK Client

平台已经提供：

ctx.logger
ctx.metrics
ctx.tracing

108. Plugin Cost Tracking

Provider Plugin 如果产生费用：

Provider
 ↓
Usage
 ↓
Cost
 ↓
Execution
 ↓
Task
 ↓
Organization

例如：

GitHub API calls
AI API tokens
SMS
Email
Cloud API

都可以归因到：

Plugin
Action
Execution
Organization
Project
Agent

109. Plugin Resource Quotas

例如：

limits:
  apiCallsPerMinute: 100
  maxConcurrentJobs: 5
  maxStorage: 10GB

Runtime 统一执行。

Plugin 不实现：

RateLimiter

110. Developer Experience 原则

Plugin 开发者应该感觉：

我只是在实现业务能力。

而不是：

我要实现：
Auth
RBAC
Queue
Redis
Events
Storage
Secrets
Observability

所以：

SDK 越简单
Runtime 越强
Plugin 越容易开发

111. 官方 Plugin 示例

DevOS 应提供至少：

plugin-example-basic
plugin-example-resource
plugin-example-provider
plugin-example-ui
plugin-example-mcp
plugin-example-skill
plugin-example-notification
plugin-example-agent-tool

这些 Example 同时作为：

Documentation
Regression Test
SDK Reference
Certification Fixture

112. 推荐第一批官方 Plugin

基础生态可以包括：

GitHub
GitLab
Slack
Discord
Cloudflare
AWS
Docker
SSH
SMTP
Google
Microsoft
Telegram
Webhook

但这些都应该是：

Plugin

而不是：

Core

113. Core 与 Plugin 的边界

Core：

Auth
Security
Data
Config
Secret
Task
Event
Storage
Search
Agent
Model
Notification
Communication
Observability
Plugin Runtime

Plugin：

GitHub
Cloudflare
AWS
Slack
SEO Provider
CRM
CMS
External APIs
Business Integrations

原则：

如果没有这个能力，DevOS 仍然应该是完整的平台，那么它通常应该是 Plugin。

114. SEO Plugin

特别注意：

SEO 不应该重新创建：

SEO Infrastructure Runtime
SEO Queue
SEO Event Bus
SEO Storage
SEO Credential

SEO Plugin 只提供：

seo.website
seo.keyword
seo.backlink
seo.content
seo.audit

以及：

SEO Actions
SEO Skills
SEO Providers
SEO MCP
SEO UI

全部使用 DevOS Runtime。

115. 一个完整 Plugin 示例

例如：

Cloudflare Plugin

提供：

Resources
  cloudflare.zone
  cloudflare.dns_record

Actions
  cloudflare.zone.scan
  cloudflare.dns.create
  cloudflare.dns.update

Queries
  cloudflare.zone.search

Providers
  cloudflare

Events
  cloudflare.dns.updated

Skills
  cloudflare.dns.management

MCP
  cloudflare.dns

UI
  Zones
  DNS
  Settings

但底层：

Auth
Security
Config
Secret
Task
Event
Storage
Search
Agent

全部来自 DevOS。

116. Plugin SDK API 最小集合

第一版 SDK 不要追求巨大。

MVP：

ctx.logger
ctx.config
ctx.secrets

ctx.actions
ctx.resources
ctx.queries
ctx.events

ctx.tasks
ctx.storage

ctx.providers
ctx.capabilities

第二阶段：

ctx.search
ctx.notifications
ctx.skills
ctx.mcp
ctx.ui

117. Implementation Phase

建议 Zcode 按以下顺序实现。

Phase 1

Plugin Manifest
Plugin SDK
Plugin Context
Plugin Loader

Phase 2

Resource
Action
Query
Event

Phase 3

Config
Secret
Provider
Task
Storage

Phase 4

UI Extension
Settings
Navigation

Phase 5

Skill
MCP
Capability Discovery

Phase 6

Testing SDK
Certification
Marketplace

Phase 7

Signing
Sandbox
Quarantine
Advanced Security

118. Zcode 实施顺序

Zcode 不允许一次实现整个 Plugin Ecosystem。

每一个 Vertical Slice：

Manifest
 ↓
SDK
 ↓
Runtime
 ↓
Test
 ↓
UI
 ↓
CLI

例如第一个 Slice：

Plugin
 ↓
registerResource()
 ↓
Resource Runtime
 ↓
Resource UI
 ↓
Contract Test

然后：

Action

再：

Provider

119. 第一 Vertical Slice

实现：

example.hello

Plugin 提供：

Resource:
example.message

Action:
example.message.create

Query:
example.message.list

UI：

Messages

CLI：

devos plugin dev

验证：

Plugin
 ↓
Resource
 ↓
Action
 ↓
Task
 ↓
UI

如果这条链路完整，才继续扩展。

120. Definition of Done

Plugin SDK 第一阶段完成必须满足：

[ ] Manifest 可解析
[ ] Plugin 可安装
[ ] Plugin 可启用
[ ] Plugin 可禁用
[ ] Plugin 可卸载
[ ] PluginContext 可注入
[ ] Resource 可注册
[ ] Action 可注册
[ ] Query 可注册
[ ] Event 可注册
[ ] Permission 生效
[ ] Scope 生效
[ ] Audit 生效
[ ] Execution 可追踪
[ ] Task 可运行
[ ] UI 可扩展
[ ] Plugin Test 可运行
[ ] Package 可生成
[ ] Upgrade 可运行
[ ] Migration 可运行

121. Architecture Contract Tests

必须存在：

plugin-manifest.contract.spec.ts
plugin-context.contract.spec.ts
plugin-resource.contract.spec.ts
plugin-action.contract.spec.ts
plugin-query.contract.spec.ts
plugin-event.contract.spec.ts
plugin-provider.contract.spec.ts
plugin-ui.contract.spec.ts
plugin-security.contract.spec.ts
plugin-upgrade.contract.spec.ts
plugin-migration.contract.spec.ts

122. Architecture Lint

必须检测：

Plugin → Prisma
Plugin → Redis
Plugin → Queue
Plugin → Worker
Plugin → Secret DB
Plugin → Master Secret
Plugin → Auth internals
Plugin → Permission internals
Plugin → private plugin internals

发现：

ERROR
Plugin Runtime Boundary Violation

123. Zcode 禁止事项

Zcode 实现本章时：

禁止 1

创建第二套 Queue。

禁止 2

创建第二套 Event Bus。

禁止 3

创建第二套 Auth。

禁止 4

创建第二套 Secret Manager。

禁止 5

创建第二套 Storage。

禁止 6

Plugin 直接访问 Prisma。

禁止 7

Plugin 直接访问 Redis。

禁止 8

Plugin UI 创建自己的 Router。

禁止 9

MCP 创建独立业务 Handler。

禁止 10

Agent 直接访问 Plugin Database。

124. Zcode Plugin Master Prompt

Zcode 实现 Plugin SDK 时必须遵守：

You are implementing the DevOS Plugin Developer Platform.

Plugin is an extension of DevOS, not a second DevOS.

The platform owns:
Security
Authorization
Scope
Action Runtime
Task Runtime
Queue
Worker
Event Runtime
Storage Runtime
Config Runtime
Secret Runtime
Provider Runtime
Observability
Audit
UI Shell
Agent Runtime
MCP Runtime

Plugin owns:
Resources
Actions
Queries
Events
Providers
Skills
MCP capabilities
UI contributions
Configuration declarations
Migrations

Every Plugin capability must enter the corresponding DevOS Runtime.

Never create duplicate infrastructure.

Never allow Plugin code to bypass:
Security
Authorization
Scope
Action Runtime
Task Runtime
Event Runtime
Storage Runtime
Secret Runtime

Never allow Plugin UI to create:
Router
Auth
Permission
Global Runtime

125. Plugin Implementation Checklist

Zcode 每次修改 Plugin Platform 前：

[ ] Read architecture docs 01–31
[ ] Read Plugin Runtime doc 27
[ ] Read Security doc 25
[ ] Read API doc 26
[ ] Read Task doc 09
[ ] Read Event doc 16
[ ] Read Config doc 18
[ ] Read UI doc 20
[ ] Read Agent doc 06
[ ] Read Memory doc 29
[ ] Read Model doc 30
[ ] Read Notification doc 31

然后：

[ ] Inspect existing implementation
[ ] Reuse existing Runtime
[ ] Identify duplicate infrastructure
[ ] Define bounded slice
[ ] Implement
[ ] Add contract tests
[ ] Add integration test
[ ] Run architecture lint
[ ] Run typecheck
[ ] Run build
[ ] Run E2E

126. Plugin Developer Contract

DevOS 对 Plugin Developer 的核心承诺：

Stable SDK
Stable Manifest
Stable Capability Contract
Stable Action Contract
Stable Resource Contract
Stable Event Contract
Stable Upgrade Path

Plugin Developer 不应该依赖：

DevOS internal database schema
DevOS internal Redis schema
DevOS internal queue implementation
DevOS internal React store
DevOS internal private classes

127. 为什么必须这样设计

如果 Plugin 直接依赖内部实现：

Plugin
 ↓
Prisma
 ↓
Database

那么：

DevOS Upgrade
 ↓
Database Change
 ↓
Plugin Broken

最终 Plugin Ecosystem 无法成长。

正确：

Plugin
 ↓
SDK Contract
 ↓
Runtime
 ↓
Implementation

Runtime 可以内部升级：

PostgreSQL
Redis
Queue
Storage
Provider
UI

而 Plugin 不需要跟着内部实现改变。

128. 最终 Developer Model

开发者最终应该只需要思考：

What Resource do I provide?

What Action do I provide?

What Query do I provide?

What Event do I provide?

What Provider do I provide?

What Skill do I provide?

What MCP capability do I provide?

What UI do I provide?

而不是：

How do I implement:
Auth?
Queue?
Redis?
Storage?
Secrets?
Tracing?
Audit?
RBAC?

这些全部由 DevOS 提供。

129. 最终架构

                    Developer
                       │
                       ↓
                Plugin SDK / CLI
                       │
              ┌────────┴────────┐
              ↓                 ↓
           Manifest          Source Code
              │                 │
              └────────┬────────┘
                       ↓
                 Plugin Package
                       │
             ┌─────────┴─────────┐
             ↓                   ↓
        Registry             Marketplace
             │
             ↓
        Plugin Runtime
             │
             ↓
        Plugin Context
             │
      ┌──────┼────────┬─────────┐
      ↓      ↓        ↓         ↓
 Resource  Action   Query     Event
      ↓      ↓        ↓         ↓
      └──────┴────────┴─────────┘
                       ↓
                  DevOS Runtime
                       │
 ┌──────────┬──────────┼──────────┬──────────┐
 ↓          ↓          ↓          ↓          ↓
Security   Task       Event      Storage   Config
 ↓          ↓          ↓          ↓          ↓
Provider   Worker     Bus        Artifact   Secret
                       │
                       ↓
               Agent / Workflow
                       │
                       ↓
                   UI / API

130. DevOS Plugin Ecosystem 最终模型

                   DEVOS
                     │
        ┌────────────┴────────────┐
        │                         │
   Core Runtime             Plugin Runtime
        │                         │
        │                 ┌───────┴────────┐
        │                 │                │
        │              SDK/CLI        Marketplace
        │                 │
        │                 ↓
        │              Plugin
        │                 │
        │      ┌──────────┼──────────┐
        │      ↓          ↓          ↓
        │   Resource    Action     Provider
        │      ↓          ↓          ↓
        └──────┴──────────┴──────────┘
                       │
                 Unified Runtime
                       │
      ┌────────────────┼─────────────────┐
      ↓                ↓                 ↓
    Agent            Workflow          UI/API

131. 最重要的三层抽象

DevOS Plugin Ecosystem 最终必须保持：

Plugin Runtime
=
平台如何运行 Plugin

Plugin SDK
=
开发者如何扩展 DevOS

Plugin Marketplace
=
Plugin 如何分发

不要混淆。

132. Golden Rules

Rule 1

Plugin 提供能力，DevOS 提供 Runtime。

Rule 2

SDK 是 Plugin Developer 的正式入口，内部实现不是 API。

Rule 3

Plugin 不创建第二套 DevOS。

Rule 4

Resource / Action / Query / Event 必须进入统一 Runtime。

Rule 5

Plugin UI 是 UI Shell Extension，不是第二个 Frontend Application。

Rule 6

Plugin 不直接访问 DB / Redis / Queue / Secret / Storage。

Rule 7

MCP 和 Skill 是 Plugin 可以提供的能力，但 Runtime 仍由 DevOS 管理。

Rule 8

Plugin 必须可安装、升级、禁用、卸载、回滚。

Rule 9

生产 Plugin 必须可验证、可追踪、可审计。

Rule 10

Plugin Contract 优先于 Plugin 内部实现。

133. 最终一句话

DevOS Plugin SDK 的目标不是让开发者“调用 DevOS”，而是让开发者能够以标准 Contract 把新的 Resource、Action、Provider、Skill、MCP 和 UI 能力插入 DevOS，而所有安全、权限、任务、事件、存储、配置、Secret、Observability 和执行控制继续由 DevOS Runtime 统一负责。

最终：

PLUGIN
  ↓
SDK
  ↓
CONTRACT
  ↓
DEVOS RUNTIME
  ↓
SECURITY
  ↓
EXECUTION
  ↓
EVENT / TASK / ARTIFACT
  ↓
AGENT / WORKFLOW / UI / API

这才是 DevOS 真正成为“可扩展开发平台”而不是“带插件功能的业务系统”的关键。

53 KiB Raw Blame History Unescape Escape

DevOS Plugin SDK & Developer Platform

1. 文档目标

2. 核心定位

3. 最重要的设计原则

4. Developer Experience

5. SDK Package

6. Plugin SDK API

7. Plugin Context

8. Plugin Manifest

9. Manifest 必须是声明式的

10. Resource SDK

11. Resource Namespace

12. Action SDK

13. Action Handler 不拥有 Runtime

14. Action Metadata

15. Query SDK

16. Event SDK

17. Event Subscription

18. Provider SDK

19. Provider 不管理 Credential

20. Provider Runtime Contract

21. Storage SDK

22. Configuration SDK

23. Secret SDK

24. Task SDK

25. Skill SDK

26. Skill 与 Plugin 的关系

27. MCP Extension

28. MCP Tool Registration

29. UI SDK

30. Plugin UI 禁止事项

31. UI Extension Contract

32. Navigation Contribution

33. Settings UI

34. Resource UI

35. Action UI

36. Plugin Testing SDK

37. Plugin Contract Tests

38. Plugin Security Tests

权限绕过

Scope 越权

Secret 泄漏

IDOR

SSRF

文件访问

39. Plugin Local Development

40. Dev Mode

41. Plugin CLI

42. Create

43. Plugin Build

44. Plugin Package

45. Checksum

46. Plugin Signing

47. Trust Level

48. Marketplace Metadata

49. Permission Diff

50. Dependency Resolution

51. Plugin-to-Plugin Communication

52. Public Contract

53. Version Compatibility

54. SemVer

55. Deprecated API

56. Migration

57. Plugin Data Ownership

58. Plugin Uninstall

59. Plugin Sandbox

60. Plugin Network Policy

61. Plugin Resource Limits

62. Observability

63. Plugin Health

64. Plugin Doctor

65. Plugin Certification

66. Basic

67. Runtime Safe

68. Secure

69. Marketplace Verified

70. Official

71. Documentation

72. Developer Portal

53 KiB

Raw Blame History