# aide

**Repository Path**: SlayerNux_admin/aide

## Basic Information

- **Project Name**: aide
- **Description**: No description available
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Aide

基于消息循环驱动的自主 AI 生产力工具，使用 Rust 实现。

核心设计哲学：**尽可能少地使用代码定义流程，做好记忆能力，让 LLM 自己决策如何做事情。**

## 特性

- **Agent 消息循环** — LLM 驱动的工具调用循环，自然终止，上下文自动压缩
- **Agent 群组系统** — 按"开发团队"思路组织多 Agent 协作，群聊模型，消息广播
- **Workflow 自然语言流程** — 从文本文档导入流程树，LLM 自主推进，检查点保证可审计性
- **Agent 执行状态** — Running/Idle/Cancelled 三态管理，CancellationToken 取消控制，执行日志
- **增强 Heartbeat 晶振** — 定期唤醒 Agent，构建完整上下文，LLM 自主决策下一步行动
- **两层工具策略引擎** — 管理员层 + 用户层分层访问控制，支持 Profile/Group/Session 粒度
- **索引目录记忆系统** — MEMORY.md 结构化索引注入系统提示词，LLM 自主决定读取详细文件
- **SQLite FTS5 历史搜索** — 每日笔记全文检索，支持 BM25 排名
- **技能系统** — 目录级能力包，YAML front matter 元数据，三级优先级懒加载
- **Docker 沙箱** — 只读根文件系统、无网络、drop ALL capabilities
- **用户画像** — 领域识别、沟通风格、工具使用统计，自动学习
- **现代化 TUI** — Solo/Team 双模式布局，完整鼠标交互，Docking 可拖拽面板

## 架构概览

```
TUI (ratatui) ──► GroupManager ──► Agent（异步, tokio）
                       │                    │
                       ├── AgentGroup       ├── LLM Provider（OpenAI 兼容）
                       ├── Workflow Tree    ├── 工具注册表 + 策略引擎
                       └── Heartbeat 定时器 └── 记忆管理器（SQLite + FTS5）
```

| 子系统 | 说明 | 入口文件 |
|--------|------|----------|
| Agent | 异步消息循环，支持 CancellationToken 取消 | `src/agent.rs` |
| 群组系统 | 多 Agent IM 式群聊协作 | `src/group.rs` |
| 工作流 | 自然语言流程树 + Soft/Hard 检查点 | `src/workflow.rs` |
| 记忆系统 | 索引目录架构 + FTS5 全文搜索 | `src/memory/mod.rs` |
| 工具系统 | 注册表 + 两层策略引擎 + Docker 沙箱 | `src/tools/mod.rs` |
| TUI | ratatui 终端界面，Solo/Team 布局，鼠标交互 | `src/tui/mod.rs` |
| 配置 | TOML 配置 + `.aide/` 目录结构 | `src/config.rs`、`src/dotaide.rs` |
| 调度器 | Heartbeat 晶振 + 定时任务 | `src/scheduler.rs` |

### Agent 群组

按"开发团队"思路组织 Agent 协作——定义角色、拉群、给流程文档，然后让 Agent 们自己干活。群组内所有消息对所有成员可见（群聊模型），Agent 基于自身角色和消息上下文自主决定何时发言和行动。

### Workflow 自然语言流程

从纯文本流程文档导入生成 Workflow 树状结构，LLM 自主判断阶段完成并推进流程：

- **Soft 检查点**：通知用户，不阻塞后续流程
- **Hard 检查点**：暂停所有依赖该节点的后续流程，等待人工审查

### Heartbeat 晶振

Agent 通过可配置频率的 Heartbeat 定期唤醒（默认 15 分钟），唤醒后 LLM 自主检查记忆、群组消息和待处理事项，决定下一步行动。不是"执行任务清单"，而是赋予 Agent 自主决策能力。

详细架构说明参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)，API 参考参见 [`docs/API.md`](docs/API.md)，使用示例参见 [`docs/EXAMPLES.md`](docs/EXAMPLES.md)。

## 快速开始

```bash
# 1. 编译
cargo build --release

# 2. 首次运行（Setup Wizard 自动引导配置）
./target/release/aide                           # 交互模式
./target/release/aide -p "你好"                  # 单次查询
echo "审查这段代码" | ./target/release/aide -p   # 管道输入
```

