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)

高級用法

# 這裡可以根據不同的 API 組合使用，實現更復雜的功能，例如先搜索文件，再提取文件內容並分析 token 使用情況
from tokenscope import create_client

client = create_client()
files = client.search_files_by_pattern("path/to/directory", ["*.py"])
for file in files:
    content = client.extract_file_content(file)
    analysis = client.analyze_token_usage(file)
    print(f"File: {file}, Content: {content}, Token Analysis: {analysis}")

📚 詳細文檔

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/",
]

📄 許可證

本項目遵循 MIT 許可證 - 詳見 LICENSE 文件。

致謝

• 結合了 FastMCP
• 使用 tiktoken 進行 token 化