Files

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

45 KiB

Raw Blame History

`07_UI_SHELL_APP_MODULE.md`

DevOS Developer Work OS

UI Shell / App / Module / Plugin Runtime 设计规范

Version: 1.0

1. 文档目标

本文定义 DevOS 前端 UI 平台架构。

目标不是开发一个固定的 Admin Dashboard，而是建立一个：

可复用、可扩展、可插拔、可被 App/Plugin/MCP/Agent 动态扩展的前端 UI Shell。

DevOS 前端应该能够支持：

Core 页面
App 页面
Module 页面
Plugin 页面
Resource 页面
Action 页面
Settings 页面
Dashboard Widget
Statistics Widget
Chat Widget
Report Widget
Context Action
Command Palette
Global Search
Workspace
Agent UI

最终结构：

DevOS UI Shell
│
├── Core UI
│   ├── Layout
│   ├── Navigation
│   ├── Header
│   ├── Sidebar
│   ├── Workspace
│   ├── Command Palette
│   ├── Global Search
│   ├── Notifications
│   └── User Menu
│
├── App Runtime
│   ├── App Registry
│   ├── Module Registry
│   ├── Route Registry
│   ├── Navigation Registry
│   └── Widget Registry
│
├── Resource UI
│   ├── List
│   ├── Detail
│   ├── Create
│   ├── Edit
│   └── Actions
│
├── Plugin UI
│   ├── Pages
│   ├── Settings
│   ├── Dashboard
│   ├── Statistics
│   ├── Reports
│   ├── Chat
│   └── Context Actions
│
└── Agent UI
    ├── Goals
    ├── Runs
    ├── Tasks
    ├── Execution Trace
    └── Agent Chat

2. 核心原则

DevOS UI 必须遵循：

UI
 ↓
UI Action / Query
 ↓
API
 ↓
Action Runtime / Resource Runtime
 ↓
Backend

禁止：

UI
 ↓
直接操作数据库

禁止：

UI
 ↓
自己实现业务逻辑

禁止：

Plugin UI
 ↓
绕过 DevOS Runtime

前端负责：

展示
用户交互
表单
状态
路由
权限可见性
调用 API
展示执行结果

后端负责：

Authentication
Authorization
Business Logic
Action Runtime
Resource Runtime
Task
Job
Queue
Audit
Transaction

3. App / Module / Plugin 的区别

必须明确三者边界。

3.1 App

App 是一个完整的产品/业务应用。

例如：

DevOS
SEO App
DevOps App
CRM App
Content App

App 可以包含：

Pages
Resources
Actions
Skills
Plugins
Widgets
Settings
Agents

例如：

SEO App
├── Websites
├── Keywords
├── Content
├── Backlinks
├── Reports
└── SEO Agent

4. Module

Module 是 App 内部的功能模块。

例如：

SEO App
├── Website Module
├── Keyword Module
├── Content Module
├── Backlink Module
└── Report Module

Module 通常不应该成为独立安装包。

它主要解决：

如何组织大型 App。

5. Plugin

Plugin 是可独立安装/卸载/启用/禁用的扩展。

例如：

GitHub Plugin
Browser Plugin
Cloudflare Plugin
Google Search Console Plugin
OpenAI Plugin

Plugin 可以提供：

Resource
Action
Skill
MCP
Workflow
Page
Settings
Widget
Context Action

例如：

GitHub Plugin
├── Resource
│   ├── repository
│   ├── issue
│   └── pull_request
│
├── Action
│   ├── repository.clone
│   ├── repository.create
│   └── issue.create
│
├── Skill
│   └── github.code_review
│
├── MCP
│   └── github
│
└── UI
    ├── Repositories
    ├── Settings
    └── Statistics

6. UI Shell

DevOS Shell 是所有 App/Plugin 共用的 UI 基础。

7. App Registry

所有 App 都必须通过 Registry 注册。

export interface AppManifest {
  id: string;
  name: string;
  description?: string;

  version: string;

  icon?: string;

  route?: string;

  navigation?: NavigationItem[];

  modules?: ModuleManifest[];

  widgets?: WidgetManifest[];

  permissions?: string[];

  metadata?: Record<string, unknown>;
}

例如：

