# docforge

**Repository Path**: frailty/docforge

## Basic Information

- **Project Name**: docforge
- **Description**: 一个文档生成Agent
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocForge

AI 驱动的项目文档生成器。分析项目结构，调用 LLM 自动生成高质量的 README.md。

## 功能特性

- **智能分析**：自动检测项目名称、构建工具、主语言和依赖列表
- **三种运行模式**：
  - `generate`：单次管道，快速生成文档
  - `agent`：REPL 多轮对话，交互式生成
  - `agent --one-shot`：Agent 循环一次性跑完即退
- **多 LLM 支持**：支持 Anthropic Claude 和 OpenAI GPT 系列
- **13 个内置工具**：文件系统操作、搜索、web 获取、交互提问
- **交互式权限**：写/删/执行类操作需用户确认，支持 session-allow
- **会话持久化**：REPL 模式自动保存/恢复对话历史
- **Token 优化**：滑动窗口记忆 + 自动摘要

## 系统要求

- Node.js 18+
- Anthropic API Key 或 OpenAI API Key

## 安装

```bash
git clone <repo>
cd docforge
pnpm install
pnpm build
```

开发模式（无需构建）：

```bash
pnpm dev -- --help
```

## 配置

复制配置文件模板并填入你的 API Key：

```bash
mkdir -p ~/.docforge
cp config.json.template ~/.docforge/config.json
```

编辑 `~/.docforge/config.json`：

```json
{
  "provider": "anthropic",
  "apiKey": "${ANTHROPIC_API_KEY}",
  "defaultModel": "claude-3-5-sonnet-latest",
  "summaryModel": "claude-3-5-haiku-latest",
  "fileQaModel": "claude-3-5-haiku-latest"
}
```

### 配置字段说明

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `provider` | LLM 提供商：`anthropic` 或 `openai` | `anthropic` |
| `baseUrl` | API 地址，第三方代理填自己的 URL | 官方地址 |
| `apiKey` | API Key，支持 `${ENV_VAR}` 语法 | 必填 |
| `defaultModel` | 默认模型名 | 必填 |
| `reasoningModel` | 推理/规划阶段模型 | `null`（回落 defaultModel） |
| `generationModel` | 文档生成阶段模型 | `null`（回落 defaultModel） |
| `summaryModel` | 历史摘要模型（可配便宜模型省成本） | `null` |
| `fileQaModel` | file_qa 子代理模型 | `null` |

## 使用方法

### REPL 模式（默认）

```bash
# 默认进入 REPL，交互式对话
pnpm start

# 指定项目路径
pnpm start -- --project /path/to/project

# 跳过权限询问
pnpm start -- --project /path/to/project --yes
```

### generate 模式

```bash
# 单次生成，analyze → prompt → chat → writeFile，跑完即退
pnpm start generate -- --project /path/to/project
pnpm start generate -- --project /path/to/project --output /path/to/README.md
```

### agent 模式

```bash
# REPL 多轮对话
pnpm start agent -- --project /path/to/project

# 一次性跑完（无需 REPL）
pnpm start agent -- --project /path/to/project --one-shot

# 跳过权限询问
pnpm start agent -- --project /path/to/project --one-shot --yes
```

### 日志选项

```bash
# 自定义日志路径（默认 ~/.docforge/logs/YYYY-MM-DD_HH-mm-ss.log）
pnpm start -- --log-out /path/to/audit.log

# 开启 debug 日志（记录完整 LLM request/response）
pnpm start -- --debug-log

# 禁用全部文件日志
pnpm start -- --no-log
```

### 命令行选项

| 选项 | 说明 |
|------|------|
| `-p, --project <path>` | 项目根目录（默认当前目录） |
| `-o, --output <path>` | README 输出路径（默认 `<project>/README.md`） |
| `-y, --yes` | 跳过权限询问，预 allow 所有写/删/执行类工具 |
| `--one-shot` | agent 模式一次性跑完即退 |
| `--log-out <path>` | 自定义日志路径 |
| `--debug-log` | 开启 debug 日志 |
| `--no-log` | 禁用全部文件日志 |
| `-h, --help` | 显示帮助 |

