Files
agent/local/README.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

108 lines
5.1 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 模式)
把同一个 `agent-core` 直接跑在本机(macOS / Linux),不装 Docker、不起 executor。
它和服务器版是**同一份代码**,差别只在三件事,全部由 `local/start.sh` 注入:
| 差异 | 服务器 | 本地 |
|---|---|---|
| 命令在哪跑 | `agent-executor` 容器(mount/pid namespace 隔离) | 直接在本机 `spawn`(无沙箱) |
| 文件工具的根 | 会话目录 `tasks/<会话id>/` | 你指定的工作目录 `workspace_root` |
| 监听地址 | `0.0.0.0`(靠宿主机端口映射对外) | `127.0.0.1`(只有本机能访问) |
后两项分别由环境变量 `AGENT_FILE_SCOPE=workspace` 和 `HOST=127.0.0.1` 控制,容器部署不设置,
行为与以前完全一致。
## 快速开始
```bash
git clone <本仓库> agent && cd agent
./local/start.sh # macOS 也可以在 Finder 里双击 local/start.command
```
首次运行会:
1. 自检环境(Node 20+ 必需;ffmpeg / python3 可选)
2. 弹窗让你选一个**工作目录**(AI 会在这个目录里干活)
3. 生成 `local/config.local.yml`
4. 装一次 `app/` 的 Node 依赖(需要联网)
5. 起 core + 4 个 MCP 子进程,就绪后自动打开浏览器
6. 停在那儿守护:core 退出就自动拉起
浏览器里首次使用:**左下角「用户区」→ 设置 → 模型池**,添加平台和 API Key,然后点「重启」。
> 「重启」能用是因为启动器在守护。`routes/system.js` 的重启实现是 `process.exit(0)`,
> 原本靠 Docker 的 restart 策略拉起;本地没有 Docker,没有守护的话点一次服务就回不来了。
关闭:在终端按 `Ctrl-C`,子进程会一起收掉。
## 可选能力
| 能力 | 需要 | 没有时的表现 |
|---|---|---|
| 语音输入 | `ffmpeg` + 设置页给 `asr` 填上游(`X-ASR-Base-Url` / `X-ASR-Model`) | 麦克风入口自动隐藏(`/api/asr/status` 返回 `enabled:false`) |
| 技能 | `python3` | 技能清单为空,其余功能不受影响 |
| 网页搜索 | 无 | 装了 Node 就有(内置免费后端) |
| 图片 / 视频生成 | 设置页给对应 MCP 填上游 key | 调用时报明确的缺参错误 |
装完 `ffmpeg` / `python3` 之后**重跑一次 `./local/start.sh`** 即可生效——这两项都不写进配置,
靠「起不起子进程 / 软链指向哪 / 注入什么环境变量」切换。
## 配置放哪
- 生成的配置:`local/config.local.yml`(**首次生成,之后永不覆盖**,避免冲掉你在网页里配的模型与密钥)
- 会话数据:`data/`(SQLite + prompt dump)与工作目录下的 `task-YYYYMMDD-NNN/`
- 运行期产物:`local/.runtime/`(`core.log`、各 MCP 日志、自检页、技能软链)
想彻底重来:删掉 `local/config.local.yml`(以及可选的 `data/`)再启动。会话目录里的产出不会被删。
## 常用环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
| `PORT` | `8090` | core 端口 |
| `NPM_REGISTRY` | 空 | 首次装依赖时用的 npm 源,如 `https://registry.npmmirror.com` |
| `MCP_WEB_PORT` / `MCP_IMAGE_PORT` / `MCP_VIDEO_PORT` / `MCP_ASR_PORT` | 3101~3104 | 四个 MCP 的端口(同机跑必须各占一个) |
## 更新
```bash
git pull
./local/start.sh # package.json 变了会自动重装依赖
```
`app/server` 是直接跑源码,前端也是免构建的,所以改完代码重启(或在网页点「重启」)即生效。
## 安全边界(务必知情)
本地模式**没有沙箱**:AI 的 `terminal` 就是本机 shell,能读写你账号有权限的任何文件,
包括 `~/.ssh`、浏览器数据、其它项目。这不是配置疏漏,而是「给它一个目录就放开手脚」的代价。
两条低成本保险:
1. 工作目录选一个**专用**目录,别直接选 `$HOME` 或整个代码仓库根
2. 那个目录先 `git init` 一下,改坏了能回滚
另外,`core` 只监听 `127.0.0.1`,同一局域网的人访问不到。
## 已知限制
- **MCP 子进程里 `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` 不可用**:`public_link.base_url` 未配置(本地生成的链接只有本机能打开),
模型调用该工具会得到明确的「未配置」错误。
- **技能依赖**:有 `requirements.txt` 的技能需要自己把包装进 `skills/deps`
(服务器上这一步由 `agent-executor-init` 在构建期完成)。默认只保证纯标准库技能可用。
## 排查
```bash
tail -f local/.runtime/core.log # core 日志(含 prompt dump 路径、MCP 发现结果)
tail -f local/.runtime/mcp-asr.log # 单个 MCP 的日志
```
启动前自检不通过时,会生成并打开 `local/.runtime/setup.html`——那是个静态页,
所以改完环境要自己重跑脚本(它不会自动重试)。