AI 编码智能体运行框架（learn-claude-code-refactor）

原仓库：https://github.com/shareAI-lab/learn-claude-code

一个本地、终端驱动的 AI 编码智能体（"harness"），灵感来自 Claude Code。它提供一个 REPL（交互式命令行），接收用户的自然语言任务，并通过"工具调用循环"驱动一个 兼容 Anthropic 协议的 LLM 来逐步执行任务。

Harness >> <你的任务>

智能体会用 todo 做计划、调用文件 / Shell 工具、在后台执行命令、维护记忆，并可以派生队友智能体通过"信箱"协作。

功能特性

• 工具调用智能体循环（app/loop.py）：与模型进行多轮对话，每轮动态组装工具池，解析工具调用、执行并把结果回传。对 529 / 提示过长等错误支持重试与升级。
• 文件与 Shell 工具（app/tools/）：bash、read、write、edit、glob。
• 任务规划：todo_write 做步骤规划；任务系统（task_tool.py）支持创建 / 列出 / 获取 / 认领 / 完成。
• 定时任务 / Cron（scheduler_task.py、cron_tool.py）：可调度周期性或单次提示，在后台线程运行并注入智能体循环。
• 多智能体团队（multi_agent.py、multi_agent_tool.py）：派生队友、发送消息、查收信箱、请求 / 审批计划、请求关闭。
• 技能（app/skills/、skill.py）：将技能定义（Markdown + 可选脚本）加载到上下文中（内置：agent-builder、code-review、mcp-builder、pdf）。
• 上下文压缩（compact.py）：snip / micro / reactive 压缩，控制 token 预算。
• 记忆（memory.py）：持久化记忆文件，附带由模型输出重建的索引。
• 生命周期钩子（hook.py、app/hooks/）：如 UserPromptSubmit 等钩子。
• 后台任务（background_task.py）：在后台执行耗时命令，并在结果就绪后收集。
• MCP（mcp.py、mcp_tool.py）：连接 Model Context Protocol 服务器。
• Git worktree 隔离（worktree.py）：为每个任务创建独立 worktree。
• 错误恢复（error_recovery.py）：重试并升级 token 额度。

项目结构

.
├── app/                      # 智能体运行框架包
│   ├── main.py               # REPL 入口（python -m app.main）
│   ├── loop.py               # 核心 agent_loop 工具调用循环
│   ├── context.py            # 构建 / 刷新对话上下文
│   ├── prompt.py             # 组装系统提示词
│   ├── tool.py               # 工具池组装与分发
│   ├── constants.py          # 配置、API 客户端、模型 id、路径
│   ├── tools/                # 工具实现
│   ├── agents/               # 智能体脚手架 / 子智能体模块
│   ├── skills/               # 内置技能
│   ├── hooks/                # 生命周期钩子
│   ├── memory.py             # 持久化记忆存储
│   ├── compact.py            # 上下文压缩
│   ├── scheduler_task.py     # Cron / 定时任务队列与持久化任务
│   ├── multi_agent.py        # 团队 / 信箱 / 队友
│   ├── background_task.py    # 后台命令执行
│   ├── mcp.py                # MCP 客户端
│   ├── worktree.py           # Git worktree 管理
│   ├── error_recovery.py     # 重试 / 升级
│   ├── hook.py               # 钩子触发
│   └── skill.py              # 技能加载
├── requirements.txt          # 固定版本的 Python 依赖
├── .env                      # 本地密钥（不提交，见 .gitignore）
├── .gitignore
├── README.md                 # 本文档（中文）
└── README_EN.md              # 英文文档

环境准备

前置条件

• Python 3.12+（推荐）。部分模块（如 app/memory.py）使用了 f-string 嵌套引号语法，在 Python < 3.12 下会抛出 SyntaxError。
• 一个 兼容 Anthropic 协议的 API 端点。客户端使用 anthropic SDK，但 base_url 可配置，因此兼容 OpenAI 协议的代理（如 DeepSeek）也可使用。

安装

1. 克隆仓库。

2. 创建并激活虚拟环境，安装依赖：

   pip install -r requirements.txt

3. 在项目根目录创建 .env（见下方环境变量）。

环境变量

在项目根目录创建 .env：

OPENAI_API_KEY=sk-...                                # 你的 API 密钥
MODEL_ID=deepseek-v4-flash                           # 传给 API 的模型 id
OPENAI_BASE_URL=https://api.deepseek.com/anthropic   # 兼容 Anthropic 协议的端点

可选：

• FALLBACK_MODEL_ID — 主模型失败时使用。

python-dotenv 为必需依赖（已在 requirements.txt 固定版本），因为 app/constants.py 在导入时会加载 .env。

运行

在项目根目录执行：

python -m app.main

然后在 Harness >> 提示符下输入任务并回车。输入 q 或 exit 退出。

• 已调度的 Cron 任务会在后台线程自动运行，并把结果注入循环。
• 多智能体消息会通过信箱到达，并自动呈现。

注意事项 / 已知限制

• Cron 与交互输入共享状态：定时任务目前会获取同一把 agent 锁并写入共享会话历史，长时间运行的定时任务可能短暂阻塞交互输入。（计划改进：将每个 cron 任务隔离到独立线程与独立会话。）
• Python 版本：请使用 Python 3.12+，以避免 app/memory.py 的 f-string SyntaxError。
• anthropic SDK 为硬依赖，客户端通过 OPENAI_API_KEY / OPENAI_BASE_URL / MODEL_ID 配置。