CodePilot 是一个面向软件开发任务的终端 AI Agent。它以 Textual TUI 为主界面，将大模型对话、文件与命令工具、权限控制、会话记忆、MCP 扩展、子 Agent 协作和 Git Worktree 隔离整合到同一条可观察的执行链路中。
项目的目标不是封装一次模型调用，而是实现一个可持续执行多步开发任务的 Agent 运行时：模型可以读取代码、提出并执行修改、调用外部工具、等待权限确认、将结果回写会话，并在复杂任务中将工作拆分给独立的子 Agent。
CodePilot 的产品形态和部分工作流参考了 Claude Code：让 Agent 以终端为主要工作界面，围绕真实代码仓库完成“理解任务、读取上下文、调用工具、修改文件、执行命令、处理反馈”的连续闭环。参考的重点是 Agent 在软件开发场景中的交互方式与工程组织思路，而不是将模型调用包装成一次性的问答工具。
在设计上，项目主要借鉴以下思路：
- 终端优先的开发体验：将对话、执行过程、工具结果和需要人工确认的操作放在同一条终端工作流中，既支持交互式 TUI，也支持通过 CLI 执行单次任务。
- 面向任务的 Agent Loop：模型根据当前上下文决定下一步行动，工具调用结果会回写到会话历史，使任务能够在多轮推理、读取和修改之间持续推进。
- 可控的工具与权限机制：文件访问、命令执行和高风险操作都经过统一的工具注册和权限判断，避免 Agent 在缺少约束时直接扩大操作范围。
- 开发上下文管理：将会话记录、压缩摘要、环境信息和长期记忆纳入提示词组装过程，降低长任务中上下文丢失或无效膨胀的风险。
- 可扩展的协作方式：通过 MCP、Skills、子 Agent 和 Git Worktree，将外部工具、专项能力和并行任务逐步接入 Agent 运行时。
在具体实现上，CodePilot 采用 Python 构建运行时，使用 Textual 提供终端界面，并实现了多模型协议接入、工具注册表、权限校验、会话与记忆管理、MCP 工具加载、Skill 安装以及多 Agent 团队协作等模块。项目会根据自身的架构与使用场景演进，并不应被视为 Claude Code 的官方客户端、兼容实现或替代产品。
- 终端优先：提供 Textual 交互界面和
-p非交互命令行入口。 - 多模型协议：支持 Anthropic、OpenAI 和 OpenAI-Compatible 接口。
- 可控工具执行：内置读写文件、搜索、命令执行、交互提问等工具，并通过统一注册表管理工具 Schema、启用状态和延迟暴露。
- 权限分层：危险命令检测、路径范围校验、规则文件和权限模式共同决定一次工具调用是否放行。
- 上下文管理：对长工具输出、历史对话和压缩后的恢复信息进行控制，降低长任务中的上下文膨胀。
- 多 Agent 协作：支持后台子 Agent、团队邮箱、共享任务、协调者模式和 Worktree 隔离。
- 可扩展生态：支持 MCP 服务端接入与从公共 URL 安装 Skill。
用户输入 / CLI Prompt
|
v
Textual TUI / 命令行入口
|
v
Agent Loop
| | | |
| | | +--> Memory / Session / Context Compression
| | +-----------> Permission Checker / User Confirmation
| +-------------------> Tool Registry
| |-- 文件与搜索工具
| |-- Bash 与 OS Sandbox
| |-- MCP Tools / McpCall
| |-- Skills
| +-- Agent Teams / Worktree
v
LLM Client (Anthropic / OpenAI / Compatible)
核心执行过程如下：
- 读取配置并初始化模型客户端、会话、记忆、权限和工具注册表。
- 组装系统提示词、项目指令、环境信息和必要的长期记忆。
- 将用户消息发送给模型，并消费流式文本、思考和工具调用事件。
- 对工具调用执行权限判断；需要确认时由 TUI 请求用户决策。
- 执行工具、规范化结果、修复工具调用与结果的会话配对关系，再将结果写回对话。
- 在模型结束前持续循环；必要时压缩上下文、派生子 Agent 或创建隔离 Worktree。
- 维护结构化对话历史、工具调用和工具结果。
- 支持流式文本、思考内容和工具调用事件的统一处理。
- 自动修复缺失的工具结果，避免部分模型接口因工具调用链不完整而拒绝后续请求。
- 编辑文件后返回带行号的差异摘要，便于模型和用户确认实际修改。
- 支持上下文压缩、会话持久化、会话摘要和恢复。
内置工具包括：
ReadFile、WriteFile、EditFileGlob、GrepBashAskUserQuestionToolSearch
权限控制由多个层次组成：
- 对高风险命令进行模式匹配和拦截。
- 对读写目标执行路径沙箱校验。
- 读取用户级、项目级和本地级权限规则。
- 根据
default、acceptEdits、plan、bypassPermissions、custom等模式做默认决策。 - 对未自动放行的操作请求用户确认。
在 Linux 上，可通过 bwrap 启用 OS 级命令隔离；在 macOS 上可使用 sandbox-exec。Windows 当前不提供等价的 OS 沙箱后端，仍使用路径校验和权限确认机制。
CodePilot 可连接 stdio 或 Streamable HTTP MCP 服务端，并将服务端工具包装为内部统一工具。
- 自动拉取 MCP 工具 Schema。
- 根据 Schema 体积与模型端点选择直接暴露或延迟加载策略。
- 大规模 MCP 工具集可通过
ToolSearch查找，再使用McpCall统一调度。 - 对常见参数错误进行保守修正，例如数字字符串、布尔字符串和数组形式，减少模型调用外部工具时的无效重试。
Skill 用于把可复用的工作流、提示词和专用工具打包为一个可加载单元。
- 支持项目级、用户级和内置 Skill 的优先级加载。
- 支持
LoadSkill激活 Skill，并向当前 Agent 注入对应的操作约束。 - 支持目录型 Skill 的附属工具注册。
- 支持从
skills.sh、GitHub Tree URL 或 GitHub RawSKILL.mdURL 安装公共 Skill。 - 安装过程限制目录深度、文件数和下载体积，先写入临时目录并验证
SKILL.md后再替换正式目录。
复杂任务可委派给后台子 Agent，并通过任务管理器收集完成通知。
团队协作能力包括：
- 创建团队、成员注册和任务状态维护。
- Lead 与队友之间的邮箱消息通信。
- 结构化的停机请求和计划审批消息。
TaskStop：可取消运行中的 in-process 队友任务，并尝试关闭外部 pane 后端。- 协调者模式：将主 Agent 收敛为拆解、委派、汇总和验证职责。
- Git Worktree：为需要隔离修改的任务创建独立工作目录，并支持回收。
codepilot/
├── __main__.py # CLI 入口
├── app.py # Textual TUI 应用与装配层
├── agent.py # Agent Loop 与工具执行编排
├── client.py # 多模型协议客户端
├── conversation.py # 对话、工具调用和结果结构
├── context/ # 上下文预算、压缩与恢复
├── memory/ # 会话、长期记忆与召回
├── permissions/ # 权限模式、规则、危险命令与路径校验
├── tools/ # 内置工具、MCP 调度、Skill 安装等
├── mcp/ # MCP 客户端、管理器和工具包装
├── skills/ # Skill 解析、加载、执行和安装
├── sandbox/ # Linux/macOS OS 沙箱后端
├── agents/ # 子 Agent、后台任务和追踪
├── teams/ # 团队、邮箱、协议和成员管理
├── worktree/ # Git Worktree 创建、切换和清理
└── commands/ # Slash Command 注册与处理器
- Python
>= 3.11 uv- Git
- 至少一个可用的大模型 API Key
可选依赖：
- Linux：安装
bwrap后可使用 OS 级 Bash 沙箱。 - macOS：系统存在
sandbox-exec时可使用 Seatbelt 沙箱。 - 使用 MCP 时，需要对应 MCP 服务端及其运行依赖。
uv venv
.venv\Scripts\Activate.ps1
uv sync安装开发依赖并运行测试：
uv sync --group dev
uv run pytest如使用第三方 PyPI 镜像遇到下载问题，可临时使用官方索引：
$env:UV_INDEX_URL = "https://pypi.org/simple"
uv syncCodePilot 按下列顺序读取并合并配置，后面的文件会覆盖前面的同名字段：
~/.codepilot/config.yaml<项目目录>/.codepilot/config.yaml<项目目录>/.codepilot/config.local.yaml
最小 Anthropic 配置示例：
providers:
- name: anthropic-main
protocol: anthropic
base_url: https://api.anthropic.com
model: claude-sonnet-4-20250514
api_key: ${ANTHROPIC_API_KEY}
permission_mode: defaultOpenAI 兼容接口示例：
providers:
- name: openai-main
protocol: openai
base_url: https://api.openai.com/v1
model: gpt-4.1
api_key: ${OPENAI_API_KEY}
permission_mode: defaultMCP 服务端示例：
mcp_servers:
- name: local-tools
command: python
args:
- tools_server.py不要将包含真实 API Key 的 .codepilot/config.yaml 或 .codepilot/config.local.yaml 提交到仓库。
启动交互式终端界面：
uv run codepilot指定权限模式：
uv run codepilot --mode default
uv run codepilot --mode acceptEdits
uv run codepilot --mode plan
uv run codepilot --mode bypassPermissions执行单次非交互任务：
uv run codepilot -p "解释 codepilot/agent.py 的主循环，并列出关键状态转换"当配置中包含多个 Provider 时，可通过其 name 指定本次非交互任务使用的模型：
uv run codepilot --provider openai -p "为当前项目运行测试并总结失败原因"常用 Slash Command：
| 命令 | 作用 |
|---|---|
/help |
查看命令帮助 |
/session |
创建、查看或恢复会话 |
/permission |
查看或切换权限模式与规则 |
/memory |
查看和管理记忆 |
/compact |
手动压缩当前上下文 |
/mcp |
查看 MCP 服务状态 |
/tasks |
查看后台任务 |
/worktree |
管理隔离工作目录 |
/sandbox |
查看、开启或关闭 OS 命令沙箱 |
/status |
查看运行状态 |
当前版本已经实现：
- 终端 TUI 与 CLI 单次执行入口。
- 多模型协议客户端与流式工具调用。
- 文件读写、搜索、命令执行和用户确认。
- 会话持久化、记忆提取、上下文压缩与恢复。
- 权限模式、规则引擎、危险命令检测与路径校验。
- MCP 服务连接、工具包装、延迟发现和统一调度。
- Skill 加载、目录型工具注册与公共 URL 安装。
- 子 Agent、后台任务、团队邮箱、共享任务、协调者模式和 Worktree 隔离。
- Linux/macOS OS 级 Bash 沙箱后端，以及 Windows 下的明确降级行为。
- 本项目会执行模型生成的文件操作和命令。请从
default或plan权限模式开始使用。 bypassPermissions会显著降低交互确认，不应在不了解风险的环境中使用。- MCP 服务和从 URL 安装的 Skill 均属于外部输入，应仅使用可信来源。
- 本仓库当前未单独声明 License。公开发布前应先确定许可证，并保留或补充所有必要的第三方署名和许可文本。