Files
agent/app/AGENTS.md
T
kicer ac052d6997 docs: 补齐 tunnel 模块,更新 SSE 合并与文件面板懒加载
- README:组成表加 tunnel/;本机运行补隧道 client;安全边界补隧道
- AGENTS:仓库结构、运行时拓扑、端口表、数据持久化、同步清单、常见任务补 tunnel
- local/README:可选能力与安全边界补隧道
- app/AGENTS:sse.js 补高频事件合并;前端补文件面板按目录懒加载
2026-11-15 15:16:54 +08:00

32 KiB
Raw Blame History

AGENTS.md — agent-core (app/)

agent 仓库的 core 服务:Express + better-sqlite3 + 免构建 H5 前端,负责会话、模型调度、 Agent 主循环、工具执行、上下文管理、微信接入与定时任务。仓库级拓扑与部署见 ../AGENTS.md,用户视角说明见 ../README.md。

运行形态:Node 20,单进程,单实例;SQLite 同步 API(better-sqlite3),WAL 模式。 所有运行时状态(正在跑的回合、标题生成中、自动压缩提议额度、微信回合投递状态与实例缓存)都在进程内存里, 重启即清空——这是有意的设计,不要引入需要跨进程一致性的机制(微信投递游标 last_msg_id 是落库的)。

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 是共享并发资源: 同一 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};正文开头混入的 <think> 块会被 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 会被映射到 <taskDir>/.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 校验,不随之外扩。
  • 跨会话只读:@<session-id>/<rel> 只允许 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> 的信任模型:随机 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 的 <script> 顺序——没有 import/export,顺序就是依赖。
  • sw.js:HTML/JS/CSS 网络优先,图片/JSON 缓存优先。改图片或 JSON 才需要升 CACHE_VERSION; JS/CSS 改动不需要。
  • 另有 login.html、memory.html(日记调试页)。
  • API 调用统一走 core.js 的 req();SSE 用 EventSource + 前端看门狗。
  • 文件面板(files.js)按目录懒加载:只请求 GET /api/sessions/:id/tree?dir=<rel> 的当前层, 进入子目录才拉下一层;会话详情接口不返回全量 files。

扩展指南

新增内置工具

  1. tools/definitions.json 加 schema(遵循 ../docs/tool-design.md:共享标识空间/生命周期就用 op 合并)。
  2. tools/executor.js 写 toolXxx(ctx, args) 并注册进 HANDLERS。
  3. 若返回图片,返回 {text, image_rel}(且 read_file 之外的语义要想清楚)。
  4. 更新 ../docs/tool-design.md 相关说明、README 工具表。
  5. 注意:tools 数组每轮全量重发,能并进已有 op 就不要新开工具。

新增 HTTP 路由

  1. routes/<name>.js 用 express.Router(),错误用 err.status_code + {error}。
  2. 在 server.js 按"鉴权边界"选择挂载位置(是否需要 admin、是否需要匿名)。
  3. 若放在 auth.middleware 之后,req.user 可用(未启用认证时为空串)。

新增 DB 列

  1. 写进 db.js 的 CREATE TABLE;2. 加 PRAGMA table_info + ALTER TABLE 幂等迁移;
  2. 想清楚旧值语义(默认值、回填语句)与删会话时的清理归属。

新增 SSE 事件

  1. engine/wechat 里 bus.emit(sessionId, '<event>', data);
  2. 前端 stream.js/sessions.js 监听并处理重连后的幂等(事件可能重放,DB 才是真相)。

新增配置项

  1. config.js 的 DEFAULTS;2. config.example.yml 同步;3. 若需重启才生效,不要假装热加载。

改 prompt / profile

  • 默认 prompt:templates/profile-default.txt({APP_SKILLS_SECTION} 占位技能清单, {APP_ENV_SECTION} 占位环境段)。
  • 环境段:templates/env-server.txt(executor 容器形态)/ env-local.txt(本机 spawn 形态), 启动时按 EXECUTOR_URL 有无选定(server.js 的 llm.setEnvMode),改完重启。
  • 压缩/标题指令:templates/prompt-compress.txt / prompt-title.txt。
  • 自定义组合:config.yml 的 model_profiles + 模型的 profile: <名>;改完重启。

陷阱清单(都是踩过的)

  • 循环依赖:engine 绝不 require('./wechat') 或 require('./scheduler'),否则拿到半成品 exports。通知面/engine 引用一律由 server.js 注入。executor → scheduler 是单向的,安全。
  • tool_call 配对:删 assistant 必须连带删该轮的 tool 回执;删单条 tool 回执必须从父 assistant 的 tool_calls 里摘除,纯工具轮且无文本时整行删掉。否则上游拒收整个请求。
  • errAck 必须整轮排除:只丢 assistant 不丢 tool 回执会留下孤儿 tool 行。
  • archived ≠ 删除:UI 仍展示,只是不进模型;不要用删除来实现压缩。
  • 清空会话(clearSessionMessages)要一并:删消息、清 .tmp、删日记碎片、复位标题与 journaled_at、重新冻结画像快照;但定时任务"专柜"会话例外(碎片与 journaled_at 保留)。
  • 微信 deep_think 默认值:历史库曾按默认 1 补列,db.js 里有重建表把默认改回 0 的逻辑, 别删。
  • /wxhook 必须在全局 express.json 之前,否则 2mb 限制会拒掉媒体 base64。
  • /p/<id> 必须在 auth.middleware 之前(外部服务不带 cookie)。
  • preview-proxy 的 earlyGuard 必须在 express.static 之前,否则 vendor 预览页的根路径请求 会被静态首页吃掉。
  • 短链签发要复核 realpath:任务目录里可能有权向外部的符号链接。
  • agent.max_tool_iterations 是硬闸:打满会追加一条停止提示,不要让循环无上限。
  • 不要给 tick / sweep 加同步重活:它们跑在主线程,会直接卡住所有会话。
  • 改动 package.json 必须重建镜像(node_modules 在镜像层,只有 app/server 是挂载的)。