# Node 模式部署与联调手册

## 使用场景

当你准备把 Jarvis Web Gateway 以主节点 / 子节点方式部署起来，并验证浏览器、Web 前端或 VSCode 插件是否能够按节点创建和访问 Agent 时，可以使用这份手册完成最小可用部署与联调。

## 部署目标

- 启动一个主节点 Gateway
- 启动一个或多个子节点 Gateway
- 让子节点成功接入主节点
- 通过主节点查看节点列表
- 通过 Web 前端或 VSCode 插件按节点创建 Agent
- 验证对远端子节点 Agent 的访问由主节点完成转发

## 操作步骤

### 1. 启动主节点

1. 在主节点机器上启动 Web Gateway。
2. 示例：`jarvis-service start --node-mode master`
3. 如有需要，再补充监听地址、端口和密码参数。

### 2. 启动子节点

1. 在子节点机器上启动 Web Gateway。
2. 示例：`jarvis-service start --node-mode child --node-id worker-01 --master-url ws://master-host:8000 --node-secret your_secret`
3. 确保子节点具备接入主节点所需的网络可达性与配置。

### 3. 验证子节点接入

1. 通过主节点提供的节点状态接口，或通过前端节点列表确认子节点已出现。
2. 如果主节点看不到子节点，优先检查：
   - 主子节点网络是否互通
   - 子节点是否已成功登录主节点
   - 主节点与子节点是否处于兼容版本

### 4. 通过 Web 前端联调

1. 浏览器连接主节点。
2. 打开创建 Agent 弹窗。
3. 在“目标节点”中选择某个子节点。
4. 创建 Agent 后，确认列表中出现节点标识。
5. 打开该 Agent 并继续发送消息，确认交互正常。

### 5. 通过 VSCode 插件联调

1. 在 VSCode 插件中连接主节点。
2. 打开创建 Agent 表单。
3. 选择目标节点并创建 Agent。
4. 在插件列表中确认新 Agent 带有对应节点标识。
5. 打开 Agent 聊天面板并继续交互。

## 你会看到的提示与反馈

- 主节点上会看到已接入的子节点信息。
- 创建到子节点的 Agent 会显示对应 `node_id`。
- 浏览器与 VSCode 插件都只需要连接主节点，但可以无感访问子节点上的 Agent。

## 联调检查清单

- 主节点是否成功启动
- 子节点是否成功启动
- 子节点是否出现在主节点节点列表中
- Web 前端是否能选择目标节点
- VSCode 插件是否能选择目标节点
- 创建到子节点的 Agent 是否显示正确节点归属
- 与子节点 Agent 的消息交互是否正常
- 复制 Agent 后节点归属是否符合预期

## 注意事项

- 单节点模式下，可继续把当前节点视为主节点使用。
- 如果子节点接入失败，客户端侧通常只会看到主节点上的 Agent。
- token 对齐与主子节点长连接属于系统内部机制，日常使用时通常不需要手工干预。
- 当前若未进行真实端到端联调，请把结果标记为“已完成文档与静态适配，待实机联调验证”。
