# 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。

最终目标：

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

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

开发者只需要理解：

```text
Resource
Action
Query
Event
Provider
Task
Skill
MCP
UI
Configuration
```

其余能力由 DevOS Runtime 提供。

---

# 2. 核心定位

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

它实际上是：

> DevOS Extension Programming Model。

也就是说：

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

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

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

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

Marketplace
    =
Plugin 负责“怎么分发”
```

四者关系：

```text
             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 的标准开发流程：

```bash
devos plugin create
```

↓

```bash
devos plugin dev
```

↓

```bash
devos plugin validate
```

↓

```bash
devos plugin test
```

↓

```bash
devos plugin pack
```

↓

```bash
devos plugin sign
```

↓

```bash
devos plugin publish
```

↓

```bash
devos plugin install
```

完整生命周期：

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

---

# 5. SDK Package

推荐：

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

可以进一步拆分：

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

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

推荐初始结构：

```text
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 应该提供：

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

例如：

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

而不是：

```ts
await prisma.githubRepository.update(...)
```

---

# 7. Plugin Context

PluginContext 必须携带完整 Runtime Context。

例如：

```ts
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 的核心声明文件。

推荐：

```text
devos.plugin.yaml
```

示例：

```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 提供什么。

因此：

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

而不是：

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

这样可以提高：

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

---

# 10. Resource SDK

Plugin 可以注册 Resource。

例如：

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

例如：

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

禁止：

```text
user
project
settings
```

这种容易污染 Core Namespace 的 ID。

Plugin 必须遵守：

```text
<pluginId>.<resource>
```

或者：

```text
<vendor>.<domain>.<resource>
```

---

# 12. Action SDK

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

例如：

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

错误：

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

  redis.lpush(...);

  sendEmail(...);
}
```

正确：

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

  const result = await githubProvider.sync(repo);

  return result;
}
```

更复杂的任务：

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

Plugin 不创建自己的队列。

---

# 14. Action Metadata

每个 Action 至少应该定义：

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

例如：

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

  resource: "github.repository",

  input: SearchQuerySchema,

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

Query 必须经过：

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

Plugin 不能通过 Query 绕过权限。

---

# 16. Event SDK

Plugin 可以注册 Event：

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

  version: "1",

  schema: RepositoryUpdatedSchema,
});
```

发布：

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

事件最终进入：

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

Plugin 不拥有自己的 Event Bus。

---

# 17. Event Subscription

Plugin 可以订阅平台事件：

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

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

但订阅必须声明：

```yaml
subscriptions:
  - event: core.project.created
```

并经过：

- Permission
- Scope
- Compatibility
- Security Policy

---

# 18. Provider SDK

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

> External Provider Integration。

例如：

```text
GitHub
Google
Slack
Cloudflare
AWS
OpenAI
SMTP
Telegram
```

Plugin 可以注册 Provider：

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

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

  credentials: {
    type: "oauth2",
  },

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

---

# 19. Provider 不管理 Credential

错误：

```ts
process.env.GITHUB_TOKEN
```

正确：

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

Credential 最终由：

```text
Credential Runtime
 ↓
Secret Runtime
 ↓
Provider Runtime
```

管理。

Plugin 永远不接触 Master Secret。

---

# 20. Provider Runtime Contract

Provider 应支持：

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

Plugin 只实现 Provider Adapter。

例如：

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

  async repositories.get() {},

  async repositories.create() {},
};
```

Provider Runtime 负责：

```text
Credential
Timeout
Retry
Rate Limit
Tracing
Metrics
Error Normalization
```

---

# 21. Storage SDK

Plugin 不允许：

```ts
fs.writeFile(...)
```

用于业务文件。

也不应该：

```ts
s3.putObject(...)
```

正确：

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

或者：

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

最终：

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

---

# 22. Configuration SDK

Plugin 配置：

```yaml
config:
  github.defaultOrganization:
    type: string

  github.syncInterval:
    type: duration

  github.enableIssues:
    type: boolean
```

Plugin 使用：

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

禁止：

```ts
process.env.GITHUB_INTERVAL
```

---

# 23. Secret SDK

Plugin 使用：

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

而不是：

```ts
database.secrets.find(...)
```

更不允许：

```ts
console.log(secret);
```

Secret Runtime 应自动防止：

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

---

# 24. Task SDK

Plugin 可以创建 Task：

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

然后：

```text
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action Runtime
```

Plugin 不允许：

```ts
new Worker(...)
```

或者：

```ts
new Queue(...)
```

创建第二套任务系统。

---

# 25. Skill SDK

Plugin 可以提供 Skill。

例如：

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

Skill：

```text
Skill
 ↓