## 构建

### 前置条件

- **Rust nightly 工具链**（1.85.0+，edition 2024）
  - 项目包含 `rust-toolchain.toml`，会自动使用 nightly 工具链
  - 安装/更新 nightly：`rustup update nightly`
- 可选：Docker（沙箱执行）

### 编译

```bash
cargo build --release
```

产物位于 `target/release/aide`。

### 主要依赖

| Crate | 用途 |
|-------|------|
| `tokio` | 异步运行时 |
| `ratatui` + `crossterm` | TUI 框架 + 终端控制 |
| `serde` + `serde_json` + `toml` + `serde_yaml` | 序列化（JSON、TOML、YAML） |
| `rusqlite`（bundled-full） | SQLite + FTS5 全文搜索 |
| `reqwest` | HTTP 客户端（LLM API） |
| `clap` | 命令行参数解析 |
| `syntect` | 代码语法高亮 |
| `termimad` | 终端 Markdown 渲染 |
| `thiserror` | 结构化错误类型 |
| `tracing` | 结构化日志 |
| `proptest`（dev） | 属性测试 |
| `mockall`（dev） | Mock trait |
| `criterion`（dev） | 基准测试 |

## 测试

### 运行全部离线测试

```bash
cargo test
```

包含 815+ 个测试（属性测试、集成测试、端到端测试），无需 API 密钥。

### 运行特定模块测试

```bash
cargo test memory::          # 记忆系统
cargo test tools::           # 工具系统
cargo test workflow::        # 工作流引擎
cargo test agent::           # Agent 循环
cargo test config::          # 配置管理
cargo test group::           # 群组系统
cargo test execution::       # Agent 执行状态
```

### 运行属性测试

```bash
cargo test "prop_"           # 所有属性测试
cargo test --test memory_index_parser_props      # 索引解析往返
cargo test --test memory_write_read_props         # 写入-读取往返
cargo test --test memory_hits_props               # 访问计数递增
cargo test --test memory_search_limit_props       # 搜索 limit 约束
cargo test --test memory_backup_props             # 索引备份一致性
cargo test --test memory_archive_props            # 归档保留文件
cargo test --test memory_prompt_injection_props   # 索引注入提示词
```

### 运行异步架构集成测试

```bash
cargo test --test e2e_async_agent                # 端到端异步 Agent 测试
cargo test --test group_isolation_integration    # 群组隔离测试
cargo test --test workflow_integration           # Workflow 集成测试
```

### 运行真实 LLM 集成测试

需要设置 `AIDE_API_KEY` 环境变量，这些测试标记为 `#[ignore]`，默认不运行：

```bash
export AIDE_API_KEY="sk-..."
cargo test -- --ignored                          # 运行所有 ignored 测试
cargo test --test integration_llm -- --ignored   # LLM API 基础测试
cargo test --test integration_llm_full -- --ignored  # 完整工具链集成测试
```

### 代码检查

```bash
cargo clippy                 # lint 检查
cargo fmt --check            # 格式检查
```

## 使用

### 交互模式

```bash
aide
```

进入 TUI 交互界面。Header 提供 4 个标签页（Chat / Skills / Agents / Groups），可鼠标点击切换。

### 键盘快捷键

#### 全局

| 快捷键 | 功能 |
|--------|------|
| `Tab` | 焦点循环切换 |
| `Ctrl+L` | 切换 Solo/Team 布局模式 |
| `Ctrl+,` | 打开设置 |
| `Ctrl+O` | 切换工具输出展开/折叠 |
| `Ctrl+C` | 强制退出 |
| `Esc` | 取消/打断当前操作，连按两次弹出退出确认 |

