# Dialogue-to-Document

**Repository Path**: wentao02/dialogue-to-document

## Basic Information

- **Project Name**: Dialogue-to-Document
- **Description**: D2D (Dialogue to Document) Agent 是一个将对话记录转换为结构化软件文档的智能系统。它采用 Agent 架构，支持多种文档类型生成，并集成了 LLM 模型进行自然语言处理。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# D2D Agent 开发使用文档

## 项目概述

D2D (Dialogue to Document) Agent 是一个将对话记录转换为结构化软件文档的智能系统。它采用 Agent 架构，支持多种文档类型生成，并集成了 LLM 模型进行自然语言处理。

## 目录结构

```
D2D/
├── config/          # 配置文件目录
│   ├── d2d.yaml     # D2D Agent 主要配置
│   ├── templates.yaml # 模板配置
│   ├── embedding_modes.yaml # 嵌入模式配置
│   ├── embedding_strategies.yaml # 嵌入策略配置
│   └── api_config.yaml # API 配置
├── src/             # 源代码目录
│   ├── core/        # 核心组件
│   │   ├── config.py # 配置管理
│   │   ├── config_enhanced.py # 增强版配置管理
│   │   ├── embedding_client.py # 嵌入客户端
│   │   ├── embedding_client_enhanced.py # 增强版嵌入客户端
│   │   ├── embedding_strategy.py # 嵌入策略
│   │   ├── llm_client.py # LLM 客户端
│   │   ├── reranker.py # 重排序器
│   │   ├── validation.py # 验证器
│   │   ├── workflow.py # 工作流
│   │   └── workflow_embedding_integration.py # 工作流嵌入集成
│   ├── phases/      # 处理阶段
│   │   ├── atomic_proposition_extraction.py # 原子命题提取
│   │   ├── global_topology_discovery.py # 全局拓扑发现
│   │   ├── semantic_synthesis.py # 语义合成
│   │   ├── state_machine.py # 状态机
│   │   └── structured_preprocessing.py # 结构化预处理
│   ├── preprocessing/ # 预处理模块
│   │   ├── dialogue_parser.py # 对话记录解析器
│   │   ├── block_classifier.py # 原子块分类器
│   │   ├── connection_creator.py # 连接关系创建器
│   │   ├── glossary_extractor.py # 词汇表提取器
│   │   ├── logic_capsule_generator.py # 逻辑胶囊生成器
│   │   ├── preprocess.py # 预处理主程序
│   │   └── preprocessing_models.py # 预处理数据模型
│   ├── templates/   # 模板文件
│   │   ├── prompts/ # 提示文件
│   │   │   └── ics.md
│   │   └── render/ # 渲染模板
│   │       └── ics.j2
│   └── utils/       # 工具函数
│       ├── llm.py # LLM 工具
│       └── rate_limiter.py # 速率限制器
├── tests/           # 测试代码目录
│   ├── check_env.py # 环境检查
│   ├── check_sys_env_key.py # 系统环境密钥检查
│   ├── simple_env_test.py # 简单环境测试
│   ├── system_env_test.py # 系统环境测试
│   ├── test_api_services.py # API 服务测试
│   ├── test_config_and_clients.py # 配置和客户端测试
│   ├── test_embedding_modes.py # 嵌入模式测试
│   ├── test_glm_api.py # GLM API 测试
│   ├── test_glm_api_debug.py # GLM API 调试测试
│   ├── test_latest_models.py # 最新模型测试
│   ├── test_local_model.py # 本地模型测试
│   ├── test_preprocessing.py # 预处理测试
│   ├── test_robustness.py # 鲁棒性测试
│   ├── trace_env_vars.py # 环境变量追踪
│   └── validate_cloud_config.py # 云配置验证
├── tools/           # 工具脚本目录
│   ├── convert_json_to_markdown.py # JSON 转 Markdown 工具
│   ├── embedding_mode_manager.py # 嵌入模式管理器
│   └── simple_doc_generator.py # 简单文档生成器
├── docs/            # 文档目录
│   ├── embedding_modes_implementation.md # 嵌入模式实现文档
│   └── glm_api_troubleshooting.md # GLM API 故障排除文档
├── main.py          # 主入口文件（支持嵌入模式）
├── pyproject.toml   # 项目配置
└── requirements.txt # 依赖列表
```

## 安装说明

### 环境要求

- Python 3.12+
- pip 或 uv 包管理工具

### 安装依赖

使用 pip 安装：

```bash
pip install -r requirements.txt
```

