CodePilot

CodePilot 是一个面向本地 Workspace 的多 Agent 软件开发系统。用户通过 Web 界面提交自然语言需求后，系统使用 LangGraph 编排规划、代码生成、测试生成、沙箱执行、代码审查、自动修复、变更审批和安全写回流程。

当前版本以 Windows 本地 Web 应用为主要运行形态，通过 Docker Desktop Linux Engine 为每个任务创建隔离的代码快照和执行环境。真实 Workspace 在最终审批前不会被直接修改。

核心能力

多 Agent 协作：Planner、Implementation、Test Generation、Test Solver、Code Review、Code Repair 和 Test Repair 各自使用经过裁剪的专属上下文。
动态 Capability 编排：Planner 只输出 Task Intent 和 Capability，系统通过 Registry、Plan Validator 与 Execution Policy 生成不可绕过安全门的 ExecutionPlan。
Specification 驱动：Requirement 与 Acceptance Criterion 使用任务内稳定 ID，并贯穿 TestEvidence、Failure Evidence、Review Issue 和 Repair Result。
测试证据治理：生成测试必须先通过确定性 Test Validation；Specification、已验证回归测试、生成契约测试和诊断测试具有明确权威等级。
Docker Sandbox：在任务专属快照中安装依赖并运行编译、导入检查、Ruff、Mypy、Bandit 和 Pytest。
修复权限隔离：Code Repair 仅能依据证据修改生产代码，Test Repair 仅能修改生成测试；需求冲突进入 HITL，需要扩大范围时返回 replan_required。
双重审批：Sandbox Patch 审批和最终 Workspace ChangeSet 审批相互独立，支持 Diff 检查、冲突检测和原子写回。
上下文治理：ContextManager 是统一的 State-to-Prompt 边界，支持 Workspace 文件选择、隐私过滤、Artifact 外置和 75/25 滚动压缩。
记忆与恢复：使用 LangGraph SQLite Checkpointer、Task Snapshot 和 Artifact 支持中断恢复，并提供 Global/Workspace 两级长期记忆。
可观测性：LangSmith 记录节点输入输出和 Agent 实际 LLM 输入输出；本地 Usage Dashboard 按 Task 和 Workspace 聚合 Token 与成本。
本地 Web 工作台：提供 Workspace 管理、任务执行、实时事件、代码浏览、变更审批、质量结果和用量查看。

系统架构

flowchart LR
    UI[React Web UI] --> API[FastAPI]
    API --> TSM[TaskSessionManager]
    TSM --> GR[GraphRuntime]
    GR --> LG[LangGraph Workflow]

    LG --> CM[ContextManager]
    CM --> LLM[OpenAI-Compatible LLM]
    LG --> SB[Docker Sandbox]
    LG --> MEM[Memory Manager]

    SB --> TOOLS[Compile / Import / Ruff / Mypy / Bandit / Pytest]
    LG --> CS[ChangeSet + Approval]
    CS --> WS[User Workspace]

    TSM --> DB[(SQLite)]
    GR --> LS[LangSmith]

Agent 工作流

flowchart TD
    START([User Request]) --> PLAN[Planner]
    PLAN -->|信息不足| CLARIFY[Human Clarify]
    CLARIFY --> PLAN
    PLAN --> PVAL[Plan Validator + Execution Policy]
    PVAL -->|Feature / Refactor| GEN[Implementation Agent]
    PVAL -->|Bug Fix| DIAG[Diagnosis Agent]
    PVAL -->|Test Generation| TGEN[Test Generation]
    PVAL -->|Review Only| REVIEW[Code Review]
    PVAL -->|Analysis Only| ANALYSIS[Analysis Agent]
    ANALYSIS --> FINAL[Final Summary]
    DIAG --> PREP[Prepare Sandbox]
    GEN --> TGEN
    TGEN --> TVAL[Deterministic Test Validation]
    TVAL --> PREP
    PREP -->|Generated artifacts| MAT[Materialize Code]
    PREP -->|Bug Fix| REPAIR[Code Repair Subgraph]
    MAT --> ENV[Plan / Approve / Build Environment]
    ENV --> TOOLS[Run Tool Pipeline]
    TOOLS --> TEST[Test Solver]
    TEST --> REVIEW
    REVIEW --> GATE{Deterministic Quality Gate}
    GATE -->|Code Failure| REPAIR[Code Repair Subgraph]
    GATE -->|Test Defect| TREPAIR[Test Repair Subgraph]
    GATE -->|Requirement Conflict| HITL[Human Review / Replan]
    REPAIR --> PATCH[Apply Patch Tool]
    TREPAIR --> PATCH
    PATCH --> TGEN
    GATE -->|Passed| CHANGESET[Prepare ChangeSet]
    CHANGESET --> APPROVAL[Final Changes Approval]
    APPROVAL -->|Approved| WRITE[Atomic Workspace Writeback]
    APPROVAL -->|Rejected| FINAL
    WRITE --> FINAL

