dsh-my-observability 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,89 +2,19 @@
 
 本文件记录 dsh-my-observability 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [0.3.0] - 2026-09-07
+## [0.3.2] - 2026-09-17
 
 ### 变更
 
-- feat(observability): #155 错误上报统一——plugin_error 事件类型 + /errors API (#177)
-- feat(observability): #155 资源监控扩展——新增 $DSH_HOME 目录总大小监控 (#176)
-- feat(observability): #155 插件状态查询聚合——统一 status-query 事件 + /plugin-status API (#170)
-- chore(plugins): #165 清理失效的 dsh.client.inject 声明（13 插件） (#167)
+- docs: skill 合并 12→10 并拆分超限文件，修 observability 聚合端点缺陷
+- docs(清理): #341 文档瘦身 23765 → 8309 行并固化精简规范 (#348)
+- chore(artifacts): #318 同步 8 处共享件产物漂移 + 新增产物一致性门禁（fail-closed） (#325)
+- fix(test): cucumber-js --import glob 改用双引号，兼容 Windows
+- fix(security): 批量修复 'Insecure temporary file' 安全漏洞
+- chore: 项目全面优化和完善
 
-## [0.2.0] - 2026-09-07
+## [0.3.1] - 2026-09-10
 
 ### 变更
 
-- feat(observability): #155 错误上报统一——plugin_error 事件类型 + /errors API (#177)
-- feat(observability): #155 资源监控扩展——新增 $DSH_HOME 目录总大小监控 (#176)
-- feat(observability): #155 插件状态查询聚合——统一 status-query 事件 + /plugin-status API (#170)
-- chore(plugins): #165 清理失效的 dsh.client.inject 声明（13 插件） (#167)
-
-## [0.1.7] - 2026-09-06
-
-### 变更
-
-- fix(task-reliability,observability): #165 Session.events 迁移——snapshotEvents 优先 + 旧 API 兜底 (#166)
-- feat(observability,task-reliability): #154 插件关键行为纳入事件审计（干预/ask 决策/救场/verify/恢复）+ 文件体积控制 (#158)
-- fix(observability): #142 dispose 落盘链可等待，修复 release 门禁 flaky 测试 (#148)
-
-## [0.1.6] - 2026-09-04
-
-### 变更
-
-- fix(observability): 轨迹回放会话下拉可读标题（首条用户消息）——此前只展示 UUID 清单
-
-## [0.1.5] - 2026-09-04
-
-### 变更
-
-- feat(observability): #127 资源看门狗自动降级——写入速率/文件大小连续 ≥3 次采样超限自动暂停落盘（事件仍入内存，FIFO 有界不丢）+ 日志告警；连续 ≥3 次正常自动恢复（全量快照补齐降级窗口）；API 暴露 degraded 标记（#136）
-- 发版前功能级验证清单（issue #67）：verification/dsh-my-observability-0.1.5.md
-
-## [0.1.4] - 2026-09-03
-
-### 变更
-
-- feat(observability): #R17 资源监控看板——写放大/资源超限提前发现
-
-## [0.1.3] - 2026-09-03
-
-### 变更
-
-- fix(observability): 审计持久化改增量追加，根治写放大磁盘风暴
-- feat(observability): #89 审计日志搜索/过滤 + JSON/CSV 导出 (#120)
-- docs: #106 安装命令统一加 --trust-lockfile (#113)
-
-## [0.1.2] - 2026-09-01
-
-### 变更
-
-- fix(ui): 9 个插件未定义 token danger-primary 改用 error-primary（DSH 主题仅定义 business/error/success/warn）
-
-## [0.1.1] - 2026-08-28
-
-### 变更
-
-- feat(ui): dsh-my-observability 时间轴翻新——类型图标/连线节点/前缀（issue #54）
-- fix(security): 修复 CodeQL 告警——正则 ReDoS/随机数/命令注入（issue #5/#6/#7/#9/#10）
-- refactor(shared): 抽取 dsh-shared 共享工具包，10 个插件迁移消除重复实现（issue #45）
-- chore(deps): 升级 react 19 兼容性——13 个插件 peer 声明 ^18.2.0 || ^19.2.0（issue #49）
-- style(format): 全仓 prettier 格式化（issue #44）
-
-## [0.1.0] - 2026-08-28
-
-### 新增
-
-- **事件审计（issue #53）**：监听 `agent/status`（agent_status，含顶层/子代理标记）、`llm/stream`（llm_stream，同步包装流透传全部 chunk，记录开始/结束/错误 + chunk/字符/耗时统计）、`tools/pre-execute`（tool_call，工具名 + 参数键列表 + 文本摘要截断）、`tools/execute`（tool_result，成功/失败 + 耗时）；waterfall 一律透传 `next()`，只读观察不改变流程。
-- **审计持久化**：`$DSH_HOME/observability/audit.json`（防抖 500ms + 原子写 tmp+rename + teardown flush），启动异步加载（加载前事件缓冲不丢），重启后完整恢复；按会话隔离；每会话 2000 条 / 全局 20000 条上限防膨胀。
-- **轨迹回放面板**：侧边栏页签 `dsh-my-observability:replay`（dsh-better-sidebar 服务），会话选择 + 类型过滤（全部/状态/模型流/工具）+ 时间轴事件列表（徽标 + 时间 + 摘要）；可见时 5s 轮询、隐藏时暂停。
-- **结构化 Git 工具**：侧边栏页签 `dsh-my-observability:git`——仓库状态（分支 + 暂存/未暂存计数）、差异查看（工作区/暂存区）、类型化提交（Conventional Commits：type 枚举 feat/fix/docs/style/refactor/test/chore + 可选 scope/body，服务端生成消息 + execFile 执行 git 不经 shell）。
-- **增量 diff 审查**：`POST /observability/api/review`——unified diff 解析 + 8 条规则引擎（secret-leak/conflict-marker 为 error，debug-statement/large-diff/binary-file 为 warning，todo-marker/trailing-space/no-test-change 为 info）；可选 AI 审查增强（agents.create，超时/失败/解析失败降级，规则结果不受影响）。
-- **查询接口**：`GET /observability/api/events`（会话事件，type 过滤 + limit）、`GET /observability/api/sessions`（会话列表）、`GET /observability/api/status`（审计统计 + 开关）；全部经 loopback 信任围栏。
-- **测试**：`test/host-audit.mjs`（事件监听/会话隔离/重启恢复/上限/fence）、`test/host-git.mjs`（真实临时 git 仓库 status/diff/commit）、`test/host-review.mjs`（规则引擎 + AI 各路径）、`test/host-mutation.mjs`（变异补充）、Gherkin 验收（observability/git/review 3 个 feature 16 场景）；覆盖率 行 95% / 分支 85%；变异测试 ≥70%。
-
-**真实环境验证**（独立端口 3081 隔离实例）：
-
-- 侧边栏「轨迹回放」页签出现，时间轴展示真实 agent 行为（状态/模型流/工具调用）；
-- 「Git 工具」页签：真实仓库状态/差异/类型化提交/提交前审查全流程可用；
-- 重启验证实例后审计事件恢复。
+- feat(ts): 第四轮 JS→TS 迁移（5 个插件，server + client 全量）

