# Scout Agent **真的会操作你 Windows 电脑的 AI 智能体 —— 真实点击、真实击键、真正记得你** [English](README.md) · [简体中文](README.zh-CN.md) [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE) [![Version](https://img.shields.io/badge/Version-1.0.0.6-orange.svg)](VERSION) *持久记忆 · 桌面操控 · 多渠道接入 · 安全优先*

--- ## 🖱️ 它真的有手 —— 一句话，Scout 接管你的 Windows

_{一镜到底屏幕录制 · 21 秒 · 无任何模拟。在 Scout 里敲一行指令 —— 它先推演、再打开记事本、逐行把中文待办清单敲进去，最后回来告诉你"已完成"。}

▶ 观看高清版 MP4

**刚才那 21 秒，逐段拆解：** | ⏱️ | 画面 | Scout 真正在做什么 | |:---:|---|---| | 0–3 秒 | 🗣️ *"打开记事本，帮我写一份今天的待办清单"* | 在 Scout 输入框敲一句自然语言 —— 没有脚本、没有宏、没有 API | | 3–9 秒 | 🧠 ReAct 推演 | 拆解任务、选中 `desktop` 工具、决定启动记事本 | | 9–18 秒 | 🖱️ 真实 GUI 操控 | 记事本被打开，焦点落到编辑区，中文待办**逐行真实击键**写入（兼容输入法） | | 18–21 秒 | ✅ *"已完成，记事本已打开，清单已写好"* | 全选展示成果，并在对话里回报执行结果 | **为什么重要：**绝大多数"智能体"走到生成文本就停了。Scout 内置 `desktop` 工具，能下**真实的鼠标点击、真实的键盘输入、真实的屏幕截图**，还配了 `skills-library/` 里 **11 套实测技能包** —— 发微信消息、飞书找人、驱动浏览器、填 Excel 表格。你说一句，它在你真实的桌面、真实的软件里真的做完。 > 🔒 全程本地执行：以上录制都在作者本机 Windows 上完成，不依赖云桌面，也不上传任何屏幕内容。 --- ## 📖 目录 - [简介](#简介) - [60 秒看懂 Scout](#demo) - [它真的有手 —— 桌面操控实录](#桌面操控) - [为什么选择 Scout Agent？](#为什么选择-scout-agent) - [界面预览](#界面预览) - [特性](#特性) - [特色功能深潜](#特色功能深潜) - [快速开始](#快速开始) - [配置](#配置) - [命令行](#命令行) - [安全](#安全) - [开发](#开发) - [测试](#测试) - [项目结构](#项目结构) - [许可证](#许可证) --- ## 🔍 简介 Scout Agent 是一个智能个人助手 AI 智能体，支持持久记忆、工具调用和多渠道接入。它通过记住你的偏好、自动化任务，并连接你日常使用的平台，与你共同成长。 --- ## ⚡ 60 秒看懂 Scout（实录演示，无任何模拟）

🖥️ 全新 Web UI · 一分钟巡礼
Scout UI 巡礼

_{命令面板 Ctrl K → 知识库 → 20+ 工具 → 记忆库 → 设置 → 深浅主题一键切换
▶ 高清版 MP4}

| 🧰 **20+** 内置工具 | 🌐 **12+** 聊天渠道 | 🖱️ **11** 个实测桌面技能 | 🧩 **5** 类核心组件可替换 | |:---:|:---:|:---:|:---:| --- ## ⭐ 为什么选择 Scout Agent？市面上的 AI 助手大多是"无状态工具"——每次对话都从零开始。Scout 的不同在于：它是一个**会复利的智能体**——用得越久，越懂你，也越会干你的活。 | # | 差异化优势 | 对你的意义 | |---|---|---| | 1 | 🧬 **自我进化** | 任务失败时 Scout 会自我反思并修复；修复成功的经验会被**自动提炼成可复用 Skill** 沉淀进语义技能库——下次再遇到同类问题直接秒解。你不用"装"技能，而是"养"技能。 | | 2 | 🧠 **工程化长时记忆** | 关键记忆自动抽取、去重，跨会话按 **重要性 × 时间衰减 + 历史摘要 `

