Super Dolphin Harness Driver

设计目标

Super Dolphin 是面向 AI coding harness 的 Harness Driver：它位于人的方向、Harness 执行与仓库验收之间。项目采用明确的开发模型：AI 编写和重构原创产品代码、测试与项目自有文档，人类保留产品、安全、凭据和发布决策权，仓库拥有可执行的接受规则。为了让这种协作能够长期持续，Driver 必须同时提供：

可以驱动 Codex 并通过 Harness Orch 编排、观察子 Agent 工作的运行时。
可以按有界上下文理解的代码库。
能确定性证明变更遵守仓库契约的验收证据。

因此，系统优先采用窄端口、明确所有权、fail-fast 错误、生成式导航和可执行边界规则。

系统总览

frontend-app/             React / Vite desktop UI
        |
cmd/agent-terminal/       Wails host + typed RPC boundary
        |
internal/app/             composition + anti-corruption adapters
        |
internal/contract/        stable ports, events and DTOs
        |
internal/module/          thread / turn / memory / skill / workflow
   |             |
internal/store/   internal/provider/
SQLite + sqlc     Codex and provider runtimes

cmd/mcp-lsp/              seven-tool, workspace-scoped LSP service
cmd/mcp-orch/             Codex-integrated Harness Orch, DAG and task tools

桌面链路负责把用户操作送入类型化后端边界；MCP peers 则把代码理解与编排能力提供给可信工作区中的 Agent。两条入口最终都依赖相同的所有权、契约和失败语义。

组件职责

区域	负责	不应拥有
`frontend-app`	React/Vite 用户界面	后端生命周期、数据库句柄、Provider 进程
`cmd/agent-terminal`	桌面入口、Wails 主机、前端嵌入、RPC 边界	业务模块应拥有的规则
`internal/app`	依赖装配与防腐适配器	新产品能力或持久化 schema
`internal/contract`	稳定 port、事件与 DTO 契约	对模块、Provider、Store、UI 或命令入口的反向依赖
`internal/module`	Thread、Turn、Cron、Memory、Skill、Prompt 等产品能力	Store 实现或数据库所有权
`internal/platform`	RPC、配置、事件、进程安全与可观测性	产品模块或 Store 依赖
`internal/provider`	Codex 与其他 Provider 的运行时和传输集成	产品数据库所有权
`internal/store`	SQLite/sqlc 持久化适配器	属于业务模块的策略
`cmd/mcp-lsp`	七工具、工作区隔离的 LSP 服务；声明 27 个 primary language 路由入口	把入口数量写成 27 种完整语言支持，或复用相邻 worktree 状态
`cmd/mcp-orch`	Codex 集成的 Harness Orch、Agent 生命周期、Workflow、DAG 与调度工具	把 Claude/Antigravity 或其他 Harness 写成已支持的完整 Orch

依赖方向

业务模块拥有自己需要的 port；Store、Provider 和运行时适配器从 internal/app 完成实现或桥接。产品行为因此不依赖某一种数据库、Provider 进程或 UI 主机。

entrypoints -> app composition -> contract-owned ports <- modules
                                      ^
                                      |
                         store / provider / platform adapters

这张图只是阅读模型。真正可执行的边界真源是 internal/archtest 使用的类型化后端边界注册表；生成的架构地图只是它的派生视图。若派生文件过期，检查应该失败，而不是允许手工修改生成结果。

关键运行流

桌面请求

React UI 调用类型化后端 bridge。
桌面 RPC 层校验并转换请求。
业务模块或面向契约的应用适配器拥有本次操作。
持久化与 Provider 工作通过注入的 port 完成。
类型化事件和 RPC 响应更新 UI。

缺少能力、身份、所有权或配置时必须返回错误，不能通过旧路径或空默认值制造成功。

Agent 工具请求

Provider session 请求一个允许的工具。
Toolbridge 校验 session 与运行时所有权。
MCP peers 在可信工作区内执行代码智能或编排操作。
结果返回时保留协议级错误。
本地运行时与 UI 可以保留相关 trace 和证据。

Worktree scope 是信任边界的一部分。来自相邻 checkout 的 LSP 结果，即使语法上看起来正确，也被视为不安全证据。

持久工作流

Workflow 与自动化状态保存在 SQLite。运行时使用明确的生命周期所有权、乐观并发、租约和恢复规则，而不是只依赖内存任务。只有持久身份与必要运行时状态都存在时，Agent 或 DAG 才能被描述为可恢复。

真源与失败语义

事实	规范真源
后端依赖边界	`internal/archtest` 类型化注册表
文件级导航	仓库树与 project-map 配置
Go 能力清单	源码符号与 capability-contract generator
运行时 port 与 DTO	`internal/contract`
持久化形态	migrations、SQL 与生成的 sqlc 代码
公开源码边界	`release/open-source-policy.json`

系统遵循 fail-fast 契约：无效配置阻止相关操作；缺少 Provider 或持久 Agent 身份时不回退到共享所有权；被吞掉的异步 UI 错误会被前端守卫拒绝；依赖和生命周期违规应在邻近变更面的测试中失败；任何绿色状态都必须说明对应命令和证据。

当前范围

架构与治理规则是为本仓库定制的，当前没有发布通用守卫包。
Provider 行为依赖已安装且已认证的 Provider CLI。
Codex 是当前完整 Driver 的集成默认路径；Claude 仍在适配且子 Agent Orch 不支持；Google Antigravity 只有 LSP client 配置。
27 个 primary language ID 是路由入口；多语言 LSP 深度取决于发行包、已安装 server、平台和上游 capability。
已检入的公开源码策略与验证基础并不等于端到端源码导出、密封 receipt 或公共发布已经完成。
通过守卫只证明已编码的不变量，不代表软件没有缺陷，也不能替代安全或发布评审。

下一步

继续阅读治理与证明，了解地图、契约、AST/SSA 守卫、测试和 Git 门禁如何把这套架构变成可执行的接受规则。

Harness Driver 架构