# selfagent

**Repository Path**: HiGrant/selfagent

## Basic Information

- **Project Name**: selfagent
- **Description**: 个人尝试性项目, 开发具有自我进化能力的AI Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/HiGrant/selfagent
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, Agent

## README

# Self-Evolving AI Agent 使用说明

## 项目架构

```
selfagent/
├── Cargo.toml                    # Workspace 根配置
└── crates/
    ├── agent-core/               # 核心类型系统（Message, ContentBlock, ToolHost trait, 权限, 压缩）
    ├── agent-llm/                # LLM 适配层（OpenAI/Anthropic/DeepSeek, SSE 流式）
    ├── agent-store/              # 会话持久化（JSONL append-only log）
    ├── agent-memory/             # 记忆宫殿（zone 分区 + 超越链 + 效果追踪 + 遗忘衰减）
    ├── agent-skills/             # 技能系统（BM25 + 触发词混合检索 + 效果追踪）
    ├── agent-tools/              # 13 个内置工具（read/write/edit/bash/grep/glob/git/think/todo 等）
    ├── agent-mcp/                # MCP 协议层（stdio + HTTP, CompositeToolHost）
    ├── agent-reflect/            # 自省引擎（micro 反思 + 全量反思 + profile 编译 + 审计日志）
    ├── agent-turn/               # 核心执行引擎（工具并行 + 权限分类 + 上下文压缩 + Agent 主循环）
    ├── agent-cli/                # CLI 前端（REPL + slash commands + chat/ask/agent 子命令）
    └── agent-gui/                # 桌面前端（预留）
```

## 编译项目

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

编译完成后，可执行文件在 `target/release/self-agent`（Windows 下为 `self-agent.exe`）。

## 配置

有两种方式配置 LLM API Key：

### 方式 A：环境变量（最简单）

```bash
# 三选一，程序会按优先级自动检测
set ANTHROPIC_API_KEY=sk-ant-xxx     # 优先级最高
set DEEPSEEK_API_KEY=sk-xxx          # 优先级第二
set OPENAI_API_KEY=sk-xxx            # 优先级第三
```

### 方式 B：配置文件（更灵活）

在 `~/.self-agent/config.toml` 创建配置文件：

```toml
[provider]
provider = "anthropic"             # 可选: openai, anthropic, deepseek
api_key = "sk-ant-xxx"
model = "claude-sonnet-4-20250514"
base_url = "https://api.anthropic.com"
max_tokens = 4096
temperature = 0.7

model_limit = 128000               # 模型上下文窗口大小
headroom = 0.18                    # 压缩触发阈值（保留18%给回复）

[permissions]
allow = ["read", "grep", "glob"]   # 自动允许的工具
deny = ["memory_delete"]           # 永远拒绝的工具

[[mcp_servers]]                    # MCP 服务器配置（可选）
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```

## 三种使用模式

### Chat 模式 — 交互式对话（带记忆、技能、反思）

```bash
self-agent chat              # 开始新会话
self-agent chat --resume     # 恢复上次会话
```

进入 REPL 后，提示符为 `self-agent>`：

```
self-agent> 帮我看看这个项目的结构
self-agent> 我喜欢用 rust 写代码，记住这个偏好
self-agent> /memory          # 查看当前所有活跃记忆
self-agent> /skills          # 查看所有技能
self-agent> /reflect         # 触发全量反思
self-agent> /compile         # 编译用户画像（节省 token）
self-agent> /clear           # 清空当前会话
self-agent> /quit            # 退出
```

### Ask 模式 — 单次提问

```bash
self-agent ask "解释一下 Rust 的所有权机制"
```

一问一答，不进入交互模式。

### Agent 模式 — 自主任务执行

```bash
self-agent agent "给 src/main.rs 加上错误处理"
```

Agent 会进入 **PLAN → EXECUTE → VERIFY** 自主循环：

1. **PLAN**：用 `think` 分析目标，用 `todo_add` 创建步骤计划
2. **EXECUTE**：逐步执行计划，用 `todo_update` 标记进度
3. **VERIFY**：测试或审查后声明完成

最多自动迭代 20 轮，直到输出 `[GOAL_COMPLETE]` 或 `[GOAL_FAILED]`。

## 工具确认交互

当 Agent 调用危险工具（bash、write、edit、memory_save、memory_delete、MCP 工具）时，会弹出确认：

```
⚠ Confirm bash: [y/a/N] or type feedback:
```

- **y** — 允许本次执行
- **a** — 永久允许这个工具（自动加入 allow 列表）
- **N**（直接回车）— 拒绝执行
- **输入任意文字** — 作为反馈返回给 LLM（例如："不要删除文件"）

## 核心特点

### 记忆宫殿 — 不是数据库，是认知架构

```
记忆宫殿
├── core/          — 用户身份、偏好、原则（几乎不变）
├── work/          — 当前焦点、近期决策（中频更新）
├── project:xxx/   — 项目级约定和上下文（按项目隔离）
├── episode/       — 会话摘要（高频写入）
└── general/       — 未分类（兜底）
```

