Krebs

一个精简、模块化的 AI Agent 框架

架构评分: 8.75/10 ⭐ | 最新版本: v1.0.0

📋 项目简介

Krebs 是一个轻量级、高度模块化的 AI Agent 框架，专注于提供清晰、可扩展的智能体运行时。

核心特性：

🎯 职责分离：Orchestrator 层专门负责技能调度
🔌 依赖注入：完全符合 SOLID 原则
💾 可插拔存储：支持多种存储实现
🚦 智能调度：Lane 队列系统实现并发控制
🛠️ 技能系统：可扩展的技能框架

架构优势：

✅ 高模块化（9/10）
✅ 高可扩展性（9/10）
✅ 高可测试性（8/10）
✅ 易维护性（9/10）

🏗️ 架构设计

架构层次（2026-02-04 更新）

┌─────────────────────────────────────────┐
│           Gateway Layer                 │
│  HTTP/WebSocket + ChatService Interface │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│        Orchestrator Layer 🆕            │
│     (Skill Dispatch & Routing)          │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           Agent Layer                   │
│  (LLM Processing + History Management)  │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Provider Layer                  │
│  (Anthropic, OpenAI, DeepSeek)          │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│         Storage Layer                   │
│  (ISessionStorage Interface)            │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│        Lane Scheduler                   │
│  (Command Queue + Concurrency Control)  │
└─────────────────────────────────────────┘

新架构亮点

🎯 Orchestrator 层

职责分离：

Agent：专注 LLM 对话管理
Orchestrator：负责技能调度和编排

// 技能触发和调度
const orchestrator = agentManager.getOrchestrator("my-agent");
const result = await orchestrator.process(userMessage, sessionId);

🔌 依赖注入

移除全局单例：

❌ 之前：globalSkillRegistry
✅ 现在：AgentManager 管理，可注入

const agentManager = new AgentManager(
  { enableSkills: true },
  { provider, storage, skillRegistry },
);

💾 Storage 接口化

支持多种存储：

✅ Markdown 文件存储（默认）
✅ 数据库存储（可扩展）
✅ Redis 缓存（可扩展）

interface ISessionStorage {
  saveSession(sessionId: string, messages: Message[]): Promise<void>;
  loadSession(sessionId: string): Promise<Message[] | null>;
}

📚 核心层次

1. Gateway 层 (`src/gateway/`)

服务接口：IChatService - 解耦 Gateway 和 Agent
HTTP 服务器：REST API 接口
WebSocket 服务器：实时双向通信
协议定义：统一的请求/响应格式

2. Agent 层 (`src/agent/`)

Core (`src/agent/core/`)

Agent：LLM 对话管理（196 行）
Orchestrator 🆕：技能调度和编排（282 行）
AgentManager：依赖管理和生命周期（187 行）

Skills (`src/agent/skills/`)

SkillsManager 🆕：技能管理器（Facade 模式）
- 多目录加载（Extra、Bundled、Managed、Workspace）
- 技能安装和状态检查
- Hot Reload 支持
SkillsLoader 🆕：技能加载器
- 从多个目录加载技能
- 优先级合并（高优先级覆盖低优先级）
- 解析 frontmatter 和 install specs
SkillInstaller 🆕：技能安装器
- 支持 8 种安装类型（brew、node、go、uv、download、python、ruby、cargo、bash）
- 自动检测已安装依赖
- Dry-run 模式预览
CLI 命令 🆕：
- skills create - 创建新技能目录
- skills add - 添加技能（目录、文件、URL）
- skills remove - 移除技能
- skills package - 打包技能
- skills list/status/install - 查看和安装技能

3. Provider 层 (`src/provider/`)

基础接口：LLMProvider 抽象
DeepSeek：默认 Provider，性价比高
Anthropic：Claude 模型支持
OpenAI：GPT 模型支持

4. Storage 层 (`src/storage/`)

接口定义 🆕：ISessionStorage
Markdown 存储：会话和文档管理
Frontmatter 支持：元数据管理
可插拔：支持自定义存储实现

5. Lane 调度系统 (`src/scheduler/`)

命令队列：异步任务调度
并发控制：Lane 隔离和限流
自动监控：任务等待时间警告

🚀 快速开始

安装依赖

npm install

配置环境变量

