Initial release v1.1.0: WorkBuddy Local Gateway
- Pure Go, zero CGO, single binary, cross-platform (Windows/Linux/macOS) - Full model passthrough to Tencent CodeBuddy upstream - CLI login with ASCII QR, auto token refresh - OpenAI-compatible API with SSE streaming + non-stream aggregation - Reasoning-effort passthrough only when client explicitly requests - No credentials, secrets, IPs or sensitive domains in repo
This commit is contained in:
CangShui
+19
@@ -0,0 +1,19 @@
|
||||
# 凭据与敏感数据（切勿提交！）
|
||||
workbuddy.json
|
||||
workbuddy-console.json
|
||||
dist/workbuddy.json
|
||||
dist/*.json
|
||||
last-*.json
|
||||
*.json.bak
|
||||
|
||||
# 本地编译产物
|
||||
workbuddy-gateway.exe
|
||||
dist/*.exe
|
||||
dist/workbuddy-gateway-linux-*
|
||||
dist/workbuddy-gateway-darwin-*
|
||||
|
||||
# 日志与临时文件
|
||||
*.log
|
||||
*.tmp
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
@@ -0,0 +1,240 @@
|
||||
# WorkBuddy Local Gateway
|
||||
|
||||
基于腾讯 **CodeBuddy / 混元（Hunyuan）** 协议开发的**纯 Go、零 CGO 依赖、跨平台单二进制**本地 AI 代理网关。无 Web UI，仅通过命令行（CLI）完成扫码登录、凭据续期与服务控制。
|
||||
|
||||
## 核心特性
|
||||
|
||||
- **模型完全透传**：客户端（OpenAI SDK、Cursor、Claude Code、DSH 等）传什么 `model`（如 `hy4-preview`、`hy3-preview-agent`、`hy3`、`deepseek-v4-pro`、`glm-5.2`…），网关原样透传至腾讯上游，无白名单限制。
|
||||
- **纯 CLI 控制**：终端内嵌 ASCII 二维码，微信 / 企业微信扫码登录；`status` / `refresh` / `serve` 子命令完成全部管理。
|
||||
- **后台自动续期**：运行期间每 5 分钟检查 Token，距过期不足 15 分钟自动刷新并持久化到 `workbuddy.json`。
|
||||
- **OpenAI 兼容协议**：`POST /v1/chat/completions`（SSE 流式 + 非流式聚合）、`GET /v1/models`、`GET /health`。
|
||||
- **深度思考透传规则**：仅当客户端显式请求 `reasoning_effort` 时转发；绝不强制注入，避免触发上游内容安全策略。
|
||||
- **反审查净化**：自动改写 Claude Code 等框架被上游逐字拉黑的固定 Prompt 语句。
|
||||
- **单并发串行化**：同一账号请求自动排队，避免并发双发触发上游风控。
|
||||
|
||||
## 快速上手
|
||||
|
||||
### 1. 扫码登录
|
||||
|
||||
首次使用或凭据失效时执行（需微信 / 企业微信扫码）：
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
.\workbuddy-gateway-windows-amd64.exe login
|
||||
|
||||
# Linux / macOS
|
||||
./workbuddy-gateway-linux-amd64 login
|
||||
./workbuddy-gateway-darwin-arm64 login
|
||||
```
|
||||
|
||||
终端将打印 ASCII 二维码与浏览器直达链接，扫码后凭据自动保存到当前目录 `workbuddy.json`（请勿提交到代码仓库）。
|
||||
|
||||
> 提示：建议在 **CodeBuddy 控制台（网页端）** 扫码登录获取更高权限评级的 Token；若使用 `login` 命令扫码，账号渠道可能受限（`azp=invite`）。
|
||||
|
||||
### 2. 查看凭据状态
|
||||
|
||||
```bash
|
||||
workbuddy-gateway status
|
||||
```
|
||||
|
||||
### 3. 启动本地网关
|
||||
|
||||
```bash
|
||||
# 默认监听 127.0.0.1:8317
|
||||
workbuddy-gateway serve
|
||||
|
||||
# 自定义端口 / 地址 / 详细日志
|
||||
workbuddy-gateway serve -port 8317 -verbose
|
||||
|
||||
# 通过出口代理转发（可选，降低上游风控概率）
|
||||
workbuddy-gateway serve -proxy http://127.0.0.1:7890
|
||||
|
||||
# 开启客户端鉴权
|
||||
workbuddy-gateway serve -api-key sk-localsecret
|
||||
```
|
||||
|
||||
## 客户端接入
|
||||
|
||||
网关启动后服务地址为 `http://127.0.0.1:8317/v1`。
|
||||
|
||||
```bash
|
||||
curl -N -s http://127.0.0.1:8317/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"hy4-preview","messages":[{"role":"user","content":"你好"}],"stream":true}'
|
||||
```
|
||||
|
||||
Python OpenAI SDK：
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key="none")
|
||||
resp = client.chat.completions.create(
|
||||
model="hy4-preview",
|
||||
messages=[{"role": "user", "content": "写一个快速排序"}],
|
||||
)
|
||||
print(resp.choices[0].message.content)
|
||||
```
|
||||
|
||||
DSH (`~/.dsh/settings.yaml`)：
|
||||
|
||||
```yaml
|
||||
llm-pi-ai:
|
||||
providers:
|
||||
workbuddy-local:
|
||||
baseURL: http://127.0.0.1:8317/v1
|
||||
apiKeyEnv: LOCAL_API_KEY # 任意字符串即可
|
||||
api: openai-completions
|
||||
models:
|
||||
- id: hy4-preview
|
||||
contextWindow: 1000000
|
||||
maxTokens: 128000
|
||||
```
|
||||
|
||||
## 各平台使用方法
|
||||
|
||||
### Windows
|
||||
|
||||
1. 下载 `dist/workbuddy-gateway-windows-amd64.exe`。
|
||||
2. 在 PowerShell / CMD 中进入文件所在目录：
|
||||
```powershell
|
||||
.\workbuddy-gateway-windows-amd64.exe login
|
||||
.\workbuddy-gateway-windows-amd64.exe serve -port 8317
|
||||
```
|
||||
3. 如需开机自启：`Win+R` → `shell:startup`，将 exe 的快捷方式放入启动文件夹即可（命令行加 `serve` 参数需通过快捷方式"目标"追加）。
|
||||
|
||||
### Linux (amd64 / arm64)
|
||||
|
||||
1. 下载对应架构二进制，赋执行权限并放入 PATH：
|
||||
```bash
|
||||
# x86_64
|
||||
sudo install -m 755 workbuddy-gateway-linux-amd64 /usr/local/bin/workbuddy-gateway
|
||||
# ARM64 (树莓派 / 飞腾 / Apple silicon 云主机等)
|
||||
sudo install -m 755 workbuddy-gateway-linux-arm64 /usr/local/bin/workbuddy-gateway
|
||||
```
|
||||
2. 登录并启动：
|
||||
```bash
|
||||
workbuddy-gateway login # 终端二维码扫码（可用 tmux 保持）
|
||||
workbuddy-gateway serve -addr 127.0.0.1 -port 8317
|
||||
```
|
||||
|
||||
#### Linux 注册为 systemd 服务（推荐，开机自启 + 崩溃自动拉起）
|
||||
|
||||
创建 `/etc/systemd/system/workbuddy-gateway.service`：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=WorkBuddy Local Gateway (CodeBuddy/Hunyuan OpenAI-compatible proxy)
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
# 二进制与 workbuddy.json 所在目录；请按实际部署路径修改
|
||||
WorkingDirectory=/opt/workbuddy-gateway
|
||||
ExecStart=/opt/workbuddy-gateway/workbuddy-gateway serve -addr 127.0.0.1 -port 8317
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
User=root
|
||||
NoNewPrivileges=true
|
||||
ProtectSystem=full
|
||||
ProtectHome=false
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
部署文件：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/workbuddy-gateway
|
||||
sudo cp workbuddy-gateway /opt/workbuddy-gateway/ # 对应架构的二进制
|
||||
# 首次登录（会生成 workbuddy.json）
|
||||
sudo /opt/workbuddy-gateway/workbuddy-gateway login
|
||||
```
|
||||
|
||||
启用并启动服务：
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now workbuddy-gateway
|
||||
sudo systemctl status workbuddy-gateway # 查看状态
|
||||
sudo journalctl -u workbuddy-gateway -f # 查看实时日志
|
||||
```
|
||||
|
||||
常用运维命令：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart workbuddy-gateway # 重启（如更换凭据后）
|
||||
sudo systemctl stop workbuddy-gateway # 停止
|
||||
sudo systemctl disable workbuddy-gateway # 取消开机自启
|
||||
```
|
||||
|
||||
如需对外开放（例如给局域网其他设备使用），将 `-addr` 改为 `0.0.0.0`，**并务必**配合 `-api-key` 设置访问密钥：
|
||||
|
||||
```bash
|
||||
ExecStart=/opt/workbuddy-gateway/workbuddy-gateway serve -addr 0.0.0.0 -port 8317 -api-key sk-changeme
|
||||
```
|
||||
|
||||
### macOS (Apple Silicon / Intel)
|
||||
|
||||
1. 下载 `workbuddy-gateway-darwin-arm64`（M 系列）或 `workbuddy-gateway-darwin-amd64`（Intel）。
|
||||
2. 首次运行需移除隔离属性：
|
||||
```bash
|
||||
chmod +x workbuddy-gateway-darwin-arm64
|
||||
xattr -d com.apple.quarantine workbuddy-gateway-darwin-arm64 2>/dev/null || true
|
||||
```
|
||||
3. 登录与启动：
|
||||
```bash
|
||||
./workbuddy-gateway-darwin-arm64 login
|
||||
./workbuddy-gateway-darwin-arm64 serve
|
||||
```
|
||||
4. 开机自启（launchd）：创建 `~/Library/LaunchAgents/com.workbuddy.gateway.plist`：
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key><string>com.workbuddy.gateway</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/path/to/workbuddy-gateway-darwin-arm64</string>
|
||||
<string>serve</string>
|
||||
<string>-port</string><string>8317</string>
|
||||
</array>
|
||||
<key>RunAtLoad</key><true/>
|
||||
<key>KeepAlive</key><true/>
|
||||
<key>WorkingDirectory</key><string>/path/to/workbuddy-gateway-dir</string>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
```bash
|
||||
launchctl load ~/Library/LaunchAgents/com.workbuddy.gateway.plist
|
||||
```
|
||||
|
||||
## 安全提示
|
||||
|
||||
- `workbuddy.json` 包含真实 CodeBuddy 访问凭据（Access Token / Refresh Token），**严禁提交到 Git 仓库或公开分享**；本仓库 `.gitignore` 已将其排除。
|
||||
- 网关默认只监听 `127.0.0.1`。需要局域网 / 公网访问时请改用 `-addr 0.0.0.0` 并配合 `-api-key` 鉴权，或置于反向代理（如 nginx）之后。
|
||||
- 若不再需要某账号的授权，请删除对应 `workbuddy.json` 并在 CodeBuddy 控制台撤销应用授权。
|
||||
|
||||
## 命令行速查
|
||||
|
||||
```
|
||||
命令: serve | login | status | refresh | version | help
|
||||
选项: -addr <ip> · -port <port> · -auth <path> · -api-key <key> · -proxy <url> · -verbose
|
||||
```
|
||||
|
||||
## 从源码构建
|
||||
|
||||
需要 Go 1.20+：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/CangShui/workbuddy-gateway.git
|
||||
cd workbuddy-gateway
|
||||
CGO_ENABLED=0 go build -ldflags="-s -w" -o workbuddy-gateway .
|
||||
```
|
||||
|
||||
## 免责声明
|
||||
|
||||
本项目仅用于个人学习与技术研究。腾讯 CodeBuddy 的接口协议与风控策略可能随时变化；请遵守腾讯服务条款，自行承担使用风险。本仓库不包含任何官方未公开的密钥或凭据。
|
||||
@@ -0,0 +1,7 @@
|
||||
module workbuddy-gateway
|
||||
|
||||
go 1.26.5
|
||||
|
||||
require github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
|
||||
|
||||
require github.com/google/uuid v1.6.0
|
||||
@@ -0,0 +1,4 @@
|
||||
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
|
||||
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
|
||||
github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
|
||||
github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
|
||||
Reference in New Issue
Block a user