**超越链（Supersedes Chain）**：新记忆不会删除旧记忆，而是通过 `supersedes` 字段标记替代关系。`list_active()` 自动过滤掉被传递性超越的记忆，但历史可追溯。

**效果追踪（Effectiveness Tracking）**：每条记忆追踪 `Loaded`（被注入 context）和 `Referenced`（被 LLM 实际引用）两个事件，计算 effectiveness factor（0.5~1.0）。低效记忆自动降权但不删除——它可能只是暂时不相关。

**遗忘衰减（Decay Factor）**：长时间未被引用的记忆按半衰期衰减权重，模拟人类遗忘曲线。

### 自省引擎 — Agent 的元认知

- **Micro 反思**：每 3 轮对话后自动异步执行（`tokio::spawn`，不阻塞用户输入），提取记忆候选、技能候选、冲突检测
- **全量反思**（`/reflect`）：对整个会话深度分析
- **Profile 编译**（`/compile`）：用 LLM 将所有活跃记忆合成约 200 token 的用户画像，替代逐条记忆注入，大幅节省 token
- **审慎持久化**：只有满足条件的候选才自动保存，其余进入延迟队列等用户审核，每次持久化都有审计日志

### 技能系统 — 可进化的行为模式

技能以 Markdown 文件存储在 `~/.self-agent/skills/`：

```markdown
---
name: code-review
description: 代码审查的标准流程
triggers: [review, 审查, PR, code review]
always_active: false
---
1. 先看 git diff，理解变更范围
2. 检查是否有测试覆盖
3. 关注安全相关的变更
```

匹配算法：**BM25 语义检索 + 触发词精确匹配**混合，再乘以 effectiveness 加权。用过的、有效的技能排名上升，从未被采纳的技能逐渐退居幕后。

### 工具并行 — 不是优化，是正确的选择

安全工具（read、grep、glob、think 等）使用 `futures::future::join_all` 并发执行，危险工具串行等待用户确认。Rust 的 `Send + Sync` trait bound 在编译期就保证了并发安全——没有锁、没有 Arc、没有 unsafe。

### 权限系统 — 信任但验证

三级分类：`Allow`（直接执行）→ `Confirm`（需用户确认）→ `Deny`（直接拒绝）。可通过配置文件预设规则，也可在运行时通过 `a` 命令动态添加。

### 上下文压缩 — 和遗忘做朋友

当 token 数接近模型限制时，自动触发 LLM 驱动的智能摘要：保留最近 4 轮原文，旧消息压缩为 `[Context Summary]`，目标压缩率 1/5，关键信息一条不丢。

### MCP 扩展 — 无限工具生态

支持 MCP 协议的 stdio 和 HTTP 两种传输方式，可接入任意 MCP Server 扩展工具能力。MCP 工具自动采用 `server__tool` 命名格式，且默认分类为危险工具需确认。

### 崩溃恢复 — 会话不丢失

所有消息以 JSONL 格式追加写入，Agent 异常退出后可通过 `self-agent chat --resume` 恢复完整会话历史。

## 记忆体系详解

### 5 层分区 × 3 套进化机制 = 立体的记忆体系

5 层分区：

| 分区 | 用途 | 更新频率 |
|------|------|---------|
| core | 用户身份、偏好、原则 | 几乎不变 |
| work | 当前焦点、近期决策 | 中频更新 |
| project:xxx | 项目级约定和上下文 | 按项目隔离 |
| episode | 会话摘要 | 高频写入 |
| general | 未分类兜底 | 按需 |

3 套进化机制：

| 机制 | 作用 | 类比 |
|------|------|------|
| 超越链（Supersedes Chain） | 新记忆替代旧记忆，但旧记忆保留可追溯 | 大脑更新认知，但不会真的"忘记" |
| 效果追踪（Effectiveness Tracking） | 追踪 Loaded/Referenced 比率，低效记忆降权 | 自然选择——有用的记忆越来越容易被召回 |
| 遗忘衰减（Decay Factor） | 长时间未被引用的记忆按半衰期衰减权重 | 遗忘曲线——不用就淡了，但不会消失 |

### 各模式的记忆行为对比

| 模式 | 记忆检索 | 自动反思 | 手动 /reflect | 会话持久化 |
|------|---------|---------|--------------|-----------|
| chat | ✅ | ✅（每3轮） | ✅ | ✅ |
| ask | ✅ | ❌（仅1轮） | ❌ | ✅（仅存最近2条） |
| agent | ✅ | ✅（迭代≥3轮后） | ❌ | ✅ |

### Ask 模式的记忆限制

ask 模式会触发记忆检索、技能匹配和效果追踪，但不会触发 micro 反思，因为反思需要 3 轮对话才触发，而 ask 只走 1 轮。

如果用户在 ask 中说"记住我喜欢 Rust"，不会自动记住，除非 Agent 主动调用 `memory_save` 工具并经用户确认。

1. 将 `turns_since_last_reflect >= 3` 改为 `>= 1`，使单次 ask 也会触发反思
2. 在 ask 模式结束后手动调用一次 micro_reflect