Files
agent/docs/local-mode.md
T
kicer a7eecdbe97 feat(local): 技能不再因缺 python3 整体隐藏;缺解释器时先问用户再装
A1:link_skills 恒指向仓库 skills。原来没有 python3 就把 skills_root 指到空目录,
把所有技能一起藏掉——但技能不一定是 Python 的(office 是 SKILL.md + terminal 里调
officecli,跟 python3 无关),一刀切会误伤。而 run.py 类技能缺解释器时 skills.js
的 runEntry 对 spawn error 有处理,模型拿到「技能入口启动失败:spawn python3 ENOENT」,
干净可读,不需要靠藏清单避险。状态页/终端文案同步改成「python3 未安装:Python 技能
会失败,非 Python 技能不受影响」。

B2:env-local 允许模型装运行时,但必须先问用户;仍禁止 sudo 与装系统包。
macOS 的 /usr/bin/python3 是 CLT 桩,真装要走 brew 或官方安装器,耗时长且可能改
PATH / 要管理员权限,这种改动不能默许自主执行。

文档同步:docs/local-mode 4.4 重写(记录为什么不再切换)、4.13 补 B2 理由、
验证表该行标为待复测;local/README 的可选能力表与已知限制同步。
2026-11-11 17:07:20 +08:00

395 lines
30 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/` 的设计说明 + 交接单。
> **状态:已在 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` 本体时:提示词允许模型装运行时,但**必须先问用户**(`ask the user before
installing a runtime`)。理由:macOS 的 `/usr/bin/python3` 是 Xcode CLT 的桩,真装要走 brew
或官方安装器,耗时长且可能改 `PATH`/要管理员权限——这种级别的改动不能默许模型自主做。
同时仍然禁止 `sudo` 与装系统包。
- 技能自己的 `requirements.txt` 一律**不写版本号**:服务端 init 用
`pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会让探测失败 → 真的往
`skills/deps` 装一份旧的,而 `PYTHONPATH` 优先于系统 site-packages,等于反向遮蔽镜像包。
需要系统库的包(`weasyprint` → pango/cairo)pip 装不了,仍需用户 `brew install`;这类不在
自动修复范围内,模型只报结论。
## 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` 处理 |
| 首个 `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` 列恒为空,行为与旧版完全一致。