opencode-metrics-plugin 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.0（2026-09-15）
+
+- 新增会话 agent 白名单 `agents`（支持 `*` 通配，如 `["android-to-hmos-*", "build"]`）：配置后只有根会话 agent 命中任一模式才记录——快照、事件日志、system prompt、上传全不产生；子会话（task/explore 等）随父会话判定正常并入；agent 未知的会话默认记录（fail-open）。缺省/空数组 = 不过滤全记（向后兼容）。
+- 典型用法：全局 `~/.config/opencode/opencode.json` 注册 `["opencode-metrics-plugin", { "agents": ["android-to-hmos-*"] }]`，实现「插件处处加载、只统计迁移 agent 的会话」，不受 opencode 项目级配置发现的 git 边界限制。注意项目 `.opencode/opencode-metrics.json(c)` 存在时仍会完全接管（含 `agents`），接管文件需同步配置。
+
 ## 0.3.5（2026-09-15）
 
 - 修复「重启 + resume 续跑」系列数据损坏：steps 重复乱序、planning 清零、tokens/工具统计丢段、agent/model 归因丢失；累加字段改差量并入，连发消息即切轮、退出兜底补轮。

package/README.md

@@ -90,6 +90,7 @@
 | 选项 | 类型 | 默认 | 说明 |
 |---|---|---|---|
 | `enabled` | boolean | `true` | 总开关，`false` 时不记录任何会话 |
+| `agents` | string[] | — | 会话 agent 白名单（`*` 通配，如 `["android-to-hmos-*", "build"]`）：根会话 agent 命中才记录（快照/事件日志/上传全不产生），子会话随父判定；缺省全记 |
 | `eventLogging` | boolean | `true` | 原始事件写盘；关闭后快照仍生成，但 `steps[].text/reasoning` 为空 |
 | `checkpointFlushIntervalMs` | number | `2000` | 实时落盘冷却窗口（ms），`0` 关闭退回只在会话空闲时落盘 |
 | `dirs` | object | env-paths | `metricsDir` / `eventsDir` / `logFile`（基准，实际写 `<所在目录>/log/plugin/YYYYMMDD.log`）/ `uploadStagingDir` |

package/dist/metrics/runtime.d.ts

@@ -6,6 +6,12 @@ export interface MetricsRuntimeOptions extends Omit<MetricsEngineOptions, 'enabl
     enabled?: boolean;
     /** 事件写盘（events/<sessionId>.log；steps 全文的数据源） */
     eventLogging?: boolean;
+    /**
+     * 会话 agent 白名单（通配符 `*`，如 ["android-to-hmos-*", "build"]）：
+     * 根会话的 agent 命中任一模式才记录（快照/事件日志/上传全不产生），子会话随父判定；
+     * 缺省/空数组 = 不过滤，记录全部会话（向后兼容）。
+     */
+    agents?: string[];
     /** 上传子系统配置（DESIGN.md §13.8）；enabled:true 才会创建管理器 */
     upload?: UploadConfig;
 }
