aws-runtime-bridge 1.9.175 → 1.9.180

package/CHANGELOG.md

@@ -5,6 +5,229 @@ files 白名单），供调度中心「查看本次更新内容」弹窗按 `##
 展示。发布新版本时须在仓库中先写好 `## v<version>` 段（prepack-guard 校验缺段
 即阻断发布）；Bridge 自更新成功后的运行时追加仅作为包内缺段时的兜底。
 
+## v1.9.180
+
+_发布日期：2026-11-01_
+
+### 功能：累计消耗 token（从 Agent 启动起）全链路
+
+此前面板只有「当前上下文」口径的输入/输出 token（覆盖式，压缩/清空会回落），
+没有「从启动到此刻一共烧了多少」的累计口径。本次打通 runtime → adapter →
+调度中心的全链路：
+
+1. **acode runtime 累计消耗**：新增 `totalInputTokens` / `totalOutputTokens`
+   累计字段（Σ 各次请求 provider 真实上报的 prompt/completion tokens，输入含
+   缓存命中），跨迭代、跨 turn 只增不减，压缩/清空不影响；与缓存命中计数同
+   口径——只累计真实上报值，文本长度兜底不计入，压缩摘要 LLM 请求（独立
+   fetch）不计入。`turn_complete` / `iteration_usage` 的 usage 覆盖式携带累计
+   快照，前端无需自行累加。
+2. **休眠唤醒跨快照延续**：休眠导出的 tokenUsage 快照（含累计与缓存四字段）
+   由调度中心落库，唤醒启动时经 `resumeTokenUsage` 回灌，runtime `start()`
+   重建 state 时以 `config.initialTokenUsage` 为累计初值——唤醒后继续累计而非
+   清零。普通启动缺省从 0 起；旧快照（无累计字段）按无 seed 处理，不阻断启动。
+3. **adapter / 终端路由透传**：`toUsage` 逐字段解析累计值（独立于 0/0 丢弃与
+   fallback 判定，不参与文本长度兜底）；`totalUsage` 字段级 presence 覆盖
+   （旧版 runtime 不带累计字段时保留现值，不清零不回落）；`resolveStatusChangeUsage`
+   在 input/output 为 0（如 seed 后、首个请求前）但累计已有值时也照常传出。
+   `getTotalUsage`（休眠导出通道）一并带出累计与缓存快照。
+
+配套调度中心侧：状态回调透传累计字段、AgentContextPanel 新增「累计消耗」区块、
+休眠快照表补列（cache_hit/miss + total_input/output tokens）。
+
+### 修复：唤醒请求的累计 token seed 解析
+
+`parseResumeTokenUsage`（与 `parseResumeTranscript` 同模式）只接受四个累计字段，
+非法/缺失字段丢弃、全部非法返回 undefined（累计从 0 起，不阻断启动），
+JSON 文本异常不会让唤醒流程失败。
+
+## v1.9.179
+
+_发布日期：2026-10-27_
+
+### 修复：注册成功后立刻拆掉自己的隧道并退出进程
+
+现象：日志依次出现「隧道客户端已启动」→「目标已不在配置中，停止旧隧道」→
+「未捕获异常: {}」→ 优雅关闭 → 注销实例。机器明明注册成功却连不上。
+
+三个叠加缺陷：
+
+1. **`instanceId` 预声明用了对象展开重绑定**（`config = {...config, instanceId}`）。
+   `autoRegisterAll` 用同一个 `config` 对象数组构造隧道「保留集」，重绑定后外层
+   仍持有旧对象，后续补上的 `credentialId` 传不出去。
+2. **`credentialId` 同样只改了局部变量**。于是一边按 `credentialId` 启动隧道、
+   一边按 `userKey 指纹` 计算保留集，键不一致 → 刚建的隧道被判定为「已不在配置
+   中」而拆除。两处均改为原地写回。
+3. **`teardownConnection` 先 `removeAllListeners()` 再 `close()`**。对仍在
+   `CONNECTING` 的 socket 调 `close()`，`ws` 会异步 emit `'error'`
+   （"WebSocket was closed before the connection was established"）；此时已无任何
+   error 监听，EventEmitter 把它抛成未捕获异常 → 进程级 `uncaughtException` →
+   整个 bridge 优雅关闭。现在保留一个忽略用的 `error` 监听。
+
+### 修复：未捕获异常日志只打印 `{}`
+
+`Error` 的 `message` / `stack` 是非可枚举属性，`JSON.stringify(error)` 只得到
+`"{}"`，此前根本看不出崩溃原因。日志格式化现在显式展开
+`name [code]: message` 与 `stack`。
+
+### 代码质量：lint 全量清零
+
+`npm run lint`（`eslint src --max-warnings 0`）从 89 error / 34 warning 降到 0 / 0：
+清理未使用导入与变量、修正 `import/order` 与重复导入；测试文件中的非空断言
+（`!`）按惯例在 eslint 配置里对 `**/*.test.ts` 放宽，避免为消除告警引入无意义判空。
+
+## v1.9.178
+
+_发布日期：2026-10-27_
+
+### 目标身份升级为 `credentialId`：轮换 Key 不再断链
+
+上一版用 `serverUrl + userKey 指纹` 作目标身份，解决了同址多账号并行；但**轮换
+API Key 会改变指纹**，导致 runtime token、隧道、注册状态、instanceId 全部重新开始
+（表现为换 Key 后 agent 找不到实例）。本版把身份锚点换成服务端下发的稳定凭据 ID：
+
+- `config.json` 的 target 新增 `credentialId` / `credentialType`，注册成功时由
+  服务端回填并持久化（与 instanceId 同一条回写路径）。
+- `targetKeyOfConfig` 改为 `buildTargetKey(serverUrl, credentialId ?? userKey)`：
+  有 credentialId 时身份不随 Key 变化；旧配置无该字段时仍回退 userKey 指纹，平滑迁移。
+- runtime token 存储、隧道槽位、注册重试、instanceId 反查统一用
+  `identityKeyOfConfig(config)`（credentialId 优先）。
+- **删除隧道鉴权的 userKey 兜底**：此前取不到 runtime token 时会把 userKey 当
+  token 发出去，服务端只认 hash 匹配必然 401，却掩盖了「未注册/注册失败」的真实
+  原因。现在明确报错并提示重新注册。
+
+### 同一调度中心地址支持多账号/多租户并行注册
+
+（承接 v1.9.177）身份模型继续保证：同一 `serverUrl` 下不同凭据各自独立隧道、
+独立 runtime token、独立 instanceId，互不覆盖。
+
+## v1.9.177
+
+_发布日期：2026-10-26_
+
+### 同一调度中心地址支持多账号/多租户并行注册
+
+同一用户加入多个组织（租户）时，同一台机器往往需要连接**同一个调度中心地址**、
+但使用**不同的 API Key** 各自注册一个实例。此前桥内以归一化 `serverUrl` 作为唯一
+身份键，同址两行会互相覆盖（隧道被拆、runtime token 串用、instanceId 写乱），
+面板因此直接拒绝保存第二行。
+
+本次把桥内身份模型从「地址」升级为「目标身份」＝ `归一化 serverUrl + userKey 指纹`：
+
+- 新增 `utils/target-identity`：`buildTargetKey(serverUrl, userKey)`，形如
+  `http://host:port#a1b2c3d4`（sha256 前 8 位，不落明文；可读、可作 properties 键）。
+  地址归一化（尾斜杠/协议大小写/`ws→http`/`localhost→127.0.0.1`/重复端口）抽到
+  `utils/scheduler-url`，由 `config`、`runtime-binding`、`target-identity` 共用一份实现。
+- **runtime token 存储**：`runtime-tokens.properties` 的键由 `md5(serverUrl)` 改为
+  目标身份键，同址多账号各存各的 token。旧键自动兼容读取；未指定 `userKey` 且该地址
+  只有一个身份时仍可命中（单目标老调用点无需改动），多身份时必须显式指定，避免串用
+  别的账号 token 造成「注册成功但回调 401」。新增 `listScopedRuntimeAccessTokens`。
+- **隧道**：`tunnels` Map 改按目标身份键控；同址不同账号各自一条隧道并存。
+  新增 `stopTunnelClientForTarget(serverUrl, userKey)` 精确停止单个身份；
+  `stopTunnelClientsExcept` 改为接收身份键集合；`stopTunnelClientForServer` 保留，
+  语义改为「停该地址下所有账号」。
+- **注册状态**：`registrationState.registrations` 键改为目标身份键，instanceId 互不覆盖；
+  新增 `resolveInstanceIdForTarget`。注销只清理本身份的 token/隧道/记录，其余身份保持注册。
+- **instanceId 回写**：只回写与本次注册身份匹配的那一行（此前按地址会把所有同址行写成
+  同一个 instanceId）。
+- **注册重试**：后台重试定时器按身份键去重，同址两个账号各自独立重试。
+- **面板去重规则**：由「同址即重复」改为「同址 + 同一 API Key」才是重复；同址不同 Key
+  属合法配置。去重校验移到「继承原配置」之后，因为编辑行留空 userKey 时真实身份要等
+  继承完成才确定。
+- **面板交互**：列表每行显示 API Key 掩码与租户 ID，便于区分同址多行；编辑行新增
+  `originalTargetKey` 精确指代被编辑的那一行（同址多行时仅靠地址无法定位），两行都留空
+  userKey 时按写入顺序逐条认领旧身份继承。
+- **目标解析**：`resolveSchedulerBaseUrlFrom` 返回值新增 `userKey`；歧义判定改用
+  「目标身份数量」而非「去重后 URL 数量」——否则同址多账号会被误判为单目标而静默选中
+  其中一个账号。新增 `resolveTargetIdentityFromToken` 按 token 反查身份（含地址与
+  userKey），供入站回调确定该用哪个账号的凭据。
+
+> **兼容**：单地址单账号的既有配置行为不变；旧 token 文件（md5 键）继续可读。
+> 无需改动 `config.json`。
+
+## v1.9.176
+
+_发布日期：2026-10-25_
+
+### 工作区代码导航：语言服务 + 语法索引兜底
+
+- `/ws/lsp` 从「仅 TypeScript 单进程」升级为多语言模型：按
+  `工作区 + provider + clientId` 隔离进程，同一会话内跨文件复用；不同浏览器
+  标签/面板使用不同 `clientId`（tsserver、pyright 都不支持多客户端共享文档状态）。
+  进程池设并发上限（`AWS_LSP_MAX_PROCESSES`，默认 6）并按最久未用淘汰，断连后
+  保活 60s 供快速重连复用。
+- 新增 provider 注册表（`services/lsp/provider-registry`），覆盖 15 个语言服务：
+  TypeScript/JavaScript、Vue、Python、JSON、CSS、HTML、YAML、Bash、Dockerfile、
+  PHP、Java、Go、Rust、clangd、C#、Ruby。按扩展名推断 provider，统一
+  `languageId` 归并与启动参数拼装；新增 `services/lsp/uri-rewrite` 处理客户端与
+  服务端路径形态差异（Windows 盘符大小写、`file://` 编码）。
+- 新增 `GET /runtime/lsp/providers`、`POST .../install`、`POST .../uninstall`、
+  `GET .../task/:id`、`GET /runtime/lsp/processes`：npm provider 按需安装到
+  `.aws-bridge/lsp-servers`，安装进度可轮询，进程列表供排障。
+- 新增工作区语法索引（`services/workspace-index`）：以 tree-sitter 抽取声明与
+  导入，覆盖 12 种语言（TypeScript/JavaScript、Python、Go、Rust、Java、C、C++、
+  Ruby、PHP、Lua、Bash），提供定义/引用/符号/大纲查询。LSP 不可用时前端回退到
+  该索引，不因语言服务缺失而失去跳转能力。端点挂在
+  `/api/workspace-index/{status,build,query,drop}`，索引随工作区切换释放。
+
+> **兼容**：旧前端只带 `file`/`language`（无 `provider`/`clientId`）时按扩展名
+> 推断 provider、`clientId` 视为 `default`，行为与历史版本一致。
+
+### 桌面控制人工治理：急停与动作审计
+
+- 新增 `POST /runtime/desktop-control/:agentId/pause`（急停/恢复）与
+  `GET .../state`（控制状态 + 最近动作审计）。急停后所有 `desktop_*` 工具
+  一律拒绝（含读类），并产生 `rejected` 事件而非静默失败。
+- 动作事件流：`desktop_*` 调用映射为 `started`/`done`/`error`/`rejected`
+  四态事件，按 agent 维护 100 条环形审计缓冲，经远程桌面 WS 实时推送，
+  每个 agent 独立自增 `seq` 供前端排序与去重。
+- **坐标陈旧性校验**：截图成功后记录「坐标依据」（截图文件 + 时刻 + 可重放参数）；
+  带坐标的动作执行前，若依据超过 `AWS_DESKTOP_STALE_WARN_MS`（默认 60s），
+  用记忆参数重截一次并做内容比对——画面已变则在结果尾部追加警告（不阻断，
+  LLM 读到后自行重截），未变则静默刷新依据时刻。5s 内结果缓存，连续动作不重复校验；
+  sharp 不可用/截屏失败时退化为时间戳警告（安全方向）。
+- 状态为进程级内存态：Bridge 重启即自动解除急停（重启本身会终止桌面 MCP，
+  等效急停，无需持久化）。
+
+### 桌面安装包 sidecar 模式
+
+- 新增 `AWS_BRIDGE_APP_MODE=desktop` 与 `AWS_BRIDGE_LISTEN_HOST`：桌面态只监听
+  回环，不暴露局域网；未显式配置注册地址时默认走隧道（回环地址对外不可达）。
+- 端口探测改为「探测形态 = listen 形态」：指定 host 时只探测该 host，避免把
+  「别的进程占了通配、但 127.0.0.1 仍可绑定」误判为冲突导致端口无谓顺延。
+- 未设置这两个变量时行为与既有一致（通配绑定、服务器部署语义不变）。
+
+### Bridge 面板
+
+- 面板 HTML 拆分为独立模块（`routes/dashboard-theme`、`routes/dashboard-icon`），
+  主题令牌与图标不再内联在巨型模板字符串里，便于维护与复用。
+
+### 子 Agent 与工具组
+
+- `SubAgentManager` 等待结果时，store 查询失败不再让该项从结果中静默消失：
+  超时后按 `settled` 集合补报未终态项，避免「部分子 agent 结果莫名丢失」。
+- 工具组：新增命名分组与 `tools/list` 名称对齐校验（`named-group-tool-names-alignment`），
+  防止分组配置与实际暴露的工具名漂移。
+- `aws-client-agent-mcp` 补齐邮箱工具组（`send_email`/`list_emails`/`read_email`/
+  `reply_email`/`ack_email`）与 `list_project_members` 的转发分支，全部经
+  `callAgentScopedTool` 注入 agentId（防越权）。
+
+### 发布链路修复
+
+- **修复 `npm publish` 被自身守卫误拦**：`verify-dist-minified` 原先用
+  `code.includes("/**")` 判断「未混淆」。但本仓库把 HTML/CSS/内联脚本放在模板
+  字符串里（`DASHBOARD_HTML`、`THEME_CSS`），压缩后字符串内的 `/** ... */`
+  会原样保留（那是要发给浏览器的页面源码，不是 JSDoc），导致
+  `dist/routes/dashboard.js` 被误判并直接阻断发布。
+  新增 `scripts/source-comments.mjs`，基于 TypeScript AST + 字面量区间排除
+  判定「代码区注释」；`minify-dist.mjs` 的 .d.ts 注释剥离同步切到同一口径，
+  避免「剥干净了却仍被判为脏」。守卫对真实未压缩文件仍然拦截（已验证）。
+
+> **验证**：`npm run typecheck` 与 `npm test` 通过（137 files、1915 passed、
+> 3 skipped）；`npm pack` 端到端通过（780 files / 6.6MB，postpack 正确还原）。
+> 新增/覆盖 `workspace-index`、`provider-registry`、`uri-rewrite`、`lsp`、
+> `desktop-control`、`desktop-staleness`、`desktop-mode`、`sub-agent-manager`、
+> `named-group-tool-names-alignment`、`mcp-tools` 等用例。
+
 ## v1.9.175
 
 _发布日期：2026-10-23_

