yield-audit

技能简介

yield-audit 是一款完全本地化的命令行审计工具，专门用来回答一个困扰许多团队的问题：AI 编程代理到底产出了多少真正有用的代码？

传统的用量工具（ccusage 等）告诉你花了多少钱，但 yield-audit 告诉你那些钱换来了什么。它通过交叉比对 AI 编程代理的 Session 转录文件与 Git 提交历史，量化代码的真实存活率、浪费成本、重试税、AI 与人类代码的重做率差异。

一句话定位：本地化、AI 编程代理专项、无网络依赖的代码产出审计工具。

核心能力

yield-audit 提供 12 个量化视角（Lens），覆盖代码存活、成本归属、验证缺口、AI 重做率等多个维度：

工作原理

yield-audit 的审计链路分为四层：

① Session 发现层 — 自动扫描 Claude Code（~/.claude/projects）和 Codex CLI（~/.codex/sessions）的转录文件目录，读取 AI 代理的 Session 元数据。

② 关联匹配层 — 将每个 Session 与对应提交建立关联，匹配逻辑基于：文件交集 × 时间窗口（默认 24 小时，可配置 --proximity-hours）。Pair Programming 和手动提交会被标记为低置信度。

③ Git Blame 快照层 — 在指定的 horizons（默认 7 天和 30 天）对每个提交打快照，用 git blame --porcelain 对比当前代码，若行被后续提交修改或删除则标记为「未存活」。

④ 报告聚合层 — 将所有指标聚合成文本、JSON、Markdown 三种格式输出；支持 Perfetto 时序图导出（需安装 yield-audit[perfetto]）。

整个过程完全只读：只读取转录文件和 Git 历史，不向任何外部服务发送数据。

安装配置

方式一：pip 安装

pip install yield-audit

方式二：uv 安装

uv tool install yield-audit

方式三：一次性运行（无需安装）

uvx yield-audit audit --repo /path/to/your/repo

环境要求

• Python ≥ 3.10
• Git CLI（需在 PATH 中）
• 无其他运行时依赖
• 完全离线运行，无网络请求

使用步骤

以下为完整使用流程，从安装到生成报告：

第一步：安装工具（任选一种方式）

pip install yield-audit

第二步：运行环境检查（验证 git 和转录文件路径）

yield-audit doctor --repo /path/to/your/repo

第三步：对指定仓库执行完整审计

yield-audit audit --repo /path/to/your/repo

默认扫描所有已安装代理的转录文件，输出 M1–M11 核心指标。

第四步：导出结构化报告（用于 CI 或数据存档）

# JSON 格式详细报告
yield-audit audit --repo . --format json --details > yield-report.json

# Markdown 格式，适合人类阅读
yield-audit audit --repo . --format markdown > yield-report.md

第五步：AI 转型前后对比（指定分界日期）

# 对比 2026-03-01 前后的 AI vs 人类产出质量
yield-audit aidd --repo . --split 2026-03-01 --days 90

第六步（可选）：预热缓存，提升定期审计速度

# cron 友好：提前生成 blame/tree 缓存
yield-audit snapshot --repo .

适用场景

场景一：团队引入 AI 编程工具后的效果评估

团队声称 AI 帮大家提效了 40%，但 yield-audit 能告诉你有多少提交在两周内被重做。22% 的产出是 rework — 这个数字才是真实水平。

场景二：识别 AI 编程的验证缺口

通过 M8（验证缺口率）发现某个阶段大量 Session 在提交前从未运行过测试或 linter，早于 CI 失败发现问题。

场景三：AI vs 人类代码质量对比

用 M11/M12 量化 AI 标记代码的重做率是否真的高于人类代码，打破主观印象，用数据说话。

场景四：CI/CD 集成实现自动化质量门禁

配合 GitHub Actions，在每次 PR 时自动运行 yield-audit，将输出存活率、重做率作为代码质量的量化指标之一。

场景五：个人开发者追踪自己的 AI 使用效率

在个人项目中单独运行 yield-audit audit --repo .，了解自己的 AI 代理产出质量和浪费情况。

适用人群

• 工程团队负责人：评估 AI 编程工具 ROI，量化团队产出质量
• DevOps/平台工程师：建立 AI 编程能力引入前后的基线对比
• AI 编程工具使用者（个人）：自我复盘，了解自己的 AI 辅助效率
• 安全/合规团队：确保 AI 编程工具使用符合内部代码质量要求
• 初创公司 CTO：在引入 AI 编程工具时建立量化指标体系

官方链接

• PyPI 项目页面：https://pypi.org/project/yield-audit/
• GitHub 仓库：https://github.com/ictechgy/yield-audit