` 压缩**重组——它真的记得昨天的上下文，而不只是今天的聊天窗口。 | | 3 | 🚀 **思考者/执行者双模型** | "慢思考"负责拆解难题，"快执行"负责落地干活——该深度推理时深思熟虑，该快时绝不拖沓。 | | 4 | 🌐 **在哪都能聊** | 12+ 渠道：飞书、微信（个人/公众号/企微/客服/群机器人）、Telegram、钉钉、Discord、Slack、QQ……外加 Web UI（可装成 PWA 桌面应用）。助手跟随你的聊天习惯，而不是反过来。 | | 5 | 🖱 **真的长着"手"** | 内置 `desktop` 工具能做真实的**点击、输入、截图**，替你操作**任意本机软件**——发微信、在飞书找人、驱动浏览器、填 Excel 表格。附带 11 个实测技能包（`skills-library/`）：说一声"给 XX 发消息"，它就真去做，而不是"建议你这样做"。 | | 6 | 🤝 **Agent 与 Agent 互通（A2A）** | 实现 Google A2A 协议——其他智能体可以把任务委派给 Scout，Scout 也能委派给它们。为多智能体时代而生，而不是一座孤岛。 | | 7 | 🔒 **天生安全优先** | Docker 沙箱执行、危险命令黑名单（`rm -rf /`、fork 炸弹……）、Shell 注入与 XSS 防护、可选 JWT 认证、密钥加密存储。让智能体跑代码本让人紧张——Scout 把它变得平淡无奇。 | | 8 | ⚡ **零门槛上手** | Windows 绿色便携版：解压 → 双击 → 完事（不用 Python、不安装、不动注册表）；也可 `pip install` 源码运行。数据随用户目录走，换机、升级覆盖都不丢。 | **最适合这些场景：** 一个帮你跑日常杂活的个人副驾——定时 + 事件驱动的自动化任务、基于私有知识库问答、通过团队 IM 主动汇报结果——同时密钥、记忆、代码都私有地留在你自己的硬件上。 > 👉 想看完整清单？见下方 [特性](#特性) 表，或直接跳到 [快速开始](#快速开始)。 --- ## 🖼 界面预览全新设计的现代化界面（深浅双主题、对话区与输入框 1280px 精准对齐、命令面板 `Ctrl K`、一键中英切换）：

主聊天界面	设置 · 模型配置	设置 · 工具配置
知识库 · 文档导入	插件 · 20+ 工具注册表	记忆库

📋 查看全部功能截图（15）

#### 设置 · Agent 行为设置回复语言、运行模式（ReAct 单智能体循环或 Multi-Agent 委派架构）、系统提示词与深度思考等参数。 ![设置 · Agent 行为](docs/images/settings-agent.png) #### 设置 · 安全策略可视化配置危险命令检测（`rm -rf /`、`dd if=`、`mkfs`、`curl | sh` 等 13 种模式）、自动审批开关、Docker 沙箱隔离，让 Agent 在受限环境中运行。输入框内置**权限开关**（标准 / 全部放行 / 谨慎）：标准模式下删除、格式化等高危操作先弹窗确认，`全部放行` 后同类操作不再打扰，不可逆操作（`rm -rf /`、`mkfs`、远程脚本管道执行）任何模式仍硬拦截。 ![设置 · 安全策略](docs/images/settings-security.png) #### 设置 · 渠道管理支持飞书、微信、微信公众号、企业微信、企微群机器人、微信客服、个人微信、Telegram、钉钉、Discord、Slack、QQ 等 12+ 平台接入，配置后即可在这些平台与 Scout 对话。 ![设置 · 渠道管理](docs/images/settings-channels.png) #### 设置 · 登录认证可选启用 JWT 登录密码保护 Web 界面与 API，提升服务安全性。 ![设置 · 登录认证](docs/images/settings-auth.png) #### 模型 · 嵌入配置配置嵌入模型（远程 API / 内置哈希 / 纯文本三档），切换后记忆与知识检索方式即时生效。 ![模型 · 嵌入配置](docs/images/settings-model-embedding.png) #### 目标 Goals 把长期任务拆成可跟踪的目标清单，状态实时更新，跨会话持续跟进。 ![目标 Goals](docs/images/goals.png) #### AI 插件生成器描述想要的插件功能，AI 自动生成完整插件代码，也可以先搜索全网现有 Skill/插件。 ![AI 插件生成器](docs/images/plugin-builder.png) #### 自动化中心基于事件触发器、运行历史、无人值守策略与定时任务，让 Scout 响应 EventBus 事件或按 Cron 自动执行任务。 ![自动化中心](docs/images/automation.png) #### 运行观测时间线按 trace 聚合查看最近会话的运行时间线、成功率与 Token 消耗，快速定位异常。 ![运行观测时间线](docs/images/observe.png) #### 模型监控 Token 消耗与模型调用统计，成本一目了然。 ![模型监控](docs/images/monitor-usage.png) #### 系统监控实时查看 CPU、内存、磁盘、网络、Agent 运行状态与历史曲线。 ![系统监控](docs/images/monitor-system.png) #### Multi-Agent 模式多个协作 Agent 分工推进同一任务，界面实时展示各 Agent 的角色与产出。 ![Multi-Agent 模式](docs/images/runtime-multi-agent.png) #### ReAct 反思 + 安全拦截 ReAct 推理过程实时可见，危险命令在执行前被安全层拦截并提示。 ![ReAct 反思 + 安全拦截](docs/images/runtime-security-block.png) #### 事件总线查看系统内 EventBus 广播的事件流（含事件类型、来源、载荷摘要），插件与自动化均基于该总线触发。 ![事件总线](docs/images/events.png) #### 通知中心集中管理推送规则（最低级别、去重窗口）、按类型开关（任务异常 / 任务完成 / 定时触发 / 系统 / 提醒）、IM 渠道目标与推送历史，并提供一键「发送测试通知」验证整条链路。 ![通知中心](docs/images/notify.png)

--- ## ✨ 特性 | 特性 | 说明 | |------|------| | 🧬 **技能自进化** | 自愈闭环：任务失败自动反思修复；修复成功经验自动提炼为可复用 Skill（错误模式→解决方案，LLM 泛化）入语义技能库，下次同类问题秒解 | | 🤝 **A2A 互通** | 实现 Google A2A 协议（AgentCard / 任务收发），与其他智能体通过 HTTP 互派任务 | | 🧠 **持久记忆** | 自动保存对话上下文和用户偏好；纯文本检索（默认）+ 可选 API 向量语义检索 | | 🔧 **工具调用** | 20+ 内置工具：文件编辑、安全 Shell、代码执行、网络搜索、记忆回溯、定时任务、MCP 等 | | 🖱 **桌面操控** | `desktop` 工具直接操作本机 GUI 软件：窗口管理（含托盘恢复/强制前台）、控件与坐标点击（DPI 感知统一坐标系）、中英文输入（SendInput unicode + 剪贴板双路）、PrintWindow 截图（被遮挡也能截）——实测打通微信/飞书/浏览器/Office/UWP/记事本，配套 11 个实测技能库 `skills-library/` | | 🌐 **多渠道** | 接入飞书、微信、Telegram、Discord、Slack、钉钉、QQ 等 12+ 平台 | | 🤖 **多智能体** | ReAct 单智能体循环、Multi-Agent 委派架构、DAG 计划-执行循环 | | 🚀 **双模型架构** | 思考者/执行者模型架构，支持深度思考开关 | | 🔒 **安全优先** | 沙箱执行、危险命令拦截、XSS 防护、可选认证 | | 📊 **使用监控** | Token 消耗与模型调用统计 | | 🎙 **语音** | ASR + TTS 语音交互 | | 🧩 **插件系统** | 基于 EventBus 的插件扩展 + SPI（可替换 LLM/存储等核心组件） | | 📚 **知识库** | 多格式文档解析 + 力导向图可视化 | | 🔄 **测试反馈闭环** | 代码失败自动跑 pytest，结构化失败堆栈喂回上下文自纠错 | | 🗂 **可插拔循环** | ReAct（默认）或 DAG 计划-执行循环，按会话切换 | | 📜 **工具契约** | 注解推导 schema、运行时参数校验、统一错误码 | | 🐚 **持久 Shell** | 长驻 bash 会话，跨调用保留 cwd/环境变量/后台任务 | | 🖥 **PTY 终端** | 伪终端交互：vim/top 等程序可用，按键注入 + 显式中断 + 窗口尺寸 | | 📊 **eval 基准** | `python -m scout.eval`：隔离评测 + Pass@1/3/5 无偏估计（对标 DSBench） | | 🧠 **记忆工程化** | 跨会话关键记忆抽取（LLM 结构化/启发式降级 + 去重）、跨会话上下文组装（记忆 × 重要性 × 时间衰减 + 历史摘要 `

