# AGENTS.md — agent-core (`app/`) `agent` 仓库的 core 服务:Express + better-sqlite3 + 免构建 H5 前端,负责会话、模型调度、 Agent 主循环、工具执行、上下文管理、微信接入与定时任务。仓库级拓扑与部署见 [../AGENTS.md](../AGENTS.md),用户视角说明见 [../README.md](../README.md)。 **运行形态**:Node 20,单进程,单实例;SQLite 同步 API(`better-sqlite3`),WAL 模式。 所有运行时状态(正在跑的回合、标题生成中、自动压缩提议额度、微信回合投递状态与实例缓存)都在进程内存里, 重启即清空——这是有意的设计,不要引入需要跨进程一致性的机制(微信投递游标 `last_msg_id` 是落库的)。 ```bash cd app && npm install cp config.example.yml config.yml # 本地调试记得把 workspace_root / data_root 改成仓库内可写目录 AGENT_CONFIG=./config.yml node server/server.js ``` ## 启动顺序(`server/server.js`,顺序是刻意的) 1. `loadConfig(AGENT_CONFIG)` → 校验 + 默认值合并;`log.setLevel`;`llm.setPayloadTrim`。 2. `initDb(cfg.db_path)`:建表 + 幂等迁移(见「数据层」)。 3. `createBus()`:SSE 事件总线(同时支持内部订阅者,微信投递靠它)。 4. `engine.setModelPool(cfg, db, bus)` + `engine.init()`(`syncModelPool`):注册 profile prompt、 按配置重建 `model_pool` 槽位、清掉已删除的槽位、把 `active`/遗留 `queued` 统一归位为 `held`、 启动空闲收口扫描器。**必须先于 scheduler 启动**,否则首轮 tick 会看到脏状态。 5. `scheduler.start(engine, p => wechat.notifyTask(p))`:注入 engine 与通知面,避免反向 require 成环。 6. `memory.prune(db, cfg)`:长期记忆保留窗兜底裁剪。 7. `wechat.init(cfg, db, bus)`:微信能力,`WXBOT_URL`/`WXBOT_TOKEN` 缺失时整体静默关闭。 8. Express 装配(顺序见「HTTP 层」)。 9. `mcp.init(cfg)`(发现 MCP 工具,失败按 2s/20s/1min 重试)→ 技能清单快照 `llm.setSkillListText(...)` → `server.listen(PORT)` → `wechat.restore()` → `dumpPromptBundle()` (把实际下发的 system prompt / tools 写进 `data/prompt.txt`,供人工核对)。 `SIGTERM`/`SIGINT` 走 `shutdown()`:先 `bus.closeAllSessions()`(给 SSE 干净的流结束),再 `server.close()`,3s 后兜底硬退。容器里 node 是 PID 1,不注册信号会白等 `stop_grace_period`。 ## 模块地图 | 文件 | 职责 | |---|---| | `server/server.js` | 装配、路由挂载、`/api/models`、`/api/health`、prompt dump、优雅退出 | | `server/config.js` | YAML 加载/校验/默认值;`platforms` 展开成 `cfg.models`;配置文本改写(设置页) | | `server/presets.json` | 平台与同栈 MCP 的固定契约(url / type / header 名),设置页新增时的模板来源;改服务地址改这里 | | `server/db.js` | 建表、索引、幂等迁移;纯 SQL 数据层,不放业务 | | `server/engine.js` | **核心**:会话状态机、模型池调度、Agent 主循环、压缩、标题、日记收口、消息增删 | | `server/llm.js` | 消息组装、system prompt 拼接、上游流式调用、占位裁剪、多模态块编解码 | | `server/tools/executor.js` | 14 个内置工具实现、路径沙箱、`@会话` 跨会话只读、fetch SSRF、SQLite 工具 | | `server/tools/definitions.json` | 内置工具 schema(发给模型的 `tools` 事实源) | | `server/tools/skills.js` | 技能发现、`SKILL.md` 解析、参数校验与执行(远端 executor 或本地 spawn) | | `server/mcp.js` | 极简 MCP 客户端:启动发现、工具名重名加前缀、`tools/call` 转发、`ui_card` 剥离 | | `server/scheduler.js` | 定时任务 CRUD 校验、30s tick、存档后投递、完成通知组装 | | `server/wechat.js` | 微信绑定、媒体落盘、上下文注入、SSE→微信分段投递、任务通知 | | `server/routes/channel.js` | 文本命令层(`/new` `/switch` `/think` …),微信与外部接入端共用 | | `server/routes/*.js` | HTTP API,按资源分文件 | | `server/sse.js` | 按会话分组的 SSE 总线(`addClient`/`emit`/`onInternal`);`assistant_delta` / `reasoning_delta` / `tool_call_args` 攒 50ms 或 8 条合并写入 | | `server/auth.js` | HMAC cookie 登录、Basic 兜底、`requireAdmin`、免认证路径 | | `server/memory.js` | 长期记忆(日记碎片)读写与检索,仅依赖 `time.js` | | `server/time.js` | 业务时区单一入口:`TZ`、`dayString`、`stampString`、`fmtTime`、`fmtIso` | | `server/user-profile.js` | 用户画像读写、会话快照冻结 | | `server/public-files.js` | `mint_public_link` 的短链签发与解析(进程内 Map) | | `server/download-token.js` | 浏览器下载链接的 HMAC 签名(密钥进程内随机) | | `server/remote-exec.js` | 调 `agent-executor` 的 `/exec`(SSE)与预览槽清理 | | `server/log.js` | 分级日志 `log.debug/info/warn/error(category, ...)` | | `server/balance.js` | 平台余额查询适配器(按 `platform.type` 分发) | | `server/version.js` | git commit/date:优先读 `version.json`(post-commit 钩子生成),宿主机有 git 时兜底 `git rev-parse`;页面版本号另外由 `routes/system.js` 的 `VERSION` 字面量决定 | | `server/templates/` | system prompt 模板、环境段(按部署形态二选一)、压缩/标题指令、profile prompt | ## 一次用户消息的生命周期 ``` POST /api/sessions/:id/messages → engine.postUserMessage saveMessage(user) // 先落库,保证不丢 已有 looping 回合 → 返回 delivered:'live'(下一轮迭代自动带上这条) 否则 ensureBinding → status=active → emitStatus → runLoop()(不 await) → runLoop → runLoopInner(最多 agent.max_tool_iterations 轮) loadHistory → buildMessages / compressMessages → effectiveTools(profile) 模型调用(失败按 429/5xx 重试 agent.max_retries 次) unwrapToolArgs(弱模型多包一层外层时解包)+ schedule 缺 op 推断 checkToolArgs:JSON 非法/缺必填 → 整条 assistant 标 type='errAck' saveMessage(assistant) + recordModelUsage 压缩回合的收尾答复 → type='summary',之前全部消息 → type='archived' 无 tool_calls → 待投递里有「干预」则投递并继续;否则若有新 user 消息继续,否则收尾 有 tool_calls → 逐个 executeTool → saveMessage(tool) → emit tool_result (每步之后与整批之前各查一次「干预」,命中就先闭合批次再投递) → finalize closeToolBatch(兜底:补齐本批未执行调用的合成回执) cancelled → status=cancelled 正常 → status=held,emit done,maybeGenerateTitle,run.taskWrap → taskClockOut 收尾后若队列非空 → setImmediate 投递队首(排队模式的唯一出口) → maybeAutoCompress(回合彻底结束后才检查) ``` **给前端的是 SSE 事件,不是响应体**。前端在 `GET /api/sessions/:id/stream` 上听: `status`、`assistant_delta`、`reasoning_delta`、`tool_call_start`、`tool_call_args`、 `tool_call`、`tool_result`、`assistant_message`、`done`、`error`、`title`、`auto_compress`、 `ui_card`、`pending_added`、`pending_removed`、`user_message`,以及每 15s 的具名心跳 `ping` (注释帧不触发 JS 事件,所以用具名事件做前端看门狗)。 ## 待投递消息(排队 / 干预 / 立即发送) 回合正在跑时,Web 端发送不再「立即插话」,而是进**服务端队列**(`engine.js` 的 `pendings`, 进程内内存态,同 `runs`,重启即丢):输入框上方出现一行条幅,默认等本轮结束自动发出。 | 模式 | 入口 | 行为 | |---|---|---| | `queue`(默认) | 网页端运行中点发送 | 本轮 `finalize` 后作为新回合的第一条消息发出 | | `interject`(干预) | 条幅「干预」/ **IM 渠道消息** | 当前工具跑完(或本条回复落库)后,闭合批次、就地插话,同一回合继续 | | `now`(立即发送) | 条幅「立即发送」 | 杀进程 + abort 流,本回合判 `cancelled`,收尾后立刻发 | 微信 / `POST /api/channel/send` 的普通消息走 `enqueueMessage(..., {mode:'interject'})`: IM 用户在实时对话,回合中插话应当“当前这步跑完就插”,不排队等本轮结束;且**必须走队列** (旧的直接 `postUserMessage` 会把 user 行插进工具批次中间)。`interject` 入队时插到所有 `queue` 之前(已在队列里的 interject 仍保持先来后到),这样它立刻成为队首,边界检查才能命中。 **铁律:队列里的消息绝不先落 `messages` 表。** 只在安全边界写库——① 工具批次闭合 (本批每个 `tool_call_id` 都有回执);② 无 `tool_calls` 的回复已落库;③ 回合 finalize。 否则 `user` 行会夹在 `assistant.tool_calls` 与 `tool` 回执之间,或批次没闭合就收尾, 上游一律拒收整个请求。 - `closeToolBatch(sessionId, reason)` 是配对兜底的唯一写入口:给最后一条带 `tool_calls` 的 assistant 里缺回执的调用补一条 `is_error=1` 的合成 tool 行(「用户介入/终止,本次调用未执行」)。 `finalize` 无条件调一次,取消路径与干预路径各调一次。广播的 `tool_result` 带 `skipped:true`, 微信端据此显示「N 次因你介入未执行」。 - **微信端不下发任何工具失败**(即使 `is_error=true`):多数是模型参数用错、下一轮自己会改, 推给用户既看不懂也帮不上忙;要交代就由模型自己的回复说。失败仍完整保留在库里与网页端工具卡上。 - 读侧还有一层纯过滤(`llm.buildMessages` 的 `pairedByAssistant` / `emittedCallIds`):只下发 「本批(紧邻的连续 tool 行)确有回执」的调用,孤儿回执也不下发。DB/UI 不动,专门兜历史脏数据。 - `stop()`(用户点「停止」)**会清空队列**(全停语义);「立即发送」不走 `stop`,只中断当前回合、保留队首。 - 只允许升级**队首**(`promotePending` 对非队首回 409),避免「越过后面的消息先发」。 - HTTP:`POST /messages` 的 `delivery:'queue'`;`POST /pending/:qid {action}`;`DELETE /pending/:qid`; 会话详情响应带 `pending`,`status` 事件也带 `pending`(前端把条幅当服务端状态的回显)。 ## 会话状态机 | 状态 | 含义 | 进入方式 | 离开方式 | |---|---|---|---| | `active` | 回合执行中 | `postUserMessage` / `summarizeContext` / `bindToSession`(有待答消息) | `finalize` → `held`;`stop` → `cancelled` | | `held` | 回合结束,可继续追问 | `finalize` 正常收尾 | 超 `agent.auto_complete_ms` → `completed`;手动断开 → `completed` | | `completed` | 已收口(纯状态,历史与绑定不动) | 断开、超时收口、清空 | 再发言直接回 `active` 续跑 | | `cancelled` | 用户终止 | `stop` | 再发言回 `active` | | `queued` | 旧版排队语义 | 已废弃 | 启动时归位为 `held` | 要点:`held` **不占任何资源**(没有租约、没有独占 key);`completed` 也只是视觉收口。绑定 (`model_id` / `model_slot`)在断开、收口、重启后都保持。 ## 模型池与绑定 - 配置加载时 `platforms[].models` × `platforms[].keys` 展开成 `cfg.models`: `id = "<平台名>/<模型id>"`(内部唯一键),`mid` 是发给上游的原始模型名。 - `model_pool` 一行一个**物理 key 槽位**,`id = "<平台名>#"`。key 是**共享并发资源**: 同一 key 可同时服务多个会话,没有排队、没有独占。 - `chooseKey(preferPlatform, strict)` 排序:**回合中会话数(内存 `runs`)→ 在用会话数(active/held) → 最久未用(`last_used_at`)→ id**。`strict` 只用于手动绑定「就要这个平台」。 - `chooseModel(platform, preferred)`:优先会话上次用过的同平台模型,否则选该平台绑定会话数最少的。 - `ensureBinding`:开回合前校验槽位在池中 + 模型仍启用;失效则自动改选(优先原平台), 用户无感;池完全为空才报 503。 - `applyBinding` 写 `sessions.model_id` / `model_slot` / `last_model_id`,并刷新槽位 `last_used_at`。 - `bindToSession`:正在输出时拒绝(409);换绑后有未回应消息就直接开跑。 - `vision` 决定 `read_file` 读图是否回传像素。 ## 消息表与上下文组装(`llm.js`) `buildMessages(session, language, mintUrl, profile)` 的输出顺序固定: 1. `system`:模板(`profile-default.txt` 或 profile 自定义 prompt)+ 环境段 + 技能清单段 + 语言指令; 进程内按 `(profile, language)` 缓存,保证前缀缓存稳定。 2. 画像快照(`sessions.profile_snapshot`,建会话/清空时冻结):作为首条 `user`。**不在 messages 表里**, 压缩与归档碰不到它。 3. 历史行(见下)。 历史行规则: - `type='archived'`:**不发模型**,UI 照常展示(压缩的核心语义)。 - `type='errAck'`:整轮移除,关联 `tool` 回执按 `tool_call_id` 一并丢弃;改以一条 `user` 错误提示 替代(回显上轮参数形 + 真实错误),避免模型模仿自己的坏样本死循环。 - `type='summary'`:保留,作为压缩后的上下文起点。 - 含图消息:DB 里存 `{"__blocks__":[...]}` 哨兵 JSON(`encodeBlocks`/`decodeBlocks`); 发请求时 `image_ref` 现签公网短链(`mintUrl`,每次请求重签、不会中途过期)。 `tool` 回执里的未消费图片会**挪出回执**,合并成该批回执之后的一条 `user` 消息 (`tool` 角色带图是非标准形态,很多上游会吞图);已消费的图只省略像素块,回执原样保留。 - `read_file` 读图的回执是**结构化 JSON**(`tools/executor.js` 的 `imageReceipt`:`ok` / `image_attached` / `reason` / `width` / `height` …),不是散文。发送侧改写只限两种真事件 (engine 同回合/同批去重、`buildMessages` 签外链失败),一律走 `patchImageReceipt` **只改字段**。 - **已消费的图重放时只省略像素块,不改写回执**:回执是「那次读取」的历史事实,把当时成功的 读图改写成 `image_attached:false` 会让模型以为当时就没拿到画面 → 反复重读同一条(实测循环)。 - 图片注入消息的两条硬约束(踩过循环):①**消费判据是「最后一条写过文本的 assistant」** (不要求无 `tool_calls`)——旧判据只认收尾回复,多步任务里图永远「未消费」;②**只有本批新增的图 带「一句话说明」的祈使句**,早前批次静默携带。两者合起来才断得掉「每轮要求描述 → 模型描述并继续 调工具 → 图仍算未消费」的自维持重复循环。 - 重读去重(engine `run.imgDelivered`)**只拦同一批 tool call 内的重复读**(一次请求里塞两份同样的图 没意义);跨批次重读一律放行。不要写成「一回合只投递一次」,也不要靠推测「图还在不在上下文里」—— 模型说拿不到就得给,而且文件可能已重新生成(路径相同、内容不同);拦掉只会把新像素挡在门外。 - 占位裁剪(`agent.trim.rules`):指定工具的参数(`side: args` + `fields`,仅顶层字符串)或回执正文 (`side: result`)在满足**两个距离条件**时换成单行占位:`rounds` = 其后又有几条 assistant 行 (「后面 AI 又说了几句话」)、`turns` = 其后又有几条真人消息(`role=user` 且 `type` 为空, 「后面又来了几条真人消息」)。两者是 AND,同时满足才裁;`turns: 1` = 回合内绝不裁、跨过用户 回合边界才裁——`fetch` / `read_file` / `web_search` 默认都配了它(否则长回合里模型会把同一段 反复重读,实测有回合重读同一文件 24 次);`write_file` 的参数只是快照,只配 `rounds: 1`。 默认规则在 `config.js` 的 `DEFAULTS.agent.trim.rules`(唯一来源),`config.yml` 写了 `trim.rules` 就整体替换(`[]` = 全关)。**只改发给上游的副本**,DB 与 UI 不动。规则只给「内容可再生或 只是当时快照」的工具配:`terminal` 这类一次性输出裁掉后模型就再也看不到 (规则写法与示例见 `config.example.yml` 的 `agent.trim`)。 - `compressMessages` = `buildMessages` + 末尾一条压缩指令 `user`。**铁律**:压缩请求必须与上一次 常规请求字节同构、只在尾部追加;不要为了省 token 在压缩回合抽掉快照或裁剪历史,断前缀缓存等于全价重读。 - `titleMessages`:不带 system prompt,只取 user/assistant 纯文本行(白名单 `null`/`summary`/`task_brief`) + 末尾标题指令。 `callModel`:`body.model` 用 `mid`;固定 `stream:true` + `stream_options.include_usage`; `extra_params` 合并进 body;`deepThink` 时再合并 `thinking_params`;`reasoning_ack_field` 非空时把 内部键 `__reasoning` 改名为该字段回传(否则剥除,内部键不出仓库)。返回 `{content, reasoning, tool_calls, finish_reason, usage, aborted, sseFrames}`;正文开头混入的 `` 块会被 `splitInlineThinking` 剥离到 reasoning。 ## 工具层 - 工具全集 = `definitions.json`(14 个内置)+ MCP 发现结果;再依次叠 profile 的 `tools_allow` 白名单、`tools_deny` 黑名单(**deny 赢**;profile 不配 deny 时继承全局 `tools_deny`)。 `tools_allow: []` = 零工具(纯文本组合)。过滤只影响"模型看得到什么",名单外工具若真被调用, `executeTool` 仍会执行(不误杀)。 - MCP 服务按 `mcp_servers[].mode` 参与:`advertise`(默认)进 `toolDefs` 下发;`skill` 只进 `toolIndex`(`mcp.hasTool` 为真,`lab` 可调),且由 `skills.js` 自动 包装成技能(`mcp.skillTools()` / `getSkillTool()`,get 返回注册表里的原始 inputSchema); `disable` 连 `tools/list` 都不发。旧字段 `enable` 已废弃,`mode: silent` 已移除, 出现即报配置错(不静默忽略)。 - `executeTool(baseCtx, name, args)`:先查 `HANDLERS` 表,未命中再交给 MCP 注册表。 `ctx = {sessionId, taskDir, workDir, run, cfg, db, vision}`;工具返回字符串,`read_file` 读图时返回 `{text, image_rel}`(`text` 是结构化 JSON 回执,由 engine 转成 `image_ref` 块)。 `workDir` = 会话手选的工作目录(本地端新建会话可选),空串时 `taskDir` 就是默认的 `workspace_root/<会话id>`。 - **路径沙箱**:所有路径经 `resolveInTask` 解析到 `taskDir` 内;`/tmp` 会被映射到 `/.tmp`(与 executor 容器里 `/tmp` 的 bind 对齐)。符号链接越界一律拒绝。 例外:`AGENT_FILE_SCOPE=workspace`(本地端 `local/start.sh` 注入)把业务工具的根放宽到 `workspace_root`,且 `/tmp` 不重写、直接放行(本地 terminal 写的是真 `/tmp`); 会话若手选了目录(`sessions.work_dir` 非空),业务工具与文件 API 的根都取那个真实目录 (`fsRoot` 优先返回 `ctx.workDir`),且不再创建 `task-*` 子目录; 路由层(文件 API / 公网短链 / data-page)与 `@会话` 仍按 `taskDir` 校验,不随之外扩。 - **跨会话只读**:`@/` 只允许 `list_directory`、`read_file`、`copy_path` 的 `source_path`,且只限同一用户的会话。写侧显式拒绝——否则会造出字面 `@task-x` 目录。 - `checkToolArgs` + `unwrapToolArgs`:前者做结构性预检并生成 `errAck`,后者按 schema 逐层剥掉 弱模型多包的信封。两者都是纯函数并已导出,便于回归验证。 - 技能(`tools/skills.js`):`SKILL.md` front matter 提供 `description`/`input_schema`。 front matter 的 `thinking: true` 会在 `get` 时把 `run.deepThink` 置真(不影响脚本本身); 每回合只触发一次,engine 经 SSE `think_auto` 同步前端,开启后保持到用户手动关闭。 工具参数是扁平的 `{op, name, args}`:`op` 必填且三选一(`list`/`get`/`run`),`name` 供 get/run 指认技能,`args` 仅 run 用;条件必填写不进 schema,由 `toolSkill` 校验并点名。 `toolSkill` 在入口把旧字段名 `input_args` 归一化成 `args`,之后只走一条分派路径 (曾有两条路径,其中一条只读 `input_args`,会静默丢参)。 `input_schema.required` 在 `run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径, cwd 也一律是会话目录(本地 spawn 与远端一致,否则按 cwd 干活的技能会写到技能目录里)。 配了 executor 就走 `remote-exec`,否则本地 `spawn`。 模型可见的技能清单是 `listCallableSkills`(目录技能 + `mode=skill` 的 MCP 工具,同名时目录胜出); 设置页的技能 API 仍只用 `listSkills`(按目录增删改),两者不要混用。 mode=skill 的 MCP 技能在 `runSkill` 里位于 `absolutizeArgs` **之前**:直接 `mcp.callTool` 转发 (不落沙箱,也不需要密钥),因此 URL 与含 `/` 的 prompt 不会被当路径改写;同样不跑 `input_schema.required` 校验(参数与 MCP 工具自己的 `op` 相关,交给服务管)。 - MCP(`mcp.js`):启动时 `initialize` → `notifications/initialized` → `tools/list`;与内置或已有 MCP 工具重名时加 `<服务名>__` 前缀;请求随带 `X-Session-Dir`、`X-Public-Base`; `content` 里的 `ui_card` 块不进模型上下文,转成 SSE `ui_card` 事件。 ## 数据层(`db.js`) 表:`sessions`、`messages`、`files`、`model_pool`、`meta`、`scheduled_tasks`、`channel_sessions`、 `memory_fragments`、`wechat_bindings`、`model_usage`、`user_profiles`;`wait_queue` 是废表。 - 时间戳统一 **毫秒整数**;`memory_fragments.day` 是 `Asia/Shanghai` 的 `YYYY-MM-DD` 字符串。 - `messages` 的 `type` 取值:`NULL`(普通)、`archived`(不进模型)、`summary`(压缩摘要)、 `errAck`(参数错误轮,整轮不进模型)、`channel_note`(微信渠道上下文)、`memory_note`(开场日记)、 `scheduler_note`(定时任务通知行);`summarize_request` / `task_brief` 是历史遗留类型。 - 外键:只有 `scheduled_tasks` 有 `ON DELETE CASCADE`;删会话时 `messages`/`files`/日记碎片/通道绑定 由 `engine.deleteSession` 显式清理,`model_usage` **故意保留**(用量统计不清账)。 - **迁移方式**:`initDb` 里用 `try { ALTER TABLE ... } catch {}` 幂等补列,没有 down migration、 没有迁移版本号。新增列时:① 写进 `CREATE TABLE`;② 同时加一条 `PRAGMA table_info` + `ALTER` (老库升级用)。删除列改用"保留但代码不再读写"(SQLite 删列不值得)。 - WAL 模式下备份 `data/` 时要连同 `-wal`/`-shm` 一起。 ## 后台生命周期任务(都在 `engine.js`) | 机制 | 触发 | 关键约束 | |---|---|---| | 自动标题 | `finalize` 正常收尾 | 有标题即跳过;本轮真执行过工具才立题,否则要求非注入 user 行 ≥3 条且 ≥30 字;最多 60 字 | | 收口补题 | 两个 sweep 各补一次 | `force` 跳过字数门槛(收口是最后一站);其余守卫不变 | | 自动压缩提议 | `runLoop` finally | 回合 In token 峰值 ≥ `agent.auto_compress_tokens`;延迟 1.5s;每会话至多一次;只发提议,由用户确认 | | held 超时收口 | 定时扫描 | `agent.auto_complete_ms`;纯状态动作,历史/绑定不动 | | 日记收口 | 空闲扫描 | `memory.wrap_idle_ms`;`journaled_at` 占坑防重复;候选模型链最多 3 个;删会话连带删碎片 | | 定时即下班 | 回合内创建过定时任务 | `run.taskWrap` → `finalize` 后 `taskClockOut`:用 brief 落碎片、归档、解绑通道 | | 记忆裁剪 | 启动 + 每次追加 | `memory.retain_days`(0 = 永久保留) | 所有扫描定时器都 `unref()`;后台任务 fire-and-forget,异常只记日志,**绝不阻塞消息主路径**。 ## 定时任务(`scheduler.js`) - 每会话至多一个任务(表主键就是 `session_id`),最小间隔 1 小时,时区固定 `Asia/Shanghai`。 - 每 30s tick。投递前**先** `archiveHistory`(全部消息 `type='archived'`)**再** `postUserMessage`, 顺序不能反:投递会同步起回合,存档晚一步模型就会带着旧上下文开跑。 - 状态:`running` → 下一轮 tick 发现会话已非 `active` → `ok`(异常结束也会记 ok,已知局限); 会话仍 active → 跳过本次记 `skipped`;投递抛错记 `error` 并通知。 - 完成通知由 `server.js` 注入的 `wechat.notifyTask` 送出;`scheduler` 不反向 require `wechat`。 ## 微信与命令层 - `wechat.js` 负责绑定表、扫码实例、媒体落盘(`MEDIA_MAX_BYTES=20MB`)、渠道上下文 (`channel_note`)、开场日记(`memory_note`)、SSE→微信投递(配额、分段、附件、工具台账、UI 卡片)。 - `routes/wechat.js` 有两个导出: - `router`:Web 设置页用,挂 `auth.middleware` 之后,按 `req.user` 隔离; - `hookRouter`:wxbot 回调(`/wxhook/inbox|hook`),挂**全局 `express.json(2mb)` 之前**, 自带 32mb 解析器(媒体 base64 超 2mb),用共享 Bearer token 常量时间比较把门。 - `routes/channel.js` 是"无 UI 端的按钮替代品":命令只在 `/api/channel/send` 解析,Web 上以 `/` 开头的文本照常发给模型。数据面零特殊,全部走 `engine` 既有函数。 ## HTTP 层 挂载顺序(`server.js`,顺序即语义): ``` /wxhook ← 内部回调,早于 body 解析(大 body) express.json(2mb) auth.router ← /login /logout /api/login /api/login_restore /api/password /api/me /p ← 公网临时文件,匿名可达(22 字符随机 ID + 服务端过期) auth.middleware ← 其余请求需登录(cookie 优先,Basic 兜底) preview-proxy.earlyGuard express.static(public) /api/sessions ×4 ← sessions / messages / files / skill-run(通用执行面) /api/skills /api/asr ← 语音识别代理:/transcribe 走登录态;ASR_URL 空或配置里无可用 asr 段则 503 /api/config ← requireAdmin /api/platforms /api/system ← /restart 需 admin,其余登录即可 /api/users ← 管理员;写盘后热更新 /api/profile /api/memory /api/wechat /api/channel /api/health ← 免认证探活:套壳 App / 运维脚本用它校验服务器地址 (只认 200 + body.ok + service==='agent-core') data-page ← GET /app/:task_id/*、POST /api/db/:task_id/query preview-proxy.mount(末尾兜底) ``` - 错误形状统一 `{ error: string }`,`err.status_code` 决定 HTTP 码。 - 认证:HMAC 签名 HttpOnly cookie(`agent_token`),`Authorization: Basic` 兜底, `Authorization: Bearer` 仅用于 `/api/login_restore`。`auth.users` 为空 = 完全关闭认证。 - 免认证路径集中在 `auth.js` 的 `PUBLIC_EXACT`(含 `/api/health`,且容忍尾斜杠)。 新增免登录接口必须加进去,否则会被中间件先拦成 401。 - **单租户警告**:除管理员接口外不做资源级授权;按用户的会话列表隔离在查询层(`sessions.user`)。 - 公网短链 `/p/` 的信任模型:随机 ID + 服务端 TTL + 签发时 `realpath` 校验,不靠登录态。 ## 前端(`server/public/`) - **无构建**:`index.html` 按顺序加载经典脚本,共享全局作用域: `core.js → chat.js → sessions.js → stream.js → files.js → voice.js → preview.js → settings.js` (`settings.js` 必须最后,尾部有全局初始化);`marked.min.js` 走 `vendor/`。 - 新增 JS 文件必须同时改 `index.html` 的 `