Skip to content

node-windows.md

Latest commit

 

History

History
53 lines (32 loc) · 5.61 KB

node-windows.md

File metadata and controls

53 lines (32 loc) · 5.61 KB
Raw

独立节点小窗

在本机 AgentPark 网页中右键节点，选择“弹出节点”。小窗置顶、可拖动及调整大小；关闭网页后小窗继续使用 AgentPark 后台。后台服务仍须运行。

点击节点展开聊天，使用与网页相同的 MemoryPanel、NodeInputDock 和 ConversationWindow。点击“收起”返回节点，保留未发送的输入与附件。收起状态没有额外的移动手柄和顶部关闭按钮，直接拖动节点卡片即可移动小窗；拖动不会误触打开聊天。卡片里的红色 × 只关闭小窗，不删除节点，也不停止任务。网页画布中的红色 × 仍用于删除节点。Trigger、暂停、输入等控件不会触发拖动。

work_persisted_alert 到达后，节点头顶显示 !。只有成功读取消息历史、聊天可见且窗口获得焦点时，才清除对应的未读标记。读取期间有更新的落盘事件到达时，旧读取不会清除新提醒。标记存储在当前客户端的本地存储中，重新打开小窗后保留；浏览器与桌面程序使用各自的存储。

安装与启动

弹出节点的注释放在主体上方的独立区域，复用画布注释的样式和换行。窗口按实际注释高度留出空间；超过 240px 的长注释可以滚动阅读全部内容。修改注释、调整宽度或从聊天收起时同步所需空间，并保留手动调整过的节点主体大小。

Windows 开发环境需 Node.js 22.12 或以上。build_and_run.bat 在检查 Node.js/npm 后自动准备节点小窗依赖，Restart.bat 也会走该流程。运行环境缺失或 Electron 版本不符时按 lockfile 安装；版本已就绪时跳过下载。安装失败会中止启动并输出错误。Git 不包含 node_modules，换电脑拉取后由该启动流程安装。

仅手动准备小窗依赖和构建页面时，在项目根目录执行：

npm ci --prefix desktop/node-window
npm --prefix webui run build

Electron 二进制下载与 npm 包下载是两个阶段。安装入口会按项目 network.httpProxy、代理环境变量、npm 代理、Windows 已启用的手动系统代理的顺序选择现有配置，并开启 Electron 下载器的代理支持；不会设置固定代理端口或修改系统设置。日志打印代理来源，不打印凭据。下载失败时保留目标主机和底层错误码（如 DNS、连接或证书错误），安装仍然失败退出，不能将缺失运行文件视为就绪。PAC 自动配置不在此处执行；可以通过项目或环境变量明确配置 HTTP(S) 代理。

新增后端接口首次使用前需重启 AgentPark。桌面依赖不从旧 desktop/pet 目录加载。桌面宿主日志位于 .runtime/node-windows/host.log。安装脚本获取 Electron 本身的运行文件，界面及 Agent 请求继续走现有 WebUI 和后端 API。

窗口边缘与布局记忆

节点小窗的四条可见边框使用 12px 宽的缩放热区，四个圆角使用 24px 的热区，不需要寻找透明留白外沿的系统缩放点。拖动边缘只调整窗口尺寸，不触发卡片移动或内容点击。

关闭小窗时，宿主按服务地址、画布和节点保存窗口位置与尺寸，记录位于 .runtime/node-window-profile/window-layouts.json。再次打开同一节点时恢复布局，包括全部小窗关闭、宿主退出后的重新打开。节点重命名时迁移记录；不同节点和画布分别保存。恢复时会将窗口限制在当前显示器工作区内，注释高度变化仍按实际差值调整。

更新这部分代码后，需要关闭所有已有节点小窗，再从网页弹出，以加载新的宿主和 preload 接口。

模块边界

  • src/web_backend/node_window_api.py：仅允许本机请求，从实际监听端口构造回环地址，验证节点存在，启动宿主并等待渲染就绪回执。
  • desktop/node-window/：独立 Electron 进程；每个服务器、画布、节点只有一个窗口，重复弹出聚焦原窗口。管理窗口大小、置顶、原生拖动与受限的窗口 IPC，不包含 Agent 推理或另一套聊天逻辑。
  • webui/src/NodeWindowWorkspace.vue：独立页面实例，复用节点运行状态、配置、聊天、输入与事件流。通过 preload 明确识别桌面模式，小窗口不会误切换到移动端。
  • useNodeUnread / useMemoryUnread：未读落盘回执与可见阅读确认；与临时 Toast 生命周期分离。

关闭窗口不会发出停止节点请求。切换到其他软件不会暂停事件流。主页面不需要保持打开。每次打开都显式绑定目标画布和节点，不修改默认启动画布。重命名通过节点事件同步窗口身份；删除或移出节点时显示明确错误。

不同节点可以同时开启小窗，未设置固定数量上限；实际数量受系统内存等资源约束。重复打开相同服务器、画布和节点时只聚焦已有窗口。修改桌面宿主或 preload 后必须关闭所有旧小窗再重新弹出，旧宿主不会自动更新；只刷新网页可能造成新版页面等待旧宿主响应。正常开窗接口会等到节点渲染就绪再返回，不能用进程已创建冒充成功。

验证

npm --prefix desktop/node-window test
npm --prefix webui test -- --project unit
python -m pytest tests/test_node_window_api.py tests/test_http_transport_boundary.py tests/test_webui_node_notes.py -q

桌面验收应覆盖：网页右键弹出、关闭网页后继续使用、打开/收起聊天保留草稿、实际落盘出现感叹号、阅读成功后清除、连续两次落盘、后台完成消息、多个节点同时悬浮、重复弹出、窗口缩放、节点重命名与删除。