Skip to content

代码行数与 Git 历史统计 ​

这两个脚本用于回顾仓库规模和文本变更。count_code_lines.py 读取当前工作区文件;generate_code_history_dashboard.py 同时读取指定 Git 提交的第一父链和当前磁盘工作区,将两者作为独立数据范围展示。它们不调用产品发布链,但保存报告、缓存或图表会写入本地文件。

选择统计范围 ​

需要回答的问题工具与数据来源
当前目录有多少代码、注释和空行?行数统计器;默认含已跟踪文件与未被 Git 忽略的未跟踪文件,读取磁盘内容
只统计已跟踪文件?行数统计器加 --tracked-only;仍读取工作区修改后的内容,不是 HEAD 快照
某个分支或提交的规模如何变化?历史图表;默认 --ref HEAD,不含未提交或未跟踪内容

两者使用同一套文件类型和注释识别规则,但数据来源不同。比较结果时同时确认提交、工作区状态、排除规则和统计列。

统计当前目录 ​

需要 Python;使用 Git 文件筛选时还需要可用的 Git。统计器本身仅依赖 Python 标准库。从仓库根目录运行:

powershell
# 输出语言分类表,不写报告文件
py Scripts\count_code_lines.py
# 缩小到 UI 目录,输出 JSON;该文件会被创建或覆盖
py Scripts\count_code_lines.py UI --tracked-only --format json --output .codex-artifacts\code-lines.json
参数默认值与作用
位置参数 path脚本所在仓库根目录;可指定子目录或其它目录
--tracked-only默认关闭;Git 可用时只选已跟踪文件
--exclude-generated默认关闭;排除已列出的 Designer、AssemblyInfo、.g.cs、压缩 JS/CSS 等后缀,不是完整生成文件识别
--formattable,也支持 json、csv
--output默认标准输出;指定时创建父目录并写 UTF-8 文件,扫描会排除这一个输出路径

Git 正常时使用 ls-files --cached,默认另加 --others --exclude-standard。已跟踪文件不会仅因后来加入 .gitignore 而自动消失。Git 不可用或 Git 查询失败时,脚本回退目录遍历,不再应用 Git 忽略规则或 --tracked-only 筛选;不能把这种回退报告当作已跟踪文件清单。

两种扫描都排除 bin、obj、node_modules、packages 等固定目录,完整集合在 SKIP_DIRECTORIES。文件类型由扩展名及少量特殊文件名决定;Markdown、JSON、XAML、工程文件和文本也属于统计对象,Code 并不只代表可执行语句。

行数如何分类 ​

  • 非空且不只是注释的行计为 Code;同一行同时有代码和注释时只计代码。
  • 纯注释计为 Comments,其余空行计为 Blank;三者之和为物理文本行数。
  • 这是字符标记扫描,不是各语言的完整解析器。字符串转义、多行字符串、嵌套注释等复杂语法不能按编译器精度理解;Python 文档字符串也不会自动归入注释。
  • UTF-8/BOM、UTF-16 BOM 和 cp1252 回退由解码函数处理。无法读取、未识别或被判为二进制的文件会跳过;报告的跳过数不包含所有目录/生成文件排除项。

生成历史图表 ​

历史分析需要 Python、Git、所选 ref 的本地历史,以及生成 PNG 的 Pillow。PNG 优先使用 Windows 中文字体,缺少时回退默认字体,中文显示需另行检查。

HTML 默认使用仓库内的 Scripts/code_history_dashboard/ 模板,由 Python 将数据、样式和脚本打包为单个文件,不需要 Node.js、外部网页构建器或已有 HTML。打开后可离线使用;页面不会联网拉取数据,重新运行脚本才刷新统计。

总览区分当前工作区规模与 Git 历史快照。项目规模支持筛选和项目 → 目录 → 文件下钻。提交节奏按日期和粒度展示变动。CSV 按当前视图导出周快照、筛选后的项目、当前目录文件或筛选后的提交记录。

规模曲线可独立选择近 30 天、近 90 天或全部历史,也可输入日期范围。放大/缩小以当前结束日期为锚点减半/加倍显示天数,左右箭头按半个窗口前后平移,边界限制在所选 Git 历史内。局部范围的纵轴适配实际数值并显示精确行数,方便观察小幅变化;全部历史保留零基线。缩放不会改变其它周统计、提交页日期筛选或总览 CSV 导出口径。

工作区使用与行数统计器相同的 Git 文件选择和文本分类,包含未提交修改和未被忽略的未跟踪文件;排除本次生成的输出路径。工程目录通过 .csproj、.vcxproj、.fsproj、.vbproj、.shproj 识别。每个文件归最近的祖先工程目录,嵌套工程单独归属,同目录多个工程定义合并;没有工程定义的文件按顶层目录归组,因此分组可加总且不重复。这里是物理目录规模,不执行 MSBuild,不展开链接文件,也不代表某个配置的实际编译输入。Git 枚举失败会报错,不静默扫描整个目录;扫描期间发生的并发修改可能使文件来自相邻写入时点。

powershell
# 生成数据、PNG 和内置离线 HTML(首次运行也不需要外部网页构建器)
py Scripts\generate_code_history_dashboard.py
# 仅跳过 HTML 打包,仍写缓存、artifact.json 和 PNG,仍需要 Pillow
py Scripts\generate_code_history_dashboard.py --no-build