#### Chat 模式

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Up` / `Down` | 浏览输入历史 |
| `Backspace` | 删除字符 |

#### Skills / Agents / Groups 列表

| 快捷键 | 功能 |
|--------|------|
| `Up` / `Down` | 列表导航 |
| `Enter` | 执行选中技能 |
| `1`-`9` | 快速切换到第 N 个群组（仅 Groups 视图） |

#### Skill 执行中（检查点审查）

| 快捷键 | 功能 |
|--------|------|
| `a` | 批准检查点（Approve） |
| `r` | 拒绝检查点并输入反馈（Reject） |

#### Settings 视图

| 快捷键 | 功能 |
|--------|------|
| `Up` / `Down` | 菜单导航 |
| `Enter` | 进入子项 / 编辑 |
| `n` | 新建资源 |
| `e` | 编辑选中资源 |
| `d` | 删除选中资源 |
| `s` | 设为默认模型（仅 Models 列表） |
| `a` | 打开 LLM 助手辅助生成 |
| `Ctrl+S` | 保存修改 |
| `Tab` | 移到下一个字段 |
| `Esc` | 返回上级 / 退出编辑 |

#### Setup Wizard

| 快捷键 | 功能 |
|--------|------|
| `Left` / `Right` | 步骤前进 / 后退 |
| `1`-`6` | 跳转到已完成的步骤 |
| `Up` / `Down` | 选择选项 |
| `Enter` | 确认选择 |

### 鼠标操作

| 操作 | 功能 |
|------|------|
| 点击 Header 标签 | 切换视图 |
| 点击列表项 | 选中（双击执行技能） |
| 点击输入框 | 定位光标 |
| 拖拽输入框文本 | 文本选择 |
| 拖拽 Dock 分隔线 | 调整侧边栏宽度（Team 模式） |
| 双击 Dock 分隔线 | 重置为默认宽度 |
| 滚轮 | 各区域独立滚动 |

### 布局模式

按 `Ctrl+L` 在两种模式间切换，Footer 右侧显示当前模式名称：

- **Solo**（默认）：全屏聊天 — Header + ChatView + InputBox + Footer
- **Team**：多面板 IM 布局 — Header + [IM_Sidebar | 分隔线 | 主内容区] + InputBox + Footer
  - 主内容区子标签：Chat | Workflow | Review
  - 焦点环扩展为：IMSidebar → ChatView → WorkflowPanel → ReviewPanel → InputBox

### 斜杠命令

在输入框中输入斜杠命令：

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/new [标题]` | 创建新会话 |
| `/switch <id>` | 切换会话 |
| `/memory search <query>` | 搜索记忆 |
| `/memory forget <query>` | 删除记忆 |
| `/memory status` | 记忆状态 |
| `/profile` | 查看用户画像 |
| `/model [名称]` | 切换模型 |
| `/compact` | 手动压缩上下文 |
| `/skill list` | 列出技能 |
| `/workflow list` | 列出工作流 |
| `/quit` | 退出 |

### 单次查询（Print Mode）

```bash
aide -p "解释这段代码的作用"
```

输出不带装饰，适合管道和脚本：

```bash
cat main.rs | aide -p "审查这段代码"
```

### 命令行参数

| 参数 | 说明 |
|------|------|
| `<prompt>` | 初始提示词 |
| `-p, --print` | 单次查询后退出 |
| `-c, --continue-session` | 继续最近会话 |
| `-r, --resume <id>` | 恢复指定会话 |
| `--config <path>` | 指定配置文件 |
| `--model <name>` | 指定模型 |

## 配置

### 配置文件

Aide 启动时按以下优先级自动搜索配置文件：

1. `--config <path>` 命令行参数（最高优先级）
2. `./aide.toml`（当前工作目录）
3. `~/.config/aide/aide.toml`（用户配置目录，Windows: `%APPDATA%\aide\aide.toml`）

找到第一个存在的文件即加载，全部不存在则自动进入 Setup Wizard 引导配置。

### aide.toml 主要字段

```toml
default_model = "model-id"       # 引用 .aide/models/<id>.md
log_level = "info"               # debug, info, warn, error
data_dir = "..."                 # 数据存储目录
agent_max_turns = 50             # 单次 Agent 调用最大 LLM 轮次
theme = "Dark"                   # TUI 主题

[heartbeat]
interval_secs = 900              # Heartbeat 间隔（默认 15 分钟）
min_interval_secs = 60           # 最小间隔
enabled = false                  # 是否启用

[sandbox]
mode = "Off"                     # Off / NonMain / All
workspace_access = "ReadWrite"   # None / ReadOnly / ReadWrite
network = false                  # 是否允许网络
```

### `.aide/` 目录结构

