agent-workbench-connector 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +26 -10
  2. package/dist/agent.mjs +1964 -317
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -6,27 +6,39 @@
6
6
 
7
7
  ## 安装与启动
8
8
 
9
- 发布到 npm 后安装:
9
+ 推荐在工作台“设备与 Agent → 连接设备”点击“生成并复制部署命令”,在开发机终端粘贴运行。命令使用 Node.js 自带的 `npx` 获取最新连接器,兑换服务端的临时令牌后直接启动,无需密码、配置文件或全局安装。支持 macOS、Linux 和 Windows PowerShell,Google 登录账号也适用。
10
+
11
+ `--connect` 默认启动后台进程,在服务器确认设备上线后返回命令提示符,可以关闭终端。终端会显示连接标识、日志路径及停止命令。查看与停止方式:
10
12
 
11
13
  ```bash
12
- npm install -g agent-workbench-connector
14
+ npx --yes agent-workbench-connector@latest --status
15
+ npx --yes agent-workbench-connector@latest --stop <连接标识>
13
16
  ```
14
17
 
15
- 尚未发布到 registry 时,可直接安装维护者提供的安装包:
18
+ 日志和本机控制信息位于 `~/.workflow-data/connectors/`,仅当前用户可读;控制信息不包含工作台登录凭据或设备会话令牌。停止会取消同步、关闭连接并保留待核对的执行状态,不会自动重发 Agent 指令。重复连接同一设备会明确失败;先正常停止旧连接器,再生成新的部署命令。旧版前台进程仍需 Ctrl+C 退出。后台进程崩溃后可重新生成命令启动,状态查询会标为已停止。后台运行不是系统服务,不会在退出系统登录或电脑重启后自动恢复;24 小时设备会话过期后也需重新生成命令。
16
19
 
17
- ```bash
18
- npm install -g ./agent-workbench-connector-0.3.0.tgz
19
- ```
20
+ 排查时在部署命令末尾添加 `--foreground`,保持前台输出并用 Ctrl+C 停止;配置文件启动方式仍默认保持前台运行。后台启动失败会显示原因和日志路径,不会自动重试令牌兑换或切换连接方式。本机控制通道仅监听 `127.0.0.1`,通过独立随机密钥校验状态与停止请求,不根据持久化 PID 杀进程。控制端口由设备状态目录确定并由操作系统独占,异常退出会释放;若与其他本机程序端口冲突,会明确失败,需先检查并释放提示的端口。
21
+
22
+ `--connect <页面生成的参数>` 携带工作台地址、一次性临时令牌和有效期,不包含浏览器会话或账号密码。令牌最长 10 分钟有效,重新生成后旧命令失效。命令包含接入凭据,请勿分享;跨设备使用 HTTPS,回环地址可用 HTTP。兑换成功后使用独立的 24 小时受限设备会话,仅保存在进程内存中,不写入文件。退出浏览器不影响已接入设备;账号停用、重置密码或撤销执行权限会使设备会话失效。退出连接器或授权失效后需在网页重新生成命令。
23
+
24
+ 兑换不会跟随重定向、自动重试或回退到密码登录。网络失败会提示结果未知并停止,不启动替代连接。该模式不读取默认配置文件,不使用环境中的旧账号密码或令牌,不能与 `--env-file` / `--once` 混用;其他高级环境变量仍保留。设备会话通过父子进程的私有 IPC 通道传递,不放入后台进程的命令参数、环境变量、日志或控制文件。先停止已有连接器再启动。
20
25
 
21
- 在工作台“设备与 Agent → 连接本机 Agent”复制登录配置,保存到任意目录的 `agent.env`,填写密码。在 macOS/Linux 上运行 `chmod 600 agent.env`,Windows 上将文件权限限制为当前用户可读,然后启动:
26
+ 维护者需先发布支持令牌版 `--connect` 的连接器,再部署带临时令牌接口、数据库迁移 008 及新版网页的工作台。未发布时,安装维护者提供的 tgz,使用 `agent-workbench-connector` 替换页面命令的 `npx --yes agent-workbench-connector@latest` 前缀。
27
+
28
+ 高级用户仍可使用配置文件:
22
29
 
23
30
  ```bash
31
+ pnpm add -g agent-workbench-connector
24
32
  agent-workbench-connector --env-file ./agent.env
25
33
  ```
26
34
 
35
+ 手动创建 `agent.env`,填写 `WORKBENCH_URL`、`WORKBENCH_USERNAME` 和 `WORKBENCH_PASSWORD`。macOS/Linux 使用 `chmod 600 agent.env`,Windows 将文件权限限制为当前用户可读。
36
+
27
37
  也可以把配置保存为 `~/.bugflow/agent.env`,然后直接运行 `agent-workbench-connector`。已有环境变量优先于文件;不自动加载当前目录的 `.env`。令牌登录仍支持 `WORKBENCH_TOKEN`。不要把密码或令牌放入命令行参数。
28
38
 
