Files
agent/local
kicer 8a5c8b1547 新增本地端(local 模式):同一份代码直接跑在本机,不起 Docker / executor
后端只改两处,都靠 env 开关,不设置时服务器行为与 v2.5.0 完全一致:
- server.js:支持 HOST,本地注入 127.0.0.1(不设仍是 0.0.0.0)
- tools/executor.js:AGENT_FILE_SCOPE=workspace 把文件工具的根从会话目录放宽到
  workspace_root,并关掉 /tmp 重定向(本地 terminal 写的是真 /tmp,重定向会造成
  AI 自己写的东西自己读不到);recordFile 跳过会话外文件,避免附件表存 ../ 路径。
  路由层、@历史会话、mint_public_link 仍按会话目录校验,不变。

新增 local/:start.sh(探测 → 首次生成配置 → 装依赖 → 起 core +4 个 MCP → 守护重启)、
start.command(mac 双击)、config.example.yml(参考)、README.md。
能力按需:node 必需,ffmpeg 决定语音(靠 ASR_URL 注入)、python3 决定技能(靠
.runtime/skills 软链切换),两者都不写进配置——配置首次生成后永不覆盖,避免冲掉
用户在网页里配的模型与密钥。

另加 docs/local-mode.md:设计决定、验证状态与 mac 上的逐项验证清单(含重启按钮
守护、/tmp 一致性两个关键项)。
2026-11-11 10:25:33 +08:00
..

本地端(local 模式)

把同一个 agent-core 直接跑在本机(macOS / Linux),不装 Docker、不起 executor。

它和服务器版是同一份代码,差别只在三件事,全部由 local/start.sh 注入:

差异 服务器 本地
命令在哪跑 agent-executor 容器(mount/pid namespace 隔离) 直接在本机 spawn(无沙箱)
文件工具的根 会话目录 tasks/<会话id>/ 你指定的工作目录 workspace_root
监听地址 0.0.0.0(靠宿主机端口映射对外) 127.0.0.1(只有本机能访问)

后两项分别由环境变量 AGENT_FILE_SCOPE=workspace 和 HOST=127.0.0.1 控制,容器部署不设置, 行为与以前完全一致。

快速开始

git clone <本仓库> agent && cd agent
./local/start.sh          # macOS 也可以在 Finder 里双击 local/start.command

首次运行会:

  1. 自检环境(Node 20+ 必需;ffmpeg / python3 可选)
  2. 弹窗让你选一个工作目录(AI 会在这个目录里干活)
  3. 生成 local/config.local.yml
  4. 装一次 app/ 的 Node 依赖(需要联网)
  5. 起 core + 4 个 MCP 子进程,就绪后自动打开浏览器
  6. 停在那儿守护:core 退出就自动拉起

浏览器里首次使用:左下角「用户区」→ 设置 → 模型池,添加平台和 API Key,然后点「重启」。

「重启」能用是因为启动器在守护。routes/system.js 的重启实现是 process.exit(0), 原本靠 Docker 的 restart 策略拉起;本地没有 Docker,没有守护的话点一次服务就回不来了。

关闭:在终端按 Ctrl-C,子进程会一起收掉。

可选能力

能力 需要 没有时的表现
语音输入 ffmpeg + 设置页给 asr 填上游(X-ASR-Base-Url / X-ASR-Model) 麦克风入口自动隐藏(/api/asr/status 返回 enabled:false)
技能 python3 技能清单为空,其余功能不受影响
网页搜索 无 装了 Node 就有(内置免费后端)
图片 / 视频生成 设置页给对应 MCP 填上游 key 调用时报明确的缺参错误

装完 ffmpeg / python3 之后重跑一次 ./local/start.sh 即可生效——这两项都不写进配置, 靠「起不起子进程 / 软链指向哪 / 注入什么环境变量」切换。

配置放哪

  • 生成的配置:local/config.local.yml(首次生成,之后永不覆盖,避免冲掉你在网页里配的模型与密钥)
  • 会话数据:data/(SQLite + prompt dump)与工作目录下的 task-YYYYMMDD-NNN/
  • 运行期产物:local/.runtime/(core.log、各 MCP 日志、自检页、技能软链)

想彻底重来:删掉 local/config.local.yml(以及可选的 data/)再启动。会话目录里的产出不会被删。

常用环境变量

变量 默认 说明
PORT 8090 core 端口
NPM_REGISTRY 空 首次装依赖时用的 npm 源,如 https://registry.npmmirror.com
MCP_WEB_PORT / MCP_IMAGE_PORT / MCP_VIDEO_PORT / MCP_ASR_PORT 3101~3104 四个 MCP 的端口(同机跑必须各占一个)

更新

git pull
./local/start.sh     # package.json 变了会自动重装依赖

app/server 是直接跑源码,前端也是免构建的,所以改完代码重启(或在网页点「重启」)即生效。

安全边界(务必知情)

本地模式没有沙箱:AI 的 terminal 就是本机 shell,能读写你账号有权限的任何文件, 包括 ~/.ssh、浏览器数据、其它项目。这不是配置疏漏,而是「给它一个目录就放开手脚」的代价。

两条低成本保险:

  1. 工作目录选一个专用目录,别直接选 $HOME 或整个代码仓库根
  2. 那个目录先 git init 一下,改坏了能回滚

另外,core 只监听 127.0.0.1,同一局域网的人访问不到。

已知限制

  • MCP 子进程里 mcp_asr 仍然监听 0.0.0.0:它只认 PORT 环境变量,没有 --host 参数 (另外三个服务都传了 --host 127.0.0.1)。它不存任何密钥(上游参数随请求带入), 暴露面有限,但严格起见可以给 mcp/asr 补一个 --host 支持。
  • Windows 暂不支持:本机执行走 spawn('/bin/sh') 与 process.kill(-pid),都是 POSIX 语义。
  • mint_public_link 不可用:public_link.base_url 未配置(本地生成的链接只有本机能打开), 模型调用该工具会得到明确的「未配置」错误。
  • 技能依赖:有 requirements.txt 的技能需要自己把包装进 skills/deps (服务器上这一步由 agent-executor-init 在构建期完成)。默认只保证纯标准库技能可用。

排查

tail -f local/.runtime/core.log        # core 日志(含 prompt dump 路径、MCP 发现结果)
tail -f local/.runtime/mcp-asr.log     # 单个 MCP 的日志

启动前自检不通过时,会生成并打开 local/.runtime/setup.html——那是个静态页, 所以改完环境要自己重跑脚本(它不会自动重试)。