package/README.md

@@ -7,101 +7,43 @@
   <img alt="Git 工具面板：仓库状态 / 差异 / 提交前审查 / 类型化提交" src="https://unpkg.com/dsh-my-observability/assets/git-panel.png" width="640" />
 </div>
 
-**DSH 可观测性 + Git 工程工具插件**：**事件审计**记录 agent 的每一次行为（状态变化 / 模型流 / 工具调用与结果），**轨迹回放面板**在侧边栏按时间轴回放会话轨迹；**结构化 Git 工具**提供 Conventional Commits 类型化提交；**增量 diff 审查**在提交前用规则引擎（可选 AI 增强）检查调试残留、密钥泄露等问题。
+**dsh-my-observability**：DSH 可观测性 + Git 工程工具插件——**事件审计**记录 agent 的每一次行为（状态变化 / 模型流 / 工具调用与结果），**轨迹回放面板**按时间轴回放会话轨迹；**结构化 Git 工具**提供 Conventional Commits 类型化提交；**增量 diff 审查**在提交前用规则引擎（可选 AI 增强）检查调试残留、密钥泄露等问题。
 
 ## 功能
 
-### 1. 事件审计（agent 行为可追溯）
-
-Server 端只读观察 DSH 生命周期事件并记录审计日志：
-
-| 事件                | 审计记录       | 说明                                                                 |
-| ------------------- | -------------- | -------------------------------------------------------------------- |
-| `agent/status`      | `agent_status` | 状态变化 + 顶层/子代理标记                                           |
-| `llm/stream`        | `llm_stream`   | 流开始/结束/错误 + chunk/字符/耗时统计（同步包装流，透传全部 chunk） |
-| `tools/pre-execute` | `tool_call`    | 工具名 + 参数键列表 + 主要文本参数截断摘要                           |
-| `tools/execute`     | `tool_result`  | 工具名 + 成功/失败 + 耗时                                            |
-
-- **会话隔离**：事件按会话分桶，切换会话互不串扰；
-- **重启恢复**：持久化到 `$DSH_HOME/observability/audit.jsonl`（**增量追加** + 防抖批量 flush + 周期 compact 原子快照），重启后完整恢复；升级前旧格式 `audit.json` 自动迁移；
-- **防膨胀**：每会话最多 2000 条（FIFO 淘汰）、全局 20000 条（轮转淘汰）；
-- **零写放大**：落盘只写新增事件（≈事件本体字节），不会因事件流持续而反复全量重写审计文件；
-- **资源监控 + 自动降级（资源看门狗）**：面板「资源」区块展示本进程 CPU/内存 + 审计文件大小与写入速率（15s 采样），写放大/超限自动告警（告警列表展示在「资源」区块，阈值见 `resource-budget-review`）；写入速率/文件大小连续超限自动**暂停落盘**（事件仍入内存，有界不丢），回落自动恢复（全量快照补齐降级窗口），全程日志告警 + API `degraded` 标记（issue #127）。
-- **只读观察**：waterfall 事件一律透传 `next()`，绝不改变工具/模型流程。
-
-### 2. 轨迹回放面板（时间轴）
-
-侧边栏「轨迹回放」页签：选择会话 + 类型过滤（全部 / 状态 / 模型流 / 工具），按时间轴展示 agent 行为（类型徽标 + 时间 + 摘要）；面板可见时 5s 轮询、隐藏时暂停。
-
-### 3. 结构化 Git 工具（类型化提交）
-
-侧边栏「Git 工具」页签：输入仓库路径 → 查看状态（分支 + 暂存/未暂存计数）与差异（工作区/暂存区）→ **类型化提交**：
-
-- 类型枚举：`feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore`；
-- 消息格式：`<type>(<scope>): <description>`（scope 可选，body 可选）；
-- 服务端生成消息 + `execFile` 执行 git（不经 shell），提交历史清晰可追溯。
-
-### 4. 增量 diff 审查（提交前审查）
-
-「提交前审查」按钮对增量 diff 运行规则引擎（确定性、可测试）：
-
-| 规则              | 严重级别 | 检查内容                                              |
-| ----------------- | -------- | ----------------------------------------------------- |
-| `secret-leak`     | error    | 密钥/凭据硬编码（password/api_key/secret/token）      |
-| `conflict-marker` | error    | 合并冲突标记残留（`<<<<<<<` / `=======` / `>>>>>>>`） |
-| `debug-statement` | warning  | 调试残留（console.* / debugger / print 族）           |
-| `large-diff`      | warning  | 单文件变更 > 300 行                                   |
-| `binary-file`     | warning  | 二进制文件变更                                        |
-| `todo-marker`     | info     | TODO/FIXME/HACK 标记                                  |
-| `trailing-space`  | info     | 行尾多余空格                                          |
-| `no-test-change`  | info     | 有源码变更但无测试变更                                |
-
-- **可选 AI 审查**：配置 `aiReview`（默认开）且 agents 服务可用时，创建独立审查 agent 阅读 diff 输出总评（verdict/summary/topIssues）；超时/失败/解析失败自动降级，规则引擎结果不受影响（AI 是增强，不是门禁）。
-
-## 工作原理
-
-- **Server 端**（`lib/index.js`）：`audit.js` 监听四类事件 → `store.js` 按会话分桶持久化；`git.js` 类型化提交（execFile）；`review.js` + `diff.js` 规则引擎；`ai.js` 可选 AI 增强；`routes.js` 提供 `/observability/api` 路由（全部经 loopback 信任围栏）。
-- **Client 端**（`lib/client.js`）：两个侧边栏页签（`dsh-my-observability:replay` 轨迹回放、`dsh-my-observability:git` Git 工具），样式走 DSH 语义 token，随 fiber 卸载无残留。
+- **事件审计**：只读观察并记录 `agent/status`（状态变化 + 顶层/子代理标记）、`llm/stream`（流开始/结束/错误 + chunk 与耗时统计，透传全部 chunk）、`tools/pre-execute`（工具名 + 参数摘要）、`tools/execute`（成功/失败 + 耗时）；waterfall 事件一律透传 `next()`，绝不改变工具/模型流程。
+- **持久化与上限**：按会话分桶增量追加到 `$DSH_HOME/observability/audit.jsonl`（防抖批量 flush + 周期原子 compact），重启后完整恢复；每会话上限 2000 条、全局 20000 条，超出淘汰最旧事件。
+- **轨迹回放面板**：侧边栏「轨迹回放」页签，选会话 + 类型过滤（全部 / 状态 / 模型流 / 工具），时间轴展示类型徽标 + 时间 + 摘要；可见时 5s 轮询、隐藏时暂停。
+- **结构化 Git 工具**：侧边栏「Git 工具」页签，输入仓库路径查看分支与暂存/未暂存计数、工作区/暂存区差异，按 `<type>(<scope>): <description>` 生成类型化提交（`feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore`）；服务端 `execFile` 执行 git，不经 shell。
+- **增量 diff 审查**：「提交前审查」对增量 diff 跑确定性规则引擎——error：密钥/凭据硬编码、合并冲突标记；warning：调试残留（console/debugger/print）、单文件变更 > 300 行、二进制文件变更；info：TODO/FIXME/HACK 标记、行尾空格、有源码变更但无测试变更。
+- **资源看门狗**：面板「资源」区块展示本进程 CPU/内存 + 审计文件大小与写入速率（15s 采样），写放大或连续超限时自动暂停落盘（事件仍入内存，有界不丢），回落自动恢复，附日志告警与 API `degraded` 标记。
 
 ## 安装
 
-> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-my-observability --trust-lockfile`——无需克隆本仓库；以下 link 方式供本仓库开发者使用。
+> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-my-observability --trust-lockfile`——无需克隆本仓库；link 方式供本仓库开发者使用。
 
 ```bash
-# 1) 克隆本仓库（任意目录）
 git clone https://github.com/baosfeng/my-dsh-plugins.git
-# 2) 以本地 link 方式安装（将 <仓库路径> 替换为上面的克隆目录）
 dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-observability
 ```
 
-- server 端改动需重启 `dsh web`；client 端改动浏览器硬刷新（Cmd/Ctrl+Shift+R）即可。
+server 端改动需重启 `dsh web`；client 端改动硬刷新浏览器（Cmd/Ctrl+Shift+R）即可。
 
 ## 配置
 
-插件级配置（`cordis.patch.yml` 对应插件行的 `config` 字段，均为可选）：
-
-```yaml
-- insert:
-    - id: observability
-      name: 'dsh-my-observability'
-    - config: # 传给 apply(ctx, config)
-        aiReview: true # 增量 diff 审查启用 AI 增强（默认 true；agents 服务不可用时自动降级）
-        aiTimeoutMs: 60000 # AI 审查超时（毫秒，默认 60000）
-```
-
-## 依赖
+插件行 `config` 字段，均可选：
 
