Skip to content

Latest commit

 

History

History
52 lines (34 loc) · 5.39 KB

requirements.md

File metadata and controls

52 lines (34 loc) · 5.39 KB

Node Agent API 当前需求

更新时间:2026-10-06。用户已明确修订:所有 bot,包括实验 A、B,沿用原始 GrokNode 的定义,桌面不同,容器和数据共用。本文件替代早期“每 bot 独立容器、数据卷与网络”的需求。

2026-10-08 修订:用户明确要求每个 API 会话可选择两种路径。backend:codex(默认)继续保留 Mac Harness;backend:grok 使用已有 sendPrompt/getAgentTranscript,直接共享对应 Bot 原生聊天和原生模型配置。原生输入允许发送到用户已运行的 Grok Node 容器,不再要求该输入路径是实验容器;此授权不扩展至 Bot 创建、容器管理或原程序修改。会话 backend 不可切换,既有 Harness 会话不迁移、不重放。

原程序不变

Node Agent API 是独立的外部服务,通过 GrokNode 已存在的接口读取 bot、桌面和运行时映射,再封装 API。不得修改原始 GrokNode 源码、Electron 包、登录与启动流程、bot 管理、桌面分配或盒子管理逻辑;不得注入补丁、替换 host/coordinator/daemon,或把 API 打进原 App。

API 不得改写原程序的设置、凭据和用户数据格式,也不得以 API 启动为由重启、重建或替换原容器。此前允许实验副本修改盒子管理和工具路由的约束已被本条取代。

允许继续维护独立 API、网页、CLI 包装与 Codex Harness 适配代码。原先已授权在 Linux 中安装的 Codex/exec-server 作为单独的附加进程管理,不能替换 GrokNode 的启动包、supervisor 或原有服务。

既有接口不足以支持某项能力时,记录限制并提供外部适配方案,不能通过改原程序补齐。已有实验副本源码改动保留为历史原型,不部署、不合入原程序;不能为了满足新约束直接丢弃旧修改。

目标行为

  1. GrokNode 管理 bot 身份及桌面分配。各 bot 共用同一盒子容器和数据;bot 数量增加不应相应创建容器、卷或网络。
  2. 每个 bot 使用 GrokNode 分配的桌面。网页、CLI、GrokNode 指向同一 bot 的同一桌面;复用现有分配与归属校验,不另建一套桌面编号规则。
  3. 数据与项目按原始 GrokNode 语义共享。不强制建立每 bot 私有数据卷或私有项目目录,不承诺阻止 bot 通过 Linux 工具访问其他 bot 的共享文件。
  4. Codex Harness、模型调用、对话与模型凭据留在 Mac。共享 Linux 盒子承担 shell、文件修改、构建和测试;执行端不可用时工具失败,不回落 Mac。
  5. 网页和 CLI 支持真实项目的对话、改代码、测试、审查和导出;保留各自会话身份,不能把多个 bot 的对话混成一个 thread。
  6. 封装整桌面和单应用窗口的 VNC 观看与实时操作。窗口必须来自该 bot 的实际桌面,并沿用短期授权、明确接管与交还。桌面区分是交互归属,不是 Linux 安全隔离。
  7. 剪贴板只在用户明确操作时传递,默认无自动同步。
  8. 文件、未提交修改、会话与日志可备份和恢复。运行中的进程按中断或未知处理,用户决定重跑;不承诺恢复进程内存。
  9. 多用户、API 权限、密钥轮换、配额、审计、签名 webhook 和 trace/usage 保留。API 的 bot 范围限制控制接口访问,不代表共享 Linux 文件系统提供 bot 间安全隔离。

保留的安全边界

隔离对象是 Linux 执行端与 Mac。Mac 模型凭据、主配置和宿主文件不能因为 API 接入而暴露给 Linux 执行端。现有共享盒子的宿主凭据挂载需要单独核实;“数据共用”不能自动解释为允许复制 Mac 模型凭据。

取消某一回合应使用 Harness 的取消机制,不能停止共享容器来代替取消。重建或维护共享盒子会影响所有 bot,应报告影响范围并先保全数据。

验收

  • 实验 A、B 使用同一容器与同一共享数据区;它们的桌面身份不同,并与 GrokNode 分配结果一致。
  • 从网页和 CLI 选择同一 bot,看到同一桌面及其真实应用窗口,执行代码落在共享 Linux 项目中。
  • 真实项目完成改代码、安装依赖、测试、差异审查与导出,未提交修改得到保全。
  • 观看、接管、交还、单应用窗口与手动剪贴板通过真实浏览器验收。
  • 断线、API 重启及盒子损坏后恢复文件、会话和日志,没有自动重放任务。
  • 执行端无法读取 Mac 模型凭据;远端失联后没有 Mac 工具回落。
  • API 用户、授权、轮换、配额和 webhook 通过接口与实际服务测试;未知结果保持未知。
  • README、OpenAPI、差距分析描述实际实现与证据,不把旧的双容器验收当作共享盒子的验收。

现有原型与迁移

当前默认 API 与 CLI 已使用原有共享盒子的外部适配。真实测试 bot A、B 共用 grok-node-local-vm 的数据,桌面由原 GrokNode 分配;单应用 VNC 与显式剪贴板已有验收记录。旧的每 bot 容器代码与备份保留为历史原型,不参与默认路径。

合并运行环境前,先保存 A、B 的共享项目候选内容、Git 历史、未提交修改、Mac thread 与日志。检查同名文件冲突,保留来源和备份,不能以覆盖文件或删除卷完成合并。

先用独立 API 对原程序已有接口完成适配和验证,再保全式迁移旧实验数据。整个接入过程保持原始 GrokNode 程序与管理机制不变。