复制 .env.example 到 .env 并配置：

cp .env.example .env

必需的配置：

# 默认使用 DeepSeek（推荐）

DEEPSEEK_API_KEY=your_deepseek_key

# 可选：配置其他 Provider

ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key

DeepSeek 获取 API Key：

访问 DeepSeek 开放平台
注册并创建 API Key
复制到 .env 文件的 DEEPSEEK_API_KEY

启动服务

npm run dev

输出：

██████╗██╗ ██╗██████╗ ███████╗██████╗
██╔════╝██║ ██║██╔══██╗██╔════╝██╔══██╗
██║ ██║ ██║██║ ██║█████╗ ██████╔╝
██║ ██║ ██║██║ ██║██╔══╝ ██╔══██╗
╚██████╗╚██████╔╝██████╔╝███████╗██║ ██║
╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝
中文版 AI Agent 框架 v1.0.0

✅ krebs CN 启动成功！
HTTP: http://localhost:3000
WebSocket: ws://localhost:3001

构建

npm run build

🛠️ CLI 命令

Krebs 提供了完整的命令行界面（CLI），用于管理 Skills 和查看系统状态。

基本用法

krebs <命令> [选项]

可用命令

帮助命令

krebs help           # 显示帮助信息
krebs --help         # 同上
krebs -h             # 同上

krebs version        # 显示版本信息
krebs --version      # 同上
krebs -v             # 同上

Skills 命令

# ========== 技能管理 ==========

# 创建新技能
krebs skills create <name> [选项]

# 添加技能（从目录、.skill.gz 或 URL）
krebs skills add <source> [选项]

# 移除技能
krebs skills remove <name> [选项]

# 打包技能为 .skill.gz
krebs skills package <path>

# ========== 技能查看和安装 ==========

# 列出所有技能
# 验证 skills 格式（新增）
krebs validate:skills                 # 验证 skills/bundled 目录
krebs validate:skills <custom-dir>   # 验证自定义目录

krebs skills list

# 仅列出有安装规范的技能
krebs skills list --install

# 查看技能安装状态
krebs skills status <技能名>

# 安装单个技能的依赖
krebs skills install <技能名>

# 安装所有技能的依赖
krebs skills install --all

# 仅检查安装状态，不实际安装
krebs skills install <技能名> --check

# 预览将要安装的内容
krebs skills install <技能名> --dry-run

# 强制重新安装
krebs skills install <技能名> --force

命令示例

技能管理示例

# 创建新技能（带示例文件）
krebs skills create my-skill --resources scripts,references --examples

# 从本地目录添加技能
krebs skills add ./my-skill

# 从 .skill.gz 文件添加技能
krebs skills add ./my-skill.skill.gz

# 从 URL 下载并添加技能
krebs skills add https://example.com/skills/my-skill.skill.gz

# 添加到 workspace 目录
krebs skills add ./my-skill --target=workspace

# 添加并自动安装依赖
krebs skills add ./my-skill --install

# 强制覆盖已存在的技能
krebs skills add ./my-skill --force

# 移除技能（带确认提示）
krebs skills remove my-skill

# 强制移除技能（跳过确认）
krebs skills remove my-skill --force

# 从特定目录移除技能
krebs skills remove my-skill --target=managed

# 打包技能
krebs skills package skills/bundled/my-skill

技能安装和查看示例

# 查看 test-install 技能的状态
krebs skills status test-install

# 安装 test-install 技能的依赖
krebs skills install test-install

# 预览将要安装的内容
krebs skills install test-install --dry-run

# 安装所有技能的依赖
krebs skills install --all

# 查看所有有安装规范的技能
krebs skills list --install

命令选项说明

Skills Add 选项

选项	说明
`--target=<dir>`	目标目录：`managed` 或 `workspace`（默认：managed）
`--install`	添加后自动安装依赖
`--force`	强制覆盖已存在的技能

Skills Remove 选项

选项	说明
`--target=<dir>`	目标目录：`managed` 或 `workspace`（默认：自动检测）
`--force`	跳过确认提示

Skills Create 选项

选项	说明
`--path=<dir>`	输出目录（默认：skills/bundled/）
`--resources=<list>`	逗号分隔的资源列表：scripts,references,assets
`--examples`	在资源目录中创建示例文件