-| 依赖     | 用途          | 可选           |
-| -------- | ------------- | -------------- |
-| `cordis` | 插件运行时    | 是（宿主提供） |
-| `react`  | client 端组件 | 是（宿主提供） |
+| 配置键        | 作用                                                                   |
+| ------------- | ---------------------------------------------------------------------- |
+| `aiReview`    | 增量 diff 审查启用 AI 增强（默认 `true`；agents 服务不可用时自动降级） |
+| `aiTimeoutMs` | AI 审查超时（毫秒，默认 60000）                                        |
 
 ## 限制与说明
 
-- **Git 工具作用于本机仓库**：仓库路径由你在面板中输入（localStorage 记住），仅本机可访问（loopback 围栏）。
-- **AI 审查需要 agents 服务**：不可用时审查自动降级为纯规则引擎结果，不影响使用。
-- **审计上限**：每会话 2000 条 / 全局 20000 条，超出自动淘汰最旧事件。
+- **Git 工具作用于本机仓库**：仓库路径由你在面板输入（localStorage 记住），仅本机可访问（loopback 围栏）。
+- **AI 审查是增强不是门禁**：agents 服务不可用或超时/解析失败时自动降级为纯规则引擎结果。
+- **审计有上限**：每会话 2000 条 / 全局 20000 条，超出自动淘汰最旧事件。
 
 ## 相关文档
 
