docs: 补齐 tunnel 模块,更新 SSE 合并与文件面板懒加载
- README:组成表加 tunnel/;本机运行补隧道 client;安全边界补隧道 - AGENTS:仓库结构、运行时拓扑、端口表、数据持久化、同步清单、常见任务补 tunnel - local/README:可选能力与安全边界补隧道 - app/AGENTS:sse.js 补高频事件合并;前端补文件面板按目录懒加载
This commit is contained in:
@@ -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` |
|
||||||
|
|||||||
@@ -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
@@ -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`。
|
||||||
|
|
||||||
## 扩展指南
|
## 扩展指南
|
||||||
|
|
||||||
|
|||||||
@@ -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` 不启动(它转码要靠
|
||||||
|
|||||||
Reference in New Issue
Block a user