aws-runtime-bridge 1.9.172 → 1.9.179

package/CHANGELOG.md

@@ -5,6 +5,320 @@ files 白名单），供调度中心「查看本次更新内容」弹窗按 `##
 展示。发布新版本时须在仓库中先写好 `## v<version>` 段（prepack-guard 校验缺段
 即阻断发布）；Bridge 自更新成功后的运行时追加仅作为包内缺段时的兜底。
 
+## 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_
+
+### 技术栈自动识别：扫描工作区生成启动项候选
+
+- 新增端点 `POST /runtime/tech-stack/scan`（body `{ workspacePath }`）：只读扫描
+  工作区标记文件，返回可直接创建的启动项候选（名称/类型/命令/工作目录/依据）。
+- 识别范围：`pom.xml`/`build.gradle(.kts)`（Spring Boot 走 `spring-boot:run`/`bootRun`，
+  有 wrapper 优先 `mvnw`/`gradlew`）、`package.json`（按 `pnpm-lock.yaml`/`yarn.lock`/
+  `bun.lockb` 推断包管理器，脚本按 dev>develop>serve>start 取）、`manage.py`、
+  `pyproject.toml`/`requirements.txt`（FastAPI 出 `uvicorn main:app --reload`，
+  uv/poetry 项目自动加 `uv run`/`poetry run` 前缀）、`go.mod`（根 `main.go` 出
+  `go run .`，否则展开 `cmd/*/main.go`）、`composer.json`（Laravel `php artisan serve`、
+  Symfony `php -S localhost:8000 -t public`），以及 `Cargo.toml`/`deno.json`/
+  `docker-compose.yml` 兜底为 generic。
+- 遍历全层级且尊重 `.gitignore`（规则引擎抽到 `services/gitignore.ts`，与文件浏览器
+  目录树共用同一实现）；依赖/构建/版本库目录（`node_modules`/`target`/`dist`/
+  `.venv`/`.git` 等）恒跳过。目录预算 4000，超限返回 `truncated` 并保留已识别结果。
+- 命中标记文件才读内容，单文件读取上限 64KB；候选 id 为「相对目录+技术栈+命令」
+  的稳定哈希，重复扫描结果一致。
+
+> **验证**：bridge `npm run typecheck` 通过；新增 `tech-stack-scanner.test.ts`
+> （16 passed）覆盖 Spring Boot/wrapper 平台分支、Maven 回退、Node 包管理器推断、
+> monorepo 子包、Django/FastAPI/uv 前缀、Go 单入口与 `cmd/*` 展开、Laravel/Symfony、
+> Cargo 可运行 crate 判定与 lib crate 排除、compose 兜底、.gitignore 排除、
+> 同目录多栈、id 稳定性。
+
+### Git 提交历史分页与快照保留策略
+
+- `POST /runtime/git/commits` 支持 `skip`/`limit` 分页：新增 `resolveCommitPageLimit`
+  / `resolveCommitPageSkip` / `sliceCommitPage`，一次抓取多取一条用于判定 `hasMore`，
+  避免整段历史一次性返回；保留不传 `skip` 的旧单页响应形状。
+- 全分支图按 `--branches --remotes --tags` 收敛引用范围，内部引用（如 cline
+  checkpoint）不再混入提交图；detached HEAD 通过显式 revision 保留。
+- 新增工作区快照保留策略（`snapshot-retention`）：默认不清理，面板下发保留天数后
+  按 mtime 删除过期快照；与 change-cache 复用同一节流（写缓存时 1h + 24h 兜底扫描），
+  配置变更立即执行一次。面板显式下发的值不会被迟到的 `config.json` 覆盖。
+
+### 终端与隧道稳定性
+
+- 隧道请求体分帧：请求体超过单帧上限（2MB WS 文本帧）时，server 改为 `req` 头帧
+  + `reqchunk` 数据帧 + `reqend` 收尾，bridge 侧按 id 归集拼装后转发本地服务；
+  半包请求带 5 分钟空闲超时，连接断开时清理残留缓冲。
+- 终端 SDK 作答/取消：新增取消作答链路（含可选原因），与回答共用幂等与回执；
+  `compaction_summary` 走独立推送通道，不进 `sdkOutputQueueBySession` 串行队列，
+  摘要流与主输出流互不阻塞。
+- 修复时间线重复卡片：仅刷新用量的 `status-change`（`iteration_usage` 等）不再
+  重放上一次 `ai_request` 动作；抽为 `isUsageOnlyStatusChange` 便于单测覆盖。
+- 终端「等待输入」判定抽到 `lastOutputLine` + `listWaitingForInput`：只取输出末行
+  做启发式匹配，纯读不消费输出游标，供压缩后重建资源快照给出「哪些终端卡在提示符上」。
+
+### Bridge 面板
+
+- 仪表盘时间统一按面板当前语言（中/英）与浏览器本地时区渲染，修复切换语言后
+  日期仍按系统语言、以及直接切 ISO 字符串导致显示 UTC 挂钟值的问题。
+- 自更新前增加确认弹窗，明确「更新会重启 Bridge、运行中的实例会停止、进行中的
+  任务会中断」。
+
+> **验证**：`npm run typecheck` 与 `npm test` 通过（130 files、1827 passed、
+> 6 skipped）；`git-commits-page.test.ts`（4 passed）、`tech-stack.test.ts`、
+> `snapshot-retention.test.ts`、`tunnel-client.test.ts`、`terminal.sdk-answer.test.ts`
+> 均通过。
+
+## v1.9.174
+
+_发布日期：2026-10-21_
+
+### 私信附件「存到对方机器」：bridge 临时文件通道
+
+- 新增 bridge 临时文件通道：上传的文件直接落到**接收方实例所在机器**的
+  `<系统临时目录>/aw-temp/ATT/YYYYMMDD/{uuid}{扩展名}`，服务端不落盘，
+  按天归档并在写入时顺带清理超过 7 天的旧目录。
+- 新增端点：`POST /api/bridge-temp-files/upload`（multipart 上传）、
+  `POST /api/bridge-temp-files/read`（按绝对路径读回字节）、
+  `POST /api/bridge-temp-files/delete`（删除临时文件）。
+- 落盘文件名用 uuid 而非原始文件名（原始名只回传展示，规避文件名注入）；
+  扩展名由原始名清洗而来，保留原扩展名便于 agent 判断读取方式。
+- 回传路径统一为正斜杠：Windows 的 `path.resolve` 接受正斜杠，跨平台一致，
+  且正文标记进 JSON 载荷时不会被反斜杠转义弄乱。
+- 修正 multipart 文件名在部分代理链路被 latin1 解读导致的中文乱码
+  （与工作区上传同一口径）。
+- 读/删接口做路径越界校验：只允许访问 `aw-temp/ATT` 目录树内的文件，
+  越界与不存在统一返回 404，不向调用方泄露目录结构。
+- 上传超限（>512MB）返回 413 与明确错误码，不落成 HTML 500。
+
+> **验证**：bridge `npm run typecheck` 通过；新增 `bridge-temp-files.test.ts`
+> （10 passed）覆盖上传落盘/扩展名保留/读回/越界 404/删除/正斜杠跨平台往返。
+## v1.9.173
+
+_发布日期：2026-10-21_
+
+### 上下文压缩后补齐「运行时资源事实」，修复命令失忆
+
+- 压缩后重建的运行时资源快照新增「当前打开的文档」一类：画布（pencil）、
+  绘图（draw）、Office 文档各自登记**面板当前开着的那一份**。此前快照只列
+  「存在哪些文档」，压缩后 agent 不知道用户正看着哪份文档，容易重复 open
+  或对着已被取代的版本继续改。
+- 打开状态由 bridge 侧按 agentId 维护（`open-doc-registry`）：依据工具调用流
+  登记 / 清除，随会话结束清理；识别直调与收纳态 `call_tool` 中转两种形态。
+- 终端快照补「waiting for input」状态：停在 ssh 密码提示等交互提示上的会话
+  单独标出（判定只取输出末行，历史输出里的旧提示符不误判）。
+- 浏览器条目补 `browserId`：同 agent 可有多个独立 chromium 实例，缺 id 时
+  agent 无法分辨「已开的那一个」。
+- 修复两条漏掉重建快照的路径：`resetContext`（对话还原到启动基线但真实资源
+  并未消失）与休眠恢复 `importTranscript`（预压缩同样会丢弃资源事实）。
+
+- 修复「面板事件顺序与真实运行态相悖」：LLM 同一轮声明 `poll_message` + 兄弟工具
+  （如 `get_profile`）时，`call_tool` 事件原在**准备阶段**按声明序发出，但 blocking
+  工具会被调度器排到**批尾串行**执行 —— 于是 poll_message 的「调用中」卡片先落库、
+  实际先跑完的兄弟工具后落库，面板最后一条停在 `get_profile`，而 agent 正阻塞在
+  poll_message。现改为「工具真正开始执行时」才发 `call_tool`，事件顺序即真实执行顺序。
+- poll_message 阻塞期间新增**面板事件矫正**：以 runtime 内部的阻塞型调用计数
+  （`hasActiveBlockingToolCall`，经 bridge `GET /runtime/sessions/:agentId/current-action`
+  暴露）为权威判据。该判据是运行时事实、不经事件流派生，故不会被兄弟工具的完成
+  事件覆盖；发现权威状态与本地 tag 不一致时补发一次 poll_message 事件矫正面板，
+  并保留 30s 冷却避免刷屏。无法判定（查不到会话/查询失败/无阻塞调用在飞）时一律
+  不矫正，宁可保持现状也不凭猜测改写面板。
+
+> **验证**：bridge `npm run typecheck` 与 `npm test` 通过（123 files、
+> 1775 passed、2 skipped）；`package/acode` legacy 套件 175 passed / 0 failed、
+> vitest 828 passed。事件顺序修复另行验证：`package/acode` 新增
+> `call-tool-event-order.test.ts`（3 passed）、`aws-client-agent-mcp` 新增
+> 面板矫正用例（mcp-server 162 passed / 0 failed）、bridge `npm test`
+> 1775 passed / 0 failed。
+
 ## v1.9.172
 
 _发布日期：2026-10-21_

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` 或后续多调度中心身份路由明确目标。