servex
servex 是一个面向 AI 应用的 Go 微服务开发工具包。它把模型访问、AI 网关、鉴权、计费、限流、缓存、MCP 工具、可观测性、脚手架和部署治理收敛到同一套 Go 微服务体系中；Eino、ADK 等 Agent/Workflow 框架通过 adapter 接入，而不是反过来主导 servex 的包边界。
当前 v2 主线中，servex 的公共 API 按稳定性分层：核心包承诺长期兼容；重依赖和框架适配器按需导入；历史工具包和业务组件不再进入核心叙事，避免把通用工具库、业务中台组件和微服务框架绑成一个不可维护的公共面。
发布状态
当前 v2 主线正在进行破坏性 API 整理。仓库已经提供明确的发布门槛和迁移说明：
发布候选至少需要通过：
just check
just check-workspace
just vuln
CI 会对 go.work 中的根模块、CLI、LLM adapters 和 testx/container 分别执行 test、vet、build 和 govulncheck。
定位
servex 解决的是 AI 应用生产化接入问题：
- 把 OpenAI、Anthropic、Gemini、DeepSeek、Ollama、Bedrock 等模型后端统一成 Go 接口。
- 用 middleware、router、gateway、apikey、billing、cache、prompt、mcp、observability 等组件承接生产治理。
- 通过
llm/adapter/eino 和 llm/adapter/adk 把 Go Agent 框架接入 servex LLM facade。
- 用 CLI 生成传统微服务和 AI service 骨架，保持 monorepo、DDD、HTTP/gRPC、配置和部署结构一致。
- 保留 Go 微服务基础设施能力：transport、discovery、config、auth、storage、messaging、observability、testx。
servex 不在根 module 里复刻以下运行时：
- Agent planning runtime
- Graph workflow scheduler
- RAG framework
- Long-term memory engine
- Multi-agent conversation framework
- Evaluation platform
这些能力通过 llm/adapter/*、llm/mcp 和业务层显式接入。servex 的职责是把 AI 应用稳定地纳入 Go 服务、网关和微服务治理体系，同时保持根 module 的依赖面可控。
安装
go get github.com/Tsukikage7/servex/v2
License
servex is released under the MIT License.
AI 应用快速开始
创建一个最小 AI service：
go install github.com/Tsukikage7/servex/v2/cmd/servex@latest
servex new ai-service assistant --module github.com/example/assistant --provider openai --framework eino
cd assistant
go mod tidy
OPENAI_API_KEY=sk-... just dev
生成的服务包含：
internal/llm：模型 Provider 初始化。internal/agent：业务 Agent 边界，不内置复杂 runtime。internal/tools：业务工具定义入口。internal/http：POST /chat HTTP 接口，复用 transport/response 和 i18n 错误输出。configs/config.yaml：Provider、model、timeout 等配置。
完整示例见 examples/ai-support。
API 分层
servex 的基础包默认只暴露抽象和轻量实现，Redis、Consul、etcd、Nacos、Kafka、RabbitMQ、GORM、gRPC adapter、testcontainers 等重依赖放在子包中按需导入。
稳定核心
| 能力 | 包 |
|---|
| 应用生命周期 | app |
| Endpoint 抽象 | endpoint |
| 错误模型 | errors、errors/grpcx |
| 编解码 | encoding、encoding/json、encoding/proto、encoding/xml、encoding/pbjson |
| 配置 | config、config/source/* |
| 服务发现抽象 | discovery |
| HTTP/gRPC 服务 | transport/httpserver、transport/grpcserver、transport/gateway |
| HTTP/gRPC 客户端 | transport/httpclient、transport/grpcclient |
| 健康检查 | transport/health |
| 常用中间件 | middleware/recovery、logging、timeout、retry、ratelimit、circuitbreaker、cors |
| 认证 | auth、auth/jwt、auth/apikey、auth/rbac |
| 可观测性 | observability/logger、observability/metrics、observability/tracing |
| 存储抽象 | storage/cache、storage/rdbms |
| 消息抽象 | messaging/pubsub、messaging/jobqueue |
| 领域模式 | domain、domain/cqrs、domain/outbox、domain/saga、domain/eventsourcing |
| LLM facade | llm、llm/provider/*、llm/gateway、llm/mcp |
按需扩展
| 能力 | 基础包 | 按需子包 |
|---|
| 错误模型 | errors | errors/grpcx |
| 认证抽象 | auth | auth/grpcx |
| JWT | auth/jwt | auth/jwt/grpcx |
| 通知 | notify | notify/jobqueuex |
| 缓存 | storage/cache | storage/cache/redis |
| 服务发现 | discovery | discovery/consul、discovery/etcd、discovery/nacos |
| Pub/Sub 工厂 | messaging/pubsub/factory | messaging/pubsub/factory/redis、kafka、rabbitmq |
| 分页/排序 | xutil/pagination、xutil/sorting | xutil/pagination/gorm、xutil/sorting/gorm |
| 测试工具 | testx | testx/grpcx、testx/container |
非核心历史包
xutil/*、collections/* 和 bizx/* 是历史扩展能力，不再作为 servex 核心 API 叙事的一部分。新代码应优先依赖稳定核心包；确实需要通用工具或业务组件时，在应用层显式选择并承担对应依赖，而不是把它们当成微服务框架基础能力。
使用 Config 工厂时，provider 子包通过 blank import 注册：
import (
"github.com/Tsukikage7/servex/v2/discovery"
_ "github.com/Tsukikage7/servex/v2/discovery/consul"
)
本仓库用 just deps-check 固化这些边界，防止基础包重新引入未使用的重依赖。
Claude Code Plugin
servex 内置 Claude Code Plugin，为 AI 辅助开发提供模块使用指南、代码生成规范和最佳实践。
安装插件：
# 1. 添加 servex marketplace
/plugin marketplace add Tsukikage7/servex
Tsukikage7
JuliusBrussee
anthropics
wshobson
thedotmack
coreyhaines31
Lucklyric