URL: /advanced/architecture

---
title: 架构说明
description: Zapmyco 项目的架构设计和技术决策
---

## 架构概览

```mermaid
graph TB
    subgraph Source["源代码 (src/)"]
        main["main.rs<br/>二进制入口"]
        lib["lib.rs<br/>库入口"]
        cli["cli.rs<br/>CLI 定义 & 路由"]
        agent["agent.rs<br/>AI Agent"]
        output["output/<br/>输出总线"]
        models["models.rs<br/>模型注册表"]
        settings["settings.rs<br/>配置管理"]
    end

    subgraph Quality["代码质量"]
        fmt["cargo fmt<br/>格式化"]
        clippy["cargo clippy<br/>Lint"]
        test["cargo test<br/>测试"]
    end

    subgraph Release["发布流程"]
        crates_io["crates.io"]
        gh_release["GitHub Release"]
        binaries["多平台二进制<br/>(交叉编译)"]
    end

    main --> cli
    cli --> agent
    agent --> output
    agent --> models
    agent --> settings
    output --> main
    output --> cli
    Source --> Quality
    Quality --> Release
    Release --> gh_release
    gh_release --> crates_io
    gh_release --> binaries
```

## 目录结构

```
zapmyco/
├── Cargo.toml              # Rust 项目配置和依赖管理
├── .github/workflows/
│   ├── ci.yml              # Rust CI (fmt + clippy + test + build)
│   └── release.yml         # 发布流水线
├── src/
│   ├── main.rs             # 二进制入口
│   ├── lib.rs              # 库入口
│   ├── cli.rs              # clap CLI 定义
│   ├── agent.rs            # AiAgent（Anthropic API 封装）
│   ├── output/             # 统一输出总线（Message、Router、Target）
│   │   ├── mod.rs          # 核心类型 + Router + 全局单例
│   │   ├── terminal.rs     # TerminalTarget（终端渲染）
│   │   └── log.rs          # LogTarget（日志持久化 + ANSI 剥离）
│   ├── models.rs           # 10 个内置模型注册表
│   └── settings.rs         # ~/.zapmyco/settings.toml 管理
├── tests/
│   └── integration_test.rs # 集成测试 (wiremock)
└── AGENTS.md               # AI 辅助开发上下文
```

## 技术决策

### 为什么选择 Rust？

- **零成本抽象** — 无运行时开销，单二进制文件约 5-10MB
- **内存安全** — 编译器保证内存安全，无需 GC
- **跨平台编译** — 原生支持 5 平台交叉编译
- **丰富生态** — clap（CLI）、tokio（异步）、serde（序列化）等成熟库

### 为什么使用 anthropic-ai-sdk？

- **兼容 Anthropic API** — DeepSeek 和 GLM 都提供 Anthropic 兼容接口
- **流式支持** — 原生支持 SSE 流式解析
- **自定义 endpoint** — `with_api_base_url()` 可对接任意兼容服务

## 核心模块

### CLI 入口（`src/main.rs`）

基于 clap 的命令行参数解析，路由到对应子命令处理函数。

### AiAgent（`src/agent.rs`）

AI 对话核心模块，封装 `anthropic-ai-sdk`：

- `chat()` — 非流式对话
- `chat_stream()` — 流式对话（SSE 事件解析）

配置解析链：`options` > `settings.toml` > 环境变量

### 配置管理（`src/settings.rs`）

管理 `~/.zapmyco/settings.toml`：

- 旧版格式（扁平 apiKey/baseURL/model）→ 新版格式（providers/models）自动迁移
- `${env.VAR}` 环境变量引用解析
- API Key 脱敏显示

### 模型注册表（`src/models.rs`）

内置 10 个模型，含供应商、baseURL、上下文窗口、max tokens 信息。

### 输出系统 / Output Bus（`src/output/`）

基于 **发布-订阅模式** 的统一输出基础设施，管理所有终端渲染和日志持久化。详见[输出系统详解](/advanced/output-system)。

## 构建与发布

详见[发布流程](/advanced/release-flow)。