dsh-my-observability 0.3.1 → 0.3.4

package/CHANGELOG.md

@@ -2,101 +2,37 @@
 
 本文件记录 dsh-my-observability 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## [Unreleased]
+## [0.3.4] - 2026-09-18
 
 ### 变更
 
-- refactor(observability): #198 资源看门狗改为消费 `dsh-shared` 的 `createResourceGuard`（第三批）——插件私有状态机/判定/ring buffer 删除，只保留宿主职责（采样源 + $DSH_HOME 字节维度 + 降级动作）。行为等价：降级在第 3 个连续超限窗口触发、恢复在第 3 个连续正常窗口触发、回调恰好一次、告警规则与顺序不变；新增 `monitor.stats()` / `monitor.history()` 与可注入采样源/时钟（确定性测试）
+- fix(my-observability): 去掉仅内部使用的 4 个导出（knip 死代码门禁）
+- docs(guard,observability,mermaid-render): 设置页面板真实截图 + README 效果图
+- fix(my-observability): 拆分设置视图至尺寸门禁内
+- feat(my-observability): 设置页配置面板（aiReview / aiTimeoutMs 可视化编辑）
 
-## [0.3.1] - 2026-09-10
-
-### 变更
-
-- feat(ts): 第四轮 JS→TS 迁移（5 个插件，server + client 全量）
-
-## [0.3.0] - 2026-09-07
-
-### 变更
-
-- 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.2.0] - 2026-09-07
+## [0.3.3] - 2026-09-18
 
 ### 变更
 
-- 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)
+- fix(my-observability): 去掉仅内部使用的 4 个导出（knip 死代码门禁）
+- docs(guard,observability,mermaid-render): 设置页面板真实截图 + README 效果图
+- fix(my-observability): 拆分设置视图至尺寸门禁内
+- feat(my-observability): 设置页配置面板（aiReview / aiTimeoutMs 可视化编辑）
 
-## [0.1.7] - 2026-09-06
+## [0.3.2] - 2026-09-17
 
 ### 变更
 
-- 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
+- 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: 项目全面优化和完善
 
-### 变更
-
-- 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
+## [0.3.1] - 2026-09-10
 
 ### 变更
 
-- 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

@@ -5,103 +5,49 @@
 <div align="center">
   <img alt="轨迹回放面板：侧边栏时间轴展示 agent 行为（状态/模型流/工具调用）" src="https://unpkg.com/dsh-my-observability/assets/replay-panel.png" width="640" />
   <img alt="Git 工具面板：仓库状态 / 差异 / 提交前审查 / 类型化提交" src="https://unpkg.com/dsh-my-observability/assets/git-panel.png" width="640" />
+  <br/>
+  <img alt="设置页配置面板（设置 → 插件 → 可观测性）：AI 审查增强开关 + AI 审查超时" src="https://unpkg.com/dsh-my-observability/assets/settings-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 工具），每个面板一个页签类型，经**宿主原生侧边栏扩展点**注册（`ctx.sidebarRightTabs` 页签类型 + `slots` 的 `sidebar.right.pane.tab` / `.title` 席位，issue #187 批 1），样式走 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` 字段，均可选：
 
-## 依赖
+| 配置键        | 作用                                                                   |
+| ------------- | ---------------------------------------------------------------------- |
+| `aiReview`    | 增量 diff 审查启用 AI 增强（默认 `true`；agents 服务不可用时自动降级） |
+| `aiTimeoutMs` | AI 审查超时（毫秒，默认 60000）                                        |
 
-| 依赖     | 用途          | 可选           |
-| -------- | ------------- | -------------- |
-| `cordis` | 插件运行时    | 是（宿主提供） |
-| `react`  | client 端组件 | 是（宿主提供） |
+`aiReview` 与 `aiTimeoutMs` 可在 **设置 → 插件 → 可观测性** 里可视化编辑：保存即写回 profile 层 `cordis.patch.yml` 的插件行（行 id `observability`，其余手写键原样保留），DSH 热重载后立即生效，无需重启。其余字段（`aiProvider` / `aiModel` / `aiCwd` / `resourceIntervalMs` 等）仍按上表在 `cordis.patch.yml` 手写；非法值不会写坏配置（`aiReview` 非布尔忽略，`aiTimeoutMs` 非正/非有限回退 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

