内容
# 🤖 智能代理框架
**适用于 AI 代理角色、技能和认知植入的通用 MCP 服务器**
一个语义路由器，根据用户查询动态加载专门的代理角色、领域技能和认知推理植入。与任何兼容 MCP 的客户端（Claude Code、Cursor、Windsurf 等）配合使用。
---
## 🚀 快速开始
### 克隆后
```bash
git clone <仓库 URL>
cd Agents
# 运行初始化脚本
./scripts/init_repo.sh
```
脚本将：
- ✅ 创建 Python 虚拟环境（`.venv/`）
- ✅ 安装所有依赖项
- ✅ 创建 `.env` 配置文件
- ✅ 验证 MCP 服务器配置
### 手动设置
```bash
# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
# 配置环境
cp env.example .env
# 使用 API 密钥编辑 .env
```
---
## ⚙️ 配置
### 必需的环境变量
创建 `.env` 文件，内容如下：
```env
LANGFUSE_PUBLIC_KEY=pk-lf-... # 可选：可观察性
LANGFUSE_SECRET_KEY=sk-lf-... # 可选：可观察性
LANGFUSE_HOST=https://cloud.langfuse.com
ANTHROPIC_API_KEY=sk-ant-... # 可选：用于文档 OCR
AGENTS_DEBUG=0 # 设置为 1 以启用日志中的 JSON 调试日志记录
```
> **注意**：嵌入由 `fastembed`（ONNX Runtime）在本地处理。模型在设置期间选择 - 不需要核心路由的外部 API 密钥。
### 后台自动更新
服务器可以保持最新状态。在启动时，守护进程线程（非阻塞，因此它永远不会延迟服务）快速转发安装的 git 仓库并重建向量存储；拉取的代码在 **下一个** 启动时生效（对于每个会话的 stdio 服务器，下一个实例化）。在当前会话的后台进行重索引运行，以便下一个会话快速启动。
它是 **默认安全** 的：
- 仅当检出的分支是 `AGENTS_AUTO_UPDATE_BRANCH`（默认为 `main`）时才执行 - **对功能分支的操作为 no-op**，因此本地开发永远不会被触摸；
- 仅当工作树干净时，并且仅 **快进**（从不合并、变基或切换分支）；
- 索引失败（例如，损坏的新代码）会 **回滚** 到上一个提交；
- 任何错误（离线、锁被另一个进程持有、超时）都会被记录，服务器会继续提供当前代码。依赖项 **不会** 自动安装。
```env
AGENTS_AUTO_UPDATE=1 # 禁用设置为 0
AGENTS_AUTO_UPDATE_REMOTE=origin
AGENTS_AUTO_UPDATE_BRANCH=main # 仅在检出此分支时更新
AGENTS_AUTO_UPDATE_TIMEOUT=30 # 每个 git 操作的秒数
AGENTS_AUTO_UPDATE_INTERVAL=900 # 节流网络检查（0 = 每次启动）
AGENTS_AUTO_UPDATE_REINDEX_TIMEOUT=600
```
随时使用 `python -m src.reindex` 手动重建。
---
## 🎯 工作原理
服务器公开 MCP 工具，任何兼容的客户端都可以调用：
| 工具 | 目的 |
|------|---------|
| `route_and_load(query)` | 语义路由 - 查找最佳代理，丰富其提示信息，并添加相关技能和植入 |
| `get_agent_context(agent_name, query)` | 直接加载代理 - 当目标已知时 |
| `load_implants(query\|task_type)` | 加载认知推理策略 - 通过语义查询或预设包 |
| `list_agents()` | 枚举所有可用的代理及其元数据 |
| `log_interaction(agent_name, query, response_content, intent?, action?, outcome?, files?, tags?)` | 结束时记录器 - 追加到 `history.md`（按内容哈希去重）和，如果配置了，发送 Langfuse 生成跟踪 |
| `clear_session_cache()` | 重置会话缓存 |
| `describe_repo(force_refresh=False)` | 一次性仓库引导 - 将结构化摘要写入 CLAUDE.md 的托管仓库内存部分 |
| `read_history(limit?, since?, query?)` | 最近的条目或基于历史日志的延迟语义回忆 |
### 路由流程
1. **`route_and_load(query)`** → 通过语义缓存进行单跳路由
2. **元检测** → 问候/短查询自动路由到 `universal_agent`
3. **缓存命中** → 返回丰富的提示信息（成功）或采样的响应（成功采样）
4. **缓存未命中** → 返回 ROUTE_REQUIRED 以及客户端选择所需的代理候选项
5. **基于层级的丰富** → 精简（无额外）/ 标准（2 个技能 + 2 个植入）/ 深度（4+ 个技能 + 3 个植入）
6. **多轮** → `context_hash` 启用后续查询的增量优化
---
## 🏗️ 架构
```
Agents/
├── agents/ # 代理角色（系统提示，38 个代理）
│ ├── software_engineer/
│ │ └── system_prompt.mdc
│ ├── common/ # 共享代理资源
│ ├── capabilities/ # 能力组合（registry.yaml）
│ └── schemas/ # 验证模式
├── skills/ # 可重用的知识块（RAG）
│ └── skill-*.mdc
├── implants/ # 认知推理策略（RAG）
│ └── implant-*.mdc
├── src/
│ ├── server.py # MCP 服务器入口点（FastMCP）
│ ├── engine/
│ │ ├── router.py # 语义路由（缓存优先）
│ │ ├── skills.py # 技能检索（向量搜索）
│ │ ├── implants.py # 植入检索（向量搜索）
│ │ ├── config.py # 集中式配置
│ │ ├── embedder.py # FastEmbed 包装器（ONNX Runtime）
│ │ ├── vector_store.py # 基于 NumPy 的向量存储
│ │ ├── enrichment.py # 基于层级的上下文丰富
│ │ ├── capabilities.py # 能力注册解析
│ │ ├── context.py # 上下文检索（历史格式化）
│ │ └── language.py # 语言检测
│ └── utils/
│ ├── prompt_loader.py
│ ├── debug_logger.py # 可选的 JSON 调试日志记录
│ └── langfuse_compat.py # 可选的 Langfuse 层
├── data/ # 向量存储缓存（自动初始化）
├── mcp.json # MCP 服务器配置
├── pyproject.toml # Python 项目元数据
└── requirements.txt
```
### 关键组件
| 组件 | 描述 |
|-----------|-------------|
| **代理** | 具有独特系统提示的专门角色 |
| **技能** | 领域特定的知识块（通过 RAG 检索） |
| **植入** | 认知模式和推理策略 |
| **路由器** | 语义匹配 + 缓存，用于快速代理选择 |
---
## 🔌 MCP 客户端配置
### Claude Code（`.mcp.json` 在项目根目录）
```json
{
"mcpServers": {
"Agents-Core": {
"command": ".venv/bin/python",
"args": ["src/server.py"]
}
}
}
```
### Cursor（`.mcp.json` 在项目根目录）
```json
{
"mcpServers": {
"Agents-Core": {
"command": ".venv/bin/python",
"args": ["src/server.py"]
}
}
}
```
### 通用 stdio
```bash
source .venv/bin/activate
python src/server.py
# 服务器通过 stdin/stdout 使用 MCP 协议通信
```
---
## 🧠 创建新代理
1. 创建目录：`agents/<agent_name>/`
2. 创建 `system_prompt.mdc`，包含 frontmatter：
```yaml
---
identity:
name: "my_agent"
display_name: "我的代理"
role: "X 领域的专家"
tone: "专业、清晰"
routing:
domain_keywords: ["keyword1", "keyword2"]
trigger_command: "/my_command"
---
# 我的代理系统提示
## 身份
您是 X 领域的专家...
```
MCP 服务器将在下一次启动时自动发现该代理。
### 能力系统
无需为每个代理列出技能，而是可以声明高级别的能力：
```yaml
capabilities: [development, dev-security]
```
丰富管道通过 `agents/capabilities/registry.yaml` 将能力解析为技能包。可用能力：`critical-analysis`、`content-structure`、`development`、`dense-summary`、`trust-weighted-research`、`bio-health`、`tech-documentation`、`dev-security`、`consultative-intake`、`creative-writing`、`psychology`、`3d-printing`、`data-investigation`、`epistemic-analysis`、`code-review`、`decision-making`、`product-thinking`、`temporal-research`、`performance-engineering`、`prompt-design`、`prompt-security`、`roblox-development`、`dev-tools`、`blender-scripting`、`health-optimization`、`consumer-research`、`visualization`、`child-psychology`。
---
## 🧠 仓库内存
服务器配备了每个仓库的内存子系统，因此每个新的 Claude 会话不必从头开始重新探索代码库：
- **`describe_repo`** — 通过 MCP 采样生成压缩的、LLM 可消耗的仓库概述，并将其写入 `CLAUDE.md` 的托管仓库内存部分。幂等：除非仓库清单更改或 `force_refresh=True`，否则重新运行是无操作的。
- **`log_interaction`** — 结束时记录器。追加 `intent / action / outcome` 条目（带有可选的文件和标签）到仓库根目录的 `history.md`；按内容哈希去重；当文件超过 512 KB 时，旋转到 `history/YYYY-MM.md`。如果配置了，还会发送 Langfuse 生成跟踪。
- **`read_history`** — 返回最近的条目，按时间/ `since` 过滤，或运行由相同的 `NumpyVectorStore` 支持的延迟语义搜索，用于路由。
完整设计和逐步原理说明位于 [`docs/memory-subsystem-spec.md`](docs/memory-subsystem-spec.md)。
> ⚠️ **隐私警告** — `history.md` 捕获原始提示和响应。如果您将密钥（API 密钥、令牌、凭证）粘贴到 Claude 中，它们将出现在此文件中。**默认情况下，它被 gitignore** 以将其排除在 git 历史记录之外；如果您希望在 PR 中可见操作日志，请从 `.gitignore` 中删除 `history.md` / `history/`，并在推送前审查条目。
---
## 📊 可观察性
框架与 LangFuse 集成以进行跟踪：
- 所有工具调用都会自动跟踪
- 路由决策被记录
- 缓存命中/未命中被跟踪
在 `.env` 中配置 LangFuse，或留空以仅限本地操作。
---
## 🛠️ 开发
### 手动运行服务器
```bash
source .venv/bin/activate
python src/server.py
```
### 调试日志记录
启用详细的每次调用 JSON 日志记录：
```bash
AGENTS_DEBUG=1 python src/server.py
```
日志记录到 `logs/{YYYY-MM-DD}/{HH-MM-SS.fff}_{tool}_{direction}.json`。禁用时零开销。
---
## 📝 许可证
MIT
