重构文档

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