Skip to content

index.md

Latest commit

 

History

History
309 lines (232 loc) · 8.87 KB

index.md

File metadata and controls

309 lines (232 loc) · 8.87 KB

Blade 架构设计文档

核心理念

blade = LLMs + System Prompt + Context + Tools

Blade 是一个 AI 原生的 CLI Agent，充分利用 LLM 的能力来提供智能化的命令行体验。

工作流程

  1. 构建 Prompt: 将系统提示（定义 Blade 的角色、能力、工具用法）、收集到的上下文、以及用户指令组合成一个完整的 Prompt。
  2. LLM 交互: 将完整 Prompt 发送给配置的 LLM API。
  3. LLM 推理与规划: LLM 理解需求，进行思考和规划。它可能直接生成回答，或者决定调用一个或多个工具来完成任务。
  4. 工具执行: 根据 LLM 的决策，执行相应的工具调用。
  5. 循环或响应: LLM 根据工具结果继续推理，可能进行更多工具调用，或生成最终的响应。
  6. 安全确认: 集中处理危险操作的用户确认逻辑。

架构概览

Blade 采用现代化的 Monorepo 分层架构 设计：

packages/
├── cli/             # 用户界面层 (CLI 包)
│   ├── src/contexts/ # 会话状态管理
│   ├── src/config/   # CLI 配置管理
│   ├── src/services/ # 业务流程编排
│   ├── src/components/ # 终端 UI 组件
│   └── tests/        # E2E 测试
└── core/             # 核心业务层 (@blade-ai/core)
    ├── src/agent/    # Agent 核心组件系统
    ├── src/config/   # 统一配置系统
    ├── src/context/  # 上下文管理系统
    ├── src/llm/      # LLM 提供商实现
    ├── src/mcp/      # MCP 协议支持
    ├── src/services/ # 核心业务服务
    ├── src/tools/    # 工具系统
    ├── src/telemetry/ # 遥测系统
    ├── src/types/    # 共享类型定义
    ├── src/utils/    # 通用工具函数
    ├── tests/        # 单元测试和集成测试
    └── dist/         # 编译输出

分层设计

CLI 层 (应用层)

职责: 处理用户交互和界面展示，作为纯粹的应用层

主要组件:

  • REPL 界面: 基于 React 和 Ink 构建的会话式终端界面
  • 会话管理: 使用 Zustand 管理全局状态，实现单一数据源
  • 配置服务: 通过 @blade-ai/core 包加载和管理配置
  • 流程编排: 命令解析、执行编排和结果展示

Core 层 (核心业务层)

职责: 提供独立的、可重用的核心功能和服务

主要组件:

  • Agent 核心: 统一的 AI Agent 入口点，嵌入 LLM 能力
  • 配置系统: 纯函数式的分层配置合并和验证系统
  • 工具系统: 25+ 内置工具和智能工具
  • 核心服务: 文件系统、Git、聊天记录等核心服务
  • LLM 管理: 多提供商 LLM 实现
  • 上下文管理: 会话上下文和内存管理
  • MCP 支持: Model Context Protocol 协议支持
  • 遥测系统: 使用数据收集和分析

详细架构说明

1. Agent 架构

Blade 的核心是 Agent 类，它将 LLM 能力直接嵌入而不是作为外部组件：

Agent = LLMs + System Prompt + Context + Tools

核心特性:

  • Agent-as-Entry-Point 模式: Agent 类是单一入口点，协调 LLM、工具和上下文管理
  • 组件化系统: LLMManager、ToolComponent、ContextComponent 等模块化组件
  • 内置 LLM 支持: QwenLLM 和 VolcEngineLLM 实现直接集成
  • 工具注册机制: 组件向 Agent 注册而不是相反

2. 工具系统

架构特点:

  • 模块化组织: 按功能领域组织工具（Git、文件系统、网络等）
  • 智能工具: LLM 驱动的代码审查、文档生成等高级工具
  • 安全确认: 统一的危险操作确认机制
  • 性能优化: 异步执行和并发控制

工具分类:

  • Git 工具: 状态查看、提交、分支管理等 (7个)
  • 文件系统工具: 读写文件、目录操作等 (4个)
  • 网络工具: HTTP 请求、URL 处理等 (4个)
  • 文本处理工具: 搜索、替换、格式化等 (4个)
  • 实用工具: 时间戳、UUID、Base64 等 (6个)
  • 智能工具: 代码审查、文档生成、智能提交等 (3个)

3. 状态管理系统

Blade 使用 Zustand 实现了高效、可扩展的状态管理系统，提供单一数据源和统一的状态操作入口。

