前言¶
在 DSH 里做 lot2 相关开发或运维时，运行期 gauge、阈值结论和数据库查询画像往往散落在采集脚本落盘的 JSON 与 Prometheus 侧；智能体若要回答「现在慢在哪」「阈值是否越界」，要么读本地文件、要么再拼一遍查询逻辑。重复实现评分或展示规则，还容易和采集器结论不一致。dsh-lot2-metrics 由 LosEcher 维护，归类为联网工具，只做一件事：只读呈现 lot2 后端指标快照，并在 host 侧注册两个只读 agent 工具与会话视图，不抓取 /metrics、不写盘。
这是什么¶
插件把 lot2 后端数据库指标 的采集快照变成 DSH 里「agent 可查 + 可观测」的只读层。数据契约见 dsfolder/CROSS-PROJECT-INTEGRATION-MECHANISM-2026-10-07.md §9（「项目快照信封 v1」）：取数与契约属 lot2（lot2extension/scripts/metrics-report.mjs）；触发与落盘属 DSH 采集（dsfolder/scripts/lot2-metrics-collect.sh 与 launchd com.echerlos.lot2-metrics）；呈现与查询属本插件——只读快照文件，绝不抓取、不写盘。
两半分工如下：
| 面 | 内容 |
|---|---|
| host | 2 个只读 agent 工具 + GET /plugins/dsh-lot2-metrics/status、GET /plugins/dsh-lot2-metrics/snapshot |
| client | 会话 tab「lot2 指标」（conversation.view，order 92） |
社区目录页：https://www.skillhub.cn/plugins/LosEcher/dsh-lot2-metrics；源码：https://github.com/LosEcher/dsh-lot2-metrics。目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
Agent 工具（只读）¶
lot2_metrics_overview：概览，含新鲜度、Top-N 调用量、放大倍数，以及采集器状态、阈值结论、运行期 gauge。lot2_metrics_query：按 operation / 关键字过滤，按 count、p95、deltaCount、amplification 排序并取 Top-N。
回答必带 capturedAt 与快照路径，便于追溯；p95 在展示与工具输出中均标注为直方图插值近似值。
HTTP 端点¶
GET /plugins/dsh-lot2-metrics/status：约定形状的插件状态。GET /plugins/dsh-lot2-metrics/snapshot：面板数据源，cache-control: no-store。
会话 tab「lot2 指标」¶
在 DSH shell 的会话视图中展示：阈值 → 运行期 → 调用量 Top → 放大倍数 Top；60 秒轮询，支持手动刷新。
配置项¶
插件可读配置包括：snapshotPath、statePath、staleSeconds（默认 1500）、topN（默认 5）。
运行期与阈值（快照 runtime{}）¶
快照在兼容变更下增加 runtime{}（信封 v 仍为 1）：声明式 gauge 清单，以及 http（如 5xx）、cache、counterDelta 等。本插件对显示有三条纪律：
value=null且带reason时显示为—并给出原因，避免「分母为 0 算不出命中率」被误读成「没有这一项」；面板与工具一致。unknown（采集器声明了但/metrics未上报的名称）单独列出，标注「缺失≠0」；例如snapshot_queue_depth、unified_queue_depth可能长期处于该状态（按需注册）。- 阈值不由本插件判定：采集器在
dsfolder/scripts/lot2-metrics-collect.sh中判定一次并写入collector-state.json的thresholds[]，插件只读结论，避免同一份事实两处评分。面板上可区分：越界 / 正常 / 无数据。
四条语义（有测试覆盖）¶
- 未知信封版本
v⇒ 报契约不兼容，绝不渲染数字（不猜字段）。 ok=false⇒ 不给任何数字，不把上一次数值当成本次结果。- 缺字段、坏 JSON、文件不存在 ⇒ 不抛异常，降级为该块留空并附 reason；插件不向 cordis 抛异常。
- 回答必带
capturedAt与快照路径；p95标注为直方图插值近似值。
derived.note 仅作人读提示，不参与判断（lot2 契约 §10：固定字段名与固定句子，不承载数据）。
安装与启用¶
在对应 profile 下执行官方安装方式之一。首次挂载仅改配置时可热生效；改 host 半代码后须重启对应 DSH 宿主（Node ESM 按 URL 缓存）。只改 client 半（src/client/* 且 npm run build）则刷新页面即可。
本地开发（link 工作副本）：
cd ~/.dsh/profiles/web
dsh plugin --profile web add link:<这个仓的本机路径>
使用发布版：
cd ~/.dsh/profiles/web
dsh plugin --profile web add github:LosEcher/dsh-lot2-metrics#main
desktop profile 需要同样工具时，将命令中的 web 换成 desktop（会重启桌面宿主，正在跑的会话可能被打断，请择时操作）。
安装前请自行查看仓库源码与许可证（README 标明 MIT）；插件以当前 dsh 进程权限运行，只读本地快照路径，仍应确认路径与数据敏感度是否符合你的环境。
典型用法¶
验收与本地检查¶
node --test test/*.test.mjs
node test/preflight.mjs
curl -s localhost:3080/plugins/dsh-lot2-metrics/status | python3 -m json.tool
在已挂载插件且宿主运行的前提下，智能体可调用 lot2_metrics_overview、lot2_metrics_query 做只读查询；人在会话中打开「lot2 指标」tab 查看同一快照源的图形化分区。
看不到「lot2 指标」tab 时¶
该 tab 属于 DSH shell 会话视图；桌面 App 与浏览器共用同一 shell，未通过 DSH 浏览器认证时可能什么都看不到。
本机 dsh web 需使用带 launch token 的 URL（非普通 http://127.0.0.1:3080/），daemon 以 --no-open 启动时 URL 写在 ~/.dsh/logs/dsh-web.log：
dsh-web-url
dsh-web-url --open
远程经 Tailscale serve 时：
dsh-web-url --remote
进入后，tab 仍会按契约不兼容、采集失败、过期、新鲜等状态独立展示。
适用场景与边界¶
适合：已在 lot2 + DSH 采集链路上落盘指标快照，希望在 DSH 内用 agent 工具与会话 tab 统一只读查看，且不希望插件侧再实现一套阈值或抓取逻辑。
不适合或不做的事（README 明确边界）：
- 不抓取
/metrics、不写任何文件、不改 lot2 库。 - 不往
dsh-dashboards塞 widget；本插件走自有状态端点与 agent 工具。
依赖方面，package.json 要求 @deepseek-ai/cordis 为 >=4.0.0 <5.0.0；当前资料中插件版本为 0.1.0。
结尾¶
dsh-lot2-metrics 把 lot2 后端指标快照固定在「只读呈现 + 两个 agent 工具 + 会话 tab」一层，阈值与采集仍归采集器，避免双源评分。需要安装说明与排障细节时，以 GitHub README 为准；社区索引见 SkillHub 目录页，源码见 LosEcher/dsh-lot2-metrics。
