# coding-plan-usage

**Repository Path**: dorne/coding-plan-usage

## Basic Information

- **Project Name**: coding-plan-usage
- **Description**: coding-plan 额度查询，支持火山和MiniMax
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# coding-plan-usage

AI 供应商 Coding Plan 套餐用量查询 CLI 工具。支持 MiniMax 和火山引擎（Volcengine），可按账号组查询，适合多账号日常监控。

---

## 功能概述

| 功能 | 说明 |
|------|------|
| 查询用量 | 无头浏览器自动打开目标页面，抓取并格式化套餐用量数据 |
| 多供应商 | MiniMax Token Plan、火山引擎 Coding Plan，可扩展 |
| 多账号组 | 通过 `--group` 切换不同账号，Session 隔离保存 |
| 登录持久化 | Chrome 用户数据持久化，登录一次，长期有效 |
| 无头模式 | 默认无头运行，`--show` 可打开可见窗口调试 |

---

## 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Python | ≥ 3.9 | 运行时 |
| [DrissionPage](https://github.com/g1879/DrissionPage) | ≥ 4.1 | 浏览器自动化，复用系统 Chrome，无需驱动 |
| [Click](https://click.palletsprojects.com/) | ≥ 8.1 | CLI 参数解析 |
| [uv](https://docs.astral.sh/uv/) | 最新 | 依赖管理与虚拟环境 |
| [PyInstaller](https://pyinstaller.org/) | ≥ 6.0 | 打包为 onedir 可执行文件 |
| [UPX](https://upx.github.io/) | 最新 | 压缩打包产物体积 |

---

## 运行环境要求

- Windows 10/11（64 位）
- 系统已安装 **Google Chrome**（DrissionPage 直接调用，无需 ChromeDriver）
- Python ≥ 3.9（开发 / 调试环境）
- uv（开发 / 调试环境）

---

## 项目结构

```
coding-plan-usage/
├── src/coding_plan_usage/
│   ├── main.py                  # CLI 入口、浏览器创建、登录/查询调度
│   └── plan/
│       ├── minimax.py           # MiniMax 查询解析
│       ├── volcengine.py        # 火山引擎查询解析
│       └── debug_net.py         # --debug 模式网络请求捕获
├── config.json                  # 供应商配置（URL、账号组）
├── browser-data/                # 各账号 Chrome 用户数据（登录后自动生成）
│   ├── minimax/main/
│   └── volcengine/main/
├── coding-plan-usage.spec       # PyInstaller 打包配置
├── pyproject.toml
└── doc/
    ├── plan/                    # 需求与实施计划
    └── improve/                 # 优化复盘记录
```

---

## 配置文件

`config.json` 放于可执行文件同目录（打包后）或项目根目录（开发时）：

```json
{
  "minimax": {
    "login_url": "https://platform.minimaxi.com/login",
    "usage_group": {
      "main": {
        "browser_data_name": "main",
        "query_url": "https://platform.minimaxi.com/user-center/payment/token-plan"
      }
    }
  },
  "volcengine": {
    "login_url": "https://console.volcengine.com/auth/login",
    "usage_group": {
      "main": {
        "browser_data_name": "main",
        "query_url": "https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&advancedActiveKey=subscribe"
      }
    }
  }
}
```

---

## 命令行用法

### 登录（首次使用必须）

```powershell
# MiniMax 登录
coding-plan-usage --provider=minimax --login

# 火山引擎登录（指定账号组）
coding-plan-usage --provider=volcengine --group=sub --login
```

登录流程：打开 Chrome 窗口 → 手动完成登录 → 程序检测到 URL 跳转后自动保存 Session → 关闭浏览器。

### 查询用量

```powershell
# 默认无头模式
coding-plan-usage --provider=minimax
coding-plan-usage --provider=volcengine

# 显示 Chrome 窗口（调试用）
coding-plan-usage --provider=minimax --show

# 指定账号组
coding-plan-usage --provider=minimax --group=sub
```

### 调试网络请求

```powershell
# 打印页面加载时所有网络请求 URL（排查接口名称用）
coding-plan-usage --provider=volcengine --debug
```

### 完整参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--provider` | 必填 | 供应商：`minimax` / `volcengine` |
| `--group` | `main` | 账号组，对应 config.json 中的 usage_group key |
| `--login` | False | 执行登录流程 |
| `--show` | False | 显示 Chrome 窗口（默认无头） |
| `--debug` | False | 打印所有网络请求 |

---

## 开发环境搭建

```powershell
# 1. 安装 uv（若未安装）
winget install astral-sh.uv

# 2. 克隆项目
git clone <repo> coding-plan-usage
cd coding-plan-usage

# 3. 安装依赖（含 dev 依赖 pyinstaller）
uv sync -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 运行
uv run coding-plan-usage --provider=minimax
```

### 常用 uv 调试命令

```powershell
# 安装 / 同步依赖
uv sync -i https://pypi.tuna.tsinghua.edu.cn/simple

# 修改源码后重新安装（使修改立即生效）
uv sync --reinstall-package coding-plan-usage -i https://pypi.tuna.tsinghua.edu.cn/simple

# 添加新依赖
uv add <package> -i https://pypi.tuna.tsinghua.edu.cn/simple

# 添加 dev 依赖
uv add --dev <package> -i https://pypi.tuna.tsinghua.edu.cn/simple

# 查看当前已安装的包
uv pip list

# 在 uv 虚拟环境中运行任意命令
uv run <command>

# 直接进入 uv 管理的 Python 交互式环境
uv run python

# 查看依赖树
uv tree
```

---

## 打包交付

### 前置条件

1. 下载 [UPX](https://upx.github.io/)，解压到本地目录
2. 编辑 `coding-plan-usage.spec` 第 15 行，填入 UPX 目录路径：
   ```python
   UPX_DIR = r'C:\tools\upx-4.2.4-win64'   # 若 UPX 已在 PATH 则保持 None
   ```

### 一键打包（推荐）

在**项目根目录**执行：

```powershell
cd C:\Users\dorne\Downloads\coding-plan-usage
uv run python build.py
```

`build.py` 自动完成：重新安装源码包 → PyInstaller 打包 → 复制 `config.json` → 复制 `browser-data/`（若存在）。

### 手动执行打包

```powershell
uv run pyinstaller coding-plan-usage.spec --clean
```

### 产物结构

```
dist/coding-plan-usage/       ← 交付此文件夹 + config.json
├── coding-plan-usage.exe
├── config.json               ← 从项目根手动复制
└── _internal/                ← 运行时依赖，勿删
```

### 用户使用流程

```
1. 将 dist/coding-plan-usage/ 和 config.json 放在同一目录
2. 首次运行登录：coding-plan-usage.exe --provider=minimax --login
3. 后续查询：coding-plan-usage.exe --provider=minimax
```

> `browser-data/` 目录在首次登录后自动生成，无需手动创建或打包。

---

## 反爬虫 / 反检测机制

无头模式下 Chrome 会暴露多项自动化特征，现代网站（如 MiniMax）会检测并拦截。本项目在 `create_browser()` 中实现了七层防护：

| 层级 | 措施 | 说明 |
|------|------|------|
| 启动参数 | `--disable-blink-features=AutomationControlled` | 禁用 Chrome 自动化标志 |
| 启动参数 | `--headless=new` | Chrome 112+ 新架构 headless，渲染管线与真实浏览器一致，特征更难被识别 |
| 启动参数 | `--window-size=1920,1080` | 使用常见分辨率，与 screen 注入保持一致 |
| ChromiumOptions | `set_user_agent(...)` | 伪装为正常 UA，去掉 `HeadlessChrome` 字样 |
| CDP 注入 | `navigator.webdriver → undefined` | 最基础的 bot 检测指标 |
| CDP 注入 | `window.chrome` / `navigator.plugins` / `navigator.languages` / `navigator.permissions` | 伪造真实 Chrome 特征对象与多语言环境 |
| CDP 注入 | `screen.width/height → 1920×1080` / `colorDepth → 24` | 防止 screen 尺寸为 0 或与 viewport 不符被检测 |

CDP 脚本通过 `Page.addScriptToEvaluateOnNewDocument` 注入，**在每个页面文档加载前执行**，保证所有属性在页面 JS 运行前已就绪。

> `screen` 属性已用 `try/catch` 包裹，部分 Chrome 版本中该属性不可重定义时静默跳过，不影响其他项注入。

---

## 新增供应商

1. 在 `src/coding_plan_usage/plan/` 新建 `newprovider.py`，实现 `query(page, query_url) -> str`
2. 在 `main.py` 的 `_QUERY_MODULES` 字典中加一行：
   ```python
   'newprovider': 'coding_plan_usage.plan.newprovider',
   ```
3. 在 `config.json` 补充对应供应商配置
4. 在 `coding-plan-usage.spec` 的 `hiddenimports` 中加入模块路径