supa-agent

一个轻量的 coding agent:给模型一套工具 (bash / read_file / write_file / list_dir / grep),让它自主完成编码任务,像 Claude Code 一样在终端里聊着干活。核心 agent 零依赖 (纯 Python 标准库), TUI 输入框仅需 prompt_toolkit。兼容任何 OpenAI-format 的 API (DeepSeek / OpenAI / Ollama / vLLM 等)。

功能

• 交互式 TUI — 全屏界面 (参考 opencode / Claude Code):圆角边框输入框、多行输入、历史记录、斜杠命令自动补全;工具调用与思维链默认折叠,鼠标点击 ▸ 展开,PgUp/PgDn 滚动,ctrl-c 中断运行中的任务
• 状态栏 — 底部实时显示模型型号、reasoning effort 和工作目录
• 模型切换 — /model 随时切换模型, 无需重启
• 推理强度 — /effort 按模型适配档位 (deepseek: none/low/high/max, none 关闭思考), 不支持的模型不发参数
• 自主编码 — agent 自动调用 bash / 文件读写 (含精确 diff 编辑) / 搜索工具,无需人工干预
• 工具渲染 — ▸ ● 工具行默认折叠 (首行+行数),点击展开完整输出,edit_file 显示彩色 diff;/verbose 切换新块默认展开
• 任务系统 — agent 用 todo_write 维护任务清单,终端实时渲染 ☐ ◐ ☑,/todos 查看
• 子代理 — task 工具派生空白上下文子代理跑独立子任务,只回传结论
• 记忆 — 项目根目录 AGENTS.md(通用标准)/SUPA.md 自动载入,agent 用 remember 沉淀事实,/memory 查看
• 上下文管理 — token 用量实时统计 (状态栏 ctx 占比),超 50% 自动裁剪旧工具输出,超 70% 自动压缩历史为摘要,/compact 手动触发,/cost 查看用量
• 会话持久化 — 每轮自动落盘 ~/.supa/sessions/,supa --resume 或 /resume 恢复 (含历史/todos/cwd)
• 并行执行 — 同一轮的多个只读工具调用自动线程池并发
• 后台任务 — bash 支持 background=true 起服务/长任务,job_output 工具与 /jobs 查看
• 配置文件 — ~/.supa/config.json + 项目 .supa/config.json (model/effort/yolo/bash_allow),优先级 CLI > 环境变量 > 项目 > 全局
• 子代理类型 — .supa/agents/<名称>.md 定义角色指令,task 工具 agent_type 参数选用
• Skills — .supa/skills/*/SKILL.md 自动发现进系统提示,/skills 查看
• 斜杠命令 — /exit、/reset、/model、/effort、/cwd、/skills、/memory、/todos、/help
• 轻依赖 — 核心仅用 Python 标准库,TUI 只需 prompt_toolkit
• API 兼容 — 任何 OpenAI-format 端点都能接 (DeepSeek / OpenAI / Ollama / vLLM)
• 可扩展 — 加一个函数就能注册新工具
• 双模式 — 交互式对话,或一次性执行单个任务

快速开始

1. 安装

需要 Python 3.8+。安装时自动带上 TUI 依赖:

git clone git@github.com:boonguan/supa-agent.git
cd supa-agent
python3 -m pip install -e .   # Ubuntu/Debian 需要加 --user --break-system-packages

装完直接使用 supa 命令 (也可以不安装,用 python3 main.py 代替)。

2. 配置 API key

export LLM_API_KEY=sk-xxx                              # 必填
export LLM_BASE_URL=https://api.deepseek.com/v1        # 可选, 默认 DeepSeek
export LLM_MODEL=deepseek-v4-flash                    # 可选, 默认 deepseek-v4-flash
export LLM_EFFORT=high                                 # 可选, 推理强度, deepseek: none/low/high/max

也可以复制 .env.example 后自行 source:

cp .env.example .env && vim .env    # 填入 LLM_API_KEY
set -a && source .env && set +a

或用命令行参数 --api-key / --base-url / --model,优先级高于环境变量。

3. 使用

交互模式 (推荐, 像 Claude Code 一样连续对话):

supa -d /path/to/your/project

supa-agent  ·  model: deepseek-v4-flash  ·  effort: high  ·  cwd: /path/to/your/project
输入 / 查看可用命令
> 看看这个项目是做什么的
> 给代码加上错误处理
> /exit

一次性任务模式 (适合脚本调用 / CI):

supa "看看当前目录有什么文件, 然后写一个 hello.py 并运行它" -d /tmp/demo

4. 斜杠命令

命令	说明
/exit	退出
/reset	清空对话历史
/model [名称]	查看当前模型, 或切换 (如 /model deepseek-v4-pro), 输入 /model 会自动补全支持列表
/effort [级别]	查看或切换推理强度 (档位随模型, 自动补全)
/cwd <路径>	切换工作目录
/help	显示帮助

输入 / 加 Tab 或直接输入可见自动补全建议。

配置项

环境变量	必填	默认值	说明
LLM_API_KEY	是	-	API key
LLM_BASE_URL	否	https://api.deepseek.com/v1	OpenAI 兼容 base url
LLM_MODEL	否	deepseek-v4-flash	模型名 (DeepSeek 支持 deepseek-v4-pro / deepseek-v4-flash)
LLM_EFFORT	否	high	推理强度, 按模型映射: 支持的发 reasoning_effort, none 发 thinking: disabled, 不支持的不发

其他兼容端点示例:

# OpenAI
export LLM_BASE_URL=https://api.openai.com/v1 LLM_MODEL=gpt-4o-mini
# Ollama (本地, 免费)
export LLM_BASE_URL=http://localhost:11434/v1 LLM_MODEL=qwen2.5-coder
# DeepSeek 推理模型 (max 强度)
export LLM_BASE_URL=https://api.deepseek.com/v1 LLM_MODEL=deepseek-v4-pro

内置工具

工具	说明
bash	执行任意 shell 命令 (120s 超时)
read_file	读取文件, 带行号
write_file	写入/覆盖文件, 自动建目录
edit_file	精确字符串替换 (old 须唯一), 终端显示彩色 diff
list_dir	列出目录内容
grep	正则搜索文件内容
todo_write	维护任务清单, 终端实时渲染 ☐ ◐ ☑
task	派生子代理独立完成子任务, 回传结果摘要 (可选 agent_type, 不能再派生)
job_output	查看后台任务状态与输出
remember	追加事实到项目记忆 AGENTS.md/SUPA.md

记忆 / Skills / 任务系统

• 项目记忆 — 项目根目录的 SUPA.md 每次会话自动载入系统提示; agent 用 remember 工具写入, /memory 查看
• Skills — 在 <项目>/.supa/skills/<名称>/SKILL.md 或 ~/.supa/skills/ 放带 frontmatter (name / description) 的技能文件, 自动发现并列入系统提示, agent 匹配到任务时自行读取完整指令; /skills 查看
• 任务系统 — 多步骤任务 agent 会先用 todo_write 列计划并逐步更新, /todos 随时查看
• 子代理 — 独立大块子任务通过 task 工具派生新 agent (空白上下文, 深度限 1 层), 只回传结论, 不污染主对话

扩展新工具

在 harness/tools.py 里加一个函数:

@tool(
    "git_status",
    "查看 git 状态。",
    {"type": "object", "properties": {}},
)
def git_status(agent):
    return "clean"

工具函数第一个参数是 agent 实例 (可取 agent.cwd / agent.llm / agent.todos)。

注册后 agent 会自动拿到该工具的 schema, 无需其他改动。

作为库使用

from harness import LLM, Agent

llm = LLM(api_key="sk-xxx", model="deepseek-v4-flash", effort="high")
agent = Agent(llm, cwd="/path/to/project")
result = agent.run("给项目加一个 README")
print(result)

项目结构

supa-agent/
├── main.py            # CLI 入口 (交互模式 + 一次性模式)
├── harness/
│   ├── agent.py       # agent 主循环 (流式 / 工具调用 / 子代理深度)
│   ├── tools.py       # 工具注册与实现 (含 edit/todo/task/remember)
│   ├── context.py     # 项目记忆 (SUPA.md) 与 skills 发现
│   ├── ui.py          # 终端渲染: 工具行 / diff / 任务清单
│   ├── tui.py         # prompt_toolkit 输入框 / 状态栏 / 斜杠补全
│   └── llm.py         # OpenAI 兼容 API 客户端 (流式 + 非流式)
├── tests/             # 零依赖自检: python3 tests/test_harness.py
├── .env.example       # 环境变量示例
└── requirements.txt   # 仅 prompt_toolkit