# wwanet_agent_go

**Repository Path**: makeval/wwanet_agent_go

## Basic Information

- **Project Name**: wwanet_agent_go
- **Description**: wwanet 算力房东
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miner-go · WWA 算力房东客户端（Go）

> WWA 算力节点客户端（Go）：将你自托管、自行审阅的本地模型接入开放算力网络，按 token 对外服务并按平台规则结算。
> 节点部署后的网络安全、内容合规与税务申报义务由节点运营者自行承担。

> ⚠️ 安全与法律提示：本程序为开源客户端，请自行审阅源码并编译；运行后会与平台网关建立出站长连接。位于中国大陆的
> 个人及实体禁止以商业收益为目的运行本程序；请勿在存放个人数据、商业秘密或敏感信息的设备上运行。

## WWA 算力生态速览

WWA（World Wide Agents）是一个开放的 Agent 与算力互联平台：

- 调用方：用 OpenAI 兼容的 `POST /v1/chat/completions` 按模型 ID 调用；
- 平台网关：负责模型路由、多实例负载均衡、用量计费与分成结算；
- 算力房东（你）：提供本地模型服务，节点客户端与平台保持长连接，接收 `llm.request` 并回传结果与 usage。

本仓库即“算力房东客户端”的 Go 实现（项目代号 miner-go），**独立分发**：
克隆本仓库即可完成部署、更新与维护，不需要下载平台侧的其他工程。

## 工作方式

```text
调用方
  │  /v1/chat/completions
  ▼
WWA 网关（计费 / 调度 / 健康监控）
  │  llm.request（WS 长连接，X-Agent-Key 鉴权）
  ▼
miner-go（本仓库）
  │  /chat/completions（OpenAI 兼容）
  ▼
本地推理服务：vLLM / Ollama / llama.cpp
  │  llm.response / llm.chunk / llm.done（含 usage）
  ▼
WWA 网关 → 调用方，同时按 usage 记账 → 房东钱包
```

## 特性

- 高并发转发：每路 `llm.request` 一个 goroutine，`MINER_MAX_CONCURRENCY` 信号量闸门，忙时立即回 `llm.error`；
- 计费可靠：流式请求自动携带 `stream_options.include_usage`；usage 缺失时走平台“保守估算”兜底，并在 `/healthz` 暴露 `no_usage`；
- 协议完整：非流式 `llm.response`、流式 `llm.chunk`/`llm.done`、失败 `llm.error`；透传真实 `finish_reason`；
  `tool_calls` 暂不支持时明确报错，不静默返回空回复；
- 在线保持：心跳 + WS 控制帧保活；断线指数退避 + ±20% 抖动重连（1s→30s）；心跳连续失败自动强制重连；
- 热配置：消费平台 `agent.config` 推送，并以 `/self` 2 分钟轮询兜底；
- 可观测：`/healthz` 输出 `connected / active / served / failed / no_usage`，监听地址可配置；
- 优雅退出：SIGINT/SIGTERM 停止收发，等待在飞请求最多 10 秒；
- 多形态：单二进制直接运行，或 Docker 一键部署 NVIDIA（vLLM）与 Apple Silicon（Ollama）。

## 目录结构

```text
├── main.go          客户端主程序（单文件实现）
├── main_test.go     单元测试（usage 兜底 / 退避抖动 / rune 截断）
├── Dockerfile       客户端镜像（独立构建）
├── deploy/          Docker 一键部署（NVIDIA / Apple Silicon）
├── go.mod / go.sum  Go 模块
└── LICENSE          Apache-2.0
```

## 快速开始

### 方式一：Docker 一键部署（推荐）

```bash
git clone https://gitee.com/makeval/wwanet_agent_go.git
cd wwanet_agent_go/deploy
cp .env.example .env
# 按 deploy/README.md 生成 proxy-credentials.json 后：
docker compose -f docker-compose.nvidia.yml up -d --build   # NVIDIA 4090/3090
docker compose -f docker-compose.apple.yml up -d --build    # Apple Silicon Mac mini
```

凭据注册、模型上架、验证与更新详见 [deploy/README.md](deploy/README.md)。

### 方式二：已有本地模型服务时直接运行

先准备 `proxy-credentials.json`（结构见 deploy/README.md），再写 `proxy.env`：

```bash
cat > proxy.env <<'EOF'
WWA_SERVER=https://www.wwanet.com
LIGHTAGENT_API_BASE=http://127.0.0.1:18080/v1   # 本地 OpenAI 兼容服务
LIGHTAGENT_LLM_MODEL=qwen2.5-coder-14b          # 本地服务暴露的模型名
LIGHTAGENT_MAX_TOKENS=2048
EOF

go build -o miner .
./miner
curl -s http://127.0.0.1:2110/healthz
```

## 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `WWA_SERVER` | `https://www.wwanet.com` | 平台地址（凭据文件 `server` 为空时生效） |
| `LIGHTAGENT_API_BASE` | `http://127.0.0.1:18080/v1` | 本地 OpenAI 兼容服务地址 |
| `LIGHTAGENT_LLM_MODEL` | 空 | 本地模型名（平台请求自带 model 时以请求为准） |
| `LIGHTAGENT_MAX_TOKENS` | 2048 | 平台未指定 max_tokens 时的本地默认值 |
| `MINER_MAX_CONCURRENCY` | 8 | 并发闸门上限 |
| `MINER_HEARTBEAT_SECONDS` | 25 | 心跳间隔（秒） |
| `MINER_RECONNECT_MAX_SECONDS` | 30 | WS 重连退避封顶（秒） |
| `MINER_HTTP_ADDR` | `:2110` | healthz 监听地址 |

## 协议要点

- 凭据：`proxy-credentials.json`（`server` / `agent_id` / `secret`）；
- 连接：`wss://<server>/ws`，握手头 `X-Agent-Key: <secret>`（密钥不进 URL）；
- 入站事件：`llm.request`、`agent.config`；
- 出站事件：`llm.response` / `llm.chunk` / `llm.done` / `llm.error`；
- 心跳：`POST /api/agents/{id}/heartbeat`。

## 安全与生产建议

- 本地推理服务只监听容器内网或回环地址，不要暴露公网；
- `proxy-credentials.json` 设为 600、只读挂载、不要提交进 git（已在 `.gitignore`）；
- 保持平台地址为 https/wss；
- 生产环境锁定镜像版本，升级前先在测试机回归；
- 模型权重与推理数据不出本机；自托管模型请确认许可。

## License

Apache License 2.0，见 [LICENSE](LICENSE)。