新增本地端(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:
@@ -7,6 +7,9 @@ data/
|
||||
tasks/
|
||||
skills/deps/
|
||||
skills/*/.deps_installed
|
||||
# 本地端(local/):运行期产物与生成的配置都不入库(含密钥,见 local/README.md)
|
||||
local/.runtime/
|
||||
local/config.local.yml
|
||||
# officecli 二进制资产:skills/office/install.sh 运行期拉取,不进 git
|
||||
skills/office/bin/
|
||||
skills/**/__pycache__/
|
||||
|
||||
@@ -169,6 +169,9 @@ app.get('/api/health', (req, res) => {
|
||||
});
|
||||
|
||||
const PORT = process.env.PORT || cfg.port;
|
||||
// 监听地址:不设 = 0.0.0.0(容器/服务器形态,宿主机端口映射靠它)。
|
||||
// 本机 local 模式由 local/start.sh 注入 HOST=127.0.0.1:单机自用不该让同一局域网的人直接访问。
|
||||
const HOST = String(process.env.HOST || '').trim();
|
||||
|
||||
// 启动成功后把模型实际收到的各部分 dump 到文件方便人工核对(data_root 默认 ./data,
|
||||
// 宿主机对应 <repo>/data/prompt.txt,已被 gitignore)。包含:
|
||||
@@ -211,8 +214,8 @@ mcp.init(cfg).then(async () => {
|
||||
} catch (e) {
|
||||
log.warn('startup', '技能列表生成失败:' + e.message);
|
||||
}
|
||||
server.listen(PORT, () => {
|
||||
log.info('startup', 'Agent server listening on ' + PORT);
|
||||
const onListening = () => {
|
||||
log.info('startup', 'Agent server listening on ' + (HOST ? HOST + ':' : '') + PORT);
|
||||
log.info('startup', ' public_link=' + ((cfg.public_link || {}).base_url || '未配置(mint_public_link 不可用)'));
|
||||
log.info('startup', ' workspace_root=' + cfg.workspace_root);
|
||||
log.info('startup', ' data_root=' + cfg.data_root);
|
||||
@@ -231,7 +234,9 @@ mcp.init(cfg).then(async () => {
|
||||
} catch (e) {
|
||||
log.warn('startup', 'prompt dump 失败:' + e.message);
|
||||
}
|
||||
});
|
||||
};
|
||||
if (HOST) server.listen(PORT, HOST, onListening);
|
||||
else server.listen(PORT, onListening);
|
||||
});
|
||||
|
||||
// 优雅退出(照抄 executor/server.js 的 shutdown 形态):node 在容器里是 PID 1,
|
||||
|
||||
@@ -19,26 +19,49 @@ const memory = require('../memory'); // recall 工具的数据面(日记翻阅
|
||||
const BUILTIN_TOOL_DEFS = require('./definitions.json');
|
||||
|
||||
// ---------- 路径沙箱 ----------
|
||||
function resolveInTask(taskDir, p) {
|
||||
// 文件工具的可见范围(AGENT_FILE_SCOPE,默认 session):
|
||||
// session = 锁在会话目录。与 executor 容器里的物理视图一致,是服务器形态。
|
||||
// workspace= 放宽到 workspace_root。本地桌面端形态(不起 executor、单机单用户):
|
||||
// AI 要能操作你指定的整个工作目录,而不是它的一个子目录。
|
||||
// 纯 env 接线与 EXECUTOR_URL/ASR_URL 同类:这是部署形态,不是平台配置。
|
||||
const WIDE_SCOPE = String(process.env.AGENT_FILE_SCOPE || '').trim().toLowerCase() === 'workspace';
|
||||
|
||||
function resolveInTask(taskDir, p, rootDir) {
|
||||
if (typeof p !== 'string' || !p.trim()) throw new Error('路径不能为空');
|
||||
const taskRoot = path.resolve(taskDir);
|
||||
let abs;
|
||||
if (path.isAbsolute(p)) {
|
||||
abs = path.normalize(p);
|
||||
// /tmp → <taskDir>/.tmp:与 executor 容器的 bind 对齐(容器内 /tmp 即会话 .tmp,
|
||||
// terminal 写 /tmp/x,core 侧实体在 <taskDir>/.tmp/x)。先 normalize 再重写,
|
||||
// 重写后仍走下方越界校验,无穿越风险。
|
||||
if (abs === '/tmp') abs = path.join(path.resolve(taskDir), '.tmp');
|
||||
else if (abs.startsWith('/tmp/')) abs = path.join(path.resolve(taskDir), '.tmp', abs.slice(5));
|
||||
// workspace 形态【不重写】:本地 terminal 是真 spawn,写的就是本机 /tmp,
|
||||
// 两边必须指向同一处——否则 AI 自己刚写到 /tmp 的文件,自己 read_file 读不到。
|
||||
if (!WIDE_SCOPE) {
|
||||
if (abs === '/tmp') abs = path.join(taskRoot, '.tmp');
|
||||
else if (abs.startsWith('/tmp/')) abs = path.join(taskRoot, '.tmp', abs.slice(5));
|
||||
}
|
||||
} else {
|
||||
abs = path.resolve(taskDir, p);
|
||||
// 相对路径永远相对会话目录(AI 的 cwd 就在那里),不随 rootDir 漂移。
|
||||
abs = path.resolve(taskRoot, p);
|
||||
}
|
||||
const root = path.resolve(taskDir);
|
||||
if (abs !== root && !abs.startsWith(root + path.sep)) {
|
||||
throw new Error('路径越界(只允许任务目录内操作):' + p);
|
||||
const root = path.resolve(rootDir || taskRoot);
|
||||
const inRoot = abs === root || abs.startsWith(root + path.sep);
|
||||
// workspace 形态额外放行本机 /tmp:AI 与 terminal 共用的临时区。
|
||||
const inTmp = WIDE_SCOPE && (abs === '/tmp' || abs.startsWith('/tmp/'));
|
||||
if (!inRoot && !inTmp) {
|
||||
throw new Error((rootDir ? '路径越界(只允许工作目录内操作):' : '路径越界(只允许任务目录内操作):') + p);
|
||||
}
|
||||
return abs;
|
||||
}
|
||||
|
||||
// 工具层允许的根:session 形态 = 会话目录;workspace 形态 = workspace_root。
|
||||
// 只给「业务工具」用;路由层(文件 API/公网短链/data-page)与 @历史会话仍按会话目录校验。
|
||||
function fsRoot(ctx) {
|
||||
if (!WIDE_SCOPE) return ctx.taskDir;
|
||||
return (ctx.cfg && ctx.cfg.workspace_root) || ctx.taskDir;
|
||||
}
|
||||
|
||||
function relOf(taskDir, abs) {
|
||||
return path.relative(path.resolve(taskDir), abs) || '.';
|
||||
}
|
||||
@@ -284,7 +307,7 @@ async function toolReadFile(ctx, args) {
|
||||
const inner = relOf(past.dir, abs);
|
||||
disp = inner === '.' ? '@' + past.sid : '@' + past.sid + '/' + inner;
|
||||
} else {
|
||||
abs = resolveInTask(ctx.taskDir, args.path);
|
||||
abs = resolveInTask(ctx.taskDir, args.path, fsRoot(ctx));
|
||||
// 本会话沿用绝对路径做展示(大纲/首 1KB 头,历史行为不变);历史会话只暴露 @<sid>/<rel> 形,
|
||||
// 不把别的会话的 workspace_root 绝对路径喂进上下文。
|
||||
disp = abs;
|
||||
@@ -370,7 +393,7 @@ async function toolListDirectory(ctx, args) {
|
||||
const inner = relOf(past.dir, abs);
|
||||
prefix = '@' + past.sid + (inner === '.' ? '/' : '/' + inner + '/');
|
||||
} else {
|
||||
abs = resolveInTask(ctx.taskDir, p || '.');
|
||||
abs = resolveInTask(ctx.taskDir, p || '.', fsRoot(ctx));
|
||||
const inner = relOf(ctx.taskDir, abs);
|
||||
prefix = inner === '.' ? '' : inner + '/';
|
||||
}
|
||||
@@ -408,14 +431,15 @@ async function toolCopyPath(ctx, args) {
|
||||
const dp = String(args.destination_path || '').trim();
|
||||
if (!sp || !dp) throw new Error('source_path 与 destination_path 都必填');
|
||||
if (dp.startsWith('@')) throw new Error('destination_path 不支持 @ (历史只读)');
|
||||
const dst = resolveInTask(ctx.taskDir, dp);
|
||||
if (path.resolve(dst) === path.resolve(ctx.taskDir)) throw new Error('destination_path 不能是任务目录本身');
|
||||
const root = fsRoot(ctx);
|
||||
const dst = resolveInTask(ctx.taskDir, dp, root);
|
||||
if (path.resolve(dst) === path.resolve(root)) throw new Error('destination_path 不能是任务目录本身');
|
||||
let src;
|
||||
if (sp.startsWith('@')) {
|
||||
const past = resolvePastPath(ctx, sp);
|
||||
src = past.abs;
|
||||
} else {
|
||||
src = resolveInTask(ctx.taskDir, sp);
|
||||
src = resolveInTask(ctx.taskDir, sp, root);
|
||||
}
|
||||
if (path.resolve(src) === path.resolve(dst)) throw new Error('源与目标相同');
|
||||
let lst;
|
||||
@@ -445,7 +469,7 @@ async function toolCopyPath(ctx, args) {
|
||||
|
||||
async function toolWriteFile(ctx, args) {
|
||||
if (String(args.path || '').trim().startsWith('@')) throw new Error('write_file 不支持 @ 路径(历史只读;要改旧成果先 copy_path 导入本会话)');
|
||||
const abs = resolveInTask(ctx.taskDir, args.path);
|
||||
const abs = resolveInTask(ctx.taskDir, args.path, fsRoot(ctx));
|
||||
// 纵深防御:引擎 checkToolArgs 已把 null 判缺,但直调 executor(测试等)不经过它;
|
||||
// 旧版 `?? ''` 会把 null 洗成空串静默清空已有文件,这里显式拒绝。
|
||||
if (args.content == null) throw new Error('write_file 缺少参数 content(写空文件请显式传空字符串 "")');
|
||||
@@ -686,7 +710,7 @@ function applyEdit(text, edit, i) {
|
||||
// 错误信息告知模型已应用了多少、需重新 read_file。
|
||||
async function toolEditFile(ctx, args) {
|
||||
if (String(args.path || '').trim().startsWith('@')) throw new Error('edit_file 不支持 @ 路径(历史只读;要改旧成果先 copy_path 导入本会话)');
|
||||
const abs = resolveInTask(ctx.taskDir, args.path);
|
||||
const abs = resolveInTask(ctx.taskDir, args.path, fsRoot(ctx));
|
||||
let st;
|
||||
try { st = await fsp.stat(abs); }
|
||||
catch (_) { throw new Error('文件不存在:' + args.path); }
|
||||
@@ -751,7 +775,7 @@ async function toolTerminal(ctx, args) {
|
||||
const timeout = args.timeout_ms || cfg.terminal.default_timeout_ms;
|
||||
const maxChars = cfg.terminal.max_output_chars;
|
||||
let cwd = ctx.taskDir;
|
||||
if (args.cd) cwd = resolveInTask(ctx.taskDir, args.cd);
|
||||
if (args.cd) cwd = resolveInTask(ctx.taskDir, args.cd, fsRoot(ctx));
|
||||
if (!fs.existsSync(cwd)) throw new Error('工作目录不存在:' + cwd);
|
||||
|
||||
// 配了 executor.url(或 env EXECUTOR_URL):命令交给远端 agent-executor 执行,文本拼回与本地完全一致。
|
||||
@@ -1166,9 +1190,13 @@ function recordFile(ctx, abs) {
|
||||
try {
|
||||
const st = fs.statSync(abs);
|
||||
if (!st.isFile()) return;
|
||||
// 宽根模式(本地)下写在会话目录之外的文件不进附件表:表里的 filename 是会话相对路径,
|
||||
// 存个 '../x' 会让前端按会话去取,最终只能拿到 400。
|
||||
const rel = relOf(ctx.taskDir, abs);
|
||||
if (rel === '..' || rel.startsWith('..' + path.sep)) return;
|
||||
ctx.db.prepare(
|
||||
'INSERT INTO files (session_id, filename, size, created_at) VALUES (?,?,?,?)'
|
||||
).run(ctx.sessionId, relOf(ctx.taskDir, abs), st.size, Date.now());
|
||||
).run(ctx.sessionId, rel, st.size, Date.now());
|
||||
} catch (_) { /* 文件表仅用于展示,失败不影响主流程 */ }
|
||||
}
|
||||
|
||||
|
||||
@@ -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 不会有这些。
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
# 本地端(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`——那是个静态页,
|
||||
所以改完环境要自己重跑脚本(它不会自动重试)。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 本机 local 模式的配置参考。
|
||||
#
|
||||
# ⚠️ 这个文件不会被读取,只是给人看的样板:真正的配置由 local/start.sh 首次运行时
|
||||
# 生成到 local/config.local.yml(含你选的工作目录与分配好的端口)。
|
||||
# 想看自己机器上实际生成成什么样,启动一次后直接打开 local/config.local.yml。
|
||||
#
|
||||
# 字段含义与服务器版完全一致(见 app/config.example.yml);下面只列 local 模式实际用到的那部分。
|
||||
|
||||
port: 8090
|
||||
|
||||
# AI 的工作根。local 模式注入 AGENT_FILE_SCOPE=workspace 后,文件工具可读写这个目录下任何位置。
|
||||
workspace_root: /Users/you/AgentWork
|
||||
|
||||
# SQLite(.agent.db)与启动 prompt dump。默认指到仓库里的 data/(已在 .gitignore)。
|
||||
data_root: /path/to/agent/data
|
||||
|
||||
skills:
|
||||
# 指向 local/.runtime/skills —— 启动脚本按「python3 是否可用」把它软链到真技能目录或空目录,
|
||||
# 因此装不装 python3 都不需要改这里,改完重跑启动脚本即生效。
|
||||
skills_root: /path/to/agent/local/.runtime/skills
|
||||
|
||||
# 留空:启动后到设置页添加平台与 API Key,再点「重启」(启动器负责把进程拉起来)。
|
||||
platforms: []
|
||||
|
||||
log_level: info
|
||||
|
||||
mcp_servers:
|
||||
# 四个同栈 MCP 由启动器在本机拉起,端口与 start.sh 里的常量对应。
|
||||
# web_search 不需要任何密钥(内置免费后端);其余三个的上游参数在设置页卡片里填,
|
||||
# 会写进对应条目的 headers。
|
||||
- name: web_search
|
||||
url: "http://127.0.0.1:3101/"
|
||||
- name: image_task
|
||||
url: "http://127.0.0.1:3102/mcp"
|
||||
mode: skill
|
||||
- name: video_task
|
||||
url: "http://127.0.0.1:3103/mcp"
|
||||
mode: skill
|
||||
- name: asr
|
||||
url: "http://127.0.0.1:3104/mcp"
|
||||
mode: skill
|
||||
# 例:填了这两项才算启用语音(缺 X-ASR-Base-Url 时 /api/asr/status 返回 enabled:false,麦克风自动隐藏)
|
||||
# headers:
|
||||
# Authorization: Bearer <key>
|
||||
# X-ASR-Base-Url: "https://<host>/v1"
|
||||
# X-ASR-Model: "whisper-1"
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
#!/bin/sh
|
||||
# macOS 双击入口:在 Finder 里双击本文件,会用「终端」打开并执行 ../local/start.sh。
|
||||
#
|
||||
# 为什么不直接 exec:脚本失败时要留窗口给人看错误(双击启动的窗口默认一退出就关)。
|
||||
# 为什么要补 PATH:双击启动的进程不继承登录 shell 的环境,Homebrew 装的 node/ffmpeg
|
||||
# 常常不在默认 PATH 里(Apple Silicon 是 /opt/homebrew,Intel 是 /usr/local)。
|
||||
cd "$(dirname "$0")/.." || exit 1
|
||||
PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
|
||||
export PATH
|
||||
|
||||
./local/start.sh
|
||||
code=$?
|
||||
if [ "$code" -ne 0 ] && [ -t 0 ]; then
|
||||
printf '\n按回车关闭窗口…'
|
||||
read -r _
|
||||
fi
|
||||
exit "$code"
|
||||
Executable
+450
@@ -0,0 +1,450 @@
|
||||
#!/bin/sh
|
||||
# local/start.sh —— 本机(macOS / Linux)一键启动 agent-core。
|
||||
#
|
||||
# 这个脚本只负责「把容器部署的形状换成本机形状」,不改任何业务逻辑:
|
||||
# 1. 探测环境(node 必需;ffmpeg 决定能不能语音;python3 决定技能可不可用)
|
||||
# 2. 首次运行:选工作目录 + 生成 local/config.local.yml
|
||||
# 3. 起 core(+ 四个同栈 MCP 子进程),就绪后打开浏览器
|
||||
# 4. 守护:core 退出就拉起来
|
||||
#
|
||||
# 第 4 步是必须的,不是锦上添花:设置页的「重启」按钮实现是 process.exit(0),
|
||||
# 原本靠 Docker 的 restart 策略把容器拉起来(routes/system.js 注释写明「非 docker 部署不会自动拉起」)。
|
||||
# 本地没有 Docker,没有这个循环,用户配完模型一点重启,服务就再也回不来了。
|
||||
#
|
||||
# 为什么用 POSIX sh 写:macOS 自带的是 bash 3.2(2007 年),没有关联数组等语法,
|
||||
# 当作 sh 跑最稳,Linux 上也一样。
|
||||
set -u
|
||||
|
||||
HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
|
||||
ROOT=$(CDPATH= cd -- "$HERE/.." && pwd)
|
||||
RUNTIME="$HERE/.runtime"
|
||||
CONFIG="$HERE/config.local.yml"
|
||||
LOG="$RUNTIME/core.log"
|
||||
|
||||
PORT="${PORT:-8090}"
|
||||
HOST_ADDR="127.0.0.1"
|
||||
NPM_REGISTRY="${NPM_REGISTRY:-}"
|
||||
|
||||
# 四个同栈 MCP 服务在服务器上是各自独立的容器,都监听 3000 也不冲突;
|
||||
# 本地挤在同一台机器上,必须各占一个端口。
|
||||
MCP_WEB_PORT="${MCP_WEB_PORT:-3101}"
|
||||
MCP_IMAGE_PORT="${MCP_IMAGE_PORT:-3102}"
|
||||
MCP_VIDEO_PORT="${MCP_VIDEO_PORT:-3103}"
|
||||
MCP_ASR_PORT="${MCP_ASR_PORT:-3104}"
|
||||
|
||||
mkdir -p "$RUNTIME" "$ROOT/data"
|
||||
printf '\n==== %s 启动 ====\n' "$(date '+%Y-%m-%d %H:%M:%S')" >> "$LOG"
|
||||
|
||||
if [ -t 1 ]; then C='\033[1;32m'; Y='\033[1;33m'; N='\033[0m'; else C=''; Y=''; N=''; fi
|
||||
say() { printf "${C}==>${N} %s\n" "$*"; }
|
||||
warn() { printf "${Y}[!]${N} %s\n" "$*"; }
|
||||
|
||||
# ---------- 探测 ----------
|
||||
NODE_VER=''
|
||||
NODE_OK=0
|
||||
if command -v node >/dev/null 2>&1; then
|
||||
NODE_VER=$(node -v 2>/dev/null || echo '')
|
||||
# 用真跑一次判定而不是只看版本字符串:确保这个 node 是可执行的。
|
||||
if node -e 'process.exit(parseInt(process.versions.node, 10) >= 20 ? 0 : 1)' >/dev/null 2>&1; then
|
||||
NODE_OK=1
|
||||
fi
|
||||
fi
|
||||
|
||||
NPM_OK=0
|
||||
command -v npm >/dev/null 2>&1 && NPM_OK=1
|
||||
|
||||
# macOS 的 /usr/bin/python3 是 Xcode 命令行工具的桩:文件存在,但没装 CLT 时一执行就弹安装窗。
|
||||
# 所以必须真跑一句,command -v 会骗人。
|
||||
PY_OK=0
|
||||
PY_VER=''
|
||||
if command -v python3 >/dev/null 2>&1 && python3 -c 'import sys' >/dev/null 2>&1; then
|
||||
PY_OK=1
|
||||
PY_VER=$(python3 -c 'import sys;print("%d.%d"%sys.version_info[:2])' 2>/dev/null || echo '')
|
||||
fi
|
||||
|
||||
FF_OK=0
|
||||
FF_VER=''
|
||||
if command -v ffmpeg >/dev/null 2>&1 && ffmpeg -version >/dev/null 2>&1; then
|
||||
FF_OK=1
|
||||
FF_VER=$(ffmpeg -version 2>/dev/null | head -n 1 | sed -e 's/^ffmpeg version //' -e 's/ .*//')
|
||||
fi
|
||||
|
||||
PORT_FREE=1
|
||||
if [ "$NODE_OK" = 1 ]; then
|
||||
node -e 'const net=require("net"),s=net.createServer();s.once("error",()=>process.exit(1));s.listen(Number(process.argv[1]),"127.0.0.1",()=>s.close(()=>process.exit(0)))' "$PORT" >/dev/null 2>&1 || PORT_FREE=0
|
||||
fi
|
||||
|
||||
case "$(uname -s)" in
|
||||
Darwin) NODE_HINT='<code>brew install node@20</code>,或到 nodejs.org 下载 macOS 安装包';;
|
||||
*) NODE_HINT='用 nvm 安装(<code>nvm install 20</code>),或发行版包管理器装 nodejs 20+';;
|
||||
esac
|
||||
|
||||
# ---------- 自检页(纯静态,无 node 也能打开) ----------
|
||||
html_escape() {
|
||||
printf '%s' "$1" | sed -e 's/&/\&/g' -e 's/</\</g' -e 's/>/\>/g'
|
||||
}
|
||||
|
||||
open_target() {
|
||||
if command -v open >/dev/null 2>&1; then open "$1" >/dev/null 2>&1 || true
|
||||
elif command -v xdg-open >/dev/null 2>&1; then xdg-open "$1" >/dev/null 2>&1 || true
|
||||
fi
|
||||
}
|
||||
|
||||
setup_head() {
|
||||
# $1 标题 $2 建议(可含 HTML)
|
||||
cat > "$RUNTIME/setup.html" <<EOF
|
||||
<!doctype html>
|
||||
<html lang="zh-CN"><head><meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<title>$(html_escape "$1")</title>
|
||||
<style>
|
||||
:root{color-scheme:light dark}
|
||||
*{box-sizing:border-box}
|
||||
body{margin:0;padding:44px 22px;font:15px/1.7 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:#f5f6f8;color:#20242a}
|
||||
main{max-width:820px;margin:0 auto;background:#fff;border-radius:14px;padding:28px 30px;box-shadow:0 2px 14px rgba(0,0,0,.07)}
|
||||
h1{font-size:20px;margin:0 0 6px}
|
||||
.hint{margin:0 0 20px;color:#4a5563}
|
||||
table{width:100%;border-collapse:collapse;font-size:14px}
|
||||
th,td{text-align:left;padding:9px 10px;border-bottom:1px solid #eceef1;vertical-align:top}
|
||||
th{color:#6b7480;font-weight:600;font-size:12.5px;text-transform:uppercase;letter-spacing:.04em}
|
||||
td:first-child{width:120px;white-space:nowrap}
|
||||
.s-ok{color:#1a7f37;font-weight:600;white-space:nowrap}
|
||||
.s-bad{color:#c0392b;font-weight:600;white-space:nowrap}
|
||||
.s-warn{color:#9a6700;font-weight:600;white-space:nowrap}
|
||||
code{background:#f0f2f5;border-radius:5px;padding:1px 5px;font-size:12.5px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;-webkit-user-select:all;user-select:all}
|
||||
.note{margin:20px 0 0;padding-top:16px;border-top:1px solid #eceef1;color:#4a5563;font-size:14px}
|
||||
.tip{margin:16px 0 0;color:#6b7480;font-size:13px}
|
||||
@media (prefers-color-scheme:dark){
|
||||
body{background:#16181d;color:#e6e8eb}
|
||||
main{background:#1d2026;box-shadow:none}
|
||||
.hint,.note{color:#a8b1bd}
|
||||
th,td{border-color:#2b3038}
|
||||
code{background:#2a2f38}
|
||||
}
|
||||
</style></head><body><main>
|
||||
<h1>$(html_escape "$1")</h1>
|
||||
<p class="hint">$2</p>
|
||||
<table><thead><tr><th>检查项</th><th>状态</th><th>说明</th></tr></thead><tbody>
|
||||
EOF
|
||||
}
|
||||
|
||||
setup_row() {
|
||||
# $1 名称 $2 ok|bad|warn $3 状态文字 $4 说明(可含 HTML)
|
||||
printf '<tr><td>%s</td><td class="s-%s">%s</td><td>%s</td></tr>\n' \
|
||||
"$(html_escape "$1")" "$2" "$(html_escape "$3")" "$4" >> "$RUNTIME/setup.html"
|
||||
}
|
||||
|
||||
setup_rows() {
|
||||
if [ "$NODE_OK" = 1 ]; then
|
||||
setup_row 'Node.js' ok "已安装 $NODE_VER" '需要 20 或更高版本'
|
||||
else
|
||||
setup_row 'Node.js' bad '缺失或版本过低' "必需。$NODE_HINT"
|
||||
fi
|
||||
if [ "$NPM_OK" = 1 ]; then
|
||||
setup_row 'npm' ok '可用' '安装依赖用'
|
||||
else
|
||||
setup_row 'npm' bad '缺失' '随 Node.js 一起安装,重装 Node 即可'
|
||||
fi
|
||||
if [ "$PY_OK" = 1 ]; then
|
||||
setup_row 'python3' ok "已安装 $PY_VER" '可选:用于技能(skills/*/run.py)'
|
||||
else
|
||||
setup_row 'python3' warn '未安装' '可选。没有它时技能清单为空,其余功能不受影响'
|
||||
fi
|
||||
if [ "$FF_OK" = 1 ]; then
|
||||
setup_row 'ffmpeg' ok "已安装 $FF_VER" '可选:语音输入与音频转码'
|
||||
else
|
||||
setup_row 'ffmpeg' warn '未安装' '可选。没有它时语音输入入口自动隐藏'
|
||||
fi
|
||||
if [ "$PORT_FREE" = 1 ]; then
|
||||
setup_row "端口 $PORT" ok '可用' 'agent-core 监听地址'
|
||||
else
|
||||
setup_row "端口 $PORT" bad '已被占用' "换一个端口再启动:<code>PORT=8091 ./local/start.sh</code>"
|
||||
fi
|
||||
}
|
||||
|
||||
setup_close() {
|
||||
cat >> "$RUNTIME/setup.html" <<'EOF'
|
||||
</tbody></table>
|
||||
<p class="note">装好之后回到终端,重新执行 <code>./local/start.sh</code>(或双击 <code>start.command</code>)。</p>
|
||||
<p class="tip">这个页面是本地静态文件,不会自动刷新,也不会重试。</p>
|
||||
</main></body></html>
|
||||
EOF
|
||||
open_target "$RUNTIME/setup.html"
|
||||
printf '\n自检页已保存:%s\n' "$RUNTIME/setup.html"
|
||||
}
|
||||
|
||||
# ---------- 首次运行:选目录 + 生成配置 ----------
|
||||
choose_workspace() {
|
||||
ws=''
|
||||
if [ "$(uname -s)" = 'Darwin' ] && command -v osascript >/dev/null 2>&1; then
|
||||
ws=$(osascript -e 'POSIX path of (choose folder with prompt "选择 Agent 的工作目录:AI 会在这个目录里干活")' 2>/dev/null) || ws=''
|
||||
fi
|
||||
if [ -z "$ws" ] && [ -t 0 ]; then
|
||||
printf '工作目录(AI 会在这里干活)[%s/AgentWork]: ' "$HOME"
|
||||
read -r ans || ans=''
|
||||
if [ -n "${ans:-}" ]; then ws=$ans; else ws="$HOME/AgentWork"; fi
|
||||
fi
|
||||
[ -z "$ws" ] && ws="$HOME/AgentWork"
|
||||
printf '%s\n' "${ws%/}"
|
||||
}
|
||||
|
||||
generate_config() {
|
||||
ws=$1
|
||||
mkdir -p "$ws" 2>/dev/null || { say "无法创建工作目录:$ws"; exit 1; }
|
||||
cat > "$CONFIG" <<EOF
|
||||
# 本机 local 模式配置 —— 由 local/start.sh 首次启动时生成,之后不再覆盖。
|
||||
# 改模型 / 密钥 / MCP:浏览器打开 http://$HOST_ADDR:$PORT → 左下角用户区 → 设置。
|
||||
# 想彻底重来:删掉本文件再跑一次 ./local/start.sh(会话记录在 data/ 和工作目录里,不会被删)。
|
||||
port: $PORT
|
||||
# AI 的工作根。启动器注入 AGENT_FILE_SCOPE=workspace,文件工具可读写这个目录下的任意位置,
|
||||
# 不再像服务器那样被限制在单个会话子目录里。
|
||||
workspace_root: $ws
|
||||
data_root: $ROOT/data
|
||||
skills:
|
||||
# 指向 local/.runtime/skills:启动脚本按「有没有可用的 python3」把它软链到真技能目录或空目录。
|
||||
# 这样装不装 python3 都不用改这份配置(改完重跑脚本即生效)。
|
||||
skills_root: $ROOT/local/.runtime/skills
|
||||
# 故意留空:启动后在设置页添加平台与 API Key,再点「重启」——启动器会自动拉起。
|
||||
platforms: []
|
||||
log_level: info
|
||||
mcp_servers:
|
||||
# 四个同栈 MCP 都在本机跑(零依赖 Node),端口由启动器分配,别和上面的 PORT 撞。
|
||||
# 上游密钥/地址由这里的 headers 带(在设置页对应卡片里填);不填则该能力不可用。
|
||||
- name: web_search
|
||||
url: "http://127.0.0.1:$MCP_WEB_PORT/"
|
||||
- name: image_task
|
||||
url: "http://127.0.0.1:$MCP_IMAGE_PORT/mcp"
|
||||
mode: skill
|
||||
- name: video_task
|
||||
url: "http://127.0.0.1:$MCP_VIDEO_PORT/mcp"
|
||||
mode: skill
|
||||
- name: asr
|
||||
url: "http://127.0.0.1:$MCP_ASR_PORT/mcp"
|
||||
mode: skill
|
||||
EOF
|
||||
say "已生成配置:$CONFIG"
|
||||
say "工作目录:$ws"
|
||||
}
|
||||
|
||||
# ---------- 技能目录:用软链切换,不动配置 ----------
|
||||
link_skills() {
|
||||
link="$RUNTIME/skills"
|
||||
if [ "$PY_OK" = 1 ]; then dest="$ROOT/skills"; else dest="$RUNTIME/empty-skills"; mkdir -p "$dest"; fi
|
||||
rm -f "$link" 2>/dev/null || true
|
||||
# 万一上次留下了真目录(老版本行为),先挪走再建软链
|
||||
if [ -d "$link" ] && [ ! -L "$link" ]; then rm -rf "$link"; fi
|
||||
ln -s "$dest" "$link" || { warn "技能目录软链创建失败:$link"; return 1; }
|
||||
}
|
||||
|
||||
# ---------- 依赖安装 ----------
|
||||
# 不只 app:mcp/image_task 与 mcp/video_task 也带 npm 依赖(@modelcontextprotocol/sdk + express),
|
||||
# 服务器上这些是镜像构建时装好的,本地得自己装。asr / web_search 是零依赖,自动跳过。
|
||||
ensure_deps() {
|
||||
NEED=''
|
||||
for d in "$ROOT/app" "$ROOT"/mcp/*/; do
|
||||
[ -f "$d/package.json" ] || continue
|
||||
if node -e 'process.exit(Object.keys(require(process.argv[1]).dependencies||{}).length?0:1)' "$d/package.json" >/dev/null 2>&1; then
|
||||
if [ ! -d "$d/node_modules" ] || [ "$d/package.json" -nt "$d/node_modules" ]; then
|
||||
NEED="$NEED $d"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
[ -z "$NEED" ] && return 0
|
||||
if [ "$NPM_OK" != 1 ]; then
|
||||
SETUP_TITLE='缺少 npm,无法安装依赖'
|
||||
SETUP_HINT='Node.js 一般自带 npm。若你是用系统包管理器装的 node,可能需要单独安装 <code>npm</code>。'
|
||||
return 1
|
||||
fi
|
||||
say '首次运行:安装 Node 依赖(需要联网,通常 1~3 分钟)'
|
||||
for d in $NEED; do
|
||||
say " npm install → ${d#$ROOT/}"
|
||||
if [ -n "$NPM_REGISTRY" ]; then
|
||||
( cd "$d" && npm install --no-audit --no-fund --omit=dev --registry "$NPM_REGISTRY" ) || return 1
|
||||
else
|
||||
( cd "$d" && npm install --no-audit --no-fund --omit=dev ) || return 1
|
||||
fi
|
||||
done
|
||||
return 0
|
||||
}
|
||||
|
||||
# ---------- 子进程 ----------
|
||||
MCP_PIDS=''
|
||||
# 四个服务对接参数的方式不一样,别混用:
|
||||
# image_task / video_task / web_search → 认 --http --host --port
|
||||
# mcp_asr → 只认 PORT 环境变量(它的 argv 不解析)
|
||||
start_mcp_flags() {
|
||||
dir=$1; mport=$2; tag=$3; shift 3
|
||||
( cd "$ROOT/mcp/$dir" && exec node "$@" --host "$HOST_ADDR" --port "$mport" >>"$RUNTIME/mcp-$tag.log" 2>&1 ) &
|
||||
MCP_PIDS="$MCP_PIDS $!"
|
||||
}
|
||||
|
||||
start_mcp_env() {
|
||||
dir=$1; mport=$2; tag=$3; shift 3
|
||||
( cd "$ROOT/mcp/$dir" && exec env PORT="$mport" node "$@" >>"$RUNTIME/mcp-$tag.log" 2>&1 ) &
|
||||
MCP_PIDS="$MCP_PIDS $!"
|
||||
}
|
||||
|
||||
CORE_PID=''
|
||||
STOPPING=0
|
||||
|
||||
kill_tree() {
|
||||
pid=$1
|
||||
[ -n "$pid" ] || return 0
|
||||
if command -v pgrep >/dev/null 2>&1; then
|
||||
for c in $(pgrep -P "$pid" 2>/dev/null); do kill_tree "$c"; done
|
||||
fi
|
||||
kill "$pid" 2>/dev/null || true
|
||||
}
|
||||
|
||||
do_cleanup() {
|
||||
for p in $CORE_PID $MCP_PIDS; do kill_tree "$p"; done
|
||||
CORE_PID=''
|
||||
MCP_PIDS=''
|
||||
}
|
||||
|
||||
on_signal() { STOPPING=1; }
|
||||
trap 'on_signal' INT TERM HUP
|
||||
trap 'do_cleanup' EXIT
|
||||
|
||||
health() {
|
||||
if command -v curl >/dev/null 2>&1; then
|
||||
curl -fsS --max-time 2 "http://$HOST_ADDR:$PORT/api/health" >/dev/null 2>&1
|
||||
else
|
||||
node -e 'fetch("http://127.0.0.1:"+process.argv[1]+"/api/health").then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))' "$PORT" >/dev/null 2>&1
|
||||
fi
|
||||
}
|
||||
|
||||
port_open() {
|
||||
node -e 'const s=require("net").connect(Number(process.argv[1]),"127.0.0.1");s.setTimeout(800);s.on("connect",()=>{s.destroy();process.exit(0)});s.on("error",()=>process.exit(1));s.on("timeout",()=>{s.destroy();process.exit(1)})' "$1" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
# MCP 起不来是静默降级(core 只会发现不到工具),所以启动后主动点名报告。
|
||||
check_mcp() {
|
||||
if ! port_open "$1"; then
|
||||
warn "MCP $2 没起来(端口 $1)——日志:local/.runtime/mcp-$2.log"
|
||||
fi
|
||||
}
|
||||
|
||||
start_core() {
|
||||
( cd "$ROOT/app" && exec env \
|
||||
PORT="$PORT" \
|
||||
HOST="$HOST_ADDR" \
|
||||
AGENT_CONFIG="$CONFIG" \
|
||||
AGENT_FILE_SCOPE=workspace \
|
||||
ASR_URL="$ASR_URL" \
|
||||
PYTHONPATH="$ROOT/skills/deps" \
|
||||
node server/server.js >>"$LOG" 2>&1 ) &
|
||||
CORE_PID=$!
|
||||
}
|
||||
|
||||
open_browser() {
|
||||
url="http://$HOST_ADDR:$PORT"
|
||||
if command -v open >/dev/null 2>&1; then open "$url" >/dev/null 2>&1 || true
|
||||
elif command -v xdg-open >/dev/null 2>&1; then xdg-open "$url" >/dev/null 2>&1 || true
|
||||
fi
|
||||
}
|
||||
|
||||
# ============ 主流程 ============
|
||||
if [ "$NODE_OK" != 1 ]; then
|
||||
setup_head '启动前自检未通过' "没有找到可用的 Node.js 20+,服务起不来。按下面提示装好后,重新执行 <code>./local/start.sh</code>。"
|
||||
setup_rows
|
||||
setup_close
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ "$PORT_FREE" != 1 ]; then
|
||||
setup_head '端口被占用' "端口 $PORT 上已经有程序在监听。关掉它,或者换个端口启动:<code>PORT=8091 ./local/start.sh</code>(记得把设置页里的访问地址一起改)。"
|
||||
setup_rows
|
||||
setup_close
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "$CONFIG" ]; then
|
||||
say '首次运行:需要选一个 AI 的工作目录'
|
||||
WS=$(choose_workspace)
|
||||
generate_config "$WS"
|
||||
else
|
||||
say "使用已有配置:$CONFIG"
|
||||
fi
|
||||
|
||||
if ! ensure_deps; then
|
||||
setup_head "${SETUP_TITLE:-依赖安装失败}" "${SETUP_HINT:-安装 <code>app/</code> 的 Node 依赖时出错了,多半是网络问题。}"
|
||||
setup_rows
|
||||
setup_close
|
||||
printf '\n最近日志:\n'
|
||||
tail -n 20 "$LOG" 2>/dev/null || true
|
||||
exit 1
|
||||
fi
|
||||
|
||||
link_skills
|
||||
|
||||
# 语音:ffmpeg 在就启用(ASR_URL 由 core 直接读 env,不是配置),不在就不给入口。
|
||||
if [ "$FF_OK" = 1 ]; then ASR_URL="http://$HOST_ADDR:$MCP_ASR_PORT"; else ASR_URL=''; fi
|
||||
|
||||
say '启动 MCP 服务…'
|
||||
start_mcp_flags web_search "$MCP_WEB_PORT" web server.js --http
|
||||
start_mcp_flags image_task "$MCP_IMAGE_PORT" image src/mcp-server.js --http
|
||||
start_mcp_flags video_task "$MCP_VIDEO_PORT" video src/mcp-server.js --http
|
||||
start_mcp_env asr "$MCP_ASR_PORT" asr src/server.js
|
||||
|
||||
say "启动 agent-core($HOST_ADDR:$PORT)…"
|
||||
FIRST=1
|
||||
FAILS=0
|
||||
while :; do
|
||||
start_core
|
||||
|
||||
i=0
|
||||
while [ "$i" -lt 60 ]; do
|
||||
health && break
|
||||
kill -0 "$CORE_PID" 2>/dev/null || break
|
||||
sleep 1
|
||||
i=$((i + 1))
|
||||
done
|
||||
|
||||
if health; then
|
||||
if [ "$FIRST" = 1 ]; then
|
||||
FIRST=0
|
||||
open_browser
|
||||
printf '\n'
|
||||
say "已启动:http://$HOST_ADDR:$PORT"
|
||||
sleep 1
|
||||
check_mcp "$MCP_WEB_PORT" web
|
||||
check_mcp "$MCP_IMAGE_PORT" image
|
||||
check_mcp "$MCP_VIDEO_PORT" video
|
||||
check_mcp "$MCP_ASR_PORT" asr
|
||||
if [ "$FF_OK" = 1 ]; then
|
||||
say '语音:可用(ffmpeg 已就绪;还需在设置页给 asr 填上游地址与模型)'
|
||||
else
|
||||
say '语音:不可用(未安装 ffmpeg,麦克风入口会自动隐藏)'
|
||||
fi
|
||||
if [ "$PY_OK" = 1 ]; then
|
||||
say '技能:已启用(python3 就绪)'
|
||||
else
|
||||
say '技能:已关闭(未安装 python3;装好后重跑本脚本即可)'
|
||||
fi
|
||||
printf '\n首次使用:左下角「用户区」→ 设置 → 模型池,添加平台和 API Key,然后点「重启」。\n'
|
||||
printf '关闭:在本终端按 Ctrl-C(会一起停掉子进程)。\n\n'
|
||||
fi
|
||||
else
|
||||
warn 'agent-core 没能起来,最近日志:'
|
||||
tail -n 30 "$LOG" 2>/dev/null || true
|
||||
kill_tree "$CORE_PID"
|
||||
CORE_PID=''
|
||||
exit 1
|
||||
fi
|
||||
|
||||
wait "$CORE_PID" 2>/dev/null
|
||||
code=$?
|
||||
[ "$STOPPING" = 1 ] && break
|
||||
# 设置页的「重启」就是 exit 0;非 0 = 崩溃。连续崩 5 次就停下来别刷屏(典型是配置写坏了)。
|
||||
if [ "$code" = 0 ]; then FAILS=0; else FAILS=$((FAILS + 1)); fi
|
||||
if [ "$FAILS" -ge 5 ]; then
|
||||
warn "agent-core 连续 $FAILS 次异常退出,不再自动重启。最近日志:"
|
||||
tail -n 30 "$LOG" 2>/dev/null || true
|
||||
exit 1
|
||||
fi
|
||||
warn 'agent-core 已退出,1 秒后自动拉起(设置页点「重启」走的也是这条路)'
|
||||
sleep 1
|
||||
done
|
||||
|
||||
say '已停止。'
|
||||
Reference in New Issue
Block a user