English | 简体中文

ByteMind

面向真实代码仓库的终端原生 AI Coding Agent。

让 AI 在终端中读代码、搜文件、执行命令、修改代码、规划任务，并在关键操作前保持可控审批。

文档 · 为什么是 ByteMind · 使用场景 · 快速开始 · 功能矩阵 · 架构 · Skills / MCP / SubAgents

为什么是 ByteMind

ByteMind 面向的是这样一类开发者：希望 AI 直接在代码仓库内部工作，而不是停留在外部聊天窗口中。

它不只给建议，而是尝试进入真实工程闭环：

需求输入 → 制定计划 → 调用工具 → 观察结果 → 修改代码 → 执行验证 → 输出结果

使用场景

快速开始

安装

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.sh | bash

Windows PowerShell

iwr -useb https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.ps1 | iex

安装指定版本

curl -fsSL https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.sh | BYTEMIND_VERSION=vX.Y.Z bash

$env:BYTEMIND_VERSION='vX.Y.Z'; iwr -useb https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.ps1 | iex

配置

mkdir -p .bytemind
cp config.example.json .bytemind/config.json

运行

bytemind chat

bytemind run -prompt "分析当前仓库并总结架构"

bytemind run -prompt "重构这个模块并更新测试" -max-iterations 64

5 分钟演示

一个可复现的 Bug 修复闭环，展示 ByteMind 的完整工程能力：

go run ./cmd/bytemind run \
  -prompt "修复失败的测试并验证它通过" \
  -workspace examples/bugfix-demo/broken-project \
  -approval-mode full_access

Bug: CalculateAverage 在空切片上除零返回 NaN。
修复: 添加 len(nums) == 0 守卫条件。

离线验证（无需 API Key）：

go run ./evals/runner.go -smoke -run bugfix_go_001

详见 examples/bugfix-demo/、DEMO.md（评审向导）和 ENGINEERING.md（工程证据）。

工程证据

ByteMind 专为需要可复现、可验证工程输出的评估场景而设计。

真实 Agent 循环

多步工具调用 + 观测反馈、上下文压缩、限流重试、执行预算控制（internal/agent/engine_run_loop.go）。

编码原生工具

14 个内置工具，输出结构化 JSON — git_status、git_diff、run_tests、文件读写搜索、补丁应用、Shell 执行和 Web 访问。每个工具都有单元测试和安全分类。

可复现 Demo

examples/bugfix-demo/broken-project 是一个自包含的 Go 项目，初始 go test ./... 失败，Agent 修复后通过。提供离线验证方式。

评估系统

YAML 定义评估任务，通过 evals/runner.go 运行，支持命令退出码、输出模式、文件内容正则、文件修改检测。已集成 CI（-validate / -smoke）。

安全边界

三层安全模型：审批策略（on-request/always/never）、沙箱（off/best_effort/required）、运行时边界（可写目录、执行白名单、网络白名单）。详见 bytemind safety explain。

CI 与测试

PR 门禁 CI：go build ./...、单元测试 + 覆盖率、Linux/macOS/Windows 沙箱验收、评估冒烟检查。

可扩展性

Skills（可复用工作流）、MCP（外部工具集成）、SubAgents（聚焦委派）。

功能矩阵

内置工具

核心体验

工作原理

graph TD
    A["用户输入"] --> B["构建运行时上下文"]
    B --> C["LLM 决定：回答或调用工具"]
    C --> D{"是否调用工具"}
    D -- "否" --> E["最终回答"]
    D -- "是" --> F["审批 / 策略检查"]
    F --> G["执行工具"]
    G --> H["观察结果写回会话"]
    H --> I{"是否完成"}
    I -- "否" --> C
    I -- "是" --> E

架构