{
  id: "seo",
  name: "SEO",
  version: "1.0.0",
  route: "/seo"
}

8. Module Manifest

export interface ModuleManifest {
  id: string;

  appId: string;

  name: string;

  version: string;

  routes?: RouteDefinition[];

  navigation?: NavigationItem[];

  widgets?: WidgetManifest[];

  resources?: string[];

  permissions?: string[];
}

例如：

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

9. Plugin UI Manifest

Plugin UI 必须与 Plugin Manifest 统一。

export interface PluginUIManifest {
  pluginId: string;

  routes?: RouteDefinition[];

  navigation?: NavigationItem[];

  widgets?: WidgetManifest[];

  settings?: SettingsPageDefinition[];

  contextActions?: ContextActionDefinition[];
}

10. Route Registry

不要让每个 Plugin 自己修改 React Router。

统一：

Route Registry
      ↓
React Router

定义：

export interface RouteDefinition {
  id: string;

  path: string;

  title: string;

  component: string;

  icon?: string;

  permission?: string;

  children?: RouteDefinition[];

  metadata?: Record<string, unknown>;
}

例如：

{
  id: "github.repositories",
  path: "/plugins/github/repositories",
  title: "Repositories",
  component: "github.repositories"
}

11. Route Namespace

Plugin 路由必须隔离。

15. Resource UI

Resource Metadata 应该能够驱动通用 UI。

例如：

Resource:

seo.website

定义：

{
  id: "seo.website",

  fields: {
    name: {...},
    domain: {...},
    status: {...}
  },

  actions: [
    "seo.website.create",
    "seo.website.update",
    "seo.website.delete",
    "seo.website.scan"
  ]
}

UI 可以自动生成：

Website List
Website Detail
Create Website
Edit Website

16. Resource List

通用 Resource List：

┌─────────────────────────────────────────────┐
│ Websites                       + Create     │
├─────────────────────────────────────────────┤
│ Search                                      │
│                                             │
│ Domain        Status       Last Scan        │
│ example.com   Healthy      2 min ago        │
│ example.org   Warning      1 hour ago       │
│                                             │
└─────────────────────────────────────────────┘

表格定义可以来自：

ResourceMetadata

但允许业务页面覆盖默认 UI。

17. Resource Detail

/seo/websites/:id

Detail 页面：

Website
├── Overview
├── SEO
├── Keywords
├── Content
├── Backlinks
├── Tasks
├── Executions
└── Activity

其中：

Overview

可以是通用 Resource UI。

而：

SEO
Keywords
Backlinks

可以是 App 自定义页面。

18. Action UI

Action 不是简单的 Button。

Action Metadata：

export interface ActionUIConfig {
  actionId: string;

  label: string;

  icon?: string;

  confirm?: boolean;

  danger?: boolean;

  form?: FormSchema;

  resultView?: ResultViewDefinition;
}

例如：

Website Detail

[Scan Website]

点击：

seo.website.scan

进入：

Action Runtime

而不是：

POST /scan

再由 Controller 自己实现业务逻辑。

19. Action 状态

对于异步 Action：

pending
running
completed
failed
cancelled

UI 应该统一展示：

ActionExecution

例如：

Scan Website

Running...

████████████░░░░░░ 65%

Current:
Checking backlinks

20. Task UI

Action 如果创建 Task：

Action
 ↓
Task
 ↓
Job
 ↓
Execution

UI：

Task
├── Status
├── Progress
├── Jobs
├── Logs
├── Executions
└── Output

Agent、用户、Plugin 都应该使用同一 Task UI。

21. Agent UI

Agent 页面：

/agents

列表：

SEO Agent
DevOps Agent
General Agent
Content Agent

Agent Detail：

Agent
├── Overview
├── Goals
├── Runs
├── Skills
├── Capabilities
├── Policies
└── Settings

22. Agent Chat

Chat 只是 Agent 的一种 UI。

例如：

┌─────────────────────────────────────────────┐
│ SEO Agent                                   │
├─────────────────────────────────────────────┤
│                                             │
│ User:                                      │
│ 检查 example.com 的 SEO                     │
│                                             │
│ Agent:                                      │
│ 我发现该网站存在 12 个问题。                │
│                                             │
│ [View Report] [Create Tasks]                │
│                                             │
└─────────────────────────────────────────────┘