` 注入） | | 🧩 **插件 SPI 全类型** | llm/storage/cache/session/memory 五类核心组件可声明式替换 | | 📱 **PWA 桌面化** | Web UI 可安装为独立应用（manifest + Service Worker + 图标），离线秒开 | | 💰 **成本可视化** | LLM 调用成本估算（缓存命中折扣计价），`scout doctor` 汇总命中率与节省金额 | | 🪟 **Windows 绿色版** | `desktop/build.bat` 一键打包免安装免注册桌面程序（WinForms + WebView2 + PyInstaller），数据存于 `%APPDATA%\Scout`——升级覆盖程序不丢配置 | --- ## 🔬 特色功能深潜下面 5 个是 Scout 区别于普通 Chatbot 的**底层机制**——也是"为什么越用越强"的答案。 ### 🧬 1. 自进化技能闭环（Self-Evolving Skill Loop）普通助手失败就失败；Scout 会把失败变成经验： > 任务执行失败 → Agent 自我反思定位错误 → 自动修复并重跑 → 成功路径被提炼为 Skill（错误模式 → 解决方案，经 LLM 泛化去重）→ 存入语义技能库 → 下次命中同类问题直接秒解 - 技能库是**从你的使用历史里长出来的**：不用手动"装" Skill，用得越多沉淀越多； - 沉淀的 Skill 与手动安装、网上获取的 Skill 同库管理，可随时在「知识库 / 技能」页查看、禁用或删除。 ### 🧠 2. 工程化长时记忆（Engineered Long-term Memory）普通助手靠"上下文窗口"硬塞，Scout 把记忆当工程问题处理： - **抽取**：会话中自动识别值得记住的信息（偏好、约定、任务进度），自动去重； - **重组**：跨会话重放时按「记忆 × 重要性 × 时间衰减 + 历史摘要 `

