# BidMaster-CLI 架构文档

## 系统架构概览

BidMaster-CLI 采用分层架构设计，确保模块间的清晰边界和单向依赖。

```
┌─────────────────────────────────────┐
│     CLI Layer (Interface)           │ ← 用户交互层
├─────────────────────────────────────┤
│   Agent Layer (Orchestration)       │ ← 业务编排层
├─────────────────────────────────────┤
│    Tools Layer (Infrastructure)     │ ← 基础设施层
└─────────────────────────────────────┘
```

## 层级职责

### CLI Layer (命令行接口层)
- **职责**: 处理用户输入，展示输出结果
- **模块**: `src/bidmaster/cli/`
- **依赖**: 可调用 Agent Layer 和 Tools Layer
- **关键组件**:
  - `main.py`: CLI入口和命令注册
  - `kb.py`: 知识库管理命令
  - `project.py`: 项目管理命令
  - `generate.py`: 内容生成命令
  - `assemble.py`: 合规组装命令

### Agent Layer (业务编排层)
- **职责**: 实现核心业务逻辑，编排工具调用
- **模块**: `src/bidmaster/agents/`
- **依赖**: 仅可调用 Tools Layer
- **关键组件**:
  - `analysis.py`: 分析Agent - 解析招标文件
  - `generation.py`: 生成Agent - 内容生成
  - `assembly.py`: 组装Agent - 表格生成
  - `graph.py`: LangGraph工作流编排

### Tools Layer (基础设施层)
- **职责**: 提供原子化的工具函数
- **模块**: `src/bidmaster/tools/`
- **依赖**: 不依赖其他层
- **关键组件**:
  - `parser.py`: 文档解析工具
  - `rag.py`: RAG检索工具
  - `word.py`: Word文档处理
  - `table.py`: 表格生成工具

## 辅助模块

### Config (配置管理)
- **路径**: `src/bidmaster/config/`
- **职责**: 统一管理配置
- **文件**: `settings.py`

### Models (数据模型)
- **路径**: `src/bidmaster/models/`
- **职责**: 定义数据结构
- **文件**: `project.py`, `task.py`

### Internal (内部实现)
- **路径**: `src/bidmaster/internal/`
- **职责**: 内部实现细节，禁止外部引用
- **说明**: 存放不对外暴露的内部功能

## 依赖规则

1. **单向依赖**: 上层可以调用下层，禁止逆向引用
2. **跨层调用**: CLI可以直接调用Tools，无需经过Agent
3. **内部模块**: internal目录内容仅供内部使用
4. **统一导出**: 通过`__init__.py`管理模块导出

## 数据流

```
用户输入 → CLI Layer → Agent Layer → Tools Layer
                ↓           ↓            ↓
            命令解析    业务编排      工具执行
                ↓           ↓            ↓
            展示结果  ← 返回结果  ← 返回数据
```

## 核心工作流

### 1. 项目创建流程 (project new)
```
CLI(project.py)
  → Analysis Agent
    → Parser Tool (解析招标文件)
    → Word Tool (生成模板)
  → 保存项目文件
```

### 2. 内容生成流程 (generate)
```
CLI(generate.py)
  → Generation Agent
    → RAG Tool (检索知识库)
    → LLM调用
  → 更新任务状态
```

### 3. 合规组装流程 (assemble)
```
CLI(assemble.py)
  → Assembly Agent
    → Table Tool (生成表格)
    → Word Tool (插入文档)
  → 生成最终文档
```

## 设计原则

1. **高内聚低耦合**: 每个模块职责单一
2. **依赖倒置**: 上层定义接口，下层实现
3. **开闭原则**: 对扩展开放，对修改关闭
4. **最小知识原则**: 模块只了解必要的依赖

## 扩展指南

新增功能时遵循以下步骤：

1. 确定功能层级（CLI/Agent/Tool）
2. 在对应目录创建模块
3. 遵循现有命名规范
4. 更新相应的`__init__.py`
5. 添加单元测试
6. 更新本文档

## 版本历史

- v0.1.0: 初始架构设计
- v0.2.0: 添加internal目录
- v0.3.0: 完善三层架构