# 前后端 ConnectRPC 重构完整方案

## 1. 目标

本方案重构桌面端、前端、本机控制面、代理层和具体服务端实现之间的边界。

最终目标如下：

1. 前端业务通信全部使用 ConnectRPC，不再使用任何 Wails 业务 IPC。
2. `internal/startup` 只负责依赖组装、启动顺序、运行时注册和优雅退出。
3. 操作系统与 Wails 能力统一收敛到 `internal/platform`。
4. `internal/backend/app` 只负责产品级本机控制面。
5. Cursor 协议、Agent 和 Prompt 全部归 `internal/backend/cursor`。
6. Runtime 是通用服务运行时，不绑定 Cursor，也不使用“Cursor backend”作为领域名称。
7. 当前 Cursor Host 与 MITM 只是一个 Runtime 实现，未来可以并列注册 Devin 等实现。
8. Cursor Host 未处理的接口返回 `404`；代理层未命中的请求原样转发到原始上游。

## 2. 强制边界

### 2.1 禁止业务 IPC

前端禁止继续使用以下能力：

```text
@bindings
Call.ByName
Events.On
Events.Emit
application.NewService
```

Wails 只负责桌面应用生命周期和 WebView，不再承载配置、运行时、模型或事件等业务接口。

### 2.2 Runtime 不绑定 Cursor

`backend/app/runtime.go` 表达的是通用运行时用例：

- 列出可用运行时；
- 启动、停止和重启指定运行时；
- 查询状态和最近一次错误；
- 向前端发布运行时状态变化。

它不能出现以下设计：

```text
CursorBackend
StartCursor
StopCursor
CursorMITMStatus
```

Cursor Host、MITM 和系统代理的组合只存在于启动装配阶段，不进入 App 的通用 DTO。

## 3. 总体架构

```mermaid
flowchart LR
    UI["Frontend"] -->|"ConnectRPC"| APP["app.v1.AppService"]

    APP --> APPDOMAIN["backend/app"]

    APPDOMAIN -->|"RuntimeController"| SUPERVISOR["startup.Supervisor"]
    SUPERVISOR --> CURSORRT["Cursor Runtime"]
    SUPERVISOR --> DEVINRT["Devin Runtime"]
    SUPERVISOR --> FUTURERT["Future Runtime"]

    CURSORRT --> CURSORHOST["Cursor Host"]
    CURSORRT --> MITM["MITM"]
    CURSORRT --> SYSPROXY["platform/network"]

    CURSORIDE["Cursor IDE"] --> MITM
    MITM -->|"模型和 Agent 路由"| CURSORHOST
    MITM -->|"其他请求原样转发"| UPSTREAM["原始上游"]
```

## 4. 目标目录

```text
internal/
├── startup/
│   ├── bootstrap.go
│   ├── wiring.go
│   └── supervisor.go
│
├── platform/
│   ├── desktop/
│   │   ├── app.go
│   │   ├── window.go
│   │   ├── tray.go
│   │   └── browser.go
│   ├── filesystem/
│   │   ├── paths.go
│   │   └── migrate.go
│   ├── network/
│   │   └── system_proxy.go
│   └── update/
│       └── installer.go
│
├── backend/
│   ├── app/
│   │   ├── host.go
│   │   ├── module.go
│   │   ├── service.go
│   │   ├── snapshot.go
│   │   ├── events.go
│   │   ├── config.go
│   │   ├── runtime.go
│   │   ├── model.go
│   │   ├── update.go
│   │   ├── desktop.go
│   │   ├── repository.go
│   │   ├── proto/
│   │   │   ├── app_v1.proto
│   │   │   └── types_v1.proto
│   │   └── gen/appv1/
│   │
│   ├── cursor/
│   │   ├── module.go
│   │   ├── host.go
│   │   ├── prompt/
│   │   ├── llm/
│   │   ├── loop/
│   │   ├── store/
│   │   ├── transport/
│   │   ├── proto/
│   │   │   ├── agent_v1.proto
│   │   │   ├── aiserver_v1.proto
│   │   │   ├── from_extensions/
│   │   │   ├── extractor/
│   │   │   └── scripts/
│   │   └── gen/
│   │       ├── agentv1/
│   │       └── aiserverv1/
│   │
│   └── devin/
│       └── .gitkeep
│
└── proxy/
    ├── server.go
    ├── router.go
    ├── passthrough.go
    └── certificate.go
```