Skills Install 选项

选项	说明
`--all`	安装所有技能的依赖
`--check`	仅检查安装状态，不实际安装
`--dry-run`	预览将要执行的操作
`--force`	强制重新安装

Skills List 选项

选项	说明
`--install`	仅列出有安装规范的技能

📦 Skills 依赖安装

Krebs 支持自动安装 Skill 依赖的功能。当 Skill 的 frontmatter 中定义了 install 字段时，系统可以自动安装所需的依赖。

支持的安装类型

1. Node.js 包

---
install:
  - kind: node
    npmPackage: prettyping
    label: "Prettyping - 美化ping输出"
    bins:
      - prettyping
---

支持的包管理器（自动检测）：npm、pnpm、yarn、bun

2. Homebrew Formula

---
install:
  - kind: brew
    formula: ffmpeg
    label: "FFmpeg 多媒体处理工具"
---

3. Go 模块

---
install:
  - kind: go
    goModule: github.com/golangci/golangci-lint/cmd/golangci-lint@latest
    label: "Go 代码检查工具"
    bins:
      - golangci-lint
---

4. Python 包 🆕

---
install:
  - kind: python
    pythonPackage: black
    pythonInstaller: pipx  # 可选: pip, pipx, poetry, uv
    label: "Python 代码格式化工具"
    bins:
      - black
---

支持的包管理器（自动检测或手动指定）：pip、pipx、poetry、uv

5. Ruby Gem 🆕

---
install:
  - kind: ruby
    gemPackage: jekyll
    label: "Jekyll 静态网站生成器"
    bins:
      - jekyll
---

6. Cargo/Rust Crate 🆕

---
install:
  - kind: cargo
    cratePackage: ripgrep
    label: "ripgrep 快速搜索工具"
    bins:
      - rg
---

7. 下载文件

---
install:
  - kind: download
    url: https://example.com/tool.tar.gz
    extract: true
    targetDir: ./bin
    stripComponents: 1
    label: "下载并解压工具"
    bins:
      - tool
---

Install Spec 字段说明

interface SkillInstallSpec {
  // 安装类型
  kind: "node" | "brew" | "go" | "uv" | "download" | "python" | "ruby" | "cargo";

  // 可选标识符
  id?: string;              // 唯一标识
  label?: string;           // 人类可读描述

  // 可执行文件列表（用于检查安装状态）
  bins?: string[];          // 可执行文件名列表

  // 平台限制
  os?: string[];            // 限制操作系统：["darwin", "linux"]

  // 下载相关
  targetDir?: string;       // 目标目录
  extract?: boolean;        // 是否解压
  archive?: string;         // 归档类型：tar.gz, zip
  stripComponents?: number; // 解压时去掉的目录层级

  // Kind 特定字段
  formula?: string;         // brew: formula 名称
  npmPackage?: string;      // node: npm 包名
  goModule?: string;        // go: 模块路径
  uvPackage?: string;       // uv: 包名
  pythonPackage?: string;   // python 或 uv: Python 包名
  pythonInstaller?: string; // python: 安装器类型（pip/pipx/poetry/uv）
  gemPackage?: string;      // ruby: gem 包名
  cratePackage?: string;    // cargo: crate 包名
  url?: string;             // download: 下载 URL
}

安装机制

安装检查：系统首先检查依赖是否已安装
缓存机制：已安装的依赖会被缓存，避免重复安装
超时控制：每个安装操作有默认超时时间
Dry-run 模式：可以预览将要安装的内容而不实际执行

示例 Skill

---
name: VideoProcessor
description: "视频处理技能"
install:
  - kind: brew
    formula: ffmpeg
    label: "FFmpeg 多媒体处理工具"

  - kind: node
    npmPackage: @ffprobe-installer/ffprobe
    label: "FFprobe 探测工具"

  - kind: download
    url: https://example.com/video-tools.tar.gz
    extract: true
    targetDir: ./bin
    bins:
      - video-tool
---

# VideoProcessor Skill

这个技能用于视频处理和转码...

## 使用方法

```typescript
await agent.process("处理这个视频文件");


---

## 💡 API 使用示例

### 发送聊天消息

```bash
curl -X POST http://localhost:3000/api/chat \\
-H "Content-Type: application/json" \\
-d '{
"id": "test-001",
"method": "chat.send",
"params": {
"agentId": "default",
"sessionId": "session-001",
"message": "你好！"
}
}'

