后端只改两处,都靠 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 一致性两个关键项)。
12 KiB
本地端(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 的两个分叉点:
- 根:
rootDir给了就按它校验(workspace 形态 =workspace_root),否则仍按会话目录 /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 即可。
-
首次启动
./local/start.sh预期:弹出「选择工作目录」窗口 → 生成
local/config.local.yml→ 装依赖(app+mcp/image_task+mcp/video_task)→ 起 4 个 MCP + core → 自动打开浏览器 → 终端打印访问地址与 「首次使用」提示。 -
配置文件内容:检查
workspace_root是你选的目录、data_root指向仓库data/、skills_root指向local/.runtime/skills、platforms: []。 -
绑定地址:
lsof -nP -iTCP:8090 -sTCP:LISTEN应只有127.0.0.1(不是*)。 -
重启按钮(最关键):设置页加一个平台 + API Key → 点「重启」→ 页面应能在十几秒内自行恢复 (
settings.js会轮询/api/health90 秒后 reload)。若页面一直转圈,说明守护循环没生效。 -
文件工具越出会话目录:在工作目录根(不是
task-*子目录里)放一个probe.txt,让 AIread_file它的绝对路径。预期:能读到(session形态下这里会报「路径越界」)。 -
/tmp一致性(本次修的 bug):让 AI 执行terminal: echo hello-tmp > /tmp/probe-local.txt read_file: /tmp/probe-local.txt预期:读得到。反过来也可验证
ls /tmp与read_file指向同一处。 -
语音(可选能力):没装 ffmpeg 时终端应打印「语音:不可用」,输入框没有麦克风;
brew install ffmpeg后重跑脚本 → 打印「语音:可用」+ 麦克风出现(还需在设置页给asr填X-ASR-Base-Url/X-ASR-Model才真正能用)。 -
技能(可选能力):有 python3 时打印「技能:已启用」;临时把 PATH 里的 python3 藏掉再跑, 应打印「技能:已关闭」,且设置页技能列表为空、模型提示词里没有技能段。
-
退出清理:
Ctrl-C后确认没有残留进程。按 PID 查,不要用pkill -f:lsof -nP -iTCP:8090 -sTCP:LISTEN lsof -nP -iTCP:3101-3104 -sTCP:LISTEN三个 MCP 端口都应释放。
-
二次启动:再跑一次
./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 不会有这些。