package/README.md

@@ -2,7 +2,24 @@
 
 AgentsWorkStudio 机器实例运行时桥接服务，用于在实例上管理 Agent 运行时、终端、配置与回调通信。
 
-> `aws-runtime-bridge` 面向机器实例宿主机运行，需要访问本机工作区、终端、运行时配置和文件系统；不要将它作为 Docker/Compose 服务部署。Docker Compose 仅用于仓库根目录的 `aws-dashboard` 与 `aws-mcp-server` Web 服务。
+> `aws-runtime-bridge` 面向机器实例宿主机运行，需要访问本机工作区、终端、运行时配置和文件系统；不要将它作为 Docker/Compose 服务部署。Docker Compose 用于仓库根目录的 `aws-dashboard`、`aws-mcp-server` 与自托管邮件服务 `james`。
+
+## 能力范围
+
+Bridge 是执行机器上的能力宿主，调度中心只下发指令与配置，实际执行都在本机：
+
+| 领域 | 能力 |
+| --- | --- |
+| Agent 运行时 | 启动/停止/重启自研 ACode 运行时；会话、状态、时间线、调试日志、子 Agent |
+| 工作区 | 文件浏览/读写/上传下载、搜索、变更记录与 diff、快照、文件监听、忽略规则 |
+| 终端 | 多 PTY 会话、断线恢复、系统指标、命令模板、后台任务 |
+| Git | 状态、diff、提交图/分页、提交、重置、历史 |
+| MCP / Skill / Plugin | 持久化配置、包型 MCP 解压装配、市场安装、开发期临时挂载与热重载 |
+| LSP | 语言服务进程池与 WebSocket 桥接，工作区符号/定义/引用索引 |
+| 浏览器 | Playwright 会话、实时画面、截图、人工接管、按 scope 持久化登录态 |
+| 远程桌面 | 屏幕采集、键鼠输入、AI 操作时间线、人工互斥 |
+| 启动项 | 业务程序起停、就绪探测、日志与指标 |
+| 通信 | 主动注册、反向隧道、运行时 token 刷新、配置下发与能力热推 |
 
 ## 全局安装
 
