Metadata-Version: 2.4
Name: ai-agent-axon
Version: 0.4.34
Summary: Axon — 单用户 CLI Agent Harness：沙箱工具网关、双模型接入、可续跑与项目记忆
License: MIT
Project-URL: Homepage, https://github.com/gufengaoyue/axon
Project-URL: Repository, https://github.com/gufengaoyue/axon
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: openai>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: tiktoken>=0.7
Requires-Dist: send2trash>=1.8
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: codebuddy-agent-sdk>=0.3.274
Provides-Extra: mcp
Requires-Dist: mcp>=2.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Axon

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

<p align="center">
  <a href="https://github.com/gufengaoyue/axon"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-gufengaoyue%2Faxon-181717?logo=github"></a>
  <a href="https://pypi.org/project/ai-agent-axon/"><img alt="PyPI" src="https://img.shields.io/badge/PyPI-ai--agent--axon-3775A9?logo=pypi&logoColor=white"></a>
  <img alt="version" src="https://img.shields.io/badge/version-0.4.34-blue">
  <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-3776AB">
  <img alt="platform" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-green">
  <img alt="tests" src="https://img.shields.io/badge/tests-407%20passed-success">
</p>

> **项目地址**：[https://github.com/gufengaoyue/axon](https://github.com/gufengaoyue/axon) · **PyPI**：`pip install ai-agent-axon`

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

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

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

---

## ✨ 核心特性

| 能力                          | 说明                                                                                                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧠 **双模型接入**       | `codebuddy`（SDK 自驱执行引擎）与 `openai`（兼容任意 OpenAI 格式 API、本地模型）两条路，配置一行切换                                                                                                                                          |
| 🛡️ **沙箱工具网关**   | 所有工具调用先过 Hook 管线：路径策略 → 命令分析 → 网络策略 → 风险分级 → 审批；**审计全落库**                                                                                                                                            |
| 👁️ **图片理解**       | 粘贴的图片**直接进模型视野**（OpenAI 兼容 image_url / Claude 风格 image block，自动缩放≤1568px）；模型无视觉时自动降级为**视觉副模型描述**（含 OCR）或元数据提示；`model.vision: auto\|on\|off` 控制，描述按 sha256 缓存             |
| 🐍 **共享 Python 环境** | 程序级 venv（`<数据目录>/venv`）不存在时**自动创建**（`--system-site-packages` 继承系统已装库）；该 venv 属信任区，装包免询问；提示词给出解释器**绝对路径**，禁止满盘找 python                                                    |
| 🗂️ **分级信任区**     | 工作空间（全权限）→ 项目目录（信任）→ 程序级 venv/临时区（信任）→ 区外（询问）→ 系统目录/盘根（拒绝），并带 ⚠ 高危提示；**兼容 Cygwin/WSL/Git-Bash 路径**（`/cygdrive/d/...` 自动折算为本机路径）                                    |
| 🔁 **中断续跑**         | `Ctrl+C` 中断 → 写入「未完成任务」→ `--resume` 恢复 → 说「继续」即从断点续做（不重放副作用）                                                                                                                                               |
| 💬 **插嘴（steering）** | 任务执行中可随时补充要求，回合结束后确认注入，模型据此调整方向                                                                                                                                                                                    |
| 🧩 **三层记忆**         | `AXON.md`：长期记忆（模型写）+ 项目记忆（会话总结/踩坑）+ 进度日志（每回合自动）                                                                                                                                                                |
| 📦 **产物归档**         | 交付物自动从工作空间移到项目目录，页脚列出产物清单（路径 + 大小）                                                                                                                                                                                 |
| 🌐 **网络与下载**       | 网页正文提取；pdf/pptx/xlsx/docx/图片等常规文件直接下载，zip/exe 等风险类型先询问；**文件类型多重推断**（URL 后缀须合法 → Content-Disposition → Content-Type → 魔数嗅探，OOXML 家族细分）                                                |
| 📎 **粘贴即收编**       | **Ctrl+G / Alt+V / F2 / Ctrl+V** 四键收编（Ctrl+V 在 Windows Terminal 被系统接管，故提供终端不吞的键）；图片/文件收编到 `<项目>/tmp/`，`>引用` **插入输入行**（可继续打字），提示走底部工具栏                                     |
| 📎 **粘贴即收编**       | **只监听粘贴动作（Ctrl+V）**——截图/复制不会误触发；图片/文件收编到 `<项目>/tmp/`，引用 `>./tmp/图片1.png` **直接插入输入行**（可继续打字），提示走底部工具栏（不打断输入）                                                      |
| ⌨️ **输入补全**       | `/` → 斜杠命令；行首 `>` → **项目内文件与文件夹**（≤15 个，目录带 `/` 可续拼子路径；自动排除 `.workspace`/`.git`/依赖目录）                                                                                                    |
| ⌨️ **输入补全**       | 输入 `/` 补全斜杠命令；行首 `>` 补全**项目内文件**（≤15 个，自动排除 `.workspace`/`.git`/依赖目录）                                                                                                                                |
| 📎 **粘贴即收编**       | 截图/复制文件被**实时监测**（后台看门狗，不依赖回车）：不在项目内则复制到 `<项目>/tmp/`，项目内则原位；提示中以 **`>./tmp/图片1.png`** 引用并附「引用 → 绝对路径」清单                                                           |
| ⏳ **静默期转圈**       | 输出停顿/等待模型响应超过 1.2 秒自动恢复转圈（看门狗），界面不再「停着不动」                                                                                                                                                                      |
| 🖼️ **图片输入**       | 截图或复制文件后回车即被收编为 `@图片1.png`，避免超长路径进提示                                                                                                                                                                                 |
| 🛟 **数据自愈**         | 启动时做数据库完整性自检（损坏则只读降级 + 明确修复指引）；`--repair-db` 一键**备份坏库 → 按官方 schema 重建 → 逐行救回 → 校验**；迁移旧数据用 **SQLite 一致性快照**（不复制活动库）                                             |
| 🧹 **自动收尾**         | 每回合清理临时文件、异常退出下次启动补沉淀记忆、跨项目会话索引与删除                                                                                                                                                                              |
| ✅ **双层验证**         | **V 层技术验证**（6 条确定性规则：错误悬挂/写入回读/退出码/审批/打转/终答）+ **任务级验收自检**（数量词 ↔ 产物数、产物存在性、失败项、请求中的输出路径），结论进页脚与进度日志                                                       |
| 🔤 **输出保真**         | 流式文本四道防线去重（增量/累积/前缀重放/**尾部重叠**），修复多轮叙述整段重复                                                                                                                                                               |
| 🧩 **模块化输出**       | 各类输出带类型标签（`⚙ 运行 ·` / `✓ 完成 ·` / `✗ 失败 ·` / `💭 深度思考`），不再全部堆在一起；**长内容折叠**（>3 行只显前 2 行 + 提示），`Ctrl+O` 或 `/verbose` 切换详细模式（终端无法回删已打印行，故采用打印前折叠）    |
| 💬 **插嘴即时生效**     | 执行中打字回车 → 独立一行回显；插嘴到达即 **interrupt() 中断当前回合**，同 session 用 `query(插嘴)` 立即重发（**下一个决策点生效**，不再排队到回合结束）；工具栏常驻「执行中可直接输入补充」提示                                   |
| ⌨️ **审批独占键盘**   | 沙箱确认期间**暂停插嘴采集器与看门狗**——修复「敲 y 被插嘴线程吃掉、审批卡死」的竞争（用户实测 91s 无响应）                                                                                                                                |
| 🪟 **思考滚动窗**       | 思考/决策内容**固定高度滚动显示**（默认 6 行，带 `┌─ 💭 深度思考 ─┐` 边框）——1-6 行 → 2-7 行推进，历史随框滚出，既全流过又不霸屏（非 TTY 全显）                                                                                    |
| 🌐 **系统级长期记忆** | 跨项目共享的 `longtermmemory.md`（默认 `<个人文档>/.axon/`）——系统环境、用户信息、偏好、工具链路径等**所有项目通用**的事实；启动时按「长期记忆 > 项目记忆」顺序载入；模型经 `global_memory_write` 工具适时更新，`memory.long_term_file` 可改位置 |
| ⏱️ **每回合用时** | 每次完成任务后在页脚显示本回合耗时（`── 已完成 · 轮次 N · token M · 用时 X 分 Y 秒`） |
| 🧠 **三层记忆沉淀** | L0 规则式教训（每回合自动从「失败→成功」配对提取，零 token，下一回合即注入）＋ L1 触发式沉淀（有变化信号才调模型写 pitfall）＋ L2 退出总结；提示词明确要求「遇到相似问题直接采用已验证方法，禁止重复已失败路径」；`agent.auto_note: trigger/always/off` |
| 🧷 **跨回合去重**       | 流式文本五道防线（增量/累积/前缀重放/**整段重放 rfind 探测**/尾部重叠），修复 client 模式下的整页重放                                                                                                                                       |
| 📏 **流式限行**         | 思考流 ≤4 行、正文流 ≤30 行（超出静默累积 + 折叠提示，`Ctrl+O` 详细模式全显），防「内心独白」霸屏                                                                                                                                             |
| 💬 **插嘴即时生效**     | **模态输入**（v0.4.31）：执行中（含思考）按 `Enter` 唤起 `⌨ 插嘴>` 独占输入行 → 输入 → `Enter` 确认 / `Esc` 取消 / 空白确认=取消；编辑期间工具结果打印到输入行**上方**，思考框内输入行并入面板底部（不与 Live 抢终端）；确认后经 prompt 流式通道**立即注入**，智能体在**下一个动作前**确认并重新规划；`agent.stream_interject` 可回退旧行为 |
| ⚡ **并行执行**         | 底层 CLI **默认并发执行**同一条消息里的多个工具调用（已实证）；提示词引导模型把无依赖子任务放进同消息（3–5 个），有依赖的步骤等上游结果；**并发审批互斥锁**保证多个「询问」不错串（防误批准）                                        |
| 🧠 **思考可见**         | 模型的思考/决策过程实时呈现（`💭` 前缀 + 弱化样式，穿插在工具调用之间）；codebuddy 路取 SDK `ThinkingBlock`（**流式**：SSE thinking_delta 逐字播出），openai 路取 `reasoning_content`；过长自动折叠首尾；`agent.show_thinking` 可关 |
| 📊 **可观测**           | 状态行（转圈 + 计时 + 操作概要轮换）、工具行动线、审计日志 `/audit` 与导出                                                                                                                                                                      |
| 🎨 **生图模型入口** | 文生图/图生图**独立接入口**（`image_gen` 配置段，OpenAI 兼容 images API：generations=文生图 / edits=图生图）——**只有显式生图任务才调用**，调用时终端 🖼 特别提醒；未配置或失败 → 放弃任务并告知用户，**禁止**用无生图能力的模型冒充生成图片 |
| 🧯 **中断即恢复** | `Ctrl+C` 中断后**立即停止转圈/思考框**（修复 rich Live 刷新线程在中断后持续重绘终端导致的"一直转圈"）；看门狗线程停止时 join，杜绝"停止后又转起来"的竞态 |
| 🔌 **端点灵活切换** | `--base-url` 临时覆盖端点；`base_url` 支持**环境变量名间接**（写 `OPENAI_BASE_URL` 自动展开，未设置启动时报可操作错误）；模型调用失败（连接/401/404/429/400）给出**分型排查话术**——端点与模型名错配（如 qwen 打到 api.openai.com）、代理环境变量陷阱都会明确指出，不再裸 traceback |
| 🛑 **验证防死循环** | 修复“答对了却反复自证重写”：打转后用户选继续即**解除粘滞**（换方法成功可正常结题）；V 层验证连续 2 次未通过即**熔断**（不再无限追加 `<verification_failed>` 观察消息）；验证规则按**回合 scope** 扫描（历史遗留失败不污染新回合）；被拒后换方法成功不判负 |
| ⏹️ **中断即停** | Ctrl+C 中断的回合**不触发沉淀**（旧实现在中断后又开一个沉淀回合、继承毒上下文再次陷循环——用户实测“停了还在想”）；沉淀提示词显式隔离历史观察消息；L1 信号源改本回合增量消息（corrected 不再恒真） |
| 🧹 **状态行无残影** | 双行状态行**默认关闭**（占位/上移重绘与流式输出、思考框互相干扰，实测“正在执行…”残行停住 (0s) 不消失）；改单行 `\r` 同行重写（无占位无上移）；底部工具栏常驻等价提示；`agent.two_line_status: true` 可开回（占位重复 bug 已修） |
| 💭 **思考可回顾** | 思考仍以滚动窗显示（不霸屏），同时全文存档 `<数据目录>/thinking/<会话>.log`；`/think [n|all]` 随时回顾（收起=默认滚动，展开=/think 读档），长内容折叠、Ctrl+O 全显 |
| 🔒 **全量审计加固** | v0.4.29–v0.4.30 两轮全面审计（含对修复本身的复审）：解释器写路径提取（shutil/rename/mkdir）+ 动态目标 fail-closed、`%VAR%`/`${HOME}`/`!VAR!` 绕过封堵、Windows 开关/复合删除命令/引号路径解析、CRLF 编辑闭环、非 UTF-8 字节保护、授权缓存粒度、压缩摘要不叠加、规则 2 反复被拒判负、插嘴全链路（bind/fallback/边界残留）、资源生命周期收口 |

---

## 🚀 快速开始

### 1. 安装

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

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

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

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

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

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

### 2. 配置模型

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

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

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

再编辑 `config.yml`：

```yaml
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. 配置凭证（一次性）

```bash
set CODEBUDDY_API_KEY=xxx
set CODEBUDDY_INTERNET_ENVIRONMENT=internal
```

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

### 3. 第一次对话

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

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

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

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

---

## 🕹️ 命令速查

### 命令行参数

| 参数                            | 作用                                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| `--project PATH`              | 指定项目目录（工作空间默认为 `<项目>/.workspace`）                                      |
| `--workspace PATH`            | 单独指定工作空间                                                                          |
| `--provider codebuddy\|openai` | 覆盖模型接入路                                                                            |
| `--model NAME`                | 覆盖模型名                                                                                |
| `--base-url URL`              | 临时覆盖当前 provider 的 API 端点（v0.4.26；openai 路生效，换服务商试模型不必改 config.yml） |
| `--resume [ID\|last]`          | 恢复会话；不带值则列出最近会话供选择（**跨项目生效**）                              |
| `--delproj [项目]`            | 删除项目（列出 / 按序号 / 名称 / 目录 / session 前缀）；`--with-files` 连目录移入回收站 |
| `--repair-db`                 | 检测并修复会话数据库（损坏时自动备份坏库、按 schema 重建、逐行救回；不需要 API key）      |
| `-p "任务"`                   | 非交互单发：跑完一个任务就退出                                                            |
| `--max-turns N`               | 单回合最大轮次                                                                            |
| `--version`                   | 版本                                                                                      |

### 会话内斜杠命令

| 命令                                  | 作用                                                   |
| ------------------------------------- | ------------------------------------------------------ |
| `/help`                             | 帮助                                                   |
| `/save [补充]`                      | 立即沉淀项目记忆（调用模型总结本次会话）               |
| `/think [n\|all]`                    | 回顾思考全文（默认最近 1 段；n=最近 n 段；all=全部；v0.4.28） |
| `/attach [路径]`                    | 附加图片/文件（不带参数读剪贴板）                      |
| `/sessions`                         | 最近会话（跨项目索引：时间 · 项目 · 消息数 · 标题） |
| `/resume [last\|id]`                 | 恢复会话                                               |
| `/memory`                           | 查看三层记忆                                           |
| `/audit [--export csv\|json <路径>]` | 查看 / 导出审计日志                                    |
| `/compact`                          | 手动压缩上下文（openai 路）                            |
| `/delproj [项目]`                   | 删除项目（等价于命令行 `--delproj`）                 |
| `/exit`                             | 退出（退出前自动沉淀项目记忆）                         |

**运行中**：`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 行自检（`✅ 完成 / ⚠ 偏差`），两边不一致时以事实（页脚结论）为准。

---

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

| 区域                                     | 默认权限               | 说明                                                                                                             |
| ---------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **工作空间** `<项目>/.workspace` | ✅ 全权限免询问        | 读写 / 删除 / 建目录 / 跑脚本 / 装依赖；删除走回收站，写入前快照                                                 |
| **项目目录** `<项目>`            | ✅ 信任（写/删免确认） | 你的项目资产区；产物归档落点                                                                                     |
| **区外路径**                       | ⚠️ 询问              | 弹审批面板，可 `[y]es / [n]o / [a]lways(本会话记住此模式)`                                                     |
| **系统目录 / 盘根**                | ⛔ 拒绝                | `Windows` / `Program Files` / `ProgramData` / 回收站 / 盘根本身；**盘根下的文件**操作 → ⚠ 高危确认 |

- **高危提示**：路径涉及盘符根目录或系统目录时，审批面板标题显示 `⚠`，正文追加醒目警示；
- **删除保护**：`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 <前缀>` 全局匹配会话，自动切换项目上下文。

---

## 📁 目录与文件

| 位置                                                        | 内容                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `%LOCALAPPDATA%\Axon\`（POSIX：`~/.local/share/axon/`） | **程序级数据**（所有项目共用）：`sessions.db`（会话与审计）、`snapshots/`（写入前快照）、`trash/`（回收站）、`tmp/`、`quarantine/`（损坏库隔离区）。**故意不放个人文档**：云同步/企业 DLP 会逐文件回滚，而 SQLite 由主库 + `-wal` + `-shm` 三文件组成，逐文件回滚必然损坏 |
| `<项目>/`                                                 | 你的项目资产：源码、产物、`AXON.md`（记忆）                                                                                                                                                                                                                                                       |
| `<数据目录>/venv/`                                        | **程序级共享 Python 环境**（所有项目共用；不存在自动创建，继承系统已装库）                                                                                                                                                                                                                    |
| `<项目>/.workspace/`                                      | 智能体工作区：草稿、脚本、`downloads/`（下载物）、`tmp/attach/`（粘贴的图片）                                                                                                                                                                                                                   |

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

---

## ⚙️ 配置要点（`config.yml`）

| 配置                               | 默认          | 说明                                                  |
| ---------------------------------- | ------------- | ----------------------------------------------------- |
| `model.active_provider`          | `codebuddy` | 接入路                                                |
| `sandbox.paths`                  | 见文件        | 路径规则（allow / ask / deny，按特指度 + 严格度排序） |
| `sandbox.commands.ask/deny`      | 见文件        | 命令模式规则                                          |
| `sandbox.approval_granularity`   | `prefix`    | `[a]lways` 的授权粒度（同类命令共享）               |
| `sandbox.network.remote_default` | `allow`     | 远程请求默认策略；域名黑白名单仍生效                  |
| `memory.auto_journal`            | `true`      | 每回合自动进度日志                                    |
| `memory.auto_summary_on_exit`    | `true`      | 退出时沉淀项目记忆                                    |
| `memory.recover_prompt`          | `true`      | 启动时检测异常退出并提示补沉淀                        |
| `tools.move_products_to_project` | `true`      | 产物归档到项目目录                                    |
| `tools.max_download_mb`          | `100`       | 单文件下载上限                                        |
| `tools.cleanup_temp_each_turn`   | `true`      | 回合结束清理临时文件                                  |
| `tools.clipboard_auto_attach`    | `false`     | 每次输入都读剪贴板（默认改为主粘贴动作触发）          |
| `image_gen.model` / `.base_url`  | 空（未配置） | 生图模型入口（v0.4.25）：两者必填才启用；`api_key_env` 默认 `IMAGE_GEN_API_KEY` |
| `model.providers.openai.base_url` | `https://api.openai.com/v1` | OpenAI 兼容端点；支持环境变量名（如 `OPENAI_BASE_URL`，自动展开）；qwen 等模型须改为对应服务商兼容端点（如 DashScope） |

---

## ❓ 常见问题

<details><summary><b>为什么产物不在 <code>.workspace</code> 里？</b></summary>

工作空间是草稿区，项目目录是产出区。回合结束时 Axon 会把产物**自动归档**到项目目录（`downloads/`、`tmp/` 除外），页脚显示 `[文件→项目]`。也可以直接要求「写到项目目录」。

</details>

<details><summary><b>审批面板弹太多怎么办？</b></summary>

- 选 `[a]lways`：本会话内**同类命令**不再询问（粒度见 `approval_granularity`）；
- 让 Axon 在工作空间内干活（它本来就该如此）；
- 查询类命令（`dir` / `type` / `findstr`…）与安全的 `python -c` 已默认放行。

</details>

<details><summary><b>中断后怎么继续？</b></summary>

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

恢复后会回显历史对话与「未完成任务」，直接说「继续」即可。中断时的原始请求会被写入 `<interrupted_task>` 与项目记忆。

</details>

<details><summary><b>能从旧版 OPENWP 升级吗？</b></summary>

可以，数据自动迁移：`~/Documents/.openwp` → `.axon`（复制保留原目录）、`<项目>/OPENWP.md` → `AXON.md`。环境变量 `OPENWP_HOME` 仍兼容读取。

</details>

<details><summary><b>模型看得到图片吗？</b></summary>

截图 / 复制文件后回车会被收编为 `@图片1.png` 并附「名称 → 绝对路径」清单，模型可据此用脚本（PIL 等）处理图片内容。

</details>

---

## 🧪 开发

```bash
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`](designs/Axon-harness-design-v1.md)（含全部架构决策与 80 项偏差记录）。

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

---

## 📄 License

MIT © gufengaoyue
