Files
agent/docs/local-mode.md
T
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

12 KiB
Raw Blame History

本地端(local 模式):设计与交接

本文是 local/ 的设计说明 + 交接单。 状态:代码已写完,仅在 Linux 服务器上做过「能否启动」的粗测,尚未在 macOS 真机验证。 下一轮的任务就是按第 6 节的清单在 mac 上逐项确认。

1. 目标

把同一个 agent-core 直接跑在本机(macOS / Linux),不装 Docker、不起 executor,形态类似 桌面 agent:给它一个工作目录,它在这个目录里放开手脚干活。

明确的设计约束(都来自讨论):

  • 和服务器端同一份代码,不 fork 新仓库、不长期开 branch;靠运行时开关分叉
  • app/ 最小化改动(最终只有 2 个后端文件,前端 0 改动)
  • 组件按需:node 必需;ffmpeg 决定语音;python3 决定技能
  • Windows 暂时不做(本机执行依赖 POSIX 语义,见第 7 节)
  • 不用 Docker(用户明确否决)

基线版本:v2.5.0(服务器端最后一个纯容器部署版本)。

2. 与服务器形态的差异(只有三处)

差异 服务器 本地 由谁注入
命令在哪跑 agent-executor 容器(mount/pid namespace 隔离) 本机 spawn(无沙箱) EXECUTOR_URL 留空 → 现成分支,未改代码
文件工具的根 会话目录 tasks/<会话id>/ 指定的工作目录 AGENT_FILE_SCOPE=workspace
监听地址 0.0.0.0 127.0.0.1 HOST=127.0.0.1

后两项是本次新增的开关。两者都不设置时,行为与 v2.5.0 完全一致(容器部署不受影响)。

3. 本次改动清单

后端(app/,只 2 个文件)

文件 改动
app/server/server.js 读 HOST 环境变量;有值则 server.listen(PORT, HOST, cb),无值维持 listen(PORT, cb)(= 0.0.0.0)。启动日志带上 host
app/server/tools/executor.js 新增 WIDE_SCOPE(由 AGENT_FILE_SCOPE=workspace 打开)与 fsRoot(ctx);resolveInTask() 增加可选第三参 rootDir;6 个业务工具的调用点改为传 fsRoot(ctx);recordFile() 跳过会话目录之外的文件

resolveInTask 的两个分叉点:

  1. 根:rootDir 给了就按它校验(workspace 形态 = workspace_root),否则仍按会话目录
  2. /tmp:session 形态保持「重定向到 <会话>/.tmp」;workspace 形态不重定向,并把真实 /tmp 纳入允许范围

刻意没有动的(重要)

  • resolvePastPath()(@<会话id>/... 跨会话只读)—— 仍锁在对方会话目录
  • routes/files.js、routes/public-files.js、routes/data-page.js —— HTTP 文件 API 与公网短链 仍按会话目录校验,前台不能借本地模式越权
  • mint_public_link —— 仍会话目录语义(本地本来也没配 public_link.base_url)
  • 前端 —— 一行没改;首次配置靠终端提示「用户区 → 设置 → 模型池」

新增 local/

文件 作用
start.sh 主入口:探测 → 首次生成配置 → 装依赖 → 起 core + 4 个 MCP → 开浏览器 → 守护重启
start.command macOS 双击入口(补 Homebrew 的 PATH,失败时留窗口)
config.example.yml 仅作参考,不被读取;实际配置由 start.sh 生成到 config.local.yml
README.md 给使用者的说明(含安全边界、已知限制)

.gitignore 增加 local/.runtime/、local/config.local.yml。

4. 关键设计决定(含「为什么」,别推翻)

4.1 开关用环境变量,不进 config.yml

EXECUTOR_URL / ASR_URL 已经是「部署接线走 env」的先例,本地模式属于同一类(部署形态), 不是平台配置。好处是 app/ 只需改 2 个文件,不必动 config.js 的 DEFAULTS 和 config.example.yml(改配置项必须两处同步,是仓库的硬规则)。

4.2 配置首次生成后永不覆盖

config.local.yml 里既有启动器生成的字段(workspace_root / skills_root),也有用户在网页里 配的东西(platforms、API Key、MCP headers)。每次启动重写会直接冲掉后者。

