Code2Prompt

Code2Prompt 是一款功能强大的命令行工具，能够从代码库中生成全面的提示词，旨在简化开发者与大型语言模型（LLM）之间的交互，以实现代码分析、文档生成和改进任务。

目录

1. 为什么选择 Code2Prompt？
2. 特性
3. 安装
4. 快速入门
5. 快速开始
6. 使用方法
7. 选项
8. 示例
9. 模板系统
10. 与 LLM CLI 集成
11. GitHub Actions 集成
12. 配置文件
13. 故障排除
14. 贡献
15. 许可证

Code2Prompt：将你的代码库转化为适合 AI 的提示词

为你的 AI 辅助开发注入强大动力

Code2Prompt 是一款功能强大且开源的命令行工具，它架起了你的代码库与大型语言模型（LLM）之间的桥梁。通过将整个项目转化为全面、适合 AI 的提示词，Code2Prompt 让你能够充分发挥 AI 在代码分析、文档生成和改进任务中的潜力。

🚀 核心功能

• 全面的代码库表示：生成结构清晰的 Markdown 提示词，完整捕捉项目的精髓，让 LLM 更容易理解上下文。
• 智能源码树生成：创建清晰的分层代码库结构视图，便于更好地导航和理解项目。
• 可自定义的提示词模板：利用 Jinja2 模板定制输出内容，以适应特定的 AI 任务，提升生成提示词的相关性。
• 智能 Token 管理：统计并优化 Token 数量，确保与各种 LLM 的 Token 限制兼容，避免处理时出错。
• Gitignore 集成：尊重项目的 .gitignore 规则，准确反映代码库内容，确保无关文件不会被纳入处理。
• 灵活的文件处理：通过强大的 glob 模式筛选和排除文件，让你掌控哪些文件会被纳入提示词生成。
• 自定义语法高亮：使用 --syntax-map 选项，为自定义文件扩展名指定特定的语法高亮。例如，你可以指定 .inc 文件应被视为 bash 脚本。
• 剪贴板就绪：即时将生成的提示词复制到剪贴板，方便快速进行 AI 对话，简化工作流程。
• 多种输出选项：保存到文件或直接在控制台显示，提供灵活的使用方式。
• 增强代码可读性：为源码块添加行号，便于精准引用，更容易讨论代码的特定部分。
• 包含文件：支持模板导入，允许模块化设计模板。
• 输入变量：支持模板中的输入变量，根据用户输入动态生成提示词。

💡 为什么选择 Code2Prompt？

• 上下文理解：为 LLM 提供项目的全面视图，以便更准确地给出建议和分析。
• 一致性提升：在整个项目中保持编码风格和规范，提高代码质量。
• 高效重构：实现更好的依赖关系分析和更智能的重构建议，节省时间和精力。
• 改善文档生成：生成符合上下文的文档，真实反映代码库内容，提升可维护性。
• 模式识别：帮助 LLM 学习并应用项目特有的模式和惯用法，提升 AI 交互的质量。

改变你与 AI 进行软件开发互动的方式。借助 Code2Prompt，你在每次 AI 对话中都能充分挖掘代码库的潜力。

准备好提升你的 AI 辅助开发水平了吗？让我们一起出发吧！🏊‍♂️

安装

选择以下任一方式安装 Code2Prompt：

使用 pip

pip install code2prompt

使用 pipx（推荐）

pipx install code2prompt

快速入门

要开始使用 Code2Prompt，请按照以下步骤操作：

1. 安装 Code2Prompt：使用上述任一安装方法。
2. 准备你的代码库：确保项目组织良好，并根据需要准备好 .gitignore 文件。
3. 运行 Code2Prompt：使用命令行从你的代码库生成提示词。

例如，要从单个 Python 文件生成提示词，运行：

code2prompt --path /path/to/your/script.py

快速开始

1. 从单个 Python 文件生成提示词：

   code2prompt --path /path/to/your/script.py
   

2. 处理整个项目目录并保存输出：

   code2prompt --path /path/to/your/project --output project_summary.md
   

3. 为多个文件生成提示词，排除测试文件：

   code2prompt --path /path/to/src --path /path/to/lib --exclude "*/tests/*" --output codebase_summary.md
   

使用方法

Code2Prompt 的基本语法为：

code2prompt --path /path/to/your/code [OPTIONS]

对于多个路径：

code2prompt --path /path/to/dir1 --path /path/to/file2.py [OPTIONS]

自定义语法高亮

