新增本地端(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 一致性两个关键项)。
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
# 本地端(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 不会有这些。
|
||||
Reference in New Issue
Block a user