# srclaw

**Repository Path**: xtmpfc/srclaw

## Basic Information

- **Project Name**: srclaw
- **Description**: 开箱即用、插件化的自托管 AI Agent 框架：多模型兼容 + 会话持久化 + 子 Agent + Skills 工具 + 流式 Web UI。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Srclaw

[![Version](https://img.shields.io/badge/version-1.30.0-blue.svg)](CHANGELOG.md)
[![Python](https://img.shields.io/badge/python-3.12+-green.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-974%20passed-brightgreen.svg)](CHANGELOG.md)

一个开源、自托管、插件化的通用 AI Agent 框架。支持多模型提供商（OpenAI 兼容）、
会话持久化、多用户认证、子 Agent 派发、Skills 扩展，提供 REST API
与内置 Web 聊天页。

## 特性

- **插件系统**：三路发现（目录 / entry-points / 内置）、五态生命周期、失败隔离
- **Agent 循环**：ReAct 风格工具循环（同步 + SSE 流式），OpenAI 兼容多 provider
  （DeepSeek / MiniMax 等，思维链自动剥离）
- **会话管理**：SQLite（WAL）持久化，消息按 seq 重放；Session Notes 会话记忆（POST 条目级追加 + DELETE 按索引删除 + GET 读 + PUT 覆写四件套）；
  会话导出/导入（JSON / Markdown）、标题搜索、会话收藏/置顶（`starred` 字段）、会话备注（`description` 字段）、会话归档（`archived` 字段）、会话标签/分类（`tags` 字段，逗号分隔，多标签 OR 过滤）、会话文件夹/嵌套分类（`folder` 字段，路径式如 `work/projectA`，前缀匹配过滤）、会话模板/快速创建（POST /sessions 端点支持元数据 + folder 列表导航）、会话锁定/解锁（`locked` 字段，锁定后拒绝修改/删除）、会话分叉/分支（`/sessions/{id}/fork` 从任意消息点创建分支会话，复制元信息 + 消息前缀）
- **工具集**：`read_file` / `list_files`（递归目录树）/ `write_file` / `edit_file`
  / `search_files`（内容搜索 + glob 过滤）/ `run_shell`（权限分级 + 沙箱）/
  `web_search`（自定义脚本 + DuckDuckGo Lite 兜底）/ `save_note`
- **多 Agent 配置**：YAML 声明多个 Agent（模型 / 端点 / 提示词 / 工具子集）
- **子 Agent**（Agent-as-Tool）：`task` 工具派发子任务，上下文隔离，递归深度 1
- **Skills 扩展**：多根目录扫描 SKILL.md，目录清单注入提示词，按需加载全文
- **多用户认证**：Bearer Token（默认关闭，向后兼容），会话归属隔离，管理 API
- **可观测性**：请求审计日志 + token 用量统计 + 用量端点
- **多阶段 Docker 构建**：非 root 运行 + HEALTHCHECK + Docker Compose + CI/CD

## 快速开始

```bash
pip install -e .

# 配置 API Key（项目根 .env 或环境变量）
export SRCLAW_API_KEY=sk-...
export SRCLAW_API_BASE=https://api.minimaxi.com/v1
export SRCLAW_MODEL=MiniMax-M3

srclaw serve --port 8146
```

启动后打开 <http://localhost:8146> 即可使用内置 Web 聊天页。

## API 速览

所有端点挂载在 `/api/v1` 前缀下，保证向后兼容：

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/chat` | Agent 对话（同步） |
| `POST` | `/api/v1/chat/stream` | Agent 对话（SSE 流式） |
| `GET` | `/api/v1/sessions` | 会话列表（分页，`limit`/`offset`/`starred`/`archived`/`tags`/`folder` 可选过滤） |
| `POST` | `/api/v1/sessions` | 快速创建会话（支持完整元数据：title/notes/description/tags/folder/starred/archived） |
| `GET` | `/api/v1/sessions/search` | 会话搜索（`q` 关键字匹配标题/消息） |
| `GET` | `/api/v1/sessions/folders` | 文件夹列表（去重 + 字典序，导航侧边栏用） |
| `GET` | `/api/v1/sessions/{id}` | 会话详情（含消息） |
| `PATCH` | `/api/v1/sessions/{id}` | 会话更新（`title` / `starred` / `description` / `archived` / `tags` / `folder` 任选） |
| `DELETE` | `/api/v1/sessions/{id}` | 删除会话 |
| `GET` | `/api/v1/sessions/{id}/export` | 导出会话（`json`/`markdown`） |
| `POST` | `/api/v1/sessions/import` | 导入会话 |
| `GET` | `/api/v1/sessions/{id}/notes` | 读取会话记忆 |
| `PUT` | `/api/v1/sessions/{id}/notes` | 覆写会话记忆 |
| `POST` | `/api/v1/sessions/{id}/notes` | 追加单条笔记（去重 + 截断，v1.19.0） |
| `DELETE` | `/api/v1/sessions/{id}/notes/{index}` | 按索引删除笔记（v1.19.0） |
| `GET` | `/api/v1/agents` | 可用 Agent 列表 |
| `GET` | `/api/v1/skills` | 可用 Skills 列表 |
| `GET` | `/api/v1/plugins` | 插件快照 |
| `GET` | `/api/v1/usage` | 用量统计聚合 |
| `GET` | `/api/v1/usage/logs` | 审计日志分页 |
| `POST` | `/api/v1/auth/users` | 创建用户（管理员） |
| `GET` | `/api/v1/auth/users` | 用户列表（管理员） |
| `PATCH` | `/api/v1/auth/users/{name}` | 禁用/启用用户（管理员） |
| `DELETE` | `/api/v1/auth/users/{name}` | 删除用户（管理员） |

### 健康检查

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/health` | 综合健康探针（含 `uptime_seconds`，适合 liveness） |
| `GET` | `/health/live` | Liveness 探针（纯内存返回，零 IO） |
| `GET` | `/health/ready` | Readiness 探针（探测组件连通性；不可用时 503，引导摘流） |

认证开启（`SRCLAW_AUTH=on`）后除 `/`、`/health`、`/health/*`、`/api/v1` 外的所有端点
需要 `Authorization: Bearer <key>`。

## 配置参考

### AI 提供商

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_API_KEY` | （无） | API Key（或 `DEEPSEEK_API_KEY`） |
| `SRCLAW_API_BASE` | （无） | API 端点，如 `https://api.minimaxi.com/v1` |
| `SRCLAW_MODEL` | `deepseek-chat` | 模型名 |

### 路径与存储

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_WORKSPACE` | `cwd` | Agent 工具的工作区根目录 |
| `SRCLAW_DATA_DIR` | `<cwd>/.srclaw/` | SQLite 数据库目录（sessions/users/audit） |

### 功能开关

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_AUTH` | `off` | 认证开关（`on` 启用 Bearer Token） |
| `SRCLAW_ADMIN_KEY` | （无） | 管理员引导密钥（不落库） |
| `SRCLAW_SUBAGENTS` | `on` | 子 Agent（`task` 工具）开关 |
| `SRCLAW_SKILLS` | `on` | Skills 系统开关 |
| `SRCLAW_WRITE` | `on` | `write_file` 工具开关 |
| `SRCLAW_EDIT` | `on` | `edit_file` 工具开关 |
| `SRCLAW_SEARCH` | `on` | `search_files` 工具开关 |
| `SRCLAW_WEB_SEARCH` | `on` | `web_search` 工具开关 |
| `SRCLAW_AUDIT` | `on` | 审计日志开关 |
| `SRCLAW_CONTEXT` | `on` | 上下文管理开关 |

### 上下文管理

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_CONTEXT_MAX_TOKENS` | `28000` | 历史 token 预算上限 |
| `SRCLAW_CONTEXT_KEEP_TURNS` | `2` | 最少保留轮数（永不清空） |

### Shell 权限

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_SHELL_ALLOW` | （无） | 逗号分隔的允许范围 |
| `SRCLAW_SHELL_DENY` | （无） | 逗号分隔的拒绝范围 |
| `SRCLAW_SHELL_ASK` | （无） | 逗号分隔的询问范围 |
| `SRCLAW_SHELL_DEFAULT` | `ask` | 默认模式（`allow`/`ask`/`deny`） |

### 搜索与审计

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_WEB_SEARCH_CMD` | （无） | 自定义搜索脚本路径 |
| `SRCLAW_WEB_SEARCH_MAX_RESULTS` | `5` | 联网搜索结果数（1-10） |
| `SRCLAW_AUDIT_RETENTION_DAYS` | `0` | 审计保留天数（`0` = 永久） |

### 请求限制

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_RATE_LIMIT` | `0` | 每 IP 每分钟请求上限（`0` = 不限流） |
| `SRCLAW_RATE_LIMIT_BURST` | `60` | 令牌桶突发容量 |
| `SRCLAW_MAX_BODY_SIZE` | `10485760` | 最大请求体字节数（默认 10MB；`0` = 不限制） |

### 请求追踪

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_REQUEST_ID` | `on` | 启用请求 ID 追踪（`off`/`0`/`false` 禁用；每个 HTTP 响应带 `X-Request-ID` 头） |

### 扩展路径

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SRCLAW_PLUGIN_PATHS` | （无） | 额外插件目录（os.pathsep 分隔） |
| `SRCLAW_SKILLS_PATHS` | （无） | 额外 Skill 目录（os.pathsep 分隔） |
| `SRCLAW_AGENTS_CONFIG` | `<cwd>/.srclaw/agents.yaml` | 多 Agent 配置文件路径 |

## Docker 部署

```bash
# 构建并启动
docker compose up -d

# 开启认证：在同目录 .env 写入 SRCLAW_AUTH=on + SRCLAW_ADMIN_KEY
# 然后重启：docker compose up -d

curl http://localhost:8000/health
```

不用 Compose：

```bash
docker build -t srclaw:latest .
docker run -p 8000:8000 -v srclaw-data:/data \
  -e SRCLAW_API_KEY=sk-... srclaw:latest
```

## 项目结构

```
srclaw/
├── src/srclaw/            # 主包
│   ├── agent/             # Agent 循环、多 Agent 配置、子 Agent、LLM 适配
│   ├── auth/              # Bearer Token 认证、用户存储
│   ├── core/              # 插件系统（注册表/发现/管理器）
│   ├── observability/     # 审计日志 + 统计
│   ├── server/           # FastAPI 应用与路由
│   ├── session/          # SQLite 持久化 + Session Notes + 上下文管理
│   ├── skills/           # Skills 扫描加载
│   ├── tools/            # 内置工具（文件/Shell/搜索/网络/笔记）
│   └── ui/               # 内置 Web 聊天页
├── doc/                   # 文档（部署指南、版本路线、评估文档）
├── examples/              # 示例（插件/Skills/多 Agent）
├── tests/                 # 测试套件（890 例，全程 mock 无联网）
├── Dockerfile             # 多阶段构建
├── docker-compose.yml     # Compose 编排
├── Makefile               # 开发/测试/发布命令
└── CHANGELOG.md           # 变更日志
```

## 文档

- **部署指南**：[doc/deployment.md](doc/deployment.md)（源码 / Docker / 认证 / 反代 / 备份）
- **版本路线**：[doc/versioning.md](doc/versioning.md)
- **扩展示例**：[examples/README.md](examples/README.md)

## 开发

```bash
pip install -e ".[dev]"
make test        # 全部测试（mock，无联网）
make lint        # ruff 检查
make typecheck   # mypy 严格类型检查
make build       # Docker 镜像构建
```

## 版本

当前版本：**1.15.0**（详见 [CHANGELOG.md](CHANGELOG.md)）

本项目采用 [SemVer 2.0.0](https://semver.org/)，版本路线图见
[doc/versioning.md](doc/versioning.md)。1.0.0 起 API 稳定承诺生效：1.0.x
内不做破坏性变更。

## License

[MIT](LICENSE)