opencode-qwen-cli-auth 2.2.9 → 2.3.0

package/README.md

@@ -1,62 +1,261 @@
-# opencode-qwen-cli-auth (local fork)
-
-Plugin OAuth cho **OpenCode** để dùng Qwen theo cơ chế giống **qwen-code CLI** (free tier bằng Qwen account), không cần DashScope API key.
-
-## Cấu hình nhanh
-
-`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ì sao plugin trước bị `insufficient_quota`?
-
-Từ việc đối chiếu với **qwen-code** (gốc), request free-tier cần:
-
-- Base URL đúng (DashScope OpenAI-compatible):
-  - mặc định: `https://dashscope.aliyuncs.com/compatible-mode/v1`
-  - có thể thay đổi theo `resource_url` trong `~/.qwen/oauth_creds.json`
-- Headers DashScope đặc thù:
-  - `X-DashScope-AuthType: qwen-oauth`
-  - `X-DashScope-CacheControl: enable`
-  - `User-Agent` + `X-DashScope-UserAgent`
-- Giới hạn output token theo model (qwen-code):
-  - `coder-model`: 65536
-  - `vision-model`: 8192
-
-Fork này đã **inject headers ở tầng fetch** để vẫn hoạt động ngay cả khi OpenCode không gọi hook `chat.headers`.
-
-## Debug / logging
-
-```bash
-DEBUG_QWEN_PLUGIN=1 opencode run "hello" --model=qwen-code/coder-model
-ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "hello" --model=qwen-code/coder-model
-```
-
-Log path: `~/.opencode/logs/qwen-plugin/`
-
-## Clear auth
-
-PowerShell:
-
-```powershell
-Remove-Item -Recurse -Force "$HOME/.opencode/qwen"
-Remove-Item -Recurse -Force "$HOME/.qwen"  # nếu muốn xoá token qwen-code luôn
-```
-
-## Ghi chú build
-
-Repo này chỉ chứa output `dist/` (không có `src/`/`tsconfig.json`), nên `npm run build/typecheck` sẽ không compile lại TS.
+# opencode-qwen-cli-auth
+
+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 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
+
+- Node.js >= 20.0.0
+- OpenCode with plugin support
+- Qwen Account (free)
+
+### Add to OpenCode
+
+Configure in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-qwen-cli-auth"],
+  "model": "qwen-code/coder-model"
+}
+```
+
+### Login
+
+```bash
+opencode auth login
+```
+
+Select provider **Qwen Code (qwen.ai OAuth)** and follow the instructions:
+
+1. Open the URL displayed in the terminal
+2. Enter the provided code
+3. The plugin will automatically poll and save the token
+
+## Supported Models
+
+| 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
+
+### Environment Variables
+
+| 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 |
+
+### Debug & Logging
+
+```bash
+# Debug mode - logs to console
+DEBUG_QWEN_PLUGIN=1 opencode run "hello" --model=qwen-code/coder-model
+
+# Request logging - saves detailed JSON files
+ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "hello" --model=qwen-code/coder-model
+```
+
+Log files are stored at: `~/.opencode/logs/qwen-plugin/`
+
+## How It Works
+
+### OAuth Flow
+
+```
+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
+```
+
+### Token Storage
+
+- **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
+
+### Required Headers
+
+The plugin automatically injects required headers for 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}
+```
+
+## Error Handling
+
+### Insufficient Quota
+
+When hitting a `429 insufficient_quota` error, the plugin automatically:
+
+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
+
+### Token Expiration
+
+- Automatically uses refresh token
+- Retries up to 2 times for transient errors (timeout, network)
+- Clears token and requests re-auth on 401/403
+
+## Authentication Management
+
+### Check Status
+
+```bash
+# View saved token
+cat ~/.qwen/oauth_creds.json
+```
+
+### Remove Authentication
+
+**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
+```
+
+### Manual Refresh
+
+```bash
+# Clear old token and login again
+opencode auth logout
+opencode auth login
+```
+
+## Plugin Architecture
+
+```
+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`
+
+**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
+```
+
+### Lint & Format
+
+```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.