Axon

单用户 CLI Agent Harness —— 把大模型接上真实的终端、文件与网络，并让每一次操作都可审计、可中断、可续跑。

项目地址：https://github.com/gufengaoyue/axon · PyPI：pip install ai-agent-axon

Axon 是一个在你的电脑上本地运行的 AI 智能体。它不是一个聊天窗口，而是一个能真正动手干活的执行环境：

• 读你的文件、改你的代码、跑你的脚本、装你需要的依赖、下载你想要的资料；
• 每一步操作都经过沙箱网关审查（权限分级 + 审计留痕），危险动作会先问你；
• 长任务可以中断、恢复、续做，它会记住项目进展，下次接着干。

名字取自神经元轴突（axon）——负责把信号准确传递到该去的地方：模型负责思考，Axon 负责让思考落地。

✨ 核心特性

🚀 快速开始

1. 安装

方式一：pip 直接安装（推荐，普通用户）

# 需要 Python 3.11+
pip install ai-agent-axon

装完在任意目录敲 axon 即可启动。升级：pip install -U ai-agent-axon。 项目主页：https://github.com/gufengaoyue/axon（PyPI：https://pypi.org/project/ai-agent-axon/）。

方式二：源码安装（想改代码/参与开发）

git clone https://github.com/gufengaoyue/axon.git && cd axon
pip install -e .          # 核心依赖
pip install -e ".[dev]"   # 可选：测试依赖

也可以不安装，直接在项目根目录用 python -m axon 运行。

2. 配置模型

选一条路（推荐 codebuddy，工具执行更稳）：

# 方式 A：codebuddy 路
set CODEBUDDY_API_KEY=xxx
set CODEBUDDY_INTERNET_ENVIRONMENT=internal

# 方式 B：openai 兼容路
set OPENAI_API_KEY=xxx

再编辑 config.yml：

