@kitsunemori96/opencode-session-metrics 0.1.0 → 0.2.0

package/README.md

@@ -183,15 +183,67 @@ opencode.db (只读)                    .data/metrics.db (查询用)
 正文落库时有长度上限（text / reasoning 2000 字符、工具入参 1500、工具回显 3000），
 超出部分面板本来就画不出来（回显最多展示 40 行）。
 
+## 数据源
+
+面板可以读两种来源，两库并存、随时切换：
+
+| 来源 | 位置 | 成本单位 | 物化库 |
+| --- | --- | --- | --- |
+| OpenCode | `~/.local/share/opencode/opencode.db`（SQLite，只读） | 美元 | `metrics.db` |
+| Qoder CLI | `~/.qoder/projects/<encoded-cwd>/<sessionId>.jsonl`（JSONL） | 积分 | `metrics-qoder.db` |
+
+数据源是**作用域**，不是筛选器：它是面板最高一层决定（高于路由、窗口、facet），在页眉右端
+一次性选定并记住，不写进 URL。两库各存一份切片，切回来还是原来的窗口与筛选。
+完整设计（线框、像素账、API 契约、验收门）见
+[docs/source-scope.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/source-scope.md)。
+
+启动时的默认源：`OSM_SOURCE=opencode\|qoder` → 显式给了 `OSM_SOURCE_DB`（按 OpenCode 处理）→
+存在 `opencode.db` → 存在 `~/.qoder/projects`。启动只物化默认源；另一个库在你第一次切过去时
+才建（Qoder 约 4 秒），之后由 2 分钟一轮的增量同步跟着走。
+
+Qoder 没有会话数据库，转录是逐行 JSONL。两条格式陷阱决定了解析方式：一次模型响应会被
+拆成 2–4 个 `assistant` 事件（只有最后一条带 `usage`，必须按 `message.id` 合并），
+子代理的转录写在 `<sessionId>/subagents/` 下（`sessionId` 仍是父会话，必须并入父会话而不是
+另起一个会话）。token 字段恒为 0，上下文占用由 `context_usage_ratio × contextWindow` 还原；
+积分按整数微积分（`credits_micro`，×1e6）入库，`cost` 列存同一数值供现有聚合使用。
+完整规则与验收门见 [docs/qoder-source.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/qoder-source.md)。
+
+成本单位由 `meta.unit` 声明、`/api/status` 透出，面板在渲染任何数字之前按当前库的单位把
+`$` 换成 `cr`，不需要手工切换。
+
 ## 快速开始
 
-从源码运行：要求 Node 24+、pnpm，且本机已存在 `opencode.db`。
+从源码运行：要求 Node 24+、pnpm，且本机已有 `opencode.db` 或 `~/.qoder/projects`。
 
 ```bash
 pnpm install
-pnpm build            # web/dist + server/dist
-pnpm materialize --full
-pnpm start            # http://127.0.0.1:8787
+pnpm serve            # 构建 web+server，重启在 http://127.0.0.1:8787，就绪后才返回
+```
+
+`pnpm serve` 是推荐的启动方式，它把「构建」和「重启」绑成一件不可分的事：
+
+1. `pnpm build`（web → server）。构建失败就到此为止，旧进程继续服务，不会留下半个产物。
+2. 停掉占用端口的那个进程——**包括没有 pid 文件、手工 `node server/dist/index.js` 起的**。
+3. detached 重启，等到 `/api/status` 真正应答才返回，并打印 pid、数据目录与 URL。
+
+这一步之所以必要：前端产物与服务端产物分别构建，而 `express.static` 会把未知的 `/api/*`
+回落到 `index.html`。只换前端不换后端时，新 bundle 请求 `/api/sources` 收到 200 HTML，
+解析失败后静默降级——页眉的数据源控件会退化成纯文本。`pnpm serve` 从根上消掉这种错配。
+
+首次启动若无指标库会自动物化（全量，几分钟内完成）；之后按水位增量更新。
+
+```bash
+pnpm serve -- --no-open   # 不打开浏览器
+pnpm serve -- --port 8899
+```
+
+进程管理交给同一个脚本：
+
+```bash
+node bin/osm.js status    # 端口、pid、数据目录、bundle 构建时间；进程早于产物会直接告警
+node bin/osm.js stop
+node bin/osm.js logs      # 跟随日志
+node bin/osm.js restart
 ```
 
 开发模式（server 热重载 + Vite 代理）：
@@ -200,8 +252,6 @@ pnpm start            # http://127.0.0.1:8787
 pnpm dev              # API :8787 · Web :5174
 ```
 
-首次启动若无指标库会自动物化；之后按水位增量更新。表结构变更后需要 `--full` 重建。
-
 仓库里的 `bin/osm.js` 与 npm 包里的 `osm` 是同一个脚本，数据目录为仓库的 `.data`：
 
 ```bash
