# `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 最终结构： ```text 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 必须遵循： ```text UI ↓ UI Action / Query ↓ API ↓ Action Runtime / Resource Runtime ↓ Backend ``` 禁止： ```text UI ↓ 直接操作数据库 ``` 禁止： ```text UI ↓ 自己实现业务逻辑 ``` 禁止： ```text 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 是一个完整的产品/业务应用。 例如： ```text DevOS SEO App DevOps App CRM App Content App ``` App 可以包含： ```text Pages Resources Actions Skills Plugins Widgets Settings Agents ``` 例如： ```text SEO App ├── Websites ├── Keywords ├── Content ├── Backlinks ├── Reports └── SEO Agent ``` --- # 4. Module Module 是 App 内部的功能模块。 例如： ```text SEO App ├── Website Module ├── Keyword Module ├── Content Module ├── Backlink Module └── Report Module ``` Module 通常不应该成为独立安装包。 它主要解决： > 如何组织大型 App。 --- # 5. Plugin Plugin 是可独立安装/卸载/启用/禁用的扩展。 例如： ```text GitHub Plugin Browser Plugin Cloudflare Plugin Google Search Console Plugin OpenAI Plugin ``` Plugin 可以提供： ```text Resource Action Skill MCP Workflow Page Settings Widget Context Action ``` 例如： ```text 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 基础。 推荐： ```text React TypeScript React Router Ant Design TanStack Query Zustand TipTap ``` Shell： ```text ┌───────────────────────────────────────────────┐ │ Header │ │ Logo | Search | Command | Notifications | Me │ ├──────────────┬────────────────────────────────┤ │ │ │ │ Navigation │ Workspace │ │ │ │ │ Dashboard │ Breadcrumb │ │ Apps │ │ │ Resources │ Page │ │ Plugins │ │ │ Settings │ │ │ │ │ │ │ │ └──────────────┴────────────────────────────────┘ ``` --- # 7. App Registry 所有 App 都必须通过 Registry 注册。 ```ts 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; } ``` 例如： ```ts { id: "seo", name: "SEO", version: "1.0.0", route: "/seo" } ``` --- # 8. Module Manifest ```ts export interface ModuleManifest { id: string; appId: string; name: string; version: string; routes?: RouteDefinition[]; navigation?: NavigationItem[]; widgets?: WidgetManifest[]; resources?: string[]; permissions?: string[]; } ``` 例如： ```text seo.website seo.keyword seo.content seo.backlink ``` --- # 9. Plugin UI Manifest Plugin UI 必须与 Plugin Manifest 统一。 ```ts export interface PluginUIManifest { pluginId: string; routes?: RouteDefinition[]; navigation?: NavigationItem[]; widgets?: WidgetManifest[]; settings?: SettingsPageDefinition[]; contextActions?: ContextActionDefinition[]; } ``` --- # 10. Route Registry 不要让每个 Plugin 自己修改 React Router。 统一： ```text Route Registry ↓ React Router ``` 定义： ```ts export interface RouteDefinition { id: string; path: string; title: string; component: string; icon?: string; permission?: string; children?: RouteDefinition[]; metadata?: Record; } ``` 例如： ```ts { id: "github.repositories", path: "/plugins/github/repositories", title: "Repositories", component: "github.repositories" } ``` --- # 11. Route Namespace Plugin 路由必须隔离。 推荐： ```text /plugins/{pluginId}/... ``` 例如： ```text /plugins/github/repositories /plugins/github/issues /plugins/cloudflare/zones /plugins/cloudflare/dns /plugins/browser/sessions ``` App： ```text /seo/... /devops/... /crm/... ``` Core： ```text /dashboard /tasks /agents /settings /plugins ``` 禁止 Plugin 任意覆盖： ```text /settings /users /tasks ``` 除非明确声明扩展点。 --- # 12. Navigation Registry Navigation 不应该硬编码。 统一： ```ts NavigationRegistry.register(...) ``` 结构： ```ts export interface NavigationItem { id: string; title: string; path?: string; icon?: string; parentId?: string; order?: number; permission?: string; visible?: boolean; badge?: BadgeDefinition; metadata?: Record; } ``` 例如： ```text SEO ├── Overview ├── Websites ├── Keywords ├── Content └── Backlinks ``` Plugin 安装后： ```text Plugins ├── GitHub │ ├── Repositories │ └── Issues │ ├── Cloudflare │ └── Zones │ └── Browser └── Sessions ``` --- # 13. Navigation 权限 前端可以根据权限隐藏菜单。 例如： ```ts permission: "seo.website.read" ``` 没有权限： ```text Navigation → hidden ``` 但是： > 前端隐藏不是安全机制。 用户直接访问： ```text /seo/websites ``` 后端仍必须检查： ```text seo.website.read ``` 真正的安全边界始终是 Backend Authorization。 --- # 14. Dynamic Navigation Plugin 启用后： ```text Plugin Runtime ↓ Plugin Manifest ↓ Navigation Registry ↓ UI Shell ↓ Navigation 更新 ``` 不应该修改： ```text Sidebar.tsx ``` 来添加 Plugin。 --- # 15. Resource UI Resource Metadata 应该能够驱动通用 UI。 例如： ```text Resource: seo.website ``` 定义： ```ts { id: "seo.website", fields: { name: {...}, domain: {...}, status: {...} }, actions: [ "seo.website.create", "seo.website.update", "seo.website.delete", "seo.website.scan" ] } ``` UI 可以自动生成： ```text Website List Website Detail Create Website Edit Website ``` --- # 16. Resource List 通用 Resource List： ```text ┌─────────────────────────────────────────────┐ │ Websites + Create │ ├─────────────────────────────────────────────┤ │ Search │ │ │ │ Domain Status Last Scan │ │ example.com Healthy 2 min ago │ │ example.org Warning 1 hour ago │ │ │ └─────────────────────────────────────────────┘ ``` 表格定义可以来自： ```ts ResourceMetadata ``` 但允许业务页面覆盖默认 UI。 --- # 17. Resource Detail ```text /seo/websites/:id ``` Detail 页面： ```text Website ├── Overview ├── SEO ├── Keywords ├── Content ├── Backlinks ├── Tasks ├── Executions └── Activity ``` 其中： ```text Overview ``` 可以是通用 Resource UI。 而： ```text SEO Keywords Backlinks ``` 可以是 App 自定义页面。 --- # 18. Action UI Action 不是简单的 Button。 Action Metadata： ```ts export interface ActionUIConfig { actionId: string; label: string; icon?: string; confirm?: boolean; danger?: boolean; form?: FormSchema; resultView?: ResultViewDefinition; } ``` 例如： ```text Website Detail [Scan Website] ``` 点击： ```text seo.website.scan ``` 进入： ```text Action Runtime ``` 而不是： ```text POST /scan ``` 再由 Controller 自己实现业务逻辑。 --- # 19. Action 状态 对于异步 Action： ```text pending running completed failed cancelled ``` UI 应该统一展示： ```text ActionExecution ``` 例如： ```text Scan Website Running... ████████████░░░░░░ 65% Current: Checking backlinks ``` --- # 20. Task UI Action 如果创建 Task： ```text Action ↓ Task ↓ Job ↓ Execution ``` UI： ```text Task ├── Status ├── Progress ├── Jobs ├── Logs ├── Executions └── Output ``` Agent、用户、Plugin 都应该使用同一 Task UI。 --- # 21. Agent UI Agent 页面： ```text /agents ``` 列表： ```text SEO Agent DevOps Agent General Agent Content Agent ``` Agent Detail： ```text Agent ├── Overview ├── Goals ├── Runs ├── Skills ├── Capabilities ├── Policies └── Settings ``` --- # 22. Agent Chat Chat 只是 Agent 的一种 UI。 例如： ```text ┌─────────────────────────────────────────────┐ │ SEO Agent │ ├─────────────────────────────────────────────┤ │ │ │ User: │ │ 检查 example.com 的 SEO │ │ │ │ Agent: │ │ 我发现该网站存在 12 个问题。 │ │ │ │ [View Report] [Create Tasks] │ │ │ └─────────────────────────────────────────────┘ ``` Chat 不应该直接执行业务。 流程： ```text Chat ↓ Agent Goal ↓ Agent Runtime ↓ Capability ↓ Action Runtime ``` --- # 23. Widget Registry Widget 是 DevOS UI 的重要扩展机制。 Plugin 可以提供： ```text Dashboard Widget Statistics Widget Report Widget Chat Widget Resource Widget Agent Widget ``` 定义： ```ts 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; } ``` --- # 24. Dashboard Extension Dashboard 不应该写死。 例如： ```text Dashboard ├── System Health ├── Tasks ├── Agent Activity │ ├── SEO Traffic ├── SEO Issues │ ├── GitHub PRs └── Cloudflare Traffic ``` 其中： ```text SEO Traffic ``` 来自 SEO App。 ```text GitHub PRs ``` 来自 GitHub Plugin。 --- # 25. Widget Slot Shell 提供 Extension Point： ```text dashboard.main dashboard.sidebar resource.detail.before resource.detail.after resource.list.toolbar resource.detail.toolbar agent.sidebar agent.chat.toolbar ``` Plugin 可以： ```ts WidgetRegistry.register({ slot: "dashboard.main", widget: "github.pull_requests" }); ``` 这样 Plugin 不需要修改 Core Dashboard。 --- # 26. Context Action Context Action 是 Plugin 非常重要的 UI 能力。 例如： ```text 用户查看： Website: example.com ``` 右上角： ```text More ├── Scan SEO ├── Open in Browser ├── Search Google ├── Create Content └── Ask Agent ``` 定义： ```ts export interface ContextActionDefinition { id: string; label: string; icon?: string; resourceTypes?: string[]; actionId: string; permission?: string; } ``` 例如： ```ts { id: "browser.open_website", resourceTypes: ["seo.website"], actionId: "browser.open_url" } ``` --- # 27. Resource Context Action 对于： ```text seo.website ``` Plugin 可以注册： ```text Open Browser Run SEO Scan Search Backlinks Create Article Ask SEO Agent ``` 所有这些最终必须转换为： ```text Action ``` 或者： ```text Agent Goal ``` --- # 28. Settings UI Settings 必须支持： ```text Core Settings App Settings Plugin Settings User Settings Organization Settings Project Settings ``` 结构： ```text Settings ├── General ├── Account ├── Organization ├── Security ├── Agents ├── Models ├── Plugins │ ├── GitHub │ ├── Cloudflare │ └── Browser └── Developer ``` --- # 29. Plugin Settings Plugin 自己可以定义 Settings Page： ```ts export interface SettingsPageDefinition { id: string; pluginId: string; title: string; path: string; component: string; permissions?: string[]; } ``` 例如： ```text /settings/plugins/github ``` 页面： ```text GitHub Connection [ Connected ] Default Organization [ example ] Webhook [ Enabled ] [ Save ] ``` 保存： ```text UI ↓ Action ↓ Action Runtime ``` --- # 30. Settings 不应该直接调用 Plugin API 禁止： ```ts fetch("https://api.github.com/...") ``` 在 React Component 中直接执行。 应该： ```text GitHub Settings UI ↓ github.connection.update ↓ Action Runtime ↓ GitHub Plugin ``` 这样才能统一： * Permission * Audit * Validation * Retry * Error * Secret * Logging --- # 31. Secret UI Plugin 可能需要： ```text API Key Token OAuth Secret ``` UI 只能操作： ```text Secret Reference ``` 不要让普通 UI State 长期保存明文 Secret。 例如： ```ts { credentialId: "cred_xxx" } ``` 后端负责： ```text Credential Store ``` --- # 32. Global Search DevOS 应提供统一搜索。 搜索范围： ```text Resources Tasks Agents Plugins Actions Users Projects Documentation ``` 例如： ```text Search: example.com ``` 结果： ```text Websites example.com Tasks SEO Scan example.com Reports SEO Audit example.com Agent Runs SEO Agent / example.com ``` --- # 33. Search Provider 不要让 Search UI 知道具体数据库。 统一： ```ts export interface SearchProvider { search( query: SearchQuery ): Promise; } ``` Backend 根据： ```text Resource Registry Plugin Registry Search Index ``` 返回结果。 --- # 34. Command Palette DevOS 应提供： ```text Cmd/Ctrl + K ``` Command Palette。 例如： ```text > scan example.com Actions Scan Website Pages Website Agents Ask SEO Agent ``` Command Palette 可以搜索： ```text Navigation Resources Actions Commands Agents ``` --- # 35. Command Registry ```ts export interface CommandDefinition { id: string; title: string; description?: string; keywords?: string[]; actionId?: string; route?: string; permission?: string; } ``` Plugin 可以注册 Command。 例如： ```text GitHub: Create Repository Open Pull Requests ``` --- # 36. Breadcrumb Breadcrumb 不应该硬编码。 由 Route / Resource Context 自动生成。 例如： ```text SEO / Websites / example.com ``` 如果进入： ```text SEO / Websites / example.com / Scan ``` Action 页面可以显示： ```text SEO / Websites / example.com / Scan ``` --- # 37. Workspace DevOS 应支持 Workspace 概念。 Workspace 可以理解为： > 用户当前工作的上下文空间。 例如： ```text Workspace ├── Project ├── Organization ├── Environment └── Active Resources ``` Header： ```text [ Organization ▼ ] [ Project ▼ ] ``` 切换 Workspace 后： ```text Navigation Data Permissions Agents Tasks ``` 都应该根据 Workspace Context 更新。 --- # 38. Workspace Context 前端： ```ts interface WorkspaceContext { organizationId?: string; projectId?: string; environmentId?: string; } ``` 所有 API Query 都应该带： ```text organizationId projectId ``` 但是： > 前端传入的 Workspace Context 不能作为安全依据。 Backend 必须重新验证： ```text Actor + Organization + Project + Resource Scope ``` --- # 39. React Query Server State 统一使用： ```text TanStack Query ``` 例如： ```ts useQuery({ queryKey: [ "resource", "seo.website", websiteId ], queryFn: ... }); ``` 禁止使用 Zustand 保存大量 Server State。 --- # 40. Zustand Zustand 用于： ```text UI State Session UI Sidebar State Workspace UI Command Palette Modal Theme Preferences ``` 不要： ```text Zustand ↓ 保存整个后端数据库 ``` --- # 41. Form 通用 Resource Form 可以根据 Schema 自动生成。 例如： ```ts { fields: { name: { type: "string", required: true }, domain: { type: "url", required: true } } } ``` 生成： ```text Name [________________] Domain [________________] [ Save ] ``` 但复杂业务表单允许完全自定义 React Component。 --- # 42. Dynamic UI 与 Custom UI DevOS 不应该追求： > 所有页面都自动生成。 正确原则： ```text 简单 CRUD ↓ Schema-driven UI 复杂业务 ↓ Custom React UI ``` 例如： ```text User CRUD → Dynamic UI SEO Website → Custom UI + Resource metadata Agent Workspace → Custom UI DevOps Terminal → Custom UI ``` --- # 43. UI Registry 统一 UI Registry： ```text AppRegistry ModuleRegistry PluginRegistry RouteRegistry NavigationRegistry WidgetRegistry CommandRegistry ContextActionRegistry ``` 建议： ```ts export interface UIRegistry { apps: AppRegistry; modules: ModuleRegistry; routes: RouteRegistry; navigation: NavigationRegistry; widgets: WidgetRegistry; commands: CommandRegistry; contextActions: ContextActionRegistry; } ``` --- # 44. Registry 生命周期 系统启动： ```text Load Core ↓ Load Apps ↓ Load Modules ↓ Load Plugins ↓ Register Routes ↓ Register Navigation ↓ Register Widgets ↓ Register Commands ↓ Register Context Actions ↓ Render Shell ``` Plugin 动态启用： ```text Plugin Enable ↓ Load Manifest ↓ Register UI ↓ Invalidate Registry ↓ Shell Update ``` Plugin 禁用： ```text Plugin Disable ↓ Unregister UI ↓ Invalidate Registry ↓ Routes disappear ↓ Navigation disappears ↓ Widgets disappear ``` --- # 45. Lazy Loading Plugin 页面必须支持 Lazy Loading。 不要： ```text App Startup ↓ 加载所有 Plugin UI ``` 应该： ```text Shell ↓ Load Manifest ↓ User opens Plugin page ↓ Lazy Load Component ``` 例如： ```ts const GitHubRepositories = lazy(() => import("@devos/plugin-github/ui/repositories") ); ``` --- # 46. Plugin UI Isolation Plugin UI 必须： * 使用自己的 namespace * 不能覆盖 Core Route * 不能随意修改全局 State * 不能直接访问数据库 * 不能绕过 Permission * 不能绕过 Action Runtime Plugin 可以通过： ```text Registry Extension Point Action Resource Event ``` 与 Core 集成。 --- # 47. Error Boundary 每个 App/Plugin UI 都必须有 Error Boundary。 例如： ```text Shell ├── Core Error Boundary │ ├── SEO Error Boundary │ ├── GitHub Plugin Error Boundary │ └── Browser Plugin Error Boundary ``` 如果 GitHub Plugin 崩溃： ```text GitHub Plugin failed ``` 不能导致： ```text 整个 DevOS 白屏 ``` --- # 48. Permission Guard 前端： ```tsx ``` 作用： ```text UI visibility ``` 不是： ```text Security ``` Backend 必须再次验证。 --- # 49. Feature Flag UI 支持 Feature Flag： ```ts feature("new_agent_ui") ``` 可以控制： ```text App Module Plugin Widget Route ``` 例如： ```text agent.workspace.v2 ``` --- # 50. UI Extension API 建议提供： ```ts ui.registerRoute(...) ui.registerNavigation(...) ui.registerWidget(...) ui.registerCommand(...) ui.registerContextAction(...) ui.registerSettings(...) ui.registerSlotExtension(...) ``` Plugin 开发者不需要修改： ```text Core UI source ``` --- # 51. 示例：GitHub Plugin 安装： ```text GitHub Plugin ``` Plugin Runtime 注册： ```text 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 自动出现： ```text Plugins └── GitHub ├── Repositories ├── Issues ├── Pull Requests ├── Statistics └── Settings ``` 同时 Dashboard： ```text GitHub PR Widget ``` Command Palette： ```text Create GitHub Repository ``` Context Action： ```text Resource: github.repository Open Clone Create Issue Ask Agent ``` --- # 52. 示例：Browser Plugin Browser Plugin： ```text Resource: browser.session Actions: browser.open browser.navigate browser.screenshot MCP: browser Skill: browser.research UI: Browser Sessions Browser Console Browser Settings ``` SEO Website 页面： ```text example.com ``` Context Actions： ```text Open Browser Screenshot Run SEO Audit Ask Agent ``` 其中： ```text Open Browser ↓ browser.open ↓ Action Runtime ``` --- # 53. 示例：SEO App SEO App 不应该重新实现： ```text Layout Navigation Task UI Agent UI Settings Notification Permission Search Command Palette ``` 这些全部由 DevOS Core 提供。 SEO App 只提供： ```text Resources Actions Skills Agents Pages Widgets Reports ``` 例如： ```text SEO ├── Overview ├── Websites ├── Keywords ├── Content ├── Backlinks ├── Reports └── Agent ``` --- # 54. App Fork 模式 DevOS 必须支持： ```text DevOS Core ↓ Starter App ``` 开发者可以： ```text Fork DevOS Starter ``` 然后： ```text Remove unused Apps Remove unused Plugins Add custom modules ``` 形成： ```text My Product ``` 而不是： ```text 必须运行完整 DevOS ``` --- # 55. Core / Starter / Full Distribution 建议提供三种发行模式。 ## Core ```text DevOS Core ``` 只包含： ```text Identity Resource Action Task Plugin Agent MCP UI Shell ``` --- ## Starter ```text DevOS Starter ``` 包含： ```text Core + 基础 Dashboard + 基础 Settings + 示例 Plugin ``` --- ## Full ```text DevOS Full ``` 包含： ```text Core + 多个 App + 常用 Plugins ``` --- # 56. 不允许 Core 与 App 强耦合 错误： ```ts import SEOWebsitePage from "@devos/seo/pages/Website"; ``` 然后 Core Dashboard 写死 SEO。 正确： ```text SEO App ↓ App Registry ↓ Route Registry ↓ Navigation Registry ↓ UI Shell ``` Core 不需要知道： ```text SEO GitHub Cloudflare CRM ``` 具体存在什么 App。 --- # 57. App 间集成 App 不应该直接互相 import 内部业务代码。 例如： ```text SEO App ↓ Browser Plugin ``` 应该： ```text SEO App ↓ Capability / Action ↓ Browser Action ``` 例如： ```text browser.open ``` 这样： ```text Browser Plugin ``` 不存在时： ```text Capability unavailable ``` SEO App 仍然可以正常运行。 --- # 58. UI → Capability UI 可以展示 Capability： ```text Capability: browser.open ``` 然后： ```ts executeAction({ actionId: "browser.open", input: { url: "https://example.com" } }); ``` API Client 最终： ```text POST /api/actions/execute ``` 或者： ```text POST /api/actions/browser.open ``` 但后端必须统一进入： ```text Action Runtime ``` --- # 59. API Client 前端建议统一： ```ts devos.api ``` 例如： ```ts 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 所有： ```text Action Task Agent Plugin System Event ``` 都可以产生 Notification。 统一： ```text Notification Center ``` 例如： ```text ✓ SEO Scan completed ⚠ GitHub token expires in 7 days ✕ Deployment failed ``` Notification 来源可以是： ```text Event Bus ``` 而不是组件之间互相调用。 --- # 61. Event → UI 例如： ```text seo.website.scan.completed ``` Event Bus： ```text Event ↓ Notification ↓ Query Invalidation ↓ Widget Refresh ``` 例如： ```text Website Scan 完成 ↓ Website Detail 自动刷新 ↓ Dashboard SEO Issues 自动刷新 ``` --- # 62. Query Invalidation Action 成功后： ```ts queryClient.invalidateQueries({ queryKey: ["resource", "seo.website"] }); ``` 但最好由 Action/Event Metadata 提供： ```text Action ↓ Events ↓ UI Query Invalidation ``` 避免 UI 到处硬编码业务依赖。 --- # 63. Audit UI 用户应该能够看到： ```text Activity ``` 例如： ```text 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 ``` 来自： ```text Audit + Execution + Event + Agent Trace ``` --- # 64. Agent Trace UI Agent Trace： ```text Goal ↓ Plan ↓ Capability Discovery ↓ Action ↓ Task ↓ Execution ↓ Observation ↓ Evaluation ↓ Report ``` UI： ```text SEO Agent Goal: 检查 example.com SEO ✓ Discover capabilities ✓ Scan website ✓ Analyze issues ✓ Generate report Result: 12 issues found [View Report] ``` 不要展示模型隐藏 Chain-of-Thought。 只展示： ```text Decision Summary Action Input Summary Result Summary Reason / Status ``` --- # 65. Mobile / Responsive Shell 必须支持： ```text Desktop Tablet Mobile ``` 但核心 Developer Work OS 优先： ```text Desktop ``` Mobile 主要支持： ```text Monitoring Notifications Task Status Agent Chat Approval ``` 复杂： ```text Terminal Table Workflow ``` 优先 Desktop。 --- # 66. Theme Core UI 支持： ```text Light Dark System ``` Plugin UI 必须使用 DevOS Design Tokens。 禁止 Plugin 自己创建完全独立的： ```text Color System Typography System Spacing System ``` 否则整个 DevOS 会出现视觉碎片化。 --- # 67. Design Tokens 统一： ```text colors spacing radius typography shadow breakpoints z-index ``` 例如： ```ts devos.theme ``` Plugin 只能： ```text 使用 Token ``` 而不是覆盖整个 Theme。 --- # 68. Developer API 最终开发者应该可以这样开发： ```ts 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 安装： ```text Install Plugin ↓ Registry ↓ UI automatically available ``` --- # 69. Plugin Page API Plugin Page： ```ts definePluginPage({ id: "github.repositories", route: "/plugins/github/repositories", permission: "github.repository.read", component: GithubRepositoriesPage }); ``` --- # 70. Widget API ```ts defineWidget({ id: "github.pull_requests", slot: "dashboard.main", title: "Pull Requests", permission: "github.pull_request.read", component: PullRequestWidget }); ``` --- # 71. Context Action API ```ts defineContextAction({ id: "github.create_issue", resourceTypes: [ "github.repository" ], actionId: "github.issue.create" }); ``` --- # 72. UI 与 Backend Contract 前端和 Backend 不应该通过： ```text 任意 JSON ``` 随意通信。 必须定义： ```text Resource Schema Action Input Schema Action Output Schema Task Schema Execution Schema Event Schema Capability Schema ``` 推荐： ```text Zod + OpenAPI ``` 前端可以生成： ```text TypeScript Types API Client Form Schema ``` --- # 73. UI Error Model 统一 Error： ```ts interface DevOSError { code: string; message: string; details?: unknown; retryable?: boolean; actionId?: string; executionId?: string; } ``` UI 根据： ```text code ``` 决定： ```text Toast Modal Inline Error Retry Button Login Permission ``` --- # 74. Loading State 禁止每个页面自己发明： ```text Loading... Please wait... Processing... ``` 统一组件： ```text Loading Skeleton Progress ActionProgress TaskProgress ExecutionStatus ``` --- # 75. Empty State Resource： ```text No websites yet. [Create Website] ``` Plugin： ```text GitHub is not connected. [Connect GitHub] ``` Agent： ```text No goals yet. [Create Goal] ``` Empty State 可以由 Resource/Plugin Metadata 提供。 --- # 76. Confirmation 危险 Action： ```text Delete Deploy Merge Rotate Credentials Drop Database ``` 必须由 Action Metadata 指定： ```ts requiresApproval: true ``` UI 显示： ```text Confirm ``` 但真正的安全控制仍然在 Backend。 --- # 77. Approval UI 统一： ```text /approvals ``` 例如： ```text SEO Agent wants to: Publish 20 articles Risk: Medium [Approve] [Reject] ``` Approval： ```text Agent ↓ Action ↓ Approval Required ↓ Human ↓ Action Runtime ``` --- # 78. Command + Agent Command Palette 可以直接进入 Agent： ```text > optimize example.com ``` 系统可以识别： ```text This is a Goal ``` 然后： ```text Command ↓ Agent Goal ``` 因此 Command Palette 不是简单： ```text route search ``` 它也是 DevOS 的 Agent Entry Point。 --- # 79. UI Architecture 推荐最终目录： ```text 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 ```text packages/shell/ ├── AppShell ├── Header ├── Sidebar ├── Workspace ├── Breadcrumb ├── CommandPalette ├── GlobalSearch ├── NotificationCenter └── UserMenu ``` --- # 81. Registry Package ```text 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 ```text packages/resource-ui/ ├── ResourceList ├── ResourceDetail ├── ResourceForm ├── ResourceCreate ├── ResourceEdit ├── ResourceActions └── ResourceActivity ``` --- # 83. Agent UI Package ```text packages/agent-ui/ ├── AgentList ├── AgentDetail ├── AgentChat ├── AgentGoal ├── AgentRun ├── AgentTrace └── AgentApproval ``` --- # 84. Plugin UI Package ```text packages/plugin-ui/ ├── PluginPage ├── PluginSettings ├── PluginWidget ├── PluginNavigation ├── PluginContextAction └── PluginErrorBoundary ``` --- # 85. 不允许的架构 以下全部禁止： ```text ❌ 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. 推荐架构 最终： ```text 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 不是： ```text 一个 Admin Dashboard ``` 而是： ```text 一个可扩展的 UI Runtime ``` 核心能力： ```text Shell + Registry + Route + Navigation + Resource UI + Action UI + Task UI + Agent UI + Plugin UI + Widget + Command + Context Action ``` 最终实现： ```text 安装 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： ```text AppRegistry.register() ``` 并自动出现 Navigation。 --- ## AC-02 可以动态注册 Plugin。 Plugin 安装后自动出现： ```text Route Navigation Settings Widget ``` --- ## AC-03 Plugin 禁用后： ```text Navigation 消失 Route 不可访问 Widget 不再显示 ``` 且不能导致 Shell 崩溃。 --- ## AC-04 实现： ```text Resource List Resource Detail Resource Create Resource Edit ``` 并能读取 Resource Metadata。 --- ## AC-05 Resource Action 必须通过： ```text Action Runtime ``` 执行。 --- ## AC-06 实现： ```text Task Detail Execution Detail Progress Logs Output ``` --- ## AC-07 实现： ```text Command Palette ``` 至少支持： ```text Navigation Action Resource Agent ``` --- ## AC-08 实现： ```text Global Search ``` 支持： ```text Resource Task Agent Plugin Action ``` --- ## AC-09 实现： ```text Widget Slot ``` 至少支持： ```text dashboard.main dashboard.sidebar resource.detail.toolbar resource.list.toolbar ``` --- ## AC-10 实现： ```text Context Action ``` 例如： ```text seo.website ↓ Open Browser Scan SEO Ask Agent ``` --- ## AC-11 实现： ```text Plugin Settings ``` Plugin 可以拥有自己的： ```text /settings/plugins/{pluginId} ``` --- ## AC-12 实现： ```text PermissionGuard ``` 并确保： > Frontend Permission 仅用于 UI，Backend Authorization 才是最终安全边界。 --- ## AC-13 实现： ```text Agent Chat Agent Goal Agent Run Agent Trace Agent Approval ``` 并与 DevOS Agent Runtime 对接。 --- ## AC-14 实现： ```text Workspace Context ``` 支持： ```text Organization Project Environment ``` --- ## AC-15 实现 Plugin Error Boundary。 单个 Plugin 崩溃不能导致整个 DevOS Shell 崩溃。 --- ## AC-16 实现 Lazy Loading。 Plugin UI 不应该在 DevOS 首屏全部加载。 --- ## AC-17 实现完整 UI Registry： ```text AppRegistry ModuleRegistry RouteRegistry NavigationRegistry WidgetRegistry CommandRegistry ContextActionRegistry ``` --- ## AC-18 至少完成以下 Demo： ### Demo A 安装： ```text GitHub Plugin ``` 自动出现： ```text GitHub ├── Repositories ├── Issues └── Settings ``` --- ### Demo B GitHub Plugin 注册： ```text dashboard.main ``` Widget。 Dashboard 自动显示。 --- ### Demo C SEO Website： ```text example.com ``` 右上角自动出现： ```text Open Browser Scan SEO Ask Agent ``` --- ### Demo D Command Palette： ```text Cmd/Ctrl + K ``` 输入： ```text scan example.com ``` 可以发现： ```text SEO Scan ``` 并执行： ```text seo.website.scan ``` --- ### Demo E Agent： ```text 检查 example.com 的 SEO ``` UI 显示： ```text Goal ↓ Plan ↓ Action ↓ Task ↓ Execution ↓ Report ``` --- # 89. Zcode 开发优先级 严格按照： ```text P0 ├── UI Shell ├── Registry ├── Route ├── Navigation ├── Permission ├── API Client └── Action UI P1 ├── Resource UI ├── Task UI ├── Plugin UI ├── Widget ├── Settings └── Context Action P2 ├── Agent UI ├── Command Palette ├── Global Search ├── Workspace └── Approval UI P3 ├── Advanced Dashboard ├── UI Marketplace ├── Dynamic UI Schema └── Advanced Extension System ``` --- # 90. 最终 Golden Rule DevOS 前端必须遵守： ```text Shell 不知道业务 App 不拥有 Shell Plugin 不修改 Core Module 不绕过 App UI 不实现业务逻辑 UI 不直接访问 DB UI 不绕过 Action Runtime Agent UI 不绕过 Agent Runtime Frontend Permission 不等于 Security ``` 真正的扩展模型： ```text DevOS Core │ UI Runtime │ ┌─────────────┼─────────────┐ │ │ │ App Plugin Agent │ │ │ └─────────────┼─────────────┘ │ Registry │ ┌─────────────┼─────────────┐ │ │ │ Route Navigation Widget │ │ │ └─────────────┼─────────────┘ │ Action Runtime │ DevOS Backend ``` 最终目标： > **开发者只需要开发 Resource / Action / Skill / Plugin / App，而不需要重复开发 Admin、Layout、Navigation、Task、Agent、Settings、Permission、Search、Notification 等基础设施。** 这才是 DevOS UI Shell 的核心价值。