@hsupu/copilot-api 0.7.17-beta.0 → 0.7.18-beta

package/README.md

@@ -1,183 +1,229 @@
 # Copilot API Proxy (Fork)
 
-> [!WARNING]
-> 这是 GitHub Copilot API 的逆向代理。GitHub 官方不提供支持，且可能随时失效。使用风险自负。
-
-本项目是 [ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api) 的 fork，因使用中遇到报错，故尝试魔改。
+> [!NOTE]
+> This is a fork of [ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api) with additional improvements and bug fixes.
 
-## Fork 的考虑和改进
+> [!WARNING]
+> This is a reverse proxy for the GitHub Copilot API. It is not officially supported by GitHub and may break at any time. Use at your own risk.
 
-CC + Opus/Haiku 是作者的唯一核心场景。其他任何花哨的功能要么是继承自上游，要么是 fallback 方案。改动全 AI 完成，我只提供功能需求、参考项目和使用反馈。
+A reverse proxy that exposes GitHub Copilot's API as standard OpenAI and Anthropic compatible endpoints. Works with Claude Code, Cursor, and other tools that speak these protocols.
 
-本 fork 相对于上游项目包含以下增强：
+## Quick Start
 
-### 新功能
+### Install from npm (Recommended)
 
-- **`--host` 选项**：将服务器绑定到指定网络接口（如 `--host 0.0.0.0` 绑定所有接口，`--host 127.0.0.1` 仅绑定本地）
-- **自适应限流**：基于指数退避的智能限流，支持自动恢复和 Retry-After 头（替代原有的队列限流）
-- **直连 Anthropic API**：Claude 模型使用 Copilot 的原生 Anthropic 端点，无需格式转换
-- **智能自动截断**：超出上下文限制时自动截断对话历史，支持可选的 tool result 压缩
-- **`/api/event_logging/batch` 端点**：为 Anthropic SDK 的 event logging 提供兼容端点（返回 OK，不做处理）
-- **`logout` 命令**：通过 `copilot-api logout` 移除已存储的 GitHub token
-- **`list-claude-code` 命令**：列出所有本地安装的 Claude Code 版本
-- **工具名长度处理**：自动截断超过 64 字符的工具名以符合 OpenAI 限制，使用 hash 后缀避免冲突。响应中会还原原始名称。
-- **请求历史 UI**：内置 Web UI（默认启用），可查看、搜索、过滤和导出所有 API 请求/响应。访问 `/history`。
-- **`setup-claude-code` 命令**：交互式配置 Claude Code 以使用本代理
-- **Sonnet 重定向到 Opus**：可选将 sonnet 模型请求重定向到最佳可用 opus 模型
-- **安全研究模式**：为授权渗透测试、CTF 和安全教育提供专用模式
+```sh
+npx -y @hsupu/copilot-api start
+```
 
-### Bug 修复
+### Run from Source
 
-- **修复流式响应中缺少 `model` 字段**：Copilot API 的首个流式 chunk 有时 `choices` 数组为空但包含模型名。现已保存该值供后续事件使用。
-- **自动修复消息序列错误**：当 tool 调用被中断（如用户取消）时，API 会自动添加占位 `tool_result` 块以维持合法的消息序列
-- **修复 `bunx` 符号链接问题**：将 pre-commit hook 改为使用 `bun x` 替代 `bunx` 以提高兼容性
+```sh
+git clone https://github.com/puxu-msft/copilot-api-js.git
+cd copilot-api-js
+bun install
+bun run dev      # Development mode with hot reload
+bun run start    # Production mode
+bun run build    # Build for distribution
+
+# Testing
+bun test                   # Backend unit tests
+bun run test:all           # All backend tests
+bun run test:ui            # Frontend (History UI) tests
+bun run typecheck          # TypeScript type checking
+```
 
-## 快速开始
+## Using with Claude Code
 
-### 从 npm 安装（推荐）
+Run the interactive setup command:
 
 ```sh
-# 直接用 npx 运行
-npx @hsupu/copilot-api start
+copilot-api setup-claude-code
+```
+
+Or manually create `~/.claude/settings.json`:
 