## REPL 内置命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/new` | 开启新会话（清空对话，不删历史） |
| `/clear` | 清空当前对话（磁盘会话不删除） |
| `/load <path>` | 加载/切换项目上下文 |
| `/save [path]` | 保存最近一次 LLM 文本到文件 |
| `/config` | 交互式配置 ~/.docforge/config.json |
| `/config edit` | 调起 $EDITOR 编辑配置 |
| `/session list` | 列出历史会话 |
| `/session load <n>` | 载入第 n 个历史会话 |
| `/session delete` | 删除当前会话（二次确认） |
| `/session delete-all` | 删除所有历史会话（二次确认） |
| `/exit` `/quit` | 退出 REPL |

快捷键：Ctrl-D 退出，Ctrl-C（第一次取消输入，第二次退出）

## 内置工具

Agent/REPL 模式下 LLM 可调用的工具：

| 工具 | 说明 | 风险 |
|------|------|------|
| `list_directory` | 列出目录内容 | 低 |
| `read_file` | 读取文件（最大 1 MiB） | 低 |
| `get_file_info` | 获取文件/目录元信息 | 低 |
| `search_files` | 按 glob 模式搜索文件 | 低 |
| `content_search` | 按正则搜索文件内容 | 低 |
| `file_qa` | 对单个文件提问（子代理） | 低 |
| `write_file` | 写入文件 | 中 |
| `edit_file` | 编辑文件（精确替换） | 中 |
| `create_directory` | 创建目录 | 中 |
| `delete_file` | 删除文件或目录 | 中 |
| `execute_command` | 执行 shell 命令 | 高 |
| `web_fetch` | 获取 URL 内容 | 中 |
| `ask_user` | 向用户提问（暂停循环等待回答） | 低 |

### 路径安全

所有文件操作限制在项目根目录下。尝试访问外部路径会被拒绝。

### 权限决策

- `[y]es once`：本次允许
- `[n]o`：拒绝
- `[s]ession-allow`：本会话后续同类操作自动允许

## 项目结构

```
docforge/
├── src/
│   ├── agent.ts            # Agent 循环核心
│   ├── repl.ts             # REPL 交互界面
│   ├── analyze.ts          # 项目结构分析
│   ├── cli.ts              # CLI 入口
│   ├── config.ts           # 配置加载
│   ├── config-check.ts     # 配置检查
│   ├── llm.ts              # LLM 业务编排
│   ├── prompt.ts           # 提示词构造
│   ├── audit-log.ts        # 文件日志
│   ├── llmRequest/         # LLM 适配器层
│   │   ├── index.ts
│   │   ├── anthropic.ts
│   │   ├── openai.ts
│   │   └── types.ts
│   ├── session/            # 会话持久化
│   │   ├── index.ts
│   │   ├── memory.ts       # 滑动窗口 + 摘要
│   │   ├── store.ts        # 磁盘持久化
│   │   └── types.ts
│   └── tools/              # 工具系统
│       ├── index.ts
│       ├── registry.ts
│       ├── types.ts
│       ├── permissions.ts
│       ├── pathSafety.ts
│       ├── validate.ts
│       ├── adapters/       # LLM 协议适配器
│       └── builtin/        # 工具实现
├── test/                   # 测试
├── config.json.template    # 配置模板
└── package.json
```

## 开发

```bash
# 构建
pnpm build

# 代码格式化
pnpm format

# 代码检查
pnpm lint
pnpm lint:fix

# 运行测试
pnpm test

# 检查配置
pnpm config:check
```

## 技术约束

- Node 18+，使用内置 `fetch`、`fs/promises`、`path`
- `"type": "module"`，ESM 导入
- TypeScript 严格模式
- 纯函数优先，避免 class
- 错误处理：直接抛出异常，由 CLI 入口统一捕获
- 中文注释

## License

MIT