# wanqi-development/ai-coding-harness architecture

> Architecture diagram of the GitHub repository wanqi-development/ai-coding-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wanqi-development/ai-coding-harness
- Repository: https://github.com/wanqi-development/ai-coding-harness

## Overview

这是一个单用户 AI 编程助手：用户创建仓库会话后发送消息，服务判定意图并选择智能体形态；智能体可规划、委派编码与审查任务，在隔离沙箱中操作仓库，再将过程和结果通过 SSE 返回。同步意图则直接执行，不经过智能体。图保留了 README 描述的平台 PR、方案、记忆、只读代码浏览、OAuth 与可选 Redis 能力；部分实现未采样，相关连线仅依据 README 和可见源码。

Main entry points: [`src/ai_coding_harness/server/service.py`](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/service.py) (会话编排), [`src/ai_coding_harness/agent/graph.py`](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/graph.py) (主智能体), [`frontend/src/App.vue`](https://github.com/wanqi-development/ai-coding-harness/blob/main/frontend/src/App.vue) (聊天界面), [`src/ai_coding_harness/server/runs.py`](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/runs.py) (运行与流缓冲)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["接口与界面"]
  node_frontend["聊天界面<br/>[App.vue]"]
  node_repo_panel["代码面板<br/>[RepoPanel.vue]"]
  node_api_routes["HTTP 路由<br/>[chat.py]"]
  node_repo_routes["仓库路由<br/>[repo.py]"]
  node_auth_routes["OAuth 路由<br/>[auth.py]"]
end

subgraph group_workflow["意图与智能体"]
  node_service["会话编排<br/>[service.py]"]
  node_intent["意图判定<br/>[intent.py]"]
  node_manager["会话与运行时<br/>[manager.py]"]
  node_profiles["形态配置<br/>[profiles.py]"]
  node_agent_graph["主智能体<br/>[graph.py]"]
  node_subagents["子智能体<br/>[subagents.py]"]
  node_middleware["安全与防护"]
  node_tools["工具注册与执行<br/>[register.py]"]
end

subgraph group_workspace["工作区与代码"]
  node_sandbox_runtime["沙箱工作区<br/>[provider.py]"]
  node_sandbox_backend["文件后端<br/>[composite.py]"]
  node_repo_cache[("只读仓库缓存<br/>[repo_cache.py]")]
end

subgraph group_integrations["外部集成"]
  node_llm["角色模型路由<br/>[llm.py]"]
  node_pr_clients["Gitee 与 GitHub 客户端<br/>[pr_client.py]"]
end

subgraph group_state["持久化与运行"]
  node_database[("业务数据库<br/>[engine.py]")]
  node_runhub["运行与流缓冲<br/>[runs.py]"]
  node_stream["SSE 事件转换<br/>[stream.py]"]
end

node_user(("用户"))
node_platforms{{"代码平台"}}
node_sandbox_service{{"OpenSandbox"}}
node_redis[("Redis（可选）")]

node_user -->|"发送请求"| node_frontend
node_frontend -->|"调用聊天接口"| node_api_routes
node_api_routes -->|"启动或续订"| node_runhub
node_runhub -->|"运行一轮"| node_service
node_service -->|"判定意图"| node_intent
node_service -->|"取得会话运行时"| node_manager
node_manager -->|"选择形态"| node_profiles
node_manager -->|"构建智能体"| node_agent_graph
node_agent_graph -->|"请求角色模型"| node_llm
node_agent_graph -->|"经由中间件"| node_middleware
node_agent_graph -->|"调用工具"| node_tools
node_agent_graph -->|"委派任务"| node_subagents
node_subagents -->|"请求角色模型"| node_llm
node_tools -->|"读写沙箱文件"| node_sandbox_backend
node_sandbox_backend -->|"执行文件操作"| node_sandbox_runtime
node_sandbox_runtime -->|"创建与执行"| node_sandbox_service
node_tools -->|"调用 PR 操作"| node_pr_clients
node_pr_clients -->|"查询或变更 PR"| node_platforms
node_service -->|"读写业务记录"| node_database
node_service -->|"翻译运行事件"| node_stream
node_runhub -->|"发布事件帧"| node_stream
node_runhub -.->|"跨进程缓冲与锁"| node_redis
node_frontend -->|"请求仓库视图"| node_repo_routes
node_repo_panel -->|"读取目录与文件"| node_repo_routes
node_repo_routes -->|"查询或同步缓存"| node_repo_cache
node_repo_cache -->|"克隆或获取仓库"| node_platforms
node_frontend -->|"发起授权"| node_auth_routes
node_auth_routes -->|"OAuth 授权"| node_platforms

click node_frontend "https://github.com/wanqi-development/ai-coding-harness/blob/main/frontend/src/App.vue"
click node_repo_panel "https://github.com/wanqi-development/ai-coding-harness/blob/main/frontend/src/RepoPanel.vue"
click node_api_routes "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/chat.py"
click node_repo_routes "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/repo.py"
click node_auth_routes "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/auth.py"
click node_service "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/service.py"
click node_intent "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/intent.py"
click node_manager "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/session/manager.py"
click node_profiles "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/profiles.py"
click node_agent_graph "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/graph.py"
click node_subagents "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/subagents.py"
click node_middleware "https://github.com/wanqi-development/ai-coding-harness/tree/main/src/ai_coding_harness/agent/middleware"
click node_tools "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/tools/register.py"
click node_sandbox_runtime "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/sandbox/provider.py"
click node_sandbox_backend "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/backends/composite.py"
click node_repo_cache "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/repo_cache.py"
click node_llm "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/llm.py"
click node_pr_clients "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/tools/pr_client.py"
click node_database "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/db/engine.py"
click node_runhub "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/runs.py"
click node_stream "https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/stream.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_repo_panel,node_api_routes,node_repo_routes,node_auth_routes toneBlue
class node_service,node_intent,node_manager,node_profiles,node_agent_graph,node_subagents,node_middleware,node_tools,node_redis toneAmber
class node_sandbox_runtime,node_sandbox_backend,node_repo_cache toneMint
class node_llm,node_pr_clients toneRose
class node_database,node_runhub,node_stream,node_user,node_platforms,node_sandbox_service toneIndigo
```

## Components

### 接口与界面

- [聊天界面](https://github.com/wanqi-development/ai-coding-harness/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [代码面板](https://github.com/wanqi-development/ai-coding-harness/blob/main/frontend/src/RepoPanel.vue): `frontend/src/RepoPanel.vue`
- [HTTP 路由](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/chat.py): `src/ai_coding_harness/api/routes/chat.py`
- [仓库路由](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/repo.py): `src/ai_coding_harness/api/routes/repo.py`
- [OAuth 路由](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/api/routes/auth.py): `src/ai_coding_harness/api/routes/auth.py`

### 意图与智能体

- [会话编排](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/service.py): `src/ai_coding_harness/server/service.py`
- [意图判定](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/intent.py): `src/ai_coding_harness/server/intent.py`
- [会话与运行时](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/session/manager.py): `src/ai_coding_harness/session/manager.py`
- [形态配置](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/profiles.py): `src/ai_coding_harness/agent/profiles.py`
- [主智能体](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/graph.py): `src/ai_coding_harness/agent/graph.py`
- [子智能体](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/subagents.py): `src/ai_coding_harness/agent/subagents.py`
- [安全与防护](https://github.com/wanqi-development/ai-coding-harness/tree/main/src/ai_coding_harness/agent/middleware): `src/ai_coding_harness/agent/middleware`
- [工具注册与执行](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/tools/register.py): `src/ai_coding_harness/tools/register.py`

### 工作区与代码

- [沙箱工作区](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/sandbox/provider.py): `src/ai_coding_harness/sandbox/provider.py`
- [文件后端](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/backends/composite.py): `src/ai_coding_harness/backends/composite.py`
- [只读仓库缓存](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/repo_cache.py): `src/ai_coding_harness/repo_cache.py`

### 外部集成

- [角色模型路由](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/agent/llm.py): `src/ai_coding_harness/agent/llm.py`
- [Gitee 与 GitHub 客户端](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/tools/pr_client.py): `src/ai_coding_harness/tools/pr_client.py`

### 持久化与运行

- [业务数据库](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/db/engine.py): `src/ai_coding_harness/db/engine.py`
- [运行与流缓冲](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/server/runs.py): `src/ai_coding_harness/server/runs.py`
- [SSE 事件转换](https://github.com/wanqi-development/ai-coding-harness/blob/main/src/ai_coding_harness/stream.py): `src/ai_coding_harness/stream.py`

### Other components

- **用户**
- **代码平台**
- **OpenSandbox**
- **Redis（可选）**

## Connections

- 用户 → 聊天界面: 发送请求
- 聊天界面 → HTTP 路由: 调用聊天接口
- HTTP 路由 → 运行与流缓冲: 启动或续订
- 运行与流缓冲 → 会话编排: 运行一轮
- 会话编排 → 意图判定: 判定意图
- 会话编排 → 会话与运行时: 取得会话运行时
- 会话与运行时 → 形态配置: 选择形态
- 会话与运行时 → 主智能体: 构建智能体
- 主智能体 → 角色模型路由: 请求角色模型
- 主智能体 → 安全与防护: 经由中间件
- 主智能体 → 工具注册与执行: 调用工具
- 主智能体 → 子智能体: 委派任务
- 子智能体 → 角色模型路由: 请求角色模型
- 工具注册与执行 → 文件后端: 读写沙箱文件
- 文件后端 → 沙箱工作区: 执行文件操作
- 沙箱工作区 → OpenSandbox: 创建与执行
- 工具注册与执行 → Gitee 与 GitHub 客户端: 调用 PR 操作
- Gitee 与 GitHub 客户端 → 代码平台: 查询或变更 PR
- 会话编排 → 业务数据库: 读写业务记录
- 会话编排 → SSE 事件转换: 翻译运行事件
- 运行与流缓冲 → SSE 事件转换: 发布事件帧
- 运行与流缓冲 → Redis（可选）: 跨进程缓冲与锁
- 聊天界面 → 仓库路由: 请求仓库视图
- 代码面板 → 仓库路由: 读取目录与文件
- 仓库路由 → 只读仓库缓存: 查询或同步缓存
- 只读仓库缓存 → 代码平台: 克隆或获取仓库
- 聊天界面 → OAuth 路由: 发起授权
- OAuth 路由 → 代码平台: OAuth 授权