使用 uv 安装：

```bash
uv install
```

## 使用方法

### 基本使用

```bash
python main.py --input "D2D Agent.json" --output "output_dir"
```

### 命令行参数

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--input` | `-i` | 输入 JSON 文件路径（必需） | - |
| `--output` | `-o` | 输出目录路径 | `output` |
| `--config` | `-c` | 主配置文件路径 | `config/d2d.yaml` |
| `--templates` | `-t` | 模板配置文件路径 | `config/templates.yaml` |
| `--skip-preprocessing` | `-s` | 跳过预处理阶段 | `False` |
| `--embedding-mode` | `-e` | 嵌入模式（local_only/cloud_only/hybrid） | `cloud_only` |
| `--embedding-config` | - | 嵌入模式配置文件路径 | `config/embedding_modes.yaml` |
| `--show-embedding-info` | - | 显示嵌入客户端信息 | `False` |

### 嵌入模式说明

系统支持三种嵌入模式：

1. **local_only**: 仅使用本地嵌入模型
   - 优点：无需网络，速度快，无 API 费用
   - 缺点：需要本地模型，可能精度较低

2. **cloud_only**: 仅使用云端嵌入模型
   - 优点：精度高，模型更新及时
   - 缺点：需要网络，有 API 费用

3. **hybrid**: 混合模式，智能选择本地或云端
   - 优点：平衡速度和精度
   - 缺点：配置较复杂

### 使用示例

#### 1. 基础文档转换
```bash
python main.py --input "D2D Agent.json" --output "output"
```

#### 2. 跳过预处理（使用已预处理的数据）
```bash
python main.py --input "preprocessing_result.json" --output "output" --skip-preprocessing
```

#### 3. 使用本地嵌入模式
```bash
python main.py --input "D2D Agent.json" --output "output" --embedding-mode local_only
```

#### 4. 使用混合嵌入模式
```bash
python main.py --input "D2D Agent.json" --output "output" --embedding-mode hybrid
```

#### 5. 查看嵌入客户端信息
```bash
python main.py --show-embedding-info
```

## 核心组件

### 增强版功能

- **配置管理器 (ConfigManager)**: 统一管理所有配置，支持嵌入模式切换
- **嵌入客户端 (EmbeddingClient)**: 支持多种嵌入提供商（OpenAI、SiliconFlow 等）
- **嵌入策略 (EmbeddingStrategy)**: 智能选择本地或云端嵌入模型
- **速率限制器 (RateLimiter)**: 防止 API 调用过载，支持令牌桶算法
- **重排序器 (Reranker)**: 优化检索结果质量
- **工作流嵌入集成 (WorkflowEmbeddingIntegrator)**: 将嵌入功能集成到工作流中

### 预处理模块

- **对话记录解析器 (DialogueParser)**: 将对话记录解析为原子块
- **原子块分类器 (BlockClassifier)**: 对原子块进行分类和关键词提取
- **连接关系创建器 (ConnectionCreator)**: 建立原子块之间的关联关系
- **词汇表提取器 (GlossaryExtractor)**: 提取项目专属词汇表
- **逻辑胶囊生成器 (LogicCapsuleGenerator)**: 将原子块升级为逻辑胶囊

### Agent 架构

- **Root Agent**: 根代理，负责整体流程协调
- **Leaf Agent**: 叶子代理，负责具体任务执行
- **Context Agent**: 上下文管理代理
- **Architect Agent**: 架构设计代理
- **Namer Agent**: 命名代理
- **SDRS Agent**: 语义合成代理

### 处理阶段

1. **结构化预处理**: 解析对话记录
2. **原子命题提取**: 提取关键信息（使用规则提取，减少 LLM 调用）
3. **全局拓扑发现**: 发现组件关系（支持批量处理，优化 API 调用）
4. **语义合成**: 生成结构化文档

### 性能优化

- **LLM 调用优化**: 从 126 次减少到 7 次（94% 优化）
- **规则提取**: 使用规则提取原子命题，减少 LLM 依赖
- **批量处理**: 支持批量命名和拓扑发现
- **速率限制**: 防止 API 调用过载，避免 429 错误

## 配置说明

### LLM 配置

在 `config/d2d.yaml` 中配置 LLM 模型：

```yaml
llm:
  type: "openai"  # 或 "glm"
  api_key: "your_api_key"
  model: "gpt-4"
  base_url: "https://api.openai.com/v1"
