feat(#90): ccxray usage CLI — automated data-driven analysis

[lis186]

摘要

新增 ccxray usage CLI 命令 — 直接讀取 index.ndjson，0.6 秒內產出使用量分析，不需啟動 server。把 #89 手動跑 Python 腳本的分析能力變成一個零成本的指令，讓 agent 和開發者快速做資料驅動的決策。

所有過濾器都走「現有 flag 變聰明」的設計（Do-What-I-Mean），使用者不需學新概念：

• --session 接受 latest/costliest 別名、標題子字串、UUID 前綴
• --cwd 接受目錄名子字串，多個值自動切換成專案比較表
• --open 從分析結果一鍵跳到 dashboard 的該 session

設計過程用多專家模擬（fzf / ripgrep / clig.dev / gh CLI 作者的心智模型）+ 加權評分機制（只接受 9 分以上方案）逐一驗證每個 UX 決策。

Detail

What it does

ccxray usage reads ~/.ccxray/logs/index.ndjson directly and prints aggregated analysis. Human-readable by default, --json for agents (<4KB, deterministic, idempotent).

Sections:

• meta — total entries, sessions, cost, time range
• sessions — by provider, subagent ratio, turn distribution, top 10 costliest sessions (with titles)
• models — turns + cost share per model
• tools — call counts, fail rate (--tools for full list)
• skills — per-skill invocations + loads (unique sessions) + scope detection (user/project/plugin)
• prompt hash stability — how often sys/tools/core prompts change between turns
• cache — hit rate, plus hit rate bucketed by inter-turn gap (reveals the 1h cache TTL cliff)

Filters (all composable)

ccxray usage --last 7d                   # time filter (d/h/m)
ccxray usage --cwd myproject             # directory name substring
ccxray usage --cwd proj-a,proj-b         # multi-project comparison table
ccxray usage --session latest            # alias
ccxray usage --session costliest         # alias
ccxray usage --session "fix login"       # title substring
ccxray usage --session 950432            # UUID prefix
ccxray usage --session costliest --open  # jump to dashboard

Implementation notes

• Fast-path dispatch in server/index.js before any server require — keeps it at 0.6s with no server boot
• extractToolCalls in helpers.js now expands Skill/Workflow tool calls to Skill:<name> for per-skill tracking (new data only; old data shows as (pre-tracking))
• Skill scope is derived at analysis time by scanning known skill directories — reflects current state, not historical
• Cross-validated against raw index computation: entry count, cost, tool calls, cache tokens, model breakdown all match exactly (Codex sessions included)

Tests

29 unit + CLI e2e tests in test/usage.test.js. No hardcoded user paths.

What's documented

docs/wire-protocol-reference.md unaffected. README updated in all three languages (en/zh-TW/ja).

🤖 Generated with Claude Code

[lis186]

Self-review findings (sorted by severity)

The substantive risk concentrates in the 5-line helpers.js change — extractToolCalls is a shared writer, so its output ripples through the whole dashboard data path, not just usage.js.

🔴 High — extractToolCalls Skill:<name> expansion has unverified downstream side effects

server/helpers.js:724 now rewrites Skill/Workflow tool-call keys to Skill:<name>. But this function feeds wire-parsers/anthropic.js:55 → live entry → SSE broadcast → index.ndjson. Every new Anthropic turn's toolCalls changes from {Skill: 5} to {"Skill:review": 5}. Three downstream consumers assume the key is exactly 'Skill':

1. public/miller-columns.js:2332 & :2337 — tc['Skill'] > 0 is the cheap pre-lazy-load signal for "does this turn have a skill call". New data has Skill:review keys → tc['Skill'] is undefined → the Skills section loses its pre-reqLoaded detection (graceful degradation, not a crash — recovers from req.tools once the turn is loaded).
2. public/entry-rendering.js:513 — tool chips render Skill:review instead of Skill (visible, undocumented UI change).
3. public/miller-columns.js:1791 — usedTools set counts each Skill:x as a distinct tool → inflates toolUtilization %.

CLAUDE.md requires a browser smoke test for server/UI changes; it wasn't run here. Classic "unit tests don't catch render-pipeline coupling" case.

Fix options: treat Skill:* as Skill in the 3 dashboard consumers (altitude-correct), or run a browser smoke and accept the degradation.

🟡 Medium — whole-file read into memory, no cap

server/usage.js:57 fs.readFileSync loads the entire index.ndjson (~87 MB in practice) then split('\n'). Fine for a one-shot CLI today, but OOM risk as the index grows unbounded. Worth a ponytail: comment naming the ceiling + upgrade path (streaming readline).

🟡 Medium — --cwd path-vs-substring heuristic can misfire

server/usage.js:86 decides "path vs substring" via p.startsWith('/') || p.startsWith('~'). Relative paths (./foo, foo/bar) fall into the substring branch and may match unintended cwds. The naming/behavior gap isn't documented in --help.

🟢 Low — openDashboard exec string concatenation

exec(\${cmd} ${JSON.stringify(url)}`): url is s=${encodeURIComponent(sid.slice(0,8))}— session id is a hash/UUID and encoded, so injection risk is low.execFile` with an args array would be more robust than string concat.

🟢 Low — no test guards the dashboard coupling

test/usage.test.js covers analyze() and the CLI well, but nothing tests the extractToolCalls Skill:<name> expansion, and no test pins the dashboard's Skill-key assumptions. A future revert wouldn't be caught.

---

Codex second-pass review pending; will append if it surfaces anything new.

[lis186]

Codex second-pass review — net-new findings

Codex confirmed the 🔴 tc['Skill'] break (ranks it Critical) and surfaced these additional issues not in the first comment:

🔴 High — Workflow:<name> expansion is asymmetric (dropped stats)

helpers.js:724 expands both Skill and Workflow to <name>:<x>, but usage.js:175 only rolls them back via name.startsWith('Skill:'). So Workflow:<name> keys are counted in tools.totalCalls but never aggregated into skills — Workflow invocation stats are silently dropped. Also: no evidence in the codebase (no test, no wire doc) that the Workflow tool even uses input.skill. Either drop the Workflow branch or read both prefixes back.

🔴 High — analyze([]) produces NaN for subagentRatio (no guard)

usage.js:233 subagentCount / entries.length is unguarded, unlike failRate at :250 which correctly guards entries.length ? … : 0. run() exits early on empty, but analyze() is exported and called directly (tests, multi-cwd per-group) — analyze([]) returns NaN.

🔴 High — gapVsCache throws on non-numeric elapsed

usage.js:319 — if prev.elapsed is non-numeric, gapSec becomes NaN; the gapSec < 0 guard doesn't catch NaN, so BUCKETS.find(b => NaN < b.max) returns undefined → .key throws. Real data is always numeric, but the guard is absent.

🟡 Medium — latest resolves by write-order, not receivedAt (regression from simplify pass)

The simplify pass changed latest to entries[entries.length - 1] (O(1)). But index lines are append-order, not guaranteed chronological under hub mode with concurrent clients or startup restoration. latest can silently return a stale session. The original reduce by receivedAt was correct — this is a speed-for-correctness regression I introduced.

🟡 Medium — --json caps tools at 10, but help/README say "top 7"

analyze() caps tools.top at 10 (:249), printHuman slices to 7 (:429). HELP text and README both say "default: top 7". JSON consumers without --tools get 10 — documented-contract violation.

🟡 Medium — analyze() is not pure (filesystem read)

buildSkillScopeMap() runs readdirSync on plugin trees inside analyze(). Makes the exported function environment-dependent (tests pick up whatever skills the runner has installed) and, in multi-cwd mode, re-scans the same plugin dirs once per project. Build the map once, pass it in.

🟢 Low

• docs/normalization-map.md:146 still says extractToolCalls counts by name — now stale.
• parseArgs dead test scaffold (test/usage.test.js:144-150) extracts via regex then returns null — invalid --last 7x silently ignored, untested.
• Combined --session + --cwd empty result only reports the --session branch in the hint.

---

Consolidated priority: the Critical tc['Skill'] break + the two 🔴 High correctness bugs (Workflow asymmetry, analyze NaN/gapVsCache crash) should block merge. The latest write-order regression is mine to revert. Medium/Low can be follow-ups.

[lis186]

Review findings resolved + green CI + Codex second pass

繁中：兩輪 review 的 14 項 + 失敗的 CI + Codex 二審新發現的 3 項，已全部修復並推上來。核心改動：Skill:<name> 不再塞進共用的 toolCalls 契約，改用獨立的 skillCalls index 欄位——dashboard 零改動（瀏覽器 smoke 驗證 chips 為乾淨的 Skill/Bash/Read、無 Skill: 洩漏、零 console error）。940 測試綠；Codex 二審 round 2 clean。

Key architectural change (resolves 🔴 A1–A4)

Rather than expand Skill/Workflow to Skill:<name> inside extractToolCalls (a shared writer feeding the dashboard and index.ndjson), extractToolCalls is reverted to a clean {toolName: count} map, and a dedicated extractSkillCalls → skillCalls index field carries per-skill granularity that only ccxray usage reads. The dashboard is untouched (zero render-pipeline risk). Verified by browser smoke: tool chips render Skill/Bash/Read, no Skill: leak anywhere, zero console errors. (Workflow has no skill input, so its branch was dead and is dropped.)

Findings → fixes

Finding (severity)	Commit
🔴 extractToolCalls dashboard coupling (A1/A2/A3) + Workflow asymmetry (A4)	10c7e3d
🔴 analyze([]) NaN + gapVsCache crash on non-finite gap	91ca52f
🟡 --session latest resolved by write-order	275ebbf
🟡 analyze() not pure (fs read inside)	6ced143
🟡 --json tools cap 10 vs documented top 7	c65fa54
🟡 --cwd path-vs-substring heuristic (+ ~ never matched)	fe6367c
🟡 whole-file read, no ceiling	1213568
🟢 openDashboard shell string → execFile	a2184be
🟢 invalid --last silently ignored + dead test scaffold	18681f1
🟢 combined --session/--cwd empty-hint	195a7f3
🟢 no test guarding the dashboard/skill contract	6d0b375
🟢 stale normalization-map.md / data-model.md	0f2a9b3

Failing CI

Root cause: the CLI e2e tests defaulted CCXRAY_HOME to the real ~/.ccxray, so they passed locally but failed in CI (no logs → exit 1, 11 failures). They now use an isolated synthetic CCXRAY_HOME fixture and pass with an empty $HOME. — cfe5c19 (+ hermetic ~ test 53c2c97)

Codex second pass

Round 1 surfaced 3 net-new issues, all fixed:

• --session latest/costliest resolved before --last/--cwd → now resolved within the filtered scope — fcbb146
• absolute --cwd prefix not path-bound (/work/proj matched /work/proj-sibling) — fd2b763
• no test proving skillCalls survives the real buildEntryFields → buildIndexLine projection — db6abce

Round 2: no substantive findings.

Follow-up docs (intentionally not in this PR)

• docs: document the ccxray usage --json output schema (agent-facing contract) #95 — document the ccxray usage --json output schema (agent-facing contract)
• docs: document test hygiene — isolated synthetic CCXRAY_HOME, no real user data #96 — document test hygiene (isolated synthetic CCXRAY_HOME, no real user data)
• docs: add a decision record for the toolCalls vs skillCalls index contract #97 — decision record for the toolCalls vs skillCalls index contract

Verification: npm test → 940 pass / 0 fail; browser smoke on an isolated server; full diff re-reviewed by Codex (clean).