# FineProxy Agent Pack

版本：2026-09-22

使用此文件评估现有代理集成能否迁移到 FineProxy。此文件不包含 API 密钥、账户数据或私有端点。

## 事实依据

- 交互式客户端 API 文档：`https://fineproxy.org/account_new/docs`
- MCP 设置：`https://fineproxy.org/account_new/mcp`
- 当前客户端 OpenAPI 规范：请从客户控制面板的 API 文档中下载。
- 创建和管理 API 密钥：`https://fineproxy.org/account_new/settings`
- MCP 端点：`https://fineproxy.org/account_new/api/v1/mcp`

切勿根据此概览虚构端点。请求路径、架构、参数和响应应以当前 OpenAPI 规范为准。

## 平台概览

- REST API：OpenAPI 3.1，包含 49 项有文档记录的客户操作。
- MCP：通过无状态 JSON-RPC 2.0 和 Streamable HTTP 提供 49 个工具。
- 身份验证：在客户控制面板中创建的 bearer API 密钥。
- API 和 MCP 使用相同的权限范围。
- 合作伙伴 API 文档仅对具备有效合作伙伴状态的账户可见。

## 支持的工作流程

### 购买与配置

- 列出国家/地区和实时 IP 库存。
- 在不购买的情况下为精确的多国家/地区套餐报价。
- 使用价格保护和幂等键从控制面板钱包购买。

标准 MCP 购买顺序为：

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### 服务管理

- 读取和管理服务。
- 在支持的情况下续订、暂停、恢复或取消服务。
- 启用或禁用自动续订。
- 更换或添加 IP 地址。
- 更改服务凭据。
- 读取和管理允许列表限制。
- 列出、购买和取消兼容的附加项。

### 分析与诊断

- 使用情况概览和时间序列。
- 主要目标地址。
- 错误类别。
- 运维建议。

### 账单与支持

- 读取账单并下载账单 PDF。
- 列出支付网关。
- 发起钱包充值并读取其状态。
- 创建、读取、回复和关闭支持工单。

### 代理访问与账户

- 读取轮换代理连接配置。
- 更改服务登录名和密码。
- 管理允许列表中每个 IP 的连接限制。
- 读取个人资料信息、调用方 IP 和登录历史记录。
- 配置 Webhook。

## 权限范围

- `customer:read` — 读取客户和账户信息。
- `customer:write` — 更新客户信息。
- `wallet:read` — 读取钱包信息。
- `wallet:deposit` — 创建并监控充值。
- `wallet:spend` — 支出钱包资金。应将其视为财务权限。
- `services:read` — 读取服务和代理设置。
- `services:write` — 创建或修改服务及附加项。
- `tickets:read` — 读取支持工单。
- `tickets:write` — 创建、回复、更新或关闭工单。
- `catalog:read` — 读取产品、选项、国家/地区和库存。
- `usage:read` — 读取使用情况和诊断数据。
- `webhooks` — 管理 Webhook 订阅。

迁移审计应从只读权限开始。仅在审核提议的变更后，才添加写入或财务权限。

## 安全行为

- 财务工具需要 `wallet:spend`。
- 购买操作会携带报价中的预期总额。价格不匹配时，操作将被拒绝。
- 不可逆操作需要显式确认。
- 财务请求重试使用幂等键，避免同一操作被重复扣费。
- 实时库存、套餐资格和账户权限可能阻止原本有效的操作。
- FineProxy MCP 用于操作客户账户。除非用户另行向编码智能体授予代码仓库访问权限，否则它无法访问源代码。

## MCP 配置模板

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

请将真实密钥存储在环境变量或机密管理器中。不要将其与 MCP 配置一同提交。

## 迁移兼容性检查清单

检查现有集成中的以下内容：

1. 提供商客户端初始化和所有提供商专用导入。
2. 身份验证请求头、凭据、环境变量和机密存储。
3. 购买、续订、取消和 IP 更换工作流程。
4. 国家/地区标识符和库存假设。
5. 代理列表格式、协议、端口、用户名、密码和 IP 允许列表。
6. 分页和筛选。
7. 重试行为、超时处理和幂等性。
8. 错误模型和速率处理。
9. 使用情况分析和诊断。
10. 账单、发票和充值。
11. 支持工单集成。
12. Webhook 和事件负载假设。
13. 与当前提供商绑定的测试、固定测试数据、模拟对象和 CI 机密。

将每个工作流程归入以下类别：

- 无需更改即可兼容。
- 通过配置变更即可兼容。
- 需要适配器或数据转换。
- 需要不同的运维工作流程。
- 不受支持或当前文档尚未确认。

## 必需的审计输出

审计应包括：

1. 每项当前提供商依赖的清单。
2. 逐工作流程的兼容性评估。
3. 所需的 FineProxy 权限范围。
4. 将会更改的确切文件和代码路径。
5. 身份验证和机密管理方面的变更。
6. 需要当前 OpenAPI 规范或支持团队确认的待确认问题。
7. 包含回滚方案的分阶段迁移计划。
8. 切换前所需的集成测试。

首次审计期间请勿修改代码。