```

### 嵌入模式配置

在 `config/embedding_modes.yaml` 中配置嵌入模式：

```yaml
modes:
  local_only:
    provider: "local"
    model: "sentence-transformers/all-MiniLM-L6-v2"
  
  cloud_only:
    provider: "openai"
    model: "text-embedding-3-small"
    api_key: "your_api_key"
  
  hybrid:
    primary: "local"
    fallback: "cloud"
    threshold: 0.7
```

### 嵌入提供商配置

支持的嵌入提供商：

1. **OpenAI**: `text-embedding-3-small`, `text-embedding-3-large`
2. **SiliconFlow**: `BAAI/bge-large-zh-v1.5`, `BAAI/bge-small-en-v1.5`
3. **Local**: `sentence-transformers/all-MiniLM-L6-v2`

### 模板配置

在 `config/templates.yaml` 中配置文档模板：

```yaml
templates:
  - name: "ICS"
    file: "ics.j2"
    prompt: "ics.md"
```

## 开发指南

### 添加新 Agent

1. 在 `src/phases/` 目录下创建新的 Agent 类
2. 继承基础 Agent 类
3. 实现 `run` 方法
4. 在工作流中集成新 Agent

### 添加新模板

1. 在 `src/templates/render/` 目录下创建新的模板文件（.j2 格式）
2. 在 `src/templates/prompts/` 目录下创建对应的提示文件（.md 格式）
3. 在 `config/templates.yaml` 中注册新模板

### 添加新预处理模块

1. 在 `src/preprocessing/` 目录下创建新的模块
2. 继承或使用现有的数据模型（`preprocessing_models.py`）
3. 在 `preprocess.py` 中集成新模块
4. 更新导入路径和依赖关系

## 工具脚本

### convert_json_to_markdown.py
将 JSON 格式的对话记录转换为 Markdown 格式文档。

```bash
python tools/convert_json_to_markdown.py --input "D2D Agent.json" --output "output.md"
```

### embedding_mode_manager.py
嵌入模式管理工具，用于查看和管理嵌入模式配置。

```bash
python tools/embedding_mode_manager.py --list
python tools/embedding_mode_manager.py --set local_only
```

### simple_doc_generator.py
简单的文档生成工具，用于快速生成基础文档。

```bash
python tools/simple_doc_generator.py --input "D2D Agent.json" --output "output"
```

## 测试

运行测试命令：

```bash
# 运行所有测试
python -m pytest tests/

# 运行特定测试文件
python -m pytest tests/test_preprocessing.py

# 运行特定测试函数
python -m pytest tests/test_preprocessing.py::test_dialogue_parser
```

### 可用测试文件

- `test_preprocessing.py`: 预处理模块测试
- `test_api_services.py`: API 服务测试
- `test_config_and_clients.py`: 配置和客户端测试
- `test_embedding_modes.py`: 嵌入模式测试
- `test_glm_api.py`: GLM API 测试
- `test_local_model.py`: 本地模型测试
- `test_robustness.py`: 鲁棒性测试

## 故障排除

### 常见问题

1. **JSON 解析错误**: 确保 LLM 输出格式正确，包含有效的 JSON
2. **API 429 错误**: 检查 API 密钥和请求频率，考虑使用不同的 LLM 模型
3. **HDBSCAN 聚类错误**: 确保使用正确的距离度量和参数
4. **嵌入模式不可用**: 检查 `config/embedding_modes.yaml` 配置是否正确
5. **速率限制触发**: 调整 `config/embedding_modes.yaml` 中的 `rate_limit` 参数
6. **NamerAgent 批量命名失败**: 检查 API 密钥和网络连接，系统会自动降级处理
7. **模块导入错误**: 确保使用 `python -m` 方式运行模块，如 `python -m src.preprocessing.preprocess`

### 调试技巧

1. **查看嵌入信息**:
   ```bash
   python main.py --show-embedding-info
   ```

2. **检查配置验证**:
   ```bash
   python tests/validate_cloud_config.py
   ```

3. **查看调试输出**:
   ```bash
   python main.py --input "D2D Agent.json" --output "output" --config config/d2d.yaml
   ```

4. **检查中间结果**:
   - 中间结果保存在 `debug/intermediate_result.json`
   - 包含所有阶段的处理结果和错误信息

5. **运行环境检查**:
   ```bash
   python tests/check_env.py
   python tests/system_env_test.py
   ```

## 版本控制

- Python: 3.12+
- LangChain: 1.0+
- LangGraph: 1.0+

## 贡献指南

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送分支
5. 创建 Pull Request

## 许可证

MIT License