sumeshi/agentlogparser-rs

# agentlogparser-rs `agentlogparser-rs` 是一个 Rust 库，用于将 AI agent 产物解析为统一的 timeline schema。它提供 Rust 和 Python API，并将结果 序列化为 JSON、JSONL 或 CSV。 解析器在读取源产物时不会对其进行修改。 ## 支持的产物 ### Claude Code | Path | Parsed data | |---|---| | `.claude/history.jsonl` | Prompt 文本、内嵌 timestamp、工作目录、session ID 以及粘贴/图片引用 | | `.claude/paste-cache/*` | 外部存储的文本粘贴 | | `.claude/image-cache/*` | 外部存储的图片粘贴 | | `.claude/file-history/*` | 编辑前的文件快照，按 session 和版本分组 | 传入 `.claude` 目录以解析并关联这些产物。history 文件、cache 路径或 file-history 路径也可以独立解析。 当仅提供 `history.jsonl` 时，无法解析外部 `contentHash` 引用。 `.claude/projects` 下的 Claude Code 对话记录不会被解析。 ### Codex CLI | Path | Parsed data | |---|---| | `.codex/history.jsonl` | Prompt 文本、session ID 和 Unix timestamp | | `.codex/sessions/**/rollout-*.jsonl` | Session 元数据、消息、reasoning、tool 调用与结果、task 状态、token 使用情况、compaction 和错误 | | `.codex/attachments/**` | 附件路径、文件系统 timestamp、大小、媒体类型和 SHA-256 | 传入 `.codex` 目录以解析所有支持的 Codex 产物。history 文件、sessions 目录、rollout 文件、attachments 目录或附件 文件也可以独立解析。 SQLite 数据库、身份验证数据、环境文件、配置、 shell 快照和内部 cache 不会被解析。 Codex history 和 rollout 文件中匹配的 prompt 记录将作为独立的 事件保留，因为它们是独立的源记录。 Provider 检测使用已注册的 adapter。显式的 provider 目录 优先于通用文件名，而特定于 provider 的目录布局 优先于通用的 history 布局。在匹配项具有同等特定性时，检测会 返回错误，而不是按注册 顺序选择 adapter。 ## 快速转换 `examples/inspect_evidence.py` 解析受支持的产物并将 选定格式写入标准输出。它可以作为直接转换器使用： ``` python examples/inspect_evidence.py ~/.claude --format csv > timeline.csv python examples/inspect_evidence.py ~/.codex --format jsonl > timeline.jsonl python examples/inspect_evidence.py ~ --format json > all-agents.json ``` 当用户配置目录包含已注册的 provider 目录时，所有 检测到的 provider 都会被解析到一个 timeline 中。该脚本还接受 单个受支持的文件和目录。 有用的选项包括： ``` --strict --include-raw --include-content --follow-symlinks --max-line-size BYTES --max-content-size BYTES ``` 在运行脚本之前必须安装 Python 扩展。在 源码检出目录中使用 `python -m pip install ./python`。 ## Rust API 将该 crate 添加为依赖项： ``` [dependencies] agentlogparser = { path = "../agentlogparser-rs" } ``` 解析受支持的目录或文件： ``` use agentlogparser::{parse_path, ParserOptions}; fn main() -> Result<(), agentlogparser::Error> { let report = parse_path( r"C:\Users\alice\.codex", &ParserOptions::default(), )?; println!("events: {}", report.events.len()); println!("diagnostics: {}", report.diagnostics.len()); Ok(()) } ``` `parse_path` 接受受支持的 provider 根目录以及上面列出的各个 产物路径。`parse_history` 接受包含 Claude Code history 记录的 `BufRead`。 `ParserOptions::default()` 使用以下设置： | Option | Default | Effect | |---|---:|---| | `input_kind` | `Auto` | 从路径检测产物类型 | | `mode` | `BestEffort` | 在发生可恢复的错误后继续并记录诊断信息 | | `include_raw` | `false` | 不包含原始 JSON 记录 | | `include_content` | `false` | 不包含文件内容或 Codex 工具参数/结果 | | `follow_symlinks` | `false` | 不遵循符号链接 | | `max_line_size` | 10 MiB | 保留的最大 JSONL 行大小；过大的行将被排空并跳过 | | `max_content_size` | 50 MiB | 有资格包含内容的最大文件大小 | `Strict` 模式在遇到 error 级别诊断时停止。大小 限制为 `0` 将禁用该限制。启用 `follow_symlinks` 可能会读取所提供证据根目录之外的 目标。 序列化内存中的已解析报告： ``` use agentlogparser::{write_csv, write_json, write_jsonl}; let mut json = Vec::new(); write_json(&report, &mut json, true)?; let mut jsonl = Vec::new(); write_jsonl(&report.events, &mut jsonl)?; let mut csv = Vec::new(); write_csv(&report.events, &mut csv, true, false)?; # Ok::<(), agentlogparser::Error>(()) ``` ## Python API 通过 CPython 稳定 ABI 支持 Python 3.10 或更高版本。 从 PyPI 安装： ``` python -m pip install agentlogparser ``` 从源码检出安装： ``` python -m pip install ./python ``` 将产物解析为 Python 对象： ``` from agentlogparser import parse report = parse( r"C:\Users\alice\.claude", mode="best_effort", include_raw=False, include_content=False, follow_symlinks=False, max_line_size=10 * 1024 * 1024, max_content_size=50 * 1024 * 1024, ) print(report["events"]) print(report["diagnostics"]) ``` 返回序列化数据而不创建输出文件： ``` from agentlogparser import to_csv, to_json, to_jsonl csv_text = to_csv(r"C:\Users\alice\.codex") json_text = to_json(r"C:\Users\alice\.codex") jsonl_text = to_jsonl(r"C:\Users\alice\.codex") ``` 将序列化数据写入文件： ``` from agentlogparser import convert convert( r"C:\Users\alice\.codex", "timeline.jsonl", format="jsonl", ) ``` `format` 接受 `json`、`jsonl` 或 `csv`。Python 函数接受 `str`、`pathlib.Path` 以及其他 `os.PathLike` 值。`parse`、`to_json`、 `to_jsonl`、`to_csv` 和 `convert` 会公开 `follow_symlinks`、 `max_line_size` 和 `max_content_size`。大小值为 `0` 将禁用相应的 限制。 ## 输出 schema 所有受支持的 provider 使用相同的 `TimelineEvent` 字段和 CSV 列。 特定于 provider 的记录会映射到公共的 `provider`、`event_type`、 `source` 和 `artifact` 字段。 | Field | Description | |---|---| | `schema_version` | 输出 schema 版本 | | `event_id` | 确定性的 SHA-256 事件标识符，由 provider 命名空间划分 | | `sequence` | 确定性 timeline 排序后从零开始的位置 | | `provider` | 生成该事件的解析器的标识符，或为 `unknown` | | `source_file_sha256` | 完整源 JSONL 文件的 SHA-256（如果可用） | | `timestamp` | UTC RFC 3339 timestamp 或 `null` | | `timestamp_source` | `embedded`、`referenced_event`、`filesystem_modified` 或 `none` | | `timestamp_raw` | 原始 timestamp 值（如果存在） | | `event_type` | 规范化的事件类型 | | `session_id` | 源 session 标识符（如果存在） | | `working_directory` | 源工作目录（如果存在） | | `message` | Prompt、消息、reasoning 文本、工具名称或可选的工具内容 | | `source` | 产物种类、provider 原生记录类型、相对路径、行号和源标识符 | | `artifact` | 引用状态、解析出的路径、版本、大小、SHA-256、媒体类型和可选内容 | | `fs_times` | 可用的文件系统修改、访问和创建 timestamp | | `warnings` | 特定于事件的警告 | | `raw` | 启用 `include_raw` 时的原始 JSON 记录 | 规范化的事件类型有： - `prompt_input` - `paste_attachment` - `image_attachment` - `orphan_cache` - `file_snapshot` - `session_start` - `developer_message` - `agent_message` - `agent_reasoning` - `tool_call` - `tool_result` - `task_state` - `token_usage` - `context_compacted` - `attachment` - `error` - `unknown` ### JSON JSON 包含完整的 `ParseReport`： ``` { "events": [], "diagnostics": [] } ``` ### JSONL JSONL 每行包含一个紧凑的 `TimelineEvent`。诊断信息不会与 timeline 事件混在一起。`write_jsonl_diagnostics` 可以单独 序列化诊断信息。 ### CSV CSV 是带有 RFC 4180 标头的 UTF-8 编码。其列包括： ``` schema_version,event_id,sequence,provider,source_file_sha256,timestamp,timestamp_raw,timestamp_source,event_type,session_id,working_directory,message,artifact_kind,source_record_type,source_relative_path,source_line,source_id,reference_status,resolved_path,snapshot_version,size,sha256,media_type,content,content_encoding,fs_modified,fs_accessed,fs_created,warnings,raw ``` `include_message` 和 `include_content` 控制是否填充这些 CSV 单元格。 原始 JSON 仅在启用 `include_raw` 时填充。 CSV 中不包含诊断信息。 ## Timestamp 处理 - 有效时使用内嵌的记录 timestamp。 - 被引用的 Claude 附件继承父事件的 timestamp，并使用 `timestamp_source = "referenced_event"`。 - 独立文件产物使用其文件系统的修改时间，并使用 `timestamp_source = "filesystem_modified"`。 - 缺失或无效的 timestamp 会产生 `timestamp = null`；解析器不会 替换为其他 timestamp。 - 相等的 timestamp 保持相等。`sequence` 提供确定性的排序。 文件系统 timestamp 可能会在收集或复制过程中发生变化。 ## 内容与 hash - 当源文件被完全读取时，源 JSONL 事件包含 `source_file_sha256`。 - 文件产物在 `artifact` 中包含大小和 SHA-256 值。 - Claude `contentHash` 值被视为不透明的 cache 标识符。 解析器会计算自己的 SHA-256 值。 - 当启用 `include_content` 时，UTF-8 内容将作为文本返回。二进制 内容会进行 Base64 编码，并标记为 `content_encoding = "base64"`。 - 仅当启用 `include_content` 时，才会包含 Codex 工具参数和结果。 工具名称在没有它的情况下依然可用。 - Claude file-history 标识符不包含原始文件路径。 解析器不会推断路径。 ## 构建与测试 ``` cargo fmt --check cargo clippy --workspace --all-targets --all-features -- -D warnings cargo test --workspace --all-features cargo build --workspace --all-features --release ``` 为本地开发构建 Python 扩展： ``` python -m pip install maturin cd python maturin develop --release ```

标签：AI智能体, PKI安全, Python, Rust, 可视化界面, 数据解析, 无后门, 日志解析, 网络流量审计, 证书伪造, 逆向工具, 通知系统