Chat 不应该直接执行业务。

流程：

Chat
 ↓
Agent Goal
 ↓
Agent Runtime
 ↓
Capability
 ↓
Action Runtime

Widget 是 DevOS UI 的重要扩展机制。

Plugin 可以提供：

Dashboard Widget
Statistics Widget
Report Widget
Chat Widget
Resource Widget
Agent Widget

定义：

export interface WidgetManifest {
  id: string;

  title: string;

  type:
    | "dashboard"
    | "statistics"
    | "report"
    | "chat"
    | "resource"
    | "agent";

  component: string;

  size?: "small" | "medium" | "large";

  permissions?: string[];

  dataSource?: string;

  metadata?: Record<string, unknown>;
}

24. Dashboard Extension

Dashboard 不应该写死。

例如：

Dashboard
├── System Health
├── Tasks
├── Agent Activity
│
├── SEO Traffic
├── SEO Issues
│
├── GitHub PRs
└── Cloudflare Traffic

其中：

SEO Traffic

来自 SEO App。

GitHub PRs

来自 GitHub Plugin。

Shell 提供 Extension Point：

dashboard.main
dashboard.sidebar

resource.detail.before
resource.detail.after

resource.list.toolbar
resource.detail.toolbar

agent.sidebar
agent.chat.toolbar

Plugin 可以：

WidgetRegistry.register({
  slot: "dashboard.main",
  widget: "github.pull_requests"
});

这样 Plugin 不需要修改 Core Dashboard。

26. Context Action

Context Action 是 Plugin 非常重要的 UI 能力。

例如：

用户查看：

Website: example.com

右上角：

More
├── Scan SEO
├── Open in Browser
├── Search Google
├── Create Content
└── Ask Agent

定义：

export interface ContextActionDefinition {
  id: string;

  label: string;

  icon?: string;

  resourceTypes?: string[];

  actionId: string;

  permission?: string;
}

例如：

{
  id: "browser.open_website",
  resourceTypes: ["seo.website"],
  actionId: "browser.open_url"
}

27. Resource Context Action

对于：

seo.website

Plugin 可以注册：

Open Browser
Run SEO Scan
Search Backlinks
Create Article
Ask SEO Agent

所有这些最终必须转换为：

Action

或者：

Agent Goal

28. Settings UI

Settings 必须支持：

Core Settings
App Settings
Plugin Settings
User Settings
Organization Settings
Project Settings

结构：

Settings
├── General
├── Account
├── Organization
├── Security
├── Agents
├── Models
├── Plugins
│   ├── GitHub
│   ├── Cloudflare
│   └── Browser
└── Developer

29. Plugin Settings

Plugin 自己可以定义 Settings Page：

export interface SettingsPageDefinition {
  id: string;

  pluginId: string;

  title: string;

  path: string;

  component: string;

  permissions?: string[];
}

例如：

/settings/plugins/github

页面：

GitHub

Connection
[ Connected ]

Default Organization
[ example ]

Webhook
[ Enabled ]

[ Save ]

保存：

UI
 ↓
Action
 ↓
Action Runtime

30. Settings 不应该直接调用 Plugin API

禁止：

fetch("https://api.github.com/...")

在 React Component 中直接执行。

应该：

GitHub Settings UI
 ↓
github.connection.update
 ↓
Action Runtime
 ↓
GitHub Plugin

这样才能统一：

Permission
Audit
Validation
Retry
Error
Secret
Logging

31. Secret UI

Plugin 可能需要：

API Key
Token
OAuth
Secret

UI 只能操作：

Secret Reference

不要让普通 UI State 长期保存明文 Secret。

例如：

{
  credentialId: "cred_xxx"
}

后端负责：

Credential Store

32. Global Search

DevOS 应提供统一搜索。

搜索范围：

Resources
Tasks
Agents
Plugins
Actions
Users
Projects
Documentation

例如：

Search: example.com

结果：

Websites
  example.com

Tasks
  SEO Scan example.com

Reports
  SEO Audit example.com

Agent Runs
  SEO Agent / example.com

33. Search Provider

不要让 Search UI 知道具体数据库。

统一：

export interface SearchProvider {
  search(
    query: SearchQuery
  ): Promise<SearchResult[]>;
}