核心功能:

  • 单一数据源: 使用 Zustand 实现统一的内存状态管理
  • React 集成: 提供 useBladeStore Hook 供 React 组件订阅
  • 非 React 支持: 提供 vanillaStore 供 Agent 和服务层使用
  • 持久化同步: 自动将配置变更同步到磁盘
  • 防御性初始化: 确保状态在任何环境下都可用

详细文档: 请参考 状态管理系统 文档了解完整实现细节、API 参考和最佳实践。

4. 配置管理系统

架构特点:

  • 统一数据源: 配置存储在 Zustand Store 中，确保内存状态与持久化数据一致性
  • 分层配置加载: 环境变量 > 配置文件 > 命令行参数 > 默认值
  • 自动持久化: 通过 configActions() 自动同步配置变更到磁盘
  • 范围控制: 支持全局配置和项目级配置

核心组件:

  • ConfigStore: Zustand Store 中的配置切片
  • ConfigService: 封装配置持久化逻辑
  • ConfigManager: 底层配置加载和合并机制
  • PermissionChecker: 权限规则验证和检查

配置操作:

// 读取配置
import { getCurrentModel, getAllModels } from '../store/vanilla.js';

const currentModel = getCurrentModel();
const allModels = getAllModels();

// 写入配置（自动同步）
import { configActions } from '../store/vanilla.js';

// 更新全局配置
await configActions().updateConfig({ temperature: 0.7 });

// 添加模型
await configActions().addModel({
  id: 'gpt-4',
  name: 'GPT-4',
  apiKey: 'sk-...',
  provider: 'openai'
});

// 管理权限规则
await configActions().appendPermissionAllowRule('rm -rf *');

5. 安全架构

多层安全机制:

  • 权限控制: 基于角色的访问控制
  • 路径安全: 文件系统路径验证和限制
  • 命令确认: 危险操作的用户确认机制
  • 输入验证: 严格的输入参数检查
  • 沙箱机制: 安全的命令执行环境

6. 性能优化

优化策略:

  • 缓存机制: 文件内容、Git 状态等多层缓存
  • 并发执行: 工具调用的并行处理
  • 内存管理: 智能垃圾回收和内存优化
  • 响应式设计: 异步 UI 更新和流式输出

核心服务详解

文件系统服务

主要功能:

  • 完整的文件读写操作
  • 目录遍历和搜索
  • 权限检查和安全控制
  • 缓存机制和性能优化

Git 服务

主要功能:

  • 完整的 Git 操作封装
  • 状态检查和变更跟踪
  • 分支管理和合并操作
  • 日志查看和差异比较

聊天记录服务

主要功能:

  • 聊天记录的录制和回放
  • 消息存储和检索
  • 导出和导入功能
  • 搜索和过滤支持

IDE 集成服务

主要功能:

  • 多种 IDE 检测支持
  • 实时通信和消息传递
  • 项目上下文管理
  • 安装和配置管理

MCP 协议服务

主要功能:

  • MCP 客户端和服务器实现
  • 工具调用和资源访问
  • OAuth 认证和令牌管理
  • 服务器发现和连接管理

扩展性设计

插件系统

扩展点:

  • 工具插件: 自定义工具注册和管理
  • UI 插件: 组件和主题扩展
  • 服务插件: 核心服务扩展
  • 协议插件: 通信协议扩展

MCP 扩展

外部集成:

  • 工具发现: 动态工具加载和注册
  • 资源访问: 外部资源访问接口
  • 协议兼容: 标准化协议支持
  • 性能优化: 远程调用优化

测试架构

测试策略

单元测试 (70%) → 集成测试 (20%) → E2E 测试 (10%)

测试覆盖

  • CLI 包: 组件、Hooks、服务测试
  • Core 包: 核心引擎、工具、服务测试
  • 集成测试: 模块间协作测试
  • 端到端测试: 完整用户流程测试

部署和运维

构建流程

源码 → TypeScript 编译 → 代码检查 → 单元测试 → 构建打包 → 发布

监控和日志

遥测数据:

  • 功能使用统计
  • 性能指标收集
  • 错误和异常追踪
  • 用户行为分析

日志系统:

  • 多级别日志记录
  • 结构化日志输出
  • 远程日志收集
  • 日志搜索和分析

未来发展方向

短期目标

  1. 功能完善

    • 更多智能工具开发
    • 高级配置选项
    • 完善的文档系统
    • 更好的错误处理

  2. 性能优化

    • 启动速度优化
    • 内存使用优化
    • 响应速度提升
    • 并发性能改进

长期规划

  1. 平台扩展

    • Web 界面支持
    • 移动端应用
    • 桌面应用
    • IDE 插件

  2. AI 能力增强

    • 多模型支持
    • 自适应学习
    • 知识库构建
    • 推理能力提升

  3. 生态系统建设

    • 插件市场
    • 社区贡献
    • 企业版功能
    • 云服务集成