release: bump version to 0.43.0

2026-04-28 16:10:17 +08:00
parent 1cd2dab0ee
commit ac69d5d354
69 changed files with 6954 additions and 1141 deletions
--- a/docs/technical/zh/agents-aiprovider.md
+++ b/docs/technical/zh/agents-aiprovider.md
@@ -1,108 +1,108 @@
-# AI Provider Guide
+# AI Provider 指南

-## Overview
+## 概览

-`aiprovider` is the model-adapter service for Planet.
+`aiprovider` 是 Planet 的模型适配服务。

-It isolates model-vendor details from the main backend so the rest of the system can call a stable business API:
+它把模型厂商差异隔离在主后端之外，让系统其它部分可以调用稳定的业务 API：

- Caller service -> `planet backend`
+- 调用方服务 -> `planet backend`
 - `planet backend` -> `aiprovider`
- `aiprovider` -> concrete model provider
+- `aiprovider` -> 具体模型提供方

-The recommended default is:
+推荐默认方式：

- External and cross-service callers use `planet backend`
- Only infrastructure-grade internal jobs call `aiprovider` directly
+- 外部调用方和跨服务调用方统一调用 `planet backend`
+- 只有基础设施级内部任务才直接调用 `aiprovider`

-## Responsibilities
+## 职责边界

-`backend` is responsible for:
+`backend` 负责：

- authentication and authorization
- business-level request shaping
- stable `/api/v1/ai/...` endpoints
- internal service-to-service authentication toward `aiprovider`
+- 身份认证和权限控制
+- 业务层请求整理
+- 稳定的 `/api/v1/ai/...` 接口
+- 面向 `aiprovider` 的内部服务认证

-`aiprovider` is responsible for:
+`aiprovider` 负责：

- model protocol adaptation
- provider selection by `.env`
- timeout and lightweight retry
- request tracing via `X-Request-ID`
+- 模型协议适配
+- 基于 `.env` 选择 provider
+- 超时和轻量重试
+- 通过 `X-Request-ID` 串联请求追踪

-This now follows an OpenClaw-like seam:
+当前配置采用类似 OpenClaw 的拆分方式：

- `AI_PROVIDER` identifies the vendor or logical provider
- `AI_PROVIDER_API` identifies the wire adapter
+- `AI_PROVIDER` 标识厂商或逻辑 provider
+- `AI_PROVIDER_API` 标识实际请求协议适配器

-That split makes MiniMax, Claude-compatible gateways, and self-hosted OpenAI-compatible services easier to model without overloading one config field.
+这个拆分能更清楚地表达 MiniMax、Claude 兼容网关、自托管 OpenAI 兼容服务等情况，避免把所有含义塞进一个配置项。

-## Supported Providers
+## 支持的 Provider

-`aiprovider` currently supports these provider identities:
+`aiprovider` 当前支持以下 provider 标识：

 - `openai`
 - `anthropic`
 - `minimax`
 - `ollama`

-Supported request adapters:
+支持的请求适配器：

 - `openai-completions`
 - `anthropic-messages`
 - `ollama-generate`

-Backward-compatible aliases still accepted:
+仍然兼容的历史别名：

 - `openai_compatible`
 - `anthropic_compatible`
 - `claude_compatible`

-Provider mapping:
+推荐映射关系：

- `vLLM`, `LM Studio`, `One API`: `AI_PROVIDER=openai`, `AI_PROVIDER_API=openai-completions`
- `MiniMax`: `AI_PROVIDER=minimax`, `AI_PROVIDER_API=anthropic-messages`
- Claude-compatible gateways: `AI_PROVIDER=anthropic`, `AI_PROVIDER_API=anthropic-messages`
- `Ollama`: `AI_PROVIDER=ollama`, `AI_PROVIDER_API=ollama-generate`
+- `vLLM`、`LM Studio`、`One API`：`AI_PROVIDER=openai`，`AI_PROVIDER_API=openai-completions`
+- `MiniMax`：`AI_PROVIDER=minimax`，`AI_PROVIDER_API=anthropic-messages`
+- Claude 兼容网关：`AI_PROVIDER=anthropic`，`AI_PROVIDER_API=anthropic-messages`
+- `Ollama`：`AI_PROVIDER=ollama`，`AI_PROVIDER_API=ollama-generate`

-## API Surfaces
+## API 面

-### Main backend API
+### 主后端 API