@@ -18,6 +24,11 @@ export declare function createMetricsRuntime(opts?: MetricsRuntimeOptions): {
     eventLogger: import("./eventlog/event-logger.js").EventLogger | null;
     engine: import("./types.js").MetricsEngine;
     uploadManager: import("./upload/uploadManager.js").UploadManager | null;
+    sessionFilter: {
+        active: boolean;
+        shouldTrackEvent: (event: import("./sessionFilter.js").SessionFilterEvent) => boolean;
+        shouldTrackSession: (sessionId: string) => boolean;
+    };
     /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
     event(input: {
         event: {

package/dist/metrics/runtime.js

@@ -1,5 +1,6 @@
 import { createMetricsEngine } from './engine/engine.js';
 import { createEventLogger } from './eventlog/event-logger.js';
+import { createSessionFilter } from './sessionFilter.js';
 import { resolveDirs } from './dirs.js';
 import { createUploadManager } from './upload/uploadManager.js';
 /**
@@ -17,6 +18,8 @@ export function createMetricsRuntime(opts = {}) {
     const eventLogger = (opts.eventLogging ?? true)
         ? createEventLogger(true, false, { eventsDir: dirs.eventsDir })
         : null;
+    // 会话 agent 过滤：event 入口统一拦截，事件日志/引擎/上传三个子系统一次挡住
+    const sessionFilter = createSessionFilter(opts.agents);
     // 上传管理器旁路挂在 runtime.event 上（在 engine.ingest 之后，保证触发时快照已落盘）
     const uploadManager = createUploadManager({
         config: opts.upload,
@@ -32,8 +35,11 @@ export function createMetricsRuntime(opts = {}) {
         eventLogger,
         engine,
         uploadManager,
+        sessionFilter,
         /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
         event(input) {
+            if (!sessionFilter.shouldTrackEvent(input.event))
+                return;
             eventLogger?.log(input.event);
             engine.ingest(input.event);
             uploadManager?.observe(input.event);

package/dist/metrics/sessionFilter.d.ts

@@ -0,0 +1,12 @@
+export interface SessionFilterEvent {
+    type: string;
+    properties?: Record<string, unknown>;
+}
+/** 通配符转正则：* → 任意串，其余字符按字面匹配；整串匹配，大小写敏感 */
+export declare function compileAgentPatterns(patterns: readonly string[]): RegExp[];
+export declare function createSessionFilter(agents?: readonly string[]): {
+    active: boolean;
+    shouldTrackEvent: (event: SessionFilterEvent) => boolean;
+    shouldTrackSession: (sessionId: string) => boolean;
+};
+export type SessionFilter = ReturnType<typeof createSessionFilter>;

package/dist/metrics/sessionFilter.js

@@ -0,0 +1,104 @@
+// 会话 agent 过滤器：按根会话的 agent 通配匹配决定是否记录，子会话随父判定。
+//
+// 设计要点：
+// - 判定信号：session.created / session.updated 的 properties.info.agent（实测会话首个事件即携带）；
+//   message.updated 的 info.agent 作兜底（session 事件缺 agent 时）。agent 首次非空即终判，不再翻案。
+// - fail-open：agent 始终未知的会话默认记录，防止 opencode 事件结构变化导致漏采。
+// - 子会话（info.parentID）不独立判定，解析到根会话后跟随其判定；父未判定时同样放行。
+// - 未配置 agents（缺省/空数组/全空串）时过滤器不激活，所有事件直通（向后兼容）。
+/** 通配符转正则：* → 任意串，其余字符按字面匹配；整串匹配，大小写敏感 */
+export function compileAgentPatterns(patterns) {
+    const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return patterns.map((p) => new RegExp(`^${p.split("*").map(escape).join(".*")}$`));
+}
+export function createSessionFilter(agents) {
+    const patterns = (agents ?? []).filter((p) => typeof p === "string" && p.length > 0);
+    const active = patterns.length > 0;
+    const regexes = active ? compileAgentPatterns(patterns) : [];
+    const decisions = new Map();
+    const childToParent = new Map();
+    function matchesAgent(agent) {
+        return regexes.some((re) => re.test(agent));
+    }
+    /** 沿 parentID 链向上找根会话（防环，最多 10 层） */
+    function resolveRoot(sessionId) {
+        let root = sessionId;
+        for (let i = 0; i < 10; i++) {
+            const parent = childToParent.get(root);
+            if (!parent)
+                break;
+            root = parent;
+        }
+        return root;
+    }
+    function decide(rootId, agent) {
+        const existing = decisions.get(rootId);
+        if (existing === "in" || existing === "out")
+            return;
+        decisions.set(rootId, matchesAgent(agent) ? "in" : "out");
+    }
+    /** 会话级判定：供 system.transform 等按 sessionId 查询的入口 */
+    function shouldTrackSession(sessionId) {
+        if (!active)
+            return true;
+        return decisions.get(resolveRoot(sessionId)) !== "out";
+    }
+    function extractSessionId(props) {
+        const sessionID = props.sessionID;
+        if (typeof sessionID === "string" && sessionID)
+            return sessionID;
+        const info = props.info;
+        const id = info?.id;
+        if (typeof id === "string" && id)
+            return id;
+        return undefined;
+    }
+    /**
+     * 事件级判定 + 状态机推进；返回 false 表示该事件所属会话不在记录范围。
+     * 无法归属会话的事件放行（引擎侧自会丢弃）。
+     */
+    function shouldTrackEvent(event) {
+        if (!active)
+            return true;
+        const props = event.properties;
+        if (!props)
+            return true;
+        if (event.type === "session.created" || event.type === "session.updated") {
+            const info = props.info;
+            const id = info?.id;
+            if (typeof id === "string" && id) {
+                const parentID = info.parentID;
+                if (typeof parentID === "string" && parentID) {
+                    childToParent.set(id, parentID);
+                }
+                else {
+                    const agent = info.agent;
+                    if (typeof agent === "string" && agent)
+                        decide(id, agent);
+                }
+            }
+        }
+        else if (event.type === "message.updated") {
+            // 兜底：session 事件一直没带 agent 时，用消息的 agent 定案（仅根会话）
+            const sessionID = props.sessionID;
+            const info = props.info;
+            const agent = info?.agent;
+            if (typeof sessionID === "string" && sessionID && typeof agent === "string" && agent && !childToParent.has(sessionID)) {
+                decide(resolveRoot(sessionID), agent);
+            }
+        }
+        else if (event.type === "session.deleted") {
+            // 清理：根会话删除即移除判定；子会话删除移除映射
+            const sid = extractSessionId(props);
+            if (sid) {
+                childToParent.delete(sid);
+                decisions.delete(sid);
+            }
+        }
+        const sid = extractSessionId(props);
+        if (!sid)
+            return true;
+        return shouldTrackSession(sid);
+    }
+    return { active, shouldTrackEvent, shouldTrackSession };
+}

package/dist/plugin.js

@@ -23,6 +23,7 @@ export const MetricsPlugin = async (input, options) => {
         eventsDir: runtime.dirs.eventsDir,
         enabled: config.enabled !== false,
         upload: Boolean(runtime.uploadManager),
+        agents: runtime.sessionFilter.active ? config.agents : null,
         configSource: source,
     });
     const hooks = {
@@ -31,11 +32,13 @@ export const MetricsPlugin = async (input, options) => {
                 event: event,
             });
         },
-        // 记录各模型 system prompt（只读不改写、不返回；子代理跳过）
+        // 记录各模型 system prompt（只读不改写、不返回；子代理跳过；agents 过滤外的会话跳过）
         "experimental.chat.system.transform": async (input, output) => {
             const sessionId = input.sessionID;
             if (!sessionId)
                 return;
+            if (!runtime.sessionFilter.shouldTrackSession(sessionId))
+                return;
             if (runtime.eventLogger?.isSubAgent(sessionId))
                 return;
             const modelId = input.model?.id ?? "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-metrics-plugin",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "opencode plugin: auto-records every session's metrics (tokens/rounds/steps/sub-agents/hvigor builds) to snapshot JSON. Zero DB, zero config. Pair with session-viewer for visualization.",
   "type": "module",
   "license": "MIT",