@dijkspicy/opencode-stats-reporter 0.1.4 → 0.1.6

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

@@ -65,7 +65,7 @@ config.json 不存在、JSON 非法、字段缺失或 URL 非法时一律静默
 {
   "schema_version": 1,
   "install_id": "0b3f7e6a-....",
-  "reporter": { "client": "opencode", "version": "0.1.4" },
+  "reporter": { "client": "opencode", "version": "0.1.6" },
   "sessions": [
     {
       "session_id": "ses_...",
@@ -81,13 +81,15 @@ config.json 不存在、JSON 非法、字段缺失或 URL 非法时一律静默
       "session_created_at": 1759000000000,
       "session_title": "每30s自动刷新功能",
       "session_directory": "/opt/projects/BlueRegionUsage",
+      "parent_session_id": "ses_...",
+      "root_session_id": "ses_...",
       "last_activity_at": 1759003600123
     }
   ]
 }
 ```
 
-`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。`session_title` / `session_directory` 取自**同一次** `session.get` 调用（不新增 API 请求），取不到时为 `null`（不是空字符串）。载荷中**不存在** consumer/identity 类字段。
+`model` 取该会话最后一条已完成助手消息的 `providerID/modelID`；`agent` 取其 `mode`（无则为 `null`）。`session_title` / `session_directory` / `parent_session_id`（取自 `session.get` 的 `parentID`）复用**同一次** `session.get` 调用（不新增 API 请求），取不到时为 `null`（不是空字符串）。`root_session_id` 为沿 `parentID` 回溯到的顶层祖先（深度上限 20、防环；祖先已删除/报错时以最近一次验证成功的会话为根；自身即顶层时等于 `session_id`）。载荷中**不存在** consumer/identity 类字段。
 
 ## 测试
 

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

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

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

@@ -78,7 +78,7 @@ 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 },
+  meta?: { created?: number | null; title?: string | null; directory?: string | null; parentID?: string | null; throws?: boolean },
 ): ReporterClient => ({
   session: {
     messages: async (args: { path: { id: string } }) => ({ data: messages[args.path.id] ?? [] }),
@@ -92,7 +92,12 @@ const makeClient = (
                 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 },
+                data: {
+                  time: { created: meta.created ?? 1_700_000_000_000 },
+                  title: meta.title ?? null,
+                  directory: meta.directory ?? null,
+                  parentID: meta.parentID ?? null,
+                },
               }),
         }
       : {}),
@@ -137,6 +142,8 @@ const snap = (sessionID: string, over: Partial<SessionSnapshot> = {}): SessionSn
     session_created_at: null,
     session_title: null,
     session_directory: null,
+    parent_session_id: null,
+    root_session_id: null,
     last_activity_at: 1_000 + snapSeq,
     ...over,
   }
@@ -149,7 +156,9 @@ const SESSION_KEYS = [
   "last_activity_at",
   "message_count",
   "model",
+  "parent_session_id",
   "revision",
+  "root_session_id",
   "session_created_at",
   "session_directory",
   "session_id",
@@ -554,6 +563,181 @@ await runTest("session.get 不存在 → 三个元数据字段均为 null", asyn
   assertEqual(snapshot!.session_created_at, null, "created → null")
 })
 
