belisarius (Kostchei)

贝利撒留

通过Ollama驱动的本地大型语言模型（LLM）赋能的自主AI编码代理

贝利撒留（Belisarius）是一个任务执行系统，它利用本地大型语言模型自主完成软件开发任务。该系统具有不可变的任务列表架构和动态模型上下文协议（MCP）服务器管理功能，以实现资源的高效利用。

🚀 刚来Belisarius的新手吗？ 办理退房 《GETTING_STARTED.md》翻译为中文是《入门指南.md》或《开始使用指南.md》（具体翻译可能根据上下文有所调整，但“GETTING_STARTED”通常指“入门”或“开始使用”的意思） 快速介绍一下！

特点/特性

• 本地大型语言模型执行由Ollama提供支持，兼容Qwen 2.5 Coder、DeepSeek Coder和CodeLlama
• 不可变的任务列表基于YAML的任务定义，包含依赖管理
• 动态MCP工具按需加载MCP服务器（文件操作、代码执行、网络搜索）
• 状态机具有验证和重试逻辑的健壮任务状态管理
• 16GB 显存优化精心挑选的消费级GPU型号

建筑学

见 ARCHITECTURE.md（文件名，可译为“架构说明.md”或保持原样，具体取决于上下文是否需要翻译文件名） 用于详细系统设计。

关键组件：

• 任务协调器带有状态机的主要执行循环
• Ollama 客户端本地大型语言模型（LLM）的接口
• MCP 管理器MCP服务器的动态生命周期管理
• 验证者任务完成验证

先决条件

• Python 3.11+（或 Python 3.11及以上版本）
• Ollama（注：Ollama是一个用于训练和运行大型语言模型的工具或框架的名称，直接翻译可能无具体含义，故在此保留原英文形式） 已安装并运行
• 16GB 显存 GPU（建议使用NVIDIA RTX 4080或同等性能）
• Windows 10及以上版本 （用于Windows服务支持）

快速入门

太长，读不下去了

ollama pull qwen2.5-coder:32b  # Download the model
. venv/Scripts/activate         # Activate virtual environment
python -m src.main              # Run it! (opens web UI automatically)

见 GETTING_STARTED.md 翻译为中文是：《入门指南.md》（或《开始使用指南.md》，具体翻译可能根据上下文有所调整） 以获取完整的操作指南。

______________________________________________________________________

安装

1. 安装Ollama

从……下载 ollama.com（这个网址本身在中文中没有特定的翻译，但可以理解为“奥拉玛网站”或保持原样，因为网址通常不直接翻译） 并进行安装。

2. 拉取推荐模型

# Primary model (best performance)
ollama pull qwen2.5-coder:7b-instruct-q4_K_M

# Alternative models
ollama pull deepseek-coder:6.7b-instruct-q4_K_M
ollama pull codellama:13b-instruct-q4_K_M
ollama pull codellama:7b-code-q4_K_M

3. 安装贝里萨里乌斯（Belisarius，此处可能指某软件、系统或设备的名称，具体根据上下文确定）

# Clone repository
git clone 
cd belisarius

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers (for web_search MCP)
playwright install chromium

4. 比利萨留斯跑（或译为“比利萨留斯战役”）

# Auto-discover and run (easiest - uses primary_task.yaml or demo)
python -m src.main

# Or run specific task file
python -m src.main tasks/examples/hello_world.yaml

# Or run headless (no UI)
python -m src.main --no-ui

发生的事情：

• Web 用户界面自动在 http://localhost:8080 启动
• 浏览器打开以显示实时进度
• 任务使用配置的模型执行
• 文档是在 docs/

用法

创建任务列表

创建一个YAML文件来定义你的任务：

# tasks/my_project.yaml
version: "1.0"
metadata:
  name: "My Project"
  description: "Build something awesome"

tasks:
  - id: "TASK-001"
    title: "Setup project"
    description: "Initialize a Python project with pytest"
    dependencies: []
    priority: high
    model: "qwen2.5-coder:7b-instruct-q4_K_M"
    required_tools: ["file_ops"]
    validation:
      - type: "path_exists"
        paths: ["pyproject.toml", "tests/"]