Backend 根据：

Resource Registry
Plugin Registry
Search Index

返回结果。

34. Command Palette

DevOS 应提供：

Cmd/Ctrl + K

Command Palette。

例如：

> scan example.com

Actions
  Scan Website

Pages
  Website

Agents
  Ask SEO Agent

Command Palette 可以搜索：

Navigation
Resources
Actions
Commands
Agents

35. Command Registry

export interface CommandDefinition {
  id: string;

  title: string;

  description?: string;

  keywords?: string[];

  actionId?: string;

  route?: string;

  permission?: string;
}

Plugin 可以注册 Command。

例如：

GitHub:
  Create Repository
  Open Pull Requests

Breadcrumb 不应该硬编码。

由 Route / Resource Context 自动生成。

例如：

SEO
/
Websites
/
example.com

如果进入：

SEO
/
Websites
/
example.com
/
Scan

Action 页面可以显示：

SEO / Websites / example.com / Scan

37. Workspace

DevOS 应支持 Workspace 概念。

Workspace 可以理解为：

用户当前工作的上下文空间。

例如：

Workspace
├── Project
├── Organization
├── Environment
└── Active Resources

Header：

[ Organization ▼ ]
[ Project ▼ ]

切换 Workspace 后：

Navigation
Data
Permissions
Agents
Tasks

都应该根据 Workspace Context 更新。

38. Workspace Context

前端：

interface WorkspaceContext {
  organizationId?: string;

  projectId?: string;

  environmentId?: string;
}

所有 API Query 都应该带：

organizationId
projectId

但是：

前端传入的 Workspace Context 不能作为安全依据。

Backend 必须重新验证：

Actor
+
Organization
+
Project
+
Resource Scope

39. React Query

Server State 统一使用：

TanStack Query

例如：

useQuery({
  queryKey: [
    "resource",
    "seo.website",
    websiteId
  ],
  queryFn: ...
});

禁止使用 Zustand 保存大量 Server State。

40. Zustand

Zustand 用于：

UI State
Session UI
Sidebar State
Workspace UI
Command Palette
Modal
Theme
Preferences

不要：

Zustand
 ↓
保存整个后端数据库

41. Form

通用 Resource Form 可以根据 Schema 自动生成。

例如：

{
  fields: {
    name: {
      type: "string",
      required: true
    },

    domain: {
      type: "url",
      required: true
    }
  }
}

生成：

Name
[________________]

Domain
[________________]

[ Save ]

但复杂业务表单允许完全自定义 React Component。

42. Dynamic UI 与 Custom UI

DevOS 不应该追求：

所有页面都自动生成。

正确原则：

简单 CRUD
    ↓
Schema-driven UI

复杂业务
    ↓
Custom React UI

例如：

User CRUD
→ Dynamic UI

SEO Website
→ Custom UI + Resource metadata

Agent Workspace
→ Custom UI

DevOps Terminal
→ Custom UI

43. UI Registry

统一 UI Registry：

AppRegistry
ModuleRegistry
PluginRegistry
RouteRegistry
NavigationRegistry
WidgetRegistry
CommandRegistry
ContextActionRegistry

建议：

export interface UIRegistry {
  apps: AppRegistry;

  modules: ModuleRegistry;

  routes: RouteRegistry;

  navigation: NavigationRegistry;

  widgets: WidgetRegistry;

  commands: CommandRegistry;

  contextActions: ContextActionRegistry;
}

44. Registry 生命周期

系统启动：

Load Core
 ↓
Load Apps
 ↓
Load Modules
 ↓
Load Plugins
 ↓
Register Routes
 ↓
Register Navigation
 ↓
Register Widgets
 ↓
Register Commands
 ↓
Register Context Actions
 ↓
Render Shell

Plugin 动态启用：

Plugin Enable
 ↓
Load Manifest
 ↓
Register UI
 ↓
Invalidate Registry
 ↓
Shell Update

Plugin 禁用：

Plugin Disable
 ↓
Unregister UI
 ↓
Invalidate Registry
 ↓
Routes disappear
 ↓
Navigation disappears
 ↓
Widgets disappear

45. Lazy Loading

Plugin 页面必须支持 Lazy Loading。

不要：

