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

235 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 本地端(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. **首次启动**
```bash
./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 执行
```bash
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`**:
```bash
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. 回滚
本地模式的所有开关默认关闭,服务器行为不变。真要整体撤掉:
```bash
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 不会有这些。