@@ -273,11 +323,14 @@ pid 与日志落在数据目录的 `osm.{pid,log}`。
 
 ```bash
 pnpm dev                    # server + web
+pnpm serve                  # 构建 + 重启 8787（见「快速开始」）
 pnpm typecheck              # 两个包 tsc --noEmit
 pnpm test                   # ETL 测试（离线 fixture，36 项断言，无需服务与网络）
 pnpm -F @osm/server test:smoke   # HTTP 冒烟测试（需服务在线，9 项）
 pnpm materialize            # 增量物化
 pnpm materialize --full     # 全量重建（写入临时文件后原子替换）
+pnpm materialize --source qoder --full   # 只重建 Qoder 库
+pnpm plans                  # 按两库实测单价算套餐性价比（见 docs/plan-value.md）
 ```
 
 前端图表用 `@visx/*`（d3 的无样式原语）与 `@tanstack/react-table` +
@@ -288,8 +341,10 @@ pnpm materialize --full     # 全量重建（写入临时文件后原子替换
 
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
-| `OSM_SOURCE_DB` | `~/.local/share/opencode/opencode.db` | 源库路径（只读） |
-| `OSM_DATA_DIR` | `<项目根>/.data` | 指标库与价目缓存目录（已 gitignore） |
+| `OSM_SOURCE` | 自动 | 默认数据源：`opencode` 或 `qoder`（页眉可切换，不设则自动探测） |
+| `OSM_SOURCE_DB` | `~/.local/share/opencode/opencode.db` | OpenCode 源库路径（只读） |
+| `OSM_QODER_HOME` | `~/.qoder` | Qoder 数据根目录（读其下 `projects/` 与 `logs/`） |
+| `OSM_DATA_DIR` | `<项目根>/.data` | 两库（`metrics.db` / `metrics-qoder.db`）与价目缓存目录（已 gitignore） |
 | `OSM_HOST` | `127.0.0.1` | API 监听地址 |
 | `OSM_PORT` | `8787` | API 端口 |
 | `OSM_OFFLINE` | — | 设为 `1` 时不访问 models.dev，价目走缓存或零值兜底 |
@@ -345,5 +400,11 @@ web/src/
 
 - [docs/opencode-top-parity.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/opencode-top-parity.md) — 与 `opencode-top` 的功能对照，
   以及两处有意的口径差异
+- [docs/qoder-source.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/qoder-source.md) — Qoder CLI 数据源：
+  实测证据、解析规则、单位与模型映射、验收门
+- [docs/source-scope.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/source-scope.md) — 数据源切换：
+  作用域定位、页眉线框与像素账、两库契约、切片归属、验收门
 - [docs/backend-refactor.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/backend-refactor.md) — 2026-10 后端重构的接口变更明细
 - [docs/motion.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/motion.md) — 动效令牌、六个动词、交互对照与静态审计的规则
