opencode-qwen-cli-auth 2.2.8 → 2.3.0

package/README.md

@@ -1,31 +1,28 @@
 # opencode-qwen-cli-auth
-OAuth plugin for OpenCode that lets you use Qwen models with your Qwen account, without managing a DashScope API key directly.
 
-## Scope
-
-- Uses OAuth Device Authorization Grant (RFC 8628) for sign-in.
-- Best suited for personal/dev workflows.
-- For production or commercial workloads, use DashScope API key auth instead:
-  https://dashscope.console.aliyun.com/
+OAuth plugin for [OpenCode](https://opencode.ai) to use Qwen for free via Qwen Account, compatible with the [qwen-code CLI](https://github.com/QwenLM/qwen-code) mechanism.
 
 ## Features
 
-- OAuth login through `opencode auth login`.
-- Automatic token refresh before expiration.
-- Dynamic API base URL from token `resource_url` with safe fallback.
-- Model normalization to `coder-model` for Qwen Portal API.
-- Optional prompt bridge behavior via `QWEN_MODE`.
-- Optional debug and request logging via environment variables.
+- **OAuth 2.0 Device Authorization Grant** (RFC 8628) - login with your Qwen Account
+- **No API key required** - utilize Qwen's free tier
+- **Automatic token refresh** when expired
+- **DashScope compatibility** - automatically injects required headers for the OAuth flow
+- **Smart output token limit** - auto-caps tokens based on model (65K for coder-model, 8K for vision-model)
+- **Retry & Fallback** - handles quota/rate limit errors with payload degradation mechanism
+- **Logging & Debugging** - detailed debugging support via environment variables
+
+## Installation
 
-## Requirements
+### Requirements
 
-- Qwen account
-- OpenCode
-- Node.js `>=20` (only required when building/testing from source)
+- Node.js >= 20.0.0
+- OpenCode with plugin support
+- Qwen Account (free)
 
-## Quick start
+### Add to OpenCode
 
-Add the plugin to your OpenCode config:
+Configure in `opencode.json`:
 
 ```json
 {
@@ -35,128 +32,230 @@ Add the plugin to your OpenCode config:
 }
 ```
 
-Then sign in:
+### Login
 
 ```bash
 opencode auth login
 ```
 
-Choose `Qwen Code` -> `Qwen Code (qwen.ai OAuth)`.
+Select provider **Qwen Code (qwen.ai OAuth)** and follow the instructions:
 
-## Usage
+1. Open the URL displayed in the terminal
+2. Enter the provided code
+3. The plugin will automatically poll and save the token
 
-```bash
-opencode run "create a hello world file" --model=qwen-code/coder-model
-opencode chat --model=qwen-code/coder-model
-```
+## Supported Models
 
-Always keep the provider prefix `qwen-code/` in model configuration.
+| Model | ID | Context | Max Output | Cost |
+|-------|-----|---------|------------|---------|
+| Qwen Coder (Qwen 3.5 Plus) | `coder-model` | 1M tokens | 65,536 tokens | Free |
+| Qwen VL Plus (Vision) | `vision-model` | 128K tokens | 8,192 tokens | Free |
 
 ## Configuration
 
-### `QWEN_MODE`
+### Environment Variables
 
-Resolution order:
+| Variable | Description | Value |
+|------|-------|---------|
+| `QWEN_CLI_PATH` | Path to qwen CLI (for fallback) | Default: auto-detect |
+| `QWEN_MODE` | Qwen mode toggle | `1`/`true` (default) |
+| `DEBUG_QWEN_PLUGIN=1` | Enable debug logging | Optional |
+| `ENABLE_PLUGIN_REQUEST_LOGGING=1` | Enable request logging to file | Optional |
+| `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1` | Enable CLI fallback on quota error | Optional |
 
-1. Environment variable `QWEN_MODE`
-2. File `~/.opencode/qwen/auth-config.json`
-3. Default value: `true`
+### Debug & Logging
 
-Example `~/.opencode/qwen/auth-config.json`:
+```bash
+# Debug mode - logs to console
+DEBUG_QWEN_PLUGIN=1 opencode run "hello" --model=qwen-code/coder-model
 
-```json
-{
-  "qwenMode": true
-}
+# Request logging - saves detailed JSON files
+ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "hello" --model=qwen-code/coder-model
 ```
 
-Supported env values:
-
-- Enable: `QWEN_MODE=1` or `QWEN_MODE=true`
-- Disable: `QWEN_MODE=0` or `QWEN_MODE=false`
+Log files are stored at: `~/.opencode/logs/qwen-plugin/`
 
-## Logging and debug
+## How It Works
 
-- Enable debug logs:
+### OAuth Flow
 
-```bash
-DEBUG_QWEN_PLUGIN=1 opencode run "your prompt"
+```
+1. OpenCode requests auth -> Plugin
+2. Plugin requests device code from Qwen OAuth Server
+3. Displays URL + code to user
+4. User opens URL and enters code to authorize
+5. Plugin polls token from Qwen OAuth Server
+6. Saves token and returns to OpenCode
+7. All API requests are injected with headers and sent to DashScope
 ```
 
-- Enable request logging to files:
+### Token Storage
 
-```bash
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "your prompt"
-```
+- **Location**: `~/.qwen/oauth_creds.json`
+- **Format**: JSON with access_token, refresh_token, expiry_date, resource_url
+- **Auto-refresh**: Triggered when less than 30 seconds to expiration
+- **Lock mechanism**: Safe multi-process token refresh
 
-Log path: `~/.opencode/logs/qwen-plugin/`
+### Required Headers
 
-## Local plugin data
+The plugin automatically injects required headers for DashScope OAuth:
 
-- OAuth token: `~/.opencode/qwen/oauth_token.json`
-- Plugin config: `~/.opencode/qwen/auth-config.json`
-- Prompt cache: `~/.opencode/cache/`
+```
+X-DashScope-AuthType: qwen-oauth
+X-DashScope-CacheControl: enable
+User-Agent: opencode-qwen-cli-auth/{version}
+X-DashScope-UserAgent: opencode-qwen-cli-auth/{version}
+```
 
-## Troubleshooting
+## Error Handling
 
-### `Authentication required. Please run: opencode auth login`
+### Insufficient Quota
 
-Token is missing or refresh failed. Re-authenticate:
+When hitting a `429 insufficient_quota` error, the plugin automatically:
 
-```bash
-opencode auth login
-```
+1. **Degrades payload** - removes tools, reduces max_tokens to 1024
+2. **Retries** - attempts request with degraded payload
+3. **CLI fallback** (optional) - invokes `qwen` CLI if `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1` is set
 
-### Device authorization timed out
+### Token Expiration
 
-The device code expired or was not confirmed in time. Run `opencode auth login` again and confirm in the browser sooner.
+- Automatically uses refresh token
+- Retries up to 2 times for transient errors (timeout, network)
+- Clears token and requests re-auth on 401/403
 
-### `429` rate limit
+## Authentication Management
 
-The server is throttling requests. Reduce request frequency and retry later.
+### Check Status
 
-### Wrong model behavior
+```bash
+# View saved token
+cat ~/.qwen/oauth_creds.json
+```
 
-Ensure your model is set correctly in OpenCode:
+### Remove Authentication
 
-```yaml
-model: qwen-code/coder-model
+**PowerShell:**
+```powershell
+Remove-Item -Recurse -Force "$HOME/.opencode/qwen"
+Remove-Item -Force "$HOME/.qwen/oauth_creds.json"
 ```
 
-## Clear auth state
+**Bash (Linux/macOS):**
+```bash
+rm -rf ~/.opencode/qwen
+rm ~/.qwen/oauth_creds.json
+```
 
-- macOS/Linux:
+### Manual Refresh
 
 ```bash
-rm -rf ~/.opencode/qwen/
+# Clear old token and login again
+opencode auth logout
+opencode auth login
 ```
 
-- PowerShell:
+## Plugin Architecture
 
-```powershell
-Remove-Item -Recurse -Force "$HOME/.opencode/qwen"
 ```
+dist/
+├── index.js              # Entry point, exports QwenAuthPlugin
+├── lib/
+│   ├── auth/
+│   │   ├── auth.js       # OAuth flow: device code, poll token, refresh
+│   │   └── browser.js    # Browser opener utility
+│   ├── config.js         # Config paths, QWEN_MODE
+│   ├── constants.js      # Constants: OAuth endpoints, headers, errors
+│   ├── logger.js         # Logging utilities
+│   └── types.js          # TypeScript types
+```
+
+### Internal Hooks Used
+
+| Hook | Purpose |
+|------|----------|
+| `auth.loader` | Provides apiKey, baseURL, custom fetch |
+| `auth.methods.authorize` | Device Authorization OAuth flow |
+| `config` | Registers provider and models |
+| `chat.params` | Sets timeout, maxRetries, max_tokens limits |
+| `chat.headers` | Injects DashScope headers |
+
+## Comparison with Previous Plugin
+
+| Feature | Old Plugin | This Plugin |
+|-----------|-----------|------------|
+| OAuth Device Flow | ✓ | ✓ |
+| Custom fetch layer | ✗ | ✓ |
+| DashScope headers | ✗ | ✓ (auto-inject) |
+| Output token capping | ✗ | ✓ |
+| Quota degradation | ✗ | ✓ |
+| CLI fallback | ✗ | ✓ (optional) |
+| Multi-process lock | ✗ | ✓ |
+| Legacy token migration | ✗ | ✓ |
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Persistent `insufficient_quota` errors**
+- Your account may have exhausted the free tier quota
+- Try deleting the token and logging in again
+- Enable CLI fallback: `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1`
+
+**2. OAuth timeout**
+- Check network connection
+- Increase timeout in config if needed
+- View detailed logs with `DEBUG_QWEN_PLUGIN=1`
 
-Then log in again with `opencode auth login`.
+**3. Cannot find qwen CLI**
+- Install qwen-code: `npm install -g @qwen-code/qwen-code`
+- Or set env var: `QWEN_CLI_PATH=/path/to/qwen`
+
+**4. Token not saving**
+- Check write permissions for `~/.qwen/` directory
+- View logs with `ENABLE_PLUGIN_REQUEST_LOGGING=1`
 
 ## Development
 
+### Build
+
 ```bash
+npm install
 npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+### Type Check
+
+```bash
 npm run typecheck
-npm run test
-npm run lint
 ```
 
-## Policy and links
+### Lint & Format
 
-- Terms of Service: https://qwen.ai/termsservice
-- Privacy Policy: https://qwen.ai/privacypolicy
-- Usage Policy: https://qwen.ai/usagepolicy
-- NPM: https://www.npmjs.com/package/opencode-qwen-cli-auth
-- Repository: https://github.com/TVD-00/opencode-qwen-cli-auth
-- Issues: https://github.com/TVD-00/opencode-qwen-cli-auth/issues
+```bash
+npm run lint
+npm run format
+```
 
 ## License
 
 MIT
+
+## Repository
+
+- **Source**: https://github.com/TVD-00/opencode-qwen-cli-auth
+- **Issues**: https://github.com/TVD-00/opencode-qwen-cli-auth/issues
+- **NPM**: https://www.npmjs.com/package/opencode-qwen-cli-auth
+
+## Author
+
+Geoff Hammond
+
+## Contributing
+
+All contributions (PRs, issues, feedback) are welcome at the GitHub repository.

package/README.vi.md

@@ -0,0 +1,261 @@
+# opencode-qwen-cli-auth
+
+Plugin OAuth cho [OpenCode](https://opencode.ai) để sử dụng Qwen miễn phí thông qua Qwen Account, tương thích với cơ chế của [qwen-code CLI](https://github.com/QwenLM/qwen-code).
+
+## Tính năng
+
+- **OAuth 2.0 Device Authorization Grant** (RFC 8628) - đăng nhập bằng Qwen Account
+- **Không cần API key** - sử dụng free tier của Qwen
+- **Tự động refresh token** khi hết hạn
+- **Tương thích DashScope** - tự động inject headers cần thiết cho OAuth flow
+- **Giới hạn output token thông minh** - tự động cap theo model (65K cho coder-model, 8K cho vision-model)
+- **Retry & Fallback** - xử lý lỗi quota/rate limit với cơ chế degrade (giảm tải payload)
+- **Logging & Debugging** - hỗ trợ debug chi tiết qua biến môi trường
+
+## Cài đặt
+
+### Yêu cầu
+
+- Node.js >= 20.0.0
+- OpenCode có hỗ trợ plugin
+- Qwen Account (miễn phí)
+
+### Thêm vào OpenCode
+
+Cấu hình trong file `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-qwen-cli-auth"],
+  "model": "qwen-code/coder-model"
+}
+```
+
+### Đăng nhập
+
+```bash
+opencode auth login
+```
+
+Chọn provider **Qwen Code (qwen.ai OAuth)** và làm theo hướng dẫn:
+
+1. Mở URL hiển thị trong terminal
+2. Nhập mã code được cung cấp
+3. Plugin sẽ tự động poll và lưu token
+
+## Models hỗ trợ
+
+| Model | ID | Context | Max Output | Chi phí |
+|-------|-----|---------|------------|---------|
+| Qwen Coder (Qwen 3.5 Plus) | `coder-model` | 1M tokens | 65,536 tokens | Miễn phí |
+| Qwen VL Plus (Vision) | `vision-model` | 128K tokens | 8,192 tokens | Miễn phí |
+
+## Cấu hình
+
+### Biến môi trường
+
+| Biến | Mô tả | Giá trị |
+|------|-------|---------|
+| `QWEN_CLI_PATH` | Đường dẫn đến qwen CLI (cho fallback) | Mặc định: tự động tìm |
+| `QWEN_MODE` | Bật/tắt Qwen mode | `1`/`true` (mặc định) |
+| `DEBUG_QWEN_PLUGIN=1` | Bật debug logging | Tùy chọn |
+| `ENABLE_PLUGIN_REQUEST_LOGGING=1` | Bật ghi log request ra file | Tùy chọn |
+| `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1` | Bật tính năng gọi CLI khi hết quota | Tùy chọn |
+
+### Debug & Logging
+
+```bash
+# Debug mode - in log ra console
+DEBUG_QWEN_PLUGIN=1 opencode run "hello" --model=qwen-code/coder-model
+
+# Request logging - lưu chi tiết vào file JSON
+ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "hello" --model=qwen-code/coder-model
+```
+
+File log được lưu tại: `~/.opencode/logs/qwen-plugin/`
+
+## Cơ chế hoạt động
+
+### Luồng OAuth (OAuth Flow)
+
+```
+1. OpenCode yêu cầu xác thực -> Plugin
+2. Plugin xin cấp device code từ Qwen OAuth Server
+3. Hiển thị URL + code cho người dùng
+4. Người dùng mở URL và nhập code để ủy quyền
+5. Plugin liên tục gọi (poll) Qwen OAuth Server để lấy token
+6. Lưu token và trả về cho OpenCode
+7. Tất cả request API sẽ được đính kèm headers và gửi đến DashScope
+```
+
+### Lưu trữ Token
+
+- **Vị trí**: `~/.qwen/oauth_creds.json`
+- **Định dạng**: JSON chứa access_token, refresh_token, expiry_date, resource_url
+- **Tự động refresh**: Kích hoạt khi token còn dưới 30 giây là hết hạn
+- **Cơ chế khóa (Lock)**: Đảm bảo an toàn khi refresh token trong môi trường đa tiến trình (multi-process)
+
+### Headers Bắt buộc
+
+Plugin tự động đính kèm các headers cần thiết cho DashScope OAuth:
+
+```
+X-DashScope-AuthType: qwen-oauth
+X-DashScope-CacheControl: enable
+User-Agent: opencode-qwen-cli-auth/{version}
+X-DashScope-UserAgent: opencode-qwen-cli-auth/{version}
+```
+
+## Xử lý lỗi
+
+### Hết Quota (Insufficient Quota)
+
+Khi gặp lỗi `429 insufficient_quota`, plugin sẽ tự động:
+
+1. **Degrade payload** - loại bỏ mảng tools, giảm max_tokens xuống 1024
+2. **Retry** - thử gọi lại API với payload đã giảm tải
+3. **CLI fallback** (tùy chọn) - gọi `qwen` CLI nếu biến `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1` được bật
+
+### Token Hết Hạn
+
+- Tự động sử dụng refresh token để lấy token mới
+- Thử lại tối đa 2 lần đối với các lỗi tạm thời (timeout, lỗi mạng)
+- Xóa token cũ và yêu cầu đăng nhập lại nếu nhận lỗi 401/403
+
+## Quản lý xác thực
+
+### Kiểm tra trạng thái
+
+```bash
+# Xem token đang được lưu
+cat ~/.qwen/oauth_creds.json
+```
+
+### Xóa xác thực
+
+**PowerShell:**
+```powershell
+Remove-Item -Recurse -Force "$HOME/.opencode/qwen"
+Remove-Item -Force "$HOME/.qwen/oauth_creds.json"
+```
+
+**Bash (Linux/macOS):**
+```bash
+rm -rf ~/.opencode/qwen
+rm ~/.qwen/oauth_creds.json
+```
+
+### Refresh thủ công
+
+```bash
+# Xóa token cũ và đăng nhập lại
+opencode auth logout
+opencode auth login
+```
+
+## Kiến trúc Plugin
+
+```
+dist/
+├── index.js              # Entry point, exports QwenAuthPlugin
+├── lib/
+│   ├── auth/
+│   │   ├── auth.js       # Luồng OAuth: device code, poll token, refresh
+│   │   └── browser.js    # Tiện ích mở trình duyệt
+│   ├── config.js         # Đường dẫn cấu hình, QWEN_MODE
+│   ├── constants.js      # Hằng số: OAuth endpoints, headers, mã lỗi
+│   ├── logger.js         # Tiện ích logging
+│   └── types.js          # Định nghĩa kiểu (TypeScript)
+```
+
+### Các Hook Sử Dụng
+
+| Hook | Mục đích |
+|------|----------|
+| `auth.loader` | Cung cấp apiKey, baseURL, custom fetch |
+| `auth.methods.authorize` | Thực hiện luồng Device Authorization OAuth |
+| `config` | Đăng ký provider và models |
+| `chat.params` | Thiết lập timeout, maxRetries, giới hạn max_tokens |
+| `chat.headers` | Đính kèm các headers của DashScope |
+
+## So sánh với Plugin Cũ
+
+| Tính năng | Plugin cũ | Plugin này |
+|-----------|-----------|------------|
+| OAuth Device Flow | ✓ | ✓ |
+| Custom fetch layer | ✗ | ✓ |
+| Headers của DashScope | ✗ | ✓ (tự động đính kèm) |
+| Giới hạn Output token | ✗ | ✓ |
+| Degradation khi hết quota| ✗ | ✓ |
+| Fallback dùng CLI | ✗ | ✓ (tùy chọn) |
+| Khóa đa tiến trình | ✗ | ✓ |
+| Migrate token cũ | ✗ | ✓ |
+
+## Khắc phục sự cố (Troubleshooting)
+
+### Các lỗi thường gặp
+
+**1. Bị lỗi `insufficient_quota` liên tục**
+- Tài khoản của bạn có thể đã hết hạn mức miễn phí
+- Hãy thử xóa token và đăng nhập lại
+- Bật tính năng CLI fallback: `OPENCODE_QWEN_ENABLE_CLI_FALLBACK=1`
+
+**2. OAuth timeout**
+- Kiểm tra lại kết nối mạng
+- Tăng timeout trong cấu hình nếu cần
+- Xem log chi tiết bằng cách bật `DEBUG_QWEN_PLUGIN=1`
+
+**3. Không tìm thấy qwen CLI**
+- Cài đặt qwen-code: `npm install -g @qwen-code/qwen-code`
+- Hoặc cấu hình biến: `QWEN_CLI_PATH=/path/to/qwen`
+
+**4. Không lưu được token**
+- Kiểm tra quyền ghi (write permissions) cho thư mục `~/.qwen/`
+- Xem log bằng cách bật `ENABLE_PLUGIN_REQUEST_LOGGING=1`
+
+## Phát triển
+
+### Build
+
+```bash
+npm install
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+### Type Check
+
+```bash
+npm run typecheck
+```
+
+### Lint & Format
+
+```bash
+npm run lint
+npm run format
+```
+
+## Giấy phép (License)
+
+MIT
+
+## Repository
+
+- **Mã nguồn**: https://github.com/TVD-00/opencode-qwen-cli-auth
+- **Báo lỗi (Issues)**: https://github.com/TVD-00/opencode-qwen-cli-auth/issues
+- **NPM**: https://www.npmjs.com/package/opencode-qwen-cli-auth
+
+## Tác giả
+
+Geoff Hammond
+
+## Đóng góp
+
+Mọi sự đóng góp (PR, issue, feedback) đều được hoan nghênh tại GitHub repository.