+/** 辅助：用给定 client 采集，返回指定会话快照的 root_session_id */
+const collectAndRootOf = async (client: ReporterClient, trigger: string, want?: string): Promise<string | null> => {
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession(trigger)
+  const snap = core.queue.drainAll().find((s) => s.session_id === (want ?? trigger))
+  return snap ? snap.root_session_id : null
+}
+
+await runTest("session.get 返回 parentID → 快照/载荷带上 parent_session_id；顶层会话 root 等于自身", async () => {
+  // 顶层会话：无 parentID
+  const topClient = makeClient(
+    { ses_top: [assistantMessage()] },
+    {},
+    { parentID: null, title: "顶层任务", directory: "/opt/x" },
+  )
+  const { core } = makeCore(topClient, { endpoint: "http://e" })
+  await core.collectSession("ses_top")
+  const topSnap = core.queue.drainAll().find((s) => s.session_id === "ses_top")
+  assert(!!topSnap, "应产出快照")
+  assertEqual(topSnap!.parent_session_id, null, "顶层无父")
+  assertEqual(topSnap!.root_session_id, "ses_top", "自身即顶层 → root 等于 session_id")
+
+  // 带父会话的子会话 → 载荷验证
+  const childClient = makeClient({ ses_c: [assistantMessage()] }, { ses_p: ["ses_c"] }, { parentID: "ses_p" })
+  const { fetchFn, calls } = makeFetch("ok")
+  const q = createQueue(50)
+  const core2 = makeCore(childClient, { endpoint: "http://e", queue: q, fetchFn }).core
+  await core2.collectSession("ses_c")
+  const childSnap = q.drainAll().find((s) => s.session_id === "ses_c")
+  assert(!!childSnap, "子会话应产出快照")
+  assertEqual(childSnap!.parent_session_id, "ses_p", "快照 parent_session_id")
+  assertEqual(childSnap!.root_session_id, "ses_p", "root 解析为已验证的顶层")
+
+  q.push(childSnap!)
+  const core3 = makeCore(makeClient({}), { endpoint: "http://e", queue: q, fetchFn }).core
+  await core3.flushOnce()
+  const body = JSON.parse(calls[0]!.init.body ?? "{}")
+  assertEqual(body.sessions[0].parent_session_id, "ses_p", "载荷 parent_session_id")
+  assertEqual(body.sessions[0].root_session_id, "ses_p", "载荷 root_session_id")
+})
+
+await runTest("子会话触发采集时能上溯到根：root_session_id 等于顶层 id", async () => {
+  // 结构：ses_top（顶层） → ses_mid → ses_leaf
+  const client = makeClient(
+    { ses_top: [assistantMessage()], ses_mid: [assistantMessage()], ses_leaf: [assistantMessage()] },
+    { ses_top: ["ses_mid"], ses_mid: ["ses_leaf"] },
+  )
+  const getCalls: string[] = []
+  client.session.get = (async (args: { path: { id: string } }) => {
+    getCalls.push(args.path.id)
+    const parentID = args.path.id === "ses_top" ? null : args.path.id === "ses_mid" ? "ses_top" : "ses_mid"
+    return { data: { time: { created: 1 }, title: `t-${args.path.id}`, directory: "/d", parentID } }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_leaf") // 由最深层子会话触发
+
+  const drained = core.queue.drainAll()
+  const leaf = drained.find((s) => s.session_id === "ses_leaf")
+  const mid = drained.find((s) => s.session_id === "ses_mid")
+  const top = drained.find((s) => s.session_id === "ses_top")
+  assert(!!leaf && !!mid && !!top, "从根开始应连带采集整棵树")
+  assertEqual(leaf!.root_session_id, "ses_top", "leaf root")
+  assertEqual(leaf!.parent_session_id, "ses_mid", "leaf parent")
+  assertEqual(mid!.root_session_id, "ses_top", "mid root")
+  assertEqual(top!.root_session_id, "ses_top", "top root 等于自身")
+  assertEqual(top!.parent_session_id, null, "top 无父")
+  assert(getCalls.includes("ses_top") && getCalls.includes("ses_mid") && getCalls.includes("ses_leaf"), "回溯与采集覆盖全链")
+})
+
+await runTest("同一子会话由不同入口触发，root_session_id 一致", async () => {
+  const parentOf = (id: string) => (id === "ses_top" ? null : "ses_top")
+  const buildClient = () => {
+    const client = makeClient(
+      { ses_top: [assistantMessage()], ses_child: [assistantMessage()] },
+      { ses_top: ["ses_child"] },
+    )
+    client.session.get = (async (args: { path: { id: string } }) => ({
+      data: { time: { created: 1 }, title: null, directory: null, parentID: parentOf(args.path.id) },
+    })) as typeof client.session.get
+    return client
+  }
+
+  // 入口一：子会话自身的空闲信号；入口二：顶层会话的空闲信号
+  const rootFromChild = await collectAndRootOf(buildClient(), "ses_child", "ses_child")
+  const rootFromTop = await collectAndRootOf(buildClient(), "ses_top", "ses_child")
+  assertEqual(rootFromChild, "ses_top", "子会话入口 → root=顶层")
+  assertEqual(rootFromTop, "ses_top", "顶层入口 → 子会话 root=顶层")
+  assertEqual(rootFromChild, rootFromTop, "两个入口解析出的 root 一致")
+})
+
+await runTest("祖先缺失（get 抛错）→ 以最近验证成功的会话为根，不崩溃不丢快照", async () => {
+  // 链：ses_child → ses_ghost（已删除，get 抛错）
+  const client = makeClient({ ses_child: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_ghost") throw new Error("deleted session")
+    return {
+      data: {
+        time: { created: 1 },
+        title: null,
+        directory: null,
+        parentID: args.path.id === "ses_child" ? "ses_ghost" : null,
+      },
+    }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_child")
+  const child = core.queue.drainAll().find((s) => s.session_id === "ses_child")
+  assert(!!child, "主流程不崩溃，快照仍产生")
+  assertEqual(child!.root_session_id, "ses_child", "以最近验证成功的会话为根")
+  assertEqual(child!.parent_session_id, "ses_ghost", "直接父保留（即使其已删除）")
+})
+
+await runTest("血缘完全不可解析（get 全抛错）→ 血缘为 null，退化为从传入 id 采集", async () => {
+  const client = makeClient({ ses_x: [assistantMessage()] }, {}, { throws: true })
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_x")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_x")
+  assert(!!snap, "不崩溃，快照仍产生")
+  assertEqual(snap!.root_session_id, null, "root 不可知 → null")
+  assertEqual(snap!.parent_session_id, null, "parent 不可知 → null")
+})
+
+await runTest("祖先已删除（get 返回 data 缺失）→ 回溯就地停止，root 为最近验证成功的会话", async () => {
+  // 链：ses_leaf → ses_mid（已删除，get 返回 data: undefined） → ses_root（实际不可达）
+  const client = makeClient({ ses_leaf: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_mid") return { data: undefined }
+    if (args.path.id === "ses_leaf")
+      return { data: { time: { created: 1 }, title: null, directory: null, parentID: "ses_mid" } }
+    return { data: { time: { created: 1 }, title: null, directory: null, parentID: null } }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_leaf")
+  const leaf = core.queue.drainAll().find((s) => s.session_id === "ses_leaf")
+  assert(!!leaf, "主流程不崩溃，快照仍产生")
+  assertEqual(leaf!.root_session_id, "ses_leaf", "root 应为最近真正取到元数据的 leaf")
+  assert(leaf!.root_session_id !== "ses_mid", "root 不得指向已删除的幽灵会话")
+  assertEqual(leaf!.parent_session_id, "ses_mid", "直接父保留（即使其已删除）")
+})
+
+await runTest("起始节点自身已删除（data 缺失）→ 血缘 null，退化为从传入 id 采集", async () => {
+  const client = makeClient({ ses_ghost: [assistantMessage()] })
+  client.session.get = (async () => ({ data: undefined })) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_ghost")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_ghost")
+  assert(!!snap, "不崩溃；messages 仍可用时快照照常产出")
+  assertEqual(snap!.root_session_id, null, "血缘不可知 → null")
+  assertEqual(snap!.parent_session_id, null, "parent 不可知 → null")
+  assertEqual(snap!.session_title, null, "title 不可知 → null")
+  assertEqual(snap!.session_directory, null, "directory 不可知 → null")
+})
+
+await runTest("存在但字段缺失（无 parentID/time）→ 视为存在的顶层，不误判为已删除", async () => {
+  const client = makeClient({ ses_min: [assistantMessage()] })
+  client.session.get = (async (args: { path: { id: string } }) => {
+    if (args.path.id === "ses_min") return { data: { id: "ses_min", title: "T", directory: "/d" } }
+    return { data: undefined }
+  }) as typeof client.session.get
+
+  const { core } = makeCore(client, { endpoint: "http://e" })
+  await core.collectSession("ses_min")
+  const snap = core.queue.drainAll().find((s) => s.session_id === "ses_min")
+  assert(!!snap, "应产出快照")
+  assertEqual(snap!.root_session_id, "ses_min", "存在的顶层 → root 等于自身")
+  assertEqual(snap!.parent_session_id, null, "无 parentID → null")
+  assertEqual(snap!.session_title, "T", "title 正常带上")
+  assertEqual(snap!.session_directory, "/d", "directory 正常带上")
+  assertEqual(snap!.session_created_at, null, "无 time → created 为 null")
+})
+
 // ---------------------------------------------------------------------------
 // 汇总
 // ---------------------------------------------------------------------------

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

@@ -5,6 +5,9 @@
  * - 在会话空闲（bus 事件 `session.idle`，或 `session.status` 且 `status.type === "idle"`）时，
  *   读取该会话及其全部后代子会话的「已完成」助手消息 token 用量，按会话各自聚合为快照。
  * - 父会话快照绝不并入子会话用量；每个会话（含子代理会话）都是独立记录。
+ * - 血缘字段：parent_session_id = 直接父会话（session.get 的 parentID）；root_session_id = 沿
+ *   parentID 回溯到的顶层祖先（自身即顶层时等于 session_id）。祖先查不到（已删除/报错）时
+ *   就地停止，以最近一次验证成功的会话为根；完全不可解析时血缘为 null。
  * - token 口径原样分列上报（input / output / reasoning / cache.read / cache.write），
  *   不在客户端做任何相加或换算（`output` 不含 reasoning，`input` 不含 cache.read）。
  * - hook 只触发后台采集并入队，绝不等待网络；由后台 flush 统一 POST 到解析出的上报端点
@@ -43,7 +46,7 @@ import { dirname, join } from "node:path"
 // ---------------------------------------------------------------------------
 
 const SCHEMA_VERSION = 1
-const PLUGIN_VERSION = "0.1.4"
+const PLUGIN_VERSION = "0.1.6"
 /** 队列容量：最多积压 500 条会话快照，溢出丢最旧 */
 const QUEUE_CAP = 500
 /** 单次上报请求超时（AbortSignal.timeout） */
@@ -57,6 +60,8 @@ const FLUSH_DEBOUNCE_MS = 250
 const DISPOSE_BUDGET_MS = 3_000
 /** 子会话递归深度上限（防御环/异常数据） */
 const MAX_SESSION_DEPTH = 32
+/** 血缘回溯（向上找顶层祖先）深度上限（防御环/异常数据） */
+const MAX_ANCESTOR_DEPTH = 20
 
 const INSTALL_ID_STATE_FILE = () => join(homedir(), ".local", "state", "opencode-session-reporter", "install_id")
 
@@ -113,6 +118,8 @@ export type SessionSnapshot = {
   session_created_at: number | null
   session_title: string | null
   session_directory: string | null
+  parent_session_id: string | null
+  root_session_id: string | null
   last_activity_at: number | null
 }
 
@@ -148,6 +155,14 @@ export type ReporterClient = {
   }
 }
 
+/** 一次 session.get 能取到的会话元数据；null 表示本次调用失败 / 不可用（get 缺失、抛错、会话已删除） */
+export type SessionMeta = {
+  created: number | null
+  title: string | null
+  directory: string | null
+  parentID: string | null
+}
+
 /** 可注入的定时器（测试用手动调度器替换，避免真实 setTimeout） */
 export type ReporterScheduler = (fn: () => void, delayMs: number) => () => void
 
@@ -260,6 +275,8 @@ const aggregateSessionImpl = (sessionID: string, messages: readonly UsageMessage
     session_created_at: null, // 由采集层补充
     session_title: null, // 由采集层补充（session.get）
     session_directory: null, // 由采集层补充（session.get）
+    parent_session_id: null, // 由采集层补充（session.get 的 parentID）
+    root_session_id: null, // 由采集层补充（血缘回溯解析出的顶层祖先）
     last_activity_at: lastActivity,
   }
 }
@@ -517,52 +534,61 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     return ids
   }
 
-  const readSessionMeta = async (
-    sessionID: string,
-  ): Promise<{ created: number | null; title: string | null; directory: string | null }> => {
+  const fetchSessionMeta = async (sessionID: string): Promise<SessionMeta | null> => {
     try {
       const getSession = options.client.session.get
-      if (typeof getSession !== "function") return { created: null, title: null, directory: null }
+      if (typeof getSession !== "function") return null
       const response = await getSession.call(options.client.session, { path: { id: sessionID }, query: query() })
       const data = (
         response as
-          | { data?: { time?: { created?: unknown }; title?: unknown; directory?: unknown } }
+          | { data?: { time?: { created?: unknown }; title?: unknown; directory?: unknown; parentID?: unknown } }
           | undefined
       )?.data
-      const created = data?.time?.created
-      const title = data?.title
-      const directory = data?.directory
+      // 「取不到会话」（data 缺失 / null / 非对象，典型为会话已删除）必须与
+      // 「取到了但某些字段缺失」区分开：前者返回 null，血缘回溯据此就地停止，
+      // 不得把该会话当作已验证的祖先（否则 root 会指向幽灵会话）。
+      if (!data || typeof data !== "object" || Array.isArray(data)) return null
+      const created = data.time?.created
+      const parentID = data.parentID
       return {
         created: typeof created === "number" ? created : null,
-        title: typeof title === "string" && title ? title : null,
-        directory: typeof directory === "string" && directory ? directory : null,
+        title: typeof data.title === "string" && data.title ? data.title : null,
+        directory: typeof data.directory === "string" && data.directory ? data.directory : null,
+        parentID: typeof parentID === "string" && parentID ? parentID : null,
       }
     } catch {
-      // session.get 抛错 / 形状异常：元数据缺省为 null，绝不影响采集主流程
-      return { created: null, title: null, directory: null }
+      // session.get 抛错 / 形状异常：元数据不可用（null），绝不影响采集主流程
+      return null
     }
   }
 
-  /** 递归聚合会话及其后代；每个会话独立成快照，父快照不含子用量 */
+  /**
+   * 递归聚合会话及其后代；每个会话独立成快照，父快照不含子用量。
+   * rootSessionID 为血缘回溯解析出的顶层祖先（不可解析时为 null）；metaGet 为单次采集运行内的
+   * 元数据缓存读取器（血缘回溯与递归采集共用同一次 session.get 结果，不新增 API 请求）。
+   */
   const collectRecursive = async (
     sessionID: string,
     out: SessionSnapshot[],
     visited: Set<string>,
     depth: number,
+    rootSessionID: string | null,
+    metaGet: (id: string) => Promise<SessionMeta | null>,
   ): Promise<void> => {
     if (!sessionID || visited.has(sessionID) || depth > MAX_SESSION_DEPTH || visited.size >= QUEUE_CAP) return
     visited.add(sessionID)
     const snapshot = aggregateSessionImpl(sessionID, await readMessages(sessionID))
     if (snapshot) {
-      // 复用同一次 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
+      const meta = await metaGet(sessionID)
+      snapshot.session_created_at = meta?.created ?? null
+      snapshot.session_title = meta?.title ?? null
+      snapshot.session_directory = meta?.directory ?? null
+      snapshot.parent_session_id = meta?.parentID ?? null
+      snapshot.root_session_id = rootSessionID
       out.push(snapshot)
     }
     for (const childID of await readChildIDs(sessionID)) {
-      await collectRecursive(childID, out, visited, depth + 1)
+      await collectRecursive(childID, out, visited, depth + 1, rootSessionID, metaGet)
     }
   }
 
@@ -571,8 +597,37 @@ const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
     if (inFlight.has(sessionID)) return // 同一会话采集中：跳过，下次空闲信号再采
     inFlight.add(sessionID)
     try {
+      // 单次采集运行内的元数据缓存：血缘回溯与递归采集共用同一次 session.get 结果。
+      // 顶层会话的常见路径（get 一次、无 parent）不产生任何额外 API 请求。
+      const metaCache = new Map<string, SessionMeta | null>()
+      const metaGet = async (id: string): Promise<SessionMeta | null> => {
+        if (metaCache.has(id)) return metaCache.get(id) ?? null
+        const meta = await fetchSessionMeta(id)
+        metaCache.set(id, meta)
+        return meta
+      }
+
+      // 1) 血缘回溯：从触发会话沿 parentID 向上找顶层祖先。
+      //    边界：深度上限 MAX_ANCESTOR_DEPTH、visitedAncestors 防环（含自父）；
+      //    祖先查不到（已删除 / get 抛错 / 不可用）就地停止，以「最近一次验证成功的会话」为根；
+      //    起始节点自身查不到 → 根不可知（null），退化为从传入 id 开始采集。
+      const visitedAncestors = new Set<string>([sessionID])
+      let current = sessionID
+      let verifiedRoot: string | null = null
+      for (let depth = 0; depth < MAX_ANCESTOR_DEPTH; depth++) {
+        const meta = await metaGet(current)
+        if (!meta) break // 查不到：就地停止
+        verifiedRoot = current
+        const parentID = meta.parentID
+        if (!parentID || visitedAncestors.has(parentID)) break // 到顶 / 环 / 自父
+        visitedAncestors.add(parentID)
+        current = parentID
+      }
+
+      // 2) 从根开始递归采集（同一次空闲信号能连带刷新所有兄弟会话）
+      const startID = verifiedRoot ?? sessionID
       const out: SessionSnapshot[] = []
-      await collectRecursive(sessionID, out, new Set(), 0)
+      await collectRecursive(startID, out, new Set(), 0, verifiedRoot, metaGet)
       for (const snapshot of out) queue.push(snapshot)
       if (out.length > 0) scheduleFlush()
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dijkspicy/opencode-stats-reporter",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "本地一体化 MaaS 用量看板：托管静态面板、反代用量接口、本地存储会话用量",
   "type": "module",
   "main": "./contrib/opencode-session-reporter/plugin-server.ts",

package/panel/css/style.css

@@ -537,9 +537,9 @@ body {
   white-space: nowrap;
   vertical-align: bottom;
   font-weight: 600;
-  cursor: pointer;
 }
-.sess-title:hover { color: var(--accent-hover); text-decoration: underline; }
+.sess-title.is-link { cursor: pointer; }
+.sess-title.is-link:hover { color: var(--accent-hover); text-decoration: underline; }
 .sess-sub-line {
   display: flex;
   align-items: center;
@@ -562,6 +562,85 @@ body {
   .sess-dir { max-width: 120px; }
 }
 
+/* 任务行：箭头展开控件 + 「任务」徽标 + 会话数徽标；token 列为任务合计，模型/代理/消息数留 '--' */
+#session-table tr.sess-task > td { padding-top: 14px; }
+tr.sess-task .sess-title-line { display: flex; align-items: center; gap: 6px; }
+.sess-task-badge {
+  flex: none;
+  padding: 0 7px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--text-secondary);
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 16px;
+}
+.sess-count-chip {
+  flex: none;
+  padding: 0 7px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--bg);
+  color: var(--text-secondary);
+  font-size: 10px;
+  line-height: 16px;
+  font-variant-numeric: tabular-nums;
+}
+
+/* 展开/收起箭头：独立点击区，与标题（进详情）互不误触；加载中转圈 */
+.sess-expand {
+  flex: none;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: none;
+  background: transparent;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+.sess-expand:focus-visible { outline: 1px solid var(--accent); }
+.sess-expand .tri {
+  width: 0;
+  height: 0;
+  border-left: 5px solid var(--text-secondary);
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  transition: transform .15s;
+}
+.sess-expand:hover .tri { border-left-color: var(--accent); }
+.sess-expand .tri.is-open { transform: rotate(90deg); }
+.sess-expand .spin {
+  width: 10px;
+  height: 10px;
+  border: 2px solid var(--border);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  animation: sess-spin .8s linear infinite;
+}
+@keyframes sess-spin { to { transform: rotate(360deg); } }
+
+/* 任务展开区的加载 / 错误通栏行：与子会话行同缩进 */
+#session-table tr.sess-expand-state > td {
+  font-size: 12px;
+  color: var(--text-secondary);
+  padding-left: 30px;
+}
+#session-table tr.sess-expand-state > td .btn { margin-left: 10px; }
+#session-table tbody tr.sess-expand-state:hover { background: transparent; }
+
+#session-table tr.sess-child .sess-cell { position: relative; padding-left: 30px; }
+#session-table tr.sess-child .sess-cell::before {
+  content: "";
+  position: absolute;
+  left: 14px;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--border);
+}
+
 /* 会话 ID：默认弱化（有标题时），等宽头尾截断，完整值在 title，点击进详情 */
 .sess-id-btn {
   display: inline-block;

package/panel/index.html

@@ -280,7 +280,7 @@
       <!-- 会话列表 -->
       <section id="card-session-list" class="card">
         <div class="table-head">
-          <h2 class="card-title">会话列表 <span class="src-badge" title="数据来自客户端上报，可能延迟或遗漏">客户端上报</span></h2>
+          <h2 class="card-title">任务列表 <span class="src-badge" title="数据来自客户端上报，可能延迟或遗漏">客户端上报</span></h2>
           <div class="sess-filter">
             <label class="sess-filter-item">模型
               <select id="sess-filter-model" aria-label="按模型筛选">
@@ -296,16 +296,16 @@
           <table id="session-table" class="session-table">
             <thead>
               <tr>
-                <th title="优先显示会话标题，无标题时显示会话 ID；下方小字为会话所属项目目录，悬浮可看完整路径">会话</th>
-                <th>模型</th>
-                <th>代理</th>
-                <th class="num" title="输入总量 = 输入 + 缓存读 + 缓存写">输入总量</th>
-                <th class="num" title="输出总量 = 输出 + 推理">输出总量</th>
-                <th class="num">推理</th>
-                <th class="num">缓存读</th>
-                <th class="num">缓存写</th>
-                <th class="num">消息数</th>
-                <th>最后活动</th>
+                <th title="每行一个顶层任务（token 为任务合计）；点箭头展开/收起子会话，点标题查看根会话详情">任务</th>
+                <th title="会话级属性；任务行不显示，展开子会话查看">模型</th>
+                <th title="会话级属性；任务行不显示，展开子会话查看">代理</th>
+                <th class="num" title="输入总量 = 输入 + 缓存读 + 缓存写；任务行 = 该任务全部会话合计">输入总量</th>
+                <th class="num" title="输出总量 = 输出 + 推理；任务行 = 该任务全部会话合计">输出总量</th>
+                <th class="num" title="任务行 = 该任务全部会话合计">推理</th>
+                <th class="num" title="任务行 = 该任务全部会话合计">缓存读</th>
+                <th class="num" title="任务行 = 该任务全部会话合计">缓存写</th>
+                <th class="num" title="会话级属性；任务行不聚合消息数">消息数</th>
+                <th title="任务行 = 该任务最近一次会话活动">最后活动</th>
               </tr>
             </thead>
             <tbody id="session-tbody"></tbody>

package/panel/js/api.js

@@ -89,7 +89,9 @@
   }
 
   // ---- 会话用量接口（自建会话服务，经同一网关地址访问；数据为客户端上报口径，非网关权威） ----
