codeAgent README

The project's README from github.com/Harvil1/codeAgent. As one markdown file: README.md.

CodeAgent

自学习 AI Agent 命令行工具——交互体验对标 claude code，Windows 优先，开箱即用。

Python 3.11+ License: MIT Platform

English | 简体中文

CodeAgent 是一个跑在终端里的 AI 编程助手：你用自然语言下指令，它读代码、改文件、跑命令、查资料，把活干完。它有自己的一套「长本事」机制——从对话轨迹里沉淀可复用的技能，越用越顺手。

🧭 这是一份手写的「中文版 claude code」

不是套壳，也不是翻译——是从交互界面到 Agent 主循环一行行手写出来的完整实现，注释全是中文：

✨ 特性

终端体验（对标 claude code）

模型与工具

安全防线

记忆与自学习

协作与自动化

上下文工程

🖥 界面一览

运行中的 CodeAgent

🚀 快速开始

前提：Python 3.11+ 和 uv（Python 包管理器）。

# 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) 跑起来
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 计划模式：先出方案批准再动手
/stats /usage /trace 花费统计 / 用量 / 调用链追踪

⚙️ 配置与数据

运行时数据统一放在 ~/.codeAgent/（环境变量 CODEAGENT_HOME 可覆盖，测试 / 多配置隔离用）：

路径 内容
settings.json 全部配置（默认值单一源头在代码里，落盘深合并，手改安全）
sessions.db/ 会话持久化（JSONL）
MEMORY.md + 记忆库 长期记忆索引与正文
skills/ 用户技能
plugins/ 插件（含官方市场 claude-plugins-official）
logs/ 运行日志（滚动，5MB × 3）

🏗 架构一览

调用链一句话：main.py（点火：控制台编码、终端自举）→ cli.main → run_interactive（REPL + slash 命令 + RuntimeContext 装配）→ AIAgent.run_conversation（主循环心脏）。

主循环每轮：组装消息（注入后台 / 定时 / 团队 / 计划等临时消息）→ 上下文压缩 → 刷新工具集 → 调 LLM → 分发工具调用，模型不再要工具即收尾。

子系统 模块
LLM llm_client.py（OpenAI 兼容 / Anthropic 协议）、aux_llm.py（辅助小模型路由）
记忆 memory_store.py、memory_retriever.py
上下文 context_compressor.py（分级压缩）、context_pipeline.py
子代理 / 团队 tools/delegate_tool.py、agent/team/
工作流 workflow_engine.py + workflow_journal.py
技能 ~/.codeAgent/skills/ + agent/skill_learning/（自学习）
安全 bash_injection.py、ssrf_guard.py、secret_scanner.py、sandbox_runner.py、permission.py
持久化 session_store.py、task_store.py、hooks.py

🧪 开发

uv run python scripts/verify.py   # 60+ 项回归检查（改完代码先跑这个）
uv run ruff check .               # lint

❓ FAQ

📄 许可证

MIT © 2026 Harvil1

codeAgent (Harvil1/codeAgent)

Searching Database…

812 ·GitHub
CodeAgent
这是什么?CodeAgent 是一个开源的 AI 编程助手,运行在终端里:你用自然语言下达指令,它会阅读你的代码、编辑文件、执行命令、搜索信息,并把任务完成。
这只是 Claude Code 的套壳,还是一个独立的实现?它不是套壳,也不是翻译版——整个交互循环和智能体核心都是逐行手写的,源代码带有完整的中文注释,从零开始刻意复刻了 Claude Code 的使用体验。
怎么把它跑起来?你需要先安装 Python 3.11+ 和 uv 包管理器;运行起来后,可以在会话中用 /model 配置模型服务商,或者编辑 ~/.codeAgent/settings.json。
它能在 macOS 和 Linux 上用吗,还是只支持 Windows?它以 Windows 优先进行开发和验证;支持 Linux(包括可选的 bwrap 沙箱),macOS 理论上应该能跑,但还没有经过完整测试。
我必须有 DeepSeek 的 API 密钥吗,还是可以用其他服务商?DeepSeek 只是默认选项——任何 OpenAI 兼容接口或 Anthropic 协议接口都可以用,通过 /model 或 settings.json 即可切换;密钥可以通过环境变量或配置文件提供。
自学习技能系统是什么?CodeAgent 会观察自己的对话记录,并从中提炼出可复用的"技能",方式可以是启发式规则,也可以借助一个辅助模型;用得越多,它就越熟悉你的代码库和工作流程。
内置了哪些安全防护?破坏性命令和白名单之外的写入操作都需要人工确认;它会检测 shell 注入模式,在密钥被写入文件或记忆之前进行扫描,防范 SSRF,并且在 Linux 上可以把命令放进 bwrap 沙箱里运行。
bigger 的任务它能协调多个智能体一起干吗?可以——它支持同步或后台的子智能体委派,并用 git worktree 做隔离;对付更大的任务,还有完整的协调者/工作者团队模式,带消息总线和邮箱机制。
What are similar projects?Baize, lean-ctx, bareloop, KiroCrew, Raven, DeepCode, qwen-code, superpowers-zh
Which topics is it in?subagents, context-engineering, ai-coding, agent-memory, sandbox, openai-compatible, model-context-protocol, skills, deepseek, multi-agent, coding-agent, ai-agent
Creator
Harvil1
Size
5.3 MB
Stars
812
Updated
CommitOct 14
Age
15d
Commits · 90 Days