diff --git a/AGENTS.md b/AGENTS.md index 92808f1..511ea1d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,7 @@ | `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 | @@ -38,10 +39,13 @@ ```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["agent-core(8090,唯一对外端口)"] CORE --> EXEC["agent-executor(9000 exec / 3100 预览,仅内网)"] CORE --> MCP["mcp_web_search / mcp_image_task / mcp_video_task / mcp_asr(3000,仅内网)"] CORE -->|"分段投递回复"| WXBOT @@ -59,6 +63,7 @@ flowchart TD | 服务 | 端口 | 可见性 | |---|---|---| | `agent-core` | 8090 | 宿主机映射,**唯一对外** | +| `tunnel` server | 19000 | 仅 `127.0.0.1`,对外经 nginx 反代 | | `agent-executor` | 9000(exec)、3100(预览网关) | 仅 `expose`,内网 | | `agent-wxbot` | 8093 | 仅内网 | | `mcp_*` | 3000 | 仅内网 | @@ -72,6 +77,7 @@ flowchart TD | `./skills/` | `/workspace/skills` | `/workspace/skills:ro` | 技能与共享依赖 | | `./config.yml` | `/app/config.yml` | 不挂、不读 | 平台密钥、登录密钥 | | `./app/server/` | `/app/server` | — | 后端代码(**热挂载**) | +| `./tunnel/data/` | — | — | 隧道服务端配置 `server.yml`(首次启动自动生成,含 token) | | `./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/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` 的解析 | @@ -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/public/js/voice.js`(录音与插入)+ `app/server/routes/asr.js`(代理)+ `mcp/asr/`(转写);客户端桥契约见 `docs/voice-input.md` | | 改隔离执行 | `executor/server.js`(先读顶部安全模型注释) | +| 改隧道路由 / 转发 | `tunnel/server.js`(按 Host / 端口匹配)+ `tunnel/client.js`(本地服务映射) | | 加同栈 MCP 服务 | `mcp//` + `docker-compose.yml` + `config.yml` 的 `mcp_servers` | | 加技能 | `skills//`(`SKILL.md` + `run.py`),见 `skills/README.md` | diff --git a/README.md b/README.md index 2240bda..f0f8f8a 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ macOS / Linux,Node 20+,不需要 Docker: 首次运行会让你选一个工作目录(技能、会话、数据库都在里面)。命令直接在本机执行,没有沙箱隔离,只监听 `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 服务:网页搜索、图片生成、视频生成、语音转写 | | [`skills/`](skills/README.md) | 内置技能 | | [`local/`](local/README.md) | 本机模式启动器 | +| [`tunnel/`](tunnel/README.md) | 反向隧道:把本机服务经服务器中转,供外网访问 | ## 配置 @@ -68,6 +71,7 @@ docker compose up -d --build ## 安全 - 对外只开 agent-core 一个端口,其余服务只在 Docker 内网 +- 隧道只经服务器 nginx(TLS)对外,宿主机端口仅绑 `127.0.0.1`;`server.yml` 与 `client.yml` 的 token 必须一致 - 命令在 executor 容器里执行,只挂当前会话目录,根文件系统只读 - 单租户设计:除管理员接口外不做用户级资源隔离,不要开放给互不信任的人 - `config.yml`、`.env`、`wxbot/data/` 存密钥,已加入 `.gitignore` diff --git a/app/AGENTS.md b/app/AGENTS.md index 4f4bb06..c35e9b6 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -51,7 +51,7 @@ AGENT_CONFIG=./config.yml node server/server.js | `server/wechat.js` | 微信绑定、媒体落盘、上下文注入、SSE→微信分段投递、任务通知 | | `server/routes/channel.js` | 文本命令层(`/new` `/switch` `/think` …),微信与外部接入端共用 | | `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/memory.js` | 长期记忆(日记碎片)读写与检索,仅依赖 `time.js` | | `server/time.js` | 业务时区单一入口:`TZ`、`dayString`、`stampString`、`fmtTime`、`fmtIso` | @@ -354,6 +354,8 @@ preview-proxy.mount(末尾兜底) JS/CSS 改动不需要。 - 另有 `login.html`、`memory.html`(日记调试页)。 - API 调用统一走 `core.js` 的 `req()`;SSE 用 `EventSource` + 前端看门狗。 +- 文件面板(`files.js`)按目录懒加载:只请求 `GET /api/sessions/:id/tree?dir=` 的当前层, + 进入子目录才拉下一层;会话详情接口不返回全量 `files`。 ## 扩展指南 diff --git a/local/README.md b/local/README.md index 8440e7d..7fb464f 100644 --- a/local/README.md +++ b/local/README.md @@ -72,6 +72,7 @@ cd agent | Office 文档(docx/xlsx/pptx) | 首次用到时下载一次 officecli 二进制(约 34MB) | `office` 报 `binary missing` 并给出该技能 `AGENTS.md` 的路径,按它下载即可(不需 root、不需重启);预览面板里直接显示同一份安装说明 | | 网页搜索 | 无 | 装了 Node 就有(内置免费后端) | | 图片 / 视频生成 | 设置页给对应 MCP 填上游 key | 调用时报明确的缺参错误 | +| 反向隧道 | `tunnel/client.yml`(服务器地址 + token) | `start.sh` 跳过,不占端口;配置说明见 `tunnel/README.md` | 装完 `ffmpeg` 之后**重跑一次 `./local/start.sh`** 即可生效。`python3` 稍特殊:技能清单本来就在, 只要新装的解释器落在 core 启动时 `PATH` 已包含的目录里(如 brew 的 `/opt/homebrew/bin`)就无需重启; @@ -144,6 +145,9 @@ git pull 另外,`core` 只监听 `127.0.0.1`,同一局域网的人访问不到。 +配了隧道后,core 会经隧道 client 暴露到公网域名。访问控制靠隧道 token + 上游 nginx 的 TLS; +入口仍是 `127.0.0.1:8090`,不额外监听端口。 + ## 已知限制 - **没 ffmpeg 时 core 日志会有一条 `asr 工具发现失败`**:此时 `mcp_asr` 不启动(它转码要靠