Metadata-Version: 2.4
Name: yaping-aether
Version: 0.12.1
Summary: 双模型 Agent 框架 — 一个执行，一个学习。面向国产大模型
Project-URL: Homepage, https://github.com/AQ-july/aether
Project-URL: Repository, https://github.com/AQ-july/aether.git
Project-URL: Issues, https://github.com/AQ-july/aether/issues
Author: Aether Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai-assistant,chinese-llm,cli,llm,multi-agent,smolagents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: litellm>=1.60.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: smolagents>=1.20.0
Provides-Extra: analyst
Requires-Dist: matplotlib>=3.7; extra == 'analyst'
Requires-Dist: numpy>=1.24; extra == 'analyst'
Requires-Dist: openpyxl>=3.1; extra == 'analyst'
Requires-Dist: pandas>=2.0; extra == 'analyst'
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: embedding
Requires-Dist: sentence-transformers>=3.0; extra == 'embedding'
Provides-Extra: notify
Requires-Dist: win10toast>=0.9; (sys_platform == 'win32') and extra == 'notify'
Description-Content-Type: text/markdown

# Aether v0.12.0

**双模型 + 三阶段 Agent 框架** — Observer 观测全局，main / auditor / analyst 协作执行。

> 规划（并行三路）→ 执行（串行循环）→ 交付。面向国产大模型，终端即用。

## 安装

```bash
pip install yaping-aether
aether
```

无需配置文件，直接 CLI 传参：

```bash
aether --api-key sk-xxx --model deepseek/deepseek-chat "你的任务"
```

## 架构

```
                         Observer (qwen-turbo)
                      观测全部 Agent 执行轨迹
                     自动反思 → 生成 Skill → 去重
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         Planning          Execution        Delivery
         并行三路           串行循环          整合输出
              │               │               │
        ┌─────┼─────┐    main → auditor     analyst
        │     │     │    写代码   审代码      给建议
      计划  风险  建议    ↓ 修复 ↓
```

**Planning** — 一次 LLM 调用同时产出：任务拆解 + 风险清单 + 产品建议。

**Execution** — main 写代码 → auditor 委托审查 → main 修正，循环至多 3 轮。连续失败 ≥3 次自动从 `exec()` 切换为写 `.py` 文件 + subprocess 验证。

**Delivery** — Observer 收三路 trace，生成可复用 Skill。analyst 基于最终代码输出下一步建议。

## 更新日志

| | v0.10.0 | v0.11.0 |
|---|---------|---------|
| 架构 | 主模型一人干活，偶尔叫帮手 | 三阶段分阶段协作 |
| 委派 | LLM 猜测何时叫人 | system prompt 注入触发规则矩阵 |
| 沙箱 | 8 个授权模块，无自测能力 | 16 个模块含 subprocess/tempfile，可写 .py 跑验证 |
| 代码修复 | 失败后盲重试 | `ast.parse()` 预检 + 连续失败切换策略 |
| edit_file | 精确匹配，LLM 几乎无法使用 | 三层模糊匹配（精确→去空白→逐行相似度），失败返回文件摘要 |
| 非 TTY | 首次向导 EOFError 崩溃 | 友好提示 + `--api-key` 绕过 |
| read_file | 全量加载 >1MB 拒绝 | `head`/`tail` 分页读取，>500KB 自动截断 |
| CLI 参数 | 仅 `--mode` `--debug` | 新增 `--api-key` `--model` `--plan-model` `--max-steps` |
| 搜索 | DuckDuckGo 单一后端 | DuckDuckGo → Google 自动降级 + SerpAPI 可选 |

## 快速开始

```bash
pip install yaping-aether
aether                    # 交互式配置向导
```

CI / Docker / 脚本（非交互）：

```bash
export SUPERVISOR_API_KEY=sk-xxx
aether "统计 src/ 下所有 .py 文件行数"
```

完全命令行：

```bash
aether --api-key sk-xxx --model deepseek/deepseek-chat "写一个快速排序"
```

## 命令

| 命令 | 别名 | 用途 |
|------|------|------|
| `/mode auto/plan/step` | `/m` | 切换执行模式 |
| `/model [名称]` | `/md` | 查看/切换模型 |
| `/plan 任务` | `/p` | 生成执行计划 |
| `/usage` | `/u` | Token 用量 |
| `/status` | `/s` | 会话状态 |
| `/compact` | `/c` | 压缩上下文 |
| `/memory` | — | 查看记忆 |
| `/remember 名 描述` | `/rm` | 记录记忆 |
| `/forget 名` | — | 删除记忆 |
| `/checkpoint` | `/cp` | 快照列表 |
| `/rewind [id]` | `/w` | 回滚 |
| `/sandbox on/off` | `/sb` | Docker 沙箱 |
| `/export` | `/ex` | 导出对话 |
| `/skill [名]` | `/sk` | Skills 管理 |
| `/config` | — | 查看配置 |
| `/quit` | `/q` | 退出 |

## 配置

`.env`：

```env
SUPERVISOR_MODEL=deepseek/deepseek-chat
SUPERVISOR_API_KEY=sk-xxx
PLAN_MODEL=dashscope/qwen-turbo
# AUDITOR_MODEL=deepseek/deepseek-chat
# ANALYST_MODEL=dashscope/qwen-max
DEFAULT_MODE=auto
MAX_STEPS=15
```

优先级：CLI 参数 > 环境变量 > `.env` > `~/.aether/config.env`。

## 项目结构

```
src/aether/
├── main.py              # CLI 入口 + 事件循环
├── harness.py           # 启动流水线
├── controller.py        # 执行控制器（三层 + ast 预检 + 失败切换）
├── agent_pool.py        # Agent 池 + run_planning_phase() 三路并行
├── observer.py          # 观测模型（反思 → Skill 去重）
├── config.py            # 四层配置加载 + parse_cli_overrides()
├── registry.py          # 工具注册表
├── compact.py           # 上下文压缩
├── memory.py            # 记忆系统
├── learn.py             # 人格学习
├── supervisor.py        # 计划生成
├── commands.py          # 命令路由
├── checkpoint.py        # 文件快照
├── sandbox.py           # Docker 沙箱
├── session.py           # 会话管理
├── mcp.py               # MCP 加载
├── skill.py             # Skills 管理
├── usage.py             # Token 追踪
├── toolkit.py           # 更新检查 + 通知
├── tools/
│   ├── file_tools.py         # 文件读写（head/tail 分页）
│   ├── search_tools.py       # 搜索（DuckDuckGo → Google 降级）
│   ├── create_tools.py       # 创作（直接调 LLM）
│   ├── git_tools.py          # Git 操作
│   ├── project_tools.py      # 项目地图 + edit_file（模糊匹配）
│   ├── memory_tools.py       # 主动记忆检索
│   └── delegate_tools.py     # Agent 委派
├── cache/
│   └── semantic_cache.py     # 语义缓存
└── tests/
    └── test_agents.py         # 25 个单元测试
```

## License

Apache 2.0
