AgentCode v1.0

AgentCode 是一款极简、高效且功能强大的 AI 编程代理，灵感源自 Claude Code 架构。它能够深度理解您的项目代码库，自主执行复杂的工程任务，并兼容所有 OpenAI 标准接口及本地 Ollama 模型。

---

🌟 核心特性

• 🤖 通用代理能力 — 支持通过 sold.md (OpenClaw 风格) 自定义代理的“灵魂”，从编程专家到私人助理随心切换。
• ⚙️ 灵活配置 — 顺序支持 默认值 → config.json → .env → 环境变量 的多级配置加载。
• 🚀 并行工具执行 — 自动识别任务并并发执行多个工具（如同时读取多个文件），显著提升效率。
• 📝 精确文件编辑 — 核心 edit_file 工具采用精确字符串替换，支持自动备份 .bak，并在匹配失败时提供智能上下文提示。
• 🧠 三层上下文压缩 — 智能剪裁工具输出、自动生成对话摘要、硬折叠保护，确保在 128k 窗口内持续工作。
• 🌍 跨平台兼容性 — 针对 Windows/Linux/macOS 进行了全平台 UTF-8 编码优化，完美支持中文注释与路径。
• 🛠️ 派生子代理 (Sub-Agent) — 支持生成独立的子代理处理复杂调研或重构任务，保持主对话上下文整洁。

---

🛠️ 安装

运行环境： Python 3.11+

# 克隆仓库
git clone https://github.com/qyhua0/AgentCode.git
cd agentcode

# 安装项目（推荐使用编辑模式）
pip install -e .

---

⚙️ 配置指南

AgentCode 提供了多种配置方式，优先级最高的是环境变量。

1. 使用 config.json (推荐)

在项目根目录下创建 config.json：

{
  "model": "gpt-4o",
  "api_key": "sk-...",
  "base_url": "https://api.openai.com/v1",
  "temperature": 0,
  "soul_file": "sold.md"
}

2. 使用环境变量

export AGENTCODE_API_KEY=sk-...
export AGENTCODE_MODEL=gpt-4o
export AGENTCODE_BASE_URL=https://api.openai.com/v1

3. 本地 Ollama 支持

export AGENTCODE_MODEL=qwen2.5-coder
export AGENTCODE_BASE_URL=http://localhost:11434/v1
export AGENTCODE_API_KEY=ollama

---

🎭 灵魂文件 (sold.md)

您可以创建一个 sold.md 文件来定义代理的行为准则。如果该文件存在，AgentCode 将根据其中的内容调整其交互风格。 示例 sold.md：

# AgentCode 编程专家版
你是一个极高性能、追求完美代码质量的 AI 编程专家。
- **质量优先**：代码必须健壮、可读。
- **极简主义**：多写代码，少废话。
- **先读后写**：修改前必须读取文件上下文。

---

快速上手

交互模式 (REPL)

agentcode

在交互界面中，您可以直接输入需求，或使用内置指令：

• /help - 显示帮助
• /reset - 重置会话（清空历史与待办项）
• /stats - 查看 Token 使用统计与压缩日志
• /sessions - 列出历史会话
• /save - 手动保存当前会话
• /load <path> - 将指定文件内容注入上下文
• quit - 退出

命令行模式

agentcode -p "帮我检查项目中所有的 TODO 并生成报告"
agentcode -m gpt-4o-mini -p "重构 agentcode/config.py"

---

🧰 内置工具箱

AgentCode 拥有 9 个核心工具，LLM 会根据任务自主调用：

工具	说明
bash	执行 Shell 命令，支持链式 cd 追踪与危险指令拦截。
read_file	带行号读取文件，自动处理编码，支持分页。
edit_file	精确替换文件内容，匹配失败时提供相似块提示。
write_file	创建或覆盖文件。
grep	基于正则表达式的内容全局搜索。
ls	详尽的目录列表，包含文件大小与修改时间。
glob	强大的模式匹配（如 **/*.py），按时间排序。
todo	任务追踪系统（add/update/list），辅助规划多步任务。
agent	派生具备独立上下文的子代理。

---

🔒 安全准则

为了保护您的系统安全，bash 工具会拦截以下具有破坏性的操作：

• 根目录/家目录的递归删除 (rm -rf /)。
• 文件系统格式化 (mkfs)。
• 原始磁盘写入 (dd)。
• 管道执行远程未知脚本 (curl | bash)。

---

📈 版本信息

v1.0.0

• 核心发布：AgentCode 正式发布。
• 多级配置：完善的 config.json 与环境变量加载机制。
• 灵魂系统：支持通过 sold.md 动态定义代理人格与准则。
• 稳健编辑：增强型 edit_file 与 bash 追踪逻辑。
• 全平台支持：针对中文字符与跨平台环境进行了深度编码优化。

---

👨‍💻 作者

zhenhua

📄 开源协议

MIT License