要将自定义文件扩展名与特定的语法高亮关联起来，请使用 --syntax-map 选项。此选项允许您以 扩展名:语法 的格式指定映射关系。例如：

code2prompt --path /path/to/your/code --syntax-map "inc:bash,customext:python,ext2:javascript"

该命令会将 .inc 文件视为 bash 脚本，.customext 文件视为 python，.ext2 文件视为 javascript。

您也可以使用多个 --syntax-map 参数，或用逗号分隔多个映射关系：

code2prompt --path /path/to/your/script.py --syntax-map "inc:bash"

code2prompt --path /path/to/your/project --syntax-map "inc:bash,txt:markdown" --output project_summary.md

code2prompt --path /path/to/src --path /path/to/lib --syntax-map "inc:bash,customext:python" --output codebase_summary.md

选项

选项	短标志	描述
--path	-p	要处理的目录或文件的路径（必选，可指定多个）
--output	-o	输出 Markdown 文件的名称
--gitignore	-g	.gitignore 文件的路径
--filter	-f	以逗号分隔的过滤模式，用于包含文件（例如：.py,.js）
--exclude	-e	以逗号分隔的排除模式，用于排除文件（例如：.txt,.md）
--case-sensitive		执行区分大小写的模式匹配
--suppress-comments	-s	从代码文件中去除注释
--line-number	-ln	在源代码块中添加行号
--no-codeblock		禁用将代码包裹在 Markdown 代码块中
--template	-t	指定用于自定义提示生成的 Jinja2 模板文件的路径
--tokens		显示生成提示的标记数
--encoding		指定使用的分词器编码（默认：“cl100k_base”）
--create-templates		创建包含示例模板的 templates 目录
--version	-v	显示版本并退出
--log-level		设置日志级别（例如：DEBUG、INFO、WARNING、ERROR、CRITICAL）
--interactive	-i	激活交互模式以选择文件
--syntax-map		将自定义文件扩展名与特定的语法高亮关联起来（例如：“inc:bash,customext:python,ext2:javascript”）

命令参数

--filter 或 -f 与 --exclude 或 -e

--filter 和 --exclude 选项允许您指定应包含或排除处理的文件或目录的模式。

语法：

--filter "PATTERN1,PATTERN2,..."
--exclude "PATTERN1,PATTERN2,..."

或

-f "PATTERN1,PATTERN2,..."
-e "PATTERN1,PATTERN2,..."

描述：

• 两个选项都接受以逗号分隔的模式列表。
• 模式可以包含通配符 (*) 和目录指示符 (**)。
• 默认区分大小写（使用 --case-sensitive 标志可更改此行为）。
• --exclude 模式优先于 --filter 模式。

示例：

1. 只包含 Python 文件：

   --filter "**.py"
   

2. 排除所有 Markdown 文件：

   --exclude "**.md"
   

3. 包含 src 目录中的特定文件类型：

   --filter "src/**.{js,ts}"
   

4. 排除多个文件类型和特定目录：

   --exclude "**.log,**.tmp,**/node_modules/**"
   

5. 包含所有文件，但排除 'test' 目录中的文件：

   --filter "**" --exclude "**/test/**"
   

6. 复杂过滤（包含 JavaScript 文件，排除 minified 和测试文件）：

   --filter "**.js" --exclude "**.min.js,**test**.js"
   

7. 包含所有目录中的特定文件：

   --filter "**/config.json,**/README.md"
   

8. 排除临时文件和目录：

   --exclude "**/.cache/**,**/tmp/**,**.tmp"
   

9. 包含源文件，但排除构建输出：

   --filter "src/**/*.{js,ts}" --exclude "**/dist/**,**/build/**"
   

10. 排除版本控制和 IDE 特定文件：

    --exclude "**/.git/**,**/.vscode/**,**/.idea/**"
    

注意事项：

• 始终对模式使用双引号，以防止 shell 解释特殊字符。
• 模式会针对每个文件的完整路径进行匹配，相对于项目根目录。
• ** 通配符匹配任意数量的目录。
• 单个 * 匹配单个目录或文件名中的任意字符。
• 使用逗号分隔同一选项中的多个模式。
• 结合使用 --filter 和 --exclude 可实现对处理文件的精细控制。

最佳实践：

1. 先使用较宽泛的模式，再根据需要逐步细化。
2. 首先在项目的较小子集上测试您的模式。
3. 如果需要区分大小写相似的文件名，请使用 --case-sensitive 标志。
4. 对于复杂项目，建议使用配置文件管理您的过滤和排除模式。

