内容
# DocDog
[](https://opensource.org/licenses/Apache-2.0)
## 概述
DocDog 是一个基于 AI 的工具，通过自动生成高质量的 README 文件来简化软件项目的文档编写过程。它分析项目的代码库，包括源代码、文档和配置文件，以提取相关信息并生成针对项目特定需求的全面 README。
DocDog 旨在通过自动化繁琐的文档编写任务来节省开发人员的时间和精力，同时通过直接引用代码库来确保准确性和完整性。它为随着项目的发展保持文档的最新状态提供了便捷的解决方案。
## 特性
- **代码分析**：彻底检查项目的代码库，包括源代码文件、文档和配置文件。
- **并行处理**：利用并行处理技术高效处理大型代码库。
- **模板支持**：允许使用自定义模板生成 README，确保与项目品牌和风格指南的一致性。
- **自动生成 README**：生成包含概述、安装、使用、API 文档、配置、示例、故障排除、贡献指南和许可证信息等部分的完整 README 文件。
- **推理文档**：通过记录生成内容背后的推理，提供透明度，引用影响决策的特定代码片段和文件。
## 安装
```bash
pip install docdog
```
## 快速入门指南
要为您的项目生成 README，只需运行：
```
docdog
```
此命令将分析您的项目代码库，并在当前目录生成一个名为 `README.md` 的全面 README 文件。
## 使用
```
usage: docdog [-h] [-o OUTPUT] [-m MODEL] [--reasoning] [-p PROMPT_TEMPLATE] [--max-iterations MAX_ITERATIONS] [--workers WORKERS] [--cache-size CACHE_SIZE]
基于 AI 的软件项目 README 生成器
可选参数：
-h, --help 显示此帮助信息并退出
-o OUTPUT, --output OUTPUT
生成的 README 的输出文件（默认：README.md）
-m MODEL, --model MODEL
用于生成的 AI 模型名称（默认：claude-v1）
--reasoning 包括生成内容背后的推理
-p PROMPT_TEMPLATE, --prompt-template PROMPT_TEMPLATE
自定义提示模板文件的路径
--max-iterations MAX_ITERATIONS
分析的最大迭代次数（默认：15）
--workers WORKERS, -w WORKERS
工作线程的数量（默认：自动）
--cache-size CACHE_SIZE
LRU 缓存的大小（默认：128）
```
## API 文档
### `docdog.tools.Tools`
`Tools` 类提供与项目文件和目录交互的实用方法。
- `list_files(directory: str) -> str`: 列出项目中给定目录的文件。
- `read_file(file_path: str) -> str`: 读取项目中某个文件的内容。
- `batch_read_files(file_paths: list) -> str`: 读取项目中多个文件的内容。
### `docdog.chunking.chunk_project`
`chunk_project` 函数负责将项目文件拆分为更小的块，以便高效处理。
```python
def chunk_project(project_root, output_dir="chunks", config=None) -> List[str]:
...
```
- `project_root` (str): 项目的根目录。
- `output_dir` (str, optional): 存储生成块的目录（默认：`"chunks"`）。
- `config` (dict, optional): 指定分块选项的配置字典。
返回生成块的文件路径列表。
### `docdog.utils.sanitize_prompt`
`sanitize_prompt` 函数是一个用于清理提示的实用工具，以防止 Unicode 混淆和提示注入攻击。
```python
def sanitize_prompt(prompt: str) -> str:
...
```
- `prompt` (str): 要清理的输入提示。
返回清理后的提示字符串。
## 配置
DocDog 可以通过命令行参数和环境变量进行配置。
### 命令行参数
- `--output`: 指定生成的 README 的输出文件（默认：`README.md`）。
- `--model`: 设置用于生成的 AI 模型名称（默认：`claude-v1`）。
- `--reasoning`: 在单独的文件中包含生成内容背后的推理（`reasoning.md`）。
- `--prompt-template`: 提供自定义提示模板文件以生成 README。
- `--max-iterations`: 设置分析阶段的最大迭代次数（默认：`15`）。
- `--workers`: 指定并行处理的工作线程数量（默认：自动确定）。
- `--cache-size`: 设置用于缓存文件操作的 LRU 缓存大小（默认：`128`）。
### 环境变量
- `ANTHROPIC_API_KEY`: 设置您的 Anthropic API 密钥以进行身份验证。
## 示例和用例
### 基本用法
```bash
docdog
```
此命令将根据项目的代码库在当前目录生成一个 `README.md` 文件。
### 自定义输出文件
```bash
docdog --output project_readme.md
```
生成 README 并将其保存到 `project_readme.md`，而不是默认的 `README.md`。
### 包含推理
```bash
docdog --reasoning
```
除了 `README.md` 文件外，此命令还将生成一个 `reasoning.md` 文件，记录生成内容背后的推理，引用特定的代码片段和文件。
### 自定义提示模板
```bash
docdog --prompt-template custom_template.txt
```
使用自定义提示模板文件（`custom_template.txt`）生成 README，而不是默认模板。
### 支持的模型
目前，docdog 仅支持 `claude-3-sonnet-20240229`。
## 故障排除/常见问题
### 缺少 API 密钥
如果您遇到与缺少 API 密钥相关的错误，请确保您已设置 `ANTHROPIC_API_KEY` 环境变量，并提供有效的 Anthropic API 密钥。
### 文档生成不完整
在某些情况下，由于分析代码库的限制或遇到不支持的文件类型，DocDog 可能无法生成完整的 README。如果您遇到不完整的 README，请检查日志文件以获取更多信息，并考虑使用不同的配置或提供额外的上下文再次运行 DocDog。
## 贡献
欢迎对 DocDog 进行贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 文件以获取有关如何贡献的指南，包括报告问题、建议增强功能和提交拉取请求。
## 许可证
DocDog 根据 [Apache 2.0 许可证](https://opensource.org/licenses/Apache-2.0) 发布。
---
*由 DocDog 于 2025-05-05 生成*
---
*由 DocDog 于 2025-04-01 生成*
MCP 市场