Files
agent/local/README.md
kicer 29be7bd9d7 feat(shell): 抽出执行后端,Windows 用 git-bash / busybox 跑命令
POSIX 上 spawn('/bin/sh') + kill(-pid) 是刻意选的最强约束:/bin/sh 固定
(不读 $SHELL,否则用户把 shell 设成 fish 后模型写的 POSIX 语法全废),
进程组让「停止」能一次带走孙进程。Windows 这三样都没有,同一个写法从
「有效」变成「静默失效」,detached 还会多弹一个控制台。

把三种能力收敛到 app/server/shell.js(resolve / spawnShell / killTree),
terminal、技能、engine 的取消都改走它,上层不再出现 process.platform 分支:

  - POSIX 分支逐字节不变,Linux / macOS / OpenWrt 行为与拆分前一致
  - Windows 依次探测 git-bash、busybox-w32,都没有就明确报错,不静默退到
    cmd.exe——cmd 的语法与模型写的 POSIX 差太远,降级只会让它反复试错
  - killTree 在 Windows 走 taskkill /T:child.kill() 只杀 shell 本身,
    模型起的 node/python/ffmpeg 孙进程会留下来继续占端口
  - detached 在 Windows 关闭(会新建控制台,且让子进程脱离 taskkill 的父子树)
  - 三级覆盖:AGENT_SHELL > config.terminal.shell > 自动探测;
    AGENT_SHELL_ARGS 可改参数模板(bash 想读 rc 时写 -lc)

新增 local/start-win.mjs:start.sh 那 1100 多行 bash 靠 lsof / pgrep /
readlink -f / nohup / setsid / 进程组信号,Windows 一个都没有。启动器这层
本来就只做进程管理,用 Node 重写更省事;业务代码一行都不分平台。首次运行
自动把 busybox-w32(单文件 600KB)下到 local/bin/,生成 local/config.win.yml,
之后不再覆盖。

验证(macOS 实跑):普通命令 / 超时 704ms / 取消 403ms 三条路径正常,进程组
3 个进程 kill 后归 0,procs 无残留;真实 core 启动 health 200,日志多一行
terminal=/bin/sh -c ← default。win32 分支只做了逻辑模拟(无 shell 的报错
文案、有 busybox 时解析为 busybox sh -c),真机待验。

未做:Windows 启动器未拉起四个同栈 MCP 与 office 预览网关,配置里
mcp_servers 暂为空,terminal / 文件工具 / 技能不受影响。
2026-11-19 11:27:17 +08:00

15 KiB
Raw Permalink Blame History

本地端(local 模式)

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

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

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

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

快速开始

cd agent
./local/start.sh     # 后台启动,命令 1 秒就返回,可以关掉终端窗口
./local/stop.sh      # 停止

首次运行会:

  1. 自检环境(Node 20+ 必需;ffmpeg / python3 可选),并打开一个启动状态页
  2. 弹窗让你选一个工作目录,在里面建 data/、skills/、tasks/ 三个子目录
  3. 把仓库 skills/ 里的内置技能复制到 <工作目录>/skills/
  4. 生成 local/config.local.yml
  5. 装一次 Node 依赖(app/ 与带依赖的 MCP,需要联网)
  6. 起 core + MCP 子进程(没 ffmpeg 时 asr 不启动)
  7. 停在那儿守护:core 退出就自动拉起

工作目录是你的:数据库、会话、技能都在里面,仓库里不存任何运行数据。

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

新建会话时,欢迎页「随时开始吧」下方可以手选一个工作目录:选了之后这个会话的 AI 一切操作 都在那个目录里(不再建 task-* 子目录);不选就沿用默认(<工作目录>/tasks/<会话id>)。 删会话不会删你选的目录。

没有 Node 20+ 时不会让你白选目录:脚本在入口就停下,终端打出安装方式,自检结果(哪项缺、怎么装)写到状态页。

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

启动器在后台常驻,所以:

  • 关掉终端窗口不会停服务;要停就 ./local/stop.sh
  • 重复跑 ./local/start.sh 是安全的:检测到已在运行就只打印地址和停止方式
  • 想在终端里看实时日志、用 Ctrl-C 停:AGENT_LOCAL_DETACH=0 ./local/start.sh

启动状态页

启动时会在浏览器打开 local/.runtime/status.html(macOS 默认自动弹,Linux 要 AGENT_LOCAL_UI=1):

  • 启动过程中每秒自动刷新,依次列出环境自检、工作目录、依赖安装、MCP、core 就绪
  • 长步骤(装依赖、等 core 起来)会显示已用时间,并把 npm / core 日志的尾巴实时刷出来
  • 首次安装(配置刚生成)不自动跳转:就停在这一页,点「打开应用」自己进去
  • 后续启动:就绪后 2 秒自动进应用(同一个标签页)
  • 失败时就在页面上给出原因和日志,不用回头翻终端

这个页面是纯静态文件(不用起服务),所以“node 都没装”的时候也能打开。重跑脚本会重新生成; 即使没自动弹出,文件也一直在那个路径。

Windows

需要 Node 20+(不需要 Docker,也不需要装 Git):

node local\start-win.mjs
node local\start-win.mjs --workspace=D:\AgentWork --port=8090

首次运行会:

  1. 自检 Node 版本
  2. 找命令执行环境:优先用已装的 Git for Windows(自带 bash);没有再自动下载 busybox-w32(单文件约 600KB)到 local/bin/busybox.exe
  3. 建工作目录(默认 %USERPROFILE%\AgentWork,--workspace 可改)下的 tasks/ data/ skills/
  4. 生成 local/config.win.yml(首次生成,之后永不覆盖)
  5. 把仓库 skills/ 里的内置技能补过去(只补缺不覆盖)
  6. app/node_modules 缺失时 npm install
  7. 起 core 并守护(退出 3 秒后自动重启,连崩 5 次停)

浏览器开 http://127.0.0.1:8090,到「设置 → 模型池」加平台和 API Key。 停止:Ctrl+C(没有 stop.sh,启动器就是前台进程)。--check 只做自检不启动。

为什么 Windows 是另一条代码路径

start.sh 靠 lsof / pgrep / readlink -f / nohup / setsid / 进程组信号,Windows 一个都没有。 所以那 1100 多行 bash 没有移植,而是用 Node 重写了「启动器」这一层——它本来就只做进程管理, 不需要 shell。业务代码一行都不分平台:平台差异只落在两个文件里:

文件 负责
app/server/shell.js 用哪个 shell 跑命令、怎么杀进程树(POSIX 进程组 / Windows taskkill /T)
local/start-win.mjs 探测、下载 busybox、生成配置、起进程、守护

覆盖与排错

变量 作用
AGENT_SHELL 直接指定 shell(绝对路径或 PATH 名),跳过一切探测
AGENT_SHELL_ARGS 参数模板,默认 -c(如 bash 想读 rc 可写 -lc)
AGENT_GIT_BASH 指定 git-bash 位置(便携版/非标准安装路径)
AGENT_BUSYBOX 指定 busybox.exe 位置
AGENT_BUSYBOX_URL 换 busybox 下载源(国内网络)

命令到底交给了谁跑:启动日志里有一行 terminal=...,失败时会写成 terminal=未找到(...)。

Windows 上仍有的限制

  • 四个同栈 MCP 没有自动拉起(配置里 mcp_servers: []):网页搜索/图片/视频/语音暂不可用, terminal、文件工具、技能正常。
  • office 预览网关没起:docx/xlsx/pptx 不能在线预览,但 office 技能生成文件不受影响。
  • 没有沙箱:和 macOS/Linux 本地模式一样,AI 的 terminal 就是你的 shell,能读写你有权限的任何文件。 工作目录选专用的,别选 C:\ 或整个仓库。
  • chmod / ln -s 这类不生效:Windows 没有 POSIX 权限位;模型写这类命令会“成功但什么都没做”。
  • /tmp 不是 Linux 的 /tmp:busybox 会把它当当前盘根目录(C:\tmp),git-bash 映射到 %TEMP%。 模型最好用相对路径或会话目录。

可选能力

能力 需要 没有时的表现
语音输入 ffmpeg + 设置页给 asr 填上游(X-ASR-Base-Url / X-ASR-Model) 麦克风入口自动隐藏(/api/asr/status 返回 enabled:false),mcp_asr 子进程也不启动
技能 python3(仅 Python 类技能需要) 技能清单照常显示;调 run.py 类技能报「入口启动失败」,office 这类非 Python 技能不受影响
Office 文档(docx/xlsx/pptx) 首次用到时下载一次 officecli 二进制(约 34MB) office 报 binary missing 并给出该技能 AGENTS.md 的路径,按它下载即可(不需 root、不需重启);预览面板里直接显示同一份安装说明
网页搜索 无 装了 Node 就有(内置免费后端)
图片 / 视频生成 设置页给对应 MCP 填上游 key 调用时报明确的缺参错误
反向隧道 tunnel/client.yml(服务器地址 + token) start.sh 跳过,不占端口;配置说明见 tunnel/README.md

装完 ffmpeg 之后重跑一次 ./local/start.sh 即可生效。python3 稍特殊:技能清单本来就在, 只要新装的解释器落在 core 启动时 PATH 已包含的目录里(如 brew 的 /opt/homebrew/bin)就无需重启; 换了目录就重跑脚本。这三项都不写进配置,靠「起不起子进程 / 注入什么环境变量」切换。

配置放哪

你选的工作目录下:

路径 内容
<工作目录>/data/ SQLite(.agent.db)、启动时的 prompt dump
<工作目录>/tasks/ 会话工作区,一个会话一个 task-YYYYMMDD-NNN/
<工作目录>/skills/ 技能;内置技能首次启动时复制过来,以后只补缺不覆盖。依赖装在 skills/deps/

仓库里只有:

  • 生成的配置:local/config.local.yml(首次生成,之后永不覆盖,避免冲掉你在网页里配的模型与密钥)
  • 运行期产物:local/.runtime/(status.html 状态页、core.log、npm-install.log、mcp-*.log、preview.log + watch-<端口>.log)

想彻底重来:删掉 local/config.local.yml 再启动(工作目录里的数据不会动,重选一个目录就换一套)。 技能要跟着仓库更新:删掉 <工作目录>/skills/<技能名> 再启动,脚本会把新版补回来(你自建的技能不受影响)。

常用环境变量

变量 默认 说明
PORT 8090 core 端口(别撞下面的 MCP 端口)
NPM_REGISTRY 空 手动指定 npm 源(默认自动探测;指定后不再自动换源)
MCP_WEB_PORT / MCP_IMAGE_PORT / MCP_VIDEO_PORT / MCP_ASR_PORT 8091~8094 四个 MCP 的端口(同机跑必须各占一个;改这里还要同步改配置里的 url)
PREVIEW_PORT 3100 office 文档预览网关的端口(被占时自动往后找);watch 自己的端口从 26315 起
AGENT_LOCAL_UI auto 是否自动打开状态页:auto = 仅 macOS,1 强制,0 关闭(页面无论如何都会生成)
AGENT_LOCAL_DETACH 1 1 = 后台启动后立即返回(用 stop.sh 停);0 = 前台阻塞(看实时日志、Ctrl-C 停)
AGENT_LOCAL_CACHE ~/.cache/agent-local 依赖缓存的存放位置(多个 clone 共享)
AGENT_LOCAL_NPM_TIMEOUT 240 单次 npm install 的超时秒数,超过就换源重试

依赖安装与网络(国内环境)

