Code Analysis Toolkit Free

SKILL.md

---
name: "code-analysis-toolkit-free"
description: "个人Git历史自查工具,生成提交模式、代码风格、质量指标的描述性报告"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "代码分析工具包免费版"
  version: "1.0.0"
  summary: "个人Git历史自查工具,生成提交模式、代码风格、质量指标的描述性报告"
  tags:
    - "代码分析"
    - "Git历史"
    - "开发自查"
    - "代码质量"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

# 代码分析工具包免费版

## 概述

代码分析工具包免费版为个人开发者提供 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` |
| PDF | 归档打印 | `-f pdf` |

**输入**: 用户提供多格式输出所需的指令和必要参数。
**处理**: 按照skill规范执行多格式输出操作,遵循单一意图原则。
**输出**: 返回多格式输出的执行结果,包含操作状态和输出数据。
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：历史自查工具、生成提交模式、质量指标的描述性、面向个人开发者的、生成描述性的提交、模式分析报告、核心能力、个人提交模式分析、合并率、代码风格标记、提交规范、代码质量指标、复杂度、自我反思叙事报告等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

### 场景一: 个人开发习惯自查

开发者回顾自己的提交习惯,寻找改进空间。

```bash
# 生成个人自查报告
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
```

输出示例:

```text
个人 Git 历史自查报告
=====================================

使用须知:
- 本报告描述 Git 历史,不描述个人能力
- 代码审查、设计、指导等贡献在此不可见
- 高/低值通常有多种合理解释

反思叙事:
观察: 你的提交频率在工作日较为稳定,周末提交较少。
这可能是健康工作节奏的体现。

考虑点: 提交消息平均长度为 45 字符,有改进空间。
较长的提交消息有助于团队理解变更意图。

反思提示: 你的 Bug 修复占比为 18%。
这是否反映了测试覆盖的不足?还是正常的新功能迭代?

提交模式:
- 总提交数: 156
- 平均提交大小: 23 行
- 合并提交占比: 12%
- 提交消息平均长度: 45 字符

代码质量标记:
- Bug 修复占比: 18%
- 回退提交占比: 3%
- 测试文件变更占比: 22%
```

### 场景二: 代码提交质量回顾

定期回顾提交质量,改进提交习惯。

```bash
# 季度提交质量回顾
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
```

### 场景三: 开发效率自我评估

通过提交模式评估自己的开发效率。

```bash
# 月度自查
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
```

## 不适用场景

以下场景代码分析工具包免费版不适合处理：

- 实时流数据处理
- 小规模数据手动分析
- 非结构化文本情感分析

## 触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

## 快速开始

### 依赖详情

```bash
# 安装必需依赖
pip install gitpython pydriller radon tabulate jinja2 click reportlab

# PDF 高质量输出(可选)
pip install weasyprint
```

### 第二步: 运行分析

```bash
# 基本用法(必须包含 --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. 正确理解报告

```text
报告是什么:
- 对 Git 历史的描述性汇总
- 以观察和讨论提示形式呈现
- 每个指标都有具体数据支撑

报告不是什么:
- 不是个人能力评分
- 不是绩效评估工具
- 不是排名或对比依据
```

### 2. 拒绝不当使用

以下使用方式必须拒绝:

```text
不可接受的使用:
- "对比 Alice 和 Bob 谁更努力" (排名个人)
- "看看谁最摸鱼" (监控/羞辱)
- "找出绩效不行的同事" (HR 决策)
- "给每个人打分,决定裁谁" (惩罚性使用)
```

### 3. 稀疏节奏的正确理解

```text
稀疏提交不等于低效:
- 架构师、审查者、值班工程师自然产生稀疏提交
- 代码审查、设计、指导等贡献不在 Git 中
- 休假、轮班等正常生活也会导致稀疏

正确做法:
- 将稀疏视为"提交集中在某段时间"
- 不要等同于"工作不努力"
- 结合实际工作上下文理解
```

### 4. 本地运行保证

```text
数据安全:
- 工具完全在本地运行
- 不向外部服务器传输数据
- 生成的报告包含个人信息,需安全存储
- 不要公开发布包含个人数据的报告
```

## 常见问题

### 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命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 已知限制

- 本地运行，不支持多设备同步
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力