29
- 进程需要保持运行,按 Ctrl+C 正常退出。仅同步模式配置 `WORKBENCH_EXECUTE_CODEX=false` 后,可以使用 `agent-workbench-connector --env-file ./agent.env --once` 单次同步。`agent-workbench-connector --help` 查看参数,`agent-workbench-connector --version` 查看版本。
39
+ 配置文件方式的进程需要保持前台运行,按 Ctrl+C 正常退出。仅同步模式配置 `WORKBENCH_EXECUTE_CODEX=false` 后,可以使用 `agent-workbench-connector --env-file ./agent.env --once` 单次同步。`agent-workbench-connector --help` 查看参数,`agent-workbench-connector --version` 查看版本。
40
+
41
+ 执行模式主动连接工作台 `/api/realtime` 的 WebSocket 设备控制通道,令牌通过首条消息认证。收到任务、审批、停止、目录或 Git 请求变化后立即读取状态,并每 3 秒补查。执行输出、审批请求和执行状态先保存到本地日志,再通过同一条 WebSocket 回报,等待服务端保存确认。断线时会提示、继续补查并自动重连;未确认回报保留待重连重报,命令仍通过原有领取和持久回执处理,不会自动重发已提交的 Agent 指令。历史及图片同步独立每轮等待 30 秒,另有每 30 秒心跳;慢同步或目录选择器等待不会阻塞已有执行的停止与审批。退出时取消通知、在途请求和目录选择器,通过 HTTP 回报最后状态,并保存未结束执行供核对。使用这些能力需先更新工作台,再重新打包、升级并重启连接器,无需新增环境变量或数据库迁移;HTTPS 反向代理须允许 `/api/realtime` 的 WebSocket Upgrade。
30
42
 
31
43
  ## 状态与迁移
32
44
 
@@ -36,10 +48,14 @@ agent-workbench-connector --env-file ./agent.env
36
48
 
37
49
  从源码版连接器迁移时,先正常停止旧进程,在配置中将 `WORKBENCH_DEVICE_DIR` 设置为旧状态目录的**绝对路径**,再启动新命令。保留该目录才能继续核对旧执行,不要同时运行两个连接器处理同一设备。显式相对状态目录仍相对于启动目录解析。
38
50
 
39
- 其他配置沿用源码版:`WORKBENCH_DEVICE_NAME` 设置设备名,`WORKBENCH_SYNC_EXCERPTS=false` 关闭摘要同步,`ACP_*`、`CODEX_EXECUTABLE` 和 `IDE_HISTORY_*` 配置本机 Agent 及历史来源。连接器只负责连接和调度,不包含 Codex / Claude 可执行程序,也不复制用户业务仓库。
51
+ 其他配置沿用源码版:`WORKBENCH_DEVICE_NAME` 设置设备名,`WORKBENCH_SYNC_EXCERPTS=false` 关闭摘要、逐条历史记录和图片预览同步,`ACP_*`、`CODEX_EXECUTABLE` 和 `IDE_HISTORY_*` 配置本机 Agent 及历史来源。连接器只负责连接和调度,不包含 Codex / Claude 可执行程序,也不复制用户业务仓库。
52
+
53
+ 历史正文预览保留最近 30 条消息的角色、工具记录和轮次信息,每个会话最多 23,000 字符。新增或发生变化的会话会单独同步图片,不受 30 条窗口限制;在历史页“会话图片”中点击查看或下载原图。支持嵌入的 PNG、JPEG、GIF、WebP,单张最多 12 MiB、每个会话最多 50 MiB 或 1000 张,不缩放、不读取远程地址或任意本地路径。上传失败时保留待同步状态,重试只补传缺失图片。先更新工作台,再更新并重启连接器;图片功能不重置旧增量索引,也不全量回填旧会话。更早的文字记录仍在来源设备查看;关闭正文同步也会清除服务端已同步图片。
40
54
 
41
55
  ## 维护者打包
42
56
 
43
- 在工作台仓库运行 `pnpm agent:pack`,生成 `dist/device-agent/agent-workbench-connector-0.3.0.tgz`。包内只包含编译后的连接器、说明、许可证和包元数据;上下文工作区代码已打包,无 `workspace:*` 运行时依赖,ACP SDK 由包管理器安装。源码改动后必须重新打包。
57
+ 日常发布可在 GitHub **Actions → Release Agent → Run workflow** 选择 main 和 `patch` / `minor` / `major`。流程自动更新本包版本、提交并打标签,再启动现有 CI / CD 检查和 npm 发布;最终发布状态查看 CI / CD,而非仅看 Release Agent。main / 标签保护必须允许该机器人的推送,否则继续使用版本 PR 和手动标签,不绕过仓库规则。现有 npm Trusted Publisher 仍是 `ci-cd.yml`,无需更换。
58
+
59
+ 在工作台仓库运行 `pnpm agent:pack`,生成 `dist/device-agent/agent-workbench-connector-0.3.2.tgz`。包内只包含编译后的连接器、说明、许可证和包元数据;上下文工作区代码已打包,无 `workspace:*` 运行时依赖,ACP SDK 由包管理器安装。源码改动后必须重新打包。
44
60
 
45
61
  CI / CD 在 `agent-vX.Y.Z` 标签推送后执行完整检查,再发布同一次构建的 tgz。标签版本必须与本包版本一致,提交必须已合入 main;PR 和普通 main 提交只打包不发布。发布使用独立的 GitHub `npm` Environment 和 npm Trusted Publisher(`Gausons/auto-workflow`、`ci-cd.yml`、Environment `npm`),首次发布也可配置临时 `NPM_TOKEN` Secret。具体初始化步骤见仓库 README 的“连接器 npm 发布”。本机 npm 登录状态不会传递给 CI;包版本一旦发布不能覆盖。安装或构建本身不会自动发布,也不会要求用户在安装机器上构建。