Skip to content

usage.zh-CN.md

Latest commit

 

History

History
258 lines (189 loc) · 19 KB

usage.zh-CN.md

File metadata and controls

258 lines (189 loc) · 19 KB
Raw

使用与参考

项目首页 · English reference · 离线 inspect · 执行证据

本页保留完整功能、截图、安装方式、配置和 HTTP API；首次体验请先看项目首页。

功能特性

  • 离线证据 CLI — agentxray inspect --platform codex session.jsonl --json 无需启动服务或调用模型，输出带输入/规则哈希和原始行号的结构化报告，供 Agent、脚本和 CI 使用。只读明确指定的 Codex、OMP、Claude Code JSONL；默认不输出日志正文和参数，门禁须显式开启。自动化契约。

  • 自动会话体检 — 默认自动整理失败、重复操作、后续候选和调用最后记录状态；执行中、未知及未记录结果可追溯证据。不依赖人工标注或模型调用，笔记与迁移改为可选，不影响自动事实展示。口径与离线验证。

  • Codex 后台进程证据 — 用明确进程 ID 关联启动、write_stdin 轮询和退出结果，可逐步跳转原始证据。ID 重用、轮询交叠和冲突保持未知；不改写历史工具状态，不把进程退出当作任务通过。关联边界。

  • 修改—检查时序 — 区分修改前成功的检查、与修改重叠的检查及后续最新结果；不把先前通过或管道整体成功当作修改后的验证。复杂命令片段执行状态保持未知。识别边界。

  • 有证据的失败事件（React UI） — 将同一调用所在用户轮次、同工具、完整同参数的待复查失败分组，重复最多的操作优先展示；可跳转首末及每条原始证据。同参成功切断分组，缺少参数不合并。执行成功采用明确零退出码或 OMP 原生完成证据；事件不等于根因或任务失败。本地规则，无 LLM。合成演示与判定边界。

  • 后续相关操作 — 展示仅 i 参数不同的调用，以及同轮次、明确同文件的后续修改；标明关系依据、五类结果状态并可跳转证据。候选不自动关闭事件、不代表原问题已修复。匹配边界。

  • 本机复核队列 — 用必填依据标记“需跟进”“预期失败”“其他验证已通过”，仅存当前浏览器；新证据使旧标记失效，人工判断不改写自动结果。无需账号或复核后端。使用方式与存储边界。

  • 复核迁移 — 预览并导出当前会话的有效复核，导入只接受完整证据匹配且本地为空的记录；不覆盖已有笔记，跳过过期或不匹配记录。明文 JSON 含手写依据，不自动复制日志。迁移边界。

  • 窄屏会话复核 — 小于 768px 时切换“会话列表 / 返回内容”，正文获得完整宽度，切换列表不清空当前复核草稿；平台栏横向滚动，证据跳转保留顶部导航，桌面继续双栏。验收范围。

  • 多平台支持 — 一个界面统一查看 OpenClaw、Codex、Claude Code、Hermes、OMP、DeepSeek Harness、Gemini CLI 的会话日志（dsh 的多帧 zstd 压缩日志透明解压；Gemini CLI 的 /rewind 回滚记录会先折叠，回滚掉的历史不会重复渲染）

  • 会话浏览 — 浏览 Agent 列表，搜索/过滤会话，查看消息历史

  • 工具调用检查 — 可展开的工具调用详情，包含参数和返回结果

  • Trace 视图 — 每轮对话的耗时瀑布图：模型推理（蓝）与工具执行（绿，出错为红）一目了然，点击色条在侧栏查看该 span 详情（紫色条则加载派生出的子 Agent 对话）

  • Prompt 提取 — 按 session 提取全部真人 prompt（自动过滤工具结果、斜杠命令、系统注入等噪音），按工作目录分组，支持搜索 / JSON 导出 / 复制

  • Prompt 优化 — 相似 prompt 自动聚类成模板，结合 session 效果归因（轮次、工具调用、错误率），通过配置的 LLM 后端（设置 → LLM 接口）或本机 claude CLI 生成改写建议

  • Prompt 资产库 — 把值得复用的 prompt 收进 ~/.agentxray/library，支持标签 / 编辑 / 搜索，一键安装为 Claude Code、Codex、OMP 的原生 slash command（$ARGUMENTS 原样保留，在目标 CLI 里 /名字 参数 直接可用）

  • 全局搜索 — 一个搜索框同时搜七个平台，多关键词 AND 匹配，每条结果带平台色标 —— 包含从被 Claude Code 清理掉的会话里恢复出来的 prompt

  • 会话洞察 — 聚合分析面板：工具统计、错误聚类、每日趋势

  • Spawn 追踪 — 检测并导航父子 Agent 之间的调用关系

  • OMP 子 Agent — OMP 会话派生的子 Agent 会在摘要区以标签列出，点击即可查看子 Agent 的完整对话

  • 消息时间线 — 可视化对话流程图，不同角色用不同颜色标识

  • Resume 命令 — 一键复制该会话在原 CLI 中的续跑命令（codex resume、claude --resume、omp --resume=）

  • 摘要可折叠 — 需要更多阅读空间时可折叠会话摘要

  • 自动刷新 — 会话列表和消息实时更新

  • 设置面板 — 在页面上直接配置各平台目录，保存到 localStorage，无需重启

  • 会话备份 — 增量归档 Codex、Claude Code、OMP、DeepSeek Harness、Gemini CLI 的会话日志到 ~/.agentxray/archive（Hermes 与 OpenClaw 不归档），在设置面板一键触发（也会每天自动执行），未变化的文件自动跳过

  • 键盘导航 — 使用方向键在会话之间切换