-# 或全局安装
-npm install -g @hsupu/copilot-api
-copilot-api start
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:4141",
+    "ANTHROPIC_AUTH_TOKEN": "dummy",
+    "ANTHROPIC_MODEL": "opus",
+    "ANTHROPIC_SMALL_FAST_MODEL": "haiku",
+    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+  }
+}
 ```
 
-### 从 GitHub 安装
+## Features
 
-也可以直接从 GitHub 安装（需要构建步骤）：
+### Dual API Compatibility
 
-```sh
-npm install -g github:puxu-msft/copilot-api-js
-copilot-api start
-```
+Exposes both OpenAI and Anthropic compatible endpoints through a single proxy:
 
-### 从源码运行
+- **Direct Anthropic path** — Uses Copilot API's native Anthropic endpoint for Claude models
+- **Translated path** — Translates between OpenAI and Anthropic formats for other models
 
-```sh
-# 克隆仓库
-git clone https://github.com/puxu-msft/copilot-api-js.git
-cd copilot-api-js
+### Auto-Truncate
 
-# 安装依赖
-bun install
+Automatically handles context length limits (enabled by default):
 
-# 开发模式（热重载）
-bun run dev
+- **Reactive** — Retries failed requests with a truncated payload when hitting token or byte limits
+- **Proactive** — Pre-checks requests against known model limits before sending
+- **Dynamic limit learning** — Adjusts limits based on actual API error responses
+- **Tool result compression** — Compresses old `tool_result` content before truncating messages
 
-# 生产模式
-bun run start
+### Message Sanitization
 
-# 构建发布版
-bun run build
-```
+Cleans up messages before forwarding to the API:
 
-### 构建后使用
+- Filters orphaned `tool_use` / `tool_result` blocks (unpaired due to interrupted tool calls or truncation)
+- Fixes tool name casing mismatches
+- Removes empty text content blocks
+- Strips `<system-reminder>` tags from message content
+- **[Optional]** Deduplicates repeated tool calls (`config.yaml: anthropic.dedup_tool_calls`)
+- **[Optional]** Strips system-reminder tags from Read tool results (`config.yaml: anthropic.truncate_read_tool_result`)
 
-```sh
-# 本地运行构建版本
-npx .
+### Model Name Translation
 
-# 或全局链接
-bun link
-copilot-api start
-```
+Translates client-sent model names to matching Copilot models:
 
-## 命令参考
-
-| 命令 | 说明 |
-|------|------|
-| `start` | 启动 API 服务器（需要时自动进行认证） |
-| `auth` | 仅运行 GitHub 认证流程 |
-| `logout` | 移除已存储的 GitHub token |
-| `check-usage` | 查看 Copilot 用量和配额 |
-| `debug` | 显示诊断信息 |
-| `list-claude-code` | 列出所有本地安装的 Claude Code 版本 |
-| `setup-claude-code` | 交互式配置 Claude Code 连接 |
-
-### start 命令选项
-
-| 选项 | 说明 | 默认值 |
-|------|------|--------|
-| `--port`, `-p` | 监听端口 | 4141 |
-| `--host`, `-H` | 绑定的主机/接口 | （所有接口） |
-| `--verbose`, `-v` | 启用详细日志 | false |
-| `--account-type`, `-a` | 账户类型（individual, business, enterprise） | individual |
-| `--manual` | 手动请求审批模式 | false |
-| `--no-rate-limit` | 禁用自适应限流 | false |
-| `--retry-interval` | 限流后重试等待秒数 | 10 |
-| `--request-interval` | 限流模式下请求间隔秒数 | 10 |
-| `--recovery-timeout` | 尝试恢复前等待的分钟数 | 10 |
-| `--consecutive-successes` | 退出限流模式所需的连续成功次数 | 5 |
-| `--github-token`, `-g` | 直接提供 GitHub token | 无 |
-| `--show-github-token` | 在日志中显示 GitHub token | false |
-| `--proxy-env` | 使用环境变量中的代理 | false |
-| `--history-limit` | 内存中最大历史记录条数（0 = 无限） | 200 |
-| `--no-auto-truncate` | 禁用超限自动截断 | false |
-| `--no-compress-tool-results` | 禁用自动截断时的 tool result 压缩 | false（默认启用压缩） |
-| `--redirect-anthropic` | 强制 Anthropic 请求走 OpenAI 转换 | false |
-| `--no-rewrite-anthropic-tools` | 不重写服务端工具 | false |
-| `--redirect-count-tokens` | count_tokens 走 OpenAI 转换而非原生 Anthropic | false |
-| `--redirect-sonnet-to-opus` | 将 sonnet 模型请求重定向到最佳可用 opus 模型 | false |
-| `--security-research-mode` | 启用安全研究模式（需要口令） | 无 |
-
-## API 端点
-
-### OpenAI 兼容
-
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/v1/chat/completions` | POST | Chat completions |
-| `/v1/models` | GET | 列出可用模型 |
-| `/v1/embeddings` | POST | 文本嵌入 |
+| Input | Resolved To |
+|-------|-------------|
+| `opus`, `sonnet`, `haiku` | Best available model in that family |
+| `claude-opus-4-6` | `claude-opus-4.6` |
+| `claude-sonnet-4-5-20250514` | `claude-sonnet-4.5` |
+| `claude-sonnet-4`, `gpt-4` | Passed through directly |
 