默认输出都位于脚本所在仓库的 .codex-artifacts/code-history-dashboard/,该目录已被 Git 忽略:

文件用途
index.html用于离线阅读的历史仪表盘;重新运行才刷新数据
artifact.json历史图表的数据与展示声明,以及 analysis 中的工作区和提交明细
share-card.png1080 × 1440 的摘要图片
history-cache.json复用提交、文件和周快照统计的本地缓存

输出文件可被覆盖;缓存/数据/图片先于 HTML 生成,后续打包失败不会撤销已经写入的文件。artifact.json 存在不代表 HTML 或浏览器检查成功。

参数作用
--repo、--ref选择仓库和提交,默认脚本仓库与 HEAD;不自动拉取远端历史
--output、--artifact、--share-card、--cache分别指定四种输出路径;仅设置 --repo 不会把默认输出迁到目标仓库,设置 --output 也不改变其余三项
--exclude-generated与行数统计器共用生成文件后缀规则
--refresh-cache忽略可复用缓存并重新统计,无需手工删除目录
--builder使用外部 deliver_portable_artifact.mjs 兼容链,需要 Node.js 和构建脚本
--no-build跳过 HTML 打包及 --verify/--open 分支,不跳过数据和图片生成
--verify调用外部构建器验证。未传 --builder 时从 Codex 插件缓存找构建脚本,缺失时报错
--openHTML 生成后在 Windows 打开它;默认不打开

历史图表的统计口径 ​

历史来自 git log --first-parent --reverse --diff-merges=first-parent --no-renames --numstat。合并提交按第一父提交的差异计一次;不逐一展开另一条分支的内部提交。重命名按删除加新增处理,二进制 numstat 和不在识别范围的路径不计文本变更。浅克隆或缺失历史只能支持实际可读的范围。

周期和小时/星期分布均按提交者时间 %cI 的自带日期、时刻与 UTC 偏移统计,没有统一转换为读者时区;它不等同于作者最初编写时间,也不能反推工作时长。日期快捷范围以所选历史最后日期为终点;活跃日历只显示筛选范围末尾最多 365 天,其余区间统计保留完整筛选。周从星期一开始,另支持日、月、半年和年;空周期保留,日均分母使用与历史范围相交的自然天数。切换粒度改变周期表和相应图表;周快照、语言规模、目录汇总等数据仍保持各自口径,不是所有组件都重算成所选粒度。

指标解释
新增、删除、总变更、净增长Git 文本 diff 行数;总变更=新增+删除,净增长=新增-删除,包含被识别文件中的注释和空行
日/周代码/内容快照读取每天或每周最后一个可用提交的 Git blob,按上述字符规则分类;没有新提交的日/周沿用上一提交
最近 1 周变更比较历史最后日期所在周之前的两个完整自然周。历史覆盖不足时不比较,零基数不计算百分比
改写/重构估算每周期 2 × min(新增, 删除);没有配对具体文件或语句,不能据此认定发生了语义重构
8 周趋势和节奏对比取完整周的变更量;近期窗口最多 8 周,早期基准最多 26 周,起始残周和末尾未完整周不进入基准
持续节奏变化前后各 8 个完整周的分位值相差至少 1.6 倍且较小值大于零,再筛选间隔至少 12 周的候选,最多 5 个
规模跃变与版本背景比较相邻周的代码/内容规模并筛选较大变化;附近 21 天内的 CHANGELOG 条目只是背景线索,不解释因果

界面称为“中位数”的值由 percentile 选取排序后 round((n - 1) × 0.5) 位置的一个样本;偶数样本时没有对中间两项求平均。日/周快照是按规则重新分类的结果,普通周期的 total_lines 则由选定提交的总行数和 Git 净变化反推,不能把每个中间点都称作重新读取后的精确代码规模。

这些指标反映文本规模和变动,不直接衡量功能质量、个人工作量或 AI 带来的效率。图表没有预设 AI 工具时代;语义归因需结合实际修改另行分析。

缓存、失败与验证 ​

缓存核对仓库路径、缓存版本、计数器规则和生成文件选项。同一提交可以复用;旧缓存提交位于新 ref 第一父链时增量补算,否则重建。更改历史分析算法时仍需检查 CACHE_RULES_VERSION 与缓存指纹覆盖范围,不能假定脚本任何修改都会使旧缓存失效。

现象检查顺序
当前行数与历史图表不同工作区修改、未跟踪文件、所选 ref、排除选项、代码/物理行列,以及 Git 是否回退目录扫描
找不到 builder 或 base builder默认内置页面不需要 builder;仅显式 --builder 或 --verify 时确认外部路径、配套文件及其运行依赖
Pillow is required to generate --share-card为执行脚本的 Python 环境提供 Pillow;--no-build 不跳过 PNG
切换仓库后输出仍在原位置四个默认输出路径不随 --repo 改变,按需分别指定
--verify 后仍有布局疑问查看完整构建器输出并实际检查 HTML,不能只看脚本退出码

package_html 有一条验证降级路径:外部验证非零退出但输出包含 "code":"horizontal_overflow" 时,会改用普通构建器,后者成功即可继续。它没有证明该错误只来自滚动条,也没有排除同次验证中的其它失败;因此脚本成功不等于浏览器验证全部通过。

实际页面需用浏览器检查视觉、响应式、键盘和下载。只审阅说明时无需遍历仓库历史或生成图表。

基于 MIT License 发布。