App Startup
 ↓
加载所有 Plugin UI

应该：

Shell
 ↓
Load Manifest
 ↓
User opens Plugin page
 ↓
Lazy Load Component

例如：

const GitHubRepositories =
  lazy(() =>
    import("@devos/plugin-github/ui/repositories")
  );

46. Plugin UI Isolation

Plugin UI 必须：

使用自己的 namespace
不能覆盖 Core Route
不能随意修改全局 State
不能直接访问数据库
不能绕过 Permission
不能绕过 Action Runtime

Plugin 可以通过：

Registry
Extension Point
Action
Resource
Event

与 Core 集成。

47. Error Boundary

每个 App/Plugin UI 都必须有 Error Boundary。

例如：

Shell
├── Core Error Boundary
│
├── SEO Error Boundary
│
├── GitHub Plugin Error Boundary
│
└── Browser Plugin Error Boundary

如果 GitHub Plugin 崩溃：

GitHub Plugin failed

不能导致：

整个 DevOS 白屏

48. Permission Guard

前端：

<PermissionGuard
  permission="seo.website.scan"
>
  <Button>
    Scan
  </Button>
</PermissionGuard>

作用：

UI visibility

不是：

Security

Backend 必须再次验证。

49. Feature Flag

UI 支持 Feature Flag：

feature("new_agent_ui")

可以控制：

App
Module
Plugin
Widget
Route

例如：

agent.workspace.v2

50. UI Extension API

建议提供：

ui.registerRoute(...)

ui.registerNavigation(...)

ui.registerWidget(...)

ui.registerCommand(...)

ui.registerContextAction(...)

ui.registerSettings(...)

ui.registerSlotExtension(...)

Plugin 开发者不需要修改：

Core UI source

51. 示例：GitHub Plugin

安装：

GitHub Plugin

Plugin Runtime 注册：

Resources:
github.repository
github.issue
github.pull_request

Actions:
github.repository.create
github.repository.clone
github.issue.create
github.pull_request.merge

Skills:
github.code_review

MCP:
github

UI:
Repositories
Issues
Pull Requests
Settings
Statistics

UI 自动出现：

Plugins
└── GitHub
    ├── Repositories
    ├── Issues
    ├── Pull Requests
    ├── Statistics
    └── Settings

同时 Dashboard：

GitHub PR Widget

Command Palette：

Create GitHub Repository

Context Action：

Resource: github.repository

Open
Clone
Create Issue
Ask Agent

52. 示例：Browser Plugin

Browser Plugin：

Resource:
browser.session

Actions:
browser.open
browser.navigate
browser.screenshot

MCP:
browser

Skill:
browser.research

UI:
Browser Sessions
Browser Console
Browser Settings

SEO Website 页面：

example.com

Context Actions：

Open Browser
Screenshot
Run SEO Audit
Ask Agent

其中：

Open Browser
 ↓
browser.open
 ↓
Action Runtime

53. 示例：SEO App

SEO App 不应该重新实现：

Layout
Navigation
Task UI
Agent UI
Settings
Notification
Permission
Search
Command Palette

这些全部由 DevOS Core 提供。

SEO App 只提供：

Resources
Actions
Skills
Agents
Pages
Widgets
Reports

例如：

SEO
├── Overview
├── Websites
├── Keywords
├── Content
├── Backlinks
├── Reports
└── Agent

54. App Fork 模式

DevOS 必须支持：

DevOS Core
 ↓
Starter App

开发者可以：

Fork DevOS Starter

然后：

Remove unused Apps
Remove unused Plugins
Add custom modules

形成：

My Product

而不是：

必须运行完整 DevOS

55. Core / Starter / Full Distribution

建议提供三种发行模式。

Core

DevOS Core

只包含：

Identity
Resource
Action
Task
Plugin
Agent
MCP
UI Shell

Starter

DevOS Starter

包含：

Core
+
基础 Dashboard
+
基础 Settings
+
示例 Plugin

Full

DevOS Full

包含：

Core
+
多个 App
+
常用 Plugins

56. 不允许 Core 与 App 强耦合

错误：

import SEOWebsitePage from
"@devos/seo/pages/Website";

然后 Core Dashboard 写死 SEO。

正确：

SEO App
 ↓