Planner 不创建任意 Graph 节点，只能从 Capability 白名单选择能力。系统把选择转换为经过验证的串行 ExecutionPlan，并记录 completed_steps、current_step、failed_step 和 pending_steps。只读分析与审查不会创建 Sandbox 或 ChangeSet；写入型任务仍强制经过 Sandbox、Quality Gate、ChangeSet、人工审批、冲突检测和安全写回。

Agent 职责

Agent	主要输入	主要输出
Planner	用户需求、Workspace 相关文件、长期记忆	Intent、Capabilities、稳定 Requirement/AC、Dev Plan、Test Plan
Diagnosis	Specification、Bug 请求、Workspace 相关文件	受影响生产文件、Failure Evidence、Repair 范围
Analysis	用户问题、Workspace 相关文件	只读分析报告与建议
Implementation	Specification、Dev Plan、现有项目上下文	实现文件、Requirement Coverage、Code Version
Test Generation	Specification、Test Plan、当前代码版本	候选测试和 TestEvidence
Test Solver	真实工具结果、测试报告、当前实现	测试通过状态和结构化失败问题
Code Review	Requirements、代码、测试和工具证据	Review Report、Issues、Suggestions
Code Repair	Failure Evidence、诊断摘要、相关生产代码	Patch / Replan Required / No Repair Possible
Test Repair	TestEvidence、Failure Evidence、生成测试	仅针对生成测试的 Patch 或人工审批请求

Repair Agent 不直接修改 State 中的代码镜像。只有 apply_patch_tool 可以应用补丁、更新 generated_files / generated_test_files 并递增 code_version。

Sandbox 与质量门

每个任务拥有独立的：

Baseline Workspace 快照；
Task Workspace；
Artifact 目录；
Python venv Docker Volume；
Sandbox 元数据和执行记录。

默认执行容器限制为 2 GB 内存、2 个 CPU、128 个 PID，默认禁止网络、特权模式、宿主 Shell 和越界路径。依赖安装只有在用户允许网络后才会启用。

Execution Policy 根据 Intent、目标文件和项目配置选择质量检查：

Python 生产代码改动 -> Python Compile / Import Smoke
Python 文件改动 -> Ruff
存在测试或 Test Plan -> Pytest
项目配置 Mypy -> Mypy
安全敏感改动 -> Bandit
写入型任务 -> Deterministic Quality Gate

上下文、记忆与 Artifact

所有 LLM Agent 必须通过 ContextManager 获取上下文，Prompt Builder 不接收完整 Graph State。上下文由以下部分组成：

Fixed Context：Agent 角色、安全规则和用户明确约束；
Selected Context：按 Agent 职责投影的 State 字段和 Workspace 文件；
Dynamic Context：历史 Test、Review、Patch 和 Repair 记录；
Task Snapshot：任务目标、当前阶段、代码版本和最新失败；
Global / Workspace Memory：经过证据门控和细粒度去重的长期记忆。

大体积历史记录会先外置为 Artifact。上下文仍超限时，系统压缩较旧约 75% 的 Dynamic Context，并原样保留较新约 25%，同时验证任务目标、阶段、代码版本、最新失败和未解决问题没有变化。

技术栈

层级	技术
Agent 编排	LangGraph、Pydantic
LLM	OpenAI-Compatible Async API
后端	FastAPI、Uvicorn
前端	React、TypeScript、Vite、Monaco Editor
数据	SQLite、LangGraph SQLite Checkpointer
沙箱	Docker Desktop、Docker SDK for Python
质量工具	Pytest、Ruff、Mypy、Bandit
可观测性	LangSmith、本地 Usage Metrics

目录结构

CodePilot/
├── codepilot/                       # Python 后端主包
│   ├── orchestration/               # LangGraph 编排层
│   │   ├── agents/                  # Planner、Generation、Review、Repair Agent
│   │   ├── graph/                   # State、节点、路由和 Subgraph
│   │   └── runtime/                 # GraphRuntime、RuntimeContext 和事件流
│   ├── intelligence/                # 模型与上下文智能层
│   │   ├── llm/                     # Client、Schema、Prompt 和结构化重试
│   │   ├── context/                 # AgentContext、Token 预算和压缩
│   │   └── memory/                  # Global / Workspace 长期记忆
│   ├── execution/                   # 隔离执行与验证层
│   │   ├── sandbox/                 # Docker Provider、快照和恢复
│   │   ├── environment/             # 项目检测、依赖计划和环境构建
│   │   ├── tools/                   # Tool Registry、Runner 和 Patch Tool
│   │   └── testing/                 # 测试计划、证据和确定性验证
│   ├── application/                 # Task、Workspace、Artifact、ChangeSet 服务
│   │   ├── specification/           # Requirement 与 Acceptance Criterion
│   │   └── usage/                   # Token、成本和预算管理
│   ├── infrastructure/              # 本地基础设施
│   │   ├── database/                # SQLite 与 LangGraph Checkpointer
│   │   └── observability/           # 本地指标聚合
│   └── interfaces/                  # 对外接口
│       ├── web/                     # FastAPI 与生产静态资源
│       └── cli/                     # 命令行入口
├── docker/          # Sandbox 镜像和受控 Runner
├── frontend/        # React + TypeScript Web 前端
├── notebooks/       # 项目与 LangGraph 学习材料
└── scripts/         # 运行检查和 Web 启动脚本

