@dijkspicy/opencode-stats-reporter 0.1.1 → 0.1.3

package/README.md

@@ -23,7 +23,7 @@ npm i -g @dijkspicy/opencode-stats-reporter
 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>`，或环境变量 `OPENCODE_STATS_GATEWAY` / `OPENCODE_STATS_API_KEY`（优先级：本工具配置 > 环境变量 > opencode 推导）；
+- **无需单独填网关和 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 也不会进入浏览器**；
@@ -31,7 +31,7 @@ opencode-stats-reporter web start          # 打开 http://127.0.0.1:8787
   ```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.3" },
   "sessions": [
     {
       "session_id": "ses_...",
@@ -66,13 +79,15 @@ cp session-usage-reporter.ts .opencode/plugins/
       "tokens_cache_write": 1320,
       "message_count": 12,
       "session_created_at": 1759000000000,
+      "session_title": "每30s自动刷新功能",
+      "session_directory": "/opt/projects/BlueRegionUsage",
       "last_activity_at": 1759003600123
     }
   ]
 }
 ```
 
-`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。载荷中**不存在** consumer/identity 类字段。
+`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。`session_title` / `session_directory` 取自**同一次** `session.get` 调用（不新增 API 请求），取不到时为 `null`（不是空字符串）。载荷中**不存在** consumer/identity 类字段。
 
 ## 测试
 
@@ -80,13 +95,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.3",
   "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,
@@ -75,12 +77,25 @@ const assistantMessage = (over: Partial<NonNullable<UsageMessage["info"]>> = {})
 const makeClient = (
   messages: Record<string, UsageMessage[]>,
   children: Record<string, string[]> = {},
+  /** session.get 的返回元数据；不传则 client 不含 session.get */
+  meta?: { created?: number | null; title?: string | null; directory?: string | null; throws?: boolean },
 ): ReporterClient => ({
   session: {
     messages: async (args: { path: { id: string } }) => ({ data: messages[args.path.id] ?? [] }),
     children: async (args: { path: { id: string } }) => ({
       data: (children[args.path.id] ?? []).map((id) => ({ id })),
     }),
+    ...(meta
+      ? {
+          get: meta.throws
+            ? async () => {
+                throw new Error("boom: session.get failed")
+              }
+            : async () => ({
+                data: { time: { created: meta.created ?? 1_700_000_000_000 }, title: meta.title ?? null, directory: meta.directory ?? null },
+              }),
+        }
+      : {}),
   },
 })
 
@@ -120,6 +135,8 @@ const snap = (sessionID: string, over: Partial<SessionSnapshot> = {}): SessionSn
     tokens_cache_write: 0,
     message_count: 1,
     session_created_at: null,
+    session_title: null,
+    session_directory: null,
     last_activity_at: 1_000 + snapSeq,
     ...over,
   }
@@ -134,7 +151,9 @@ const SESSION_KEYS = [
   "model",
   "revision",
   "session_created_at",
+  "session_directory",
   "session_id",
+  "session_title",
   "tokens_cache_read",
   "tokens_cache_write",
   "tokens_input",
@@ -364,6 +383,177 @@ 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
+  }
+})
+
+await runTest("session.get 返回 title/directory → 快照与载荷带上，且复用同一次调用", async () => {
+  const client = makeClient(
+    { ses_meta: [assistantMessage()] },
+    {},
+    { created: 1_759_000_000_000, title: "每30s自动刷新功能", directory: "/opt/projects/BlueRegionUsage" },
+  )
+  let getCalls = 0
+  const origGet = client.session.get!
+  client.session.get = (async (args: { path: { id: string } }) => {
+    getCalls += 1
+    return origGet(args)
+  }) as typeof client.session.get
+
+  const { fetchFn, calls } = makeFetch("ok")
+  const { core } = makeCore(client, { endpoint: "http://e", fetchFn })
+  await core.collectSession("ses_meta")
+
+  const snapshot = core.queue.drainAll().find((s) => s.session_id === "ses_meta")
+  assert(!!snapshot, "应产出快照")
+  assertEqual(snapshot!.session_title, "每30s自动刷新功能", "快照 title")
+  assertEqual(snapshot!.session_directory, "/opt/projects/BlueRegionUsage", "快照 directory")
+  assertEqual(snapshot!.session_created_at, 1_759_000_000_000, "快照 created")
+  assertEqual(getCalls, 1, "单会话恰好一次 session.get（不新增 API 请求）")
+
+  // 载荷层面
+  const q = createQueue(50)
+  q.push(snapshot!)
+  const core2 = makeCore(makeClient({}), { endpoint: "http://e", queue: q, fetchFn }).core
+  await core2.flushOnce()
+  const body = JSON.parse(calls[0]!.init.body ?? "{}")
+  assertEqual(body.sessions[0].session_title, "每30s自动刷新功能", "载荷 title")
+  assertEqual(body.sessions[0].session_directory, "/opt/projects/BlueRegionUsage", "载荷 directory")
+})
+
+await runTest("session.get 抛错 → title/directory/created 为 null 而非崩溃", async () => {
+  const client = makeClient({ ses_err: [assistantMessage()] }, {}, { throws: true })
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_err")
+  const snapshot = core.queue.drainAll().find((s) => s.session_id === "ses_err")
+  assert(!!snapshot, "采集主流程不受影响，快照仍产生")
+  assertEqual(snapshot!.session_title, null, "title → null")
+  assertEqual(snapshot!.session_directory, null, "directory → null")
+  assertEqual(snapshot!.session_created_at, null, "created → null")
+})
+
+await runTest("session.get 不存在 → 三个元数据字段均为 null", async () => {
+  const client = makeClient({ ses_noget: [assistantMessage()] }) // 无 session.get
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_noget")
+  const snapshot = core.queue.drainAll().find((s) => s.session_id === "ses_noget")
+  assert(!!snapshot, "应产出快照")
+  assertEqual(snapshot!.session_title, null, "title → null")
+  assertEqual(snapshot!.session_directory, null, "directory → null")
+  assertEqual(snapshot!.session_created_at, null, "created → null")
+})
+
 // ---------------------------------------------------------------------------
 // 汇总
 // ---------------------------------------------------------------------------

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.3"
 /** 队列容量：最多积压 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 的「导出必须全是函数」校验）
 // ---------------------------------------------------------------------------
@@ -94,6 +111,8 @@ export type SessionSnapshot = {
   tokens_cache_write: number
   message_count: number
   session_created_at: number | null
+  session_title: string | null
+  session_directory: string | null
   last_activity_at: number | null
 }
 
@@ -113,6 +132,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: {
@@ -232,6 +258,8 @@ const aggregateSessionImpl = (sessionID: string, messages: readonly UsageMessage
     tokens_cache_write: cacheWrite,
     message_count: count,
     session_created_at: null, // 由采集层补充
+    session_title: null, // 由采集层补充（session.get）
+    session_directory: null, // 由采集层补充（session.get）
     last_activity_at: lastActivity,
   }
 }
@@ -340,6 +368,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 +438,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 +466,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
@@ -438,16 +517,29 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     return ids
   }
 
-  const readSessionCreatedAt = async (sessionID: string): Promise<number | null> => {
+  const readSessionMeta = async (
+    sessionID: string,
+  ): Promise<{ created: number | null; title: string | null; directory: string | null }> => {
     try {
       const getSession = options.client.session.get
-      if (typeof getSession !== "function") return null
+      if (typeof getSession !== "function") return { created: null, title: null, directory: null }
       const response = await getSession.call(options.client.session, { path: { id: sessionID }, query: query() })
-      const created = (response as { data?: { time?: { created?: unknown } } | undefined } | undefined)?.data?.time
-        ?.created
-      return typeof created === "number" ? created : null
+      const data = (
+        response as
+          | { data?: { time?: { created?: unknown }; title?: unknown; directory?: unknown } }
+          | undefined
+      )?.data
+      const created = data?.time?.created
+      const title = data?.title
+      const directory = data?.directory
+      return {
+        created: typeof created === "number" ? created : null,
+        title: typeof title === "string" && title ? title : null,
+        directory: typeof directory === "string" && directory ? directory : null,
+      }
     } catch {
-      return null
+      // session.get 抛错 / 形状异常：元数据缺省为 null，绝不影响采集主流程
+      return { created: null, title: null, directory: null }
     }
   }
 
@@ -462,7 +554,11 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     visited.add(sessionID)
     const snapshot = aggregateSessionImpl(sessionID, await readMessages(sessionID))
     if (snapshot) {
-      snapshot.session_created_at = await readSessionCreatedAt(sessionID)
+      // 复用同一次 session.get：created / title / directory 一并取得，不新增 API 请求
+      const meta = await readSessionMeta(sessionID)
+      snapshot.session_created_at = meta.created
+      snapshot.session_title = meta.title
+      snapshot.session_directory = meta.directory
       out.push(snapshot)
     }
     for (const childID of await readChildIDs(sessionID)) {
@@ -544,17 +640,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 +667,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.1",
+  "version": "0.1.3",
   "description": "本地一体化 MaaS 用量看板：托管静态面板、反代用量接口、本地存储会话用量",
   "type": "module",
   "main": "./contrib/opencode-session-reporter/plugin-server.ts",

package/panel/css/style.css

@@ -527,22 +527,63 @@ body {
 #session-table tbody tr:hover { background: rgba(127,127,127,.06); }
 #session-table tbody tr:last-child td { border-bottom: none; }
 
-/* 会话 ID：等宽截断，完整值在 title，点击进详情 */
-.sess-id-btn {
+/* 会话首列：两行结构（主行标题 / 次行目录+ID），次要信息弱化不喧宾夺主 */
+.sess-title-line { min-width: 0; }
+.sess-title {
   display: inline-block;
+  max-width: 340px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  vertical-align: bottom;
+  font-weight: 600;
+  cursor: pointer;
+}
+.sess-title:hover { color: var(--accent-hover); text-decoration: underline; }
+.sess-sub-line {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 2px;
+  font-size: 11px;
+  color: var(--text-secondary);
+}
+.sess-sub-sep { flex: none; }
+.sess-dir {
   max-width: 200px;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+  font-size: 11px;
+  cursor: default;
+}
+@media (max-width: 767px) {
+  .sess-title { max-width: 180px; }
+  .sess-dir { max-width: 120px; }
+}
+
+/* 会话 ID：默认弱化（有标题时），等宽头尾截断，完整值在 title，点击进详情 */
+.sess-id-btn {
+  display: inline-block;
+  max-width: 130px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
   vertical-align: bottom;
   padding: 0;
   border: none;
   background: transparent;
-  color: var(--accent);
+  color: var(--text-secondary);
   font-family: Consolas, monospace;
-  font-size: 12px;
+  font-size: 11px;
   cursor: pointer;
 }
+/* 无标题时的降级主标识：恢复高亮，保证一眼可点 */
+.sess-id-btn.is-primary {
+  max-width: 200px;
+  color: var(--accent);
+  font-size: 12px;
+}
 .sess-id-btn:hover { color: var(--accent-hover); text-decoration: underline; }
 .sess-id-btn:focus-visible { outline: 1px solid var(--accent); }
 

package/panel/index.html

@@ -296,7 +296,7 @@
           <table id="session-table" class="session-table">
             <thead>
               <tr>
-                <th>会话</th>
+                <th title="优先显示会话标题，无标题时显示会话 ID；下方小字为会话所属项目目录，悬浮可看完整路径">会话</th>
                 <th>模型</th>
                 <th>代理</th>
                 <th class="num" title="输入总量 = 输入 + 缓存读 + 缓存写">输入总量</th>

package/panel/js/format.js

@@ -106,6 +106,15 @@
       ' ' + p(d.getHours()) + ':' + p(d.getMinutes()) + ':' + p(d.getSeconds());
   }
 
+  /** 毫秒时间戳 -> 'MM-DD HH:MM'（当年，会话列表"最后活动"列）；跨年回退完整格式，完整值另放 title */
+  function shortDateTime(ms) {
+    if (ms === null || ms === undefined || !isFinite(Number(ms))) return '--';
+    var d = new Date(Number(ms));
+    if (d.getFullYear() !== new Date().getFullYear()) return dateTime(ms);
+    function p(x) { return (x < 10 ? '0' : '') + x; }
+    return p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes());
+  }
+
   /**
    * 环比变化（比值）：当前值与上一周期值比较，返回 { text, dir }
    * dir: 1 升 / -1 降 / 0 持平；基准为 0 或空值时返回 null（不展示）
@@ -149,6 +158,7 @@
     todayStr: todayStr,
     hourLabel: hourLabel,
     dateTime: dateTime,
+    shortDateTime: shortDateTime,
     pctChange: pctChange,
     ppChange: ppChange,
     maskKey: maskKey

package/panel/js/sessions.js

@@ -196,18 +196,84 @@
     st.rows.forEach(function (r) { tbody.appendChild(sessionRow(r)); });
   }
 
+  /** 空值守卫：非字符串或空白串返回 null，避免把 null/undefined/空串渲染到页面 */
+  function nonEmpty(v) {
+    return (typeof v === 'string' && v.trim()) ? v.trim() : null;
+  }
+
+  /** 会话 ID 头尾截断：ses_k2X9fjQ3mT…89xQ，头尾是最有辨识度的部分；完整值在 title 与详情 */
+  function shortId(id) {
+    return id.length > 20 ? id.slice(0, 14) + '…' + id.slice(-4) : id;
+  }
+
+  /** 目录压缩：取末两级，如 /opt/projects/BlueRegionUsage -> …/projects/BlueRegionUsage；完整路径放 title */
+  function shortDir(dir) {
+    var parts = String(dir).replace(/\\/g, '/').split('/').filter(function (s) { return s !== ''; });
+    if (!parts.length) return dir;
+    if (parts.length <= 2) return '/' + parts.join('/');
+    return '…/' + parts.slice(-2).join('/');
+  }
+
+  /** 会话 ID 按钮：等宽展示（头尾截断），完整值放 title，点击进详情；primary = 无标题时作为降级主标识 */
+  function idButton(sid, primary) {
+    var b = document.createElement('button');
+    b.type = 'button';
+    b.className = 'sess-id-btn mono' + (primary ? ' is-primary' : '');
+    b.textContent = shortId(sid);
+    b.title = sid + '\n点击查看详情';
+    b.addEventListener('click', function () { openDetail(sid); });
+    return b;
+  }
+
+  /**
+   * 首列「会话」：两行结构
+   *   主行：会话标题（加粗）；无标题时降级为会话 ID（等宽、高亮、可点）
+   *   次行：项目目录（末两级压缩，悬浮显全路径）· 会话 ID（弱化；ID 已作主标识时不重复）
+   */
   function sessionRow(r) {
     var tr = document.createElement('tr');
-    // 会话 ID：等宽截断展示，完整值放 title，点击查看详情
-    var sidTd = document.createElement('td');
-    var sidBtn = document.createElement('button');
-    sidBtn.type = 'button';
-    sidBtn.className = 'sess-id-btn mono';
-    sidBtn.textContent = r.session_id || '--';
-    sidBtn.title = (r.session_id || '') + '\n点击查看详情';
-    sidBtn.addEventListener('click', function () { openDetail(r.session_id); });
-    sidTd.appendChild(sidBtn);
-    tr.appendChild(sidTd);
+    var title = nonEmpty(r.session_title);
+    var dir = nonEmpty(r.session_directory);
+    var sid = nonEmpty(r.session_id) || '--';
+
+    var cell = document.createElement('td');
+    cell.className = 'sess-cell';
+
+    var line1 = document.createElement('div');
+    line1.className = 'sess-title-line';
+    if (title) {
+      var t = document.createElement('span');
+      t.className = 'sess-title';
+      t.textContent = title;
+      t.title = title + '\n点击查看详情';
+      t.addEventListener('click', function () { openDetail(sid); });
+      line1.appendChild(t);
+    } else {
+      line1.appendChild(idButton(sid, true));
+    }
+    cell.appendChild(line1);
+
+    var line2 = document.createElement('div');
+    line2.className = 'sess-sub-line';
+    if (dir) {
+      var d = document.createElement('span');
+      d.className = 'sess-dir mono';
+      d.textContent = shortDir(dir);
+      d.title = '目录：' + dir;
+      line2.appendChild(d);
+    }
+    if (title) {
+      if (dir) {
+        var sep = document.createElement('span');
+        sep.className = 'sess-sub-sep';
+        sep.textContent = '·';
+        line2.appendChild(sep);
+      }
+      line2.appendChild(idButton(sid, false));
+    }
+    if (line2.childNodes.length) cell.appendChild(line2);
+
+    tr.appendChild(cell);
 
     tr.appendChild(td(r.model || '--'));
     tr.appendChild(td(r.agent || '--'));
@@ -217,7 +283,8 @@
     tr.appendChild(td(F.fullNumber(r.tokens_cache_read), 'num'));
     tr.appendChild(td(F.fullNumber(r.tokens_cache_write), 'num'));
     tr.appendChild(td(F.fullNumber(r.message_count), 'num'));
-    tr.appendChild(td(F.dateTime(r.last_activity_at)));
+    var lastFull = F.dateTime(r.last_activity_at);
+    tr.appendChild(td(F.shortDateTime(r.last_activity_at), null, lastFull === '--' ? '' : lastFull));
     return tr;
   }
 
@@ -312,6 +379,8 @@
     ]));
 
     body.appendChild(group('会话信息', [
+      item('会话标题', nonEmpty(d.session_title) || '--'),
+      item('项目目录', nonEmpty(d.session_directory) || '--', true),
       item('模型', d.model || '--'),
       item('代理', d.agent || '--'),
       item('安装标识', d.install_id || '--', true),

package/src/cli.js

@@ -42,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       显示帮助
@@ -57,15 +58,17 @@ 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("显式配置 reportEndpoint: " + (cfg.reportEndpoint || "(未设置)"))
     const r = resolveGateway({ fileConfig: cfg })
     if (r.ok) {
       console.log("生效网关: " + r.config.gatewayBaseUrl + "（来源: " + r.source + (r.providerId ? "，provider=" + r.providerId : "") + "）")
@@ -107,11 +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 + "（来源: " + 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)
 
@@ -121,6 +138,7 @@ async function cmdWeb(argv) {
     server.close(() => process.exit(0))
     setTimeout(() => process.exit(0), 1000).unref()
   })
+  return server
 }
 
 function cmdPlugin(argv) {
@@ -145,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/store.js

@@ -29,6 +29,8 @@ CREATE TABLE IF NOT EXISTS session_usage (
   client_reported_at    INTEGER,
   first_seen_at         INTEGER NOT NULL,
   last_reported_at      INTEGER NOT NULL,
+  session_title         TEXT,
+  session_directory     TEXT,
   PRIMARY KEY (consumer_id, install_id, session_id)
 );
 CREATE INDEX IF NOT EXISTS idx_su_consumer_activity ON session_usage(consumer_id, last_activity_at DESC);
@@ -89,6 +91,8 @@ export function sanitizeRecord(raw) {
     last_activity_at: int(raw.last_activity_at),
     client_reported_at: optInt(raw.client_reported_at),
     client_session_header: str(raw.client_session_header),
+    session_title: str(raw.session_title, 300),
+    session_directory: str(raw.session_directory, 512),
   }
 }
 
@@ -109,6 +113,23 @@ export class Store {
 
   migrate() {
     this.db.exec(SCHEMA)
+    this.ensureColumns()
+  }
+
+  /**
+   * 幂等迁移：为已存在的旧库补齐后增列。
+   * SCHEMA 只在表不存在时建表；旧库需用 PRAGMA table_info 检测缺列后 ALTER TABLE ADD COLUMN
+   * （可空 TEXT 列，不写默认值 → 旧行自动为 NULL，既有数据不受影响；重复调用安全）。
+   */
+  ensureColumns() {
+    const existing = new Set(
+      this.db.prepare("PRAGMA table_info(session_usage)").all().map((r) => r.name),
+    )
+    for (const [name, type] of [["session_title", "TEXT"], ["session_directory", "TEXT"]]) {
+      if (!existing.has(name)) {
+        this.db.exec(`ALTER TABLE session_usage ADD COLUMN ${name} ${type}`)
+      }
+    }
   }
 
   indexes() {
@@ -134,13 +155,13 @@ export class Store {
       (consumer_id, install_id, session_id, source, schema_version, reporter_version, client_session_header,
        model, agent, tokens_input, tokens_output, tokens_reasoning, tokens_cache_read, tokens_cache_write,
        cost, message_count, revision, session_created_at, last_activity_at, client_reported_at,
-       first_seen_at, last_reported_at)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+       first_seen_at, last_reported_at, session_title, session_directory)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
     const update = this.db.prepare(`UPDATE session_usage SET
       source=?, schema_version=?, reporter_version=?, client_session_header=?, model=?, agent=?,
       tokens_input=?, tokens_output=?, tokens_reasoning=?, tokens_cache_read=?, tokens_cache_write=?,
       cost=?, message_count=?, revision=?, session_created_at=?, last_activity_at=?, client_reported_at=?,