前端目标目录如下：

```text
frontend/src/rpc/
├── transport.js
├── appClient.js
├── watch.js
└── gen/
    └── appv1/
```

`backend/app` 保持单一扁平 Go package，不按配置、模型等功能继续拆子目录。只有 protobuf 源文件和生成代码保留独立目录。

## 5. 模块职责

### 5.1 `internal/startup`

`startup` 是唯一组合根，负责：

- 创建数据库连接；
- 执行各模块声明的迁移；
- 创建 App、Cursor、Proxy 和 Platform 实例；
- 注入模块依赖；
- 注册所有 Runtime 实现；
- 确定启动和停止顺序；
- 捕获退出信号并等待资源释放。

`startup` 不负责窗口、托盘、浏览器、系统代理命令等具体平台操作，这些能力必须通过 `platform` 注入。

### 5.2 `internal/platform`

`platform` 只包装本机和操作系统能力：

- `desktop`：Wails、窗口、托盘和浏览器；
- `filesystem`：数据目录、配置目录、日志目录和文件迁移；
- `network`：系统代理读取、设置和恢复；
- `update`：安装包验证与执行。

只有 `platform/desktop` 可以直接导入 Wails application API。`platform` 不依赖 protobuf、AppService 或 Cursor 协议。

### 5.3 `internal/backend/app`

App 是产品级本机控制面，负责：

- 产品配置；
- 通用 Runtime 控制；
- BYOK 模型配置和连通性测试；
- 应用更新状态；
- 受控桌面动作；
- App 快照和 App 事件流。

App 不负责：

- Cursor IDE 协议；
- MITM 实现；
- 具体 Runtime 的启停细节；
- 操作系统命令。

### 5.4 `internal/backend/cursor`

Cursor 模块拥有所有 Cursor 专属语义：

- Cursor Host 路由；
- Cursor Connect、Bidi 和 RunSSE 协议；
- Agent Loop、Prompt、LLM 和会话存储；
- Cursor 提取的 protobuf 和生成代码。

Cursor 不导入 `backend/app`。需要模型目录等通用数据时，由 Cursor 自己声明小接口，再由 `startup` 注入实现。

### 5.5 `internal/proxy`

Proxy 是通用代理基础设施，不导入 Cursor package。

Cursor 模块提供它能处理的路由集合，`startup` 将路由匹配器和目标地址注入 Proxy。未命中的请求必须保留原请求的 method、path、query、header、body 和流式响应语义，并发送到原始上游。

## 6. Runtime 设计

### 6.1 App 侧端口

`backend/app/runtime.go` 定义通用端口：

```go
// RuntimeController 管理已注册的服务运行时。
type RuntimeController interface {
	List(context.Context) ([]RuntimeDescriptor, error)
	Start(context.Context, string) error
	Stop(context.Context, string) error
	Restart(context.Context, string) error
	Status(context.Context, string) (RuntimeStatus, error)
}
```

Runtime DTO 只包含通用字段：

```text
RuntimeDescriptor {
  id
  kind
  state
  capabilities
  endpoint
  last_error
  revision
}
```

其中 `id` 标识一个配置实例，`kind` 标识实现类型，例如 `cursor` 或 `devin`。App 和前端不能根据 Cursor 专属字段决定运行时流程。

### 6.2 Supervisor

`startup/supervisor.go` 实现 `RuntimeController`，维护 Runtime 注册表和状态机：

```text
Stopped -> Starting -> Running -> Stopping -> Stopped
                     -> Failed
```

必须满足：

- 同一个 Runtime 的启停操作串行执行；
- 重复 Start 和 Stop 具有幂等语义；
- 启动中途失败时回滚已经启动的组件；
- Stop 按 Start 的逆序执行；
- 状态变化携带递增 revision；
- 应用退出时统一停止所有已启动 Runtime。

### 6.3 当前 Cursor Runtime

