OpenPanel

OpenPanel 是一个多宿主项目，核心目标是复用同一套 protocol + channel + DI + transport 基座，在 node 与 electron 宿主上承载正式业务。

当前仓库已经从“架构验证工程”收口为“正式应用壳工程”：首页不再展示协议测试页和 container demo，而是只展示运行状态，等待正式业务模块继续接入。

当前能力

• 多宿主：node / electron
• 多传输：browser 侧 HTTP + SSE，Electron 侧 IPC
• 统一协议：PersistentProtocol + ProtocolMessage
• 统一服务接入：ServiceCollection + InstantiationService + SyncDescriptor
• 统一服务暴露：ChannelServer + ProxyChannel
• 对外接口层：/openpanel/global/*
• 前端正式壳：首页只展示 runtime status

当前目录重点

src/
  base/
    common/

  platform/
    protocol/common/
    ipc/common/
    instantiation/common/
    transport/
      browser/
      electron-browser/
      electron-main/
      http/
      node/

  workbench/
    services/
      common/
        serviceRegistry.ts
        createConfiguredChannelServer.ts
        runtimeOverrides.ts
      runtimeStatus/
        common/
          runtimeStatus.ts
          runtimeStatusDefinition.ts
          runtimeStatusService.ts
    external/
      common/
        createExternalRuntime.ts
        alert.ts
        alertService.ts
        health.ts
        healthService.ts
        externalApi.ts
      node/
        registerExternalApiRoutes.ts
      electron/
        startExternalApiServer.ts
        electronAlertBridge.ts

  server/node/
    remoteAgentMain.ts

  hosts/
    node/main.ts
    electron/main.ts
    electron/createDesktopChannels.ts

  frontend/
    App.tsx
    application/
      client.ts
      types.ts
    infrastructure/
      openpanelClient.ts
      protocol/
        createProtocolClient.ts
      transport/
        resolveTransport.ts
      adapters/
        runtimeStatusAdapter.ts
    host/
      types.ts

架构分层

1. platform foundation

• src/base/common/*
• src/platform/protocol/*
• src/platform/ipc/*
• src/platform/instantiation/*
• src/platform/transport/*

这几层是项目底座，负责协议、通道、DI 和传输，不承载 demo 页面职责。

2. workbench services

src/workbench/services/* 承载真正暴露给前端的业务 service。当前保留的正式 service 是：

• runtimeStatus

它通过 HealthService.snapshot() 向前端提供运行状态。

3. external

src/workbench/external/* 是独立外部边界，负责：

• external HTTP routes
• alert/health 模型
• 宿主级 external runtime 装配
• Electron embedded external API server

4. frontend shell

前端当前是正式壳，而不是协议测试台：

• App.tsx 只展示 runtime status
• application/* 暴露前端消费合同
• infrastructure/* 承接 protocol / transport / adapter 细节

依赖方向应保持为：

App.tsx
  -> frontend/application/*
  -> frontend/infrastructure/*
  -> platform/* + workbench/*

宿主启动方式

Node 宿主

• 入口：src/hosts/node/main.ts
• 实际服务启动：src/server/node/remoteAgentMain.ts

Node 模式会：

1. 创建 external runtime
2. 创建 configured channel server
3. 在同一个 Hono app 上挂载 external routes、protocol routes 和前端静态资源
4. 对外监听 HTTP 端口

Electron 宿主

• 入口：src/hosts/electron/main.ts

Electron 模式会：

1. 创建 external runtime
2. 创建 desktop channel server
3. 注册 Electron IPC protocol server
4. 启动 embedded external API server
5. 通过 app://openpanel/ 加载 renderer

架构文档

详细架构说明已经拆到多层文档中：

• AGENTS.md
• docs/architecture/INDEX.md
• docs/architecture/platform-foundation.md
• docs/architecture/runtime-shell.md
• docs/architecture/service-surface.md
• docs/architecture/hosts-and-runtime.md
• docs/architecture/verification.md

开发命令

npm run typecheck
npm run build
npm run start:node
npm run start:electron

发布版本

scripts/release.js 通过 npm run release -- <version> 调用。执行前需要确保当前 git 工作区干净，并且不能处于 detached HEAD。

示例：

npm run release -- 0.2.93

脚本会依次执行：

1. npm version <version> --no-git-tag-version 更新 package.json 和 package-lock.json。
2. npm run typecheck。
3. npm run build。
4. 提交版本文件，提交信息为 release: v<version>。
5. 创建 v<version> tag。
6. 推送当前分支和对应 tag 到 origin。

示例：

curl "http://127.0.0.1:8787/openpanel/global/health"