通过有效且安全地使用 --filter 和 --exclude 选项（配合正确的引号），您可以精确控制项目中哪些文件会被处理，从而确保命令执行的准确性和安全性。

示例

1. 为 Python 库生成文档：

   code2prompt --path /path/to/library --output library_docs.md --suppress-comments --line-number --filter "*.py"
   

2. 准备代码库摘要以进行代码审查，重点关注 JavaScript 和 TypeScript 文件：

   code2prompt --path /path/to/project --filter "*.js,*.ts" --exclude "node_modules/*,dist/*" --template code_review.j2 --output code_review.md
   

3. 为 AI 模型创建输入以提出改进建议，重点关注特定目录：

   code2prompt --path /path/to/src/components --suppress-comments --tokens --encoding cl100k_base --output ai_input.md
   

4. 分析多语言项目的注释密度：

   code2prompt --path /path/to/project --template comment_density.j2 --output comment_analysis.md --filter "*.py,*.js,*.java"
   

5. 为一组特定文件生成提示，并添加行号：

   code2prompt --path /path/to/important_file1.py --path /path/to/important_file2.js --line-number --output critical_files.md
   

模板系统

Code2Prompt 支持使用 Jinja2 模板进行自定义输出格式化。要使用自定义模板：

code2prompt --path /path/to/code --template /path/to/your/template.j2

创建模板示例

使用 --create-templates 命令生成示例模板：

code2prompt --create-templates

这将在 templates 目录下创建一些 Jinja2 示例模板，包括：

• default.j2：通用模板
• analyze-code.j2：用于详细代码分析
• code-review.j2：用于全面代码审查
• create-readme.j2：帮助生成 README 文件
• improve-this-prompt.j2：用于优化 AI 提示词

有关完整模板文档，请参阅 文档模板化。

与 LLM CLI 的集成

Code2Prompt 可以与 Simon Willison 的 llm CLI 工具集成，以增强代码分析功能，或与 qllm 集成，亦或是为 Rust 爱好者提供 hiramu-cli。

安装

pip install code2prompt llm

基本用法

1. 生成代码摘要并用 LLM 进行分析：

   code2prompt --path /path/to/your/project | llm "分析这个代码库，提供其结构和潜在改进的见解"
   

2. 处理特定文件并获取重构建议：

   code2prompt --path /path/to/your/script.py | llm "为这段代码提出重构改进建议"
   

更多高级用法，请参考完整文档中的 与 LLM CLI 的集成 部分。

GitHub Actions 集成

您可以将 Code2Prompt 集成到您的 GitHub Actions 工作流中。以下是一个示例：

name: 代码分析
on: [push]
jobs:
  analyze-code:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: 设置 Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'
    - name: 安装依赖
      run: |
        pip install code2prompt llm
    - name: 分析代码库
      run: |
        code2prompt --path . | llm "对这个代码库进行全面分析。识别需要改进的地方、潜在错误，并提出优化建议。" > analysis.md
    - name: 上传分析结果
      uses: actions/upload-artifact@v2
      with:
        name: code-analysis
        path: analysis.md

理解 Code2Prompt 中的标记与标记类型

标记是语言模型处理文本的基本单元。它们可以是单词、单词的一部分，甚至标点符号。不同的分词器编码会以不同方式将文本分割成标记。Code2Prompt 通过 --encoding 选项支持多种标记类型，默认为 "cl100k_base"。这种编码被 GPT-3.5 和 GPT-4 等模型所使用，擅长处理代码和技术内容。其他常见编码还包括 "p50k_base"（用于早期 GPT-3 模型）和 "r50k_base"（用于 CodeX 等模型）。

要统计生成提示词中的标记数，使用 --tokens 标志：

code2prompt --path /your/project --tokens

对于特定编码：

code2prompt --path /your/project --tokens --encoding p50k_base

了解标记数量在使用有标记限制的 AI 模型时至关重要，确保您的提示词符合模型的上下文窗口要求。

标记价格估算

Code2Prompt 现在新增了一个强大的功能，可估算各种 AI 提供商和模型的标记价格。结合 --tokens 使用 --price 选项，即可显示详细的成本估算。此功能根据输入和输出标记计算价格，其中输入标记由您的代码库决定，默认输出标记为 1000 个（可通过 --output-tokens 自定义）。您可以指定特定提供商或模型，也可以查看所有可用选项的价格。这一功能有助于开发者做出明智的 AI 模型使用和成本管理决策。例如：

code2prompt --path /your/project --tokens --price --provider openai --model gpt-4

