# 翻译Skill全面改造计划

## 概述

本文档是针对AiNiee-Next翻译系统的全面分析和技术改造计划。基于对现有代码和skill架构的深入分析，制定完善的skill构建和优化方案。

---

## 1. 当前状态分析

### 1.1 现有Skills结构

```
.codex/skills/
├── ainiee-next-maintainer/          # 项目维护skill
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   └── references/
│       ├── repo-map.md
│       ├── workflows.md
│       └── extensions.md
│
└── translation-assistant/           # 翻译助手skill
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── README.md
    ├── IMPLEMENTATION.md
    └── references/
        ├── translation-workflow.md    # 翻译流程
        ├── quality-optimization.md   # 质量优化
        ├── troubleshooting.md        # 故障排查
        └── prompt-customization.md  # 提示词定制
```

### 1.2 现有Skills的优缺点

#### 优点

1. **基础结构完整**: 包含SKILL.md、agents配置、references文档
2. **分类清晰**: 按功能分为ainiee-next-maintainer和translation-assistant
3. **文档丰富**: 包含大量使用指南和故障排查文档
4. **工作流说明**: 详细描述了翻译pipeline的各个阶段

#### 缺点

1. **内容重复**: translation-assistant和ainiee-next-maintainer有大量重叠内容
2. **深度不足**: 缺少对核心配置、Prompt模板、API集成的深入分析
3. **缺乏实战**: 缺少具体的命令示例和最佳实践
4. **更新滞后**: 没有随着代码更新而同步更新
5. **索引缺失**: 缺少代码文件索引，定位具体模块困难
6. **配置分散**: 没有集中说明配置的位置和优先级

---

## 2. 翻译核心架构分析

### 2.1 翻译Pipeline详细流程

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           翻译Pipeline完整流程                              │
└─────────────────────────────────────────────────────────────────────────────┘

1. 文本输入 (FileReader)
   │
   ├── 读取源文件 (TxtReader, EpubReader, SrtReader等)
   ├── 解析格式结构
   └── 创建CacheItem对象
         │
         ▼
2. 文本预处理 (TextProcessor)
   │
   ├── normalize_text (插件事件)
   ├── replace_all (预翻译处理)
   │     ├── 行尾规范化
   │     ├── 预翻译规则应用
   │     ├── 占位符提取 {p1}, {p2}
   │     ├── 空白字符提取
   │     └── 前缀/后缀提取
   └── preproces_text (插件事件)
         │
         ▼
3. Prompt构建 (PromptBuilder)
   │
   ├── 选择PromptBuilder类型
   │     ├── PromptBuilder - 标准翻译
   │     ├── PromptBuilderLocal - 本地模型
   │     ├── PromptBuilderSakura - 日→中专用
   │     └── PromptBuilderPolishing - 润色
   ├── 填充模板变量
   │     ├── {source_language}
   │     ├── {target_language}
   │     ├── {glossary}
   │     └── {previous_lines}
   └── 生成最终Prompt
         │
         ▼
4. LLM请求 (LLMRequester)
   │
   ├── 选择Requester类型
   │     ├── OpenAIRequester
   │     ├── AnthropicRequester
   │     ├── GoogleRequester
   │     ├── CohereRequester
   │     ├── DashscopeRequester
   │     └── AmazonBedrockRequester
   ├── 速率限制 (RequestLimiter)
   ├── 错误处理 (ErrorClassifier)
   └── 重试机制 (Tenacity)
         │
         ▼
5. 响应提取 (ResponseExtractor)
   │
   ├── 格式检测 (<textarea>, 编号, 纯文本)
   ├── 行提取
   └── 行数验证
         │
         ▼
6. 响应验证 (ResponseChecker)
   │
   ├── BaseChecks
   │     ├── 长度检查
   │     ├── 行数检查
   │     └── 空翻译检查
   └── AdvancedChecks
         ├── 语言检测
         ├── 占位符保留
         └── 格式标记保留
         │
         ▼
7. 后处理 (TextProcessor)
   │
   ├── restore_all (翻译后恢复)
   │     ├── 占位符恢复
   │     ├── 空白字符恢复
   │     ├── 前缀/后缀恢复
   │     ├── 后翻译规则应用
   │     └── 行尾恢复
   └── postprocess_text (插件事件)
         │
         ▼
8. 输出写入 (FileWriter)
   │
   ├── 写入目标格式
   ├── 保持格式结构
   └── 更新Cache状态