```
.aide/
├── agents/<name>/      # Agent 定义（目录结构）
│   ├── agent.md        # front-matter 配置（id、name、role、model、skills）
│   └── soul.md         # Agent 身份描述（注入系统提示词）
├── skills/<name>/      # 技能定义（统一替代原 workflows）
│   └── skill.md        # front-matter（name、description、tags、requirements）+ 正文
├── groups/<name>.toml  # 群组配置（members、workflow、heartbeat、preferences）
└── models/<name>.md    # 模型配置（api_endpoint、api_key、模型参数）
```

### 模型配置

模型配置存放在 `.aide/models/` 目录下，每个模型一个 Markdown 文件（YAML front-matter 格式）：

```markdown
---
id: gpt-4
name: GPT-4
api_endpoint: https://api.openai.com/v1
api_key: ${OPENAI_API_KEY}
model: gpt-4
temperature: 0.7
---

OpenAI GPT-4 模型。
```

API Key 支持 `${ENV_VAR}` 语法引用环境变量，避免明文存储。

### 环境变量

环境变量优先级高于配置文件：

| 变量 | 说明 |
|------|------|
| `AIDE_API_KEY` | API 密钥 |
| `AIDE_API_ENDPOINT` | LLM API 端点 |
| `AIDE_MODEL` | 模型名称 |
| `AIDE_LOG_LEVEL` | 日志级别 |

## 记忆系统

Aide 使用索引目录架构管理知识，三层记忆：

```
data_dir/
├── MEMORY.md              # 结构化索引（注入系统提示词）
├── MEMORY.md.bak          # 索引备份
├── PREFERENCES.md         # 用户偏好（跨 Agent 共享）
└── memory/
    ├── coding/            # 编码知识
    ├── projects/          # 项目知识
    └── daily/             # 每日笔记（FTS5 全文索引）
        ├── 2026-03-01.md
        └── 2026-03-09.md
```

索引条目格式：`- 摘要 [文件路径] (hits: N, updated: YYYY-MM-DD)`

LLM 自主决定记忆层级提升：每日笔记（事实）→ MEMORY.md（规律）→ Profile（稳固规则）。

工具集：

| 工具 | 说明 | 权限 |
|------|------|------|
| `memory_get` | 读取记忆文件，递增 hits | AlwaysAllow |
| `memory_write` | 写入记忆文件，自动维护索引 | AlwaysAllow |
| `history_search` | FTS5 全文搜索每日笔记 | AlwaysAllow |

## 工具系统

两层策略引擎（管理员层 + 用户层）控制工具访问权限，支持 Profile/Group/Session 粒度。

工具组：`fs`（文件操作）、`runtime`（Shell 执行）、`memory`（记忆读写）、`session`（会话管理）、`web`（HTTP）、`ui`（终端交互）、`automation`（定时任务）、`messaging`（消息发送）。

内置工具在启动时注册。技能从 `.aide/skills/` 目录懒加载，优先级：工作区 > 用户级 > 内置。

## TUI 界面

### 布局模式

- **Solo 模式**（默认）：全屏聊天 — Header + ChatView + InputBox + Footer
- **Team 模式**：多面板 IM 布局 — Header + [IM_Sidebar | DockDivider | 主内容区] + InputBox + Footer
  - 主内容区标签：Chat | Workflow | Review
  - DockDivider 支持鼠标拖拽调整面板大小

### 鼠标交互

- **点击**：标签切换、列表选择、焦点转移、Picker 选择
- **悬停**：标签/列表项/按钮的视觉高亮反馈
- **拖拽**：输入框文本选择、面板大小调整
- **滚轮**：各区域独立滚动（ChatView、SkillList、Picker、InputBox、IM_Sidebar）

### 配置面板

- **Skill 编辑器**：创建、导入、LLM 辅助生成、检视和修改技能定义
- **Agent 配置面板**：查看和编辑 Agent 身份、模型、工具权限、技能过滤器
- **Team 配置面板**：查看和编辑群组成员、Workflow 关联、Heartbeat 设置

## 项目结构