环境要求

Windows 10/11；
Conda；
Python 3.12 或更高版本；
Docker Desktop，使用 Linux Containers；
Node.js 和 npm；
一个 OpenAI-Compatible LLM API；
可选：LangSmith API Key。

快速开始

1. 克隆并创建 Python 环境

git clone https://github.com/lsz-code/CodePilot.git
cd CodePilot

conda create -n codepilot python=3.12 -y
conda activate codepilot
python -m pip install -r requirements.txt

2. 配置环境变量

Copy-Item .env.example .env

编辑 .env，至少设置：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
CODEPILOT_MODEL=your_model_name
CODEPILOT_LLM_ENABLED=true
CODEPILOT_USE_MOCK_LLM=false
CODEPILOT_PATCH_MODE=web_approval

启用 LangSmith：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_PROJECT=CodePilot

不要提交 .env。仓库只保留不包含真实凭据的 .env.example。

3. 构建 Sandbox 镜像

在项目根目录执行：

docker build -t codepilot-python:3.11-v1 -f docker/sandbox/python-3.11.Dockerfile .

镜像预装 Pytest、Ruff、Mypy、Bandit 和 Coverage，并以非 root 用户运行任务代码。

4. 构建前端

Set-Location frontend
npm ci
npm run build
Set-Location ..

Vite 会将生产资源构建到 codepilot/interfaces/web/static/。该目录是生成产物，不提交到 Git。

5. 启动 CodePilot

powershell -ExecutionPolicy Bypass -File .\scripts\start_codepilot.ps1

脚本会检查 Python、Conda、Docker Desktop、Sandbox 镜像、数据目录、端口和前端资源，然后启动：

http://127.0.0.1:8765

也可以直接启动后端：

python main.py

本地数据

默认运行数据保存在：

%USERPROFILE%\.codepilot\
├── codepilot.db       # Workspace、Task、Memory、Usage 等业务数据
├── checkpoints.db     # LangGraph Checkpointer
├── tasks\             # Task Workspace、Baseline 和执行数据
├── artifacts\         # 大输出和工具日志
├── backups\           # Workspace 写回备份
└── logs\              # 本地日志

可以通过 CODEPILOT_HOME 修改数据目录。API Key、LLM Client、Workspace Root 和 Sandbox Provider 只存在于 RuntimeContext，不会写入 Graph State。

安全边界

Graph State 不保存 API Key、Client、Workspace Root 或 Sandbox Provider；
所有 Graph 执行统一通过 GraphRuntime；
所有 LLM Agent 统一通过 ContextManager 构建 Prompt；
工具命令必须通过 Tool Registry 和 Tool Policy；
Code Repair 和 Test Repair 只能生成各自权限范围内的 pending_patch；
Patch 只能由 apply_patch_tool 应用；
最终写回前执行 Baseline Hash 冲突检查；
Web Approval 模式下，后端不会绕过审批直接修改真实 Workspace；
LangGraph Interrupt 必须向上透传，用于可靠恢复人工审批。

当前边界

当前主要支持 Python 项目和 Windows + Docker Desktop 本地运行环境；
Planner 通过受控 Capability Registry 选择任务路径，ExecutionPolicy 强制注入安全步骤；当前只执行受验证的串行 ExecutionPlan，不开放任意 Agent DAG；
依赖计划读取已有 requirements.txt、requirements-dev.txt 或 pyproject.toml，不会根据源码 import 自动推导依赖；
单进程内默认限制同时运行 2 个 Task、4 个 Container 和 1 个 Environment Build；多 Worker/多主机尚未使用共享资源协调器；
当前不包含 Parallel DAG Scheduler 和基于历史成本的加权公平调度。

Navigation Menu

Repository files navigation

CodePilot

核心能力

系统架构

Agent 工作流

Agent 职责

Sandbox 与质量门

上下文、记忆与 Artifact

技术栈

目录结构

环境要求

快速开始

1. 克隆并创建 Python 环境

2. 配置环境变量

3. 构建 Sandbox 镜像

4. 构建前端

5. 启动 CodePilot

本地数据

安全边界

当前边界

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
codepilot		codepilot
docker/sandbox		docker/sandbox
frontend		frontend
notebooks		notebooks
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
main.py		main.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

CodePilot

核心能力

系统架构

Agent 工作流

Agent 职责

Sandbox 与质量门

上下文、记忆与 Artifact

技术栈

目录结构

环境要求

快速开始

1. 克隆并创建 Python 环境

2. 配置环境变量

3. 构建 Sandbox 镜像

4. 构建前端

5. 启动 CodePilot

本地数据

安全边界

当前边界

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages