Hotdry.
归档
ai-systems

代码库 LLM 上下文适配徽章：递归 token 估算与 fit-score

递归扫描仓库，使用 tiktoken 等工具估算总 tokens，并计算对 Claude/GPT 等 LLM 上下文窗口的适配分数，生成可视化徽章，便于预分析代码库规模。

在 LLM 驱动的代码代理时代，整个代码库能否完整塞入模型上下文窗口已成为关键指标。小型代码库不仅便于调试，还能让代理一次性理解全局架构，避免 RAG 或 chunking 引入的幻觉与延迟。qwibitai/nanoclaw 项目中的 repo-tokens 工具正是为此设计：通过 GitHub Action 递归扫描仓库，精确估算 tokens，并生成 “上下文适配徽章”（context fit badge），直观显示代码库占用比例。该徽章采用 shields.io 风格，颜色编码（绿色 < 30%、黄色 50-70%、红色 > 70%），默认针对 200k tokens 的 Claude 模型窗口，帮助开发者量化 “agent-friendly” 程度。

核心实现：递归扫描与语言特定 token 估算

repo-tokens 的扫描逻辑简洁高效，仅约 60 行内嵌 Python 代码，利用 tiktoken 库（OpenAI 官方 tokenizer）处理多语言文件。流程如下：

  1. 文件遍历：从 repo 根目录递归走查，自动尊重 .gitignore、.dockerignore 等模式，跳过二进制（如 .png、.bin）、构建产物（如 node_modules/、dist/）和测试数据。自定义忽略列表可扩展，支持正则过滤大型 vendor 目录。

  2. 语言特定估算：非简单字符计数，而是加载 tiktoken 的 cl100k_base 编码器（适用于 GPT-4/Claude 近似），逐文件读取 UTF-8 内容，计算精确 tokens。Tiktoken 支持 Python、JS、Rust、Go 等主流语言的 BPE 分词，平均误差 <5%。例如，nanoclaw repo 总计 34.9k tokens，其中 TS 文件占 70%、MD 文档 15%、其余配置 / YAML 15%。

  3. 聚合与输出：累加所有文件 tokens，生成 JSON 摘要（{"total_tokens": 34900, "files": 150, "largest": "src/index.ts:2500"}），并计算 fit-score：fit = min(100, repo_tokens / context_window * 100)。默认 context_window=200000（Claude 3.5 Sonnet），支持多模型配置如 { "claude-sonnet": 200000, "gpt-4o": 128000, "grok-beta": 131072 }。

扫描耗时约 10 秒（中小 repo），无需外部 API 调用，全离线运行。徽章 URL 示例：https://img.shields.io/badge/LLM%20context%20fit-17%25-brightgreen?style=flat&amp;logo=claude ，嵌入 README 实时更新。

如 nanoclaw README 所示：“34.9k tokens, 17% of context window”。

配置参数与落地清单

要集成到自家 repo，复制 repo-tokens 作为 composite Action，定义 .github/workflows/token-badge.yml：

name: Update Context Badge
on: [push, pull_request]
jobs:
  tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: qwibitai/repo-tokens@main  # 或本地路径
        id: tokens
        with:
          context-windows: |  # YAML 多行配置
            claude: 200000
            gpt4o: 128000
          ignore-patterns: |  # 自定义忽略
            - '**/*.min.js'
            - 'tests/fixtures/**'
          tiktoken-model: cl100k_base  # 或 p50k_base for GPT-3.5
      - name: Update README
        run: |
          sed -i "s|&lt;!-- TOKEN_BADGE --&gt;|\${{ steps.tokens.outputs.badge_md }}|g" README.md
        # 后续 commit/push 由 workflow 控制，避免循环

关键参数：

  • context-windows：JSON/YAML 映射，多徽章支持（如并排 Claude & GPT）。
  • tiktoken-model：cl100k_base（推荐，覆盖 99% 现代 LLM）；r50k_base 旧模型。
  • max-file-size：默认 1MB，超大文件采样前 N tokens 避免 OOM。
  • color-thresholds：自定义 {green: 30, yellow: 70}，红色默认 >70%。
  • output-format：badge_md（Markdown）、json 或 csv，便于 CI 告警（如 fit>80% 失败 build）。

回滚策略：Action 不自动 commit，使用 git diff 检查变化，阈值超标时通知 Slack / 邮件。监控点：tokens 增长率（周环比 >20% 告警）、fit-score 趋势（Grafana dashboard 嵌入 repo metrics）。

工程化优化与风险控制

为大 repo（>500k tokens），分层采样：先估算目录级 tokens，优先核心模块（如 src/ 80% 权重）。结合 tree-sitter 解析器，可进一步语言特定优化（如忽略 JS minified 代码的压缩 tokens）。

风险：

  1. 估算偏差：tiktoken 为 OpenAI 优化，Claude Sonnet 实际 tokens 可能 +10-20%（BPE 差异）。缓解：基准测试自家 repo 与官方 tokenizer API。
  2. 性能瓶颈：10k+ 文件 repo 扫描 >1min。优化：缓存上周 tokens，仅增量 diff。
  3. 隐私：纯本地计算，无上传。但 CI 跑在 GitHub runner，敏感 repo 用 self-hosted。

实际落地参数示例：

LLM 模型 窗口大小 绿色阈值 理想 repo tokens
Claude 3.5 Sonnet 200k <60k <30k
GPT-4o 128k <38k <20k
Gemini 1.5 Pro 1M+ <300k <100k

此徽章不仅是美化，更是文化信号：鼓励 “最小 viable codebase”，优先重构而非膨胀。集成后，每 PR 即见 fit-score 变化，推动团队自律。

总结与扩展

repo-tokens 证明：LLM 时代，tokens 即新 LOC，徽章化指标驱动行为变革。未来可扩展到多 repo monorepo（加权平均 fit）、动态窗口（API 查询最新模型 spec）。

资料来源：

（正文字数：1256）

查看归档