```

### 2.2 核心模块映射表

| 功能 | 模块路径 | 关键类 |
|------|----------|--------|
| 翻译执行 | `ModuleFolders/Service/TaskExecutor/` | TaskExecutor, TranslatorTask, PolisherTask |
| 文本处理 | `ModuleFolders/Domain/TextProcessor/` | TextProcessor, PolishTextProcessor |
| Prompt构建 | `ModuleFolders/Domain/PromptBuilder/` | PromptBuilder, PromptBuilderLocal, PromptBuilderSakura |
| LLM请求 | `ModuleFolders/Infrastructure/LLMRequester/` | LLMRequester, AsyncLLMRequester |
| 响应提取 | `ModuleFolders/Domain/ResponseExtractor/` | ResponseExtractor |
| 响应验证 | `ModuleFolders/Domain/ResponseChecker/` | ResponseChecker, BaseChecks, AdvancedChecks |
| 缓存管理 | `ModuleFolders/Infrastructure/Cache/` | CacheManager, CacheItem |
| 配置管理 | `ModuleFolders/Infrastructure/TaskConfig/` | TaskConfig, ConfigRegistry |
| 文件读取 | `ModuleFolders/Domain/FileReader/` | FileReader, (各格式Reader) |
| 文件写入 | `ModuleFolders/Domain/FileOutputer/` | FileWriter, (各格式Writer) |

### 2.3 配置文件层级

```
配置优先级 (高 → 低):
┌─────────────────────────────────────────┐
│ 1. CLI参数 (-s, -t, -o等)             │ 最高优先级
├─────────────────────────────────────────┤
│ 2. 代码内硬编码 (TaskConfig默认值)     │
├─────────────────────────────────────────┤
│ 3. Profile配置 (Resource/profiles/)    │
├─────────────────────────────────────────┤
│ 4. 全局配置 (Resource/config.json)     │ 最低优先级
└─────────────────────────────────────────┘
```

### 2.4 关键配置文件位置

| 配置项 | 文件位置 |
|--------|----------|
| 全局配置 | `Resource/config.json` |
| 默认Profile | `Resource/profiles/default.json` |
| 自定义Profile | `Resource/profiles/{profile_name}.json` |
| Regex规则 | `Resource/Regex/regex.json` |
| 检查规则 | `Resource/Regex/check_regex.json` |
| Prompt模板 | `Resource/Prompt/Translate/*.txt` |
| 平台配置 | `Resource/platforms/preset.json` |
| 术语表 | `Resource/glossary/` |

---

## 3. Skills改造计划

### 3.1 重新设计Skills架构

#### 方案A: 合并方案 (推荐)

将translation-assistant合并到ainiee-next-maintainer，减少重复:

```
.codex/skills/
└── ainiee-next-maintainer/
    ├── SKILL.md                     # 主入口，合并两个skill功能
    ├── agents/
    │   └── openai.yaml
    └── references/
        ├── repo-map.md              # 项目结构
        ├── workflows.md             # 工作流
        ├── extensions.md             # 扩展点
        ├── translation-pipeline.md  # 新增: 翻译流程详解
        ├── prompt-templates.md      # 新增: Prompt模板
        ├── api-integrations.md      # 新增: API集成
        ├── config-reference.md      # 新增: 配置参考
        ├── quality-tuning.md       # 增强: 质量优化
        └── troubleshooting.md        # 增强: 故障排查
```

#### 方案B: 专业化方案

保持两个skill，但明确定义边界:

```
.codex/skills/
├── ainiee-next-maintainer/          # 项目级维护
│   └── 关注: 架构、扩展、跨层问题
│
└── translation-assistant/            # 翻译功能
    └── 关注: 翻译质量、Prompt、配置
```

### 3.2 新增核心文档

#### 3.2.1 translation-pipeline.md (新增)

详细描述翻译Pipeline的每个阶段，包括代码示例:

```markdown
# 翻译Pipeline详解

## 阶段1: 文本输入

### 关键代码
位置: `ModuleFolders/Domain/FileReader/FileReader.py`

### 支持格式
- TXT: TxtReader
- EPUB: EpubReader
- SRT: SrtReader
- ASS: AssReader
...

## 阶段2: 文本预处理

### 占位符处理
...
```

#### 3.2.2 prompt-templates.md (新增)

详细说明所有Prompt模板:

```markdown
# Prompt模板详解

## 标准翻译 (common_system_zh.txt)

### 模板内容
...

### 适用场景
- 一般文本翻译
- 保持格式
- 占位符保留

## Sakura翻译 (sakura_system_zh.txt)

### 特点
- 日→中专用
- 轻小说优化
- 角色对话自然

## 自定义模板
...
```

#### 3.2.3 api-integrations.md (新增)

详细说明支持的API:

```markdown
# API集成指南

## OpenAI

### 配置
```json
{
  "platform": "Openai",
  "model": "gpt-4",
  "api_url": "https://api.openai.com/v1",
  "api_key": "sk-..."
}
```

### 支持模型
- gpt-4o
- gpt-4-turbo
- gpt-3.5-turbo

## Anthropic Claude

### 配置
...

## Google Gemini

### 配置
...
```

#### 3.2.4 config-reference.md (新增)

完整的配置参考:

```markdown
# 配置参考手册

## TaskConfig所有配置项

### 翻译相关
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| source_language | str | "Japanese" | 源语言 |
| target_language | str | "Chinese" | 目标语言 |
| batch_size | int | 10 | 批处理大小 |
| max_concurrent_requests | int | 5 | 最大并发 |

### API相关
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| platform | str | "Openai" | API平台 |
| model | str | "gpt-4" | 模型名称 |
| api_url | str | - | API地址 |
| api_key | str | - | API密钥 |

### 质量相关
...
```

### 3.3 增强现有文档

#### 3.3.1 故障排查增强

按问题类型分类:

```markdown
# 故障排查指南

## API问题
- 连接失败
- 速率限制
- 认证错误

## 质量问题
- 翻译不准确
- 格式丢失
- 占位符问题

## 性能问题
- 速度慢
- 内存占用高

## 配置问题
- 配置不生效
- Profile加载失败
```

#### 3.3.2 代码索引增强

添加快速索引:

```markdown
# 快速代码索引

## 翻译核心
- TaskExecutor:55 → 翻译任务执行
- TranslatorTask:12 → 翻译任务
- TextProcessor:89 → 文本处理

## 配置
- TaskConfig:156 → 任务配置
- ConfigRegistry:45 → 配置注册

## 缓存
- CacheManager:234 → 缓存管理
- CacheItem:67 → 缓存项
```

---

## 4. 具体改造任务

### 4.1 优先级1: 核心文档创建

| 任务 | 描述 | 预估行数 |
|------|------|----------|
| T1.1 | 创建translation-pipeline.md | 500+ |
| T1.2 | 创建prompt-templates.md | 400+ |
| T1.3 | 创建api-integrations.md | 600+ |
| T1.4 | 创建config-reference.md | 500+ |

### 4.2 优先级2: 现有文档增强

| 任务 | 描述 | 预估行数 |
|------|------|----------|
| T2.1 | 增强troubleshooting.md | 300+ |
| T2.2 | 增强quality-optimization.md | 200+ |
| T2.3 | 添加代码索引 | 150+ |

### 4.3 优先级3: 工具脚本

| 任务 | 描述 |
|------|------|
| T3.1 | 创建配置验证脚本 |
| T3.2 | 创建Prompt测试脚本 |
| T3.3 | 创建性能基准脚本 |

---

## 5. 实现时间线

```
Week 1: 核心文档创建
├── T1.1 translation-pipeline.md
└── T1.2 prompt-templates.md

Week 2: API和配置文档
├── T1.3 api-integrations.md
└── T1.4 config-reference.md

Week 3: 文档增强
├── T2.1 增强troubleshooting.md
├── T2.2 增强quality-optimization.md
└── T2.3 添加代码索引

Week 4: 测试和优化
├── 测试所有文档准确性
├── 验证命令示例
└── 最终发布
```

---

## 6. 成功标准

### 6.1 文档完整性

- [ ] 覆盖所有核心模块
- [ ] 包含代码示例
- [ ] 包含配置示例
- [ ] 包含故障排查指南

### 6.2 可用性

- [ ] 快速索引建立
- [ ] 文档交叉引用
- [ ] 示例可执行验证

### 6.3 准确性

- [ ] 代码路径准确
- [ ] 配置项准确
- [ ] 命令示例验证

---

## 7. 附录

### 7.1 关键文件速查

| 功能 | 文件 |
|------|------|
| 入口点 | `ainiee_cli.py` |
| 翻译执行 | `ModuleFolders/Service/TaskExecutor/TaskExecutor.py` |
| 文本处理 | `ModuleFolders/Domain/TextProcessor/TextProcessor.py` |
| Prompt构建 | `ModuleFolders/Domain/PromptBuilder/PromptBuilder.py` |
| LLM请求 | `ModuleFolders/Infrastructure/LLMRequester/LLMRequester.py` |
| 响应检查 | `ModuleFolders/Domain/ResponseChecker/ResponseChecker.py` |
| 缓存管理 | `ModuleFolders/Infrastructure/Cache/CacheManager.py` |
| 配置管理 | `ModuleFolders/Infrastructure/TaskConfig/TaskConfig.py` |

### 7.2 命令速查

```bash
# 基本翻译
uv run python ainiee_cli.py translate input.txt -s Japanese -t Chinese -o output

# 指定Profile
uv run python ainiee_cli.py translate input.txt -p my_profile

# 断点续传
uv run python ainiee_cli.py translate input.txt -r

# Web模式
uv run python ainiee_cli.py translate input.txt --web-mode
```

### 7.3 配置速查

```python
# 快速获取配置
from ModuleFolders.Infrastructure.TaskConfig.TaskConfig import TaskConfig
config = TaskConfig()
print(f"Batch size: {config.batch_size}")
print(f"Source language: {config.source_language}")
```

---

**文档版本**: 1.0
**创建日期**: 2025-01-14
**最后更新**: 2025-01-14
**状态**: 规划完成，准备实施
