# desktop-agent
**Repository Path**: mingwuda/desktop-agent
## Basic Information
- **Project Name**: desktop-agent
- **Description**: 一个本地/私有部署的桌面 AI 智能体。它基于 FastAPI、LangGraph 和 OpenAI 兼容模型接口，提供聊天式任务执行、工具调用、文件制品下载、Skills 技能扩展、多用户隔离、长期记忆和可视化执行过程
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 7
- **Forks**: 3
- **Created**: 2026-05-24
- **Last Updated**: 2026-10-02
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Moss Agent
[中文](README.md) | [English](README.en.md)
Moss Agent 是一个本地/私有部署的桌面 AI 工作台。它基于 FastAPI、LangGraph 和 OpenAI 兼容模型接口，提供聊天式任务执行、工具调用、文件制品下载、Skills 技能扩展、多用户隔离、长期记忆和可视化执行过程。
适合用作个人或团队内网的项目控制台：浏览工作区文件、运行 Python、搜索网页、管理 Git、生成文档、分析图片、委派子代理处理独立任务。代码编辑交给专业编辑器，这里只做决策与执行。
## 目录
- [核心能力](#核心能力)
- [快速开始](#快速开始)
- [登录与多用户](#登录与多用户)
- [模型配置](#模型配置)
- [使用方式](#使用方式)
- [文件制品](#文件制品)
- [Python 实时输出流](#python-实时输出流)
- [ZIP 文件上传与分析](#zip-文件上传与分析)
- [长上下文处理](#长上下文处理)
- [Skills](#skills)
- [子代理](#子代理)
- [长期记忆](#长期记忆)
- [自进化记忆（Case→Skill 蒸馏）](#自进化记忆case-skill-蒸馏)
- [多页签与 SSE 持久化](#多页签与-sse-持久化)
- [定时任务](#定时任务)
- [征询用户](#征询用户)
- [插件系统](#插件系统)
- [Jev 决策库](#jev-决策库)
- [微信集成](#微信集成)
- [数据库交互](#数据库交互)
- [远程部署](#远程部署)
- [系统守护与自愈](#系统守护与自愈)
- [Windows 打包](#windows-打包)
- [项目结构](#项目结构)
- [技术栈](#技术栈)
- [安全边界](#安全边界)
- [API](#api)
---
⬆ 返回目录
## 核心能力
| 能力 | 说明 |
| --- | --- |
| 聊天式 Agent | LangGraph ReAct Agent，支持流式输出、思考/工具步骤展示、长任务进度提示和终止任务 |
| 多行与图片输入 | 输入框支持多行文本、粘贴图片；图片只用于当轮分析，不把 base64 写入历史 |
| 文件与 ZIP 上传 | 支持上传图片（分析视觉内容）和 ZIP 压缩包（自动解压到工作区，生成文件清单供 AI 分析项目结构） |
| 多模态模型切换 | MiMo 系列发图时，如果当前模型不支持图片，会本轮临时切换到 `mimo-v2.5` |
| 文件工具 | 读写/追加/删除/列出/搜索工作区文件，大文件只返回摘要和路径，避免撑爆上下文 |
| 文件制品 | AI 生成工作区文件后自动追加下载链接；Markdown 文件支持弹窗预览 |
| 文件 Diff 可视化 | Agent 修改文件后，前端实时展示绿/红高亮的行级变更对比，支持折叠展开 |
| 文件浏览器推送 | 文件浏览器头部自动检测未推送提交数量，支持一键推送当前分支到远程 |
| 文件预览体系 | Markdown 渲染、highlight.js 语法高亮、零依赖行号、Diff 双列行号可视化、新增文件合成 diff |
| Git 工作流闭环 | LLM 自动生成提交信息 → 一键 commit → 一键 push，高危命令需用户确认 |
| Agent 输出卡片 | 工作耗时 + 思考/工具过程 + 当前动作 + 进度指示，历史消息回放统一结构 |
| 项目工作区 | 引入「项目」概念，会话归属项目，文件浏览器直接浏览项目目录 |
| MCP 动态重载 | 切换会话按 workspace 合并配置、后台线程重载、右上角实时展示连接状态 |
| Todo 清单 | Agent 自动将复杂任务拆解为 Todo 清单，逐项跟踪完成进度，支持批量完成和状态同步 |
| Python 执行 | 运行 Python 代码并返回输出；超大输出只返回摘要、开头和结尾；**支持实时流式输出**，避免用户空等 |
| 网页能力 | `web_search` 搜索网页（Bing → 搜狗 → DuckDuckGo 逐级 fallback），`web_fetch` 抓取正文 |
| Git 工具 | 查看状态、diff、日志、show、worktree；按明确指令 add/commit/push/revert/merge/checkout |
| Shell 命令 | `run_shell` 执行 shell 命令（bash/zsh/sh/powershell/cmd），自动跨平台适配，内置安全拦截 |
| 浏览器自动化 | 内置 Playwright 浏览器，支持导航、点击、填表、截图、JS 执行等操作；截图通过 token URL 访问，避免路径泄露 |
| 验证码识别 | 基于多模态大模型的验证码自动识别，支持扭曲文字/滑块/图标点选/汉字点选等类型；验证码元素自动定位、坐标自适应缩放、低置信度自动刷新重试 |
| 子代理 | `delegate_task` 串行 + `delegate_tasks_parallel` 并行委派 coder/reviewer/debugger/searcher；**支持实时日志流**展示执行过程 |
| Skills | 加载 `SKILL.md`，兼容 YAML frontmatter 和 oh-my-openagent / Superpowers 风格技能；内置 `database-interaction` 技能支持自然语言数据库交互 |
| 长期记忆 | 按用户隔离保存长期偏好、项目事实和常用环境信息 |
| 数据库交互 | 内置 `dbcli` 核心库 + CLI 工具 + Agent 技能，支持 SQLite / PostgreSQL / MySQL 自然语言查询，列级/行级权限控制 |
| 多用户 | 登录保护、管理员用户管理、每个用户独立工作区、会话、用量和记忆；支持 `AGENT_USERS` 环境变量批量配置 |
| 上下文管理 | 按模型上下文窗口估算长度，达到阈值时压缩历史；大日志/大文件不直接塞全文 |
| 用量统计 | 按用户、会话、Provider、模型和工具统计调用与 token |
| 会话消息管理 | 支持删除单条消息、历史消息图片点击放大、图片懒加载（lite 接口不传 base64） |
| 系统守护与自愈 | Guardian 守护进程：boot 自愈、健康巡检、崩溃自动重启；主进程 + 守护进程双 systemd unit 管理 |
| 工具卡片 | 步骤卡片带绿色左边框、工具名 + 耗时 + 状态圆点、参数/结果分栏展示，支持折叠 |
| 多页签 | 单界面同时打开多个会话页签；页签状态持久化到 localStorage，刷新浏览器自动还原；正在请求的页签标题带扫光 loading 效果 |
| 定时任务 | 侧边栏「定时任务」面板，按项目管理 cron 任务，支持表达式解析、创建/编辑/删除、手动立即执行、自动打开执行轨迹会话 |
| 征询用户 | `ask_user` 工具在决策边界主动弹出选项让用户拍板，阻塞等待用户答复后再继续；多页签不串台（弹窗绑定当前会话） |
| SSE 持久化 | 流式消息实时落盘，刷新浏览器/关闭重开后可从文件恢复已生成的轨迹，不丢失上下文 |
| 自进化记忆 | 借鉴 EverOS：Agent 完成任务 → reflect 提炼 technique → 累积 Case → 达阈值蒸馏候选 SKILL → 半自动审批生效 |
| 插件系统 | 插件加载器 + 事件钩子 + 设置页管理，支持自定义 SSE 事件推送和前端注入；参数变更自动热重载 |
| Jev 决策 | 通用 LLM 决策库：表单字段自动填充、shell 风险门控、验证码置信度交叉校验、判别式上下文压缩 |
---
⬆ 返回目录
## 快速开始
### 环境要求
- Python 3.9+，推荐 3.10+（3.9 通过 `from __future__ import annotations` 兼容）
- 一个 OpenAI 兼容模型 API Key
- 可选：Git、curl、Windows 打包环境
### 启动
```bash
git clone https://gitee.com/mingwuda/desktop-agent.git
cd desktop-agent
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements.txt
./start.sh
```
或使用 Docker 一键部署（见下方 [远程部署 → Docker](#docker推荐)）。
启动后打开：
```text
http://127.0.0.1:8899/
```
也可以直接启动后端：
```bash
cd agent_core
.venv/bin/python main.py
```
Windows 可执行：
```cmd
.venv\Scripts\python.exe -m pip install -r requirements.txt
start.cmd
```
首次启动会创建配置、认证和用户数据目录。默认如果没有配置用户，会创建 `admin / admin123`，正式部署请立即修改。
---
⬆ 返回目录
## 登录与多用户
服务默认启用登录保护。认证文件位于：
```text
~/.desktop_agent/auth.json
```
可通过环境变量初始化登录配置：
```bash
# 多用户（推荐，Docker / systemd 环境）
export AGENT_USERS='admin:your-password;guest:guest123'
# 或单用户（DEPRECATED）
export DESKTOP_AGENT_AUTH_USER=admin
export DESKTOP_AGENT_AUTH_PASSWORD='your-strong-password'
export DESKTOP_AGENT_AUTH_SECRET='replace-with-a-random-secret'
```
支持短期免密登录链接：
```bash
python generate_login_url.py --host 127.0.0.1 --port 8899 --expires 300 --user admin
```
可选参数：
- `--qr`：在终端显示二维码
- `--copy`：复制到剪贴板
多用户数据按用户隔离：
```text
~/.desktop_agent/users/{user_id}/sessions/sessions.sqlite3
~/.desktop_agent/users/{user_id}/usage/usage.sqlite3
~/.desktop_agent/users/{user_id}/memory/
~/agent_workspace/{user_id}/
```
只有 `admin` 用户能看到设置和用户管理相关入口。
---
⬆ 返回目录
## 模型配置
在页面右上角点击“设置”，可以配置：
| 字段 | 说明 |
| --- | --- |
| 模型厂商 | OpenAI、DeepSeek、通义千问、Anthropic 或自定义 Provider |
| API Key | 模型服务密钥 |
| 模型名称 | 例如 `gpt-4o`、`deepseek-chat`、`qwen-plus`、`mimo-v2.5-pro`、`claude-sonnet-4-20250514` |
| API 地址 | OpenAI 兼容地址，留空则使用厂商默认地址 |
| 最大推理步数 | LangGraph 单次任务最大循环步数，默认 `60` |
| 请求重试次数 | 模型连接错误重试次数，默认 `3` |
| 请求超时 | 模型读取超时，默认 `30` 秒 |
| 上下文窗口 | 当前模型最大上下文长度；留空时按模型名内置估算 |
配置保存到：
```text
~/.desktop_agent/config.json
```
常用环境变量：
| 环境变量 | 说明 | 默认 | 必需? |
| --- | --- | --- | --- |
| `LLM_API_KEY` / `OPENAI_API_KEY` | API Key | 空 | **✅ 必需** — 无默认值，服务无法连接模型 |
| `LLM_MODEL` | 模型名称 | `gpt-4o` | **✅ 必需** — 需改为你实际可用的模型名 |
| `LLM_PROVIDER` | 当前 Provider | `openai` | 可选 — 使用其他厂商时修改 |
| `LLM_BASE_URL` / `OPENAI_BASE_URL` | API 地址 | 空 | 可选 — 非 OpenAI 官方时填写 |
| `ANTHROPIC_API_KEY` | Anthropic API Key | 空 | 可选 — 使用 Claude 模型时填写 |
| `ANTHROPIC_BASE_URL` | Anthropic API 地址 | 空 | 可选 — 非官方地址时填写 |
| `AGENT_HOST` | 监听地址 | `127.0.0.1` | 可选 — 公网部署需改为 `0.0.0.0` |
| `AGENT_PORT` / `DESKTOP_AGENT_PORT` | 监听端口 | `8899` | 可选 |
| `AGENT_USERS` | 多用户列表 `user1:pass1;user2:pass2` | 空 | 可选 — 不设置则默认创建 `admin/admin123` |
| `AGENT_WORKSPACE` | 工作区根目录 | `~/agent_workspace` | 可选 |
| `AGENT_SKILLS_DIR` | 额外 Skills 目录 | 内置 samples | 可选 |
| `AGENT_RECURSION_LIMIT` | 最大推理步数 | `60` | 可选 |
| `AGENT_API_MAX_RETRIES` | 模型连接错误重试次数 | `3` | 可选 |
| `AGENT_API_TIMEOUT_SECONDS` | 模型请求超时秒数 | `120` | 可选 |
| `AGENT_CONTEXT_WINDOW_TOKENS` | 手动指定模型上下文窗口 | 自动识别 | 可选 |
| `AGENT_API_HOST_IPS` | 自定义模型网关 DNS 兜底 IP 列表 | 空 | 可选 — 仅网络排障时使用 |
| `AGENT_SHARED_TOKEN` | 共享 API Token | 空 | 可选 |
| `DESKTOP_AGENT_AUTH_COOKIE_SECURE` | Cookie 是否仅 HTTPS 发送 | `0` | 可选 — 公网 HTTPS 部署建议设为 `1` |
`AGENT_API_HOST_IPS` 只用于 DNS/网络排障，服务不会内置任何厂商 IP。多个 IP 用英文逗号分隔。
### 图片输入与视觉模型
前端支持直接粘贴图片到输入区。后端会把图片转换为 OpenAI 兼容的 `image_url` 消息格式。
图片不会写入 SQLite 历史，也会在本轮完成后从 LangGraph checkpoint 中清理，避免后续纯文本消息重复携带图片。
MiMo 系列模型有特殊处理：当本轮包含图片，且当前模型名包含 `mimo` 但不是 `mimo-v2.5` / `mimo-v2-omni` 时，系统会临时使用 `mimo-v2.5` 执行本轮请求，并在前端显示提示。默认模型设置不会被修改。
---
⬆ 返回目录
## 使用方式
输入框支持：
- `Enter` 换行
- `Cmd/Ctrl + Enter` 发送
- 直接粘贴图片
- 执行中点击“停止”终止当前任务
示例问题：
```text
帮我列出工作区文件
写一段 Python 代码计算斐波那契数列并运行
搜索今天的 AI 新闻并总结
打开这个链接并总结正文：https://example.com/article
看一下这个仓库当前有哪些改动
把当前改动提交一下，提交信息是：完善 Skills 支持
帮我 push 当前分支
回退上一个提交
记住：我希望回复默认使用中文
帮我规划一个博客系统，列出 Todo 清单并逐步完成
帮我分析这个项目的代码结构，生成一个改进建议报告
```
### Git 工具边界
Git 工具包括：
```text
git_status git_diff git_log git_show
git_add git_commit git_commit_all git_push
git_revert git_command
```
`git_command` 安全白名单：
| 子命令 | 允许操作 |
|--------|---------|
| `status` / `diff` / `log` / `show` | 查看 |
| `add` | 暂存文件 |
| `commit -m` / `commit --amend -m` | 提交 / 改写最近提交信息 |
| `push` / `push -u origin branch` | 推送 |
| `revert ` | 回退提交 |
| `branch` / `branch -a` / `branch -d/-D ` | 查看/删除分支 |
| `checkout ` / `checkout -b ` | 切换/创建分支 |
| `merge ` | 合并分支 |
| `worktree list / add / remove / prune` | 工作树管理 |
| `remote -v` | 查看远程仓库 |
安全策略：
- 只有用户明确要求提交时才使用 `git_add` / `git_commit` / `git_commit_all`
- 只有用户明确要求推送时才使用 `git_push`
- 只有用户明确要求回退版本时才使用 `git_revert`
- `git commit --amend -m` 仅允许改写最近提交信息（amend 会改写历史，仅限用户明确要求时使用）
- `git_push` 只允许普通 push、指定 remote/branch、首次设置 upstream
- `git_revert` 只允许单个 revision，支持 `--no-commit`
- 不开放 `pull`、`reset`、`restore`、force push、range revert、merge revert 等高风险操作
### Shell 工具边界
`run_shell` 工具支持跨平台 shell 命令执行：
| 平台 | 使用的 Shell |
|------|-------------|
| Linux/macOS | bash → zsh → sh（自动检测） |
| Windows | powershell → cmd（自动检测） |
安全策略：
- 禁止提权操作（`sudo`、`su`）
- 禁止格式化磁盘（`mkfs`、`mkswap`、`dd if=`）
- 禁止 fork bomb 和管道关机
- 默认 120 秒超时（最大 600 秒）
- 输出超过 20000 字符时自动截断（保留头 8000 + 尾 8000）
- 自动对比执行前后工作区文件变更并汇总
### 浏览器自动化
Moss Agent 内置 Playwright 浏览器，支持完整的页面交互流程：
| 工具 | 用途 |
|------|------|
| `browser_navigate` | 导航到指定 URL |
| `browser_click` | 点击 CSS 选择器匹配的元素 |
| `browser_fill` | 在输入框中填入文本 |
| `browser_select` | 选择下拉框选项 |
| `browser_get_text` | 获取元素文本内容 |
| `browser_screenshot` | 截图（全页或视口） |
| `browser_evaluate` | 执行 JavaScript |
| `browser_wait` | 等待指定时长 |
| `browser_scroll_to` | 滚动页面到元素或坐标 |
| `browser_wait_for_element` | 等待元素出现/可见 |
| `browser_drag` | 拖拽元素到目标位置 |
| `browser_slide` | 滑块操作（含人类化轨迹模拟） |
### 验证码识别
基于多模态大模型（如 step-3.7-flash、gpt-4o）的验证码自动识别与交互：
| 验证码类型 | 识别方式 |
|------------|----------|
| 扭曲字母/数字 | 直接返回字符，调用 `browser_fill` 填入 |
| 文字点选（汉字） | 识别汉字位置和顺序点击 |
| 图标点选 | 识别图标名称和位置，按顺序点击 |
| 滑块验证码 | 标记类型，引导 `browser_slide` 拖动 |
**工具链：**
1. `browser_captcha_recognize(source="page")` — 全页截图检测验证码
2. `browser_captcha_recognize(source="selector:#captcha")` — 验证码元素特写截图，精确坐标
3. `browser_captcha_scan_grid(rows=9, cols=16)` — 叠加 SVG 网格辅助定位
4. `browser_click_captcha(clicks=...)` — 视口坐标点击
5. `browser_captcha_click_sequence(selector, clicks, ...)` — 元素内坐标点击
6. `browser_captcha_refresh(selector)` — 低置信度时自动刷新验证码重试
**低置信度处理：** 识别置信度低于 0.5 时自动建议刷新验证码重试。
**日志上下文：** 每条日志携带 `[s:sessionId] [m:messageId]` 前缀，支持按会话和消息维度检索。
### 文件工具边界
`write_file` / `append_to_file` / `edit_file` 等写操作默认只能修改工作区内的文件。
如需编辑工作区外的文件，前端工具卡片会显示 **「授权写入」** 按钮：
1. 点击后授权该文件路径（同时自动授权其父目录）
2. 授权仅当前进程有效，重启后需要重新授权
3. 也可通过设置会话工作目录来扩大允许范围
### 会话工作目录
每个会话可以设置独立的工作目录，切换会话时自动恢复。工作目录内的文件操作不受"路径超出工作区"限制。
在顶部栏点击 📁 路径显示区域，输入绝对路径或相对于默认工作区的路径即可设置。设置后的目录会自动创建（如不存在），并立即生效。
支持 API：
- `PUT /sessions/{session_id}/workspace` — 设置工作目录
- `GET /sessions/{session_id}/workspace` — 获取工作目录
⬆ 返回目录
## 文件制品
如果 Agent 使用 `write_file` 或 `append_to_file` 在工作区生成文件，最终回复会自动追加“可下载文件”区域。
Markdown 文件会同时提供：
- `预览`：在页面弹窗中渲染 Markdown
- `下载`：直接下载原文件
普通文件只提供下载链接。
---
⬆ 返回目录
## Python 实时输出流
当 Agent 执行 `run_python` 时，输出会**实时流式推送**到前端的终端风格黑底代码块中，无需等待脚本执行完毕即可看到中间输出。
适用于长时间运行的脚本（如数据爬取、模型训练、批量处理）。
---
⬆ 返回目录
## ZIP 文件上传与分析
支持上传 `.zip` 压缩包（最大 50MB），后端自动解压到工作区并生成文件清单：
```
[DIR] src/
[FILE] src/main.py (2.3KB)
[FILE] src/utils.py (1.1KB)
...
```
LLM 会直接看到项目结构，可以据此分析代码、给出建议或执行后续操作。解压后的文件保留在工作区 `~/.agent_zip/{name}_{hash}/` 目录下，Agent 可直接读写。
---
⬆ 返回目录
## 长上下文处理
系统会估算 LangGraph checkpoint 中的消息长度，并根据模型最大上下文窗口的 80% 作为压缩阈值。
内置识别示例：
| 模型 | 上下文窗口 |
| --- | --- |
| `gpt-4o` / `gpt-4o-mini` | 128K |
| `gpt-4.1` / `gpt-4.1-mini` | 1M |
| `qwen-long` | 1M |
| `mimo-v2.5-pro` / `mimo-*` | 1M |
| `deepseek-chat` / `deepseek-reasoner` | 64K |
达到阈值后会压缩旧消息，保留最近上下文。完整历史仍在 SQLite 中，可通过会话记录查看。
大文件、大日志和 Python 超大输出不会完整塞入模型上下文，只返回摘要、路径、开头和结尾。
---
⬆ 返回目录
## Skills
Moss Agent 会加载以下目录中的 `SKILL.md`：
```text
agent_core/samples/
AGENT_SKILLS_DIR 指定目录
项目内 .opencode/skills/
项目内 skills/
项目内 .claude/skills/
项目内 .agents/skills/
```
支持两种格式：
1. 简单 Markdown 章节：`Description`、`Trigger`、`Instructions`
2. YAML frontmatter：兼容 oh-my-openagent / Superpowers 风格
示例：
```markdown
---
name: systematic-debugging
description: 系统化定位根因
triggers: [debug, 排查, 根因]
---
当用户需要排查问题时：
1. 先复现现象
2. 列出假设
3. 逐步验证
4. 给出根因和修复建议
```
侧边栏会显示已加载技能，区域固定高度并支持滚动；鼠标悬停会展示描述和触发词。用户问“你有哪些技能”时，后端会直接返回真实 SkillRegistry 内容，避免模型误报。
当前项目内置/随项目保留的技能包括 14 个：
| 技能 | 来源 | 用途 |
|------|------|------|
| `daily-report` | 内置示例 | 日报生成 |
| `brainstorming` | oh-my-openagent | 需求澄清、方案设计 |
| `writing-plans` | oh-my-openagent | 生成实施计划 |
| `executing-plans` | oh-my-openagent | 批量执行计划 |
| `test-driven-development` | oh-my-openagent | TDD 红绿重构 |
| `systematic-debugging` | oh-my-openagent | 四阶段系统化调试 |
| `verification-before-completion` | oh-my-openagent | 完成前验证 |
| `receiving-code-review` | oh-my-openagent | 接收代码审查反馈 |
| `frontend-ui-ux` | oh-my-openagent | 前端 UI/UX 设计 |
| `subagent-driven-development` | Superpowers | 子代理派发 + 两阶段审查（P0） |
| `requesting-code-review` | Superpowers | 主动代码审查，严重等级评估（P0） |
| `dispatching-parallel-agents` | Superpowers | 并行派发独立子代理（P1） |
| `finishing-a-development-branch` | Superpowers | 开发分支收尾清理（P2） |
| `using-git-worktrees` | Superpowers | Git Worktree 隔离开发环境（P1） |
| `database-interaction` | 内置 | 自然语言数据库交互 |
---
⬆ 返回目录
## 子代理
`delegate_task` 可以把独立任务委派给子代理同步执行，`delegate_tasks_parallel` 可以并行派发多个独立任务。
| 子代理 | 用途 |
| --- | --- |
| `coder` | 编码实现、局部修改 |
| `reviewer` | 代码审查、风险和缺失测试检查 |
| `debugger` | 系统化排障、根因定位 |
| `searcher` | 专精互联网搜索，调用 web_search + web_fetch 整理结果 |
所有子代理都支持**实时日志流**，点击胶囊可查看执行过程（工具调用、AI 思考、结果）。
### 串行执行
```python
delegate_task(task="...", agent_type="coder", context="...")
```
主 Agent 等待子代理完成后继续。适用于有依赖关系的任务。
### 并行执行
```python
delegate_tasks_parallel('''[
{"task": "任务1", "agent_type": "coder", "context": "..."},
{"task": "任务2", "agent_type": "coder", "context": "..."}
]''')
```
基于 `ThreadPoolExecutor` 真正并行，同一时间最多 4 个子代理。适用于无文件/数据依赖的任务。
### 安全策略
- 子代理默认不能再调用 `delegate_task` 和 `delegate_tasks_parallel`，避免递归委派
- 每个子代理的 prompt 必须完全自包含
- 并行任务的同一文件同一时间只能被一个子代理修改
---
⬆ 返回目录
## 长期记忆
长期记忆按用户隔离，适合保存：
- 用户偏好：默认语言、回答风格
- 项目事实：部署目录、端口、常用服务器
- 长期约定：公网部署必须开启登录保护
工具：
```text
remember
recall_memory
forget_memory
list_memories
```
当前采用显式记忆策略：只有用户明确要求“记住/以后记得/保存偏好”时才写入。不要保存 API Key、密码、Cookie、Token 等敏感信息。
页面顶部“记忆”按钮可打开管理面板，支持新增、搜索和删除。
---
⬆ 返回目录
## 自进化记忆（Case→Skill 蒸馏）
Moss Agent 内置借鉴 EverOS 的自进化机制：Agent 完成带工具调用的任务后，`reflect_on_task` 会提炼出一条 technique 反思，`case_forge` 把同类反思累积成结构化 Case，达到阈值后自动起草候选 SKILL.md 进入「待审批目录」，由用户确认后生效。
### 闭环
```text
Agent 完成任务
└─ reflect_on_task → 一条 technique（{t, v}）
└─ case_forge.accumulate_case → 结构化 Case（背景/动作序列/结果/出现次数）
└─ 同一 Case occurrences ≥ 3（_CASE_PROMOTE_THRESHOLD）
└─ 起草候选 SKILL.md → skills_dir/pending/
├─ 用户 approve → 移入技能目录 + registry.reload() → 下次命中触发词时生效
└─ 用户 reject → 丢弃候选
```
### 特性
- **半自动**：生成后待用户确认再生效，避免单次偶发方法污染技能库
- **动作序列**：记录工具调用轨迹（去重、封顶 12 步），蒸馏出的 SKILL.md 含可复用步骤
- **幂等**：同 topic 同方法用全文 hash 指纹防碰撞（不同方法各自成 Case）
- **Markdown 可读镜像**：记忆库同时输出可读 Markdown，便于人工审查
- **双轨正交检索**：case（可执行技能轨迹）与 preference/avoid（偏好/踩坑）分轨检索，互不污染；检索支持同义词扩展与相关性阈值过滤
- **审批接口**：`/skills/pending` 列表、`/skills/pending/approve`、`/skills/pending/reject`（body 含 `name`）；桌面端设置页提供待审批技能面板
---
⬆ 返回目录
## 多页签与 SSE 持久化
### 多页签
桌面端支持在同一界面打开多个会话页签，无需切换侧边栏即可并行查看多个对话。
- **状态持久化**：打开/关闭/激活页签实时写入 `localStorage`（`desktop_chat_tabs_v1`），刷新浏览器自动还原所有页签并加载各自的历史消息
- **loading 效果**：正在请求中的页签标题带浅蓝扫光动画（参考 deepseek-harness 风格），请求结束自动停止
- **会话隔离**：每个页签的 SSE 流、运行状态、停止逻辑互相独立，不会串台
### SSE 持久化
流式消息（工具调用、思考、输出）实时落盘到文件。刷新浏览器或关闭重开后，可从文件恢复已生成的完整轨迹，不会因断连丢失上下文。
---
⬆ 返回目录
## 定时任务
侧边栏「定时任务」面板支持按项目管理 cron 定时任务。
| 功能 | 说明 |
| --- | --- |
| 创建/编辑 | 指定 cron 表达式 + 项目工作区 + 提示词，后端按 schedule 自动触发 |
| 表达式解析 | `/cron/parse` 支持标准 5 段 cron，返回人类可读描述（如「每天 09:00」） |
| 手动立即执行 | 「立即执行」按钮，执行过程写入固定会话 `cron_sess_{taskId}`，自动打开该会话展示轨迹 |
| 管理 | 按项目列表、按 taskId 编辑/删除；全局列表支持跨项目 |
API：
| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/cron` | GET/POST | 列出所有定时任务 / 创建 |
| `/cron/{task_id}` | PUT/DELETE | 更新 / 删除 |
| `/cron/parse` | POST | 解析 cron 表达式 |
| `/cron/{task_id}/run` | POST | 手动立即执行 |
| `/projects/{project_id}/cron` | GET | 列出某项目的定时任务 |
---
⬆ 返回目录
## 征询用户
`ask_user` 工具允许 Agent 在执行中主动向用户征询意见，弹出选项（+可选自定义输入）等待用户拍板后再继续。
- **适用场景**：多个互斥方案需选择、涉及用户资源/账户操作需确认、需用户补充关键参数
- **阻塞式**：调用后当前任务暂停，前端弹出问卷弹窗，用户提交后 Agent 继续
- **多页签不串台**：弹窗绑定当前会话的 `thread_key`，多页签环境下不会因切换会话导致提交失败
---
⬆ 返回目录
## 插件系统
支持第三方插件扩展 Agent 能力，包括自定义工具、事件钩子、SSE 事件推送和前端 UI 注入。
| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/plugins` | GET | 列出已加载插件 |
| `/plugins/{name}/toggle` | POST | 启用/禁用插件 |
插件参数变更时自动热重载，无需重启服务。
---
⬆ 返回目录
## Jev 决策库
通用 LLM 决策层，将复杂判断封装为可复用决策，接入多个工具场景：
| 场景 | 说明 |
| --- | --- |
| 表单自动填充 | `browser_form_fill` 用 Jev 逐字段决策（单选/复选/提交），文本字段由 values 提供 |
| Shell 风险门控 | `run_shell` 高危命令前 Jev 判断语义风险，命中则拦截 |
| 验证码置信度 | 识别结果交叉校验，低置信度建议刷新重试 |
| 上下文压缩 | 判别式压缩（保留/丢弃决策），替代简单截断 |
---
⬆ 返回目录
## 微信集成
Moss Agent 通过**腾讯官方 iLink Bot API** 接入微信个人号，让你可以直接在微信里与 Agent 对话。
### 特性
- **官方合法**：基于腾讯 iLink 协议，有法律条款背书，无封号风险
- **无需公网 IP**：客户端主动长轮询微信服务器，不需要 ngrok / frp / 公网域名
- **扫码一次，永久使用**：Token 持久化到本地文件，服务重启后自动恢复轮询
- **多用户隔离**：每个平台用户可绑定独立的微信 Bot，token、会话、轮询完全隔离
- **信息零存储**：腾讯仅做消息管道中转，不存储你的消息内容和 AI 输出
- **图文消息**：支持接收用户发送的图片+文字提问，也支持 Agent 生成图片后主动向用户发送图文消息（CDN 上传 + AES 加密）
- **会话同步**：微信中的对话自动保存到 Web 端会话列表，带 💬 图标标识；同名 ID 的 Web 和微信会话各自独立展示
### 使用步骤
#### 1. 安装依赖
```bash
pip install qrcode[pil]
```
#### 2. 重启服务
确保后端已加载最新代码（`agent_core/wechat_bot.py`）。
#### 3. 扫码登录
浏览器访问：
```
http://localhost:8899/wechat/qrcode
```
页面会显示微信登录二维码，用手机微信扫码并确认。扫码成功后 Bot 自动开始轮询消息。
如果是多用户环境，每个用户访问 `/wechat/qrcode` 都会生成**属于该用户的二维码**，token 按用户隔离存储。
#### 4. 开始使用
在微信里给 Bot 发送消息，Agent 会自动回复。回复内容会同步显示在 Web 端的会话列表中（带 💬 图标标记）。
支持在微信内通过指令管理会话：
| 指令 | 说明 |
|------|------|
| `/new` | 创建新会话 |
| `/list` | 列出所有会话（带序号），显示 sessionId 和最后一条用户消息，当前会话用 `→` 标记 |
| `/switch <序号\|sessionId>` | 切换到指定会话（支持 `/list` 显示的序号或原始 ID） |
| `/delete <序号\|sessionId> [...]` | 删除一个或多个历史会话（空格分隔多个，支持序号或原始 ID；删除后自动回显删除后的最新会话清单并刷新序号映射；删除当前会话后，下一轮消息会自动重建默认会话） |
### 管理端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/wechat/qrcode` | GET | 微信扫码登录页面（返回 HTML，按当前登录用户生成二维码） |
| `/wechat/qrcode-status?qrcode=xxx` | GET | 轮询扫码状态 |
| `/wechat/status` | GET | 查看当前用户的登录/运行状态 |
| `/wechat/start` | POST | 手动启动当前用户的消息轮询 |
| `/wechat/stop` | POST | 停止当前用户的消息轮询 |
| `/wechat/sessions` | GET | 列出当前用户的微信 Bot 会话列表 |
| `/wechat/sessions/{id}` | GET | 获取当前用户的微信会话消息详情 |
每个用户的 token 存储在独立目录 `~/.desktop_agent/wechat_{user_id}/` 下，互不干扰。服务重启后，所有已登录用户的 Bot 自动恢复轮询。
### 注意事项
- 首次使用必须先扫码登录（一次即可，Token 持久化）
- Agent 处理消息需要一定时间（通常 30-60 秒），处理期间微信会显示"对方正在输入..."
- 目前只支持 1 对 1 私聊，不支持群消息
- 腾讯保留控制权，可能会限速或调整策略
---
⬆ 返回目录
## 数据库交互
Moss Agent 内置 `dbcli` 数据库交互系统，让 Agent 可以直接用自然语言与数据库对话。
### 架构
```
用户 ═▶ Agent ═▶ database_tool（Agent 工具）
│
dbcli 核心库
┌─ auth.py —— 列级/行级权限控制
├─ connection.py —— SQLAlchemy 连接池
├─ query.py —— SQL 执行与结果格式化
└─ schema.py —— 表结构自省
│
┌──────────┼──────────┐
SQLite PostgreSQL MySQL
```
### 使用方法
在设置弹窗的「数据库」面板中添加/测试/保存连接，然后 Agent 就能直接查询：
```
用户：帮我查一下 orders 表里上周的订单
Agent：先调用 db_schema 查看 orders 表结构，再生成 SQL 查询并返回结果
```
### 命令行
```bash
cd agent_core
python -m dbcli.cli query "SELECT count(*) FROM users" --conn prod_db
python -m dbcli.cli schema --conn prod_db --table orders
python -m dbcli.cli connect list
python -m dbcli.cli connect test my_db
```
### 权限控制
数据库面板默认开启只读模式，更细粒度的权限在 `~/.desktop_agent/dbcli/permissions.yaml` 中配置：
```yaml
roles:
analyst:
databases:
prod_db:
- table: orders
columns_allow: [id, amount, status, created_at] # 列级白名单
row_filter: "dept_id = {{user.dept_id}}" # 行级过滤
allow_write: false
max_rows: 200
```
### 配置文件
- 数据库连接：`~/.desktop_agent/dbcli/connections.yaml`
- 权限规则：`~/.desktop_agent/dbcli/permissions.yaml`
---
⬆ 返回目录
## 远程部署
### Docker（推荐）
```bash
git clone https://gitee.com/mingwuda/desktop-agent.git
cd desktop-agent
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API Key 和用户密码
vim .env
```
`.env` 示例：
```bash
# 模型配置
LLM_API_KEY=sk-your-api-key-here
LLM_MODEL=gpt-4o
LLM_BASE_URL=
LLM_PROVIDER=openai
# 用户管理（多个用户用 ; 分隔，格式 user:password;user2:password2）
AGENT_USERS=admin:your-strong-password;guest:guest123
# 可选
# AGENT_CONTEXT_WINDOW=128000
# AGENT_RECURSION_LIMIT=60
```
启动：
```bash
docker compose up -d --build
```
访问 `http://<服务器IP>:8080`，首次启动自动创建默认用户。配置、会话数据和工作区文件保存在 Docker volumes 中，重启不丢失。
```bash
# 查看日志
docker compose logs -f agent
# 停止
docker compose down
# 数据备份
docker run --rm -v desktop-agent_agent_data:/data -v $(pwd):/backup alpine cp -r /data /backup/agent_data_backup
```
### systemd 部署
示例部署到 `/opt/desktop-agent`，监听 `8080`：
```bash
git clone https://gitee.com/mingwuda/desktop-agent.git /opt/desktop-agent
cd /opt/desktop-agent
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements.txt
```
systemd 示例：
```ini
[Unit]
Description=Moss Agent
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
# 安装路径从环境变量读取，未配置时使用下方默认值（${VAR:-默认值}）。
# 两种覆盖方式任选其一：
# 方式 A（推荐）：把变量写进 /etc/default/desktop-agent，本 unit 自动加载
# echo 'DA_HOME=/srv/desktop-agent' > /etc/default/desktop-agent
# echo 'DA_PYTHON=/srv/desktop-agent/.venv/bin/python' >> /etc/default/desktop-agent
# 方式 B：直接在下方用 Environment= 改默认值
EnvironmentFile=-/etc/default/desktop-agent
WorkingDirectory=${DA_HOME:-/opt/desktop-agent}
ExecStart=${DA_PYTHON:-/opt/desktop-agent/.venv/bin/python} agent_core/main.py
# 崩溃自动拉起，比 nohup 更稳；守护进程（guardian）也依赖此 unit 名做 Restart
Restart=always
RestartSec=5
# 配置开关在此注入（按需取消注释；不配置则按 config.yaml / 默认值）
# Environment=AGENT_SELF_EVOLUTION=1
# Environment=AGENT_SELF_HEALING=1
# Environment=AGENT_SELF_HEALING_INTERVAL=600
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
Guardian 守护进程 unit（可选，用于 boot 自愈 + 健康巡检）：
```ini
[Unit]
Description=Desktop Agent 守护进程（控制面：巡检与自愈编排）
# 依赖主服务先起来；主服务挂了由它自己的 unit 拉起，本单元只管守护进程自身
After=network.target desktop-agent.service
Wants=desktop-agent.service
[Service]
Type=simple
# 运行时参数（含健康探针 URL、重启命令）从 /etc/default/desktop-agent-guardian 读取
EnvironmentFile=-/etc/default/desktop-agent-guardian
# WorkingDirectory 必须是仓库根：python -m agent_core.xxx 靠 cwd 加入 sys.path 才能找到 agent_core 包
WorkingDirectory=/opt/desktop-agent
ExecStart=/opt/desktop-agent/.venv/bin/python -m agent_core.guardian_daemon
# 恢复时执行的重启命令（值含空格必须加引号）；主服务用 systemd 管理
Environment="SELF_HEAL_RESTART_CMD=systemctl restart desktop-agent"
# 健康探针默认 http://127.0.0.1:8899/health，可在 /etc/default/desktop-agent-guardian 覆盖
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
启动：
```bash
systemctl daemon-reload
systemctl enable desktop-agent
systemctl enable desktop-agent-guardian
systemctl restart desktop-agent desktop-agent-guardian
systemctl status desktop-agent desktop-agent-guardian
```
查看日志：
```bash
journalctl -u desktop-agent -f
journalctl -u desktop-agent-guardian -f
```
公网部署建议放在 HTTPS 反向代理后，并设置强密码和固定 `DESKTOP_AGENT_AUTH_SECRET`。
---
⬆ 返回目录
## 系统守护与自愈
Moss Agent 提供 Guardian 守护进程，实现 boot 自愈、健康巡检和崩溃自动重启。采用**双进程双 unit** 架构：
- `desktop-agent.service`：主服务 unit，负责运行 FastAPI 后端
- `desktop-agent-guardian.service`：守护进程 unit，负责健康巡检与自愈编排
### 架构
```text
systemd
├─ desktop-agent.service (主服务)
│ └─ agent_core/main.py
└─ desktop-agent-guardian.service (守护进程)
└─ agent_core/guardian_daemon.py
├─ 定期探活 /health
├─ 检测到异常时执行 SELF_HEAL_RESTART_CMD
└─ 启动时自检常见问题并修复
```
### 核心特性
- **Boot 自愈**：服务启动时自动检测并修复常见问题
- **健康巡检**：定期访问主服务 `/health` 接口，确认服务存活
- **崩溃自动重启**：主服务异常退出后，由 systemd 自动拉起；守护进程可执行额外重启命令
- **配置外置**：健康探针 URL、重启命令等通过 `/etc/default/desktop-agent-guardian` 覆盖，无需修改 unit 文件
- **双 unit 协作**：主服务 unit 负责自身 `Restart=always`，守护进程 unit 负责更高层级的巡检与编排
### 配置覆盖
在 `/etc/default/desktop-agent-guardian` 中可覆盖：
```bash
# 健康探针 URL（默认 http://127.0.0.1:8899/health）
SELF_HEAL_HEALTH_URL=http://127.0.0.1:8080/health
# 自愈重启命令（默认 systemctl restart desktop-agent）
SELF_HEAL_RESTART_CMD="systemctl restart desktop-agent"
```
主服务路径配置写在 `/etc/default/desktop-agent`：
```bash
DA_HOME=/srv/desktop-agent
DA_PYTHON=/srv/desktop-agent/.venv/bin/python
```
### 管理命令
```bash
# 查看主服务状态
systemctl status desktop-agent
# 查看守护进程状态
systemctl status desktop-agent-guardian
# 重启主服务
systemctl restart desktop-agent
# 重启守护进程
systemctl restart desktop-agent-guardian
# 查看主服务日志
journalctl -u desktop-agent -f
# 查看守护进程日志
journalctl -u desktop-agent-guardian -f
```
---
⬆ 返回目录
## Windows 打包
Windows 桌面版**统一以 Electron 安装包形式分发**（双击安装、无浏览器、不暴露端口）。PyInstaller 构建出的后端目录只作为 Electron 打包的内部输入，不再单独对外分发。
底层后端构建（供 Electron 打包消费，不直接分发）：
```cmd
packaging\windows\build.cmd
```
或：
```powershell
powershell -ExecutionPolicy Bypass -File .\packaging\windows\build.ps1
```
输出：
```text
dist\windows\DesktopAgent-Windows\ # 自包含后端目录（被 electron-builder 收进安装包）
```
### Electron 桌面应用（唯一桌面交付形态）
如果你希望用户像使用原生桌面软件一样——**双击安装、无浏览器、不暴露本地端口**，可用 Electron 把同一套后端与前端包装成原生窗口：
```cmd
packaging\windows\build-electron.cmd
```
后端构建默认**自动探测**：若 `dist\windows\DesktopAgent-Windows\DesktopAgent.exe` 已存在则跳过后端重建、直接重新打包；产物缺失时自动先构建后端。
可选参数：
- `--rebuild-backend`：即使后端产物已存在，也强制重新构建后端后再打包。
输出：
```text
dist\electron\MossAgent-Setup-0.1.1.exe # NSIS 安装包
```
安装包内置 Electron 运行时、Python 后端（含 Playwright Chromium）。用户双击安装后从桌面/开始菜单快捷方式启动，首次启动自动拉起后端并加载窗口，**全程不出现浏览器、不显示端口、无需联网下载任何东西**。
> 说明：Electron 窗口壳通过 `main.py` 的随机端口能力（`AGENT_PORT=0`，监听地址打印为 `AGENT_LISTEN_URL=` 一行供解析）加载后端，前端代码零改动。浏览器开发形态（`python main.py` / `start.sh`）仍保留用于本地调试，但**非用户交付**；Windows 桌面端唯一对外交付形态为上面的 Electron 安装包，早期的解压版 `Start Moss Agent.bat` 已停止分发。
#### macOS 打包（Electron 桌面应用）
同样用 Electron 把同一套后端与前端包装成 macOS 原生窗口应用。**打包必须在 macOS 机器上完成**——electron-builder 需要系统的 `codesign` / `ditto`，且 PyInstaller 不支持交叉编译（无法在 Windows 上打出 macOS 二进制）。
后端构建（PyInstaller，产出 `dist/macos/DesktopAgent-macOS/`）：
```bash
bash packaging/macos/build.sh
```
一键打包成 dmg（默认 Apple Silicon / arm64，适配 M 系列 Mac）：
```bash
bash packaging/macos/build-electron-mac.sh
```
后端构建默认**自动探测**：若 `dist/macos/DesktopAgent-macOS/DesktopAgent` 已存在则跳过后端重建、直接重新打包；产物缺失时自动先构建后端。
可选参数：
- `--rebuild-backend`：即使后端产物已存在，也强制重新构建后端后再打包。
- `--x64`：打包 Intel 版（x86_64）。
- `--universal`：打包通用二进制（同时含 arm64 与 x86_64）。
输出（取决于架构参数）：
```text
dist/electron/Moss Agent-0.1.1-arm64.dmg # Apple Silicon 安装镜像（默认）
dist/electron/Moss Agent-0.1.1-x64.dmg # Intel 安装镜像
dist/electron/Moss Agent-0.1.1.dmg # 通用安装镜像（--universal）
```
> 代码签名：未签名的 dmg 在其它 Mac 上会被 Gatekeeper 拦截（"无法验证开发者"）。如需对外分发，请在 `electron/package.json` 的 `mac.identity` 填入 Apple 开发者证书、并配置 `afterSign` / `notarize` 后重跑脚本。开发自用可在「系统设置 → 隐私与安全性」中手动允许。
> 说明：macOS 与 Windows 共用同一套 `electron/` 桌面壳——`main.js` 已跨平台识别后端产物（Windows 的 `DesktopAgent.exe` 与 macOS 的 `DesktopAgent`），前端 / 后端代码均无需改动。
依赖排查：
```cmd
packaging\windows\verify-venv.cmd
packaging\windows\verify-venv.cmd run
```
内网 PyPI：
```cmd
set DESKTOP_AGENT_PIP_INDEX_URL=http://your-internal-pypi/simple/
set DESKTOP_AGENT_PIP_TRUSTED_HOST=your-internal-pypi-host
```
---
⬆ 返回目录
## 项目结构
```text
moss-agent/
├── agent_core/
│ ├── main.py # FastAPI 入口、middleware、Agent 生命周期
│ ├── agent.py # DesktopAgent、LangGraph、流式事件、上下文处理
│ ├── config.py # Provider、模型、环境变量和配置持久化
│ ├── context_manager.py # 上下文估算、阈值和压缩
│ ├── subagents.py # coder/reviewer/debugger/searcher 子代理 + 并行支持
│ ├── case_forge.py # Case→Skill 离线蒸馏（自进化闭环）
│ ├── plugin_loader.py # 插件加载器（参数变更热重载）
│ ├── session_store.py # SQLite 会话存储（按用户隔离）
│ ├── user_manager.py # 多用户数据目录管理
│ ├── cron_service.py # 定时任务调度服务
│ ├── api/ # API 路由模块
│ │ ├── deps.py # 认证依赖（get_current_user、require_admin）
│ │ ├── auth.py # 登录/登出/修改密码路由
│ │ └── routes/
│ │ ├── agent.py # /run、/run/stream 路由
│ │ ├── sessions.py # 会话 CRUD（Web + 微信独立命名空间）
│ │ ├── skills.py # Skills 列表与热加载
│ │ ├── artifacts.py # 文件制品下载与预览
│ │ ├── files.py # 文件浏览、读取、Diff、提交、推送
│ │ ├── db.py # 数据库连接管理
│ │ ├── system.py # 设置与用户管理
│ │ ├── wechat.py # 微信 Bot 管理端点
│ │ └── monitoring.py # 用量统计与健康检查
│ ├── services/
│ │ ├── workspace.py # 工作区与 ZIP 解压工具
│ │ └── agent_service.py # Agent 调用封装
│ ├── network_resolver.py # DNS 兜底解析
│ ├── dbcli/ # 数据库交互核心库
│ │ ├── auth.py # 列级/行级权限引擎
│ │ ├── connection.py # SQLAlchemy 连接池
│ │ ├── query.py # SQL 执行与结果格式化
│ │ ├── schema.py # 表结构自省
│ │ ├── config.py # 连接与权限配置管理
│ │ ├── cli.py # Click 命令行工具
│ │ └── permissions.yaml # 权限规则模板
│ ├── memory/
│ │ └── local_memory.py # 长期记忆
│ ├── monitoring/
│ │ └── usage_tracker.py # 用量统计
│ ├── skills/
│ │ ├── loader.py # SKILL.md 解析（支持 YAML frontmatter）
│ │ └── registry.py # SkillRegistry 技能注册表
│ ├── samples/ # 示例技能
│ └── tools/
│ ├── file_tools.py # 文件工具（含工作区外授权机制）
│ ├── code_tools.py # Python 执行
│ ├── shell_tools.py # Shell 命令执行（跨平台，安全拦截）
│ ├── git_tools.py # Git 工具（含白名单安全验证）
│ ├── web_tools.py # 搜索和网页抓取
│ ├── browser_tools.py # 浏览器自动化 + 验证码识别（Playwright，截图 token URL）
│ ├── memory_tools.py # 记忆工具
│ ├── system_tools.py # 系统信息和 Skills 列表
│ ├── database_tool.py # 数据库交互工具（db_schema, db_query, db_connections）
│ └── todo_tools.py # Todo 清单任务分解与进度跟踪
├── desktop/
│ └── index.html # 单页前端（已拆分为 js/styles/libs 子目录）
├── skills/ # 项目内 Skills（9 个 oh-my-openagent + 5 个 Superpowers）
├── electron/ # Electron 桌面壳（跨平台：main.js / package.json / loading.html）
├── packaging/windows/ # Windows 打包脚本（build.cmd / build-electron.cmd）
├── packaging/macos/ # macOS 打包脚本（build.sh / build-electron-mac.sh）
├── start.sh
├── start.cmd
├── generate_login_url.py
└── requirements.txt
```
---
⬆ 返回目录
## 技术栈
| 层面 | 技术 |
| --- | --- |
| Agent | LangGraph ReAct Agent |
| LLM 接口 | LangChain OpenAI / Anthropic，兼容 OpenAI 风格接口 |
| 后端 | FastAPI + Uvicorn |
| 前端 | 原生 HTML/CSS/JS + marked.js + highlight.js |
| 状态 | LangGraph MemorySaver + SQLite |
| 认证 | HttpOnly Cookie + HMAC 签名 |
| 运行时 | Python 3.13+ |
---
⬆ 返回目录
## 安全边界
- 工具默认限制在当前用户工作区内，编辑工作区外文件需显式授权（点击「授权写入」按钮或设置会话工作目录）。
- 文件下载和预览只能访问当前用户工作区内的文件。
- Git 高风险命令默认不开放。
- Shell 命令禁止提权、格式化磁盘、fork bomb 等危险操作。
- 图片不会持久化保存到历史数据库。
- 长期记忆需要用户明确要求才写入，超过 10 天自动清理。
- 多用户微信 Bot token 按用户隔离存储，互不干扰。
- 公网部署必须配置强密码、固定密钥和 HTTPS。
## API
启动后访问：
```text
http://127.0.0.1:8899/docs
```
主要接口：
| 端点 | 方法 | 说明 |
| --- | --- | --- |
| `/` | GET | 桌面 UI |
| `/login` | GET | 登录页 |
| `/auth/login` | POST | 登录 |
| `/auth/logout` | POST | 退出 |
| `/auth/token-login` | GET | 短期 Token 登录 |
| `/run` | POST | 非流式执行 |
| `/run/stream` | POST | SSE 流式执行 |
| `/sessions` | GET/POST | 列出或创建会话 |
| `/sessions/{id}` | GET/DELETE | 获取或删除会话 |
| `/sessions/{id}/rename` | PUT | 重命名会话 |
| `/sessions/{id}/workspace` | GET/PUT | 获取或设置会话工作目录 |
| `/permissions/grant-path` | POST | 授权工作区外路径写入 |
| `/permissions/granted-paths` | GET | 查看已授权的路径列表 |
| `/skills` | GET | 列出 Skills |
| `/skills/reload` | POST | 热加载 Skills |
| `/subagents` | GET | 列出子代理类型 |
| `/subagents/tasks/{id}` | GET | 查询子代理任务 |
| `/memories` | GET/POST | 查询或保存长期记忆 |
| `/memories/{key}` | DELETE | 删除长期记忆 |
| `/artifacts/download` | GET | 下载工作区文件制品 |
| `/artifacts/preview` | GET | 预览 Markdown 制品 |
| `/settings` | GET/POST | 读取或保存配置 |
| `/usage` | GET | 今日用量 |
| `/usage/session` | GET | 会话用量 |
| `/usage/history` | GET | 历史用量 |
| `/users` | GET/POST | 管理用户 |
| `/users/{user_id}` | DELETE | 删除用户 |
| `/users/me` | GET | 当前登录用户 |
| `/users/me` | GET | 当前登录用户 |
| `/db/connections` | GET/POST | 列出或添加数据库连接 |
| `/db/connections/{name}` | DELETE | 删除数据库连接 |
| `/db/connections/{name}/test` | POST | 测试已保存连接 |
| `/db/test-connection` | POST | 测试未保存连接（表单预测试） |
| `/db/permissions` | GET/PUT | 读写权限配置 |
| `/db/query` | POST | 执行 SQL 查询（含权限检查） |
| `/db/schema/{connection_name}` | GET | 获取数据库表结构 |
| `/wechat/qrcode` | GET | 微信扫码登录页 |
| `/wechat/status` | GET | 微信 Bot 状态 |
| `/wechat/start` | POST | 启动微信轮询 |
| `/wechat/stop` | POST | 停止微信轮询 |
| `/wechat/sessions` | GET | 微信会话列表 |
| `/wechat/sessions/{id}` | GET | 微信会话消息 |
| `/plugins` | GET | 列出已加载插件 |
| `/plugins/{name}/toggle` | POST | 启用/禁用插件 |
| `/cron` | GET/POST | 列出所有定时任务 / 创建 |
| `/cron/{task_id}` | PUT/DELETE | 更新 / 删除定时任务 |
| `/cron/parse` | POST | 解析 cron 表达式 |
| `/cron/{task_id}/run` | POST | 手动立即执行定时任务 |
| `/projects/{project_id}/cron` | GET | 列出某项目的定时任务 |
| `/skills/pending` | GET | 列出待审批技能候选 |
| `/skills/pending/approve` | POST | 批准候选技能生效（body 含 `name`） |
| `/skills/pending/reject` | POST | 拒绝候选技能（body 含 `name`） |
| `/health` | GET | 健康检查 |
除登录、退出、Token 登录和健康检查外，其它 API 都需要登录。
---
⬆ 返回目录