web_search 从内置工具改为 MCP 服务:新增 server/mcp.js 极简 MCP 客户端(JSON-RPC over HTTP,SSE 帧容错解析),config.yml 新增 mcp_servers(可多个,每项 name?/url/headers,authorization 即普通 header),启动时 tools/list 发现工具转 OpenAI function 格式,随 system prompt 与内置工具一起发给模型(内置 definitions.json 移除 web_search,剩 12 个);executeTool 未命中内置时按注册表经 tools/call 转发,工具重名加服务名前缀;旧 web_search.{url,authorization} 配置自动迁移为一条 mcp_servers;单服务发现失败仅告警不阻塞启动;README/example 配置同步

This commit is contained in:
2026-08-31 17:12:32 +08:00
parent 93e463e704
commit 526880a956
9 changed files with 175 additions and 151 deletions
+4 -35
View File
@@ -131,7 +131,7 @@ models:
> 注:system prompt 完全静态(所有会话共用,利于前缀缓存)。动态会话信息(日期、任务目录、模型显示名)在新建会话时作为首条 user 消息自动发送,跟会话走。`<available_skills>` 当前为空,预留扩展。
### 7.2 工具定义(保留 14 个,去掉 diagnostics、skill、spawn_agent)
### 7.2 内置工具定义(12 个;去掉 diagnostics、skill、spawn_agent;web_search 移至 MCP 服务)
以下工具定义沿用 Zed 原始 JSON Schema,**保持字段完全一致以利于缓存**。
@@ -464,38 +464,7 @@ models:
}
```
#### 12. `web_search`
```json
{
"type": "function",
"function": {
"name": "web_search",
"description": "免费网页搜索:Parallel(默认,匿名免 key)或 Exa(备用)。返回结构化结果数组(title / url / snippet / publishedAt)。",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索查询词"
},
"provider": {
"type": "string",
"enum": ["parallel", "exa"],
"description": "免费后端:parallel(默认)/ exa(备用)"
},
"numResults": {
"type": "number",
"description": "返回结果条数上限(默认 8)"
}
},
"required": ["query"]
}
}
}
```
#### 13. `write_file`
#### 12. `write_file`
```json
{
@@ -521,7 +490,7 @@ models:
}
```
> 说明:Zed 原始 16 个工具中去掉 `diagnostics`、`skill`、`spawn_agent`,保留上述 13 个。`fetch` 和 `web_search` 都保留。后续如需扩展 `skill` / `spawn_agent`,可在 tools 数组中追加定义并实现对应逻辑。
> 说明:Zed 原始 16 个工具中去掉 `diagnostics`、`skill`、`spawn_agent`、`web_search`,内置保留上述 12 个。`web_search` 等外部能力改由 MCP 服务提供:在 config 的 `mcp_servers`(url + headers)配置,启动时 `tools/list` 自动发现并追加到内置工具之后一起发给模型,与内置工具严格分离。
---
@@ -757,7 +726,7 @@ function runAgent(session):
- **文件工具**:所有路径必须解析到任务目录内(防路径穿越)。
- **terminal**:使用 `child_process.spawn`,设置超时(默认 30s),输出截断(前 10000 字符)。支持 kill。
- **fetch**:使用 HTTP 客户端抓取,转换为 Markdown 返回。
- **web_search**:调用 Parallel 或 Exa 搜索 API,返回结构化 JSON。
- **MCP 工具**:外部 MCP 服务在 config 的 `mcp_servers` 配置(url + headers,可多个);启动时 `tools/list` 发现工具追加到内置工具之后,调用经 `tools/call` 转发(如 web_search)。
### 11.3 模型调度器要点
+4 -3
View File
@@ -12,14 +12,15 @@ app/
│ ├── db.js # SQLite(better-sqlite3,WAL)
│ ├── engine.js # 会话管理 + 模型池 FIFO 调度 + Agent 主循环
│ ├── llm.js # OpenAI 兼容上游流式调用(SSE 解析/工具分片合并)
│ ├── mcp.js # MCP 客户端:mcp_servers 工具发现(tools/list)与转发(tools/call)
│ ├── sse.js # 按会话分组的 SSE 事件总线
│ ├── routes/
│ │ ├── sessions.js # 会话 CRUD(10.1)
│ │ ├── messages.js # 消息/SSE/start/stop(10.2)
│ │ └── files.js # 文件上传/列表/下载/删除(10.3)
│ ├── tools/
│ │ ├── definitions.json # 14 个工具的 JSON Schema
│ │ └── executor.js # 13 个工具执行器(任务目录沙箱)
│ │ ├── definitions.json # 内置 12 个工具的 JSON Schema
│ │ └── executor.js # 内置工具执行器(任务目录沙箱;未知工具名转 MCP)
│ ├── templates/system-prompt.txt # System prompt 模板(直接编辑)
│ └── public/ # H5 前端(Vanilla JS + SSE)
├── test/ # mock 上游 + 端到端冒烟测试
@@ -55,6 +56,6 @@ System prompt 完全静态(所有会话共用,利于上游前缀缓存),
- 规划阶段点「开始执行」:追加固定模板消息并切 execution。
- 终止:置位标志 + kill 进程组 + 中止模型流,不再发新请求。
- 所有文件路径解析到任务目录内,拒绝越界。
- web_search 调用内网 MCP 服务(config.web_search.url/authorization,默认已内置);如服务不可用会返回错误文本。
- MCP 服务在 config.yml 的 `mcp_servers` 配置(可多个,每项 name?/url/headers);启动时发现其工具,追加在内置工具之后与 system prompt 一起发给模型;服务不可用仅启动日志告警,工具名重名时加「服务名__」前缀。
部署见 `../docs/DEPLOY.md`。
+8 -4
View File
@@ -42,7 +42,11 @@ model_hold:
# user: admin
# password: "change-me"
# web_search 工具:直接调用内网 MCP 服务(JSON-RPC over HTTP,无状态,默认已内置)
web_search:
url: "https://web-search.ai.foresh.com/"
authorization: "Basic a2ljZXI6USF3MmUzcjQ="
# MCP 服务(可配多个;与内置工具分开)。启动时对每个服务调 tools/list 发现工具,
# 追加到内置工具之后一起发给模型;调用经 tools/call 转发。headers 是任意请求头(如 Authorization)。
# 服务不可用时只在启动日志告警,不影响其他服务与内置工具。
mcp_servers:
- name: web-search # 选填,缺省取主机名首段
url: "https://web-search.ai.foresh.com/"
headers:
Authorization: "Basic a2ljZXI6USF3MmUzcjQ="
+27 -5
View File
@@ -15,11 +15,9 @@ const DEFAULTS = {
model_hold: { idle_release_ms: 180000, active_max_ms: 1800000, sweep_ms: 10000 },
models: [],
auth: null, // { user, password },为空则不启用内置 basic auth(可交给 nginx-proxy)
// web_search 工具:内网 MCP 服务(JSON-RPC over HTTP,无状态)
web_search: {
url: 'https://web-search.ai.foresh.com/',
authorization: 'Basic a2ljZXI6USF3MmUzcjQ=',
},
// MCP 服务列表:每项 {name?, url, headers?};启动时发现其工具并追加到内置工具之后。
// 注意与内置工具(definitions.json)严格分离:这里只配外部 MCP 服务。
mcp_servers: [],
};
function deepMerge(base, extra) {
@@ -56,6 +54,30 @@ function loadConfig(configPath) {
cfg.workspace_root = path.resolve(cfg.workspace_root);
if (!cfg.db_path) cfg.db_path = path.join(cfg.workspace_root, '.agent.db');
// 兼容旧配置:顶层 web_search.{url,authorization} 自动转为一条 mcp_servers(authorization 即一条 header)
if (raw.web_search && raw.web_search.url && !raw.mcp_servers) {
const ws = raw.web_search;
cfg.mcp_servers = [{
name: 'web-search',
url: ws.url,
headers: ws.authorization ? { Authorization: ws.authorization } : {},
}];
console.log('[config] 检测到旧配置 web_search.*,已自动转为一条 mcp_servers;建议更新 config.yml 为 mcp_servers 格式');
}
// MCP 服务规范化:url 必填;name 缺省取主机名首段;headers 为普通键值对象(如 Authorization)
if (!Array.isArray(cfg.mcp_servers)) cfg.mcp_servers = [];
for (const s of cfg.mcp_servers) {
if (!s || !s.url) throw new Error('mcp_servers 每项必须有 url(MCP 服务的 JSON-RPC 端点)');
if (!s.name) {
try { s.name = String(new URL(s.url).hostname.split('.')[0]); } catch (_) { s.name = 'mcp'; }
}
const headers = {};
for (const [k, v] of Object.entries(s.headers || {})) headers[k] = String(v);
s.headers = headers;
}
cfg.config_path = p;
return cfg;
}
+3 -1
View File
@@ -4,6 +4,7 @@ const fs = require('fs');
const path = require('path');
const { buildMessages, callModel } = require('./llm');
const { executeTool, resolveInTask } = require('./tools/executor');
const mcp = require('./mcp');
const TOOL_DEFINITIONS = require('./tools/definitions.json');
@@ -303,7 +304,8 @@ async function runLoopInner(sessionId, run) {
session.history = loadHistory(sessionId);
for (const m of session.history) if (m.id > lastIncludedId) lastIncludedId = m.id;
const messages = buildMessages(session);
const tools = TOOL_DEFINITIONS;
// 内置工具 + 启动时发现的 MCP 工具,一起随 system prompt 发给模型
const tools = TOOL_DEFINITIONS.concat(mcp.toolDefinitions());
let result = null;
let lastErr = null;
+111
View File
@@ -0,0 +1,111 @@
// 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。
// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?}。
// 启动时 init() 对每个服务调 tools/list 发现工具,转成 OpenAI function 格式,
// 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型;
// 工具调用经 tools/call 转发给对应服务。
// 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名,
// 仅当与内置工具或其他 MCP 工具重名时加「服务名__」前缀。
let toolDefs = []; // OpenAI function 格式(所有 MCP 工具)
const toolIndex = new Map(); // 发送名 -> { server, tool }(服务配置 + 原始工具名)
let builtinNames = new Set();
// 发一次 JSON-RPC 请求,返回 result(HTTP 非 2xx / error / 无法解析时抛异常)。
async function rpc(server, method, params, timeoutMs) {
const callId = Date.now();
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), timeoutMs || 30000);
try {
const res = await fetch(server.url, {
method: 'POST',
signal: ctrl.signal,
headers: Object.assign({
'Content-Type': 'application/json',
'Accept': 'application/json, text/event-stream',
}, server.headers || {}),
body: JSON.stringify({ jsonrpc: '2.0', id: callId, method, params: params || {} }),
});
const raw = await res.text();
if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + raw.slice(0, 300));
// 响应可能是 SSE 帧(多行 data: {...}),取 id 匹配或最后一条 JSON
let payload = null;
try {
payload = JSON.parse(raw);
} catch (_) {
for (const line of raw.split('\n')) {
const t = line.trim();
if (!t.startsWith('data:')) continue;
try {
const obj = JSON.parse(t.slice(5).trim());
if (!payload || obj.id === callId) payload = obj;
} catch (_) { /* 跳过非 JSON 帧 */ }
}
}
if (!payload) throw new Error('响应无法解析:' + raw.slice(0, 300));
if (payload.error) throw new Error('MCP 错误:' + JSON.stringify(payload.error).slice(0, 500));
return payload.result;
} finally {
clearTimeout(timer);
}
}
// 发现所有 MCP 服务的工具。单个服务失败只警告,不影响其他服务与内置工具。
async function init(cfg) {
toolDefs = [];
toolIndex.clear();
try {
for (const d of require('./tools/definitions.json')) {
if (d.function && d.function.name) builtinNames.add(d.function.name);
}
} catch (_) { /* 内置定义读不到就不做重名保护 */ }
const servers = (cfg && cfg.mcp_servers) || [];
for (const s of servers) {
try {
const result = await rpc(s, 'tools/list', {}, 15000);
const tools = (result && result.tools) || [];
for (const t of tools) {
if (!t || !t.name) continue;
let name = t.name;
if (builtinNames.has(name) || toolIndex.has(name)) name = s.name + '__' + name;
toolIndex.set(name, { server: s, tool: t.name });
toolDefs.push({
type: 'function',
function: {
name,
description: t.description || t.title || '',
parameters: t.inputSchema || t.input_schema || { type: 'object', properties: {} },
},
});
}
console.log('[mcp] ' + s.name + ': 发现 ' + tools.length + ' 个工具');
} catch (err) {
console.error('[mcp] ' + s.name + ' 工具发现失败(本轮运行该服务不可用): ' + (err && err.message || err));
}
}
}
// 随请求发送的 MCP 工具定义(追加在内置工具之后)。
function toolDefinitions() { return toolDefs; }
function hasTool(name) { return toolIndex.has(name); }
// 把工具调用转发给对应 MCP 服务,返回给模型的文本结果。
async function callTool(name, args) {
const entry = toolIndex.get(name);
if (!entry) return 'Error: 未知 MCP 工具 ' + name;
let result;
try {
result = await rpc(entry.server, 'tools/call', { name: entry.tool, arguments: args || {} }, 60000);
} catch (err) {
return 'MCP ' + entry.server.name + '/' + entry.tool + ' 调用失败: ' + (err && err.message || err);
}
const content = result && result.content;
if (Array.isArray(content)) {
const text = content.filter(c => c && c.type === 'text').map(c => c.text || '').join('\n');
if (text) return text;
}
return JSON.stringify(result).slice(0, 20000);
}
module.exports = { init, toolDefinitions, hasTool, callTool };
+11 -4
View File
@@ -8,6 +8,7 @@ const { loadConfig } = require('./config');
const { initDb } = require('./db');
const { createBus } = require('./sse');
const engine = require('./engine');
const mcp = require('./mcp');
const cfg = loadConfig(process.env.AGENT_CONFIG);
const db = initDb(cfg.db_path);
@@ -45,8 +46,14 @@ app.get('/api/models', (req, res) => {
app.get('/api/health', (req, res) => res.json({ ok: true, time: Date.now() }));
const PORT = process.env.PORT || cfg.port;
server.listen(PORT, () => {
console.log('Agent server listening on ' + PORT);
console.log(' workspace_root=' + cfg.workspace_root);
console.log(' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', '));
// 启动时先发现各 MCP 服务的工具(单个服务失败只警告,不阻止启动),发现完成后再开始监听。
mcp.init(cfg).then(() => {
server.listen(PORT, () => {
console.log('Agent server listening on ' + PORT);
console.log(' workspace_root=' + cfg.workspace_root);
console.log(' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', '));
const mcpList = (cfg.mcp_servers || []).map(s => s.name + '@' + s.url).join(', ');
console.log(' mcp_servers=' + (mcpList || '(none)'));
});
});
-31
View File
@@ -302,37 +302,6 @@
}
}
},
{
"type": "function",
"function": {
"name": "web_search",
"description": "免费网页搜索:Parallel(默认,匿名免 key)或 Exa(备用)。返回结构化结果数组(title / url / snippet / publishedAt)。",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索查询词"
},
"provider": {
"type": "string",
"enum": [
"parallel",
"exa"
],
"description": "免费后端:parallel(默认)/ exa(备用)"
},
"numResults": {
"type": "number",
"description": "返回结果条数上限(默认 8)"
}
},
"required": [
"query"
]
}
}
},
{
"type": "function",
"function": {
+7 -68
View File
@@ -1,10 +1,11 @@
// 工具执行器。所有文件路径强制解析到任务目录内(防路径穿越)。
// 工具名与参数 schema 来自 README 7.2(生成到 definitions.json)。
// 工具执行器(内置工具)。所有文件路径强制解析到任务目录内(防路径穿越)。
// 工具名与参数 schema 来自 definitions.json;MCP 工具不在这里,见 ../mcp.js。
const fs = require('fs');
const path = require('path');
const fsp = require('fs').promises;
const { spawn } = require('child_process');
const { Minimatch } = require('minimatch');
const mcp = require('../mcp');
function makeMatcher(pattern, opts) {
const mm = new Minimatch(pattern, opts || {});
@@ -616,68 +617,6 @@ function htmlToMarkdown(html) {
function strip(s) { return s.replace(/<[^>]+>/g, ''); }
// web_search:调用内网 MCP 服务(JSON-RPC over HTTP,无状态,响应为 SSE 帧包裹的 JSON)。
async function toolWebSearch(ctx, args) {
const ws = ctx.cfg.web_search || {};
if (!ws.url) return 'web_search 未配置:请在 config.yml 的 web_search.url 中填写 MCP 服务地址';
const query = args.query;
if (!query) return 'web_search 缺少参数 query';
const callId = Date.now();
const rpc = {
jsonrpc: '2.0',
id: callId,
method: 'tools/call',
params: {
name: 'web_search',
arguments: {
query,
...(args.provider ? { provider: args.provider } : {}),
...(args.numResults ? { numResults: args.numResults } : {}),
},
},
};
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), 60000);
try {
const res = await fetch(ws.url, {
method: 'POST',
signal: ctrl.signal,
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json, text/event-stream',
...(ws.authorization ? { Authorization: ws.authorization } : {}),
},
body: JSON.stringify(rpc),
});
const raw = await res.text();
if (!res.ok) return 'MCP web_search HTTP ' + res.status + ': ' + raw.slice(0, 300);
// 响应可能是 SSE 帧(多行 data: {...}),取 id 匹配或最后一条 JSON
let payload = null;
try {
payload = JSON.parse(raw);
} catch (_) {
for (const line of raw.split('\n')) {
const t = line.trim();
if (!t.startsWith('data:')) continue;
try {
const obj = JSON.parse(t.slice(5).trim());
if (!payload || obj.id === callId) payload = obj;
} catch (_) { /* 跳过非 JSON 帧 */ }
}
}
if (!payload) return 'MCP web_search 响应无法解析:' + raw.slice(0, 300);
if (payload.error) return 'MCP web_search 错误:' + JSON.stringify(payload.error).slice(0, 500);
const content = payload.result && payload.result.content;
if (Array.isArray(content)) {
const text = content.filter(c => c && c.type === 'text').map(c => c.text || '').join('\n');
if (text) return text;
}
return JSON.stringify(payload.result).slice(0, 20000);
} finally {
clearTimeout(timer);
}
}
function recordFile(ctx, abs) {
try {
const st = fs.statSync(abs);
@@ -701,15 +640,15 @@ const HANDLERS = {
grep: toolGrep,
terminal: toolTerminal,
fetch: toolFetch,
web_search: toolWebSearch,
};
// ctx: {sessionId, taskDir, run, cfg, db}
// 内置工具优先;未命中时交给 MCP 注册表(启动时发现的服务工具)。
async function executeTool(baseCtx, name, args) {
const handler = HANDLERS[name];
if (!handler) return 'Error: 未知工具 ' + name;
const ctx = baseCtx;
return handler(ctx, args || {});
if (handler) return handler(baseCtx, args || {});
if (mcp.hasTool(name)) return mcp.callTool(name, args || {});
return 'Error: 未知工具 ' + name;
}
module.exports = { executeTool, resolveInTask, recordFile };