-Preferred stable entrypoints:
+推荐使用的稳定入口：

 - `GET /api/v1/ai/provider/status`
 - `POST /api/v1/ai/situational-awareness/analyze`

-Authentication:
+认证方式：

 - `Authorization: Bearer <jwt>`

-Optional tracing header:
+可选追踪头：

 - `X-Request-ID: <caller-generated-id>`

-The backend will propagate `X-Request-ID` to `aiprovider` and return the same header in the response.
+后端会把 `X-Request-ID` 透传给 `aiprovider`，并在响应中返回同一个 header。

-### AI provider internal API
+### AI Provider 内部 API

-Internal-only endpoints:
+仅供内部调用的接口：

 - `GET /v1/provider/status`
 - `POST /v1/analyze`

-Authentication:
+认证方式：

 - `X-Provider-Token: <shared-secret>`

-Optional tracing header:
+可选追踪头：

 - `X-Request-ID: <caller-generated-id>`

-## Request Example
+## 请求示例

-### Call through backend
+### 通过后端调用

 ```bash
 curl -X POST http://localhost:8000/api/v1/ai/situational-awareness/analyze \
@@ -127,7 +127,7 @@ curl -X POST http://localhost:8000/api/v1/ai/situational-awareness/analyze \
  }'
 ```

-### Call `aiprovider` directly
+### 直接调用 `aiprovider`

 ```bash
 curl -X POST http://localhost:8010/v1/analyze \
@@ -149,9 +149,9 @@ curl -X POST http://localhost:8010/v1/analyze \
  }'
 ```

-## Response Shape
+## 响应结构

-Both backend and `aiprovider` return the same payload shape:
+后端和 `aiprovider` 返回相同的 payload 结构：

 ```json
 {
@@ -166,15 +166,15 @@ Both backend and `aiprovider` return the same payload shape:
 }
 ```

-Both services also return:
+两个服务都会返回：

 - `X-Request-ID: <id>`

-## Configuration
+## 配置

-### Backend
+### 后端

-Recommended backend `.env`:
+推荐的后端 `.env`：

 ```env
 AI_PROVIDER_SERVICE_URL=http://localhost:8010
@@ -183,21 +183,21 @@ AI_PROVIDER_TIMEOUT_SECONDS=60
 AI_PROVIDER_RETRY_ATTEMPTS=2
 ```

-Reference file:
+参考文件：

 - [backend/.env.example](/home/ray/dev/linkong/planet/backend/.env.example)

 ### AI Provider

-Reference file:
+参考文件：

 - [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)

-Frontend local reference:
+前端本地参考：

 - [frontend/.env.example](/home/ray/dev/linkong/planet/frontend/.env.example)

-Common settings:
+通用配置：

 ```env
 SERVICE_NAME=planet-ai-provider
@@ -208,7 +208,7 @@ AI_HTTP_RETRY_ATTEMPTS=2
 AI_ANALYSIS_SYSTEM_PROMPT=你是态势感知分析助手。请基于输入的上下文、观测与约束，输出结构化、克制、可执行的分析。
 ```

-### OpenAI-compatible example
+### OpenAI 兼容示例

 ```env
 AI_PROVIDER=openai
@@ -218,7 +218,7 @@ AI_API_KEY=local-key
 AI_MODEL=your-local-model
 ```

-### MiniMax CN example
+### MiniMax 中国区示例

 ```env
 AI_PROVIDER=minimax
@@ -230,13 +230,13 @@ AI_MAX_TOKENS=1200
 AI_ANTHROPIC_VERSION=2023-06-01
 ```

-MiniMax note:
+MiniMax 说明：

- This follows the same Anthropic Messages request shape as the official MiniMax examples.
- For MiniMax, `aiprovider` now disables `thinking` by default unless the caller explicitly passes a `thinking` object.
- This mirrors OpenClaw's caution around MiniMax Anthropic-compatible behavior.
+- 这里使用官方 MiniMax 示例中的 Anthropic Messages 请求结构。
+- 对 MiniMax，`aiprovider` 默认不会开启 `thinking`，除非调用方显式传入 `thinking` 对象。
+- 这个行为和 OpenClaw 对 MiniMax Anthropic 兼容接口的谨慎处理保持一致。