-→ [可观测性模块文档](../../docs/可观测性/概述.md) · [需求清单](../../docs/可观测性/需求清单.md) · [CHANGELOG](CHANGELOG.md)
+→ [可观测性模块文档](../../docs/可观测性/概述.md) · [CHANGELOG](CHANGELOG.md)

package/lib/ai.js

@@ -10,67 +10,88 @@
  * 参考 dsh-task-reliability 的校验 agent 模式（agents.create + whenIdle
  * 超时 + dispose）。
  */
-import { randomUUID } from 'node:crypto'
-import { withTimeout, userMessage } from 'dsh-shared'
-import { REVIEW_TIMEOUT_MS } from './constants.js'
-
+import { randomUUID } from 'node:crypto';
+import { withTimeout, userMessage } from 'dsh-shared';
+import { REVIEW_TIMEOUT_MS } from './constants.js';
 /** diff 送入 prompt 的最大长度（截断防 token 爆炸）。 */
-const AI_DIFF_MAX = 8000
-
+const AI_DIFF_MAX = 8000;
+/** 从 AiAgentOptions 构建 agents.create 所需的 agentOptions 对象。 */
+function buildAgentOptions(opts) {
+    if (opts === undefined)
+        return {};
+    const result = {};
+    if (opts.provider !== undefined)
+        result.provider = opts.provider;
+    if (opts.model !== undefined)
+        result.model = opts.model;
+    if (opts.cwd !== undefined)
+        result.cwd = opts.cwd;
+    return result;
+}
 /** 运行 AI 审查（尽力而为；任何失败都降级为 failed 标记）。 */