推论:能力变化不能靠改配置实现,只能靠 env / 起不起子进程 / 软链(见 4.3、4.4)。

4.3 ffmpeg 是运行时能力,与配置解耦

routes/asr.js 直接读 process.env.ASR_URL,/api/asr/status 在 ASR_URL 为空时返回 enabled:false,前端 voice.js 据此自动隐藏麦克风。所以:

  • 有 ffmpeg → 启动器起 mcp_asr + 注入 ASR_URL
  • 没 ffmpeg → 不起、不注入 → 麦克风自动消失

装完 ffmpeg 后重跑脚本即生效,配置文件一个字不用改。

4.4 python3 用软链切换,与配置解耦

skills.js 对技能根目录不存在的行为是「warn + 返回空列表」,不报错不阻塞。于是配置里永远写 skills_root: <仓库>/local/.runtime/skills,启动器每次都重建这个软链:

  • 有可用 python3 → 指向 <仓库>/skills
  • 没有 → 指向 .runtime/empty-skills(空目录)

装完 python3 重跑脚本即生效。没有改 skills.js 一行代码。

4.5 启动器必须是守护进程

routes/system.js 的重启实现是「校验配置 → process.exit(0) → 等 Docker restart 策略拉起」, 注释里写明「非 docker 部署不会自动重启」。本地没有 Docker,如果启动器只是前台 node, 用户配完模型点一次「重启」,服务就再也回不来。

所以主循环是:起 core → 等健康 → wait → 非用户中断就 1 秒后重启;连续异常退出 5 次才停 (防配置写坏导致无限刷屏)。exit 0 视为用户主动重启。

4.6 四个 MCP 必须分端口

容器里它们是四个独立容器、都监听 3000;本地同机必须错开(默认 3101~3104)。 另外它们的启动参数不统一,这是个坑:

服务 启动方式 说明
web_search node server.js --http --host --port 默认 host 已经是 127.0.0.1
image_task node src/mcp-server.js --http --host --port 默认 0.0.0.0
video_task node src/mcp-server.js --http --host --port 默认 0.0.0.0
mcp_asr 只认 PORT 环境变量 不解析 argv,且 listen 没带 host(= 0.0.0.0)

所以 start.sh 拆成 start_mcp_flags / start_mcp_env 两个函数,别合并。

4.7 /tmp 语义为什么分叉

服务器端:executor 在 session 模式下执行 mount --bind <会话>/.tmp /tmp,容器内 /tmp 的物理 落点就是宿主 <会话>/.tmp。core 的文件工具必须去同一处找,否则 AI 用 terminal 写 /tmp/x 后 read_file /tmp/x 读不到。所以那份「重定向」是必需的,不是 bug。

本地端:toolTerminal 是真 spawn('/bin/sh'),/tmp 就是本机 /tmp。此时再重定向就会造成 「terminal 写真实 /tmp、file 工具读会话 .tmp」的错位——这正是 AGENT_FILE_SCOPE=workspace 要关掉重定向的原因。

4.8 skills_root 的默认值陷阱

skills.skills_root 留空时默认取 workspace_root 的同级 skills 目录。本地把 workspace_root 指到用户选的目录后,默认值会变成不存在的 <用户目录>/../skills。 因此生成的配置必须显式写死 skills_root。

5. 已验证 / 未验证

已在 Linux 服务器上粗测(PORT=18090,避免碰线上 8090)