Capability Discovery
 ↓
Action
 ↓
Action Runtime
```

Skill 不直接执行基础设施。

---

# 26. Skill 与 Plugin 的关系

Plugin：

> 提供能力。

Skill：

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

例如：

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

例如：

```yaml
mcp:
  - github.repository
```

但是：

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

不能：

```text
MCP
 ↓
Plugin
 ↓
直接数据库
```

MCP 是 Transport / Access Layer。

不是新的业务 Runtime。

---

# 28. MCP Tool Registration

示例：

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

  description: "Search GitHub repositories",

  input: SearchRepositorySchema,

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

注意这里：

```text
MCP Tool
      ↓
Action ID
```

而不是：

```text
MCP Tool
      ↓
独立 Handler
```

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

---

# 29. UI SDK

Plugin UI 是 DevOS UI Shell 的扩展。

Plugin 可以贡献：

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

例如：

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

  path: "/plugins/github/repositories",

  component: RepositoryPage,
});
```

---

# 30. Plugin UI 禁止事项

Plugin UI 不允许创建：

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

禁止：

```tsx
<BrowserRouter>
```

禁止：

```ts
new QueryClient()
```

禁止：

```ts
axios.post("/internal/database")
```

正确：

```ts
devos.actions.execute(...)
```

---

# 31. UI Extension Contract

Plugin UI 应该通过：

```ts
PluginUIContext
```

访问平台：

```ts
interface PluginUIContext {
  api: DevOSApiClient;

  actions: ActionClient;

  resources: ResourceClient;

  queries: QueryClient;

  tasks: TaskClient;

  notifications: NotificationClient;

  navigation: NavigationClient;

  settings: SettingsClient;
}
```

---

# 32. Navigation Contribution

Manifest：

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

平台负责：

- 权限
- 路由
- 菜单
- Visibility
- Layout
- Breadcrumb
- Active state

Plugin 只提供声明。

---

# 33. Settings UI

Plugin 可以声明：

```yaml
settings:
  - github
```

DevOS 自动生成：

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

配置通过：

```text
Config Runtime
Secret Runtime
Credential Runtime
```

管理。

---

# 34. Resource UI

Resource Schema 可以携带 UI Metadata：

