多模态上游兼容性事故:tool 角色消息带 image_url 块是非标准形态,大量 OpenAI 兼容上游整批忽略或只认批次最后一张——模型看不到图、却见回执写着 「已回传」,加上旧催读文案「如需重读请再次 read_file」火上浇油,模型一轮轮 重读同一批图烧 token 死循环。改为: - llm.js buildMessages:未消费的 tool 回执图不塞回执内(回执降级纯文本), image_ref 现签外链后统一并入该批回执之后的一条 user 消息(user 角色各家 通吃);每张图前配一行「[图片 N,对应回执] <回执首行>」标签,模型可对号; 旧库 data: URL 块原样并入;签不到降级文字占位。顺序天然满足 assistant→ tool 紧邻配对约束(合并消息落在整段历史尾部)。 - 两处催读文案(已省略/外链不可用)改为「请告知用户、勿反复重读同一文件」。 - engine.js runLoopInner 死循环护栏:run.imgDelivered 按图 rel 去重,同回合 再读同图只回文字提示不再签新图;run 随回合销毁,新回合自动重置,正常 追问重看不受影响。 - definitions.json read_file 描述同步新形态(图在批次回执后的独立 user 消息到达;同回合重读不再带像素,勿重试)。 - ARCHITECTURE.md §5.1 图片约定、§14 陷阱 7 改写,记录本次复盘。 验证:容器内构造 history 直调 buildMessages 六场景单测全过(合并/标签/ 现签/签失败占位/已消费省略/同批多图序号/旧 data: 透传/user 行原位现签); JSON 与 node --check 通过;restart agent-core 启动干净、微信对账正常。
Agent 任务台(app)
按仓库根目录 README.md 设计方案实现的自用通用 Agent 系统。
目录结构
app/
├── server/
│ ├── server.js # 入口:装配配置/DB/总线/路由/静态资源
│ ├── config.js # config.yml 加载与校验
│ ├── 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 # 内置 16 个工具的 JSON Schema
│ │ └── executor.js # 内置工具执行器(任务目录沙箱;未知工具名转 MCP)
│ ├── templates/system-prompt.txt # System prompt 模板(直接编辑)
│ └── public/ # H5 前端(Vanilla JS + SSE;无构建,index.html + js/ 六模块按序加载)
├── test/ # mock 上游 + 端到端冒烟测试
├── config.example.yml # core 专属配置模板(部署时生成/复制为仓库根 config.yml 挂进容器)
├── Dockerfile / docker-compose.yml
本地运行
cd app
npm install
cp config.example.yml config.yml # platforms 可先留空(启动后在设置页添加);本地跑再把 workspace_root / data_root 改回 ./data/...
npm start # http://localhost:8090
测试
cd app
npm test # 启动 mock 上游 + 真实 server 的端到端冒烟测试(25 项断言)
提示词与工具 schema
System prompt 完全静态(所有会话共用,利于上游前缀缓存),在 server/templates/system-prompt.txt 直接编辑;工具定义在 server/tools/definitions.json。改完重启服务。
关键行为速查
- 会话创建即尝试绑定空闲模型;无空闲则进全局队列 FIFO。
- 每轮 AI 完成(无工具调)或用户终止后释放模型;新消息重新入队。
- 规划阶段点「开始执行」:追加固定模板消息并切 execution。
- 终止:置位标志 + kill 进程组 + 中止模型流,不再发新请求。
- 所有文件路径解析到任务目录内,拒绝越界。
- MCP 服务在 config.yml 的
mcp_servers配置(可多个,每项 name?/url/headers/enable?/timeout_ms?,enable 默认 true、false 时启动不加载其工具;timeout_ms 为该服务单次工具调用最大等待,默认 60s);启动时发现其工具,追加在内置工具之后与 system prompt 一起发给模型;服务不可用仅启动日志告警,工具名重名时加「服务名__」前缀。
部署见 ../docs/DEPLOY.md。