trailofbits/aicov

# aicov `aicov` 用于追踪 AI 编程代理读取了代码库中的哪些行。它会 将 AI 的读取计数映射到 LCOV 和文本格式的 `.gcov` 报告中，同时也会 生成一种原生 JSON 格式，其中包含逐行的读取计数、搜索命中、命令以及 任务元数据。 ## 安装 从此代码库安装： ``` uv tool install . ``` 通过已发布的包安装，使用相同的形式： ``` uv tool install aicov ``` 用于本地开发： ``` uv sync --dev uv run aicov --help ``` ## 快速开始 安装 Codex hooks： ``` aicov install-codex-hooks --user ``` 如果需要在代码库本地安装： ``` aicov install-codex-hooks --repo ``` 回填现有会话： ``` aicov backfill --agent auto --session-id aicov backfill --agent auto --path ~/.codex/sessions/.jsonl aicov backfill --agent pi --path ~/.pi/agent/sessions//.jsonl ``` 生成报告： ``` aicov report --format lcov --counts full --out aicov.info aicov report --format gcov --counts binary --out-dir coverage-gcov aicov html --out aicov.html aicov summary aicov unread --limit 20 ``` 使用标准工具渲染 LCOV： ``` genhtml aicov.info --output-directory coverage-html ``` ## 捕获内容 - 来自 `Bash`、`apply_patch` 和 MCP 工具的 Codex hook payload。 - 通过 session id 或 JSONL 路径，对 Codex、Claude Code 和 Pi 的记录进行回填。 在回填 Pi 会话路径时，通过 `parentSession` 关联的 Pi 子会话也会被包含在内。 - 常见的 shell 读取操作：`sed`、`head`、`tail`、`cat`、`awk` 和 `nl|sed`。 - `rg` 和 `grep` 的输出被作为 `search_seen` 记录，与直接读取分开。在原生 JSON 和 HTML 中，匹配行和上下文行会分别进行计数。 - 未被读取但受 Git 追踪的文本文件，这样未被触及的文件将以零覆盖率显示。 不支持的类读取 shell 形式会被记录为未知事件，而不会 被盲目猜测为全文件读取。 ## 输出 - `.aicov/events.jsonl`：仅追加的已观测读取事件。 - `.aicov/coverage.json`：原生逐文件和逐行覆盖率数据。 - `aicov.info`：兼容 `genhtml` 的 LCOV tracefile。 - `coverage-gcov/*.gcov`：文本格式的 gcov 样式文件。 - `aicov.html`：自包含的热力图报告。 `--counts full` 会将观测到的读取计数写入 LCOV/gcov 输出。`--counts binary` 会为已读取的行写入 `1`，为未读取的行写入 `0`。 原生 JSON 和 HTML 包含已读取行和范围的紧凑归属信息： agent、session id、来源、工具名称、命令、任务路径、时间戳，以及 可用时的置信度。未知事件也会被呈现出来，以便可以审计不支持的 命令，而不是让它们默默地消失。 ## 配置 当需要调整默认设置时，在代码库根目录创建 `.aicov.toml`： ``` storage_dir = ".aicov" exclude = [".aicov/", "node_modules/", "vendor/", "dist/", "build/", ".git/"] include_lockfiles = true auto_reports = ["json"] ``` `auto_reports` 控制在 Codex `Stop` 时写入的额外报告。JSON 覆盖率始终 会刷新；添加 `lcov`、`gcov` 或 `html` 以在 `.aicov/reports/` 下生成可共享的报告。 推荐的本地忽略规则： ``` .aicov/ ``` 仅当您需要持久的审计产物时，才提交或归档 `.aicov/coverage.json`、LCOV、gcov 或 HTML 输出。 ## 隐私 默认情况下，`aicov` 会存储命令、路径、行范围、时间戳、session 和 工具 ID、agent 名称以及任务归属。回填的记录可能会在 `task_path` 中包含 agent 的 prompt 或任务标签，以便报告能解释某行为何 被检查。它不会在事件日志中存储原始的工具输出或源代码片段。 原生覆盖率 JSON 和 HTML 报告包含来自事件日志的归属信息。 HTML 报告还会嵌入源代码行，因为它是一个源代码查看器；分享 这些文件时，请采取与分享代码库和记录元数据相同的谨慎态度。 ## 开发 ``` uv run pytest uv run ruff check . uv run ruff format . ```

标签：AI编程助手, API集成, Python, SOC Prime, 代码覆盖率, 可观测性, 安全规则引擎, 开发工具, 无后门, 逆向工具