@@ -15,8 +15,21 @@ import { withTimeout, userMessage } from 'dsh-shared';
 import { REVIEW_TIMEOUT_MS } from './constants.js';
 /** diff 送入 prompt 的最大长度（截断防 token 爆炸）。 */
 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) {
+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' };
@@ -28,11 +41,17 @@ export async function runAiReview(ctx, diffText, report, timeoutMs = REVIEW_TIME
         handle = await agents.create({
             sessionId,
             meta: { origin: 'subagent', delegationDepth: 1 },
-            agentOptions: {},
+            agentOptions: buildAgentOptions(agentOptions),
         });
         handle.agent.followup(userMessage(aiReviewPrompt(diffText, report)));
         await withTimeout(handle.agent.whenIdle(), timeoutMs);
-        const parsed = parseAiConclusion(lastAssistantText(handle.agent.session));
+        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 };

package/lib/client.js

@@ -37,8 +37,7 @@ window.__ModuleLoader__.load({
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
     const { createElement, useEffect, useState } = require('react')
 
-    // 原生页签身份（issue #187 批 1）：id/kind = 迁移前 better-sidebar 的 tab id
-    // （每个面板一个类型，id 全局唯一且是席位的 key），order = 迁移前的指南页顺序。
+    // 原生页签身份（issue #187 批 1）：id/kind 沿用迁移前 better-sidebar 的 tab id（每面板一个类型，id 全局唯一且是席位 key），order 为指南页顺序。
     const REPLAY_TAB_ID = 'dsh-my-observability:replay'
     const GIT_TAB_ID = 'dsh-my-observability:git'
     const REPLAY_TAB_ORDER = 40
@@ -194,6 +193,23 @@ const strings = {
     loading: () => (isZh() ? '加载中…' : 'Loading…'),
     emptyDiff: () => (isZh() ? '（空）' : '(empty)'),
     noRepo: () => (isZh() ? '请输入仓库路径' : 'Enter a repo path'),
+    // 设置页（设置 → 插件 → 可观测性，issue #383）
+    settingsTitle: () => (isZh() ? '可观测性' : 'Observability'),
+    settingsSectionTitle: () => (isZh() ? 'AI 审查' : 'AI review'),
+    settingsAiReviewLabel: () => (isZh() ? 'AI 审查增强' : 'AI review enhancement'),
+    settingsAiReviewHint: () => isZh()
+        ? '增量 diff 审查调用 AI agent 补充规则引擎结论（agents 服务不可用或超时自动降级为纯规则）'
+        : 'Let an AI agent augment the rule-engine review of the incremental diff (degrades to rules only when the agents service is unavailable)',
+    settingsAiTimeoutLabel: () => (isZh() ? 'AI 审查超时（ms）' : 'AI review timeout (ms)'),
+    settingsAiTimeoutHint: () => isZh()
+        ? '单次 AI 审查的最长等待；非正数或非有限值在保存时回退为 60000'
+        : 'Max wait per AI review; non-positive or non-finite values fall back to 60000 on save',
+    settingsSave: () => (isZh() ? '保存' : 'Save'),
+    settingsSaved: () => (isZh() ? '已保存并生效' : 'Saved and applied'),
+    settingsSaveFailed: () => (isZh() ? '保存失败' : 'Save failed'),
+    settingsLoadFailedHint: () => isZh()
+        ? '无法读取 /observability/api/config：请确认服务端插件已加载（改过 server 端后需重启 dsh web）'
+        : 'Cannot read /observability/api/config: make sure the host half is loaded (restart dsh web after host-side changes)',
 };
 
     // ── shared icons (inline, stroke=currentColor, matching better-sidebar) ──
@@ -365,6 +381,33 @@ const icon = {
       ],
       size,
     ),
+  // 箭头向上（更新图标）：向上的箭头，表示更新操作
+  arrowUp: (size = 16) =>
+    iconSvg(
+      [
+        createElement('line', { x1: 12, y1: 19, x2: 12, y2: 5 }),
+        createElement('polyline', { points: '5 12 12 5 19 12' }),
+      ],
+      size,
+    ),
+  // 电源关（禁用图标）：圆形电源按钮，表示禁用操作
+  powerOff: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M18.36 6.64a9 9 0 1 1-12.73 0' }),
+        createElement('line', { x1: 12, y1: 2, x2: 12, y2: 12 }),
+      ],
+      size,
+    ),
+  // 电源开（启用图标）：圆形电源按钮，表示启用操作
+  powerOn: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M18.36 6.64a9 9 0 1 1-12.73 0' }),
+        createElement('line', { x1: 12, y1: 2, x2: 12, y2: 12 }),
+      ],
+      size,
+    ),
 }
 
 // Common-language / file-type badges (issue #24): brand fill + contrast
@@ -1605,6 +1648,167 @@ function GitPanel() {
     }), createElement(DiffView, { diff }), createElement(ReviewReport, { report }), createElement(CommitForm, { repo, onCommitted }));
 }
 