截图预览

会话浏览

侧边栏浏览 Agent 和会话列表。每个会话卡片显示按角色分类的消息数（👤 用户、🤖 助手、🔧 工具）和 spawn 标记。主面板展示会话元数据、Token 用量和热门工具概览。

Main View

工具调用检查

展开任意工具调用可查看其参数和返回结果。折叠状态下按工具类型显示调用次数，方便快速扫视。

Tool Calls

Spawn 追踪

含有子 Agent 的会话会标注 🔗 徽章。点击可导航父子 Agent 调用链。

Spawn Tracking

多平台支持

一键切换 OpenClaw、Codex、Claude Code、Hermes、OMP、DeepSeek Harness、Gemini CLI。每个平台的会话均从其原生日志格式解析。

Codex View

设置面板

在页面上配置各平台目录，保存到 localStorage，无需重启服务。

Settings

安装

方式一 — 通过 npm 使用 npx

npx @alloevil/agent-xray            # 默认 http://localhost:3800
npx @alloevil/agent-xray --port 3900 --host 127.0.0.1

全局安装（npm i -g @alloevil/agent-xray）后可直接使用 agentxray 命令。

方式二 — 直接从 GitHub 运行 npx（现在即可用，无需克隆）

npx github:alloevil/AgentXRay

首次运行会在本地构建 Web UI（约一分钟），之后会复用缓存。

方式三 — 源码运行

git clone https://github.com/alloevil/AgentXRay.git
cd AgentXRay
npm install               # 首次安装会自动构建 Web UI
npm start

打开 http://localhost:3800

使用方法

基本流程

  1. 选择平台 — 点击顶部 OpenClaw、Codex、Claude Code、Hermes、OMP、DeepSeek Harness 或 Gemini CLI
  2. 选择 Agent — OpenClaw 平台下，从下拉菜单选择 Agent（如 xiaot、mimo）
  3. 浏览会话 — 会话按时间倒序排列，每张卡片显示：
    • 时间戳和状态（active / archived）
    • 消息计数：👤 用户、🤖 助手、🔧 工具调用
    • 🔗 Spawn 标记（如果该会话产生了子 Agent）
  4. 查看消息 — 点击会话加载完整对话
  5. 检查工具调用 — 点击 🔧 tool_name 按钮展开参数/结果
  6. 导航 Spawn — 点击 🔗 链接跳转到子 Agent 会话

Prompt 视图

点击顶部 Prompts 标签（Sessions / Insights 旁），即可看到所有 session 的真人 prompt，按 session 所属工作目录分组。工具结果、斜杠命令回显、系统提醒、任务通知等噪音会被自动过滤。

  • 预览与展开 — 每个 session 行内直接预览首条 prompt，点击展开完整列表（markdown 渲染）
  • 搜索 — 实时过滤 prompt / 目录 / session
  • Export JSON — 导出全部提取的 prompt 用于离线处理
  • 分析优化 — 相似 prompt 聚类成模板，结合每个模板的 session 效果归因（平均轮次、工具调用、错误率），由配置的 LLM 后端（设置 → LLM 接口）生成模板改写建议；未配置端点时改由服务器 PATH 中的 claude CLI 生成。两者都没有时，聚类和归因仍然可用，接口会把缺失的后端报告为 llmError
  • 优化单条 — 悬停任意 prompt 点击「优化」，内联生成 LLM 改写版本（在 设置 → LLM 接口 配置后端，或 PATH 上有 claude CLI）

