# localBot **Repository Path**: ereddate2017/local-bot ## Basic Information - **Project Name**: localBot - **Description**: LocalBot 是一个开源的功能完整的AI智能助手系统,提供Web界面、多模型支持、会话管理、工具调用、长记忆、联网搜索等核心功能。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-02-17 - **Last Updated**: 2026-11-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # LocalBot 一个可操控本机的本地 AI Agent。核心能力是**像人一样操作电脑**——用鼠标、键盘、窗口与界面元素控制真实桌面应用,同时具备文件读写、命令执行、联网搜索、定时任务与多 Agent 协作。提供 Web 界面、HTTP API、WebSocket 与命令行四种使用方式。 ## 特性 - **真实操作本机**:`exec` 执行命令、文件工具读写任意路径;`mouse` / `keyboard` / `ui` / `window` 等工具直接操作真实桌面(点按钮、填表单、操作桌面软件) - **原生 Function Calling**:工具以标准 OpenAI `tools` schema 下发,模型返回 `tool_calls` 后自动执行并回传结果,支持多轮链式调用(默认最多 60 轮,只读工具自动并发) - **长任务不丢上下文**:历史超出 token 预算时,早期轮次会被自动摘要成一段再继续(而不是直接丢弃),用户目标、已确认事实、产物路径与待办都会保留 - **子 Agent 独立上下文**:`task` 工具可派生一个独立上下文的子 Agent 去探索/读文件/调研,只把结论摘要带回主对话,避免中间过程撑爆上下文 - **多模型支持**:DeepSeek(推荐)、OpenAI、Anthropic、Ollama - **50 个内置工具**:桌面操作、文件(含回滚与代码索引)、命令、搜索、浏览器、记忆、定时与监控、技能、Agent 管理、子任务,并可通过 MCP 动态扩展 - **多种接入方式**:Web 界面、REST API、流式 SSE、WebSocket、CLI - **会话与长记忆**:按会话保存历史与记忆文件,支持会话派生与互通;`memory/user_profile.md` 保存跨会话的用户偏好与项目约定 ## 快速开始 ### 前置要求 - Node.js 18+ - Python 3.7+(仅外部 Python 工具需要) - npm ### 1. 安装依赖 ```bash npm install ``` 如需使用外部 Python 工具(archive / calculator / database / email / markdown-generator / summarize): ```bash # Windows:双击运行 install-python-deps.bat # 或手动安装 pip install -r tools/requirements.txt # 国内镜像源 pip install -r tools/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### 2. 配置环境变量 复制 `.env.example` 为 `.env`: ```bash cp .env.example .env ``` 最少需要填写一个模型 API Key,推荐使用 DeepSeek: ```ini localbot_DEFAULT_PROVIDER=deepseek localbot_DEFAULT_MODEL=deepseek-chat DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 DEEPSEEK_MODELS=deepseek-chat,deepseek-reasoner ``` > `.env` 已加入 `.gitignore`,不会进入版本库。`.env.example` 中保留的都是占位符,填写真实 Key 后请勿提交。 ### 3. 启动服务 ```bash npm start ``` 启动后访问 http://localhost:18789 。 ## 模型配置 | Provider | 环境变量 | 说明 | |----------|----------|------| | `local` | `localbot_LOCAL_MODEL_ENABLED`、`localbot_LOCAL_MODEL_BASE_URL`、`localbot_LOCAL_MODEL_NAME` | **默认**,项目内 `qwen_model`,由 `tools/local_model_server.py` 提供 OpenAI 兼容接口 | | `deepseek` | `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL`、`DEEPSEEK_MODELS` | OpenAI 兼容协议 | | `openai` | `OPENAI_API_KEY`、`OPENAI_BASE_URL` | OpenAI 兼容协议 | | `anthropic` | `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL` | 原生协议 | | `ollama` | `OLLAMA_ENABLED=true`、`OLLAMA_BASE_URL`、`OLLAMA_MODELS` | 本地模型,需显式开启 | 未填写有效 Key 的 Provider 不会被注册,服务启动日志会打印 `Available providers`。查询当前可用模型: ```bash curl http://localhost:18789/api/models ``` ### 本地模型(默认) 项目内的 `E:\work\202611010935\qwen_model`(Qwen2-1.5B-Instruct,HuggingFace safetensors)通过 `tools/local_model_server.py` 以 OpenAI 兼容接口提供服务,默认端口 **8090**: ```bash npm run local-model # 等价于 python tools/local_model_server.py ``` 然后在另一个终端启动应用: ```bash npm start ``` `.env` 中相关配置: ```ini localbot_LOCAL_MODEL_ENABLED=true localbot_DEFAULT_PROVIDER=local localbot_LOCAL_MODEL_BASE_URL=http://127.0.0.1:8090/v1 localbot_LOCAL_MODEL_NAME=qwen-local localbot_LOCAL_MODEL_TIMEOUT_MS=300000 ``` 服务端可用变量:`LOCAL_MODEL_DIR`、`LOCAL_MODEL_PORT`、`LOCAL_MODEL_DEVICE`(cpu / cuda / auto)、`LOCAL_MODEL_THREADS`、`LOCAL_MODEL_MAX_TOKENS`(默认 512,CPU 推理慢,会限制单次生成长度)。 说明: - 模型权重目录 `qwen_model/` 已加入 `.gitignore`,不会进版本库。 - 仅用 CPU 时推理较慢(1.5B、8GB 内存的机器上约 1–2 字/秒),建议把问题拆小;有 GPU 时设 `LOCAL_MODEL_DEVICE=cuda` 会快很多。 - 小模型对工具调用的准确度有限:服务端把工具目录写进系统提示,模型输出 `{"tool": "...", "arguments": {...}}` 时会被转换成标准 `tool_calls`。需要更强的工具调用能力时,把 `localbot_DEFAULT_PROVIDER` 切回 `deepseek` 即可。 - 不想启动本地服务时:`localbot_LOCAL_MODEL_ENABLED=false`。 ## 使用方式 ### Web 界面 ``` http://localhost:18789 ``` 界面包含:聊天(WebSocket 流式)、会话管理(含会话记忆查看)、可用工具(可手动执行)、权限策略切换、模型切换、系统日志、定时任务(创建 / 监控任务 / 取消 / 执行历史)、扩展管理(技能 / 子 Agent / 沙箱状态)、下载中心,以及高危操作的审批弹窗。每轮对话结束后会显示本轮累计 token、耗时与工具调用次数。 ### REST API ```bash # 单轮对话(内部自动完成多轮工具调用) curl -X POST http://localhost:18789/api/agent \ -H "Content-Type: application/json" \ -d '{"message":"在 e:\\work 下创建一个 hello.txt,内容为 world"}' # 流式对话(SSE,逐 token 返回) curl -X POST http://localhost:18789/api/agent/stream \ -H "Content-Type: application/json" \ -d '{"message":"列出当前目录下的 js 文件"}' ``` > Windows 下使用 PowerShell 请求时,建议用 `[System.Text.Encoding]::UTF8.GetBytes($json)` 编码请求体,避免中文乱码。 ### WebSocket 连接 `ws://localhost:18789`,发送: ```json { "type": "agent_stream", "message": "你的问题" } ``` 接收 `agent_stream_chunk`(增量内容)、`agent_stream_done`(最终结果)、`agent_stream_error`(错误)。 ### 命令行 ```bash npm run chat-cli # 通过 WebSocket 连接网关的交互式聊天 ``` 内置斜杠命令与断线自动重连,详见 [CHAT_CLI_EXAMPLES.md](CHAT_CLI_EXAMPLES.md)。 回复是流式输出的,工具调用会实时打印在中间,不用等整轮跑完: ``` Assistant: 我先查一下当前的电源和睡眠设置 → exec {"command":"powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE"} ✓ exec 312ms 当前交流电源设置索引: 0x00000258 · 第 2 轮 Assistant: 当前休眠超时是 600 秒,也就是 10 分钟... ``` `→` 是正在调用的工具和参数(截断到 160 字符),`✓` / `✗` 是执行结果、耗时与一句话摘要,`· 第 N 轮` 表示模型又进行了一轮工具调用。事件同样通过 `agent_event` 推给网页端。 ## 内置工具 ### 桌面操作 像人一样操作图形界面,适合 shell 做不到的 GUI 场景(点按钮、填表单、操作桌面软件)。这组工具默认保留但**不主动使用**:有命令实现的任务一律走 `exec`,只有用户明确要求“在屏幕上操作”、或目标程序确实没有命令行入口时才会用到鼠标键盘。 | 工具 | 说明 | |------|------| | `mouse` | 移动、点击、双击、右键、拖拽、滚轮、查询光标坐标 | | `keyboard` | 输入文本(支持中文,走剪贴板粘贴)、按单键、组合键(如 `ctrl+s`) | | `screen` | 截屏保存 PNG(支持区域)、获取屏幕分辨率 | | `window` | 列举、激活、最小化、最大化、还原、关闭窗口;查询前台窗口 | | `ui` | 读取界面元素树(Windows 用 UI Automation,macOS 用 Accessibility),返回按钮/输入框的名称、类型与屏幕坐标 | | `clipboard` | 读写系统剪贴板 | 推荐流程:`window list` → `window activate` → `ui snapshot`(拿到控件坐标)→ `mouse` / `keyboard` 操作 → 再 `ui snapshot` 验证。 ### 平台支持 | 系统 | 驱动 | |------|------| | Windows | PowerShell + Win32 / UI Automation | | macOS | osascript(JXA)+ CoreGraphics / Accessibility,截屏走 `screencapture`,剪贴板走 `pbcopy` / `pbpaste` | | Linux | 不做桌面驱动,调用时直接报错,请改用 `exec` | macOS 首次使用前,到「系统设置 → 隐私与安全性」给运行本程序的终端 / IDE 授权: - **辅助功能**:鼠标、键盘、窗口控制、`ui snapshot` - **屏幕录制**:`screen capture` - **自动化**:允许控制 System Events(首次调用会弹窗) 授权后要重启进程才生效。macOS 上组合键用 `cmd`(`cmd+s`、`cmd+tab`),Windows 用 `ctrl`。`ui action=children`(子窗口枚举,专治任务计划程序这类 MMC 界面)只有 Windows 有,macOS 用 `ui action=snapshot` 读 Accessibility 树。 ### 操作手感(需要时像人) 日常任务默认用命令完成,只有需要上屏操作时才走鼠标键盘——此时动画依然保留:光标不是瞬移,而是沿三次贝塞尔曲线移动(EaseInOutCubic 缓动 + 轻微随机弧线,按距离 180–620ms),点击和拖拽前都会先把光标滑过去;输入中文时分段粘贴,每段之间 45–140ms 随机停顿。所以一旦上屏,能看到完整的操作过程。 | 变量 | 默认 | 说明 | |------|------|------| | `localbot_GUI_ANIMATION` | true | 设为 false 则光标瞬移、文本一次性粘贴 | | `localbot_GUI_SPEED` | normal | `slow` / `normal` / `fast` 调节动画时长倍率 | 工具参数也可临时覆盖:`mouse` 的 `smooth`(默认 true)与 `duration`(毫秒),`keyboard` 的 `humanize`(默认 true)。文本超过 400 字符时会自动退回一次性粘贴,避免长文本逐段输入过慢。 安全约定:输入前用 `window foreground` 确认前台是目标窗口;关闭应用用 `window close`(会触发保存提示),不要 `taskkill /F` 强杀可能含未保存内容的程序。 ### 长任务与睡眠 系统默认 10 分钟无操作就睡眠(本项目所在机器实测 600 秒),带工具调用的长任务会被直接打断。Agent 在每个任务开始时会自动占住「系统不休眠 + 屏幕常亮」,任务结束(包括异常退出)立即释放;嵌套的子 Agent、定时任务共用同一个计数,全部结束才真正放开。 | 系统 | 实现 | |------|------| | Windows | `SetThreadExecutionState(ES_CONTINUOUS \| ES_SYSTEM_REQUIRED \| ES_DISPLAY_REQUIRED)`,休眠和关屏都挡 | | macOS | `caffeinate -d -i -w `(`-d` 挡关屏、`-i` 挡休眠),随本进程退出自动结束 | `localbot_PREVENT_SLEEP=false` 可关闭这个行为。 ### 文件操作 | 工具 | 说明 | |------|------| | `read` | 读取文件内容(支持 `offset`/`limit` 分页) | | `write` | 写入 / 创建文件 | | `edit` | 原地替换文件中的指定字符串 | | `list_dir` | 列出目录内容 | | `glob` | 按通配模式查找文件 | | `grep` | 按正则搜索文件内容 | | `code_search` | 代码索引检索:按符号名或路径定位 function / class / type 定义(首次自动建索引,存 `.localbot/index.json`) | | `move` / `copy` / `delete` | 移动、复制、删除文件 | | `undo` | 查看最近的修改快照,或回滚到修改前(`action=list` / `action=restore`) | > 每次 `write` / `edit` / `delete` / `move` 之前都会自动保存快照到 `.localbot/checkpoints`(最多 50 条、单文件 5MB 上限),所以误改后可以直接让 Agent 用 `undo` 回滚,或手动执行 `undo action=restore`。 **文件放置规则**:只写文件名(如 `todo.md`)时自动落到项目下的 `outputs/`,不会污染仓库根目录;写 `src/xxx.js` 这类带目录的路径则按项目根解析。生成物、临时脚本、缓存分别归到 `outputs/`、系统临时目录、`.localbot/`,`outputs/` 已加入 `.gitignore`。 **路径校验**:读写前会检查盘符是否存在、是否含 Windows 非法字符、父级是否被文件占用、是否把目录当文件;写入时若父目录不存在且名字像「漏了分隔符」(如 `202611010935reports`),会直接拒绝并给出推测的正确路径。 ### 命令执行 | 工具 | 说明 | |------|------| | `exec` | 在本机执行 shell 命令,默认 60s 超时、10MB 输出上限,支持指定 `cwd` | `exec` 会先确定用哪个 shell 再执行,结果里回报实际使用的 shell: | 平台 | 默认 | 可选 `shell` | |------|------|--------------| | Windows | `cmd` | `cmd`、`powershell`、`pwsh` | | macOS / Linux | `bash` | `bash`、`sh`、`zsh`(装了 `pwsh` 也能用) | 写 PowerShell 语法时必须显式传 `shell=powershell`,否则会按 cmd 解析失败。命令找不到时结果会附带 `hint`,提示换哪个 shell 或改用对应语法。 ### 搜索与浏览器 | 工具 | 说明 | |------|------| | `web_search` | 联网搜索 | | `browser` | 基于 Playwright 打开网页并提取内容;`open` 支持 `includeText`(一次调用直接取正文)与 `waitMs`(等待异步渲染),`close` 关闭浏览器 | ### 系统与实用 | 工具 | 说明 | |------|------| | `time` / `calculate` / `random` / `env` | 时间、计算、随机数、环境变量 | | `create_download_file` | 生成可下载文件 | ### 记忆 | 工具 | 说明 | |------|------| | `memory_write` / `memory_read` / `memory_append` / `memory_list` | 按会话写入、读取、追加、列举记忆 | | `memory_remember` / `memory_forget` | 跨会话记忆:写入/按关键词删除用户偏好、背景与项目约定 | 跨会话记忆存在 `memory/user_profile.md`,不属于任何会话,每轮对话都会拼进系统提示,所以换会话、重开进程后依然生效: - 自动:当你说到长期有效的偏好(语言、系统、技术栈、命名规范、不要动的目录),模型会调用 `memory_remember` 记一条;说「忘掉 xxx」时调用 `memory_forget` 删掉对应条目。 - 手动:直接编辑 `memory/user_profile.md`,一行一条即可;该文件已加入 `.gitignore`。 - 只用于长期事实,密钥、令牌和一次性任务细节不写入。 ### 会话与子任务 | 工具 | 说明 | |------|------| | `sessions_list` / `sessions_history` | 列举本 Agent 的真实会话、查看某个会话的历史消息 | | `sessions_send` | 向另一个会话发送消息并等待回复(会完整跑一轮 Agent) | | `sessions_spawn` | 创建一个空会话,可指定 `system_prompt` | | `task` | 派生子 Agent 在**独立上下文**中完成一项自包含任务,只返回结论摘要。可传 `tools` 限定它可用的工具 | > `task` 与 `sessions_*` 的区别:前者是一次性、隔离的子任务(不写长记忆、不污染主上下文),后者是长期存在的会话。子 Agent 默认不允许再派生下一层(最多 2 层)与操作其它会话。 ### 定时任务 | 工具 | 说明 | |------|------| | `cron_schedule` / `cron_list` / `cron_cancel` / `cron_validate` | 创建、列举、取消、校验 cron 任务 | | `cron_runs` | 查看执行历史:时间、耗时、成功与否、重试次数、回复摘要 | | `monitor_create` | 一次调用同时建「周期采集」与「到点出报告」两个任务 | ### 技能与 Agent 管理 | 工具 | 说明 | |------|------| | `skill_search` | 按关键词搜索可发现的技能(`SKILL.md`):本项目已安装、`~/.localbot/skills`、本机 Trae 插件自带技能、以及配置的远程索引 | | `skill_install` | 安装技能到 `.localbot/skills//`:`path` 传本地技能目录,`url` 传 zip / tar.gz;安装后 Agent 会读其中的 `SKILL.md` 按步骤执行 | | `create_skill` / `list_skills` / `delete_skill` | 技能的创建、列举、删除 | | `create_agent` / `list_agents` / `delete_agent` / `start_agent` / `stop_agent` | 子 Agent 的创建、列举、删除、启停 | 技能目录格式与 Trae / Agent Skills 一致: ``` .localbot/skills/pdf-toolkit/ ├── SKILL.md # --- name / description --- 加正文执行步骤 └── references/ # 可选:参考文件、模板、脚本 ``` Agent 的系统提示里会带上已安装技能的名称、描述与路径,所以遇到匹配的任务会直接读 `SKILL.md`;没有匹配时会自己 `skill_search` → `skill_install` → 读技能执行,不需要你手动指定。`create_skill` 生成的也是同一位置的 `SKILL.md`,建完立刻能被搜索到并写进系统提示。 搜索 → 安装 → 使用是一条真实链路,而不是只列清单: - **搜索**:`skill_search` 扫描本项目 `.localbot/skills`、`~/.localbot/skills`、本机 Trae 插件目录(`~/.trae-cn/plugins`、`~/.trae/plugins`)与远程索​引;没有匹配时再去 GitHub 搜公开技能仓库。本机插件目录通常带 `pdf` / `docx` / `xlsx` / `pptx` / `html-report` 等现成技能。 - **联网搜索**:`localbot_SKILL_GITHUB_SEARCH`(默认开启)会用 `topic:claude-skills`、`topic:agent-skills` 等条件搜 GitHub,并内置了 `anthropics/skills`、`appautomaton/document-SKILLs`、`ComPDFKit/compdf-skills` 三个已知仓库做兜底;结果按关键词命中与星数排序,60 秒缓存以避开未认证限流。配置 `localbot_SKILL_INDEX_URL` 后优先用自定义索引。 - **安装**:`skill_install` 支持本地目录 `path`、任意 zip/tar.gz 的 `url`,也支持 GitHub 仓库或子目录链接(如 `https://github.com/xxx/yyy/tree/main/skills/pdf`)。仓库里有多个 `SKILL.md` 时会列出可选技能名,用 `name` 指定后安装;tar 包用内置解析器解包,符号链接会被跳过(Windows 自带的 bsdtar 遇到符号链接会报错)。 - **自动安装**:当请求涉及 PDF / Word / Excel / PPT / 报告时,Agent 会在开始回答前自动把匹配的技能装进 `.localbot/skills`(整个目录连同 `scripts/` 一起复制),装完立刻出现在系统提示里;同名技能不会重复安装。 - **真实执行**:技能自带的脚本可以直接用 `exec` 运行——把 `cwd` 指到技能目录(或传脚本绝对路径)。`skills/` 目录下的脚本不受「禁止临时脚本」策略限制。 搜索范围可用 `localbot_SKILL_DIRS` 追加(逗号分隔),远程索引通过 `localbot_SKILL_INDEX_URL` 配置(返回 `[{name, description, url}]` 或 `{skills: [...]}` 的 JSON,`url` 指向 zip / tar.gz 技能包)。`.localbot/` 已在 `.gitignore` 中,安装的技能不会进版本库。 ### 外部 Python 工具 位于 `tools/external/`,需安装 `tools/requirements.txt`: - **archive**:压缩包创建 / 解压 / 列举 - **calculator**:数学表达式计算 - **database**:数据库查询,支持 SQLite(单条语句) - **email**:邮箱收发(需自备邮件服务器配置) - **markdown-generator**:Markdown 文档生成 - **summarize**:文本摘要 ### MCP 外部工具 在项目根目录放 `mcp-servers.json`,即可接入任意 MCP server,工具会自动注册为 `mcp__` 并常驻下发: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "e:\\work"] } } } ``` `command`/`args`/`env`/`cwd` 原样传给子进程;单个 server 启动失败只会跳过它,不影响主流程。`localbot_MCP_ENABLED=false` 可整体关闭。 查询当前已注册的工具与状态: ```bash curl http://localhost:18789/api/tools ``` ## 自动化任务实例 一个完整的多步任务:让 Agent 自己上网查数据、写脚本、画图、生成 PDF 并自校验,全程无人工介入。 **任务描述**(原样提交给 `/api/agent`) > 打开浏览器访问百度,搜索抚顺市 2021 年到 2026 年的 GDP 数据(含 2026 年前三季度),然后生成一份中文 PDF 分析报告,保存到 `reports/` 目录。 > 数据必须来自公开统计公报或政府网站;2022 年存在 927.7 亿元与 951.6 亿元两个说法,需核实口径并标注;PDF 至少包含 2 张图表,中文字体用 `simhei.ttf`;生成后用 pypdf 或 pymupdf 校验。 **执行过程**(`/api/agent` 返回的 `stats`) | 指标 | 数值 | |---|---| | 工具调用 | 37 次 | | 模型调用 | 37 次 | | 总耗时 | 151 秒 | | 工具分布 | `exec` 22、`browser` 9、`write`/`edit` 4、`read`/`screen`/`time` 3 | | 结束状态 | `finishReason: stop` | **产物**:`reports/抚顺GDP_agent_v3.pdf`(4 页、262 KB,含 GDP 总量柱状图与增速折线图,正文与图表均使用 SimHei) 报告里每个数字都标注了来源标题与统计口径,并主动处理了两处数据陷阱: - 2023 年公报初步核算 949.3 亿元,五经普后修订为 972.2 亿元,两个值分列、注明修订关系,不混用; - 2022 年另有 951.6 亿元的说法,3 次检索未找到官方公报原文,按任务约定注明"未获官方公报原文确认"后停止检索。 **复现方式** ```bash curl -X POST http://localhost:18789/api/agent \ -H "Content-Type: application/json" \ -d '{"message":"打开浏览器访问百度,搜索抚顺市 2021 年到 2026 年的 GDP 数据(含 2026 年前三季度),生成中文 PDF 报告保存到 reports/ 目录"}' ``` 这个过程同时验证了几个关键能力:浏览器检索、脚本编写与执行、工具结果截断后的多轮续跑、文件检查点,以及 `stats` 提供的用量与耗时统计。 ## 实时监控 「持续盯一个指标,到点给我报告」用一个工具就能建好: ```bash curl -X POST http://localhost:18789/api/tools/execute \ -H "Content-Type: application/json" \ -d '{"toolName":"monitor_create","parameters":{ "name":"price_watch", "target":"https://example.com/prices", "metric":"商品价格", "collectExpression":"*/10 * * * *", "reportAt":"0 18 * * *" }}' ``` 它会同时创建两个任务: - `_collect`:按 `collectExpression` 周期抓取,往 `data/monitor/.jsonl` 追加一行 JSON(含 `ts`、`value`、`raw`) - `_report`:到 `reportAt` 时读取全部记录,统计条数/最新值/极值/异常点,生成 PDF 报告到 `reports/`,执行后自动删除(一次性任务) 查看执行历史: ```bash curl "http://localhost:18789/api/cron/runs?limit=20&taskId=<可选>" ``` 每条记录包含开始时间、耗时、成功与否、重试次数与回复摘要。任务失败会自动重试一次;连续失败 3 次会在 `cron_list` 里标记 `status: failing`。 > cron 在进程内运行,服务需保持启动;重启后任务从 `cron-tasks.json` 恢复。无人值守场景建议保持 `localbot_PERMISSION_MODE=block`,避免 `ask` 模式下等待审批超时。 ## 主要接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/health` | 健康检查 | | GET | `/api/models` | 可用 Provider 与模型 | | GET | `/api/tools` | 已注册工具列表 | | POST | `/api/tools/execute` | 直接执行指定工具 | | GET | `/api/approvals` | 待审批的高危操作 | | POST | `/api/approvals/:id` | 批准或拒绝(`{"approved":true}`) | | POST | `/api/agent` | 对话(含工具调用) | | POST | `/api/agent/stream` | 流式对话(SSE) | | POST | `/api/agent/session` | 创建会话 | | GET | `/api/sessions` | 会话列表 | | GET | `/api/cron/tasks` | 定时任务列表 | | GET | `/api/cron/runs` | 定时任务执行历史 | | GET / POST | `/api/permissions` | 查看或运行时切换权限模式 | | GET | `/api/memory/:sessionId` | 读取指定会话的记忆文件 | | POST | `/api/downloads/create` | 创建下载文件 | | GET | `/api/downloads/list` | 下载文件列表 | > `/api/agent` 的返回包含 `usage`(本次对话累计 token)与 `stats`(迭代次数、总耗时、各工具调用次数与耗时);`finishReason` 为 `max_iterations` 表示工具轮次耗尽、任务未完成。 ## 上下文压缩 历史按「轮次」切分(一轮从 user 消息开始,到下一条 user 之前),并按字符估算 token(中日韩字符按 1 个、其余按 4 字符 1 个)。当上下文占用超过预算的 80% 时,Agent 会把最早的若干轮交给模型摘要成一段,压到 50% 水位后继续,而不是直接丢弃。 摘要会保留:用户目标与约束(关键原话)、已确认的事实与数据、已完成的动作与产物路径、失败过的尝试、未完成的待办;不保留工具调用的原始输出。 | 变量 | 默认 | 说明 | |------|------|------| | `localbot_HISTORY_TOKEN_BUDGET` | 24000 | 单次请求携带的历史 token 预算 | | `localbot_COMPACTION_ENABLED` | true | 关闭后回退为「超出预算直接丢弃最早轮次」 | | `localbot_COMPACTION_TRIGGER_RATIO` | 0.8 | 超过预算的该比例时触发摘要 | | `localbot_COMPACTION_TARGET_RATIO` | 0.5 | 摘要后希望压缩到的水位 | 摘要调用失败不会中断任务:本轮回退到丢弃策略,并进入 60 秒冷却,避免每轮重复消耗模型调用。 除整轮摘要外,还有两层更轻量的省 token 机制: - **旧工具结果只留开头**:最新 3 轮的工具输出保持原文,更早的 `tool` 消息只保留前 400 字符并标注省略量;需要细节时模型会重新调用工具或缩小范围。 - **单次输出截断**:单个工具结果超过 8000 字符时保留头 4000 + 尾 1500,中间省略,避免一次读大文件就把预算顶满。 ## 禁止临时脚本(默认开启) 默认情况下 Agent 不能用「现写一个脚本再执行」的方式绕过工具:`write` / `edit` 会拒绝在项目源码目录(`src/` `web/` `tests/` `tools/` `scripts/`)之外创建 `.py` `.js` `.ps1` `.sh` 等脚本文件,`exec` 会拒绝用解释器执行这些脚本或内联代码(`python -c` / `node -e`)。技能自带的脚本(路径含 `skills/`)和项目自身源码不受影响。 这样任务只能靠现成工具(文件、浏览器、搜索、定时任务等)或安装技能来完成;确实缺能力时,Agent 会明确说明缺什么,而不是堆一堆临时文件。 | 变量 | 默认 | 说明 | |------|------|------| | `localbot_ALLOW_ADHOC_CODE` | false | 设为 `true` 恢复「允许临时脚本」的旧行为 | ## 工具按需下发 工具定义随每次请求一起发送,全量下发约 4200 tokens。开启懒加载(默认)后只下发核心工具:文件、命令、搜索、浏览器、记忆、技能、子任务;桌面操作(`mouse` / `keyboard` / `screen` / `window` / `ui` / `clipboard`)、定时任务、会话、子 Agent、技能管理这几组,只有在消息命中对应关键词或本会话已经用过时才附带。关闭方式:配置 `tools.lazy = false`。 ## 生命周期 hooks 在 `.localbot/hooks.json`(或项目根 `hooks.json`)中配置,即可在工具执行前后插入自己的脚本。脚本通过 stdin 收到 JSON 载荷:`{ event, tool, parameters, sessionId, cwd, result? }`。 ```json { "hooks": { "PreToolUse": [ { "matcher": "write|edit", "command": "node scripts/lint-guard.js", "timeoutMs": 5000 } ], "PostToolUse": [ { "matcher": "*", "command": "node scripts/audit-log.js" } ] } } ``` - `matcher` 是工具名正则,`*` 表示全部 - `PreToolUse` 的拦截条件:退出码非 0,或 stdout 输出 `{"decision":"deny","reason":"..."}` - `PostToolUse` 只用于观察/记录,失败不影响工具结果 - 超时(默认 5s)按拦截处理;`localbot_HOOKS_ENABLED=false` 可整体关闭 ## 权限与安全 内置工具每次执行前都会经过统一权限校验(Agent 调用与 `/api/tools/execute` 两条链路都覆盖),策略由 `localbot_PERMISSION_MODE` 控制: | 模式 | 行为 | |------|------| | `block`(默认) | 命中高危规则直接拒绝,返回 `blocked: true` 与原因 | | `ask` | 命中规则时挂起,等待用户批准;超时(默认 120s)按拒绝处理 | | `warn` | 放行,但在结果里附加 `_warning` | | `off` | 不校验(等同旧行为) | 模式可在 Web 界面「可用工具」页或通过 `POST /api/permissions` 运行时切换,无需重启服务。 `ask` 模式的审批交互: ```bash # 查看待审批请求(含工具名、参数、拦截原因) curl http://localhost:18789/api/approvals # 批准或拒绝 curl -X POST http://localhost:18789/api/approvals/ \ -H "Content-Type: application/json" -d '{"approved":true}' ``` Web 界面收到 `approval_request` 会直接弹窗,展示工具、命中规则与完整参数,点"批准/拒绝"即可;其他客户端也可订阅 WebSocket 事件自行处理。 默认拦截:删盘/递归强删、`format`/`diskpart`、关机重启、改 HKLM 注册表、强杀 explorer/lsass 等关键进程、修改引导配置,以及**写入或删除 `C:\Windows`、`C:\Program Files`、`C:\ProgramData` 等系统目录**。`exec` 里通过 `Set-Content`、`copy`、`>` 重定向等方式写这些目录同样会被拦截,不能绕过。 如需进一步收窄文件操作范围,设置白名单:`localbot_ALLOWED_ROOTS=e:\work,e:\data`,此后写文件/删除只能发生在这些根目录内。 > 权限策略用于拦截误操作和提示注入导致的意外破坏,**不是安全边界**:刻意构造的绕过(相对路径、脚本内拼接路径等)仍可能存在。需要硬隔离时请叠加 Docker 沙箱(见下节)。 ## 沙箱 默认关闭(`localbot_SANDBOX_MODE=off`),`exec` 直接在本机执行。如需限制执行范围,可切换为 Docker 沙箱: ```ini localbot_SANDBOX_MODE=docker localbot_SANDBOX_BACKEND=docker localbot_SANDBOX_WORKSPACE_ACCESS=ro localbot_SANDBOX_NETWORK=none ``` 相关参数见 `.env.example` 的 Sandbox Configuration 段落。 ## Docker 部署 ```bash # 构建并启动 docker-compose up -d # 查看日志 docker-compose logs -f localbot # 停止服务 docker-compose down # 重新构建 docker-compose up -d --build ``` 或使用 Docker 命令: ```bash docker build -t localbot . docker run -d --name localbot -p 18789:18789 \ -v $(pwd)/data:/app/data \ -v $(pwd)/uploads:/app/uploads \ localbot ``` 数据卷:`localbot-data`(应用数据)、`localbot-uploads`(上传文件)、`localbot-memory`(记忆)、`localbot-logs`(日志)。容器每 30 秒执行一次健康检查: ```bash docker inspect --format='{{.State.Health.Status}}' localbot ``` ## 开发 ### 添加核心工具 1. 在 `src/tools/` 下实现工具类,提供 `definition` 与 `execute(params)` 2. 在 `src/tools/index.js` 的 `registerTools`、`defaultTools`、`allowedTools` 中注册 3. 重启服务,通过 `/api/tools` 确认状态为 `ready` ### 添加外部 Python 工具 1. 在 `tools/external/` 下创建 `xxx.py`,实现: ```python def execute(operation, params): """ operation: 操作类型 params: 参数字典 返回: {"success": bool, "data": any, "error": str} """ ``` 2. 创建同名 `xxx.json` 描述文件(`name` 字段为注册名,须与调用名一致) 3. 重启服务自动加载 ### 运行测试 ```bash npm test ``` 覆盖权限规则、审批队列、代码索引、文件工具参数兼容、记忆截断、检查点回滚、定时任务重试与监控创建,共 55 项断言。 ## 故障排除 ### 启动后提示没有任何 Provider `.env` 中的 Key 仍是占位符(如 `your-deepseek-api-key-here`)会被忽略。填入真实 Key 后重启。 ### Python 工具执行失败 1. 确认 `python --version` 可用 2. 安装依赖:`pip install -r tools/requirements.txt` 3. 查看服务端日志中的 Python 脚本 stderr ### 数据库工具报 "only execute one statement at a time" `database` 工具每次只接受一条 SQL,请拆分执行。 ### 端口被占用 ```bash # 查找占用进程 netstat -ano | findstr :18789 ``` 修改 `localbot_PORT` 或结束对应 PID。 ### 长任务返回 `finishReason: max_iterations` 单轮对话内的工具调用轮次达到上限(默认 60)时,`/api/agent` 会在返回内容末尾给出提示并把 `finishReason` 标为 `max_iterations`,表示任务可能尚未完成(不会把中途叙述当成结果)。回复"继续"可接着执行,或调大 `localbot_MAX_TOOL_ITERATIONS` 后重启。 ## 相关文档 - [CHAT_CLI_EXAMPLES.md](CHAT_CLI_EXAMPLES.md) — 命令行用法与示例 - [DEPLOYMENT.md](DEPLOYMENT.md) — 部署说明 - [CHANGELOG.md](CHANGELOG.md) — 变更记录 - [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南 ## 许可证 MIT License