```ts
{
  id: "github.repository",

  ui: {
    icon: "github",

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

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

最终：

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

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

---

# 35. Action UI

Action 可以声明：

```ts
ui: {
  label: "Sync Repository",

  confirm: true,

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

UI Runtime 自动处理：

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

---

# 36. Plugin Testing SDK

推荐：

```text
@devos/plugin-testing
```

提供：

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

例如：

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

测试：

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

---

# 37. Plugin Contract Tests

每个 Plugin 至少必须通过：

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

必须测试：

### 权限绕过

```text
No Permission
→ Action rejected
```

### Scope 越权

```text
Project A
→ Cannot access Project B
```

### Secret 泄漏

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

### IDOR

```text
Resource ID
→ scope check
```

### SSRF

```text
External URL
→ Network Policy
```

### 文件访问

```text
File ID
→ Storage Authorization
```

---

# 39. Plugin Local Development

推荐：

```bash
devos plugin dev
```

执行：

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

开发环境应该自动生成：

```text
Development Organization
Development Project
Development Environment
```

---

# 40. Dev Mode

Plugin 开发模式：

```text
Development
    ↓
Plugin Sandbox
    ↓
Mock/Local Runtime
```

不应该直接连接 Production。

尤其：

```text
Production Secrets
Production Database
Production Storage
Production Provider
```

默认禁止。

---

# 41. Plugin CLI

推荐：

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

例如：

```bash
devos plugin create github
```

生成：

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

```bash
devos plugin build
```

执行：

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

---

# 44. Plugin Package

最终生成：

```text
github-1.0.0.devos-plugin
```

推荐内容：

```text
github-1.0.0.devos-plugin
├── manifest.yaml
├── dist/
│   ├── server.js
│   └── ui.js
├── migrations/
├── assets/
├── docs/
├── LICENSE
├── README.md
├── checksum.json
└── signature.json
```

---

# 45. Checksum

Package 必须计算：

```text
SHA-256
```

例如：

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

安装时：

```text
Download
 ↓
Checksum Verify
 ↓
Signature Verify
 ↓
Manifest Verify
 ↓
Compatibility Verify
```

---

# 46. Plugin Signing

推荐：

```text
Ed25519
```

签名内容至少包括：

```text
Package Hash
Plugin ID
Plugin Version
Manifest Hash
Signer ID
Timestamp
```

示例：

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

---

# 47. Trust Level

Plugin Trust：

```text
Official
Verified
Community
Private
Unverified
```

安装策略可以：

```text
Production
→ Official / Verified
```

开发环境：

```text
Development
→ Community / Private / Unverified
```

但必须显式允许。

---

# 48. Marketplace Metadata

Marketplace Plugin 至少需要：

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

Marketplace 不应该隐藏 Plugin 的权限。

用户安装前必须看到：

```text
Plugin
Permissions
Scopes
Network Access
Storage Access
Secrets
Dependencies
```

---

# 49. Permission Diff

升级 Plugin 时：

```text
Version 1
Permissions:
  github.repository.read

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

DevOS 必须显示：

```text
+ github.repository.write
+ github.webhook.manage
```

并根据安全策略：

```text
自动批准
```

或：

```text
要求管理员重新批准
```

---

# 50. Dependency Resolution

Plugin 可以依赖：

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

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

Resolver 必须检查：

```text
Version
Compatibility
Conflict
Permission
Capability
Dependency Cycle
```

禁止：

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

---

# 51. Plugin-to-Plugin Communication

Plugin 不应该：

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

也不应该：

```ts
query otherPluginTable;
```

正确：

```text
Plugin A
 ↓
Public Capability
 ↓
Capability Registry
 ↓
Plugin B
```

例如：

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

---

# 52. Public Contract

Plugin 可以暴露：

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

但这些必须是稳定 Contract。

内部实现：

```text
private
```

不应该被其他 Plugin 依赖。

---

# 53. Version Compatibility

Plugin Manifest：

```yaml
version: 2.3.0

apiVersion: "1"

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

同时需要：

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

---

# 54. SemVer

Plugin：

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

规则：

```text
PATCH
Bug Fix

MINOR
Backward Compatible Feature

MAJOR
Breaking Change
```

不能因为：

```text
内部代码重构
```

就随意升级 Major。

---

# 55. Deprecated API

Plugin API 必须支持：

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

Runtime 可以产生：

```text
Plugin API Deprecated
```

而不是突然删除。

---

# 56. Migration

Plugin Migration：

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

Migration 必须通过：

```text
Migration Runtime
```

不能自己：

```ts
ALTER TABLE
```

---

# 57. Plugin Data Ownership

Plugin 数据必须 namespace 化。

例如：

```text
plugin_github_repository
plugin_github_account
```

或者统一 Resource Schema：

```text
github.repository
github.account
```

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

卸载 Plugin 时：

```text
Keep Data
```

默认优先。

不要：

```text
uninstall
→ delete everything
```

---

# 58. Plugin Uninstall

卸载流程：

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

默认：

```text
Keep Data
```

只有用户明确要求：

```text
Delete Plugin Data
```

才执行删除。

---

# 59. Plugin Sandbox

建议支持：

```text
Level 1
Trusted In-Process

Level 2
Restricted Runtime

Level 3
Isolated Process

Level 4
Container Sandbox
```

第一阶段：

```text
Official Plugin
→ Trusted
```

第三方：

```text
Community
→ Restricted / Isolated
```

高风险 Plugin：

```text
Container
```

---

# 60. Plugin Network Policy

Plugin Manifest 可以声明：

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

而不是默认：

```text
0.0.0.0/0
```

Runtime 可以执行：

```text
Allowlist
DNS Policy
HTTP Timeout
SSRF Protection
Rate Limit
Audit
```

---

# 61. Plugin Resource Limits

Plugin 可以受到：

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

限制。

例如：

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

---

# 62. Observability

所有 Plugin 日志必须包含：

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

例如：

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

---

# 63. Plugin Health

Plugin 可以提供：

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

Runtime 汇总：

```text
Plugin Health
Provider Health
Action Health
Dependency Health
Migration Health
UI Health
```

---

# 64. Plugin Doctor

CLI：

```bash
devos plugin doctor github
```

检查：

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

最终：

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

Plugin is healthy.
```

---

# 65. Plugin Certification

建议：

```text
Level 0
Basic

Level 1
Runtime Safe

Level 2
Secure

Level 3
Marketplace Verified

Level 4
Official
```

---

# 66. Basic

必须：

```text
Manifest Valid
Package Valid
Installable
Enable/Disable
```

---

# 67. Runtime Safe

必须：

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

---

# 68. Secure

增加：

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

---

# 69. Marketplace Verified

增加：

```text
Compatibility
Upgrade
Migration
Rollback
Performance
Documentation
License
Security Review
```

---

# 70. Official

Official Plugin 由 DevOS 官方维护。

可以获得：

```text
Official Signature
Official Support
Highest Trust
Production Default
```

---

# 71. Documentation

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

```text
Manifest
Resources
Actions
Queries
Events
Providers
Skills
MCP
Config
Permissions
```

例如：

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

文档最好从：

```text
TypeScript Types
Manifest
Schema
OpenAPI
```

自动生成。

---

# 72. Developer Portal

未来可以提供：

```text
DevOS Developer Portal
```

包括：

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

但 Developer Portal 本身仍然使用：

```text
DevOS API
```

而不是建立第二套后端。

---

# 73. Plugin Analytics

Marketplace 可以统计：

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

但必须注意：

```text
Analytics ≠ Runtime
```

Analytics 使用：

```text
Event
Observability
Usage Runtime
```

生成。

---

# 74. Plugin API

平台 API 可以提供：

```text
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 最终仍然进入：

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

---

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

错误：

```text
CLI
 ↓
Plugin Database
```

正确：

```text
CLI
 ↓
SDK
 ↓
API
 ↓
Action Runtime
```

因此：

```text
UI
CLI
API
Agent
MCP
```

最终都应该执行相同 Action。

---

# 76. Project Factory Integration

Plugin 必须成为 Project Factory 的 Capability Source。

例如：

```yaml
capabilities:
  - github
  - notification
  - storage
```

Project Factory：

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

例如用户：

> 创建一个 GitHub 自动化 Agent。

可以自动选择：

```text
GitHub Plugin
Agent Runtime
Task Runtime
Notification Runtime
```

---

# 77. Plugin Template

推荐官方提供：

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

例如：

```bash
devos plugin create \
  --template provider \
  github
```

生成 Provider Plugin。

---

# 78. 推荐 Plugin Project Structure

```text
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 内部：

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

依赖关系：

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

而不是：

```text
plugin-runtime
 ↓
plugin-cli
```

Runtime 不依赖 CLI。

---

# 80. SDK Dependency Rule

Plugin SDK 应尽量保持轻量。

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

```text
Prisma
Redis Client
BullMQ
Kafka Client
S3 SDK
SMTP SDK
```

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

默认：

```text
Plugin
 ↓
DevOS SDK
```

---

# 81. Forbidden Imports

架构 Lint 应禁止 Plugin：

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

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

默认业务 Plugin：

```text
禁止直接使用
```

特殊 build/runtime 工具除外。

---

# 82. Forbidden Runtime Duplication

以下代码属于架构违规：

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

Plugin 应使用：

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

---

# 83. Plugin Security Boundary

最终边界：

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

Plugin 不能：

```text
Plugin Code
    ↓
Database
```

也不能：

```text
Plugin Code
    ↓
Master Secret
```

---

# 84. Agent 与 Plugin

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

Agent 只看到：

```text
Capability
Skill
Action
Resource
```

例如：

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

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

---

# 85. MCP 与 Plugin

MCP 同样：

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

Plugin 可以：

```text
提供 MCP Capability
```

但：

```text
MCP Runtime
```

仍然属于 DevOS Core。

---

# 86. Workflow 与 Plugin

Workflow 可以使用：

```text
Plugin Action
Plugin Event
Plugin Resource
Plugin Query
```

例如：

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

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

---

# 87. Notification 与 Plugin

Plugin 可以定义：

```yaml
notifications:
  - github.sync.failed
```

但实际发送：

```text
Plugin Event
 ↓
Notification Runtime
 ↓
Communication Runtime
 ↓
Provider
```

Plugin 不直接：

```ts
sendMail(...)
```

---

# 88. Storage 与 Plugin

Plugin 的大型输出：

```text
Plugin
 ↓
Artifact Runtime
 ↓
Storage Runtime
```

例如：

```text
GitHub Export
 ↓
Artifact
 ↓
Object Storage
```

Plugin 只保存：

```text
artifactId
```

而不是：

```text
blob
```

---

# 89. Plugin Configuration UI

配置 Schema：

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

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

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

UI Runtime 可以自动生成：

```text
TextInput
Select
Switch
DurationInput
SecretInput
ProviderSelector
```

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

---

# 90. Plugin Lifecycle Hooks

允许：

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

但生命周期 Hook 必须：

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

禁止在：

```text
onEnable
```

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

长任务必须：

```text
Task
```

---

# 91. Plugin Startup

启动：

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

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

禁止：

```ts
await database.sync();
```

出现在 module initialization 中。

---

# 92. Plugin Failure

如果 Plugin 启动失败：

```text
Plugin
 ↓
failed
```

而不是：

```text
整个 DevOS
 ↓
crash
```

Runtime 应支持：

```text
Plugin Isolation
Plugin Quarantine
Plugin Restart
Plugin Disable
```

---

# 93. Quarantine

如果 Plugin 出现：

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

可以：

```text
active
 ↓
quarantined
```

Quarantine：

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

---

# 94. Runtime Contract

所有 Plugin 都必须遵守：

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

Contract 测试必须验证：

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

---

# 95. Plugin Certification CI

Marketplace CI：

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

任何关键阶段失败：

```text
Publish Blocked
```

---

# 96. CI Architecture

推荐：

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

---

# 97. Plugin SDK Version

开发者依赖：

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

但发布 Package 时：

```text
Plugin Manifest
 ↓
SDK Compatibility
 ↓
DevOS Compatibility
```

最终锁定实际兼容范围。

---

# 98. devos.lock

生产环境必须支持：

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

不要：

```yaml
version: latest
```

这样才能实现：

```text
Reproducible Deployment
```

---

# 99. Plugin Upgrade

标准升级：

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

失败：

```text
Rollback
```

---

# 100. Backward Compatibility

Plugin API 必须优先：

```text
Additive Change
```

例如增加：

```text
github.repository.archive
```

而不是修改：

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

的输入语义。

Breaking Change：

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

或者 Action Version：

```text
version: 2
```

---

# 101. Plugin Event Compatibility

Event Schema 必须版本化：

```text
github.repository.updated.v1
github.repository.updated.v2
```

消费者可以：

```text
subscribe v1
subscribe v2
```

Event Runtime 负责兼容期。

---

# 102. Plugin Capability Discovery

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

例如：

```text
Capability Summary
 ↓
Capability Schema
 ↓
Action Schema
 ↓
Execution
```

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

---

# 103. Token Efficiency

Plugin 能力很多时：

错误：

```text
把 300 个 Action 全部发送给 Agent
```

正确：

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

Plugin SDK 的 Manifest 应支持：

```text
description
tags
category
keywords
capability metadata
```

方便 Capability Search。

---

# 104. Plugin Semantic Metadata

例如：

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

Agent 可以进行：

```text
Semantic Capability Search
```

而不是遍历所有 Plugin。

---

# 105. Plugin Documentation Contract

每个公开 Action 至少：

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

例如：

```text
github.repository.sync

Description:
Synchronize repository metadata.

Permission:
github.repository.write

Risk:
medium

Mode:
async

Idempotent:
yes
```

---

# 106. Plugin Error Contract

Plugin 不应该返回：

```ts
throw new Error("something failed");
```

然后让 Runtime 猜。

应该使用：

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

Runtime 再统一处理：

```text
Retry
Audit
Metrics
User Message
Agent Observation
```

---

# 107. Plugin Observability Contract

Plugin Action：

```text
Action
 ↓
Execution
 ↓
Trace
 ↓
Metrics
 ↓
Logs
 ↓
Audit
```

Plugin 不应该自行创建：

```text
OpenTelemetry SDK
Prometheus Registry
ELK Client
```

平台已经提供：

```ts
ctx.logger
ctx.metrics
ctx.tracing
```

---

# 108. Plugin Cost Tracking

Provider Plugin 如果产生费用：

```text
Provider
 ↓
Usage
 ↓
Cost
 ↓
Execution
 ↓
Task
 ↓
Organization
```

例如：

```text
GitHub API calls
AI API tokens
SMS
Email
Cloud API
```

都可以归因到：

```text
Plugin
Action
Execution
Organization
Project
Agent
```

---

# 109. Plugin Resource Quotas

例如：

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

Runtime 统一执行。

Plugin 不实现：

```text
RateLimiter
```

---

# 110. Developer Experience 原则

Plugin 开发者应该感觉：

```text
我只是在实现业务能力。
```

而不是：

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

所以：

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

---

# 111. 官方 Plugin 示例

DevOS 应提供至少：

```text
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 同时作为：

```text
Documentation
Regression Test
SDK Reference
Certification Fixture
```

---

# 112. 推荐第一批官方 Plugin

基础生态可以包括：

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

但这些都应该是：

```text
Plugin
```

而不是：

```text
Core
```

---

# 113. Core 与 Plugin 的边界

Core：

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

Plugin：

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

原则：

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

---

# 114. SEO Plugin

特别注意：

SEO 不应该重新创建：

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

SEO Plugin 只提供：

```text
seo.website
seo.keyword
seo.backlink
seo.content
seo.audit
```

以及：

```text
SEO Actions
SEO Skills
SEO Providers
SEO MCP
SEO UI
```

全部使用 DevOS Runtime。

---

# 115. 一个完整 Plugin 示例

例如：

```text
Cloudflare Plugin
```

提供：

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

但底层：

```text
Auth
Security
Config
Secret
Task
Event
Storage
Search
Agent
```

全部来自 DevOS。

---

# 116. Plugin SDK API 最小集合

第一版 SDK 不要追求巨大。

MVP：

```ts
ctx.logger
ctx.config
ctx.secrets

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

ctx.tasks
ctx.storage

ctx.providers
ctx.capabilities
```

第二阶段：

```ts
ctx.search
ctx.notifications
ctx.skills
ctx.mcp
ctx.ui
```

---

# 117. Implementation Phase

建议 Zcode 按以下顺序实现。

## Phase 1

```text
Plugin Manifest
Plugin SDK
Plugin Context
Plugin Loader
```

## Phase 2

```text
Resource
Action
Query
Event
```

## Phase 3

```text
Config
Secret
Provider
Task
Storage
```

## Phase 4

```text
UI Extension
Settings
Navigation
```

## Phase 5

```text
Skill
MCP
Capability Discovery
```

## Phase 6

```text
Testing SDK
Certification
Marketplace
```

## Phase 7

```text
Signing
Sandbox
Quarantine
Advanced Security
```

---

# 118. Zcode 实施顺序

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

每一个 Vertical Slice：

```text
Manifest
 ↓
SDK
 ↓
Runtime
 ↓
Test
 ↓
UI
 ↓
CLI
```

例如第一个 Slice：

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

然后：

```text
Action
```

再：

```text
Provider
```

---

# 119. 第一 Vertical Slice

实现：

```text
example.hello
```

Plugin 提供：

```text
Resource:
example.message

Action:
example.message.create

Query:
example.message.list
```

UI：

```text
Messages
```

CLI：

```bash
devos plugin dev
```

验证：

```text
Plugin
 ↓
Resource
 ↓
Action
 ↓
Task
 ↓
UI
```

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

---

# 120. Definition of Done

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

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

必须存在：

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

必须检测：

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

发现：

```text
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 时必须遵守：

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

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

然后：

```text
[ ] 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 的核心承诺：

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

Plugin Developer 不应该依赖：

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

---

# 127. 为什么必须这样设计

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

```text
Plugin
 ↓
Prisma
 ↓
Database
```

那么：

```text
DevOS Upgrade
 ↓
Database Change
 ↓
Plugin Broken
```

最终 Plugin Ecosystem 无法成长。

正确：

```text
Plugin
 ↓
SDK Contract
 ↓
Runtime
 ↓
Implementation
```

Runtime 可以内部升级：

```text
PostgreSQL
Redis
Queue
Storage
Provider
UI
```

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

---

# 128. 最终 Developer Model

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

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

而不是：

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

这些全部由 DevOS 提供。

---

# 129. 最终架构

```text
                    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 最终模型

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

---

# 131. 最重要的三层抽象

DevOS Plugin Ecosystem 最终必须保持：

```text
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 统一负责。**

最终：

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

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