-### Anthropic 兼容
+User-configured `model_overrides` (via config.yaml) can redirect any model name to another, with chained resolution and family-level overrides.
 
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/v1/messages` | POST | Messages API |
-| `/v1/messages/count_tokens` | POST | Token 计数 |
-| `/api/event_logging/batch` | POST | Event logging（空操作） |
+### Server-Side Tools
 
-### 工具端点
+Supports Anthropic server-side tools (`web_search`, `tool_search`). These tools are executed by the API backend, with both `server_tool_use` and result blocks appearing inline in assistant messages. Tool definitions can optionally be rewritten to a custom format (`--no-rewrite-anthropic-tools`).
 
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/` | GET | 服务器状态 |
-| `/usage` | GET | Copilot 用量统计 |
-| `/token` | GET | 当前 Copilot token |
-| `/health` | GET | 健康检查 |
-| `/history` | GET | 请求历史 Web UI（默认启用） |
-| `/history/api/*` | GET/DELETE | 历史记录 API 端点 |
+### Request History UI
 
-## 配合 Claude Code 使用
+Built-in web interface for inspecting API requests and responses. Access at `http://localhost:4141/history/v3/`.
 
-在用户根目录或者打开的项目中创建 `.claude/settings.json`：
+- Real-time updates via WebSocket
+- Filter by model, endpoint, status, and time range
+- Session tracking and statistics
 
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://localhost:4141",
-    "ANTHROPIC_AUTH_TOKEN": "dummy",
-    "ANTHROPIC_MODEL": "gpt-4.1",
-    "ANTHROPIC_SMALL_FAST_MODEL": "gpt-4.1",
-    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
-  },
-  "permissions": {
-    "deny": ["WebSearch"]
-  }
-}
-```
+### Additional Features
 
-或使用交互式设置：
+- **Model overrides** — Configure arbitrary model name redirections via config.yaml
+- **Adaptive rate limiting** — Intelligent rate limiting with exponential backoff (3 modes: Normal, Rate-limited, Recovering)
+- **Tool name truncation** — Truncates tool names exceeding 64 characters (OpenAI limit) with hash suffixes
+- **Health checks** — Container-ready endpoint at `/health`
+- **Graceful shutdown** — Connection draining on shutdown signals
+- **Proxy support** — HTTP/HTTPS proxy via environment variables
 
-```sh
-copilot-api setup-claude-code
-```
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start the API server (authenticates automatically if needed) |
+| `auth` | Run GitHub authentication flow only |
+| `logout` | Remove stored GitHub token |
+| `check-usage` | Show Copilot usage and quota information |
+| `debug info` | Display diagnostic information |
+| `debug models` | Fetch and display raw model data from Copilot API |
+| `list-claude-code` | List all locally installed Claude Code versions |
+| `setup-claude-code` | Interactively configure Claude Code to use this proxy |
+
+### `start` Options
+
+**General:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port`, `-p` | 4141 | Port to listen on |
+| `--host`, `-H` | (all interfaces) | Host/interface to bind to |
+| `--verbose`, `-v` | false | Enable verbose logging |
+| `--account-type`, `-a` | individual | Account type: `individual`, `business`, or `enterprise` |
+| `--github-token`, `-g` | | Provide GitHub token directly |
+| `--no-http-proxy-from-env` | enabled | Disable HTTP proxy from environment variables |
+
+**Auto-Truncate:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-auto-truncate` | enabled | Disable auto-truncation on context limit errors |
+
+**Anthropic-Specific (via config.yaml):**
+
+These options are configured in `config.yaml` under the `anthropic:` section. See [`config.example.yaml`](config.example.yaml).
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `anthropic.rewrite_tools` | true | Rewrite server-side tools to custom format |
+| `stream_idle_timeout` | 300 | Max seconds between SSE events (0 = no timeout) |
+
+**Sanitization:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--collect-system-prompts` | false | Collect system prompts to file |
+
+**Rate Limiting:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-rate-limit` | enabled | Disable adaptive rate limiting |
+
+Rate limiter sub-parameters are configured in `config.yaml` under `rate_limiter:`. See [`config.example.yaml`](config.example.yaml).
+
+## Configuration
+
+Create a `config.yaml` in the working directory. See [`config.example.yaml`](config.example.yaml) for all available options.
+
+## API Endpoints
+
+### OpenAI Compatible
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/completions` | POST | Chat completions |
+| `/v1/responses` | POST | Responses API |
+| `/v1/models` | GET | List available models |
+| `/v1/models/:model` | GET | Get specific model details |
+| `/v1/embeddings` | POST | Text embeddings |
+
+All endpoints also work without the `/v1` prefix.
+
+### Anthropic Compatible
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/messages` | POST | Messages API |
+| `/v1/messages/count_tokens` | POST | Token counting |
+
+### Utility
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check (200 healthy, 503 unhealthy) |
+| `/usage` | GET | Copilot usage and quota statistics |
+| `/token` | GET | Current Copilot token information |
+| `/history/v3/` | GET | History web UI |
+| `/history/ws` | WebSocket | Real-time history updates |
+| `/history/api/entries` | GET | Query history entries |
+| `/history/api/entries/:id` | GET | Get single entry |
+| `/history/api/summaries` | GET | Entry summaries |
+| `/history/api/stats` | GET | Usage statistics |
+| `/history/api/sessions` | GET | List sessions |
+
+## Account Types
+
+The account type determines the Copilot API base URL:
+
+| Type | API Base URL |
+|------|-------------|
+| `individual` | `api.githubcopilot.com` |
+| `business` | `api.business.githubcopilot.com` |
+| `enterprise` | `api.enterprise.githubcopilot.com` |
 
-## 上游项目
+## License
 
-原始项目的文档、功能和更新请参见：[ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api)
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,39 @@
+
+## 项目概述
+
+GitHub Copilot API 的逆向代理，将其暴露为 OpenAI 和 Anthropic 兼容端点。使得 Claude Code 等工具可以使用 GitHub Copilot 作为后端。
+
+## 常用命令
+
+```sh
+bun install              # 安装依赖
+bun run dev              # 开发模式（热重载）
+bun run start            # 生产模式
+bun run build            # 构建发布版（tsdown）
+bun run typecheck        # 类型检查
+bun run lint             # Lint 暂存文件
+bun run lint:all         # Lint 所有文件
+bun run knip             # 查找未使用的导出/依赖
+bun test                 # 运行所有测试
+bun test tests/foo.test.ts  # 运行单个测试文件
+```
+
+## API 端点
+
+| 端点 | 用途 |
+|------|------|
+| `/v1/chat/completions` | OpenAI 兼容 chat |
+| `/v1/messages` | Anthropic 兼容 messages |
+| `/v1/messages/count_tokens` | Anthropic 兼容 token 计数 |
+| `/v1/models` | 列出可用模型 |
+| `/v1/embeddings` | 文本嵌入 |
+| `/api/event_logging/batch` | Event logging（空操作） |
+| `/usage` | Copilot 配额/用量统计 |
+| `/health` | 健康检查 |
+| `/token` | 当前 Copilot token 信息 |
+| `/history` | 请求历史 Web UI（v1 和 v2） |
+| `/history/ws` | WebSocket 实时历史更新 |
+| `/history/api/entries` | 历史查询 API |
+| `/history/api/sessions` | 会话列表 API |
+| `/history/api/stats` | 统计 API |
+| `/history/api/export` | 导出历史（JSON/CSV） |