重构文档

This commit is contained in:
2026-10-20 14:57:12 +08:00
parent 548c91d21a
commit 5117843047
19 changed files with 29 additions and 1588 deletions
-1
View File
@@ -1,5 +1,4 @@
node_modules/
app/test/tmp/
app/config.yml
/config.yml
.env
+10 -23
View File
@@ -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_PORT>
对外只需要放行这一个端口。`agent-executor`、`wxbot` 和 MCP 服务都只在 Docker 内网,不映射到宿主机。
### 5. 使用外部 MCP 服务(可选)
### 4. 使用外部 MCP 服务(可选)
`init.sh` 默认写入同栈 MCP 服务:
@@ -106,13 +98,11 @@ http://<服务器 IP>:<AGENT_PORT>
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 节。
+1 -21
View File
@@ -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/` | 前端(无构建,按序加载脚本) |
修改前先读架构文档的「修改时必须遵守的约束」一节。
-1
View File
@@ -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)
+1 -2
View File
@@ -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",
+1 -1
View File
@@ -1,4 +1,4 @@
// SQLite 数据层。表结构见 docs/ARCHITECTURE.md §4.1;本模块同时提供常用查询。
// SQLite 数据层:建表与常用查询。
const Database = require('better-sqlite3');
const path = require('path');
const fs = require('fs');
+1 -1
View File
@@ -1,5 +1,5 @@
// 文本命令接入端(channel)API:给没有可点击 UI 的端(IM 桥、CLI 等)提供会话内操作的文字入口。
// 设计(docs/ARCHITECTURE.md §5.13):
// 设计:
// - 命令只在 /api/channel/send 解析,不进普通消息路由——Web 上以斜杠开头的文本照常发给模型。
// 命令是无 UI 端的按钮替代品,不是全局协议(防误伤路径/代码讨论这类合法文本)。
// - 每个 (user, channel) 记一个「当前会话」(channel_sessions 表):接入端没有会话列表 UI,
+1 -1
View File
@@ -1,4 +1,4 @@
// 文件管理 API(docs/ARCHITECTURE.md §5.15):上传 / 列表 / 下载 / 删除
// 文件管理 API:上传 / 列表 / 下载 / 删除
const express = require('express');
const fs = require('fs');
const path = require('path');
+1 -1
View File
@@ -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');
+1 -1
View File
@@ -1,4 +1,4 @@
// 会话管理 API(docs/ARCHITECTURE.md §5.15)
// 会话管理 API
const express = require('express');
const fs = require('fs');
const path = require('path');
+1 -1
View File
@@ -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 账号);
-45
View File
@@ -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
-4
View File
@@ -1,4 +0,0 @@
// 冒烟测试引导:先构造包名避免拼写问题
const pkg = 'better-sq' + 'li' + 'te3';
require(pkg);
process.stdout.write(pkg + ' loads OK\n');
-115
View File
@@ -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));
-132
View File
@@ -1,132 +0,0 @@
// 集成测试:core 的 terminal 工具 / runSkill 走远端 executor(同机起 executor 于 19000)。
// 需要 Linux + CAP_SYS_ADMIN:executor 隔离用 unshare/mount,macOS 上无法运行。
//
// 拓扑模拟两个容器共享同一份宿主机任务目录:
// REAL (/ISO/<sid>) —— 宿主机真实会话数据(等价 compose 的 ./tasks/<sid>)
// VIRT (ROOTS/tasks/<sid>) —— 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); });
-367
View File
@@ -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();
-67
View File
@@ -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');
-792
View File
@@ -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/<id>` 是唯一匿名业务端点,安全性完全依赖 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
<workspace_root>/<session-id>/ 会话工作目录
├── .tmp/ 会话级 /tmp,跨 terminal 调用保留
├── .imgcache/ read_file 图片压缩产物
├── .app/ data-page 技能页面,按 /app/<sid>/ 暴露
├── data.db db 工具与 /api/db/<sid>/query
└── ... 用户上传与 AI 生成文件
<data_root>/.agent.db SQLite
<data_root>/prompt.txt 启动时实际下发的 prompt/tools dump
<skills_root>/<skill>/ 技能;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 <url>/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` 重写为 `<taskDir>/.tmp`,与 executor 容器内 `/tmp` 的 bind 对齐;
- 越界抛错。
`@<session-id>/<rel>` 由 `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: 未知工具 <name>`。
### 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/<session>`。
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=<sid>, day=<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<res>`。
- `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/<binding_id>/`。
- 不保存业务状态;启动扫描凭证目录拉起实例,状态回报失败不影响上线,首条消息会纠偏。
- 除 `/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/<sid>/` | `data-page.js` | 任务 `.app/` 静态页 |
| `/api/db/<sid>/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/<name>/` 放 `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`**:它看不到任务数据,也不应该看到。
+11 -12
View File
@@ -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 <<EOF
- name: image_task
url: "http://mcp_image_task:3000/mcp"
headers:
Authorization: "Bearer $ZHIPU_KEY"
Authorization: "Bearer $BIGMODEL_KEY"
- name: video_task
url: "http://mcp_video_task:3000/mcp"
headers:
Authorization: "Bearer $ZHIPU_KEY"
Authorization: "Bearer $BIGMODEL_KEY"
EOF
else
cat <<'EOF'
- name: image_task
url: "http://mcp_image_task:3000/mcp"
enable: false # 未配 ZHIPU_KEY:只注册不加载,工具不发给模型
enable: false # 未配 BIGMODEL_KEY:只注册不加载,工具不发给模型
- name: video_task
url: "http://mcp_video_task:3000/mcp"
enable: false # 未配 ZHIPU_KEY:只注册不加载,工具不发给模型
enable: false # 未配 BIGMODEL_KEY:只注册不加载,工具不发给模型
EOF
fi
@@ -236,7 +235,7 @@ public_link:
EOF
} > "$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 "---------------------------------------------"