项 结果
sh -n / node --check 通过
首次运行生成 config.local.yml 通过(无 tty 时回落 ~/AgentWork)
core 启动 + /api/health 通过,auth_required:false
HOST=127.0.0.1 生效 通过(ss 只看到 127.0.0.1:18090)
端口占用检测 + 自检页 通过(线上 8090 被占时正确拒绝并生成 setup.html)
MCP 端口分配 / start_mcp_env 分离 web_search、asr 起来了;image_task、video_task 因缺 npm 依赖未起
因此新增 ensure_deps 遍历 app 与 mcp/*/ 改完未复验(用户要求停止测试)

完全未验证(mac 上要逐项确认)

osascript 选目录、start.command 双击、open 打开浏览器、ffmpeg 语音链路、python3 软链切换、 重启按钮的守护拉起、Ctrl-C 清理子进程、AGENT_FILE_SCOPE=workspace 下文件工具的真实行为、 /tmp 读写一致性、ensure_deps 在 mac 上的实际效果。

6. macOS 验证清单(下一轮按这个做)

前置:全新 clone(不要带服务器上的测试残留)。全程只用非默认端口的前提不再需要——mac 上没有 常驻服务,用默认 8090 即可。

  1. 首次启动

    ./local/start.sh
    

    预期:弹出「选择工作目录」窗口 → 生成 local/config.local.yml → 装依赖(app + mcp/image_task + mcp/video_task)→ 起 4 个 MCP + core → 自动打开浏览器 → 终端打印访问地址与 「首次使用」提示。

  2. 配置文件内容:检查 workspace_root 是你选的目录、data_root 指向仓库 data/、 skills_root 指向 local/.runtime/skills、platforms: []。

  3. 绑定地址:lsof -nP -iTCP:8090 -sTCP:LISTEN 应只有 127.0.0.1(不是 *)。

  4. 重启按钮(最关键):设置页加一个平台 + API Key → 点「重启」→ 页面应能在十几秒内自行恢复 (settings.js 会轮询 /api/health 90 秒后 reload)。若页面一直转圈,说明守护循环没生效。

  5. 文件工具越出会话目录:在工作目录根(不是 task-* 子目录里)放一个 probe.txt,让 AI read_file 它的绝对路径。预期:能读到(session 形态下这里会报「路径越界」)。

  6. /tmp 一致性(本次修的 bug):让 AI 执行

    terminal: echo hello-tmp > /tmp/probe-local.txt
    read_file: /tmp/probe-local.txt
    

    预期:读得到。反过来也可验证 ls /tmp 与 read_file 指向同一处。

  7. 语音(可选能力):没装 ffmpeg 时终端应打印「语音:不可用」,输入框没有麦克风; brew install ffmpeg 后重跑脚本 → 打印「语音:可用」+ 麦克风出现(还需在设置页给 asr 填 X-ASR-Base-Url / X-ASR-Model 才真正能用)。

  8. 技能(可选能力):有 python3 时打印「技能:已启用」;临时把 PATH 里的 python3 藏掉再跑, 应打印「技能:已关闭」,且设置页技能列表为空、模型提示词里没有技能段。

  9. 退出清理:Ctrl-C 后确认没有残留进程。按 PID 查,不要用 pkill -f:

    lsof -nP -iTCP:8090 -sTCP:LISTEN
    lsof -nP -iTCP:3101-3104 -sTCP:LISTEN
    

    三个 MCP 端口都应释放。

  10. 二次启动:再跑一次 ./local/start.sh,应跳过生成配置、跳过装依赖、直接起服务 (验证「配置不覆盖」与依赖检测的 mtime 判断)。

7. 已知限制(都不打算在本次解决)

限制 说明
无沙箱 AI 的 terminal 就是本机 shell,能读 ~/.ssh 等一切。这是「给它一个目录就放开手脚」的代价;README 已提示「专用目录 + git init」
mcp_asr 监听 0.0.0.0 它只认 PORT 环境变量、listen 不带 host。不存密钥(上游参数随请求带入),暴露面有限;要收紧需给 mcp/asr 加 --host 支持
Windows 不支持 spawn('/bin/sh')、process.kill(-pid)、模型写的 bash 语法都是 POSIX 语义
mint_public_link 不可用 本地 public_link.base_url 为空,工具会回明确的「未配置」错误
技能依赖 有 requirements.txt 的技能需手工装进 skills/deps(服务器上由 agent-executor-init 在构建期做)。默认只保证纯标准库技能
首个 npm install 要联网 支持 NPM_REGISTRY 覆盖源

8. 回滚

本地模式的所有开关默认关闭,服务器行为不变。真要整体撤掉:

git revert <本次提交>
rm -rf local/   # 或保留脚本、只是不用

v2.5.0 是这批改动之前的基线,可随时对照。

9. 记录:上一台机器上的测试残留(mac 全新 clone 不受影响)

在 Linux 服务器上试跑时产生过:local/.runtime/、local/config.local.yml、~/AgentWork/、 mcp/image_task/node_modules/、mcp/video_task/node_modules/(可能半成品)。全部在 gitignore 内, 不影响仓库;mac 上重新 clone 不会有这些。