aws-runtime-bridge 1.9.153 → 1.9.168

package/CHANGELOG.md

@@ -5,6 +5,772 @@ files 白名单），供调度中心「查看本次更新内容」弹窗按 `##
 展示。发布新版本时须在仓库中先写好 `## v<version>` 段（prepack-guard 校验缺段
 即阻断发布）；Bridge 自更新成功后的运行时追加仅作为包内缺段时的兜底。
 
+## v1.9.168
+
+_发布日期：2026-10-11_
+
+### 发版稳定性：测试兼容、任务通知与连接生命周期修复
+
+本版本主要为发版验证中暴露的兼容性与稳定性问题收敛，既有功能契约保持不变：
+
+- `aws-client-agent-mcp` 的 `initialize` 返回完整工具组清单，能力开关三态
+  （`disabled` / `collapsed` / `expanded`）契约与 Java 侧保持一致。
+- `pipeline_task_assigned` 的 `SYSTEM_NOTIFY` 与持久化任务通知增加强制任务域
+  hydrate，首次落空时自动重试，避免重启或长轮询窗口内遗漏流程任务。
+- `.agentswork` 记忆目录搜索增加项目根与 Git 仓库边界，避免相邻项目目录串用；
+  `MemoryStore` 增加 domain 写入缓存，修复大量 domain 场景测试超时。
+- WebSocket 手动断开与异步 token 刷新重连之间的竞态修复，断开后不再重新排程
+  重连，非 CLOSED 连接句柄会被终止。
+- `RuntimeBridgeService` 的 SSE 客户端改为首次使用时初始化；同步迁移版本数、
+  `reply_to` 测试 schema 与 Direct/Group Message 控制器测试签名。
+- 测试命令增加 Node 测试进程强制退出兼容项，确保 CI 收尾不被子进程管道句柄
+  阻塞。
+- 修复 Linux CI 启动项端口探测用例的 shell PID / 命令进程 PID 替换竞态，
+  避免发布流水线因平台进程发现时序产生偶发失败。
+
+> **验证**：Java 后端 `mvn test`（1873 tests）、bridge 根目录测试、ACode 测试与
+> `aws-client-agent-mcp` 测试全部通过；`npm run build:all`、`npm run build`
+> 和 `npm run typecheck` 均通过。
+
+## v1.9.167
+
+_发布日期：2026-10-07_
+
+### Word 格式管控：OOXML 版式底座 + 信任机制（自动备份 / 保护区域 / 报告聚合）
+
+面向「生成复杂排版文档并严格把控」这一目标，分两条线补强 office 工具链。
+Java 侧新增 3 个 OOXML 助手并扩展 5 个，bridge 侧补齐备份、参数透传与工具契约。
+
+#### 1. 写盘前自动备份（改坏了能回滚）
+
+`office_edit` / `office_format(fix)` / `office_apply_profile` / `office_generate_from_template`
+直接改写用户文档，此前改错只能靠事先手动 copy。现在覆盖写盘前自动留一份
+`<基名>-backup-<时间戳><扩展名>`，滚动保留最近 5 份；回执透出 `backupPath` + `backupHint`。
+**另存到已有文件**同样先备份（等价于覆盖）。备份失败不阻断写盘（磁盘满/权限异常时
+不带该字段）；只清理严格匹配时间戳命名的文件，不会误删 `报告-backup-未命名.docx` 这类同名文件。
+
+#### 2. 保护区域：封面/题注/代码块不被正文规则触碰
+
+规则新增 `exclude`（支持 `/body/p[1]-p[14]` 区间简写与 `{path/from/to/style/contains/role}` 对象）
+与 `excludeByRole`，**check 与 fix 同源生效**。`summary.excludedParagraphs` 透出命中段数。
+`office_format` 另提供顶层 `exclude` 便捷入口（preset 场景下也能一次排除封面）；
+实现上复制 rules 再写入，不原地修改 preset 共享实例（否则会污染后续所有调用）。
+
+#### 3. 三套规则系统打通：profile 可直接当 rules
+
+`office_view(mode=profile)` 的产物此前**无法**直接喂给 `office_format`——启发式识别出的
+角色其 `match` 为空对象，`RoleMatcher.matches()` 恒为 false 且不回落到内置判定。
+现空 `match` 回落内置启发式，并新增 `unmatchedRoles`/`unmatchedRolesHint` 显式报出
+「既无 match 又非内置角色名」的规则（此前这类规则静默失效，是「配了规则却没反应」的根因）。
+推荐链路：模板 `view(profile)` → `office_format(rules=profile, exclude=[封面范围], action=check)` → `action=fix`。
+
+#### 4. 报告可读性：106 条平铺 → 可定位
+
+- 每条违规新增 `textDigest`（段落文字摘要），不必再按 path 反查原文；
+- `summary.byRole`（按角色聚合降序）、`summary.paragraphs`（按段落聚合，含该段问题属性列表）、
+  `summary.topIssue`（一句话摘要）。
+- 阅读顺序：`topIssue` → `byRole` → `paragraphs` → 需要细节时再读 `violations`。
+
+#### 5. `office_format(action=dryRun)` 与 `office_view(paths=[...])`
+
+- **dryRun**：按 fix 逻辑算出将改哪些项，返回 `willModify` + `nextStep`，不写盘、不返回字节
+  （bridge 侧即使服务端意外带回字节也直接丢弃）。注意 dryRun **不产生 `converged`**——
+  未真正修正就不能声称收敛。
+- **paths**：段落白名单（`/body/p[7]`、区间 `/body/p[5]-p[11]`），仅对 `styles`/`profile`/`selfcheck`
+  生效。大文档（几百段）下排查局部时把返回量从整篇压到几段。`profile` 的 `page`/`numbering`
+  来自文档级部件仍按整篇提取；`selfcheck` 的 `pageNo` 仍为真实页码。无法解析的 `paths`
+  一律回退为「不过滤」，避免空结果误导。
+
+#### 6. OOXML 版式能力补齐 + 4 个 P0 缺陷修复
+
+新增 `DocxLayoutOps`（分栏/页码分区/文档网格/titlePg/分页控制/中文排版开关/动态版心宽）、
+`DocxRunFormatExtras`（双删除线/小型大写/字符缩放/复杂文种字号/字体 hint）、
+`DocxFootnoteOps`（脚注尾注）；扩展 `DocxStyleOps`（样式创建**与改写**、字符样式）、
+`DocxNumberingOps`（多级编号/样式绑定/一键编号）、`DocxTableOps`（行高/cantSplit/表格布局/边框）、
+`DocxPaths`（`/body/table[T]/row[R]`、`/body/style[ID]`）。
+
+修复的 P0：
+
+| 缺陷 | 影响 | 修复 |
+|---|---|---|
+| `pageBreakBefore` 进规则但不被下游识别 | 标记 `fixable=true` 却写不进去 → **check 永不收敛** | `applyParagraphExtras` 委托 `DocxLayoutOps.applyParagraphLayout` |
+| `applyProfile` 编号硬编码 `numId=2` | 文档已占用 numId=2 时挂错编号定义 | 改用 `createStyleBoundHeadingNumbering` 返回值 |
+| bridge 从不读 `outputFile` | 描述承诺「标注版不覆盖原件」落空 | 接上 `outputFile`，缺省自动派生 `<原名>-标注版.docx` |
+| `fontSize` 走 `intProp` + `setFontSize(int)` | **10.5pt 被截断为 10pt**（论文图题/表题标准字号） | 按双精度写 `w:sz`+`w:szCs`（半磅精度） |
+
+另：`keywordCount`/`refCount` 角色级聚合断言从「只在描述里」补成真实实现
+（此前按描述配置会静默零违规）；selfcheck 分页识别补齐「显式分页符 + 段前分页 + 分节符」并修正
+**文本归属页**（段前分页段的文本此前被算进上一页）；标题级别判定兼容中文样式名「标题 N」与纯 `outlineLvl`。
+
+#### 7. 颜色值序列化：`STHexColor` 联合类型陷阱
+
+`w:color/@w:val` 的类型是 XMLBeans **联合类型** `STHexColor`——RGB 分支存 3 字节 `byte[]`，
+另一分支存字符串 `"auto"`，因此 `CTColor.getVal()` 返回 `Object`。
+`DocxStyleResolver` 直接 `String.valueOf(getVal())`，RGB 被渲染成 `[B@74a239d7`。
+
+**不只是显示乱码**：`OfficeRuleEngine.compareColor` 拿这个值跟期望值比对，
+任何带 `color` 期望的规则**都不可能收敛**（fix 写完复检仍报违规，`converged` 永远 false）。
+读取改走 `xgetVal().getStringValue()`（两类分支都正确），字节分支兜底手写十六进制。
+
+同根因的写入侧缺陷：颜色归一化一律 `toUpperCase()`，把合法的 `auto` 变成非法的 `AUTO`，
+被 XMLBeans 以「union value 'AUTO' does not match any members」拒绝
+（传 `color="auto"` 清色直接报错）。归一化统一收敛到 `OfficeArgs.normalizeColor` 单点权威
+（命名色表 + `auto` 保留小写），`OfficeDocService` 与 `OfficeRuleEngine` 都委托它；
+xlsx/pptx 无 `auto` 概念，走新增的 `rgbColorOf` 显式拒绝并给可读提示。
+
+顺带修复 `office_view(outline)` 两处同源缺陷：标题判定只认 `styleId` 以 `heading` 开头
+（中文模板「标题 1」与纯 `outlineLvl` 标题全部漏检）；表格节点只有行列数，现附加题注文本
+（先取表格前一段、再取后一段，按「表 X-Y」文本特征或题注样式判定，都不中则回退）。
+
+> **升级须知**：本版本无破坏性变更。`office_format` 的 `action` 枚举新增 `dryRun`，
+> 旧调用方不受影响；备份文件会在文档同目录产生额外的 `<基名>-backup-*` 文件，
+> 若不希望出现在工作区索引中，可在 `.gitignore` 加 `*-backup-????????-??????.*`。
+
+## v1.9.166
+
+_发布日期：2026-10-05_
+
+### 修复：submit_task_result 丢参导致循环节点恒被拒绝提交
+
+`handleSubmitTaskResult` 只向 `agentClient.submitTaskResult` 透传了
+`nodeId / outputPayload / changeLog`，而工具 schema 早已声明、服务端也早已消费的
+**`handoverNote` 与 `deliverables` 在这一层被静默丢弃**。后果：
+
+- 位于循环路径（模板 `require_handover=true`）的节点，Agent 即便按描述传入
+  `handoverNote`，抵达 Java 侧时仍为 null，`validateHandoverNoteIfRequired`
+  恒定抛「必须提供交接经验」拒绝提交 —— 表现为「nodeId 能识别、handoverNote 却
+  永远缺失」的固定失败，Agent 侧穷尽调用通道与字段命名均无法绕过；
+- 结束节点的 `requiredDeliverables` 同理永远收不到交付物，必填项必然判缺。
+
+修复内容：
+
+- **补齐 5 参透传**：`handoverNote`（`getOptionalString`）与 `deliverables` 一并
+  下发到 `agentClient.submitTaskResult(nodeId, outputPayload, changeLog,
+  handoverNote, deliverables)`。
+- **新增 `prepareDeliverables`**：逐项归一化交付物，文件类（`path`）复用
+  `uploadAttachmentFiles` 换取 `url/mediaType/size` 后回传，文本类（`text`）原样
+  透传；无 key 项与空数组安全忽略。服务端 `parseDeliverablesArg` 可直接消费。
+- **changeLog 放宽形态**：数组（MCP 已解析）与 JSON 字符串两种形态均透传，
+  原先只认数组、字符串形态被吞（服务端 `parseChangeLog` 本就两种都支持）。
+
+### 错误结构化：errorCode / field 回传给 Agent
+
+服务端校验失败原先只回 `{"error":"<纯文本>"}`，Agent 只能从中文长句里猜原因。
+现新增 `McpToolError`（携带 `errorCode` / `field`），`callTool` 抛出时保留，
+`McpToolError` 经 MCP 错误响应原样透出：
+
+```json
+{"error":"该节点位于循环路径…","errorCode":"HANDOVER_REQUIRED","field":"handoverNote"}
+```
+
+仅新增字段、不改 `error` 语义，向后兼容；Agent 可据此直接补齐入参重试。
+
+> **回归锁定**：`mcp-server.test.ts` 的 `submit_task_result` 分发断言原先只校验
+> 3 个位置参数（`["node-1","...",undefined]`），恰好把丢参行为固化，导致测试全绿
+> 而线上必然失败。现改为 5 参断言，并新增 handoverNote / text 交付物 / file 交付物
+> （打桩上传）/ changeLog 字符串形态四条用例。
+
+> **兼容性**：MCP 工具 schema 未变更，仅修复「声明了却不转发」的实现缺口；
+> 新旧服务端均可对接（服务端本就接受这两个可选字段）。
+
+## v1.9.165
+
+_发布日期：2026-10-03_
+
+### 浏览器画质档位：原画改为无损 PNG，高清 80 / 流畅 60
+
+原先三档都是 JPEG，所谓「原画」实为 JPEG q80；且 tile 差量路径把 CDP 帧解码后
+**再按同一质量重编码一次**，同一区域反复变化时有损伪影逐次累积。
+
+- **档位参数改为格式驱动**（`QUALITY_PRESETS` 新增 `format` 字段）：
+  - `original`：无损 PNG，像素级还原（`quality` 不生效）；
+  - `hd`：JPEG 80；
+  - `smooth`：JPEG 60。
+- **tile 重编码跟随档位格式**（新增 `frame-encode.ts` 统一编码入口）：
+  无损档位下增量块同样输出 PNG，不再被二次有损压缩；整帧与 tile 两条路径
+  共用同一实现，避免只改一半造成「整帧无损、增量有损」的错配。
+- **CDP 参数修正**：`Page.startScreencast` 仅在 jpeg 格式下携带 `quality`，
+  png 格式传 0 会被 CDP 判为非法参数。
+- **默认格式由默认档位派生**：原先 `DEFAULT_FORMAT` 写死 `'jpeg'`，与默认档位
+  `original` 冲突，会让会话初始状态变成「UI 显示原画、实际下发 JPEG q0」。
+- **单帧上限 2MB → 6MB**（`WS_DEFAULT_MAX_SEND_BYTES`）：1280×720 的无损 PNG
+  整帧可达 3.5MB 量级，沿用 2MB 会让高熵内容的整帧被静默丢弃，
+  表现为画面冻结并反复 resync。
+- **切换档位时丢弃差分参考帧**：格式变化会改变参考帧的编码语义，
+  沿用旧基准会把新格式首帧差分成跨格式 tile。
+
+前端同步：`createImageBitmap` 不再声明 `image/jpeg`（原画档位是 PNG，
+声明错误的 MIME 会选错解码路径，改由内容嗅探）；画质下拉文案标注「原画（无损）」。
+
+> **兼容性**：帧协议未变更（`createImageBitmap` 按内容嗅探格式），
+> 新旧前端均可解码；但旧 bridge + 新前端会失去无损能力（仍为 JPEG）。
+
+## v1.9.164
+
+_发布日期：2026-09-26_
+
+### 项目级 / 角色级能力层（inherited 层）：bridge 侧落地
+
+能力配置由「全局默认 + 实例覆盖」两级升级为**四层逐键覆盖链**
+（角色实例 > 角色 > 项目 > 全局默认），本版本承接 bridge 侧全部落地。
+解析权威仍在 Java（`AgentCapabilityService.buildInheritedLayers` 产出「项目 ⊕ 角色」的
+增量层），bridge 只负责存储与逐键取用：
+
+- **能力布尔（MCP / Skill / 插件）**：per-agent 文件由「平铺 map」升级为
+  `{ overrides, inherited }` 双子对象；旧平铺文件读作 `overrides`，向后兼容。
+  取值链 `overrides > inherited > 共享默认(config) > deployedDefault > false`。
+  新增整表替换端点 `POST /runtime/{skills|mcp|plugins}/deployed/inherited`
+  （`{ agentId, inherited }`，null/缺省 = 清空本层），由 Java fan-out 推送。
+- **工具三态（disabled / collapsed / expanded）**：新增内存层
+  `inheritedFeaturesByAgent`，`getFeatureState` 改为
+  `实例显式 > inherited > 内置默认` 逐键解析；**分组父门禁**在合并视图上判定
+  （父主开关 `disabled` 则子能力一律未授权），与 Java `AgentAbilitySwitchService`
+  同口径。
+- **分层推送互不覆盖**：全局改动只动共享默认、项目/角色改动只推 inherited、
+  实例改动只推 overrides —— 因此删掉本层键即可自然露出下层值，
+  「恢复跟随上层」得以正确工作。
+- `/runtime/start` 与 `POST /instances/:id/features` 同步接收 `inheritedFeatures` /
+  `capabilitiesInherited` 字段（undefined = 不改动，避免误清空其它实例的推送值）。
+
+> **升级须知（重要）**：低于本版本的 bridge 不认识 inherited 层，会回退到
+> 「缺名 = 启用」的迁移期路径，导致**上层已禁用的能力仍被启用**。因此本版本要求
+> bridge 与 Java 端同批升级；环境变量四层链（v1.9.163 起）不涉 bridge 存储，滚动安全。
+
+### 工具批次归组：阻塞型通讯工具移出「并行执行工具」
+
+`poll_message` / `create_meeting` 这类核心阻塞型通讯工具不再进入工具批次：
+
+- **移出批次**（不进批次根事件、不带 `batchId`、不计入 `tool_batch_metrics` 的
+  `toolCount`/`traces`），时间线上按普通工具扁平展示；执行本身不变，仍由调度器排到
+  批尾串行（`poll_message` 的 while(true) 阻塞等待语义不受影响）。
+- 动因：这两者与本批其他工具毫无并行收益，归进「并行执行工具」卡片会造成双重误导——
+  卡片名宣称并行、实测 `speedup` 恒为 1.00x；`poll_message` 的阻塞等待也会被错觉为
+  批次成员。之前的批调用把 `search_memory` 与 `poll_message` 并列，既无加速、又难看懂。
+- 批次成立条件收紧为「**批次成员**数 > 1」：若排除后成员不足 2 个（如
+  `poll_message` + 单个 `write_file`），则不发根事件与指标，时间线完全扁平。
+- 运行时新增 `isMcpBatchExcludedToolName`（`mcpToolNames.ts`）作为批次排除判据；
+  与「MCP 超时策略」集合 `isMcpBlockingToolName` 语义分离。
+
+配套 Java 侧（同批发布）：`ProjectCapabilityOverrideService` 项目层存储（
+`project_capability_overrides:{tenant}:{projectId}`）、`AgentCapabilityService`
+四层解析与 source 细化（agent/role/project/bridge）、`AgentAbilitySwitchService`
+三态四层 + 分组门禁、`RuntimeBridgeService` inherited 推送与 fan-out、
+项目/角色能力配置接口与新建项目草稿落库。
+
+### 修复：Agent 回到 waiting_input 后长时间"空闲"（每次任务后约 10min 死区）
+
+现象：角色实例状态徽章长时间显示"空闲"，而时间线最新事件停在"编辑文件"；
+期间私信/流程线任务完全不消费，约 10 分钟后才自行恢复。
+
+根因（`AcodeSdkAdapter`）：`turn_complete` 的"用户消息轮调用了工作工具"分支
+（`!autoPollActive && observedAnyTool && !observedPollingTool`）原本只做 `return`——
+既不派发空闲提示词、也放弃了重臂。而 `waiting_input` 下 turn 级看门狗不计时，
+会话遂无任何定时器在看守，只能等 10min 会话存活看门狗兜底。
+且重试轮（`retryFailedRequest`，`autoPollActive=false`）同样命中该分支，
+而该路径不重置观察标记，上一失败轮残留的 `observedAnyTool` 使分支必然成立 →
+**每次任务结束都固定触发约 10min 死区**。
+
+修复（保留"不立即派发"的节流意图，改为**延迟重臂**）：
+- 新增 `ACODE_DEFERRED_IDLE_REARM_MS`（默认 3s，env 可覆盖）与
+  `scheduleDeferredIdleRearm()`：分支 2 不立即派发空闲提示词，但延迟后重臂监听，
+  把死区从 10min 压到 3s。刻意走 `scheduleAutoPoll` 而非 `armIdleLoopOrAutoPoll`，
+  避免配置了 polling 类 idle 命令时被 `IdlePollLoop`（0ms）架空延迟。
+- `armIdleLoopOrAutoPoll` 重臂前清除待触发的延迟定时器（只清 timer、不动退避档位），
+  防止延迟重臂与正常重臂双发。
+- `retryFailedRequest` 与其它提交入口对齐，重置 `autoPollObserved*` 三标记，
+  消除跨轮污染导致的"重试轮被误判为用户消息轮"。
+
+## v1.9.163
+
+_发布日期：2026-09-25_
+
+### 三级环境变量（全局 / 项目 / 角色实例）→ 工具子进程 + MCP 配置
+
+环境变量由单一「面板全局层」升级为**三级合并**（角色实例 > 项目 > 全局，择近优先），
+合并结果随 `/runtime/start` 下发，作用于 bridge 管理的工具子进程与 MCP stdio 服务器配置。
+Java 侧 `EnvVarResolver` 为唯一权威计算点，本版本承接 bridge 侧全部落地：
+
+- **per-agent 环境变量存储**：`panel-env` 由进程级单例改为按 agentId 键控。此前最后启动的
+  实例会覆盖整个 bridge 的环境变量（多实例静默串味）；现在各实例独立，桌面工具子进程按
+  调用方实例取值，切换实例时经 env 签名检测触发重启应用新值（`ownerAgentId` 记录归属）。
+- **MCP stdio spec 注入**：MCP 子进程**不继承 bridge 的 `process.env`**（MCP SDK 的
+  `StdioClientTransport` 只带 HOME/PATH 等少数键），故新增 `mcp-env-injector` 把有效环境变量
+  写入每个 stdio server 的 `env`。优先级：**server 自身 env > 三级合并结果 > SDK 默认继承项**；
+  内置 `agents-work-studio` 与 sse/http 服务器跳过。acode（per-instance acode.json 装配）
+  与 Claude SDK 两条适配器路径均已接入。
+- **`${VAR}` 占位符展开**：stdio spec 的 `env` 值与远程 spec 的 `url` / `headers` 值中的
+  `${变量名}` 按该实例有效环境变量展开（如 `Authorization: "Bearer ${API_KEY}"`）；
+  未命中的占位符保持原样，便于在 MCP 启动失败信息中定位拼写错误。
+- **子进程 env 安全名单**：新增 `utils/env-safety.ts`，把原 plugin-manager 的
+  `BLOCKED_ENV_KEYS` 集中为单点权威并新增 `sanitizeEnvForChild`，在面板环境变量入站、
+  MCP spec 注入、桌面子进程显式覆盖层三处统一把关（挡掉 `NODE_OPTIONS` / `LD_PRELOAD` /
+  `PATH` 等执行流劫持与宿主关键路径键）。
+
+配套 Java 侧（同批发布）：`EnvVarResolver` 三级合并与「空串=屏蔽」解析、`t_agent.env_overrides`
+实例层存储、项目级 `project_env_vars:*` 存储与掩码读写、有效值预览接口、三级配置 UI。
+
+## v1.9.162
+
+_发布日期：2026-09-24_
+
+### 工具懒加载：browser / desktop 收纳态展开链路打通（关键修复）
+
+v1.9.153 起 browser / desktop 改为**收纳态不注入会话工具列表**（缓存稳定化的
+前提：LLM 请求的 tools 前缀字节级不变，provider 前缀缓存全程命中），工具定义改由
+`expand_tools` 结果下发、执行经 `call_tool` 回传。但回传链路在重构中被删除且未补回，
+导致收纳态（默认档）下：
+
+- `expand_tools({group:"browser"})` 从本地 `exposedTools` 取 manifests → 收纳态下
+  必然为空（工具按设计就没注入），agent 拿到 0 个工具定义；
+- `call_tool({name:"browser_navigate"})` 找不到工具名 → 直接报「未知工具」；
+- bridge 侧 `POST /sessions/:agentId/capability-tools[/call]` 端点恢复后**没有任何调用方**
+  （原 MCP Server 中继 `setBridgeCapabilityTools` / `handleExpandTools` 已随重构移除）。
+
+本次以**同进程中继**补齐（不改 tools/list 载荷，缓存稳定性不回退）：
+
+- ACode 新增 `CapabilityToolRelay` 契约（`tool-group-manager.ts`）+ 运行时配置
+  `capabilityToolRelay`（`types.ts`），`expand_tools` / `call_tool` 的桥接组分支经其
+  回传；本地组（pencil / draw / office / launch / hire / task / meeting / debug /
+  fileHistory）路径完全不变。
+  - 展开：先中继（`setBuiltInCapabilityTools(expand)` 刷新定义缓存并授予调度授权、
+    返回 manifests），成功后才置本地展开态 —— 中继失败可重试，不留半展开态；
+  - `group="all"`：桥接组经中继拉 manifests，`disabled` 静默跳过、单组失败不阻断其余组
+    （该组 `call_tool` 会被拒并提示重新 expand，自愈）；收起时桥接授权全部回收；
+  - 调度：`findTool` 落空且工具名归 bridge 托管时，按 `call_tool` 三道闸同口径的
+    本地预检（`disabled` 拒绝 / 未展开引导 expand）后执行 `callBuiltInCapabilityTool`。
+- `AcodeSdkAdapter` 会话启动时注入中继（同进程直连，无 HTTP、无 token 依赖；
+  HTTP 端点 `capability-tools[/call]` 保留供外部/兼容调用）。无 `agentId` 时不注入，
+  退化为本地查找（与启动注入的缺省兜底一致）。
+
+配套测试：acode `tool-group-manager.test.ts` 新增「capabilityToolRelay」12 项（展开
+manifests 来自中继、幂等、失败不留状态且可重试、disabled 不触中继、group=all 混合
+本地+桥接+disabled、收起回收、调度透传参数/未展开拒绝/disabled 拒绝/错误透传/
+非桥接未知工具不触中继）；bridge `AcodeSdkAdapter.test.ts` 新增端到端用例
+（启动注入中继 → `expand` 下发 manifests 且不注入 exposedTools → `call` 执行 →
+`collapse` 后调度被拒）。bridge 套件 1473 通过 + 4 跳过、acode 743 通过。
+
+### 工具组：ACode 短 key ↔ 能力 featureKey 错位修复
+
+`collaboration.*`（流程任务 / 会议 / 调试日志 / 文件变更历史）与 `agentSys.launchItem` /
+`agentSys.hire` 的工具组短 key（`task` / `meeting` / `debug` / `fileHistory` / `launch` /
+`hire`）与完整 featureKey 不一致，ACode 侧把「收纳」误判为「禁用」（实测确认）：
+系统提示词把已授权能力显示为未开启、`expand_tools` 直接拒绝。本次新增
+`GROUP_KEY_TO_FEATURE` 映射与 `resolveGroupFeatureKey()`（`instance-features.ts`），
+`capabilityState` 回调先归一再取三态；同时补齐父门禁级联
+（`collaboration` / `agentSys` 主开关 `disabled` 时其子能力一律 `disabled`），
+与前端清除子键、Java 门禁传播同口径。
+
+工具组归属推断同时加固（`tool-group-manager.ts`）：不再只认 `key_` 前缀，注册的
+精确 `toolNames` 先于前缀命中，`listToolManifests` 忽略 MCP 的 `serverName__` 命名空间
+取裸名匹配 —— `my_task` / `create_meeting` / `query_debug_logs` /
+`query_file_changes_history` 等非前缀命名的 MCP 工具组据此正确归组与下发定义。
+
+### 协作能力分组：默认收纳 + 父门禁级联
+
+`instance-features.ts` 新增 `collaboration` 主开关与 `collaboration.task` /
+`collaboration.meeting` / `collaboration.debug` / `collaboration.fileHistory` 四个子能力
+（默认收纳），ACode 侧注册同名工具组；四个分组在收纳态下不进 LLM 工具列表，经
+`expand_tools` 展开后由 `call_tool` 调度。
+
+### 工具并发执行（资源驱动调度）
+
+新增 `tool-concurrency/` 子系统（`types` / `resource-lock` / `scheduler` /
+`observability`），ACode 一条 LLM 响应返回多个 `tool_calls` 时按**资源冲突关系**
+并发而非按工具类型分组，并新增运行时配置 `toolConcurrency`
+（`enabled` 默认 true、`maxReadOnly` 默认 8、`maxBash` 默认 0=不限）：
+
+- 资源键层级（`file:` / 目录前缀 / `bash:` 等）与祖先-后代判定；区间重叠即冲突；
+- 同资源读写按读写锁串行，写-写互斥；未声明并发策略的工具（如 bridge 注入的
+  `browser_` / `desktop_`）默认独占串行 —— 关闭 `enabled` 即退化为旧的串行行为；
+- `ToolTraceRecorder` 记录每个工具的 waiting_resource / running / completed 时序并聚合
+  批次度量（墙钟、并行度、等锁总时长、竞争次数、加速比），`ConcurrencyLimiter` 提供
+  只读 / Bash 并发上限；
+- 文件工具声明资源键（`buildFileResourceKey` / `fileResourceClaim`），读 `read`、
+  写 `write`。
+
+### 文件写入 stale guard（陈旧写入拒绝）
+
+新增 `read-file-state.ts`：`read_file` 记录 mtime / size / 内容快照，`edit_file` /
+`write_file` 落盘前比对，文件在上次读取后被外部修改（且内容与快照不匹配）时拒绝写入
+并提示模型重读，避免并发会话/外部编辑器改动被静默覆盖。运行时开关
+`enableStaleFileGuard`（缺省启用，`false` 关闭比对；状态仅存内存，`stop()` 清空）。
+
+### 工具权限：新增 `fileModificationOutside` 档位
+
+「限制操作」新增工作区外文件修改权限（`fileModificationOutside`），
+`resolveAgentToolPermissions` 全 allow 兜底值同步补齐，热推路径显式下发默认值以
+清除历史限制。
+
+### 会话启动令牌吊销与运行时钟强化
+
+- `RuntimeGlobalSettingsService` 启动时吊销历史运行令牌，避免重启后旧令牌继续可用。
+- `terminal.ts` 抽出 `isIdleStatusChangeRetryable()`：`waiting_input` 纯状态切换
+  （`turn_complete` 仅带 usage、不带 `actionType`）也纳入 idle 串行重试队列，
+  修复该类状态切换漏到零重试路径的问题；原 `!params.actionInfo` 空判改为
+  `!params.actionInfo?.actionType`。
+
+### LTR 临时文件读取端点
+
+`POST /api/ltr/read`：按绝对路径返回 LTR 临时文本内容，安全校验拒绝 `LTR_ROOT`
+目录树之外的路径（防路径穿越），文件不存在 404、非文件 400、上限 512KB。
+
+### Agent Todo 重置与 acode-todos 路由
+
+`AgentTodoService` / `routes/acode-todos.ts` 支持重置（清空）会话待办列表，
+配套 `acode-todos.test.ts` 覆盖重置语义。
+
+### 空闲监听指令（poll_message）措辞收敛
+
+`MESSAGE_POLLING_IDLE_PROMPT` 改为显式前置条件：「此指令仅在当前没有未完成任务时生效；
+若仍在处理任务请忽略本指令并继续执行」，仅在确认无进行中/未完成任务时才调用
+`poll_message`，降低任务中途被空闲轮询打断的概率（三个 adapter 的单测改为从
+`prompts.ts` 导入常量，避免文案与断言再次脱节）。
+
+### 依赖与其它
+
+- `aws-client-agent-mcp` 新增 `temml`（Office 公式渲染）依赖，新增
+  `office_format` / `office_apply_profile` / `office_generate_from_template` 三个
+  Office 工具及 `office-equation.ts` 公式模块（含测试）。
+- `AcodeSdkAdapter` 恢复 `POST /sessions/:agentId/capability-tools[/call]` 路由，
+  `resolveAdapter(providerId)` 按会话 providerId 解析适配器；sessions 测试 29 项通过。
+- 版本号 1.9.157 – 1.9.162 为连续未发布开发周期（npm 上仍为 1.9.153），
+  本次一并发布。
+
+## v1.9.161
+
+_发布日期：2026-09-18_
+
+### Office 题注位置与回执提示修复（依据 v4 回归报告 N7/N8）
+
+**N7：`captioned_table` 题注位置对齐中文论文规范**
+
+中文论文（学位论文）规范要求「图题在下、表题在上」，本项目脚本产物同样如此；
+此前 `captioned_table` 一律把题注插在表格**下方**，用工具链重做论文逐页比对时会显现差异。
+现按元素类型区分默认位置：
+
+- `captioned_image`：题注默认在图片**下方**（行为不变）
+- `captioned_table`：题注默认在表格**上方**
+- 新增 `props.captionPosition`（`above`/`below`，兼容 `top`/`before`/`bottom`/`after`）显式覆盖
+
+实现：新增 `insertParagraphBeforeElement`（表题在上的插入路径）；章内序号统计按位置
+（章标题之后、插入点之前）计算，因此「表题在上」不改变编号连续性。
+
+**N8：`office_edit` 回执未透传服务端 warnings**
+
+服务端（Java）已在 `chapterHeadingStyle=false` 等场景返回 `warnings`，但 bridge 层
+`officeEdit` 组装回执时丢弃了该字段，使用者无法感知「F9 后编号不会按章重启」的风险。
+现原样透传 `warnings`（服务端未返回时不产生空数组噪音）。
+
+配套回归测试：`OfficeDocxPrecisionTest` 新增 4 个用例（表题默认在上、图题默认在下、
+captionPosition 显式覆盖、表题在上时序号连续）；bridge `mcp-server.test.ts` 新增 2 个
+用例（warnings 透传、无 warnings 时不含该键）。office 测试总数 179 全通过；
+Word COM F9 实测题注编号稳定（表1-1/表1-2/表2-1、图1-1/图1-2/图2-1）。
+
+### ACode 模型请求失败重试不再重置上下文
+
+模型请求超时/网关 5xx/看门狗中止后的重试此前会重新走主动压缩预检：一旦累计或估算
+用量越过阈值，与上下文大小无关的失败重试也会裁剪+摘要化历史，表现为「重试后上下文
+被重置」。本次修复：
+
+- **恢复式重试（resume，与失败请求逐字节一致）**：非溢出的普通失败（5xx/超时/看门狗）
+  后，适配器以 `resume: true` 恢复同一轮——不重发 prompt 钩子、不重复 push 用户消息、
+  **不回滚轮内进展**（工具结果/部分输出原地保留），基于与失败请求同一份 conversation
+  重建请求：重试请求与上次失败的请求逐字节一致，重试之前的状态不丢失。原先的失败轮
+  锚点回滚（`rollbackFailedTurn`）会把会话截回 turn 开始前、丢弃轮内已成功的迭代，已移除。
+- **轮级跳过压缩**：重试 submit 携带 `skipProactiveCompaction`（resume 隐含），覆盖整轮
+  全部 LLM 迭代，并同时约束 800KB 请求体字节上限截断（`truncateConversationIfNeeded`），
+  旧版 `markSkipNextCompaction()` 单次标记兼容保留；仅 provider 显式溢出信号（错误字段/
+  `finish_reason`）触发响应式压缩重建，413 溢出仍正常兜底——上下文改写只属于溢出响应。
+- **结构化溢出判定**：新增 `context-overflow.ts`（cause 链下钻 + 字段级标记 + 精选消息
+  片段），`length`/`max_tokens` 被输出长度标记独占短路，绝不因输出上限触发压缩。
+- **4xx 确定性错误短路重试**：invalid_request 类错误直接 `retry_aborted`（「请求无效」），
+  5xx/超时仍按指数退避+抖动重投。
+
+配套回归测试：acode `runtime.test.ts` 新增/强化 5 个用例（resume 重试请求体逐字节一致
+且不重复 push、中途失败保留轮内工具结果后 resume 与失败迭代逐字节一致、整轮跳过主动
+压缩、legacy 单次标记、重试轮跳过 800KB 字节截断而普通轮照常截断）；bridge
+`AcodeSdkAdapter.test.ts` 断言重试提交携带 `resume + skipProactiveCompaction`，并含
+4xx 短路与重试计数语义用例（套件 82/82 通过）。
+
+## v1.9.160
+
+_发布日期：2026-09-18_
+
+### Office 题注编号与格式检查修复（依据 v3 回归报告 N1-N6）
+
+**N1（高）：SEQ 域 `\s` 值写成了章号，F9 后含小节的章出现重复编号**
+
+`\s N` 的 N 是**标题级别**（1-9），不是章号。原实现写 `SEQ figure \s <章号>`，导致：
+含 H2 小节的章在每次小节标题处错误重启（实测 Word F9 后 图2-1 重复出现），
+第十章还会写出超范围值 `\s 10`。现固定为 `SEQ figure \s 1`（按 1 级标题重启），
+章号只体现于静态前缀；章内序号改为按「本章范围内、插入点之前」的实际域数量统计
+（`countSeqFieldsBefore`），与 `\s` 值彻底解耦。
+
+**N2（中）：题注按章重启依赖章标题具备「标题 1」样式，此前不校验也不提示**
+
+Word 的 `\s 1` 按**样式名为内置「标题 1」**的段落重启（COM 实测：仅补直接格式
+`outlineLvl` 或自定义名样式均无效）。而论文类模板常把章标题写成直排格式（无样式），
+此时 F9 后编号会跨章累计。修复：
+
+- `captioned_*` 在 `chapterTracker=auto` 时自动为识别出的章标题补「标题 1」样式
+  （新增 `DocxStyleOps`：找样式 → 套用并逐项还原差异 → 若仍不等价则回退到工具自建的
+  **最少格式「标题 1」样式**，保证可见外观零变化）
+- 新增 `props.chapterHeadingStyle=false` 可关闭自动补样式（回执带 `warnings` 说明风险）
+- `office_edit` 回执新增 `warnings` 字段
+
+**N3（低）：`props.heading` 传数字不生效（静默）**
+
+数字 `1`、字符串 `"1"`、`"Heading1"`、`"标题 1"` 现均可用；非法值（`"abc"`、越界 `4`）
+改为**显式报错**，不再静默不加样式。
+
+**N5：check 空段落噪音**
+
+`office_format` 默认跳过无文本段落（空段落/纯图片段落）的正文类检查与修正，
+summary 增加 `skippedBlankParagraphs`；`rules.blankParagraphPolicy="report"` 可恢复旧行为。
+实测重生成论文违规数 421 → 199（其中 222 条为纯空段落噪音）。
+
+**N6：preset 与模板实测口径统一**
+
+- profile 聚合修正「非空众数」偏差：此前 114 段中仅 1 段 `bold=true` 也会输出 `bold=true`
+  （回灌 apply_profile 会把全文错误加粗）；现按全量多数票取值，未显式设置的属性不输出
+- 新增 `OfficeFormatPresets.merge(base, overrides)` 与 `office_format` 的 `mergePreset=true`：
+  以 preset 为基线、实测 profile 逐键覆盖（page/rules[role].props/roles），
+  解决「preset 期望黑体 vs 模板实测宋体」的系统性差异导致的验收比对失真
+- 合并时归一「首行缩进/悬挂缩进」互斥（OOXML 中两者共存只有悬挂生效，会造成
+  check 期望与实际永不收敛）；写入端同步加固
+
+**实测验收**：模板实测 profile + preset 合并后，对重生成论文 check→fix→check
+收敛 219 → 0；对既有论文 179 → 0（此前因缩进互斥存在 12 条不可收敛残留）。
+
+配套回归测试：`OfficeDocxPrecisionTest` 新增 11 个用例（SEQ 恒定值、同章序号解耦、
+章标题样式自动补/外观保持/可关闭、heading 数字与非法值、空段落跳过与 report 策略、
+preset 合并与缩进互斥收敛、profile null 噪声）；office 测试总数 175 全通过。
+
+### office 卡片：指定文件强校验 + 预览链接服务端权威化
+
+**背景**：office 卡片的 `card.previewUrl` 此前由 agent 自报、bridge 与 Java 两端均无校验
+（纯透传），前端直接塞进无 sandbox 的 iframe——agent 可拼造任意地址（含站外页面）。
+同时卡片引用的文件是否真实存在没有任何服务端校验。
+
+**新契约**：office 卡片只能用 `filePath`（工作区路径）或 `docId`（云文档 id）之一指定
+文件，二者必居其一、不可同时传；`previewUrl` 从入参契约中移除，由服务端生成。
+
+- **bridge（发送前校验，失败即工具调用失败、消息不发送）**：`buildOfficeCardPayload`
+  重写——filePath 经 `packOfficeFile` 统一校验（存在/普通文件/docx-xlsx-pptx/≤16MB）后
+  上传，载荷换成 `{type,name,kind,fileUrl,sizeKb,title,filePath,workspacePath}`；
+  docId 路径本机零上传，载荷只带 `{type,docId,title?,description?}`；
+  两者同传 / 都缺 / 只传 fileUrl 均抛错。入参即使携带 `previewUrl` 也被丢弃。
+- **服务端（落库前权威校验）**：`McpToolHandler.toCardJson` 的 office 分支改为委托
+  `OfficeToolHandlers.normalizeOfficeCard`——校验 filePath/docId 二选一；filePath 路径
+  按 `fileUrl` 反解存储名并 `loadFile` 确认文件真实存在；docId 路径经
+  `OfficeCloudDocService.findDoc` 校验云文档有效（不存在则工具调用失败、消息不落库）
+  并回填 name/kind/fileUrl/sizeKb。
+- **预览由服务端生成**：取权威文件字节 → `OfficeDocService.buildPreviewHtml` →
+  `FileStorageService.storeFile("...-preview.html", ...)` → 服务端 `previewUrl` 写入卡片。
+  文件字节无法解析（损坏/伪装扩展名）时发送失败，杜绝「卡片指向不存在的文件」。
+- **工具描述**：`send_group`/`send_private` 的 `card` schema 删除 `previewUrl` 属性，
+  `docId`/`filePath` 描述改写为「二选一」口径；`office_preview` 描述改为「返回地址供自检/
+  留档，卡片预览由服务端生成」。
+- **dashboard**：新增 `utils/officeCardUrl.ts` 信任边界（`fileUrl` 只放行本站
+  `/api/files/` 地址，`previewUrl` 额外要求 `.html`；伪协议/携带凭据/站外链接一律拦截），
+  `ChatPanel.vue` 的预览按钮、点击、下载统一走该校验；预览 iframe 加
+  `sandbox="allow-same-origin"` 与 `referrerpolicy="no-referrer"`；卡片带 `docId` 时
+  「面板打开」直接按 docId 打开 Office 面板（跳过工作区路径匹配）。
+
+配套回归测试：bridge `mcp-server.test.ts` 新增 office 卡片 9 个用例（上传路径/预览地址
+丢弃/文件不存在/非 Office 扩展名/docId 零上传/二选一冲突/两者都缺/只传 fileUrl/DM 路径），
+`mcp-tools.test.ts` 新增 schema 契约 2 个用例；dashboard `officeCardUrl.test.ts` 7 个用例。
+
+## v1.9.159
+
+_发布日期：2026-09-17_
+
+### Office 回归修复（依据 v1/v2 回归报告）
+
+**严重：lineSpacing 提取值错误（会导致排版全毁）**
+
+`office_view(mode=profile)` 提取的 `body_text.lineSpacing` 为 `0.075` 而实际应为 `1.5`——
+`DocxStyleResolver` 已把 twips 转为磅值，profile 聚合时又按 twips 除以 240（等效多除 20）。
+现改为 `pt / 12` 得到倍数，与规则引擎 `normalizeLineSpacing` 对齐；提取值回灌
+`office_apply_profile` 后行距正确（360 twips = 1.5 倍）。
+
+**chapterTracker 跨章失效**
+
+`captioned_image` / `captioned_table` 在第二章后仍生成「图1-1」。修复：
+
+- 按 `before`/`after`/`index` 解析真实插入落点（而非扫描全篇）
+- 章号判定同时支持 Heading1 样式、大纲级别 0、「第X章」中文数字（`chineseNumeralToInt`）
+- 章内序号按 `SEQ ... \s N` 分组计数，跨章正确重启
+
+**SEQ 域缓存值与静态前缀叠加（显示「图1-1 前台首页1」）**
+
+题注以 `{seq}` 为界拆分为「静态前缀 run + SEQ 域 + 静态后缀 run」，域缓存值即章内序号，
+Word/WPS 打开即为正确编号，F9 刷新后保持一致。
+
+**heading1 角色漏识别**
+
+`OfficeRoleDetector` 新增大纲级别判据与中文样式名支持（`headingLevelOfStyle`：`Heading 1` /
+`标题 1`），章标题正则放宽空格并补充裸数字章标题兜底。
+
+配套新增 10 个回归测试；office 测试总数 161 全通过。
+
+## v1.9.158
+
+_发布日期：2026-09-17_
+
+### Office 模板对齐类文档生成增强（F1-F6）
+
+将「参考模板 → 逐项对齐样式 → 一键出稿」的论文类任务能力沉淀为 office 工具链通用能力，
+仍基于 Apache POI 纯格式层（无 COM、无外部进程）。新增 2 个工具 + 2 个 office_view 模式，
+扩展 office_edit 两种带题注元素与表格列声明。
+
+**新工具**
+
+- `office_apply_profile`：按样式 Profile 对匹配角色段落规整字体/字号/行距/缩进/对齐 +
+  页面设置 + 标题编号；值稳定（重复应用不回退、不翻倍）。
+- `office_generate_from_template`：`{{var}}` 全文跨 run 替换 + 内容清单注入
+  （heading/paragraph/image/table/pageBreak）+ 可选 profile 应用；`outputFile` 指定时保留模板。
+
+**office_view 新 mode**
+
+- `profile`：从模板 docx 提取按角色聚合的样式 Profile（page/roles/rules/numbering），
+  作为 apply_profile 的输入；role 附 `matchSource`/`sampleText`/`paragraphCount` 审计元数据。
+- `selfcheck`：按分页符拆页，逐页 `textDigest` + 标题层级跳跃/图片溢出/宽表 warning，
+  并复用规则引擎补充格式违规检查。
+
+**office_edit 扩展**
+
+- `add type=captioned_image / captioned_table`：一条命令插入图片/表格 + 居中题注段
+  （SEQ 域，Word F9 可刷新）；`caption`/`captionText` 双字段兼容；`chapterTracker=auto` 自动判章。
+- `add type=table` 新增 `columns: [{widthPt, align}]` 列宽（pt→dxa）与列对齐声明。
+
+**回归修复**
+
+- 修复 `office_create` 漏传 `template` 参数（bridge 侧）。
+- 修复 `captioned_*` 题注未写入（参数名不一致 + 题注段与内容段共用锚点）。
+- 修复 `office_generate_from_template` 的 `outputFile` 不生效（模板被就地污染）。
+- profile 角色识别增强：TOC/附录等辅助样式不再污染正文/标题统计。
+
+详见 `docs/Office文件操作能力实施方案.md` §12。
+
+## v1.9.157
+
+_发布日期：2026-09-16_
+
+### Office 精准操作能力大版本：Word 内核 / Excel / PPT / 公式 / 规则引擎
+
+对标参考开源实现（WordFormat、学术 skills 等）完成 Office 三件套从「能创建」到
+「精准操作」的升级：run 级定位、批注修订、公式目录页码、版式占位符、格式规则
+检查与一键修正。全部基于 Apache POI 5.2.5 纯格式层实现，无 COM/无外部进程。
+
+**Word 精准编辑内核（docx）**
+
+- 路径寻址扩展：`/body/p[N]/run[M]`（run 级）、`/body/table[T]/row[R]/cell[C]`（单元格）、
+  `/body/sectPr`（页面）、`/body/header|footer`（页眉页脚）
+- 新增 `DocxStyleResolver`：docDefaults → basedOn 链 → 直接格式的**有效格式解析**
+  （含主题字体兑现），支撑 `view styles` 与规则引擎「改得准、查不误报」
+- 新能力：`op=replace`（跨 run 保格式查找替换）、批注（写/读/删，五件套部件）、
+  修订（tracked 编辑 + accept/reject）、目录 TOC 域 + updateFields、PAGE/NUMPAGES/SEQ 域、
+  页码页脚、书签 + 外链/内链超链接、**引用上标 [n] + 锚点内链**、OMML 公式（行内/块级/编号公式三列表）、
+  **自定义标题编号**（第%1章模板 + 清除手动编号）、三线表（threeLine 预设）、
+  段落字符单位缩进（firstLineChars）、中英文字体三槽（fontEa/fontAscii/fontHAnsi）
+- `office_create` 支持 `template: cn-thesis`（A4+2.5cm、宋体/黑体样式体系、标题编号、页码）
+- `office_view` 新 mode：`styles`（有效格式）、`comments`、`revisions`、`search`（query 定位）
+- `office_validate` 增加 OOXML 结构检查：批注范围配对、w:del/w:ins 规范、xml:space
+
+**Excel 增强（xlsx）**
+
+- `add chart`（bar/column/line/pie/doughnut/area，XDDF 原生图表）、单元格批注、
+  数据验证（list/whole/decimal/date/textLength/custom）、条件格式（cellIs/containsText/colorScale）、
+  带位移插入/删除行（不覆盖相邻数据）、按范围拆分合并、富文本单元格（runs 数组）、
+  定义名称、页面设置（方向/缩放/打印区域）、自动筛选、行列隐藏
+
+**PowerPoint 增强（pptx）**
+
+- 演讲者备注（`set /slide[N]/notes`，view notes 读取）、**版式感知创建**（add slide + layout/layoutIndex，
+  view layouts 清单）、占位符直接赋值（`/slide[N]/placeholder[type|idx]`，保留模板样式）、
+  全 deck 查找替换（可限定单页）、表格单元格写入（`/shape[M]/cell[R][C]`）、
+  形状旋转/z-order（up/down/top/bottom）/超链接、**幻灯片克隆**（op=clone：复制文本/图片/备注/版式，
+  源页隔离，插入位置可控）
+
+**公式链路（bridge）**
+
+- 新建 `src/office/office-equation.ts`：`props.latex` → temml（MIT）LaTeX→MathML →
+  自研 MathML→OMML 转换（覆盖分数/根式/上下标/极限/求和积分/矩阵/括号分组），
+  失败时给出可读错误；`office_edit` 自动预处理 latex → omml 上行 Java 注入
+
+**格式规则引擎（差异化能力）**
+
+- 新工具 `office_format`：`{file, action: check|fix, preset|rulesFile|rules, annotate?, outputFile?}`
+  - 角色识别（三层）：Word 样式 → 正则启发式（第X章/图题/摘要/参考文献等）→ 显式匹配器
+  - 检查：逐角色比对期望格式 → 违规清单（path/role/property/actual/expected/fixable/severity）+ 摘要；
+    `annotate:true` 把违规写成 Word 批注生成标注版（不覆盖原件）
+  - 修正：确定性项自动改（字体三槽/字号/加粗/对齐/行距/缩进/编号/手动编号清除），判断类只报告
+  - 预置：`cn-thesis`（学位论文）、`cn-report`（公文）；rulesFile 支持工作区 YAML/JSON
+- 收敛性验证：fix 后复查零违规（加权优先级 + 半磅字号 + 悬挂缩进语义）
+
+**预览增强（docx HTML 预览）**
+
+- 批注标记（含正文悬浮）、修订 ins/del 着色、公式文本化、TOC 占位、
+  域友好占位（〔页码〕）、超链接渲染为可点击 a[href]、上下标
+
+**测试**
+
+- Java：新增 `OfficeDocxPrecisionTest`（25 用例）、`OfficePptxAdvancedTest`（11 用例）、
+  `OfficeFormatEngineTest`（9 用例）等，全量 1442 用例通过
+- bridge：新增 `office-equation.test.ts`（17 用例）+ mcp-tools 描述契约测试；
+  `tsc` 与本套件通过
+- 前端：`officeTimeline` 支持 office_format 事件刷新，测试补齐
+
+## v1.9.156
+
+_发布日期：2026-09-13_
+
+### Office 三件套能力升级：图片、排版、形状
+
+按照 genoffice 对标，大幅增强 Office 文件引擎和工具描述，agent 现在可以生成含图片、列表、格式化表格的工作级文档。
+
+**Java POI 引擎**（OfficeDocService.java）
+
+- **图片基础设施**：严格 Base64 校验 + 魔数嗅探（PNG/JPEG/GIF/BMP/TIFF，WebP 等明确拒绝）+ ImageIO 像素尺寸读取 + 等比缩放辅助
+- **docx 新增**：`add image`（source 支持工作区路径 / http URL / data URL → bridge 侧解析，Java 无状态接收 imageBase64）、`add pageBreak`、列表（`list: "bullet"|"number"` + `level: 0-2` 惰性初始化 XWPFNumbering）、`set /body header/footer`、段落 `pageBreakBefore`
+- **xlsx 新增**：单元格 `numberFormat`（`0.00%`、`¥#,##0`、`yyyy-mm-dd` 等）、`border`+`borderColor`（thin/medium/thick/dashed/dotted/double）、`wrapText`、`valign`（top/center/bottom）、工作表 `colWidth`（px）、`rowHeight`（pt）、`freeze`（行/列）、`add merge`（range 字符串）、`add image`（anchorCell + 图片字节 → XSSFDrawing）
+- **pptx 新增**：`add image`（fit=contain/cover/stretch，cover 写 srcRect 裁剪）、`add shape`（rect/roundRect/ellipse/triangle/diamond/chevron 等 + fillColor/lineColor/lineWidth + 垂直居中文字）、`add table`（均分列宽行高 + header 加粗）、`set /slide[N] background`（十六进制背景色）、`remove /slide[N]/shape[M]`（含图片/形状）、列表（`list: "bullet"|"number"` + bullet 三级字符差异）
+- **view 升级**：stats 增加 `images` 计数、图片段落/形状标注 `（图片）`
+- **preview 预览**：三格式含图片标注
+
+**bridge 侧**（aws-client-agent-mcp）
+
+- 新建 `src/office/office-image.ts`：`officeResolveImageSource(source)` 支持三种图片来源（data:image URL / http(s) URL / 工作区路径），含魔数校验和严格格式约束；`prepareOfficeImageCommands(commands)` 预处理 office_edit 命令中的 props.source → imageBase64
+- `mcp-server.ts`：`officeEdit` 新增调用 `prepareOfficeImageCommands`，使图片 URL/路径自动解析为 base64 上行 Java 引擎
+- `mcp-tools.ts`：`OFFICE_EDIT_TOOL` 描述重写为三格式完整能力清单 + 图片通用规则 + 使用要点；props schema 补充所有新增字段
+- 测试 `office-image.test.ts`：11 测试全通过
+
+## v1.9.155
+
+_发布日期：2026-09-13_
+
+- Office 文件能力面板化（与 pencil / draw 画布面板同款体验）：Agent 可在 Dashboard
+  面板中实时查看自己创建/编辑的 Word / Excel / PowerPoint 文档。
+  - aws-client-agent-mcp：office 工具组新增 3 个面板工具——`office_open_document`
+    （校验工作区文件存在并返回 file/kind/sizeKb/workspacePath，驱动前端打开面板）、
+    `office_close_document`（收起面板）、`office_list_open`（列出本会话已打开的文件）；
+    `office_create` / `office_edit` 返回值补充 `kind` 字段，供前端时间线提取器维护
+    文件列表（Agent 行徽标计数）；工具描述同步引导「打开面板即可实时看到编辑效果，无需截图」。
+  - aws-mcp-server：`OfficeToolHandlers` 注册同款 3 个 handler（open 校验扩展名并归一
+    kind；close/list 为轻量信封），`TOOL_NAMES` 扩为 8 个——office 能力门禁
+    （`checkAbilityGate`）自动覆盖新工具；新增 `OfficeToolHandlersTest`（8 用例）。
+  - aws-dashboard：新增 `OfficePanel.vue`（docx 用 docx-preview、xlsx 用
+    @vue-office/excel、pptx 用 pptx-preview 本地渲染，注册 workspace watch 后经
+    FILE_CHANGED 事件自动刷新，头部按类型显示 Word/Excel/PPT 彩色徽标）；
+    `useAgentTimeline` 新增 `extractOfficeDocInfo`（解析逻辑抽为可单测的
+    `officeTimeline.ts`，覆盖 call_tool 懒加载包裹形态）；index.vue 完成桌面/移动端
+    面板挂载、可拖拽宽度注册（office: 720/480/1200）与 Agent 行 Office 徽标按钮；
+    ChatPanel office 卡片新增「面板打开」入口（卡片载荷携带 filePath/workspacePath，
+    同工作区时可直接在面板中打开原文件）。
+  - 修复 `writeOfficeFileAtomic` 对非法 Base64 静默解码的存量问题（Node
+    `Buffer.from(x,"base64")` 宽容语义），改为严格字符集 + 长度校验后再解码。
+
 ## v1.9.153
 
 _发布日期：2026-09-12_