键盘快捷键

按键 操作
↑ / ↓ 在会话间切换
Enter 选中高亮的会话

过滤与搜索

  • 搜索框 — 按 ID 或内容过滤会话
  • 包含已归档 — 切换显示/隐藏已归档（.reset.* / .deleted.*）会话
  • 自动刷新 — 自动轮询获取新会话和消息
  • 自动滚动 — 新内容到达时自动滚动到最新消息

配置

默认目录

平台 默认路径
OpenClaw ~/.openclaw/agents
Codex ~/.codex/sessions
Claude Code ~/.claude/projects
Hermes ~/.hermes
OMP ~/.omp/agent/sessions
DeepSeek Harness ~/.dsh/sessions（同时识别 DSH_HOME）
Gemini CLI ~/.gemini/tmp

自定义目录

通过页面设置： 点击侧边栏的齿轮图标，为每个平台设置自定义路径。保存到 localStorage，无需重启服务。

通过环境变量：

OPENCLAW_DIR=/custom/path/openclaw \
CODEX_DIR=/custom/path/codex \
CLAUDE_CODE_DIR=/custom/path/claude \
HERMES_DIR=/custom/path/hermes \
OMP_DIR=/custom/path/omp \
DSH_DIR=/custom/path/dsh/sessions \
GEMINI_DIR=/custom/path/gemini/tmp \
npm start

通过 API： 在任意 API 请求后附加 ?dir=/absolute/path 参数。

API

接口 说明
GET /api/agents 获取 OpenClaw Agent 列表
GET /api/agents/:name/sessions 获取指定 Agent 的会话列表
GET /api/agents/:name/sessions/:id 获取会话消息详情
GET /api/codex/sessions 获取 Codex 会话列表
GET /api/codex/sessions/:id 获取 Codex 会话消息详情
GET /api/claude-code/sessions 获取 Claude Code 会话列表
GET /api/claude-code/sessions/:id 获取 Claude Code 会话消息详情
GET /api/hermes/sessions 获取 Hermes 会话列表
GET /api/hermes/sessions/:id 获取 Hermes 会话消息详情
GET /api/omp/sessions 获取 OMP（oh-my-pi）会话列表
GET /api/omp/sessions/:id 获取 OMP 会话消息详情
GET /api/dsh/sessions 获取 DeepSeek Harness 会话列表
GET /api/dsh/sessions/:id 获取 DeepSeek Harness 会话消息详情
GET /api/gemini/sessions 获取 Gemini CLI 会话列表
GET /api/gemini/sessions/:id 获取 Gemini CLI 会话消息详情
GET /api/spawn-map 获取 Agent spawn 关系图
GET /api/insights 聚合分析（工具统计、错误聚类、趋势）
GET /api/prompts 按目录分组的各 session 真人 prompt
GET /api/prompts/analyze 模板聚类 + 效果归因 + Claude 建议（?refresh=1 重算，?skipLlm=1 仅聚类）
POST /api/prompts/rewrite 通过配置的 LLM 后端改写单条 prompt（{ "text": "..." }；无可用后端时返回 503 及配置指引）
GET/PUT /api/settings/llm LLM 后端配置：OpenAI 兼容 baseUrl/model/apiKey,持久化在 ~/.agentxray/llm.json（key 不回显）
GET /api/search 会话全文搜索（?platform=all 一次搜索全部平台，多关键词 AND）
GET /api/omp/sessions/:id/children 获取该 OMP 会话派生的子 Agent 列表
GET /api/omp/sessions/:id/children/:name 获取指定子 Agent 的消息详情
GET /api/library 获取资产库 prompt 列表（含各目标的安装状态）
POST /api/library 新建 prompt（{ "name": "...", "content": "...", "description": "...", "tags": [...] }）
PUT /api/library/:name 更新 / 重命名 prompt（newName、content、description、tags），已安装的副本同步刷新
DELETE /api/library/:name 删除 prompt 及其已安装的 slash command
POST /api/library/:name/install 安装为 slash command（{ "targets": ["claude", "codex", "omp"] }）
POST /api/library/:name/uninstall 卸载已安装的 slash command（请求体同上）
POST /api/library/suggest-name 通过配置的 LLM 后端为 prompt 生成库内命名（{ "text": "..." }，无可用后端时返回 null）
POST /api/backup 执行一次增量备份到 ~/.agentxray/archive
GET /api/backup/status 归档统计：文件数、总字节数、最近备份时间

