一个跨平台 AI Agent 应用，使用 Flutter 构建。Athena 具备完整的 Agent 循环（推理 → 工具调用 → 结果 → 再推理）、内置 12 个工具实现类（桌面端运行时 11 个、移动端 3 个）、可自我进化的 Skill 系统、以及严谨的权限与安全模型。
Athena 内置完整的 AI Agent，可自主调用工具完成复杂任务：
- 推理-工具循环：Agent 在每轮迭代中进行推理、调用工具、获取结果、再推理，最大 100 轮可配置
- 并行工具执行：同一轮内可并行的工具调用（只读/已放行）自动分组并发执行，最多 8 个并发，信号量限流，取消优先响应
- 流式响应：文本和推理过程（reasoning）实时流式呈现，工具调用卡片随流实时产出（参数增量逐片追加）
- 参数校验：工具调用参数在执行前经过 JSON Schema 校验，非法参数直接拒绝并返回错误信息
- 截断保护：响应被输出 token 上限切断时拒绝执行工具调用，防止截断参数被误执行
- 工具输出保护：工具结果超过 12000 字符时自动保留头尾、截断中间，防止过长输出挤占上下文
- 取消令牌：支持随时中断 Agent 运行，取消时保留已生成内容并标记
[Cancelled] - 自动压缩：上下文占用超过窗口 80% 时自动将早期对话压缩为摘要（
retention = -1模式），保持长对话可继续 - 消息注入：支持运行时注入 steering 消息（当前轮工具执行后、下一轮推理前）与 followUp 消息（Agent 停止后继续运行）
| 工具 | 说明 |
|---|---|
bash / powershell |
执行终端命令，支持自定义工作目录和超时（最高 600s），超时自动 kill 进程 |
file_read |
读取文件，支持 offset/limit 分段读取和行号输出 |
file_write |
创建或覆写文件，自动递归创建父目录 |
file_update |
精确字符串替换编辑文件，支持 replace_all、自动去除行号前缀、智能引号归一化、外部修改检测 |
web_fetch |
HTTP GET/POST 抓取网页（200KB 上限），支持自定义 headers 和 body，自动 HTML→Markdown 转换 |
web_search |
Brave Search API 网络搜索，为 Agent 提供实时信息 |
skill |
加载 Skill 的完整 Level 2 指令到当前上下文 |
skill_evolve |
Agent 自我进化：创建/更新 Skill（SKILL.md），扩展未来能力 |
experience_learn |
记录经验教训到长期记忆，支持标签和上下文、Sentinel 私有或全局共享 |
experience_recall |
检索过往经验以指导当前任务 |
sentinel_evolve |
改进当前角色（系统提示词），支持重命名、原地更新，内置 Sentinel 不可改名 |
三层决策，自动放行绝大多数调用：
- 只读短路：只读工具（file_read、web_fetch、web_search）和只读 shell 命令（ls、git status 等）永不弹窗
- 会话级缓存：当前对话中已批准过的调用直接放行，同一轮内不再重复弹窗
- 用户持久化规则：
~/.athena/permissions.json存储匹配规则，支持*和?通配符；shell 命令可记忆为动作级规则（如git push*）。命中则直接放行，不弹窗。
未命中时弹出完整命令预览弹窗（shell 命令全文展示不截断），用户可选 Allow/Deny，并可将本次批准记忆为会话级或持久化规则。弹窗不可被空白点击关闭。
独立于权限系统，在工具内部执行的安全检查：
- 递归删除拦截：bash/powershell 检测到
rm -rf、del /s等模式时拒绝执行 - Shell 进程管理：超时主动 SIGTERM → SIGKILL 杀死进程，防止孤儿进程泄漏
- 文件修改检测：
file_update在写入前校验 mtime，防止覆盖外部并发修改
采用 Claude Code 风格的三级渐进式加载：
| 层级 | 内容 | 加载时机 | Token 消耗 |
|---|---|---|---|
| Level 1 | name + description（最近使用 Top 20，按访问时间排序） | 由 skill 工具按名加载时提示可用技能清单（当前版本未在会话启动时自动注入） |
按需 |
| Level 2 | SKILL.md 完整指令 | Agent 调用 skill("name") 时按需加载 |
按需 |
| Level 3 | scripts/references 等资源 | Level 2 指令引用时加载 | 按需 |
最多展示最近使用的 20 个 Skill（按访问时间排序），其余需显式调用。
---
name: my-skill
description: What this skill does and when to use it
allowed-tools: file_read, web_search
---
## Process
1. Step one
2. Step two~/.athena/skills/— 用户级（始终信任，所有项目可用）.athena/skills/— 项目级（可随版本控制，首次加载需用户确认信任）
项目级 Skill 在信任后可覆盖同名用户级 Skill。内置 self-evolve Skill 提供完整的自我进化指导。
- 未信任的项目级 Skill 不出现在 Level 1 列表，不可通过
skill工具加载 - 信任状态持久化到
~/.athena/trusted_skill_dirs.json - 每次会话仅提示一次信任弹窗
- 信任后 Skill 指令会注入系统提示词，但工具调用仍需经过权限检查
Agent 可通过三个机制持续改进自身：
- Skill Evolution（
skill_evolve）：创建或改进 Skill，扩展未来能力 - Experience Learning（
experience_learn/experience_recall）：构建长期经验记忆，存储在~/.athena/experiences/ - Sentinel Optimization（
sentinel_evolve）：基于使用反馈优化系统提示词
每次对话自动注入极简进化提示（~30 token），完整指南通过内置 self-evolve Skill 按需加载。
- Sentinel 系统：预定义角色和系统提示词，支持 AI 元数据生成（名称、描述、标签、头像 Emoji），内置默认 "Athena" Sentinel
- 多 AI 提供商管理：支持 OpenAI API 兼容的任何提供商，预设 DeepSeek、OpenRouter、阿里云百炼、硅基流动、火山方舟、智谱、MiniMax；启动时后台自动从 models.dev 同步模型元数据（7 天缓存，失败降级）
- 重试机制：指数退避 + 随机抖动，可重试网络错误（连接异常、超时、限流、5xx），不重试业务错误（4xx、解析错误）
- 聊天管理：会话置顶、批量删除、AI 自动命名、上下文管理（零上下文 / 自动压缩 / 全量）、温度参数调整、Token 用量追踪
- 视觉与推理：支持视觉模型（图片附件）和推理模型（DeepSeek-R1 等 reasoning 展示）
- 数据导入/导出：JSON 格式完整数据迁移，自动重整悬空引用
内置 5 个场景化快捷入口（Translation、Summary、Food、Code、TRPG），每个绑定独立的专属 Sentinel（能力配置）：
- 点击后以其绑定 Sentinel 身份发起对话，支持场景级 JSON 输出模式（模型直接产出结构化 JSON）
- Translation / Summary / TRPG 快捷入口直接打开对应的定制功能页，Food / Code 进入默认聊天页
- 网页摘要：AI 解析网页内容，生成结构化摘要
- 文本翻译：AI 多语言翻译
- 网络搜索：Brave Search 集成
- TRPG 游戏：AI 驱动的桌面角色扮演游戏，含行动建议和状态面板
- 桌面端：macOS、Windows、Linux。窗口管理、系统托盘、全局快捷键（Meta+W 隐藏）
- 移动端：iOS、Android。触摸优化界面
- Flutter SDK >= 3.8.0
- Dart SDK >= 3.8.0
项目为 monorepo 多包结构：athena_core（纯 Dart 核心）与 athena_gui（Flutter 应用）。
git clone https://github.com/CalsRanna/athena.git
cd athena/packages/athena_gui
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter run -d <device># GUI（Flutter 应用）
cd packages/athena_gui
flutter analyze # 静态代码分析
flutter test # 运行 GUI 测试
# 核心（纯 Dart，无 Flutter 依赖）
cd packages/athena_core
dart analyze
dart test # 运行核心测试（Agent 引擎、服务、工具等）项目拆分为两个 package，依赖方向严格单向：athena_gui → athena_core。
packages/
├── athena_core/ # ★ 纯 Dart 核心，零 Flutter / 零 SQL 依赖
│ ├── agent/ # Agent 引擎：工具、权限、Skill、进化、取消令牌
│ ├── coordinator/ # AgentRunCoordinator：UI 无关的 run 编排层（RunEvent 流）
│ ├── service/ # LlmClient、Chat、Summary、Translation、TRPG 等
│ ├── repository/ # 存储接口（Chat/Message/Model/Provider/...）
│ ├── entity/ model/ preset/ extension/ util/
│ └── storage/ # KeyValueStore 接口 + AgentSettings
└── athena_gui/ # ★ Flutter 应用
├── page/ # UI 层（desktop 多区工作台 / mobile 分段浏览）
├── view_model/ # Signals 状态管理
│ └── delegate/ # AgentStreamDelegate：包装核心协调层 + 对话框注入
├── repository/ # SQLite 实现（SqliteChatRepository 等）
├── database/ # SQLite + Laconic ORM + 迁移
├── router/ widget/ component/ util/
└── storage/ # KeyValueStore 的 SharedPreferences 实现
核心通过存储接口（repository/）与注入回调（权限审批、Skill 信任）
与持久化策略解耦：GUI 用 SQLite + SharedPreferences；未来 TUI 可实现同一组
接口用 JSONL/文件存储。
| 层 | 技术 |
|---|---|
| UI | Flutter（athena_gui） |
| 核心 | 纯 Dart（athena_core，零 Flutter 依赖） |
| 状态管理 | Signals（Computed、Signal、listSignal、setSignal） |
| 依赖注入 | GetIt（LazySingleton，仅 GUI 装配层） |
| 路由 | AutoRoute（桌面无过渡，移动标准过渡） |
| 数据库 | SQLite + Laconic ORM（GUI 侧实现，PRAGMA foreign_keys = ON） |
| AI API | openai_dart v5.0.0（流式 + 工具调用 + 推理） |
| HTTP | http v1.x（web_fetch、web_search） |
| 测试 | athena_core：dart test；athena_gui：flutter test |
┌─────────────────────────────────────────────┐
│ athena_gui（Flutter） │
│ UI Layer（page / widget / component） │
│ ViewModel Layer（signals + Delegate 委托） │
│ SQLite 实现（repository / database） │
├─────────────────────────────────────────────┤
│ athena_core（纯 Dart） │
│ AgentRunCoordinator（run 编排层，RunEvent）│
│ Service Layer（LLM 通信 / 数据转换 / 编排）│
│ Repository 接口（存储抽象，port） │
│ Agent Layer（Agent Service / Tool / │
│ Permission / Skill） │
│ Entity / Storage / Util │
└─────────────────────────────────────────────┘
GUI 通过 GetIt 装配：注入 SQLite 实现 +
权限弹窗 / Skill 信任回调（TUI 可注入替代实现）
在应用内设置页面添加 OpenAI API 兼容的提供商。预设包括：
| 提供商 | 内置模型示例 |
|---|---|
| DeepSeek | deepseek-chat, deepseek-reasoner |
| OpenRouter | Claude 3.5 Sonnet, GPT-4o, Gemini 2.0 Flash, Llama 3.3 等 |
| 阿里云百炼 | 通义千问系列, DeepSeek 系列 |
| 硅基流动 | DeepSeek 系列 |
| 火山方舟 | 豆包系列, DeepSeek 系列 |
| 智谱 | GLM 系列 |
| MiniMax | MiniMax-Text-01 |
模型元数据（名称、上下文窗口、价格、reasoning/vision 标志）由应用启动时后台从 models.dev 自动同步，预设模型列表随上游更新，无需手工维护。
- 创建
SKILL.md文件，包含 YAML front matter 和 Markdown body - 放入
~/.athena/skills/<skill-name>/（用户级）或.athena/skills/<skill-name>/（项目级） - 重启应用或新开会话即可发现
用户持久化规则存储在 ~/.athena/permissions.json，格式：
{
"rules": [
{"tool": "bash", "action": "git", "pattern": "push*"},
{"tool": "bash", "pattern": "ls *"},
{"tool": "file_read", "pattern": "/home/user/projects/*"},
{"tool": "web_fetch", "pattern": "https://example.com"}
]
}- 文件类工具（file_read / file_write / file_update）：pattern 为路径，支持
*/?通配符 - Shell 工具（bash / powershell）：action 为命令动作（git、ls、npm…），pattern 为参数模式；不加通配符时按前缀匹配
- web_fetch：pattern 为 URL origin（scheme://host[:port]）
- pattern 为空表示允许该工具（及 action，若指定）的所有调用
项目为双包结构，共 35 个测试文件，覆盖：
- Agent 层（athena_core）：工具执行、并行执行分组、权限规则、Skill 加载与信任、Shell 进程管理、Schema 校验
- Service 层（athena_core）：消息转换、聊天服务、会话管理、模型目录同步
- ViewModel 层（athena_gui）：聊天流、设置、摘要、翻译、TRPG
- UI 层（athena_gui）：移动端主页和聊天页 widget 测试
- 数据库（athena_gui）：迁移、CASCADE 行为验证
# 核心包（纯 Dart）
cd packages/athena_core && dart test
# GUI 包（Flutter）
cd packages/athena_gui && flutter test- Fork 仓库
- 创建功能分支 (
git checkout -b feature/xxx) - 提交更改 (
git commit -m 'Add xxx') - 推送 (
git push origin feature/xxx) - 创建 Pull Request
MIT License