首次启动要装一次 Node 依赖,启动器会自己处理环境问题,不需要你操心:

  • 自动选源:并行探 registry.npmmirror.com 与官方源,用最快的那个(国内基本会选 npmmirror)。 结果缓存一天;不写你本机的 ~/.npmrc,也不改全局配置。
  • 失败自动换源重试:一个源不行就换下一个;换源成功会记住它。
  • 卡住有看门狗:npm 在断网时可能既不报错也不退出,超过 AGENT_LOCAL_NPM_TIMEOUT 就结束它并换源。
  • 装完存缓存:打成一张 tarball 放到 ~/.cache/agent-local/。之后重启、删掉 node_modules、 再 clone 一份,都是解压恢复(秒级、零网络)。
  • 失败说人话:状态页会直接告诉你「网络没通 / 缺编译工具链(xcode-select --install)/ 没有写权限」, 不需要读 npm 日志。

要清缓存就删那个目录:rm -rf ~/.cache/agent-local(下次启动会重新装一次)。

更新

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

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

安全边界(务必知情)

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

两条低成本保险:

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

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

配了隧道后,core 会经隧道 client 暴露到公网域名。访问控制靠隧道 token + 上游 nginx 的 TLS; 入口仍是 127.0.0.1:8090,不额外监听端口。

已知限制

  • 没 ffmpeg 时 core 日志会有一条 asr 工具发现失败:此时 mcp_asr 不启动(它转码要靠 ffmpeg),但配置里的 asr 条目仍保留(配置不被覆盖)。重试几次后放弃,不影响其它功能。
  • 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 与页面访问地址都会签成 http://127.0.0.1:<PORT>/...,在这台机器上点得开,发给别人打不开。要对外暴露再填 public_link.base_url(设置页)。本地监听回环地址,模型厂商也拉不到,所以读图回传改走内联 base64(AGENT_IMAGE_INLINE=1,启动器已注入)。
  • office 预览依赖 officecli:网关按需起 officecli watch(最多 4 个,闲置 6 小时回收)。 没装二进制时预览面板会直接显示安装说明,不会无限转圈。watch 只能监听 0.0.0.0(它没有 --host 参数),同机其它用户理论上能访问那几个端口。
  • 技能依赖不预装:本地没有 agent-executor-init,技能自带的 requirements.txt 不会在启动时 自动安装。缺包时会报 ModuleNotFoundError,模型会把缺的包装进 <工作目录>/skills/deps (AGENT_SKILLS_DEPS 指向它,且已在该进程的 PYTHONPATH 里,装完下次运行即生效)。 连 python3 都没有时技能清单依旧完整,模型会自己把它装上再继续。 需要系统库的包(如 weasyprint 依赖 pango/cairo)pip 装不了,得自己 brew install。
  • 首个 npm install 要联网:启动器会自动选源、换源重试、并把装好的依赖缓存到 ~/.cache/agent-local/;之后重启 / 换 clone 都是本地解压,不需要网络。真要手动指定源: NPM_REGISTRY=https://registry.npmmirror.com ./local/start.sh。中途失败留下的半成品 node_modules 不用手删(换源重试前会自动清)。

排查

open local/.runtime/status.html        # 启动状态页:步骤、失败原因、日志尾巴
tail -f local/.runtime/core.log        # core 日志(含 prompt dump 路径、MCP 发现结果)
tail -f local/.runtime/npm-install.log # 装依赖的输出
tail -f local/.runtime/mcp-asr.log     # 单个 MCP 的日志
tail -f local/.runtime/preview.log     # office 预览网关(watch 启动失败的原因也在这)

启动失败时状态页会自己弹出(带错误说明和日志尾部);它是个静态页,所以改完环境要自己重跑脚本 (它不会自动重试)。

进程表 / 端口对不上时:

lsof -nP -iTCP:8090-8094 -sTCP:LISTEN   # core + 四个 MCP 的监听情况
lsof -nP -iTCP:3100 -sTCP:LISTEN        # 预览网关(没用 office 时不存在)