44 KiB
Agent 内部架构说明
面向修改本仓库的开发者。对外能力与部署请看
../README.md。本文只记录代码实际行为与修改时必须遵守的约束。设计动机写在相关注释里,这里不再重复。
1. 运行时拓扑
系统由四个进程角色组成,core 是唯一的业务与状态权威。
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. 代码地图
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 的顺序有依赖,不要随意调整:
loadConfig:读AGENT_CONFIG,应用DEFAULTS,规范化平台、profile、MCP、公网前缀,并从 env 注入executor/wxbot接线。log.setLevel、llm.setPayloadTrim。initDb:建表、迁移、清理孤儿日记碎片。createBus。engine.setModelPool(cfg, db, bus)+engine.init():- 按配置重建
model_pool; - 把
active/ 遗留queued会话归位为held; - 启动空闲扫描定时器(
auto_complete_ms/wrap_idle_ms)。
- 按配置重建
scheduler.start(engine, notify):必须在engine.init()之后,否则首轮 tick 会看到旧状态。memory.prune:按retain_days兜底裁剪。wechat.init:注册总线内部监听。- 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,必须最后,避免兜底吞掉现有路径。
mcp.init:发现所有 MCP 工具;单个服务失败只告警。- 生成技能清单快照并写入 system prompt。
server.listen。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 文件布局
<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 会话状态
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)排序:- 该槽位正在
looping的会话数; - 绑在该槽位上的
active/held会话数; last_used_at最久未用;- 槽位 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) 的过滤顺序:
- 内置定义 + MCP 工具;
- 若 profile 配了
tools_allow,先按白名单过滤;未配 = 全量;[]= 零工具; - 再按
tools_deny过滤;profile 未配时继承全局tools_deny,deny优先。
默认全局 tools_deny: [lab];lab profile 必须显式写 tools_deny: [],否则 lab 自己也会被屏蔽。名单只影响模型「看得到什么」,名单外但真实存在的工具被调用时仍会执行。
主循环
postUserMessage:
- 落一条 user 消息。
- 记录
run.deepThink。 - 若会话正在
looping,返回delivered:'live',下一轮迭代会从 DB 重新加载历史。 - 否则
ensureBinding→ 置active→runLoop。
runLoopInner 每轮:
- 从 DB 重新读会话与历史,记录
lastIncludedId。 - 组装 messages(压缩回合走
compressMessages)。 - 工具集 = 内置 + MCP,经 profile allow/deny 过滤;压缩回合为空。
streamAssistant调用模型,流式转发 SSE。- 失败重试:无
upstream_status、429、5xx 才重试,最多agent.max_retries次。 - 参数容错:
unwrapToolArgs剥掉{"arguments":{...}}/{"function":{...}}等外层;schedule缺op且具 create 形状时补op=create;checkToolArgs校验 JSON 与必填;失败则整条 assistant 标errAck。
- 保存 assistant 消息,写
model_usage,更新回合 In token 峰值。 - 无工具调用:若期间有新 user 消息则继续,否则结束回合。
- 有工具调用:逐个执行
executeTool,落tool消息,广播tool_call/tool_result。 - 达到
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 顺序:
system;profile_snapshot(会话创建/清空时冻结的画像);- 历史消息。
历史处理规则:
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→ SSEui_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 服务。
隔离模型:
- 宿主机
./tasks挂到EXECUTOR_ISOLATION_BASE(默认/mnt/host-tasks),该路径不在EXECUTOR_ROOTS内。 - 每条命令在
unshare --mount --pid --ipc --fork --propagation private中执行;有 Office 预览牢笼时先nsenter进同一 PID namespace。 - 先把当前会话目录 bind 到私有 tmpfs 的 anchor,再用空只读 tmpfs 遮盖
/mnt,最后把 anchor bind 回/workspace/tasks/<session>。 - 会话
.tmpbind 到容器/tmp,实现同一会话跨命令保留临时文件。 - 根文件系统只读;
/dev/shm、/var/tmp、/run每次私有化;executor 自身代码目录用 tmpfs 遮盖。 - 启动自检验证
ISOLATION_BASE是挂载点、DEFAULT_CWD是空目录、unshare可用、/mnt遮盖不会封死工作区。 - cwd 必须落在
EXECUTOR_ROOTS,不得是任务根本身,不得含..、空段、符号链接或指向基路径。 - 拒绝来自容器自身网卡 / 回环的
/exec:隔离没有独立 net namespace,否则 token 泄漏后可借/exec绕过隔离。 - 资源限制在 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。
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_tokenCookie: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 解析与认证之前,凭 BearerWXBOT_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外全部要求 BearerWXBOT_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、MCPheaders值脱敏;提交时按掩码还原。 - 配置是冷加载:写盘后必须重启 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 发消息到回复
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
- 用户消息落库,
run记录deepThink。 - 会话非
looping则置active并开跑;正在跑则只投递,下一轮迭代自动带上。 - 每轮从 DB 重读历史,组装 messages 与 tools。
- 模型流式输出;工具调用经参数校验、解包、执行、落库、广播。
- 无工具调用则收尾;有新用户消息则继续。
finalize进入held,发done,触发标题与自动压缩检查。
6.2 工具执行
- 内置工具在 core 进程内执行,文件类直接在任务目录操作。
terminal与skill在有EXECUTOR_URL时走远端。- 未命中内置工具则查 MCP 注册表。
- 工具回执先落库再广播,前端工具卡可据此定位消息行。
- 执行抛错转
Error: ...,is_error=1,模型能看到失败原因。 - 用户终止时
run.cancelled置位,本地杀进程组、远端发 DELETE、中止模型流。
6.3 压缩
- 用户点「压缩」或确认自动提议。
summarizeContext置run.summarizing,开一个正常回合。- 该回合不传 tools,末尾追加压缩提示词。
- 收尾答复标
summary,之前消息标archived。 - 前端把摘要卡片之前的消息淡出;后续请求从摘要开始。
6.4 定时任务
- AI 调
schedule op=create,scheduler.createTask校验 cron 与间隔。 run.taskWrap=true;当前回合finalize后taskClockOut:写任务 brief 碎片、归档、解绑通道。scheduler.tick每 30 秒检查到期任务。- 先
archiveHistory,再postUserMessage。 - 下一轮 tick 看到会话非
active,标ok并通知。
6.5 微信
- wxbot 收到消息,
POST /wxhook/inbox。 - core 校验绑定,必要时把媒体落盘。
channel.ensureSession找到当前会话;没有则新建。- 新会话注入
channel_note与memory_note。 - 普通消息走
handleSend→engine.postUserMessage。 - 回合事件经
sse.onInternal进入串行投递链,按预算推给 wxbot。 - 用户下条消息到达时重置回合预算。
6.6 日记收口
sweepJournalWrap找到静默超阈值的held/completed会话。journalFragment组装转录,依次尝试候选模型。- 清洗为
-行,写memory_fragments,写journaled_at。 - 归档
held,删除channel_sessions绑定。 - 微信下一条消息自动新建会话,并注入最近日记。
7. 修改时必须遵守的约束
- core 单实例。
runs、titling、journaling、SSE 客户端、public-files表、下载签名密钥都在进程内存。多副本部署会破坏会话状态、SSE 和链接有效性。 - 配置冷加载。改
config.yml后重启;运行期不要假设cfg会变。 - system prompt 在两次变更之间字节稳定。默认模板、技能清单、语言后缀在进程内恒定;按
profile + language缓存,技能清单变化时清缓存。任何每轮变化的内容不要塞进 system 开头,否则前缀缓存全断。 - 压缩请求与常规请求同构。压缩只能追加尾部指令,不能删画像快照、不能改中间历史。
archived与 UI 解耦。UI 展示全部历史,模型只看未归档;不要让前端删除archived行。- 工具调用与回执成对。删 assistant 必须连带删 tool 回执;删 tool 回执必须从父 assistant 的
tool_calls摘除。 errAck整轮隔离。参数错误的 assistant 行与关联 tool 行都不进模型上下文,用一条纠错 user 消息替代。- 路径沙箱。所有文件工具必须经
resolveInTask;@路径只能读、只能同用户。 - 公网链接校验。
mint前必须realpath确认文件仍在任务目录内;/p端只按 ID 查表。 - executor 不含密钥。不要把
config.yml、平台 Key、AUTH_SECRET挂进 executor / wxbot。 - 隔离层只允许 mount,不允许 umount
ISOLATION_BASE。容器根 mount table 是 shared,umount 可能传播回父 namespace,导致数据卷被摘。 - 消息类型改动要全链路检查。至少覆盖
llm.buildMessages、titleMessages、journalTranscript、前端chat.js。 - 定时任务一会话一条。主键
session_id是约束,不要改成多任务而不改 UI 与工具语义。 - 日记与来源会话同生共死。删会话删碎片;清空会话默认删碎片,任务专柜例外。
- 登录不是资源 ACL。新增业务路由默认对所有登录用户开放;若需要按用户隔离,必须在路由层显式校验
session.user。
8. 扩展点
8.1 新增内置工具
tools/definitions.json加 OpenAI function 定义。tools/executor.js加 handler,并注册到HANDLERS。- 需要出现在
lab help的话,确保在definitions.json中。 - 参数遵循
tool-design.md:共享资源用op分派,条件必填写进 description。 - 默认会被全局
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 服务
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. 测试与调试
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:它看不到任务数据,也不应该看到。