dev-core-busy/jarvis

## 📋 目录 - [概述](#overview) - [截图](#screenshots) - [核心功能](#key-features) - [架构](#architecture) - [技术栈](#tech-stack) - [安装说明](#installation) - [配置](#configuration) - [多用户聊天](#multi-user-chat) - [多代理系统](#multi-agent-system) - [技能系统](#skill-system) - [WhatsApp 集成](#whatsapp-integration) - [知识库](#knowledge-base) - [视觉与人脸识别](#vision--face-recognition) - [AD/LDAP 与安全](#adldap--security) - [多媒体附件](#multimedia-attachments) - [反馈与自我改进](#feedback--self-improvement) - [认知进化](#cognitive-evolution) - [客户端应用](#client-apps) - [API 参考](#api-reference) - [贡献](#contributing) - [第三方许可证](#third-party-licenses) - [许可证](#license) ## 概述 Jarvis 是一个运行在 Linux 服务器上的**自托管自主 AI 代理**。通过网页聊天、内置的**支持门户**甚至 **WhatsApp**，用自然语言给它设定一个目标，它就能规划并执行：浏览网页、读写文件、运行代码、生成 Office 文档和图表、发送电子邮件、管理你的日历。随时随刻，你都可以通过**可选的 VNC 视图**在桌面上实时观看它工作。 ``` "Find all emails from last week about Project Alpha, summarize them, and create a calendar event for the follow-up meeting." ``` Jarvis 全能搞定——而且因为它是**多 LLM**、**多用户**的，并包裹在带有沙盒化执行的真正**安全层**中，你可以安全地将其开放给整个团队使用。 ## 截图 ## 核心功能 ### 🖥️ 真正的桌面控制（实时 VNC 视图） Jarvis 操控真实的 Linux 桌面——启动应用、点击、输入。开启**实时桌面视图**，随时观看或接管；截图会直接回传给 LLM 上下文，因此代理能看到它在做什么。拒绝盲目的自动化。 ### 🔀 多 LLM 支持 无需重启任何服务即可在 AI 提供商之间切换： - **Google Gemini** (gemini-2.5-flash, gemini-2.0-flash, gemini-1.5-pro, …) - **Anthropic Claude** (claude-opus-4, claude-sonnet-4-5, claude-haiku-4, …) - **OpenRouter**（通过单一 API 调用数百个模型） - **本地 Ollama**（llama3, mistral, qwen2.5 等——完全离线） - 任何兼容 **OpenAI** 的 endpoint 同时支持原生 tool/function calling **以及**基于 prompt 的工具调用——因此即使是不支持原生工具调用的模型也能使用 Jarvis 的所有功能。 ### 🤖 多代理系统 **主代理可以生成自主的子代理**，用于处理并行或后台任务。每个子代理独立运行，实时汇报，并显示在侧边栏中。复杂的多步骤工作流可并行运行，而不会阻塞主对话。 ### 💬 多用户聊天 内置的**用户间聊天** (`/userchat`) 让所有登录用户可以实时交流——支持图片画廊、音视频播放器、文件附件、灯箱预览以及转发/保存的上下文菜单。 ### 📎 多媒体附件 直接在 Jarvis 聊天中发送**图片、音频、视频和 PDF**： - 图片将被发送给 LLM 进行视觉分析（支持所有提供商） - 音频/视频在交由 LLM 处理前，会先通过 Whisper 进行本地转录 - PDF 将被提取并作为文本上下文注入 - 聊天内置画廊，支持灯箱模式、右键上下文菜单及移动端长按支持 ### 📱 WhatsApp 代理 在 WhatsApp 上给 Jarvis 发送语音留言或文本消息，即可收到回复。语音消息通过 faster-whisper 转录（在本地运行，无需云端）。非常适合移动端的任务委派。 ### 📚 知识库 将 PDF、DOCX 文件或纯文本放入监控文件夹中。Jarvis 会同时使用 **TF-IDF 和 ChromaDB 向量搜索**（多语言 embedding）对其进行索引。支持多文件夹，并在文件更改时自动重新索引。 ### 🧩 模块化技能系统 技能是独立的 Python 包，可通过新功能扩展 Jarvis。无需触及配置文件，即可通过 UI 安装、启用、停用和配置它们。兼容 [OpenClaw](https://github.com/steipete/gogcli) 技能。 ### 👁️ 视觉与人脸识别 可选的**视觉技能**通过 dlib/face_recognition 添加了实时人脸识别。为每个人定义特定操作（webhook、LLM prompt、仅记录日志），并具备可配置的冷却时间和容差。支持 USB 摄像头或 IP 摄像头。 ### 🛡️ 安全层与沙盒 专为向整个团队开放而构建——所有限制都是在**代码中强制执行**的，而不仅仅是在 prompt 中请求（因此无法通过对话绕过、通过 base64 编码绕过，或通过“学习”绕过）： - **针对网络/域用户的沙盒化执行** — shell 命令以非特权 OS 用户身份运行；文件访问受限（无系统/root/密钥路径，防止符号链接逃逸） - 跨聊天、支持工单和 WhatsApp 的**prompt 注入、越狱和 Base64 混淆检测**（启发式算法 + LLM 分类器） - 多次攻击尝试后的**自动账号锁定**，并附带详细的事件违规日志 - **基于角色的权限**（本地管理员与网络用户对比）+ 子代理继承调用者的限制——无提权行为 ### 🔐 身份验证与访问 - **Active Directory / LDAP** 身份验证（无需加入域） - 面向所有用户的 **2FA / TOTP** - 细粒度的**知识库编辑权限**（按用户或 AD 组划分） - 支持 HTTPS，配备自动生成的自签名证书或 Let's Encrypt - 基于 token 的身份验证（HMAC-SHA256，有效期 30 天） ### 🌐 Google Workspace 集成 通过自然语言命令管理 Gmail、Google Calendar 和 Google Drive——由 openclaw/gog CLI 提供支持。 ### 🤖 浏览器自动化 通过 CDP (Chrome DevTools Protocol) 和 xdotool 实现完整的浏览器控制。代理可以浏览网站、填写表单、点击元素并提取信息。 ### ⭐ 反馈与自我改进 每次机器人回复后，一键点击 **👍 👎 ❌ 反馈**即可触发自动 LLM 分析，生成 3–5 个更好的备选方案，并将学习规则永久输入到知识库中——无需手动配置。 ### 🧬 认知进化 **认知进化技能**让 Jarvis 能够改进和扩展自身：它分析差距，提出新的技能或代码补丁，通过第二个 LLM 进行验证，然后应用它们——包括在不重启服务的情况下热重载其自身的引擎。 ### 🧭 基于角色的门户、聊天与支持助手 简洁的 `/portal` 中心根据权限引导每位用户：AI **聊天**、**用户间聊天**，以及专用的**支持助手** (`/support`)，利用你的知识库 + Jira/Confluence 提供按相关性排序的解答。管理工具（设置、VNC、安全）仅向管理员显示。 ### 📄 Office 与文件生成 动态生成 **Word、Excel、PowerPoint 和 PDF**（python-docx / openpyxl / python-pptx + LibreOffice）——包括带有方框和连接线的图表。任何生成的文件（或图片）都将作为内嵌预览或一键下载芯片直接发送到聊天中。 ### 📊 知识组与批量打标 将文档组织到逻辑分组中（多重成员身份），将搜索范围限定在某个组内，并在**全屏打标矩阵**中管理一切——在几秒钟内将数百份文档分配到各个组中。 ### 🔌 交互式 API 控制台 在 `/api` 提供仅限管理员访问的、自动生成的 **API 浏览器**：列出并解释每一个 REST endpoint，提供示例和**实时测试调用器**。OpenAPI schema 和 Swagger/ReDoc 受管理员身份验证保护。 ### 📱 桌面与移动客户端 随时随地使用 Jarvis：**原生 Windows 应用**（Go 语言编写——系统托盘、设备端语音转文字、动态头像、自动更新），**原生 Android 应用**（Kotlin/Jetpack Compose——流式聊天、语音、附件、推送），以及通过可安装 PWA 支持的 **iOS**（原生应用在规划路线图中）。所有客户端共享同一个登录名、聊天记录和附件。→ [详情](#client-apps) ## 架构 ``` flowchart LR subgraph Clients["📱 Clients"] WebUI["Web UI\n(Browser)"] AndroidApp["Android App"] WindowsApp["Windows App"] WA["WhatsApp"] end subgraph Backend["⚙️ FastAPI Backend :443"] Agent["JarvisAgent\n(agent.py)"] AgentMgr["AgentManager\n(Multi-Agent)"] SkillsAPI["Skills API"] WAProxy["WhatsApp Proxy"] SkillMgr["SkillManager"] subgraph Tools["🔧 Tool Layer"] ToolList["shell · desktop · filesystem · screenshot\nknowledge · memory · browser · whatsapp · vision"] end LLM["LLM Client\n(Multi-Provider)"] VNCServer["x11vnc :5900\n(→ noVNC :6080)"] Bridge["Baileys Bridge\nNode.js :3001"] end WebUI -->|WSS/HTTPS| Agent AndroidApp -->|HTTPS| Agent WindowsApp -->|HTTPS| Agent WA --> Bridge --> WAProxy --> Agent Agent --> AgentMgr AgentMgr -->|spawns| Agent Agent --> SkillMgr --> Tools Agent --> LLM VNCServer --> WebUI ``` ### 组件概览 | 组件 | 文件 | 描述 | |-----------|------|-------------| | FastAPI Server | `backend/main.py` | HTTP/WebSocket endpoint、身份验证、AD/LDAP、WhatsApp 代理 | | Agent Loop | `backend/agent.py` | 任务执行、工具调用、LLM 编排、多模态 | | Agent Manager | `backend/agent.py` | 主 + 子代理生命周期、并行执行 | | LLM Client | `backend/llm.py` | 多提供商抽象（Gemini、Claude、OpenRouter、Ollama） | | Config | `backend/config.py` | 环境变量 + settings.json 管理 | | Skill Manager | `backend/skills/manager.py` | 加载、启用、停用、配置技能 | | Tool Base | `backend/tools/base.py` | 所有工具继承的 `BaseTool` 类 | | Learning | `backend/learning.py` | 反馈处理、自我改进、知识索引 | | WhatsApp Bridge | `services/whatsapp-bridge/index.js` | Baileys v7 + Express API | | Frontend | `frontend/index.html` + `js/` | 主 SPA — 代理聊天、设置、VNC | | PWA Chat | `frontend/chat.html` + `js/chat.js` | 轻量级 PWA 聊天，支持历史记录持久化 | | User Chat | `frontend/userchat.html` + `js/userchat.js` | 支持多媒体的多用户实时聊天 | ## 技术栈 ### 后端 | 技术 | 版本 | 用途 | |-----------|---------|---------| | Python | 3.13 | 核心运行时 | | FastAPI | 最新版 | REST API + WebSocket 服务器 | | uvicorn | 最新版 | ASGI 服务器 | | ldap3 | 最新版 | Active Directory / LDAP 身份验证 | | faster-whisper | 最新版 | 语音转录（CPU，int8） | | pypdf | 最新版 | PDF 文本提取 | | ChromaDB | 最新版 | 用于语义搜索的向量数据库 | | sentence-transformers | 最新版 | 多语言 embeddings（MiniLM-L12-V2） | | face_recognition | 最新版 | 人脸检测 + 识别 | ### 前端 | 技术 | 用途 | |-----------|---------| | Vanilla JS | 零依赖 UI（无构建系统） | | CSS Custom Properties | 深色磨砂玻璃主题 | | WebSocket API | 实时代理通信 | | noVNC | 浏览器内 VNC 客户端 | | Service Worker | PWA 离线支持 | ### 桌面 / 系统 | 技术 | 用途 | |-----------|---------| | Xvfb | 虚拟帧缓冲（无头 X11） | | Openbox | 轻量级窗口管理器 | | x11vnc | 用于 X11 会话的 VNC 服务器 | | websockify | WebSocket 到 TCP 代理（noVNC 桥接） | | xdotool | X11 自动化（键盘、鼠标、窗口管理） | ### WhatsApp | 技术 | 用途 | |-----------|---------| | Node.js 20+ | WhatsApp 桥接运行时 | | Baileys v7 | WhatsApp Web API（无需官方 API） | | Express | 用于桥接 ↔ 后端通信的 HTTP API | ## 安装说明 ### 前置条件 ``` # Debian/Ubuntu sudo apt-get update && sudo apt-get install -y \ python3.13 python3.13-venv python3-pip \ nodejs npm \ git \ xvfb x11vnc openbox \ websockify \ xdotool \ ffmpeg \ cmake libboost-all-dev # required for face_recognition (dlib) ``` ### 快速开始 ``` # 1. Clone 仓库 git clone https://github.com/dev-core-busy/jarvis.git cd jarvis # 2. 创建 Python 虚拟环境 python3 -m venv venv source venv/bin/activate # 3. 安装 Python 依赖 pip install -r requirements.txt # 4. 安装 WhatsApp bridge 依赖 cd services/whatsapp-bridge npm install cd ../.. # 5. 配置环境 cp .env.example .env nano .env # Add your API keys (see Configuration section) # 6. 启动 Jarvis ./start_jarvis.sh ``` 在浏览器中打开 `https://your-server-ip` 并使用 `jarvis/jarvis` 登录。 ### systemd 服务（推荐用于生产环境） ``` # 复制 service 文件 sudo cp services/systemd/jarvis.service /etc/systemd/system/ sudo cp services/systemd/whatsapp-bridge.service /etc/systemd/system/ # 启用并启动 sudo systemctl daemon-reload sudo systemctl enable jarvis.service whatsapp-bridge.service sudo systemctl start jarvis.service whatsapp-bridge.service # 检查状态 sudo journalctl -u jarvis.service -f ``` ### 端口概览 | 端口 | 服务 | 访问级别 | |------|---------|--------| | 443 | FastAPI (HTTPS) | 外部访问 | | 80 | HTTP → HTTPS 重定向 | 外部访问 | | 6080 | noVNC (WSS) | 外部访问 | | 5900 | x11vnc | 仅限本地 | | 3001 | WhatsApp Bridge | 仅限本地 | ## 配置 所有配置都位于 `.env`（机密信息）和 `data/settings.json`（UI 管理的设置）中。大多数设置可以在运行时通过 Web UI 进行更改。 ### `.env` 参考 ``` # ── LLM Providers ────────────────────────────────────────────── GOOGLE_API_KEY=your_gemini_api_key ANTHROPIC_API_KEY=your_claude_api_key OPENROUTER_API_KEY=your_openrouter_api_key # Local Ollama（无需密钥 — 只需设置 base URL） OLLAMA_BASE_URL=http://localhost:11434 # ── Authentication ────────────────────────────────────────────── JARVIS_USERNAME=jarvis JARVIS_PASSWORD=jarvis # Change this in production! SECRET_KEY=change-me-to-a-random-string # ── WhatsApp ──────────────────────────────────────────────────── WA_ALLOWED_NUMBERS=+4915112345678,+4917098765432 # Comma-separated whitelist # ── Optional ──────────────────────────────────────────────────── DISPLAY=:1 # X11 display for desktop control KNOWLEDGE_DIRS=/data/docs,/home/jarvis/notes # Watched knowledge folders ``` ### 切换 LLM 提供商 使用 Web UI 中的设置面板在运行时切换提供商和模型——无需重启。可以保存多个配置文件，并一键激活。 ## 多用户聊天 `/userchat` endpoint 为所有登录到 Jarvis 的用户提供**实时 P2P 聊天**。 ### 功能特性 - **实时状态** — 通过彩色状态点查看谁在线 - **图片画廊** — 网格中最多显示 4 张图片，点击打开全屏灯箱 - **音视频播放器** — 直接在聊天气泡中内联播放 - **文件芯片** — PDF 及其他附件，带下载链接 - **灯箱** — 全屏图片查看器，支持键盘导航（← → Esc）和保存按钮 - **上下文菜单** — 右键点击或长按（移动端）任何附件：保存 / 转发 - **转发** — 一键将任何文件发送给另一位在线用户 - **表情符号回应** — 对任何消息做出反应 - **输入指示器**和已读回执 附件通过服务器在点对点之间传输——Jarvis **不会**对其进行分析。 ## 多代理系统 Jarvis 可以生成与主代理并行工作的**自主子代理**。 ``` # 在任务中，主 agent 可以生成 sub-agents： # {"_spawn_agent": true, "label": "Research Agent", "task": "Find all papers about X"} ``` - 每个子代理都可以访问所有工具和技能 - 子代理在侧边栏中显示为卡片（紫色 = 子代理，绿色 = 主代理） - 每个代理都有实时流式输出 - 子代理完全自主——无需中断或确认 这使得类似这样的模式成为可能：*“同时研究主题 A 和 B，然后合并结果。”* ## 技能系统 技能通过新功能扩展 Jarvis。每个技能都是独立的 Python 包： ``` skills/ my_skill/ skill.json # Manifest main.py # Tool definitions requirements.txt # Optional extra dependencies ``` ### `skill.json` 结构 ``` { "name": "my_skill", "display_name": "My Awesome Skill", "version": "1.0.0", "description": "Does something awesome", "author": "Your Name", "tools": ["MyTool"], "config_schema": { "api_endpoint": { "type": "string", "description": "The API endpoint URL", "required": true } } } ``` ### `main.py` 结构 ``` from backend.tools.base import BaseTool class MyTool(BaseTool): name = "my_tool" description = "Does something specific and useful" async def execute(self, param1: str, param2: int = 10) -> str: # Your implementation here return f"Result: {param1} with {param2}" def get_tools(config: dict) -> list: return [MyTool(config=config)] ``` ### 内置技能 | 技能 | 描述 | |-------|-------------| | `browser_control` | CDP + xdotool 浏览器自动化 | | `whatsapp` | 发送/接收 WhatsApp 消息 | | `telegram` | Telegram bot 集成（接收消息，发送回复） | | `google` | Google Calendar、Drive 和 Gmail 集成 | | `vision` | 实时人脸识别（USB/IP 摄像头） | | `cron` | 计划周期性/定时任务（cron jobs） | | `cognitive_evolution` | 自我改进代理（分析 → 提议 → 验证 → 应用） | | `claude_bridge` | 将任务委派给 Claude 桌面应用 | | `example_skill` | 用于新技能开发的模板 | 除了技能之外，后端还公开了一个 **MCP 客户端** (`backend/mcp_client.py`)，以便 Jarvis 可以连接到外部的 Model Context Protocol 服务器。 ### 安装技能 1. 将技能文件夹放在 `skills/` 下 2. 在 Web UI 的 Settings → Skills 中启用（支持热重载，无需重启） ## 🔌 OpenClaw 技能生态系统 OpenClaw 是一个不断发展的 AI 代理技能生态系统。Jarvis 可以直接导入任何 OpenClaw 技能包。 ### 内置 OpenClaw 技能 | 技能 | 描述 | |---|---| | `openclaw_gmail` | 通过 gog CLI 进行完整的 Gmail 集成（发送、读取、搜索、管理） | | `agent_orchestrator` | 编排多个子代理以处理复杂的并行任务 | | `agent_autonomy_kit` | 心跳监控、任务队列、自主运行 | ### 导入 OpenClaw 技能 ``` # 将其放入 skills/ 目录 cp -r my_openclaw_skill/ skills/ # 在 UI 中启用：Settings → Skills → 开启 ``` ## WhatsApp 集成 Jarvis 使用 [Baileys v7](https://github.com/WhiskeySockets/Baileys) 连接到 WhatsApp Web——**无需官方 API 或商业账户**。 ### 设置 1. 启动 WhatsApp 桥接服务：`systemctl start whatsapp-bridge.service` 2. 打开 `https://your-server` → Settings → WhatsApp 3. 使用你的 WhatsApp 应用扫描二维码 4. 在 `.env` 中将你的号码添加到 `WA_ALLOWED_NUMBERS` ### 语音消息 给 Jarvis 发送语音留言——它会自动使用 **faster-whisper** 进行转录（在 CPU 上本地运行，无需云端）： ``` You: [Voice note: "Check if there's anything urgent in my email today"] Jarvis: "Found 3 emails marked as urgent. Here's a summary: ..." ``` ### 安全 只有 `WA_ALLOWED_NUMBERS` 中列出的号码才能向 Jarvis 发送任务。自聊天消息和桥接反馈循环会被自动过滤。 ## 知识库 将文档放入监控文件夹中，Jarvis 即可在任务执行期间对其进行搜索。 ### 支持的格式 - PDF (`.pdf`) — 全文本提取 - Word 文档 (`.docx`) - 纯文本 (`.txt`, `.md`) - 任何文本格式 ### 搜索模式 | 模式 | 描述 | |------|-------------| | **Auto** | 优先尝试向量搜索，失败则回退到 TF-IDF | | **TF-IDF** | 快速的基于关键字的搜索，支持离线工作 | | **Vector** | 通过 ChromaDB + 多语言 embeddings 进行语义搜索 | ### 配置 ``` KNOWLEDGE_DIRS=/home/jarvis/docs,/opt/company-wiki ``` 或者通过设置 UI 进行配置。文件更改时会自动建立索引。 ### 知识编辑权限 在 **Settings → Security → Active Directory** 下，你可以限制允许添加、编辑或删除知识库内容的人员： - **Allowed Editors** — 逗号分隔的用户名（例如 `mueller,schmidt`） - **Editor Group** — AD 组 DN（例如 `CN=Knowledge-Editors,OU=Groups,DC=firma,DC=local`） - 留空 = 所有经过身份验证的用户均可编辑（默认） - 本地管理员用户始终允许编辑 ## 视觉与人脸识别 可选的**视觉技能**通过 [face_recognition](https://github.com/ageitgey/face_recognition) (dlib) 增加了实时人脸识别功能。 ### 功能特性 - 从 USB 摄像头或 IP 摄像头（RTSP/HTTP）检测和识别人脸 - 针对每个人的可配置操作： - **Webhook** — HTTP POST 到任何 URL - **LLM Prompt** — 触发 Jarvis 任务（例如“向 {name} 打招呼并解锁门”） - **Log only** — 静默事件日志记录 - 针对每个人的可配置容差 (0.0–1.0) 和冷却时间 - 通过设置 UI 进行训练——为每个人上传照片 - 支持 HOG（速度快，基于 CPU）和 CNN（精度高，基于 GPU）检测模型 ### 设置 1. 在 Settings → Skills 中启用视觉技能 2. 在 Settings → Vision → Profiles 中添加人员 3. 上传训练照片并点击“Train” 4. 为每个配置文件设置操作 5. 启动摄像头画面推送 ## AD/LDAP 与安全 ### Active Directory / LDAP 登录 Jarvis 支持域登录而无需加入域——服务器只需要能够通过网络访问域控制器。 ``` Settings → Security → Active Directory / LDAP ``` | 字段 | 描述 | |-------|-------------| | Domain Controller | 你的 DC 的 IP 或主机名 | | Domain | 例如 `firma.local` | | Allowed Users | 逗号分隔的白名单（留空 = 允许所有 AD 用户） | | Allowed Group | AD 组 DN — 优先于用户列表 | | Allowed Editors | 谁可以编辑知识库 | | Editor Group | 用于知识编辑器的 AD 组 | - 会自动尝试 TLS / StartTLS - 组成员身份会在登录时进行检查并缓存 - 无论 AD 配置如何，本地管理员账户始终可访问 ### 安全层与沙盒 Jarvis 旨在向非管理员（网络/域）用户公开。所有限制都在**工具调度（代码内）中强制执行**——而不仅仅是在系统 prompt 中声明——因此它们无法通过 prompt 注入、编码的 payload 或恶意的“学习到的事实”来绕过。 - **Shell 沙盒：** 来自网络用户的命令以非特权 OS 用户 (`runuser`) 身份在临时工作区中运行；更改系统的命令、混淆（base64/eval/通过管道传递给 shell）以及机密/root 路径都会被阻止。 - **文件系统限制：** 写入操作仅限于工作区，读取操作仅限于知识/工作目录；拒绝访问机密、root 和系统区域（解析符号链接以防止逃逸）。 - **攻击检测与自动锁定：** 越狱 / prompt 注入 / Base64 尝试会被记录为详细事件；多次违规将自动锁定账户（本地管理员豁免；只有本地管理员才能解锁）。 - **无提权行为：** 子代理继承调用者的限制；“学习到的事实”被视为不受信任的上下文，且无法覆盖最高优先级的安全规则。 - **可配置**，位于 `Settings → Security` 下（攻击防护面板、沙盒状态、违规日志）。通过那里的 ❓ 按钮可在应用内查看完整的技术说明。 ### 双重身份验证 每位用户都可以通过 **Settings → Security → 2FA** 启用 2FA（Google Authenticator、Authy 或任何兼容 RFC 6238 的 TOTP 应用）。 ### 密码管理 本地用户可以通过 **Settings → Security → Change Password** 更改其密码。 ## 多媒体附件 所有 Jarvis 聊天界面都支持丰富的文件附件。 ### 主聊天 (`/`) | 文件类型 | LLM 处理方式 | |-----------|-------------| | 图片 (JPG, PNG, GIF, WebP, …) | 作为视觉输入直接发送给 LLM | | 音频 (MP3, WAV, OGG, M4A, …) | 通过 Whisper 转录，将文本发送给 LLM | | 视频 (MP4, WebM, …) | 通过 Whisper 转录音轨 | | PDF | 通过 pypdf 提取文本，作为上下文注入 | 支持所有主要的 LLM 提供商： - **Gemini**：原生多模态（图片作为字节发送） - **Claude/Anthropic**：图片作为 base64 内容块 - **OpenAI 兼容**：图片作为 `image_url` 内容块 ### PWA 聊天 (`/chat`) 完整的附件支持，具备**聊天记录持久化**（localStorage，最近 120 条消息）。下次登录时会恢复历史记录，并带有日期分隔符和会话标记。 ### 用户聊天 (`/userchat`) 附件在用户之间原样传输——不涉及 LLM。图片以网格画廊形式显示，音视频显示为内联播放器，PDF/文件显示为下载芯片。 **附件 UI 功能：** - 拖放到消息区域 - 发送前带有缩略图芯片的预览栏 - 针对不支持格式的 Toast 通知 - 右键点击 / 长按已接收文件的上下文菜单：**保存**或**转发** - 带有键盘导航的灯箱 (← → Esc) ## 反馈与自我改进 每次 Jarvis 回复后，都会内联显示 **👍 👎 ❌ 反馈按钮**： | 评分 | 效果 | |--------|--------| | 👍 积极 | 记录为积极示例 | | 👎 消极 | LLM 分析回复，生成 3–5 个更好的备选方案，并得出学习规则 | | ❌ 错误 | 同消极处理 + 标记为事实错误 | 学习规则存储在知识中，并立即影响未来的回复——无需重新训练，无需手动配置。 适用于：Web 聊天、Android 应用、iOS PWA、Windows 应用。 ## 认知进化 **认知进化技能** (`skills/cognitive_evolution/`) 赋予了 Jarvis 通过结构化的 4 阶段循环来扩展和改进自身的能力： ``` Analyze → Propose → Validate → Apply ``` | 工具 | 描述 | |------|-------------| | `evolution_analyze` | 识别差距并规划所需的更改 | | `evolution_propose` | 生成代码（新技能或补丁），另存为提案 | | `evolution_validate` | 语法检查 + 独立的 LLM 安全审查 | | `evolution_apply` | 写入文件，热重载技能，更新引擎 | | `evolution_cycle` | 通过自主子代理运行所有 4 个阶段 | ### 它能做什么 - **编写新技能** — 生成 `skill.json` + `main.py`，在运行时激活它们 - **自我修补** — 重写 `engine.py` 并通过 `importlib.reload()` 重载，而无需重启 - **修复后端代码** — 委派给现有的 ReflectionTool（备份 + LLM 验证） - **更新指令** — 修改 Jarvis 的行为指令文件 ### 安全性 - 每一项提案都通过 `py_compile`（语法）和第二个独立的 LLM 进行验证 - 在覆盖任何文件之前都会创建备份 - 技能隔离在 `skills/` 中——核心后端仅通过明确的 `code_fix` 范围进行触及 - 该技能**默认禁用**——需在 Settings → Skills 中手动启用 ## 客户端应用 随时随地使用 Jarvis——浏览器、桌面或手机。每个客户端都通过 HTTPS/WebSocket 与同一服务器通信，并共享登录名、聊天记录和附件。 | 平台 | 客户端 | 亮点 | |----------|--------|-----------| | **Web**（任何 OS） | 内置 Web UI / PWA | 功能齐全，可安装到主屏幕 | | **Windows** | 原生 Go 客户端 (`windows-app-go/`) | 系统托盘、本地语音转文字、动态头像、自动更新 | | **Android** | 原生应用 (`android/`, Kotlin/Compose) | 流式聊天、语音输入、附件、推送 | | **iOS** | 目前的 PWA · 原生应用在路线图中 | 添加到主屏幕、麦克风输入、离线外壳 | ### 🪟 Windows 应用（原生，Go） 位于 `windows-app-go/` 下的轻量级**原生** Windows 客户端——无需浏览器： - **系统托盘**集成，触手可及 - **本地语音转文字** — 解放双手与 Jarvis 对话（在设备上运行） - 带有语音/文本回复的**动态头像** - 与代理的实时 **WebSocket** 连接 - **自动更新**（拉取最新的签名发布版本） ``` cd windows-app-go && bash build.sh ``` ### 🤖 Android 应用 位于 `android/` 下的原生、**已签名**的 Android 应用： - 具备**流式**响应的完整 Jarvis 聊天 - **语音输入**和多媒体**附件**（图片 / 音频 / 视频 / PDF） - 👍 👎 ❌ 反馈，可选的**推送通知** - **Active Directory / LDAP** 域登录 构建：在 Android Studio 中打开 `android/` 并运行（发布版本通过 `.jks` keystore 进行签名）。 ### 🍎 iOS 目前不需要原生 iOS 应用——在 Safari 中打开 `https://your-server/chat` → **添加到主屏幕**，即可获得类似应用的 PWA 体验： - 麦克风输入及附件 - 支持离线的外壳，持久化的聊天记录 **原生 iOS 客户端已在路线图中**，可根据要求优先开发。 ## API 参考 FastAPI 后端公开了 REST + WebSocket API。可在 `https://your-server/docs` 获取交互式文档。 ### 身份验证 所有 API 调用都需要通过 `/api/login` 获取的 Bearer token： ``` curl -s -X POST https://your-server/api/login \ -H "Content-Type: application/json" \ -d '{"username":"jarvis","password":"jarvis"}' | jq .token ``` ### 主要 Endpoint | 方法 | Endpoint | 描述 | |--------|----------|-------------| | `POST` | `/api/login` | 身份验证，获取 Bearer token | | `WS` | `/ws` | WebSocket — 代理流式传输，多用户聊天 | | `GET` | `/api/skills` | 列出所有技能及其状态 | | `POST` | `/api/skills/{name}/enable` | 启用某个技能 | | `POST` | `/api/skills/{name}/disable` | 停用某个技能 | | `GET` | `/api/knowledge/files` | 列出已建立索引的知识文件 | | `POST` | `/api/knowledge/upload` | 将文件上传到知识库 | | `PUT` | `/api/knowledge/file_write` | 编辑知识文件 | | `DELETE` | `/api/knowledge/files` | 删除知识文件 | | `POST` | `/api/knowledge/extract` | 从 URL 提取知识 | | `GET` | `/api/wa/logs` | WhatsApp 消息日志 | | `GET` | `/api/auth/ad_status` | Active Directory 配置 + 状态 | | `POST` | `/api/feedback` | 提交响应反馈 | | `GET` | `/api/memory` | 读取持久化记忆 | | `POST` | `/api/memory` | 写入持久化记忆 | ### WebSocket 协议 ``` const ws = new WebSocket('wss://your-server/ws'); // Run an agent task ws.send(JSON.stringify({ type: 'task', text: 'Take a screenshot of the current desktop', token: 'your-bearer-token', lang: 'de', // optional: 'de' or 'en' attachments: [ // optional { name: 'photo.jpg', mime_type: 'image/jpeg', data: '' } ] })); // Receive messages ws.onmessage = (event) => { const msg = JSON.parse(event.data); // msg.type: 'status' | 'agent_event' | 'llm_stats' | 'agent_list' | 'dm' // msg.highlight: true → LLM response text // msg.agent_id: which agent sent this }; // User-to-user DM ws.send(JSON.stringify({ type: 'dm', to: 'other_user', text: 'Hello!', token: 'your-bearer-token', attachments: [] // optional })); // Stop running agent ws.send(JSON.stringify({ type: 'control', action: 'stop', token: '...' })); ``` ## 贡献 非常欢迎您的贡献！以下是参与方式： ### 🐛 报告 Bug 在 [github.com/dev-core-busy/jarvis/issues](https://github.com/dev-core-busy/jarvis/issues) 提交 issue，并包含： - 你的 OS 和 Python 版本 - 复现步骤 - 预期与实际行为对比 - 相关日志 (`journalctl -u jarvis.service`) ### ✨ 建议新功能 提交带有 `enhancement` 标签的 issue。描述使用场景，而不仅仅是解决方案。 ### 🔧 提交代码 1. Fork 仓库 2. 创建功能分支：`git checkout -b feature/my-new-skill` 3. 进行修改（参见下文的约定） 4. 全面测试 5. 提交 pull request ### 开发约定 - **代码注释：** 首选德语（项目约定 / *Projektkonvention*） - **提交信息：** 描述性的德语 - **CSS：** 使用 `var(--text-primary)`, `var(--bg-glass)`, `var(--accent)` 等——不使用硬编码颜色 - **前端：** 纯 Vanilla JS，无框架，无构建系统 - **机密信息：** 切勿提交 `.env` 文件或 API 密钥 - **numpy：** 必须保持在 `< 2.1` 版本以下（虚拟机缺乏 SSE4.2 / x86-v2 支持） - **现有文件：** 始终使用 Edit（定向 diff）——切勿使用 Write 覆盖（有产生 0 字节文件的风险） ### 编写新技能 最快的贡献方式是构建新技能。使用 `skills/example_skill/` 作为你的模板： ``` cp -r skills/example_skill skills/my_new_skill # 编辑 skill.json 和 main.py # 在 Settings → Skills 中启用 # 提交 PR！ ``` ## 第三方许可证 Jarvis 建立在优秀的开源项目基础之上： | 库 / 工具 | 许可证 | 链接 | |---------------|---------|------| | FastAPI | MIT | https://github.com/tiangolo/fastapi | | uvicorn | BSD-3-Clause | https://github.com/encode/uvicorn | | python-dotenv | BSD-3-Clause | https://github.com/theskumar/python-dotenv | | ldap3 | LGPL-3.0 | https://github.com/cannatag/ldap3 | | Baileys (WhatsApp) | MIT | https://github.com/WhiskeySockets/Baileys | | faster-whisper | MIT | https://github.com/SYSTRAN/faster-whisper | | pypdf | BSD-3-Clause | https://github.com/py-pdf/pypdf | | ChromaDB | Apache-2.0 | https://github.com/chroma-core/chroma | | sentence-transformers | Apache-2.0 | https://github.com/UKPLab/sentence-transformers | | face_recognition | MIT | https://github.com/ageitgey/face_recognition | | noVNC | MPL-2.0 | https://github.com/novnc/noVNC | | websockify | LGPL-3.0 | https://github.com/novnc/websockify | | xdotool | MIT | https://github.com/jordansissel/xdotool | | openclaw/gog CLI | MIT | https://github.com/steipete/gogcli | | Openbox | GPL-2.0 | http://openbox.org | | x11vnc | GPL-2.0 | https://github.com/LibVNC/x11vnc | 完整的许可证文本包含在 `LICENSES/` 目录中。 ## 许可证 Jarvis AI Desktop Agent 采用 **Apache License 2.0 (Apache-2.0)** 授权。 这意味着： - ✅ 可免费使用、修改和分发——适用于个人和商业用途 - ✅ 可以嵌入到专有/闭源产品中；无需公开你的修改 - ✅ 包含明确的专利授权 - ⚠️ 保留版权/`NOTICE` 和许可证声明；标记你更改过的文件 完整文本请参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。第三方组件仍保留其各自的许可证（参见上方的*第三方许可证*）。

**用 ❤️ 为开源社区构建** [jarvis-ai.info](https://jarvis-ai.info) · [GitHub](https://github.com/dev-core-busy/jarvis) · [Issues](https://github.com/dev-core-busy/jarvis/issues) *“预测未来的最好办法就是将其自动化。”* 由 Andreas Bender 在 [Claude](https://claude.ai) (Anthropic) 的协助下开发 – 代码、架构与落地页。 © 2026 Andreas Bender · 采用 [Apache-2.0](LICENSE) 授权

标签：AI智能体, MITM代理, RAG, VNC, 多模型集成, 桌面自动化, 逆向工具