所有列表和详情接口均支持 ?dir= 参数来覆盖默认目录。

技术栈

  • 后端： Node.js + Express
  • 前端： frontend/ 下的 React + Vite + TypeScript（默认 UI，服务自 frontend/dist）
  • Legacy UI： public/ 下的原版 vanilla HTML/CSS/JS 应用，服务于 /legacy —— 已冻结，仅接受安全修复。新功能只进 React 应用；改动 React 渲染器无需触碰 public/js/。共享逻辑（格式化、trace 构建、markdown/转义管线）单一源在 frontend/src/lib/pure.ts 与 frontend/src/lib/markdown.ts,public/js/pure.js 由其生成（npm run build:legacy-pure,也包含在 build:ui 中）。
  • 数据： 直接从磁盘读取 JSONL 会话文件 / SQLite 数据库
  • 零外部 CDN — 完全自包含，离线可用

支持的日志格式

平台 格式 路径模式
OpenClaw JSONL ~/.openclaw/agents/{agent}/sessions/{id}.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]
Gemini CLI JSONL ~/.gemini/tmp/{projectHash}/chats/session-*.jsonl

dsh 的 .jsonl.zstd 日志是多个独立 Zstandard 帧的串联（每个持久化批次一帧）；AgentXRay 会扫描帧边界并逐帧解压，崩溃残留的尾部不完整帧会被容忍丢弃。读取压缩日志需要 Node.js ≥ 22.15（内置 zstd）；未压缩的 session.jsonl 在任何受支持的 Node 上都能读。

启用「包含已归档」后，OpenClaw 还会显示 .jsonl.reset.* 和 .jsonl.deleted.* 的归档会话；其他适配器只列出活跃的 .jsonl 文件。

开发

测试代码位于 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 lib/generated/diagnostics.cjs）、npx biome check . 和 npm test。

新增平台只需两个文件：在 lib/platforms/<name>.js 写一个适配器（针对该日志格式的 list / find / parse / normalize，lib/platforms/shared.js 提供元数据缓存、归一化消息工厂和会话排序），再到 lib/platforms/index.js 的 PLATFORMS 注册表登记一条。通用会话路由、搜索、watch（SSE 实时跟踪）、洞察、Prompt 提取、工具体检、OTLP 与 Markdown/HTML 导出全部通过该注册表解析平台，无需改动其他文件。

常见问题

AgentXRay 支持哪些 agent 和日志格式？ 七个平台：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 会把我的会话数据传到别处吗？ 核心日志查看和离线 inspect 不调用模型、不上传日志。可选的 prompt 改写与建议会使用配置的端点，或回退到可能访问远程服务的 claude CLI；Fabric 导入会从 GitHub 下载内容，安装依赖可能访问包仓库。开发实验中的远程对照须单独运行且只接收通过门禁的脱敏载荷，不随正常看板启动。要求零模型外发时，请勿使用改写与建议功能。

需要改动我的 agent 或加埋点吗？ 不需要。CLI coding agent 本来就把完整会话日志写在磁盘上，AgentXRay 只是读它们。你不需要在代码里接 SDK，也不需要用什么包装命令来启动 agent。默认安装同样无需配置，配置 一节列出的默认目录会直接生效，除非你在设置面板里改，或用 CLAUDE_CODE_DIR 之类的环境变量覆盖。

不装任何东西能先试试吗？ 可以，打开 https://alloevil.github.io/AgentXRay/。这个 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/<name>.js 写一个适配器，实现该格式的 list / find / parse / normalize，然后在 lib/platforms/index.js 的 PLATFORMS 表里登记一条。所有通用路由都通过该注册表解析平台，无需改动其他文件。详见 开发。