files-to-prompt

将一个包含多个文件的目录合并为一个可用于大语言模型的单一提示文本。

有关该项目的背景信息，请参阅 完全使用 Claude 3 Opus 构建 files-to-prompt。

安装

使用 pip 安装此工具：

pip install files-to-prompt

使用方法

要使用 files-to-prompt，请提供您想要处理的一个或多个文件或目录的路径：

files-to-prompt path/to/file_or_directory [path/to/another/file_or_directory ...]

这将输出每个文件的内容，每个文件前面会加上其相对路径，并用 --- 分隔。

选项

• -e/--extension <extension>：仅包含具有指定扩展名的文件。可以多次使用。

  files-to-prompt path/to/directory -e txt -e md
  

• --include-hidden：包含以 . 开头的文件和文件夹（隐藏文件和目录）。

  files-to-prompt path/to/directory --include-hidden
  

• --ignore <pattern>：指定一个或多个要忽略的模式。可以多次使用。模式可以匹配文件名和目录名，除非同时指定了 --ignore-files-only。模式语法使用 fnmatch，支持 *、?、[anychar]、[!notchars] 和 [?] 用于特殊字符字面量。

  files-to-prompt path/to/directory --ignore "*.log" --ignore "temp*"
  

• --ignore-files-only：包含那些本会被 --ignore 模式忽略的目录路径。

  files-to-prompt path/to/directory --ignore-files-only --ignore "*dir*"
  

• --ignore-gitignore：忽略 .gitignore 文件并包含所有文件。

  files-to-prompt path/to/directory --ignore-gitignore
  

• -c/--cxml：以 Claude XML 格式输出。

  files-to-prompt path/to/directory --cxml
  

• -m/--markdown：以带有围栏代码块的 Markdown 格式输出。

  files-to-prompt path/to/directory --markdown
  

• -o/--output <file>：将输出写入文件，而不是打印到控制台。

  files-to-prompt path/to/directory -o output.txt
  

• -n/--line-numbers：在输出中包含行号。

  files-to-prompt path/to/directory -n
  

  示例输出：

  files_to_prompt/cli.py
  ---
    1  import os
    2  from fnmatch import fnmatch
    3
    4  import click
    ...
  

• -0/--null：从标准输入读取路径时，使用 NUL 字符作为分隔符。当文件名可能包含空格时非常有用。

  find . -name "*.py" -print0 | files-to-prompt --null
  

示例

假设您有一个如下所示的目录结构：

my_directory/
├── file1.txt
├── file2.txt
├── .hidden_file.txt
├── temp.log
└── subdirectory/
    └── file3.txt

运行 files-to-prompt my_directory 将输出：

my_directory/file1.txt
---
file1.txt 的内容
---
my_directory/file2.txt
---
file2.txt 的内容
---
my_directory/subdirectory/file3.txt
---
file3.txt 的内容
---

如果您运行 files-to-prompt my_directory --include-hidden，输出还将包括 .hidden_file.txt：

my_directory/.hidden_file.txt
---
.hidden_file.txt 的内容
---
...

如果您运行 files-to-prompt my_directory --ignore "*.log"，输出将不包含 temp.log：

my_directory/file1.txt
---
file1.txt 的内容
---
my_directory/file2.txt
---
file2.txt 的内容
---
my_directory/subdirectory/file3.txt
---
file3.txt 的内容
---

如果您运行 files-to-prompt my_directory --ignore "sub*"，输出将不包含 subdirectory/ 中的所有文件（除非您还指定了 --ignore-files-only）：

my_directory/file1.txt
---
file1.txt 的内容
---
my_directory/file2.txt
---
file2.txt 的内容
---

从标准输入读取

该工具也可以从标准输入读取路径。这可用于将另一个命令的输出通过管道传递进来：

# 查找过去一天内修改过的文件
find . -mtime -1 | files-to-prompt

当使用 --null（或 -0）选项时，路径应以 NUL 字符分隔（处理包含空格的文件名时很有用）：

find . -name "*.txt" -print0 | files-to-prompt --null

您可以混合使用命令行参数和标准输入中的路径：

# 包括过去一天内修改过的文件，并且还包括 README.md
find . -mtime -1 | files-to-prompt README.md

Claude XML 输出

Anthropic 提供了 特定指南 来优化提示的结构，以便充分利用 Claude 的扩展上下文窗口。

要以这种方式组织输出，请使用可选的 --cxml 标志，它将生成如下输出：

<documents>
<document index="1">
<source>my_directory/file1.txt</source>
<document_content>
file1.txt 的内容
</document_content>
</document>
<document index="2">
<source>my_directory/file2.txt</source>
<document_content>
file2.txt 的内容
</document_content>
</document>
</documents>

--markdown 围栏代码块输出

--markdown 选项会将文件以围栏代码块的形式输出，这对于粘贴到 Markdown 文档中非常有用。

files-to-prompt path/to/directory --markdown

语言标签将根据文件名自动推断。

如果代码本身包含三重反引号，则其外层将多使用一个反引号。

示例输出：

myfile.py
```python
def my_function():
    return "Hello, world!"
```
other.js
```javascript
function myFunction() {
    return "Hello, world!";
}
```
file_with_triple_backticks.md
````markdown
这个文件有自己的
```
围栏代码块
```
在里面。

## 开发

要为此工具做出贡献，首先克隆代码库。然后创建一个新的虚拟环境：

```bash
cd files-to-prompt
python -m venv venv
source venv/bin/activate
```

现在安装依赖项和测试依赖项：

```bash
pip install -e '.[test]'
```

运行测试：

```bash
pytest
```

files-to-prompt 快速上手指南

files-to-prompt 是一个命令行工具，用于将目录中的多个文件内容合并为一个单一的提示词（Prompt），专为大型语言模型（LLM）设计。它支持自动添加文件路径分隔符、忽略特定文件、输出为 Claude XML 格式或 Markdown 代码块等功能。

环境准备

• 操作系统：Linux、macOS 或 Windows（需安装 Python 环境）
• Python 版本：建议 Python 3.8 及以上
• 前置依赖：无特殊系统依赖，仅需 pip 包管理器

💡 国内用户建议使用清华或阿里镜像源加速安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple files-to-prompt

安装步骤

使用 pip 一键安装：

pip install files-to-prompt

如需使用国内镜像源加速：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple files-to-prompt

基本使用

最简单用法

将指定目录下的所有文件内容合并输出到终端：

files-to-prompt path/to/your/directory

输出示例：

path/to/your/directory/file1.txt
---
文件 1 的内容
---
path/to/your/directory/file2.py
---
文件 2 的内容
---

常用选项示例

• 仅处理特定扩展名文件（如 .py 和 .md）：

  files-to-prompt src/ -e py -e md
  

• 忽略日志文件和临时文件：

  files-to-prompt project/ --ignore "*.log" --ignore "temp*"
  

• 输出为 Markdown 格式（适合粘贴到文档中）：

  files-to-prompt code/ --markdown
  

• 输出为 Claude XML 格式（优化长上下文提示）：

  files-to-prompt docs/ --cxml
  

• 包含行号：

  files-to-prompt src/ -n
  

• 将结果保存到文件：

  files-to-prompt project/ -o prompt.txt
  

结合其他命令使用

通过管道动态选择文件（例如最近一天修改过的文件）：

find . -mtime -1 | files-to-prompt

处理含空格的文件名时推荐使用 -0 选项：

find . -name "*.txt" -print0 | files-to-prompt --null