新增 README：原理、构建、API 用法、公共端点与模型列表

# NoCost

AI 免费转发服务：聚合多个免费 API（转发器），自动路由到**最快**或**最智能**的模型，支持错误重试与自动回退，对外保持 OpenAI 兼容接口。

> ⚠️ 注意：当前接入的模型提供商会收集用户数据，**请勿用于隐私敏感场景**（详见[注意事项](#注意事项)）。

## 原理

1. **转发器（Repeater）**：每个上游 API（如 OpenRouter）是一个转发器，用 `Name` + `Key` 标识，端点地址内置于转发器类型。

2. **模型（Model）**：描述模型名、所属转发器、模态、智能等级、隐私级别。

3. **路由**：`ModelPool` 维护每个模型的延迟（EMA）与错误率统计，按选择模式排行：

   - `Fast`（默认）：最快且错误率最低；

   - `Smart`：最智能且可用；

   - `FastSmart`：速度与智能加权平衡（各 50%）。

   - 请求有小概率（默认 10%）落到非最优模型，用于刷新排行。

4. **回退**：首选模型失败时自动尝试下一个候选，全部失败返回 502。

5. **隐私阈值**：请求可声明隐私级别，只命中 `PrivacyMode <= 阈值` 的模型。

## 从源码构建

前置：.NET 10 SDK（解决方案为 SLNX 格式）。

```bash

# 还原 + 构建

dotnet restore NoCost.slnx

dotnet build NoCost.slnx -c Release

# 运行

dotnet run --project src/NoCost/NoCost.csproj

# 测试（注意：必须使用无参 dotnet test）

dotnet test

```

### 配置（appsettings.json）

```jsonc

{

  "RepeaterConfig": [

    { "Name": "openrouter", "Key": "env:OPENROUTER_API_KEY" }

  ],

  "ModelsConfig": [

    {

      "Model": "nvidia/nemotron-3-ultra-550b-a55b:free",

      "Repeater": "openrouter",

      "Modal": "Text",

      "SmartLevel": 100,

      "PrivacyMode": "Both"

    }

  ]

}

```

- `Key` 支持 `env:XXX` 引用环境变量。

- `PrivacyMode`：`Safe`（不保留不训练）/ `CollectOnly`（保留不训练）/ `TrainOnly`（保留对称）/ `Both`（保留且训练）。

## API 用法（OpenAI 兼容）

| 端点 | 说明 |

|---|---|

| `GET /v1/models` | 模型列表（含 `privacy_mode`） |

| `POST /v1/chat/completions` | 对话补全，支持 `stream: true`（SSE） |

**选择模式**（Authorization 头，任意 Bearer 均可）：

```http

Authorization: Bearer {"selectmode":"smart"}

```

`selectmode` 取值：`fast`（默认）/ `fast-smart` / `smart`。

**隐私级别**（自定义头优先，可省略）：

```http

Authorization: Bearer {"selectmode":"smart","privacy":"both"}

X-Private-Mode: collect-only   # 存在则覆盖 authorization 里的 privacy

```

`X-Private-Mode` 取值：`safe` / `collect-only` / `train-only` / `both`（别名 `on/1`、`off/0` 等）。

## 公共端点

- 反向代理（HTTPS）：`https://shrabbit.com:5120/v1`

  - `https://shrabbit.com:5120/v1/models`

  - `https://shrabbit.com:5120/v1/chat/completions`

- 本机直连：`http://127.0.0.1:8081/v1`

## 公共可用模型列表

| 模型 | 隐私模式 | 智能等级 |

|---|---|---|

| `nvidia/nemotron-3-ultra-550b-a55b:free` | Both | 100 |

| `poolside/laguna-s-2.1:free` | Both | 99 |

| `nvidia/nemotron-3.5-lightning:free` | Both | 98 |

| `nvidia/nemotron-3-super-120b-a12b:free` | Both | 97 |

| `cohere/north-mini-code:free` | CollectOnly | 96 |

| `poolside/laguna-xs-2.1:free` | Both | 95 |

## 注意事项

- **数据收集**：以上模型的提供商（nvidia / poolside / cohere）会收集用户数据用于训练，**请勿用于隐私敏感场景**。若要严格隐私，请配置 `PrivacyMode: Safe` 的模型并请求 `X-Private-Mode: safe`（当前列表内无 Safe 模型，严格隐私会返回 502）。

- **免费层过载**：免费模型可能偶发 `Service temporarily overloaded`（502），服务会按配置回退到下一个候选。

- **reasoning 模型**：部分模型会把 token 消耗在推理上，`max_tokens` 过小时 `content` 可能为 `null`，建议适当调大。

- **Bearer 说明**：服务接受任意 Bearer；若 token 为 `{"selectmode":...}` 形式则按 JSON 解析路由选项。

## 贡献

1. Fork 并基于 `master` 新建分支。

2. 修改代码并补充/更新单元测试（xunit v3）。

3. 本地跑通 `dotnet test`（必须无参）。

4. 提交并创建 Merge Request。

5. 涉及重大架构/功能变更时，同步更新 `CLAUDE.md`。