Agent

一个真的会“动手”的终端 Agent。

它不是只会聊天的壳子，而是一个单文件、可直接运行、面向真实项目落地的执行型 Agent：能先理解需求、拆任务，再读代码、改文件、跑命令、启动后台服务，并把过程和结果沉淀到本地运行时状态里。

如果你想要的是一个轻量、透明、可控、能在本地工作区里真正做事的 Agent，这个项目就是为此而写的。

项目亮点

• 双 Agent 协作：PlanAgent 负责理解需求、查看上下文、拆分任务；ExecuteAgent 负责逐个任务真实执行。
• 不是玩具 Demo：内置文件浏览、代码搜索、按行读取、整文件写入、精确替换、命令执行、后台服务管理、任务状态回写。
• 适合真实开发场景：可以启动 dev server、读取日志、检查端口、停止后台任务，而不只是输出一段“建议你去做什么”。
• 单文件架构：核心逻辑都在 main.py，容易读、容易改、容易二次定制。
• 安全边界明确：所有路径都限制在工作区内，内部运行时目录 .agent 也做了隔离和忽略。
• 终端体验友好：支持流式输出、内置命令、上下文 usage 展示、会话导出。

它解决什么问题

很多 Agent 项目都卡在“会说不会做”：

• 会分析代码，但不能安全落地修改
• 会建议运行命令，但不会自己执行和验证
• 能启动服务，却不会跟踪日志和回收后台进程
• 一轮请求里缺少连续性，上一任务做完，下一任务又像重新开局

这个项目的目标很直接：

把“规划”和“执行”拆开，把“能力边界”和“状态沉淀”做实，让 Agent 更像一个真正可协作的终端开发助手。

适合谁

• 想研究“可执行 Agent”而不是纯 prompt wrapper 的开发者
• 想自己掌控工具集、提示词、任务编排逻辑的人
• 想要一个容易 fork、容易改造成自己内部工具的基础版本
• 想在本地工作区里用最少依赖跑通 Agent 工作流的人

核心能力

PlanAgent 可用能力：

• 浏览工作区结构
• 搜索代码
• 读取文件片段
• 创建任务列表
• 分发任务给执行 Agent

ExecuteAgent 可用能力：

• 继续理解单个任务上下文
• 读取、搜索、修改文件
• 执行非交互式命令
• 启动并管理后台服务
• 读取后台任务日志
• 等待服务启动并检查可用性
• 回写任务结果和状态

工作方式

整体流程是：

1. 用户在终端输入需求
2. PlanAgent 判断这是聊天、问答，还是需要落地执行
3. 如果需要执行，就先看项目上下文，再拆出明确任务
4. ExecuteAgent 逐个消费任务并真实操作
5. 每个任务结束后更新状态，最终由 PlanAgent 汇总结果

这让项目同时具备两点：

• 高层规划能力：不会一上来就盲改
• 底层执行能力：不会只停留在“我建议你……”

快速开始

1. 安装依赖

项目依赖非常少，核心只需要 Python 和 openai SDK。

pip install openai

建议使用 Python 3.10 及以上版本。

2. 配置模型

程序运行时会使用 .agent/config.json 和环境变量读取配置。

首次运行会自动创建 .agent/config.json。你需要至少提供这几个值：

{
  "OPENAI_API_KEY": "your-api-key",
  "OPENAI_BASE_URL": "https://your-openai-compatible-endpoint/v1",
  "OPENAI_MODEL": "your-model-name",
  "WORKSPACE_DIR": "C:/path/to/your/workspace"
}

说明：

• OPENAI_API_KEY：模型服务密钥
• OPENAI_BASE_URL：兼容 OpenAI Chat Completions 的接口地址
• OPENAI_MODEL：默认模型名
• WORKSPACE_DIR：Agent 允许操作的工作区根目录；不填时默认取当前目录

你也可以直接用环境变量配置同名字段。

3. 启动

python main.py

启动后会进入交互式终端，你可以直接输入自然语言需求，例如：

帮我看一下这个项目结构，然后把 README 补完整

或：

在工作区里启动前端开发服务器，并告诉我访问地址

内置命令

交互终端支持这些命令：

• /help：查看所有命令
• /reset：清空当前会话和任务状态
• /clear-logs：一键清除所有日志与缓存（agent.log、task、history、jobs、background_logs）
• /export：把当前 PlanAgent 上下文导出为 Markdown
• /usage：查看当前上下文 token usage
• /jobs：查看后台任务列表
• /job-log <job_id> [stdout|stderr|both] [tail]：读取后台任务日志
• /stop-job <job_id>：停止后台任务
• /exit 或 /quit：退出

项目结构

项目刻意保持为单文件核心实现：

.
├─ main.py          # Agent 全部核心逻辑
├─ tests/           # 关键工具行为测试
└─ .agent/          # 运行时状态目录（自动生成，已忽略）

其中 main.py 的内部结构也比较清晰：

• 配置加载
• 路径安全
• 工具基类
• 任务存储
• 文件/命令工具
• Agent 核心
• 任务编排
• CLI 入口

为什么值得宣传

如果把它当成一个项目来介绍，我会这样定义它：

Agent 是一个面向真实工作区执行的本地终端开发助手。

它把“任务规划”和“任务执行”拆成两个协作 Agent，用最少依赖实现文件修改、命令执行、后台服务编排和任务状态沉淀，适合拿来做自己的可执行 Agent 基座。

它的宣传关键词可以是：

• 单文件可执行 Agent
• 本地优先的终端开发助手
• 会拆任务，也会真的执行
• 轻量但不简陋
• 适合作为自定义 Agent 框架起点

已有特性验证

仓库里已经包含了针对关键执行链路的测试，覆盖例如：

• 非交互式命令执行
• 后台任务启动与记录
• 日志读取
• .agent 内部路径隔离
• 等待服务就绪
• 超时与交互式命令提示

这意味着它不只是“看起来能跑”，而是已经开始关注执行过程中的边界问题。

注意事项

• 这是一个本地工作区内执行的 Agent，不是沙箱云服务
• 命令执行虽然有基础限制，但仍建议在你信任的工作区中使用
• 项目当前采用单文件架构，更利于快速演化；如果以后要做大型产品化，再考虑拆模块也不迟

接下来可以怎么演进

如果你想继续把它做成一个更完整的项目，下一步很自然的是：

• 增加更多工具类型，例如 git、浏览器、HTTP、数据库
• 支持更丰富的任务恢复和会话续跑
• 为不同模型提供独立上下文窗口和能力配置
• 补齐更多端到端测试
• 增加 Web UI 或 TUI 外壳

---

一句话总结：

这是一个不是只会“说”，而是会在你的工作区里“继续把事做完”的 Agent。