App Registry
 ↓
Route Registry
 ↓
Navigation Registry
 ↓
UI Shell

Core 不需要知道：

SEO
GitHub
Cloudflare
CRM

具体存在什么 App。

57. App 间集成

App 不应该直接互相 import 内部业务代码。

例如：

SEO App
 ↓
Browser Plugin

应该：

SEO App
 ↓
Capability / Action
 ↓
Browser Action

例如：

browser.open

这样：

Browser Plugin

不存在时：

Capability unavailable

SEO App 仍然可以正常运行。

58. UI → Capability

UI 可以展示 Capability：

Capability:
browser.open

然后：

executeAction({
  actionId: "browser.open",
  input: {
    url: "https://example.com"
  }
});

API Client 最终：

POST /api/actions/execute

或者：

POST /api/actions/browser.open

但后端必须统一进入：

Action Runtime

59. API Client

前端建议统一：

devos.api

例如：

devos.api.resources.list(...)
devos.api.resources.get(...)
devos.api.actions.execute(...)
devos.api.tasks.get(...)
devos.api.agents.createGoal(...)
devos.api.search(...)

UI Component 不应该自己拼接 API URL。

60. Notification

所有：

Action
Task
Agent
Plugin
System Event

都可以产生 Notification。

统一：

Notification Center

例如：

✓ SEO Scan completed

⚠ GitHub token expires in 7 days

✕ Deployment failed

Notification 来源可以是：

Event Bus

而不是组件之间互相调用。

61. Event → UI

例如：

seo.website.scan.completed

Event Bus：

Event
 ↓
Notification
 ↓
Query Invalidation
 ↓
Widget Refresh

例如：

Website Scan
完成
 ↓
Website Detail 自动刷新
 ↓
Dashboard SEO Issues 自动刷新

62. Query Invalidation

Action 成功后：

queryClient.invalidateQueries({
  queryKey: ["resource", "seo.website"]
});

但最好由 Action/Event Metadata 提供：

Action
 ↓
Events
 ↓
UI Query Invalidation

避免 UI 到处硬编码业务依赖。

63. Audit UI

用户应该能够看到：

Activity

例如：

10:21 User started SEO Scan
10:21 Agent created Task
10:22 Website Scan running
10:23 Website Scan completed
10:23 Agent generated report

来自：

Audit
+
Execution
+
Event
+
Agent Trace

64. Agent Trace UI

Agent Trace：

Goal
 ↓
Plan
 ↓
Capability Discovery
 ↓
Action
 ↓
Task
 ↓
Execution
 ↓
Observation
 ↓
Evaluation
 ↓
Report

UI：

SEO Agent

Goal:
检查 example.com SEO

✓ Discover capabilities
✓ Scan website
✓ Analyze issues
✓ Generate report

Result:
12 issues found

[View Report]

不要展示模型隐藏 Chain-of-Thought。

只展示：

Decision Summary
Action
Input Summary
Result Summary
Reason / Status

65. Mobile / Responsive

Shell 必须支持：

Desktop
Tablet
Mobile

但核心 Developer Work OS 优先：

Desktop

Mobile 主要支持：

Monitoring
Notifications
Task Status
Agent Chat
Approval

复杂：

Terminal
Table
Workflow

优先 Desktop。

66. Theme

Core UI 支持：

Light
Dark
System

Plugin UI 必须使用 DevOS Design Tokens。

禁止 Plugin 自己创建完全独立的：

Color System
Typography System
Spacing System

否则整个 DevOS 会出现视觉碎片化。

67. Design Tokens

统一：

colors
spacing
radius
typography
shadow
breakpoints
z-index

例如：

devos.theme

Plugin 只能：

使用 Token

而不是覆盖整个 Theme。

68. Developer API

最终开发者应该可以这样开发：

export default definePlugin({
  id: "github",

  ui: {
    routes: [
      {
        path: "/plugins/github/repositories",
        component: "repositories"
      }
    ],

    navigation: [
      {
        title: "Repositories",
        path: "/plugins/github/repositories"
      }
    ],

    widgets: [
      {
        slot: "dashboard.main",
        component: "pull_requests"
      }
    ]
  }
});

然后 Plugin 安装：

Install Plugin
 ↓
Registry
 ↓