+- [docs/markdown-transcript.md](https://github.com/kitsuneMori96/opencode-session-metrics/blob/master/docs/markdown-transcript.md) — transcript 的 Markdown 子集：
+  映射表、语料实测、表格判据、搜索投影、验收门与已知边界

package/bin/osm.js

@@ -11,7 +11,7 @@
 // One process, one port: Express serves both the API and the built web bundle.
 // State goes to the XDG data dir (`~/.local/share/opencode-session-metrics`), never
 // into the package directory, so `npm i -g` upgrades cannot delete it.
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import {
   createReadStream,
   existsSync,
@@ -43,6 +43,7 @@ const USAGE = `osm ${PKG.version} — local web cockpit for OpenCode session met
 Usage
   osm [start] [options]   start in the background, then open the browser
   osm run [options]       run in the foreground (Ctrl-C to stop)
+  osm restart [options]   stop, then start again
   osm stop                stop the background server
   osm status              process, URL, data dir, source db, bundle age
   osm logs [-n N]         follow the server log (default: last 40 lines)
@@ -67,6 +68,9 @@ let logLines = 40;
 for (let i = 0; i < argv.length; i += 1) {
   const arg = argv[i];
   switch (arg) {
+    // `pnpm serve -- --no-open` forwards the separator verbatim.
+    case "--":
+      break;
     case "-h":
     case "--help":
       positional.push("help");
@@ -189,6 +193,38 @@ function isOurServer(pid) {
   }
 }
 
+/**
+ * Who holds the port, when we can see it without being root.
+ *
+ * This exists because a server started by hand (`node server/dist/index.js &`)
+ * writes no pid file, and `osm stop` would then refuse to touch it — leaving a
+ * stale bundle answering on the port while `osm start` says "already running".
+ * That is exactly the mismatch `pnpm serve` must not inherit.
+ */
+function listenerPid() {
+  const run = (bin, args) => {
+    try {
+      return execFileSync(bin, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      return "";
+    }
+  };
+  let out = "";
+  if (process.platform === "linux") {
+    for (const bin of ["ss", "/usr/sbin/ss", "/bin/ss", "/usr/bin/ss"]) {
+      out = run(bin, ["-ltnpH", `sport = :${PORT}`]);
+      if (out) break;
+    }
+    const hit = out.match(/pid=(\d+)/);
+    return hit ? Number(hit[1]) : null;
+  }
+  if (process.platform === "darwin") {
+    out = run("lsof", ["-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN", "-t"]);
+    return Number(out.trim().split("\n")[0]) || null;
+  }
+  return null;
+}
+
 function onPath(bin) {
   return (process.env.PATH ?? "")
     .split(path.delimiter)
@@ -225,6 +261,27 @@ function childEnv() {
   };
 }
 
+/**
+ * When a pid started, as epoch ms (Linux only).
+ *
+ * `status` uses it for the one staleness question that matters: a process older
+ * than `web/dist` is serving a bundle that no longer exists on disk — the panel
+ * runs, the page renders, and only the API is from last week.
+ */
+function startedAt(pid) {
+  if (process.platform !== "linux") return null;
+  try {
+    // Field 22 is starttime in USER_HZ ticks since boot. `comm` may contain
+    // spaces, so the fields resume after the last ")".
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const ticks = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]);
+    const uptime = Number(readFileSync("/proc/uptime", "utf8").split(" ")[0]);
+    return Date.now() - (uptime - ticks / 100) * 1000;
+  } catch {
+    return null;
+  }
+}
+
 function lastLines(file, count) {
   const size = statSync(file).size;
   const start = Math.max(0, size - 64 * 1024);
@@ -243,6 +300,11 @@ async function start(foreground) {
 
   if (await isUp()) {
     note(`already running — ${URL}`);
+    const holder = readPid() ?? listenerPid();
+    const since = holder ? startedAt(holder) : null;
+    if (since && existsSync(WEB_INDEX) && statSync(WEB_INDEX).mtime.getTime() - since > 60000) {
+      note("the bundle on disk is newer than the running process — osm restart (or pnpm serve) to load it");
+    }
     openBrowser();
     return;
   }
@@ -298,7 +360,16 @@ async function start(foreground) {
 }
 
 async function stop() {
-  const pid = readPid();
+  let pid = readPid();
+  let adopted = false;
+  if (!pid) {
+    // No pid file: the process may still be ours, just started by hand.
+    const holder = listenerPid();
+    if (holder && isOurServer(holder)) {
+      pid = holder;
+      adopted = true;
+    }
+  }
   if (!pid) {
     if (await isUp()) {
       note(`${URL} answers, but it was not started by osm — leaving it alone`);
@@ -331,19 +402,31 @@ async function stop() {
   try {
     unlinkSync(PID_FILE);
   } catch {}
-  note(`stopped (pid ${pid})`);
+  note(`stopped (pid ${pid}${adopted ? ", stopped a server osm did not start" : ""})`);
 }
 
 async function status() {
   const pid = readPid();
   const up = await isUp();
+  // One lookup either way: a pid file is authoritative, the listener is the fallback.
+  const holder = pid ?? (up ? listenerPid() : null);
   note(`${up ? "up" : "down"} — ${URL}`);
   if (pid) note(`  pid     ${pid}`);
-  else if (up) note("  pid     unknown (not started by osm)");
+  else if (up) note(`  pid     ${holder ? `${holder} (not started by osm)` : "unknown (not started by osm)"}`);
   note(`  data    ${DATA_DIR}${existsSync(path.join(DATA_DIR, "metrics.db")) ? "" : " (no metrics.db yet)"}`);
   note(`  source  ${SOURCE_DB}${existsSync(SOURCE_DB) ? "" : " (missing)"}`);
   if (existsSync(WEB_INDEX)) {
-    note(`  bundle  ${statSync(WEB_INDEX).mtime.toISOString().slice(0, 16).replace("T", " ")}`);
+    // Local time, not ISO: the question this answers is "did the build I just ran
+    // land in the bundle the server is serving", and that comparison happens in
+    // the reader's timezone.
+    const built = statSync(WEB_INDEX).mtime;
+    const age = Math.round((Date.now() - built.getTime()) / 60000);
+    note(`  bundle  ${built.toLocaleString("sv-SE").slice(0, 16)} (${age}m old)`);
+    const since = holder ? startedAt(holder) : null;
+    // A minute of slack: the two timestamps come from different clocks.
+    if (since && built.getTime() - since > 60000) {
+      note(`  stale   pid ${holder} predates the bundle — restart it: pnpm serve`);
+    }
   } else {
     note("  bundle  missing");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsunemori96/opencode-session-metrics",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A local-first web cockpit for OpenCode session metrics: tokens, cost, tools, and transcripts.",
   "type": "module",
   "license": "MIT",
@@ -40,7 +40,9 @@
     "build:web": "pnpm -F @osm/web build",
     "build:server": "pnpm -F @osm/server build",
     "prepack": "pnpm build",
+    "serve": "pnpm build && node bin/osm.js restart",
     "materialize": "pnpm -F @osm/server materialize",
+    "plans": "pnpm -F @osm/server plans",
     "start": "pnpm -F @osm/server start",
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test"