Files
agent/AGENTS.md
T

224 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md — 仓库总览
本文件写给在本仓库里动手的 AI / 开发者:系统由哪些进程组成、边界在哪、哪些约束一碰就坏。
用户视角的能力、部署与配置说明见 [README.md](README.md);`app/`(agent-core)的内部实现见
[app/AGENTS.md](app/AGENTS.md)。
## 一句话架构
自托管的单实例 Agent 任务台:浏览器或微信发来任务 → `agent-core` 调度模型(OpenAI 兼容
`/chat/completions`)→ 模型调用内置工具 / MCP / 技能 → 命令在 `agent-executor` 隔离容器里执行 →
产物落在会话工作目录并回传。每个会话 = 一个真实 Linux 工作目录 + 一条 SQLite 会话记录。
另有一个可选的**设备执行端** `device/`:设备主动出站连 core 的 `/dev/ws`,模型用 `device`
工具在远端机器(Mac / Windows / OpenWrt 盒子)上跑命令、拉推文件。
设计基调:**单进程内存模型 + SQLite 同步 API**(JS 单线程,不存在跨进程竞争);**配置冷加载**
(改 `config.yml` 需重启,少数写盘接口例外);**单租户**(登录只把门,不做资源级授权)。
## 仓库结构
| 路径 | 职责 | 形态 |
|---|---|---|
| `app/` | **agent-core**:Express + better-sqlite3 + 免构建 H5 | Node 20,容器 `agent-core` |
| `app/server/` | 后端全部代码(入口 `server.js`) | 见 `app/AGENTS.md` |
| `app/server/public/` | 前端静态资源,经典脚本按序加载,共享全局作用域 | 无构建步骤 |
| `executor/` | **agent-executor**:`/exec` 隔离命令执行 + Office 预览网关 | 零依赖 Node,独立容器 |
| `device/` | **agent-device**:设备执行端,出站连 core 的 `/dev/ws`,提供 exec / 文件传输 | Go 单二进制,交叉编译(amd64/arm64/mips/mipsle/windows),见 `device/README.md` |
| `wxbot/` | 微信 iLink 协议调制解调器(多实例) | 独立容器 `agent-wxbot` |
| `mcp/` | 同栈 MCP 服务:`web_search` / `image_task` / `video_task` / `asr` | 四个容器,仅内网 |
| `skills/` | 目录式技能(`SKILL.md` + `run.py`/`run.sh`) | 运行时挂载,`skills/deps` 为依赖层 |
| `local/` | **本地端启动器**:同一份代码跑在本机(不起 Docker / executor),`start.sh` 负责探测、装依赖、守护 | 独立于 compose,见 `docs/local-mode.md` |
| `tunnel/` | **反向隧道**:服务器端 `server.js` 按 Host / 固定端口 / 通配路由转发,本机 `client.js` 承接 | 独立 compose,见 `tunnel/README.md` |
| `scripts/` | `init.sh` 生成 `.env` + 首次创建 `config.yml`(仅初始管理员);`init_host.sh` 裸机初始化 | 幂等,**不覆盖已有配置** |
| `docs/` | 专题文档:`tool-design.md`(工具接口规范)、`OFFICE.md` | — |
| `tasks/` | **运行时数据**:每个会话一个工作目录 | gitignore |
| `data/` | **运行时数据**:SQLite `.agent.db`、`prompt.txt` 调试产物 | gitignore |
| `docker-compose.yml` | 全栈编排(唯一入口) | — |
`executor/` 已相对稳定,没有单独的 AGENTS.md;改它之前先读 `executor/server.js` 顶部长注释
(隔离模型与 v4 教训),不要凭直觉动 mount/umount 流程。
## 运行时拓扑
```mermaid
flowchart TD
CORE["agent-core(8090,唯一对外端口)"]
B["浏览器 / PWA"] -->|"HTTP + SSE"| CORE
M["手机 / 外网"] -->|"HTTPS"| TUN["tunnel server(19000,仅回环)"]
TUN -->|"WebSocket"| TC["tunnel client(本机)"]
TC -->|"HTTP"| CORE
W["微信客户端"] --> WXBOT["agent-wxbot(8093,仅内网)"]
WXBOT -->|"回调 /wxhook/*(共享 Bearer token)"| CORE
CORE --> EXEC["agent-executor(9000 exec / 3100 预览,仅内网)"]
CORE --> MCP["mcp_web_search / mcp_image_task / mcp_video_task / mcp_asr(3000,仅内网)"]
CORE -->|"分段投递回复"| WXBOT
DEV["设备:Mac / Windows / OpenWrt"] -->|"wss 出站 /dev/ws"| CORE
```
- **对外只暴露 `agent-core` 一个端口**(宿主 `AGENT_PORT`,默认 8090)。executor、wxbot、MCP
一律不映射宿主机端口——MCP 没有鉴权,暴露即被白嫖额度。
- `wxbot` 不直连微信服务器以外的东西;它回调 core 的 `/wxhook/*`,用共享 Bearer token 把门。
- 容器间按容器名访问(`http://agent-executor:9000`、`http://mcp_web_search:3000/`);
所有业务容器同在 `agent-mcp-net`(compose 里固定网络名,避免被加上项目名前缀)。
- `agent-executor-init` 是一次性容器:把技能依赖装进 `./skills/deps` 后退出,属正常现象。
- 设备(`device/`)**不需要任何入站端口**:设备主动连 `wss://<PUBLIC_BASE_URL 的 host>/dev/ws`,
core 按 `DEVICE_TOKEN` 校验。本地部署没有公网前缀,端点不挂,`device` 工具直接回“未启用”。
### 端口与网络(要改先看这里)
| 服务 | 端口 | 可见性 |
|---|---|---|
| `agent-core` | 8090 | 宿主机映射,**唯一对外** |
| `tunnel` server | 19000 | 仅 `127.0.0.1`,对外经 nginx 反代 |
| `agent-executor` | 9000(exec)、3100(预览网关) | 仅 `expose`,内网 |
| `agent-wxbot` | 8093 | 仅内网 |
| `mcp_*` | 3000 | 仅内网 |
### 数据持久化(bind mount)
| 宿主机 | core 容器内 | executor 容器内 | 内容 |
|---|---|---|---|
| `./tasks/` | `/workspace/tasks` | `/mnt/host-tasks`(启动即遮蔽) | 会话工作目录 |
| `./data/` | `/workspace/data` | — | SQLite、`prompt.txt` |
| `./skills/` | `/workspace/skills` | `/workspace/skills:ro` | 技能与共享依赖 |
| `./config.yml` | `/app/config.yml` | 不挂、不读 | 平台密钥、登录密钥 |
| `./app/server/` | `/app/server` | — | 后端代码(**热挂载**) |
| `./tunnel/data/` | — | — | 隧道服务端配置 `server.yml`(首次启动自动生成,含 token) |
| `./wxbot/data/` | — | `/data`(wxbot) | 微信登录凭证 |
推论:
- 改后端代码 → **重启 `agent-core` 即可**(`docker compose restart agent-core`),不必重建镜像;
改前端静态资源同理(浏览器刷新即可;只有改图片/JSON 才需要升 `sw.js` 的 `CACHE_VERSION`)。
- 改 `app/package.json` / 依赖 / Dockerfile → 必须 `docker compose up -d --build agent-core`。
- `config.yml` 只给 core 读;**不要**把它挂给 executor / wxbot。
### 环境变量(接线全靠根 `.env` + compose)
`AGENT_CONFIG`、`PORT`、`EXECUTOR_URL`、`EXECUTOR_TOKEN`、`WXBOT_URL`、`WXBOT_TOKEN`、
`PUBLIC_BASE_URL`、`DEVICE_TOKEN`、`ASR_URL`、`PREVIEW_PROXIES`、`EXECUTOR_LOG_LEVEL`、`WXBOT_LOG_LEVEL`、`ASR_LOG_LEVEL`。
密钥生成:`./scripts/init.sh`(幂等,重跑不掉登录态;**从不覆盖已有 config.yml**,只在其缺失时创建
最小骨架)。语音识别的上游 key/base/model 不在 env,
写在 `config.yml` 的 `mcp_servers[name=asr].headers`(容器不存平台密钥)。
## 四条主链路
1. **Web / HTTP**:`app/server/server.js` 装配 → 路由 → `engine.js` 起回合 →
`llm.js` 组装并流式调用上游 → `tools/executor.js` 执行工具(`terminal` / `skill` 走
`remote-exec.js` 打进 executor)→ SSE 回推前端。
2. **微信**:`agent-wxbot` 收消息 → 回调 core `/wxhook/inbox` → `wechat.js` 落媒体、注入上下文 →
`routes/channel.js` 的命令层(`/new` `/switch` `/think` …)→ 同一套 `engine`;回合结束由
SSE 内部订阅者(`bus.onInternal`)分段推回微信。
3. **远端设备**:设备上的 `agent-device` 出站连 core `/dev/ws` → `devices.js` 维护连接表 →
模型调 `device` 工具(`list` / `health` / `exec` / `pull` / `push`)→ 命令经 WS 下发、输出分片
回传;`pull` 落到会话目录后,`read_file` / 技能可直接消费。
4. **定时任务**:`scheduler.js` 每 30s tick → 到期则先 `archiveHistory`(历史整体 `archived`,
模型等价新会话)→ `engine.postUserMessage` 投递 → 结束后 `wechat.notifyTask` 通知。
## 数据与状态
- **会话工作目录** `tasks/<session-id>/`:`session-id` 形如 `task-YYYYMMDD-NNN`(UTC 日期 + 当日
递增序号,序号持久化在 `meta` 表)。模型产出、用户上传、`data.db`(`db` 工具用)、`.tmp`
(容器内 `/tmp` 的宿主实体)、`.imgcache/`(读图压缩缓存)、`.app/`(data-page 技能页面)。
- **唯一数据库** `data/.agent.db`(WAL 模式,`foreign_keys=ON`)。表:`sessions`、`messages`、
`files`、`model_pool`、`meta`、`scheduled_tasks`、`channel_sessions`、`memory_fragments`、
`wechat_bindings`、`model_usage`、`user_profiles`;`wait_queue` 是已废弃残留表。
- 备份至少覆盖 `data/`、`tasks/`、`config.yml`(有微信登录态再加 `wxbot/data/`)。
## 全局约束(改之前先读)
1. **单实例、单进程内存态**。`engine.js` 的 `runs`/`titling`/`pendings`(待投递消息队列)、`wechat.js` 的回合投递状态与实例缓存、
`publicFiles` 的短链表、`download-token` 的随机密钥都在进程内——重启即清空,多实例不共享。
(微信投递游标 `last_msg_id` 例外,它是落库的。)不要引入需要跨进程一致性的设计。
2. **配置冷加载**。`config.js` 的 `DEFAULTS` 在启动时 deep-merge 并校验;改 `config.yml` 后必须
重启。例外(写盘后热生效):用户增删改(`routes/users.js`)、改自己的密码、技能列表刷新。
3. **密钥边界**。`config.yml`、`.env`、`wxbot/data/` 都是敏感数据:不提交、不打印、不挂给
不需要它的容器。`GET /api/config` 已脱敏,别绕过它把 `api_key` 回显给前端。
4. **单租户**。除配置 / 用户管理 / 重启等管理员接口外,会话、消息、文件、技能 API **只校验已登录**,
不按用户做资源级授权(按用户的会话列表隔离在前端查询层)。不要把这个实例开放给互不信任的用户。
5. **executor 隔离不可降级**。命令必须在 mount/pid namespace 内跑;只在会话目录可见。任何
"为了调试方便加个直通" 的改动都会把其它会话的数据暴露给 AI 命令。
6. **模型池 key 是共享并发资源**。没有排队、没有独占、没有租约。调度只在多个 key 之间按
「回合中会话数 → 在用会话数 → 最久未用」择优(详见 `app/AGENTS.md`)。
7. **运行时目录不入库**。`tasks/`、`data/`、`skills/deps/`、`wxbot/data/` 已被 gitignore;
不要把样例任务、数据库、密钥当成源码提交。
8. **设备是远端 shell**。`device exec` 在设备上就是 `sh -c` / `cmd /c`;`root` 只约束**起始
cwd**,命令里 `cd /etc` 照样能跑。`DEVICE_TOKEN` 泄漏等价于那台机器的 shell 泄漏,按这个等级管理。
9. **工具 schema 是每轮全量重发的上下文成本**。新增工具前先读 `docs/tool-design.md`:能用已有工具
的 `op` 扩展就不要新开工具。
## 开发与验证
```bash
# 本地跑 core(无容器;默认路径是容器内路径,本地调试要改 workspace_root/data_root)
cd app && npm install
AGENT_CONFIG=./config.yml node server/server.js
# 容器栈
docker compose up -d --build
docker compose logs -f agent-core
curl -s http://127.0.0.1:8090/api/health
```
- 本仓库**没有单元测试框架**,也没有 lint。唯一的自动化验证是 `executor/smoke-test.js`
(覆盖 executor 的鉴权、隔离、取消;隔离用例需 root/CAP_SYS_ADMIN,无权限时自动 SKIP):
```bash
cd executor && node smoke-test.js
```
- 改完 JS 至少做语法自检:`node --check <file>`。
- 排查时先看日志等级:core 用 `config.yml` 的 `log_level`(`debug` 会打印完整交互、SSE 帧、
工具参数),executor / wxbot 用各自的 `*_LOG_LEVEL`。
- 启动会在 `data/prompt.txt` dump 实际下发的 system prompt 与各 profile 的工具清单——核对
"模型到底看到了什么"时看它,不要猜。
## 修改时的同步清单
这些地方是"同一事实的多份表述",改一处要顺手改另一处:
| 改动 | 需要同步 |
|---|---|
| 配置默认值 | `app/server/config.js` 的 `DEFAULTS` ↔ `app/config.example.yml` |
| 内置工具 | `app/server/tools/definitions.json` ↔ `app/AGENTS.md` / README 工具表 ↔ `docs/tool-design.md` 规范 |
| 新增服务 / 端口 / 卷 | `docker-compose.yml` ↔ `README.md` 的部署与安全章节 |
| 隧道 token | `tunnel/data/server.yml`(自动生成)↔ `tunnel/client.yml`(手写),两边必须一致 |
| 新增环境变量 | compose ↔ README「环境变量」 |
| 发版号 | `app/package.json` 的 `version` ↔ `app/server/routes/system.js` 的 `VERSION` 字面量(两者不自动同步) |
| 技能格式 | `skills/README.md` ↔ `app/server/tools/skills.js` 的解析 |
| 同栈 MCP 的 url / header 名 | `app/server/presets.json` ↔ `mcp/<服务>/src`(设置页引导表单的字段来自前者,不会自动跟随后者) |
| 对外 API | `app/server/routes/*` ↔ 前端 `app/server/public/js/*` ↔ README |
## 代码约定
- **注释与用户可见文案用中文**。注释不是复述代码,而是记录"为什么这么做 / 踩过什么坑";本仓库
大量关键约束只写在注释里,改逻辑前先读该文件头与函数上方注释。
- 错误统一抛 `Error` 并可选挂 `status_code`;HTTP 层回 `{ error: string }`。工具层错误以
`Error: ...` 文本形式回给模型(模型能读懂并自我纠正)。
- 定时器一律 `unref()`,fire-and-forget 的后台任务(标题、日记、通知)绝不阻塞消息主路径。
- 需要反向依赖时用**注入**而不是 `require` 成环:`engine` 不 require `wechat`/`scheduler`,
由 `server.js` 传函数进去。
- 前端是**无构建的经典脚本**:新增文件要同时改 `app/server/public/index.html` 的 `<script>`
顺序(共享全局作用域,顺序即依赖)。
- 前端图标统一走 `index.html` 顶部的 `<symbol>` sprite:引用写成
`<svg class="…" viewBox="0 0 24 24"><use href="#i-xxx"/></svg>`,形状只改 sprite 里那一行,
尺寸与描边归各处 CSS(`.ic` / `.tree-act svg` 等)。加图标先加 `<symbol id="i-xxx">`,
漏了不报错、界面只是空白。
## 常见任务去哪改
| 想做的事 | 起点 |
|---|---|
| 加一个给模型的工具 | `app/server/tools/definitions.json` + `app/server/tools/executor.js` 的 `HANDLERS` |
| 加一个 HTTP 接口 | `app/server/routes/` 新建/修改 router,在 `app/server/server.js` 挂载 |
| 加一个配置项 | `app/server/config.js` 的 `DEFAULTS` + `app/config.example.yml` |
| 改模型调度 / 绑定 | `app/server/engine.js` 的 `chooseKey` / `chooseModel` / `ensureBinding` |
| 改上下文组装 / 省 token | `app/server/llm.js` 的 `buildMessages` / `trim*` |
| 改微信投递 | `app/server/wechat.js`(业务)+ `app/server/routes/wechat.js`(HTTP/鉴权) |
| 改语音输入 | `app/server/public/js/voice.js`(录音与插入)+ `app/server/routes/asr.js`(代理)+ `mcp/asr/`(转写);客户端桥契约见 `docs/voice-input.md` |
| 改隔离执行 | `executor/server.js`(先读顶部安全模型注释) |
| 改设备执行 / 文件传输 | `app/server/devices.js`(连接表 + exec/health/pull/push)+ `app/server/tools/executor.js` 的 `toolDevice` |
| 改设备端行为 | `device/cmd/agent/`(协议 `device/pkg/proto`,连接基座 `device/pkg/wsnode`) |
| 改隧道路由 / 转发 | `tunnel/server.js`(按 Host / 端口匹配)+ `tunnel/client.js`(本地服务映射) |
| 加同栈 MCP 服务 | `mcp/<name>/` + `docker-compose.yml` + `config.yml` 的 `mcp_servers` |
| 加技能 | `skills/<name>/`(`SKILL.md` + `run.py`),见 `skills/README.md` |