运行中的任务

# Auto-discover primary task (easiest!)
python -m src.main

# Run specific task file
python -m src.main 

# Run headless (no UI)
python -m src.main --no-ui

# Custom port
python -m src.main --port 8888

# Disable auto-browser launch
python -m src.main --no-browser

自动发现： 如果你没有指定任务文件，Belisarius 将自动搜索：

1. primary_task.yaml （在当前目录）
2. tasks/primary_task.yaml
3. tasks/examples/hello_world.yaml （演示备用）

创建你的主要任务：

# Copy the template
cp tasks/primary_task.yaml primary_task.yaml

# Edit it with your tasks
# Then just run:
python -m src.main

监测进度

Web 用户界面（推荐）：

• 自动在 http://localhost:8080 打开
• 实时任务进度
• 交互式任务编辑器
• 系统日志和指标

数据库查询：

sqlite3 state.db "SELECT id, status, attempts FROM tasks"

配置

MCP 服务器

编辑 config/mcp_registry.json 配置MCP服务器：

{
  "mcp_servers": {
    "file_ops": {
      "display_name": "File Operations",
      "entry_point": "mcp_servers/file_ops/server.py",
      "idle_timeout_seconds": 300
    }
  }
}

模型

编辑 config/models.json 配置模型偏好设置：

{
  "default_model": "qwen2.5-coder:7b-instruct-q4_K_M",
  "fallback_chain": [
    "qwen2.5-coder:7b-instruct-q4_K_M",
    "deepseek-coder:6.7b-instruct-q4_K_M"
  ]
}

MCP 工具

Belisarius 包含三个内置的 MCP 服务器：

1. 文件操作（file_ops)

• read_file读取文件内容
• write_file写入文件
• list_directory列出目录内容
• search_files按模式搜索文件
• create_directory创建目录

2. 代码执行（code_exec)

• execute_python在沙箱中运行Python代码
• execute_node运行 Node.js 代码
• execute_shell运行受限的Shell命令
• run_tests执行测试套件

3. 网络搜索（web_search）

• search_web上网搜索
• fetch_url检索网页内容
• extract_content解析结构化数据
• search_documentation查询文档网站

注MCP服务器按需启动，并在空闲超时后关闭。

发展

运行测试

pytest tests/

代码格式化

black src/ mcp_servers/ tests/
ruff check src/ mcp_servers/ tests/

类型检查

mypy src/

项目结构

belisarius/
├── src/
│   ├── core/           # Task orchestration
│   ├── llm/            # Ollama client
│   ├── mcp/            # MCP management
│   └── utils/          # Utilities
├── mcp_servers/        # MCP server implementations
│   ├── file_ops/
│   ├── code_exec/
│   └── web_search/
├── config/             # Configuration files
├── tasks/              # Task list definitions
└── tests/              # Test suite

路线图

• \[x\] 核心任务协调器
• \[x\] Ollama 集成
• \[x\] 动态MCP管理器
• \[ \] MCP服务器实现
• \[ \] 任务验证框架
• \[ \] Windows 服务包装器
• \[ \] 文档生成
• \[ \] 用于监控的Web用户界面

贡献；做出贡献

欢迎投稿！请阅读 CONTRIBUTING.md 翻译为中文是：“贡献指南/贡献文档.md”。

许可证

MIT 许可证 - 请参阅 许可证

参考文献

• Ollama（注：Ollama是一个用于运行和管理大型语言模型的工具或平台的名称，在中文中通常直接保留原名，不进行翻译。）
• 模型上下文协议
• 人类智能体软件开发工具包（Anthropic Agent SDK）
• 如何构建一个编码代理

支持

• GitHub Issues（问题追踪）： 报告错误
• 讨论： 提问

______________________________________________________________________

贝利撒留该名称取自拜占庭传奇将军的名字，他曾以有限的资源取得辉煌胜利。