代码分析工具包免费版
概述
代码分析工具包免费版为个人开发者提供 Git 历史自查能力。工具将提交历史聚合为描述性统计(提交频率、文件变更模式、提交规范使用率、Bug 修复率等),并生成自我反思报告。
重要原则:本工具输出的是对 Git 历史的描述性画面,不是对个人能力的评判。代码审查、设计、指导、运维等贡献在 Git 历史中不可见,应将分析结果作为讨论起点,而非结论。
核心能力
1. 使用政策(必须遵守)
本工具处理个人 Git 活动数据,使用前必须确认:
| 要求 | 说明 |
|---|---|
| 自我反思 | 仅分析当前本地 Git 用户自己的仓库 |
| 非惩罚性 | 不用于绩效、排名、薪酬等 HR 决策 |
| 不监控 | 不用于监控他人或非同意的贡献者 |
| 合规 | 遵守适用的隐私和劳动法规 |
输入: 用户提供使用政策(必须遵守)所需的指令和必要参数。 处理: 按照skill规范执行使用政策(必须遵守)操作,遵循单一意图原则。 输出: 返回使用政策(必须遵守)的执行结果,包含操作状态和输出数据。
2. 六大分析维度
| 维度 | 分析内容 | 注意事项 |
|---|---|---|
| 提交纪律 | 频率、消息长度、规范符合 | 仅反映 Git 可见部分 |
| 节奏一致性 | 提交时间分布 | 时区、批量提交会失真 |
| 变更模式 | 代码变动量、重做率 | 高变动可能是探索性开发 |
| 代码质量标记 | Bug 修复率、回退率 | 基于提交标签,非实际缺陷 |
| 代码风格 | 规范提交、Issue 引用 | 反映工具采用度,非技能 |
| 节奏密度 | 活动集中度 | 稀疏不等于低效 |
输入: 用户提供六大分析维度所需的指令和必要参数。 处理: 按照skill规范执行六大分析维度操作,遵循单一意图原则。 输出: 返回六大分析维度的执行结果,包含操作状态和输出数据。
3. 自我反思叙事
报告以叙事形式呈现,包含:
- 支持性观察(基于具体数据)
- 需结合上下文考虑的要点
- 个人反思提示
报告不包含:
- 0-100 的综合评分
- S/A/B/C/D/E/F 等级
- 一句话评判
- 排行榜或对比表
输入: 用户提供自我反思叙事所需的指令和必要参数。 处理: 按照skill规范执行自我反思叙事操作,遵循单一意图原则。 输出: 返回自我反思叙事的执行结果,包含操作状态和输出数据。
4. 多格式输出
| 格式 | 适用场景 | 命令参数 |
|---|---|---|
| Markdown | 默认,版本控制友好 | -f markdown |
| JSON | 程序化处理 | -f json |
| HTML | 网页展示 | -f html |
| 归档打印 | -f pdf |
输入: 用户提供多格式输出所需的指令和必要参数。 处理: 按照skill规范执行多格式输出操作,遵循单一意图原则。 输出: 返回多格式输出的执行结果,包含操作状态和输出数据。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：历史自查工具、生成提交模式、质量指标的描述性、面向个人开发者的、生成描述性的提交、模式分析报告、核心能力、个人提交模式分析、合并率、代码风格标记、提交规范、代码质量指标、复杂度、自我反思叙事报告等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。
使用场景
场景一: 个人开发习惯自查
开发者回顾自己的提交习惯,寻找改进空间。
# 生成个人自查报告
python -m src.main --i-have-consent -r /path/to/my-repo
# 指定时间范围
python -m src.main --i-have-consent -r /path/to/my-repo \
-s 2026-01-01 -u 2026-06-30 \
-f markdown -o my-reflection.md
输出示例:
个人 Git 历史自查报告
=====================================
使用须知:
- 本报告描述 Git 历史,不描述个人能力
- 代码审查、设计、指导等贡献在此不可见
- 高/低值通常有多种合理解释
反思叙事:
观察: 你的提交频率在工作日较为稳定,周末提交较少。
这可能是健康工作节奏的体现。
考虑点: 提交消息平均长度为 45 字符,有改进空间。
较长的提交消息有助于团队理解变更意图。
反思提示: 你的 Bug 修复占比为 18%。
这是否反映了测试覆盖的不足?还是正常的新功能迭代?
提交模式:
- 总提交数: 156
- 平均提交大小: 23 行
- 合并提交占比: 12%
- 提交消息平均长度: 45 字符
代码质量标记:
- Bug 修复占比: 18%
- 回退提交占比: 3%
- 测试文件变更占比: 22%
场景二: 代码提交质量回顾
定期回顾提交质量,改进提交习惯。
# 季度提交质量回顾
python -m src.main --i-have-consent -r /path/to/my-repo \
-s 2026-04-01 -u 2026-06-30 \
-f html -o quarterly-review.html
# 对比格式
python -m src.main --i-have-consent -r /path/to/my-repo \
-f "markdown,html" -o quarterly-report
场景三: 开发效率自我评估
通过提交模式评估自己的开发效率。
# 月度自查
python -m src.main --i-have-consent -r /path/to/my-repo \
-s 2026-07-01 -u 2026-07-31 \
-f markdown -o monthly-reflection.md
不适用场景
以下场景代码分析工具包免费版不适合处理：
- 实时流数据处理
- 小规模数据手动分析
- 非结构化文本情感分析
触发条件
需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。
快速开始
依赖详情
# 安装必需依赖
pip install gitpython pydriller radon tabulate jinja2 click reportlab
# PDF 高质量输出(可选)
pip install weasyprint
第二步: 运行分析
# 基本用法(必须包含 --i-have-consent)
python -m src.main --i-have-consent -r /path/to/my-repo
# 指定输出格式
python -m src.main --i-have-consent -r /path/to/my-repo -f html -o report.html
# 多格式输出
python -m src.main --i-have-consent -r /path/to/my-repo \
-f "markdown,html,pdf" -o report
第三步: 查看报告
报告以使用须知开头,阅读时注意:
- 数字描述的是 Git 历史,不是个人
- 许多贡献在 Git 历史中不可见
- 高/低值有多种合理解释,先问再下结论
示例
CLI 参数
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--repo-path | -r | 仓库路径 | 必需 |
--i-have-consent | 使用政策确认(必需) | 必需 | |
--since | -s | 开始日期(ISO) | 无 |
--until | -u | 结束日期(ISO) | 无 |
--branch | -b | 分析的分支 | 当前分支 |
--format | -f | 输出格式 | markdown |
--output | -o | 输出路径 | stdout |
分析维度详解
| 维度 | 指标 | 说明 |
|---|---|---|
| 提交纪律 | 提交频率 | 每日/周/月提交数 |
| 消息长度 | 平均提交消息字符数 | |
| 规范符合 | Conventional Commits 占比 | |
| 节奏一致性 | 时间分布 | 活跃时段分布 |
| 连续性 | 提交连续天数 | |
| 变更模式 | 代码变动 | 每次提交变更行数 |
| 重做率 | 同文件反复修改率 | |
| 代码质量 | Bug 修复率 | 标记为 fix 的提交占比 |
| 回退率 | revert 提交占比 | |
| 测试变更 | 测试文件修改占比 | |
| 代码风格 | 规范提交 | Conventional Commits 使用 |
| Issue 引用 | 提交中引用 Issue 的占比 |
最佳实践
1. 正确理解报告
报告是什么:
- 对 Git 历史的描述性汇总
- 以观察和讨论提示形式呈现
- 每个指标都有具体数据支撑
报告不是什么:
- 不是个人能力评分
- 不是绩效评估工具
- 不是排名或对比依据
2. 拒绝不当使用
以下使用方式必须拒绝:
不可接受的使用:
- "对比 Alice 和 Bob 谁更努力" (排名个人)
- "看看谁最摸鱼" (监控/羞辱)
- "找出绩效不行的同事" (HR 决策)
- "给每个人打分,决定裁谁" (惩罚性使用)
3. 稀疏节奏的正确理解
稀疏提交不等于低效:
- 架构师、审查者、值班工程师自然产生稀疏提交
- 代码审查、设计、指导等贡献不在 Git 中
- 休假、轮班等正常生活也会导致稀疏
正确做法:
- 将稀疏视为"提交集中在某段时间"
- 不要等同于"工作不努力"
- 结合实际工作上下文理解
4. 本地运行保证
数据安全:
- 工具完全在本地运行
- 不向外部服务器传输数据
- 生成的报告包含个人信息,需安全存储
- 不要公开发布包含个人数据的报告
常见问题
Q1: 免费版可以分析其他开发者的提交吗?
不可以。免费版默认仅分析当前本地 Git 用户(自我范围)。分析其他人需要明确同意机制,请使用 PRO 版。
Q2: 报告会给出评分或等级吗?
不会。报告是描述性的,不包含综合评分、字母等级或评判性结论。这是设计决策,防止被用作个人评分卡。
Q3: --i-have-consent 参数可以跳过吗?
不能。这是硬性门禁,没有环境变量绕过方式。不提供此参数,工具会打印使用须知并退出。
Q4: 分析大仓库会很慢吗?
是的。10万+提交的仓库分析可能需要较长时间,建议限制日期范围(-s 和 -u 参数)。
Q5: Python 复杂度分析支持其他语言吗?
不支持。复杂度分析依赖 radon,仅适用于 .py 文件。其他语言文件的复杂度不分析。
Q6: 报告可以用于团队复盘吗?
免费版仅支持自我分析。团队复盘(多作者)需要 PRO 版的同意管理机制。
依赖说明
运行环境
- Agent 平台: 支持读取 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等)
- 操作系统: Windows / macOS / Linux
- Python: 3.8 或更高版本
- Git: 已安装且待分析仓库存在
第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由 Agent 内置 LLM 提供 |
| gitpython | Python 库 | 必需 | pip install gitpython |
| pydriller | Python 库 | 必需 | pip install pydriller |
| radon | Python 库 | 必需 | pip install radon |
| tabulate | Python 库 | 必需 | pip install tabulate |
| jinja2 | Python 库 | 必需 | pip install jinja2 |
| click | Python 库 | 必需 | pip install click |
| reportlab | Python 库 | PDF 必需 | pip install reportlab |
| weasyprint(可选) | Python 库 | PDF 推荐 | pip install weasyprint |
API Key 配置
- 本工具完全在本地运行,无需外部 API Key
- 分析过程不传输数据到外部服务器
可用性分类
- 分类: MD+EXEC+SCRIPT(Markdown 指令 + 命令行执行 + Python 分析脚本)
- 说明: 通过自然语言指令驱动 Agent 执行 Git 历史分析脚本
- 离线可用: 是,完全在本地运行,不传输数据
错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |
已知限制
- 本地运行，不支持多设备同步
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
评论
加载中…