UI automatically available

69. Plugin Page API

Plugin Page：

definePluginPage({
  id: "github.repositories",

  route: "/plugins/github/repositories",

  permission: "github.repository.read",

  component: GithubRepositoriesPage
});

defineWidget({
  id: "github.pull_requests",

  slot: "dashboard.main",

  title: "Pull Requests",

  permission: "github.pull_request.read",

  component: PullRequestWidget
});

71. Context Action API

defineContextAction({
  id: "github.create_issue",

  resourceTypes: [
    "github.repository"
  ],

  actionId: "github.issue.create"
});

72. UI 与 Backend Contract

前端和 Backend 不应该通过：

任意 JSON

随意通信。

必须定义：

Resource Schema
Action Input Schema
Action Output Schema
Task Schema
Execution Schema
Event Schema
Capability Schema

73. UI Error Model

统一 Error：

interface DevOSError {
  code: string;

  message: string;

  details?: unknown;

  retryable?: boolean;

  actionId?: string;

  executionId?: string;
}

UI 根据：

code

决定：

Toast
Modal
Inline Error
Retry Button
Login
Permission

74. Loading State

禁止每个页面自己发明：

Loading...
Please wait...
Processing...

统一组件：

Loading
Skeleton
Progress
ActionProgress
TaskProgress
ExecutionStatus

75. Empty State

Resource：

No websites yet.

[Create Website]

Plugin：

GitHub is not connected.

[Connect GitHub]

Agent：

No goals yet.

[Create Goal]

Empty State 可以由 Resource/Plugin Metadata 提供。

76. Confirmation

危险 Action：

Delete
Deploy
Merge
Rotate Credentials
Drop Database

必须由 Action Metadata 指定：

requiresApproval: true

UI 显示：

Confirm

但真正的安全控制仍然在 Backend。

77. Approval UI

统一：

/approvals

例如：

SEO Agent wants to:

Publish 20 articles

Risk:
Medium

[Approve]
[Reject]

Approval：

Agent
 ↓
Action
 ↓
Approval Required
 ↓
Human
 ↓
Action Runtime

78. Command + Agent

Command Palette 可以直接进入 Agent：

> optimize example.com

系统可以识别：

This is a Goal

然后：

Command
 ↓
Agent Goal

因此 Command Palette 不是简单：

route search

它也是 DevOS 的 Agent Entry Point。

79. UI Architecture

推荐最终目录：

apps/
└── web/

packages/
├── ui/
├── shell/
├── registry/
├── navigation/
├── routing/
├── resource-ui/
├── action-ui/
├── task-ui/
├── agent-ui/
├── plugin-ui/
├── widget-ui/
├── command/
├── search/
├── workspace/
├── permissions/
├── api-client/
└── theme/

80. Shell Package

packages/shell/

├── AppShell
├── Header
├── Sidebar
├── Workspace
├── Breadcrumb
├── CommandPalette
├── GlobalSearch
├── NotificationCenter
└── UserMenu

81. Registry Package

packages/registry/

├── app-registry.ts
├── module-registry.ts
├── route-registry.ts
├── navigation-registry.ts
├── widget-registry.ts
├── command-registry.ts
└── context-action-registry.ts

82. Resource UI Package

packages/resource-ui/

├── ResourceList
├── ResourceDetail
├── ResourceForm
├── ResourceCreate
├── ResourceEdit
├── ResourceActions
└── ResourceActivity

83. Agent UI Package

packages/agent-ui/

├── AgentList
├── AgentDetail
├── AgentChat
├── AgentGoal
├── AgentRun
├── AgentTrace
└── AgentApproval

84. Plugin UI Package

packages/plugin-ui/

├── PluginPage
├── PluginSettings
├── PluginWidget
├── PluginNavigation
├── PluginContextAction
└── PluginErrorBoundary

85. 不允许的架构

以下全部禁止：

❌ Plugin 修改 Sidebar.tsx

❌ Plugin 修改 Core Router

❌ UI 直接访问 Database

❌ UI 直接调用第三方 API

❌ UI 自己实现业务 Action

❌ Agent UI 直接调用 Plugin API

❌ Plugin 绕过 Permission

❌ Frontend Permission 代替 Backend Permission

❌ 每个 App 自己实现 Layout