-### Anthropic-compatible example
+### Anthropic 兼容示例

 ```env
 AI_PROVIDER=anthropic
@@ -248,7 +248,7 @@ AI_MAX_TOKENS=1200
 AI_ANTHROPIC_VERSION=2023-06-01
 ```

-### Ollama example
+### Ollama 示例

 ```env
 AI_PROVIDER=ollama
@@ -258,36 +258,36 @@ AI_API_KEY=
 AI_MODEL=qwen2.5:7b
 ```

-## Deployment Modes
+## 部署模式

-### Single machine
+### 单机部署

-Recommended local flow:
+推荐的本地流程：

- `backend` on `localhost:8000`
- `aiprovider` on `localhost:8010`
- local model gateway on `localhost:11434` or another local port
+- `backend` 运行在 `localhost:8000`
+- `aiprovider` 运行在 `localhost:8010`
+- 本地模型网关运行在 `localhost:11434` 或其它本地端口

-Helpers already included:
+仓库内已包含辅助入口：

 - [planet.sh](/home/ray/dev/linkong/planet/planet.sh)
 - [docker-compose.local-model.yml](/home/ray/dev/linkong/planet/docker-compose.local-model.yml)

-### Multi-machine
+### 多机部署

-Example topology:
+示例拓扑：

- app machine: `backend`
- AI gateway machine: `aiprovider`
- model machine: local model service or cloud proxy
+- 应用机器：`backend`
+- AI 网关机器：`aiprovider`
+- 模型机器：本地模型服务或云代理

-In that case, this becomes service-to-service HTTP RPC:
+此时链路变成服务间 HTTP RPC：

 - caller -> backend
 - backend -> `http://10.0.0.12:8010`
- `aiprovider` -> model endpoint
+- `aiprovider` -> 模型端点

-Recommended cross-machine backend config:
+推荐的跨机器后端配置：

 ```env
 AI_PROVIDER_SERVICE_URL=http://10.0.0.12:8010
@@ -296,38 +296,38 @@ AI_PROVIDER_TIMEOUT_SECONDS=60
 AI_PROVIDER_RETRY_ATTEMPTS=2
 ```

-Recommended operating rules:
+推荐运行规则：

- keep `aiprovider` on a private network
- protect it with `X-Provider-Token` at minimum
- always send `X-Request-ID`
- keep callers on the backend API unless they are infrastructure jobs
+- 将 `aiprovider` 放在私有网络内
+- 至少用 `X-Provider-Token` 保护它
+- 始终发送 `X-Request-ID`
+- 除基础设施任务外，调用方优先走后端 API

-## Retry And Failure Behavior
+## 重试和失败行为

-`backend -> aiprovider`:
+`backend -> aiprovider`：

- retries lightweight network / 5xx failures
- returns `502` when the provider service is unavailable
+- 对轻量网络错误和 5xx 失败进行重试
+- provider 服务不可用时返回 `502`

-`aiprovider -> model provider`:
+`aiprovider -> model provider`：

- retries lightweight network / 5xx failures
- returns `502` when the model provider is unavailable
+- 对轻量网络错误和 5xx 失败进行重试
+- 模型提供方不可用时返回 `502`

-This is intentionally conservative. It avoids masking persistent errors while still absorbing short hiccups.
+这个策略故意保持保守：它能吸收短暂抖动，但不会掩盖持续性错误。

-## Operational Notes
+## 运维说明

- `./planet.sh start` now starts `aiprovider` automatically
- `./planet.sh restart -a` restarts only `aiprovider`
- `./planet.sh log -a` tails `aiprovider` logs
- `./planet.sh health` reports `aiprovider` health
+- `./planet.sh start` 会自动启动 `aiprovider`
+- `./planet.sh restart -a` 只重启 `aiprovider`
+- `./planet.sh log -a` 跟随查看 `aiprovider` 日志
+- `./planet.sh health` 会报告 `aiprovider` 健康状态

-## Recommended Calling Policy
+## 推荐调用策略

- Frontend and application services: call `backend`
- Scheduled infra jobs and diagnostics: optionally call `aiprovider`
- Do not let multiple business services integrate model vendors independently
+- 前端和应用服务：调用 `backend`
+- 定时基础设施任务和诊断任务：可选直接调用 `aiprovider`
+- 不要让多个业务服务分别接入模型厂商

-That keeps provider switching centralized and avoids model-specific drift across the system.
+这样可以集中管理 provider 切换，避免模型相关差异在系统里四处扩散。