diff --git a/README.md b/README.md index 216ab15..589581b 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,7 @@ Release License Stars - No framework - Lightweight + Express + React

@@ -35,13 +34,13 @@ X-ray vision into your AI agent sessions. Supports **OpenClaw**, **Codex**, **Claude Code**, **Hermes**, **OMP**, **DeepSeek Harness** and **Gemini CLI** — all in one interface. -AgentXRay is a single Node.js + Express server plus a React UI. It reads the JSONL session logs (SQLite, for Hermes) that those CLIs already write under your home directory and normalizes all seven formats into one view: tool calls paired with their results, tokens and cost summed per user turn, per-turn trace waterfalls, prompt extraction and cross-platform full-text search. Nothing is instrumented, and nothing leaves your machine. +AgentXRay is a single Node.js + Express server plus a React UI. It reads the JSONL session logs (SQLite, for Hermes) that those CLIs already write under your home directory and normalizes all seven formats into one view: tool calls paired with their results, tokens and cost summed per user turn, per-turn trace waterfalls, prompt extraction and cross-platform full-text search. Nothing is instrumented, and your session data never leaves your machine — the only outbound calls are the prompt-rewrite backend you configure and the on-demand Fabric pattern import. ## Why AgentXRay AgentXRay is a **local-first viewer for the agent sessions you already have**. -Observability platforms like LangSmith and Langfuse are built for agents *you* write: you add their SDK, instrument your code, and traces stream to a hosted backend. Great for building your own agent — but CLI coding agents (Claude Code, Codex, Gemini CLI, …) aren't your code to instrument. They already write complete session logs to your disk; AgentXRay just reads them. Zero integration, zero config, nothing leaves your machine. +Observability platforms like LangSmith and Langfuse are built for agents *you* write: you add their SDK, instrument your code, and traces stream to a hosted backend. Great for building your own agent — but CLI coding agents (Claude Code, Codex, Gemini CLI, …) aren't your code to instrument. They already write complete session logs to your disk; AgentXRay just reads them. Zero integration, zero config, and your logs stay on your machine. Compared to grepping the raw JSONL yourself, AgentXRay normalizes seven different log formats into one interface: tool calls paired with their results, token usage summed per session, full-text search across every platform at once, prompt extraction, and trace timelines — things that are tedious to reconstruct by hand from a 50MB session log. @@ -52,7 +51,7 @@ If you build and operate your own agent in production, use a tracing platform. I - You use one or more CLI coding agents and want to review what a session actually did — which tools ran, with what arguments, what came back, where the time and tokens went. - You want token and cost accounting per user turn for sessions that have already finished, without having instrumented anything beforehand. - You need to search across every agent platform at once, including prompts recoverable from sessions Claude Code's own cleanup already deleted. -- You want your session data to stay on your machine: no SDK, no account, no egress. +- You want your session data to stay on your machine: no SDK, no account, and no egress unless you configure a rewrite backend or use the Fabric pattern import. - You want to collect the prompts worth keeping and install them as native slash commands for Claude Code, Codex or OMP. ## When NOT to use it @@ -71,7 +70,7 @@ If you build and operate your own agent in production, use a tracing platform. I | Built for | agent sessions you already have on disk | agents you write yourself | | Integration | none — reads existing log files | add their SDK and instrument your code | | Works with off-the-shelf CLI agents (Claude Code, Codex, Gemini CLI) | yes, they already log to disk | not their model — that code is not yours to instrument | -| Where data lives | your machine only | hosted backend | +| Where data lives | your machine only | hosted backend (or a self-hosted Langfuse deployment) | Rule of thumb: if you build and operate your own agent in production, use a tracing platform. If you want to see what your coding agents actually did, use AgentXRay. LangSmith and Langfuse are the only alternatives this project makes any comparison against. @@ -79,11 +78,11 @@ Rule of thumb: if you build and operate your own agent in production, use a trac ## Features -- **Per-turn ledger** — In the session summary: one row per user turn with wall-clock time, tokens (input + output + cache) and cost, bars scaled to the session maximum, tool-call and error counts, click to jump. Answers "why did this take 40 minutes / cost $3" without reading the transcript. +- **Per-turn ledger** — In the session summary, from two user turns on: one row per user turn with wall-clock time, tokens (input + output + cache) and cost, bars scaled to the session maximum, tool-call counts inline (error counts in the row tooltip), click to jump. Answers "why did this take 40 minutes / cost $3" without reading the transcript. - **Multi-platform** — Unified view across OpenClaw, Codex, Claude Code, Hermes, OMP, DeepSeek Harness and Gemini CLI sessions (dsh's multi-frame zstd session logs are decompressed transparently; Gemini CLI's `/rewind` checkpoints are folded so rewound history never renders twice) - **Session browser** — Browse agents, filter/search sessions, view message history - **Tool call inspection** — Expandable tool calls with arguments and results -- **Trace view** — Per-turn waterfall of where the time went: model inference (blue) vs tool execution (green, red on error); click any bar to jump to that message +- **Trace view** — Per-turn waterfall of where the time went: model inference (blue) vs tool execution (green, red on error); click any bar for its span detail in the sidebar, and a purple bar to load the spawned sub-agent's transcript - **Prompt extraction** — See every real human prompt per session (tool results, slash commands and injected noise filtered out), grouped by working directory, with search / JSON export / copy - **Prompt optimization** — Cluster prompts into templates, attribute session outcomes (turns, tool calls, error rate) per template, and get LLM-powered rewrite suggestions — through any OpenAI-compatible endpoint (Settings → LLM 接口) or, if none is configured, the local `claude` CLI - **Prompt library** — Curate the prompts worth keeping into `~/.agentxray/library`, tag / edit / search them, then install any of them as a native slash command for Claude Code, Codex or OMP with one click — `$ARGUMENTS` is passed through, so `/name some args` works in the target CLI @@ -96,7 +95,7 @@ Rule of thumb: if you build and operate your own agent in production, use a trac - **Collapsible summary** — Fold the session summary away when you want the full height for messages - **Auto-refresh** — Live-updating session list and messages - **Settings panel** — Configure platform directories from the UI, persisted in localStorage -- **Session backup** — Incremental archive of your session logs into `~/.agentxray/archive`, one click in settings (also runs automatically, daily); unchanged files are skipped +- **Session backup** — Incremental archive of your Codex, Claude Code, OMP, DeepSeek Harness and Gemini CLI session logs into `~/.agentxray/archive` (Hermes and OpenClaw are not archived), one click in settings (also runs automatically, daily); unchanged files are skipped - **Keyboard navigation** — Arrow keys to move between sessions --- @@ -188,7 +187,7 @@ Click the **Prompts** tab (next to Sessions / Insights) to see every real human - **Preview & expand** — Each session row shows a one-line preview of its first prompt; click to expand the full markdown-rendered prompt list - **Search** — Filter prompts / directories / sessions live - **Export JSON** — Download all extracted prompts for offline processing -- **分析优化 (Analyze)** — Cluster prompts into templates, attribute session outcomes (avg turns, tool calls, error rate) per template, and get rewrite suggestions from Claude. Requires the [`claude` CLI](https://claude.com/claude-code) on the server's PATH; without it the clustering and attribution table still works +- **分析优化 (Analyze)** — Cluster prompts into templates, attribute session outcomes (avg turns, tool calls, error rate) per template, and get rewrite suggestions from the configured LLM backend (Settings → LLM 接口) or, when no endpoint is set, the [`claude` CLI](https://claude.com/claude-code) on the server's PATH. With neither, clustering and attribution still work, and the analysis route reports the missing backend as `llmError` - **优化 (Optimize)** — Hover any single prompt and click 优化 for an inline LLM-powered rewrite (configure the backend in Settings → LLM 接口, or have the `claude` CLI on PATH) ### Keyboard Shortcuts @@ -299,8 +298,8 @@ All list/detail endpoints accept an optional `?dir=` parameter to override the d | Platform | Format | Path Pattern | |----------|--------|--------------| | OpenClaw | JSONL | `~/.openclaw/agents/{agent}/sessions/{id}.jsonl` | -| Codex | JSONL | `~/.codex/sessions/{id}.jsonl` | -| Claude Code | JSONL | `~/.claude/projects/*/sessions/*/session.jsonl` | +| Codex | JSONL | `~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{uuid}.jsonl` (session id is the trailing UUID) | +| Claude Code | JSONL | `~/.claude/projects/{project-slug}/{sessionId}.jsonl` (plus `{sessionId}/subagents/agent-*.jsonl` for spawned children) | | Hermes | SQLite | `~/.hermes/state.db` | | OMP | JSONL | `~/.omp/agent/sessions/*/{timestamp}_{id}.jsonl` | | DeepSeek Harness | JSONL / zstd-compressed JSONL | `~/.dsh/sessions/{project}/{id}/session.jsonl[.zstd]` | @@ -308,13 +307,13 @@ All list/detail endpoints accept an optional `?dir=` parameter to override the d dsh's `.jsonl.zstd` logs are a concatenation of independent Zstandard frames (one per append batch); AgentXRay scans the frame boundaries and decompresses every frame, tolerating a torn trailing frame after a crash. Reading compressed dsh logs requires Node.js ≥ 22.15 (built-in zstd); plain `session.jsonl` logs work on any supported Node. -Archived sessions (`.jsonl.reset.*`, `.jsonl.deleted.*`) are also supported when "Include archived" is enabled. +Archived sessions (`.jsonl.reset.*`, `.jsonl.deleted.*`) are shown for OpenClaw when "Include archived" is enabled; the other adapters list active `.jsonl` files only. --- ## Development -Tests live in `test/` and use Node's built-in test runner — no extra dependencies. Run `npm ci` once, then `npm test` (`node --test test/*.test.js`). The tests start their own server on a random port with `HOME` and every platform directory pointed at a throwaway copy of `test/fixtures/home`, so your real session logs are never read or modified. CI runs the same two commands on Node 22 for every push and pull request to `master` (see `.github/workflows/test.yml`). +Tests live in `test/` and use Node's built-in test runner — no extra dependencies. Run `npm ci` once, then `npm test` (`node --test test/*.test.js`). The tests start their own server on a random port with `HOME` and every platform directory pointed at a throwaway copy of `test/fixtures/home`, so your real session logs are never read or modified. CI (`.github/workflows/test.yml`) runs on Node 22 for every push and pull request to `master`, in four steps: `npm ci` (whose `prepare` script builds the web UI and regenerates `public/js/pure.js`), a drift check (`git diff --exit-code public/js/pure.js`), `npx biome check .`, and `npm test`. **Adding a platform** takes two files: write one adapter in `lib/platforms/.js` (list / find / parse / normalize for that log format — `lib/platforms/shared.js` provides the metadata cache, the normalized-message factory and the session sort), then register it in the `PLATFORMS` table in `lib/platforms/index.js`. The generic session routes, search, watch (SSE tail), insights, prompts, tool audit, OTLP and Markdown/HTML export all resolve platforms through that registry — no other file needs to change. @@ -326,13 +325,13 @@ Tests live in `test/` and use Node's built-in test runner — no extra dependenc Seven platforms: OpenClaw, Codex, Claude Code, Hermes, OMP (oh-my-pi), DeepSeek Harness and Gemini CLI. Six of them store JSONL; Hermes stores SQLite at `~/.hermes/state.db`. DeepSeek Harness logs may be multi-frame zstd-compressed `.jsonl.zstd`, which AgentXRay decompresses frame by frame, tolerating a torn trailing frame left by a crash. The authoritative list is the `PLATFORMS` registry in `lib/platforms/index.js` — run `node -e 'console.log(Object.keys(require("./lib/platforms/index.js").PLATFORMS))'` to print it. **Does AgentXRay send my session data anywhere?** -No. It is a local Node.js server reading files from your own disk, serving a self-contained UI with zero external CDN dependencies, so it works offline. The only outbound traffic it can make is the optional prompt-rewrite feature, which calls an OpenAI-compatible endpoint you configure yourself or shells out to a local `claude` CLI; configure neither and nothing is sent anywhere. +No. It is a local Node.js server reading files from your own disk, serving a self-contained UI with zero external CDN dependencies, so it works offline. Two features make outbound calls, and only when you use them: the optional prompt-rewrite feature, which sends the prompt text you asked to rewrite to the OpenAI-compatible endpoint you configure or to a local `claude` CLI, and the prompt-library Fabric import, which on demand downloads the pattern list from `api.github.com` and each pattern's `system.md` from `raw.githubusercontent.com` (falling back to the contents API), caching the pattern list on disk for 24 hours. Configure no endpoint and never use the Fabric import and nothing is sent anywhere. **Do I have to change my agent or add instrumentation?** No. CLI coding agents already write complete session logs to disk, and AgentXRay just reads them. There is no SDK to add to your code and no wrapper command to run your agent under. A default install needs no configuration either, because the default directories listed under [Configuration](#configuration) are used unless you override them in the settings panel or through environment variables such as `CLAUDE_CODE_DIR`. **How do I try it without installing anything?** -Open . That GitHub Pages deployment is the real React UI, built by `.github/workflows/pages.yml`, running against the synthetic sample logs committed under `frontend/demo/sample-logs`. It contains no real user sessions, so treat it as a UI tour rather than as data. +Open . That GitHub Pages deployment is the real React UI, built by `.github/workflows/pages.yml`, running against `frontend/src/demo/fixtures.json` — API fixtures generated from the synthetic sample logs committed under `frontend/demo/sample-logs` by `scripts/build-demo-fixtures.mjs`. It contains no real user sessions, so treat it as a UI tour rather than as data. **How do I add support for a log format that is not listed?** Two files: write an adapter at `lib/platforms/.js` implementing list / find / parse / normalize for that format, then register it in the `PLATFORMS` table in `lib/platforms/index.js`. Every generic route resolves platforms through that registry, so no other file needs to change. See [Development](#development). diff --git a/README.zh-CN.md b/README.zh-CN.md index a5a5c24..a04dde8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -10,13 +10,13 @@ AI Agent 会话 X 光透视工具，支持 **OpenClaw**、**Codex**、**Claude Code**、**Hermes**、**OMP**、**DeepSeek Harness** 和 **Gemini CLI** —— 一个界面全搞定。 -AgentXRay 由一个 Node.js + Express 服务和一套 React UI 组成：它读取这些 CLI 本来就写在你 home 目录下的 JSONL 会话日志（Hermes 是 SQLite），把七种格式归一化到同一个视图 —— 工具调用与结果自动配对、按轮次汇总 token 与花费、每轮耗时瀑布图、prompt 提取、跨平台全文搜索。零埋点、零接入，数据不出本机。 +AgentXRay 由一个 Node.js + Express 服务和一套 React UI 组成：它读取这些 CLI 本来就写在你 home 目录下的 JSONL 会话日志（Hermes 是 SQLite），把七种格式归一化到同一个视图 —— 工具调用与结果自动配对、按轮次汇总 token 与花费、每轮耗时瀑布图、prompt 提取、跨平台全文搜索。零埋点、零接入，会话数据不出本机（仅有的外发请求，是你自行配置的 prompt 改写后端，以及按需触发的 Fabric 模式导入）。 ## 为什么是 AgentXRay AgentXRay 是一个 **local-first 的查看器，看的是你已经拥有的 agent 会话**。 -LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接入 SDK、埋点插桩，trace 上报到托管后端。做自研 agent 时它们很好用 —— 但 Claude Code、Codex、Gemini CLI 这些现成的 CLI coding agent 不是你的代码，没法插桩。它们本来就把完整会话日志写在你的磁盘上，AgentXRay 直接读这些日志：零接入、零配置，数据不出本机。 +LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接入 SDK、埋点插桩，trace 上报到托管后端。做自研 agent 时它们很好用 —— 但 Claude Code、Codex、Gemini CLI 这些现成的 CLI coding agent 不是你的代码，没法插桩。它们本来就把完整会话日志写在你的磁盘上，AgentXRay 直接读这些日志：零接入、零配置，会话数据留在本机。 相比自己翻原始 JSONL，AgentXRay 把七种日志格式归一化到一个界面里：工具调用与结果自动配对、token 用量按会话汇总、跨平台全文搜索、prompt 提取、trace 时间线 —— 这些从一份 50MB 的会话日志里手工还原起来非常费劲。 @@ -29,7 +29,7 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接 - 你在用一个或多个 CLI coding agent，想复盘某次会话到底做了什么：调用了哪些工具、参数是什么、返回了什么、时间和 token 花在哪里。 - 你想按用户轮次核算 token 与花费，而这些会话早已结束，当时并没有做任何埋点。 - 你需要一次搜索全部 agent 平台，包括从 Claude Code 自身清理机制已删除的会话里恢复出来的 prompt。 -- 你希望会话数据只留在本机：不装 SDK、不注册账号、不外传。 +- 你希望会话数据只留在本机：不装 SDK、不注册账号；除非你自行配置改写后端或使用 Fabric 模式导入，否则不外传。 - 你想把值得复用的 prompt 收集起来，并一键安装为 Claude Code、Codex 或 OMP 的原生 slash command。 ## 何时不该用 @@ -48,7 +48,7 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接 | 面向 | 你磁盘上已有的 agent 会话 | 你自己写的 agent | | 接入方式 | 无需接入，直接读现有日志文件 | 接入 SDK，在代码里埋点 | | 能否覆盖现成 CLI agent（Claude Code、Codex、Gemini CLI） | 可以，它们本来就在落盘 | 不适用，这些代码不是你的，没法埋点 | -| 数据存放 | 仅本机 | 托管后端 | +| 数据存放 | 仅本机 | 托管后端（Langfuse 也可自托管） | 一句话：在生产环境构建和运营自己的 agent，请用 tracing 平台；想看清 coding agent 到底干了什么，用 AgentXRay。本项目只与 LangSmith、Langfuse 作对比，不评价其他工具。 @@ -57,9 +57,9 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接 - **多平台支持** — 一个界面统一查看 OpenClaw、Codex、Claude Code、Hermes、OMP、DeepSeek Harness、Gemini CLI 的会话日志（dsh 的多帧 zstd 压缩日志透明解压；Gemini CLI 的 `/rewind` 回滚记录会先折叠，回滚掉的历史不会重复渲染） - **会话浏览** — 浏览 Agent 列表，搜索/过滤会话，查看消息历史 - **工具调用检查** — 可展开的工具调用详情，包含参数和返回结果 -- **Trace 视图** — 每轮对话的耗时瀑布图：模型推理（蓝）与工具执行（绿，出错为红）一目了然，点击色条跳转到对应消息 +- **Trace 视图** — 每轮对话的耗时瀑布图：模型推理（蓝）与工具执行（绿，出错为红）一目了然，点击色条在侧栏查看该 span 详情（紫色条则加载派生出的子 Agent 对话） - **Prompt 提取** — 按 session 提取全部真人 prompt（自动过滤工具结果、斜杠命令、系统注入等噪音），按工作目录分组，支持搜索 / JSON 导出 / 复制 -- **Prompt 优化** — 相似 prompt 自动聚类成模板，结合 session 效果归因（轮次、工具调用、错误率），通过本机 `claude` CLI 生成改写建议 +- **Prompt 优化** — 相似 prompt 自动聚类成模板，结合 session 效果归因（轮次、工具调用、错误率），通过配置的 LLM 后端（设置 → LLM 接口）或本机 `claude` CLI 生成改写建议 - **Prompt 资产库** — 把值得复用的 prompt 收进 `~/.agentxray/library`，支持标签 / 编辑 / 搜索，一键安装为 Claude Code、Codex、OMP 的原生 slash command（`$ARGUMENTS` 原样保留，在目标 CLI 里 `/名字 参数` 直接可用） - **全局搜索** — 一个搜索框同时搜七个平台，多关键词 AND 匹配，每条结果带平台色标 —— 包含从被 Claude Code 清理掉的会话里恢复出来的 prompt - **会话洞察** — 聚合分析面板：工具统计、错误聚类、每日趋势 @@ -70,7 +70,7 @@ LangSmith、Langfuse 这类观测平台面向的是*你自己写的* agent：接 - **摘要可折叠** — 需要更多阅读空间时可折叠会话摘要 - **自动刷新** — 会话列表和消息实时更新 - **设置面板** — 在页面上直接配置各平台目录，保存到 localStorage，无需重启 -- **会话备份** — 增量归档会话日志到 `~/.agentxray/archive`，在设置面板一键触发（也会每天自动执行），未变化的文件自动跳过 +- **会话备份** — 增量归档 Codex、Claude Code、OMP、DeepSeek Harness、Gemini CLI 的会话日志到 `~/.agentxray/archive`（Hermes 与 OpenClaw 不归档），在设置面板一键触发（也会每天自动执行），未变化的文件自动跳过 - **键盘导航** — 使用方向键在会话之间切换 ## 截图预览 @@ -156,8 +156,8 @@ npm start - **预览与展开** — 每个 session 行内直接预览首条 prompt，点击展开完整列表（markdown 渲染） - **搜索** — 实时过滤 prompt / 目录 / session - **Export JSON** — 导出全部提取的 prompt 用于离线处理 -- **分析优化** — 相似 prompt 聚类成模板，结合每个模板的 session 效果归因（平均轮次、工具调用、错误率），由 Claude 生成模板改写建议。需要服务器 PATH 中有 [`claude` CLI](https://claude.com/claude-code)；没有时聚类和归因表格仍可用 -- **优化单条** — 悬停任意 prompt 点击「优化」，内联生成 Claude 改写版本 +- **分析优化** — 相似 prompt 聚类成模板，结合每个模板的 session 效果归因（平均轮次、工具调用、错误率），由配置的 LLM 后端（设置 → LLM 接口）生成模板改写建议；未配置端点时改由服务器 PATH 中的 [`claude` CLI](https://claude.com/claude-code) 生成。两者都没有时，聚类和归因仍然可用，接口会把缺失的后端报告为 `llmError` +- **优化单条** — 悬停任意 prompt 点击「优化」，内联生成 LLM 改写版本（在 设置 → LLM 接口 配置后端，或 PATH 上有 `claude` CLI） ### 键盘快捷键 @@ -259,8 +259,8 @@ npm start | 平台 | 格式 | 路径模式 | |------|------|----------| | OpenClaw | JSONL | `~/.openclaw/agents/{agent}/sessions/{id}.jsonl` | -| Codex | JSONL | `~/.codex/sessions/{id}.jsonl` | -| Claude Code | JSONL | `~/.claude/projects/*/sessions/*/session.jsonl` | +| Codex | JSONL | `~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{uuid}.jsonl`（session id 是结尾的 UUID） | +| Claude Code | JSONL | `~/.claude/projects/{project-slug}/{sessionId}.jsonl`（派生子 Agent 另有 `{sessionId}/subagents/agent-*.jsonl`） | | Hermes | SQLite | `~/.hermes/state.db` | | OMP | JSONL | `~/.omp/agent/sessions/*/{timestamp}_{id}.jsonl` | | DeepSeek Harness | JSONL / zstd 压缩 JSONL | `~/.dsh/sessions/{project}/{id}/session.jsonl[.zstd]` | @@ -268,11 +268,11 @@ npm start dsh 的 `.jsonl.zstd` 日志是多个独立 Zstandard 帧的串联（每个持久化批次一帧）；AgentXRay 会扫描帧边界并逐帧解压，崩溃残留的尾部不完整帧会被容忍丢弃。读取压缩日志需要 Node.js ≥ 22.15（内置 zstd）；未压缩的 `session.jsonl` 在任何受支持的 Node 上都能读。 -启用「包含已归档」后，还会显示 `.jsonl.reset.*` 和 `.jsonl.deleted.*` 的归档会话。 +启用「包含已归档」后，OpenClaw 还会显示 `.jsonl.reset.*` 和 `.jsonl.deleted.*` 的归档会话；其他适配器只列出活跃的 `.jsonl` 文件。 ## 开发 -测试代码位于 `test/`，使用 Node 内置的测试运行器，无需额外依赖。先执行一次 `npm ci`，然后运行 `npm test`（即 `node --test test/*.test.js`）。测试会在随机端口上启动自己的服务实例，并把 `HOME` 及各平台目录都指向 `test/fixtures/home` 的临时副本，因此不会读取或修改你的真实会话日志。CI 在每次向 `master` 的 push 和 pull request 上以 Node 22 执行同样的两条命令（见 `.github/workflows/test.yml`）。 +测试代码位于 `test/`，使用 Node 内置的测试运行器，无需额外依赖。先执行一次 `npm ci`，然后运行 `npm test`（即 `node --test test/*.test.js`）。测试会在随机端口上启动自己的服务实例，并把 `HOME` 及各平台目录都指向 `test/fixtures/home` 的临时副本，因此不会读取或修改你的真实会话日志。CI（`.github/workflows/test.yml`）在每次向 `master` 的 push 和 pull request 上以 Node 22 执行四个步骤：`npm ci`（其 `prepare` 脚本会构建 Web UI 并重新生成 `public/js/pure.js`）、漂移检查（`git diff --exit-code public/js/pure.js`）、`npx biome check .` 和 `npm test`。 **新增平台只需两个文件**：在 `lib/platforms/.js` 写一个适配器（针对该日志格式的 list / find / parse / normalize，`lib/platforms/shared.js` 提供元数据缓存、归一化消息工厂和会话排序），再到 `lib/platforms/index.js` 的 `PLATFORMS` 注册表登记一条。通用会话路由、搜索、watch（SSE 实时跟踪）、洞察、Prompt 提取、工具体检、OTLP 与 Markdown/HTML 导出全部通过该注册表解析平台，无需改动其他文件。 @@ -282,13 +282,13 @@ dsh 的 `.jsonl.zstd` 日志是多个独立 Zstandard 帧的串联（每个持 七个平台：OpenClaw、Codex、Claude Code、Hermes、OMP（oh-my-pi）、DeepSeek Harness 和 Gemini CLI。其中六个是 JSONL，Hermes 是位于 `~/.hermes/state.db` 的 SQLite。DeepSeek Harness 的日志可能是多帧 zstd 压缩的 `.jsonl.zstd`，AgentXRay 会逐帧解压，并容忍崩溃残留的尾部不完整帧。权威清单是 `lib/platforms/index.js` 里的 `PLATFORMS` 注册表，可用 `node -e 'console.log(Object.keys(require("./lib/platforms/index.js").PLATFORMS))'` 打印。 **AgentXRay 会把我的会话数据传到别处吗？** -不会。它是一个读取你本机磁盘文件的本地 Node.js 服务，UI 完全自包含、零外部 CDN，因此离线也能用。唯一可能产生外发流量的是可选的 prompt 改写功能：它调用你自己配置的 OpenAI 兼容端点，或调起本机的 `claude` CLI；两者都不配置时，不会有任何数据外发。 +不会。它是一个读取你本机磁盘文件的本地 Node.js 服务，UI 完全自包含、零外部 CDN，因此离线也能用。有两个功能会产生外发请求，且只在你主动使用它们时：可选的 prompt 改写功能，把你要求改写的那段 prompt 文本发给你自己配置的 OpenAI 兼容端点，或本机的 `claude` CLI；以及 Prompt 资产库的 Fabric 导入，它按需从 `api.github.com` 下载模式列表、从 `raw.githubusercontent.com` 下载每个模式的 `system.md`（失败时回退到 contents API），并把模式列表在磁盘上缓存 24 小时。不配置端点、也不使用 Fabric 导入，就不会有任何数据外发。 **需要改动我的 agent 或加埋点吗？** 不需要。CLI coding agent 本来就把完整会话日志写在磁盘上，AgentXRay 只是读它们。你不需要在代码里接 SDK，也不需要用什么包装命令来启动 agent。默认安装同样无需配置，[配置](#配置) 一节列出的默认目录会直接生效，除非你在设置面板里改，或用 `CLAUDE_CODE_DIR` 之类的环境变量覆盖。 **不装任何东西能先试试吗？** -可以，打开 。这个 GitHub Pages 部署就是真实的 React UI，由 `.github/workflows/pages.yml` 构建，跑在仓库里提交的合成示例日志 `frontend/demo/sample-logs` 上。它不含任何真实用户会话，所以请把它当作界面导览，而不是数据。 +可以，打开 。这个 GitHub Pages 部署就是真实的 React UI，由 `.github/workflows/pages.yml` 构建，跑在 `frontend/src/demo/fixtures.json` 上 —— 这些 API fixture 由 `scripts/build-demo-fixtures.mjs` 从仓库里提交的合成示例日志 `frontend/demo/sample-logs` 生成。它不含任何真实用户会话，所以请把它当作界面导览，而不是数据。 **想支持一个没列出的日志格式怎么办？** 两个文件：在 `lib/platforms/.js` 写一个适配器，实现该格式的 list / find / parse / normalize，然后在 `lib/platforms/index.js` 的 `PLATFORMS` 表里登记一条。所有通用路由都通过该注册表解析平台，无需改动其他文件。详见 [开发](#开发)。 diff --git a/assets/readme/hero.svg b/assets/readme/hero.svg index 23202f1..6e68edd 100644 --- a/assets/readme/hero.svg +++ b/assets/readme/hero.svg @@ -53,7 +53,7 @@ Node.js 22.13+ · MIT · ~70KB build + font-size="18">Node.js 22.13+ · MIT diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index dbfd4eb..7fb7ffb 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -8,7 +8,7 @@ - **Session browser** with tool-call inspection, trace/waterfall view, spawn tracking and message timeline - **Prompt tooling** — extraction (noise filtered), template clustering with outcome attribution, Claude-powered rewrites, and a prompt library that installs entries as native slash commands - **Global search** across all platforms, insights dashboard, incremental session backup -- **React + Vite frontend** served by an Express backend; 46 tests on Node's built-in runner, CI on Node 22 +- **React + Vite frontend** served by an Express backend; 130 tests on Node's built-in runner (`npm test`, 2026-09-12), CI on Node 22 ## Roadmap