@dijkspicy/opencode-stats-reporter 0.1.0 → 0.1.2

package/README.md

@@ -20,17 +20,18 @@
 
 ```bash
 npm i -g @dijkspicy/opencode-stats-reporter
-opencode-stats-reporter config set --gateway https://<你的网关> --key <你的 API Key>
 opencode-stats-reporter web start          # 打开 http://127.0.0.1:8787
 ```
 
+- **无需单独填网关和 Key**：默认自动从 opencode 配置读取——取所选模型对应 provider 的 `options.baseURL` / `options.apiKey`（Key 不在配置里时回退到 opencode 凭据存储 `auth.json`）；也可显式覆盖：`opencode-stats-reporter config set --gateway <url> --key <key> [--endpoint <url>]`，或环境变量 `OPENCODE_STATS_GATEWAY` / `OPENCODE_STATS_API_KEY`（优先级：本工具配置 > 环境变量 > opencode 推导）；
+
 - 本地服务同时做三件事：托管静态面板、把 `/v1/usage/*` 与 `/v1/models` **反代**到你的网关（Key 只保存在服务端）、并在本地 SQLite 存储会话用量；
 - 浏览器只与 `localhost` 通信，因此**没有 CORS 问题，上游 Key 也不会进入浏览器**；
 - 会话上报插件，**推荐用 opencode 自带的插件命令安装**（走 npm，随包更新）：
   ```bash
   opencode plugin @dijkspicy/opencode-stats-reporter -g
   ```
-  离线/本地文件方式作为替代：`opencode-stats-reporter plugin install`。之后在 opencode 进程环境设置 `SESSION_USAGE_ENDPOINT=http://127.0.0.1:8787/v1/session-usage/report`（本地模式无需 `SESSION_USAGE_API_KEY`，且不要用 `--pure` 启动）；
+  离线/本地文件方式作为替代：`opencode-stats-reporter plugin install`。插件**零配置**：启动服务后插件自动上报（`web start` 会把实际端点写入 `config.json`，插件未设环境变量时也生效；如需覆盖可用 `config set --endpoint <url>` 或环境变量 `SESSION_USAGE_ENDPOINT`。本地模式无需 `SESSION_USAGE_API_KEY`，且不要用 `--pure` 启动）；
 - 默认仅监听 `127.0.0.1`；数据落在 `~/.local/share/opencode-stats-reporter/`，不会上传第三方；
 - **托管模式**：`opencode-stats-reporter web start --mode gateway` 时，会话接口要求网关注入的身份（`X-Forward-Consumer`），并按消费者做租户隔离；本地模式则为单一本地用户；
 - 要求 Node ≥ 24（使用内置 `node:sqlite`，零外部依赖）。

package/contrib/opencode-session-reporter/README.md

@@ -22,11 +22,23 @@ cp session-usage-reporter.ts .opencode/plugins/
 - 注意：以 `--pure` 启动 opencode 会禁用全部外部插件（包括本插件）。
 - 一个 opencode server 实例加载一份插件实例；插件按事件里的 `sessionID` 处理对应会话，无需多份。
 
+## 零配置：上报端点解析
+
+插件**始终激活**，无需任何环境变量。上报端点按以下优先级解析（从高到低）：
+
+1. 环境变量 `SESSION_USAGE_ENDPOINT`（trim 后非空即用；保留为显式覆盖）
+2. 本工具配置文件 `<configDir>/config.json` 的 `reportEndpoint` 字段（须是合法 http(s) URL）
+3. 内置默认值 `http://127.0.0.1:8787/v1/session-usage/report`
+
+其中 `configDir` 为 `MONITOR_CONFIG_DIR` 或 `$XDG_CONFIG_HOME/opencode-stats-reporter`（与 `src/paths.js` 一致）。配套 CLI 的 `web start` 启动后会自动把实际监听端口的端点（`http://127.0.0.1:<port>/v1/session-usage/report`）写入 `config.json` 的 `reportEndpoint`，因此**启动服务 + 安装插件即可，无需任何手动配置**。
+
+config.json 不存在、JSON 非法、字段缺失或 URL 非法时一律静默回退到下一优先级，解析过程绝不抛错。插件初始化成功后会通过 `app.log` 输出一条 info 日志（含最终端点与来源 `env/config/default`），便于排查「装了插件却没上报」的问题。
+
 ## 环境变量
 
 | 变量 | 必填 | 说明 |
 | --- | --- | --- |
-| `SESSION_USAGE_ENDPOINT` | 是（未设置则插件完全惰性） | 上报端点 URL。插件对它发 `POST`，`content-type: application/json`，body 见下。 |
+| `SESSION_USAGE_ENDPOINT` | 否（显式覆盖，优先级最高） | 上报端点 URL。插件对它发 `POST`，`content-type: application/json`，body 见下。不设置时走 `config.json` 的 `reportEndpoint`，再退回内置默认值。 |
 | `SESSION_USAGE_API_KEY` | 否 | 上报请求的网关 Key（插件发 `Authorization: Bearer <key>`）。网关 key-auth 通过后注入 `X-Forward-Consumer`，服务端据此确定租户。未配置则不带鉴权头。 |
 
 > **身份来源**：载荷本身**不含**任何消费者身份字段。若 `SESSION_USAGE_ENDPOINT` 指向网关后的服务，必须配 `SESSION_USAGE_API_KEY`，否则请求会被网关 401 拒绝。
