workbuddy2api 2.0.6__tar.gz → 2.0.8.dev1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/PKG-INFO +162 -28
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/README.md +159 -27
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/pyproject.toml +5 -3
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/__main__.py +889 -409
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_checkin.py +4 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_manager.py +947 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_store.py +4 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/admin.html +1883 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/admin_api.py +496 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/anthropic_adapter.py +5 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/backend_profile.py +4 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/billing_proxy.py +4 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/codebuddy_client_demo.py +116 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/process_diagnostics.py +445 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/protocol_response.py +132 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/responses_adapter.py +25 -3
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/role_compat.py +55 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/tool_pairing.py +136 -0
- workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/upstream_request.py +147 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/PKG-INFO +162 -28
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/SOURCES.txt +11 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/requires.txt +2 -0
- workbuddy2api-2.0.6/src/codebuddy_proxy/backend_profile.py +0 -198
- workbuddy2api-2.0.6/src/codebuddy_proxy/codebuddy_client_demo.py +0 -533
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/LICENSE +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/setup.cfg +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/desensitize.py +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/dsml_parser.py +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/models_config.domestic.json +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/models_config.global.json +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/projection_metadata.py +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/responses_projection.py +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/dependency_links.txt +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/entry_points.txt +0 -0
- {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: workbuddy2api
|
|
3
|
-
Version: 2.0.
|
|
3
|
+
Version: 2.0.8.dev1
|
|
4
4
|
Summary: Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy
|
|
5
5
|
Requires-Python: >=3.10
|
|
6
6
|
Description-Content-Type: text/markdown
|
|
@@ -9,6 +9,8 @@ Requires-Dist: fastapi>=0.104.0
|
|
|
9
9
|
Requires-Dist: uvicorn>=0.24.0
|
|
10
10
|
Requires-Dist: httpx[socks]>=0.25.0
|
|
11
11
|
Requires-Dist: requests>=2.31.0
|
|
12
|
+
Requires-Dist: buddy-agent-auth<0.2,>=0.1.0.dev1
|
|
13
|
+
Requires-Dist: buddy-agent-checkin[workbuddy]<0.2,>=0.1.1.dev2
|
|
12
14
|
Provides-Extra: dev
|
|
13
15
|
Requires-Dist: pytest>=7.4.0; extra == "dev"
|
|
14
16
|
Dynamic: license-file
|
|
@@ -19,6 +21,8 @@ Dynamic: license-file
|
|
|
19
21
|
|
|
20
22
|
> **中文版文档见 [README_zh.md](README_zh.md).**
|
|
21
23
|
|
|
24
|
+
For unexplained Windows process exits, use the [independent process monitor](docs/external-process-monitor.md) to collect uv/Python exit codes, lifecycle, memory, health, and available Windows events without restarting the proxy.
|
|
25
|
+
|
|
22
26
|
## ✨ Core Features
|
|
23
27
|
|
|
24
28
|
- **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
|
|
@@ -28,7 +32,9 @@ Dynamic: license-file
|
|
|
28
32
|
- **DSML parsing** - Automatically detects and converts DeepSeek Markup Language (DSML) tool calls
|
|
29
33
|
- **Streaming responses** - SSE streaming output, returning generated content in real time, with built-in 60-second timeout protection
|
|
30
34
|
- **Domestic and international backends** - Uses domestic CodeBuddy by default and switches to the international CodeBuddy service with `--global`, with isolated sessions and model catalogs
|
|
31
|
-
- **Multi-account management** -
|
|
35
|
+
- **Multi-account management** - Link domestic and Global accounts, switch the active account, and remove non-active accounts from the local admin page
|
|
36
|
+
- **Model-level 429 handling** - Track cooldowns per account and model, with optional same-region failover
|
|
37
|
+
- **Daily check-in** - Check in manually or enable background checks for all linked accounts
|
|
32
38
|
|
|
33
39
|
---
|
|
34
40
|
|
|
@@ -64,12 +70,14 @@ uv sync
|
|
|
64
70
|
uv run python -m codebuddy_proxy --desensitize
|
|
65
71
|
```
|
|
66
72
|
|
|
67
|
-
On first use,
|
|
73
|
+
On first use, start the proxy and open the local account manager:
|
|
68
74
|
|
|
69
75
|
```bash
|
|
70
|
-
uv run python -m codebuddy_proxy --
|
|
76
|
+
uv run python -m codebuddy_proxy --desensitize
|
|
71
77
|
```
|
|
72
78
|
|
|
79
|
+
Then visit `http://127.0.0.1:8787/admin` and link a domestic or Global account.
|
|
80
|
+
|
|
73
81
|
## Quick Start
|
|
74
82
|
|
|
75
83
|
### 1. Start the proxy
|
|
@@ -78,8 +86,8 @@ uv run python -m codebuddy_proxy --login --desensitize
|
|
|
78
86
|
# Use the latest version (recommended)
|
|
79
87
|
uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
|
|
80
88
|
|
|
81
|
-
# First use:
|
|
82
|
-
uv run --with workbuddy2api python -m codebuddy_proxy --
|
|
89
|
+
# First use: start, then link an account at http://127.0.0.1:8787/admin
|
|
90
|
+
uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
|
|
83
91
|
|
|
84
92
|
# International service: first login and start
|
|
85
93
|
uv run --with workbuddy2api python -m codebuddy_proxy --global --login --desensitize
|
|
@@ -95,12 +103,23 @@ Listens on `http://127.0.0.1:8787` by default.
|
|
|
95
103
|
The proxy supports both CodeBuddy regions. Domestic mode remains the default,
|
|
96
104
|
so existing startup commands continue to work unchanged.
|
|
97
105
|
|
|
98
|
-
| Mode | Startup option | Upstream endpoint |
|
|
99
|
-
| --- | --- | --- |
|
|
100
|
-
| Domestic (default) | none | `https://copilot.tencent.com` |
|
|
101
|
-
| International | `--global` | `https://www.codebuddy.ai` |
|
|
106
|
+
| Mode | Startup option | Upstream endpoint |
|
|
107
|
+
| --- | --- | --- |
|
|
108
|
+
| Domestic (default) | none | `https://copilot.tencent.com` |
|
|
109
|
+
| International | `--global` | `https://www.codebuddy.ai` |
|
|
110
|
+
|
|
111
|
+
Linked accounts are stored separately by region in `~/.workbuddy2api/accounts`.
|
|
112
|
+
Use `--accounts-dir DIR` to choose another local directory. With no explicit
|
|
113
|
+
selector, the proxy restores the saved active account. On the first migration,
|
|
114
|
+
matching legacy session files are imported once and kept; deleting an imported
|
|
115
|
+
account does not import it again. Explicit `--global` or `--endpoint` selects a
|
|
116
|
+
matching account, while `--session-file` can import that file again. If there is
|
|
117
|
+
no match, the proxy starts without an active account. `--login` uses a temporary
|
|
118
|
+
session file to add or refresh an account without replacing a legacy file.
|
|
102
119
|
|
|
103
|
-
|
|
120
|
+
The account manager can add accounts for either region while the proxy is
|
|
121
|
+
running. For a terminal-driven login, the existing `--login` option remains
|
|
122
|
+
available:
|
|
104
123
|
|
|
105
124
|
```bash
|
|
106
125
|
# First login
|
|
@@ -116,16 +135,18 @@ If the package is installed as a command, the equivalent short form is
|
|
|
116
135
|
`workbuddy2api --global --login`. When running from source, use
|
|
117
136
|
`uv run python -m codebuddy_proxy --global --login`.
|
|
118
137
|
|
|
119
|
-
`--global`
|
|
120
|
-
OpenCode, and other clients continue to use
|
|
121
|
-
selected profile also controls the model catalog
|
|
138
|
+
`--global` selects the Global backend and a matching account when one exists.
|
|
139
|
+
Codex CLI, Claude Code/CC Switch, OpenCode, and other clients continue to use
|
|
140
|
+
the same local proxy URLs. The selected profile also controls the model catalog
|
|
141
|
+
returned by `/v1/models`.
|
|
122
142
|
|
|
123
|
-
Domestic and international
|
|
124
|
-
`--session-file`
|
|
125
|
-
|
|
126
|
-
|
|
143
|
+
Domestic and international accounts remain isolated. An explicit
|
|
144
|
+
`--session-file` is imported only when its saved backend and endpoint match the
|
|
145
|
+
current startup options. The proxy refuses mismatched credentials and does not
|
|
146
|
+
modify the original file.
|
|
127
147
|
|
|
128
|
-
For a custom international endpoint,
|
|
148
|
+
For a custom international endpoint, use a dedicated session file when
|
|
149
|
+
importing or creating a login from the command line:
|
|
129
150
|
|
|
130
151
|
```bash
|
|
131
152
|
uv run --with workbuddy2api python -m codebuddy_proxy \
|
|
@@ -140,6 +161,24 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
|
|
|
140
161
|
Therefore `--global` without `--endpoint` cannot be redirected to the domestic
|
|
141
162
|
host by `CODEBUDDY_ENDPOINT`.
|
|
142
163
|
|
|
164
|
+
### Built-in CodeBuddy gateways: developer-role compatibility
|
|
165
|
+
|
|
166
|
+
The built-in domestic (`https://copilot.tencent.com`) and international
|
|
167
|
+
(`https://www.codebuddy.ai`) Chat Completions gateways may reject requests
|
|
168
|
+
containing a `developer` message with HTTP 400 / code 11128. Before forwarding
|
|
169
|
+
to either matching backend and host, the proxy maps `developer` to `system`
|
|
170
|
+
without changing message order, content, tool-call history, or the original
|
|
171
|
+
client request. If enabled, `--desensitize` runs after this role adaptation.
|
|
172
|
+
No client-side configuration is needed.
|
|
173
|
+
|
|
174
|
+
The mapping is scoped to these exact backend/host pairs; endpoints using
|
|
175
|
+
other host names keep their original roles. International `X-Conversation-*` headers
|
|
176
|
+
are still generated after request-body transformations. Because the upstreams
|
|
177
|
+
do not represent the separate `system` and `developer` instruction priorities,
|
|
178
|
+
the mapping is an approximation, not exact semantic equivalence. The
|
|
179
|
+
`upstream_role_compat` log event reports the backend and number of mapped
|
|
180
|
+
messages, not prompt contents.
|
|
181
|
+
|
|
143
182
|
Runtime model catalogs are loaded from the packaged profile resources
|
|
144
183
|
`src/codebuddy_proxy/models_config.domestic.json` and
|
|
145
184
|
`src/codebuddy_proxy/models_config.global.json`. The root
|
|
@@ -307,6 +346,7 @@ Select the model inside OMP with `/model codebuddy/hy3` (or set it as the defaul
|
|
|
307
346
|
--global Use the international CodeBuddy backend (default domestic)
|
|
308
347
|
--endpoint ENDPOINT CodeBuddy backend address (overrides the profile default)
|
|
309
348
|
--session-file PATH Session file path (isolated by profile by default)
|
|
349
|
+
--accounts-dir DIR Account library directory (default ~/.workbuddy2api/accounts)
|
|
310
350
|
--log-file PATH JSONL log file (default ~/.workbuddy2api/codebuddy-proxy.jsonl)
|
|
311
351
|
--desensitize Enable desensitization (recommended)
|
|
312
352
|
--optimize-context Enable message compression (recommended for Codex CLI)
|
|
@@ -367,15 +407,58 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
|
|
|
367
407
|
|
|
368
408
|
### Multi-account switching
|
|
369
409
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
410
|
+
Start the proxy and open [http://127.0.0.1:8787/admin](http://127.0.0.1:8787/admin).
|
|
411
|
+
Choose **Domestic** or **Global**, then link the account in the browser window.
|
|
412
|
+
The first linked account becomes active automatically; linking another account
|
|
413
|
+
does not change the account currently in use. Use **Set active** to switch, or
|
|
414
|
+
remove a non-active account from the same page. The selection is saved for the
|
|
415
|
+
next proxy start. Switching affects new requests; requests already in progress
|
|
416
|
+
continue with the account selected when they began.
|
|
417
|
+
|
|
418
|
+

|
|
419
|
+
|
|
420
|
+
The screenshot uses synthetic demo accounts. Account UIDs are covered, and no
|
|
421
|
+
credentials or session contents are shown. Accounts are kept separately by
|
|
422
|
+
backend, normalized endpoint, and user ID in `~/.workbuddy2api/accounts`; use
|
|
423
|
+
`--accounts-dir DIR` to choose another local directory. The manager remains
|
|
424
|
+
available before any account is linked. Its page and API are restricted to
|
|
425
|
+
loopback access, and API responses do not include tokens or session data.
|
|
426
|
+
|
|
427
|
+
Use the language selector at the top of the page to switch between Chinese and
|
|
428
|
+
English. The choice is remembered in this browser; without a saved preference,
|
|
429
|
+
the page follows the browser language. Switching languages keeps ongoing login
|
|
430
|
+
and account operations running.
|
|
431
|
+
|
|
432
|
+
Automatic account switching after an upstream HTTP `429` is off by default.
|
|
433
|
+
When enabled, a request can fail over only before any response has been sent,
|
|
434
|
+
and only to accounts with the same region and endpoint. Each account is tried
|
|
435
|
+
at most once per request. The proxy skips a candidate only when the request's
|
|
436
|
+
model is cooling down there; other models on that account remain eligible. A
|
|
437
|
+
missing or invalid model does not create a model cooldown or trigger failover.
|
|
438
|
+
If all tried accounts return `429`, the final status remains `429`, and the
|
|
439
|
+
last upstream response's `Retry-After` header is preserved when present.
|
|
440
|
+
Cooldowns are tracked per account and model, using upstream `Retry-After` or a
|
|
441
|
+
default 60 seconds when that value is missing or invalid. The setting and model
|
|
442
|
+
cooldowns persist across restarts. Old v1 account-wide cooldowns had no model
|
|
443
|
+
identity and are not carried forward during upgrade. The page shows a separate
|
|
444
|
+
remaining countdown and source for each model, and refreshes account state
|
|
445
|
+
periodically and immediately when a hidden page becomes visible again.
|
|
446
|
+
|
|
447
|
+
The account list also shows each linked account's check-in status for today
|
|
448
|
+
(Beijing time). The **Check in** action is available for every account, including
|
|
449
|
+
the active one; it checks the account first and does nothing when today's check-in
|
|
450
|
+
is already complete. The global automatic check-in setting is off by default and
|
|
451
|
+
applies to all linked accounts without changing the active account. The page saves
|
|
452
|
+
this setting and displays status; the proxy performs automatic checks and check-ins
|
|
453
|
+
in the background, including when the management page is closed. When enabled, the
|
|
454
|
+
proxy checks all linked accounts immediately and on startup. At Beijing midnight it
|
|
455
|
+
checks them, waits a random 0–10 minutes, then checks again before signing; disabling
|
|
456
|
+
it cancels pending scheduled work. Unknown status is never treated as permission to
|
|
457
|
+
sign. The setting persists; after restart, check-in status is confirmed by querying
|
|
458
|
+
the upstream service again.
|
|
459
|
+
|
|
460
|
+
The command-line `--login` flow and `--session-file` option remain available for
|
|
461
|
+
terminal use and importing an existing session.
|
|
379
462
|
|
|
380
463
|
### Listening on all interfaces (LAN sharing)
|
|
381
464
|
|
|
@@ -391,11 +474,20 @@ All endpoints do not require an extra token in the request by default; the proxy
|
|
|
391
474
|
| Method | Path | Purpose |
|
|
392
475
|
| --- | --- | --- |
|
|
393
476
|
| GET | `/health` | Query local service and auth status |
|
|
477
|
+
| GET | `/admin` | Open the local account manager |
|
|
394
478
|
| GET | `/v1/models` | Query the CodeBuddy model list |
|
|
395
479
|
| POST | `/v1/chat/completions` | OpenAI Chat Completions, supports tools and streaming |
|
|
396
480
|
| POST | `/v1/responses` | Responses API, compatible with Codex CLI |
|
|
397
481
|
| POST | `/v1/messages` | Anthropic Messages API, compatible with Claude Code / CC Switch |
|
|
398
482
|
|
|
483
|
+
Account-management endpoints live under `/admin/api` and are restricted to
|
|
484
|
+
loopback clients. Write requests require the `X-Account-Manager: 1` header, and
|
|
485
|
+
cross-origin requests are rejected. `GET /admin/api/accounts` reports active
|
|
486
|
+
account, cooldown, and cached check-in state. `GET /admin/api/accounts/{id}/checkin-status`
|
|
487
|
+
checks that account against the upstream service; `POST /admin/api/accounts/{id}/checkin`
|
|
488
|
+
checks first and signs only when needed. `GET` and `PATCH /admin/api/settings` read
|
|
489
|
+
and save the automatic-switch and automatic-check-in preferences independently.
|
|
490
|
+
|
|
399
491
|
### `/health` - health check
|
|
400
492
|
|
|
401
493
|
```bash
|
|
@@ -704,6 +796,16 @@ Example output:
|
|
|
704
796
|
|
|
705
797
|
---
|
|
706
798
|
|
|
799
|
+
### Process diagnostics (2.0.7)
|
|
800
|
+
|
|
801
|
+
In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
|
|
802
|
+
(including Uvicorn errors and tracebacks), `process-events.jsonl` records process
|
|
803
|
+
startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
|
|
804
|
+
Python fatal fault stacks. These files are written alongside `--log-file`.
|
|
805
|
+
The console and process-event files rotate by size; see
|
|
806
|
+
[process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
|
|
807
|
+
**Console logs may contain sensitive data: review before sharing.**
|
|
808
|
+
|
|
707
809
|
### Logging
|
|
708
810
|
|
|
709
811
|
Logs include:
|
|
@@ -712,6 +814,20 @@ Logs include:
|
|
|
712
814
|
|
|
713
815
|
Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
|
|
714
816
|
|
|
817
|
+
Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
|
|
818
|
+
three attempts total). HTTP errors and read/write failures are not retried;
|
|
819
|
+
once response headers arrive, the request is never replayed. Each attempt keeps
|
|
820
|
+
the existing 30s connection timeout, so a persistent outage can take up to about
|
|
821
|
+
91.5s before the final error. This applies to streaming and aggregated responses.
|
|
822
|
+
|
|
823
|
+
`upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
|
|
824
|
+
target host/port, and bounded `exception_chain` with exception types and native
|
|
825
|
+
`errno` / `winerror` values when available. `request_id` links these to stream
|
|
826
|
+
start, error, and terminal records. `stream_completed` is reserved for streams
|
|
827
|
+
that received upstream `[DONE]` and finished forwarding; other terminal events
|
|
828
|
+
are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
|
|
829
|
+
`stream_cancelled`. `status: null` means no upstream HTTP response was received.
|
|
830
|
+
|
|
715
831
|
You can also specify an absolute path for the log file:
|
|
716
832
|
|
|
717
833
|
```bash
|
|
@@ -797,6 +913,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
|
|
|
797
913
|
--log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
|
|
798
914
|
```
|
|
799
915
|
|
|
916
|
+
### Upstream error 11148 "tool calls and tool results do not match"
|
|
917
|
+
|
|
918
|
+
Some agent clients produce nonconforming Anthropic / Responses tool histories.
|
|
919
|
+
The CodeBuddy backend requires Chat tool results to directly follow the
|
|
920
|
+
declaring assistant `tool_calls`. The proxy now repairs recoverable converted
|
|
921
|
+
histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
|
|
922
|
+
are deferred, and orphan or identical duplicate results are dropped with
|
|
923
|
+
diagnostic warnings (no tool output is logged).
|
|
924
|
+
|
|
925
|
+
Ambiguous histories are **not silently truncated**. If a call has no result, a
|
|
926
|
+
tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
|
|
927
|
+
**422**, with `detail.code=invalid_tool_history` and a specific `reason`.
|
|
928
|
+
No request is sent upstream in that case. Verify the side effects of any
|
|
929
|
+
unfinished tools before retrying or starting a fresh conversation.
|
|
930
|
+
|
|
931
|
+
This repair does not apply to direct `/v1/chat/completions` requests and cannot
|
|
932
|
+
guarantee the absence of unrelated upstream 11148 errors.
|
|
933
|
+
|
|
800
934
|
### Port already in use
|
|
801
935
|
|
|
802
936
|
```bash
|
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
> **中文版文档见 [README_zh.md](README_zh.md).**
|
|
6
6
|
|
|
7
|
+
For unexplained Windows process exits, use the [independent process monitor](docs/external-process-monitor.md) to collect uv/Python exit codes, lifecycle, memory, health, and available Windows events without restarting the proxy.
|
|
8
|
+
|
|
7
9
|
## ✨ Core Features
|
|
8
10
|
|
|
9
11
|
- **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
|
|
@@ -13,7 +15,9 @@
|
|
|
13
15
|
- **DSML parsing** - Automatically detects and converts DeepSeek Markup Language (DSML) tool calls
|
|
14
16
|
- **Streaming responses** - SSE streaming output, returning generated content in real time, with built-in 60-second timeout protection
|
|
15
17
|
- **Domestic and international backends** - Uses domestic CodeBuddy by default and switches to the international CodeBuddy service with `--global`, with isolated sessions and model catalogs
|
|
16
|
-
- **Multi-account management** -
|
|
18
|
+
- **Multi-account management** - Link domestic and Global accounts, switch the active account, and remove non-active accounts from the local admin page
|
|
19
|
+
- **Model-level 429 handling** - Track cooldowns per account and model, with optional same-region failover
|
|
20
|
+
- **Daily check-in** - Check in manually or enable background checks for all linked accounts
|
|
17
21
|
|
|
18
22
|
---
|
|
19
23
|
|
|
@@ -49,12 +53,14 @@ uv sync
|
|
|
49
53
|
uv run python -m codebuddy_proxy --desensitize
|
|
50
54
|
```
|
|
51
55
|
|
|
52
|
-
On first use,
|
|
56
|
+
On first use, start the proxy and open the local account manager:
|
|
53
57
|
|
|
54
58
|
```bash
|
|
55
|
-
uv run python -m codebuddy_proxy --
|
|
59
|
+
uv run python -m codebuddy_proxy --desensitize
|
|
56
60
|
```
|
|
57
61
|
|
|
62
|
+
Then visit `http://127.0.0.1:8787/admin` and link a domestic or Global account.
|
|
63
|
+
|
|
58
64
|
## Quick Start
|
|
59
65
|
|
|
60
66
|
### 1. Start the proxy
|
|
@@ -63,8 +69,8 @@ uv run python -m codebuddy_proxy --login --desensitize
|
|
|
63
69
|
# Use the latest version (recommended)
|
|
64
70
|
uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
|
|
65
71
|
|
|
66
|
-
# First use:
|
|
67
|
-
uv run --with workbuddy2api python -m codebuddy_proxy --
|
|
72
|
+
# First use: start, then link an account at http://127.0.0.1:8787/admin
|
|
73
|
+
uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
|
|
68
74
|
|
|
69
75
|
# International service: first login and start
|
|
70
76
|
uv run --with workbuddy2api python -m codebuddy_proxy --global --login --desensitize
|
|
@@ -80,12 +86,23 @@ Listens on `http://127.0.0.1:8787` by default.
|
|
|
80
86
|
The proxy supports both CodeBuddy regions. Domestic mode remains the default,
|
|
81
87
|
so existing startup commands continue to work unchanged.
|
|
82
88
|
|
|
83
|
-
| Mode | Startup option | Upstream endpoint |
|
|
84
|
-
| --- | --- | --- |
|
|
85
|
-
| Domestic (default) | none | `https://copilot.tencent.com` |
|
|
86
|
-
| International | `--global` | `https://www.codebuddy.ai` |
|
|
89
|
+
| Mode | Startup option | Upstream endpoint |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| Domestic (default) | none | `https://copilot.tencent.com` |
|
|
92
|
+
| International | `--global` | `https://www.codebuddy.ai` |
|
|
93
|
+
|
|
94
|
+
Linked accounts are stored separately by region in `~/.workbuddy2api/accounts`.
|
|
95
|
+
Use `--accounts-dir DIR` to choose another local directory. With no explicit
|
|
96
|
+
selector, the proxy restores the saved active account. On the first migration,
|
|
97
|
+
matching legacy session files are imported once and kept; deleting an imported
|
|
98
|
+
account does not import it again. Explicit `--global` or `--endpoint` selects a
|
|
99
|
+
matching account, while `--session-file` can import that file again. If there is
|
|
100
|
+
no match, the proxy starts without an active account. `--login` uses a temporary
|
|
101
|
+
session file to add or refresh an account without replacing a legacy file.
|
|
87
102
|
|
|
88
|
-
|
|
103
|
+
The account manager can add accounts for either region while the proxy is
|
|
104
|
+
running. For a terminal-driven login, the existing `--login` option remains
|
|
105
|
+
available:
|
|
89
106
|
|
|
90
107
|
```bash
|
|
91
108
|
# First login
|
|
@@ -101,16 +118,18 @@ If the package is installed as a command, the equivalent short form is
|
|
|
101
118
|
`workbuddy2api --global --login`. When running from source, use
|
|
102
119
|
`uv run python -m codebuddy_proxy --global --login`.
|
|
103
120
|
|
|
104
|
-
`--global`
|
|
105
|
-
OpenCode, and other clients continue to use
|
|
106
|
-
selected profile also controls the model catalog
|
|
121
|
+
`--global` selects the Global backend and a matching account when one exists.
|
|
122
|
+
Codex CLI, Claude Code/CC Switch, OpenCode, and other clients continue to use
|
|
123
|
+
the same local proxy URLs. The selected profile also controls the model catalog
|
|
124
|
+
returned by `/v1/models`.
|
|
107
125
|
|
|
108
|
-
Domestic and international
|
|
109
|
-
`--session-file`
|
|
110
|
-
|
|
111
|
-
|
|
126
|
+
Domestic and international accounts remain isolated. An explicit
|
|
127
|
+
`--session-file` is imported only when its saved backend and endpoint match the
|
|
128
|
+
current startup options. The proxy refuses mismatched credentials and does not
|
|
129
|
+
modify the original file.
|
|
112
130
|
|
|
113
|
-
For a custom international endpoint,
|
|
131
|
+
For a custom international endpoint, use a dedicated session file when
|
|
132
|
+
importing or creating a login from the command line:
|
|
114
133
|
|
|
115
134
|
```bash
|
|
116
135
|
uv run --with workbuddy2api python -m codebuddy_proxy \
|
|
@@ -125,6 +144,24 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
|
|
|
125
144
|
Therefore `--global` without `--endpoint` cannot be redirected to the domestic
|
|
126
145
|
host by `CODEBUDDY_ENDPOINT`.
|
|
127
146
|
|
|
147
|
+
### Built-in CodeBuddy gateways: developer-role compatibility
|
|
148
|
+
|
|
149
|
+
The built-in domestic (`https://copilot.tencent.com`) and international
|
|
150
|
+
(`https://www.codebuddy.ai`) Chat Completions gateways may reject requests
|
|
151
|
+
containing a `developer` message with HTTP 400 / code 11128. Before forwarding
|
|
152
|
+
to either matching backend and host, the proxy maps `developer` to `system`
|
|
153
|
+
without changing message order, content, tool-call history, or the original
|
|
154
|
+
client request. If enabled, `--desensitize` runs after this role adaptation.
|
|
155
|
+
No client-side configuration is needed.
|
|
156
|
+
|
|
157
|
+
The mapping is scoped to these exact backend/host pairs; endpoints using
|
|
158
|
+
other host names keep their original roles. International `X-Conversation-*` headers
|
|
159
|
+
are still generated after request-body transformations. Because the upstreams
|
|
160
|
+
do not represent the separate `system` and `developer` instruction priorities,
|
|
161
|
+
the mapping is an approximation, not exact semantic equivalence. The
|
|
162
|
+
`upstream_role_compat` log event reports the backend and number of mapped
|
|
163
|
+
messages, not prompt contents.
|
|
164
|
+
|
|
128
165
|
Runtime model catalogs are loaded from the packaged profile resources
|
|
129
166
|
`src/codebuddy_proxy/models_config.domestic.json` and
|
|
130
167
|
`src/codebuddy_proxy/models_config.global.json`. The root
|
|
@@ -292,6 +329,7 @@ Select the model inside OMP with `/model codebuddy/hy3` (or set it as the defaul
|
|
|
292
329
|
--global Use the international CodeBuddy backend (default domestic)
|
|
293
330
|
--endpoint ENDPOINT CodeBuddy backend address (overrides the profile default)
|
|
294
331
|
--session-file PATH Session file path (isolated by profile by default)
|
|
332
|
+
--accounts-dir DIR Account library directory (default ~/.workbuddy2api/accounts)
|
|
295
333
|
--log-file PATH JSONL log file (default ~/.workbuddy2api/codebuddy-proxy.jsonl)
|
|
296
334
|
--desensitize Enable desensitization (recommended)
|
|
297
335
|
--optimize-context Enable message compression (recommended for Codex CLI)
|
|
@@ -352,15 +390,58 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
|
|
|
352
390
|
|
|
353
391
|
### Multi-account switching
|
|
354
392
|
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
393
|
+
Start the proxy and open [http://127.0.0.1:8787/admin](http://127.0.0.1:8787/admin).
|
|
394
|
+
Choose **Domestic** or **Global**, then link the account in the browser window.
|
|
395
|
+
The first linked account becomes active automatically; linking another account
|
|
396
|
+
does not change the account currently in use. Use **Set active** to switch, or
|
|
397
|
+
remove a non-active account from the same page. The selection is saved for the
|
|
398
|
+
next proxy start. Switching affects new requests; requests already in progress
|
|
399
|
+
continue with the account selected when they began.
|
|
400
|
+
|
|
401
|
+

|
|
402
|
+
|
|
403
|
+
The screenshot uses synthetic demo accounts. Account UIDs are covered, and no
|
|
404
|
+
credentials or session contents are shown. Accounts are kept separately by
|
|
405
|
+
backend, normalized endpoint, and user ID in `~/.workbuddy2api/accounts`; use
|
|
406
|
+
`--accounts-dir DIR` to choose another local directory. The manager remains
|
|
407
|
+
available before any account is linked. Its page and API are restricted to
|
|
408
|
+
loopback access, and API responses do not include tokens or session data.
|
|
409
|
+
|
|
410
|
+
Use the language selector at the top of the page to switch between Chinese and
|
|
411
|
+
English. The choice is remembered in this browser; without a saved preference,
|
|
412
|
+
the page follows the browser language. Switching languages keeps ongoing login
|
|
413
|
+
and account operations running.
|
|
414
|
+
|
|
415
|
+
Automatic account switching after an upstream HTTP `429` is off by default.
|
|
416
|
+
When enabled, a request can fail over only before any response has been sent,
|
|
417
|
+
and only to accounts with the same region and endpoint. Each account is tried
|
|
418
|
+
at most once per request. The proxy skips a candidate only when the request's
|
|
419
|
+
model is cooling down there; other models on that account remain eligible. A
|
|
420
|
+
missing or invalid model does not create a model cooldown or trigger failover.
|
|
421
|
+
If all tried accounts return `429`, the final status remains `429`, and the
|
|
422
|
+
last upstream response's `Retry-After` header is preserved when present.
|
|
423
|
+
Cooldowns are tracked per account and model, using upstream `Retry-After` or a
|
|
424
|
+
default 60 seconds when that value is missing or invalid. The setting and model
|
|
425
|
+
cooldowns persist across restarts. Old v1 account-wide cooldowns had no model
|
|
426
|
+
identity and are not carried forward during upgrade. The page shows a separate
|
|
427
|
+
remaining countdown and source for each model, and refreshes account state
|
|
428
|
+
periodically and immediately when a hidden page becomes visible again.
|
|
429
|
+
|
|
430
|
+
The account list also shows each linked account's check-in status for today
|
|
431
|
+
(Beijing time). The **Check in** action is available for every account, including
|
|
432
|
+
the active one; it checks the account first and does nothing when today's check-in
|
|
433
|
+
is already complete. The global automatic check-in setting is off by default and
|
|
434
|
+
applies to all linked accounts without changing the active account. The page saves
|
|
435
|
+
this setting and displays status; the proxy performs automatic checks and check-ins
|
|
436
|
+
in the background, including when the management page is closed. When enabled, the
|
|
437
|
+
proxy checks all linked accounts immediately and on startup. At Beijing midnight it
|
|
438
|
+
checks them, waits a random 0–10 minutes, then checks again before signing; disabling
|
|
439
|
+
it cancels pending scheduled work. Unknown status is never treated as permission to
|
|
440
|
+
sign. The setting persists; after restart, check-in status is confirmed by querying
|
|
441
|
+
the upstream service again.
|
|
442
|
+
|
|
443
|
+
The command-line `--login` flow and `--session-file` option remain available for
|
|
444
|
+
terminal use and importing an existing session.
|
|
364
445
|
|
|
365
446
|
### Listening on all interfaces (LAN sharing)
|
|
366
447
|
|
|
@@ -376,11 +457,20 @@ All endpoints do not require an extra token in the request by default; the proxy
|
|
|
376
457
|
| Method | Path | Purpose |
|
|
377
458
|
| --- | --- | --- |
|
|
378
459
|
| GET | `/health` | Query local service and auth status |
|
|
460
|
+
| GET | `/admin` | Open the local account manager |
|
|
379
461
|
| GET | `/v1/models` | Query the CodeBuddy model list |
|
|
380
462
|
| POST | `/v1/chat/completions` | OpenAI Chat Completions, supports tools and streaming |
|
|
381
463
|
| POST | `/v1/responses` | Responses API, compatible with Codex CLI |
|
|
382
464
|
| POST | `/v1/messages` | Anthropic Messages API, compatible with Claude Code / CC Switch |
|
|
383
465
|
|
|
466
|
+
Account-management endpoints live under `/admin/api` and are restricted to
|
|
467
|
+
loopback clients. Write requests require the `X-Account-Manager: 1` header, and
|
|
468
|
+
cross-origin requests are rejected. `GET /admin/api/accounts` reports active
|
|
469
|
+
account, cooldown, and cached check-in state. `GET /admin/api/accounts/{id}/checkin-status`
|
|
470
|
+
checks that account against the upstream service; `POST /admin/api/accounts/{id}/checkin`
|
|
471
|
+
checks first and signs only when needed. `GET` and `PATCH /admin/api/settings` read
|
|
472
|
+
and save the automatic-switch and automatic-check-in preferences independently.
|
|
473
|
+
|
|
384
474
|
### `/health` - health check
|
|
385
475
|
|
|
386
476
|
```bash
|
|
@@ -689,6 +779,16 @@ Example output:
|
|
|
689
779
|
|
|
690
780
|
---
|
|
691
781
|
|
|
782
|
+
### Process diagnostics (2.0.7)
|
|
783
|
+
|
|
784
|
+
In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
|
|
785
|
+
(including Uvicorn errors and tracebacks), `process-events.jsonl` records process
|
|
786
|
+
startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
|
|
787
|
+
Python fatal fault stacks. These files are written alongside `--log-file`.
|
|
788
|
+
The console and process-event files rotate by size; see
|
|
789
|
+
[process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
|
|
790
|
+
**Console logs may contain sensitive data: review before sharing.**
|
|
791
|
+
|
|
692
792
|
### Logging
|
|
693
793
|
|
|
694
794
|
Logs include:
|
|
@@ -697,6 +797,20 @@ Logs include:
|
|
|
697
797
|
|
|
698
798
|
Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
|
|
699
799
|
|
|
800
|
+
Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
|
|
801
|
+
three attempts total). HTTP errors and read/write failures are not retried;
|
|
802
|
+
once response headers arrive, the request is never replayed. Each attempt keeps
|
|
803
|
+
the existing 30s connection timeout, so a persistent outage can take up to about
|
|
804
|
+
91.5s before the final error. This applies to streaming and aggregated responses.
|
|
805
|
+
|
|
806
|
+
`upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
|
|
807
|
+
target host/port, and bounded `exception_chain` with exception types and native
|
|
808
|
+
`errno` / `winerror` values when available. `request_id` links these to stream
|
|
809
|
+
start, error, and terminal records. `stream_completed` is reserved for streams
|
|
810
|
+
that received upstream `[DONE]` and finished forwarding; other terminal events
|
|
811
|
+
are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
|
|
812
|
+
`stream_cancelled`. `status: null` means no upstream HTTP response was received.
|
|
813
|
+
|
|
700
814
|
You can also specify an absolute path for the log file:
|
|
701
815
|
|
|
702
816
|
```bash
|
|
@@ -782,6 +896,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
|
|
|
782
896
|
--log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
|
|
783
897
|
```
|
|
784
898
|
|
|
899
|
+
### Upstream error 11148 "tool calls and tool results do not match"
|
|
900
|
+
|
|
901
|
+
Some agent clients produce nonconforming Anthropic / Responses tool histories.
|
|
902
|
+
The CodeBuddy backend requires Chat tool results to directly follow the
|
|
903
|
+
declaring assistant `tool_calls`. The proxy now repairs recoverable converted
|
|
904
|
+
histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
|
|
905
|
+
are deferred, and orphan or identical duplicate results are dropped with
|
|
906
|
+
diagnostic warnings (no tool output is logged).
|
|
907
|
+
|
|
908
|
+
Ambiguous histories are **not silently truncated**. If a call has no result, a
|
|
909
|
+
tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
|
|
910
|
+
**422**, with `detail.code=invalid_tool_history` and a specific `reason`.
|
|
911
|
+
No request is sent upstream in that case. Verify the side effects of any
|
|
912
|
+
unfinished tools before retrying or starting a fresh conversation.
|
|
913
|
+
|
|
914
|
+
This repair does not apply to direct `/v1/chat/completions` requests and cannot
|
|
915
|
+
guarantee the absence of unrelated upstream 11148 errors.
|
|
916
|
+
|
|
785
917
|
### Port already in use
|
|
786
918
|
|
|
787
919
|
```bash
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "workbuddy2api"
|
|
3
|
-
version = "2.0.
|
|
3
|
+
version = "2.0.8.dev1"
|
|
4
4
|
description = "Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.10"
|
|
@@ -9,6 +9,8 @@ dependencies = [
|
|
|
9
9
|
"uvicorn>=0.24.0",
|
|
10
10
|
"httpx[socks]>=0.25.0",
|
|
11
11
|
"requests>=2.31.0",
|
|
12
|
+
"buddy-agent-auth>=0.1.0.dev1,<0.2",
|
|
13
|
+
"buddy-agent-checkin[workbuddy]>=0.1.1.dev2,<0.2",
|
|
12
14
|
]
|
|
13
15
|
|
|
14
16
|
[project.optional-dependencies]
|
|
@@ -27,9 +29,9 @@ build-backend = "setuptools.build_meta"
|
|
|
27
29
|
where = ["src"]
|
|
28
30
|
|
|
29
31
|
[tool.setuptools.package-data]
|
|
30
|
-
codebuddy_proxy = ["models_config.*.json"]
|
|
32
|
+
codebuddy_proxy = ["models_config.*.json", "admin.html"]
|
|
31
33
|
|
|
32
34
|
[dependency-groups]
|
|
33
35
|
dev = [
|
|
34
36
|
"pytest>=7.4.0",
|
|
35
|
-
]
|
|
37
|
+
]
|