feat: add aiprovider service foundation

README.md

@@ -184,6 +184,11 @@
 ## 快速启动
 
 ```bash
+# 新机器首次初始化
+./scripts/bootstrap-dev.sh
+# 会自动安装/检查 uv、bun，并同步 Python/前端依赖
+# 会在缺少时生成 backend/.env、aiprovider/.env、frontend/.env.local
+
 # 启动前后端服务
 ./planet.sh start
 
@@ -204,6 +209,84 @@
 
 启动服务后访问: `http://localhost:8000/docs`
 
+## AI 接口预留
+
+项目现在采用“两层”设计:
+
+- 主后端暴露稳定业务接口: `GET /api/v1/ai/provider/status`、`POST /api/v1/ai/situational-awareness/analyze`
+- 独立 `aiprovider` 服务负责适配具体模型供应商
+
+这样前端和业务代码不直接依赖 OpenAI、本地模型网关或其他订阅服务，后续切换部署方式只需要调整环境变量。
+
+主后端建议配置:
+
+```env
+AI_PROVIDER_SERVICE_URL=http://localhost:8010
+AI_PROVIDER_SERVICE_TOKEN=change_me
+AI_PROVIDER_TIMEOUT_SECONDS=60
+```
+
+`aiprovider` 服务建议配置:
+
+```env
+AI_PROVIDER=openai_compatible
+AI_BASE_URL=https://api.openai.com/v1
+AI_API_KEY=your_api_key
+AI_MODEL=gpt-4o-mini
+AI_TIMEOUT_SECONDS=60
+AI_PROVIDER_SERVICE_TOKEN=change_me
+```
+
+OpenAI 兼容场景推荐使用:
+
+- `AI_PROVIDER=openai_compatible`
+
+Claude 兼容场景推荐使用:
+
+- `AI_PROVIDER=anthropic`
+- `AI_PROVIDER=anthropic_compatible`
+- `AI_PROVIDER=claude_compatible`
+
+Ollama 原生场景推荐使用:
+
+- `AI_PROVIDER=ollama`
+
+比如 MiniMax 或其他 Claude 兼容网关，可以这样配置:
+
+```env
+AI_PROVIDER=claude_compatible
+AI_BASE_URL=https://your-claude-compatible-endpoint.example.com
+AI_API_KEY=your_api_key
+AI_MODEL=your-claude-compatible-model
+AI_TIMEOUT_SECONDS=60
+AI_MAX_TOKENS=1200
+AI_ANTHROPIC_VERSION=2023-06-01
+AI_PROVIDER_SERVICE_TOKEN=change_me
+```
+
+如果你要本地直接起模型适配层，项目里已经补了模板:
+
+- [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)
+- [docker-compose.local-model.yml](/home/ray/dev/linkong/planet/docker-compose.local-model.yml)
+
+推荐映射关系:
+
+- `vLLM` / `LM Studio` / `One API`: `AI_PROVIDER=openai_compatible`
+- `MiniMax` / Claude 兼容网关: `AI_PROVIDER=claude_compatible`
+- `Ollama`: `AI_PROVIDER=ollama`
+
+运行与调用补充:
+
+- `./planet.sh start` 默认会启动 `aiprovider`
+- 其他服务优先调用主后端 `POST /api/v1/ai/situational-awareness/analyze`
+- `backend -> aiprovider` 会透传 `X-Request-ID`
+- `backend -> aiprovider` 与 `aiprovider -> 模型供应商` 都带轻量重试
+
+详细文档:
+
+- [docs/aiprovider.md](/home/ray/dev/linkong/planet/docs/aiprovider.md)
+- [aiprovider/README.md](/home/ray/dev/linkong/planet/aiprovider/README.md)
+
 ## License
 
 待定