跳转至

概念

本节提供关于 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 包:

func main() {
    if err := app.Execute(); err != nil {
        os.Exit(1)
    }
}

这种设计遵循关注点分离原则:

  • 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)。

相关文档

  • 指南 - 使用 clinvoker 的实用操作指南
  • 教程 - 分步学习材料
  • 参考 - API 和 CLI 参考文档
  • 贡献指南 - 开发设置和贡献指南