office 技能本体(SKILL.md + Node 封装层 + officecli 二进制)本来就是跨平台的, 坏在两处容器假设:install.sh 只认 linux-x64、PATH 入口只写 /usr/local/bin。 - install.sh: 按 uname -s/-m 选资产(linux x64/arm64、mac x64/arm64),校验和 pin 到 上游 release 的 SHA256SUMS(八平台齐全,linux-x64 那行与原有 pin 完全一致); mac 没有 sha256sum,补 shasum -a 256 兜底;构建阶段判定提前到平台探测之前, 避免构建机架构未被识别时中断镜像构建 - 已在且能跑就沿用:officecli 会自更新到上游 latest(实测 1.0.157 跑一次变 1.0.160, 文件大小与 latest 资产一字节不差),用 pin 去比对只会反复重拉 34MB。服务器卷 :ro、 二进制不会漂,正常仍走 sha 比对,行为不变 - local/start.sh: 起 core 时把 skills/office/scripts 塞进 PATH(服务器靠镜像里的 /usr/local/bin 软链;本地没 root 写不了系统目录)。无需复制、无需改 app/ - 封装层 ENOENT 报错带上 install.sh 绝对路径,模型看到即可自行补装 本地实测(macOS x86_64):office create / view outline 正常;启动器不预下载,首次用到时 按报错跑一次 install.sh(GitHub 慢时自动换 gh-proxy,实测 27s)。 预览仍不可用(缺 executor 的 :3100 网关),已记入文档。
415 lines
32 KiB
Markdown
415 lines
32 KiB
Markdown
# 本地端(local 模式):设计与交接
|
||
|
||
> 本文是 `local/` 的设计说明 + 交接单。
|
||
> **状态:已在 macOS 真机(12.7.6 / x86_64 / Node 22.21 / python3 3.10,本机无 ffmpeg)按第 6 节
|
||
> 清单逐项跑过,结果见第 5 节。** 只剩三件依赖人工交互或外部环境的事没覆盖(真实选目录弹窗、
|
||
> 真浏览器打开、装 ffmpeg 之后的链路),见第 6 节。
|
||
|
||
## 1. 目标
|
||
|
||
把同一个 `agent-core` 直接跑在本机(macOS / Linux),**不装 Docker、不起 executor**,形态类似
|
||
桌面 agent:给它一个工作目录,它在这个目录里放开手脚干活。
|
||
|
||
明确的设计约束(都来自讨论):
|
||
|
||
- **和服务器端同一份代码**,不 fork 新仓库、不长期开 branch;靠运行时开关分叉
|
||
- **`app/` 最小化改动**(最终只有 2 个后端文件,前端 0 改动)
|
||
- **组件按需**:node 必需;ffmpeg 决定语音;python3 决定 Python 类技能能否执行(非 Python 技能如 `office` 不受影响)
|
||
- **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/`)
|
||
|
||
| 文件 | 改动 |
|
||
|---|---|
|
||
| `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()` 跳过会话目录之外的文件 |
|
||
| `app/server/routes/files.js` | 新增 `GET /:id/tree`(桌面端左栏文件树用:单层懒加载、忽略大目录、上限 500、越界双重校验) |
|
||
|
||
`resolveInTask` 的两个分叉点:
|
||
|
||
1. **根**:`rootDir` 给了就按它校验(workspace 形态 = `workspace_root`),否则仍按会话目录
|
||
2. **`/tmp`**:`session` 形态保持「重定向到 `<会话>/.tmp`」;`workspace` 形态**不重定向**,并把真实
|
||
`/tmp` 纳入允许范围
|
||
|
||
### 刻意没有动的(重要)
|
||
|
||
- `resolvePastPath()`(`@<会话id>/...` 跨会话只读)—— 仍锁在对方会话目录
|
||
- `routes/public-files.js`、`routes/data-page.js` —— 公网短链与 data-page 仍按会话目录校验
|
||
- `mint_public_link` —— 仍会话目录语义(本地本来也没配 `public_link.base_url`)
|
||
- 前端 —— 本地模式没有专属前端代码;左栏文件树是桌面端共用的(见下)
|
||
|
||
> 追加:文件树最初只给 local 用,后来上收为桌面端通用能力 —— `/tree` 移到 `routes/files.js`,
|
||
> 服务器形态的桌面端也用它取代「输入行右侧的旧文件面板」(含下载/删除);`reveal`、`terminal`、
|
||
> `pick-dir` 仍只在 `AGENT_LOCAL_PICK=1` 下挂载(它们开的是跑 core 那台机器的窗口)。
|
||
|
||
### 新增 `local/`
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `start.sh` | 主入口:探测 → 首次生成配置 → 装依赖 → 起 core + MCP → 守护重启。**后台化**:拉起真正的启动器就返回 |
|
||
| `stop.sh` | 停止启动器(按 `supervisor.pid` → core 的父进程 → 占端口的进程,三级兜底),幂等 |
|
||
| `config.example.yml` | **仅作参考,不被读取**;实际配置由 `start.sh` 生成到 `config.local.yml` |
|
||
| `README.md` | 给使用者的说明(含安全边界、已知限制) |
|
||
|
||
`.gitignore` 增加 `local/.runtime/`、`local/config.local.yml`。
|
||
|
||
> 曾经有一个 `start.command`(macOS 双击入口),已删除:Finder 里双击 `.command` 常被系统当文本
|
||
> 预览打开、不执行,而且它补的 PATH 探测和 `start.sh` 重复。现在唯一入口就是 `./local/start.sh`。
|
||
|
||
### 3.1 真机验证阶段补的修改
|
||
|
||
首次在 mac 上跑,暴露了下面这些;都不是设计变更,是实现跟设计对不上或漏了边界:
|
||
|
||
| 文件 | 改动 | 为的什么 |
|
||
|---|---|---|
|
||
| `local/start.sh` | 新增启动即弹出的**状态页**(`local/.runtime/status.html`,每秒自刷新) | 启动时终端看不到进度;失败页既没有应用名也没有日志,用户无从判断 |
|
||
| `local/start.sh` | 依赖检测从「node_modules 在不在」改成**逐包实测 + `.agent-installed` 时间戳** | `npm install` 中途失败会留下半成品目录(目录在、包不全),原逻辑会永远跳过安装,core 起来就 require 失败 |
|
||
| `local/start.sh` | `npm install` 输出 `tee` 到 `local/.runtime/npm-install.log`,并嵌进状态页 | 失败时只有终端能看到,滚过去就没了 |
|
||
| `local/start.sh` | MCP 默认端口 3101~3104 → **8091~8094**;新增「PORT 撞 MCP 端口就拒绝启动」检查 | 跟 core 的 8090 连号,同时堵掉「换端口时不小心占用 MCP 端口」→ 子进程 bind 失败、静默降级 |
|
||
| `local/start.sh` | 已有配置里的 MCP 端口与本次启动不一致时**告警** | 配置永不覆盖,改了默认值/用了 `MCP_*_PORT` 时,旧配置会让 core 静默发现不到工具 |
|
||
| `local/start.sh` | 生成的 YAML 里路径**加引号** | 用户选的目录带空格/`:`/`#` 时会被 YAML 解析坏 |
|
||
| `local/start.sh` | 没 ffmpeg 时**不再启动** `mcp_asr`(原实现无条件启动,与 4.3 的设计说明不符) | 否则模型拿到一个必然失败的 `transcribe_audio` 工具;同时少一个 `0.0.0.0` 监听 |
|
||
| `local/start.sh` | 默认**后台化**(`AGENT_LOCAL_DETACH=1`),拉起启动器后 1 秒返回;新增 `local/stop.sh` | 用户不想让一个终端窗口永远挂着;Finder 里关窗口很容易误杀服务,后台 + 显式 `stop.sh` 更可控 |
|
||
| `local/start.sh` | 没 node 时在入口就拦下(生成配置之前),并在终端打出安装方式 | 原来先进「选工作目录」、写好配置才报「后台进程立刻退出了」,用户白选一次,而且日志里只有两行启动横幅,看不出原因 |
|
||
| `local/start.sh` | 同一轮只开一个状态页标签(`UI_OPENED`) | `ui_init` 已经开过一次,失败时 `ui_fail` 又开一个,同一个页面两个标签 |
|
||
| `local/start.sh` | 「已在运行」改看 `supervisor.pid`(pid 存活且命令行是本脚本),health 只做兜底 | 只看 health 时 core 还没起来的几秒内连跑两次,会拉起两个启动器抢同一端口(实测:互相 `EADDRINUSE` 重启,`stop.sh` 只能停一个) |
|
||
| `local/start.sh` | 首次安装**不自动跳转**,停在状态页给「打开应用」按钮;后续启动才 2 秒自动跳 | 首次装完先让用户看完「怎么配模型」再进去,别一上来就甩进空界面 |
|
||
| `app/server/tools/executor.js` | 新增 `dispPath()`:会话目录外用绝对路径回显 | 宽根模式下写 `/tmp/x` 会回 `../../../../tmp/x`,模型容易当会话内路径二次拼接 |
|
||
| `app/package-lock.json` | `resolved` 从腾讯云**内网镜像**改为公共 registry | 原 lockfile 把 tarball 钉在 `mirrors.tencentyun.com`(只有腾讯云 VPC 内能解析),外部机器 `npm install` 必失败,且换 `NPM_REGISTRY` 也无效 |
|
||
|
||
## 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_root: <仓库>/local/.runtime/skills`(首次生成后不覆盖),启动器每次都重建这个
|
||
软链,恒指向 `<仓库>/skills`。
|
||
|
||
早期版本在「没有 python3」时把它指向一个空目录,想的是“别让模型看到跑不了的工具”。两个问题:
|
||
|
||
1. **技能不一定是 Python 的**。`office` 只有 `SKILL.md` + `scripts/office`,模型在 `terminal` 里调
|
||
`office <cmd>`,完全不需要 python3——一刀切会把这类技能一并藏掉。
|
||
2. **没必要防**。`skills.js` 的 `runEntry` 对 `spawn` 的 `error` 有处理,缺解释器时模型拿到的是
|
||
「技能入口启动失败:spawn python3 ENOENT」,干净可读、不崩不挂。模型据此自己装解释器或模块,
|
||
装完继续跑即可。
|
||
|
||
所以现在只有一种行为:技能总是可见;python3 缺失只影响 `run.py` 类技能能否执行。装好 python3 后
|
||
(若在 core 启动时 `PATH` 已有的目录里,如 brew 的 `/opt/homebrew/bin`)无需重启即生效,否则重跑脚本。
|
||
|
||
**没有改 `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;本地同机必须错开(默认 **8091~8094**,紧跟 core 的 8090)。
|
||
另外**它们的启动参数不统一**,这是个坑:
|
||
|
||
| 服务 | 启动方式 | 说明 |
|
||
|---|---|---|
|
||
| `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`。
|
||
|
||
### 4.9 状态页:静态文件 + `meta refresh`,不起 HTTP 服务
|
||
|
||
启动时终端窗口不一定在前台,失败时也可能已经滚过去。所以启动就打开
|
||
`local/.runtime/status.html`,并让它能自己更新:
|
||
|
||
- 脚本把状态写进 `local/.runtime/ui/` 下的几个小文件(`title` / `steps` / `busy` / `logpath` /
|
||
`error` / `redirect`),`ui_render` 把它们拼成整页;页面用 `<meta http-equiv="refresh" content="1">`
|
||
每秒重读一次。不需要常驻服务,所以「连 node 都没装」的环境也能打开。
|
||
- 长步骤(`npm install`、等 core 健康检查)另起一个**心跳子进程**每秒重绘,页面上就能看到
|
||
已经过了多少秒 + 当前日志的尾巴(npm 输出、core 启动报错)。
|
||
- 状态全部落文件而不是留 shell 变量:心跳子进程拿到的是 fork 时的快照,用变量会越刷越旧。
|
||
- 成功时:**首次安装**(配置是本次刚生成的)页面停在「已启动」,只给一个「打开应用」按钮,
|
||
用户自己点(先看完下面的首次使用提示);**后续启动**写入 `redirect`,2 秒后自动进应用
|
||
(同一个标签页,不多开窗)。
|
||
- 失败时页面保留错误说明和日志尾部,并把完整日志路径写在页面上。
|
||
- 默认只在 macOS 自动弹出(`AGENT_LOCAL_UI=auto`),Linux 服务器上要显式 `AGENT_LOCAL_UI=1`;
|
||
无论弹不弹,页面都会生成。
|
||
- 渲染先写临时文件再 `mv`:浏览器随时可能在刷新,不能让它读到半截 HTML;临时名用 `mktemp`
|
||
而不是 `$$`——`$$` 在子 shell 里仍是主 shell 的 PID,心跳与主流程同时渲染会撞车。
|
||
|
||
### 4.10 依赖检测为什么不能只看 `node_modules` 目录
|
||
|
||
`npm install` 失败(断网、源不对)会留下一堆**空目录**:`app/node_modules` 在、`express` 目录
|
||
也在,但里面没东西。原逻辑「目录存在且不比 `package.json` 旧」会判定为已安装,以后每次启动
|
||
都跳过安装,core 起来立刻 `require` 失败——用户看到的是「装依赖那步过了,但服务起不来」。
|
||
|
||
现在的判定:
|
||
|
||
1. 逐个直接依赖检查 `node_modules/<dep>/package.json` 是否存在(比 `require.resolve` 可靠:
|
||
`@modelcontextprotocol/sdk` 这类纯 ESM 包的 `exports.require` 指向的文件根本不存在,
|
||
`require.resolve` 会误判成「没装」);
|
||
2. 装成功后 `touch node_modules/.agent-installed`,只有 `package.json` 比它新才重装
|
||
(npm 在「已经是最新」时不会更新 `node_modules` 的 mtime,只比目录 mtime 会每启动都白跑一次)。
|
||
|
||
### 4.11 后台化 + 显式 `stop.sh`,以及「已在运行」怎么判
|
||
|
||
用户不想为了跑一个本地服务永久占着一个终端窗口(而且关窗口可能连带杀掉进程)。所以:
|
||
|
||
- `start.sh` 自己**只做入口**:首次配置生成(要 tty 弹窗)→ `nohup` 拉起真正的启动器 → 1 秒后
|
||
打印地址/状态页/停止命令并 `exit 0`。`AGENT_LOCAL_DETACHED=1` 是子进程标记,防无限重入。
|
||
- 停止统一走 `local/stop.sh`。它按「`supervisor.pid` → core 的父进程 → 占端口的进程」三级兜底:
|
||
只杀 core 会被守护循环重新拉起,所以必须能认出**启动器**。命令行是相对路径(`sh ./local/start.sh`),
|
||
`pgrep -f` 匹配不到绝对路径,所以第一选择是 pid 文件。
|
||
- 前台模式保留:`AGENT_LOCAL_DETACH=0 ./local/start.sh`(看实时日志、`Ctrl-C` 停)。
|
||
|
||
「已在运行」的判定不能只看 `/api/health`:core 起来要几秒(先起 MCP,首次还要装依赖),
|
||
这期间再跟一次 `start.sh` 就会拉起第二个启动器,两个 core 抢同一个端口——一个被守护循环
|
||
反复 `EADDRINUSE` 重启,而 `stop.sh` 只认 pid 文件里那一个,等于停不干净(已实测复现)。
|
||
改成先看 `supervisor.pid`(子进程一启动就写,秒级就绪;`kill -0` + 命令行含 `start.sh` 防 pid 被回收),
|
||
health 只作为「端口上有服务但不是本启动器拉起的」兜底提示。
|
||
|
||
### 4.12 依赖安装:源探测 + 换源重试 + 本地缓存(只在 `local/` 里做)
|
||
|
||
首装联网是逃不掉的,但「哪个源能用、卡住了怎么办」不该让用户想。启动器的策略:
|
||
|
||
1. **已装齐 → 不联网**(逐包检查 + `.agent-installed` 时间戳,见 4.10);
|
||
2. **缓存命中 → 解压**:装成功后把 `node_modules` 打成
|
||
`<平台>-<架构>-abi<ABI>-<依赖哈希>.tgz` 放 `~/.cache/agent-local/`;原生模块与 ABI 绑定,
|
||
所以文件名必须含 ABI(`process.versions.modules`)。换 clone / 删 `node_modules` 都走这里,
|
||
秒级且零网络;只留最近 3 份。
|
||
3. **缓存未命中 → 选源安装**:并行探 `npmmirror` 与官方源(各 3 秒超时),取最快的;
|
||
结果缓存一天。**只用命令行参数传源,绝不写 `~/.npmrc`**。
|
||
4. **失败换源**:仅当用的是公共源(npmmirror / 官方)时换下一个重试,换源成功就记住;
|
||
用户显式指定或公司私有源不兜底(乱兜底可能装错东西)。重试前先删半成品 `node_modules`。
|
||
5. **看门狗**:npm 10 + Node 22 在断网时既不报错也不退出(已知的
|
||
`Exit handler never called`,实测卡死超过 2 分钟),所以每次 `npm install` 都带超时,
|
||
超时就 `SIGKILL` 整棵树再换源。
|
||
6. **报错翻译**:把 npm 原文归成「网络没通 / 缺编译工具链(`xcode-select --install`)/
|
||
没有写权限 / 源没响应」,状态页只显示这一句,原文仍完整落在 `npm-install.log`。
|
||
|
||
两个容易踩的实现细节(都踩过):
|
||
|
||
- `kill_tree` 不能把参数先赋给变量再递归:POSIX sh 没有局部变量,递归会覆盖它,回到外层
|
||
kill 的是子进程而不是原本那个。
|
||
- 看门狗只用 `SIGKILL`:先 `TERM` 会先干掉外壳让 npm 变成孤儿(`PPID=1`),`kill -0` 判不到,
|
||
再想硬杀就找不到它了。
|
||
|
||
### 4.13 Python 包:不预装,交给模型按提示词装进 `skills/deps`
|
||
|
||
服务器上技能依赖由 `agent-executor-init` 一次性装进 `skills/deps`(compose 再把它放进
|
||
`PYTHONPATH`)。本地没有这套东西,`start.sh` 也不去跑 pip——安装时机、镜像源、半成品清理
|
||
是另一整套逻辑,收益不抵成本。做法改成「缺了再装」:
|
||
|
||
- `start.sh` 起 core 时注入 `PYTHONPATH=<仓库>/skills/deps`(**原本就有**)与
|
||
`AGENT_SKILLS_DEPS=<仓库>/skills/deps`(新增,只为把路径交给模型)。
|
||
`terminal` 与技能子进程都继承 core 的 env,所以装进去的东西**下次运行就能 import**,不用重启。
|
||
- `templates/env-local.txt` 把原来的「永远不要自己装任何东西」改成「缺模块就装进
|
||
`$AGENT_SKILLS_DEPS` 再重试」——**只给路径,不给命令**,怎么装由模型自己决定。
|
||
技能失败时 stdout+stderr 是合并回给模型的,它能看到 `ModuleNotFoundError` 自己判断。
|
||
- 为什么给一个目录而不是让模型自己选:那个目录已经在 `PYTHONPATH` 里,装进去下次运行就能
|
||
import;而不指定位置的话,它很可能装到别处(或去改系统 Python)。pip 对 `--target` 的
|
||
PEP 668 拦截明确豁免(`pip/_internal/commands/install.py`),所以这条路在 Homebrew 那种
|
||
externally-managed 解释器上也走得通——但这话不写进提示词,交给模型自己判断。
|
||
- 缺 `python3` 本体时也放给模型自己处理:本地形态是「用户自己的机器 + 用户自己的 agent」,
|
||
目标是把事做成,而不是把它当生产环境保护。提示词只告诉它**装到哪**(Python 包进
|
||
`$AGENT_SKILLS_DEPS`),不写条件也不写禁令——要不要先知会用户,交给模型按场合自己判断。
|
||
- 技能自己的 `requirements.txt` 一律**不写版本号**:服务端 init 用
|
||
`pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会让探测失败 → 真的往
|
||
`skills/deps` 装一份旧的,而 `PYTHONPATH` 优先于系统 site-packages,等于反向遮蔽镜像包。
|
||
|
||
需要系统库的包(`weasyprint` → pango/cairo)pip 装不了,仍需用户 `brew install`;这类不在
|
||
自动修复范围内,模型只报结论。
|
||
|
||
### 4.14 `office` 本地化:平台矩阵 + PATH 直塞,不碰 `app/`
|
||
|
||
`office` 技能是 `SKILL.md` + `scripts/office`(Node 封装层)+ `bin/officecli`(.NET 单文件二进制)。
|
||
本地化只做两件小事:
|
||
|
||
- **PATH**:服务器上靠镜像里的 `/usr/local/bin/office` 软链;本地没 root 写不了系统目录,
|
||
`start.sh` 起 core 时把 `skills/office/scripts` 直接塞进 `PATH`(脚本自身可执行,不复制、不装软链)。
|
||
`terminal` 继承 core 的 env,模型调 `office <cmd>` 即命中。
|
||
- **二进制**:`install.sh` 改成按 `uname -s/-m` 选资产(linux x64/arm64、mac x64/arm64),
|
||
校验和 pin 到上游 release 的 `SHA256SUMS`(八个平台都有,不用猜);mac 没有 `sha256sum`,
|
||
用 `shasum -a 256` 兜底。但已经存在的二进制只要能跑就沿用:officecli 会把自己更新到上游
|
||
latest(实测 1.0.157 跑一次变 1.0.160,大小与 latest 资产完全一致),拿 pin 去比对只会反复
|
||
重拉 34MB。pin 因此只约束「本次下载的东西」;服务器上卷是 `:ro`,二进制不会漂,仍走 sha 比对。
|
||
**启动器不预下载**:首次用到时,封装层报错里带 `install.sh` 的绝对路径,
|
||
模型跑一次即可(~34MB,GitHub 慢时自动换 gh-proxy)。
|
||
|
||
没做的是预览:预览卡片要 executor 的 `:3100` 网关,本地没有。要补就相当于把
|
||
`executor/preview.js` 的槽位管理搬进 core,不值得。
|
||
|
||
## 5. 验证结果(macOS 12.7.6 / x86_64 / Node 22.21 / python3 3.10 / 本机无 ffmpeg)
|
||
|
||
静态检查:`sh -n local/start.sh`、`sh -n local/stop.sh`、`node --check` 均通过。
|
||
|
||
| 项 | 结果 |
|
||
|---|---|
|
||
| 首次启动:生成配置 → 装依赖(app 134 包,image_task / video_task 各 127 包)→ 起 MCP + core → 打开状态页(停在「已启动」,等点击) | 通过 |
|
||
| 配置内容:`workspace_root` 是选的目录、`data_root` 指仓库 `data/`、`skills_root` 指 `local/.runtime/skills`、`platforms: []`、MCP 端口 8091~8094 | 通过 |
|
||
| 绑定地址:`lsof` 只有 `127.0.0.1:8090` | 通过 |
|
||
| 设置页「重启」→ 守护拉起:PID 变化,2 秒内 `/api/health` 恢复 | 通过 |
|
||
| 文件工具越出会话目录:工作目录根的 `probe.txt` 可读 | 通过 |
|
||
| 越界保护:`read_file ~/.ssh/config`、`terminal cd /etc` 均报「路径越界」 | 通过 |
|
||
| `/tmp` 一致性:`write_file /tmp/x` → `terminal cat /tmp/x` 与 `read_file /tmp/x` 内容一致 | 通过 |
|
||
| 无 ffmpeg:`/api/asr/status` = `enabled:false`(麦克风隐藏),asr 子进程不启动,8094 不监听 | 通过 |
|
||
| 有 python3:Python 技能可执行;桩掉 python3 后技能清单不变(`/api/skills` 照常返回),执行 `run.py` 类技能报「技能入口启动失败:spawn python3 ENOENT」,`office` 这类非 Python 技能不受影响 | 待复测 |
|
||
| 四个 MCP 在具备条件时均能发现工具(`[mcp] web_search / image_task / video_task / asr: 发现 1 个工具`) | 通过 |
|
||
| 前台模式 `Ctrl-C` 与 `TERM`:8090 与 8091~8094 全部释放,无残留进程 | 通过 |
|
||
| 二次启动:沿用配置、跳过依赖安装(时间戳生效) | 通过 |
|
||
| 后台模式:`start.sh` 1 秒返回、启动器 PPID=1、`supervisor.pid` 是子进程 pid | 通过 |
|
||
| `stop.sh`:命中 pid 文件分支;pid 文件丢失时按 core 父进程/端口也能停;未运行时幂等返回 | 通过 |
|
||
| 重复执行 `start.sh`:打印「已在运行(启动器 pid N)」+ 停止命令,exit 0,不起第二个进程 | 通过 |
|
||
| 启动器被 `kill -9` 后的恢复:残留 pid 文件被清理,端口仍被占时明确提示先 `stop.sh` | 通过 |
|
||
| 依赖源自动探测:删依赖后启动,自动选中 `registry.npmmirror.com`(本机 npm 全局源也是它),状态页显示「依赖源」 | 通过 |
|
||
| 依赖缓存:装成功后生成 `~/.cache/agent-local/deps-...tgz`;删掉 `node_modules` 重启,日志为「使用本地依赖缓存」、`npm-install.log` 为空(零网络) | 通过 |
|
||
| 换源自愈:把缓存里的源改成不可达地址 → 看门狗超时 → 自动换到 npmmirror 装完,缓存里的源被改回可用值 | 通过 |
|
||
| 失败翻译:源不可用 + 冷 npm 缓存 → 状态页标题「依赖安装失败」、提示「源没有响应…(已自动换源重试)」,无 npm 残留进程 | 通过 |
|
||
| 前台模式 `AGENT_LOCAL_DETACH=0`:阻塞运行,`TERM` 后端口全部释放 | 通过 |
|
||
| 无 node(PATH 里剥掉 node/npm):入口直接拦下,**不** 先让选目录、不生成配置;终端打出安装方式;状态页列出自检项(X Node.js / X npm) | 通过 |
|
||
| 失败时只开一个状态页标签(不再两个) | 通过 |
|
||
| 状态页:启动即弹出、每秒刷新、显示步骤/计时/日志尾巴;失败时保留错误与日志 | 通过 |
|
||
| `osascript` 真实选目录弹窗 | 未验证(用桩跑的「没选→回落 `~/AgentWork`」分支) |
|
||
| 真浏览器打开(`open`) | 未验证(用桩记录了被打开的 URL) |
|
||
| 装 ffmpeg 之后:`ASR_URL` 注入、asr 子进程与麦克风一起出现 | 未验证(本机未装 ffmpeg) |
|
||
|
||
验证过程中发现并修掉的问题见 3.1(依赖检测、lockfile 内网源、`asr` 无条件启动、端口冲突、
|
||
状态页日志缺失、全角字符紧贴变量名导致的 `unbound variable`)。
|
||
|
||
## 6. 还没覆盖的三项(需要人工交互或外部环境)
|
||
|
||
其余清单已在 mac 上跑完(结果见第 5 节)。剩下这三项要在真实场景里补:
|
||
|
||
1. **真实选目录弹窗**:删掉 `local/config.local.yml` 后跑 `./local/start.sh`,确认弹出的是 macOS 原生
|
||
选目录窗、选完的路径写进 `workspace_root`(带空格的目录名要顺手验一下,配置里已加引号)。
|
||
2. **真浏览器打开**:跑 `./local/start.sh`(或前台模式),确认(a)状态页在启动过程中每秒刷新;
|
||
(b)首次安装停在页面上等你点「打开应用」;(c)后续启动 2 秒自动进应用。
|
||
3. **装 ffmpeg 之后**:`brew install ffmpeg` → 重跑脚本,预期:状态页显示 `ffmpeg` 为 OK、
|
||
终端打「语音:可用」、8094 开始监听、`/api/asr/status` 变成需要填上游(不再是「未设置 ASR_URL」)。
|
||
|
||
手工复验用的命令:
|
||
|
||
```bash
|
||
./local/start.sh # 后台启动(1 秒返回)
|
||
./local/stop.sh # 停止(幂等)
|
||
./local/start.sh # 已在运行时只打印地址与停止方式
|
||
lsof -nP -iTCP:8090 -sTCP:LISTEN # 应只有 127.0.0.1
|
||
lsof -nP -iTCP:8091-8094 -sTCP:LISTEN # 3 或 4 个 MCP(没 ffmpeg 时没有 8094)
|
||
curl -s http://127.0.0.1:8090/api/asr/status
|
||
curl -s -X POST http://127.0.0.1:8090/api/system/restart # 应由守护拉起
|
||
tail -f local/.runtime/core.log # 以及 npm-install.log / mcp-*.log
|
||
```
|
||
|
||
## 7. 已知限制(都不打算在本次解决)
|
||
|
||
| 限制 | 说明 |
|
||
|---|---|
|
||
| **无沙箱** | AI 的 `terminal` 就是本机 shell,能读 `~/.ssh` 等一切。这是「给它一个目录就放开手脚」的代价;README 已提示「专用目录 + `git init`」 |
|
||
| 没 ffmpeg 时 asr 会报「工具发现失败」 | 此时 `mcp_asr` 不启动(它转码依赖 ffmpeg),但配置里的 asr 条目仍在(配置不覆盖),所以 core 启动会 warn 一次并重试,属预期 |
|
||
| `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` 为空,工具会回明确的「未配置」错误 |
|
||
| 技能依赖 | 本地不预装:缺包时模型会把包装进 `skills/deps`(`$AGENT_SKILLS_DEPS`,已在该进程 `PYTHONPATH` 里,装完下次运行即生效);连 `python3` 都没有时也由它自己装。怎么装由模型自己决定。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 |
|
||
| `office` 二进制 | 不入库、镜像阶段不下载:首次用到时由模型按报错提示跑一次 `skills/office/install.sh`(按 `uname` 选 linux/mac 资产,下载时校验和 pin 到上游 `SHA256SUMS`,约 34MB;GitHub 慢时自动换 gh-proxy)。不需要 root,装完不需重启。officecli 会自更新到上游 latest,版本比 pin 新属正常 |
|
||
| `office` 预览 | 预览卡片走 core → executor 的 `:3100` 网关,本地没有这个网关 → 点开打不开。文档创建/编辑/读取不受影响 |
|
||
| 首个 `npm install` 要联网 | 支持 `NPM_REGISTRY` 覆盖源;`app/package-lock.json` 的 `resolved` 已改指向公共 registry(原来钉在内网镜像,外部机器必失败) |
|
||
|
||
## 8. 回滚
|
||
|
||
本地模式的所有开关默认关闭,服务器行为不变。真要整体撤掉:
|
||
|
||
```bash
|
||
git revert <本次提交>
|
||
rm -rf local/ # 或保留脚本、只是不用
|
||
```
|
||
|
||
`v2.5.0` 是这批改动之前的基线,可随时对照。
|
||
|
||
## 9. 记录:测试残留(都不入库)
|
||
|
||
跑过启动器之后本机会多出:`local/.runtime/`(日志、状态页、技能软链)、
|
||
`local/config.local.yml`、`~/AgentWork/`、`app/node_modules/`、`mcp/image_task|video_task/node_modules/`。
|
||
全部在 gitignore 内,不影响仓库;想彻底重来就把它们删掉再跑脚本(会话产出在 `data/` 与
|
||
工作目录下的 `task-*` 里,不会被清)。
|
||
|
||
## 10. 新建会话手选工作目录(本地端)
|
||
|
||
默认每个会话落在 `workspace_root/<会话id>`(形如 `task-YYYYMMDD-NNN`)。本地端希望「给它一个
|
||
目录就放开手脚」,所以新建会话时可以手选一个真实目录,这个会话的 AI 一切操作都在那儿。
|
||
|
||
**后端只动 `taskDirOf` 一处**(`engine.js`):
|
||
|
||
```js
|
||
taskDirOf(sessionId) = sessions.work_dir || path.join(workspace_root, sessionId)
|
||
```
|
||
|
||
全仓库的会话路径(文件 API、上传、`terminal` 的 cwd、`resolveInTask` 基准、data-page、
|
||
`@会话` 只读)都经由它,所以改这一处即全线生效,不必逐个路由改。
|
||
|
||
- 选择只存前端(`pendingWorkDir`),建档时随 `POST /api/sessions` 提交一次;不选 = 空串 = 老行为。
|
||
- **不建 `task-*` 子目录**,直接以所选目录为工作目录(隐藏产物 `.tmp`/`.imgcache`/`.app`/`data.db` 落在这里)。
|
||
- 允许多个会话选同一目录;**删会话绝不删该目录**(`deleteSession` 只在 `work_dir` 为空时才 `rmSync`)。
|
||
- `fsRoot` 优先返回 `ctx.workDir`;`@<会话>` 也按目标会话的 `work_dir` 解析(`resolvePastPath`)。
|
||
- 目录选择器:`routes/local.js` 用 `osascript`(mac)/ `zenity`/`kdialog`(Linux)弹原生窗口,
|
||
**仅 `AGENT_LOCAL_PICK=1` 时挂载**(`server.js`),服务器形态 `/api/local/*` 一律 404,前端整条入口隐藏。
|
||
必须 `execFile` 异步:同步会阻塞事件循环、卡住所有 SSE。
|
||
- 只接受已存在的目录(`normalizeWorkDir` 校验真实路径),并拒绝根目录 `/` 与平台数据目录。
|
||
- 服务器形态:前端从不传 `work_dir`,`work_dir` 列恒为空,行为与旧版完全一致。
|