插件可观测性面板ddtcorex/dsh-maestro-observe

dsh-maestro-observe

Maestro observe — trace/health/cost 调试工具（第 3 阶段）

DSH Maestro 插件 — dsh-maestro- 生态系统的一部分（@ddtcorex/dsh-maestro-observe）。

面向 Maestro 插件栈的本地优先可观测性。宿主将 turn/tool/error 信号记录到可查询的 SQLite 存储中
（~/.dsh/dsh-maestro-observe/observe.sqlite，0600），并通过
maestro-observe 工具和 /dsh-maestro-observe 回环 RPC 暴露这些信号。
渲染位于 dsh-maestro-dashboard（Activity 标签页）中，它调用下面的 RPC —
本包不附带任何客户端 UI。Telegram 摘要和峰值告警通过可选的
maestroNotifier 服务投递 — 即使没有它，插件也能完整运行。

安装

dsh plugin add @ddtcorex/dsh-maestro-observe

工具 / RPC 操作

这些操作在工具（op）和 RPC（端点名称）上一一对应；未知的
操作/端点会安全失败。

- trace { limit?, sessionId?, tool?, kind?, since? } — 最新优先的记录。
- cost { scope: 'day'|'session', sessionId?, day?, groupBy?: 'tool'|'session' }
（day 选择显式的 UTC 日期；不带 since 的 groupBy 表示全生命周期）。
- budget { action: 'set'|'check', scope, key, limit_tokens? } — token 预算。
- config { action: 'get'|'set', key, value? } — 运维调节项。
- errors { tool?, since? } — 按工具 + 规范化签名分组。
- latency { tool?, since? } — { count, p50, p95, p99 } latencyMs。
- health {} — 插件、工具数量、各通道状态、去重后的降级列表。
- status（仅 RPC）— 运行时长、版本、环形缓冲区大小、行数。

RPC 调用约定（供 dashboard 及其他消费者使用）

Connection 传输要求端点分发加上载体形状 —
rpc.call(channel, endpoint, payload) 返回
{ ok: true, value } | { ok: false, error: { code, message, details } }。
服务器会拒绝其他任何形式，因此发送单个 { method }
对象或跳过载体解包的客户端会静默失败。使用
res?.ok ? res.value : null 解包。observe 插件不存在 → 调用被拒绝：应隐藏
依赖它的 UI，而不是渲染零值。

配置键（config 操作）

| 键 | 默认值 | 含义 |
|---|---|---|
| retention_days | 30 | 每日清理的 trace 保留期 |
| detail_max_chars | 500 | 由 redact 管道应用的详情截断长度 |
| digest_schedule | 08:00 | 每日 Telegram 摘要的本地 HH:MM |
| spike_n / spike_m | 10 / 5 | 在 M 分钟内出现 N 个错误后告警 |
| telegram.botToken / telegram.chatId | — | 摘要 + 峰值告警的 Telegram 目标 |

trace 详情中的机密在持久化前会被脱敏（机密形状 →
[redacted]，详情被截断）。会话成本为会话生命周期；日成本、
摘要窗口和保留截止时间按 UTC 日计算（摘要的触发时间*
为本地 HH:MM）。

Telegram 设置

1. 安装 @ddtcorex/dsh-maestro-notifier（提供 maestroNotifier）。
2. config set telegram.botToken ，config set telegram.chatId
（或 budget/config 工具操作）。
3. 每日摘要按 digest_schedule 触发；尖峰告警在错误率阈值处触发。没有通知器时，两者都保持静默并记录一条警告——不会抛出任何异常。

开发

pnpm verify        # tsc --noEmit
pnpm test          # vitest run
pnpm build         # tsc -p tsconfig.json  -> lib/