当前在 `startup/wiring.go` 注册一个 `kind=cursor` 的 Runtime。它的启动顺序为：

1. 校验 Cursor 和模型配置；
2. 启动 Cursor Host；
3. 启动 MITM；
4. 根据配置启用系统代理；
5. 发布 Running 状态。

停止时按相反顺序恢复系统代理、停止 MITM、停止 Cursor Host。

Cursor Host 和 MITM 是当前实现的内部组件，不应被命名为整个 Runtime。未来接入 Devin 时，只需注册新的 Runtime 实现，不修改 AppService 协议。

## 7. ConnectRPC 服务面

### 7.1 `app.v1.AppService`

第一阶段使用明确方法，不提供通用 JSON Invoke：

```text
Bootstrap
Watch
GetConfig
UpdateConfig
ListRuntimes
GetRuntime
StartRuntime
StopRuntime
RestartRuntime
ListModels
SaveModel
DeleteModel
TestModel
GetAds
GetUpdate
CheckUpdate
InstallUpdate
OpenWindow
OpenExternal
```

App 的 `Watch` 第一条消息是完整 App 快照，后续发送带 revision 的增量事件：

```text
snapshot
config_changed
runtime_changed
model_changed
ads_changed
update_changed
```

### 7.2 Cursor IDE 协议服务

Cursor IDE 使用独立 Host。该 Host 只注册：

- 模型列表接口；
- Agent BidiAppend 接口；
- Agent RunSSE 接口。

其他路径全部返回 `404`，不能做代理兜底。代理兜底只能发生在 Proxy 层。

## 8. 两个本地 Host

### 8.1 App Host

App Host 绑定随机回环地址 `127.0.0.1:0`，负责：

- 提供前端静态资源；
- 注册 AppService；
- 校验 Origin 和本地会话；
- 提供 ConnectRPC 流式响应。

桌面启动时生成一次性 bootstrap token。WebView 首次访问 bootstrap 地址后，Host 写入 `HttpOnly`、`SameSite=Strict` Cookie，并重定向到普通首页。前端代码不长期保存 token。

### 8.2 Cursor Host

Cursor Host 绑定 Cursor 配置要求的本机地址，只服务 Cursor IDE 协议。它与 App Host 使用不同的路由表和认证规则。

## 9. 前端架构

前端只保留 `appClient`，负责配置、Runtime、模型、更新和桌面动作。

启动流程如下：

1. 创建同源 Connect-Web transport；
2. 调用 AppService `Bootstrap`；
3. 启动 `Watch`；
4. 按 revision 丢弃重复或乱序事件；
5. 流断开后退避重连，并重新取得完整快照。

前端不导入 Wails runtime，也不通过全局事件总线传递后端状态。

## 10. 数据库与依赖注入

启动过程固定为：

1. `platform/filesystem` 解析数据路径；
2. `startup` 打开数据库连接；
3. App 和 Cursor 分别提供自己的迁移集合；
4. `startup` 按版本执行迁移；
5. 创建 App Repository 和 Cursor Repository；
6. 将接口注入对应 Service；
7. 注册 ConnectRPC Handler；
8. 启动 App Host 和桌面窗口。

模块只能访问自己拥有的表。跨模块调用使用接口，不共享数据库 DTO。

## 11. Proto 和生成代码

新建的产品控制协议位于：

```text
internal/backend/app/proto
internal/backend/app/gen
```

所有 Cursor 专属协议位于：

```text
internal/backend/cursor/proto
internal/backend/cursor/gen
```

当前根目录的 `proto`、`gen` 以及协议提取器都要迁入 Cursor 模块。提取器必须按 parser、symbols、renderer 等职责拆分，单文件禁止超过 500 行。

前端只生成 AppService 所需的 Web 客户端，不把 Cursor IDE 上游协议暴露给 UI。

## 12. 依赖方向

允许的依赖方向如下：

```text
main -> startup
startup -> platform
startup -> backend/app
startup -> backend/cursor
startup -> proxy

frontend -> app.v1

backend/app -> 自己声明的端口
backend/cursor -> 自己声明的端口
proxy -> 注入的路由和目标接口
```