model:
  active_provider: codebuddy      # codebuddy | openai
  providers:
    codebuddy: { default_model: your-model }
    openai:    { base_url: https://api.openai.com/v1, default_model: gpt-4o-mini }

3. 配置凭证（一次性）

set CODEBUDDY_API_KEY=xxx
set CODEBUDDY_INTERNET_ENVIRONMENT=internal

想永久生效：系统属性 → 环境变量 → 新建用户变量； 或写入 <数据目录>/config.yml（首次启动自动播种到那里，任意目录共用）。

3. 第一次对话

# 在你的项目目录里启动（项目目录 = 你的工作对象）
python -m axon --project D:\Python\AI\MyProject

# 或者装好后直接用命令
axon --project D:\Python\AI\MyProject

axon ➤ 帮我看看这个项目里有哪些 Python 文件，并总结一下它们是做什么的

Axon 会：搜索文件 → 逐个阅读 → 给出总结，并把这次交互记入 AXON.md。

🕹️ 命令速查

命令行参数

会话内斜杠命令

运行中：Ctrl+C 中断当前回合；直接打字 = 插嘴（回合结束后确认发送）。

🏗️ 工作原理

                       ┌──────────────────────────────────────────┐
   你输入 ───────────►  │  CLI（REPL / 单发 / 恢复 / 删除项目）      │
                       └───────────────┬──────────────────────────┘
                                       ▼
                     ┌─────────────────────────────────────┐
                     │  Agent Loop（轮次循环 / 压缩 / 验证）  │
                     └───────┬───────────────────┬─────────┘
                             ▼                   ▼
              ┌──────────────────────┐  ┌──────────────────────┐
              │ Provider             │  │ 沙箱工具网关 Gateway   │
              │ · codebuddy SDK      │  │ Hook 管线：            │
              │ · openai 兼容 API    │  │ PathPolicy → Command   │
              └──────────────────────┘  │ → Network → Risk → 审批 │
                             │          └───────┬───────────────┘
                             ▼                  ▼
              ┌──────────────────────┐  ┌──────────────────────┐
              │ 会话存储（SQLite）     │  │ 工具（9 个）           │
              │ sessions / messages  │  │ 读 / 写 / 编辑 / 搜索 /  │
              │ audit_log / 压缩事件  │  │ 抓网页 / 执行命令 /      │
              └──────────────────────┘  │ 记忆读写 / 项目笔记      │
                             │          └──────────────────────┘
                             ▼
              ┌──────────────────────────────────────┐
              │ 记忆：AXON.md（长期记忆/项目记忆/日志）  │
              └──────────────────────────────────────┘

一次回合发生了什么

1. 你的输入进 Agent Loop，组装上下文（系统提示 + 记忆块 + 历史）；
2. 模型返回「说明文字 + 工具调用」；
3. 每个工具调用先过网关 Hook 管线：路径策略 → 命令安全分析 → 网络策略 → 风险分级，得出 允许 / 询问 / 拒绝；
4. 允许则执行（写入前自动快照、删除走回收站），询问则弹审批面板，拒绝则把理由回喂给模型让它改招；
5. 工具结果回喂模型，直到它给出结论（或达到轮次上限 / 被打转检测打断）；
6. 回合收尾：清理临时文件 → 归档产物到项目 → 任务级验收自检 → 写进度日志 →（异常退出时下次启动补沉淀）。

双层验证：V 层管"这次操作技术上是否成功"，验收自检管"用户要的东西是否真的做出来了"。 模型侧还会在回答末尾给 3 行自检（✅ 完成 / ⚠ 偏差），两边不一致时以事实（页脚结论）为准。

🛡️ 权限模型（四层信任区）

• 高危提示：路径涉及盘符根目录或系统目录时，审批面板标题显示 ⚠，正文追加醒目警示；
• 删除保护：rm / del 等纯删除命令自动改走回收站；批量删除超阈值（默认 100）升为询问；
• 命令分析：dir / type / findstr / where / tree 等查询类放行；python -c 做代码级危险信号扫描（无删除、无 shell 逃逸 → 放行）；subprocess / eval 等不透明执行 → 询问；
• 网络：远程默认放行，域名黑名单与敏感信息扫描仍硬拦；web_fetch 下载常规文件免确认，风险类型先询问；
• 审计：每次判定与结果写 audit_log（/audit 查看或导出），不存在静默操作。

🧩 记忆体系（AXON.md）

<项目>/AXON.md
├── ## 长期记忆      模型经 memory_write 维护：事实 / 偏好 / 决策（scope + confidence + 预算治理）
├── ## 项目记忆      模型经 project_note 写入：会话总结 / 关键决策 / 踩过的坑 / 偏好 / 环境 / 下一步
└── ## 进度日志      每回合自动追加：请求 · 执行 · 结果 · 变更 · 产物 · 归档 · 踩坑 · 清理

• 每轮注入：三区按 50 / 30 / 20 的预算注入 system 上下文，模型开口前就知道项目进展与历史教训；
• 踩坑必记：提示词要求模型遇到走不通的路（工具报错、方案被否、环境限制）必须记下「什么操作 → 什么错误 → 正确做法」；
• 会话结束沉淀：/exit、Ctrl+D 触发模型总结；窗口被直接关闭（异常退出）则在下次启动时提示补沉淀；
• 跨项目恢复：--resume <前缀> 全局匹配会话，自动切换项目上下文。

📁 目录与文件

可用环境变量 AXON_HOME 覆盖程序级目录位置（不要指向云同步目录）。 任意目录启动：pip install ai-agent-axon（或源码 pip install -e .）后， 在任意目录敲 axon 都读同一份配置—— 查找顺序为 --config > 当前目录 config.yml > <数据目录>/config.yml > 安装自带模板； 首次启动会把模板播种到数据目录，之后所有项目共用（改一处生效）。 从旧版本升级会自动迁移：~/Documents/.axon、~/Documents/.openwp → 新位置（只搬不删，数据库用一致性快照，旧目录保留）。 主程序所在目录禁止写入（程序与数据分离），请用 --project 指向真正的项目目录。

⚙️ 配置要点（config.yml）

❓ 常见问题

python -m axon --resume last          # 或 --resume <id前缀>

🧪 开发

pip install -e ".[dev]"
pytest -q                     # 241 passed / 1 skipped
python -m axon --version

代码结构

axon/
├── cli.py              命令行入口、REPL、状态行、审批交互
├── config.py           配置加载、程序级目录、数据迁移
├── agent/              循环、上下文组装、压缩、验证、打转检测
├── providers/          codebuddy（SDK）与 openai 兼容两条路
├── sandbox/            Hook 管线：路径 / 命令 / 网络 / 风险 + 网关 + 审计 + 回收站
├── tools/builtin/      9 个内置工具
├── session/            SQLite 会话存储、恢复、跨项目索引
├── memory/             AXON.md 三区治理 + 进度日志
├── prompts/            系统提示词
└── attachments.py      图片 / 附件 / 剪贴板

设计文档：designs/Axon-harness-design-v1.md（含全部架构决策与 80 项偏差记录）。

贡献约定：功能或行为变更必须同步更新 README.md 与 USAGE.md （后者面向非技术读者，措辞需保持"照着做就能用"）。

📄 License

MIT © gufengaoyue