# sam-agent

**Repository Path**: sanle-233/sam-agent

## Basic Information

- **Project Name**: sam-agent
- **Description**: 开源 AI Agent 框架：多智能体 · 工具调用 · 长期记忆 · RAG 检索 · 定时任务 · MCP ｜ TypeScript + AI SDK，不配 Key 也能跑起来
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ai-agent, Agent, llm, TypeScript, RAG, MCP, tool-calling, memory, multi-agent, AI-SDK

## README

<div align="center">

# sam-agent

**轻量级开源 AI Agent 框架** —— 用 TypeScript 从零手写的 Agent 内核，不依赖 LangChain

多智能体协调 · 工具调用 · 长期记忆 · RAG 检索 · 定时任务 · 插件系统 · MCP · 上下文压缩

[![star](https://gitee.com/sanle-233/sam-agent/badge/star.svg?theme=dark)](https://gitee.com/sanle-233/sam-agent/stargazers)
[![fork](https://gitee.com/sanle-233/sam-agent/badge/fork.svg?theme=dark)](https://gitee.com/sanle-233/sam-agent/members)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![node](https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen.svg)]()

</div>

---

## 这是什么

一个**能读代码、能跑命令、能记事、能定时干活**的本地 AI Agent。核心只有 6000 行左右 TypeScript，模块清晰、可以直接读源码改：

- **Agent 循环**：多步执行、循环检测、自动重试、令牌预算
- **上下文工程**：消息压缩（microcompact / summarize）、上下文溢出防护
- **记忆系统**：本地持久化 + TTL 过期校验 + 记忆健康检查（`/lint`）
- **RAG**：SQLite + 向量检索，支持文档入库与语义搜索
- **工具系统**：文件、Shell（带危险命令分级拦截）、搜索、MCP、子 Agent
- **定时任务**：标准 Cron / 间隔 / 一次性任务，持久化任务与日志

<!-- 📸 建议在这里放一张 CLI 运行截图或 GIF（转化率提升最明显的一步）
![screenshot](./docs/screenshot.png)
-->

## 30 秒跑起来

```bash
# 1. 克隆
git clone https://gitee.com/sanle-233/sam-agent.git
cd sam-agent

# 2. 安装依赖（pnpm / npm / yarn 都行，需要 Node >= 20）
pnpm install          # 或 npm install

# 3. 配置模型（可选，见下方说明）
cp .env.example .env  # Windows: copy .env.example .env
#   打开 .env 填入 AI_API_KEY（按需再填 AI_ENDPOINT / AI_MODEL）

# 4. 启动
pnpm start            # 或 npm start
```

> **没有 API Key 也能启动。** 未配置 `AI_API_KEY` 时会自动使用内置的 mock 模型，可以先把整个流程跑通、看命令和工具有哪些，再决定接哪个模型。

启动后进入交互式命令行：直接输入自然语言任务，或用 `/` 开头的命令管理记忆、知识库、定时任务。

## 环境变量

| 变量 | 必填 | 用途 |
|---|---|---|
| `AI_API_KEY` | 是（不填走 mock 模型） | 对话模型密钥，任意 OpenAI 兼容供应商均可（[阿里云百炼控制台](https://bailian.console.aliyun.com/) 可获取） |
| `AI_ENDPOINT` | 否 | 模型接口地址，缺省阿里云百炼 `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `AI_MODEL` | 否 | 模型名，缺省 `qwen3.8-flash` |
| `DASHSCOPE_API_KEY` | 否 | 旧变量名，兼容保留：未设 `AI_API_KEY` 时回退使用；RAG 向量嵌入也仍用它 |
| `SERPER_API_KEY` | 否 | 联网搜索（[serper.dev](https://serper.dev/)，免费额度 2500 次） |
| `TAVILY_API_KEY` | 否 | 联网搜索备用通道（[tavily.com](https://tavily.com/)） |
| `GITHUB_PERSONAL_ACCESS_TOKEN` | 否 | GitHub MCP 工具（读写仓库 / Issue / PR） |

## 内置工具

| 工具 | 说明 |
|---|---|
| `read_file` / `write_file` / `edit_file` | 文件读写与精确替换（edit 只改指定片段，不做全量覆写） |
| `list_directory` / `glob` / `grep` | 目录浏览与文件检索 |
| `bash` | Shell 执行，带命令分类与危险命令拦截 |
| `web_search` / `web_fetch` / `fetch_url` | 联网搜索与网页正文提取（自动剥离 HTML） |
| `memory` | 记忆保存 / 搜索 / 读取 / 删除 |
| `rag_ingest` / `rag_search` | 文档入库与向量检索 |
| `cron_manage` | 创建 / 删除 / 查看 / 立即执行定时任务 |
| `spawn_agent` | 生成子 Agent 执行独立子任务（多智能体） |
| `tool_search` | 元工具：工具变多时按需检索，节省上下文 |
| `start_preview` | 启动 `app/` 目录的预览服务器 |

## 斜杠命令

| 命令 | 说明 |
|---|---|
| `/memory` | 查看与搜索记忆（`/memory search <关键词>`） |
| `/lint` | 记忆库健康检查 |
| `/context` | 查看当前上下文状态 |
| `/rag` | 知识库（RAG）相关操作 |
| `/cron` | 定时任务管理 |
| `/skill` | 技能管理（`/skill list`） |
| `/plugin` | 插件管理（`/plugin list`） |
| `/dream` | 记忆整理 |
| `/hooks` | 查看安全钩子 |
| `/usage` | 查看用量统计 |

## 换模型 / 自定义

默认走阿里云百炼的 OpenAI 兼容端点（`https://dashscope.aliyuncs.com/compatible-mode/v1`）。
因为用的是标准 OpenAI 协议，**任何兼容端点都能直接替换**——只需在 `.env` 里改三个环境变量，无需改代码（DeepSeek、Kimi、智谱、本地 Ollama / vLLM 都行）：

```bash
# .env
AI_API_KEY=你的密钥
AI_ENDPOINT=https://api.deepseek.com/v1   # 换成供应商的 OpenAI 兼容地址
AI_MODEL=deepseek-chat                    # 换成该供应商的模型名
```

自定义 Agent：

```ts
import { agentRegistry } from './src/agents/registry';

agentRegistry.register('code-reviewer', {
  systemPrompt: '你是一个严格的代码审查者',
  maxSteps: 50,
  allowedTools: ['read_file', 'grep', 'glob'],
});
```

## 项目结构

```
sam-agent/
├── app/                       # 内置 Web 预览（Vibe Coding）
├── src/
│   ├── agent/                 # 执行循环 · 循环检测 · 重试
│   ├── agents/                # Agent 注册表 · 子 Agent 生成
│   ├── commands/              # 斜杠命令实现
│   ├── context/               # 提示词构建 · 压缩 · 溢出防护
│   ├── cron/                  # 定时任务
│   ├── memory/                # 记忆存储与检索
│   ├── plugins/               # 插件系统
│   ├── rag/                   # 向量存储 · 嵌入 · 入库 CLI
│   ├── security/              # 命令分级 · 权限 · 安全钩子
│   ├── session/               # 会话持久化
│   ├── skills/                # 技能系统
│   ├── tools/                 # 工具集
│   ├── usage/                 # 用量统计
│   └── index.ts               # 入口
├── .env.example
├── LICENSE
└── package.json
```

## 常用脚本

```bash
pnpm start        # 启动 Agent（源码直跑，tsx）
pnpm build        # 编译到 dist/
pnpm typecheck    # 只做类型检查
pnpm rag:ingest   # 文档入库（RAG）
```

## FAQ

**Q：必须用 pnpm 吗？**
不必须，npm / yarn / pnpm 都可以。仓库里带 `pnpm-lock.yaml`，用 pnpm 装出来的依赖版本最一致。

**Q：Node 版本要求？**
Node 20 及以上（开发环境 Node 24）。

**Q：Windows 能用吗？**
可以。Windows 下 Shell 命令走 bash（推荐 Git Bash），文件与记忆功能不受影响。

**Q：Windows 上安装报 better-sqlite3 的 node-gyp / Visual Studio 错误怎么办？**
用 pnpm 不会遇到（`pnpm-workspace.yaml` 已禁止它的编译脚本——该包自带各平台预编译二进制，无需编译）。用 npm 仍可能出现，加 `--ignore-scripts` 跳过即可：`npm install --ignore-scripts`。这个报错不影响使用，装完照样能跑。

**Q：怎么退出？**
在交互界面输入 `exit`。

**Q：数据存在哪？**
默认在项目目录下的本地文件（`knowledge.db`、`.memory`、`.sessions` 等），不上传云端的任何服务。

## Roadmap

- [ ] 一键安装的 CLI（`npx sam-agent`）
- [ ] Web UI
- [ ] 更多模型 provider 开箱切换（DeepSeek / Kimi / Ollama）
- [ ] 更完整的插件示例与文档

## 参与贡献

欢迎 Issue 和 PR：

1. Fork 本仓库
2. 创建分支 `git checkout -b feature/your-feature`
3. 提交 `git commit -m 'feat: xxx'`
4. 推送并发起 Pull Request

如果这个项目对你有帮助，**点个 Star** 是对作者最大的鼓励 ⭐

## 许可证

[MIT](LICENSE)