❌ 每个 Plugin 自己实现 Settings Framework

❌ 每个 Plugin 自己实现 Notification

❌ 每个 Plugin 自己实现 Task UI

86. 推荐架构

最终：

                         DevOS UI Shell
                               │
              ┌────────────────┼────────────────┐
              │                │                │
           Core UI          App UI          Plugin UI
              │                │                │
              └────────────────┼────────────────┘
                               │
                         UI Registry
                               │
        ┌──────────┬───────────┼──────────┬───────────┐
        │          │           │          │           │
      Routes    Navigation   Widgets   Commands   Context
        │          │           │          │           │
        └──────────┴───────────┼──────────┴───────────┘
                               │
                         API / Runtime
                               │
              ┌────────────────┼────────────────┐
              │                │                │
          Resource          Action            Agent
              │                │                │
              └────────────────┼────────────────┘
                               │
                         DevOS Backend

87. 最重要的设计结论

DevOS UI 不是：

一个 Admin Dashboard

而是：

一个可扩展的 UI Runtime

核心能力：

Shell
+
Registry
+
Route
+
Navigation
+
Resource UI
+
Action UI
+
Task UI
+
Agent UI
+
Plugin UI
+
Widget
+
Command
+
Context Action

最终实现：

安装 Plugin
    ↓
Plugin 注册 Resource
    ↓
Plugin 注册 Action
    ↓
Plugin 注册 Skill
    ↓
Plugin 注册 MCP
    ↓
Plugin 注册 Route
    ↓
Plugin 注册 Navigation
    ↓
Plugin 注册 Widget
    ↓
Plugin 注册 Settings
    ↓
Plugin 注册 Context Actions
    ↓
DevOS UI 自动获得完整功能

Core 不需要修改。

88. Zcode 必须实现的 Acceptance Criteria

AC-01

可以动态注册 App：

AppRegistry.register()

并自动出现 Navigation。

AC-02

可以动态注册 Plugin。

Plugin 安装后自动出现：

Route
Navigation
Settings
Widget

AC-03

Plugin 禁用后：

Navigation 消失
Route 不可访问
Widget 不再显示

且不能导致 Shell 崩溃。

AC-04

实现：

Resource List
Resource Detail
Resource Create
Resource Edit

并能读取 Resource Metadata。

AC-05

Resource Action 必须通过：

Action Runtime

执行。

AC-06

实现：

Task Detail
Execution Detail
Progress
Logs
Output

AC-07

实现：

Command Palette

至少支持：

Navigation
Action
Resource
Agent

AC-08

实现：

Global Search

支持：

Resource
Task
Agent
Plugin
Action

AC-09

实现：

Widget Slot

至少支持：

dashboard.main
dashboard.sidebar
resource.detail.toolbar
resource.list.toolbar

AC-10

实现：

Context Action

例如：

seo.website
 ↓
Open Browser
Scan SEO
Ask Agent

AC-11

实现：

Plugin Settings

Plugin 可以拥有自己的：

/settings/plugins/{pluginId}

AC-12

实现：

PermissionGuard

并确保：

Frontend Permission 仅用于 UI，Backend Authorization 才是最终安全边界。

AC-13

实现：

Agent Chat
Agent Goal
Agent Run
Agent Trace
Agent Approval

并与 DevOS Agent Runtime 对接。

AC-14

实现：

Workspace Context

支持：

Organization
Project
Environment

AC-15

实现 Plugin Error Boundary。

单个 Plugin 崩溃不能导致整个 DevOS Shell 崩溃。

AC-16

实现 Lazy Loading。

Plugin UI 不应该在 DevOS 首屏全部加载。

AC-17

实现完整 UI Registry：

AppRegistry
ModuleRegistry
RouteRegistry
NavigationRegistry
WidgetRegistry
CommandRegistry
ContextActionRegistry

AC-18

至少完成以下 Demo：

Demo A

安装：

GitHub Plugin

自动出现：

GitHub
├── Repositories
├── Issues
└── Settings

Demo B

GitHub Plugin 注册：

dashboard.main

Widget。

Dashboard 自动显示。

Demo C

SEO Website：

example.com

右上角自动出现：

Open Browser
Scan SEO
Ask Agent

Demo D