+    "use strict";
+// ── 设置页签（issue #383）：设置 → 插件 → 可观测性 ────────────────────
+// 只暴露 README 已记录的 aiReview / aiTimeoutMs 两项；其余键（aiProvider /
+// aiModel / aiCwd / resourceIntervalMs / resourceLimits）继续由用户在
+// cordis.patch.yml 手写（服务端写回时会合并保留原条目已存在的键）。
+//
+// 保存 → PUT /observability/api/config → 写回 profile patch 文件；DSH 的
+// watchUserPatches 热重载 patch 后重新 apply（保存即生效）。保存成功后面板
+// 只更新本地状态：这两项在服务端生效，前端无缓存需要同步。
+//
+// 片段文件：无 import/export，共享 factory 作用域（apiJson / strings /
+// createElement 由 replay.js / i18n.js / 模板提供）。
+const SETTINGS_API = '/observability/api/config';
+/** 设置页样式：只用自己的类名前缀 + 宿主语义 token（随 effect 注入/卸载）。 */
+const SETTINGS_STYLES = `
+.dsh-my-observability-settings{display:flex;flex-direction:column;gap:10px;padding:12px}
+.dsh-my-observability-settings-section{display:flex;flex-direction:column;gap:8px}
+.dsh-my-observability-settings-section-title{font:var(--dsw-font-xs-strong-13);color:var(--dsw-alias-label-secondary)}
+.dsh-my-observability-settings-row{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;background:var(--dsw-alias-bg-layer-2)}
+.dsh-my-observability-settings-info{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dsh-my-observability-settings-label{font:var(--dsw-font-xs-strong-13);color:var(--dsw-alias-label-primary)}
+.dsh-my-observability-settings-hint{font:var(--dsw-font-xxs-12);color:var(--dsw-alias-label-tertiary);line-height:1.5}
+.dsh-my-observability-settings-toggle{flex:none;width:34px;height:20px;border-radius:10px;border:1px solid var(--dsw-alias-border-l2);background:color-mix(in srgb, var(--dsw-alias-label-tertiary) 30%, transparent);position:relative;cursor:pointer;transition:background var(--ds-transition-duration-slow) var(--ds-ease-in-out),border-color var(--ds-transition-duration-slow) var(--ds-ease-in-out)}
+.dsh-my-observability-settings-toggle[data-on="true"]{background:var(--dsw-alias-state-success-primary);border-color:transparent}
+.dsh-my-observability-settings-toggle::after{content:"";position:absolute;top:2px;left:2px;width:14px;height:14px;border-radius:50%;background:var(--dsw-alias-label-primary);transition:transform var(--ds-transition-duration-slow) var(--ds-ease-in-out),background var(--ds-transition-duration-slow) var(--ds-ease-in-out)}
+.dsh-my-observability-settings-toggle[data-on="true"]::after{transform:translateX(12px);background:var(--dsw-alias-label-primary-foreground)}
+.dsh-my-observability-settings-input{flex:none;width:120px;height:28px;padding:0 8px;border-radius:6px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:var(--dsw-font-xxs-12)}
+.dsh-my-observability-settings-input:focus{outline:none;border-color:var(--dsw-alias-interactive-primary)}
+.dsh-my-observability-settings-actions{display:flex;align-items:center;gap:8px}
+.dsh-my-observability-settings-btn{height:28px;padding:0 14px;border-radius:6px;cursor:pointer;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-interactive-bg);color:var(--dsw-alias-label-primary);font:var(--dsw-font-xxs-12)}
+.dsh-my-observability-settings-btn:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-my-observability-settings-status{font:var(--dsw-font-xxs-12);color:var(--dsw-alias-label-tertiary)}
+.dsh-my-observability-settings-saved{font:var(--dsw-font-xxs-12);color:var(--dsw-alias-state-success-primary)}
+.dsh-my-observability-settings-error{font:var(--dsw-font-xxs-12);color:var(--dsw-alias-state-error-primary)}
+`;
+/** 开关行（布尔配置项）。 */
+function SettingsToggleRow({ label, hint, on, onChange, }) {
+    return createElement('div', { className: 'dsh-my-observability-settings-row' }, createElement('div', { className: 'dsh-my-observability-settings-info' }, createElement('div', { className: 'dsh-my-observability-settings-label' }, label), createElement('div', { className: 'dsh-my-observability-settings-hint' }, hint)), createElement('div', {
+        className: 'dsh-my-observability-settings-toggle',
+        'data-on': String(on),
+        role: 'switch',
+        'aria-checked': String(on),
+        onClick: () => onChange(!on),
+    }));
+}
+/** 数字输入行（AI 审查超时 ms）。 */
+function SettingsNumberRow({ label, hint, value, onChange, }) {
+    return createElement('div', { className: 'dsh-my-observability-settings-row' }, createElement('div', { className: 'dsh-my-observability-settings-info' }, createElement('div', { className: 'dsh-my-observability-settings-label' }, label), createElement('div', { className: 'dsh-my-observability-settings-hint' }, hint)), createElement('input', {
+        className: 'dsh-my-observability-settings-input',
+        type: 'number',
+        min: '1',
+        step: '1000',
+        value: String(value),
+        onChange: (e) => onChange(Number(e.target.value)),
+    }));
+}
+/** 保存配置：PUT 配置端点；失败只显示失败提示（绝不误报已保存）。 */
+function saveSettings(draft, setSaved, setSaveError) {
+    setSaved(false);
+    setSaveError(false);
+    apiJson(SETTINGS_API, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(draft),
+    })
+        .then(() => setSaved(true))
+        .catch(() => setSaveError(true));
+}
+/** 配置加载失败视图（读不到配置时不显示表单，避免用默认值覆盖真实配置）。 */
+function SettingsLoadError({ onRetry }) {
+    return createElement('div', { className: 'dsh-my-observability-settings' }, createElement('div', { className: 'dsh-my-observability-settings-error' }, strings.loadError()), createElement('div', { className: 'dsh-my-observability-settings-status' }, strings.settingsLoadFailedHint()), createElement('div', { className: 'dsh-my-observability-settings-actions' }, createElement('button', { className: 'dsh-my-observability-settings-btn', onClick: onRetry }, strings.retry())));
+}
+/** 加载态（配置未返回前的占位，避免先渲染出默认值表单再被回填覆盖）。 */
+function SettingsLoading() {
+    return createElement('div', { className: 'dsh-my-observability-settings' }, createElement('div', { className: 'dsh-my-observability-settings-status' }, strings.loading()));
+}
+/** 配置区块：区块标题 + 两个配置行（AI 审查开关 / 超时）。 */
+function SettingsConfigSection({ draft, patch, }) {
+    return createElement('div', { className: 'dsh-my-observability-settings-section' }, createElement('div', { className: 'dsh-my-observability-settings-section-title' }, strings.settingsSectionTitle()), createElement(SettingsToggleRow, {
+        label: strings.settingsAiReviewLabel(),
+        hint: strings.settingsAiReviewHint(),
+        on: draft.aiReview !== false,
+        onChange: (value) => patch('aiReview', value),
+    }), createElement(SettingsNumberRow, {
+        label: strings.settingsAiTimeoutLabel(),
+        hint: strings.settingsAiTimeoutHint(),
+        value: draft.aiTimeoutMs,
+        onChange: (value) => patch('aiTimeoutMs', value),
+    }));
+}
+/** 保存区块：保存按钮 + 成功/失败提示（互斥，保存失败绝不显示"已保存"）。 */
+function SettingsActions({ save, saved, saveError, }) {
+    return createElement('div', { className: 'dsh-my-observability-settings-actions' }, createElement('button', { className: 'dsh-my-observability-settings-btn', onClick: save }, strings.settingsSave()), saved ? createElement('span', { className: 'dsh-my-observability-settings-saved' }, strings.settingsSaved()) : null, saveError
+        ? createElement('span', { className: 'dsh-my-observability-settings-error' }, strings.settingsSaveFailed())
+        : null);
+}
+/** 设置页视图：GET 回填 → 编辑 → 保存（各区块拆成子组件，控制单函数长度）。 */
+function ObservabilitySettingsView() {
+    const [draft, setDraft] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [failed, setFailed] = useState(false);
+    const [saved, setSaved] = useState(false);
+    const [saveError, setSaveError] = useState(false);
+    const load = () => {
+        setLoading(true);
+        setSaved(false);
+        setSaveError(false);
+        apiJson(SETTINGS_API)
+            .then((value) => {
+            setDraft(value);
+            setLoading(false);
+        })
+            .catch(() => {
+            setLoading(false);
+            setFailed(true);
+        });
+    };
+    useEffect(() => {
+        load();
+    }, []);
+    if (loading)
+        return createElement(SettingsLoading, null);
+    if (draft === null)
+        return createElement(SettingsLoadError, { onRetry: load });
+    const patch = (key, value) => setDraft({ ...draft, [key]: value });
+    return createElement('div', { className: 'dsh-my-observability-settings' }, createElement(SettingsConfigSection, { draft, patch }), createElement(SettingsActions, {
+        save: () => saveSettings(draft, setSaved, setSaveError),
+        saved,
+        saveError,
+    }));
+}
+/** 附加设置页签：slots 服务缺失（精简上下文 / 宿主未提供）时静默跳过。 */
+function attachObservabilitySettingsTab(ctx) {
+    // strict=false：首屏时 slots 提供者 fiber 可能尚未 active，strict 模式的
+    // ctx.get 返回 undefined → 页签静默消失（要等 HMR 才出现）。取到实例即可，
+    // 注册本身由 slots.inject 等待槽位声明。
+    const slots = typeof ctx.get === 'function' ? ctx.get('slots', false) : undefined;
+    if (slots === undefined || slots === null)
+        return;
+    ctx.effect(() => {
+        if (typeof document === 'undefined' || typeof document.head === 'undefined')
+            return () => { };
+        const style = document.createElement('style');
+        style.setAttribute('data-dsh-my-observability-settings', 'styles');
+        style.textContent = SETTINGS_STYLES;
+        document.head.appendChild(style);
+        return () => {
+            if (style.parentNode !== null)
+                style.parentNode.removeChild(style);
+        };
+    }, 'dsh-my-observability: settings styles');
+    ctx.effect(() => slots.inject('settings.plugins.tab', () => slots.register({
+        name: 'settings.plugins.tab',
+        // id 必须全局唯一（list 型槽位的 tab key）：复用别人的 id 会顶掉
+        // 对方那一格（宿主契约：fresh id 追加在已有条目旁）。
+        id: 'dsh-my-observability-settings',
+        order: 92,
+        label: () => strings.settingsTitle(),
+    }, ObservabilitySettingsView)), 'dsh-my-observability: settings tab registration');
+}
+
     "use strict";
 // ── 样式（DSH 语义 token，随 activation 注入 / teardown 卸载）──────
 // 前缀 dsh-my-observability-（issue #54：与 dsh-my-guard 前缀分离，消除跨插件类名冲突）。