禁止以下依赖：

```text
backend/app -> backend/cursor
backend/cursor -> backend/app
platform -> backend
platform -> protobuf
proxy -> backend/cursor
任何业务包 -> startup
```

## 13. 现有代码迁移映射

```text
internal/app/runner.go
  -> startup/bootstrap.go
  -> startup/wiring.go
  -> platform/desktop/*

internal/bridge/*
  -> 删除

internal/client 中的产品配置、模型、更新
  -> backend/app 对应文件

internal/appdata
  -> platform/filesystem

系统代理操作
  -> platform/network

更新状态与检查
  -> backend/app/update.go

安装命令
  -> platform/update/installer.go

根 proto、gen 和提取器
  -> backend/cursor/proto
  -> backend/cursor/gen
```

## 14. TDD 实施顺序

### 阶段一：建立架构守卫

先写失败测试，检查：

- 前端禁止的 Wails IPC 标识；
- App 与 Cursor 禁止互相导入；
- Wails application API 只能出现在 `platform/desktop`；
- 根目录不再存在 Cursor `proto` 和 `gen`；
- 所有手写源码不超过 500 行。

### 阶段二：建立 App ConnectRPC Host

先测试再实现：

- loopback 随机端口；
- bootstrap token 换取 Cookie；
- AppService unary 调用；
- Watch 首包快照和 revision；
- 非法 Origin 和无会话请求拒绝。

### 阶段三：实现通用 Runtime

使用两个 Fake Runtime 先验证：

- 注册和列出多个 kind；
- 幂等 Start 和 Stop；
- 并发操作串行化；
- 部分启动失败回滚；
- 逆序停止；
- 状态 revision；
- Cursor Runtime 和 Devin Runtime 不需要修改 AppService。

然后再把 Cursor Host、MITM 和系统代理接入 Cursor Runtime。

### 阶段四：切换前端

先为 RPC 状态层编写测试，再替换现有 bindings 和 Events。切换完成后删除 `internal/bridge` 与所有 Wails 业务服务注册。

### 阶段五：迁移 Cursor Proto

迁移 Cursor IDE 协议源文件、生成代码和提取器，并使用协议 fixture 验证迁移前后字节结果一致。

### 阶段六：清理和集成验证

删除旧接口、旧事件、旧生成代码和空目录，运行完整单元测试、集成测试、静态检查与编码风格检查。

## 15. 必须覆盖的测试

### App Host

- 首次 bootstrap 成功且 token 只能使用一次；
- Connect unary 和 server stream 可用；
- 重连后重新获得完整快照；
- Host 停止后连接和 goroutine 全部退出。

### Runtime

- 多种 Runtime 并存；
- 状态转换合法；
- Cursor 启动顺序正确；
- Cursor 停止顺序与启动相反；
- MITM 启动失败时 Cursor Host 被回滚；
- 应用退出时所有 Runtime 被停止。

### Cursor Host 与 Proxy

- 模型列表和 Agent 接口可访问；
- Cursor Host 的其他路径返回 `404`；
- Proxy 只拦截 Cursor Host 明确支持的路由；
- 其他请求的 method、path、query、header、body、status 和响应流保持透传语义。

### 前端

- 不存在 Wails bindings 和业务 Events；
- App 状态订阅只通过 AppService；
- 重复 revision 不会重复更新状态；
- 断流后可以恢复快照和订阅。

## 16. 完成标准

满足以下条件才算重构完成：

1. 前端业务链路全部经过 ConnectRPC。
2. `internal/bridge` 已删除。
3. `backend/app` 只包含产品级配置、Runtime 和桌面控制能力。
4. Runtime API、DTO、状态和测试均不绑定 Cursor。
5. Cursor Host 与 MITM 只作为已注册 Runtime 的当前实现。
6. Cursor 专属 proto、gen 和提取器全部位于 `backend/cursor`。
7. Cursor Host 未注册路径稳定返回 `404`。
8. Proxy 未命中请求稳定透传到原始上游。
9. 只有 `platform/desktop` 直接使用 Wails application API。
10. 所有新增和调整的源码、测试均使用简洁中文注释，单文件不超过 500 行。