-export async function runAiReview(ctx, diffText, report, timeoutMs = REVIEW_TIMEOUT_MS) {
-  const agents = agentsServiceOf(ctx)
-  if (agents === undefined) return { enabled: true, failed: true, note: 'agents service unavailable' }
-  // CodeQL js/insecure-randomness 修复：sessionId 随机段改用 crypto.randomUUID()
-  // （密码学安全随机，无需种子），保持 `obs-review-<ts>-<6位hex>` 格式兼容。
-  const sessionId = `obs-review-${Date.now()}-${randomUUID().slice(0, 6)}`
-  let handle
-  try {
-    handle = await agents.create({
-      sessionId,
-      meta: { origin: 'subagent', delegationDepth: 1 },
-      agentOptions: {},
-    })
-    handle.agent.followup(userMessage(aiReviewPrompt(diffText, report)))
-    await withTimeout(handle.agent.whenIdle(), timeoutMs)
-    const parsed = parseAiConclusion(lastAssistantText(handle.agent.session))
-    if (parsed === undefined) return { enabled: true, failed: true, note: 'AI 结论解析失败' }
-    return { enabled: true, ...parsed }
-  } catch (error) {
-    return {
-      enabled: true,
-      failed: true,
-      note: error instanceof Error ? error.message : String(error),
+export async function runAiReview(ctx, diffText, report, timeoutMs = REVIEW_TIMEOUT_MS, agentOptions) {
+    const agents = agentsServiceOf(ctx);
+    if (agents === undefined)
+        return { enabled: true, failed: true, note: 'agents service unavailable' };
+    // CodeQL js/insecure-randomness 修复：sessionId 随机段改用 crypto.randomUUID()
+    // （密码学安全随机，无需种子），保持 `obs-review-<ts>-<6位hex>` 格式兼容。
+    const sessionId = `obs-review-${Date.now()}-${randomUUID().slice(0, 6)}`;
+    let handle;
+    try {
+        handle = await agents.create({
+            sessionId,
+            meta: { origin: 'subagent', delegationDepth: 1 },
+            agentOptions: buildAgentOptions(agentOptions),
+        });
+        handle.agent.followup(userMessage(aiReviewPrompt(diffText, report)));
+        await withTimeout(handle.agent.whenIdle(), timeoutMs);
+        const text = lastAssistantText(handle.agent.session);
+        // 区分「模型未调用」与「结论解析失败」：
+        // - text 为空 → agent 未产出 assistant 消息（模型从未被调用或调用失败）
+        // - text 非空但解析失败 → 模型回复了，但结论无法解析
+        if (text === '')
+            return { enabled: true, failed: true, note: '模型未产出回复（agent 可能未调用模型或模型请求失败）' };
+        const parsed = parseAiConclusion(text);
+        if (parsed === undefined)
+            return { enabled: true, failed: true, note: 'AI 结论解析失败' };
+        return { enabled: true, ...parsed };
+    }
+    catch (error) {
+        return {
+            enabled: true,
+            failed: true,
+            note: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await disposeHandle(handle);
     }
-  } finally {
-    await disposeHandle(handle)
-  }
 }
-
 /** agents 服务读取（不可用返回 undefined）。 */
 function agentsServiceOf(ctx) {
-  const agents = ctx.get ? ctx.get('agents') : undefined
-  if (agents === undefined || agents === null || typeof agents.create !== 'function') return undefined
-  return agents
+    const agents = ctx.get ? ctx.get('agents') : undefined;
+    if (agents === undefined || agents === null || typeof agents.create !== 'function')
+        return undefined;
+    return agents;
 }
-
 /** 释放审查 agent（尽力而为）。 */
 async function disposeHandle(handle) {
-  if (handle === undefined) return
-  try {
-    await handle.dispose()
-  } catch {
-    // dispose is best-effort
-  }
+    if (handle === undefined)
+        return;
+    try {
+        await handle.dispose();
+    }
+    catch {
+        // dispose is best-effort
+    }
 }
-
 /** 审查 prompt：规则引擎发现 + 截断的增量 diff，要求严格 JSON 输出。 */
 function aiReviewPrompt(diffText, report) {
-  const diff = diffText.length > AI_DIFF_MAX ? `${diffText.slice(0, AI_DIFF_MAX)}\n…（diff 过长已截断）` : diffText
-  const rules = report.issues
-    .map((issue) => `- [${issue.severity}] ${issue.rule} ${issue.file}:${issue.line} ${issue.message}`)
-    .join('\n')
-  return `你是一个代码审查员。请审查以下提交前的增量 diff。规则引擎已给出参考问题，请结合 diff 给出总评与最重要的补充问题。
+    const diff = diffText.length > AI_DIFF_MAX ? `${diffText.slice(0, AI_DIFF_MAX)}\n…（diff 过长已截断）` : diffText;
+    const rules = report.issues
+        .map((issue) => `- [${issue.severity}] ${issue.rule} ${issue.file}:${issue.line} ${issue.message}`)
+        .join('\n');
+    return `你是一个代码审查员。请审查以下提交前的增量 diff。规则引擎已给出参考问题，请结合 diff 给出总评与最重要的补充问题。
 
 规则引擎发现：
 ${rules === '' ? '（无）' : rules}
@@ -81,79 +102,82 @@ ${diff}
 请严格只输出一个 JSON 对象（不要输出其他内容）：
 {"verdict": "approve" 或 "changes", "summary": "50 字以内的总评", "topIssues": ["补充问题 1", "补充问题 2"]}
 
-判断标准：存在阻塞性问题（密钥泄露、冲突标记、明显 bug）时 verdict 必须为 changes。`
+判断标准：存在阻塞性问题（密钥泄露、冲突标记、明显 bug）时 verdict 必须为 changes。`;
 }
-
 /** 从 agent 回复提取 JSON 结论（容忍 markdown 代码块包裹）。 */
 function parseAiConclusion(text) {
-  const json = jsonTextOf(text)
-  if (json === undefined) return undefined
-  try {
-    const parsed = JSON.parse(json)
-    if (!isObject(parsed)) return undefined
-    return {
-      verdict: parsed.verdict === 'changes' ? 'changes' : 'approve',
-      summary: stringOf(parsed.summary).slice(0, 500),
-      topIssues: issuesOf(parsed.topIssues),
+    const json = jsonTextOf(text);
+    if (json === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(json);
+        if (!isObject(parsed))
+            return undefined;
+        return {
+            verdict: parsed.verdict === 'changes' ? 'changes' : 'approve',
+            summary: stringOf(parsed.summary).slice(0, 500),
+            topIssues: issuesOf(parsed.topIssues),
+        };
+    }
+    catch {
+        return undefined;
     }
-  } catch {
-    return undefined
-  }
 }
-
 /** 提取 JSON 文本：裸 JSON 或 ```json 代码块。 */
 function jsonTextOf(text) {
-  if (typeof text !== 'string' || text === '') return undefined
-  const trimmed = text.trim()
-  return trimmed.startsWith('{') ? trimmed : extractJsonBlock(trimmed)
+    if (typeof text !== 'string' || text === '')
+        return undefined;
+    const trimmed = text.trim();
+    return trimmed.startsWith('{') ? trimmed : extractJsonBlock(trimmed);
 }
-
 function isObject(value) {
-  return value !== null && typeof value === 'object'
+    return value !== null && typeof value === 'object';
 }
-
 function stringOf(value) {
-  return typeof value === 'string' ? value : ''
+    return typeof value === 'string' ? value : '';
 }
-
 /** topIssues 规整：字符串数组，上限 10 条。 */
 function issuesOf(raw) {
-  return Array.isArray(raw) ? raw.filter((item) => typeof item === 'string').slice(0, 10) : []
+    return Array.isArray(raw) ? raw.filter((item) => typeof item === 'string').slice(0, 10) : [];
 }
-
 /** 从 ```json ... ``` 代码块提取 JSON 文本。 */
 function extractJsonBlock(text) {
-  const match = /```(?:json)?\s*([\s\S]*?)```/.exec(text)
-  return match !== null ? match[1].trim() : undefined
+    const match = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    return match !== null ? match[1].trim() : undefined;
 }
-
 /** 会话事件快照：新 API snapshotEvents() 优先，旧 API events 兜底（issue #165）。 */
 function sessionEvents(session) {
-  return session?.snapshotEvents?.() ?? session?.events
+    const target = session;
+    return target?.snapshotEvents?.() ?? target?.events;
 }
-
 function lastAssistantText(session) {
-  try {
-    const events = sessionEvents(session)
-    if (!Array.isArray(events)) return ''
-    for (let i = events.length - 1; i >= 0; i--) {
-      const text = assistantTextOf(events[i])
-      if (text !== '') return text
+    try {
+        const events = sessionEvents(session);
+        if (!Array.isArray(events))
+            return '';
+        for (let i = events.length - 1; i >= 0; i--) {
+            const text = assistantTextOf(events[i]);
+            if (text !== '')
+                return text;
+        }
     }
-  } catch {
-    // best-effort
-  }
-  return ''
+    catch {
+        // best-effort
+    }
+    return '';
 }
-
 function assistantTextOf(event) {
-  if (event?.type !== 'assistant/message') return ''
-  const blocks = event.data?.message?.content
-  if (!Array.isArray(blocks)) return ''
-  return blocks
-    .filter(
-      (block) => block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string',
-    )
-    .map((block) => block.text)
-    .join('\n')
+    const target = event;
+    if (target?.type !== 'assistant/message')
+        return '';
+    const blocks = target.data?.message?.content;
+    if (!Array.isArray(blocks))
+        return '';
+    return blocks
+        .filter((block) => block !== null &&
+        typeof block === 'object' &&
+        block.type === 'text' &&
+        typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n');
 }