该命令将分析您的项目，统计标记数，并为 OpenAI 的 GPT-4 模型提供详细的价格估算。

🔥 分析代码库

code2prompt 现在提供了一个强大的功能，可分析代码库并提供文件扩展名的汇总信息。使用 --analyze 选项与 -p（路径）选项，即可获得项目文件组成的概览。例如：

code2prompt --analyze -p code2prompt

结果：

.j2: 6 个文件
.json: 1 个文件
.py: 33 个文件
.pyc: 56 个文件

以逗号分隔的扩展名列表：
.j2,.json,.py,.pyc

该命令将分析 'code2prompt' 目录，并显示所有找到的文件扩展名及其计数。您可以选择两种输出格式：

• 平铺格式（默认）：按字母顺序列出所有唯一扩展名及其文件计数。
• 树状格式：以目录树结构显示扩展名，每层都附带计数。

要使用树状格式，添加 --format tree 选项：

code2prompt --analyze -p code2prompt --format tree

结果：

└── code2prompt
    ├── utils
    │   ├── .py
    │   └── __pycache__
    │       └── .pyc
    ├── .py
    ├── core
    │   ├── .py
    │   └── __pycache__
    │       └── .pyc
    ├── comment_stripper
    │   ├── .py
    │   └── __pycache__
    │       └── .pyc
    ├── __pycache__
    │   └─ .pyc
    ├── templates
    │   └── .j2
    └── data
        └── .json

以逗号分隔的扩展名列表：
.j2,.json,.py,.pyc

分析还会生成一个以逗号分隔的文件扩展名列表，可轻松复制并配合 --filter 选项进行更精准的代码处理。

🔥 功能亮点：动态变量提取用于提示词生成

code2prompt 提供了从模板中动态提取变量的强大功能，允许交互式且可定制的提示词生成。通过语法 {{input:variable_name}}，您可以轻松定义变量，这些变量会在执行时提示用户输入。

这对于创建灵活的模板特别有用，可用于各种目的，比如为 Chrome 扩展生成 AI 提示词。以下是一个示例：

# Chrome 扩展的 AI 提示词生成器

生成一个 AI 提示词，用于创建一个 Chrome 扩展，具体要求如下：

扩展名称：{{input:extension_name}}
主要功能：{{input:main_functionality}}
目标受众：{{input:target_audience}}

## 提示：

你是一位经验丰富的Chrome扩展开发者。请为名为“{{input:extension_name}}”的Chrome扩展制定一份详细计划，该扩展的核心功能为{{input:main_functionality}}。此扩展专为{{input:target_audience}}设计。

你的回复应包括：

1. 扩展的简要描述及其功能
2. 核心功能（至少3个）
3. 用户界面设计考虑
4. 开发过程中可能遇到的挑战及应对策略
5. 安全与隐私考量
6. 主要组件的基本代码结构（manifest.json、后台脚本、内容脚本等）

请确保你的计划详尽、技术可行，并针对{{input:target_audience}}的需求量身定制。

从以下代码库开始：

---- 

## 代码库：

<codebase>

当你使用此模板运行code2prompt时，它会自动检测{{input:variable_name}}模式，并提示用户为每个变量（扩展名、主要功能和目标受众）提供值。这使得提示生成更加灵活且互动性强，便于为各种Chrome扩展创意快速生成定制化的AI提示。

例如，如果用户输入：

• 扩展名：“ProductivityBoost”
• 主要功能：“追踪在不同网站上花费的时间并提供生产力洞察”
• 目标受众：“居家办公的专业人士”

该工具将为AI生成一份针对此特定Chrome扩展的详细计划。这一功能尤其适合开发者、产品经理或任何希望快速为各类项目或创意生成定制化AI提示的人士。

🔥 功能亮点：“包含文件”功能

code2prompt项目现支持强大的“包含文件”功能，提升了模板的模块化与可重用性。

此功能允许你通过{% include %}指令，无缝地将外部文件内容引入主模板。例如，在主模板analyze-code.j2中，你可以将复杂部分拆解成更小、更易管理的文件：

# 精英代码分析与改进策略师2.0

{% include 'sections/role_and_goal.j2' %}

{% include 'sections/core_competencies.j2' %}

## 任务分解

1. 初步评估
{% include 'tasks/initial_assessment.j2' %}

2. 多维度分析（运用思维树）
{% include 'tasks/multi_dimensional_analysis.j2' %}

// ... 其他章节 ...