-      last_reported_at=?
+      last_reported_at=?, session_title=?, session_directory=?
       WHERE consumer_id=? AND install_id=? AND session_id=?`)
 
     for (const r of records) {
@@ -152,6 +173,7 @@ export class Store {
           consumerId, r.install_id, r.session_id, source, schemaVersion, reporterVersion, r.client_session_header,
           r.model, r.agent, r.tokens_input, r.tokens_output, r.tokens_reasoning, r.tokens_cache_read, r.tokens_cache_write,
           r.cost, r.message_count, r.revision, r.session_created_at, r.last_activity_at, r.client_reported_at, ts, ts,
+          r.session_title, r.session_directory,
         )
       } else if (r.revision > prev.revision || (r.revision === prev.revision && r.last_activity_at > prev.last_activity_at)) {
         status = "upserted"
@@ -159,6 +181,7 @@ export class Store {
           source, schemaVersion, reporterVersion, r.client_session_header, r.model, r.agent,
           r.tokens_input, r.tokens_output, r.tokens_reasoning, r.tokens_cache_read, r.tokens_cache_write,
           r.cost, r.message_count, r.revision, r.session_created_at, r.last_activity_at, r.client_reported_at, ts,
+          r.session_title, r.session_directory,
           consumerId, r.install_id, r.session_id,
         )
       } else if (r.revision === prev.revision && r.last_activity_at === prev.last_activity_at) {