---
name: ainiee-next-maintainer
description: 使用 uv run ainiee 命令进行翻译、润色、导出等操作。处理 AiNiee-Next 项目的配置、翻译流程、文件格式支持、WebServer等问题。触发条件：运行时调试、配置修改、WebServer开发、Tauri Shell集成、插件开发或Reader/Writer扩展。
---

# AiNiee-Next 维护指南

## 快速配置向导

### 配置在线 API (DeepSeek 示例)

1. **编辑 Profile 文件**: `Resource/profiles/{profile_name}.json`

2. **必须配置的关键字段**:

```json
{
  "platforms": {
    "deepseek": {
      "api_key": "sk-your-api-key",
      "api_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat",
      "auto_complete": true
    }
  },
  "target_platform": "deepseek",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat",
  "api_settings": {
    "translate": "deepseek",
    "polish": "deepseek"
  },
  "translation_prompt_selection": {
    "last_selected_id": 100
  },
  "polishing_prompt_selection": {
    "last_selected_id": 10001
  }
}
```

3. **关键配置说明**:

| 字段 | 值 | 说明 |
|------|-----|------|
| `auto_complete` | `true` | **必须为 true**，否则 API 会返回 404 |
| `last_selected_id` | `100` | **必须为整数**，不是字符串 |
| `last_selected_id` (polish) | `10001` | 润色模式的 Prompt ID |

### Prompt ID 枚举值

```python
# ModuleFolders/Domain/PromptBuilder/PromptBuilderEnum.py
COMMON = 100      # 通用翻译
COT = 200         # Chain of Thought
THINK = 300       # 思考模式
CUSTOM = 1000     # 自定义
POLISH_COMMON = 10001  # 润色通用
```

## 核心命令

### 基本使用
```bash
# 翻译文件 (使用默认配置)
uv run ainiee translate input.txt

# 指定语言翻译
uv run ainiee translate input.txt -s Japanese -t Chinese

# 断点续传
uv run ainiee translate input.txt -r -y

# 使用指定 profile
uv run ainiee translate input.txt -p my_profile
```

### 文件类型支持

| 类型 | --type 参数 | 说明 |
|------|-------------|------|
| 文本 | `Txt` | 普通文本文件 |
| 电子书 | `Epub` | EPUB格式 |
| **PDF** | `BabeldocPdf` | **注意：不是 Pdf** |
| 字幕 | `Srt, Ass, VTT, Lrc` | 各种字幕格式 |
| 游戏 | `Renpy, Mtool, Trans, TPP` | 游戏文本格式 |
| 文档 | `Docx, Md` | 办公文档 |

### PDF 翻译
```bash
# 正确的 PDF 翻译命令
uv run ainiee translate input.pdf --type BabeldocPdf -y

# 错误示例 (会报错)
uv run ainiee translate input.pdf --type Pdf -y
```

## API 平台配置

### 支持的平台

#### 本地模型
```json
{
  "sakura": {
    "api_url": "http://127.0.0.1:8080",
    "model": "Sakura-v1.0",
    "auto_complete": false  // 本地模型可以 false
  }
}
```

#### 在线模型 (需要 auto_complete: true)

```json
{
  "deepseek": {
    "api_url": "https://api.deepseek.com/v1",
    "api_key": "sk-xxx",
    "model": "deepseek-chat",
    "temperature": 1.3,
    "auto_complete": true
  },
  "openai": {
    "api_url": "https://api.openai.com/v1",
    "api_key": "sk-xxx",
    "model": "gpt-4o",
    "auto_complete": true
  },
  "anthropic": {
    "api_url": "https://api.anthropic.com",
    "api_key": "sk-ant-xxx",
    "model": "claude-3-5-haiku",
    "auto_complete": true
  },
  "google": {
    "api_url": "https://generativelanguage.googleapis.com/v1beta",
    "api_key": "xxx",
    "model": "gemini-2.5-flash",
    "auto_complete": true
  },
  "siliconflow": {
    "api_url": "https://api.siliconflow.cn/v1",
    "api_key": "xxx",
    "model": "deepseek-ai/DeepSeek-V3",
    "auto_complete": true
  },
  "dashscope": {
    "api_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "xxx",
    "model": "qwen-turbo",
    "auto_complete": true
  },
  "zhipu": {
    "api_url": "https://open.bigmodel.cn/api/paas/v4",
    "api_key": "xxx",
    "model": "glm-4.5-flash",
    "auto_complete": true
  },
  "moonshot": {
    "api_url": "https://api.moonshot.cn/v1",
    "api_key": "xxx",
    "model": "moonshot-v1-8k",
    "auto_complete": true
  }
}
```