@@ -76,7 +93,7 @@ If an existing runtime binding still stores an old scheduler URL such as `http:/
 `aws-runtime-bridge` 命令仍作为兼容别名保留。安装 `aws-runtime-bridge` 后，包内会随附
 `aws-client-agent-mcp` 的编译产物；bridge 启动时只负责准备该 MCP 产物，不再在 Agent 启动时默认动态注入 `aws-mcp`。
 
-请在面板中为目标运行时安装/配置 MCP；这样 Claude Code、Codex、OpenCode 等 SDK 启动模式都走一致的持久化 MCP 配置链路。
+请在面板中为 ACode 运行时安装/配置 MCP，走统一的持久化 MCP 配置链路。
 
 如需使用自定义 MCP 可执行文件，可设置：
 
@@ -182,6 +199,46 @@ awsb service uninstall
 
 服务未安装或日志文件未生成时会返回明确错误提示。
 
+## 多用户隔离
+
+Bridge 以 `(tenantId, userId)` 为命名空间隔离所有「用户配置」，与 Java 侧
+`t_agent.owner_user_id` / `tenant_id` 及浏览器 `scopeKey`（`t:{tenant}:u:{user}`）对齐：
+
+```
+{root}/.aws-bridge/
+  users/{tenantId}/{userId}/
+    ai/acode.json                              每用户 AI 配置（provider/model/apiKey）
+    skills/deployed/{name}/ + manifest.json    每用户技能库
+    skills/{name}/                             每用户全局技能
+    mcp/deployed/{name}.json + manifest.json   每用户 MCP 库
+    mcp/packages/{name}/                       每用户 MCP 包
+    plugins/deployed/{name}/ + manifest.json   每用户插件库
+    capability/{skills,mcp,plugins}/config.json          每用户默认开关
+    capability/{skills,mcp,plugins}/agents/{agentId}.json per-agent 覆盖 + 继承
+  instance-runtime/{agentId}/
+    owner.json                                实例归属（多用户解析依据）
+    skills/ + plugins/                        每实例链接农场
+    config.json + mcp-extra.json              每实例装配结果
+  config.json / binding.json / …              机器级配置（面板凭据、配对、访问控制）
+```
+
+身份契约：
+
+- Java `RuntimeBridgeService` 在每次 bridge 调用上注入 `X-Tenant-Id` / `X-User-Id`；
+  `/runtime/start` 与 `/runtime/init-instance` 的 body 另带 `tenantId` + `ownerUserId`。
+- Bridge 侧 `requireUserScope` 强制用户配置类路由携带身份，`requireAgentOwnership`
+  校验实例归属（`owner.json`），不匹配返回 `403 agent-ownership-mismatch`。
+- 实例归属在 `/runtime/start`、`/runtime/init-instance` 时登记；存量实例无 `owner.json`
+  时按只读遗留层兜底（`AWS_BRIDGE_DISABLE_LEGACY_FALLBACK=1` 可关闭）。
+
+迁移：执行
+`node dist/scripts/migrate-user-scopes.js --tenant <tenantId> --user <userId> [--dry-run] [--overwrite]`
+把原有 bridge 级共享配置一次性复制进指定用户命名空间（幂等、不删除遗留数据）。
+
+> **版本要求**：多用户隔离需要 bridge 与 aws-mcp-server 同版本部署。旧版 Java 不带身份头时，
+> 用户配置类写操作会返回 `400 user-scope-required`；迁移期可临时设
+> `AWS_BRIDGE_LEGACY_SCOPE=1` 回退。
+
 ## 关键环境变量
 
 | 变量名 | 说明 | 默认值 |
@@ -193,5 +250,7 @@ awsb service uninstall
 | `AWS_REGISTER_IP` | 已废弃，仅做向后兼容；等同 `registerAddr` 但只接受纯 IP，端口由 `AWS_RUNTIME_BRIDGE_PORT` 决定 | 未设置时读取配置文件 |
 | `AWS_RUNTIME_HOME_DIR` | Bridge 管理配置与状态的主目录；显式设置时优先于开发/生产环境的默认主目录 | 当前用户 Home（开发态为 `<仓库根>/.dev-home`） |
 | `AWS_RUNTIME_CORS_ORIGINS` | 允许访问 bridge 的来源，逗号分隔 | 本地开发地址 |
+| `AWS_BRIDGE_LEGACY_SCOPE` | 迁移期逃生门：设为 `1` 时，缺少 `(tenantId, userId)` 身份的请求回退到 `users/_legacy/_legacy` 命名空间；默认严格模式直接拒绝用户配置类写操作 | 未设置（严格） |
+| `AWS_BRIDGE_DISABLE_LEGACY_FALLBACK` | 设为 `1` 关闭对遗留 `instance-template/` 层的只读回退（迁移完成后可启用） | 未设置（允许回退） |
 
 生产环境中，bridge 最终解析出的调度中心地址必须是机器实例可访问的 `aws-mcp-server` 地址，不能使用不可达的容器内 `localhost`。如果配置了多个 `autoRegisterTargets`，bridge 不会静默选择第一个目标，需通过 `AWS_RUNTIME_SCHEDULER_BASE_URL` 或后续多调度中心身份路由明确目标。