| name | repo-tokens-count |
| description | 为 GitHub 项目添加 token count badge,显示代码库规模及其占 LLM 上下文窗口的比例。当用户需要展示代码规模、添加 token 统计 badge 时触发。 |
Repo Tokens Count Skill
为 GitHub 项目添加自动化的 token 统计 badge,显示代码库规模及其相对于 LLM 上下文窗口的占比。
功能
- 自动计算代码库的 token 数量
- 生成彩色 SVG badge(绿色/黄绿/黄色/红色根据占比自动调整)
- 支持自定义统计的文件范围和排除规则
- 支持自定义 LLM 上下文窗口大小
- 通过 GitHub Actions 自动更新
使用方式
用户使用示例:
为当前项目添加 token count badge
或
给 https://github.com/user/repo 添加 token badge,统计 src 目录下的 ts 文件
工作流程
1. 分析项目结构
- 检查项目类型和主要语言
- 识别源代码目录结构
- 确认 README.md 位置
2. 创建 GitHub Actions Workflow
在 .github/workflows/tokens.yml 创建 workflow:
name: Token Count Badge
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: write
jobs:
update-badge:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: qwibitai/nanoclaw/repo-tokens@main
with:
include: '<glob-pattern>'
exclude: '<exclude-pattern>'
context-window: 200000
badge-path: 'badge.svg'
- name: Commit changes
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add README.md badge.svg
git diff --cached --quiet || git commit -m "docs: update token count badge"
git push
3. 修改 README.md
在 README 中添加以下内容(注意:图片 badge 放在标记之外,避免被 action 覆盖):
# Project Name
<a href="https://github.com/qwibitai/nanoclaw/tree/main/repo-tokens"><img src="badge.svg" alt="Token count badge"></a>
<!-- token-count --><!-- /token-count -->
项目描述...
4. 提交并推送
git add -A
git commit -m "feat: add token count badge"
git push
参数说明
| 参数 | 必填 | 默认值 | 说明 |
|---|
include | 是 | - | Glob 模式,指定统计的文件 |
exclude | 否 | '' | 排除的文件模式 |
context-window | 否 | 200000 | LLM 上下文窗口大小(Claude Opus 为 200k) |
badge-path | 否 | '' | SVG badge 输出路径,为空时只更新文字 |
readme | 否 | README.md | README 文件路径 |
encoding | 否 | cl100k_base | Tiktoken 编码方式 |
Badge 颜色含义
- 🟢 绿色 (< 30%):代码库很小,轻松放入上下文
- 🟡 黄绿 (30-50%):适中,可以放入上下文
- 🟠 黄色 (50-70%):较大,需要注意
- 🔴 红色 (70%+):很大,可能需要分段处理
常见项目配置示例
TypeScript 项目
include: 'src/**/*.ts'
exclude: 'src/**/*.test.ts,src/**/*.spec.ts'
Python 项目
include: 'src/**/*.py'
exclude: '**/test_*.py,**/tests/**/*.py'
多语言项目
include: 'src/**/*.{ts,js,py}'
exclude: '**/node_modules/**,**/__pycache__/**'
故障排除
Badge 不显示图片只显示文字
确保:
- 设置了
badge-path: 'badge.svg'
- README 中
<img src="badge.svg"> 放在 <!-- token-count --> 标记之外
- Workflow 中
git add 包含 badge.svg
Action 运行失败
检查:
- 仓库是否有
main 分支(或修改 workflow 中的分支名)
permissions 是否包含 contents: write
- 如果是空仓库,先创建初始提交
参考