## 常见问题排查

### 1. HTTP 404 错误

**症状**: `Request error (HARD_ERROR) [URL: https://api.xxx.com/v1, Model: xxx] ... HTTP 404:`

**原因**: `auto_complete` 未设置为 `true`，导致请求 URL 缺少 `/chat/completions`

**解决方案**:
```json
{
  "platforms": {
    "deepseek": {
      "auto_complete": true  // 添加或修改为 true
    }
  }
}
```

### 2. KeyError: 'last_selected_id'

**症状**: `KeyError: 'last_selected_id'`

**原因**: `translation_prompt_selection` 配置为空或格式错误

**解决方案**:
```json
{
  "translation_prompt_selection": {
    "last_selected_id": 100  // 整数，不是字符串
  },
  "polishing_prompt_selection": {
    "last_selected_id": 10001
  }
}
```

### 3. Unknown translation project type

**症状**: `Warning: Unknown translation project type 'Pdf'`

**原因**: 使用了错误的文件类型参数

**解决方案**:
```bash
# 错误
uv run ainiee translate input.pdf --type Pdf

# 正确
uv run ainiee translate input.pdf --type BabeldocPdf
```

### 4. API 连接测试

```bash
# 测试 DeepSeek API
curl -s -X GET "https://api.deepseek.com/v1/models" \
  -H "Authorization: Bearer sk-xxx"

# 测试翻译请求
curl -s -X POST "https://api.deepseek.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}]}'
```

### 5. 查看翻译日志

```bash
# 查看最新日志
find . -name "*.log" -path "*AiNiee_Output*" -exec cat {} \; | tail -50

# 日志位置
{output_dir}/logs/session_*.log
```

## 配置文件结构

```
Resource/
├── config.json           # 全局配置 (active_profile)
├── profiles/
│   ├── default.json     # 默认配置 (推荐修改这个)
│   └── lin.json         # 用户自定义配置
├── cache/               # 翻译缓存
└── Models/              # 模型文件
```

### Profile 完整配置示例

```json
{
  "platforms": {
    "deepseek": {
      "tag": "deepseek",
      "group": "online",
      "name": "DeepSeek",
      "api_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key",
      "api_format": "OpenAI",
      "model": "deepseek-chat",
      "temperature": 1.3,
      "top_p": 1.0,
      "auto_complete": true,
      "rpm_limit": 4096,
      "tpm_limit": 10000000
    }
  },
  "target_platform": "deepseek",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat",
  "source_language": "Japanese",
  "target_language": "Chinese",
  "api_settings": {
    "translate": "deepseek",
    "polish": "deepseek"
  },
  "translation_prompt_selection": {
    "last_selected_id": 100
  },
  "polishing_prompt_selection": {
    "last_selected_id": 10001
  },
  "lines_limit": 20,
  "pre_line_counts": 3,
  "retry_count": 3,
  "round_limit": 3,
  "request_timeout": 60
}
```

## 开发调试

### 代码结构
```
ainiee_cli.py           # CLI入口
ModuleFolders/
  Domain/
    FileReader/         # 文件读取 (FileReader.py, BabeldocPdfReader.py)
    FileOutputer/       # 文件输出
    PromptBuilder/      # Prompt构建 (PromptBuilderEnum.py)
  Infrastructure/
    LLMRequester/       # LLM请求 (OpenaiRequester.py)
    TaskConfig/         # 配置管理
```

### 调试命令
```bash
# 查看支持的项目类型
uv run python3 -c "
from ModuleFolders.Domain.FileReader.FileReader import FileReader
fr = FileReader()
print(fr.get_support_project_types())
"

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

## WebServer 模式

```bash
# 启动 WebServer
uv run ainiee --web-mode

# 访问地址
http://127.0.0.1:15720
```
