# 功能特性

## 多协议支持

Kiro Proxy 支持三种主流 AI API 协议，可以适配不同的客户端：

| 协议 | 端点 | 适用客户端 |
|------|------|------------|
| OpenAI | `/v1/chat/completions` | Codex CLI, ChatGPT 客户端 |
| Anthropic | `/v1/messages` | Claude Code, Claude 客户端 |
| Gemini | `/v1/models/{model}:generateContent` | Gemini CLI |

代理会自动将请求转换为 Kiro API 格式，响应转换回对应协议格式。

---

## 工具调用支持

完整支持三种协议的工具调用功能：

### Anthropic 协议（Claude Code）

- `tools` 定义和 `tool_result` 响应完整支持
- `tool_choice: required` 支持（通过 prompt 注入）
- `web_search` 特殊工具自动识别
- 工具数量限制（最多 50 个）
- 描述截断（超过 500 字符自动截断）

### OpenAI 协议（Codex CLI）

- `tools` 定义（function 类型）
- `tool_calls` 响应处理
- `tool` 角色消息转换
- `tool_choice: required/any` 支持
- 工具数量限制和描述截断

### Gemini 协议

- `functionDeclarations` 工具定义
- `functionCall` 响应处理
- `functionResponse` 工具结果
- `toolConfig.functionCallingConfig.mode` 支持（ANY/REQUIRED）
- 工具数量限制和描述截断

### 历史消息修复

Kiro API 要求消息必须严格交替（user → assistant → user → assistant），代理会自动：

- 检测并修复连续的同角色消息
- 合并重复的 tool_results
- 插入占位消息保持交替

---

## 多账号管理

### 账号轮询

支持添加多个 Kiro 账号，代理会自动轮询使用（默认随机）：

- 每次请求随机选择一个可用账号（尽量避免连续命中同一账号）
- 自动跳过冷却中或不健康的账号
- 分散请求压力，降低单账号 RPM 过高导致封禁风险

### 会话粘性（可选）

为了保持对话上下文的连贯性，在非 `random` 策略下会启用会话粘性：

- 同一会话 ID 在 60 秒内会使用同一账号
- 超过 60 秒或账号不可用时才切换
- 会话 ID 由请求内容生成；可通过 `~/.kiro-proxy/priority.json` 中的 `strategy` 调整策略

### 账号状态

每个账号有四种状态：

| 状态 | 说明 | 颜色 |
|------|------|------|
| Active | 正常可用 | 绿色 |
| Cooldown | 触发限流，冷却中 | 黄色 |
| Unhealthy | 健康检查失败 | 红色 |
| Disabled | 手动禁用 | 灰色 |

---

## Token 自动刷新

### 自动检测

- 后台每 5 分钟检查所有账号的 Token 状态
- 检测 Token 是否即将过期（15 分钟内）

### 自动刷新

- 发现即将过期的 Token 自动刷新
- 支持 Social 认证（Google/GitHub）的 refresh_token
- 刷新失败会标记账号为不健康

### 手动刷新

- 在账号卡片点击「刷新 Token」
- 或点击「刷新所有 Token」批量刷新

---

## 配额管理

### 429 自动处理

当 Kiro API 返回 429 (Too Many Requests) 时：

1. 自动将该账号标记为 Cooldown 状态
2. 设置 5 分钟冷却时间
3. 立即切换到其他可用账号重试
4. 冷却结束后自动恢复

### 手动恢复

如果需要提前恢复账号：

1. 在「监控」页面查看配额状态
2. 点击账号旁的「恢复」按钮

---

## 流量监控

### 请求记录

记录所有经过代理的 LLM 请求：

- 请求时间、模型、账号
- 输入/输出 Token 数量
- 响应时间、状态码
- 完整的请求和响应内容

### 搜索过滤

- 按协议筛选（OpenAI/Anthropic/Gemini）
- 按状态筛选（完成/错误/进行中）
- 关键词搜索

### 导出功能

- 支持导出为 JSON 格式
- 可选择导出全部或指定记录

---

## 登录方式

### Google 登录

使用 Google 账号通过 OAuth 授权登录。

### GitHub 登录

使用 GitHub 账号通过 OAuth 授权登录。

### AWS Builder ID

使用 AWS Builder ID 通过 Device Code Flow 登录：

1. 点击 AWS 登录按钮
2. 复制显示的授权码
3. 在浏览器中打开授权页面
4. 输入授权码完成登录

---

## 历史消息管理

### 对话长度限制

Kiro API 有输入长度限制，当对话历史过长时会返回 `CONTENT_LENGTH_EXCEEDS_THRESHOLD` 错误。

代理内置了多种策略自动处理这个问题：

### 可用策略

| 策略 | 说明 | 触发时机 |
|------|------|----------|
| 自动截断 | 优先保留最新上下文并摘要前文，必要时截断 | 每次请求前 |
| 智能摘要 | 用 AI 生成早期对话摘要 | 超过阈值时 |
| 错误重试 | 遇到长度错误时截断重试 | 收到错误后 |
| 预估检测 | 预估 token 数量，超限预先截断 | 每次请求前 |

### 配置选项

在「设置」页面可以配置：

- **最大消息数** - 自动截断时保留的消息数量（默认 30）
- **最大字符数** - 自动截断时的字符数限制（默认 150000）
- **重试保留数** - 错误重试时保留的消息数（默认 20）
- **最大重试次数** - 错误重试的最大次数（默认 2）
- **摘要保留数** - 智能摘要时保留的最近消息数（默认 10）
- **摘要阈值** - 触发智能摘要的字符数阈值（默认 100000）
- **添加警告** - 截断时是否在日志中记录

### 推荐配置

- **默认**：只启用「错误重试」，遇到问题时自动处理
- **保守**：启用「智能摘要 + 错误重试」，保留关键信息
- **激进**：启用「自动截断 + 预估检测」，预防性截断

---

## 配置持久化

### 自动保存

账号配置自动保存到 `~/.kiro-proxy/config.json`：

- 账号列表和状态
- 启用/禁用设置
- Token 文件路径

### 重启恢复

重启代理后自动加载保存的配置，无需重新添加账号。

### 导入导出

- 「导出配置」下载当前配置
- 「导入配置」从文件恢复