响应：

{
"id": "test-001",
"result": {
"response": "你好！我是 AI 助手，有什么可以帮助您的吗？",
"usage": {
"promptTokens": 20,
"completionTokens": 15,
"totalTokens": 35
}
}
}

WebSocket 流式响应

const ws = new WebSocket("ws://localhost:3001");

ws.onopen = () => {
ws.send(JSON.stringify({
id: "ws-001",
method: "chat.send",
params: {
agentId: "default",
sessionId: "session-001",
message: "写一首诗",
stream: true
}
}));
};

ws.onmessage = (event) => {
const data = JSON.parse(event.data);

if (data.type === "chat.chunk") {
console.log("Chunk:", data.data.chunk);
} else if (data.type === "chat.complete") {
console.log("Complete!");
}
};

📁 项目结构

krebs/
├── src/
│ ├── agent/ # Agent 层
│ │ ├── core/ # 核心逻辑
│ │ │ ├── agent.ts # Agent 实现（196 行）
│ │ │ ├── orchestrator.ts # Orchestrator 🆕（282 行）
│ │ │ ├── manager.ts # AgentManager（187 行）
│ │ │ └── index.ts # 模块导出
│ │ ├── skills/ # 技能系统
│ │ │ ├── base.ts # 技能接口和注册表
│ │ │ ├── builtin.ts # 内置技能
│ │ │ └── index.ts
│ │ └── tools/ # 工具系统
│ ├── gateway/ # Gateway 层
│ │ ├── service/ # 服务接口 🆕
│ │ │ └── chat-service.ts
│ │ ├── protocol/ # 协议定义
│ │ └── server/ # 服务器实现
│ │ ├── http-server.ts
│ │ └── ws-server.ts
│ ├── provider/ # Provider 层
│ │ ├── base.ts # LLMProvider 接口
│ │ ├── deepseek.ts # DeepSeek 实现
│ │ ├── anthropic.ts # Anthropic 实现
│ │ └── openai.ts # OpenAI 实现
│ ├── scheduler/ # 调度系统
│ │ └── lanes.ts # Lane 调度
│ ├── storage/ # 存储层
│ │ ├── interface.ts # 存储接口 🆕
│ │ └── markdown/ # Markdown 实现
│ ├── cli/ # CLI 命令 🆕
│ │ ├── index.ts # CLI 入口
│ │ └── commands/ # 子命令
│ │   └── skills.ts # Skills 命令
│ ├── shared/ # 共享模块
│ │ ├── config.ts # 配置管理
│ │ └── logger.ts # 日志系统
│ ├── types/ # 类型定义
│ └── index.ts # 主入口
├── docs/ # 文档目录
│ ├── architecture-analysis.md # 架构分析
│ ├── architecture-evaluation-2026-02-04.md # 架构评估 🆕
│ ├── refactor-improvements-2026-02-04.md # 重构改进 🆕
│ └── refactor-summary.md # 重构总结 🆕
├── schema/ # 任务文档
├── config/ # 配置文件
├── data/ # 数据目录
├── package.json
├── tsconfig.json
├── production.md # 项目全局文档 🆕
└── README.md

✨ 特性

核心特性

✅ Orchestrator 层 🆕 - 技能调度和编排
✅ 依赖注入 - 移除全局单例，完全符合 SOLID 原则
✅ Storage 接口化 - 支持多种存储实现
✅ Gateway 解耦 - 通过服务接口解耦
✅ 精简架构 - 专注核心功能
✅ 模块化设计 - 高内聚低耦合

功能特性

✅ 多 Provider 支持 - DeepSeek、Anthropic、OpenAI
✅ Markdown 存储 - 会话和文档管理（带 Frontmatter）
✅ 工具系统 - 可扩展的工具框架
✅ Skills 管理系统 🆕 - 完整的技能添加、移除、查看和管理
✅ 依赖自动安装 🆕 - Skills 依赖自动安装（8 种类型：brew、node、go、uv、download、python、ruby、cargo）
✅ CLI 命令 🆕 - 完整的命令行界面
✅ Lane 并发控制 - 命令队列和限流
✅ HTTP + WebSocket - 双协议支持
✅ 流式响应 - 实时流式输出
✅ 会话管理 - 完整的会话历史