graph TD
    User["User"] --> CLI["cmd/bytemind"]
    CLI --> App["App Bootstrap"]
    App --> Runner["Runner"]

    Runner --> Engine["Agent Engine"]
    Engine --> Provider["Provider Runtime"]
    Provider --> Model["LLM Provider"]

    Engine --> Tools["Tool Registry"]
    Tools --> FileTools["File Tools"]
    Tools --> PatchTools["Patch Tools"]
    Tools --> Shell["Shell Tool"]
    Tools --> Web["Web Search / Fetch"]
    Tools --> TaskTools["Task Output / Stop"]
    Tools --> Delegate["Delegate SubAgent"]

    Runner --> Session["Session Store"]
    Runner --> Config["Config"]
    Runner --> Skills["Skills Manager"]
    Runner --> SubAgents["SubAgent Gateway"]
    Runner --> Safety["Approval / Sandbox / Allowlist"]

配置

ByteMind 默认合并三层配置：内置默认值、用户级 ~/.bytemind/config.json（或 BYTEMIND_HOME/config.json）和项目级 <workspace>/.bytemind/config.json。

下方示例是项目级配置，只影响当前工作区；跨仓库复用的 provider 凭证更适合放在用户级配置或环境变量中。显式传入 -config 时，会使用指定配置文件。

.bytemind/config.json

OpenAI-compatible 示例

{
  "provider": {
    "type": "openai-compatible",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-5.4-mini",
    "api_key_env": "BYTEMIND_API_KEY"
  },
  "approval_policy": "on-request",
  "approval_mode": "interactive",
  "max_iterations": 64,
  "stream": true
}

Anthropic 示例

{
  "provider": {
    "type": "anthropic",
    "base_url": "https://api.anthropic.com",
    "model": "claude-sonnet-4-20250514",
    "api_key_env": "ANTHROPIC_API_KEY",
    "anthropic_version": "2023-06-01"
  },
  "approval_policy": "on-request",
  "approval_mode": "interactive"
}

运行边界示例

{
  "approval_policy": "on-request",
  "approval_mode": "interactive",
  "writable_roots": [],
  "exec_allowlist": [],
  "network_allowlist": [],
  "system_sandbox_mode": "off"
}

Skills、MCP 与 SubAgents

Skills

可复用工作流定义，从三个作用域加载（builtin > user > project）。通过 /skills 和 /skill 命令管理。

/help                 显示可用命令
/session              显示当前会话
/sessions [limit]     列出最近会话
/agents [name]        列出可用 SubAgent 或查看某个定义
/explorer             显示内置 explorer SubAgent 定义
/review               显示内置 review SubAgent 定义
/resume <id>          按 id 或前缀恢复最近会话
/new                  在当前工作区开始新会话
/quit                 退出 CLI

MCP

MCP 用于把 ByteMind 连接到本地仓库之外的外部工具和上下文。

SubAgents

SubAgents 提供聚焦型隔离执行上下文：

安全模型

ByteMind 的设计原则很简单：

AI 可以执行，但最终控制边界必须掌握在人手里。

安全诊断

# 查看当前安全配置
bytemind safety status

# 了解安全模型
bytemind safety explain

# 检查环境、配置和依赖
bytemind doctor

项目结构

cmd/bytemind            CLI 入口
internal/app            应用启动装配
internal/agent          Agent loop、prompt、streaming、subagent execution
internal/config         配置加载、默认值、环境变量覆盖
internal/llm            通用消息与工具类型
internal/provider       Provider 适配与 provider runtime
internal/session        会话持久化
internal/tools          文件 / patch / shell / web 工具
internal/skills         Skills 发现与加载
internal/subagents      SubAgent 管理与 preflight gateway
internal/sandbox        运行边界与沙箱相关逻辑
tui/                    终端 UI（BubbleTea 框架）
examples/bugfix-demo    5 分钟可复现 Bug 修复演示
evals/                  评测任务与运行器
docs/                   架构文档、RFC、PRD
scripts/                跨平台安装脚本

链接

• 文档：https://1024xengineer.github.io/bytemind/zh/
• GitHub：https://github.com/1024XEngineer/bytemind

License

This project is licensed under the MIT License.