codeAgent - 终端里的自学习 AI 编程助手

codeAgent 是一个跑在终端里的 AI 编程助手：用户用自然语言下指令，它负责读代码、改文件、执行命令、查资料。据项目自述，它并不是对既有工具的套壳或翻译，而是从交互界面到 Agent 主循环逐行手写出来的完整实现，代码注释为中文。它适合两类人：一类是想找一个能在终端里干活的编程助手、并且偏好 Windows 环境的开发者；另一类是想读懂一个真实可跑的 Agent 全链路——工具注册、上下文压缩、权限审批、子代理、工作流、记忆系统——的学习者。项目自述也明确欢迎 fork 与 PR，修 bug、加功能、优化界面都可以。

维护者与状态

项目由 Harvil1 维护，仓库地址为 Harvil1/codeAgent。按官方接口数据，仓库创建于 2026-10-02，最后一次提交同样在 2026-10-02，也就是说这是一个非常年轻的项目。截至 2026-10-10，仓库星标数为 219。需要如实说明的是：该项目目前尚无正式 release，因此没有可引用的版本号、发布说明或版本化安装包，使用方式以直接拉取仓库源码为主。

许可证为 MIT，属于宽松许可，具体条款以仓库内的 LICENSE 文件为准。

主要能力

以下内容均来自项目自述（README），属于维护者的自我描述，未经独立验证。

终端交互

• 流式回答使用圆角框，思考流使用暗色框，工具事件以行内形式呈现，例如 ● Bash(...) 配合 ⎿ 结果。
• 危险命令、以及白名单之外的写文件操作会触发审批面板，提供「允许一次 / 总是允许 / 拒绝」三选；面板作答后自动擦除，不污染上下文。
• Ctrl+C 语义区分：回合中一键中断，双击强退；在审批面板上按一次 Ctrl+C 则取消并中断整轮。
• 另有皮肤系统、页脚状态栏、命令补全、输入历史，以及粘贴大段文本时自动落盘并引用。

模型与工具

• 多模型接入：支持 OpenAI 兼容协议（默认 DeepSeek）与 Anthropic 协议；采用主模型加辅助小模型的结构，压缩、检索、记忆提取等杂活交给便宜模型处理。
• 工具自注册体系：tools/ 目录下的模块被 import 即完成登记，并按「套餐」（toolset）控制实际发给模型的工具集。
• 支持 MCP 外部工具：在项目级 .mcp.json 中声明即可接入，首次连接需要审批。
• 内置工具覆盖文件读写、终端执行、搜索、代码检索、Web 抓取、后台任务、子代理派发等。

安全防线

• 破坏性命令审批，并维护跨会话白名单，可按命令或按前缀规则记忆。
• 注入面检测：对 $()、进程替换等「所见非所执行」的形态升级为审批；同时设有删除路径红线与自我保护机制。
• 秘钥扫描，防止 API key 被写入文件或记忆；另有 SSRF 防护与 Web 内容注入隔离。
• 在 Linux 下可选 bwrap 沙箱执行。

记忆与自学习

• 长期记忆采用 MEMORY.md 索引加 JSONL 存储，检索结果临时注入，不写入正式历史。
• 技能系统包含用户技能与插件市场技能（通过 /plugin 管理），支持按触碰的文件路径条件激活。
• 自学习管线：观察对话轨迹并沉淀新技能，提供启发式与辅助模型两种观察方式。

协作与自动化

• 子代理支持同步与后台派发，使用 worktree 隔离；后台代理在无人审批时自动 fail-closed。
• 团队模式包含 coordinator、worker、消息总线与邮箱。
• 工作流引擎支持确定性编排、日志断点续跑与花费封顶。
• 另有定时任务（cron）、声明式 hooks、任务清单，以及会话 checkpoint 回溯（/rewind）。

上下文工程

项目自述采用分级压缩策略（L1 轻裁剪到 L4 深度摘要）、批间工具摘要、时间基线旧结果清理，并在临时消息的注入与剥离时机上做了处理，以保持前缀缓存友好。

使用入口

仓库地址：Harvil1/codeAgent。

据项目说明，运行前提是 Python 3.11+ 与 uv（Python 包管理器）。安装与启动流程大致为：先安装 uv，再克隆仓库并执行 uv sync 安装依赖，然后配置 API key，最后运行主程序。API key 有两种配置方式：一是设置环境变量，程序会自动识别 DEEPSEEK_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、OPENROUTER_API_KEY、ZHIPUAI_API_KEY（BIGMODEL_API_KEY 亦可）中的任意一个；二是写入 ~/.codeAgent/settings.json 的 models 配置项下的 api_key。首次运行会自动生成默认配置文件，默认模型为 DeepSeek。

uv run python main.py
uv run python main.py -c

其中 -c 表示自动恢复最近一次会话。会话内提供 40 多个 slash 命令，项目自述中列出的常用项包括：/help 查看命令帮助，/model 切换或配置模型，/new、/resume、/sessions 管理会话，/rewind 回溯到某个 checkpoint 重来，/skills 与 /plugin 管理技能和插件市场，/memory 查看维护长期记忆，/permission、/sandbox、/approved 控制权限模式、沙箱开关与已批准命令白名单，/doctor 做配置、网络与组件健康检查，/plan 进入计划模式先出方案再动手，/stats、/usage、/trace 查看花费统计、用量与调用链追踪。

运行时数据统一放在 ~/.codeAgent/ 下，可用环境变量 CODEAGENT_HOME 覆盖，便于测试或多配置隔离。该目录包含 settings.json（全部配置）、sessions.db/（会话持久化，JSONL）、MEMORY.md 与记忆库、skills/、plugins/、logs/（滚动日志，5MB × 3）。据项目说明，删掉该目录即可完全重置。

开发方面，项目自述提供 uv run python scripts/verify.py 用于运行 60 多项回归检查，以及 uv run ruff check . 做 lint。

许可与限制

许可证为 MIT。以下限制来自项目自述，使用前值得留意：

• 平台优先级：项目以 Windows 为优先开发与验证平台，cmd、Windows Terminal、PowerShell 可直接使用；在 git-bash（mintty）下会自动用 winpty 重新拉起。Linux 可运行，并包含 bwrap 沙箱支持；macOS 据项目自述理论可用但未充分验证。
• 模型依赖：不强制使用 DeepSeek，任何 OpenAI 兼容端点或 Anthropic 协议端点均可，通过 /model 或修改 settings.json 配置。
• 审批与沙箱：破坏性命令与白名单外写文件默认需要人工审批；后台子代理在无人审批时按 fail-closed 处理，这意味着无人值守场景下的可用范围会受限。
• 版本状态：截至 2026-10-10 尚无正式 release，也没有版本化的发布节奏可参考，接口与配置格式存在随源码变动的可能。

需要说明的是，本文所引用的能力描述、命令清单与配置路径均来自项目自述，未经过实际运行验证；性能表现、稳定性与安全边界的实际效果，应以读者自行评估为准。