-  /** 会话列表：window / model / agent / install_id / limit / cursor（游标分页） */
+  /** 任务聚合：/v1/tasks，按顶层会话聚合的 token 合计 + 会话数（服务端口径），window/model/agent/limit/cursor */
+  function tasks(cfg, params) { return get(cfg, '/v1/tasks', params || {}); }
+  /** 会话列表：window / model / agent / root_session_id / install_id / limit / cursor（游标分页） */
   function sessions(cfg, params) { return get(cfg, '/v1/sessions', params || {}); }
   /** 单会话详情：不存在或不属于当前消费者时返回 404 */
   function sessionDetail(cfg, id) { return get(cfg, '/v1/sessions/' + encodeURIComponent(id)); }
@@ -144,6 +146,7 @@
     byModel: byModel,
     byProvider: byProvider,
     performance: performance,
+    tasks: tasks,
     sessions: sessions,
     sessionDetail: sessionDetail,
     sessionsSummary: sessionsSummary,

package/panel/js/sessions.js

@@ -1,8 +1,10 @@
 /**
- * 会话视图：客户端上报的会话级 token 用量
- * 数据源：/v1/sessions*（客户端上报，可能延迟/遗漏，非网关权威数据）
+ * 会话视图：以顶层任务为主维度的 token 用量
+ * 数据源：/v1/tasks（任务级聚合，含 token 合计与会话数）+ /v1/sessions?root_session_id=（展开时按需拉取子会话）
+ *         均为客户端上报口径，可能延迟/遗漏，非网关权威数据
  * token 口径（已实测验证）：输入总量 = 输入 + 缓存读 + 缓存写；输出总量 = 输出 + 推理（推理单列，不并入输出）
- * 结构：来源声明 → 用量对账（网关权威总量 − 会话上报合计 = 未归属用量）→ 会话列表（窗口/模型/代理筛选 + 游标分页）→ 会话详情
+ *   任务行直接展示服务端 tokens_input_total / tokens_output_total（与子会话行同口径），客户端不做页内相加
+ * 结构：来源声明 → 用量对账（网关权威总量 − 会话上报合计 = 未归属用量）→ 任务列表（子会话默认收起、点击展开 + 窗口/模型/代理筛选 + 游标分页）→ 会话详情
  * 由 app.js 初始化：BRU.sessions.init({ getCfg, getPeriod, getModelCatalog, onUnauthorized })，并经 BRU.sessions.load() 触发拉取
  */
 (function () {
@@ -20,11 +22,13 @@
   var st = {
     seq: 0,               // 请求代次：响应到达时核对，过期响应（切窗/切筛选后）直接丢弃
     period: 'today',
-    rows: [],             // 已加载会话（分页累积）
-    nextCursor: null,     // 下一页游标（null = 没有更多）
+    tasks: [],            // 已加载任务（/v1/tasks 分页累积，服务端按任务级 last_activity_at 倒序）
+    taskCursor: null,     // 下一页游标（null = 没有更多）
+    expanded: {},         // root_session_id -> { status: 'loading'|'open'|'closed'|'error', rows: []|null, error, pending }
+                          // 子会话拉取后缓存于 rows：重复展开不再请求；切窗/切筛选（load）时整体重置
     filters: { model: '', agent: '' },
-    modelSet: {},         // 模型筛选项（模型目录 + 已见会话模型）
-    agentSet: {},         // 代理筛选项（已见会话代理）
+    modelSet: {},         // 模型筛选项（模型目录 + 已展开子会话模型）
+    agentSet: {},         // 代理筛选项（已展开子会话代理）
     selectedId: null      // 当前打开详情的会话 ID
   };
 
@@ -77,7 +81,7 @@
   }
 
   // ---------- 加载编排 ----------
-  /** 整页加载：列表重置到第一页 + 对账聚合；seq 保证切窗/切筛选后的旧响应不回写 */
+  /** 整页加载：任务列表重置到第一页 + 对账聚合；seq 保证切窗/切筛选后的旧响应不回写；展开态与子会话缓存一并重置 */
   function load() {
     var cfg = deps && deps.getCfg();
     if (!cfg) return Promise.resolve();
@@ -85,34 +89,34 @@
     st.period = deps.getPeriod();
     setCardState(el.coverageCard, 'loading');
     setCardState(el.listCard, 'loading');
-    st.rows = [];
-    st.nextCursor = null;
+    st.tasks = [];
+    st.taskCursor = null;
+    st.expanded = {};
     el.tbody.innerHTML = '';
     el.count.textContent = '';
     hide(el.btnMore);
     closeDetail();
     var w = st.period;
     return Promise.all([
-      fetchPage(cfg, w, null, true, seq),
+      fetchTasks(cfg, w, null, true, seq),
       fetchCoverage(cfg, w, seq)
     ]);
   }
 
-  /** 拉取一页会话：isReset=true 首页（覆盖），false 追加（加载更多）；失败走卡片错误层 + 重试 */
-  function fetchPage(cfg, window_, cursor, isReset, seq) {
+  /** 拉取一页任务：isReset=true 首页（覆盖），false 追加（加载更多）；失败走卡片错误层 + 重试 */
+  function fetchTasks(cfg, window_, cursor, isReset, seq) {
     var params = { window: window_, limit: PAGE_SIZE };
     if (st.filters.model) params.model = st.filters.model;
     if (st.filters.agent) params.agent = st.filters.agent;
     if (cursor) params.cursor = cursor;
-    return API.sessions(cfg, params).then(function (res) {
+    return API.tasks(cfg, params).then(function (res) {
       if (seq !== st.seq) return;
       var rows = (res && res.data) || [];
-      st.rows = isReset ? rows : st.rows.concat(rows);
-      st.nextCursor = (res && res.next_cursor) || null;
-      absorbOptions(rows);
-      renderRows();
-      el.count.textContent = '已加载 ' + st.rows.length + ' 个会话' + (st.nextCursor ? '（还有更多）' : '');
-      if (st.nextCursor) show(el.btnMore); else hide(el.btnMore);
+      st.tasks = isReset ? rows : st.tasks.concat(rows);
+      st.taskCursor = (res && res.next_cursor) || null;
+      renderTasks();
+      el.count.textContent = '已加载 ' + st.tasks.length + ' 个任务' + (st.taskCursor ? '（还有更多）' : '');
+      if (st.taskCursor) show(el.btnMore); else hide(el.btnMore);
       if (isReset && !rows.length) {
         setCardState(el.listCard, 'empty', null, null,
           (st.filters.model || st.filters.agent) ? '当前筛选条件下暂无会话上报' : null);
@@ -124,7 +128,7 @@
       if (seq !== st.seq) return;
       if (err && err.code === 'unauthorized') { deps.onUnauthorized(UNAUTH_MSG); return; }
       setCardState(el.listCard, 'error', (err && err.message) || '加载失败', function () {
-        fetchPage(deps.getCfg(), deps.getPeriod(), cursor, isReset, st.seq);
+        fetchTasks(deps.getCfg(), deps.getPeriod(), cursor, isReset, st.seq);
       });
     });
   }
@@ -189,11 +193,189 @@
     el.covNote.textContent = note;
   }
 
-  // ---------- 会话列表 ----------
-  function renderRows() {
+  // ---------- 任务列表 ----------
+  /**
+   * 默认只渲染任务行（/v1/tasks，服务端已按任务级 last_activity_at 倒序，客户端不再重排）。
+   * 子会话默认收起：展开态的任务行下方按需插入「加载中 / 错误可重试 / 子会话行」。
+   * root_session_id 为空的任务（旧数据无血缘）按单会话任务降级：无展开控件、标题缺失时降级 '--'。
+   */
+  function renderTasks() {
     var tbody = el.tbody;
     tbody.innerHTML = '';
-    st.rows.forEach(function (r) { tbody.appendChild(sessionRow(r)); });
+    st.tasks.forEach(function (t) {
+      var rootId = nonEmpty(t.root_session_id);
+      tbody.appendChild(taskRow(t, rootId));
+      var s = rootId ? st.expanded[rootId] : null;
+      if (!s) return;
+      if (s.status === 'loading') tbody.appendChild(stateRow('正在加载子会话…'));
+      else if (s.status === 'error') tbody.appendChild(stateRow('子会话加载失败：' + (s.error || '加载失败'), rootId));
+      else if (s.status === 'open') (s.rows || []).forEach(function (r) { tbody.appendChild(sessionRow(r)); });
+    });
+  }
+
+  /** 展开/收起：已拉取的子会话缓存复用（重复展开不再请求）；加载中点击 = 收起并丢弃未返回的结果 */
+  function toggleTask(rootId) {
+    var s = st.expanded[rootId];
+    if (s && s.status === 'open') { s.status = 'closed'; renderTasks(); return; }
+    if (s && s.status === 'loading') { s.pending = false; s.status = 'closed'; renderTasks(); return; }
+    if (s && s.rows) { s.status = 'open'; renderTasks(); return; }   // 收起后再展开：用缓存
+    st.expanded[rootId] = { status: 'loading', rows: null, pending: true };
+    renderTasks();
+    fetchChildren(rootId);
+  }
+
+  /** 拉取单个任务的全部会话（根自身 + 全部子会话，limit=200 上限）；pending 防止已收起后迟到响应回写 */
+  function fetchChildren(rootId) {
+    var cfg = deps.getCfg();
+    if (!cfg) return;
+    var seq = st.seq;
+    API.sessions(cfg, { root_session_id: rootId, limit: 200 }).then(function (res) {
+      if (seq !== st.seq) return;
+      var s = st.expanded[rootId];
+      if (!s || !s.pending) return;
+      s.rows = (res && res.data) || [];
+      s.status = 'open';
+      s.pending = false;
+      absorbOptions(s.rows);   // 子会话的模型/代理补进筛选项
+      renderTasks();
+    }, function (err) {
+      if (seq !== st.seq) return;
+      var s = st.expanded[rootId];
+      if (!s || !s.pending) return;
+      s.pending = false;
+      if (err && err.code === 'unauthorized') { deps.onUnauthorized(UNAUTH_MSG); return; }
+      s.status = 'error';
+      s.error = (err && err.message) || '加载失败';
+      renderTasks();
+    });
+  }
+
+  /** 展开控件：箭头按钮，独立于标题的点击区；状态（开/合/加载中）每次渲染时按 st 重建 */
+  function expandButton(rootId) {
+    var b = document.createElement('button');
+    b.type = 'button';
+    b.className = 'sess-expand';
+    var tri = document.createElement('span');
+    var s = st.expanded[rootId];
+    if (s && s.status === 'open') { tri.className = 'tri is-open'; b.title = '收起子会话'; b.setAttribute('aria-label', '收起子会话'); }
+    else if (s && s.status === 'loading') { tri.className = 'spin'; b.title = '正在加载子会话'; b.setAttribute('aria-label', '正在加载子会话'); }
+    else { tri.className = 'tri'; b.title = '展开子会话'; b.setAttribute('aria-label', '展开子会话'); }
+    b.appendChild(tri);
+    b.addEventListener('click', function () { toggleTask(rootId); });
+    return b;
+  }
+
+  /** 任务行展开区的状态行：colspan 通栏；error 态带重试按钮 */
+  function stateRow(text, errorRootId) {
+    var tr = document.createElement('tr');
+    tr.className = 'sess-expand-state';
+    var c = document.createElement('td');
+    c.colSpan = 10;
+    c.textContent = text;
+    if (errorRootId) {
+      var btn = document.createElement('button');
+      btn.className = 'btn btn-sm';
+      btn.textContent = '重试';
+      btn.addEventListener('click', function () {
+        st.expanded[errorRootId] = { status: 'loading', rows: null, pending: true };
+        renderTasks();
+        fetchChildren(errorRootId);
+      });
+      c.appendChild(btn);
+    }
+    tr.appendChild(c);
+    return tr;
+  }
+
+  /**
+   * 任务行：与子会话行共用同一套列（token 各列同口径），仅「模型 / 代理 / 消息数」为会话级属性，
+   * 任务行显示 '--' 并在悬浮说明，不用某个子会话的值冒充任务值。
+   * token 合计取服务端 tokens_input_total / tokens_output_total（契约与客户端派生公式一致），缺失时才退回客户端派生。
+   */
+  function taskRow(t, rootId) {
+    var tr = document.createElement('tr');
+    tr.className = 'sess-task';
+    var rawTitle = nonEmpty(t.session_title);
+    var dir = nonEmpty(t.session_directory);
+
+    var cell = document.createElement('td');
+    cell.className = 'sess-cell';
+
+    var line1 = document.createElement('div');
+    line1.className = 'sess-title-line';
+    var cnt = Number(t.session_count);
+    var hasCount = isFinite(cnt) && cnt > 0;
+    // 单会话任务（session_count<=1）没有可展开的子会话，不提供展开控件，避免展开后空组
+    var expandable = rootId && (!hasCount || cnt > 1);
+    if (expandable) line1.appendChild(expandButton(rootId));
+
+    var badge = document.createElement('span');
+    badge.className = 'sess-task-badge';
+    badge.textContent = '任务';
+    line1.appendChild(badge);
+
+    var titleEl = document.createElement('span');
+    titleEl.className = 'sess-title' + (rootId ? ' is-link' : '');
+    titleEl.textContent = rawTitle || (rootId ? shortId(rootId) : '--');
+    if (rootId) {
+      titleEl.title = (rawTitle || rootId) + '\n点击查看根会话详情';
+      titleEl.addEventListener('click', function () { openDetail(rootId); });
+    } else if (rawTitle) {
+      titleEl.title = rawTitle;
+    }
+    line1.appendChild(titleEl);
+
+    if (hasCount) {
+      var chip = document.createElement('span');
+      chip.className = 'sess-count-chip';
+      chip.textContent = F.fullNumber(cnt) + ' 个会话';
+      chip.title = '该任务共 ' + F.fullNumber(cnt) + ' 个会话（含顶层会话与子会话）';
+      line1.appendChild(chip);
+    }
+    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 (rootId) {
+      if (dir) {
+        var sep = document.createElement('span');
+        sep.className = 'sess-sub-sep';
+        sep.textContent = '·';
+        line2.appendChild(sep);
+      }
+      line2.appendChild(idButton(rootId, !rawTitle));
+    }
+    if (line2.childNodes.length) cell.appendChild(line2);
+
+    tr.appendChild(cell);
+
+    tr.appendChild(td('--', null, '任务行不显示会话级模型，展开查看各子会话'));
+    tr.appendChild(td('--', null, '任务行不显示会话级代理，展开查看各子会话'));
+    tr.appendChild(td(F.fullNumber(taskTotal(t, 'tokens_input_total', inputTotal)), 'num', '输入总量 = 输入 + 缓存读 + 缓存写'));
+    tr.appendChild(td(F.fullNumber(taskTotal(t, 'tokens_output_total', outputTotal)), 'num', '输出总量 = 输出 + 推理'));
+    tr.appendChild(td(F.fullNumber(t.tokens_reasoning), 'num'));
+    tr.appendChild(td(F.fullNumber(t.tokens_cache_read), 'num'));
+    tr.appendChild(td(F.fullNumber(t.tokens_cache_write), 'num'));
+    tr.appendChild(td('--', null, '任务级不聚合消息数，展开查看各子会话'));
+    var lastFull = F.dateTime(t.last_activity_at);
+    var firstFull = F.dateTime(t.first_activity_at);
+    var tip = lastFull === '--' ? '' : '最后活动：' + lastFull;
+    if (tip && firstFull !== '--') tip += '\n首次活动：' + firstFull;
+    tr.appendChild(td(F.shortDateTime(t.last_activity_at), null, tip));
+    return tr;
+  }
+
+  /** 任务级合计：优先服务端聚合字段，缺失时退回与子会话行相同的客户端派生口径 */
+  function taskTotal(t, serverField, derive) {
+    var v = t[serverField];
+    return (typeof v === 'number' && isFinite(v)) ? v : derive(t);
   }
 
   /** 空值守卫：非字符串或空白串返回 null，避免把 null/undefined/空串渲染到页面 */
@@ -214,6 +396,16 @@
     return '…/' + parts.slice(-2).join('/');
   }
 
+  /**
+   * 子代理会话标题尾部「 (@xxx subagent)」与「代理」列信息重复，展示时去掉；完整原标题始终保留在悬浮。
+   * 仅在后缀中的代理名与该行 agent 字段一致时才去（不一致说明后缀另有含义，原样保留）。
+   */
+  function displayTitle(title, agent) {
+    var m = title.match(/\s*\(@([^\s()]+) subagent\)$/);
+    if (m && agent && m[1] === agent) return title.slice(0, m.index).replace(/\s+$/, '');
+    return title;
+  }
+
   /** 会话 ID 按钮：等宽展示（头尾截断），完整值放 title，点击进详情；primary = 无标题时作为降级主标识 */
   function idButton(sid, primary) {
     var b = document.createElement('button');
@@ -226,12 +418,14 @@
   }
 
   /**
-   * 首列「会话」：两行结构
+   * 子会话行（任务展开后插入）：两行结构
    *   主行：会话标题（加粗）；无标题时降级为会话 ID（等宽、高亮、可点）
    *   次行：项目目录（末两级压缩，悬浮显全路径）· 会话 ID（弱化；ID 已作主标识时不重复）
+   * token 各列与任务行同列同口径（会话级分量）。
    */
   function sessionRow(r) {
     var tr = document.createElement('tr');
+    tr.className = 'sess-child';
     var title = nonEmpty(r.session_title);
     var dir = nonEmpty(r.session_directory);
     var sid = nonEmpty(r.session_id) || '--';
@@ -243,8 +437,8 @@
     line1.className = 'sess-title-line';
     if (title) {
       var t = document.createElement('span');
-      t.className = 'sess-title';
-      t.textContent = title;
+      t.className = 'sess-title is-link';
+      t.textContent = displayTitle(title, nonEmpty(r.agent));
       t.title = title + '\n点击查看详情';
       t.addEventListener('click', function () { openDetail(sid); });
       line1.appendChild(t);
@@ -381,6 +575,8 @@
     body.appendChild(group('会话信息', [
       item('会话标题', nonEmpty(d.session_title) || '--'),
       item('项目目录', nonEmpty(d.session_directory) || '--', true),
+      item('根会话', nonEmpty(d.root_session_id) || '--', true),
+      item('父会话', nonEmpty(d.parent_session_id) || '--', true),
       item('模型', d.model || '--'),
       item('代理', d.agent || '--'),
       item('安装标识', d.install_id || '--', true),
@@ -450,11 +646,11 @@
     };
 
     el.btnMore.addEventListener('click', function () {
-      if (!st.nextCursor) return;
+      if (!st.taskCursor) return;
       el.btnMore.disabled = true;
       el.btnMore.textContent = '加载中…';
-      // fetchPage 内部消化错误，此处仅恢复按钮状态
-      fetchPage(deps.getCfg(), deps.getPeriod(), st.nextCursor, false, st.seq)
+      // fetchTasks 内部消化错误，此处仅恢复按钮状态
+      fetchTasks(deps.getCfg(), deps.getPeriod(), st.taskCursor, false, st.seq)
         .then(function () {
           el.btnMore.disabled = false;
           el.btnMore.textContent = '加载更多';

package/src/server.js

@@ -1,7 +1,7 @@
 import http from "node:http"
 import fs from "node:fs"
 import path from "node:path"
-import { ApiError, report, listSessions, sessionDetail, sessionsSummary } from "./session-api.js"
+import { ApiError, report, listSessions, sessionDetail, sessionsSummary, listTasks } from "./session-api.js"
 import { createProxy } from "./proxy.js"
 import { createIdentityResolver } from "./identity.js"
 
@@ -102,7 +102,11 @@ export function createServer({ config, store, panelDir, mode = "local", consumer
       }
 
       // 会话类 → 本地存储；托管模式需网关注入身份，本地模式归入单一本地用户
-      const isSessionRoute = p === "/v1/session-usage/report" || p === "/v1/sessions" || p.startsWith("/v1/sessions/")
+      const isSessionRoute =
+        p === "/v1/session-usage/report" ||
+        p === "/v1/sessions" ||
+        p === "/v1/tasks" ||
+        p.startsWith("/v1/sessions/")
       if (isSessionRoute) {
         const consumer = resolveConsumer(req)
         if (!consumer) {
@@ -132,6 +136,11 @@ export function createServer({ config, store, panelDir, mode = "local", consumer
           sendJson(res, 200, sessionsSummary(store, consumer, url.searchParams))
           return
         }
+        // /v1/tasks 必须先于任何 :id 形式的捕获
+        if (p === "/v1/tasks" && req.method === "GET") {
+          sendJson(res, 200, listTasks(store, consumer, url.searchParams))
+          return
+        }
         if (p.startsWith("/v1/sessions/") && req.method === "GET") {
           const id = decodeURIComponent(p.slice("/v1/sessions/".length))
           if (!id || id.includes("/")) {

package/src/session-api.js

@@ -73,6 +73,23 @@ export function listSessions(store, consumer, params) {
     model: params.get("model") || undefined,
     agent: params.get("agent") || undefined,
     installId: params.get("install_id") || undefined,
+    rootSessionId: params.get("root_session_id") || undefined,
+    limit,
+    cursor: cursorRaw ? decodeCursor(cursorRaw) : null,
+  })
+  return { object: "list", window: window || null, as_of: iso(), data, next_cursor: nextCursor ? encodeCursor(nextCursor) : null }
+}
+
+/** GET /v1/tasks —— 顶层任务聚合（分组键 COALESCE(root_session_id, session_id)） */
+export function listTasks(store, consumer, params) {
+  const window = params.get("window") || undefined
+  if (window && !WINDOWS.includes(window)) throw new ApiError(400, "window 必须是: today, week, month", "invalid_window")
+  const limit = boundedInt(params.get("limit"), "limit", 50, 1, 200)
+  const cursorRaw = params.get("cursor")
+  const { data, nextCursor } = store.listTasks(consumer, {
+    window,
+    model: params.get("model") || undefined,
+    agent: params.get("agent") || undefined,
     limit,
     cursor: cursorRaw ? decodeCursor(cursorRaw) : null,
   })

package/src/store.js

@@ -31,6 +31,8 @@ CREATE TABLE IF NOT EXISTS session_usage (
   last_reported_at      INTEGER NOT NULL,
   session_title         TEXT,
   session_directory     TEXT,
+  parent_session_id     TEXT,
+  root_session_id       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);
@@ -93,6 +95,8 @@ export function sanitizeRecord(raw) {
     client_session_header: str(raw.client_session_header),
     session_title: str(raw.session_title, 300),
     session_directory: str(raw.session_directory, 512),
+    parent_session_id: str(raw.parent_session_id, 200),
+    root_session_id: str(raw.root_session_id, 200),
   }
 }
 
@@ -125,7 +129,12 @@ export class Store {
     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"]]) {
+    for (const [name, type] of [
+      ["session_title", "TEXT"],
+      ["session_directory", "TEXT"],
+      ["parent_session_id", "TEXT"],
+      ["root_session_id", "TEXT"],
+    ]) {
       if (!existing.has(name)) {
         this.db.exec(`ALTER TABLE session_usage ADD COLUMN ${name} ${type}`)
       }
@@ -149,22 +158,22 @@ export class Store {
     let accepted = 0
     let skipped = 0
     const find = this.db.prepare(
-      "SELECT revision, last_activity_at, session_title, session_directory FROM session_usage WHERE consumer_id=? AND install_id=? AND session_id=?",
+      "SELECT revision, last_activity_at, session_title, session_directory, parent_session_id, root_session_id FROM session_usage WHERE consumer_id=? AND install_id=? AND session_id=?",
     )
     const backfill = this.db.prepare(
-      "UPDATE session_usage SET session_title=?, session_directory=?, last_reported_at=? WHERE consumer_id=? AND install_id=? AND session_id=?",
+      "UPDATE session_usage SET session_title=?, session_directory=?, parent_session_id=?, root_session_id=?, last_reported_at=? WHERE consumer_id=? AND install_id=? AND session_id=?",
     )
     const insert = this.db.prepare(`INSERT INTO session_usage
       (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, session_title, session_directory)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+       first_seen_at, last_reported_at, session_title, session_directory, parent_session_id, root_session_id)
+      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=?, session_title=?, session_directory=?
+      last_reported_at=?, session_title=?, session_directory=?, parent_session_id=?, root_session_id=?
       WHERE consumer_id=? AND install_id=? AND session_id=?`)
 
     for (const r of records) {
@@ -176,7 +185,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,
+          r.session_title, r.session_directory, r.parent_session_id, r.root_session_id,
         )
       } else if (r.revision > prev.revision || (r.revision === prev.revision && r.last_activity_at > prev.last_activity_at)) {
         status = "upserted"
@@ -184,19 +193,25 @@ 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,
+          r.session_title, r.session_directory, r.parent_session_id, r.root_session_id,
           consumerId, r.install_id, r.session_id,
         )
       } else if (r.revision === prev.revision && r.last_activity_at === prev.last_activity_at) {
-        // 单调守卫内（revision 与活动时间均未推进）：仅当元数据变化时做「窄更新」回填，
-        // 只写 session_title / session_directory / last_reported_at，不触碰 token 类字段、
-        // revision、last_activity_at、source、reporter_version 等计量与守卫字段。
+        // 单调守卫内（revision 与活动时间均未推进）：仅当元数据（含血缘）变化时做「窄更新」回填，
+        // 只写 session_title / session_directory / parent_session_id / root_session_id / last_reported_at，
+        // 不触碰 token 类字段、revision、last_activity_at、source、reporter_version 等计量与守卫字段。
         const metaChanged =
           (r.session_title ?? null) !== (prev.session_title ?? null) ||
-          (r.session_directory ?? null) !== (prev.session_directory ?? null)
+          (r.session_directory ?? null) !== (prev.session_directory ?? null) ||
+          (r.parent_session_id ?? null) !== (prev.parent_session_id ?? null) ||
+          (r.root_session_id ?? null) !== (prev.root_session_id ?? null)
         if (metaChanged) {
           status = "backfilled"
-          backfill.run(r.session_title ?? null, r.session_directory ?? null, ts, consumerId, r.install_id, r.session_id)
+          backfill.run(
+            r.session_title ?? null, r.session_directory ?? null,
+            r.parent_session_id ?? null, r.root_session_id ?? null,
+            ts, consumerId, r.install_id, r.session_id,
+          )
         } else {
           status = "unchanged"
         }
@@ -210,7 +225,7 @@ export class Store {
     return { accepted, skipped, results }
   }
 
-  listSessions(consumerId, { window, model, agent, installId, limit = 50, cursor = null } = {}) {
+  listSessions(consumerId, { window, model, agent, installId, rootSessionId, limit = 50, cursor = null } = {}) {
     const where = ["consumer_id=?"]
     const args = [consumerId]
     const start = windowStartMs(window)
@@ -230,6 +245,16 @@ export class Store {
       where.push("install_id=?")
       args.push(installId)
     }
+    if (rootSessionId) {
+      // 顶层任务标识的定义 = COALESCE(root_session_id, session_id)（与 listTasks 的分组表达式严格一致）。
+      // 这里写成语义等价的 OR 展开：root 非空 → root_session_id = X；root 为 NULL（旧数据/孤儿）→
+      // 回退到 session_id = X。若直接写 COALESCE(...) = ? 则该谓词不可走索引；OR 展开后
+      // 第二个分支可用 idx_su_consumer_session(consumer_id, session_id)，第一个分支
+      // （root_session_id = X）无专用索引，但 consumer_id 前置条件仍可借
+      // idx_su_consumer_activity 收敛范围——当前单机个人数据量（千级行）下成本可忽略。
+      where.push("(root_session_id=? OR (root_session_id IS NULL AND session_id=?))")
+      args.push(rootSessionId, rootSessionId)
+    }
     if (cursor) {
       where.push("(last_activity_at < ? OR (last_activity_at = ? AND session_id < ?))")
       args.push(cursor[0], cursor[0], cursor[1])
@@ -242,6 +267,80 @@ export class Store {
     return { data, nextCursor }
   }
 
+  /**
+   * 顶层任务聚合：按 COALESCE(root_session_id, session_id) 分组（无血缘的行各自成任务）。
+   *
+   * 语义选择：window / model / agent 过滤施加在「会话行」上（先过滤、后聚合）——
+   * 任务内只计入匹配的会话行，任务级 last_activity_at 为组内匹配行的 MAX。
+   *
+   * 根会话元数据（title/directory）用「相关子查询 + LIMIT 1」取标量：同一 consumer 下同一
+   * session_id 可能来自多个 install_id，JOIN 会造成行数膨胀；标量子查询每组恰好贡献一个值。
+   * 子查询额外要求 r.root_session_id = 根 id（即该行确实是根行），孤儿组（无血缘/根行缺失）
+   * 因此得到 null，与契约一致。
+   *
+   * 游标 [last_activity_at, root_session_id] 作用在聚合结果之后（外层 WHERE），排序键为
+   * 任务级 MAX(last_activity_at) DESC, root_session_id DESC。
+   */
+  listTasks(consumerId, { window, model, agent, limit = 50, cursor = null } = {}) {
+    const where = ["consumer_id=?"]
+    const args = [consumerId]
+    const start = windowStartMs(window)
+    if (start !== null) {
+      where.push("last_activity_at>=?")
+      args.push(start)
+    }
+    if (model) {
+      where.push("model=?")
+      args.push(model)
+    }
+    if (agent) {
+      where.push("agent=?")
+      args.push(agent)
+    }
+    const cursorWhere = []
+    const cursorArgs = []
+    if (cursor) {
+      cursorWhere.push("(t.last_activity_at < ? OR (t.last_activity_at = ? AND t.root_session_id < ?))")
+      cursorArgs.push(cursor[0], cursor[0], cursor[1])
+    }
+    const sql = `SELECT
+      t.root_session_id,
+      (SELECT r.session_title FROM session_usage r
+        WHERE r.consumer_id = t.consumer_id AND r.session_id = t.root_session_id AND r.root_session_id = t.root_session_id
+        ORDER BY r.last_reported_at DESC LIMIT 1) AS session_title,
+      (SELECT r.session_directory FROM session_usage r
+        WHERE r.consumer_id = t.consumer_id AND r.session_id = t.root_session_id AND r.root_session_id = t.root_session_id
+        ORDER BY r.last_reported_at DESC LIMIT 1) AS session_directory,
+      t.session_count, t.tokens_input, t.tokens_output, t.tokens_reasoning,
+      t.tokens_cache_read, t.tokens_cache_write,
+      t.first_activity_at, t.last_activity_at
+    FROM (
+      SELECT consumer_id,
+        COALESCE(root_session_id, session_id) AS root_session_id,
+        COUNT(*) AS session_count,
+        SUM(tokens_input) AS tokens_input,
+        SUM(tokens_output) AS tokens_output,
+        SUM(tokens_reasoning) AS tokens_reasoning,
+        SUM(tokens_cache_read) AS tokens_cache_read,
+        SUM(tokens_cache_write) AS tokens_cache_write,
+        MIN(last_activity_at) AS first_activity_at,
+        MAX(last_activity_at) AS last_activity_at
+      FROM session_usage
+      WHERE ${where.join(" AND ")}
+      GROUP BY consumer_id, COALESCE(root_session_id, session_id)
+    ) AS t
+    ${cursorWhere.length ? "WHERE " + cursorWhere.join(" AND ") : ""}
+    ORDER BY t.last_activity_at DESC, t.root_session_id DESC
+    LIMIT ?`
+    const rows = this.db.prepare(sql).all(...args, ...cursorArgs, limit + 1)
+    const hasNext = rows.length > limit
+    const data = rows.slice(0, limit).map(withDerived)
+    const nextCursor = hasNext && data.length
+      ? [data[data.length - 1].last_activity_at, data[data.length - 1].root_session_id]
+      : null
+    return { data, nextCursor }
+  }
+
   getSession(consumerId, sessionId, installId) {
     const where = ["consumer_id=?", "session_id=?"]
     const args = [consumerId, sessionId]