`」组装上下文——旧记忆自然淡出，重要记忆历久弥新； - **压缩**：超长历史自动滚成摘要，上下文窗口永远不爆。效果：隔几天、换设备、重启进程，它依然记得"上次聊到哪、你的习惯是什么"。 ### 🚀 3. 两种执行模式 × 双模型路由 - **ReAct 模式**（默认，`agent_mode: react`）：单 Agent 走「思考 → 调用工具 → 观察结果 → 再思考」循环，配合 `deep_thinking` 深度思考先推演再动手，实时推理过程在界面可见； - **Multi-Agent 模式**（`agent_mode: multi_agent`）：同一任务由多个协作 Agent 分工推进，适合复杂长任务（界面实时展示各 Agent 分工与产出）； - **双模型路由**：`.env` 里配 `SCOUT_THINKER_MODEL`（慢思考，负责规划）与 `SCOUT_EXECUTOR_MODEL`（快执行，负责高频工具调用），各用所长、成本可控。 ### 🧩 4. Skill + 插件生态：三个来源 × 五类替换点 - **Skill（可复用能力包）** 三个来源：内置、网上安装、上文的**自愈沉淀**； - **插件 SPI** 提供 `llm / storage / cache / session / memory` 五类替换点，任一层都可换成自研实现； - 内置 **20+ 工具**：文件编辑、安全 Shell、代码执行、联网搜索、记忆回溯、定时任务、MCP 接入、**桌面 GUI 操控（desktop：点击/输入/截图，实测微信/飞书/浏览器/Office/UWP，配 `skills-library/` 技能库）** 等，按需授予； - **AI 插件生成器**：在「插件管理」页用自然语言描述需求，AI 直接生成合规插件，不用手写代码。 ### 🤝 5. Agent 间互联（A2A，Google A2A 协议） - 通过 HTTP 向其他 A2A 智能体**发布 / 接收任务**，内置 AgentCard 端点可被其它智能体发现与调用； - 默认**拦截私网 / 内网目标**（防 SSRF 探测内网），仅当你显式开启 `a2a_allow_private` 才放行内网地址。 --- ## 🚀 快速开始 ### 🪟 Windows 用户：开箱即用，无需装 Python 不想折腾环境？直接用**绿色便携版**，双击即用： 1. 到 **GitHub Releases** 下载 **Windows 绿色版**：[v1.0.0.6 发布页](https://github.com/core-power/Scout-Agent/releases/tag/v1.0.0.6)（直接下载 [scout-agent-1.0.0.6-win-x64.zip](https://github.com/core-power/Scout-Agent/releases/download/v1.0.0.6/scout-agent-1.0.0.6-win-x64.zip)，或到 [全部 Releases](https://github.com/core-power/Scout-Agent/releases) 找更新版本）。 2. 解压后把**整个文件夹**拷到任意 Windows 10/11 电脑即可运行——免安装、免注册表、免管理员权限。 3. 打开解压目录，双击 **`ScoutDesktop\ScoutAgent.exe`**，对话窗口立即弹出。 4. 首次使用打开**设置**页，填入你的 LLM API Key 即可（支持通义/DeepSeek/OpenAI 等任意 OpenAI 兼容端点）。程序文件夹可整体拷贝到任意 Windows 10/11 电脑；用户数据（会话/记忆/配置/API Key）统一存放在 `%APPDATA%\Scout`（如 `C:\Users\<你>\AppData\Roaming\Scout`），与程序文件夹分离——覆盖升级永远不丢配置。旧版本数据（盘符根 `.scout`、程序旁 `data/`）首次启动自动迁移；换机时把程序文件夹 + `%APPDATA%\Scout` 一起拷走即可。 #### 🔄 升级便携版 1. 留意 [Releases 页面](https://github.com/core-power/Scout-Agent/releases)，出新版后下载最新的 `scout-agent-*-win-x64.zip`。 2. **退出 `ScoutDesktop\ScoutAgent.exe`**（弹窗询问时点「是」）。 3. 解压新版，用新文件**覆盖旧文件夹**（直接复制替换即可）。 4. 重新双击 `ScoutDesktop\ScoutAgent.exe`——你的数据和设置原样保留，无需迁移。 > 聊天记录、API Key、设置全部存放在 `%APPDATA%\Scout`（Windows 用户数据目录），**不在**应用文件夹里——所以覆盖程序文件夹永远不会动到你的数据；旧目录（盘符根 `.scout` / 程序旁 `data/`）首启自动迁移。 > Windows 版**仅通过 GitHub Releases 分发**——exe 不会提交进本仓库（保持仓库轻量）。想自己打包 exe？在 Windows 上运行 `desktop\build.bat`（需 Python 3.11+），会自动把所有依赖打进 `dist\ScoutDesktop\`。 > > 每个 Release 还会**自动附带源码归档**（`Source code (zip)` / `Source code (tar.gz)`）——开发者直接下载源码后按下方「安装」章节运行即可。 ### 环境要求 | 平台 | 要求 | |---|---| | 通用 | Python 3.11+、git、可访问 LLM API 的网络（建议 ≥4GB 内存） | | Windows | PowerShell 5.1+（一键脚本用）；或直接用上方绿色便携版，连 Python 都不用装 | | 生产 / 高可用 | （可选）Docker + docker compose（自动拉起 PostgreSQL / Redis / NATS） | ### 方式一：从源码运行（全平台，适合开发 / 深度定制） > 不想手动配环境？直接跳到 [方式三：一键脚本](#方式三一键脚本)。 **① 拉取项目代码** ```bash git clone https://github.com/core-power/scout-agent.git cd scout-agent ``` **② 创建虚拟环境并安装依赖** ```powershell # —— Windows（PowerShell）—— python -m venv .venv .\.venv\Scripts\Activate.ps1 # 若提示禁止脚本：先执行 Set-ExecutionPolicy -Scope Process Bypass # —— Linux / macOS —— # python3 -m venv .venv && source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt # 安装全部 Python 依赖 pip install -e . # 注册 scout 命令（可选，等价于 python -m scout.cli） ``` **③ 初始化配置并填入 API Key**（详见下方「配置」章节） ```powershell copy .env.example .env # Windows；Linux/macOS 用 cp .env.example .env notepad .env # 至少填 SCOUT_LLM_PROVIDER / SCOUT_LLM_MODEL / SCOUT_LLM_API_KEY ``` > Python 依赖集中在 venv 里；用户配置、会话、记忆则统一存放在数据目录（Windows 默认 `%APPDATA%\Scout`，Linux/macOS 默认项目根 `.scout/`；可用 `SCOUT_DATA_DIR` 覆盖）。 ### 方式二：Docker 部署（生产环境，一键拉起全套基础设施）仓库自带 `Dockerfile` 与 `docker-compose.yml`（含 PostgreSQL + Redis + NATS 高可用三件套）： ```bash git clone https://github.com/core-power/scout-agent.git && cd scout-agent copy .env.example .env # Windows；Linux/macOS 用 cp .env.example .env # 在 .env 中填入你的 API Key（compose 从环境读取 OPENAI_API_KEY / LLM_MODEL 等，见 docker-compose.yml） docker compose up -d --build # 构建镜像并后台启动 ``` - 应用监听 `http://localhost:8848`（健康检查 `GET /health`），数据落在 Docker 卷中（`docker compose down` 不会丢数据）； - 只想快速试跑单体容器（不需要 PG/Redis/NATS）： `docker build -t scout . && docker run -p 8848:8848 scout` ### 方式三：一键脚本（Linux/macOS `install.sh` · Windows `install.ps1`）自动完成：检测/安装 Python 3.11+ → 创建虚拟环境 → 安装依赖 → 生成 `.env` 并引导填写 Key → 注册 `scout` 快捷指令： ```bash # Linux / macOS bash install.sh # Windows（PowerShell） powershell -ExecutionPolicy Bypass -File install.ps1 ``` ### 启动服务 ```bash # 启动 Web 界面（默认端口 8848）—— 以下方式等价，任选其一 python -m scout.cli --web # 源码 / venv 环境 bash run.sh --web # Linux/macOS 脚本（Windows 用 run.bat --web） scout start # 已注册 scout 命令：后台守护启动 # 终端对话模式 python -m scout.cli # 或 bash run.sh / run.bat # 指定端口 / 监听地址 python -m scout.cli --web --port 9000 ``` > 首次启动会自动在数据目录生成 `config.json`。若服务起不来，先运行 `scout doctor` 做环境自检（Python/依赖/端口/API Key 逐项体检）。后台守护更多命令（`stop` / `restart` / `status` / `logs`）见「命令行」章节。 ### 访问界面打开浏览器访问：`http://localhost:8848` --- ## ⚙️ 配置复制 `.env.example` 为 `.env` 并配置你自己的 API Key。**切勿提交 `.env` 或 `config.json` 文件**——它们包含敏感信息。 ```ini # .env / .env.example SCOUT_LLM_API_KEY=your-api-key-here SCOUT_LLM_MODEL=qwen3.7-plus SCOUT_LLM_PROVIDER=dashscope SCOUT_LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 SCOUT_LLM_TEMPERATURE=0.7 SCOUT_LLM_MAX_TOKENS=4096 # 可选：双模型路由 # SCOUT_THINKER_MODEL=qwen3.7-plus # SCOUT_EXECUTOR_MODEL=qwen3.7-flash # 可选：嵌入模型（留空 = 纯文本检索） # provider: api（远程 API，需 Key）| hash（内置）| 空 = 纯文本（默认） # SCOUT_EMBEDDING_PROVIDER=api # SCOUT_EMBEDDING_API_KEY= # SCOUT_EMBEDDING_API_BASE_URL= # SCOUT_EMBEDDING_API_MODEL=qwen3.7-text-embedding # 可选：搜索引擎（SearXNG 实例地址） # 留空则禁用 web_search 工具与技能联网搜索 # SCOUT_SEARCH_ENGINE=http://localhost:8080/search # 多个搜索引擎源（SearXNG / Bing / Google / Tavily / DuckDuckGo / 自定义） # 可在 Web 界面配置：设置 → 工具 → 搜索引擎源。 # 数据目录 # 默认（Windows）：%APPDATA%\Scout（升级覆盖程序不丢配置；旧目录自动迁移） # 默认（Linux/macOS）：<项目根>/.scout # SCOUT_DATA_DIR=<路径> # 覆盖数据目录 # SCOUT_CONFIG_DIR=<路径> # 如需配置目录与数据目录分离 # 安全 # SCOUT_AUTO_APPROVE=true # SCOUT_SANDBOX_MODE=off # 网关端口 # SCOUT_GATEWAY_PORT=8848 ``` #### 两种配置入口怎么选 | 入口 | 存放位置 | 适合 | 修改方式 | |---|---|---|---| | `.env` | 项目根目录（**不要提交到 git**） | API Key、双模型、嵌入/搜索/数据目录等 | 文本编辑；**改动需重启生效** | | `config.json` | 数据目录（默认 `.scout/config.json`） | 模型、Agent 行为、端口、认证、搜索源等运行配置 | **Web 界面「设置」页可视化修改并即时保存**；模板见仓库根 `config.example.json`（首次启动自动生成） | 启动时读取顺序：**`.env`（`SCOUT_*` 环境变量）优先于 `config.json`**。`.env` 里**必须**配的是 LLM 三件套，缺一无法对话： ```ini SCOUT_LLM_PROVIDER=dashscope # 厂商：dashscope/deepseek/zhipu/moonshot/volcano/openai/claude/gemini/openrouter/compatible SCOUT_LLM_MODEL=qwen3.7-plus # 模型名（各厂商最新模型见 .env.example 顶部注释） SCOUT_LLM_API_KEY=sk-xxx # 密钥 ``` 其余全部可选，需要可视化管理的（多厂商密钥、双模型、端口、认证、搜索引擎源等）直接打开 Web UI「设置」页即可，全部落盘到 `config.json`，无需手改文件。 #### config.json 高频键速查（与 Web UI「设置」页同源） | 键 | 默认 | 说明 | |---|---|---| | `provider` / `model` / `base_url` / `api_key` | 见模板 | 主模型（任意 OpenAI 兼容端点） | | `provider_keys` | `{}` | 多厂商密钥映射，如 `{"deepseek":"sk-…","openai":"sk-…"}`，UI 可一键切换厂商 | | `provider_base_urls` | `{}` | 各厂商自定义端点 | | `deep_thinking` | `true` | 深度思考：先推演再执行 | | `agent_mode` | `react` | `react`（单 Agent 反思循环）/ `multi_agent`（多 Agent 协作） | | `web_host` / `web_port` | `127.0.0.1` / `8848` | Web 监听地址与端口（公网访问需改 host 并开认证） | | `auth_enabled` | `false` | 开启后 Web 界面需登录（建议公网开启） | | `language` | `auto` | `auto` 跟随用户 / `zh` 中文 / `en` 英文 | | `max_turns` / `temperature` | `30` / `0.7` | 单轮最大推理步数、采样温度 | | `sandbox_mode` / `auto_approve` | `off` / `true` | 沙箱强度（`off`/`non-main`/`all`）/ 是否自动批准工具执行 | | `a2a_allow_private` | `false` | 是否放行 A2A 私网目标（默认拦截防 SSRF） | | `cors_origins` | `[]` | 允许的跨域来源 | | `search_engine` | `""` | 旧版单值 SearXNG URL（兼容保留） | | `search_engines` | `[]` | **多搜索引擎源（新版，推荐）**，见下 | #### 搜索引擎多源（搜不到联网结果？多半是这里没配） `web_search` 工具与技能联网搜索需要至少一个**可用**的引擎源。新版走 `search_engines` 多源列表，每项结构： ```jsonc { "search_engines": [ { "name": "我的 SearXNG", "type": "searxng", "url": "http://192.168.1.10:8080/search", "api_key": "", "enabled": true }, { "name": "Tavily", "type": "tavily", "url": "", "api_key": "tvly-xxxx", "enabled": true } ] } ``` - `type` 支持 SearXNG / Bing / Google / Tavily / DuckDuckGo / 自定义等；`api_key` 落盘时自动加密； - **推荐配置方式**：Web UI「设置 → 工具 → 搜索引擎源」可视化管理（多源启停、容错、改完即时生效，无需重启）； - 配置了任一**公网可达**的引擎源（或挂代理），联网搜索才能稳定出结果；全部留空则禁用搜索类工具； - `.env` 的 `SCOUT_SEARCH_ENGINE` 仅等价于一个 `searxng` 单源（旧版兼容），新版**优先读 `search_engines`**。 ### 支持的模型 Web UI 设置页内置各 Provider 的模型目录（含能力标签与发布时间，按最新排序），也可通过 `GET /api/config/providers` 获取。常用最新模型如下： | Provider | 对话模型（最新） | 视觉模型 | 嵌入模型 | 图像模型 | |---|---|---|---|---| | **DashScope** (阿里百炼) | `qwen3.8-max`（旗舰·2026-07）、`qwen3.7-plus`（多模态·推荐）、`qwen3.7-flash`、`qwen3.6-plus`、`deepseek-v4-pro`/`deepseek-v4-flash`、`kimi/kimi-k3`、`glm-5.2`、`MiniMax/MiniMax-M3` | `qwen3.7-plus`、`qwen3.6-plus`、`qwen-vl-max` | `qwen3.7-text-embedding`（最新）、`qwen3-text-embedding-4b`（1024 维）、`text-embedding-v5/v4/v3` | `qwen-image-3.0-pro`（最新）、`qwen-image-2.0-pro`、`wan2.7-image-pro`、`qwen-image-max` | | **DeepSeek** | `deepseek-chat`（V4·2026-05）、`deepseek-reasoner`（R1）、`deepseek-v3.1`、`deepseek-r1-distill-*` | — | — | — | | **智谱 BigModel** | `glm-5.2`（旗舰·2026-04）、`glm-5-plus`、`glm-5-flash`（免费）、`glm-5`、`glm-4-plus`、`glm-4-long` | `glm-4v-plus`、`glm-4v` | `embedding-3`（2048 维）、`embedding-2` | `cogview-4`、`cogview-3-plus`、`cogview-3-flash`（免费） | | **Moonshot (Kimi)** | `kimi-k3`（旗舰·2026-01）、`kimi-k2-thinking`、`kimi-k2`、`moonshot-v1-128k/256k` | — | `embedding-1`（1024 维） | — | | **火山引擎 (豆包)** | `doubao-1.5-pro-32k/256k`、`doubao-1.5-lite-32k`、`doubao-vision-pro` | `doubao-1.5-vision-pro-32k`、`doubao-vision-pro` | `doubao-embedding-large-text`（1024 维·最新） | — | | **OpenAI** | `gpt-4.1`（多模态·最新）、`gpt-4.1-mini`、`o3`（推理）、`o4-mini`、`gpt-4o`、`gpt-4o-mini` | `gpt-4.1`、`gpt-4o`、`gpt-4o-mini` | `text-embedding-3-large`（3072 维）、`text-embedding-3-small` | `gpt-image-1`、`dall-e-3` | | **Anthropic Claude** | `claude-opus-4-20250514`（最强）、`claude-sonnet-4-20250514`（推荐） | `claude-sonnet-4-20250514`、`claude-opus-4-20250514` | — | — | | **Google Gemini** | `gemini-2.5-pro`（旗舰·推理·2M 上下文）、`gemini-2.5-flash`、`gemini-2.0-flash` | `gemini-2.5-pro`、`gemini-2.5-flash` | `gemini-embedding-001`（3072 维） | — | | **OpenRouter**（聚合） | `anthropic/claude-sonnet-4`、`openai/gpt-4.1`、`google/gemini-2.5-pro`、`qwen/qwen3-235b-a22b`、`deepseek/deepseek-chat`、`google/gemini-2.0-flash-exp:free` | 见对应模型 | `openai/text-embedding-3-large/small` | — | > 除上述 Provider 外，任意 OpenAI 兼容端点（`provider=compatible` + 自定义 `base_url`）均可接入，包括自建 vLLM / Ollama / PAI-EAS 等私有部署。 > 模型清单以 Web UI 设置页实时目录为准，代码位于 `scout/adapters/web.py` 的 `/api/config/providers`。 --- ## 💻 命令行 ### 环境自检 ```bash scout doctor ``` 一次性检查运行所需的环境、配置、依赖与运行时状态（含 embedding 配置提示），发现问题会给出修复建议。 ### API Key 管理（加密存储）后台 / Web 模式不依赖 `.env` 明文，可用 `scout key` 将 Key 加密存入 keyring / 加密文件： ```bash scout key --add # 加密保存并激活该 provider scout key --add --no-activate # 仅保存不激活 scout key --activate # 切换当前激活的 provider scout key --list # 列出已保存 Key 的 provider（不泄露明文） ``` ### 后台守护 / 服务管理后台运行 Web 服务，自动管理 PID 与日志（nohup.out）： ```bash scout start # 后台启动 Web 服务（端口 8848，可改配置） scout stop # 安全停止（含 WAL checkpoint 与数据库备份） scout restart # 重启 scout status # 查看运行状态 scout logs # 查看实时日志 scout update # 拉取最新代码并更新依赖 scout version # 查看版本 ``` > ⚠️ **不要用 `pkill -f scout.cli` 强杀进程**——会绕过 WAL checkpoint 与数据库安全备份，可能导致未落盘数据丢失。请使用 `scout stop`。 ### 一键脚本 | 脚本 | 作用 | |------|------| | `bash install.sh` | 一键安装：检测 Python 3.11+、创建 venv/Conda、安装依赖、生成 `.env` 并引导填写 API Key、注册 `scout` 快捷指令 | | `bash update.sh` | 一键更新：安全停止服务 → 备份 `.env` → 拉取代码 → 更新依赖 → 重启 | | `bash run.sh --web` | 便捷启动 Web（自动激活环境并加载 `.env`） | | `bash run.sh` | 终端对话模式 | | `bash version.sh info` | 版本管理：`info / check / bump / set / history` | | `bash run_tests.sh` | 运行全部测试 | --- --- ## 🔒 安全 Scout Agent 高度重视安全： - 🛡 **沙箱执行**：Docker 隔离的命令执行（可选） - ⛔ **危险命令拦截**：`rm -rf /`、fork 炸弹等黑名单 - 🔒 **Shell 注入防护**：白名单 + 元字符拦截 - 🧹 **XSS 防护**：DOMPurify 消毒渲染内容 - 🔑 **可选认证**：Web API 的 JWT 认证（设置页「登录认证」开关控制，默认关闭） - 📁 **文件访问控制**：下载限制在工作空间内 - 🔐 **密钥存储**：API Key 存于 keyring 或加密文件 > 💡 **Windows 沙箱须知**：沙箱依赖 Docker Desktop（WSL2 后端）。Docker 不可用时默认**回退本地执行**（仅记录告警日志）——需要杜绝静默降级时，设置 `SCOUT_SANDBOX_REQUIRE_DOCKER=1` 强制失败。在 Web UI「设置 → 安全」开启沙箱时会弹出影响范围确认（容器内无网络 / 资源受限 / 响应略慢）。 --- ## 🧑‍💻 开发 ### 项目结构 ``` scout-agent/ ├── scout/ # 核心代码 │ ├── adapters/ # 平台适配器（飞书/微信/TG/Discord 等 12+ 渠道） │ ├── a2a/ # Agent-to-Agent 协议（Google A2A：AgentCard/任务收发） │ ├── automation/ # 自动化中心（事件触发器/Cron/无人值守策略） │ ├── bus/ # 事件总线（EventBus / NATS JetStream） │ ├── config/ # 配置与路径管理（config.json 读写/api_key 加密） │ ├── context/ # 跨会话上下文组装（记忆×重要性×时间衰减+摘要） │ ├── core/ # 核心类型/工具契约注解/统一错误码 │ ├── engine/ # 智能体引擎（ReAct 循环/自愈反思/技能合成/技能搜索） │ ├── eval/ # 评测基准（隔离评测 + Pass@1/3/5） │ ├── gateway/ # Web 网关与路由 │ ├── infra/ # 基础设施（健康检查等） │ ├── llm/ # LLM Provider 统一接入 │ ├── memory/ # 记忆存储与检索（纯文本/向量） │ ├── multiagent/ # 多智能体委派架构 │ ├── notify/ # 通知中心（推送规则/IM 渠道投递） │ ├── planner/ # 任务规划（DAG 计划-执行） │ ├── plugins/ # 插件系统 + SPI（llm/storage/cache/session/memory） │ ├── scheduler/ # 定时任务调度 │ ├── security/ # 安全层（Docker 沙箱/危险命令/密钥加密/A2A SSRF 拦截） │ ├── session/ # 会话管理 │ ├── skills/ # 技能库（安装/发现/向量检索） │ ├── storage/ # 存储后端（SQLite/PostgreSQL/Redis） │ ├── tools/ # 工具实现 │ │ └── builtin/ # 20+ 内置工具（文件/shell/代码执行/搜索/MCP/浏览器/桌面操控 desktop…） │ ├── voice/ # 语音（ASR/TTS） │ ├── web/ # Web UI（FastAPI 服务 + 静态页面） │ ├── cli.py # 命令行入口 │ ├── manager.py # 守护进程管理（start/stop/restart/status/logs） │ └── doctor.py # 环境自检（scout doctor） ├── desktop/ # Windows 桌面版（launcher + PyInstaller 打包） ├── tools/ # 构建与生成脚本（build_windows_portable.py 等） ├── tests/ # 测试（unit/integration） ├── plugins/ # 示例插件 ├── skills-library/ # 11 个实测技能库（GUI 操控/微信/飞书/Office/UWP…，复制到数据目录即用） ├── examples/ # 示例代码 ├── docs/ # 文档与界面截图 ├── install.sh / install.ps1 # 一键安装（Linux·macOS / Windows） ├── run.sh / run.bat # 便捷启动脚本（--web / 终端对话） ├── update.sh # 一键更新（安全停止→备份→拉取→重启） ├── version.sh # 版本管理 ├── run_tests.sh # 测试脚本 ├── Dockerfile / docker-compose.yml # Docker 部署（+PostgreSQL/Redis/NATS） ├── config.example.json # config.json 配置模板 ├── QUICKSTART.md # 快速开始指南 ├── CONTRIBUTING.md # 贡献指南 └── THIRD_PARTY_NOTICES # 第三方组件声明 ``` ### 添加新工具 1. 在 `scout/tools/builtin/` 下新建目录 2. 实现继承 `ToolDefinition` 的工具类 3. 在 `__init__.py` 中注册工具 4. 在 `tests/unit/` 添加测试 ### 添加新平台 1. 在 `scout/adapters/platforms/` 下创建适配器 2. 实现 `ChannelAdapter` 接口 3. 在 `channel_manager.py` 注册 4. 在 Web UI 添加配置表单 --- ## 🧪 测试 ```bash # 运行全部测试 pytest tests/unit tests/integration -v # 仅运行单元测试 pytest tests/unit -v # 运行指定文件 pytest tests/unit/test_tools.py -v # 使用测试脚本 ./run_tests.sh ``` --- ## 📄 许可证 **Apache-2.0** — 详见 [LICENSE](LICENSE)。 ---