```
src/
├── main.rs              # 入口，组件串联
├── lib.rs               # 库 crate 导出
├── agent.rs             # Agent 消息循环（异步、可取消）
├── app.rs               # 应用编排
├── bootstrap.rs         # 引导文件加载（SOUL.md 等）
├── cli.rs               # CLI 参数解析（clap）
├── config.rs            # TOML 配置管理
├── dotaide.rs           # .aide/ 目录配置加载器
├── error.rs             # 错误类型层次（thiserror）
├── execution.rs         # Agent 执行状态（Running/Idle/Cancelled）+ 执行日志
├── group.rs             # Agent 群组系统（GroupManager、AgentGroup、GroupMessage）
├── llm.rs               # LLM Provider（OpenAI 兼容 API + 重试）
├── migration.rs         # 数据库迁移
├── models.rs            # 核心数据模型（Message、Role、ToolCall）
├── profile.rs           # 用户画像
├── prompts.rs           # 提示词模板管理
├── provider_registry.rs # LLM 提供者注册表
├── scheduler.rs         # Heartbeat & 定时任务调度器
├── testing.rs           # 测试辅助工具
├── workflow.rs          # 工作流树（WorkflowTree、WorkflowNode）
├── memory/
│   ├── mod.rs           # MemoryManager（索引目录 + FTS5）
│   └── index_parser.rs  # MEMORY.md 索引解析器
├── tools/
│   ├── mod.rs           # ToolProfile 工具组管理
│   ├── registry.rs      # 工具注册表 & 并行执行
│   ├── policy.rs        # 两层策略引擎（管理员层 + 用户层）
│   ├── skills.rs        # 技能系统（懒加载、三级优先级）
│   ├── sandbox.rs       # Docker 沙箱执行器
│   └── builtins.rs      # 内置工具实现
└── tui/
    ├── mod.rs           # TUI 模块入口
    ├── app.rs           # TUI 事件循环 + 鼠标事件处理
    ├── state.rs         # TUI 状态管理
    ├── events.rs        # 事件类型（TuiEvent）
    ├── commands.rs      # 斜杠命令解析
    ├── theme.rs         # 主题系统（深色/浅色、悬停、焦点样式）
    ├── focus.rs         # 焦点管理（FocusState、FocusTarget）
    ├── hit_area.rs      # 鼠标点击区域注册表（HitAreaRegistry）
    ├── hover.rs         # 悬停状态追踪
    ├── docking.rs       # Docking 面板系统（Solo/Team 布局）
    ├── im_sidebar.rs    # IM 侧边栏状态
    ├── input_selection.rs # 输入框文本选择
    ├── review_panel.rs  # 评审面板状态
    ├── workflow_panel.rs # 工作流进度面板状态
    ├── skill_editor.rs  # Skill 编辑器状态
    ├── agent_config.rs  # Agent 配置面板状态
    ├── team_config.rs   # Team 配置面板状态
    ├── field_mapping.rs # 表单字段映射
    ├── settings_state.rs # 设置状态
    ├── setup_wizard.rs  # Setup Wizard 状态
    ├── llm_assistant.rs # LLM 辅助创建集成
    └── ui/
        ├── mod.rs           # UI 模块入口
        ├── layout.rs        # 布局（Solo/Team 模式渲染）
        ├── header.rs        # 顶部标签栏
        ├── footer.rs        # 分段式底栏
        ├── input.rs         # 输入框（文本选择）
        ├── chat.rs          # 对话视图
        ├── skill_list.rs    # 技能列表
        ├── picker.rs        # 弹出式选择器
        ├── im_sidebar.rs    # IM 侧边栏渲染
        ├── team_content.rs  # Team 模式主内容区
        ├── workflow_panel.rs # 工作流进度渲染
        ├── review_panel.rs  # 评审面板渲染
        ├── skill_editor.rs  # Skill 编辑器渲染
        ├── agent_config.rs  # Agent 配置渲染
        ├── team_config.rs   # Team 配置渲染
        ├── agents.rs        # Agent 列表视图
        ├── agent_detail.rs  # Agent 详情视图
        ├── groups.rs        # 群组视图
        ├── flow_list.rs     # Flow 列表视图
        ├── flow_execution.rs # Flow 执行视图
        ├── settings.rs      # 设置 UI
        ├── setup_wizard.rs  # Setup Wizard UI
        ├── config_editor.rs # 配置编辑器 UI
        ├── resource_editor.rs # 资源编辑器 UI
        ├── status.rs        # 状态栏
        └── widgets/
            ├── mod.rs       # 组件模块
            ├── markdown.rs  # Markdown 渲染器
            ├── message.rs   # 消息组件
            └── syntax.rs    # 语法高亮组件
```

## 许可证

MIT