Harvil1/codeAgent

选用指南

AI 根据 README 整理 · 2026/10/19 21:01:29

目标用户

面向想学习 Agent 开发的开发者，以及希望上手修改代码的贡献者。

查看 README 依据

- 📚 **想学 Agent 开发？这就是活教材。** 工具自注册、上下文分级压缩、权限审批、子代理团队、工作流引擎、记忆系统——一个真实可跑的 Agent 全链路都在这儿，每个模块都是「大白话流程 → 参数 → 返回」的保姆级中文注释，读代码像读教程。 - 🛠 **欢迎上手改。** 觉得哪里不顺手？fork 了直接改——代码结构清晰、注释到位，改起来不费劲。欢迎 PR：修 bug、加功能、优化界面都行。 - 💬 **有问题社区问。** 卡住了、看不懂了、想讨论设计，直接去 [Issues](https://github.com/Harvil1/codeAgent/issues) 或 [Discussions](https://github.com/Harvil1/codeAgent/discussions) 发帖，有问必答。 ## ✨ 特性 **终端体验（对标 claude code）** - 流式回答圆角框、思考流暗色框、工具事件行（`● Bash(...)` + `⎿ 结果`） - 危险命令 / 白名单外写文件的**审批面板**：允许一次 / 总是允许 / 拒绝三选，面板答完自擦不污染上下文 - Ctrl+C 语义分明：回合中一键中断、双击强退；审批面板上 Ctrl+C 一击取消并中断整轮 - 皮肤系统、页脚状态栏、命令补全、输入历史、粘贴大段文本自动落盘引用

使用方式

通过命令行使用，运行 `uv run python main.py` 进入交互模式，或使用 `-c` 参数恢复最近会话。

查看 README 依据

uv run python main.py # 交互模式 uv run python main.py -c # 自动恢复最近一次会话 ``` > 提示：换模型 / 换厂商在会话里输 `/model` 按引导配置，或直接编辑 `~/.codeAgent/settings.json`。 ## ⌨️ 常用操作 会话内 40+ 个 slash 命令，常用如下： | 命令 | 作用 | |---|---| | `/help` | 命令帮助 | | `/model` | 切换 / 配置模型（按引导填厂商、key、端点） | | `/new` `/resume` `/sessions` | 新会话 / 恢复 / 会话列表 | | `/rewind` | 回溯到某个 checkpoint 重来 | | `/skills` `/plugin` | 管理技能 / 插件市场 | | `/memory` | 查看维护长期记忆 | | `/permission` `/sandbox` `/approved` | 权限模式 / 沙箱开关 / 已批准命令白名单 | | `/doctor` | 自诊断（配置、网络、组件健康检查） | | `/plan` | 计划模式：先出方案批准再动手 |

部署要求

需要 Python 3.11+ 和 uv 包管理器。需要配置 API key，支持 DeepSeek、OpenAI、Anthropic、OpenRouter 和 ZhipuAI 等。

查看 README 依据

- 子代理：同步 / 后台派发，worktree 隔离，后台代理无人审批时自动 fail-closed - 团队模式：coordinator / worker / 消息总线 / 邮箱 - 工作流引擎：确定性编排、日志断点续跑、花费封顶 - 定时任务（cron）、声明式 hooks、任务清单、会话 checkpoint 回溯（`/rewind`） **上下文工程** - 分级压缩（L1 轻裁剪 → L4 深度摘要）、批间工具摘要、时间基线旧结果清理 - 前缀缓存友好：临时消息注入与剥离时机讲究，不破坏缓存前缀 ## 🖥 界面一览  <!-- 想补审批面板截图：截图放 screenshots/ 后解开下一行注释  --> ## 🚀 快速开始 前提：[Python 3.11+](https://www.python.org/) 和 [uv](https://docs.astral.sh/uv/)（Python 包管理器）。 ```bash # 1) 安装 uv（已有可跳过）

# Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh # 2) 拉代码 + 装依赖 git clone https://github.com/Harvil1/codeAgent.git cd codeAgent uv sync # 3) 配置 API key（二选一） # a) 环境变量——按所用厂商设置其一即可，程序会自动识别： # DEEPSEEK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / # OPENROUTER_API_KEY / ZHIPUAI_API_KEY（BIGMODEL_API_KEY 亦可） # b) 写入 ~/.codeAgent/settings.json 的 models.<名字>.api_key # （首次运行会自动生成默认配置文件，默认模型为 DeepSeek） # 4) 跑起来

已知限制

Windows 优先开发与验证；Linux 可运行，macOS 理论可用但未充分验证。

查看 README 依据

| 持久化 | `session_store.py`、`task_store.py`、`hooks.py` | ## 🧪 开发 ```bash uv run python scripts/verify.py # 60+ 项回归检查（改完代码先跑这个） uv run ruff check . # lint ``` ## ❓ FAQ - **支持哪些终端？** cmd / Windows Terminal / PowerShell 直接可用；git-bash（mintty）下会自动用 winpty 重新拉起，无需手动处理。 - **支持 Linux / macOS 吗？** Windows 优先开发与验证；Linux 可运行（含 bwrap 沙箱支持），macOS 理论可用、未充分验证。 - **模型必须用 DeepSeek 吗？** 不。任何 OpenAI 兼容端点或 Anthropic 协议端点都可以，`/model` 或改 `settings.json` 即可，key 支持环境变量与配置文件两种方式。 - **会话数据在哪？** 全部在 `~/.codeAgent/`，删掉目录即完全重置。 ## 📄 许可证 [MIT](./LICENSE) © 2026 Harvil1