@@ -1783,8 +1987,10 @@ function injectStyles() {
       // 样式先注入：不依赖任何服务（服务缺失/时序未就绪也不影响面板配色）。
       ctx.effect(() => injectStyles(), 'dsh-my-observability: styles')
 
-      const tabs = ctx.sidebarRightTabs
-      const slots = ctx.slots
+      // 设置页签（issue #383）：只依赖 slots（strict=false 读取），与侧边栏面板所需的 sidebarRightTabs 无关，故先于判空注册。
+      attachObservabilitySettingsTab(ctx)
+
+      const { sidebarRightTabs: tabs, slots } = ctx
       // 判空必须同时覆盖 null 与 undefined（typeof null 是 object，会骗过 === undefined）。
       if (tabs == null || slots == null) return
 

package/lib/client.src.js

@@ -37,8 +37,7 @@ window.__ModuleLoader__.load({
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
     const { createElement, useEffect, useState } = require('react')
 
-    // 原生页签身份（issue #187 批 1）：id/kind = 迁移前 better-sidebar 的 tab id
-    // （每个面板一个类型，id 全局唯一且是席位的 key），order = 迁移前的指南页顺序。
+    // 原生页签身份（issue #187 批 1）：id/kind 沿用迁移前 better-sidebar 的 tab id（每面板一个类型，id 全局唯一且是席位 key），order 为指南页顺序。
     const REPLAY_TAB_ID = 'dsh-my-observability:replay'
     const GIT_TAB_ID = 'dsh-my-observability:git'
     const REPLAY_TAB_ORDER = 40
@@ -53,6 +52,7 @@ window.__ModuleLoader__.load({
     /*__PART_RESOURCE__*/
     /*__PART_REPLAY_EXT__*/
     /*__PART_GIT__*/
+    /*__PART_SETTINGS__*/
     /*__PART_STYLES__*/
 
     // ── 插件体：样式注入 + 两个原生页签注册 ─────────────────────────────
@@ -73,8 +73,10 @@ window.__ModuleLoader__.load({
       // 样式先注入：不依赖任何服务（服务缺失/时序未就绪也不影响面板配色）。
       ctx.effect(() => injectStyles(), 'dsh-my-observability: styles')
 
-      const tabs = ctx.sidebarRightTabs
-      const slots = ctx.slots
+      // 设置页签（issue #383）：只依赖 slots（strict=false 读取），与侧边栏面板所需的 sidebarRightTabs 无关，故先于判空注册。
+      attachObservabilitySettingsTab(ctx)
+
+      const { sidebarRightTabs: tabs, slots } = ctx
       // 判空必须同时覆盖 null 与 undefined（typeof null 是 object，会骗过 === undefined）。
       if (tabs == null || slots == null) return
 

package/lib/config-routes.js

@@ -0,0 +1,88 @@
+/**
+ * dsh-my-observability — 设置页配置端点（GET/PUT /observability/api/config，issue #383）。
+ *
+ * 设置 → 插件 → 可观测性 面板只暴露 README 已记录的 `aiReview` /
+ * `aiTimeoutMs` 两项；其余字段（aiProvider / aiModel / aiCwd /
+ * resourceIntervalMs / resourceLimits）继续由用户在 cordis.patch.yml 手写，
+ * 设置页保存不得连带覆盖它们。
+ *
+ * 写回复用 dsh-shared 的配置持久化原语（currentProfile / patchFileOf /
+ * writePatchConfig），并**先合并该条目已有键**：writePatchConfig 的语义是
+ * 「删除同 id 旧条目 → 追加新条目」，只写两项会把用户手写的其余配置一起删掉
+ * （数据破坏，issue #383 验收项「不写坏配置」）。
+ */
+import { readFile } from 'node:fs/promises';
+import { currentProfile, extractConfig, patchFileOf, readJsonBody, writeJson, writePatchConfig } from 'dsh-shared';
+/** aiTimeoutMs 默认值（与 src/index.ts buildOptions 的兜底共用同一口径）。 */
+const DEFAULT_AI_TIMEOUT_MS = 60000;
+/**
+ * 写回行 id：必须与 plugins/dsh-my-observability/cordis.patch.yml 里的插件行
+ * id 一致——loader 按行 id 匹配配置，id 不符会新增孤儿行、原行配置不变。
+ */
+const CONFIG_ROW_ID = 'observability';
+/** aiTimeoutMs 规整：非数字 / 非有限 / 非正 → 回退默认（绝不把 0/NaN 写进 patch）。
+ *  导出供 src/index.ts 的 buildOptions 复用，保证「默认值口径」只有一处定义。
+ *  （其余仅本文件内部使用的符号不导出：knip 会把无外部引用的导出判为 dead code。） */
+export function normalizeTimeout(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : DEFAULT_AI_TIMEOUT_MS;
+}
+/** 当前生效配置（GET 的 value，也是设置页表单的回填源）。 */
+function configValueOf(options) {
+    return { aiReview: options.aiReview !== false, aiTimeoutMs: normalizeTimeout(options.aiTimeoutMs) };
+}
+/**
+ * 校验 + 规整 PUT payload：非对象 → undefined（调用方回 400）。
+ *
+ * 非法**字段**只忽略该字段、不整单拒绝：设置页一次提交两项，因一个字段非法
+ * 而丢掉另一项合法修改，用户会误以为保存无效（issue #383 验收项「非法值回退
+ * 默认」）；aiTimeoutMs 非法时回退默认而非保留旧值，与 README 记录的默认口径
+ * 一致。
+ */
+function normalizeConfigPatch(payload, current) {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const raw = payload;
+    const next = { aiReview: current.aiReview, aiTimeoutMs: current.aiTimeoutMs };
+    if (typeof raw.aiReview === 'boolean')
+        next.aiReview = raw.aiReview;
+    if (raw.aiTimeoutMs !== undefined)
+        next.aiTimeoutMs = normalizeTimeout(raw.aiTimeoutMs);
+    return next;
+}
+/** 读取 patch 文件中该行已有的 config 块（文件不存在 / 解析失败 → 空对象）。 */
+async function readExistingConfig(file) {
+    try {
+        return extractConfig(await readFile(file, 'utf8'), CONFIG_ROW_ID) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 写回 profile 层 patch 文件：合并已有键后整体重写（保留用户手写的其他配置）。 */
+export async function persistSettingsConfig(config) {
+    const file = patchFileOf(currentProfile());
+    const existing = await readExistingConfig(file);
+    await writePatchConfig(file, CONFIG_ROW_ID, { ...existing, ...config });
+}
+/**
+ * 分派配置端点：GET 返回当前生效值；PUT 校验 → 写回 + 即时生效。
+ * 未匹配（含其他动词）返回 false，交由调用方回 404（保持既有路由契约）。
+ */
+export async function dispatchConfigRoutes(method, request, response, options, onChange) {
+    if (method !== 'config')
+        return false;
+    if (request.method === 'GET') {
+        writeJson(response, 200, { ok: true, value: configValueOf(options) });
+        return true;
+    }
+    if (request.method !== 'PUT')
+        return false;
+    const next = normalizeConfigPatch(await readJsonBody(request), configValueOf(options));
+    if (next === undefined) {
+        writeJson(response, 400, { ok: false, error: { message: 'invalid config' } });
+        return true;
+    }
+    await onChange(next);
+    writeJson(response, 200, { ok: true, value: next });
+    return true;
+}

package/lib/index.js

@@ -22,17 +22,42 @@
 import { createStore } from './store.js';
 import { attachAuditListeners } from './audit.js';
 import { registerObservabilityRoutes } from './routes.js';
+import { persistSettingsConfig, normalizeTimeout } from './config-routes.js';
 import { createResourceMonitor } from './resource-monitor.js';
 export const name = 'dsh-my-observability';
 export const inject = ['webServer'];
-export function apply(ctx, config) {
-    // ── 配置（应用层 config 覆盖，默认全部开启）─────────────────────────
-    const options = {
+/** 从配置构建 ObservabilityOptions。 */
+function buildOptions(config) {
+    return {
+        aiProvider: config?.aiProvider,
+        aiModel: config?.aiModel,
+        aiCwd: config?.aiCwd,
         aiReview: config?.aiReview !== false,
-        aiTimeoutMs: Number.isFinite(config?.aiTimeoutMs) && config?.aiTimeoutMs > 0
-            ? config?.aiTimeoutMs
-            : 60000,
+        // 与设置页保存共用同一默认值口径（config-routes.normalizeTimeout）。
+        aiTimeoutMs: normalizeTimeout(config?.aiTimeoutMs),
     };
+}
+/**
+ * 设置页保存回调（issue #383）：**先写回 profile patch 文件、再更新内存**——
+ * 写盘失败时保持内存旧值（内存与磁盘不劈叉），并把失败如实抛给路由层；
+ * DSH 的 watchUserPatches 会热重载 patch 文件，保存即生效。
+ */
+function settingsChangeHandler(ctx, options) {
+    return async (next) => {
+        try {
+            await persistSettingsConfig(next);
+        }
+        catch (error) {
+            ctx.logger.warn(`[dsh-my-observability] 配置保存失败（操作=config/save，原因=${error instanceof Error ? error.message : String(error)}）`);
+            throw error;
+        }
+        Object.assign(options, next);
+        ctx.logger.info?.(`[dsh-my-observability] 设置已保存（aiReview=${next.aiReview}, aiTimeoutMs=${next.aiTimeoutMs}）`);
+    };
+}
+export function apply(ctx, config) {
+    // ── 配置（应用层 config 覆盖，默认全部开启）─────────────────────────
+    const options = buildOptions(config);
     // ── 审计存储：会话隔离 + 持久化 + 重启恢复 ──────────────────────────
     const store = createStore(ctx);
     // ── 事件监听（只读观察；waterfall 一律透传 next()）──────────────────
@@ -52,8 +77,8 @@ export function apply(ctx, config) {
         },
     });
     monitor.start();
-    // ── 路由（查询 / git 工具 / diff 审查 / 资源）───────────────────────
-    registerObservabilityRoutes(ctx, store, monitor, options);
+    // ── 路由（查询 / git 工具 / diff 审查 / 资源 / 设置页配置）──────────
+    registerObservabilityRoutes(ctx, store, monitor, options, settingsChangeHandler(ctx, options));
     // ── 卸载冲刷：清防抖定时器 + 立即落盘 + 停采样 ──────────────────────
     ctx.effect(() => {
         monitor.stop();

package/lib/routes.js

@@ -9,14 +9,16 @@
  *  - GET  /git/diff?repo=&staged=  — 差异文本
  *  - POST /git/commit              — 类型化提交（Conventional Commits）
  *  - POST /review                  — 增量 diff 审查（规则引擎 + 可选 AI）
+ *  - GET/PUT /config               — 设置页配置读写（aiReview / aiTimeoutMs）
  */
 import { isTrustedApiRequest, readJsonBody, writeJson, writeError } from 'dsh-shared';
+import { dispatchConfigRoutes } from './config-routes.js';
 import { gitStatus, gitDiff, gitCommit } from './git.js';
 import { parseDiff } from './diff.js';
 import { reviewRules } from './review.js';
 import { runAiReview } from './ai.js';
 /** 注册 /observability/api 路由（effect 持有 disposer）。 */
-export function registerObservabilityRoutes(ctx, store, monitor, options) {
+export function registerObservabilityRoutes(ctx, store, monitor, options, onConfigChange) {
     const webRuntime = ctx.get ? ctx.get('webRuntime') : undefined;
     const trustedHosts = webRuntime !== undefined && webRuntime !== null && Array.isArray(webRuntime.trustedHosts)
         ? webRuntime.trustedHosts
@@ -25,11 +27,11 @@ export function registerObservabilityRoutes(ctx, store, monitor, options) {
     ctx.effect(() => ctx.webServer.register({
         kind: 'prefix',
         path: '/observability/api',
-        handler: apiHandler(ctx, fence, store, monitor, options),
+        handler: apiHandler(ctx, fence, store, monitor, options, onConfigChange),
     }), 'dsh-my-observability: /observability/api routes');
 }
 /** 统一 handler：fence → 方法分派 → 404/错误兜底。 */
-function apiHandler(ctx, fence, store, monitor, options) {
+function apiHandler(ctx, fence, store, monitor, options, onConfigChange) {
     return async (request, response) => {
         if (!fence(request)) {
             writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } });
@@ -43,7 +45,7 @@ function apiHandler(ctx, fence, store, monitor, options) {
             // 状态（曾经的 CI flaky：固定 40ms sleep 赌 readFile 跑完，慢机器上
             // 查询读到 0 条事件 → 0 !== 1）。whenReady 就绪后立即 resolve，无延迟。
             await store.whenReady();
-            const handled = await dispatchMethod(method, request, response, url, ctx, store, monitor, options);
+            const handled = await dispatchMethod(method, request, response, url, ctx, store, monitor, options, onConfigChange);
             if (!handled) {
                 writeJson(response, 404, {
                     ok: false,
@@ -61,11 +63,12 @@ function isMethod(method, request, name, verb) {
     return method === name && request.method === verb;
 }
 /** 按 method 分派到具体 handler；未识别返回 false（调用方回 404）。 */
-async function dispatchMethod(method, request, response, url, ctx, store, monitor, options) {
-    const handled = await dispatchCore(method, request, response, url, ctx, store, monitor, options);
-    if (handled)
+async function dispatchMethod(method, request, response, url, ctx, store, monitor, options, onConfigChange) {
+    if (await dispatchCore(method, request, response, url, ctx, store, monitor, options))
         return true;
-    return dispatchExtended(method, request, response, url, ctx, store);
+    if (dispatchExtended(method, request, response, url, ctx, store))
+        return true;
+    return dispatchConfigRoutes(method, request, response, options, onConfigChange);
 }
 /** 核心路由（复杂度 ≤10）。 */
 async function dispatchCore(method, request, response, url, ctx, store, monitor, options) {
@@ -128,39 +131,72 @@ function statusValue(store, options) {
         gitEnabled: true,
     };
 }
+/** 聚合查询默认超时（3s）：超时未响应的插件标记 { running: false, error: 'timeout' }。 */
+export const PLUGIN_STATUS_TIMEOUT_MS = 3000;
+/** 超时哨兵（区分「超时」与「监听方返回值恰好是 undefined」）。 */
+const STATUS_TIMEOUT = Symbol('plugin-status-timeout');
 /**
- * 插件状态聚合：广播 plugin:status-query 事件，收集所有插件状态。
- * 每个插件返回 { plugin, config, running, lastActions }（config 脱敏，lastActions ≤5）。
- * 超时 3s 未响应的插件标记为 { plugin, running: false, error: 'timeout' }。
+ * 读取插件清单（机会性：服务未激活时 ctx.get 返回 undefined → 空清单）。
+ *
+ * 官方服务是 `ctx.pluginInventory`（host 半边），`list()` 是 **async**——
+ * 同步解引用 `entries` 会抛错。清单名取 `entry.moduleName`（**完整包名**），
+ * 因为监听方正是按完整包名比对自己。
  */
-async function handlePluginStatus(ctx, response) {
-    const TIMEOUT_MS = 3000;
-    const results = [];
+async function readPluginNames(ctx) {
+    const service = ctx.get('pluginInventory');
+    if (service === undefined || service === null)
+        return [];
     try {
-        // 广播查询事件，带超时
-        const statuses = await Promise.allSettled((ctx.bundler?.plugins ?? []).map(async (p) => {
-            // 类型断言内联（不引入额外语句：lib/routes.js 的 v8 语句计数与迁移前一致）
-            const name = p.name ??
-                p.constructor?.name ??
-                'unknown';
-            try {
-                const result = await Promise.race([
-                    ctx.emit('plugin:status-query', { plugin: name }),
-                    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), TIMEOUT_MS)),
-                ]);
-                return result ?? { plugin: name, running: true, config: {}, lastActions: [] };
-            }
-            catch {
-                return { plugin: name, running: false, error: 'timeout' };
-            }
-        }));
-        for (const s of statuses) {
-            results.push(s.status === 'fulfilled' ? s.value : { plugin: 'unknown', running: false, error: 'rejected' });
-        }
+        const snapshot = await service.list();
+        return (snapshot?.entries ?? [])
+            .map((entry) => entry.moduleName)
+            .filter((name) => typeof name === 'string' && name !== '');
     }
     catch {
-        // bundler 不可用时返回空列表
+        return [];
     }
+}
+/** 从分发结果挑出匹配本插件的 value（`ok === true` 且 `value.plugin` 同名）。 */
+function pickStatusValue(collected, name) {
+    for (const item of Array.isArray(collected) ? collected : [collected]) {
+        const response = item;
+        if (response?.ok === true && response.value?.plugin === name)
+            return response.value;
+    }
+    return undefined;
+}
+/**
+ * 单插件状态查询：用 `ctx.serial` 收集监听方返回值。
+ *
+ * cordis 三种派发对返回值的处理各不相同（本机 @deepseek-ai/cordis@4.0.2 实测）：
+ * `emit` 同步派发**不收集**；`parallel` 只处理异常、**不返回结果**（Promise<void>）；
+ * 只有 `serial` 顺序 await 并返回首个非 null/false/undefined 的返回值。逐插件
+ * 查询时非匹配监听方一律 `return undefined`，因此 serial 恰好命中唯一那一条。
+ * 无匹配响应一律如实标记（`no-response`），**绝不编造 running: true**。
+ */
+async function queryPluginStatus(ctx, name, timeoutMs) {
+    // 期望态包装成永不 reject：超时后已丢弃的分发不得变成 unhandled rejection。
+    const dispatch = Promise.resolve()
+        .then(() => ctx.serial('plugin:status-query', { plugin: name }))
+        .then((value) => value, () => undefined);
+    const timer = new Promise((resolve) => {
+        const handle = setTimeout(() => resolve(STATUS_TIMEOUT), timeoutMs);
+        handle.unref?.();
+    });
+    const outcome = await Promise.race([dispatch, timer]);
+    if (outcome === STATUS_TIMEOUT)
+        return { plugin: name, running: false, error: 'timeout' };
+    return pickStatusValue(outcome, name) ?? { plugin: name, running: false, error: 'no-response' };
+}
+/**
+ * 插件状态聚合：按插件清单逐个查询 `plugin:status-query`，汇总监听方真实状态。
+ * 每条为监听方返回的 { plugin, config, running, stats?, lastActions? }；超时 3s
+ * 未响应标 { running: false, error: 'timeout' }，无匹配响应标 no-response。
+ * 清单不可用（服务未激活）时返回空列表 `{ ok: true, value: [] }`。
+ */
+export async function handlePluginStatus(ctx, response, timeoutMs = PLUGIN_STATUS_TIMEOUT_MS) {
+    const names = await readPluginNames(ctx);
+    const results = await Promise.all(names.map((name) => queryPluginStatus(ctx, name, timeoutMs)));
     writeJson(response, 200, { ok: true, value: results });
 }
 /** 错误事件查询（#155 错误上报统一）：返回 plugin_error 类型事件。 */
@@ -235,16 +271,15 @@ async function aiOutcome(ctx, payload, options, diffText, report) {
         return { enabled: false };
     if (payload.aiReview === false)
         return { enabled: false };
-    return runAiReview(ctx, diffText, report, options.aiTimeoutMs);
+    return runAiReview(ctx, diffText, report, options.aiTimeoutMs, {
+        provider: options.aiProvider,
+        model: options.aiModel,
+        cwd: options.aiCwd,
+    });
 }
 // ── HTTP helpers ───────────────────────────────────────────────────────────
-function queryOf(url, name) {
-    return url.searchParams.get(name) ?? '';
-}
-function repoOf(url) {
-    const repo = url.searchParams.get('repo');
-    return typeof repo === 'string' ? repo : '';
-}
+const queryOf = (url, name) => url.searchParams.get(name) ?? '';
+const repoOf = (url) => url.searchParams.get('repo') ?? '';
 function limitOf(url) {
     const raw = url.searchParams.get('limit');
     const parsed = raw === null ? 0 : Number(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-observability",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "DSH 可观测性 + Git 工程工具插件：会话轨迹回放（时间轴）、事件审计（agent 行为记录）、结构化 Git 提交（Conventional Commits）、增量 diff 审查（提交前审查）。DSH web plugin: trajectory replay timeline, event audit log, structured git commits, pre-commit incremental diff review.",
   "type": "module",
   "main": "lib/index.js",
@@ -14,7 +14,7 @@
   "scripts": {
     "build": "npx tsc -p tsconfig.json && node scripts/build.mjs",
     "typecheck": "npx tsc --noEmit -p tsconfig.json && npx tsc --noEmit -p tsconfig.client.json",
-    "test": "npx vitest run --coverage && cucumber-js test/features --import 'test/features/steps/*.mjs'"
+    "test": "npx vitest run --coverage && cucumber-js test/features --import \"test/features/steps/*.mjs\""
   },
   "exports": {
     ".": {
@@ -42,9 +42,9 @@
     }
   },
   "peerDependencies": {
-    "cordis": "^4.0.0-rc.8",
-    "react": "^18.2.0 || ^19.2.0",
-    "dsh-shared": "^0.1.4"
+    "cordis": "^4.0.0-rc.10",
+    "dsh-shared": "^0.1.4",
+    "react": "^18.2.0 || ^19.3.0"
   },
   "peerDependenciesMeta": {
     "cordis": {
@@ -58,5 +58,8 @@
     "@types/node": "^26.5.1",
     "typescript": "^7.0.2"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "tmp": "^0.2.7"
+  }
 }