cloc-ai

基于 cloc 的代码统计工具：自动识别语言，将业务代码与测试代码分类，并生成 JSON、CSV、Markdown 汇总表。

报告明确拆分业务代码和测试代码，分别展示文件数、空行、注释行、代码行、语言明细和代码行占比。报告同时公开统计原理、分类规则、硬排除、判断证据、降级条件和 cloc 计数口径。输出包括 cloc-ai.md、cloc-ai.json、cloc-ai-rules.json、cloc-ai.csv、business-code.csv 和 test-code.csv。

.md 和 .markdown 文档始终排除，不计入业务代码或测试代码；报告会显示排除的 Markdown 文档数量。

核心模式不是让路径规则猜测最终分类，而是让 Code Agent 先理解工程、逐文件生成 cloc-ai.classification.v1 语义分类清单，再由 cloc 对业务代码和测试代码分别精确计数：

cloc-ai . --classification .\cloc-ai.classification.json -o cloc-ai-report

语义分类是默认强制要求。只有明确接受较低准确性时才使用 --heuristic，报告会标记 heuristic-fallback：

cloc-ai . --heuristic -o cloc-ai-report

npm 快速安装

npx @tonyclaw/cloc-ai install --host codex
npx @tonyclaw/cloc-ai install --host claude-code
npx @tonyclaw/cloc-ai install --host opencode
npx @tonyclaw/cloc-ai install --host coding-agent

默认安装到用户范围；项目范围使用 --scope project。也可以不安装 Skill，直接统计：

npx @tonyclaw/cloc-ai run . --classification .\cloc-ai.classification.json -o cloc-ai-report

python -m cloc_ai . --classification .\cloc-ai.classification.json -o cloc-ai-report
# 或源码直接运行
$env:PYTHONPATH = "src"
python -m cloc_ai project-a --classification project-a\cloc-ai.classification.json -o report-a
python -m cloc_ai project-b --classification project-b\cloc-ai.classification.json -o report-b

需要 Python 3.9+。Skill 首次执行时会把固定版本的官方 cloc 自动安装到自身的 tools/cloc/；如果安装失败，会自动回退使用本机 PATH 中的 cloc。仅当两者均不可用时才会报错。可通过 pip install -e . 安装 cloc-ai 命令。

Agent Skill 安装

先在本仓库执行 pip install -e .，再按 Agent 的技能目录约定复制或链接 skills/cloc-ai：

• Claude Code：.claude/skills/cloc-ai
• Codex：.codex/skills/cloc-ai 或用户技能目录
• OpenCode：使用其兼容的 skills 目录加载 SKILL.md

支持 SubAgents 的环境可按项目并行统计；不支持时 CLI 会顺序处理多个项目。