# 项目开发指南

## 代码结构

```
aitf-next/
├── aitf_cli.py              # CLI 入口
├── ModuleFolders/
│   ├── Base/                  # 共享基类、事件总线
│   │   ├── PluginManager.py   # 插件管理器
│   │   └── EventBus.py        # 事件总线
│   ├── Domain/                # 领域层
│   │   ├── FileReader/        # 文件读取
│   │   ├── FileOutputer/      # 文件输出
│   │   ├── TextProcessor/     # 文本处理
│   │   ├── PromptBuilder/     # Prompt 构建
│   │   ├── ResponseExtractor/ # 响应提取
│   │   └── ResponseChecker/   # 响应检查
│   ├── Service/               # 服务层
│   │   └── TaskExecutor/      # 任务执行
│   └── Infrastructure/        # 基础设施层
│       ├── TaskConfig/        # 配置管理
│       ├── Cache/             # 缓存管理
│       └── LLMRequester/      # LLM 请求
├── PluginScripts/             # 插件脚本
├── Resource/                  # 资源文件
│   ├── profiles/              # 配置文件
│   ├── prompts/               # Prompt 模板
│   ├── cache/                 # 翻译缓存
│   └── logs/                  # 日志文件
└── Tools/
    └── WebServer/             # Web 服务器
```

## 插件开发

### 创建插件

1. 继承 `PluginScripts/PluginBase.py` 中的基类
2. 注册感兴趣的事件：
```python
self.add_event("preproces_text", priority=10)
self.add_event("postprocess_text", priority=10)
```

3. 实现事件处理方法

### 可用事件

| 事件名 | 时机 | 用途 |
|--------|------|------|
| `text_filter` | 读取文件后 | 内容过滤 |
| `normalize_text` | 规范化前 | 文本标准化 |
| `preproces_text` | 请求发送前 | 修改请求 |
| `postprocess_text` | 翻译完成后 | 后处理 |
| `build_rag_context` | 构建上下文 | RAG 增强 |
| `translation_completed` | 翻译完成 | 完成通知 |

### 插件示例

```python
class MyPlugin(PluginBase):
    def on_preproces_text(self, config, source_dict, prompt_dict):
        # 在这里修改 prompt
        for key, text in prompt_dict.items():
            prompt_dict[key] = f"[翻译任务]\n{text}"
        return prompt_dict
```

## 文件格式扩展

### 添加新格式支持

1. **简单格式** (文本分割): 修改 `FileReader/FileReader.py`
2. **结构化格式**: 使用 `FileAccessor`
3. **需要转换**: 使用 `FileConverter`

详见 `ModuleFolders/Domain/FileAccessor/README.md`

## WebServer 开发

### 启动方式

```bash
uv run aitf --web-mode
# 访问 http://127.0.0.1:15720
```

### API 端点

- `POST /translate` - 提交翻译任务
- `GET /status/{task_id}` - 获取任务状态
- `GET /logs` - 获取日志

### 内部 API

WebServer 使用内部 API 与 CLI 通信：
- 环境变量: `AINIEE_INTERNAL_API_URL`
- 保留此路径以确保监控功能正常

## 配置扩展

### 添加新配置项

1. 在 `ModuleFolders/Infrastructure/TaskConfig/TaskConfig.py` 添加默认值
2. 在 `ModuleFolders/Infrastructure/TaskConfig/ConfigRegistry.py` 添加元数据
3. 如需 UI 显示，添加本地化字符串

## 调试技巧

```bash
# 干运行模式（不实际调用 API）
# 在 profile 中设置: "enable_dry_run": true

# 详细日志
# 在 profile 中设置: "show_detailed_logs": true

# 单行测试
uv run aitf translate test.txt --lines 1 -y
```