这种方式让你能更高效地组织模板结构，提升可维护性，同时便于对特定部分进行更新而无需修改整个模板。包含功能支持相对路径和绝对路径，适用于各种项目结构。借助这一功能，你可以显著减少代码重复，改善模板管理，打造更模块化、更具扩展性的code2prompt模板结构。

交互模式

交互模式让用户能够以更友好的方式选择待处理的文件。这一功能在处理大型代码库或希望有选择性地包含文件而无需手动指定每个路径时尤为有用。

如何使用交互模式

要激活交互模式，请在运行code2prompt命令时使用--interactive或-i选项。以下是示例：

code2prompt --path /path/to/your/project --interactive

交互模式的功能

• 文件选择：通过键盘控制浏览目录结构并选择文件。
• 视觉反馈：界面提供视觉提示，帮助你了解哪些文件已被选中或忽略。

键盘控制

• 方向键：在文件列表中导航。
• 空格键：切换文件的选择状态。
• 回车键：确认选择并继续执行命令。
• Esc键：退出交互模式而不做任何更改。

这一模式提升了Code2Prompt的易用性，让你在复杂项目中更轻松地管理文件选择。

配置文件

Code2prompt支持JSON格式的.code2promptrc配置文件，用于设置默认选项。请将此文件放置在你的项目目录或主目录中。

.code2promptrc示例：

{
  "suppress_comments": true,
  "line_number": true,
  "encoding": "cl100k_base",
  "filter": "*.py,*.js",
  "exclude": "tests/*,docs/*"
}

故障排除

1. 问题：Code2prompt未识别我的.gitignore文件。 解决方案：从项目根目录运行Code2prompt，或使用--gitignore指定.gitignore路径。

2. 问题：生成的输出对我的AI模型来说太大。 解决方案：使用--tokens检查令牌数量，并优化--filter或--exclude选项。

3. 问题：某些文件未被处理。 解决方案：检查二进制文件或排除模式。如有需要，使用--case-sensitive。

路线图

• 交互式过滤
• 在模板中加入包含系统，促进子模板的可重用性。
• 支持输入变量
• 针对Anthropic模型及其他模型（如LLama3或Mistral）的令牌计数
• 根据令牌数量估算主流LLM提供商的成本
• 与qllm（Quantalogic LLM）集成
• 将文件摘要嵌入SQL-Lite
• 基于LLM的文件智能选择
• Git增强工具（Git diff集成/PR辅助评审）

贡献

欢迎为Code2prompt贡献！请阅读我们的贡献指南，了解我们的行为准则以及提交拉取请求的流程。

许可协议

Code2prompt采用MIT许可证发布。详情请参阅LICENSE文件。

---

⭐ 如果你觉得Code2prompt对你有帮助，请在GitHub上给我们点个星！这有助于我们触达更多开发者并改进工具。⭐

项目成长

由Raphaël MANSUY用❤️制作。Quantalogic创始人。qllm创作者。

Code2Prompt 快速上手指南

Code2Prompt 是一款强大的命令行工具，能将整个代码库转换为结构清晰、适合大语言模型（LLM）处理的 Prompt。它帮助开发者高效地进行代码分析、文档生成和代码优化。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip 或 pipx（推荐使用 pipx 以避免环境污染）
  • 可选：项目根目录下包含 .gitignore 文件以排除无关文件

💡 提示：国内用户可使用清华或阿里云镜像源加速安装。

安装步骤

方法一：使用 pip（通用）

pip install code2prompt -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：使用 pipx（推荐，隔离环境）

pipx install code2prompt

如未安装 pipx，可先通过以下命令安装：

pip install pipx -i https://pypi.tuna.tsinghua.edu.cn/simple
pipx ensurepath

基本使用

1. 处理单个文件

将单个 Python 文件转换为 AI 友好的 Prompt 并输出到终端：

code2prompt --path /path/to/your/script.py

2. 处理整个项目并保存结果

扫描整个项目目录，生成 Markdown 格式的总结文件：

code2prompt --path /path/to/your/project --output project_summary.md

3. 多路径处理并排除测试文件

同时处理多个目录，并排除测试相关文件：

code2prompt --path /path/to/src --path /path/to/lib --exclude "*/tests/*" --output codebase_summary.md

4. 添加行号与自定义语法高亮

为代码块添加行号，并指定特殊扩展名的语法高亮：

code2prompt --path /path/to/your/project --line-number --syntax-map "inc:bash,customext:python" --output summary.md

生成的内容可直接复制粘贴至任意 LLM 对话界面，或用于自动化工作流。