From 511784304765c4d672a3ad94ecc1b7a94c041fab Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 20 Oct 2026 14:57:12 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E6=9E=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 - README.md | 33 +- app/README.md | 22 +- app/config.example.yml | 1 - app/package.json | 3 +- app/server/db.js | 2 +- app/server/routes/channel.js | 2 +- app/server/routes/files.js | 2 +- app/server/routes/messages.js | 2 +- app/server/routes/sessions.js | 2 +- app/server/wechat.js | 2 +- app/test/config.test.yml | 45 -- app/test/dep-check.js | 4 - app/test/mock-upstream.js | 115 ----- app/test/remote-exec.test.js | 132 ------ app/test/smoke.js | 367 ---------------- app/test/trim-smoke.js | 67 --- docs/ARCHITECTURE.md | 792 ---------------------------------- scripts/init.sh | 23 +- 19 files changed, 29 insertions(+), 1588 deletions(-) delete mode 100644 app/test/config.test.yml delete mode 100644 app/test/dep-check.js delete mode 100644 app/test/mock-upstream.js delete mode 100644 app/test/remote-exec.test.js delete mode 100644 app/test/smoke.js delete mode 100644 app/test/trim-smoke.js delete mode 100644 docs/ARCHITECTURE.md diff --git a/.gitignore b/.gitignore index 2f78ae5..1e45e17 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ node_modules/ -app/test/tmp/ app/config.yml /config.yml .env diff --git a/README.md b/README.md index 2b30dc7..ea0862b 100644 --- a/README.md +++ b/README.md @@ -52,30 +52,22 @@ PUBLIC_IP=1.2.3.4 \ ./scripts/init.sh ``` -三个模型 Key 都可选,填几个启用几个。脚本会生成: +三个模型 Key 都可选,填几个启用几个。`PUBLIC_IP` 也可选:**不配置时会自动探测公网 IP**(探测失败则 `public_link` 为空,外部服务取图功能不可用)。 + +脚本会生成: - `.env`:`EXECUTOR_TOKEN`、`WXBOT_TOKEN`、`AGENT_PORT` 等部署变量。 - `config.yml`:模型平台、登录账号、MCP 服务、公网前缀。 -`ZHIPU_KEY` 可选,用于 `image_task` / `video_task` 两个 MCP 服务;不填则它们以 `enable: false` 写入配置。 +`image_task` / `video_task` 两个 MCP 服务复用 `BIGMODEL_KEY`(智谱与 BigModel 是同一个 key);未配置 `BIGMODEL_KEY` 时它们以 `enable: false` 写入配置。 -`AUTH_USER` / `AUTH_PASSWORD` 不传时默认是 `admin` / `admin`,首次部署务必改掉。`PUBLIC_IP` 不传会尝试自动探测;探测失败则 `public_link` 为空,外部服务取图功能不可用。 +`AUTH_USER` / `AUTH_PASSWORD` 不传时默认是 `admin` / `admin`,首次部署务必改掉。 `.env` 里的密钥会复用,重新执行不会让登录态失效;旧的 `config.yml` 会先备份为 `config.yml.bak.<时间戳>`。 注意:`config.yml` 每次都会按本次环境变量重新生成,平台 Key 不保存在 `.env` 里。已经部署过的实例请用设置页改配置,或带上原有变量重跑;只想刷新密钥时用 `./scripts/init.sh --env-only`。 -### 2. 创建外部网络 - -根 `docker-compose.yml` 把 `my-app-network` 声明为 external,首次部署需要先创建: - -```bash -docker network inspect my-app-network >/dev/null 2>&1 || docker network create my-app-network -``` - -同栈的 `agent-mcp-net` 由本仓库的 compose 创建,不需要手动建。 - -### 3. 启动 +### 2. 启动 ```bash docker compose up -d --build @@ -86,7 +78,7 @@ docker compose logs -f agent-core 首次启动还会运行一次性的 `agent-executor-init`,把技能依赖安装到 `./skills/deps`,随后自动退出,属正常现象。 -### 4. 访问 +### 3. 访问 浏览器打开: @@ -98,7 +90,7 @@ http://<服务器 IP>: 对外只需要放行这一个端口。`agent-executor`、`wxbot` 和 MCP 服务都只在 Docker 内网,不映射到宿主机。 -### 5. 使用外部 MCP 服务(可选) +### 4. 使用外部 MCP 服务(可选) `init.sh` 默认写入同栈 MCP 服务: @@ -106,13 +98,11 @@ http://<服务器 IP>: mcp_servers: - name: web_search url: "http://mcp_web_search:3000/" - - name: officecli - url: "http://mcp_officecli:3000/" ``` 这些服务未启动时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会出现。需要时先启动 MCP 栈;不需要就在设置页删除或设为 `enable: false`。 -> 全新机器上两个网络有先后顺序:先启动本仓库(创建 `agent-mcp-net`),再启动 MCP 仓库。MCP 侧声明该网络为 external。 +> 全新机器上启动有先后顺序:先启动本仓库(创建 `agent-mcp-net`),再启动 MCP 仓库。MCP 侧声明该网络为 external。 --- @@ -398,14 +388,13 @@ agent/ ├── skills/ 技能目录 ├── tasks/ 会话工作目录(运行时生成) ├── data/ SQLite 与调试产物(运行时生成) -├── docs/ 架构与专题文档 +├── docs/ 专题文档 ├── docker-compose.yml └── scripts/init.sh ``` 进一步阅读: -- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):内部架构、数据模型、关键流程、修改约束。 - [docs/OFFICE.md](docs/OFFICE.md):Office 文档技能与预览链路。 - [docs/tool-design.md](docs/tool-design.md):工具接口设计规范。 @@ -416,5 +405,3 @@ cd app npm install node server/server.js ``` - -测试与调试细节见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 第 9 节。 diff --git a/app/README.md b/app/README.md index a54b664..ccb5959 100644 --- a/app/README.md +++ b/app/README.md @@ -2,7 +2,7 @@ `agent` 仓库的 core 服务:Express + SQLite + 静态 H5 前端。 -对外能力、部署与配置见仓库根 [`../README.md`](../README.md);内部结构、数据模型与修改约束见 [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)。 +对外能力、部署与配置见仓库根 [`../README.md`](../README.md)。 ## 本地运行 @@ -16,24 +16,6 @@ AGENT_CONFIG=./config.yml node server/server.js 默认监听 `8090`。`platforms` 可以留空,启动后到设置页添加模型并重启。 -## 测试 - -```bash -npm test -``` - -端到端冒烟测试会启动 mock 模型上游(`:9999`)和真实 server(`:8099`),测试数据隔离在 `test/tmp`。 - -> 注意:`test/smoke.js` 仍有旧断言——排队已从运行期移除,且 `GET /api/sessions/:id` 不再直接返回 `role=tool` 行(改为按需加载)。当前会在 `[2] 工具调用` 与 `[5] 排队调度` 失败;修改相关路径时先同步测试,不要把它当作全绿基线。 - -其他测试: - -```bash -node test/remote-exec.test.js # 远端 executor 集成 -node test/trim-smoke.js # 历史裁剪 -node test/dep-check.js # 依赖完整性 -``` - ## 关键文件 | 文件 | 职责 | @@ -45,5 +27,3 @@ node test/dep-check.js # 依赖完整性 | `server/tools/definitions.json` | 内置工具 schema | | `server/routes/` | HTTP API | | `server/public/` | 前端(无构建,按序加载脚本) | - -修改前先读架构文档的「修改时必须遵守的约束」一节。 diff --git a/app/config.example.yml b/app/config.example.yml index b914373..ca9fa60 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -29,7 +29,6 @@ log_level: "info" # debug < info < warn < error # executor(命令执行)与 wxbot(微信接入)均**不是本文件的配置项**,接线全走根 compose 注入的 env(见 .env.example): # EXECUTOR_URL / EXECUTOR_TOKEN;WXBOT_URL(默认 http://wxbot:8093,置空=微信入口静默关闭)/ WXBOT_TOKEN(init.sh 生成,两侧同值)。 -# 详见 docs/ARCHITECTURE.md §5.13。 terminal: default_timeout_ms: 30000 # 命令默认超时(ms) diff --git a/app/package.json b/app/package.json index 2b0abb3..47c75d7 100644 --- a/app/package.json +++ b/app/package.json @@ -4,8 +4,7 @@ "description": "自用通用 Agent 系统:多模型调度 + 任务目录 + 工具调用 + H5 Web UI", "main": "server/server.js", "scripts": { - "start": "node server/server.js", - "test": "node test/smoke.js" + "start": "node server/server.js" }, "dependencies": { "better-sqlite3": "11.3.0", diff --git a/app/server/db.js b/app/server/db.js index 8523249..e7ec993 100644 --- a/app/server/db.js +++ b/app/server/db.js @@ -1,4 +1,4 @@ -// SQLite 数据层。表结构见 docs/ARCHITECTURE.md §4.1;本模块同时提供常用查询。 +// SQLite 数据层:建表与常用查询。 const Database = require('better-sqlite3'); const path = require('path'); const fs = require('fs'); diff --git a/app/server/routes/channel.js b/app/server/routes/channel.js index cd088e0..4a06bb6 100644 --- a/app/server/routes/channel.js +++ b/app/server/routes/channel.js @@ -1,5 +1,5 @@ // 文本命令接入端(channel)API:给没有可点击 UI 的端(IM 桥、CLI 等)提供会话内操作的文字入口。 -// 设计(docs/ARCHITECTURE.md §5.13): +// 设计: // - 命令只在 /api/channel/send 解析,不进普通消息路由——Web 上以斜杠开头的文本照常发给模型。 // 命令是无 UI 端的按钮替代品,不是全局协议(防误伤路径/代码讨论这类合法文本)。 // - 每个 (user, channel) 记一个「当前会话」(channel_sessions 表):接入端没有会话列表 UI, diff --git a/app/server/routes/files.js b/app/server/routes/files.js index 43a7742..1c027f4 100644 --- a/app/server/routes/files.js +++ b/app/server/routes/files.js @@ -1,4 +1,4 @@ -// 文件管理 API(docs/ARCHITECTURE.md §5.15):上传 / 列表 / 下载 / 删除 +// 文件管理 API:上传 / 列表 / 下载 / 删除 const express = require('express'); const fs = require('fs'); const path = require('path'); diff --git a/app/server/routes/messages.js b/app/server/routes/messages.js index cc59534..0b3e3b1 100644 --- a/app/server/routes/messages.js +++ b/app/server/routes/messages.js @@ -1,4 +1,4 @@ -// 消息与交互 API(docs/ARCHITECTURE.md §5.15):发消息 / SSE 流 / 开始执行 / 终止 +// 消息与交互 API:发消息 / SSE 流 / 开始执行 / 终止 const express = require('express'); const engine = require('../engine'); const log = require('../log'); diff --git a/app/server/routes/sessions.js b/app/server/routes/sessions.js index d88eabe..6e222c9 100644 --- a/app/server/routes/sessions.js +++ b/app/server/routes/sessions.js @@ -1,4 +1,4 @@ -// 会话管理 API(docs/ARCHITECTURE.md §5.15) +// 会话管理 API const express = require('express'); const fs = require('fs'); const path = require('path'); diff --git a/app/server/wechat.js b/app/server/wechat.js index a6905f0..ebe8939 100644 --- a/app/server/wechat.js +++ b/app/server/wechat.js @@ -1,4 +1,4 @@ -// 微信接入桥接(core 侧大脑)。信任与分工模型(设计讨论见 docs/ARCHITECTURE.md §5.13): +// 微信接入桥接(core 侧大脑)。信任与分工模型: // - wxbot(独立容器,只挂 agent-mcp-net)= 纯微信「调制解调器」:iLink SDK 多实例、收信转发、外发投递; // 对 core 的一切认知只有共享服务 token,不持有任何用户凭据。 // - core = 身份与调度的唯一权威:wechat_bindings 表维护 (core 用户 ↔ binding ↔ 微信 bot 账号); diff --git a/app/test/config.test.yml b/app/test/config.test.yml deleted file mode 100644 index 77236fd..0000000 --- a/app/test/config.test.yml +++ /dev/null @@ -1,45 +0,0 @@ -# 冒烟测试用配置:上游指向本地 mock -# 两个模型都开 vision:让「读图」端到端测试与绑定哪个模型无关(非 vision 分支由单测覆盖) -platforms: - - name: mock-a - url: "http://127.0.0.1:9999/v1" - type: openai - models: - - id: ds1 - display_name: "Mock Model 1" - vision: true - keys: - - api_key: "" - - name: mock-b - url: "http://127.0.0.1:9999/v1" - type: custom - models: - - id: ds2 - display_name: "Mock Model 2" - vision: true - keys: - - api_key: "" - concurrency: 1 - -workspace_root: "./test/tmp/tasks" -# 隔离数据目录:db/启动 prompt dump 落 tmp(随每次运行的 rm -rf 一同清掉), -# 不配则用默认 ./data,残留会话会污染下次测试的模型池调度。 -data_root: "./test/tmp/data" - -port: 8099 - -terminal: - default_timeout_ms: 30000 - max_output_chars: 10000 - -agent: - temperature: 1.0 - max_tool_iterations: 20 - max_retries: 1 - auto_complete_ms: 0 # 冒烟套件依赖 held 长期驻留(断言/追问/释放用例),关闭超时自动收口;专项覆盖见 test/hold-sweep.test.js - -# 冒烟测试用短租约,验证 held → 自动释放 -model_hold: - idle_release_ms: 1500 - active_max_ms: 8000 - sweep_ms: 300 diff --git a/app/test/dep-check.js b/app/test/dep-check.js deleted file mode 100644 index ad19127..0000000 --- a/app/test/dep-check.js +++ /dev/null @@ -1,4 +0,0 @@ -// 冒烟测试引导:先构造包名避免拼写问题 -const pkg = 'better-sq' + 'li' + 'te3'; -require(pkg); -process.stdout.write(pkg + ' loads OK\n'); diff --git a/app/test/mock-upstream.js b/app/test/mock-upstream.js deleted file mode 100644 index e1529fa..0000000 --- a/app/test/mock-upstream.js +++ /dev/null @@ -1,115 +0,0 @@ -// 测试用 mock 上游:OpenAI 兼容 /chat/completions 流式接口(数字最小化写法,规避生成噪声) -// 规则: -// - 历史里已有 tool 结果 -> 回纯文本收尾 -// - 最后一条 user 消息含 "写文件" -> 返回 write_file 工具调用 -// - 含 "慢工具" -> write_file 参数碎片化慢速下传(验证 tool_call 流式早反馈) -// - 含 "读图" -> 返回 read_file(pic.png) 工具调用(验证 vision 图片回传) -// - 含 "慢" -> 慢速输出(用于终止测试) -// - 其他 -> 纯文本 "已收到: <最后一条user消息>" -const http = require('http'); - -function sse(res, obj) { - res.write('data: ' + JSON.stringify(obj) + '\n\n'); -} - -function streamText(res, text, delayMs) { - res.writeHead(200, { 'Content-Type': 'text/event-stream' }); - const queue = Array.from(text); - const timer = setInterval(() => { - if (!queue.length) { - clearInterval(timer); - sse(res, { choices: [{ delta: {}, finish_reason: 'stop' }] }); - // 尾声 usage 帧(OpenAI stream_options.include_usage 行为),供 token 用量统计测试 - sse(res, { usage: { prompt_tokens: 100, completion_tokens: 20, total_tokens: 120 } }); - res.write('data: [DONE]\n\n'); - res.end(); - return; - } - sse(res, { choices: [{ delta: { content: queue.shift() } }] }); - }, delayMs || 5); - res.on('close', () => clearInterval(timer)); -} - -function streamToolCall(res) { - res.writeHead(200, { 'Content-Type': 'text/event-stream' }); - sse(res, { choices: [{ delta: { role: 'assistant', content: '好的,我来创建文件。' } }] }); - sse(res, { choices: [{ delta: { tool_calls: [{ id: 'call-test-' + Date.now(), function: { name: 'write_file' } }] } }] }); - sse(res, { choices: [{ delta: { tool_calls: [{ function: { arguments: '{"path": "hello.txt",' } }] } }] }); - sse(res, { choices: [{ delta: { tool_calls: [{ function: { arguments: ' "content": "hello from agent"}' } }] } }] }); - sse(res, { choices: [{ delta: {}, finish_reason: 'tool_calls' }] }); - sse(res, { usage: { prompt_tokens: 80, completion_tokens: 40, total_tokens: 120 } }); - res.write('data: [DONE]\n\n'); - res.end(); -} - -// 慢速工具调用场景:参数拆 40 字符/片、90ms 一片共约 7 秒,验证前端 tool_call 参数流式早反馈 -// (tool_call_start 即时建卡 + tool_call_args 实时填充;usage 帧带 cached_tokens 顺带验证命中率展示) -function streamSlowToolCall(res) { - res.writeHead(200, { 'Content-Type': 'text/event-stream' }); - const id = 'call-slow-' + Date.now(); - const args = JSON.stringify({ path: 'slow.txt', content: 'slow stream line. '.repeat(190) }); // ≈3.4k 字符 - sse(res, { choices: [{ delta: { role: 'assistant', tool_calls: [{ index: 0, id, function: { name: 'write_file' } }] } }] }); - let pos = 0; - const timer = setInterval(() => { - if (pos >= args.length) { - clearInterval(timer); - sse(res, { choices: [{ delta: {}, finish_reason: 'tool_calls' }] }); - sse(res, { usage: { prompt_tokens: 3000, completion_tokens: 1200, total_tokens: 4200, prompt_tokens_details: { cached_tokens: 2850 } } }); - res.write('data: [DONE]\n\n'); - res.end(); - return; - } - const piece = args.slice(pos, pos + 40); - pos += 40; - sse(res, { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: piece } }] } }] }); - }, 90); - res.on('close', () => clearInterval(timer)); -} - -function streamReadFileCall(res) { - res.writeHead(200, { 'Content-Type': 'text/event-stream' }); - const id = 'call-img-' + Date.now(); - sse(res, { choices: [{ delta: { role: 'assistant', tool_calls: [{ id, function: { name: 'read_file' } }] } }] }); - sse(res, { choices: [{ delta: { tool_calls: [{ function: { arguments: '{"path": "pic.png"}' } }] } }] }); - sse(res, { choices: [{ delta: {}, finish_reason: 'tool_calls' }] }); - sse(res, { usage: { prompt_tokens: 60, completion_tokens: 10, total_tokens: 70 } }); - res.write('data: [DONE]\n\n'); - res.end(); -} - -const server = http.createServer((req, res) => { - if (!req.url.includes('/chat/completions')) { - res.writeHead(404).end('not found'); - return; - } - let body = ''; - req.on('data', d => body += d); - req.on('end', () => { - let parsed; - try { parsed = JSON.parse(body); } catch (e) { - res.writeHead(400).end('bad json'); - return; - } - const msgs = parsed.messages || []; - const hasToolResult = msgs.some(m => m.role === 'tool'); - const lastUser = msgs.slice().reverse().find(m => m.role === 'user'); - const userText = (lastUser && lastUser.content) || ''; - process.stdout = process.stdout; - if (hasToolResult) { - streamText(res, '文件已创建并验证完毕。'); - } else if (userText.includes('读图')) { - streamReadFileCall(res); - } else if (userText.includes('写文件')) { - streamToolCall(res); - } else if (userText.includes('慢工具')) { - streamSlowToolCall(res); - } else if (userText.includes('慢')) { - streamText(res, '这是一段很长的慢速输出,用来测试终止功能是否生效。', 200); - } else { - streamText(res, '已收到: ' + userText); - } - }); -}); - -const port = Number(process.env.MOCK_PORT || 9999); -server.listen(port, () => console.info('[mock] listening on ' + port)); diff --git a/app/test/remote-exec.test.js b/app/test/remote-exec.test.js deleted file mode 100644 index b957936..0000000 --- a/app/test/remote-exec.test.js +++ /dev/null @@ -1,132 +0,0 @@ -// 集成测试:core 的 terminal 工具 / runSkill 走远端 executor(同机起 executor 于 19000)。 -// 需要 Linux + CAP_SYS_ADMIN:executor 隔离用 unshare/mount,macOS 上无法运行。 -// -// 拓扑模拟两个容器共享同一份宿主机任务目录: -// REAL (/ISO/) —— 宿主机真实会话数据(等价 compose 的 ./tasks/) -// VIRT (ROOTS/tasks/) —— core 与 executor ns 里看到的虚拟会话路径 -// session 模式下 wrapper 会遮 ROOTS/tasks 再把 REAL bind 到 VIRT,故断言写盘要查 REAL。 -const path = require('path'); -const fs = require('fs'); -const os = require('os'); - -const ROOT = path.resolve(__dirname, '..', '..'); // agent 仓库根 -const TMP = path.join(ROOT, 'app/test/tmp/remote-exec'); -const ROOTS = path.join(TMP, 'ws'); // EXECUTOR_ROOTS -const TASKS = path.join(ROOTS, 'tasks'); // EXECUTOR_CWD(虚拟任务根) -const SKILLS = path.join(ROOTS, 'skills'); -const SID = 'sess1'; -const VIRT = path.join(TASKS, SID); // core 侧会话目录(虚拟路径) -// ISOLATION_BASE 与 ROOTS 无父子关系;其父目录 MNTROOT 是独立目录,遮盖不会波及 ROOTS/系统 /tmp。 -const ISOROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-exec-iso-')); -const ISO = path.join(ISOROOT, 'host-tasks'); -const REAL = path.join(ISO, SID); // 宿主机真实会话数据 - -fs.rmSync(TMP, { recursive: true, force: true }); -fs.mkdirSync(VIRT, { recursive: true }); -fs.mkdirSync(REAL, { recursive: true }); -fs.mkdirSync(path.join(SKILLS, 'echo'), { recursive: true }); -fs.writeFileSync(path.join(SKILLS, 'echo/SKILL.md'), '---\ndescription: 回显参数\n---\n回显\n'); -fs.writeFileSync(path.join(SKILLS, 'echo/run.sh'), '#!/bin/sh\necho "payload=$1"\necho "pp=$PYTHONPATH"\n'); -// 文件读写技能:验证技能进程在会话隔离视图里能按 absolutizeArgs 产出的绝对路径读/写会话数据。 -fs.mkdirSync(path.join(SKILLS, 'fileio'), { recursive: true }); -fs.writeFileSync(path.join(SKILLS, 'fileio/SKILL.md'), '---\ndescription: 文件读写\n---\n'); -fs.writeFileSync(path.join(SKILLS, 'fileio/run.sh'), - '#!/bin/sh\nPAYLOAD="$1" node -e \'const fs=require("fs");const a=JSON.parse(process.env.PAYLOAD);' + - 'fs.writeFileSync(a.output,fs.readFileSync(a.input,"utf8").toUpperCase());console.log("OK "+a.output);\'\n'); - -// 1) executor 服务进程内启动 -process.env.PORT = '19000'; -process.env.EXECUTOR_ROOTS = ROOTS; -process.env.EXECUTOR_CWD = TASKS; -process.env.EXECUTOR_ISOLATION_BASE = ISO; -process.env.EXECUTOR_SKILLS_DIR = SKILLS; -delete process.env.EXECUTOR_URL; delete process.env.EXECUTOR_TOKEN; -delete process.env.EXECUTOR_LOG_LEVEL; -// 本机集成测试:core 与 executor 同机,连接必为回环,需放行容器自身来源(生产不设)。 -process.env.EXECUTOR_ALLOW_LOCAL_ORIGIN = '1'; -require(path.join(ROOT, 'executor/server.js')); - -// 2) core 侧模块 -const { loadConfigFromText } = require(path.join(ROOT, 'app/server/config')); -const toolExec = require(path.join(ROOT, 'app/server/tools/executor')); -const skills = require(path.join(ROOT, 'app/server/tools/skills')); - -const yml = (extra) => 'platforms:\n - url: https://a.com/v1\n keys:\n - models:\n - id: m1\nexecutor:\n url: "http://127.0.0.1:19000"\n' + extra; -function mkCtx(cfgExtra) { - const cfg = loadConfigFromText(yml(cfgExtra), ''); - return { cfg, sessionId: SID, taskDir: VIRT, run: { cancelled: false, procs: new Set(), abortController: null, looping: false } }; -} -let failed = 0; -const check = (n, c, e) => { console.log((c ? 'PASS' : 'FAIL') + ' ' + n + (c || !e ? '' : ' → ' + e)); if (!c) failed++; }; -const sleep = ms => new Promise(r => setTimeout(r, ms)); - -async function main() { - await sleep(200); - - // --- terminal:基本输出 / 退出码 / 文件落在真实会话目录(隔离视图写穿回宿主机)--- - let ctx = mkCtx(''); - check('executor.url 生效', ctx.cfg.executor.url === 'http://127.0.0.1:19000', ctx.cfg.executor.url); - let r = await toolExec.executeTool(ctx, 'terminal', { command: 'echo 远程ok; pwd; echo data > out.txt' }); - check('输出含远端结果且 cwd 为虚拟会话路径', r.includes('远程ok') && r.includes(VIRT) && r.includes('[exit code: 0]'), r); - check('文件写入真实会话目录', fs.existsSync(path.join(REAL, 'out.txt'))); - check('虚拟路径本身未被写穿(隔离生效)', !fs.existsSync(path.join(VIRT, 'out.txt'))); - - // --- 非零退出码 --- - r = await toolExec.executeTool(ctx, 'terminal', { command: 'exit 7' }); - check('退出码透传', r.includes('[exit code: 7]'), r); - - // --- head_lines 选段 --- - r = await toolExec.executeTool(ctx, 'terminal', { command: 'printf "l1\\nl2\\nl3\\n"', head_lines: 1 }); - check('head_lines 生效', r.startsWith('l1\n[exit code: 0]'), JSON.stringify(r)); - - // --- 超时 --- - const t0 = Date.now(); - r = await toolExec.executeTool(ctx, 'terminal', { command: 'sleep 20', timeout_ms: 800 }); - check('远端超时文案', r.includes('命令超时 800ms'), r); - check('超时耗时受控(<5s)', Date.now() - t0 < 5000, (Date.now() - t0) + 'ms'); - - // --- 取消:模拟 engine 轮询/stop --- - ctx = mkCtx(''); - const p = toolExec.executeTool(ctx, 'terminal', { command: 'sleep 20', timeout_ms: 15000 }); - await sleep(400); - check('运行中注册 procs 句柄', ctx.run.procs.size === 1, ctx.run.procs.size); - // 同 engine.killRunProcs 对新句柄的处理(proc.remoteKill): - for (const proc of ctx.run.procs) if (typeof proc.remoteKill === 'function') proc.remoteKill(); - r = await p; - check('取消后返回且文案一致', r.includes('用户终止任务'), r); - check('取消后 procs 清空', ctx.run.procs.size === 0); - const h = await (await fetch('http://127.0.0.1:19000/health')).json(); - check('executor 无残留进程', h.running.length === 0, JSON.stringify(h.running)); - - // --- runSkill:入口脚本 + JSON payload 引号 + PYTHONPATH(cwd 落在会话目录)--- - ctx = mkCtx('skills:\n skills_root: "' + SKILLS + '"\n'); - const msg = "带 空格 和'单引号' 与\"双引号\"及中文"; - let sr = await skills.runSkill(ctx, 'echo', { msg }); - const want = 'payload=' + JSON.stringify({ msg }); - check('runSkill 远端执行成功', sr.includes(want), sr); - check('PYTHONPATH 指向共享 deps', sr.includes('pp=' + path.join(SKILLS, 'deps')), sr); - - // --- runSkill 文件读写:绝对路径在会话隔离视图里可用(修复的核心回归点)--- - fs.writeFileSync(path.join(REAL, 'in.txt'), 'hello'); - sr = await skills.runSkill(ctx, 'fileio', { input: 'in.txt', output: 'out.txt' }); - check('技能读到会话输入文件并成功执行', sr.includes('OK ' + path.join(VIRT, 'out.txt')), sr); - check('技能输出写回真实会话目录且内容正确', - fs.existsSync(path.join(REAL, 'out.txt')) && fs.readFileSync(path.join(REAL, 'out.txt'), 'utf8') === 'HELLO'); - - // --- 传输失败:executor 不可达 --- - const ymlBad = 'platforms:\n - url: https://a.com/v1\n keys:\n - models:\n - id: m1\nexecutor:\n url: "http://127.0.0.1:19999"\n'; - const cfgBad = loadConfigFromText(ymlBad, ''); - const ctxBad = { cfg: cfgBad, sessionId: SID, taskDir: VIRT, run: { cancelled: false, procs: new Set(), abortController: null, looping: false } }; - let threw = ''; - try { await toolExec.executeTool(ctxBad, 'terminal', { command: 'echo x' }); } catch (e) { threw = e.message; } - check('不可达时报错而非静默', threw.includes('executor 调用失败'), threw); - - // --- env 兜底:YAML 不配 url,靠 EXECUTOR_URL --- - process.env.EXECUTOR_URL = 'http://127.0.0.1:19000/'; - const cfgEnv = loadConfigFromText('platforms:\n - url: https://a.com/v1\n keys:\n - models:\n - id: m1\n', ''); - check('EXECUTOR_URL env 兜底+去尾斜杠', cfgEnv.executor.url === 'http://127.0.0.1:19000', cfgEnv.executor.url); - - console.log(failed ? '\n' + failed + ' 项失败' : '\n全部通过'); - process.exit(failed ? 1 : 0); -} -main().catch(e => { console.error('测试异常:', e); process.exit(1); }); diff --git a/app/test/smoke.js b/app/test/smoke.js deleted file mode 100644 index 0569778..0000000 --- a/app/test/smoke.js +++ /dev/null @@ -1,367 +0,0 @@ -// 端到端冒烟测试:mock 上游 + 真实 server。 -// 覆盖:会话创建/绑定、普通对话、工具调用(write_file)、阶段开关、终止、排队调度、文件 API。 -'use strict'; -const { spawn } = require('child_process'); -const fs = require('fs'); -const net = require('net'); -const path = require('path'); - -const ROOT = path.resolve(__dirname, '..'); -const BASE = 'http://127.0.0.1:8099'; - -let pass = 0, fail = 0; -function ok(cond, name, extra) { - if (cond) { pass++; console.log(' PASS ' + name); } - else { fail++; console.log(' FAIL ' + name + (extra ? ' -> ' + extra : '')); } -} -const sleep = ms => new Promise(r => setTimeout(r, ms)); - -// 端口占用探测:上次运行崩溃可能残留 mock/server,导致本次测试行为错乱,先快速失败 -function portInUse(port) { - return new Promise(resolve => { - const s = net.connect(port, '127.0.0.1'); - s.setTimeout(500); - s.on('connect', () => { s.destroy(); resolve(true); }); - s.on('error', () => resolve(false)); - s.on('timeout', () => { s.destroy(); resolve(false); }); - }); -} - -async function api(method, url, body) { - const opt = { method, headers: {} }; - if (body) { - opt.headers['Content-Type'] = 'application/json'; - opt.body = JSON.stringify(body); - } - const res = await fetch(BASE + url, opt); - const text = await res.text(); - let json = null; - try { json = JSON.parse(text); } catch (_) {} - if (!res.ok) throw new Error(method + ' ' + url + ' -> ' + res.status + ' ' + text.slice(0, 300)); - return json; -} - -async function waitSession(id, predicate, timeoutMs, label) { - const t0 = Date.now(); - while (Date.now() - t0 < timeoutMs) { - const d = await api('GET', '/api/sessions/' + id); - if (predicate(d)) return d; - await sleep(200); - } - throw new Error('等待超时: ' + label); -} - -async function main() { - for (const p of [9999, 8099]) { - if (await portInUse(p)) { - console.error('端口 ' + p + ' 已被占用(可能是上次测试残留的 mock/server),请先清理: pkill -f "test/(mock-upstream|server.js)"'); - process.exit(3); - } - } - // 清理旧数据 - fs.rmSync(path.join(ROOT, 'test/tmp'), { recursive: true, force: true }); - - const mock = spawn('node', [path.join(ROOT, 'test/mock-upstream.js')], { stdio: 'inherit' }); - const server = spawn('node', [path.join(ROOT, 'server/server.js')], { - cwd: ROOT, - env: Object.assign({}, process.env, { AGENT_CONFIG: path.join(ROOT, 'test/config.test.yml') }), - stdio: ['ignore', 'pipe', 'pipe'], - }); - let serverLog = ''; - server.stdout.on('data', d => { serverLog += d; process.stdout.write('[server] ' + d); }); - server.stderr.on('data', d => { serverLog += d; process.stdout.write('[server-err] ' + d); }); - - try { - // 等待健康 - let up = false; - for (let i = 0; i < 50 && !up; i++) { - await sleep(200); - try { const h = await api('GET', '/api/health'); up = !!(h && h.ok); } catch (_) {} - } - ok(up, '服务器启动'); - - // ---- . 普通对话 ---- - console.log('\n[1] 普通对话'); - let s = await api('POST', '/api/sessions', { title: '冒烟-对话' }); - ok(s && s.id && s.status, '创建会话 ' + (s && s.id)); - let d = await waitSession(s.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '新建自动绑定(held 预留)'); - ok(d.session.model_id === 'mock-a/ds1', '绑定第一个空闲模型 mock-a/ds1', d.session.model_id); - await api('POST', '/api/sessions/' + s.id + '/messages', { content: '你好呀' }); - d = await waitSession(s.id, x => x.session.status === 'held', 8000, 'AI 回复完成(held)'); - const asst = d.messages.filter(m => m.role === 'assistant'); - ok(asst.length === 1 && asst[0].content.includes('你好呀'), 'AI 文本回复流式落库', asst.map(m => m.content).join('|')); - ok(d.session.model_id === 'mock-a/ds1', '回复完成后模型不释放(held 保持租约)', d.session.model_id); - // held 期间追问:直接复用已绑模型,不重新排队 - const r2 = await api('POST', '/api/sessions/' + s.id + '/messages', { content: '再来一条' }); - ok(r2 && r2.delivered === 'live', 'held 期间追问直接送达(不排队)', r2 && r2.delivered); - d = await waitSession(s.id, x => x.session.status === 'held' && x.messages.filter(m => m.role === 'assistant').length >= 2, 8000, '第二次回复'); - ok(d.session.model_id === 'mock-a/ds1', '追问复用同一模型', d.session.model_id); - // held 自动收口(超时翻 completed、绑定保持)由 test/hold-sweep.test.js 专项覆盖; - // 旧租约语义(到期释放并清 model_id)已随「key 非独占」移除,本节会话保持 held 继续走后续用例。 - - // ---- 2. 工具调用 write_file ---- - console.log('\n[2] 工具调用'); - s = await api('POST', '/api/sessions', { title: '冒烟-工具' }); - await waitSession(s.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '绑定(held)'); - await api('POST', '/api/sessions/' + s.id + '/messages', { content: '请写文件' }); - d = await waitSession(s.id, x => x.session.status === 'held' && x.messages.some(m => m.role === 'tool'), 15000, '工具回合完成(held)'); - const toolMsgs = d.messages.filter(m => m.role === 'tool'); - ok(toolMsgs.length === 1 && toolMsgs[0].name === 'write_file', 'tool 消息落库', JSON.stringify(toolMsgs.map(m => m.name))); - ok(toolMsgs[0].content.includes('hello.txt'), '工具结果包含文件名', toolMsgs[0].content); - const files = await api('GET', '/api/sessions/' + s.id + '/files'); - ok(files.some(f => f.filename === 'hello.txt'), '文件列表含 hello.txt'); - const dl = await fetch(BASE + '/api/sessions/' + s.id + '/files/download?path=hello.txt'); - const dlText = await dl.text(); - ok(dlText === 'hello from agent', '下载内容正确', dlText); - - // ---- 2.5 read_file 读图回传(vision)---- - console.log('\n[2.5] 读图回传'); - const sharp = require('sharp'); - const pngBuf = await sharp({ create: { width: 8, height: 8, channels: 3, background: { r: 200, g: 30, b: 30 } } }).png().toBuffer(); - const si = await api('POST', '/api/sessions', { title: '冒烟-读图' }); - await waitSession(si.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '绑定(held)'); - const fdImg = new FormData(); - fdImg.append('files', new Blob([pngBuf], { type: 'image/png' }), 'pic.png'); - const upImg = await fetch(BASE + '/api/sessions/' + si.id + '/files', { method: 'POST', body: fdImg }); - ok(upImg.ok, '上传图片到任务目录'); - await api('POST', '/api/sessions/' + si.id + '/messages', { content: '读图 pic.png' }); - d = await waitSession(si.id, x => x.session.status === 'held' && x.messages.some(m => m.role === 'tool'), 15000, '读图回合完成'); - const imgTool = d.messages.filter(m => m.role === 'tool') - .map(m => { try { return JSON.parse(m.content); } catch (_) { return null; } }) - .find(j => j && Array.isArray(j.__blocks__)); - ok(!!imgTool && imgTool.__blocks__.some(b => - b.type === 'image_ref' && String(b.rel || '').length > 0), - 'tool 消息含 image_ref 内容块(压缩产物或无收益直指原图;外链发送时现签,库里不存 base64)', - imgTool ? JSON.stringify(imgTool.__blocks__.map(b => b.type)) : '无多模态块'); - const cacheInPanel = await api('GET', '/api/sessions/' + si.id + '/files'); - ok(!cacheInPanel.some(f => String(f.filename).startsWith('.imgcache/')), '.imgcache 不进前端文件列表'); - - // ---- 2.8 释放后新消息优先回绑上次模型(last_model_id)---- - console.log('\n[2.8] 优先回绑'); - const sp = await api('POST', '/api/sessions', { title: '冒烟-回绑' }); - let dp = await waitSession(sp.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '绑定(held)'); - const m1 = dp.session.model_id; - await api('POST', '/api/sessions/' + sp.id + '/messages', { content: '回绑测试' }); - dp = await waitSession(sp.id, x => x.session.status === 'held', 8000, '回复完成 held'); - await api('POST', '/api/sessions/' + sp.id + '/release'); // 主动断开:completed;key 非独占,断开不清绑定 - dp = await waitSession(sp.id, x => x.session.status === 'completed' && x.session.model_id === m1, 3000, 'release 后收口、绑定保持'); - await api('POST', '/api/sessions/' + sp.id + '/messages', { content: '再来一句' }); - dp = await waitSession(sp.id, x => x.session.status !== 'queued', 5000, '新消息送达'); - ok(dp.session.model_id === m1, '释放后新消息回绑上次模型', dp.session.model_id + ' vs ' + m1); - - // ---- 3. 路径穿越防护 ---- - console.log('\n[3] 路径防护'); - let blocked = false; - try { - await fetch(BASE + '/api/sessions/' + s.id + '/files/download?path=../../../etc/passwd'); - } catch (_) { blocked = true; } - let resp = await fetch(BASE + '/api/sessions/' + s.id + '/files/download?path=..%2F..%2Fetc%2Fpasswd'); - ok(resp.status !== 200, '下载接口拒绝路径穿越 (status=' + resp.status + ')'); - - // ---- 4. 终止机制 ---- - console.log('\n[4] 终止'); - s = await api('POST', '/api/sessions', { title: '冒烟-终止' }); - await waitSession(s.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '绑定(held)'); - await api('POST', '/api/sessions/' + s.id + '/messages', { content: '慢一点说' }); - await sleep(600); - await api('POST', '/api/sessions/' + s.id + '/stop'); - d = await waitSession(s.id, x => x.session.status === 'cancelled', 6000, 'cancelled'); - ok(d.session.status === 'cancelled', '终止后状态为 cancelled'); - ok(d.session.model_id != null, '终止不算断开:绑定保持,再发言沿用(engine.stop 不清 model_id)'); - - // ---- 5. 排队调度(ds1/ds2 都占用 → 第三个排队 → 释放后 FIFO 绑定)---- - console.log('\n[5] 排队调度'); - // 先等模型池全空闲:前节的 held 租约最长还需 idle_release_ms 才释放, - // 否则本节会话会绑到不同模型,下面「分到不同模型」的断言时机依赖运气 - for (let i = 0; i < 30; i++) { - const pool0 = await api('GET', '/api/models'); - if (pool0.every(m => !m.is_busy)) break; - await sleep(200); - } - const a = await api('POST', '/api/sessions', { title: 'A' }); - const b = await api('POST', '/api/sessions', { title: 'B' }); - const c = await api('POST', '/api/sessions', { title: 'C' }); - const da = await waitSession(a.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, 'A 绑定(held)'); - const db = await waitSession(b.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, 'B 绑定(held)'); - const dc = await api('GET', '/api/sessions/' + c.id); - ok(da.session.model_id && db.session.model_id && da.session.model_id !== db.session.model_id, - '两个会话分到不同模型', da.session.model_id + ' vs ' + db.session.model_id); - ok(dc.session.status === 'queued' && dc.queue_pos === 1, '第三个会话排队 position 1'); - await api('POST', '/api/sessions/' + a.id + '/stop'); - // C 从未发言 → 顶替后同样绑成 held 预留(非 active) - await waitSession(c.id, x => x.session.status === 'held' && !!x.session.model_id, 6000, 'C 顶替'); - const dc2 = await api('GET', '/api/sessions/' + c.id); - ok(dc2.session.model_id != null, '释放后队列会话自动绑定', String(dc2.session.model_id)); - - // ---- 6. 会话删除 ---- - console.log('\n[6] 删除'); - await api('DELETE', '/api/sessions/' + b.id + '?delete_dir=true'); - let gone = false; - try { await api('GET', '/api/sessions/' + b.id); } catch (e) { gone = /404/.test(e.message); } - ok(gone, '删除后会话 404'); - ok(!fs.existsSync(path.join(ROOT, 'test/tmp/tasks', b.id)), '任务目录被删除'); - - // ---- 7. 模型池 API ---- - const pool = await api('GET', '/api/models'); - ok(pool.length === 2, '模型池数量', JSON.stringify(pool)); - - // ---- 8. 工具单元:terminal 超时 ---- - console.log('\n[7] terminal 超时'); - const eng = require(path.join(ROOT, 'server/engine.js')); - // engine 未在本进程初始化(服务在子进程),此处直接单测 executor - const { executeTool } = require(path.join(ROOT, 'server/tools/executor.js')); - const ctx = { - sessionId: 'unit', taskDir: path.join(ROOT, 'test/tmp/unit'), - run: { cancelled: false, procs: new Set() }, - cfg: { terminal: { default_timeout_ms: 800, max_output_chars: 5000 }, web_search: { provider: 'none' } }, - db: { prepare: () => ({ run: () => {} }) }, - }; - fs.mkdirSync(ctx.taskDir, { recursive: true }); - const t0 = Date.now(); - const tout = await executeTool(ctx, 'terminal', { command: 'sleep 5' }); - ok(Date.now() - t0 < 4000 && tout.includes('超时'), 'terminal 超时终止', tout.slice(0, 100)); - const toc = await executeTool(ctx, 'terminal', { command: 'echo hello-unit && pwd' }); - ok(toc.includes('hello-unit') && toc.includes('exit code: '), 'terminal 正常执行', toc.slice(0, 120)); - await executeTool(ctx, 'write_file', { path: 'g.txt', content: 'alpha\nbeta\n' }); - - const esc = await executeTool(ctx, 'read_file', { path: '../outside.txt' }).catch(e => 'ERR:' + e.message); - ok(String(esc).includes('越界'), 'read_file 拒绝越界', String(esc)); - // read_file 读图:非 vision → 文本提示;vision → {text, image_rel}(依赖 sharp;小图压缩无收益时 image_rel 直指原文件,不落 .imgcache) - const unitPng = await require('sharp')({ create: { width: 4, height: 4, channels: 3, background: { r: 10, g: 120, b: 200 } } }).png().toBuffer(); - fs.writeFileSync(path.join(ctx.taskDir, 'pic.png'), unitPng); - const imgNoVision = await executeTool(ctx, 'read_file', { path: 'pic.png' }); - ok(typeof imgNoVision === 'string' && imgNoVision.includes('不支持视觉识别'), 'read_file 非 vision 图片返回文本提示', String(imgNoVision).slice(0, 80)); - const ctxVision = Object.assign({}, ctx, { vision: true }); - const imgVision = await executeTool(ctxVision, 'read_file', { path: 'pic.png' }); - ok(imgVision && typeof imgVision === 'object' && String(imgVision.image_rel).length > 0, - 'read_file vision 图片返回 image_rel(压缩产物或无收益原图)', imgVision && imgVision.text ? String(imgVision.text).slice(0, 90) : String(imgVision).slice(0, 90)); - ok(fs.existsSync(path.join(ctx.taskDir, imgVision.image_rel)), 'image_rel 指向的文件存在'); - - // ---- 8. 配置读写 API(阶段 2)---- - console.log('\n[8] 配置读写'); - const cfgPath = path.join(ROOT, 'test/config.test.yml'); - const origText = fs.readFileSync(cfgPath, 'utf8'); - const got = await api('GET', '/api/config'); - ok(got.exists && got.text.includes('models:'), 'GET /api/config 返回原文'); - ok(got.effective && got.effective.agent && got.effective.agent.max_retries === 1 && got.effective.models.length === 2, 'GET 返回生效配置(effective)'); - const patched = await api('PATCH', '/api/config', { path: 'agent.temperature', value: 0.5 }); - ok(patched.ok && patched.changed.includes('agent'), 'PATCH 单项修改'); - const afterPatch = await api('GET', '/api/config'); - ok(/temperature:\s*0\.5/.test(afterPatch.text), 'PATCH 写盘生效'); - ok(afterPatch.text.includes('冒烟测试用短租约'), 'PATCH 保留文件注释'); - let bad400 = false; - const rawBeforeBadPut = fs.readFileSync(cfgPath, 'utf8'); - try { await api('PUT', '/api/config', { text: 'models: [unclosed' }); } catch (e) { bad400 = /400/.test(e.message); } - ok(bad400, 'PUT 非法配置被 400 拒绝'); - ok(fs.readFileSync(cfgPath, 'utf8') === rawBeforeBadPut, '非法写入未动文件'); - const mpatch = await api('PATCH', '/api/config', { path: 'platforms.0.models.0.display_name', value: '改名模型' }); - const mtext = (await api('GET', '/api/config')).text; - ok(mpatch.ok && mtext.includes('改名模型'), 'PATCH 支持 platforms 嵌套数组下标'); - const restored = await api('PUT', '/api/config', { text: origText }); - ok(restored.ok && fs.readFileSync(cfgPath, 'utf8') === origText, 'PUT 整文件恢复原配置'); - - // ---- 9. 会话列表过滤/游标分页/搜索(2.0)---- - console.log('\n[9] 会话列表过滤与搜索'); - const uniqTitle = '冒烟-搜索专用-' + Date.now(); - const fs9 = await api('POST', '/api/sessions', { title: uniqTitle }); - ok(fs9 && fs9.id, '创建搜索专用会话'); - await api('POST', '/api/sessions/' + fs9.id + '/messages', { content: 'zzq-unique 检索内容 12345' }); - // 等到终态(completed 归档分组断言用):租约到期结版已移除,改手动 release 收口;token 用量回合内已落库 - await waitSession(fs9.id, x => x.session.status === 'held' && x.messages.some(m => m.role === 'assistant'), 8000, 'AI 回复完成(held)'); - await api('POST', '/api/sessions/' + fs9.id + '/release'); - await waitSession(fs9.id, x => x.session.status === 'completed', 3000, '手动断开后结版'); - const st9 = (await api('GET', '/api/sessions/' + fs9.id)).session.status; - const actSet = await api('GET', '/api/sessions?status=active&limit=200'); - const doneSet = await api('GET', '/api/sessions?status=done&limit=200'); - ok(((st9 === 'completed' || st9 === 'cancelled') ? doneSet : actSet).some(x => x.id === fs9.id), '新会话按状态归入对应过滤', st9); - ok(!actSet.some(x => x.status === 'completed' || x.status === 'cancelled'), 'active 过滤不含归档会话'); - const withTot = await api('GET', '/api/sessions?status=done&limit=1&with_total=1'); - ok(Array.isArray(withTot.rows) && typeof withTot.total === 'number' && withTot.total >= withTot.rows.length, 'with_total 返回 {rows,total}'); - const pg1 = await api('GET', '/api/sessions?limit=1'); - ok(Array.isArray(pg1) && pg1.length === 1, '默认数组响应兼容旧格式(limit=1)'); - const pg2 = await api('GET', '/api/sessions?limit=1&before=' + encodeURIComponent(pg1[0].updated_at) + '&before_id=' + pg1[0].id); - ok(Array.isArray(pg2) && pg2.length === 1 && pg2[0].id !== pg1[0].id, '游标翻页取到不同的下一页'); - const qt = await api('GET', '/api/sessions?q=' + encodeURIComponent(uniqTitle)); - ok(qt.some(x => x.id === fs9.id), 'q= 按标题命中'); - const qc = await api('GET', '/api/sessions?q=zzq-unique'); - ok(qc.some(x => x.id === fs9.id), 'q= 按消息内容命中'); - const qnone = await api('GET', '/api/sessions?q=绝无此内容xyzzy-9x7'); - ok(Array.isArray(qnone) && qnone.length === 0, 'q= 无命中返回空'); - // 附件消息:服务端在正文前拼【系统通知】行,与消息一并落库 - await api('POST', '/api/sessions/' + fs9.id + '/messages', { content: '', attachments: [{ name: 'a.png', size: 1536 }, { name: 'b.txt', size: 20 }] }); - const noticePrefix = '【系统通知】用户上传了文件:a.png(大小 1.5 KB)、b.txt(大小 20 B)'; - let attOk = false; - try { - await waitSession(fs9.id, x => x.messages.some(m => m.role === 'user' && m.content.indexOf(noticePrefix) === 0), 6000, '附件通知落库'); - attOk = true; - } catch (_) {} - ok(attOk, '附件提示词按格式拼接(文件名+大小)'); - // token 用量:model_usage 由 mock 上游的 usage 帧驱动,输入/输出分开统计 - const usagePool = await api('GET', '/api/models'); - const sumP = usagePool.reduce(function (n, m) { return n + (m.today_prompt || 0); }, 0); - const sumC = usagePool.reduce(function (n, m) { return n + (m.today_completion || 0); }, 0); - const sumTP = usagePool.reduce(function (n, m) { return n + (m.total_prompt || 0); }, 0); - ok(sumP > 0 && sumC > 0 && sumTP >= sumP, - '/api/models 携带今日/累计输入输出 token 用量', '今日输入=' + sumP + ' 今日输出=' + sumC); - - // ---- 10. 技能管理(阶段 3)---- - console.log('\n[10] 技能管理'); - ok((await api('POST', '/api/skills', { name: 'demo-skill', description: '演示技能' })).ok, '创建技能'); - let slist = await api('GET', '/api/skills'); - const demo = slist.find(x => x.name === 'demo-skill'); - ok(demo && demo.has_md && String(demo.description).includes('演示技能'), '列表含新技能与描述'); - let sdet = await api('GET', '/api/skills/demo-skill'); - ok(sdet.skill_md && sdet.skill_md.includes('demo-skill') && sdet.files.some(f => f.filename === 'SKILL.md'), '详情含 SKILL.md'); - await api('PUT', '/api/skills/demo-skill/file', { path: 'sub/run.sh', content: '#!/bin/sh\necho hi\n' }); - const sfr = await api('GET', '/api/skills/demo-skill/file?path=sub%2Frun.sh'); - ok(sfr.content.includes('echo hi'), '文件写入+读取(含子目录)'); - let trav = false; - try { await api('GET', '/api/skills/demo-skill/file?path=..%2F..%2Fetc%2Fpasswd'); } catch (e) { trav = /400/.test(e.message); } - ok(trav, '路径穿越被拒 400'); - const mkFd = txt => { const fd = new FormData(); fd.append('file', new Blob([txt]), 'note.txt'); return fd; }; - const up1 = await fetch(BASE + '/api/skills/demo-skill/upload', { method: 'POST', body: mkFd('up\n') }); - const up1j = await up1.json(); - ok(up1.ok && up1j.path === 'note.txt', '上传新文件'); - const up2 = await fetch(BASE + '/api/skills/demo-skill/upload', { method: 'POST', body: mkFd('dup\n') }); - ok(up2.status === 409, '重名上传默认 409'); - const up3 = await fetch(BASE + '/api/skills/demo-skill/upload?overwrite=true', { method: 'POST', body: mkFd('ovr\n') }); - ok(up3.ok, 'overwrite=true 覆盖上传'); - ok((await api('POST', '/api/skills/demo-skill/rename', { newName: 'demo-2' })).ok, '重命名技能'); - await api('DELETE', '/api/skills/demo-2/file?path=sub%2Frun.sh'); - sdet = await api('GET', '/api/skills/demo-2'); - ok(!sdet.files.some(f => f.filename === 'sub/run.sh') && sdet.files.some(f => f.filename === 'note.txt'), '删文件生效'); - ok((await api('DELETE', '/api/skills/demo-2')).ok, '删除整个技能'); - slist = await api('GET', '/api/skills'); - ok(!slist.some(x => x.name.indexOf('demo') === 0), '删除后列表干净'); - - // ---- 11. 系统状态与优雅重启(阶段 2;放在最后,服务进程将退出收尾)---- - console.log('\n[11] 优雅重启'); - const st = await api('GET', '/api/system/status'); - ok(st.ok && st.started_at && st.port === 8099, 'GET /api/system/status'); - s = await api('POST', '/api/sessions', { title: '冒烟-重启保护' }); - await waitSession(s.id, x => x.session.status === 'held' && !!x.session.model_id, 5000, '绑定(held)'); - await api('POST', '/api/sessions/' + s.id + '/messages', { content: '慢一点说' }); - await sleep(400); // 进入慢速流式输出,looping=true - let guarded = false; - try { await api('POST', '/api/system/restart'); } catch (e) { guarded = /409/.test(e.message); } - ok(guarded, '回合执行中 restart 被 409 拦截'); - const rj = await api('POST', '/api/system/restart?force=true'); - ok(rj && rj.restarting, 'force 重启被接受'); - await sleep(800); // 服务在响应后 300ms 退出 - ok(server.exitCode === 0, '服务以退出码 0 结束(交由 Docker 拉起)', 'exitCode=' + server.exitCode); - - console.log('\n========================'); - console.log('通过 ' + pass + ' / 失败 ' + fail); - // 不用 process.exit():会跳过 finally 的子进程清理,残留 mock/server 占住 9999/8099 干扰下次运行。 - process.exitCode = fail === 0 ? 0 : 2; - } catch (e) { - console.log('\n测试异常: ' + (e && e.stack || e)); - console.log('server 日志尾部:\n' + serverLog.slice(-2000)); - process.exitCode = 2; - } finally { - server.kill('SIGKILL'); - mock.kill('SIGKILL'); - } -} - -main(); diff --git a/app/test/trim-smoke.js b/app/test/trim-smoke.js deleted file mode 100644 index 86bfa2d..0000000 --- a/app/test/trim-smoke.js +++ /dev/null @@ -1,67 +0,0 @@ -// 临时冒烟:重负载占位裁剪(跑完即删)。 -const assert = require('assert'); -const llm = require('../server/llm'); - -const big = n => 'x'.repeat(n); -const mk = (id, role, extra) => Object.assign({ id, role, type: null, content: '' }, extra); -const call = (id, name, args) => ({ id, type: 'function', function: { name, arguments: JSON.stringify(args) } }); - -const rows = [ - mk(1, 'user', { content: '抓X存notes再写summary' }), - mk(2, 'assistant', { tool_calls: JSON.stringify([call('c1', 'fetch', { url: 'https://e.com/x' })]) }), - mk(3, 'tool', { tool_call_id: 'c1', name: 'fetch', content: 'HTTP 200\n' + big(8000) }), - mk(4, 'assistant', { tool_calls: JSON.stringify([call('c2', 'write_file', { path: 'notes.md', content: big(12000) })]) }), - mk(5, 'tool', { tool_call_id: 'c2', name: 'write_file', content: '已创建文件 notes.md(12003 字节)' }), - mk(6, 'assistant', { tool_calls: JSON.stringify([call('c3', 'write_file', { path: 'summary.md', content: '小内容' })]) }), - mk(7, 'tool', { tool_call_id: 'c3', name: 'write_file', content: '已创建文件 summary.md(9 字节)' }), - mk(8, 'assistant', { content: '两篇已写好' }), -]; -const session = () => ({ history: rows.slice(), profile_snapshot: '', blocksCache: new Map() }); - -// A) 全历史:距尾够远 → fetch 回执与 write_file(大) 参数被占位;write_file(小)/回执/收尾不动 -let msgs = llm.buildMessages(session(), 'Simplified Chinese', null, null); -const a = msgs.filter(m => m.role === 'assistant' && m.tool_calls); -const argsNotes = JSON.parse(a.find(m => m.tool_calls[0].id === 'c2').tool_calls[0].function.arguments); -assert(argsNotes.content === '[OMITTED, size=12000]', 'write_file 大参数应占位: ' + argsNotes.content); -const argsSum = JSON.parse(a.find(m => m.tool_calls[0].id === 'c3').tool_calls[0].function.arguments); -assert.strictEqual(argsSum.content, '小内容', '低于 TRIM_MIN 不裁'); -const t = msgs.find(m => m.role === 'tool' && m.tool_call_id === 'c1'); -assert(t.content === '[OMITTED, http_status=200, size=8009]', 'fetch 回执应占位: ' + t.content); -assert(msgs.find(m => m.role === 'tool' && m.tool_call_id === 'c2').content.includes('已创建文件'), 'write 回执不动'); - -// B) 截到第 5 行(write 刚落盘的当次调用):都太新鲜,不裁 -msgs = llm.buildMessages({ history: rows.slice(0, 5), profile_snapshot: '', blocksCache: new Map() }, 'Simplified Chinese', null, null); -assert(msgs.find(m => m.role === 'tool' && m.tool_call_id === 'c1').content.length > 7000, 'fetch 距尾 1 轮应保留'); -assert.strictEqual(JSON.parse(msgs.filter(m => m.tool_calls).pop().tool_calls[0].function.arguments).content.length, 12000, 'write 参数距尾 0 轮应保留'); - -// C) 压缩回合与常规拼装字节同构,仅尾部多一条指令(前缀缓存铁律) -const normal = llm.buildMessages(session(), 'Simplified Chinese', null, null); -const cm = llm.compressMessages(session(), 'Simplified Chinese', null, null); -assert(cm.length === normal.length + 1, '压缩=常规+尾指令'); -assert(JSON.stringify(cm.slice(0, -1)) === JSON.stringify(normal), '前缀字节同构'); -assert(/compact|concise/.test(cm.at(-1).content), '尾指令在位'); - -// D) read_file 回执同款 -const r3orig = rows[2]; -rows[2] = mk(3, 'tool', { tool_call_id: 'c1', name: 'read_file', content: 'HTTP 200\n' + big(8000) }); -rows[1] = mk(2, 'assistant', { tool_calls: JSON.stringify([call('c1', 'read_file', { path: 'a.md' })]) }); -msgs = llm.buildMessages(session(), 'Simplified Chinese', null, null); -assert(msgs.find(m => m.tool_call_id === 'c1' && m.role === 'tool').content === '[OMITTED, size=8009]', 'read_file 应占位'); -rows[2] = r3orig; -rows[1] = mk(2, 'assistant', { tool_calls: JSON.stringify([call('c1', 'fetch', { url: 'https://e.com/x' })]) }); - -// E) 开关:0=关 -llm.setPayloadTrim({ trim_write_rounds: 0, trim_result_rounds: 0 }); -msgs = llm.buildMessages(session(), 'Simplified Chinese', null, null); -assert(msgs.find(m => m.role === 'tool' && m.tool_call_id === 'c1').content.length > 7000, '0=关'); -llm.setPayloadTrim({}); // 回落默认 1/2 - -// F) 非法/缺失参数不炸(arguments 非 JSON、无 url 的 fetch;需距尾够远) -rows.push(mk(9, 'assistant', { tool_calls: JSON.stringify([call('c9', 'fetch', {})]) })); -rows.push(mk(10, 'tool', { tool_call_id: 'c9', name: 'fetch', content: 'HTTP 404\n' + big(700) })); -rows.push(mk(11, 'assistant', { content: '页面不存在,换个 url?' })); -rows.push(mk(12, 'assistant', { tool_calls: JSON.stringify([call('c12', 'read_file', { path: 'notes.md' })]) })); -msgs = llm.buildMessages(session(), 'Simplified Chinese', null, null); -assert(msgs.find(m => m.tool_call_id === 'c9').content === '[OMITTED, http_status=404, size=709]', '缺 url 仍占位: ' + msgs.find(m => m.tool_call_id === 'c9').content); - -console.log('TRIM-SMOKE-OK'); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 0c67fe0..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,792 +0,0 @@ -# Agent 内部架构说明 - -> 面向修改本仓库的开发者。对外能力与部署请看 [`../README.md`](../README.md)。 -> -> 本文只记录**代码实际行为**与修改时必须遵守的约束。设计动机写在相关注释里,这里不再重复。 - -## 1. 运行时拓扑 - -系统由四个进程角色组成,core 是唯一的业务与状态权威。 - -```mermaid -graph TB - B["浏览器 / PWA"] -->|"HTTP + Cookie + SSE"| C["agent-core :8090"] - W["微信用户"] -->|iLink| X["wxbot :8093"] - X -->|"/wxhook/*"| C - C -->|"/api/deliver"| X - C -->|"/exec, SSE"| E["agent-executor :9000"] - C -->|"/preview 反代"| P["预览网关 :3100"] - E --- P - C -->|"tools/call"| M["MCP 服务"] - C -->|"/chat/completions"| L["OpenAI 兼容上游"] - Z["外部服务(如智谱)"] -->|"匿名 GET /p/ID"| C - C --- T[("./tasks")] - C --- D[("./data")] - E --- T - E --- S[("./skills, 只读")] -``` - -| 角色 | 代码 | 持有 | 不持有 | -|---|---|---|---| -| core | `app/server/` | 配置密钥、SQLite、任务卷、模型调度、所有用户状态 | 无 | -| executor | `executor/server.js`、`executor/preview.js` | `EXECUTOR_TOKEN`、任务卷、只读技能卷 | 平台 API Key、登录密钥、SQLite | -| wxbot | `wxbot/app/src/server.js` | `WXBOT_TOKEN`、微信登录凭证 | 业务状态、配置密钥 | -| MCP | 外部进程 | 自身凭据 | core 状态;只通过 HTTP 交互 | - -信任边界: - -- 浏览器只与 core 通信;executor、wxbot、MCP 不暴露宿主机端口。 -- `GET /p/` 是唯一匿名业务端点,安全性完全依赖 22 字符随机 ID 与服务端过期表。 -- executor 只拿到共享服务 token,即使被攻破也拿不到模型 Key 或登录密钥。 -- MCP 服务是外部依赖,配置里的 `headers` 会随 `tools/call` 发送,按不可信服务对待。 - ---- - -## 2. 代码地图 - -```text -app/server/ -├── server.js 装配配置、DB、总线、路由;启动 MCP 发现与监听 -├── config.js YAML 加载/校验/规范化/读写;环境变量接线 -├── db.js SQLite 建表与幂等迁移 -├── engine.js 会话、模型池、Agent 主循环、上下文压缩、标题、日记收口 -├── llm.js 消息组装、上游流式调用、图片块、历史裁剪 -├── sse.js 按会话分组的 SSE 总线 + 进程内订阅 -├── auth.js Cookie/Basic 认证与管理员门禁 -├── scheduler.js cron 轮询、任务投递、完成通知 -├── memory.js 长期记忆存储、注入渲染、关键词检索 -├── user-profile.js 用户画像存储与快照冻结 -├── mcp.js Streamable HTTP MCP 客户端 -├── remote-exec.js executor 的 /exec 客户端 -├── public-files.js 公网临时文件短 ID 表 -├── download-token.js 浏览器下载链接签名 -├── download-send.js 下载响应头 -├── log.js 分级日志 -├── version.js 版本与 git 提交号 -├── tools/ -│ ├── definitions.json 内置工具 schema(14 项) -│ ├── executor.js 工具实现与派发 -│ └── skills.js 技能发现、校验、执行 -├── routes/ HTTP API(见 §5.15) -├── templates/ system prompt / 压缩 / 标题 prompt -└── public/ H5 前端(无构建,经典脚本按序加载) - -executor/ 独立的命令执行与 Office 预览服务 -wxbot/app/src/server.js 微信 iLink 调制解调器 -skills/ 技能目录;deps/ 为共享 Python 依赖 -``` - -仓库根 `docker-compose.yml` 把 `./app/server` 直接挂进 core 容器。改后端代码只需重启 core,不需要重建镜像;改依赖或 Node 版本才需要重建。 - ---- - -## 3. 启动顺序 - -`server.js` 的顺序有依赖,不要随意调整: - -1. `loadConfig`:读 `AGENT_CONFIG`,应用 `DEFAULTS`,规范化平台、profile、MCP、公网前缀,并从 env 注入 `executor` / `wxbot` 接线。 -2. `log.setLevel`、`llm.setPayloadTrim`。 -3. `initDb`:建表、迁移、清理孤儿日记碎片。 -4. `createBus`。 -5. `engine.setModelPool(cfg, db, bus)` + `engine.init()`: - - 按配置重建 `model_pool`; - - 把 `active` / 遗留 `queued` 会话归位为 `held`; - - 启动空闲扫描定时器(`auto_complete_ms` / `wrap_idle_ms`)。 -6. `scheduler.start(engine, notify)`:必须在 `engine.init()` 之后,否则首轮 tick 会看到旧状态。 -7. `memory.prune`:按 `retain_days` 兜底裁剪。 -8. `wechat.init`:注册总线内部监听。 -9. Express 装配,顺序固定: - - `/wxhook` 专用 JSON 解析器与回调路由,必须早于全局 `express.json`,因为媒体 base64 超过 2 MB; - - 全局 `express.json({limit:'2mb'})`; - - `auth.router`(登录等免认证端点); - - `/p` 公网文件路由,必须早于 `auth.middleware`; - - `auth.middleware`; - - `preview-proxy.earlyGuard`,必须早于静态首页,处理预览页对 `/` 的请求; - - 静态资源; - - 业务路由; - - `data-page`; - - `preview-proxy.mount`,必须最后,避免兜底吞掉现有路径。 -10. `mcp.init`:发现所有 MCP 工具;单个服务失败只告警。 -11. 生成技能清单快照并写入 system prompt。 -12. `server.listen`。 -13. `wechat.restore()` 与 `dumpPromptBundle()` 在监听后 fire-and-forget,失败不阻塞启动。 - -退出:`SIGTERM` / `SIGINT` 先 `bus.closeAllSessions()`,再 `server.close()`,3 秒后强制退出。 - ---- - -## 4. 数据模型 - -### 4.1 SQLite - -数据库默认 `data_root/.agent.db`,WAL 模式,`foreign_keys=ON`。使用 `better-sqlite3` 同步 API。 - -| 表 | 作用 | 关键字段 / 约束 | -|---|---|---| -| `sessions` | 会话 | `id`(`task-YYYYMMDD-NNN`)、`status`、`model_id`、`model_slot`、`last_model_id`、`user`、`profile_snapshot`、`title_locked`、`journaled_at` | -| `messages` | 对话 | `role`、`content`、`reasoning`、`tool_calls`、`tool_call_id`、`type`、`is_error`、`usage` | -| `files` | 上传/生成文件元数据 | 只记 `filename` / `size` / 时间;真实文件在任务目录 | -| `model_pool` | 模型 key 槽位 | 主键 `平台名#key下标`;只有 `last_used_at` 仍被调度使用 | -| `model_usage` | 每回合 token 用量 | 不建会话外键,删会话后统计保留 | -| `scheduled_tasks` | 定时任务 | 主键 `session_id`,天然「一会话一任务」;`ON DELETE CASCADE` | -| `channel_sessions` | 文本通道当前会话 | 主键 `(user, channel)`;不建外键,懒自愈 | -| `memory_fragments` | 长期记忆碎片 | 主键 `(user, session_id)`,每会话一片;`day` 是事件日 | -| `wechat_bindings` | 微信绑定 | `id` 同时是 channel 后缀与 wxbot 凭证目录名 | -| `user_profiles` | 用户画像 | `user` 主键;`data` 为封闭 JSON | -| `meta` | 持久计数器 | 如 `task_seq:YYYYMMDD` | -| `wait_queue` | 旧版排队表 | 已废弃,代码不读写 | - -迁移策略:`CREATE TABLE IF NOT EXISTS` + `PRAGMA table_info` 后按需 `ALTER TABLE`。新增列必须写成幂等迁移,不能假设新库。 - -### 4.2 文件布局 - -```text -// 会话工作目录 -├── .tmp/ 会话级 /tmp,跨 terminal 调用保留 -├── .imgcache/ read_file 图片压缩产物 -├── .app/ data-page 技能页面,按 /app// 暴露 -├── data.db db 工具与 /api/db//query -└── ... 用户上传与 AI 生成文件 -/.agent.db SQLite -/prompt.txt 启动时实际下发的 prompt/tools dump -// 技能;deps/ 为共享依赖 -``` - -### 4.3 会话状态 - -```mermaid -stateDiagram-v2 - [*] --> held: createSession - held --> active: 用户消息 / 换绑后续跑 - active --> active: 工具迭代 - active --> held: finalize 正常结束 - active --> cancelled: stop - held --> completed: releaseHold / auto_complete - completed --> active: 新消息 - cancelled --> active: 新消息 -``` - -- 新建会话立即是 `held`,第一条消息转 `active`。 -- `held` 不占任何资源,只是「还能追问」的视觉状态。 -- 任何非 `looping` 状态收到消息都会立即开跑,不再有排队。 -- 旧库可能有 `queued`,列表按活跃组展示,运行期不再产生。 - -### 4.4 消息类型 - -`messages.type` 是消息语义的唯一标记,改动时必须同时检查 `llm.buildMessages`、标题、日记、前端渲染。 - -| type | role | 语义 | 是否发给模型 | -|---|---|---|---| -| `NULL` | user/assistant/tool | 正常对话 | 是 | -| `archived` | 任意 | 已被压缩摘要替代的旧历史 | 否 | -| `summary` | assistant | 压缩摘要,后续上下文起点 | 是 | -| `errAck` | assistant | 工具参数非法的一轮 | 否,整轮替换为纠错提示 | -| `channel_note` | user | 微信环境说明 | 是 | -| `memory_note` | user | 开场日记注入 | 是 | -| `scheduler_note` | user | 定时任务删除等系统通知 | 是 | -| `wx_media` | user | 微信单发媒体留痕,不唤醒 AI | 是 | -| `summarize_request` | user | 旧版压缩指令 | 仅兼容旧库残留 | -| `task_brief` | user | 已废弃的任务书快照 | 是(仅历史兼容) | - ---- - -## 5. 核心模块 - -### 5.1 `engine.js` - -职责:会话生命周期、模型池调度、Agent 主循环、工具执行编排、压缩、标题、日记收口。 - -**模型池** - -- `cfg.models` 是 `platforms[].keys[] × models[]` 的打平视图。`id = 平台名/模型id`,`mid` 是发给上游的原始模型名,`key_index` 只用于定位物理 key。 -- `model_pool` 一行一个 `平台名#key下标`。key 是共享资源,不做独占。 -- `chooseKey(preferPlatform, strict)` 排序: - 1. 该槽位正在 `looping` 的会话数; - 2. 绑在该槽位上的 `active/held` 会话数; - 3. `last_used_at` 最久未用; - 4. 槽位 id。 -- `strict=true` 时只允许指定平台,找不到返回 `null`。 -- `createSession` 优先使用用户锁定模型,其次前端预选模型;不可用时退回全局调度。池为空直接抛 503。 -- `applyBinding` 写 `model_id`、`model_slot`、`last_model_id` 并刷新 `last_used_at`。 -- `ensureBinding` 在发消息前校验绑定;配置改动导致模型失效时自动改选,优先留在原平台。 -- `model_pool.is_busy` / `current_session_id` 是旧独占模型残留列,运行期不读写。 - -**模型 profile** - -`resolveProfileName(session)` 只取 `cfg.models[].profile`。会话级 profile 切换已移除;`sessions.profile` 列不再使用。 - -**工具集** - -`effectiveTools(profileName)` 的过滤顺序: - -1. 内置定义 + MCP 工具; -2. 若 profile 配了 `tools_allow`,先按白名单过滤;未配 = 全量;`[]` = 零工具; -3. 再按 `tools_deny` 过滤;profile 未配时继承全局 `tools_deny`,`deny` 优先。 - -默认全局 `tools_deny: [lab]`;`lab` profile 必须显式写 `tools_deny: []`,否则 `lab` 自己也会被屏蔽。名单只影响模型「看得到什么」,名单外但真实存在的工具被调用时仍会执行。 - -**主循环** - -`postUserMessage`: - -1. 落一条 user 消息。 -2. 记录 `run.deepThink`。 -3. 若会话正在 `looping`,返回 `delivered:'live'`,下一轮迭代会从 DB 重新加载历史。 -4. 否则 `ensureBinding` → 置 `active` → `runLoop`。 - -`runLoopInner` 每轮: - -1. 从 DB 重新读会话与历史,记录 `lastIncludedId`。 -2. 组装 messages(压缩回合走 `compressMessages`)。 -3. 工具集 = 内置 + MCP,经 profile allow/deny 过滤;压缩回合为空。 -4. `streamAssistant` 调用模型,流式转发 SSE。 -5. 失败重试:无 `upstream_status`、429、5xx 才重试,最多 `agent.max_retries` 次。 -6. 参数容错: - - `unwrapToolArgs` 剥掉 `{"arguments":{...}}` / `{"function":{...}}` 等外层; - - `schedule` 缺 `op` 且具 create 形状时补 `op=create`; - - `checkToolArgs` 校验 JSON 与必填;失败则整条 assistant 标 `errAck`。 -7. 保存 assistant 消息,写 `model_usage`,更新回合 In token 峰值。 -8. 无工具调用:若期间有新 user 消息则继续,否则结束回合。 -9. 有工具调用:逐个执行 `executeTool`,落 `tool` 消息,广播 `tool_call` / `tool_result`。 -10. 达到 `max_tool_iterations` 时写入停止提示。 - -**流式事件** - -`streamAssistant` 通过 `bus.emit` 发出: - -`assistant_delta`、`reasoning_delta`、`tool_call_start`、`tool_call_args`、`assistant_message`。 - -工具执行阶段发出 `tool_call`、`tool_result`。会话状态变化发出 `status`、`done`、`title`、`auto_compress`、`error`。MCP 卡片走 `ui_card`。 - -**图片回传** - -`read_file` 读图且会话模型 `vision:true` 时返回 `{text, image_rel}`。engine 把 `image_rel` 编成 `image_ref` 块存 DB;`llm.buildMessages` 在每次请求前重新签发公网链,避免回合内过期。同一回合同一张图只投递一次。 - -**收尾与标题** - -`finalize`: - -- 用户终止 → `cancelled`; -- 正常结束 → `held`,广播 `done`。 - -`maybeGenerateTitle` 在收尾时触发: - -- 本轮真实执行过工具,或非注入 user 正文 ≥3 条且总字数 ≥30; -- 用当前模型发一次**无 system、无 tools** 的请求; -- 结果清洗后写 `sessions.title` 并广播 `title`; -- 已有标题不覆盖;失败静默,下回合重试。 - -空闲扫描收口前 `wrapTitleFallback` 会无条件补题一次。 - -**上下文压缩** - -- 手动:`POST /:id/summarize` → `run.summarizing=true` → 开一个正常回合。 -- 该回合 `compressMessages`:正常 system + 正常历史 + 末尾 `prompt-compress.txt`,不传 tools。 -- 收尾答复落库后标 `type='summary'`;它之前的消息标 `type='archived'`。 -- 后续请求从摘要开始,`archived` 行只留在 UI。 -- `run.summarizing` 只在内存,重启丢失;压缩中禁止再次压缩或清空。 -- 自动提议:回合结束后若 `run.turnMaxPt >= agent.auto_compress_tokens`,延迟 1.5 秒发 `auto_compress` 事件;每会话最多一次,且只有存在 SSE 客户端时计数。 - -**空闲扫描** - -`startHeldSweeper` 的间隔取两个阈值较小者的 1/4,夹在 1 秒到 60 秒: - -- `sweepAutoComplete`:`held` 超过 `agent.auto_complete_ms` → `completed`。 -- `sweepJournalWrap`:未收口且 `updated_at` 超过 `memory.wrap_idle_ms` 的 `held/completed` 会话 → `journalFragment`;成功后归档 `held`、删除 `channel_sessions` 绑定。每批最多 5 个,避免重启后集中烧模型。 - -**日记与定时收口** - -- `journalFragment` 用候选模型链:原绑模型 → 同平台其它 → 配置顺序其它,最多 3 个。 -- 转录只保留正常 user/assistant 文本;跳过 `archived`、`channel_note`、`scheduler_note`、`memory_note`。 -- 成功或降级都写 `memory_fragments`,并写 `sessions.journaled_at` 防止重复摘要。 -- `taskClockOut`:本回合通过 `schedule` 工具创建任务后,`run.taskWrap=true`;`finalize` 广播 `done` 后调用。用任务 `brief` 生成模板化碎片(不调 LLM),归档 `held`,删除通道绑定。 - -**删除与清空** - -- `deleteSession`:停止回合 → 删消息/文件元数据/会话 → 删日记碎片 → 清 SSE 客户端;可选删任务目录。 -- `clearSessionMessages`:删全部消息、清 `.tmp`、清标题与 `journaled_at`、重新冻结画像快照;保留会话、模型绑定和任务目录。 -- 若该会话仍是定时任务「专柜」,清空时不删日记碎片,也不清 `journaled_at`。 -- `deleteMessage`:删 assistant 时连带删其 tool 回执;删 tool 回执时同步从父 assistant 的 `tool_calls` 摘除,保持调用与回执成对。 - -### 5.2 `llm.js` - -**System prompt** - -- 默认模板 `templates/profile-default.txt`,进程启动读一次。 -- `{APP_SKILLS_SECTION}` 由技能清单替换;自定义 profile prompt 没有占位符就不注入技能段。 -- 末尾追加 `## Reply Language`。 -- 结果按 `(profile, language)` 缓存。技能清单变化时清缓存。 -- 目标是**进程内字节恒定**,保护上游前缀缓存。 - -**消息组装** - -`buildMessages` 顺序: - -1. `system`; -2. `profile_snapshot`(会话创建/清空时冻结的画像); -3. 历史消息。 - -历史处理规则: - -- `archived` 跳过; -- `errAck` 整轮跳过,替换为一条纠错 user 消息,并回显模型上轮提交的参数形状; -- `tool` 回执按 `tool_call_id` 与 assistant 配对; -- 图片用 `{"__blocks__":[...]}` 哨兵 JSON 存储;发送时还原为 `text` + `image_url`; -- 未被消费的图片不放在 `tool` 消息里(非标准、上游支持差),而是收集到该批回执之后的一条 user 消息,先列逐图说明,再按顺序附图; -- 已消费的图片替换为文字标记; -- 历史裁剪:`write_file` 参数正文、`fetch` / `read_file` 回执,距尾超过配置轮数且正文超过 600 字时换成单行占位;DB 与 UI 不变。 - -**上游调用** - -`callModel` 请求 `POST /chat/completions`: - -- `body.model` 用 `mid`; -- 合并 `extra_params`; -- `deepThink` 为真时合并 `thinking_params`,可覆盖 `extra_params`; -- `reasoning_ack_field` 非空时,把历史中的 `__reasoning` 按该字段名写回 assistant 行,然后删除内部键; -- 解析 SSE,累积 content、reasoning、tool_calls 分片; -- 兼容 `reasoning` / `reasoning_content` 两种思维链字段; -- 支持 abort 与取消检查。 - -标题回合 `titleMessages`:无 system、无 tools,历史只保留 `NULL` / `summary` / `task_brief`,末尾追加 `prompt-title.txt`。 - -压缩回合 `compressMessages`:`buildMessages` 原样 + 末尾 `prompt-compress.txt`,必须与上一轮常规请求字节同构,只追加尾部指令,否则前缀缓存失效。 - -### 5.3 `tools/executor.js` - -**路径沙箱** - -`resolveInTask(taskDir, p)`: - -- 相对路径解析到当前会话目录; -- 绝对路径必须落在会话目录内; -- `/tmp` 重写为 `/.tmp`,与 executor 容器内 `/tmp` 的 bind 对齐; -- 越界抛错。 - -`@/` 由 `resolvePastPath` 解析: - -- 会话必须存在; -- 必须与当前会话同一 `user`; -- 只允许 `list_directory`、`read_file`、`copy_path` 的源路径; -- `write_file`、`edit_file`、`copy_path` 目标一律拒绝 `@`。 - -**内置工具** - -| 工具 | 实现要点 | -|---|---| -| `read_file` | 文本行号前缀;>16 KB 返回大纲;>32 MB 拒绝;图片经 `sharp` 压缩到 `.imgcache`,仅 vision 模型回传像素 | -| `write_file` | 自动建父目录;`content` 缺失或为 `null` 拒绝,避免误清空 | -| `edit_file` | 精确匹配优先,失败走忽略空白的模糊匹配;多处命中报错;保留缩进重排 | -| `list_directory` | 单层、最多 200 项;隐藏项不列;支持 `@` | -| `copy_path` | 文件或目录递归;符号链接拒绝;200 文件 / 200 MB 上限;目标不可覆盖 | -| `terminal` | 有 `EXECUTOR_URL` 走远端;否则本地 `spawn`。超时与用户终止都杀进程组;输出按 `head_lines` / `tail_lines` 选段 | -| `fetch` | HTML → Markdown;流式读取限 `max_bytes`;返回限 `max_chars`;`offset` 续读使用回合缓存;私网地址拒绝,重定向逐跳复查 | -| `mint_public_link` | 校验文件存在、在会话目录内、`realpath` 未越界;TTL 夹在 1 分钟到 24 小时 | -| `db` | 会话目录 `data.db`;每次调用开→用→关;`exec` / `query` / `insert` / `tables` / `schema`;查询上限 500 行 / 100 KB | -| `schedule` | 委托 `scheduler.js`;`op=create` 只作用于当前会话,并标记 `run.taskWrap` | -| `skill` | `list` / `get` / `run`;`visit_url` 在成功后补公网访问地址 | -| `profile` | 委托 `user-profile.js`;写操作只影响下个会话的快照 | -| `recall` | 委托 `memory.js`;`search` / `days` / `day`,只读当前用户 | -| `lab` | 元工具:`lab(tool, args)` 转发任意内置或 MCP 工具;`help` 是伪工具;禁止嵌套 `lab` | - -**派发** - -`executeTool` 先查 `HANDLERS`,未命中再查 `mcp.hasTool`。工具返回字符串;`read_file` 读图可返回 `{text, image_rel}`。未知工具返回 `Error: 未知工具 `。 - -### 5.4 `tools/skills.js` - -- 技能根目录:`cfg.skills_root`,缺省为 `workspace_root/../skills`。 -- 技能名必须是单层目录,拒绝 `/`、`..`、`.` 开头、`deps`。 -- `SKILL.md` 解析 YAML front matter:`description`、`input_schema`、`required`、`visit_url`。 -- `run` 前把相对路径参数按会话目录转绝对路径。 -- 入口优先 `run.py`(`python3`),其次 `run.sh`(`bash`),唯一参数是 JSON 字符串。 -- 有 executor 时命令交给远端,cwd 为会话目录;否则本地执行,cwd 为技能目录。 -- 超时默认 120 秒,杀整个进程组;用户终止同样杀组。 -- 技能目录在 executor 中只读,不允许运行期写回。 - -### 5.5 `mcp.js` - -- 传输:Streamable HTTP,JSON-RPC over POST;响应可能是普通 JSON,也可能是 SSE 帧。 -- 启动时逐服务 `initialize` → `notifications/initialized` → `tools/list`。 -- 服务返回 `Mcp-Session-Id` 时缓存;非 initialize 请求带 `Mcp-Session-Id`。400 且错误含 session 时重新握手并重试一次。 -- 每个服务可配 `tools_allow` / `tools_deny`,在重命名之前按原始工具名过滤。 -- 与内置工具或已存在 MCP 工具重名时,发送名加 `服务名__` 前缀。 -- `tools/call` 时下发: - - `X-Session-Dir`:会话任务目录; - - `X-Public-Base`:公网前缀。 -- 返回内容中的 `ui_card` 块不进入模型文本,转成 `ctx.onCard` → SSE `ui_card`。 -- 运行期不重新发现工具;改 MCP 配置需重启 core。 - -### 5.6 `remote-exec.js` - -- `POST /exec` 返回 SSE:`start` / `out` / `err` / `exit`;每 15 秒 `: ping`。 -- `run` 合并 stdout/stderr 为单个字符串,保留到达顺序。 -- 本地取消与超时通过 `DELETE /exec/:id` 杀远端进程组;本地看门狗在 `timeout_ms + 15s` 后兜底。 -- 句柄注册到 `run.procs`,`remoteKill` 供 `engine.stop` / 清空 / 删除时调用。 -- `killPreviewSession` 尽力清理 executor 侧的预览槽,失败只静默。 - -### 5.7 `agent-executor` - -`executor/server.js` 是零依赖单文件 HTTP 服务。 - -隔离模型: - -1. 宿主机 `./tasks` 挂到 `EXECUTOR_ISOLATION_BASE`(默认 `/mnt/host-tasks`),该路径不在 `EXECUTOR_ROOTS` 内。 -2. 每条命令在 `unshare --mount --pid --ipc --fork --propagation private` 中执行;有 Office 预览牢笼时先 `nsenter` 进同一 PID namespace。 -3. 先把当前会话目录 bind 到私有 tmpfs 的 anchor,再用空只读 tmpfs 遮盖 `/mnt`,最后把 anchor bind 回 `/workspace/tasks/`。 -4. 会话 `.tmp` bind 到容器 `/tmp`,实现同一会话跨命令保留临时文件。 -5. 根文件系统只读;`/dev/shm`、`/var/tmp`、`/run` 每次私有化;executor 自身代码目录用 tmpfs 遮盖。 -6. 启动自检验证 `ISOLATION_BASE` 是挂载点、`DEFAULT_CWD` 是空目录、`unshare` 可用、`/mnt` 遮盖不会封死工作区。 -7. cwd 必须落在 `EXECUTOR_ROOTS`,不得是任务根本身,不得含 `..`、空段、符号链接或指向基路径。 -8. 拒绝来自容器自身网卡 / 回环的 `/exec`:隔离没有独立 net namespace,否则 token 泄漏后可借 `/exec` 绕过隔离。 -9. 资源限制在 compose:2 CPU、2 GB 内存、512 PID、单文件 2 GB;`cap_drop: ALL` + `SYS_ADMIN`;`no-new-privileges`;`apparmor=unconfined`。 - -预览网关 `executor/preview.js`: - -- 监听 3100,只走内网。 -- 每个 `.docx/.xlsx/.pptx` 一个 `officecli watch` 槽位,闲置回收,访问时冷启动。 -- core 的 `/preview/**` 反代是唯一公网入口。 -- 详细链路见 [`OFFICE.md`](OFFICE.md)。 - -`executor/init-skills.js`:一次性把技能的 `requirements.txt` 装进 `skills/deps`,把 `install.sh` 的资产落到技能卷。系统层依赖仍由镜像的 `skills` 构建阶段烘入。 - -### 5.8 `scheduler.js` - -- 表 `scheduled_tasks`,主键 `session_id`,每会话最多一条。 -- 轮询周期 30 秒;cron 时区 `Asia/Shanghai`。 -- `validateCron` 要求 cron 可解析且相邻两次间隔 ≥1 小时。 -- 触发前先把该会话全部消息标 `archived`,再 `postUserMessage` 投递提示词;顺序不可反,否则回合会带旧上下文开跑。 -- 若会话仍 `active`,本次标记 `skipped`,不投递。 -- `running` 状态没有回合结束回调,靠下一轮 tick 看到会话非 `active` 推断为 `ok`。 -- 完成/失败通过 `fireNotify` 交给 `wechat.notifyTask`;通知正文取触发后最后一条纯文本 assistant 消息,附件取触发后新增文件。 -- `schedule` 工具的 `list` 可跨会话查看当前用户全部任务;`create` 只作用于当前会话。 -- 通过 Web 弹窗手动创建的任务直接调用 `scheduler.createTask`,不经过 `run.taskWrap`,因此不会触发 `taskClockOut`;只有 AI 工具路径会在回合收尾时把当前会话收口为任务专柜。 - -### 5.9 `memory.js` - -- `memory_fragments(user, session_id PK, day, text, created_at)`。 -- `day` 是来源会话最后活跃日,不是补记日。 -- `appendFragment` 用 `INSERT OR IGNORE`,`(user, session_id)` 主键天然去重。 -- `journalFor` 取最近 `inject_max` 片,按 `day DESC, created_at DESC`;渲染为 `## id=, day=` + 正文。 -- `injectedIds` 与 `journalFor` 共用同一选取顺序,供调试页标「已注入」。 -- `searchFragments` 在内存里做关键词打分:空白/标点分词,CJK 长词用二元字组过半模糊命中。 -- `retain_days=0` 永久保留;正数按 `day` 硬删。 -- `dropFragment` 在删会话或清空会话时调用。 -- `journalFragment` 的摘要生成在 `engine.js`,`memory.js` 只做存储与读取。 - -### 5.10 `user-profile.js` - -- 三个字段:`honorific`、`industry`、`preference`。 -- `preference` 是顿号分隔的标签列表;工具只做增量 add/remove,不整段覆写。 -- 会话创建或清空时 `freezeSnapshot` 把渲染文本写入 `sessions.profile_snapshot`。 -- `buildMessages` 每轮把它作为 system 后首条 user 注入;字节恒定,且不在 `messages` 表里,压缩和归档都碰不到。 -- 写操作只影响下个会话;停用 `enabled=0` 时拒写不拒读。 -- 与 `model_profiles` 是两回事:后者是 prompt + 工具组合。 - -### 5.11 `auth.js` - -- `auth.users` 为空 → 认证整体关闭。 -- 登录成功签发 `payload.signature` 的 HMAC token,写入 `agent_token` Cookie:`HttpOnly`、`SameSite=Lax`、可配 TTL。 -- 身份解析 cookie 优先,`Authorization: Basic` 兜底。 -- `/api/login_restore` 用 Bearer 验签恢复 Cookie,服务 WebView 冷启动。 -- 管理员接口:`/api/config`、`/api/users`、`/api/system/restart`。 -- 未认证访问 API 返回 401,页面 302 到 `/login?next=...`。 -- 注意:认证是**外围门禁**,不是资源级 ACL;除管理员接口外,业务路由只检查「已登录」。 - -### 5.12 `sse.js` - -- `clients: session_id -> Set`。 -- `emit` 先跑内部订阅者,再写 HTTP 客户端;没有客户端时静默丢弃。 -- `onInternal` 供 `wechat.js` 监听回合事件,不受「无观看者」影响。 -- `closeAllSessions` 用于进程退出,先掐断长连接,`server.close` 才能返回。 - -### 5.13 `channel.js` + `wechat.js` + `wxbot` - -**文本命令层** - -- `channel_sessions(user, channel)` 记录每个接入端的当前会话。 -- 命令只在 `POST /api/channel/send` 与微信 `handleSend` 中解析;Web 聊天里以 `/` 开头的内容照常发给模型。 -- 命令表:`/new`、`/list`、`/switch`、`/rename`、`/delete`、`/models`、`/think`、`/stop`、`/compact`、`/clear`、`/status`、`/help`。 -- 首词是 `/纯 ASCII` 但不在命令表 → 回「未知命令」,不转发模型;其他 `/xxx` 按普通消息处理。 -- 命令动作本身不落消息行;`/new` 的尾随文本与普通消息照常入库。 -- 数据面全部复用 `engine`,不维护第二套会话逻辑。 - -**微信桥** - -- `wechat_bindings` 是 core 用户 ↔ wxbot 实例的唯一权威。 -- wxbot → core:`POST /wxhook/inbox`(消息)与 `/wxhook/hook`(状态)。挂在全局 JSON 解析与认证之前,凭 Bearer `WXBOT_TOKEN` 把门,媒体解析上限 32 MB。 -- core → wxbot:`/api/instances*` 控制实例与扫码,`/api/deliver` 推文本,`/api/deliver_media` 推附件,`/api/typing` 推「正在输入」。 -- 入站普通消息 → `channel.handleSend`;无当前会话则自动新建并绑定。 -- 媒体先落会话目录、写 `files` 表,再拼「用户上传了文件:<名>」作为正文;单发媒体写 `wx_media` 留痕,不唤醒 AI。 -- 新微信会话注入两类消息: - - `channel_note`:微信环境说明; - - `memory_note`:最近 `inject_max` 条日记。 -- 出站由总线内部监听驱动,按绑定串行投递,`last_msg_id` 游标防重复。 -- 回复预算:iLink 每个 context token 约 10 条。过程消息最多直发 1 条,其余省略并在结论前注记;结论放不下时截头部 + 全文落 `.md` 文件卡片;预算不足则放弃并告警,网页端仍完整可见。 -- 正文里的 `/p/<22位>` 链接会转成本地文件卡片,限 5 个、单文件 20 MB,按同用户校验。 -- `/think on|off` 写 `wechat_bindings.deep_think`,投递消息时作为 `deepThink` 参数。 -- 定时任务通知:优先发创建时记录的 `notify_channel`;没有则发给该用户全部在线绑定;若任务会话仍是该绑定的当前会话且状态为 `ok`,跳过重复通知。 - -**wxbot** - -- iLink SDK 多实例;每个绑定一个实例、一个凭证目录 `bot.storage_dir//`。 -- 不保存业务状态;启动扫描凭证目录拉起实例,状态回报失败不影响上线,首条消息会纠偏。 -- 除 `/health` 外全部要求 Bearer `WXBOT_TOKEN`。 -- `WXBOT_STRIP_MARKDOWN=1` 时出口剥 Markdown;默认透传(微信已支持渲染)。 -- 语音由 iLink 侧转写成文本,按普通文本转发。 - -### 5.14 `config.js` - -- `DEFAULTS` 是运行时默认值;`config.yml` 与之深合并。 -- `platforms` 兼容旧版扁平 `models[]`,自动迁移为平台层级。 -- 平台内部唯一键:`平台名/模型id`;跨平台允许同名。 -- `type` 决定余额查询适配器,缺省取平台名;未知类型查询返回 400,不静默回退。 -- `model_profiles` 在加载时把 `system_prompt_file` 读入内存;相对路径基于 `server/templates/`。 -- `executor` 与 `wxbot` 不是 YAML 字段,只从 env 读取。 -- `public_link.base_url` 优先取 `VIRTUAL_HOST`(`https://<第一个域名>`),其次 YAML;TTL 夹在 1 分钟到 24 小时。 -- 设置页写配置:先 `parseAndValidate`,再整份写回;不做临时文件 + rename,因为容器里 `config.yml` 是单文件 bind mount,rename 会 `EBUSY`。 -- 读取原文时对 `api_key`、`password`、MCP `headers` 值脱敏;提交时按掩码还原。 -- 配置是冷加载:写盘后必须重启 core。 - -### 5.15 路由与前端 - -**路由挂载** - -| 前缀 | 文件 | 说明 | -|---|---|---| -| `/wxhook` | `routes/wechat.js` | wxbot 内网回调,Bearer 服务 token | -| `/p` | `routes/public-files.js` | 匿名取用公网临时文件 | -| `/api/sessions` | `sessions.js` / `messages.js` / `files.js` | 会话、消息、SSE、上传下载 | -| `/api/skills` | `skills.js` | 技能与技能文件管理 | -| `/api/config` | `config.js` | 配置读写,管理员 | -| `/api/platforms` | `platforms.js` | 余额查询 | -| `/api/system` | `system.js` | 状态与重启;重启仅管理员 | -| `/api/users` | `users.js` | 用户管理,管理员 | -| `/api/profile` | `profile.js` | 当前用户画像 | -| `/api/memory` | `memory.js` | 日记只读调试 | -| `/api/wechat` | `wechat.js` | 绑定管理与二维码 | -| `/api/channel` | `channel.js` | 文本命令接入 | -| `/api/models` | `server.js` | 模型池状态与 token 用量 | -| `/api/health` | `server.js` | 健康检查,免认证 | -| `/app//` | `data-page.js` | 任务 `.app/` 静态页 | -| `/api/db//query` | `data-page.js` | 任务 `data.db` SQL API | -| `/preview/**` | `preview-proxy.js` | Office 预览反代,登录门禁 | - -**前端** - -- `index.html` + `js/core.js`、`chat.js`、`sessions.js`、`stream.js`、`files.js`、`settings.js`,按顺序加载,共享全局作用域。 -- 无构建步骤;`settings.js` 必须最后加载,因为包含全局初始化。 -- `login.html` 只依赖 `css/style.css`。 -- `memory.html` 是日记调试页。 -- 渲染消息时按 `type` 处理摘要、存档、工具卡、图片、token 用量。 -- 历史消息懒加载:`GET /api/sessions/:id?limit=...&before=...`;工具结果单独按消息 id 拉取。 - ---- - -## 6. 关键流程 - -### 6.1 发消息到回复 - -```mermaid -sequenceDiagram - participant B as 浏览器 - participant C as core - participant L as 模型上游 - participant E as executor - B->>C: POST /api/sessions/{id}/messages - C-->>B: delivered=live - C->>L: chat/completions (stream) - L-->>C: text / tool_calls - C-->>B: SSE assistant_delta - C->>E: POST /exec (如有 terminal) - E-->>C: start / out / exit - C-->>B: SSE tool_call / tool_result - C->>L: 下一轮请求(带工具回执) - L-->>C: 最终文本 - C-->>B: SSE assistant_message / done -``` - -1. 用户消息落库,`run` 记录 `deepThink`。 -2. 会话非 `looping` 则置 `active` 并开跑;正在跑则只投递,下一轮迭代自动带上。 -3. 每轮从 DB 重读历史,组装 messages 与 tools。 -4. 模型流式输出;工具调用经参数校验、解包、执行、落库、广播。 -5. 无工具调用则收尾;有新用户消息则继续。 -6. `finalize` 进入 `held`,发 `done`,触发标题与自动压缩检查。 - -### 6.2 工具执行 - -- 内置工具在 core 进程内执行,文件类直接在任务目录操作。 -- `terminal` 与 `skill` 在有 `EXECUTOR_URL` 时走远端。 -- 未命中内置工具则查 MCP 注册表。 -- 工具回执先落库再广播,前端工具卡可据此定位消息行。 -- 执行抛错转 `Error: ...`,`is_error=1`,模型能看到失败原因。 -- 用户终止时 `run.cancelled` 置位,本地杀进程组、远端发 DELETE、中止模型流。 - -### 6.3 压缩 - -1. 用户点「压缩」或确认自动提议。 -2. `summarizeContext` 置 `run.summarizing`,开一个正常回合。 -3. 该回合不传 tools,末尾追加压缩提示词。 -4. 收尾答复标 `summary`,之前消息标 `archived`。 -5. 前端把摘要卡片之前的消息淡出;后续请求从摘要开始。 - -### 6.4 定时任务 - -1. AI 调 `schedule op=create`,`scheduler.createTask` 校验 cron 与间隔。 -2. `run.taskWrap=true`;当前回合 `finalize` 后 `taskClockOut`:写任务 brief 碎片、归档、解绑通道。 -3. `scheduler.tick` 每 30 秒检查到期任务。 -4. 先 `archiveHistory`,再 `postUserMessage`。 -5. 下一轮 tick 看到会话非 `active`,标 `ok` 并通知。 - -### 6.5 微信 - -1. wxbot 收到消息,`POST /wxhook/inbox`。 -2. core 校验绑定,必要时把媒体落盘。 -3. `channel.ensureSession` 找到当前会话;没有则新建。 -4. 新会话注入 `channel_note` 与 `memory_note`。 -5. 普通消息走 `handleSend` → `engine.postUserMessage`。 -6. 回合事件经 `sse.onInternal` 进入串行投递链,按预算推给 wxbot。 -7. 用户下条消息到达时重置回合预算。 - -### 6.6 日记收口 - -1. `sweepJournalWrap` 找到静默超阈值的 `held/completed` 会话。 -2. `journalFragment` 组装转录,依次尝试候选模型。 -3. 清洗为 `- ` 行,写 `memory_fragments`,写 `journaled_at`。 -4. 归档 `held`,删除 `channel_sessions` 绑定。 -5. 微信下一条消息自动新建会话,并注入最近日记。 - ---- - -## 7. 修改时必须遵守的约束 - -1. **core 单实例**。`runs`、`titling`、`journaling`、SSE 客户端、`public-files` 表、下载签名密钥都在进程内存。多副本部署会破坏会话状态、SSE 和链接有效性。 -2. **配置冷加载**。改 `config.yml` 后重启;运行期不要假设 `cfg` 会变。 -3. **system prompt 在两次变更之间字节稳定**。默认模板、技能清单、语言后缀在进程内恒定;按 `profile + language` 缓存,技能清单变化时清缓存。任何每轮变化的内容不要塞进 system 开头,否则前缀缓存全断。 -4. **压缩请求与常规请求同构**。压缩只能追加尾部指令,不能删画像快照、不能改中间历史。 -5. **`archived` 与 UI 解耦**。UI 展示全部历史,模型只看未归档;不要让前端删除 `archived` 行。 -6. **工具调用与回执成对**。删 assistant 必须连带删 tool 回执;删 tool 回执必须从父 assistant 的 `tool_calls` 摘除。 -7. **`errAck` 整轮隔离**。参数错误的 assistant 行与关联 tool 行都不进模型上下文,用一条纠错 user 消息替代。 -8. **路径沙箱**。所有文件工具必须经 `resolveInTask`;`@` 路径只能读、只能同用户。 -9. **公网链接校验**。`mint` 前必须 `realpath` 确认文件仍在任务目录内;`/p` 端只按 ID 查表。 -10. **executor 不含密钥**。不要把 `config.yml`、平台 Key、`AUTH_SECRET` 挂进 executor / wxbot。 -11. **隔离层只允许 mount,不允许 umount `ISOLATION_BASE`**。容器根 mount table 是 shared,umount 可能传播回父 namespace,导致数据卷被摘。 -12. **消息类型改动要全链路检查**。至少覆盖 `llm.buildMessages`、`titleMessages`、`journalTranscript`、前端 `chat.js`。 -13. **定时任务一会话一条**。主键 `session_id` 是约束,不要改成多任务而不改 UI 与工具语义。 -14. **日记与来源会话同生共死**。删会话删碎片;清空会话默认删碎片,任务专柜例外。 -15. **登录不是资源 ACL**。新增业务路由默认对所有登录用户开放;若需要按用户隔离,必须在路由层显式校验 `session.user`。 - ---- - -## 8. 扩展点 - -### 8.1 新增内置工具 - -1. `tools/definitions.json` 加 OpenAI function 定义。 -2. `tools/executor.js` 加 handler,并注册到 `HANDLERS`。 -3. 需要出现在 `lab help` 的话,确保在 `definitions.json` 中。 -4. 参数遵循 [`tool-design.md`](tool-design.md):共享资源用 `op` 分派,条件必填写进 description。 -5. 默认会被全局 `tools_deny` 过滤;如果希望默认可见,不要加进 `DEFAULTS.tools_deny`。 - -### 8.2 新增技能 - -- 在 `skills//` 放 `SKILL.md` 与入口。 -- 需要 Python 依赖:`requirements.txt`,重新构建 `agent-executor` 或运行 `agent-executor-init`。 -- 需要系统包:只能改 `executor/Dockerfile` 的 `base` 阶段并重建。 -- 设置页创建/改文件后会触发技能清单刷新,不需要重启。 - -### 8.3 新增 MCP 服务 - -```yaml -mcp_servers: - - name: my_service - url: http://my_service:3000/mcp - headers: { Authorization: "Bearer ..." } - enable: true - timeout_ms: 60000 - tools_allow: [tool_a, tool_b] - tools_deny: [tool_c] -``` - -重启 core 生效。服务不可达只告警;重名工具自动加 `my_service__` 前缀。 - -### 8.4 新增模型或平台 - -- 平台加在 `platforms`,模型加在平台 `models`。 -- 模型内部键自动是 `平台名/模型id`。 -- 余额查询:在 `balance.js` 的 `ADAPTERS` 增加 `type` 对应实现。 -- 新增 profile:在 `model_profiles` 加条目,模型用 `profile: <名>` 引用。 - -### 8.5 新增 HTTP 路由 - -- 在 `app/server/routes/` 新建 `express.Router`。 -- 在 `server.js` 挂载,注意放在 `auth.middleware` 之后;需要免认证则显式放在之前。 -- 错误统一用 `{error}` JSON;状态码优先取 `err.status_code`。 -- 需要按用户隔离时自行校验 `req.user` 与会话 `user`。 - -### 8.6 新增 SSE 事件 - -- `bus.emit(sessionId, name, data)`。 -- 前端 `stream.js` 增加监听。 -- 微信投递只关心 `assistant_message` / `done` / `tool_call` / `tool_result` / `reasoning_delta` / `ui_card`;其他事件不会进微信。 - -### 8.7 新增预览服务 - -- 在 `preview-proxy.js` 的 `PREVIEW_PROXIES` 注册 `{name, prefix, host, port}`。 -- 服务自行解析前缀后的路径与槽位。 -- core 只做登录门禁、头白名单转发、Referer 兜底。 -- 预览页硬编码的根绝对路径请求依赖 Referer 识别,设计时尽量避免。 - -### 8.8 前端改动 - -- 保持无构建、经典脚本按序加载。 -- 新增模块要排在 `settings.js` 之前。 -- 消息渲染统一走 `chat.js` 的 `msgNode` / `appendMessagesDom`,不要在别处复制一套。 -- 新增设置项优先加到 `settings.js` 的 `CFG_FORM`,走统一配置编辑接口。 - ---- - -## 9. 测试与调试 - -```bash -cd app -npm test # mock 上游 + 真 server 的端到端测试 -node test/remote-exec.test.js -node test/trim-smoke.js -node test/dep-check.js -cd ../executor && node smoke-test.js -``` - -- `npm test` 固定使用 8099(server)和 9999(mock 上游);端口被占用会直接失败,先清理残留进程。 -- 已知:`smoke.js` 仍保留旧 API 断言——排队已从运行期移除,`GET /api/sessions/:id` 也不再直接返回 `role=tool` 行(改为按需加载)。当前 `npm test` 会在 `[2] 工具调用` 与 `[5] 排队调度` 失败;改动相关路径时先同步测试。 -- 测试使用的配置是 `app/test/config.test.yml`,数据隔离在 `app/test/tmp`。 -- core 日志等级:`config.yml` 的 `log_level`;改完重启。 -- executor / wxbot 日志等级:`EXECUTOR_LOG_LEVEL` / `WXBOT_LOG_LEVEL`,`debug` 打印完整交互。 -- `data/prompt.txt` 是启动时实际下发的 system prompt 与各 profile 工具清单,用于核对「模型到底看到了什么」。 -- `/api/system/status` 返回版本、运行时长、路径、模型池、容器负载、上传参数。 -- `/memory.html` 查看日记碎片、实际注入文本、已收口会话。 -- 调试 executor 隔离:先看启动自检日志;运行中连续 session miss 会打 error。 - ---- - -## 10. 已知边界与陷阱 - -- **认证边界**:会话、消息、文件 API 不做按用户授权;前端列表隔离不等于后端 ACL。 -- **`keys[].concurrency` 已解析但未参与调度**。模型池按「最少 looping / 最少在用 / 最久未用」选 key,不读取该字段。 -- **`model_pool.is_busy`、`current_session_id`、`wait_queue`、`sessions.profile`、`config.model_hold` 都是历史残留**,不要在新代码里使用。 -- **`sessions.assistant_type` 只影响前端图标**,不改变模型、prompt 或工具集。 -- **Web 会话不会自动注入长期记忆**。`memory_note` 只在微信新会话创建时写入;Web 会话可用 `recall` 主动查。 -- **日记只在空闲收口或定时任务收口时生成**,不是每条消息实时写。 -- **清空会话默认删日记碎片**;只有仍是定时任务专柜的会话保留碎片与 `journaled_at`。 -- **自动压缩提议是进程内状态**:每会话最多一次,重启重置;没有 SSE 观看者时不计数。 -- **`public-files` 与下载签名密钥都在内存**:重启后旧链接、旧下载 token 全部失效。 -- **`config.yml` 写盘不是原子替换**:单文件 bind mount 下 rename 会 `EBUSY`,因此采用「先校验后整份写」。 -- **executor 没有独立 net namespace**:所以必须靠「拒绝本机来源」防止借用;`EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 只能用于本机测试。 -- **executor 是命令沙箱,不是内核级安全边界**:它限制文件视图、能力、资源和可写层,但不防内核漏洞或 `SYS_ADMIN` 滥用。 -- **预览与 data-page 的信任模型是「登录 ≈ 运维」**:登录用户可访问任意会话的预览页与 SQL API,与 §7 第 15 条一致。 -- **定时任务 `ok` 是推断值**:回合异常结束但没有明确错误时,也可能被标成 `ok`。 -- **微信回复配额是经验值**:`REPLY_QUOTA=10`,上游实际额度不可查;预算不足时结论可能未投递,网页端仍完整可见。 -- **`VIRTUAL_HOST` 优先于 `public_link.base_url`**:仓库默认 compose 带 `VIRTUAL_HOST=agent.ai.foresh.com`,不接反向代理时会生成错误的公网链接。 -- **`my-app-network` 是 external**:首次部署必须先创建,否则 compose 直接失败。 -- **技能系统层依赖烘在镜像里**:运行期不能 `apt-get install`;新增系统包必须重建 executor 镜像。 -- **`agent-executor-init` 只挂 `./skills`**:它看不到任务数据,也不应该看到。 diff --git a/scripts/init.sh b/scripts/init.sh index 755f4f1..88203f2 100755 --- a/scripts/init.sh +++ b/scripts/init.sh @@ -10,9 +10,11 @@ # # 输入(都可选): # BIGMODEL_KEY / DEEPSEEK_KEY / QWEN_KEY 模型平台 key,填几个启用几个(0~3 个) -# ZHIPU_KEY image_task / video_task 的智谱 key(空 = 这两个服务 enable: false) +# image_task / video_task 复用 BIGMODEL_KEY(智谱即 BigModel); +# 未配 BIGMODEL_KEY 时这两个服务写为 enable: false # AUTH_USER / AUTH_PASSWORD 登录账号(默认 admin / admin,请自行改掉) -# PUBLIC_IP / AGENT_PORT 对外地址与端口,写进 public_link.base_url(PUBLIC_IP 空则尝试自动探测) +# PUBLIC_IP / AGENT_PORT 对外地址与端口,写进 public_link.base_url; +# PUBLIC_IP 不配置则自动探测公网 IP # AUTH_SECRET / EXECUTOR_TOKEN / WXBOT_TOKEN 一般不用给:不给就自动生成并复用(见下) # # 微信接入(wxbot 已合入根 compose,作为栈内服务):本脚本只负责生成/复用根 .env 的 WXBOT_TOKEN; @@ -39,7 +41,6 @@ ENV_FILE="$REPO_DIR/.env" BIGMODEL_KEY="${BIGMODEL_KEY:-}" DEEPSEEK_KEY="${DEEPSEEK_KEY:-}" QWEN_KEY="${QWEN_KEY:-}" -ZHIPU_KEY="${ZHIPU_KEY:-}" AUTH_USER="${AUTH_USER:-admin}" AUTH_PASSWORD="${AUTH_PASSWORD:-admin}" PUBLIC_IP="${PUBLIC_IP:-}" @@ -202,29 +203,27 @@ auth: mcp_servers: - name: web_search url: "http://mcp_web_search:3000/" - - name: officecli - url: "http://mcp_officecli:3000/" # Office 文档创建/修改(无需 key);预览走 core 的 /preview 反代 EOF - if [ -n "$ZHIPU_KEY" ]; then + if [ -n "$BIGMODEL_KEY" ]; then cat < "$CONFIG_YML" -info "平台: ${enabled_plats[*]:-无};智谱 MCP: $([ -n "$ZHIPU_KEY" ] && echo 启用 || echo 未配置(enable: false))" +info "平台: ${enabled_plats[*]:-无};图像/视频 MCP: $([ -n "$BIGMODEL_KEY" ] && echo 启用 || echo 未配置(enable: false))" # ============================================================ # 3. 汇总 @@ -247,7 +246,7 @@ echo " 访问地址 : http://${PUBLIC_IP:-<公网IP>}:${AGENT_PORT}" echo " 账号 : $AUTH_USER" echo " 密码 : $AUTH_PASSWORD" echo " 平台 : ${enabled_plats[*]:-(无)}" -echo " 智谱 MCP : $([ -n "$ZHIPU_KEY" ] && echo "image_task / video_task 已启用" || echo "未配置(enable: false)")" +echo " 图像/视频: $([ -n "$BIGMODEL_KEY" ] && echo "image_task / video_task 已启用" || echo "未配置(enable: false)")" echo " Office : officecli 已接入(mcp_officecli:3000;预览走 /preview 反代)" echo " 微信接入 : WXBOT_TOKEN 已就位(compose 注入 core 与 wxbot 两侧;wxbot 无需配置文件)" echo "---------------------------------------------"