概念¶
本节提供关于 clinvoker 架构、设计决策和系统组件的全面技术文档。无论您是希望贡献代码的开发者、评估系统的架构师,还是寻求深入理解的用户,这些文档都会解释 clinvoker 设计背后的"是什么"和"为什么"。
本节内容¶
概念部分按主题组织,逐步帮助您理解系统:
- 架构概述:高级系统设计和组件交互
- 后端系统:不同的 AI CLI 如何统一在通用抽象之下
- 会话系统:跨进程会话持久化和管理
- API 设计:REST API 架构和 SDK 兼容层
- 设计决策:关键架构选择背后的原理
- 贡献指南:开发指南和项目结构
- 故障排除:常见问题和诊断方法
- FAQ:涵盖所有方面的常见问题
架构文档¶
-
架构概述
clinvoker 系统架构、组件和数据流的高级视图。包括 CLI 层、核心服务和后端交互的详细图表。
-
后端系统
深入了解后端抽象层、注册表模式、线程安全设计,以及 Claude Code、Codex CLI 和 Gemini CLI 如何统一在通用接口下。
-
会话系统
会话持久化机制、原子写操作、跨进程文件锁定、内存元数据索引和生命周期管理。
-
API 设计
REST API 架构、OpenAI 和 Anthropic 兼容层、端点路由、中间件栈和请求/响应转换。
-
设计决策
关键架构选择背后的原理,包括语言选择、框架决策、SDK 兼容性方法和并发模型。
系统概述¶
flowchart TB
subgraph 客户端["客户端层"]
CLI[CLI 用户]
SDK[SDK 客户端<br/>OpenAI/Anthropic]
HTTP[HTTP 客户端<br/>curl/LangChain]
end
subgraph clinvk["clinvk 核心层"]
direction TB
subgraph CLI_Layer["CLI 层 (cmd/clinvk)"]
COBRA[Cobra 框架]
FLAGS[标志解析]
CMD[命令分发]
end
subgraph Core_Services["核心服务 (internal/)"]
API[API 层]
EXEC[执行器]
SESSION[会话管理器]
CONFIG[配置管理器]
end
end
subgraph 后端["后端层"]
CL[Claude Code]
CO[Codex CLI]
GM[Gemini CLI]
end
subgraph 存储["存储层"]
DISC[磁盘会话<br/>~/.clinvk/sessions/]
CONFIG_FILE[配置文件<br/>~/.clinvk/config.yaml]
end
CLI --> COBRA
SDK --> API
HTTP --> API
COBRA --> FLAGS
FLAGS --> CMD
CMD --> EXEC
API --> EXEC
EXEC --> SESSION
EXEC --> CONFIG
EXEC --> CL
EXEC --> CO
EXEC --> GM
SESSION --> DISC
CONFIG --> CONFIG_FILE
关键组件¶
CLI 应用 (cmd/clinvk/main.go)¶
主入口点有意保持简洁,将所有功能委托给 internal/app 包:
这种设计遵循关注点分离原则:
- cmd/:仅包含入口点和构建特定代码
- internal/app/:包含使用 Cobra 的所有 CLI 命令实现
- internal/:包含按领域组织的所有业务逻辑
内部包结构¶
| 包 | 用途 | 关键文件 |
|---|---|---|
app/ |
使用 Cobra 的 CLI 命令实现 | app.go, cmd_*.go, execute.go |
backend/ |
后端抽象和实现 | backend.go, registry.go, claude.go, codex.go, gemini.go, unified.go |
config/ |
使用 Viper 的配置管理 | config.go, validate.go |
executor/ |
命令执行和输出处理 | executor.go, signal.go |
output/ |
输出格式化和流式传输 | parser.go, writer.go, event.go |
server/ |
HTTP API 服务器 | server.go, routes.go, handlers/, middleware/, service/ |
session/ |
会话持久化和管理 | session.go, store.go, filelock.go |
auth/ |
API 密钥管理 | keystore.go |
metrics/ |
Prometheus 指标 | metrics.go |
resilience/ |
熔断器模式 | circuitbreaker.go |
设计原则¶
1. 后端无关性¶
所有 AI CLI 都抽象在通用的 Backend 接口后面(internal/backend/backend.go:16-46),实现:
- 无需代码更改即可在后端之间无缝切换
- 跨不同 AI 提供商的并行执行
- 适用于任何后端的简化客户端代码
- 无需修改核心逻辑即可轻松添加新后端
2. 会话持久化¶
会话通过跨进程同步持久化到磁盘:
- 原子写入:所有会话写入使用原子文件操作(
internal/session/store.go:1109-1152) - 文件锁定:跨进程文件锁防止并发修改(
internal/session/filelock.go) - 元数据索引:内存索引实现快速列表而无需加载所有会话
- JSON 格式:人类可读、版本控制的存储格式
3. 流式支持¶
长时间运行任务的实时输出:
- 用于 HTTP 流式传输的服务器发送事件 (SSE)
- 用于 CLI 的流式 JSON 输出格式
- 基于事件的架构实现渐进式结果
4. SDK 兼容性¶
OpenAI 和 Anthropic API 的即插即用替代:
- 与 OpenAI SDK 兼容的
/openai/v1/*端点 - 与 Anthropic SDK 兼容的
/anthropic/v1/*端点 - 用于 clinvoker 特定功能的原生
/api/v1/*端点
5. 可扩展性¶
为轻松扩展而设计:
- 新后端:实现
Backend接口并在注册表中注册 - 新命令:在
internal/app/中添加 Cobra 子命令 - 新 API 端点:使用 Huma 注册处理程序
- 中间件:用于横切关注点的 Chi 中间件链
并发模式¶
clinvoker 在整个代码库中使用多种并发模式:
注册表线程安全¶
后端注册表使用 sync.RWMutex 实现安全的并发访问(internal/backend/registry.go:12-16):
type Registry struct {
mu sync.RWMutex
backends map[string]Backend
availabilityCache map[string]*cachedAvailability
availabilityCacheTTL time.Duration
}
会话存储并发¶
会话存储结合了内存锁和跨进程文件锁(internal/session/store.go:41-48):
type Store struct {
mu sync.RWMutex // 内存锁
dir string
index map[string]*SessionMeta
fileLock *FileLock // 跨进程锁
}
HTTP 服务器并发¶
HTTP 服务器使用 Chi 的内置并发处理和可配置超时(internal/server/server.go:204-211)。