From 548c91d21a8b634a284adf93ac143552401891b6 Mon Sep 17 00:00:00 2001 From: kicer Date: Tue, 20 Oct 2026 14:47:00 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E5=BB=BA=E4=B8=8B=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1209 +++++++++-------------------- app/README.md | 71 +- app/server/db.js | 2 +- app/server/routes/channel.js | 2 +- app/server/routes/files.js | 2 +- app/server/routes/messages.js | 2 +- app/server/routes/sessions.js | 2 +- docs/ARCHITECTURE.md | 1366 +++++++++++++++++---------------- docs/DEPLOY.md | 181 ----- docs/v2-develop.md | 80 -- docs/v3-develop.md | 48 -- 11 files changed, 1099 insertions(+), 1866 deletions(-) delete mode 100644 docs/DEPLOY.md delete mode 100644 docs/v2-develop.md delete mode 100644 docs/v3-develop.md diff --git a/README.md b/README.md index 2d95555..2b30dc7 100644 --- a/README.md +++ b/README.md @@ -1,883 +1,420 @@ -# 自用通用 Agent 系统——完整设计方案 +# Agent 任务台 -## 一、项目概述 +自托管的通用 Agent 系统。浏览器或微信发来任务,服务端调度模型、调用工具,在独立工作目录里生成文件并回传结果。 -构建一个运行在自有 Docker 服务器上的**通用任务 Agent**,带 H5 移动端友好的 Web 界面。用户可以创建会话、与 AI 对话讨论需求、上传文件、让 AI 执行任务(生成文件、处理数据、搜索信息、执行脚本等),并可下载结果文件。 +它不是聊天壳子:每个会话对应一个真实的 Linux 工作目录,模型可以读写文件、执行命令、抓网页、操作 SQLite、调用技能和 MCP 服务;命令在隔离容器中运行,文件可以直接下载或生成公网临时链接。 -### 核心特性 - -- 多模型账号并行调度(ds1、ds2、ds3…) -- 任务目录自动创建,文件隔离 -- 流式输出展示 -- 任务状态开关(规划 / 执行) -- 排队机制,用户可离线输入 -- 工具调用(文件操作、终端、网络抓取、网页搜索) -- 多模态图片识别(模型默认视为支持 vision,read_file 读图会压缩回传图片内容;不支持的模型配 vision: false 显式关;用户上传仅存任务目录,不自动发送) -- 借鉴 Zed agent 的 system prompt 和工具定义 +- 面向个人或小团队自用,单实例部署。 +- 模型层兼容任何 OpenAI `/chat/completions` 接口。 +- 前端是免构建的移动优先 H5,HTTPS 下可安装为 PWA。 --- -## 二、模型与并发 +## 能力 -### 2.1 模型池配置 +| 能力 | 说明 | +|---|---| +| 任务会话 | 每个会话一个独立目录 `tasks/<会话 id>/`,历史、文件、模型绑定都随会话保存 | +| 模型池 | 多平台、每平台多 key、每平台多模型;key 共享并发,不独占、不排队 | +| 工具调用 | 文件读写编辑、目录列举、复制、命令执行、网页抓取、SQLite、定时任务、技能、长期记忆等 14 个内置工具 | +| 隔离执行 | `terminal` 和技能在 `agent-executor` 容器中运行,只看到当前会话目录,根文件系统只读 | +| 大文件交付 | 文件面板上传/下载/打包 zip;外部服务取图走带过期时间的公网短链 | +| 上下文管理 | 手动压缩、按 token 阈值提示压缩、历史重放自动裁剪、会话标题自动生成 | +| 定时任务 | 每会话最多一个 cron 任务;触发前清空模型可见历史,按计划执行并推送结果 | +| 微信接入 | 扫码绑定个人微信,文本/图片/视频/文件进入同一套会话与命令体系 | +| 长期记忆 | 会话收口时生成第一人称工作日记;微信新会话注入最近几条,`recall` 可检索全部 | +| 用户画像 | 记录称谓、行业、偏好,会话创建时冻结注入,跨会话生效 | +| 技能 | 目录式技能(`SKILL.md` + `run.py`/`run.sh`),可在设置页管理 | +| MCP | 启动时发现外部 MCP 服务的工具,与内置工具一起提供给模型 | +| 多用户 | 登录账号、管理员角色、按用户隔离的会话列表与画像 | -配置文件(如 `config.yml`)中定义模型列表: +--- + +## 快速开始 + +### 前置条件 + +- Linux 服务器,Docker 与 Docker Compose v2。 +- 至少一个 OpenAI 兼容模型平台的 API Key。 +- 一个可用端口,默认 `8090`。 + +### 1. 生成配置 + +在仓库根目录执行: + +```bash +BIGMODEL_KEY=xxx \ +DEEPSEEK_KEY=yyy \ +QWEN_KEY=zzz \ +AUTH_USER=admin \ +AUTH_PASSWORD='换一个强密码' \ +PUBLIC_IP=1.2.3.4 \ +./scripts/init.sh +``` + +三个模型 Key 都可选,填几个启用几个。脚本会生成: + +- `.env`:`EXECUTOR_TOKEN`、`WXBOT_TOKEN`、`AGENT_PORT` 等部署变量。 +- `config.yml`:模型平台、登录账号、MCP 服务、公网前缀。 + +`ZHIPU_KEY` 可选,用于 `image_task` / `video_task` 两个 MCP 服务;不填则它们以 `enable: false` 写入配置。 + +`AUTH_USER` / `AUTH_PASSWORD` 不传时默认是 `admin` / `admin`,首次部署务必改掉。`PUBLIC_IP` 不传会尝试自动探测;探测失败则 `public_link` 为空,外部服务取图功能不可用。 + +`.env` 里的密钥会复用,重新执行不会让登录态失效;旧的 `config.yml` 会先备份为 `config.yml.bak.<时间戳>`。 + +注意:`config.yml` 每次都会按本次环境变量重新生成,平台 Key 不保存在 `.env` 里。已经部署过的实例请用设置页改配置,或带上原有变量重跑;只想刷新密钥时用 `./scripts/init.sh --env-only`。 + +### 2. 创建外部网络 + +根 `docker-compose.yml` 把 `my-app-network` 声明为 external,首次部署需要先创建: + +```bash +docker network inspect my-app-network >/dev/null 2>&1 || docker network create my-app-network +``` + +同栈的 `agent-mcp-net` 由本仓库的 compose 创建,不需要手动建。 + +### 3. 启动 + +```bash +docker compose up -d --build +docker compose logs -f agent-core +``` + +看到 `Agent server listening on 8090` 即启动完成。 + +首次启动还会运行一次性的 `agent-executor-init`,把技能依赖安装到 `./skills/deps`,随后自动退出,属正常现象。 + +### 4. 访问 + +浏览器打开: + +```text +http://<服务器 IP>: +``` + +使用 `init.sh` 里的账号登录。默认端口 `8090`,可用 `.env` 的 `AGENT_PORT` 修改。 + +对外只需要放行这一个端口。`agent-executor`、`wxbot` 和 MCP 服务都只在 Docker 内网,不映射到宿主机。 + +### 5. 使用外部 MCP 服务(可选) + +`init.sh` 默认写入同栈 MCP 服务: ```yaml -models: - - id: ds1 - display_name: "AMD DeepSeek 1" - - id: ds2 - display_name: "AMD DeepSeek 2" - - id: ds3 - display_name: "AMD DeepSeek 3" +mcp_servers: + - name: web_search + url: "http://mcp_web_search:3000/" + - name: officecli + url: "http://mcp_officecli:3000/" ``` -- 所有模型 ID 使用**同一个上游 URL**(由 cli-proxy-api 代理)。 -- 每个模型 ID 对应一个独立账号,互不共享。 -- 同时活跃会话数上限 = 模型 ID 数量。 +这些服务未启动时,core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会出现。需要时先启动 MCP 栈;不需要就在设置页删除或设为 `enable: false`。 -### 2.2 调度规则 - -- 会话创建时尝试绑定空闲模型: - - 有空闲 → 立即绑定,进入活跃状态。 - - 无空闲 → 会话进入排队状态,用户可输入但 AI 不应答。 -- 任务执行期间,该会话内所有模型请求**始终使用同一个模型 ID**(保证前缀缓存命中)。 -- 模型释放后立即检查全局等待队列,按 **FIFO** 取出最早排队的会话绑定。 +> 全新机器上两个网络有先后顺序:先启动本仓库(创建 `agent-mcp-net`),再启动 MCP 仓库。MCP 侧声明该网络为 external。 --- -## 三、任务阶段状态机 +## 使用 -### 3.1 阶段定义 +### 会话与模型 -| 阶段 | 含义 | 驱动方式 | -|---|---|---| -| **规划(Planning)** | 用户与 AI 讨论需求,澄清细节 | 用户点击「开始执行」→ 切换到执行 | -| **执行(Execution)** | AI 按 task.md 实际干活 | AI 完成任务 或 用户点击「终止」→ 结束 | +- 新建会话时自动绑定一个模型;不选则按平台轮转选择。 +- 会话创建后模型绑定保持,重启、追问都不会丢。 +- 模型被删除或禁用后,下一条消息会自动改选原平台的可用模型。 +- 管理员可在「设置 → 用户」给某个用户锁定默认模型。 +- 顶部「切换模型」只在该会话空闲时可用;正在输出时会拒绝换绑。 -### 3.2 界面开关 +会话状态: -界面顶部固定一个状态按钮(物理开关样式): +| 状态 | 含义 | +|---|---| +| 保持中 | 回合已结束,可以直接继续追问 | +| 活跃中 | 正在执行模型回合 | +| 已完成 | 已手动断开或空闲超时收口,仍可继续发消息 | +| 已终止 | 用户主动停止 | -- **规划阶段**:按钮显示「▶ 开始执行」 - - 点击后:系统自动追加一条 user 消息(见下文),阶段切换为执行。 -- **执行阶段**:按钮显示「■ 终止」 - - 点击后:设置终止标志,kill 当前进程(如有),模型释放,任务结束。 +### 文件 -### 3.3 追加的 user 消息模板 +- 输入框附件、微信附件都落在 `tasks/<会话 id>/`。 +- 右侧「任务文件」面板支持上传、下载、批量打包、删除、子目录浏览。 +- 模型生成的文件与用户上传的文件在同一目录,AI 可直接继续处理。 +- 超过 50 MB 的单文件上传会被拒绝;移动端大图上传前会在浏览器端压缩。 -用户点击「开始执行」时,系统向消息流中追加: +### 上下文压缩 -``` -我说完了,你可以开始干活了。先把我上面说的需求整理成 task.md 文件写入任务目录,然后按照 task.md 开始执行。 -``` +- 顶部「压缩」可手动触发:模型基于完整历史生成摘要,摘要之前的消息标记为已存档,UI 仍可见,但不再发给模型。 +- 当单回合输入 token 超过 `agent.auto_compress_tokens` 时,前端会弹一次确认框,询问是否压缩。 +- 历史重放还会自动把较旧的 `write_file` 参数正文、`fetch` / `read_file` 回执替换为单行占位,数据库与 UI 不受影响。 -此消息走正常发送流程(若会话活跃则实时发送;若排队则进入待发送队列)。 +### 定时任务 + +对 AI 说「每天早上九点汇总……」,它会在当前会话创建 cron 任务: + +- 每会话最多一个任务,最小间隔 1 小时,时区固定 `Asia/Shanghai`。 +- 每次触发前,会话历史整体标记为已存档,模型只看到任务提示词,等价一次全新会话。 +- 执行结果留在会话里,同时可通过微信推送。 +- 创建任务后,当前会话会收口为该任务的「专柜」,用户下一条消息自动进入新会话。 + +### 微信 + +在「设置 → 账户 → 微信绑定」生成二维码,扫码后即可单线对话: + +- 微信消息复用同一套会话和命令层,支持 `/new`、`/list`、`/switch`、`/delete`、`/rename`、`/models`、`/think`、`/stop`、`/compact`、`/clear`、`/status`、`/help`。 +- 图片、视频、文件会落到当前会话目录;单发媒体只留痕,不唤醒 AI。 +- AI 最终回复会推回微信;较长回复自动分段,超长时落成 `.md` 文件卡片。 +- 定时任务完成或失败也会通知微信。 + +### 长期记忆 + +- 会话空闲超过 `memory.wrap_idle_ms`(默认 4 小时)后,后台生成一条工作日记碎片,并归档、解绑通道。 +- 微信新会话开场注入最近 `memory.inject_max` 条碎片。 +- AI 可用 `recall` 工具按关键词、日期索引、具体某天检索全部日记。 +- 删除会话会连带删除它的日记碎片;清空会话在普通情况下也会删除,但定时任务「专柜」例外。 +- 日记调试页:`/memory.html`。 --- -## 四、会话状态模型 - -| 状态 | 含义 | 模型绑定 | 用户输入行为 | -|---|---|---|---| -| **排队中** | 无模型空闲,用户可输入,消息暂存并进入全局等待队列 | 无 | 可输入,AI 不应答(灰色图标) | -| **活跃中** | 已绑定模型,实时对话/执行 | 有 | 消息实时发给模型 | -| **保持中(held)** | AI 已答完,在租约内继续占用模型等待追问 | 有(临时保持) | 消息直接复用已绑模型,免排队 | -| **已完成/已取消** | 租约到期释放、任务结束或用户终止,模型已释放 | 无 | 可继续输入,自动再次进入排队 | - -> held 租约规则(`model_hold` 可配置):页面无观看者超过 `idle_release_ms`(默认 3 分钟)即释放;有人观看最长保持 `active_max_ms`(默认 30 分钟),防止挂着页面霸占模型池。「绑定模型但闲置」的会话(如新建后从未发言)同受此租约管理,到期自动变已完成并释放模型。 - -> 「已完成」和「已取消」本质相同,都回到“空闲”状态,仅记录一个结束原因。 - -### 4.1 核心流程 - -1. **创建会话**:生成任务 ID,创建任务目录,尝试绑定空闲模型。 -2. **用户输入**: - - 活跃中 / 保持中 → 实时发送(held 直接复用已绑模型)。 - - 排队中 / 已完成 → 消息暂存,会话自动进入全局等待队列。 -3. **模型分配**:模型空闲时,从全局队列 FIFO 取会话,绑定,将暂存消息一次性发出。 -4. **回合结束**:AI 答完,会话进入 held(模型不释放,可无缝追问);租约到期无追问 → 释放变 completed;用户终止 → cancelled 并立即释放。 - ---- - -## 五、任务目录 - -- 会话创建时立即创建目录:`/workspace/tasks/{task_id}/` -- 目录永久保留,用户可在 Web 端删除任务时勾选同时删除目录。 -- 上传的文件直接存入该目录。 -- `task.md` 由 AI 在用户确认开始执行后通过 `write_file` 工具生成。 - ---- - -## 六、终止机制 - -- 用户点击「终止」:设置 `cancelled` 标志。 -- 若模型正在流式输出:等待当前输出完成,不再继续。 -- 若正在执行 `terminal` 或脚本进程:立即 kill。 -- 之后不再发起新的模型请求或工具调用。 -- 模型 ID 立即释放。 - ---- - -## 七、借鉴 Zed 的 System Prompt 与工具定义 - -> 以下内容从 Zed 实际请求日志中提取,直接沿用,保持与 Zed 一致以利用缓存和验证过的行为。 - -### 7.1 System Prompt(完整) - -``` -# /app/server/templates/profile-default.txt -``` - -> 注:system prompt 完全静态(所有会话共用,利于前缀缓存)。动态会话信息(日期、任务目录、模型显示名)在新建会话时作为首条 user 消息自动发送,跟会话走。`` 当前为空,预留扩展。 - -### 7.2 内置工具定义(12 个;去掉 diagnostics、skill、spawn_agent;web_search 移至 MCP 服务) - -以下工具定义沿用 Zed 原始 JSON Schema,**保持字段完全一致以利于缓存**。 - -#### 1. `copy_path` - -```json -{ - "type": "function", - "function": { - "name": "copy_path", - "description": "Copies a file or directory in the project, and returns confirmation that the copy succeeded.\nDirectory contents will be copied recursively.\n\nThis tool should be used when it's desirable to create a copy of a file or directory without modifying the original.\nIt's much more efficient than doing this by separately reading and then writing the file or directory's contents, so this tool should be preferred over that approach whenever copying is the goal.\nThe only supported paths outside the project are descendants of `~/.agents/skills`, for global agent skills.", - "parameters": { - "required": ["source_path", "destination_path"], - "properties": { - "source_path": { - "description": "The source path of the file or directory to copy.\nIf a directory is specified, its contents will be copied recursively.\n\n\nIf the project has the following files:\n\n- directory1/a/something.txt\n- directory2/a/things.txt\n- directory3/a/other.txt\n\nYou can copy the first file by providing a source_path of \"directory1/a/something.txt\"\n", - "type": "string" - }, - "destination_path": { - "description": "The destination path where the file or directory should be copied to.\n\n\nTo copy \"directory1/a/something.txt\" to \"directory2/b/copy.txt\", provide a destination_path of \"directory2/b/copy.txt\"\n", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 2. `create_directory` - -```json -{ - "type": "function", - "function": { - "name": "create_directory", - "description": "Creates a new directory at the specified path within the project. Returns confirmation that the directory was created.\n\nThis tool creates a directory and all necessary parent directories. It should be used whenever you need to create new directories within the project.\nThe only supported path outside the project is `~/.agents/skills` or a descendant, for global agent skills.", - "parameters": { - "required": ["path"], - "properties": { - "path": { - "description": "The path of the new directory.\n\n\nIf the project has the following structure:\n\n- directory1/\n- directory2/\n\nYou can create a new directory by providing a path of \"directory1/new_directory\"\n\n\n\nTo create a global agent skill directory, you may provide a path under `~/.agents/skills`, such as `~/.agents/skills/my-skill`.\n", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 3. `delete_path` - -```json -{ - "type": "function", - "function": { - "name": "delete_path", - "description": "Deletes the file or directory (and the directory's contents, recursively) at the specified path in the project, and returns confirmation of the deletion.\n\nThe only supported paths outside the project are descendants of `~/.agents/skills`, for global agent skills.", - "parameters": { - "required": ["path"], - "properties": { - "path": { - "description": "The path of the file or directory to delete.\n\n\nIf the project has the following files:\n\n- directory1/a/something.txt\n- directory2/a/things.txt\n- directory3/a/other.txt\n\nYou can delete the first file by providing a path of \"directory1/a/something.txt\"\n", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 4. `edit_file` - -```json -{ - "type": "function", - "function": { - "name": "edit_file", - "description": "This is a tool for applying edits to an existing file.\n\nBefore using this tool, use the `read_file` tool to understand the file's contents and context.\nTo create a new file or overwrite an existing one with completely new contents, use the `write_file` tool instead.\n\nThe only supported path outside the project is `~/.agents/skills` or a descendant, for global agent skills.\n\n`read_file` prefixes each line of its output with a line number right-aligned in a\n6-character field followed by a single tab, then the line's actual content. When you\nderive `old_text` or `new_text` from that output, strip this prefix and keep only what\ncomes after the tab, preserving the original indentation (tabs and spaces) exactly.\nNever include any part of the line number prefix in `old_text` or `new_text`.", - "parameters": { - "required": ["path", "edits"], - "properties": { - "path": { - "description": "The full path of the file to edit in the project.\n\nWARNING: When specifying which file path need changing, you MUST start each path with one of the project's root directories, unless it's a global agent skill under `~/.agents/skills`.\n\nThe following examples assume we have two root directories in the project:\n- /a/b/backend\n- /c/d/frontend\n\n\n`backend/src/main.rs`\n\nNotice how the file path starts with `backend`. Without that, the path would be ambiguous and the call would fail!\n\n\n\n`frontend/db.js`\n\n\n\nTo edit a global agent skill file, you may provide a path under `~/.agents/skills`, such as `~/.agents/skills/my-skill/SKILL.md`.\n", - "type": "string" - }, - "edits": { - "description": "List of edit operations to apply sequentially.\nEach edit finds `old_text` in the file and replaces it with `new_text`.", - "type": "array", - "items": { - "description": "A single edit operation that replaces old text with new text\nProperly escape all text fields as valid JSON strings.\nRemember to escape special characters like newlines (`\\n`) and quotes (`\"`) in JSON strings.", - "type": "object", - "properties": { - "old_text": { - "description": "The exact text to find in the file. This will be matched using fuzzy matching\nto handle minor differences in whitespace or formatting.\n\nBe minimal with replacements:\n- For unique lines, include only those lines\n- For non-unique lines, include enough context to identify them", - "type": "string" - }, - "new_text": { - "description": "The text to replace it with", - "type": "string" - } - }, - "required": ["old_text", "new_text"] - } - } - }, - "type": "object" - } - } -} -``` - -#### 5. `fetch` - -```json -{ - "type": "function", - "function": { - "name": "fetch", - "description": "Fetches a URL and returns the content as Markdown.\n\nThis tool is not run inside the terminal OS sandbox, but it still refuses to\nreach any host that hasn't been granted network access. It shares the same\nper-host grants as the `terminal` tool: approving a host for one authorizes\nit for the other, whether the grant is for this thread or saved permanently.\nWhen unsandboxed access has been granted, these restrictions are lifted\nentirely, matching the terminal, which is also how loopback and IP-literal\nhosts (which can't be granted individually) become reachable.", - "parameters": { - "required": ["url"], - "properties": { - "url": { - "description": "The URL to fetch.", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 6. `find_path` - -```json -{ - "type": "function", - "function": { - "name": "find_path", - "description": "Find file paths that match a given pattern.\n\n- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n- Returns matching file paths sorted alphabetically\n- Prefer the `grep` tool to this tool when searching for symbols unless you have specific information about paths.\n- Use this tool when you need to find files by name patterns\n- Results are paginated with 50 matches per page. Use the optional 'offset' parameter to request subsequent pages.", - "parameters": { - "required": ["glob"], - "properties": { - "glob": { - "description": "The glob to match against every path in the project.\n\n\nIf the project has the following root directories:\n\n- directory1/a/something.txt\n- directory2/a/things.txt\n- directory3/a/other.txt\n\nYou can get back the first two paths by providing a glob of \"*thing*.txt\"\n", - "type": "string" - }, - "offset": { - "description": "Optional starting position for paginated results (0-based).\nWhen not provided, starts from the beginning.", - "type": "integer", - "default": 0, - "minimum": 0 - } - }, - "type": "object" - } - } -} -``` - -#### 7. `grep` - -```json -{ - "type": "function", - "function": { - "name": "grep", - "description": "Searches the contents of files in the project with a regular expression\n\n- Prefer this tool to path search when searching for symbols in the project, because you won't need to guess what path it's in.\n- Supports full regex syntax (eg. \"log.*Error\", \"function\\\\s+\\\\w+\", etc.)\n- Pass an `include_pattern` if you know how to narrow your search on the files system\n- Never use this tool to search for paths. Only search file contents with this tool.\n- Use this tool when you need to find files containing specific patterns\n- Results are paginated with 20 matches per page. Use the optional 'offset' parameter to request subsequent pages.\n- DO NOT use HTML entities solely to escape characters in the tool parameters.", - "parameters": { - "required": ["regex"], - "properties": { - "regex": { - "description": "A regex pattern to search for in the entire project. Note that the regex will be parsed by the Rust `regex` crate.\n\nDo NOT specify a path here! This will only be matched against the code **content**.", - "type": "string" - }, - "include_pattern": { - "description": "A glob pattern for the paths of files to include in the search.\nSupports standard glob patterns like \"**/*.rs\" or \"frontend/src/**/*.ts\".\nIf omitted, all files in the project will be searched.\n\nThe glob pattern is matched against the full path including the project root directory.\n\n\nIf the project has the following root directories:\n\n- /a/b/backend\n- /c/d/frontend\n\nUse \"backend/**/*.rs\" to search only Rust files in the backend root directory.\nUse \"frontend/src/**/*.ts\" to search TypeScript files only in the frontend root directory (sub-directory \"src\").\nUse \"**/*.rs\" to search Rust files across all root directories.\n", - "type": "string", - "nullable": true - }, - "offset": { - "description": "Optional starting position for paginated results (0-based).\nWhen not provided, starts from the beginning.", - "type": "integer", - "default": 0, - "minimum": 0 - }, - "case_sensitive": { - "description": "Whether the regex is case-sensitive. Defaults to false (case-insensitive).", - "type": "boolean", - "default": false - } - }, - "type": "object" - } - } -} -``` - -#### 8. `list_directory` - -```json -{ - "type": "function", - "function": { - "name": "list_directory", - "description": "Lists files and directories in a given path. Prefer the `grep` or `find_path` tools when searching the codebase.\n\nThe only supported path outside the project is `~/.agents/skills` or a descendant, for global agent skills.", - "parameters": { - "required": ["path"], - "properties": { - "path": { - "description": "The fully-qualified path of the directory to list in the project.\n\nThis path should never be absolute, and the first component of the path should always be a root directory in a project, unless it's a global agent skill directory under `~/.agents/skills`.\n\n\nIf the project has the following root directories:\n\n- directory1\n- directory2\n\nYou can list the contents of `directory1` by using the path `directory1`.\n\n\n\nIf the project has the following root directories:\n\n- foo\n- bar\n\nIf you wanna list contents in the directory `foo/baz`, you should use the path `foo/baz`.\n\n\n\nTo list a global agent skill directory, you may provide a path under `~/.agents/skills`, such as `~/.agents/skills/my-skill`.\n", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 9. `move_path` - -```json -{ - "type": "function", - "function": { - "name": "move_path", - "description": "Moves or rename a file or directory in the project, and returns confirmation that the move succeeded.\n\nIf the source and destination directories are the same, but the filename is different, this performs a rename. Otherwise, it performs a move.\n\nThis tool should be used when it's desirable to move or rename a file or directory without changing its contents at all.\nThe only supported paths outside the project are descendants of `~/.agents/skills`, for global agent skills.", - "parameters": { - "required": ["source_path", "destination_path"], - "properties": { - "source_path": { - "description": "The source path of the file or directory to move/rename.\n\n\nIf the project has the following files:\n\n- directory1/a/something.txt\n- directory2/a/things.txt\n- directory3/a/other.txt\n\nYou can move the first file by providing a source_path of \"directory1/a/something.txt\"\n", - "type": "string" - }, - "destination_path": { - "description": "The destination path where the file or directory should be moved/renamed to.\nIf the paths are the same except for the filename, then this will be a rename.\n\n\nTo move \"directory1/a/something.txt\" to \"directory2/b/renamed.txt\",\nprovide a destination_path of \"directory2/b/renamed.txt\"\n", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -#### 10. `read_file` - -```json -{ - "type": "function", - "function": { - "name": "read_file", - "description": "Reads the content of the given file in the project.\n\n- Never attempt to read a path that hasn't been previously mentioned.\n- For large files, this tool returns a file outline with symbol names and line numbers instead of the full content.\n This outline IS a successful response - use the line numbers to read specific sections with start_line/end_line.\n Do NOT retry reading the same file without line numbers if you receive an outline.\n- This tool supports reading image files. Supported formats: PNG, JPEG, WebP, GIF, BMP, TIFF.\n Image files are returned as visual content that you can analyze directly.\n\nThe only supported path outside the project is `~/.agents/skills` or a descendant, for global agent skills.", - "parameters": { - "required": ["path"], - "properties": { - "path": { - "description": "The relative path of the file to read.\n\nThis path should never be absolute, and the first component of the path should always be a root directory in a project, unless it's a global agent skill under `~/.agents/skills`.\n\n\nIf the project has the following root directories:\n\n- /a/b/directory1\n- /c/d/directory2\n\nIf you want to access `file.txt` in `directory1`, you should use the path `directory1/file.txt`.\nIf you want to access `file.txt` in `directory2`, you should use the path `directory2/file.txt`.\n\n\n\nTo read a global agent skill file, you may provide a path under `~/.agents/skills`, such as `~/.agents/skills/my-skill/SKILL.md`.\n", - "type": "string" - }, - "start_line": { - "description": "Optional line number to start reading on (1-based index)", - "type": "integer", - "nullable": true, - "minimum": 0, - "default": null - }, - "end_line": { - "description": "Optional line number to end reading on (1-based index, inclusive)", - "type": "integer", - "nullable": true, - "minimum": 0, - "default": null - } - }, - "type": "object" - } - } -} -``` - -#### 11. `terminal` - -```json -{ - "type": "function", - "function": { - "name": "terminal", - "description": "Executes a shell one-liner and returns the combined output.\n\nThis tool spawns a process using the user's shell, reads from stdout and stderr (preserving the order of writes), and returns a string with the combined output result.\n\nThe output results will be shown to the user already, only list it again if necessary, avoid being redundant.\n\nMake sure you use the `cd` parameter to navigate to one of the root directories of the project. NEVER do it as part of the `command` itself, otherwise it will error.\n\nDo not generate terminal commands that use shell substitutions or interpolations such as `$VAR`, `${VAR}`, `$(...)`, backticks, `$((...))`, `<(...)`, or `>(...)`. Resolve those values yourself before calling this tool, or ask the user for the literal value to use.\n\nDo not pipe output to `head`, `tail`, or similar output-filtering commands just to reduce what you receive. Instead, use `head_lines` and/or `tail_lines`; this keeps the terminal output visible to the user in real time while limiting only the final output sent back to you. When both are specified, the first `head_lines` lines are returned, then a blank line, then the last `tail_lines` lines. Avoid requesting too many lines, or the response may waste tokens or exceed the context window.\n\nDo not use this tool for commands that run indefinitely, such as servers (like `npm run start`, `npm run dev`, `python -m http.server`, etc) or file watchers that don't terminate on their own.\n\nFor potentially long-running commands, prefer specifying `timeout_ms` to bound runtime and prevent indefinite hangs.\n\nRemember that each invocation of this tool will spawn a new shell process, so you can't rely on any state from previous invocations.\n\nThe terminal is an interactive pty, so any command that blocks waiting for input will hang the tool until it times out. To avoid this:\n\n- Always insert `--no-pager` immediately after `git` for any read-only git command, including `git log`, `git diff`, `git show`, `git blame`, and `git stash show`. Example: `git --no-pager log -n 5` (NOT `git log -n 5`).\n- Prefer Git flags that avoid optional metadata writes when possible, such as `git --no-optional-locks status` instead of `git status`.\n- Always prepend `GIT_EDITOR=true ` to any git command that may invoke an editor, including `git rebase`, `git commit`, `git merge`, and `git tag`. Example: `GIT_EDITOR=true git rebase origin/main` (NOT `git rebase origin/main`).\n- For other commands that may open a pager or editor, set `PAGER=cat` and/or `EDITOR=true` similarly.", - "parameters": { - "required": ["command", "cd"], - "properties": { - "command": { - "description": "The one-liner command to execute. Do not include shell substitutions or interpolations such as `$VAR`, `${VAR}`, `$(...)`, backticks, `$((...))`, `<(...)`, or `>(...)`; resolve those values first or ask the user for the literal value to use.\n\nREMINDER: read-only git commands (`git log`, `git diff`, `git show`, `git blame`) MUST include `--no-pager` (e.g. `git --no-pager log`). Prefer `git --no-optional-locks status` over `git status` to avoid optional metadata writes. Git commands that may open an editor (`git rebase`, `git commit`, `git merge`, `git tag`) MUST be prefixed with `GIT_EDITOR=true ` (e.g. `GIT_EDITOR=true git rebase origin/main`). Otherwise the terminal will hang.", - "type": "string" - }, - "cd": { - "description": "Working directory for the command. This must be one of the root directories of the project.", - "type": "string" - }, - "timeout_ms": { - "description": "Optional maximum runtime (in milliseconds). If exceeded, the running terminal task is killed.", - "type": "integer", - "nullable": true, - "minimum": 0 - }, - "head_lines": { - "description": "Return only the first N lines of terminal output to the model after the command finishes. Do not pipe output to `head`; use this parameter instead so the user can still see live output. Avoid requesting too many lines, or the response may waste tokens or exceed the context window.", - "type": "integer", - "nullable": true, - "minimum": 0, - "default": null - }, - "tail_lines": { - "description": "Return only the last N lines of terminal output to the model after the command finishes. Do not pipe output to `tail`; use this parameter instead so the user can still see live output. Avoid requesting too many lines, or the response may waste tokens or exceed the context window.", - "type": "integer", - "nullable": true, - "minimum": 0, - "default": null - } - }, - "type": "object" - } - } -} -``` - -#### 12. `write_file` - -```json -{ - "type": "function", - "function": { - "name": "write_file", - "description": "This is a tool for creating a new file or overwriting an existing file with completely new contents.\n\nTo make granular edits to an existing file, prefer the `edit_file` tool instead.\n\nBefore using this tool, verify the directory path is correct (only applicable when creating new files). Use the `list_directory` tool to verify the parent directory exists and is the correct location\n\nThe only supported path outside the project is `~/.agents/skills` or a descendant, for global agent skills.", - "parameters": { - "required": ["path", "content"], - "properties": { - "path": { - "description": "The full path of the file to create or overwrite in the project.\n\nWARNING: When specifying which file path need changing, you MUST start each path with one of the project's root directories, unless it's a global agent skill under `~/.agents/skills`.\n\nThe following examples assume we have two root directories in the project:\n- /a/b/backend\n- /c/d/frontend\n\n\n`backend/src/main.rs`\n\nNotice how the file path starts with `backend`. Without that, the path would be ambiguous and the call would fail!\n\n\n\n`frontend/db.js`\n\n\n\nTo create or overwrite a global agent skill file, you may provide a path under `~/.agents/skills`, such as `~/.agents/skills/my-skill/SKILL.md`.\n", - "type": "string" - }, - "content": { - "description": "The entire content for the file.", - "type": "string" - } - }, - "type": "object" - } - } -} -``` - -> 说明:Zed 原始 16 个工具中去掉 `diagnostics`、`skill`、`spawn_agent`、`web_search`,内置保留上述 12 个。`web_search` 等外部能力改由 MCP 服务提供:在 config 的 `mcp_servers`(url + headers)配置,启动时 `tools/list` 自动发现并追加到内置工具之后一起发给模型,与内置工具严格分离。 - ---- - -## 八、技术架构 - -### 8.1 技术栈 - -- **后端**:Node.js(或 Python FastAPI,二选一,建议 Node.js 因前端同构) -- **前端**:单页 H5 + Vanilla JS + SSE(不引入重型框架) -- **数据库**:SQLite -- **部署**:Docker Compose -- **认证**:内置多用户登录(用户名/明文密码配在 `config.yml` 的 `auth.users`,登录页 + HttpOnly cookie,不做任务隔离;不用 nginx htpasswd,因手机浏览器原生下载不带 Basic 头会失败) - -### 8.2 系统组件 - -``` -┌─────────────────────────────────────────────────┐ -│ Web UI (H5) │ -│ 会话列表 │ 聊天界面 │ 任务详情 │ 文件管理 │ -└──────────────────┬──────────────────────────────┘ - │ SSE / REST -┌──────────────────▼──────────────────────────────┐ -│ Agent 后端服务 (Docker) │ -│ ┌──────────────────────────────────────────┐ │ -│ │ 会话管理 & 模型调度器 │ │ -│ │ (模型池: ds1, ds2, ds3...) │ │ -│ └──────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ Agent 核心循环 │ │ -│ │ (模型请求 → 工具调用 → 结果反馈) │ │ -│ └──────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ 工具执行器 │ │ -│ │ (文件/终端/fetch/web_search) │ │ -│ └──────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────┐ │ -│ │ 任务目录管理 │ │ -│ │ /workspace/tasks/{task_id}/ │ │ -│ └──────────────────────────────────────────┘ │ -└──────────────────┬──────────────────────────────┘ - │ HTTP (SSE) -┌──────────────────▼──────────────────────────────┐ -│ cli-proxy-api (上游代理) │ -│ 同一 URL,多个模型 ID 映射不同账号 │ -└──────────────────┬──────────────────────────────┘ - │ -┌──────────────────▼──────────────────────────────┐ -│ 上游 AI 服务 (developer.amd.com.cn) │ -└─────────────────────────────────────────────────┘ -``` - ---- - -## 九、数据模型设计 - -### 9.1 SQLite 表结构 - -```sql --- 会话表 -CREATE TABLE sessions ( - id TEXT PRIMARY KEY, -- 任务 ID,如 "task-20260830-001" - title TEXT DEFAULT '', -- 会话标题(可由 AI 生成或用户填写) - status TEXT NOT NULL, -- queued | active | held | completed | cancelled - model_id TEXT, -- 当前绑定的模型 ID(ds1/ds2/ds3),释放/排队时为空 - last_model_id TEXT, -- 最近用过的模型;释放后新消息优先回绑,被占才另选空闲 - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL, - completed_at INTEGER, - cancelled_at INTEGER, - held_at INTEGER -- 进入 held(保持租约)的时间 -); - --- 消息表 -CREATE TABLE messages ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - session_id TEXT NOT NULL, - role TEXT NOT NULL, -- system | user | assistant | tool - content TEXT, -- 文本内容(assistant 工具调用时可为空) - tool_calls TEXT, -- JSON 字符串,assistant 工具调用 - tool_call_id TEXT, -- tool 角色消息关联的 tool_call id - name TEXT, -- 工具名称(tool 角色) - created_at INTEGER NOT NULL, - FOREIGN KEY (session_id) REFERENCES sessions(id) -); - --- 文件表(记录任务目录中的文件,用于下载) -CREATE TABLE files ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - session_id TEXT NOT NULL, - filename TEXT NOT NULL, -- 相对任务目录的路径 - size INTEGER, - created_at INTEGER NOT NULL, - FOREIGN KEY (session_id) REFERENCES sessions(id) -); - --- 模型池配置(也可存配置文件,此处作为运行时状态) -CREATE TABLE model_pool ( - id TEXT PRIMARY KEY, -- ds1, ds2, ds3 - display_name TEXT, - is_busy INTEGER DEFAULT 0, - current_session_id TEXT -); - --- 全局等待队列 -CREATE TABLE wait_queue ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - session_id TEXT NOT NULL, - queued_at INTEGER NOT NULL, - FOREIGN KEY (session_id) REFERENCES sessions(id) -); -``` - -### 9.2 任务目录结构 - -``` -/workspace/tasks/ -└── {task_id}/ - ├── task.md # 需求说明(AI 在确认开始后生成) - ├── ... # 用户上传的文件和 AI 生成的文件 -``` - ---- - -## 十、API 设计 - -### 10.1 会话管理 - -| 方法 | 路径 | 说明 | -|---|---|---| -| POST | `/api/sessions` | 创建会话,生成任务目录,尝试绑定模型 | -| GET | `/api/sessions` | 获取会话列表 | -| GET | `/api/sessions/{id}` | 获取会话详情(含消息、状态、阶段) | -| DELETE | `/api/sessions/{id}?delete_dir=true` | 删除会话,可选删除任务目录 | - -### 10.2 消息与交互 - -| 方法 | 路径 | 说明 | -|---|---|---| -| POST | `/api/sessions/{id}/messages` | 发送用户消息(活跃时实时发送,排队时暂存) | -| GET | `/api/sessions/{id}/stream` | SSE 流式获取会话事件(模型输出、工具调用等) | -| POST | `/api/sessions/{id}/start` | 点击「开始执行」:追加 user 消息,阶段切换为 execution | -| POST | `/api/sessions/{id}/stop` | 终止任务:设置取消标志,kill 进程,释放模型 | - -### 10.3 文件管理 - -| 方法 | 路径 | 说明 | -|---|---|---| -| POST | `/api/sessions/{id}/files` | 上传文件到任务目录 | -| GET | `/api/sessions/{id}/files` | 列出任务目录文件 | -| GET | `/api/sessions/{id}/files/{filename}` | 下载文件 | -| DELETE | `/api/sessions/{id}/files/{filename}` | 删除文件 | - ---- - -## 十一、Agent 核心循环 - -### 11.1 伪代码 - -``` -function runAgent(session): - model_id = session.model_id - messages = loadMessages(session.id) # 完整消息历史 - - while not session.cancelled: - # 构建请求 - request = { - model: model_id, - messages: messages, - stream: true, - stream_options: {include_usage: true}, - temperature: 1.0, - tools: TOOLS_DEFINITIONS - } - - # 调用模型(流式) - response = callModelStreaming(request) - - # 累积模型输出 - assistant_message = {role: "assistant", content: "", tool_calls: []} - - for chunk in response: - if session.cancelled: - break # 停止处理剩余 chunk,但当前 chunk 已完成 - if chunk.delta.content: - assistant_message.content += chunk.delta.content - emitSSE(session, "assistant_text", chunk.delta.content) - if chunk.delta.tool_calls: - # 累积工具调用参数(分片拼接) - mergeToolCalls(assistant_message.tool_calls, chunk.delta.tool_calls) - - if session.cancelled: - break - - # 保存 assistant 消息 - saveMessage(session, assistant_message) - - # 检查是否有工具调用 - if assistant_message.tool_calls and len(assistant_message.tool_calls) > 0: - # 执行所有工具调用(可并行) - tool_results = [] - for tool_call in assistant_message.tool_calls: - if session.cancelled: - break - emitSSE(session, "tool_call", tool_call) - result = executeTool(tool_call, session) # 可能触发 kill - emitSSE(session, "tool_result", result) - tool_results.append({ - role: "tool", - tool_call_id: tool_call.id, - content: result - }) - saveMessage(session, tool_results[-1]) - - # 将工具结果加入消息历史 - messages.append(assistant_message) - messages.extend(tool_results) - continue # 继续循环,让模型处理工具结果 - else: - # 无工具调用,任务结束 - break - - # 释放模型 - releaseModel(session) - session.status = "completed" # 或 "cancelled" - updateSession(session) - - # 检查等待队列 - dispatchNextQueuedSession() -``` - -### 11.2 工具执行器要点 - -- **文件工具**:所有路径必须解析到任务目录内(防路径穿越)。 -- **terminal**:使用 `child_process.spawn`,设置超时(默认 30s),输出截断(前 10000 字符)。支持 kill。 -- **fetch**:使用 HTTP 客户端抓取,转换为 Markdown 返回。 -- **MCP 工具**:外部 MCP 服务在 config 的 `mcp_servers` 配置(url + headers,可多个);启动时 `tools/list` 发现工具追加到内置工具之后,调用经 `tools/call` 转发(如 web_search)。 - -### 11.3 模型调度器要点 - -- 维护模型池状态(is_busy、current_session_id)。 -- 会话创建时尝试分配空闲模型。 -- 模型释放时从 wait_queue 取最早会话绑定,并发送暂存消息。 -- 同一会话内所有模型请求使用同一 model_id。 - ---- - -## 十二、前端页面设计 - -### 12.1 页面结构 - -``` -┌──────────────────────────────────────────┐ -│ 顶部栏:任务状态开关 + 新建会话按钮 │ -├──────────────────────────────────────────┤ -│ 主区域: │ -│ ├─ 会话列表(左侧或抽屉) │ -│ └─ 聊天/任务详情(右侧主视图) │ -│ ├─ 消息气泡(用户/AI/工具调用) │ -│ ├─ 文件上传按钮 │ -│ ├─ 文件列表 │ -│ └─ 输入框 │ -└──────────────────────────────────────────┘ -``` - -### 12.2 移动端交互 - -- 会话列表与详情通过滑动切换(参考采购清单页交互)。 -- 状态开关固定在顶部,规划阶段显示「▶ 开始执行」,执行阶段显示「■ 终止」。 -- 排队中时 AI 头像灰色,输入框仍可输入,发送后消息进入暂存队列。 - -### 12.3 消息展示 - -- 用户消息:右侧气泡。 -- AI 文本:左侧气泡,流式显示。 -- 工具调用:特殊卡片,显示工具名和参数摘要。 -- 工具结果:折叠显示,可展开查看完整输出。 - ---- - -## 十三、Docker 部署 - -### 13.1 Docker Compose(顶层 `docker-compose.yml`) +## 配置 + +`config.yml` 只给 `agent-core` 读取,包含平台密钥和登录密钥。`agent-executor`、`wxbot` 不挂载、不读取它。 + +主要配置段: + +| 段 | 作用 | +|---|---| +| `platforms` | 模型平台池:`name`、`url`、`type`、`models`、`keys` | +| `model_profiles` | prompt + 工具名单组合;模型用 `profile: <名>` 引用 | +| `tools_deny` | 全局工具黑名单,默认屏蔽元工具 `lab` | +| `auth` | 登录账号、`secret`、有效期;留空则不启用认证 | +| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`enable`、`timeout_ms`、工具名单 | +| `public_link` | 公网临时链接前缀与有效期 | +| `agent` | 温度、最大工具迭代、重试、语言、压缩阈值、空闲收口、历史裁剪 | +| `memory` | 日记注入条数、保留期、空闲收口阈值 | +| `terminal` / `fetch` | 命令超时与输出上限、抓取超时、字节数、SSRF 开关 | +| `skills` | 技能目录与单次执行超时 | +| `upload` | 前端大图压缩阈值与参数 | +| `workspace_root` / `data_root` | 任务目录与 SQLite / 调试产物目录 | + +平台结构示例: ```yaml -services: - agent: - build: ./app - restart: unless-stopped - ports: - - "${AGENT_PORT:-8090}:8090" # 直接映射宿主机端口,IP:端口 访问 - volumes: - - ./tasks:/workspace/tasks # 持久化:任务目录 - - ./data:/workspace/data # 持久化:数据目录 + SQLite - - ./config.yml:/app/config.yml - environment: - - PORT=8090 - - AGENT_CONFIG=/app/config.yml - networks: - - agent-mcp-net - -networks: - agent-mcp-net: - name: agent-mcp-net # 由本仓库创建(固定名字);mcp 侧 external 加入 - driver: bridge -``` - -### 13.2 对外暴露(IP:端口) - -无域名/反代时,compose 直接把容器 8090 映射到宿主机 8090,浏览器访问 `http://<服务器IP>:8090`(端口可用 `.env` 的 `AGENT_PORT` 改)。网络 `agent-mcp-net` 与 `mcp` 仓库的服务共用、由本仓库创建(无需手动 `docker network create`,但因此要**先起 agent 再起 mcp**):core 与 executor 都靠它按容器名访问 MCP。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),多用户共享同一任务库,不做任务隔离。 - -**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:外部服务(如智谱)生成视频前要拉参考图,走的是 core 的匿名短链 `GET /p/`——由 AI 调内置工具 `mint_public_link`(传文件名,core 在进程内现签)拿到,没有任何额外的签发端口,见 `docs/DEPLOY.md` 第 4.1 节。 - -HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker 不注册、`navigator.clipboard` 降级(前端已有回退),登录 cookie 无 `Secure` 标志可正常工作。日后若加 HTTPS 反代,**SSE 需关代理缓冲**(`proxy_buffering off`),详见 `docs/DEPLOY.md`。 - ---- - -## 十四、配置文件示例 - -完整字段与默认值见 `app/config.example.yml`(core 专属,与 `server/config.js` 的 `DEFAULTS` 一一对应); -部署时由 `scripts/init.sh` 生成的顶层 `config.yml` 只覆盖 `platforms` / `auth` / `mcp_servers`。 - -```yaml -# 模型池:平台(platforms) → models(平台层,多 key 共用)+ keys(api_key/concurrency)。 -# url/type 配在平台层;模型只声明 {id, display_name, profile, vision}。加载时打平成全局模型列表。 platforms: - - name: proxy-a - url: "https://proxy-a.example.com/v1" - type: openai # 选填,缺省取 name;决定余额查询适配器 + - name: bigmodel + url: https://open.bigmodel.cn/api/paas/v4 + type: bigmodel # 决定余额查询适配器 models: - - id: ds1 - display_name: "AMD DeepSeek 1" # 选填,缺省同 id - profile: mini # 选填,引用顶层 model_profiles 的 prompt+tools 组合 + - id: glm-5.3-flash + vision: true + extra_params: { reasoning_effort: "low", tool_stream: true } + thinking_params: { reasoning_effort: "max" } keys: - api_key: "sk-..." - concurrency: 1 # 该 Key 并发会话数,默认 1 - -# 模型 profile:预定义「system prompt 文件 + tools 白名单」组合,模型用 profile: <名> 引用。 -# 内置 mini/zero 两套默认组合,可用同名覆盖或新增;详见 §5.8。 -model_profiles: - mini: - tools_allow: [read_file, write_file, edit_file, list_directory, terminal] - system_prompt_file: mini-system.txt # 相对 server/templates/ - -workspace_root: "/workspace/tasks" - -terminal: - default_timeout_ms: 30000 - max_output_chars: 10000 - -agent: - temperature: 1.0 - max_tool_iterations: 100 ``` ---- +通用模型字段: -## 十五、开发阶段规划 +- `enable: false`:模型不进池,不参与分配。 +- `vision: false`:读图时不回传像素,只给文字占位。 +- `profile: <名>`:引用 `model_profiles`,不配则使用默认全量 prompt 与工具。 +- `reasoning_ack_field`:需要把思考链回传给上游时填写,例如 DeepSeek 系的 `reasoning_content`。 -1. **阶段一:核心后端** - - 数据模型与 SQLite 初始化 - - 会话管理 API - - 模型池与调度器 - - Agent 核心循环(支持工具调用) +日常修改配置建议使用设置页;改完需重启生效。设置页写入前会先校验,非法配置不会覆盖原文件。 -2. **阶段二:前端** - - 会话列表页 - - 聊天界面(SSE 流式) - - 文件上传/下载 - - 状态开关 +### 环境变量 -3. **阶段三:集成与部署** - - Docker 化 - - nginx-proxy 集成 - - 基本认证 - - 测试与优化 +| 变量 | 作用 | +|---|---| +| `AGENT_CONFIG` | core 配置文件路径,容器内固定 `/app/config.yml` | +| `PORT` | core 监听端口,容器内 `8090` | +| `EXECUTOR_URL` | `agent-executor` 地址;空则命令在 core 进程内本地执行,仅适合开发 | +| `EXECUTOR_TOKEN` | core ↔ executor 的 Bearer token,两侧同值 | +| `WXBOT_URL` | wxbot 地址;置空则微信功能整体关闭 | +| `WXBOT_TOKEN` | core ↔ wxbot 的共享 token | +| `VIRTUAL_HOST` | 设置后 `public_link.base_url` 强制取 `https://<第一个域名>` | +| `PREVIEW_PROXIES` | 覆盖内置预览反代注册表(JSON 数组) | +| `EXECUTOR_LOG_LEVEL` / `WXBOT_LOG_LEVEL` | 两个附属服务的日志等级 | + +`config.yml` 与 `.env` 都含密钥,已在 `.gitignore` 中。不要提交,也不要挂给不需要它的容器。 --- -## 十六、备注 +## 内置工具 -- 本方案借鉴 Zed agent 的 system prompt 和工具定义,保持格式一致以利用上游前缀缓存。 -- `skill` 和 `spawn_agent` 工具暂不实现,但预留扩展位。 -- 所有文件操作必须限制在任务目录内。 -- 模型调度遵循 FIFO,同一会话始终使用同一模型 ID。 +模型实际收到的工具是内置工具加 MCP 工具,再经 `tools_deny` 与模型 `profile` 过滤。 + +| 工具 | 用途 | +|---|---| +| `read_file` | 读文本或图片;大文件返回符号大纲;支持 `@<会话 id>/<路径>` 只读查看历史会话文件 | +| `write_file` | 新建或覆盖文本文件 | +| `edit_file` | 按 `old_text` / `new_text` 做精确或容错编辑 | +| `list_directory` | 单层列目录;支持 `@<会话 id>/<路径>` | +| `copy_path` | 复制文件或目录;可从历史会话导入文件 | +| `terminal` | 执行 shell 命令;默认在会话目录,超时可终止 | +| `fetch` | 抓取 HTTP/HTTPS 并转 Markdown;带 SSRF 防护与分段续读 | +| `mint_public_link` | 为会话内文件签发短期公网链接 | +| `skill` | 技能 `list` / `get` / `run` | +| `db` | 操作会话本地 `data.db`:`exec`、`query`、`insert`、`tables`、`schema` | +| `schedule` | 定时任务 `get` / `list` / `create` / `update` / `delete` | +| `profile` | 用户画像 `list` / `set` / `add` / `remove` | +| `recall` | 长期记忆 `search` / `days` / `day` | +| `lab` | 元工具:按名字调用任意工具,`help` 可列出全部工具;默认被全局黑名单屏蔽 | + +跨会话路径只读:`@` 形式只用于 `read_file`、`list_directory` 和 `copy_path` 的源路径,且只能访问同一用户自己的会话。要真正处理旧文件,先用 `copy_path` 导入当前会话。 --- -**文档版本**:v1.0 -**最后更新**:2026-08-30 +## 技能 + +技能是 `skills/<名字>/` 目录: + +```text +skills/my-skill/ +├── SKILL.md # 必需:描述、input_schema、可选 required / visit_url +├── run.py | run.sh # 必需:入口,唯一命令行参数是 JSON 字符串 +├── requirements.txt # 可选:Python 依赖 +└── install.sh # 可选:系统层安装脚本,镜像构建期执行 +``` + +- `SKILL.md` 的 `description` 会进入 system prompt,模型启动时就知道有哪些技能。 +- `input_schema.required` 在 `skill op=run` 前校验。 +- 入口脚本以绝对路径启动;远端执行时 cwd 是会话目录,本地开发时是技能目录。相对路径参数会先按会话目录转成绝对路径。 +- `requirements.txt` 的依赖由 `agent-executor-init` 安装到 `skills/deps`;技能容器通过 `PYTHONPATH` 可见。 +- `install.sh` 在镜像构建期以 root 执行,用于必须落在系统层的依赖。改完需要重建 executor 镜像。 +- 技能目录在 executor 中只读,运行期不能修改技能本身。 + +设置页支持创建、重命名、删除技能和在线编辑文本文件;技能列表变更后会实时刷新 system prompt 中的清单,无需重启。 + +--- + +## 安全模型 + +### 部署边界 + +- 对外只暴露 `agent-core` 端口。 +- `agent-executor` 使用独立的 mount / PID / IPC namespace,只 bind 当前会话目录;根文件系统只读,丢弃全部 capability 后仅保留 `SYS_ADMIN`。 +- 命令容器没有独立网络 namespace,所以 executor 会拒绝来自自身容器网卡的 `/exec` 请求,避免 token 泄漏后被借用。 +- `wxbot` 只挂内网;微信登录凭证在 `./wxbot/data`,等同微信账号权限,不要外泄。 +- 配置文件、`.env`、微信凭证、任务目录、SQLite 都属于敏感数据。 + +### 认证与授权 + +- 登录使用 HMAC 签名的 HttpOnly Cookie,支持 `Authorization: Basic` 作为脚本 / curl 的兜底。 +- `auth.users` 留空则完全关闭认证,只适合本机或完全可信网络。 +- 管理员接口:配置读写、用户管理、进程重启。 +- **重要**:系统按单租户设计。除上述管理员接口外,会话、消息、文件、技能等 API 只校验「已登录」,不按用户做资源级授权;按用户的会话列表隔离发生在前端查询层。不要把实例开放给互不信任的用户。 + +### 公网临时链接 + +`mint_public_link` 生成 22 字符随机 ID,链接形如: + +```text +http:///p/ +``` + +- 只由 core 进程内的工具签发,签发前校验文件在任务目录内且 `realpath` 未越界。 +- 默认 30 分钟过期,可配置 1 分钟到 24 小时。 +- 链接可重复使用,直到过期;服务重启后全部失效。 +- 任何人拿到链接即可匿名访问,不要对含密钥的文件签发。 + +### HTTPS + +仓库不内置 TLS 反向代理。直接 `http://IP:端口` 使用时: + +- PWA / Service Worker 不会注册。 +- 复制按钮会回退到旧 API。 +- 登录 Cookie 不带 `Secure` 标志,HTTP 下正常工作。 + +如果前面加 nginx 等反向代理,SSE 必须关闭缓冲: + +```nginx +proxy_http_version 1.1; +proxy_buffering off; +proxy_read_timeout 3600s; +``` + +若设置了 `VIRTUAL_HOST`,公网链接前缀会自动变成 `https://<域名>`;仓库默认 compose 里带有 `VIRTUAL_HOST=agent.ai.foresh.com`,不接反向代理时应删除或改成自己的域名。 + +--- + +## 运维 + +### 数据位置 + +| 宿主机路径 | 容器内 | 内容 | +|---|---|---| +| `./tasks/` | `/workspace/tasks` | 每个会话的工作目录 | +| `./data/` | `/workspace/data` | SQLite `.agent.db`、`prompt.txt` 调试产物 | +| `./skills/` | `/workspace/skills` | 技能与共享依赖 | +| `./config.yml` | `/app/config.yml` | core 配置 | +| `./wxbot/data/` | `/data` | 微信登录凭证 | + +备份至少覆盖 `data/`、`tasks/`、`config.yml`;需要保留微信登录态时再备份 `wxbot/data/`。 + +### 升级 + +```bash +git pull +docker compose up -d --build +``` + +数据库与任务目录都在 bind mount 中,升级不丢数据。进程重启时,执行中的回合会被打断;`active` 会话会归位为保持中,用户再发消息即可继续。 + +### 日志与健康检查 + +```bash +docker compose logs -f agent-core +docker compose logs -f agent-executor +docker compose logs -f wxbot +curl -s http://127.0.0.1:8090/api/health +``` + +- core 日志等级由 `config.yml` 的 `log_level` 控制,改完重启生效。 +- executor / wxbot 的日志等级由各自环境变量控制,`debug` 会打印完整交互。 +- 启动时会在 `data/prompt.txt` 写入实际下发的 system prompt 与各 profile 的工具清单,便于核对。 + +### 常见问题 + +| 现象 | 原因 / 处理 | +|---|---| +| 启动时报 `network agent-mcp-net has active endpoints` | 先停 MCP 栈,再停本栈;重新 `up` 会恢复 | +| `config.yml` 变成目录 | 启动前文件不存在,Docker 自动建了同名目录;停容器、删目录、放入配置文件 | +| 没有可用模型 | `platforms` 为空或模型全部禁用;在设置页添加后重启 | +| 创建会话报「无可用模型」 | 模型池为空,或指定模型所在平台没有 key | +| 技能依赖缺失 | 重新 `docker compose up -d --build agent-executor`;或检查 `skills/deps` | +| 微信设置页显示未连接 | wxbot 未启动,或 `WXBOT_TOKEN` 两侧不一致 | +| 图生视频拉不到参考图 | `public_link.base_url` 未配置,或公网不可达 | + +--- + +## 目录 + +```text +agent/ +├── app/ agent-core:Express + SQLite + 前端静态资源 +├── executor/ agent-executor:隔离命令执行与 Office 预览网关 +├── wxbot/ 微信 iLink 协议调制解调器 +├── skills/ 技能目录 +├── tasks/ 会话工作目录(运行时生成) +├── data/ SQLite 与调试产物(运行时生成) +├── docs/ 架构与专题文档 +├── docker-compose.yml +└── scripts/init.sh +``` + +进一步阅读: + +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md):内部架构、数据模型、关键流程、修改约束。 +- [docs/OFFICE.md](docs/OFFICE.md):Office 文档技能与预览链路。 +- [docs/tool-design.md](docs/tool-design.md):工具接口设计规范。 + +## 开发 + +```bash +cd app +npm install +node server/server.js +``` + +测试与调试细节见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 第 9 节。 diff --git a/app/README.md b/app/README.md index b425126..a54b664 100644 --- a/app/README.md +++ b/app/README.md @@ -1,60 +1,49 @@ -# Agent 任务台(app) +# agent-core -按仓库根目录 `README.md` 设计方案实现的自用通用 Agent 系统。 +`agent` 仓库的 core 服务:Express + SQLite + 静态 H5 前端。 -## 目录结构 - -``` -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/profile-default.txt # System prompt 模板(直接编辑) -│ └── public/ # H5 前端(Vanilla JS + SSE;无构建,index.html + js/ 六模块按序加载) -├── test/ # mock 上游 + 端到端冒烟测试 -├── config.example.yml # core 专属配置模板(部署时生成/复制为仓库根 config.yml 挂进容器) -├── Dockerfile / docker-compose.yml -``` +对外能力、部署与配置见仓库根 [`../README.md`](../README.md);内部结构、数据模型与修改约束见 [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)。 ## 本地运行 ```bash cd app npm install -cp config.example.yml config.yml # platforms 可先留空(启动后在设置页添加);本地跑再把 workspace_root / data_root 改回 ./data/... -npm start # http://localhost:8090 +cp config.example.yml config.yml +# 本地调试时把 workspace_root / data_root 改到仓库内可写目录 +AGENT_CONFIG=./config.yml node server/server.js ``` +默认监听 `8090`。`platforms` 可以留空,启动后到设置页添加模型并重启。 + ## 测试 ```bash -cd app -npm test # 启动 mock 上游 + 真实 server 的端到端冒烟测试(25 项断言) +npm test ``` -## 提示词与工具 schema +端到端冒烟测试会启动 mock 模型上游(`:9999`)和真实 server(`:8099`),测试数据隔离在 `test/tmp`。 -System prompt 完全静态(所有会话共用,利于上游前缀缓存),在 `server/templates/profile-default.txt` 直接编辑;工具定义在 `server/tools/definitions.json`。改完重启服务。 +> 注意:`test/smoke.js` 仍有旧断言——排队已从运行期移除,且 `GET /api/sessions/:id` 不再直接返回 `role=tool` 行(改为按需加载)。当前会在 `[2] 工具调用` 与 `[5] 排队调度` 失败;修改相关路径时先同步测试,不要把它当作全绿基线。 -## 关键行为速查 +其他测试: -- 会话创建即尝试绑定空闲模型;无空闲则进全局队列 FIFO。 -- 每轮 AI 完成(无工具调)或用户终止后释放模型;新消息重新入队。 -- 规划阶段点「开始执行」:追加固定模板消息并切 execution。 -- 终止:置位标志 + kill 进程组 + 中止模型流,不再发新请求。 -- 所有文件路径解析到任务目录内,拒绝越界。 -- MCP 服务在 config.yml 的 `mcp_servers` 配置(可多个,每项 name?/url/headers/enable?/timeout_ms?,enable 默认 true、false 时启动不加载其工具;timeout_ms 为该服务单次工具调用最大等待,默认 60s);启动时发现其工具,追加在内置工具之后与 system prompt 一起发给模型;服务不可用仅启动日志告警,工具名重名时加「服务名__」前缀。 +```bash +node test/remote-exec.test.js # 远端 executor 集成 +node test/trim-smoke.js # 历史裁剪 +node test/dep-check.js # 依赖完整性 +``` -部署见 `../docs/DEPLOY.md`。 +## 关键文件 + +| 文件 | 职责 | +|---|---| +| `server/server.js` | 装配配置、DB、SSE、路由与启动顺序 | +| `server/engine.js` | 会话、模型池、Agent 主循环、压缩、标题、日记收口 | +| `server/llm.js` | 消息组装与上游流式调用 | +| `server/tools/executor.js` | 内置工具与路径沙箱 | +| `server/tools/definitions.json` | 内置工具 schema | +| `server/routes/` | HTTP API | +| `server/public/` | 前端(无构建,按序加载脚本) | + +修改前先读架构文档的「修改时必须遵守的约束」一节。 diff --git a/app/server/db.js b/app/server/db.js index d28f1a6..8523249 100644 --- a/app/server/db.js +++ b/app/server/db.js @@ -1,4 +1,4 @@ -// SQLite 数据层。表结构见 README 第九章;本模块同时提供常用查询。 +// SQLite 数据层。表结构见 docs/ARCHITECTURE.md §4.1;本模块同时提供常用查询。 const Database = require('better-sqlite3'); const path = require('path'); const fs = require('fs'); diff --git a/app/server/routes/channel.js b/app/server/routes/channel.js index 1085505..cd088e0 100644 --- a/app/server/routes/channel.js +++ b/app/server/routes/channel.js @@ -1,5 +1,5 @@ // 文本命令接入端(channel)API:给没有可点击 UI 的端(IM 桥、CLI 等)提供会话内操作的文字入口。 -// 设计(docs/ARCHITECTURE.md §4.1/§7): +// 设计(docs/ARCHITECTURE.md §5.13): // - 命令只在 /api/channel/send 解析,不进普通消息路由——Web 上以斜杠开头的文本照常发给模型。 // 命令是无 UI 端的按钮替代品,不是全局协议(防误伤路径/代码讨论这类合法文本)。 // - 每个 (user, channel) 记一个「当前会话」(channel_sessions 表):接入端没有会话列表 UI, diff --git a/app/server/routes/files.js b/app/server/routes/files.js index dec6cad..43a7742 100644 --- a/app/server/routes/files.js +++ b/app/server/routes/files.js @@ -1,4 +1,4 @@ -// 文件管理 API(README 10.3):上传 / 列表 / 下载 / 删除 +// 文件管理 API(docs/ARCHITECTURE.md §5.15):上传 / 列表 / 下载 / 删除 const express = require('express'); const fs = require('fs'); const path = require('path'); diff --git a/app/server/routes/messages.js b/app/server/routes/messages.js index 44dd129..cc59534 100644 --- a/app/server/routes/messages.js +++ b/app/server/routes/messages.js @@ -1,4 +1,4 @@ -// 消息与交互 API(README 10.2):发消息 / SSE 流 / 开始执行 / 终止 +// 消息与交互 API(docs/ARCHITECTURE.md §5.15):发消息 / SSE 流 / 开始执行 / 终止 const express = require('express'); const engine = require('../engine'); const log = require('../log'); diff --git a/app/server/routes/sessions.js b/app/server/routes/sessions.js index a601de3..d88eabe 100644 --- a/app/server/routes/sessions.js +++ b/app/server/routes/sessions.js @@ -1,4 +1,4 @@ -// 会话管理 API(README 10.1) +// 会话管理 API(docs/ARCHITECTURE.md §5.15) const express = require('express'); const fs = require('fs'); const path = require('path'); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6fc0866..0c67fe0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,776 +1,792 @@ -# Agent 项目架构说明 +# Agent 内部架构说明 -> 本文档是给 AI 助手的代码导览——基于仓库实际代码梳理,不是设计文档(设计层面的内容看 `README.md`)。 -> 当需要修改代码时,先按目录结构定位 → 再按模块职责确认改动是否落在正确文件 → 改前先看相应"扩展点"和"约定"两节。 +> 面向修改本仓库的开发者。对外能力与部署请看 [`../README.md`](../README.md)。 +> +> 本文只记录**代码实际行为**与修改时必须遵守的约束。设计动机写在相关注释里,这里不再重复。 -## 0. 项目一句话 +## 1. 运行时拓扑 -自用通用 Agent 系统:**浏览器(移动端 H5 SPA)→ Core(Node 20 + Express + SQLite)→ LLM 池(OpenAI 兼容上游)**,配合可选的 **`agent-executor` 容器**执行 shell 命令与技能脚本。所有 AI 工具调用都在 Core 内统一分派:文件类工具走 Core 本地 fs,命令与技能走远端 Executor(隔离 Python/ffmpeg/libreoffice 等重工具链)。 - ---- - -## 1. 目录结构 - -``` -agent/ -├── README.md 设计文档(API/数据模型/部署总览) -├── docker-compose.yml 编排:agent-core / agent-executor(+init) / wxbot(微信接入) -├── config.yml 运行时配置(含密钥,已 .gitignore;只给 agent-core 进程读,其他组件禁挂禁读) -├── data/ 默认数据卷(任务目录、SQLite、prompt dump) -├── tasks/ 任务目录挂载点(同 ./data 顶层等价,二选一) -├── skills/ 技能目录(用户维护的 SKILL.md/run.py) -│ -├── app/ ── Core 服务容器 ── -│ ├── Dockerfile node:20-slim,npm install only prod -│ │ ├── package.json 依赖:express / better-sqlite3 / multer / sharp / yaml / minimatch / cron-parser -│ ├── config.example.yml core 专属配置模板(复制/生成为顶层 config.yml) -│ ├── scripts/ -│ │ └── init.sh 部署入口:生成 .env + config.yml → 起 agent/mcp 服务 -│ ├── server/ 后端代码 -│ │ ├── server.js 入口:装配 cfg / db / bus / engine / 路由 -│ │ ├── config.js YAML 配置加载、迁移、读写、校验、脱敏还原 -│ │ ├── log.js 分级日志(debug/info/warn/error/none) -│ │ ├── auth.js 多用户会话认证(HttpOnly cookie + HMAC token) -│ │ ├── db.js SQLite 初始化 + 表结构 + 增量迁移 -│ │ ├── sse.js 按会话分组的 SSE 事件总线 -│ │ ├── engine.js 会话/模型池/Agent 主循环/任务目录(核心调度器) -│ │ ├── scheduler.js 定时任务调度器(30s 轮询到期任务,存档历史后投递;需 engine.init() 后启动) -│ │ ├── llm.js 上游 OpenAI 兼容 /chat/completions 流式调用 + 消息组装 -│ │ ├── mcp.js 极简 MCP 客户端(Streamable HTTP,init→tools/list→tools/call) -│ │ ├── remote-exec.js agent-executor 远端执行客户端(SSE 收流) -│ │ ├── wechat.js 微信接入桥接(wechat_bindings 权威 / 实例控制 / inbox / 总线投递;对端服务见 wxbot/,§5.13) -│ │ ├── balance.js 余额查询适配器(按 platform.type 分发) -│ │ ├── version.js 版本信息(package.json + git 短提交号) -│ │ ├── tools/ -│ │ │ ├── definitions.json 内置工具的 OpenAI function 格式定义(现 14 项,含元工具 lab) -│ │ │ ├── executor.js 工具执行器(文件类 + terminal + skill 委托) -│ │ │ └── skills.js Skill Manager(skill 工具的 list/get/run + 路径预处理) -│ │ ├── download-token.js 下载链接签名(浏览器原生下载用;密钥进程内随机) -│ │ ├── download-send.js 单文件下载响应(Content-Disposition / 缓存策略) -│ │ ├── public-files.js 公网临时文件短 ID 表(mint/resolve + 过期) -│ │ ├── routes/ -│ │ │ ├── sessions.js /api/sessions CRUD + 列表分页 -│ │ │ ├── messages.js /api/sessions/:id/messages + SSE 流 + stop/release -│ │ │ ├── files.js /api/sessions/:id/files 上传/列表/下载/删除 -│ │ │ ├── channel.js /api/channel/send 文本命令接入(IM/CLI 等无 UI 端;当前会话绑定 + /new /list /switch /rename /delete /models /think /stop /compact /clear /status /help) -│ │ │ ├── wechat.js /api/wechat 绑定管理(设置页)+ /wxhook 内网回调(微信接入,见 §5.13) -│ │ │ ├── config.js /api/config 读写(含 api_key/password 脱敏) -│ │ │ ├── platforms.js /api/platforms/balance 余额查询 -│ │ │ ├── skills.js /api/skills 技能文件管理 -│ │ │ ├── public-files.js GET /p/ 公网临时文件取用(匿名) -│ │ │ ├── preview-proxy.js 通用预览反代(注册表驱动:/preview/** → 服务单入口,Referer 兜底;挂 server.js 最末) -│ │ │ └── system.js /api/system/status + /restart 优雅重启 -│ │ ├── templates/ -│ │ │ ├── profile-default.txt system prompt 静态模板(每次请求复用,利于上游前缀缓存) -│ │ │ ├── prompt-compress.txt 上下文压缩提示词(压缩回合末尾追加为 user 消息,历史照常走 messages) -│ │ │ └── prompt-title.txt 会话标题自动生成提示词(回合结束过门槛触发:本轮有工具,或纯聊≥ 3 正题轮且字数达标;空闲扫描自动收口时无条件补题(wrapTitleFallback,跳过现推门槛——差标题也比没标题强);{{language}} 填配置语言) -│ │ └── public/ 前端 H5 SPA(无构建,Vanilla JS 经典脚本多文件 + SSE) -│ │ ├── index.html 主页(HTML+样式;脚本全部在 js/,按序加载共享全局作用域) -│ │ ├── login.html 登录页 -│ │ ├── js/ core / chat / sessions / stream / files / settings 六模块(settings.js 尾部含全局初始化,须最后加载) -│ │ ├── css/style.css -│ │ ├── vendor/marked.min.js -│ │ └── sw.js service worker -│ └── test/ -│ ├── smoke.js 端到端冒烟(mock 上游 + 真 server,68+ 用例) -│ ├── remote-exec.test.js 远端执行集成测试(起真 executor + 调 Core) -│ ├── dep-check.js 依赖完整性 -│ ├── mock-upstream.js 测试用假 LLM 上游 -│ └── config.test.yml 测试配置(隔离 data_root) -│ -├── executor/ ── Executor 服务容器(独立部署)── -│ ├── Dockerfile node:20-slim + 系统/Python 工具链(apt + pip) -│ ├── server.js 零依赖单文件 HTTP 服务(仅 Node 内置 http) -│ └── smoke-test.js Executor 自身冒烟(/health / exec 流式 / 鉴权 / 取消) -│ -├── wxbot/ ── 微信接入容器(根 compose 的 wxbot 服务)── -│ ├── app/Dockerfile node:22-slim + @wechatbot/wechatbot / express / js-yaml / qrcode -│ ├── app/src/server.js iLink 多实例调制解调器:实例管理 + /api/{instances,deliver} + 收信转发 core -│ ├── README.md 部署/接口/零配置接线(WXBOT_TOKEN/CORE_URL 全靠 env 注入) -│ └── data/ iLink 登录凭证(gitignore,绝不入库) -│ -└── docs/ - ├── DEPLOY.md 部署(Docker,IP:端口直连) - ├── v2-develop.md v2 移动端单聊视图开发说明 - └── ARCHITECTURE.md ← 本文件 -``` - ---- - -## 2. 部署 +系统由四个进程角色组成,core 是唯一的业务与状态权威。 ```mermaid -graph LR - Browser((移动端浏览器
WebView/APK)) - Core[agent-core
宿主机 8090] - Exec[agent-executor
:9000 内网] - MCP[MCP 服务
agent-mcp-net] - Zhipu[智谱服务器] - LLM[LLM 池
OpenAI 兼容] - Tasks[./tasks
任务目录 bind mount] - Skills[./skills
技能目录 bind mount] - DB[(SQLite
.agent.db)] - - Browser -->|HTTP + Cookie| Core - Core -->|SSE /exec| Exec - Core -->|POST /chat/completions| LLM - Core -->|tools/call| MCP - MCP -->|提交任务| Zhipu - Zhipu -->|匿名 GET /p/id| Core - Core <-->|读写| Tasks - Exec <-->|读写| Tasks - Core <-->|技能| Skills - Exec <-->|技能 + deps| Skills - Core --> DB +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, 只读")] ``` -所有容器都在同一个 `agent-mcp-net` 上(core 与 executor 同时靠它访问 MCP);外网只暴露 Core -(宿主机端口映射)。注意其中一条**反向**的入站链路:外部服务(如智谱)来拉文件时,走的是 Core 的 -`GET /p/`(匿名,22 字符随机 ID + 服务端过期,见 `routes/public-files.js`);这个 id 由内置工具 -`mint_public_link` 在 core 进程内现签(AI 只传文件名,不走任何 HTTP),所以链接里既没有会话名也没有文件名。 +| 角色 | 代码 | 持有 | 不持有 | +|---|---|---|---| +| 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 交互 | -**关键约束**(改 compose 时务必保持): +信任边界: -- 全部容器同一个网络 `agent-mcp-net`(由本仓库 compose 创建,mcp 侧 external 加入)——core 与 executor 都靠它按容器名访问 MCP 服务。 -- `agent-core` 与 `agent-executor` 须把**同一份宿主机 `./tasks`、`./skills`**挂到相同的容器路径(默认 `/workspace/tasks`、`/workspace/skills`)。这是文件工具在 Core 本地直接读、命令在远端写,二者能"看到"彼此产物的根本约定。 -- **两条公网文件路径分工别搞混**:浏览器原生下载走 `download-token.js` 的签名链接(前端用 `download-token` 接口换 URL,`auth.js` 的 `isSignedDownload` 放行 `?t=`);外部服务取文件走 `GET /p/` 短 ID。前者需要在 URL 末段带文件名(给安卓下载器猜名),后者刻意不带文件名/会话名。 -- `GET /p/` 是 Core 上唯一的匿名入口(只有读、必须挂在 `auth.middleware` 之前,未命中/过期一律 404):安全性 = 22 字符随机 ID + 服务端过期(`public-files.js` 的内存表)。**唯一的签发入口是内置工具 `mint_public_link`**(在 core 进程内,与 Core 同属一个信任边界,不再额外监听端口),它自己做路径校验(`resolveInTask` 沙箱 + 会话表 + realpath 复核,挡 `ln -s` 外泄);未配 `public_link.base_url`(且容器 env 没给 `VIRTUAL_HOST`)时工具直接报错:配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS)时,前缀自动用 `https://<第一个域名>`,env 优先于 config.yml。 -- nginx-proxy 前置时**必须 `proxy_buffering off`**,否则 SSE 流被缓冲。详见 `docs/DEPLOY.md`。 -- Core 通过环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN` 注入 executor 端点(也可用 `config.yml` 的 `executor` 段覆盖)。**token 从 `.env` 读取**(compose 变量替换 `${EXECUTOR_TOKEN:?...}`,未设置直接报错,杜绝静默无鉴权);`.env` 已 gitignore,模板见 `.env.example`,生成:`openssl rand -hex 32`。 -- Executor **拒绝来自容器自身(回环/本机网卡)的 `/exec`**:隔离只 unshare mount+pid,命令与 executor 同 net ns,能打到 `127.0.0.1:9000`;据此即使 token 泄漏也无法在会话内调用 `/exec` 越权读他人会话(core 在另一容器,不受影响)。本机集成测试用 `EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 放行,生产不得设置。 -- Executor 镜像分两阶段(`executor/Dockerfile`):`base` = M(长期不变,仅系统工具 + 预烘 Python 包),`skills` = M' = M + 技能“系统层”依赖。compose 用 `build.target: skills`、上下文为仓库根(`.dockerignore` 只放行 `executor/`、`skills/`)。管理员增删/改动 skills 后 `docker compose build agent-executor` 重建 M',M 不动。 -- `agent-executor-init` 在 executor 启动前一次性执行(`executor/init-skills.js`):逐行离线探测各技能 `requirements.txt`,只把镜像缺的包 `pip --target` 装进共享 `deps/`,并执行 `install.sh` 生成技能资产,全部落到宿主 `./skills`,跑完即退出;只挂 `./skills`(不挂 `./tasks`,看不到会话数据)、无特权、`read_only`(系统层写不进去,只能写挂载卷)。executor `depends_on` 其 `service_completed_successfully`。 -- Executor 在 compose 里加了 cgroup/ulimit 护栏(`cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G`)——详见 `executor/server.js` 头注释。 +- 浏览器只与 core 通信;executor、wxbot、MCP 不暴露宿主机端口。 +- `GET /p/` 是唯一匿名业务端点,安全性完全依赖 22 字符随机 ID 与服务端过期表。 +- executor 只拿到共享服务 token,即使被攻破也拿不到模型 Key 或登录密钥。 +- MCP 服务是外部依赖,配置里的 `headers` 会随 `tools/call` 发送,按不可信服务对待。 --- -## 3. 启动流程 +## 2. 代码地图 -`app/server/server.js` 顺序: +```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 前端(无构建,经典脚本按序加载) -1. `loadConfig(AGENT_CONFIG)` 读 `config.yml`,跑完整校验与归一化(`config.js` › `parseAndValidate`)。 -2. `log.setLevel(cfg.log_level)` 注入全局日志等级。 -3. `initDb(cfg.db_path)` 建表 + 增量迁移(`db.js`,含 `held_at` / `last_model_id` / `assistant_type` / `user` / `profile` 等历史升级)。 -4. `createBus()` 建 SSE 事件总线(`sse.js`)。 -5. `engine.setModelPool(cfg, db, bus); engine.init()`:按 cfg.models 重建 `model_pool` 槽位表;会话状态归位(active/遗留 queued → held,绑定不清);指向已删/禁用模型的绑定在下次发言时由 `ensureBinding` 自动改选。 -6. `scheduler.start(engine)`:启动定时任务轮询(30s 一次,`unref`)。**必须在 engine.init() 之后**——先让会话状态归位,首轮 tick 才看不到脏状态(见 §5.12)。随后 `wechat.init(cfg, db, bus)` 挂上总线内部订阅(微信接入,§5.13;env WXBOT_URL/WXBOT_TOKEN 未就位时全程静默)。 -7. `createAuth(cfg)` 装配登录中间件;未配 `auth.users` 则认证关闭(可交给前置 nginx-proxy basic auth)。 -8. `express.static(public)` + 路由挂载(`/api/sessions`、`/api/skills`、`/api/config`、`/api/platforms`、`/api/system`、`/api/channel`、`/api/wechat`);全部业务路由之后由 `routes/preview-proxy.js` 的 mount(app) 追加通用预览反代(含根绝对路径 Referer 兜底);`auth.middleware` 之前另挂两个内网/匿名入口:`/p`(公网临时文件)与 `/wxhook`(wxbot 回调,共享服务 token 把门)。 -9. `mcp.init(cfg).then(...)`:对每个 MCP 服务 initialize → tools/list,发现的工具存在 `mcp` 模块内。 -10. `skills.listSkills(...)` → `llm.setSkillListText(...)` 快照注入 system prompt(`llm.js`)。 -11. `server.listen(PORT)`,打 startup 行:workspace_root / data_root / models / mcp_servers / auth / log_level。 -12. `dumpPromptBundle()` 把"system prompt + tools 列表 + 示例会话上下文"写进 `data_root/prompt.txt`(仅供人核对,失败不阻塞)。 +executor/ 独立的命令执行与 Office 预览服务 +wxbot/app/src/server.js 微信 iLink 调制解调器 +skills/ 技能目录;deps/ 为共享 Python 依赖 +``` -> ⚠️ 配置是**冷加载**:改 `config.yml` 需重启生效,**没有热重载**。设置页修改后必须调 `POST /api/system/restart`(路由层 409 防有活跃回合的强杀,`force=true` 可打断)。 +仓库根 `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 表(`db.js`) +### 4.1 SQLite -``` -sessions id (PK='task-YYYYMMDD-NNN') / title / status / - model_id / last_model_id / assistant_type / user / profile / - created_at / updated_at / completed_at / cancelled_at / held_at +数据库默认 `data_root/.agent.db`,WAL 模式,`foreign_keys=ON`。使用 `better-sqlite3` 同步 API。 -messages id PK / session_id FK / role (system|user|assistant|tool) / - content (TEXT, 含 __blocks__ 哨兵 JSON 多模态) / reasoning / - tool_calls (JSON) / tool_call_id / name / type / - is_error / created_at - # type 取值: summary / archived / errAck / - # session_context (name 列 = SESSION_CONTEXT_NAME) / - # scheduler_note(定时任务删除通知)/ channel_note(微信渠道上下文说明,每微信会话一条)/ - # wx_media(微信单发媒体留痕行,落盘不触发回合,同 scheduler_note 语义; - # 未知 type 一律按普通 user 消息发模型、UI 照常展示) - # 旧版遗留(只读兼容,不再生成): summarize_request(压缩指令 user 消息,已废弃,仅 buildMessages 兼容旧库)/ - # task_brief(已废弃 advising 阶段切换时代的任务书快照行,标题白名单保留读兼容) +| 表 | 作用 | 关键字段 / 约束 | +|---|---|---| +| `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` | 旧版排队表 | 已废弃,代码不读写 | -files id PK / session_id / filename / size / created_at - # 仅记录元数据;文件本体在 workspace 目录里 - -model_pool id (PK='平台#key下标') / display_name / last_used_at / is_busy / current_session_id - # 启动时 syncModelPool 按 cfg.models 重建;key 为共享资源不再独占(多会话可并发绑同一 key), - # 调度只按「最不 active」优先级选 key(engine.chooseKey);is_busy/current_session_id 为旧版独占残留列,不再读写 - -wait_queue (已废弃)旧版 FIFO 排队表;排队语义整体移除(不再等模型),表保留不再读写 - -meta key PK / value - # 杂项:如 task_seq:YYYYMMDD(每日任务序号,删除会话不回退) - -model_usage id PK / session_id / model_id / - prompt_tokens / completion_tokens / total_tokens / created_at - # 故意不建会话外键,删会话后累计统计仍保留 - -scheduled_tasks session_id PK (FK sessions, ON DELETE CASCADE) / cron_expr / - prompt / next_run_at / last_run_at / last_status (ok|error|skipped|running) / - last_note (给人看的中文说明,UI 原样展示) / created_at - # 定时任务:每会话至多一个(session_id 主键兼防重),按 next_run_at 索引; - # 创建只经 AI 工具 schedule;频次/提示词可在会话详情弹窗改(PATCH /:id/schedule, - # 改频次后端重校验并重算 next_run_at);删除走 CASCADE 或 DELETE /:id/schedule(见 §5.12) - -channel_sessions user + channel 复合 PK / session_id / updated_at - # 文本命令接入端(routes/channel.js)的「当前会话」映射:接入端无会话列表 UI, - # 普通消息与 /new 等命令都路由到绑定的会话;无外键,删会话后懒解析自愈; - # /api/channel/send 是唯一读写方,Web 路由不碰这张表 - -wechat_bindings id PK(wx+10hex)/ user / status (pending|online|expired|error) / note / - bot_account_id / wx_to_user / last_msg_id / deep_think(默认 0=关)/ created_at / updated_at - # 微信绑定权威表(§5.13):一条 core 用户 ↔ 一个 wxbot iLink bot 实例(一人一绑,换号先解绑); - # id 兼作 channel 键(channel='wx:'+id,复用 channel_sessions 全套机制)与 wxbot 凭证目录名; - # last_msg_id 是投递游标(assistant 消息 id ≤ 此值已送微信),落库防 core 重启重发 -``` - -**session.status 状态机**(`engine.js`,无排队版): - -```mermaid -stateDiagram-v2 - [*] --> held: createSession(创建即绑模型,空池报错) - held --> active: postUserMessage(沿用绑定立即开跑) - completed --> active: postUserMessage(绑定仍在,继续用原模型) - cancelled --> active: postUserMessage(同上) - active --> held: finalize(正常结束,绑定保持) - active --> cancelled: stop(用户终止,绑定保持) - held --> completed: releaseHold(手动「断开」,纯状态动作) - held --> active: bindToSession(换绑且有未回应消息) - completed --> held: bindToSession(手动选模) - cancelled --> held: bindToSession -``` - -要点:key 非独占、无排队、无保持租约——`held` 只表示「回合已收尾,绑定持续展示」,不会自动到期; -会话永远粘着自己的 model_slot(跨重启/结版/终止保持),换绑只有两条路:用户手动「选择模型」, -或绑定失效(配置删模型/禁用/改名)后由 `ensureBinding` 自动改选(优先留原平台)。 +迁移策略:`CREATE TABLE IF NOT EXISTS` + `PRAGMA table_info` 后按需 `ALTER TABLE`。新增列必须写成幂等迁移,不能假设新库。 ### 4.2 文件布局 -**任务目录**(`cfg.workspace_root//`):每个会话一个目录;Core 与 Executor 都可读写;sh 命令默认 cwd 即此目录。(旧 advising 时代的 `task.md`/`.task-history/` 特殊语义已随顾问模式一并移除,存量目录里若还有只是普通文件。) +```text +// 会话工作目录 +├── .tmp/ 会话级 /tmp,跨 terminal 调用保留 +├── .imgcache/ read_file 图片压缩产物 +├── .app/ data-page 技能页面,按 /app// 暴露 +├── data.db db 工具与 /api/db//query +└── ... 用户上传与 AI 生成文件 +/.agent.db SQLite +/prompt.txt 启动时实际下发的 prompt/tools dump +// 技能;deps/ 为共享依赖 +``` -**技能目录**(`cfg.skills_root//`):所有会话共享;`deps/` 子目录是 pip `--target` 共享的 Python 依赖(只放镜像缺失的包,镜像已带的不重复装),**与技能目录同级**(不是技能子目录)。`RESERVED_DIRS = {deps}` 在 `routes/skills.js` 里被排除以免被当成技能。 +### 4.3 会话状态 -**版本与提交号**:git short hash 来自 `version.json`(post-commit 钩子自动写)→ 容器通过 bind mount 读到;无 `version.json` 时回退 `git rev-parse`;都没有则只显示 package.json 版本。 +```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. 核心模块 -### 5.1 `engine.js` —— 调度与主循环(**最复杂的一个文件**) +### 5.1 `engine.js` -| 函数 | 角色 | -|---|---| -| `syncModelPool` | 启动时把 cfg.models 写入 `model_pool` 表,删配置中已消失的;会话状态归位(active/遗留 queued→held,绑定不清) | -| `applyBinding` / `bindingValid` / `ensureBinding` | 会话粘住 key+模型(model_slot/model_id/last_model_id + 刷新槽位 last_used_at);绑定失效(配置删模型/禁用/改名)时按优先级自动改选,优先留原平台;空池抛 503 | -| `chooseKey` / `chooseModel` | 优先级选 key(**无排队、无独占**):looping 回合数少 → 在用(active/held)会话数少 → 最久未用(轮转摊平)→ id;具体模型在同平台内选(偏好旧模型 > 绑得最少的) | -| `getRun` / `killRunProcs` | 每会话的运行控制(`cancelled` / `procs` / `abortController` / `looping`) | -| `runLoop` / `runLoopInner` | Agent 主循环:解析 profile → buildMessages → callModel → 解包 tool args → 校验 → saveMessage → executeTool → saveMessage(tool) → SSE 广播。每迭代现解 profile(`resolveProfileName`:模型配置 > 默认全量),prompt 与 tools 集(`effectiveTools` 按 `tools_allow`/`tools_deny` 过滤)跟着组合切换 | -| `streamAssistant` | 单次上游调用:拿 abortSignal / shouldCancel / 各类回调,把流式 chunk 转 SSE 事件(`assistant_delta` / `reasoning_delta`) | -| `createSession` | 生成 id(`task-YYYYMMDD-NNN`,序号从历史 + `meta.task_seq` 取大)→ mkdir 任务目录 → **创建即绑模型落 held**(指定模型优先其平台,无效退回全局;空池直接报错不建吊着会话) | -| `postUserMessage` | 用户消息入口;除 looping(下一迭代自动带上新消息)外任意状态都是「保绑定→转 active→立即开跑」,`delivered` 恒 `'live'` | -| `bindToSession` / `releaseHold` | 手动换绑(任意模型即点即换,仅输出中拒绝,无「占用」概念);「断开」= held→completed 纯状态动作(无资源可释放,绑定仍在可继续用) | -| `summarizeContext` / `clearSessionMessages` / `deleteMessage` | 收尾 + 上下文压缩(清空连带清空会话 .tmp 即执行容器里的 /tmp) | -| `checkToolArgs` / `unwrapToolArgs` | 工具参数校验 + 部分弱模型参数包裹外层自动解包 | -| `ensureSessionContext` | 注入/刷新"会话上下文"首条 user 消息(日期/任务目录/模型名/vision 能力) | +职责:会话生命周期、模型池调度、Agent 主循环、工具执行编排、压缩、标题、日记收口。 -**关键约定**: +**模型池** -- `run.cancelled = true` 是停止的最终信号;远端子进程通过 `run.procs` 注册(local spawn 用 child、remote-exec 用 `remoteKill` 句柄),`killRunProcs` 按类型分别处理。 -- `lastIncludedId` 跟踪本轮已纳入模型请求的最新消息 id;流式期间到达的新 user 消息靠它在下一轮迭代时自动带上。 -- **errAck 机制**:工具参数结构性错误(JSON 非法/缺必填)→ 整条 assistant 标 `type='errAck'`,关联 tool 回执一并丢弃,发请求时由 user 错误提示替代(`llm.buildMessages`)—— 防止模型模仿自己的坏样本死循环。 -- **archived/summary 机制**(上下文压缩):`type='archived'` 的消息 UI 照常展示但不再发模型;`type='summary'` 是压缩后的"上下文起点"。压缩回合**不插入任何指令消息**:由 `engine.summarizeContext` 在内存 run 上标 `summarizing`,`runLoopInner` 据此走 `llm.compressMessages`:沿用默认 system prompt + 正常历史 messages,末尾追加一条 user(`server/templates/prompt-compress.txt` 原文,参考标题回合的拼法),且不传 tools;回合内首条无 tool_calls 的收尾回复即摘要。(`llm.buildMessages` 仍保留旧库 `summarize_request` 行的处理,仅为历史数据兼容。) -- **图片(多模态)**:`messages.content` 列是 TEXT,含图时存 `{"__blocks__":[content...]}` 哨兵 JSON。新版 `read_file` 读图:sharp 压缩产物落任务目录 `.imgcache/`(前端文件列表隐带点的项),库里只存 `image_ref` 轻量块;`buildMessages` 发送前经调用方传入的 `mintUrl` 回调现签成公网外链(同 `mint_public_link` 那套 `GET /p/`)成 `image_url` 块,base64 不进 DB 也不进请求体;签不到降级为文字占位。**图不塞在 tool 回执里发**(tool 角色带 `image_url` 是非标准形态,大量 OpenAI 兼容上游整批忽略或只认批次最后一张,模型看不到图会反复 read_file 补看成死循环):回执降级为纯文本,未消费的图统一并入该批之后的一条 `user` 消息(逐图对应说明合并置顶为一段文字、图块按回执顺序紧随——对齐官方示例排布;探针实测 DS 对交替排布也兼容,取低风险形态),并附「先逐张简述每图内容再继续任务」指令兼作送达自检;旧库/用户粘贴附件的 `data:` URL 块原样透传。图块**保留到最后一条收尾 assistant(无 tool_calls)之前**(`lastAssistant` 判定)——只发 tool_calls 的中间轮不算已阅、图继续携带(实测过图已进上下文而模型仍自述没看到的行为,鲁棒优先于极致省 token);更早的换成"已省略"文字描述(措辞不催促重读);同回合同一图只投递一次(`run.imgDelivered` 去重,再读同图只回文字提示;多图同请求经探针实测可行,曾按批限"每轮一张"已撤);发送前 `log.debug('req', 发送形态...)` 打每轮图块计数,一眼区分发送侧漏拼与上游吞图。UI 渲染走带 cookie 的会话内下载路由,历史永不裂图。 -- **key 共享并发,无租约**:`model_pool.is_busy`/`current_session_id` 已废弃不再读写(旧库残留列,启动时清零);同一 key 可被多个会话同时绑定并发 looping(上游 key 本身支持多并发)。held 不再自动到期,顶部「保持中 · 模型」持续展示,唯一出口是手动「断开」或换绑。 -- **profile(prompt+tools 组合)**:顶层 `model_profiles` 定义多套组合,`platforms[].models[].profile` 引用(见 §5.8)——这是唯一的引用来源:运行期手动切换已全部移除(消息级 profile 参数、`sessions.profile` 会话绑定均废弃,列保留不读写);未配 profile = 默认全量组合(profile-default.txt)。名单外工具被调用不拦(`checkToolArgs` 查不到 def 不报错,`executeTool` 全表照跑);tools schema 只活在请求体不进历史,所以切换不脏化旧消息。压缩回合同样跟随(小模型会话点压缩不会回退到默认大模板)。 +- `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` 是旧独占模型残留列,运行期不读写。 -### 5.2 `llm.js` —— 上游调用 +**模型 profile** -| 函数 | 角色 | -|---|---| -| `systemPromptText(language, profile?)` | 按 profile 名选 prompt 源(缺省 = 默认模板);`{APP_SKILLS}` 占位符就地替换为技能清单(自定义文件没放占位符 = 无技能段;默认模板没放时兑底尾拼),末尾统一拼语言指令;拼接结果按 (profile, 语言) 缓存(`_promptTextCache` Map) | -| `setSkillListText(text)` | 技能列表变更后清缓存,强制重拼 | -| `setProfilePrompts(map)` | profile 自定义 prompt 注册表(name→全文,文本已随配置加载读入);engine.init 调一次,运行期选取零 IO | -| `buildMessages(session, lang, mintUrl?)` | DB 行 → OpenAI messages 数组;处理 summary/archived/errAck/图片消费;`image_ref` 块用 `mintUrl` 现签成公网 `image_url` 外链;assistant 行存库 reasoning 挂内部键 `__reasoning` 下传(callModel 消费后必剥) | -| `forEachSSEData(res, onEvent, onMeta, onBadData)` | 通用 SSE 帧解析(空行分隔,data: 行 JSON.parse,注释行走 onMeta) | -| `callModel(cfg, modelId, messages, tools, opts)` | 一次模型调用;`opts.deepThink` 启用时合并 `thinking_params`;返回 `{content, reasoning, tool_calls, finish_reason, usage, aborted, sseFrames}` | +`resolveProfileName(session)` 只取 `cfg.models[].profile`。会话级 profile 切换已移除;`sessions.profile` 列不再使用。 -**关键点**: +**工具集** -- 模型内部唯一键 = `平台名/模型id`(`model_id` 列),发上游用原始 `mid`。 -- `extra_params` 与 `thinking_params` 通过 `deepMergeInto` 合入 body;`thinking_params` 覆盖 `extra_params` 同名键。 -- `reasoning` 字段兼容 `reasoning` 与 `reasoning_content`(各家上游不一致),只走一个;接收解析与回传配置解耦。 -- 思维链回传:模型配了 `reasoning_ack_field`(如 `reasoning_content`,DeepSeek 系要求历史轮把思考链喂回)时,callModel 发请求前把 assistant 行的 `__reasoning` 按该字段名写回;纯配置闸门不看 tools,对话/压缩/标题回合同规则;未配 = 不回传(只剥内部键,零变化)。回传字节恒定,不破坏前缀缓存;代价是 prompt token 变多,逐模型 opt-in。 -- 上游错误帧(`choices=[]` 且 `usage` 也无)通过 `onBadEvent` 落 warn 日志,不再静默。 +`effectiveTools(profileName)` 的过滤顺序: -### 5.3 `mcp.js` —— 极简 MCP 客户端 +1. 内置定义 + MCP 工具; +2. 若 profile 配了 `tools_allow`,先按白名单过滤;未配 = 全量;`[]` = 零工具; +3. 再按 `tools_deny` 过滤;profile 未配时继承全局 `tools_deny`,`deny` 优先。 -- 协议:Streamable HTTP(JSON-RPC over HTTP,响应可能 SSE 包裹)。 -- 启动 `init(cfg)` 对每个服务 initialize → notifications/initialized → tools/list;单个服务失败只 warn,不影响其他。 -- **工具名单过滤**:服务配 `tools_allow`(白名单)/ `tools_deny`(黑名单,allow 之后叠加生效)时,在 tools/list 后按服务端**原始工具名**过滤(重命名之前);两者都在 `config.js` 归一化(非数组/空数组视作未配)。过滤后剩 0 个会 warn(多半是名字写错)。 -- 工具名冲突时重命名:`内置名` 或 `其他MCP名` 已占 → 加 `服务名__` 前缀(`toolIndex` 索引走重命名后的名,调用时按索引还原成原始名调 `tools/call`)。 -- session 补偿:MCP 规范的 `Mcp-Session-Id` 缓存在 `server.sessionId`;过期(400 + 含 "session" 字样)自动重 initialize 后重试一次。 -- 某些老服务无 `initialize` → catch `Method not found` 不阻断。 +默认全局 `tools_deny: [lab]`;`lab` profile 必须显式写 `tools_deny: []`,否则 `lab` 自己也会被屏蔽。名单只影响模型「看得到什么」,名单外但真实存在的工具被调用时仍会执行。 -### 5.4 `tools/executor.js` —— 内置工具(现 14 项,含元工具 `lab`)的派发器 +**主循环** -`HANDLERS` 是 `name → async(ctx, args) → result` 的表;`executeTool(ctx, name, args)` 按 `name` 派发;**未知名直接转发给 MCP**(若 `mcp.hasTool(name)`,调 `mcp.callTool`)。 +`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 /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` 重写为 `/.tmp`,与 executor 容器内 `/tmp` 的 bind 对齐; +- 越界抛错。 + +`@/` 由 `resolvePastPath` 解析: + +- 会话必须存在; +- 必须与当前会话同一 `user`; +- 只允许 `list_directory`、`read_file`、`copy_path` 的源路径; +- `write_file`、`edit_file`、`copy_path` 目标一律拒绝 `@`。 + +**内置工具** | 工具 | 实现要点 | |---|---| -| `read_file` | 走 `resolveInTask` 防路径穿越;图像(PNG/JPEG/WebP/GIF/BMP/TIFF)按 vision 能力走 `sharp` 压缩后落盘 `.imgcache/` 并回传 `image_rel`(长边 ≤ 2000px,JPEG q=80;文件名带源文件 mtime+size 指纹,重读复用不增殖;重编码无收益时不落盘、直指原文件),发送前由 `llm.buildMessages` 现签成公网外链(engine 侧 mint 前 realpath 复核);大文本/二进制给 outline,超 32MB 拒读并引导 terminal;`path` 可 `@/` 只读窥看同用户历史会话的文本(校验单点 `resolvePastPath`,与 list_directory/copy_path 同源)——字节不落本会话,terminal/edit_file 看不见它,历史图片直接拒绝并引导 copy_path(图片进模型视野必须经本会话签外链,藏进 .imgcache 等于偷偷导入);行号前缀格式 "`<6位右对齐行号>\\t<原文>`"(`edit_file` 用) | -| `write_file` / `edit_file` | `edit_file` 用模糊定位(Zed 风格):先精确匹配,失败后用 Levenshtein DP 找最相似行;超 32MB 拒绝整文件读写(OOM 防护);DP 候选区间不连续(中间跳过无关 buffer 行)即弃用,防静默吞行;空 `new_text` = 整行干净删除(精确/模糊两层统一,对齐 `"".lines()` 零行语义);`old_text`/`new_text` 协议见 `definitions.json` | -| 已移除的工具(部分复活) | `list_directory` / `copy_path` 于 2026-09 复活并加 `@/` 只读记号:当年删除理由是「环境固定,统一走 terminal」,但生产 terminal 在远端 executor 容器(compose:wrapper 启动即 unmount host-tasks),其他会话目录在 shell 物理视图里不存在——跨会话取旧成果只剩 core 进程一个口子。校验单点 `resolvePastPath`(形状+存在+同用户,承自 recall 旧 files/link);list_directory 单层 ls(≤200 条、隐藏项不列,@ 模式条目带 '@/' 全形前缀可直接抄进 copy_path);copy_path 源可 @、目标拒 @(历史只读,导入落本会话后 read_file/vision/mint 全量生效),预算 200 文件/200MB,符号链接拒收防逃逸(mint 同款防线);2026-10 给 read_file 开了只读窥看特例:跨墙不变量从「数据过墙只走 copy_path 一道门」放宽为「查看可过墙(list/read 文本),字节落地仍只走 copy_path」,写侧 write_file/edit_file 显式拒 @(否则 resolveInTask 会把 @ 当相对路径、在本会话造出字面 @ 目录)。同批拆除 recall 的 files/link 两 op(沙箱外克隆必漂移:link 漏抄 mint 的 realpath 防线),recall 收敛为纯记忆 search/days/day。仍移除:`create_directory` / `delete_path` / `move_path` / `find_path` / `grep`(写删检索继续走 terminal);17→10 大盘不变,复活两件+后续 db/profile → 2026-10 随顾问模式(advising)拆除 handoff → 现 14 项 | -| `terminal` | **唯一一个走 executor 的内置工具**(当 `rexec.isRemote(cfg)`);本地分支用 `spawn` + `detached` + 进程组 kill;远端分支 `rexec.run` SSE 收流,结果套上超时/截断/取消注解后 `truncate(text, cfg.terminal.max_output_chars)` 返回 | -| `fetch` | `AbortController` 覆盖全生命周期(响应头之后的 body 读流同样被超时/取消打断,取消用与 terminal 同款的 200ms 轮询);content-type 先行,非文本只回状态/类型/尺寸不读 body;**下载/返回双上限解耦**:流式读到 `cfg.fetch.max_bytes`(默认 1MB)即断开(下载不占上下文可宽松),返回窗默认 `max_chars`(12000)字符,模型显式传 `max_chars` 夹在 `max_chars_hard`(64000)硬帽内;超窗尾部拼 `offset` 续读提示,转换后全文缓在 `ctx.run.fetchCache`(回合级 LRU 3 条),续读纯本地切片不重抓;**SSRF 防护**:主机名解析结果含回环/私有/链路本地地址即拒(`allow_private: true` 才放行),`redirect:'manual'` 逐跳复查至多 5 次(残余风险:undici 建连时二次解析,DNS 重绑定不可根治);按响应 charset 解码(full-icu 支持 gbk/gb18030 等,未知编码退回 UTF-8);HTML 用 `htmlToMarkdown` 转(剥 script/style/head 及 nav/header/footer/aside/form 整块,class/id 样板词启发式丢块,`` 提成首行);HTML 实体单遍解码(常见命名实体+数字实体通吃,修 `&` 双重解码);字节截断切在多字节字符中时尾 U+FFFD 去噪;网络错误解包 `err.cause` 直述 ENOTFOUND/TLS 等真因,SSRF/重定向类错误带 `fetchUserError` 标记直接冒泡;engine 不截工具结果,返回值末尾另有 `truncate` 1MB 字符兜底护栏 | -| `mint_public_link` | **唯一的 mint 入口**:与 core 同进程,直接 `publicFiles.mint()`,不绕任何 HTTP;`ctx.taskDir` 就是会话目录,`relOf` 的结果正是取用侧要的 `rel`。校验:`public_link.base_url` 已配 + `resolveInTask` 沙箱 + 确认是文件 + `realpath` 未沿符号链接跳出任务目录;返回单行 URL | -| `skill` | op 分派 list/get/run(三件套合并:同一 `name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错;front matter 带 `visit_url` 的技能在 op=run 成功后由 executor 层拼 `public_link.base_url`(与 mint 同源)追加完整「访问地址」行(技能进程不知公网前缀,AI 拿相对路径会原样转给用户) | -| `schedule` | **当前会话**(`ctx.sessionId`,AI 不可指定他会话)定时任务的完整生命周期:op 分派 get/create/update/delete(表主键 session_id → 每会话至多一条,无 id 参数);条件必填在代码里校验、错误回显 op 与缺失字段;数据层在 `scheduler.js`(cron 可解析 → 间隔 ≥1h → prompt ≤20000 → 查重/存在性检查),delete 不落 scheduler_note;描述里限定「仅用户明确要求时调用」(安全缓解,见 §5.12) | -| `profile` | 用户画像增量维护(op 分派:list / set(honorific\|industry 单值≤20字,空串清除) / add / remove(preference 顿号标签));user 取自会话行,AI 不可指定他人;护栏单标≤15字×≤24个×总≤300字,整批原子(任一超限不落库);停用(enabled=0)拒写不拒读;写入自新会话生效(快照冻结语义不变),list 永远给 live 状态——取代了早期的画像一次性提取链路 | -| `lab` | 元工具统一入口:`tool` + 自由 `args` 转发内置 + MCP 全部能力(目标 schema 定义期不可知,条件校验归内层 handler);`help` 伪工具做现场发现(无参列名单、带 `args.tool` 出完整 schema),未知名回显全清单,禁嵌套、内层错误冒泡不包装。默认被全局 `tools_deny: ['lab']` 屏蔽,仅 `lab` profile(allow `[lab]` + deny `[]` 清空)下发,见 §5.8 | +| `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` | -`resolveInTask(taskDir, relOrAbs)`:把相对路径或绝对路径解析为绝对路径并校验落在 `taskDir` 之内(含根),防穿越。 +**派发** -### 5.5 `tools/skills.js` —— Skill Manager +`executeTool` 先查 `HANDLERS`,未命中再查 `mcp.hasTool`。工具返回字符串;`read_file` 读图可返回 `{text, image_rel}`。未知工具返回 `Error: 未知工具 <name>`。 -- 技能 = 单层子目录,含 `SKILL.md`(YAML front matter 可选,含 `description` / `input_schema` / `visit_url`,后者的完整链接由 executor 层在 op=run 后拼接,见 §5.4)+ `run.py` 或 `run.sh` 入口(接收 JSON 字符串作为唯一 argv)。 -- 依赖不由 core 安装(core 只发现与执行):系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M'(需重建镜像);pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 一次性落到宿主 `./skills`。 - - init 的 pip 步骤先离线探测(`pip install --no-index --dry-run <逐行>`,不联网):镜像已带的包直接跳过,只把缺的装进 `deps/`;`.deps_installed` marker(requirements/install.sh 两份 hash)也在那里维护。 - - 外挂层可见性:`skills/deps` 由 compose 放进 executor 容器 env 的 `PYTHONPATH`(`server.js` 白名单同步放行),技能入口与 AI 终端命令都能 import;运行期 skills 与 deps 均 `:ro`,**加包只需改 `requirements.txt` 后 `docker compose up -d`(重跑 init),不需重建镜像**。 -- `runSkill` 流程:`input_args` 类型守卫(非对象早拒,免得在 Object.entries 里静默错位) → `skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`,缺项报错点名字段) → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。 -- system prompt 注入(`formatSkillListForPrompt`)按 `- 名字: 描述` 每行一个(listSkills 已按名字排序,行序恒定不破坏前缀缓存;描述压单行);参数查 op=get、执行 op=run(`skill` 工具),op 间依赖写进工具 description。 -- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。 -- **cwd 分两类**:`skill` op=run 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。 +### 5.4 `tools/skills.js` -### 5.6 `remote-exec.js` —— 远端 executor 客户端 +- 技能根目录:`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 中只读,不允许运行期写回。 -`run(cfg, opts)` 流程: -1. 校验 `cfg.executor.url`(即 `isRemote`)。 -2. `fetch POST /exec`(body = `{command, cwd, timeout_ms, env}`),得到 SSE 流。 -3. 用 `for await` + 手工 `\n\n` 切帧;遇到 `[DONE]` 或 `type:'exit'` 帧 break。 -4. SSE 内只发 `out`/`err` 的 chunk;`out` 累积到字符串。 -5. `opts.run` 可选传入,句柄挂到 `run.procs`;200ms 轮询 `run.cancelled` 触发 `remoteKill`(`DELETE /exec/:id` + `ac.abort()`)。 -6. 看门狗 `timeoutMs+15s` 兜底。 +### 5.5 `mcp.js` -返回 `{code, killed_by, out, truncated}`。 +- 传输: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.7 `auth.js` —— 多用户会话认证 +### 5.6 `remote-exec.js` -- `users: [{user, password}]` 在 config.yml;`secret` 留空则随机生成(重启即掉登录态,建议固定)。 -- 签发 HMAC 签名 token(payloadB64url.signature,payload = `{u, exp}`),存 HttpOnly + SameSite=Lax cookie,30 天有效。 -- 路由: - - `POST /api/login` → 校验 + setCookie + 返回 token(WebView 封装 APK 杀进程后 cookie 不一定落盘,token 存 localStorage 备 `login_restore` 恢复)。 - - `POST /api/login_restore`(Authorization: Bearer)→ 验签 + 重新签发。 - - `POST /api/password`(认证中)→ 校验 + 改写 config.yml(保留注释 + 校验失败不动文件) + 内存同步生效。 - - `POST /api/logout` / `GET /logout`。 -- 中间件:cookie 或 Authorization: Basic 任一通过(**cookie 优先**,见 §14.16;`/api/me` 与中间件同一解析顺序,保证显示身份 = 数据身份);公开路径白名单(`/login`, `/api/login` 等)+ 签名下载链接(`?t=...`)放行;其余 API 401、页面重定向 `/login`。 -- `req.user` 在中间件通过后挂上,**业务路由不要信客户端传的 user/body 里的 user**。 +- `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.8 `config.js` —— 配置加载与读写 +### 5.7 `agent-executor` -- 加载:`loadConfig(AGENT_CONFIG)` 读文件 → `parseAndValidate`。 -- 兼容:旧版 `models[]`(扁平)自动迁移到 `platforms[]` 层级;旧版 `web_search.*` 迁移到 `mcp_servers[]`(log.info 提示)。 -- 规范化:`normalizePlatforms` 校验 `name/url/type`,key 层 `concurrency`,model 层 `{id, display_name, vision, enable, extra_params, thinking_params, reasoning_ack_field, profile}`;同平台内 model id 必须唯一(内部唯一键 = 平台名/模型id);`profile` 引用不存在的名字直接报错。 -- `model_profiles`(顶层,`normalizeModelProfiles`):多套可复用的 prompt+tools 组合,每项 `{tools_allow?, tools_deny?, system_prompt_file?}`,三者至少配一个。`tools_allow` 按**最终发给模型的工具名**匹配(内置 + MCP,含 `服务名__` 前缀,与 prompt.txt dump 同源可对);未配 = 全量,**空数组 `[]` = 零工具(纯文本组合)**——与 MCP 的 `tools_allow`(空名单视作未配)有意不同。`tools_deny` 在 allow 之后叠加生效(deny 赢);profile 未配 = 继承全局 `tools_deny`(DEFAULTS 屏蔽元工具 `lab`),`[]` = 显式清空(lab profile 靠它换回元工具),非空 = 替换全局。`system_prompt_file` 相对 `server/templates/`(compose 已 bind-mount ./app/server,宿主直接可改),**配置加载时一次性读入常驻内存**,缺失/为空报错拦在保存/重启预检;自定义文件 = 完全接管模板正文,技能清单靠模板内 `{APP_SKILLS}` 占位符就地插入(不放 = 无技能段;默认模板同机制,见 §5.2),语言指令始终尾拼。运行期切换(前端传参)零 IO、不碰本配置。 -- 默认值(`DEFAULTS`):port=8090、workspace_root/data_root=`/workspace/tasks` `/workspace/data`、log_level=info、terminal 30s/10K、fetch 30s/1MB、agent temperature=1.0、max_tool_iterations=100、max_retries=2、上传 1.5MB/2000px/0.85(旧 `model_hold` 已废弃,字段仅为旧 config.yml 解析兼容保留);顶层默认 `tools_deny: [lab]`;内置 `model_profiles` 含 `lab`(元工具自测:`tools_allow:[lab]` + 显式清空 deny + `profile-lab.txt`)与 `zero`(零工具 + `profile-zero.txt`)。`config.yml` 只覆盖 deploy 相关段,其余走默认值;整份清单见 `app/config.example.yml`。 -- 读写:`readConfigText` / `writeConfigText`(先校验后写,无原子 rename,因 bind mount 上 rename 会 EBUSY);`applyEditsToText` 用 `YAML.Document` 保留注释。 -- `getConfig` 是浅引用,路由层拿到的就是运行中实例,**改完 in-memory 不影响**(要重启)。 +`executor/server.js` 是零依赖单文件 HTTP 服务。 -### 5.9 `db.js` —— SQLite 初始化 +隔离模型: -- 启动建表(`CREATE TABLE IF NOT EXISTS`)+ 增量迁移(`ALTER TABLE` 失败忽略,重复启动安全)。 -- 迁移示例:`reasoning`、`type`、`is_error`、`held_at`、`last_model_id`、`assistant_type`、`user` 列。 -- 所有表都用自增 PK 或显式 id;`messages` 按 `session_id, id` 索引;`files` 按 `session_id`;`model_usage` 按 `model_id, created_at`。 +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`。 -### 5.10 `sse.js` —— 事件总线 +预览网关 `executor/preview.js`: -- `Map<session_id, Set<res>>`。 -- `emit(sessionId, event, data)` 拼 `event: <name>\ndata: <json>\n\n`;无客户端静默丢弃(消息本身已持久化,重连可回放)。 -- 进程内内部订阅 `onInternal(fn)`:先于 HTTP 客户端触发、不受「无观看者早退」影响、单个监听抛错不影响其余——微信投递(wechat.js)靠它拿 assistant_message(微信会话常常没有任何 Web 页面在看)。 -- SSE 心跳:路由层 15s 一次 `: ping\n\n` 注释行(`X-Accel-Buffering: no` 是给 nginx-proxy 看的)。 +- 监听 3100,只走内网。 +- 每个 `.docx/.xlsx/.pptx` 一个 `officecli watch` 槽位,闲置回收,访问时冷启动。 +- core 的 `/preview/**` 反代是唯一公网入口。 +- 详细链路见 [`OFFICE.md`](OFFICE.md)。 -### 5.11 `balance.js` —— 余额查询 +`executor/init-skills.js`:一次性把技能的 `requirements.txt` 装进 `skills/deps`,把 `install.sh` 的资产落到技能卷。系统层依赖仍由镜像的 `skills` 构建阶段烘入。 -- 按 `platform.type` 分发到 `ADAPTERS`;已接 `deepseek`(`/user/balance`)与 `bigmodel`(`/api/biz/account/query-customer-account-report`)。 -- 上游根地址 = `cfg.platforms[i].url` 去掉尾部 `/` 与 `/v1`(余额端点在站点根)。 -- `types()` 返回已接入类型列表,前端设置页据此决定要不要展示余额行。 +### 5.8 `scheduler.js` -### 5.12 `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 工具路径会在回合收尾时把当前会话收口为任务专柜。 -AI 通过 `schedule` 工具为所在会话建周期性任务(`scheduled_tasks` 表,生命周期绑定会话),无人值守时(典型是半夜)自动执行,结果留在会话里供用户次日查看。 +### 5.9 `memory.js` -- **形态**:`start(engine)` 注入 engine(避免 engine→executor→scheduler 顶层循环 require),`setInterval` 30s + `unref`,单次异常只 `log.error` 不中断定时器。周期/最小间隔是模块常量,不进 config.yml。 -- **cron**:`cron-parser@5.10.1`(锁版;v5 API 是 `CronExpressionParser.parse`,与 v4 的 `parseExpression` 不兼容),显式 `tz: 'Asia/Shanghai'`(与容器 TZ 一致,不靠隐式时区)。最小间隔 1h 在创建时校验。 -- **tick 两阶段**:A 收尾上一轮 `running`(runLoop 无结束回调,轮询推断:会话转非 active 即标 ok);B 取到期任务投递——`next_run_at <= now` 且非 running;**防堆积以会话状态为准**:active 直接标 `skipped` 不投递(比 DB 标记时序可靠)。 -- **投递 = 存档 + postUserMessage**(顺序不可换):先把会话全部消息标 `type='archived'`(`buildMessages` 跳过 → AI 只看到本次 prompt,等价全新会话,上下文不随触发次数增长;UI 照常展示全量),然后 `engine.postUserMessage`——新调度下恒立即开跑(key 不独占不排队,任何状态都拿模型直接跑;绑定失效自动改选);仅模型池整体为空会投递失败标 `error`,下个周期重试。 -- **补跑语义**:`computeNext` 一律以 `now` 为基准,停机跨过多个触发点后重启只算未来一次,天然不补跑;重启后任务从库自动恢复。 -- **安全**:本功能等价给 AI 开持久化后门(prompt injection 可诱使建任务定时执行任意指令)。缓解三件:工具描述限定「仅用户明确要求时调用」+ 会话页常驻状态条(点击弹详情窗,可见 cron/上次下次时间/提示词,能就地改提示词或删除)+ 创建/触发/跳过/删除全打 `scheduler` info 日志。无权限分级/审批/配额。 -- **边界**:两次触发之间的用户对话也会被下次触发一并存档(UI 可见、AI 下次看不到,符合设计意图);多用户:调度器全局遍历不按 user 过滤(投递目标是会话本身,隔离在建任务时的 ctx.sessionId 已有);`last_status='running'` 的收尾不精确(异常结束的回合也会被标 ok)。 +- `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` -### 5.13 `wechat.js` —— 微信接入桥接 +- 三个字段:`honorific`、`industry`、`preference`。 +- `preference` 是顿号分隔的标签列表;工具只做增量 add/remove,不整段覆写。 +- 会话创建或清空时 `freezeSnapshot` 把渲染文本写入 `sessions.profile_snapshot`。 +- `buildMessages` 每轮把它作为 system 后首条 user 注入;字节恒定,且不在 `messages` 表里,压缩和归档都碰不到。 +- 写操作只影响下个会话;停用 `enabled=0` 时拒写不拒读。 +- 与 `model_profiles` 是两回事:后者是 prompt + 工具组合。 -背景:仓库内 `wxbot/`(已入库,作为根 compose 的 `wxbot` 服务)是基于官方 iLink 协议 SDK 的微信「调制解调器」,只挂 `agent-mcp-net` 内网、不暴露公网;身份权威与全部会话逻辑在 core,引擎不感知微信。 +### 5.11 `auth.js` -- **模型**:一条 `wechat_bindings` = 一个 core 用户 = 一个 bot 实例(一人一绑,换号先解绑)。binding id 三用:实例控制/投递的寻址键、wxbot 凭证目录名、channel 键(`channel='wx:'+id`,因此命令层、会话自动新建、投递游标查询全部白借 §5.4 的 channel 机制,零新逻辑)。iLink 协议保证扫码登录后仅本人可与 bot 单线对话,无陌生人入口,故无联系人授权面。 -- **方向三条线**:① Web(设置页→账户→微信内联卡)→ `/api/wechat` → wxbot `/api/instances*`(实例控制;QR SVG 代理内联渲染,只在 has_qr 就绪后取码,服务 token 不出内网);② wxbot 收信 → `POST core:/wxhook/inbox` → 直调 `channel.handleSend()`(文本;image/video/file 媒体先落会话任务目录:带说明文字的拼「用户上传了文件」告知行+正文并进一回合,单发媒体只补一行 `wx_media` 留痕不触发回合(下次真实对话模型自然看到,「刚才那张图」指代不断),同 web 附件链路;voice 走 iLink 服务端自动转写(msg.text 即识别文字),按文本类转发——命令回执同步回文本;普通消息不回执,等异步投递);③ core 总线监听 assistant_message/done → 按回合回复预算分配投递(见下两条),分段(~1800 字/段,行优先聚合)→ `POST wxbot:/api/deliver` → `bot.send`;wxbot 出口 markdown 默认透传(微信已支持渲染;env `WXBOT_STRIP_MARKDOWN=1` 恢复 stripMarkdown 纯文化降级);tool_call/tool_result 与 reasoning_delta(思考流,只进心跳不进台账)事件另发 `/api/typing` sendTyping 心跳(每绑定 2s 冷却、失败静默),长工具/思考回合里微信持续显示「正在输入」,文本投递后自动取消;同一对事件还记账工具台账(见下段)。 -- **渠道上下文**(ensureChannelContext,普通/媒体/带尾随文本的 /new 收信时幂等确保,先于首条消息入库):注入一条 `channel_note` user 行(微信环境说明:单线纯文本、给链接即交付卡片、入站文件已存工作目录等,AI 第一回合即知);/clear 删光历史后下条消息自动重注入。 -- **出站文件(链接→卡片)**:sendAttachments 扫正文 `/p/<22位id>` 链 → 同进程 `publicFiles.resolve` + 归属硬校验(只转本会话签发的链接,防外流)→ 本地读字节(单文件≤20MB、每条回复最多 5 个)→ `POST wxbot:/api/deliver_media` → SDK 按扩展名自动路由 image/video/file 卡片;尽力而为:失败只 warn,链接文字留在正文作兜底(AI 无需感知卡片机制,channel_note 已告知「给链接即交付」)。 -- **投递游标** `last_msg_id` 落库 + 每绑定串行队列:重启不重发旧回复,wxbot 短暂不可达不丢(下一条连带补齐);errAck/纯工具轮(空文本)不进微信,`__blocks__` 图消息降级为占位文案。markdown 的出口处理在 wxbot:默认透传(微信已支持渲染),`WXBOT_STRIP_MARKDOWN=1` 时 stripMarkdown 纯文化。 -- **回合回复预算**(配额在 iLink 上游、不可查,core 记账分配):回复额度挂在入站消息的 context token 上,每轮约 10 条(分段与附件卡片各占 1),AI 多迭代中间回复 + 长结论天然撞上限,故不能按位置丢消息。策略:handleInbox 每条入站重置预算(命令回执占 1);带 `tool_calls` 的 assistant_message 必然是过程消息,直发至多 `PROC_HEAD_LIMIT=1` 条且投完仍给结论留 `CONCLUSION_RESERVE=4` 条,超出的并入结论开头「已省略 N 条过程」注记(长任务进展靠 typing 心跳);不带 `tool_calls` 的挂起到 `done` 事件确认是收尾结论再保底投递——预算够全文+卡片;不够但 ≥2 降级为「截断头 + 全文落会话 `微信回复全文-<id>.md` 转文件卡片」(内容零丢失);<2 放弃并 warn(网页端完整可见)。状态全内存按 binding 记,调度器触发的回合无入站不重置(记账继续累积,与上游 token 真实剩余一致)。 -- **工具台账**(微信端过程可见性,单一出口):`tool_call`/`tool_result` 只往 `st.tools` 记账(`name + 参数原文`,不解析、整串 120 字截断、换行压平;同类计数折叠 xN、`is_error` 标 ✗(成功行 ✓ 前缀,状态在行首醒目)、失败不插队——用户确认微信端重结果轻过程);攒满一屏 8 行 → 「### 工具调用 + ``` 代码块」**独立消息**经串行投递队列即发(占 1 条配额,长参数代码块内横向滚动不折行);`done` 时零头补发(纯工具轮兜底也在此,不依赖任何文本消息);预算保不住 `CONCLUSION_RESERVE` 或直投失败 → 降级为结论的「--- 尾段」便车(与正文同段不多占配额);过程正文不再携带工具信息。诊断日志:`台账直投 N 类调用(余 M)`。 -- **降级承诺**:微信接入未配置(env `WXBOT_URL` 置空或未配 `WXBOT_TOKEN`)= 功能整体静默关闭(启动零日志噪声、设置页入口隐藏);配了但 wxbot 没起 = restore 只留一行 info,面板显示未连接,所有外呼失败只 warn,绝不阻塞/抛出未捕获异常影响 Web 主流程(鉴权/探活失败同样只降级)。绑定/刷新/解绑对 wxbot 均 **fire-and-forget**(点击秒回,不拿 wxbot 网络往返卡按钮;失败落 note 由轮询/刷新按钮恢复);`overview()` 每轮访问拿实例快照双向纠偏(补建缺失实例/纠正丢的 hook),`restore()` 启动对账兼清孤儿实例;前端内联卡按渲染串比对增量更新,QR 只在 has_qr 就绪后才取码,无闪烁无坏图帧。 -- 鉴权:双向共用一个服务 token(根 .env `WXBOT_TOKEN`,init.sh 生成/复用)——core→wxbot 时 wxbot 把该 env 自动并入 /api 白名单;wxbot→core 走 `/wxhook`(挂 auth.middleware 之前,Bearer 哈希后定长比较,token 未配一律 503 fail-closed)。wxbot 零配置文件(同 executor 模式):接线全靠 env(`WXBOT_TOKEN` / `CORE_URL` / `WXBOT_LOG_LEVEL`,none/off→silent;debug 原样打印收信消息结构),**不挂不读 core 的 config.yml**(密钥只给 core 进程)。 +- `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` -## 6. agent-executor 容器 +- `clients: session_id -> Set<res>`。 +- `emit` 先跑内部订阅者,再写 HTTP 客户端;没有客户端时静默丢弃。 +- `onInternal` 供 `wechat.js` 监听回合事件,不受「无观看者」影响。 +- `closeAllSessions` 用于进程退出,先掐断长连接,`server.close` 才能返回。 -单文件 Node HTTP 服务(`executor/server.js`),零依赖。镜像 `executor/Dockerfile` 分两阶段:`base`(M,长期不变)与 `skills`(M' = M + 技能系统层依赖,管理员改 skills 后重建)。端点: +### 5.13 `channel.js` + `wechat.js` + `wxbot` -- `GET /health` → `{ok, running:[{id, pid, cwd, started_at}]}`,免鉴权。 -- `POST /exec` body `{command, cwd(必填), timeout_ms?, max_output_chars?, env?}` → SSE 流: - - `start`(带 id + pid + cwd)→ `out`/`err` 增量分块 → `exit` 收尾。 - - 期间每 15s 一条 `: ping` 注释行保活。 -- `DELETE /exec/:id` → 杀进程组(`process.kill(-pid, SIGKILL)`)。 +**文本命令层** -**安全约束**(改 executor 时务必保持): +- `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`,不维护第二套会话逻辑。 -- `EXECUTOR_TOKEN` 非空时,除 `/health` 外必须 `Authorization: Bearer`(常时间比较)。token 存 `.env`(gitignore),不硬编码进仓库。 -- 拒绝**来自容器自身**(回环/本机网卡)的 `/exec`:隔离未 unshare net ns,命令能打到 `127.0.0.1:9000`;据此即使 token 泄漏,会话内也无法回环调 `/exec` 以他人会话 cwd 起命令(core 在另一容器,源地址非本机,不受影响)。`EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 仅供本机集成测试,生产不得设置。 -- `cwd` 必须落在 `EXECUTOR_ROOTS`(逗号分隔白名单,默认 `/workspace`)realpath 之下,防穿越。 -- `cwd` 不得是任务根本身(realpath 相等即拒):它是全部会话目录的父目录,在其下执行会暴露所有会话,且隔离 wrapper 在此层无从生效;缺省 cwd 落任务根同样被拒 → 等效必填。 -- `timeout_ms` 夹在 `[1000, EXECUTOR_MAX_TIMEOUT_MS=1800000]`。 -- 输出按 `max_output_chars`(默认 200000)截断,**截断后仍持续消费管道**(防子进程因 pipe 满阻塞),并设 `truncated=true`。 +**微信桥** -**启动参数**(环境变量): +- `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 路由与前端 + +**路由挂载** + +| 前缀 | 文件 | 说明 | |---|---|---| -| `PORT` | 9000 | 监听端口 | -| `EXECUTOR_ROOTS` | `/workspace` | cwd 白名单,逗号分隔 | -| `EXECUTOR_CWD` | `<ROOTS[0]>/tasks` | 默认 cwd | -| `EXECUTOR_MAX_TIMEOUT_MS` | 1800000 | timeout 上限(30 分钟) | -| `EXECUTOR_MAX_OUTPUT_CHARS` | 200000 | stdout/stderr 单向截断阈值 | -| `EXECUTOR_TOKEN` | 空 | 可选 Bearer 鉴权 | -| `EXECUTOR_LOG_LEVEL` | `info` | 分级日志(debug 打满请求/响应交互) | -| `EXECUTOR_ALLOW_LOCAL_ORIGIN` | 空 | 仅本机集成测试:`1` 放行回环/本机来源的 /exec(生产勿设) | +| `/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 预览反代,登录门禁 | -**per-task 挂载隔离**(`server.js` 的 `isolatedCommand`):cwd 在任务根(`EXECUTOR_CWD`)严格之下的命令,spawn 时包一层 wrapper,在新的 mount namespace 里把任务根覆盖为 tmpfs、只把当前会话根(第一层子目录)bind 回原路径——AI 只能看到/改自己的项目,看不到别的会话;cwd 恰为任务根被 /exec 边界直接拒 400(见上);cwd 在任务根外(如技能依赖安装跑在技能目录)不隔离直接 spawn(/mnt 仍被遮,看不到任何会话数据)。wrapper 同时 `unshare --pid --fork` 进新 pid ns 并重挂 /proc(flags 对齐 docker):否则 /proc 仍是宿主视图,`nsenter --mount=/proc/1/ns/mnt` 可借 executor 主进程的 ns 句柄逃逸回原始 mount ns(已实测复现过);重挂后 /proc/1 即命令自身。新 proc 可写会顶掉 docker 防护,wrapper 逐项还原:/proc/sys 只读 bind(防 core_pattern 宿主逃逸)、/dev/null 遮蔽 kcore/keys/sysrq-trigger(echo b 可重启宿主机)。wrapper 还把 server.js 所在目录(镜像 WORKDIR,容器内 `/app`)tmpfs 盖掉(任务根与之嵌套的开发态跳过);且下发命令的 env 剥掉 `EXECUTOR_TOKEN`——否则 `env` 一 dump 即得 token,可从容器内回环调 `/exec` 以任意会话目录起命令,绕过隔离。需 compose 配 `cap_add: SYS_ADMIN` + `security_opt: apparmor=unconfined`(不用 privileged:实测 Docker 29,默认 AppArmor profile 拦 `mount(2)`,单加 SYS_ADMIN 不够;默认 seccomp 对持 CAP_SYS_ADMIN 的进程放行 `unshare(2)`/`mount(2)`,无需改动);`unshare`/`mount`/`mktemp` 来自 debian 基础包 util-linux。wrapper 还会把 `/dev/shm`、`/var/tmp`、`/dev/mqueue`、`/run` 整体换成 per-exec tmpfs,并 `unshare --ipc` 隔离 System V IPC;session 模式的 `/tmp` 另叠一层 bind 指向 `<session>/.tmp`(会话内跨调用共享、随会话目录删除),堵掉跨 exec/跨会话的共享内存、临时文件与运行时状态通道;`/dev/mqueue` 挂不上时回退用 tmpfs 遮盖(队列不可用但不泄漏)。隔离层失败退出码 ≥90 逐个区分(99=会话 /tmp bind,100=/dev/shm,101=/var/tmp,102=/run)。 +**前端** -**资源护栏**(compose 层,**不在 server.js**): -`cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G` —— 防 AI 失控命令。残余缺口(只限单文件不限总量)在 compose 注释里已标。 - -**根文件系统只读**(compose 层):`read_only: true` 挡住 AI 命令往镜像层写文件做持久化/篡改;`tmpfs: /tmp /var/tmp /run` 提供必要可写点。**`/run` 必须给**——隔离 wrapper 要在 `/run/agent-exec` 建私有 anchor/rundir,否则 `read_only` 下 `mkdir` 报 EROFS(`set -e` 直接中断每条命令);正常写盘另走 `handleExec` 的 `HOME=/tmp`/`TMPDIR=/tmp` 与 bind 卷。 +- `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 拉取。 --- -## 7. HTTP 路由 +## 6. 关键流程 -所有路由走 Express Router,`server.js` 挂到 `/api/...`;静态资源(前端)走 `express.static('public')` 直接托管;其余路径走 auth middleware。 - -| 路径前缀 | 文件 | 主要端点 | -|---|---|---| -| `/api/sessions` | `routes/sessions.js` | `POST /` 创建、`GET /` 列表(分页 + 搜索 + user 隔离)、`GET /:id` 详情(含 `schedule` 字段,列表接口不带以免 N+1)、`PATCH /:id` 改名、`DELETE /:id?delete_dir=...`、`POST /:id/bind`(`model_id`=手动换绑:任意模型即点即换、仅正在输出拒绝;原 profile 会话模式绑定已废弃)、`DELETE /:id/schedule`(删定时任务,只落 `scheduler_note` 通知消息不触发 AI)、`PATCH /:id/schedule`(改提示词/频次,cron 经 validateCron 重校验并重算 next_run_at) | -| `/api/sessions/:id/messages` | `routes/messages.js` | `POST /` 发消息(body 可选 `deepThink`;响应 `delivered` 恒 `'live'`(排队已废弃);原 `profile` 参数已废弃)、`POST /stop`、`POST /release`(held→completed,纯状态动作、无资源可释放)、`DELETE /messages`(清空)、`POST /summarize`(压缩)、`DELETE /messages/:mid`、`GET /stream` SSE 事件流 | -| `/api/sessions/:id/files` | `routes/files.js` | `POST /` 上传(multer,50MB/文件,文件名清洗 sanitizeName)、`GET /` 列表(递归)、`GET /download[-name/...]` 签名下载(5 分钟 TTL)、`GET /zip-token` + `GET /zip[-name/...]` 选中项(含文件夹)打包 zip 流式下载(纯 Node STORE,两遍读:先 CRC 后磁盘流发送)、`DELETE /` 删文件(目录递归删) | -| `/api/skills` | `routes/skills.js` | 技能列表/创建/重命名/删除 + 技能内文件 CRUD + 上传(`?overwrite=true` 覆盖) | -| `/api/config` | `routes/config.js` | `GET /` 原文+生效(脱敏)、`POST /validate`、`PUT /` 整文件保存、`PATCH /` 单项修改(path/value/op[delete\|append]) | -| `/api/platforms` | `routes/platforms.js` | `GET /balance?pi=&ki=` 余额 | -| `/api/system` | `routes/system.js` | `GET /status` + `/restart?force=...`(原 `model_profiles` 可用名单字段已删,前端无消费方) | -| `/api/profile` | `routes/profile.js` | `GET /` 读画像、`PUT /` 保存(三字段 + enabled);按 `req.user` 隔离,逻辑全在 `user-profile.js`(快照冻结见 engine `createSession`/`clearSessionMessages`;日常更新由 AI 经 `profile` 工具增量维护,见 §5.4) | -| `/api/channel` | `routes/channel.js` | `POST /send {channel, text}` 文本命令接入端(IM/CLI 等无 UI 客户端,走 Basic/cookie 鉴权):命令仅在本入口解析(Web 消息路由不受影响,防误伤路径/代码文本);严格匹配白名单 `/new[文本] /list /switch[编号] /rename[标题] /delete[编号] /models[编号] /think[on|off] /stop /compact /clear /status /help`(可带参数命令走 ARG_CMDS:switch/delete 编号=最近 /list 行号或 id 前缀,delete 删会话连同任务目录(同 Web 删除弹窗默认勾选),models 换绑复用 engine.bindToSession,think 读写用户 wechat_bindings.deep_think——微信全局深度思考开关(H5 按钮的指令形态,默认关,/think on 手动开,投递时替进既有 deepThink 参数)),未知斜杠词回提示、不像命令的当普通消息;(user,channel) 经 `channel_sessions` 表绑定当前会话(普通消息无绑定自动建);命令动作不落消息行(与 Web 按钮对称),AI 回复由接入端复用既有 SSE/详情接口获取;`handleSend()` 另供微信桥接直调 | -| `/api/wechat` | `routes/wechat.js` | 微信绑定管理(设置页,cookie 鉴权 + req.user 隔离):`GET /`(enabled/alive/我的绑定)、`POST /`(新建绑定,一人一绑)、`GET /:id/qr`(登录二维码 SVG 代理)、`POST /:id/refresh`(重发登录)、`DELETE /:id`(解绑,销毁实例与凭证);业务全在 `wechat.js`(§5.13) | -| `/wxhook` | `routes/wechat.js`(hookRouter) | wxbot → core 内网回调(**挂 auth.middleware 与全局 express.json 之前**,自带 32mb 解析器容纳媒体 base64):`POST /inbox {id, from, text, media?}` 文本/媒体转 channel 层——media={kind:image\|video\|file, b64, filename?},core 按 magic 嗅探定扩展名、落会话任务目录(文件保留消毒原名,图/视频生成 wximg-/wxvid- 时间戳名)+ 记 files 表 + 拼「用户上传了文件:<名>」告知行(同 web 附件模式,vision 模型 read_file 即见);非 2xx 时 wxbot 把 error 文案回给微信用户;`POST /hook {id, event}` 实例状态回报;Bearer 共享服务 token(哈希后定长比较,未配一律 503) | -| `/api/models` | `server.js` | 模型池(在用会话数 slots_used / 在用会话列表,非独占展示)+ token 用量 | -| `/api/health` | `server.js` | 健康检查 | -| `/api/login` `/api/login_restore` `/api/logout` `/api/password` `/api/me` | `auth.js` | 认证路由(认证前) | -| `/login` `/logout` | `auth.js` | 登录/登出页 | -| `/files/download[-name/...]?t=` `/files/zip[-name/...]?t=` | `auth.js` 白名单 | 带签名 token 的下载/打包下载(认证中免 cookie) | -| `/p/<id>` | `routes/public-files.js` | 公网临时文件取用(匿名,挂认证中间件之前;随机 ID + 过期) | -| `/preview/**` | `routes/preview-proxy.js` | 通用任务预览反代(挂认证之后、server.js 最末,信任模型同 data-page 登录≈运维):注册表(env PREVIEW_PROXIES,默认 officecli → mcp_officecli:3100)把 `<prefix>/**` 原样转发到服务单一预览入口,槽位/路径解析托管给服务端;另兜 vendor 预览页硬编码的根绝对 API(Referer 指向注册预览页 → 原路径转给对应服务,其余请求 404 照旧);头白名单(凭据/公网身份不出容器),JSON 体因全局 express.json 已消耗需重序列化重放;SSE 响应加 no-cache/no-buffering;watch url 的公网前缀由 `mcp.js` 随请求以 `X-Public-Base` 头注入,会话目录经 `X-Session-Dir` 注入(officecli 桥自动把裸文件名补全会话目录);链路见 mcp 仓库 `officecli/README.md` | - -**SSE 事件**(`/api/sessions/:id/stream`,由 `bus.emit` 触发,前端订阅): - -| event | data | 触发时机 | -|---|---|---| -| `status` | `{session_id, status, model_id}` | 状态变化时;SSE 连接建立时立即发一次 | -| `assistant_delta` | `{text}` | 模型流式文本 | -| `reasoning_delta` | `{text}` | 模型流式思考(`reasoning`/`reasoning_content`) | -| `assistant_message` | `{id, content, reasoning, tool_calls, type, is_summary, mode}` | 整轮 assistant 落库后(含 `type='errAck'` 标识) | -| `tool_call` | `{id, name, arguments}` | 即将执行工具前 | -| `tool_result` | `{tool_call_id, name, content, is_error, image_url, msg_id}` | 工具回执落库后 | -| `done` | `{status: 'held'\|'cancelled'\|'completed'}` | 回合收尾 | -| `title` | `{title}` | 首次交互结束后自动生成的标题落库时(生成流程见 §9) | -| `error` | `{message}` | 异常 | - ---- - -## 8. 前端 - -`app/server/public/` 是 H5 SPA(无构建步骤,本地 `vendor/marked.min.js` 渲染 Markdown,不引外部 CDN)。`index.html` 只包含 HTML/CSS 与按序加载的 6 个经典脚本(`<script src>`,无 import/打包):顶层 `function` 声明仍挂 window 供内联 `onclick` 调用,顶层 `const/let` 进全局词法环境跨脚本可见;每文件各自 `'use strict'`。拆自旧版单一内联脚本,**纯搬运零改动,切分均在顶层语句边界**: - -- `js/core.js` —— 架构注释头、通用工具(`$`/`esc`/`req`/`toast`/`copyText`/`fmtTime`/markdown 渲染)、MODES、全局 `state`、视图/模式切换、头部标题渲染(点击重命名)。 -- `js/chat.js` —— 消息渲染(气泡/思考面板/工具卡)、历史懒加载分页、滚动跟随与回底、typing。 -- `js/sessions.js` —— 会话列表(抽屉)、打开/新建/重命名/删除、SSE 静默看门狗与后台挂起、phase-bar、定时任务、上下文压缩。 -- `js/stream.js` —— 发送、SSE 流式渲染(delta 合帧/工具早卡)、消息复制、全屏查看器。 -- `js/files.js` —— 输入区、任务文件面板(树/选择/下载/拖拽调高)、大图压缩与上传卡片、抽屉与滑动手势。 -- `js/settings.js` —— 设置区全部(页面栈/账户/服务/config 编辑器/技能/模型池/MCP)及 `window.sUI`/`window.mcpUI` 对外接口;**文件尾是全局初始化段(load 时直接调 `bindChatScroll()`/`openDrawer()`/`loadSessionList()` 等),必须最后加载**。 - -新增模块或调整顺序时注意保持与上表一致的加载序(末尾初始化依赖前面所有文件)。`login.html` 单独登录页。`sw.js` 是 service worker:`/api/*` 与 SSE 直接放行;HTML/CSS/JS 网络优先(改完刷新即生效);图片/JSON 缓存优先(改动需升 `CACHE_VERSION`)。 - -前端用 `EventSource` 订阅 `GET /api/sessions/:id/stream`;消息体默认 `Content-Type: text/event-stream`,nginx-proxy 必须 `proxy_buffering off` 才能实时下发。 - ---- - -## 9. 配置 - -详见 `app/config.example.yml`(core 专属;字段与 `server/config.js` 的 `DEFAULTS` 一一对应;顶层 `config.yml` 由 `scripts/init.sh` 生成或手建,**已 gitignore**)。要点: - -- `platforms[].keys[].models[]` —— 三层层级。内部唯一键 = `平台名/模型id`(用于历史会话回绑、用量统计),**改名等于重建其下所有模型**。 -- `model_profiles`(顶层)—— 多套可复用的 prompt+tools 组合(`{tools_allow?, tools_deny?, system_prompt_file?}`);模型层用 `profile: <名>` 引用,不配 = 默认全量(仍受顶层 `tools_deny` 屏蔽)。内置 `lab`/`zero` 两套默认组合,可用同名覆盖。元工具自测/纯文本场景用,详见 §5.8;运行期手动切换已全部移除(消息级参数与会话绑定均废弃)。 -- `agent.max_tool_iterations`(默认 100)—— 单轮迭代上限(含工具调用),到顶自动停止并提示用户继续输入。 -- `terminal.max_output_chars`(默认 10000)—— AI 看到的命令输出上限;executor 侧另有 `EXECUTOR_MAX_OUTPUT_CHARS=200000` 兕底。 -- `fetch.timeout_ms`(默认 30000)/ `fetch.max_bytes`(默认 1MB)—— 网页抓取的全生命周期超时与流式抓取**字节**上限(超限即断开;下载不占上下文,保持宽松)。 -- `fetch.max_chars`(默认 12000)/ `fetch.max_chars_hard`(默认 64000)—— 回给模型的**字符**返回窗(与下载上限解耦);模型可传 `max_chars` 放宽到硬帽,超窗尾部提示 `offset`,续读走回合缓存不重抓(见 §5.4)。 -- `fetch.allow_private`(默认 false)—— SSRF 防护开关:目标主机名解析到回环/私有/链路本地地址即拒抓(重定向逐跳复查);确需抓内网服务才显式开 true。 -- `skills.skills_root` —— 缺省取 `workspace_root` 的同级 `skills/`。 -- ~~`model_hold`~~ —— 已废弃(旧版保持租约:held 到期自动释放);新调度下 key 不独占、不排队,held 不再到期,字段仅为旧配置解析兼容保留。 -- 上下文压缩 —— 无配置项:压缩回合沿用当前 profile 的 system prompt(无 profile = 默认模板)+ 正常历史,末尾追加一条 user(固定模板 `server/templates/prompt-compress.txt` 原文),该回合不传 tools;调整压缩策略直接改该文件。 -- 会话标题自动生成 —— 无配置项:每回合结束(`finalize` 成功分支)过门槛才触发,防「你好」开局把题定了:①本轮真实执行过工具(`run.toolWorked`,errAck 批不算)即立题;②零工具纯聊由历史现推(无计数器,重启/压缩免疫):非注入 user 正文行(type IS NULL,[CTX] 各段与 task_brief 天然排除)≥3 条且总字数 ≥30。触发后用会话当前 model_id 发一次**不带 system、不传 tools** 的标题请求(历史 user/assistant 原文,注入行不进——`llm.titleMessages` 白名单只留 null/summary/task_brief;末尾追加模板 `server/templates/prompt-title.txt` 作 user,`{{language}}` 填 `agent.language`);结果清洗后写入 `sessions.title` 并 SSE 推 `title` 事件。失败静默(title 仍空,下个回合结束自动重试);已有标题(建会话时填写或手动重命名 title_locked)不覆盖。 -- `auth.users` —— 明文密码配在配置里(自用场景);`secret` 留空则随机生成(重启掉登录态,建议固定随机串)。 -- `mcp_servers[].enable: false` —— 启动不加载该服务(配置保留),其余工具不受影响。 -- `mcp_servers[].timeout_ms` —— 该服务单次 `tools/call` 的最大等待,默认 60000(夹在 1s~10min);工具发现/握手用固定 15s,不受本项影响。 -- `mcp_servers[].tools_allow` / `tools_deny` —— 发现阶段的工具名单(字符串数组,按服务端原始名):allow 白名单,deny 在其后叠加(deny 优先);用于压低发给模型的工具数(如浏览器类服务)。 -- executor 接线 —— **不占配置字段**,纯 env(compose 从根 .env 注入 `EXECUTOR_URL` / `EXECUTOR_TOKEN`;未注 = 本地 spawn,单机调试形态);executor 进程不读本配置文件,日志等级走 `EXECUTOR_LOG_LEVEL`。 -- 微信接入(§5.13)—— **不占 config.yml 字段**(wxbot 已是栈内组件):接线纯 env,`WXBOT_URL`(缺省 `http://wxbot:8093`;根 .env 显式置空 = 微信入口整体静默关闭)与 `WXBOT_TOKEN`(init.sh 生成/复用,同一值注进 core 与 wxbot 两侧双向互信;未配 = 关闭)。旧 config.yml 里的 `wxbot:` 段直接忽略。 - ---- - -## 10. 关键流程 - -### 10.1 用户发消息到 AI 回答的完整链路 +### 6.1 发消息到回复 ```mermaid sequenceDiagram - participant U as User - participant F as Frontend - participant R as routes/messages - participant E as engine - participant L as llm - participant M as Upstream - - U->>F: 输入文本/附件 - F->>R: POST /:id/messages {content, attachments, deepThink} - R->>E: postUserMessage - Note over E: saveMessage(user) +<br/>保绑定、转 active、立即开跑 - E-->>R: {message_id, delivered} - R-->>F: {message_id, delivered} - par SSE 流 - F->>R: GET /:id/stream - R-->>F: event: status - and 主循环 - E->>E: runLoop → runLoopInner - loop max_tool_iterations - E->>L: buildMessages + callModel - L->>M: POST /chat/completions (SSE) - M-->>L: data: {choices:[{delta:{content,tool_calls}}]} - L-->>E: onText / onTool / onReasoning - E-->>F: event: assistant_delta / reasoning_delta - alt 工具调用 - E->>E: checkToolArgs + unwrap - E->>E: executeTool - E-->>F: event: tool_call → tool_result - else 收尾 - E-->>F: event: assistant_message → done - end - end - end + 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 ``` -### 10.2 命令 / 技能走 executor 的路径 +1. 用户消息落库,`run` 记录 `deepThink`。 +2. 会话非 `looping` 则置 `active` 并开跑;正在跑则只投递,下一轮迭代自动带上。 +3. 每轮从 DB 重读历史,组装 messages 与 tools。 +4. 模型流式输出;工具调用经参数校验、解包、执行、落库、广播。 +5. 无工具调用则收尾;有新用户消息则继续。 +6. `finalize` 进入 `held`,发 `done`,触发标题与自动压缩检查。 -```mermaid -sequenceDiagram - participant AI as AI tool call - participant EX as tools/executor - participant RX as remote-exec - participant XS as agent-executor - participant SH as /bin/sh +### 6.2 工具执行 - AI->>EX: terminal({command, timeout_ms}) - EX->>RX: run(cfg, {command, cwd, timeout_ms, run}) - RX->>XS: POST /exec (Bearer token) - XS->>SH: spawn detached - XS-->>RX: SSE start - loop 数据流 - SH-->>XS: stdout/stderr chunk - XS-->>RX: SSE out/err - RX-->>EX: 累积 out - end - alt 30s 到 / 用户取消 - XS->>SH: SIGKILL(-pid) - XS-->>RX: SSE exit - end - RX-->>EX: {code, killed_by, out, truncated} - EX-->>AI: truncate(组装, max_output_chars) +- 内置工具在 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] ``` -### 10.3 登录 +重启 core 生效。服务不可达只告警;重名工具自动加 `my_service__` 前缀。 -```mermaid -sequenceDiagram - participant U as User - participant A as auth.js - participant M as auth.middleware +### 8.4 新增模型或平台 - U->>A: POST /api/login {user, password} - A->>A: timingEqual(密码) - A-->>U: 200 Set-Cookie: agent_token=<HMAC>+ JSON {user, token} - Note over U: localStorage 存 token(APK 兜底) - U->>M: GET /api/* (Cookie;curl/脚本用 Authorization: Basic) - M->>M: parseCookie / readToken / timingSafeEqual - M->>M: req.user = username - M-->>U: 业务路由 - Note over U,A: cookie 丢时,APK 用 localStorage token 调 /api/login_restore - U->>A: POST /api/login_restore (Bearer) - A-->>U: 200 Set-Cookie(重新签发) +- 平台加在 `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 ``` ---- - -## 11. 扩展点(修改代码时按这里定位) - -### 11.1 加一个内置工具 - -1. 在 `app/server/tools/definitions.json` 末尾追加 OpenAI function 定义。 -2. 在 `app/server/tools/executor.js` 的 `HANDLERS` 表加一行 `name: handlerFn`;按需实现文件路径校验(用 `resolveInTask` 防穿越)。 -3. 若要走 executor(比如执行命令),参 `terminal` 模板用 `rexec.isRemote` 分流。 -4. `definitions.json` 的 `description` 是给模型看的"何时用、怎么用",写清楚边界(输入/输出/限制)。 -5. 跑 `npm test` 验证。 - -### 11.2 加一个技能 - -1. 在 `skills/<name>/` 建目录,写 `SKILL.md`(含 YAML front matter `name`/`description`/`input_schema`)+ `run.py` 或 `run.sh`。 -2. 入口脚本约定:唯一 argv = `'<JSON 字符串>'`(含全部 `input_args`)。 -3. 路径类参数会被 `absolutizeArgs` 自动按任务目录转绝对;如需输出到特定位置,传 `output` / `dest` / `target` 之类的 key 名触发"目录型参数"启发。 -4. 依赖:`requirements.txt`(pip)或 `install.sh`(系统级)放同目录;镜像缺的包在启动时由 `agent-executor-init` 装进 `deps/`(改完依赖跑 `docker compose up -d`,不用重建镜像),`install.sh` 与 `.deps_installed` marker 也在那里维护。 -5. 改完文件后 **无需重启**——`routes/skills.js` 的 `refreshSkillPrompt()` 会重建 system prompt 段落。 - -### 11.3 加一个 MCP 服务 - -直接改 `config.yml` 的 `mcp_servers` 数组加一项 `{name, url, headers, enable?, timeout_ms?, tools_allow?, tools_deny?}`。重启生效。`enable: false` 的服务不加载工具(配置保留),单服务失败只 warn 不影响其他。`timeout_ms`(默认 60000,夹在 1s~10min)是该服务单次 `tools/call` 的最大等待。`tools_allow`/`tools_deny` 可按原始工具名只放行要用的那几个(见 §5.3)。 - -### 11.4 加一个模型 / 平台 - -改 `config.yml` 的 `platforms`:加新平台 `{name, url, type, keys:[{api_key, models:[{id, display_name, vision?, enable?, extra_params?, thinking_params?, reasoning_ack_field?}]}]}`,**或**在已有平台加新 key/新 model。重启生效。`enable: false` 的模型不进模型池;`vision` 缺省开启(现在模型基本都带视觉),不支持的模型显式配 `vision: false`。小模型可加 `profile: <名>` 引用顶层 `model_profiles` 的 prompt+tools 组合(见 §5.8)。 - -模型内部唯一键 = `平台名/模型id`(用于历史回绑、token 用量统计)—— **重命名平台等于重建其下所有模型**。 - -### 11.5 加一个 HTTP 路由 - -`app/server/routes/` 新建文件,导出 `express.Router`;在 `server.js` 的 `app.use('/api/...', ...)` 挂载。要走认证中间件就放在 `auth.middleware` 之后(已经是默认行为——除 `auth.router` 里白名单的路径)。 - -### 11.6 加一个平台类型(余额查询) - -`app/server/balance.js` 的 `ADAPTERS` 加一项 `async (p, k) => balanceInfo`。`types()` 自动暴露给前端设置页。 - -### 11.7 加一个"用户进入"/"AI 动作"日志 - -统一走 `log.info(category, message)`,category 用短标识(`task`/`msg`/`model`/`file`/`sse`/`config`/`auth`/`mcp`/`skills`/`tool`/`startup`/`system`/`engine`/`scheduler`)。`log.setLevel(cfg.log_level)` 控制阈值;debug 级别会被多打几项(如 SSE 帧、tool 参数/结果)。 +- `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。 --- -## 12. 约定(修改时遵守) +## 10. 已知边界与陷阱 -### 12.1 日志 - -- `require('./log')` 拿全局 logger;四档 `debug/info/warn/error`,外加 `none` 全静默。 -- 调用形如 `log.info('category', '具体消息')`(category 走 SSE meta 不发,仅做过滤标签)。 -- 关键动作 `info`;可预期的异常状况 `warn`(如失败登录、401 token 缺失、MCP 工具发现失败);未预期异常 `error`(spawn 失败、runLoop 异常)。 -- Error 对象等原生参数透传 `console` 走 `util.format`,不会被字符串化。 -- 等级通过 `config.yml` 的 `log_level` 注入(**冷加载**,需重启)。 - -### 12.2 错误处理 - -- 业务异常走 `throw Object.assign(new Error('...'), { status_code: 4xx })`;路由层 `wrap(fn)` 的 `sendErr` 读 `err.status_code` 设响应码。 -- 工具内部异常被 `executeTool` 捕获包成 `Error: <msg>` 字符串作为 tool 回执(`is_error=true`),不会冒泡。 -- async 路由返回 Promise 时 `wrap` 会 `catch` → `sendErr`。 -- 不要在异步循环里吞错(除非明确是预期情况)—— 该 warn 的 warn、该 error 的 error。 - -### 12.3 路径安全 - -- **所有用户可传入的路径**都必须经 `resolveInTask(taskDir, relOrAbs)` 校验落在任务目录之内(含根),不允许 `..` 穿越。 -- 技能文件管理(`routes/skills.js`)走 `safeRel`(`path.posix.normalize` + 拒绝 `../` 前缀 + 拒绝绝对路径)+ `absInSkill`(解析后必须以技能目录开头)。 -- `terminal` 命令的 `cd` 同样经 `resolveInTask` 校验。 -- `@<session-id>/<rel>` 是唯一的跨会话记号,解析/同用户校验单点在 `resolvePastPath`,只接三个只读入口(list_directory、read_file、copy_path 源);写侧(write_file/edit_file/copy_path 目标)显式拒 @,历史永远只读,落地只走 copy_path。 - -### 12.4 异步 / DB - -- `better-sqlite3` **同步 API**,单进程内无竞争("JS 单线程 + 同步 DB"在头注释里也强调了)。 -- 异步用 `async/await`;`setTimeout`/`setInterval` 走定时器(scheduler 的轮询 timer、自动压缩宽限期 timer 均调 `unref()` 不阻止进程退出)。 -- 写库用 `db.prepare(...).run/get/all`;复杂查询写 `prepare` 一次复用。 - -### 12.5 进程组 / 取消 - -- 任何 `spawn` 派生的进程(`terminal` 本地、skill 本地、pip install)都用 `detached: true` + `process.kill(-child.pid, 'SIGKILL')` 杀进程组,确保 `cat | grep` 这样的管道命令连子子孙孙都死。 -- `remote-exec` 的远端进程由 executor 端做同样的进程组 kill。 -- 远端句柄用 `run.procs.add({remoteKill() {...}})` 注册,`killRunProcs` 识别后调 `remoteKill()`(不能本地 kill)。 - -### 12.6 注释 / 语言 - -- **代码注释、log 消息、SSE 用户可见文案、路由错误消息**——统一中文(README、模板除外)。 -- **system prompt、工具 description、definitions.json**——英文(给模型看的,跨模型兼容)。 -- 注释风格:函数顶部 1-2 行说明**做什么 + 为什么**(不只 what),关键边界条件点出来(如 `run.cancelled = true` 是停止的最终信号)。 - -### 12.7 命名 / 风格 - -- 模块名小写蛇形;函数 camelCase;常量 UPPER_SNAKE。 -- `async/await` + `try/catch` 为主,少用 `.then()` 链。 -- 中文标点(`,` `。` `()` `:`)为主,但代码标识符一律英文。 -- 状态机用 `s.status`、`run.looping` 这样的对象属性 + 注释说明约束。 - ---- - -## 13. 测试 - -- `app/test/smoke.js` —— 端到端冒烟:mock 上游 + 真 server,覆盖创建/绑定/对话/工具调用/阶段/终止/排队/文件 API 等 68+ 用例。`npm test` 跑。 -- `app/test/remote-exec.test.js` —— 集成测试:起真 executor,调 core 的 terminal/skill 走远端。 -- `app/test/dep-check.js` —— 依赖完整性。 -- `app/test/mock-upstream.js` —— 测试用假 LLM。 -- `executor/smoke-test.js` —— executor 自身冒烟(`cd executor && node smoke-test.js`)。 - -测试配置隔离 data_root(`app/test/config.test.yml`),不会污染生产数据。 - -跑测试前要确认端口 8099/9999 未被占用(`pkill -f "test/(mock-upstream|server.js)"`)。 - ---- - -## 14. 常见陷阱 - -1. **改了 `config.yml` 没重启** —— 配置是冷加载。改完要走 `POST /api/system/restart`(或 docker compose 重启),不能热生效。 -2. **路径穿越** —— 任何用户传 `path` 都要 `resolveInTask`,否则 `../../../etc/passwd` 就能读出去。 -3. **跨平台路径** —— Windows/macOS 路径分隔符差异:`resolveInTask` 用 `path.resolve` 适配本地;技能内部用 `path.posix.normalize`(强制 POSIX 风格)。 -4. **session.id 序号不复用** —— `genTaskId` 取历史最大 + `meta.task_seq` 取大;删会话后序号不回收。 -5. **held 的语义** —— held = 「回合已收尾,绑定持续展示」,无排队/租约含义、不会自动到期;completed = 手动「断开」,cancelled = 手动终止;三态 UI 仍需区分,但都不影响模型可用性(key 共享)。 -6. **errAck 误判** —— 弱模型会把参数多包一层 `{"arguments":{...}}`,`unwrapToolArgs` 自动解包;`checkToolArgs` 只看 required 字段是否在顶层。 -7. **图片上下文省钱与防循环** —— `lastAssistant` 之前的图发请求时被换成文字描述(DB 存全量,UI 历史重渲染仍能看图;要看原图可 `read_file` 重读,新回执会重新投递)。两条铁律(线上死循环实测复盘):① tool 回执夹图会被兼容差的上游静默吞掉,必须走批次后 `user` 合并消息;② 上游对 user 合并形态(单消息多图、公网外链、attachment 响应头、自签 https)经探针矩阵实测全部兼容——"多张看不见"的真凶是 tool 夹图时代与弱模型行为惯性,不是多图限制;对策 = 同回合同图去重 + 不催促重读文案 + 合并消息「先逐张简述再继续」送达自检。诊断三源交叉:`log.debug('req', 发送形态...)` 看拼没拼上图、`public-file 外部取用` 日志看上游拉没拉、usage.pt 增量(每图数百~1024 tok)看图进没进上下文。 -8. **SSE 被 nginx-proxy 缓冲** —— 必须 `proxy_buffering off`;否则 `assistant_delta` 攒到响应结束才一次性下发,体感卡死。 -9. **cookie 兜底(APK 场景)** —— WebView 杀进程后 cookie 不一定落盘,登录响应回 `token` 让前端存 localStorage,下次冷启动调 `/api/login_restore` 恢复。 -10. **MCP session 过期** —— 第一次 `tools/call` 可能 400 + 含 "session",`mcp.js` 自动重 initialize 后重试一次;日志会打 warn。 -11. **Executor 截断不中断** —— stdout 撞 `EXECUTOR_MAX_OUTPUT_CHARS` 后**只停止 SSE 推送,仍持续消费管道**(防子进程 pipe 满阻塞),`truncated=true` 在 exit 帧带回。所以 `cat /dev/urandom` 这类命令即使输出无限也不会卡死,只是烧 CPU 到 `timeout_ms` 触发 SIGKILL。 -12. **任意时刻发言都立即开跑** —— `postUserMessage` 除回合正在跑外不排队不分状态,保绑定后直接 `runLoop`(`delivered` 恒 live);原模型被配置改动失效时 `ensureBinding` 自动改选(优先原平台),日志有「原绑定失效…自动改选」一行。 -13. **模型 tool_calls 不带 id** —— `runLoopInner` 兜底补 `'call_' + 随机串`(与 `tool_call_id` 落库一致,`buildMessages` 按 id 配对丢弃 errAck 关联回执)。 -14. **编辑 SKILL.md 不会立即生效** —— 不需要重启,但需要 `routes/skills.js` 的 `refreshSkillPrompt()` 异步重建 system prompt 段落(fire-and-forget,扫描失败不影响 API 响应)。 -15. **`pids_limit` 与 `ulimit` 区别** —— 前者是 cgroup pids 控制器算整个容器的进程+线程;后者是 per-process `RLIMIT_FSIZE` 等。被杀时 OOM kill vs SIGXFSZ 行为不同。 -16. **浏览器内双凭据身份分裂** —— 前端 `req()` 曾附加 sessionStorage 里的 Basic 头兜底 cookie,但 sessionStorage 按标签页隔离、刷新后残留(新标签页不继承,复制标签页则继承),cookie 是浏览器全局:A/B 切号登录后刷新旧标签页,会出现 `/api/me`(读 cookie)是 A、会话列表(Basic 优先于 cookie)是 B 的不一致,SSE(EventSource 只能带 cookie)又跟着 A。现已统一:浏览器身份只认 cookie(`req()` 不带 Basic 头,登录页不再存明文口令),服务端 `authUser` 也是 cookie 优先;Basic 仅供 curl/脚本无 cookie 时使用。 - -17. **微信功能必须静默降级** —— wxbot 是可选依赖:未配置/未启动/网络断开时,core 启动与 Web 主流程必须零报错(restore 只留日志、外呼失败只 warn、设置页自动隐藏入口);改 wechat.js 时不得引入任何会冒到主流程的同步抛错或未 catch 的 promise。 - ---- - -## 15. 进一步阅读 - -- `README.md` —— 设计文档(API 设计、SQLite 表结构、任务目录结构、Agent 主循环伪代码、Zed 风格工具定义全集) -- `docs/DEPLOY.md` —— 部署(Docker,IP:端口直连;外部网络、配置绝对路径、SSE 缓冲坑) -- `docs/v2-develop.md` —— v2 移动单聊视图 -- `app/config.example.yml` —— 配置模板(字段与 `DEFAULTS` 一一对应,每个字段一行注释) -- `app/server/templates/profile-default.txt` —— AI system prompt 全文 -- `executor/server.js` 头注释 —— executor 协议、安全约束、日志/资源护栏一览 +- **认证边界**:会话、消息、文件 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`**:它看不到任务数据,也不应该看到。 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md deleted file mode 100644 index 9ea65d4..0000000 --- a/docs/DEPLOY.md +++ /dev/null @@ -1,181 +0,0 @@ -# 部署说明(Docker,IP:端口直连,无 nginx-proxy) - -配置与编排文件都放在**仓库顶层**,方便直接调整: - -| 宿主机路径 | 容器内路径 | 说明 | -|---|---|---| -| `./docker-compose.yml` | — | 编排(构建 `./app`,把容器 8090 映射到宿主机 8090) | -| `./config.yml` | `/app/config.yml` | 运行配置(AGENT_CONFIG 指向它;含密钥,已被 .gitignore 忽略) | -| `./tasks/` | `/workspace/tasks` | 任务目录:AI 的文件工作区(与 executor 必须同路径) | -| `./data/` | `/workspace/data` | 数据目录 + SQLite(`.agent.db`) | -| `./skills/` | `/workspace/skills` | 技能目录:所有任务/会话共享 | -| `./.env` | — | 编排变量(`EXECUTOR_TOKEN` / `AGENT_PORT` / `AUTH_SECRET`),已被 .gitignore 忽略 | -| `./scripts/init.sh` | — | 一键生成上面两个文件并起服务(见第 0 节) | - -> `config.yml` 与 `.env` 推荐交给 `scripts/init.sh` 生成(见第 0 节);不想用脚本的话也可以自己建(见第 2 节)。 - -## 0. 一键生成配置(推荐) - -`scripts/init.sh` 只读环境变量(不依赖任何外部文件),生成 `.env` 与 `config.yml`: - -```bash -# 什么都不给也能跑:默认账号 admin/admin、无模型(platforms: []) -./scripts/init.sh - -# 给几个变量 -BIGMODEL_KEY=xxx DEEPSEEK_KEY=yyy ZHIPU_KEY=zzz PUBLIC_IP=1.2.3.4 AUTH_USER=me ./scripts/init.sh -``` - -| 输入变量(均可选) | 说明 | -|---|---| -| `BIGMODEL_KEY` / `DEEPSEEK_KEY` / `QWEN_KEY` | 模型平台 key,**填几个启用几个**(0~3 个) | -| `ZHIPU_KEY` | image_task / video_task 用;**留空则这两个服务 `enable: false`**(工具不加载) | -| `AUTH_USER` / `AUTH_PASSWORD` | 登录账号(默认 `admin`/`admin`,记得改) | -| `PUBLIC_IP` / `AGENT_PORT` | 对外地址与端口,写进 `public_link.base_url`(`PUBLIC_IP` 空则尝试自动探测) | -| `AUTH_SECRET` / `EXECUTOR_TOKEN` | 一般不用给:不给就自动生成,并**存在 `.env` 里复用**(所以重跑不会掉登录态) | - -生成的 `config.yml` **只含 deploy 相关段**:`platforms` / `auth` / `mcp_servers` / `public_link`;其余配置项 -(路径、超时、`model_profiles` 等)走 `server/config.js` 的默认值,完整清单见 `app/config.example.yml`。 - -⚠️ **`config.yml` 是生成物,不要再手改**:每次生成都会把旧的备份成 `config.yml.bak.<时间戳>`。 -要改配置请带环境变量重跑该脚本,或者不用脚本、按第 2 节手动维护。 - -> 本机现成的一键流程(仓库外):`/root/deploy.conf` 放变量 → `/root/init_repos.sh`(拉仓库 → 把变量 export 出去 → 调本脚本)。 - -## 1. 网络(自动创建,无需手动) - -`agent-core` 与 `mcp` 仓库的服务共用网络 `agent-mcp-net`:agent 按容器名访问 MCP -(如 `http://mcp_web_search:3000/`)。该网络由**本仓库的 compose 创建**(固定名字,不带项目名前缀), -`mcp` 侧声明为 `external` 直接加入。 - -所以全新机器上有**先后顺序**:先起 agent(创建网络),再起 mcp(mcp 单独先起会因为网络不存在而报错)。 - -```bash -# 1) 先 agent,创建网络 -docker compose up -d --build - -# 2) 再 mcp -cd ../mcp && docker compose up -d --build -``` - -> 拆的时候反着来:先 `down` mcp,再 `down` agent。否则 agent 侧会报 -> `network agent-mcp-net has active endpoints`(容器照删、网络留下,重新 up 就恢复,不损数据)。 - -## 2. 准备配置(手动方式) - -不用 `scripts/init.sh` 时,自己建这两个文件: - -```bash -cp app/config.example.yml config.yml -cp .env.example .env -vi .env # 填 EXECUTOR_TOKEN / WXBOT_TOKEN(或直接跑 scripts/init.sh 自动生成) -vi config.yml -``` - -`app/config.example.yml` 与 `server/config.js` 的默认值一一对应,容器内可直接用(路径默认 -`/workspace/tasks`、`/workspace/data`)。`config.yml` 里至少要配: - -```yaml -platforms: ... # 模型池:每个平台 url + keys.api_key + models.id;可留空,启动后到设置页添加 -auth: # 建议启用,否则谁都能访问 - secret: "换一个随机串" - users: - - user: admin - password: "换一个密码" -mcp_servers: # 无域名时按容器名访问(模板已写好,按需启用) - - name: web_search - url: "http://mcp_web_search:3000/" -``` - -> `public_link.base_url` 只在需要给外部服务公网 URL(图生视频取参考图)时才配;纯 IP:端口部署 -> 填 `"http://<服务器IP>:8090"`,容器 env 有 `VIRTUAL_HOST`(nginx-proxy)时以它为准(见第 4.1 节)。 - -> ⚠️ 必须先有 `config.yml` 再 `up`:compose 挂载的是 `./config.yml:/app/config.yml`, -> 文件不存在时 Docker 会在宿主机建一个同名**目录**,容器起来会读不到配置。 - -## 3. 构建并启动 - -```bash -# 在仓库顶层(含 docker-compose.yml 的位置)执行 -docker compose up -d --build -docker compose logs -f agent-core # 看到 "Agent server listening on 8090" 即成功 -``` - -首次启动会先跑一次 `agent-executor-init`(把技能依赖落到宿主机 `./skills`),跑完自动退出, -属正常现象。 - -> 镜像构建默认走腾讯云镜像源(apt / pip / npm),否则国内机器上 `apt-get update` 可以卡十几分钟。 -> 境外构建或想换源:`docker compose build --build-arg DEBIAN_MIRROR=deb.debian.org agent-executor` -> (mcp 仓库同理,参数名是 `NPM_REGISTRY`)。腾讯云 CVM 上还可换成内网镜像 `mirrors.tencentyun.com`。 - -## 4. 访问 - -浏览器打开 **`http://<服务器IP>:8090`**(端口可用 `.env` 里的 `AGENT_PORT` 改)。 -登录用第 2 步 `auth.users` 里配的账号。 - -**对外只需要放行这一个端口**:`agent-executor`(9000)和 mcp 的三个服务都只在 `agent-mcp-net` -内网,没有映射到宿主机(需要从宿主机 curl 调试时,去 mcp 仓库的 `docker-compose.yml` 里临时 -把对应服务的 `ports` 两行取消注释)。 - -### 4.1 公网临时链接(只有“把本地文件交给外部服务”时才用到) - -场景:图生视频时,智谱服务器生成视频前要**自己来拉参考图**,它不带 cookie、不带 `Authorization`, -所以必须有一条公网匿名可达的 URL。做法是给一个**不透明短 ID**(`app/server/public-files.js`): -22 字符随机串,服务端内存表记着它对应哪个会话的哪个文件、什么时候过期。 - -AI 拿链接的姿势:直接调内置工具 `mint_public_link`(只传文件名),core 在进程内签好并把 URL 当 -工具结果返回。没有任何额外的 HTTP 签发端口,也不存在“AI 的命令带不了凭据”这个问题: - -``` -mint_public_link({ path: "_cgi-bin_..._d92292d.jpg" }) -→ http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn - 返回的就是现成 URL(约 50 字符、纯 ASCII),直接当 image_url 用 -``` - -``` -智谱 ──匿名 GET──► /p/9fQ2mZ7xK4tR1vBn (core :8090) - │ 查内存表:未过期?→ 得到(会话, 相对路径) - ▼ - ./tasks/<会话>/foo.png ← 文件仍在原地,零拷贝 -``` - -> 为什么不做成“带签名的 URL”:那样必须把会话名、文件名、过期时间、64 位签名全塞进 URL(数百字符、 -> 满是 `%XX`)。而这条 URL 会被模型抄进工具参数、并且**永久留在会话历史里每轮重发**, -> 太长又难抄,还白烧 token。短 ID 把三个问题一次解决了。 - -- 必须在 `config.yml` 配 `public_link.base_url = "http://<服务器IP>:8090"`;不配则 `mint_public_link` 直接报错 - (需要公网 URL 的那部分功能就用不了,例如 video_task 拉不到参考图)。 - 例外:容器 env 里配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS 那套)时,前缀自动用 `https://<域名>`, - 不用改 `config.yml`(改也盖不住它)。 -- 链接有效期 `public_link.ttl_ms`,默认 30 分钟;签完尽快用掉。 -- 沙箱外的人要用上这条链接,得拿到那个 22 字符随机 ID(猜不出来,也不可能枚举),且过期即废。 -- 这条路不搬字节:文件始终在它原本的位置,也不需要 video_task 参与上传/落盘。 - -## 5. 没有 HTTPS 的影响(可忽略,仅记录) - -HTTP 直连时浏览器不认为这是"安全上下文",以下能力自动降级,不影响主流程: - -- PWA / Service Worker 不注册(`http://IP` 不是 secure context),离线缓存与「添加到主屏」不可用。 -- 复制按钮的 `navigator.clipboard` 不可用,前端自动回退到旧 API。 -- 登录 cookie 本身没带 `Secure` 标志,HTTP 下正常签发与携带(`auth.js` 用的是 HttpOnly + SameSite=Lax)。 - -日后若加回 nginx / HTTPS 反代,注意 **SSE 必须关代理缓冲**,否则流式输出会被攒住不发: - -``` -location / { - proxy_pass http://agent-core:8090; # 或宿主机 IP:8090 - proxy_http_version 1.1; - proxy_buffering off; # SSE 关键 - proxy_read_timeout 3600s; -} -``` - -## 6. 升级流程 - -```bash -git pull -docker compose up -d --build # 仓库顶层执行 -``` - -数据库与任务目录都在 bind 挂载的 `./data`、`./tasks` 内,升级不丢数据。进程重启时, -原 active 会话会自动退回排队队列,待模型空闲后继续。 diff --git a/docs/v2-develop.md b/docs/v2-develop.md deleted file mode 100644 index 6b36225..0000000 --- a/docs/v2-develop.md +++ /dev/null @@ -1,80 +0,0 @@ -## 1. 页面定位 - -- `v2.html` 是并行于 `index.html` 的另一套 H5 界面,主打**移动端单聊 + 历史抽屉**,不沿用 index 的底部多 Tab 结构。 -- 直接访问 `/v2.html`;无入口链接(浏览器手动打开或自己加)。 -- index.html 仍是功能最全的 1.x 界面(tasks.js 多 Tab / 工具卡片 / makrdown / 图片压缩 / 文件面板),v2 迭代时可随时回看参考实现。 - -## 2. 涉及文件 - -| 文件 | 说明 | -|---|---| -| `app/server/public/v2.html` | 页面结构 + 全部前端逻辑(内联 `<script>`,无构建步骤) | -| `app/server/public/css/v2.css` | v2 全部样式(已从 html 内联 `<style>` 抽出) | - -- 后端只用了**既有 /api 接口**,上一轮未新增/改动任何后端代码。 -- 样式与 `index.html` 体系(`css/style.css`)完全隔离,互不干扰。 - -## 3. 已接通的真实业务流 - -全部走 `v2.html` 内联脚本,核心请求函数为自带 `req()`(401 自动跳 `/login`): - -| 用户动作 | 实现方式 | -|---|---| -| 首页欢迎态 | 仅「文秘助理 / 识图专家」两个模式胶囊,纯前端状态 | -| 首条消息 | `ensureSession()` → 无会话时先 `POST /api/sessions {title:'', model_id:''}`,再发消息;创建后进入 chat 视图 | -| 发送文本+附件 | `send()` → `POST /:id/messages {content, attachments:[{name,size}]}` | -| 附件上传 | 选文件只进本地 `state.attachments`;发送时才 `POST /:id/files`(multipart,字段名 `files`),拿回文件名后再随消息体发 attachments | -| 历史列表(抽屉) | 打开抽屉 / 发送后 / done 后调 `loadSessionList()`:搜索词为空时并行拉 `status=active&limit=100` 与 `status=done&limit=50&with_total=1` 合并;搜索走 `?q=` | -| 打开历史会话 | `openSession()` → `GET /api/sessions/:id` 渲染全部消息 → `connectStream()` | -| 实时回复 | EventSource `GET /:id/stream`:`status` / `assistant_delta` / `assistant_message` / `tool_call` / `tool_result` / `done` | -| 复制 AI 文本 | 历史 AI 消息右下角按钮,内容以 `data-b64` 存放(防引号破坏属性) | -| 删除会话 | 消息操作栏垃圾桶 → `window.confirm` → `DELETE /:id?delete_dir=true`(连同任务目录文件,不可恢复) | -| 会话标题 | 后端会在首条用户消息时自动截取前 24 字;本地 header 同步乐观赋值 | - -### 消息展示约定 - -- 用户消息:右侧浅灰气泡。附件由服务端拼成前缀 `【系统通知】用户上传了文件:xx(大小 N)…`,前端 `parseUploadNotice()` 拆出 📎 行后展示正文。 -- AI 消息:左侧大段白底文本,无 markdown,`white-space: pre-wrap`。 -- 工具调用:仅显示一行 `🔧 工具名`(有 tool_call 事件 / 历史 assistant 的 tool_calls 字段时)。历史中的 `role: tool` 消息不展示(看不到工具输出与图片)。 -- 「思考中」打字占位:每次发送后出现,首个 SSE 事件到达时消失。 - -## 4. 明确纯前端、无后端支撑的能力(现状即如此) - -这些概念在 mock 原型里能“表演”,接真实后端后**后端没有对应字段/参数**,目前只影响外观或文案: - -1. **文秘助理 / 识图专家 模式**:后端无 `mode` 字段,也暂无「模式 → 模型」映射约定。现仅影响欢迎页 hint 与聊天 header 的模式文案。 -2. **深度思考开关**:后端请求无 `reasoning`/`deep_think` 参数。开关纯本地视觉状态。 -3. **思考过程折叠块(已思考 N 秒/思考步骤)**:后端不输出 reasoning 内容,此能力已随 mock 一起删除。 -4. **按条删除消息**:后端只有会话级删除/清空,无消息级删除接口,故删除按钮 = 删除整个会话。 - -若让 1/2/4 真正生效,属于**后端新增能力或接口扩展**的范畴,需先定接口再实现(例如 `POST /:id/messages` 增加 `mode/deep_think` 参数;或前端把「识图专家」映射到某个带 vision 的 `model_id` 走现有 `POST /api/sessions` 建会话)。 - -## 5. 后端已有、v2 尚未接入 UI 的接口(下次可做清单) - -| 接口 | 建议接入点 | -|---|---| -| `PATCH /api/sessions/:id {title}` | 会话重命名(header 标题点击 / 抽屉长按) | -| `POST /:id/stop`、`/release`、`/bind {model_id}` | 对话中终止 / 保持态断开 / 换模型,需先有会话状态与模型池 UI | -| `DELETE /:id/messages` | 一键清空会话(保留文件) | -| `GET /:id/files/download-token?path=` | 附件/文件下载(配合文件面板) | -| `GET /api/models` | 当前空闲/占用模型池,供新建会话选模型、模式映射 | -| `GET /api/system/status` | 版本信息、上传压缩配置 `upload`(参考 `tasks.js` 的大图压缩逻辑) | - -## 6. 已知行为瑕疵 / 简化点(建议优先修) - -1. **流式回复完成后没有操作行**:`assistant_message` 收尾时只留文本,不追加「时间 + 复制/删除」;而历史重开(`aiMsgHtml`)有。同一消息两种状态下观感不一致。 -2. **排队场景无提示**:`send()` 无条件挂思考占位。若 `POST /messages` 返回 `delivered:'queued'`(在排队等模型),应像 index 那样提示「排队中/暂存」,避免用户以为卡死。SSE `status` 事件带 `queue_pos` 可展示第几位。 -3. **抽屉列表无分页**:只拉 active 100 + done 50,会话多时看不到更早归档;搜索无 loading/竞态处理。 -4. **无 markdown 渲染**:AI 回复为纯文本。index 用 marked CDN,若 v2 要渲染代码块/列表需引入同一方案。 -5. **移动端大图上传无压缩**:index `tasks.js` 有 `maybeCompressImage` + `/api/system/status` 的 upload 配置,v2 直传原图,流量大且可能超服务端 50MB 限制。 -6. **看不到工具输出与文件**:工具只显示一行名字;不做结果展开/图片查看下载。 -7. **会话删除不可选「保留文件」**:v2 固定传 `delete_dir=true`;index 有二次弹窗让用户选是否连目录一起删。 - -## 7. 修改 v2 时的注意点 - -- 页面**自包含**:不加载 `core.js / tasks.js / marked`,全部工具函数(`$`/`esc`/`req`/`toast`/`copyText`/`fmtTime`)在页面内定义。若今后要共享代码先考虑重名冲突。 -- 全局状态集中在 `state`(`view/mode/deepThink/sessionId/sessionTitle/status/sessions/attachments/es/streamText/streamEl/toolLines/typingEl/streaming`),别再散落游离变量。 -- 切换会话/新建/删除前务必 `closeStream()` + `removeTyping()` + 重置流式相关字段,防旧会话 SSE 污染新会话。 -- 消息内容一律 `esc()` 后再进模板;复制按钮用 base64 传内容。 -- `v2.html` 顶部大注释维护着「接口参考/未接入清单」,改动的接口状态要同步更新那里。 -- 页面入口 `/v2.html` 无防盗链,直接可访问,注意它同样受全局登录中间件保护。 diff --git a/docs/v3-develop.md b/docs/v3-develop.md deleted file mode 100644 index ee54258..0000000 --- a/docs/v3-develop.md +++ /dev/null @@ -1,48 +0,0 @@ -定位吸收了:**微信通道 = 一个有记忆的人**。会话是工作台(短期记忆),按天的日记是长期记忆,轮换即"下班记日记"。方向我认同,且它和刚落地的 30 分钟自动收口正好咬合:轮换留下的旧 held 会话自己归档。 - -先补三个**代码里发现的硬事实**,它们影响设计,然后给里程碑计划。 - -## 设计层要碰的三个钉子 - -**1. 回忆 skill 的数据通路是真坑(你第 4 点里藏着)。** 隔离是刻意的:executor 的 session 模式把其它会话的任务目录遮掉了,`read_file`/terminal 跨不出当前会话目录——skill 脚本从执行器侧**天然摸不到**旧会话的消息流和成果文件。两条出路: -- **方案 A(我推荐)**:回忆仍走 skill(SKILL.md 当"怎么回忆"的操作手册,不占 tool schema),但脚本调 core 的**只读内部接口**(`/api/sessions/:id/messages|files` 已存在,加个 executor→core 的服务 token 即可)——基础设施增量只有一条回连通道; -- 方案 B:不建 skill,加一个极简 `recall` tool(op=days / op=session)——违背你"别撑 tool 描述"的初衷,但通路最短。 -这个要你拍板,它决定 M3 的形态。 - -**2. 碎片摘要绝不能阻塞微信回信。** 轮换发生在入站消息路径上;旧会话摘要是一次 LLM 调用,必须**后台异步**生成(先换绑新会话、先回用户,碎片慢慢落),失败只记日志——日记晚到一分钟无伤大雅。另外碎片生成复用压缩那套基建(`templates/` 加个 journal prompt + 轻量 LLM 调用),不是新子系统。 - -**3. 定时任务会话和日记有个现成的交集**:scheduler 每次触发前本来就"历史整体存档、AI 只看到任务 prompt"(等价自动换班)。所以**定时任务的每次执行也是天然日记事件**——不需要 LLM,模板化一行(「X 任务按计划执行,结果:…」)直接追加当日条目。这让"纯任务会话"虽不轮换也有记忆痕迹,成本为零。 - -## 里程碑切割 - -```mermaid -flowchart LR - M0["M0 地基\n记忆表+碎片生成"] --> M1["M1 短期记忆边界\n轮换触发器组"] --> M2["M2 注入闭环\n新会话读日记"] - M3["M3 回忆通路\n跨会话细粒度"] - M4["M4 定时任务\nlist_all+承接"] - M2 -.可并行.- M3 - M2 -.可并行.- M4 -``` - -**M0 — 地基**(`db.js` / `engine.js` / `config.js`) -- `memory_entries(user, day, content)` 表 + 追加/读取/按保留期裁剪(`memory.retain_days` 默认 7、上限 30 截断); -- `appendFragment(user, day, text)` 与 `journalFor(user)`;碎片 LLM 摘要函数(异步、幂等、失败降级为"仅标题+文件清单"); -- 当日多碎片 = 机械拼接追加(每片已条目化,不再二次 LLM 合并,省钱且确定性)。 - -**M1 — 短期记忆边界**(`wechat.js` handleInbox + `engine.js`) -轮换触发器,全部收敛到同一个 `rotateChannelSession()`:① 入站距最后一条 **user** 消息 >4h(排除 scheduler_note 续命坑);② 微信会话上下文超 `auto_compress_tokens` → 直接换会话不压缩(复用现有阈值,行为按通道分叉);③ `/new`、`/switch` 换绑时对手动离开的会话产碎片;④ 删会话不产。每次轮换后台产碎片 + 旧会话 releaseHold 收口。 - -**M2 — 注入闭环**(`wechat.js` ensureChannelContext) -新通道会话创建时把近 7 天日记注入上下文(channel_note 同族的一条 memory_note,第一人称口吻「9月28日 帮他整理了…」)。到这里"这个人"已经能连续地活:**M0-M2 是最小可用闭环**。 - -**M3 — 回忆通路**(按上面方案 A/B 拍板结果做) -日记条目里带旧会话 id + 成果文件清单索引 → skill/工具按 id 下钻详细消息与文件。 - -**M4 — 定时任务配套**(`tools/executor.js` + `routes/channel.js`) -- `schedule` 加 `op=list_all`(跨会话:join sessions 出标题/cron/下次/上次状态)——只读全览,改删仍绑当前会话,引导 `/switch`; -- `op=create` 撞主键时错误文案升级为「本会话已有任务 X,如需新闹钟请开新会话承接」→ AI 依你第 5 点走 `/new` 流程; -- 微信 `/tasks` 文本命令(与现有命令同族)+ 定时任务执行结果模板化落日记(第 3 个钉子)。 - -顺序 M0→M1→M2 串行(每步都可独立验证),M3/M4 并行或调序。**要你拍板的只剩两个**:① 回忆走 A(skill+内部 API 回连)还是 B(极简 recall tool)?② `/clear`(网页端清空回 advising)要不要也产碎片——我倾向产,语义一致。 - -定了我就从 M0 开干。