Tokenscope

🚀 令牌范围

TokenScope 是一款用于高效分析代码库并与大语言模型（LLM）交互的工具。它整合了 FastMCP 和 tiktoken，旨在借助大型语言模型对代码库开展高效的上下文分析。

🚀 快速开始

以下是一个简单的使用示例：

from tokenscope import create_client

# 创建客户端
client = create_client()

# 扫描目录结构
structure = client.scan_directory_structure("path/to/directory")

# 提取文件内容
content = client.extract_file_content("path/to/file.py")

# 分析 token 使用情况
analysis = client.analyze_token_usage("path/to/directory")

print(structure)
print(content)
print(analysis)

✨ 主要特性

• 目录结构扫描：以 token 有效的方式扫描并返回目录结构。
• 文件内容提取：提取特定文件的内容，考虑 token 限制和格式。
• 文件搜索：根据指定模式在目录结构中搜索文件。
• token 使用分析：分析目录或文件的 token 使用情况，估算 LLM 处理需求。
• 生成报告：生成包含目录统计信息的综合 Markdown 报告。
• 文件复制：将文件从源路径复制到目标路径。

📦 安装指南

通过 pip 安装

pip install token-scope

克隆仓库并安装

git clone https://github.com/yourusername/token-scope.git
cd token-scope
python -m pip install .

💻 使用示例

基础用法

from tokenscope import create_client

# 创建客户端
client = create_client()

# 扫描目录结构
structure = client.scan_directory_structure("path/to/directory")

# 提取文件内容
content = client.extract_file_content("path/to/file.py")

# 分析 token 使用情况
analysis = client.analyze_token_usage("path/to/directory")

print(structure)
print(content)
print(analysis)

高级用法

以下展示了使用 TokenScope 各个功能的代码示例：

# 扫描目录结构
scan_directory_structure(
    path: str, 
    depth: int = 3,
    max_tokens: int = 10000,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

# 提取特定文件的内容
extract_file_content(
    file_path: str, 
    max_tokens: int = 10000,
    sample_only: bool = False
)

# 根据指定模式搜索目录中的文件
search_files_by_pattern(
    directory: str,
    patterns: list[str],
    max_depth: int = 5,
    include_content: bool = False,
    max_files: int = 100,
    max_tokens_per_file: int = 1000,
    sample_only: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

# 分析指定路径的 token 使用情况
analyze_token_usage(
    path: str,
    include_file_details: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

# 生成包含统计信息的 Markdown 报告
generate_directory_report(
    directory: str, 
    depth: int = 3,
    include_file_content: bool = True,
    max_files_with_content: int = 5,
    max_tokens_per_file: int = 1000,
    sample_only: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

# 复制文件到指定路径
copy_file_to_destination(
    source_path: str,
    destination_path: str
)

📚 详细文档

scan_directory_structure

扫描目录并返回其结构，考虑 token 限制。

scan_directory_structure(
    path: str, 
    depth: int = 3,
    max_tokens: int = 10000,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

extract_file_content

提取特定文件的内容，考虑 token 限制和格式。

extract_file_content(
    file_path: str, 
    max_tokens: int = 10000,
    sample_only: bool = False
)

search_files_by_pattern

根据指定模式搜索目录中的文件。

search_files_by_pattern(
    directory: str,
    patterns: list[str],
    max_depth: int = 5,
    include_content: bool = False,
    max_files: int = 100,
    max_tokens_per_file: int = 1000,
    sample_only: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

analyze_token_usage

分析指定路径的 token 使用情况。

analyze_token_usage(
    path: str,
    include_file_details: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

generate_directory_report

生成包含统计信息的 Markdown 报告。

generate_directory_report(
    directory: str, 
    depth: int = 3,
    include_file_content: bool = True,
    max_files_with_content: int = 5,
    max_tokens_per_file: int = 1000,
    sample_only: bool = False,
    ignore_patterns: list[str] | None = None,
    include_gitignore: bool = True,
    include_default_ignores: bool = True
)

copy_file_to_destination

复制文件到指定路径。

copy_file_to_destination(
    source_path: str,
    destination_path: str
)

🔧 技术细节

TokenScope 自动忽略以下常见目录和文件：

DEFAULT_IGNORE_PATTERNS = [
    ".git/",
    ".venv/",
    "venv/",
    "__pycache__/",
    "node_modules/",
    ".pytest_cache/",
    ".ipynb_checkpoints/",
    ".DS_Store",
    "*.pyc",
    "*.pyo",
    "*.pyd",
    "*.so",
    "*.dll",
    "*.class",
    "build/",
    "dist/",
    "*.egg-info/",
    ".tox/",
    ".coverage",
    ".idea/",
    ".vscode/",
    ".mypy_cache/",
]

📄 许可证

本项目 licensed under the MIT License - 详见 LICENSE 文件。

致谢

• 结合了 FastMCP
• 使用 tiktoken 进行 token 化