@@ -36,6 +48,7 @@ cp session-usage-reporter.ts .opencode/plugins/
 ## 行为
 
 - **触发时机**：bus 事件 `session.idle`，或 `session.status` 且 `status.type === "idle"`（两种空闲信号都处理）。
+- **初始化可观测**：插件加载即解析端点并通过 `app.log` 记录 info 日志（端点 + 来源）；上报失败仅在**每轮连续失败的首 次**记录日志（成功后重置），服务端未运行时不会刷屏。
 - **采集**：经 SDK 读取 `session.messages`（仅统计 `role === "assistant"` 且 `info.time.completed` 已设置的**已完成**消息，天然去重不双计），再经 `session.children` 递归子会话。
 - **父子独立**：每个会话（含子代理会话）各自生成一条快照；**父会话快照绝不并入子会话用量**。
 - **口径原样分列**：`tokens_input / tokens_output / tokens_reasoning / tokens_cache_read / tokens_cache_write` 直接取自 `info.tokens`，**客户端不做任何相加或换算**（opencode 语义：`output` 不含 `reasoning`，`input` 不含 `cache.read`；`cost` 恒为 0，不采信、不上报）。合计由服务端派生。
@@ -52,7 +65,7 @@ cp session-usage-reporter.ts .opencode/plugins/
 {
   "schema_version": 1,
   "install_id": "0b3f7e6a-....",
-  "reporter": { "client": "opencode", "version": "0.1.0" },
+  "reporter": { "client": "opencode", "version": "0.1.2" },
   "sessions": [
     {
       "session_id": "ses_...",
@@ -80,13 +93,13 @@ cp session-usage-reporter.ts .opencode/plugins/
 bun test reporter.test.ts    # 或 bun run reporter.test.ts
 ```
 
-自包含 mock 测试（mock client + mock fetch），无网络、无需真实 opencode：覆盖已完成消息过滤、父子独立计量、载荷结构与无身份字段、队列上限丢最旧、失败批次保留 + 退避调度、成功清空队列、dispose 成功/失败路径、退避曲线、install_id 稳定性。
+自包含 mock 测试（mock client + mock fetch），无网络、无需真实 opencode：覆盖已完成消息过滤、父子独立计量、载荷结构与无身份字段、队列上限丢最旧、失败批次保留 + 退避调度、成功清空队列、dispose 成功/失败路径、退避曲线、install_id 稳定性、**端点解析优先级（env / config / default 全分支）与未设环境变量时插件仍激活**。
 
 ## 局限
 
 - **队列在内存**：进程崩溃（非正常 dispose 退出）会丢失未上报的积压；队列满后丢最旧。
 - **会话级快照**：无 per-message / 按模型 / 按时间细分；一个会话只记录最后一条消息的 model/agent，多模型会话归属到最后的模型。
 - **消息被压缩/删除**时 `message_count` 可能回退，revision 随之回退——依赖服务端单调守卫保留较高修订。
-- **不携带身份与鉴权**：请求无凭据，完全依赖网关注入消费者身份（与设计 D4/D9 一致）；端点本身须由网关/服务端做租户隔离与限流。
+- **不携带身份与鉴权**：载荷无凭据；`SESSION_USAGE_API_KEY` 未配置时请求不带鉴权头，完全依赖网关注入消费者身份（与设计 D4/D9 一致）；端点本身须由网关/服务端做租户隔离与限流。默认端点指向本机 `127.0.0.1`，服务未启动时数据仅进本地队列（有界、退避重试）。
 - **与 opencode 版本耦合**：消息/事件/插件 loader 形状按 1.18.33 核实，字段均为防御式读取；升级 opencode 后建议重跑测试。
 - 每台机器一个 `install_id`；同一消费者跨机器的会话默认按 `install_id` 分列。

package/contrib/opencode-session-reporter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-reporter",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": true,
   "type": "module",
   "description": "opencode 客户端插件：在会话空闲时聚合各会话（含子代理会话）的 token 用量快照，经有界队列 + 指数退避非阻塞上报；载荷不含消费者身份字段。",

package/contrib/opencode-session-reporter/reporter.test.ts

@@ -20,6 +20,8 @@ import {
   createQueue,
   createReporterCore,
   loadOrCreateInstallId,
+  resolveReportEndpoint,
+  SessionUsageReporter,
 } from "./session-usage-reporter.ts"
 import type {
   ReporterClient,
@@ -364,6 +366,121 @@ await runTest("loadOrCreateInstallId 首次生成、之后稳定复用同一 UUI
   }
 })
 
+await runTest("resolveReportEndpoint: env 存在时优先于 config 与默认值", () => {
+  const r = resolveReportEndpoint({
+    env: { SESSION_USAGE_ENDPOINT: "http://env.example:1/report" },
+    configFile: "/nonexistent/config.json",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: "http://cfg.example:2/report" }),
+  })
+  assertEqual(r.endpoint, "http://env.example:1/report", "endpoint")
+  assertEqual(r.source, "env", "source")
+})
+
+await runTest("resolveReportEndpoint: env 为空/空白时回退 config（并 trim）", () => {
+  const empty = resolveReportEndpoint({
+    env: {},
+    configFile: "/nonexistent/config.json",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: "http://cfg.example:2/report" }),
+  })
+  assertEqual(empty.endpoint, "http://cfg.example:2/report", "空 env → config")
+  assertEqual(empty.source, "config", "source")
+
+  const blank = resolveReportEndpoint({
+    env: { SESSION_USAGE_ENDPOINT: "   " },
+    configFile: "/nonexistent/config.json",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: "  http://cfg.example:2/report  " }),
+  })
+  assertEqual(blank.endpoint, "http://cfg.example:2/report", "空白 env → config（值已 trim）")
+  assertEqual(blank.source, "config", "source")
+})
+
+await runTest("resolveReportEndpoint: config 缺失/JSON 非法/reportEndpoint 非法 → 回退默认值", () => {
+  const env = {}
+  const missing = resolveReportEndpoint({
+    env,
+    configFile: "/nonexistent/config.json",
+    readFileSyncFn: () => {
+      throw new Error("ENOENT")
+    },
+  })
+  assertEqual(missing.endpoint, "http://127.0.0.1:8787/v1/session-usage/report", "config 缺失 → 默认")
+  assertEqual(missing.source, "default", "source")
+
+  const badJson = resolveReportEndpoint({ env, configFile: "/x", readFileSyncFn: () => "{not json" })
+  assertEqual(badJson.source, "default", "JSON 非法 → 默认")
+
+  const badUrl = resolveReportEndpoint({
+    env,
+    configFile: "/x",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: "not-a-url" }),
+  })
+  assertEqual(badUrl.source, "default", "非法 URL → 默认")
+
+  const wrongScheme = resolveReportEndpoint({
+    env,
+    configFile: "/x",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: "ftp://example.com/report" }),
+  })
+  assertEqual(wrongScheme.endpoint, "http://127.0.0.1:8787/v1/session-usage/report", "非 http(s) → 默认")
+
+  const wrongType = resolveReportEndpoint({
+    env,
+    configFile: "/x",
+    readFileSyncFn: () => JSON.stringify({ reportEndpoint: 123 }),
+  })
+  assertEqual(wrongType.source, "default", "非字符串字段 → 默认")
+})
+
+await runTest("resolveReportEndpoint: 三者皆缺 → 内置默认值", () => {
+  const r = resolveReportEndpoint({
+    env: {},
+    configFile: "/nonexistent/config.json",
+    readFileSyncFn: () => {
+      throw new Error("ENOENT")
+    },
+  })
+  assertEqual(r.endpoint, "http://127.0.0.1:8787/v1/session-usage/report", "默认端点")
+  assertEqual(r.source, "default", "来源")
+})
+
+await runTest("插件未设 SESSION_USAGE_ENDPOINT 时依然激活（返回 event/dispose 并输出端点日志）", async () => {
+  const savedEndpoint = process.env.SESSION_USAGE_ENDPOINT
+  const savedConfigDir = process.env.MONITOR_CONFIG_DIR
+  delete process.env.SESSION_USAGE_ENDPOINT
+  // 指向不存在的配置目录 → config 分支静默回退默认值，测试不依赖真实 HOME
+  process.env.MONITOR_CONFIG_DIR = join(tmpdir(), `sur-resolve-${randomUUID()}`)
+  const logs: Array<{ body?: { level?: string; service?: string; message?: string } }> = []
+  try {
+    const fakeCtx = {
+      client: {
+        app: {
+          log: (args: { body?: { level?: string; service?: string; message?: string } }) => {
+            logs.push(args)
+            return Promise.resolve()
+          },
+        },
+        session: makeClient({}).session,
+      },
+      directory: "/tmp/fake-project",
+    } as unknown as Parameters<typeof SessionUsageReporter>[0]
+    const hooks = (await SessionUsageReporter(fakeCtx)) as Record<string, unknown>
+    assert(typeof hooks.event === "function", "不再惰性：应返回 event hook")
+    assert(typeof hooks.dispose === "function", "不再惰性：应返回 dispose hook")
+    const initLog = logs.map((l) => l.body?.message ?? "").find((m) => m.includes("端点"))
+    assert(
+      !!initLog &&
+        initLog.includes("http://127.0.0.1:8787/v1/session-usage/report") &&
+        initLog.includes("default"),
+      `初始化日志应包含端点与来源，实际: ${initLog}`,
+    )
+  } finally {
+    if (savedEndpoint === undefined) delete process.env.SESSION_USAGE_ENDPOINT
+    else process.env.SESSION_USAGE_ENDPOINT = savedEndpoint
+    if (savedConfigDir === undefined) delete process.env.MONITOR_CONFIG_DIR
+    else process.env.MONITOR_CONFIG_DIR = savedConfigDir
+  }
+})
+
 // ---------------------------------------------------------------------------
 // 汇总
 // ---------------------------------------------------------------------------

package/contrib/opencode-session-reporter/session-usage-reporter.ts

@@ -7,7 +7,8 @@
  * - 父会话快照绝不并入子会话用量；每个会话（含子代理会话）都是独立记录。
  * - token 口径原样分列上报（input / output / reasoning / cache.read / cache.write），
  *   不在客户端做任何相加或换算（`output` 不含 reasoning，`input` 不含 cache.read）。
- * - hook 只触发后台采集并入队，绝不等待网络；由后台 flush 统一 POST 到 SESSION_USAGE_ENDPOINT。
+ * - hook 只触发后台采集并入队，绝不等待网络；由后台 flush 统一 POST 到解析出的上报端点
+ *   （零配置解析：环境变量 SESSION_USAGE_ENDPOINT > <configDir>/config.json 的 reportEndpoint > 内置默认值）。
  * - 有界内存队列（默认 500 条快照，溢出丢最旧）+ 指数退避（带抖动）+ AbortSignal.timeout 超时。
  * - `dispose` 钩子在进程退出时以约 3 秒预算尽力刷新队列，超时即放弃，绝不阻塞退出。
  * - 载荷不含任何消费者身份字段；身份完全由网关（key-auth 注入 X-Forward-Consumer）决定。
@@ -26,11 +27,13 @@
  *   绝不能抛错、返回 null 或 undefined（否则 `V.event?.` 会读到空值导致崩溃）。
  *
  * 安装：复制本文件到 ~/.config/opencode/plugins/（全局）或 <项目>/.opencode/plugins/（项目级）。
- * 启用：设置环境变量 SESSION_USAGE_ENDPOINT（未设置时插件保持惰性）。
+ * 启用：零配置即生效（插件始终激活），初始化时会通过 app.log 输出最终端点与来源；
+ *       如需覆盖端点，可设置环境变量 SESSION_USAGE_ENDPOINT 或用配套 CLI 写 config.json 的 reportEndpoint。
  */
 
 import type { Plugin } from "@opencode-ai/plugin"
 import { randomUUID } from "node:crypto"
+import { readFileSync } from "node:fs"
 import { mkdir, readFile, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
 import { dirname, join } from "node:path"
@@ -40,7 +43,7 @@ import { dirname, join } from "node:path"
 // ---------------------------------------------------------------------------
 
 const SCHEMA_VERSION = 1
-const PLUGIN_VERSION = "0.1.0"
+const PLUGIN_VERSION = "0.1.2"
 /** 队列容量：最多积压 500 条会话快照，溢出丢最旧 */
 const QUEUE_CAP = 500
 /** 单次上报请求超时（AbortSignal.timeout） */
@@ -59,6 +62,20 @@ const INSTALL_ID_STATE_FILE = () => join(homedir(), ".local", "state", "opencode
 
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
+/** 零配置默认上报端点（与本地 `web start` 的默认端口一致） */
+const DEFAULT_REPORT_ENDPOINT = "http://127.0.0.1:8787/v1/session-usage/report"
+
+/**
+ * 本工具配置目录：必须与 src/paths.js 的 configDir() 完全一致。
+ * 本文件保持独立可复制，故此处自带一份等价实现（不 import src/）。
+ */
+const configFilePath = (): string =>
+  join(
+    process.env.MONITOR_CONFIG_DIR ||
+      join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode-stats-reporter"),
+    "config.json",
+  )
+
 // ---------------------------------------------------------------------------
 // 类型（type-only 导出在运行时会被擦除，不影响 loader 的「导出必须全是函数」校验）
 // ---------------------------------------------------------------------------
@@ -113,6 +130,13 @@ export type ReportPayload = {
   sessions: SessionSnapshot[]
 }
 
+export type ReportEndpointSource = "env" | "config" | "default"
+
+export type ResolvedReportEndpoint = {
+  endpoint: string
+  source: ReportEndpointSource
+}
+
 /** 本插件实际用到的 opencode SDK client 最小形状（便于 mock 测试） */
 export type ReporterClient = {
   session: {
@@ -340,6 +364,51 @@ const loadOrCreateInstallIdImpl = async (
   return id
 }
 
+// ---------------------------------------------------------------------------
+// 零配置端点解析：env > config.json(reportEndpoint) > 内置默认值；绝不抛错
+// ---------------------------------------------------------------------------
+
+const isValidHttpUrl = (value: string): boolean => {
+  try {
+    const parsed = new URL(value)
+    return parsed.protocol === "http:" || parsed.protocol === "https:"
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 解析上报端点（优先级从高到低）：
+ *   1. 环境变量 SESSION_USAGE_ENDPOINT（trim 后非空即用，显式覆盖）
+ *   2. 本工具配置文件 <configDir>/config.json 的 reportEndpoint 字段（须为合法 http(s) URL）
+ *   3. 内置默认值 http://127.0.0.1:8787/v1/session-usage/report
+ * config.json 不存在 / JSON 非法 / 字段缺失 / URL 非法 → 一律静默回退到下一优先级。
+ * 依赖全部可注入（env / configFile / readFileSyncFn），便于单测且不碰真实环境。
+ */
+const resolveReportEndpointImpl = (
+  options: {
+    env?: Record<string, string | undefined>
+    configFile?: string
+    readFileSyncFn?: (file: string, encoding: "utf8") => string
+  } = {},
+): ResolvedReportEndpoint => {
+  const env = options.env ?? process.env
+  const fromEnv = (env.SESSION_USAGE_ENDPOINT ?? "").trim()
+  if (fromEnv) return { endpoint: fromEnv, source: "env" }
+
+  const configFile = options.configFile ?? configFilePath()
+  const readFileSyncFn = options.readFileSyncFn ?? ((file: string) => readFileSync(file, "utf8"))
+  try {
+    const parsed = JSON.parse(readFileSyncFn(configFile, "utf8")) as { reportEndpoint?: unknown } | null
+    const candidate = typeof parsed?.reportEndpoint === "string" ? parsed.reportEndpoint.trim() : ""
+    if (candidate && isValidHttpUrl(candidate)) return { endpoint: candidate, source: "config" }
+  } catch {
+    // 文件不存在 / 不可读 / JSON 非法：静默回退到默认值
+  }
+
+  return { endpoint: DEFAULT_REPORT_ENDPOINT, source: "default" }
+}
+
 // ---------------------------------------------------------------------------
 // 核心：采集 + 非阻塞队列 + 退避重试 + dispose 限时刷新
 // ---------------------------------------------------------------------------
@@ -365,6 +434,7 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
   let flushCancel: (() => void) | null = null
   let retryCancel: (() => void) | null = null
   let retryAttempt = 0
+  let failureLogged = false
   const inFlight = new Set<string>()
 
   const send = async (snapshots: readonly SessionSnapshot[], timeoutMs: number): Promise<void> => {
@@ -392,13 +462,18 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     try {
       await send(batch, requestTimeoutMs)
       retryAttempt = 0
+      failureLogged = false // 成功即重置：下一轮失败重新记录首次
       return true
     } catch (error) {
       queue.restore(batch)
       retryAttempt += 1
       // 第 1 次失败 → 基础 1s，此后指数翻倍（2s、4s…），封顶 5 分钟，均带抖动
       const delay = computeBackoffMsImpl(Math.max(0, retryAttempt - 1), random())
-      log(`session-usage: 上报失败，${delay}ms 后重试（队列积压 ${queue.size}）`, error)
+      // 降噪：连续失败只记录首轮，避免服务端未运行时刷屏
+      if (!failureLogged) {
+        failureLogged = true
+        log(`session-usage: 上报失败，${delay}ms 后重试（队列积压 ${queue.size}）`, error)
+      }
       if (!retryCancel) {
         retryCancel = scheduler(() => {
           retryCancel = null
@@ -544,17 +619,15 @@ export const buildPayload = pluginSafe(buildPayloadImpl)
 export const createQueue = pluginSafe(createQueueImpl)
 export const computeBackoffMs = pluginSafe(computeBackoffMsImpl)
 export const loadOrCreateInstallId = pluginSafe(loadOrCreateInstallIdImpl)
+export const resolveReportEndpoint = pluginSafe(resolveReportEndpointImpl)
 export const createReporterCore = pluginSafe(createReporterCoreImpl)
 
 /**
- * 插件入口。
- * 未设置 SESSION_USAGE_ENDPOINT 时返回空 hooks，完全不影响会话。
+ * 插件入口：零配置，始终激活。
+ * 端点按 env > config.json > 默认值 解析；初始化成功后通过 app.log 输出端点与来源，便于排查。
  */
 export const SessionUsageReporter: Plugin = async (ctx) => {
   try {
-    const endpoint = (process.env.SESSION_USAGE_ENDPOINT ?? "").trim() || undefined
-    if (!endpoint) return {}
-
     const log = (message: string, error?: unknown): void => {
       try {
         const detail = error instanceof Error ? `${error.name}: ${error.message}` : error === undefined ? "" : String(error)
@@ -573,17 +646,21 @@ export const SessionUsageReporter: Plugin = async (ctx) => {
       }
     }
 
+    const resolved = resolveReportEndpointImpl()
     const installId = await loadOrCreateInstallIdImpl()
     const core = createReporterCoreImpl({
       client: ctx.client as unknown as ReporterClient,
       directory: ctx.directory,
-      endpoint,
+      endpoint: resolved.endpoint,
       installId,
       // 上报请求的网关 Key（APIG key-auth 后注入 X-Forward-Consumer）；未配置则不带鉴权头
       authToken: (process.env.SESSION_USAGE_API_KEY ?? "").trim() || undefined,
       log,
     })
 
+    // 可观测性：明确告知最终端点与来源（排查「装了插件却没上报」的关键线索）
+    log(`session-usage: 已启用会话用量上报，端点 ${resolved.endpoint}（来源: ${resolved.source}）`)
+
     return {
       event: async (input: { event?: { type?: unknown; properties?: unknown } }) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dijkspicy/opencode-stats-reporter",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "本地一体化 MaaS 用量看板：托管静态面板、反代用量接口、本地存储会话用量",
   "type": "module",
   "main": "./contrib/opencode-session-reporter/plugin-server.ts",
@@ -26,5 +26,9 @@
   "scripts": {
     "test": "node --test test/*.test.js"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "license": "Apache-2.0"
 }

package/src/cli.js

@@ -2,6 +2,7 @@ import fs from "node:fs"
 import path from "node:path"
 import { spawn } from "node:child_process"
 import { readConfig, setConfig, maskKey } from "./config.js"
+import { resolveGateway } from "./opencode-config.js"
 import { dbFile, panelDir, pluginSource, opencodePluginsDir, PKG_ROOT } from "./paths.js"
 import { Store } from "./store.js"
 import { createServer } from "./server.js"
@@ -41,11 +42,12 @@ function parseFlags(argv) {
 const HELP = `opencode-stats-reporter — 本地一体化 MaaS 用量看板
 
 用法:
-  opencode-stats-reporter config set --gateway <url> --key <key>   配置上游网关与 Key
+  opencode-stats-reporter config set --gateway <url> --key <key> [--endpoint <url>]
+                                                              配置上游网关、Key 与插件上报端点
   opencode-stats-reporter config get                              查看配置（Key 脱敏）
   opencode-stats-reporter web start [--port 8787] [--host 127.0.0.1] [--open]
-                                                              启动本地服务并托管面板
-  opencode-stats-reporter plugin install [--port 8787]            安装 opencode 上报插件
+                                                              启动本地服务并托管面板（自动写入插件上报端点 reportEndpoint）
+  opencode-stats-reporter plugin install [--port 8787]            安装 opencode 上报插件（零配置，默认上报本机服务）
 
 选项:
   -h, --help       显示帮助
@@ -56,15 +58,23 @@ function cmdConfig(argv) {
   const sub = argv[0]
   const flags = parseFlags(argv.slice(1))
   if (sub === "set") {
-    const cfg = setConfig({ gateway: flags.gateway, key: flags.key })
+    const cfg = setConfig({ gateway: flags.gateway, key: flags.key, endpoint: flags.endpoint })
     console.log("已写入配置: " + (cfg.gatewayBaseUrl || "(未设置)"))
     console.log("API Key: " + maskKey(cfg.apiKey))
+    console.log("reportEndpoint: " + (cfg.reportEndpoint || "(未设置)"))
     return
   }
   if (sub === "get") {
     const cfg = readConfig()
-    console.log("gatewayBaseUrl: " + (cfg.gatewayBaseUrl || "(未设置)"))
-    console.log("apiKey: " + maskKey(cfg.apiKey))
+    console.log("显式配置 gatewayBaseUrl: " + (cfg.gatewayBaseUrl || "(未设置)"))
+    console.log("显式配置 apiKey: " + maskKey(cfg.apiKey))
+    console.log("显式配置 reportEndpoint: " + (cfg.reportEndpoint || "(未设置)"))
+    const r = resolveGateway({ fileConfig: cfg })
+    if (r.ok) {
+      console.log("生效网关: " + r.config.gatewayBaseUrl + "（来源: " + r.source + (r.providerId ? "，provider=" + r.providerId : "") + "）")
+    } else {
+      console.log("生效网关: (未能解析，请先 `config set` 或确保 opencode 配置含 provider baseURL/apiKey)")
+    }
     return
   }
   throw new Error("用法: opencode-stats-reporter config set|get")
@@ -74,10 +84,17 @@ async function cmdWeb(argv) {
   const sub = argv[0]
   if (sub !== "start") throw new Error("用法: opencode-stats-reporter web start")
   const flags = parseFlags(argv.slice(1))
-  const cfg = readConfig()
-  if (!cfg.gatewayBaseUrl || !cfg.apiKey) {
-    throw new Error("尚未配置上游网关，请先运行: opencode-stats-reporter config set --gateway <url> --key <key>")
+  // 上游配置：显式 config.json > 环境变量 > 从 opencode 配置推导（无需手填）
+  const resolved = resolveGateway({ fileConfig: readConfig() })
+  if (!resolved.ok) {
+    throw new Error(
+      "未能确定上游网关。请任选其一：\n" +
+      "  a) 直接使用 opencode 配置（确保 opencode 里某个 provider 有 baseURL 与 apiKey）\n" +
+      "  b) 显式配置: opencode-stats-reporter config set --gateway <url> --key <key>\n" +
+      "  c) 环境变量: OPENCODE_STATS_GATEWAY / OPENCODE_STATS_API_KEY",
+    )
   }
+  const cfg = resolved.config
   const port = Number(flags.port || DEFAULT_PORT)
   const host = String(flags.host || DEFAULT_HOST)
   const mode = String(flags.mode || process.env.SESSION_USAGE_MODE || "local")
@@ -93,10 +110,25 @@ async function cmdWeb(argv) {
     server.listen(port, host, resolve)
   })
 
-  const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`
+  const address = server.address()
+  const actualPort = address && typeof address === "object" ? address.port : port
+  const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${actualPort}`
   console.log("本地看板已启动: " + url)
-  console.log("上游网关: " + cfg.gatewayBaseUrl)
+  console.log("上游网关: " + cfg.gatewayBaseUrl + "（来源: " + resolved.source +
+    (resolved.providerId ? "，provider=" + resolved.providerId : "") + "）")
   console.log("数据文件: " + dbFile())
+
+  // 零配置上报：把插件上报端点写入 config.json（插件解析顺序 env > reportEndpoint > 默认值）。
+  // 即使 --host 0.0.0.0 也写 127.0.0.1（插件默认同机）；写入失败只告警，不影响服务启动。
+  const reportEndpoint = `http://127.0.0.1:${actualPort}/v1/session-usage/report`
+  try {
+    setConfig({ endpoint: reportEndpoint })
+    console.log("插件上报端点: " + reportEndpoint + "（已写入 config.json，插件零配置自动上报）")
+  } catch (error) {
+    console.warn("警告: 未能写入插件上报端点 reportEndpoint（不影响服务运行）: " +
+      (error && error.message ? error.message : String(error)))
+  }
+
   if (!loopback) console.warn("警告: 正在监听非回环地址 " + host + "，本机网络内可访问，请自行确认风险")
   if (flags.open) openBrowser(url)
 
@@ -106,6 +138,7 @@ async function cmdWeb(argv) {
     server.close(() => process.exit(0))
     setTimeout(() => process.exit(0), 1000).unref()
   })
+  return server
 }
 
 function cmdPlugin(argv) {
@@ -130,7 +163,8 @@ function cmdPlugin(argv) {
   console.log("推荐用 npm 方式安装（可随 npm 更新、支持 -f 覆盖）:")
   console.log("  opencode plugin @dijkspicy/opencode-stats-reporter -g")
   console.log("")
-  console.log("以上为离线/本地文件安装方式。之后在 opencode 进程环境中设置:")
+  console.log("以上为离线/本地文件安装方式。插件零配置：默认上报本机服务（web start 会把实际端点自动写入 config.json）。")
+  console.log("如需显式覆盖端点，可在 opencode 进程环境中设置:")
   console.log("  SESSION_USAGE_ENDPOINT=http://127.0.0.1:" + port + "/v1/session-usage/report")
   console.log("（本地模式无需 SESSION_USAGE_API_KEY；请勿使用 --pure 启动 opencode）")
 }

package/src/config.js

@@ -34,7 +34,7 @@ function validUrl(url) {
   }
 }
 
-export function setConfig({ gateway, key }) {
+export function setConfig({ gateway, key, endpoint }) {
   const cfg = readConfig()
   if (gateway !== undefined) {
     const g = String(gateway).trim().replace(/\/+$/, "")
@@ -46,6 +46,11 @@ export function setConfig({ gateway, key }) {
     if (!k) throw new Error("key 不能为空")
     cfg.apiKey = k
   }
+  if (endpoint !== undefined) {
+    const e = String(endpoint).trim()
+    if (!validUrl(e)) throw new Error("endpoint 必须是合法的 http(s) URL")
+    cfg.reportEndpoint = e
+  }
   return writeConfig(cfg)
 }
 

package/src/opencode-config.js

@@ -0,0 +1,175 @@
+/**
+ * 从 opencode 自身配置推导上游网关与凭据，免去重复配置。
+ *
+ * 来源与优先级（后者仅在前者缺失时生效）：
+ *   1. 本工具显式配置（`config set` 写入的 config.json）
+ *   2. 环境变量覆盖：OPENCODE_STATS_GATEWAY / OPENCODE_STATS_API_KEY
+ *   3. opencode 配置：provider.<default>.options.baseURL + options.apiKey
+ *   4. opencode 凭据：<data>/opencode/auth.json 的 <provider>.key
+ *
+ * 注意：opencode 的 baseURL 指向 OpenAI 兼容根（形如 `https://host/v1`），
+ * 而本服务的面板按 `/v1/usage/*` 取路径，故推导网关根时需去掉末尾的 `/v1`。
+ */
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+/** 字符串感知的 JSONC 去注释 + 去尾逗号，避免误伤 `https://` 里的 `//` */
+export function stripJsonc(text) {
+  let out = ""
+  let inStr = false
+  let quote = ""
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    const next = text[i + 1]
+    if (inStr) {
+      out += c
+      if (c === "\\") {
+        out += next ?? ""
+        i++
+      } else if (c === quote) {
+        inStr = false
+      }
+      continue
+    }
+    if (c === '"' || c === "'") {
+      inStr = true
+      quote = c
+      out += c
+      continue
+    }
+    if (c === "/" && next === "/") {
+      while (i < text.length && text[i] !== "\n") i++
+      out += "\n"
+      continue
+    }
+    if (c === "/" && next === "*") {
+      i += 2
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
+      i++
+      continue
+    }
+    out += c
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1")
+}
+
+export function parseJsonc(text) {
+  return JSON.parse(stripJsonc(text))
+}
+
+function opencodeConfigDir() {
+  return process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), ".config", "opencode")
+}
+
+function opencodeDataDir() {
+  const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+  return path.join(base, "opencode")
+}
+
+function readConfigFiles() {
+  const explicit = process.env.OPENCODE_CONFIG
+  const candidates = explicit
+    ? [explicit]
+    : ["config.json", "opencode.json", "opencode.jsonc"].map((f) => path.join(opencodeConfigDir(), f))
+  const merged = {}
+  const readFrom = []
+  for (const f of candidates) {
+    try {
+      const obj = parseJsonc(fs.readFileSync(f, "utf8"))
+      if (obj && typeof obj === "object") {
+        Object.assign(merged, obj)
+        readFrom.push(f)
+      }
+    } catch {
+      /* 文件不存在或不可解析时跳过 */
+    }
+  }
+  return { config: merged, readFrom }
+}
+
+function readAuth() {
+  try {
+    const p = path.join(opencodeDataDir(), "auth.json")
+    const obj = JSON.parse(fs.readFileSync(p, "utf8"))
+    return obj && typeof obj === "object" ? obj : {}
+  } catch {
+    return {}
+  }
+}
+
+/** opencode baseURL → 本服务网关根（去掉末尾 /v1，因为面板路径自带 /v1 前缀） */
+export function gatewayRootFromBaseUrl(baseUrl) {
+  const trimmed = String(baseUrl).trim().replace(/\/+$/, "")
+  return trimmed.replace(/\/v1$/i, "")
+}
+
+function pickProvider(cfg) {
+  const providers = cfg.provider && typeof cfg.provider === "object" ? cfg.provider : {}
+  const ids = Object.keys(providers)
+  const modelId = typeof cfg.model === "string" && cfg.model.includes("/") ? cfg.model.split("/")[0] : null
+  if (modelId && providers[modelId]) return { id: modelId, provider: providers[modelId] }
+  const withBase = ids.filter((id) => providers[id] && providers[id].options && providers[id].options.baseURL)
+  if (withBase.length === 1) return { id: withBase[0], provider: providers[withBase[0]] }
+  return null
+}
+
+/**
+ * 解析出本服务所需的上游配置。
+ * @returns {{gatewayBaseUrl:string, apiKey:string, source:string, providerId?:string, model?:string}|null}
+ */
+export function discoverGatewayFromOpencode() {
+  const { config, readFrom } = readConfigFiles()
+  const picked = pickProvider(config)
+  if (!picked) return null
+  const opts = picked.provider.options || {}
+  if (!opts.baseURL) return null
+  const auth = readAuth()
+  const apiKey = (typeof opts.apiKey === "string" && opts.apiKey.trim()) || auth[picked.id]?.key || ""
+  if (!apiKey) return null
+  return {
+    gatewayBaseUrl: gatewayRootFromBaseUrl(opts.baseURL),
+    apiKey: String(apiKey),
+    source: "opencode 配置" + (readFrom.length ? ` (${readFrom.map((f) => path.basename(f)).join(", ")})` : ""),
+    providerId: picked.id,
+    model: typeof config.model === "string" ? config.model : undefined,
+  }
+}
+
+/**
+ * 生效配置（按来源整体选取，避免把 A 的网关和 B 的 Key 拼一起）：
+ *   1. 本工具显式配置（需成对齐全）
+ *   2. 环境变量（需成对齐全）
+ *   3. opencode 配置推导
+ * 选定来源后，允许环境变量做单项覆盖。
+ */
+export function resolveGateway({ fileConfig = {}, env = process.env } = {}) {
+  const discovered = discoverGatewayFromOpencode()
+  let config = null
+  let source = null
+
+  if (fileConfig.gatewayBaseUrl && fileConfig.apiKey) {
+    config = { gatewayBaseUrl: fileConfig.gatewayBaseUrl, apiKey: fileConfig.apiKey }
+    source = "本工具配置 (config.json)"
+  } else if (env.OPENCODE_STATS_GATEWAY && env.OPENCODE_STATS_API_KEY) {
+    config = { gatewayBaseUrl: env.OPENCODE_STATS_GATEWAY, apiKey: env.OPENCODE_STATS_API_KEY }
+    source = "环境变量"
+  } else if (discovered) {
+    config = { gatewayBaseUrl: discovered.gatewayBaseUrl, apiKey: discovered.apiKey }
+    source = discovered.source
+  }
+
+  if (!config) return { ok: false, source: null, discovered }
+
+  if (env.OPENCODE_STATS_GATEWAY) config.gatewayBaseUrl = env.OPENCODE_STATS_GATEWAY
+  if (env.OPENCODE_STATS_API_KEY) config.apiKey = env.OPENCODE_STATS_API_KEY
+
+  return {
+    ok: true,
+    config,
+    source,
+    providerId: discovered?.providerId,
+    model: discovered?.model,
+    discovered,
+  }
+}