docs: 补齐 tunnel 模块,更新 SSE 合并与文件面板懒加载

- README:组成表加 tunnel/;本机运行补隧道 client;安全边界补隧道
- AGENTS:仓库结构、运行时拓扑、端口表、数据持久化、同步清单、常见任务补 tunnel
- local/README:可选能力与安全边界补隧道
- app/AGENTS:sse.js 补高频事件合并;前端补文件面板按目录懒加载
This commit is contained in:
2026-11-15 15:16:54 +08:00
parent 67d3355f44
commit ac052d6997
4 changed files with 20 additions and 2 deletions
+9 -1
View File
@@ -25,6 +25,7 @@
| `mcp/` | 同栈 MCP 服务:`web_search` / `image_task` / `video_task` / `asr` | 四个容器,仅内网 | | `mcp/` | 同栈 MCP 服务:`web_search` / `image_task` / `video_task` / `asr` | 四个容器,仅内网 |
| `skills/` | 目录式技能(`SKILL.md` + `run.py`/`run.sh`) | 运行时挂载,`skills/deps` 为依赖层 | | `skills/` | 目录式技能(`SKILL.md` + `run.py`/`run.sh`) | 运行时挂载,`skills/deps` 为依赖层 |
| `local/` | **本地端启动器**:同一份代码跑在本机(不起 Docker / executor),`start.sh` 负责探测、装依赖、守护 | 独立于 compose,见 `docs/local-mode.md` | | `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` 裸机初始化 | 幂等,**不覆盖已有配置** | | `scripts/` | `init.sh` 生成 `.env` + 首次创建 `config.yml`(仅初始管理员);`init_host.sh` 裸机初始化 | 幂等,**不覆盖已有配置** |
| `docs/` | 专题文档:`tool-design.md`(工具接口规范)、`OFFICE.md` | — | | `docs/` | 专题文档:`tool-design.md`(工具接口规范)、`OFFICE.md` | — |
| `tasks/` | **运行时数据**:每个会话一个工作目录 | gitignore | | `tasks/` | **运行时数据**:每个会话一个工作目录 | gitignore |
@@ -38,10 +39,13 @@
```mermaid ```mermaid
flowchart TD flowchart TD
CORE["agent-core(8090,唯一对外端口)"]
B["浏览器 / PWA"] -->|"HTTP + SSE"| CORE B["浏览器 / PWA"] -->|"HTTP + SSE"| CORE
M["手机 / 外网"] -->|"HTTPS"| TUN["tunnel server(19000,仅回环)"]
TUN -->|"WebSocket"| TC["tunnel client(本机)"]
TC -->|"HTTP"| CORE
W["微信客户端"] --> WXBOT["agent-wxbot(8093,仅内网)"] W["微信客户端"] --> WXBOT["agent-wxbot(8093,仅内网)"]
WXBOT -->|"回调 /wxhook/*(共享 Bearer token)"| CORE WXBOT -->|"回调 /wxhook/*(共享 Bearer token)"| CORE
CORE["agent-core(8090,唯一对外端口)"]
CORE --> EXEC["agent-executor(9000 exec / 3100 预览,仅内网)"] CORE --> EXEC["agent-executor(9000 exec / 3100 预览,仅内网)"]
CORE --> MCP["mcp_web_search / mcp_image_task / mcp_video_task / mcp_asr(3000,仅内网)"] CORE --> MCP["mcp_web_search / mcp_image_task / mcp_video_task / mcp_asr(3000,仅内网)"]
CORE -->|"分段投递回复"| WXBOT CORE -->|"分段投递回复"| WXBOT
@@ -59,6 +63,7 @@ flowchart TD
| 服务 | 端口 | 可见性 | | 服务 | 端口 | 可见性 |
|---|---|---| |---|---|---|
| `agent-core` | 8090 | 宿主机映射,**唯一对外** | | `agent-core` | 8090 | 宿主机映射,**唯一对外** |
| `tunnel` server | 19000 | 仅 `127.0.0.1`,对外经 nginx 反代 |
| `agent-executor` | 9000(exec)、3100(预览网关) | 仅 `expose`,内网 | | `agent-executor` | 9000(exec)、3100(预览网关) | 仅 `expose`,内网 |
| `agent-wxbot` | 8093 | 仅内网 | | `agent-wxbot` | 8093 | 仅内网 |
| `mcp_*` | 3000 | 仅内网 | | `mcp_*` | 3000 | 仅内网 |
@@ -72,6 +77,7 @@ flowchart TD
| `./skills/` | `/workspace/skills` | `/workspace/skills:ro` | 技能与共享依赖 | | `./skills/` | `/workspace/skills` | `/workspace/skills:ro` | 技能与共享依赖 |
| `./config.yml` | `/app/config.yml` | 不挂、不读 | 平台密钥、登录密钥 | | `./config.yml` | `/app/config.yml` | 不挂、不读 | 平台密钥、登录密钥 |
| `./app/server/` | `/app/server` | — | 后端代码(**热挂载**) | | `./app/server/` | `/app/server` | — | 后端代码(**热挂载**) |
| `./tunnel/data/` | — | — | 隧道服务端配置 `server.yml`(首次启动自动生成,含 token) |
| `./wxbot/data/` | — | `/data`(wxbot) | 微信登录凭证 | | `./wxbot/data/` | — | `/data`(wxbot) | 微信登录凭证 |
推论: 推论:
@@ -163,6 +169,7 @@ curl -s http://127.0.0.1:8090/api/health
| 配置默认值 | `app/server/config.js` 的 `DEFAULTS` ↔ `app/config.example.yml` | | 配置默认值 | `app/server/config.js` 的 `DEFAULTS` ↔ `app/config.example.yml` |
| 内置工具 | `app/server/tools/definitions.json` ↔ `app/AGENTS.md` / README 工具表 ↔ `docs/tool-design.md` 规范 | | 内置工具 | `app/server/tools/definitions.json` ↔ `app/AGENTS.md` / README 工具表 ↔ `docs/tool-design.md` 规范 |
| 新增服务 / 端口 / 卷 | `docker-compose.yml` ↔ `README.md` 的部署与安全章节 | | 新增服务 / 端口 / 卷 | `docker-compose.yml` ↔ `README.md` 的部署与安全章节 |
| 隧道 token | `tunnel/data/server.yml`(自动生成)↔ `tunnel/client.yml`(手写),两边必须一致 |
| 新增环境变量 | compose ↔ README「环境变量」 | | 新增环境变量 | compose ↔ README「环境变量」 |
| 发版号 | `app/package.json` 的 `version` ↔ `app/server/routes/system.js` 的 `VERSION` 字面量(两者不自动同步) | | 发版号 | `app/package.json` 的 `version` ↔ `app/server/routes/system.js` 的 `VERSION` 字面量(两者不自动同步) |
| 技能格式 | `skills/README.md` ↔ `app/server/tools/skills.js` 的解析 | | 技能格式 | `skills/README.md` ↔ `app/server/tools/skills.js` 的解析 |
@@ -197,5 +204,6 @@ curl -s http://127.0.0.1:8090/api/health
| 改微信投递 | `app/server/wechat.js`(业务)+ `app/server/routes/wechat.js`(HTTP/鉴权) | | 改微信投递 | `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` | | 改语音输入 | `app/server/public/js/voice.js`(录音与插入)+ `app/server/routes/asr.js`(代理)+ `mcp/asr/`(转写);客户端桥契约见 `docs/voice-input.md` |
| 改隔离执行 | `executor/server.js`(先读顶部安全模型注释) | | 改隔离执行 | `executor/server.js`(先读顶部安全模型注释) |
| 改隧道路由 / 转发 | `tunnel/server.js`(按 Host / 端口匹配)+ `tunnel/client.js`(本地服务映射) |
| 加同栈 MCP 服务 | `mcp/<name>/` + `docker-compose.yml` + `config.yml` 的 `mcp_servers` | | 加同栈 MCP 服务 | `mcp/<name>/` + `docker-compose.yml` + `config.yml` 的 `mcp_servers` |
| 加技能 | `skills/<name>/`(`SKILL.md` + `run.py`),见 `skills/README.md` | | 加技能 | `skills/<name>/`(`SKILL.md` + `run.py`),见 `skills/README.md` |
+4
View File
@@ -28,6 +28,8 @@ macOS / Linux,Node 20+,不需要 Docker:
首次运行会让你选一个工作目录(技能、会话、数据库都在里面)。命令直接在本机执行,没有沙箱隔离,只监听 `127.0.0.1`。 首次运行会让你选一个工作目录(技能、会话、数据库都在里面)。命令直接在本机执行,没有沙箱隔离,只监听 `127.0.0.1`。
需要从外网访问时,配好 [`tunnel/client.yml`](tunnel/README.md) 后 `start.sh` 会一并拉起隧道 client;未配置则跳过。
## 组成 ## 组成
| 目录 | 说明 | | 目录 | 说明 |
@@ -38,6 +40,7 @@ macOS / Linux,Node 20+,不需要 Docker:
| [`mcp/`](mcp/README.md) | 四个 MCP 服务:网页搜索、图片生成、视频生成、语音转写 | | [`mcp/`](mcp/README.md) | 四个 MCP 服务:网页搜索、图片生成、视频生成、语音转写 |
| [`skills/`](skills/README.md) | 内置技能 | | [`skills/`](skills/README.md) | 内置技能 |
| [`local/`](local/README.md) | 本机模式启动器 | | [`local/`](local/README.md) | 本机模式启动器 |
| [`tunnel/`](tunnel/README.md) | 反向隧道:把本机服务经服务器中转,供外网访问 |
## 配置 ## 配置
@@ -68,6 +71,7 @@ docker compose up -d --build
## 安全 ## 安全
- 对外只开 agent-core 一个端口,其余服务只在 Docker 内网 - 对外只开 agent-core 一个端口,其余服务只在 Docker 内网
- 隧道只经服务器 nginx(TLS)对外,宿主机端口仅绑 `127.0.0.1`;`server.yml` 与 `client.yml` 的 token 必须一致
- 命令在 executor 容器里执行,只挂当前会话目录,根文件系统只读 - 命令在 executor 容器里执行,只挂当前会话目录,根文件系统只读
- 单租户设计:除管理员接口外不做用户级资源隔离,不要开放给互不信任的人 - 单租户设计:除管理员接口外不做用户级资源隔离,不要开放给互不信任的人
- `config.yml`、`.env`、`wxbot/data/` 存密钥,已加入 `.gitignore` - `config.yml`、`.env`、`wxbot/data/` 存密钥,已加入 `.gitignore`
+3 -1
View File
@@ -51,7 +51,7 @@ AGENT_CONFIG=./config.yml node server/server.js
| `server/wechat.js` | 微信绑定、媒体落盘、上下文注入、SSE→微信分段投递、任务通知 | | `server/wechat.js` | 微信绑定、媒体落盘、上下文注入、SSE→微信分段投递、任务通知 |
| `server/routes/channel.js` | 文本命令层(`/new` `/switch` `/think` …),微信与外部接入端共用 | | `server/routes/channel.js` | 文本命令层(`/new` `/switch` `/think` …),微信与外部接入端共用 |
| `server/routes/*.js` | HTTP API,按资源分文件 | | `server/routes/*.js` | HTTP API,按资源分文件 |
| `server/sse.js` | 按会话分组的 SSE 总线(`addClient`/`emit`/`onInternal`) | | `server/sse.js` | 按会话分组的 SSE 总线(`addClient`/`emit`/`onInternal`);`assistant_delta` / `reasoning_delta` / `tool_call_args` 攒 50ms 或 8 条合并写入 |
| `server/auth.js` | HMAC cookie 登录、Basic 兜底、`requireAdmin`、免认证路径 | | `server/auth.js` | HMAC cookie 登录、Basic 兜底、`requireAdmin`、免认证路径 |
| `server/memory.js` | 长期记忆(日记碎片)读写与检索,仅依赖 `time.js` | | `server/memory.js` | 长期记忆(日记碎片)读写与检索,仅依赖 `time.js` |
| `server/time.js` | 业务时区单一入口:`TZ`、`dayString`、`stampString`、`fmtTime`、`fmtIso` | | `server/time.js` | 业务时区单一入口:`TZ`、`dayString`、`stampString`、`fmtTime`、`fmtIso` |
@@ -354,6 +354,8 @@ preview-proxy.mount(末尾兜底)
JS/CSS 改动不需要。 JS/CSS 改动不需要。
- 另有 `login.html`、`memory.html`(日记调试页)。 - 另有 `login.html`、`memory.html`(日记调试页)。
- API 调用统一走 `core.js` 的 `req()`;SSE 用 `EventSource` + 前端看门狗。 - API 调用统一走 `core.js` 的 `req()`;SSE 用 `EventSource` + 前端看门狗。
- 文件面板(`files.js`)按目录懒加载:只请求 `GET /api/sessions/:id/tree?dir=<rel>` 的当前层,
进入子目录才拉下一层;会话详情接口不返回全量 `files`。
## 扩展指南 ## 扩展指南
+4
View File
@@ -72,6 +72,7 @@ cd agent
| Office 文档(docx/xlsx/pptx) | 首次用到时下载一次 officecli 二进制(约 34MB) | `office` 报 `binary missing` 并给出该技能 `AGENTS.md` 的路径,按它下载即可(不需 root、不需重启);预览面板里直接显示同一份安装说明 | | Office 文档(docx/xlsx/pptx) | 首次用到时下载一次 officecli 二进制(约 34MB) | `office` 报 `binary missing` 并给出该技能 `AGENTS.md` 的路径,按它下载即可(不需 root、不需重启);预览面板里直接显示同一份安装说明 |
| 网页搜索 | 无 | 装了 Node 就有(内置免费后端) | | 网页搜索 | 无 | 装了 Node 就有(内置免费后端) |
| 图片 / 视频生成 | 设置页给对应 MCP 填上游 key | 调用时报明确的缺参错误 | | 图片 / 视频生成 | 设置页给对应 MCP 填上游 key | 调用时报明确的缺参错误 |
| 反向隧道 | `tunnel/client.yml`(服务器地址 + token) | `start.sh` 跳过,不占端口;配置说明见 `tunnel/README.md` |
装完 `ffmpeg` 之后**重跑一次 `./local/start.sh`** 即可生效。`python3` 稍特殊:技能清单本来就在, 装完 `ffmpeg` 之后**重跑一次 `./local/start.sh`** 即可生效。`python3` 稍特殊:技能清单本来就在,
只要新装的解释器落在 core 启动时 `PATH` 已包含的目录里(如 brew 的 `/opt/homebrew/bin`)就无需重启; 只要新装的解释器落在 core 启动时 `PATH` 已包含的目录里(如 brew 的 `/opt/homebrew/bin`)就无需重启;
@@ -144,6 +145,9 @@ git pull
另外,`core` 只监听 `127.0.0.1`,同一局域网的人访问不到。 另外,`core` 只监听 `127.0.0.1`,同一局域网的人访问不到。
配了隧道后,core 会经隧道 client 暴露到公网域名。访问控制靠隧道 token + 上游 nginx 的 TLS;
入口仍是 `127.0.0.1:8090`,不额外监听端口。
## 已知限制 ## 已知限制
- **没 ffmpeg 时 core 日志会有一条 `asr 工具发现失败`**:此时 `mcp_asr` 不启动(它转码要靠 - **没 ffmpeg 时 core 日志会有一条 `asr 工具发现失败`**:此时 `mcp_asr` 不启动(它转码要靠