质量特性

✅ 类型安全 - 完整的 TypeScript 类型
✅ 错误处理 - 优雅的错误处理和恢复
✅ 日志系统 - 结构化日志
✅ 配置管理 - 灵活的配置系统

🎯 支持的模型

DeepSeek（默认）

"deepseek-chat" // 通用对话模型
"deepseek-coder" // 代码专用模型

Anthropic Claude

"claude-3-5-sonnet-20241022"
"claude-3-5-haiku-20241022"
"claude-3-opus-20240229"

OpenAI GPT

"gpt-4o"
"gpt-4o-mini"
"gpt-4-turbo"
"gpt-3.5-turbo"

🛠️ 开发

运行开发模式

npm run dev

构建项目

npm run build

运行测试

npm test

代码检查

npm run lint # ESLint 检查
npm run format # Prettier 格式化

📖 文档

架构分析 - 原始架构分析
架构评估 - 重构后评估 🆕
重构改进 - 详细改进记录 🆕
重构总结 - 一分钟速览 🆕
项目全局文档 - 项目全局文档 🆕

📊 架构质量

维度	评分	说明
模块化	9/10	⭐⭐⭐⭐⭐ 清晰的分层设计
可扩展性	9/10	⭐⭐⭐⭐⭐ Provider/Storage 可扩展
可测试性	8/10	⭐⭐⭐⭐ 依赖注入完善
可维护性	9/10	⭐⭐⭐⭐⭐ 代码清晰，职责单一
性能	9/10	⭐⭐⭐⭐⭐ Lane 调度优秀
安全性	8/10	⭐⭐⭐⭐ 基本安全措施
综合评分	8.75/10	⭐⭐⭐⭐⭐ 优秀

SOLID 原则合规性：

✅ 单一职责（SRP）：8.7/10
✅ 开闭原则（OCP）：9.0/10
✅ 里氏替换（LSP）：9.3/10
✅ 接口隔离（ISP）：9.7/10
✅ 依赖倒置（DIP）：9.5/10

🔄 版本历史

v1.0.0 (2026-02-04) - 架构重构版 🎉

重大改进：

🆕 引入 Orchestrator 层，分离 Agent 职责
🔄 移除全局单例，改用依赖注入
🔌 Storage 接口化，支持多种实现
🌐 Gateway 通过服务接口解耦
📦 Skills 依赖自动安装功能 🆕
- 支持 npm、brew、go、uv、download、python、ruby、cargo 八种安装类型
- 自动检测已安装依赖
- Dry-run 模式预览安装
🖥️ 完整的 CLI 命令支持 🆕
- krebs skills install - 安装技能依赖
- krebs skills list - 列出技能
- krebs skills status - 查看安装状态
- 支持 --all, --check, --dry-run, --force 选项
✅ 架构评分从 7.2/10 提升至 8.75/10

详细记录：

🤝 参考

本项目学习和借鉴了以下项目的设计思想：

openclaw-cn-ds - Agent 和工具系统

📜 许可证

MIT

** Made with ❤️ by Claude Code Agent**

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.agent/workflows		.agent/workflows
.claude-code-backup		.claude-code-backup
docs		docs
examples		examples
schema		schema
scripts		scripts
skills		skills
src		src
test		test
ui		ui
.claudecode.json		.claudecode.json
.detect-secrets.cfg		.detect-secrets.cfg
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.oxfmtrc.jsonc		.oxfmtrc.jsonc
.oxlintrc.json		.oxlintrc.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.prettierignore		.prettierignore
.secrets.baseline		.secrets.baseline
.shellcheckrc		.shellcheckrc
.swiftformat		.swiftformat
.swiftlint.yml		.swiftlint.yml
API.md		API.md
CLAUDE.md		CLAUDE.md
DEEP_DIVE_REPORT.md		DEEP_DIVE_REPORT.md
Dockerfile		Dockerfile
README.md		README.md
SOUL.md		SOUL.md
TODO.md		TODO.md
TODO_1.md		TODO_1.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
production.md		production.md
summary.md		summary.md
test-websocket.js		test-websocket.js
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation