AI导哈

开发执行合约工具

DevBox 是一个轻量级、语言无关的执行合约工具，用于明确、确定性地管理仓库的开发接口，并为人类和AI代理提供策略控制的开发环境。

  • by danieljhkim
  • Shell
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 danieljhkim/DevBox

使用说明

DevBox

现代仓库越来越多地由人工智能代理运营。

在实践中，这产生了一种新的运营债务： 教学疲劳.

每个新的代理工作流（Cursor、Claude Code、Copilot、自定义CLIs、MCP工具等）都倾向于引入自己的规则文件和约定--.cursorrules, .claudecode、提示代码片段、Allowlist、脚本和一次性文档。随着时间的推移，这些信息会逐渐积累、过时，并用零散的“真相来源”使信息库变得混乱

结果是可以预测的：

  • 入职速度较慢
  • 本地工作流不一致
  • 代理功能强大但不安全（或安全但无效）
  • 执行知识存在于太多的地方

DevBox 是一个轻量级的、与语言无关的 执行合同 这使得你的仓库的开发接口对人类和人工智能代理都是明确的、确定性的和策略性的。

DevBox生活在 .box/ 并集中：

  • 如何在本地启动/停止系统
  • 如何验证更改
  • 日志和工件所在的位置
  • 每项政策允许采取哪些行动

它定义了：

  • 项目如何启动
  • 如何验证
  • 日志和工件所在的位置
  • 允许采取哪些行动
  • 代理如何安全地与系统交互

DevBox是 不 框架、容器或运行时。
它是一个 薄控制层 围绕您现有的项目。

安装

自制（推荐）

# 0) Install DevBox
brew tap danieljhkim/tap
brew install danieljhkim/tap/devbox


# 1) Install DevBox into the target repo
cd /path/to/your-repo
devbox init .

# 2) Configure local runtime commands
cp .box/env/.env.local.example .box/env/.env.local
# edit .box/env/.env.local and set BOX_UP_CMD / BOX_DOWN_CMD / BOX_HEALTH_URL

# 3) Verify and start (can be run from anywhere inside the repo)
devbox doctor
devbox up

# 4) (Optional) Inspect or switch agent execution policy
devbox policy show
devbox policy list
devbox policy set safe-write

看 QUICK_START.md 完整的工作流程。

DevBox为什么存在

现代开发环境不再仅由人类操作。

AI代理现在可以：

  • 运行代码
  • 读取日志
  • 重试失败
  • 自主迭代

但大多数存储库都公开了 隐式、未记录和不安全的执行表面：

  • 即席shell脚本
  • 未记录的目标
  • 脆弱的本地指令
  • 无限制命令执行

为了执行更严格的规则，我们被迫为每个新的代理工作流维护碎片化的、特定于工具的规则（.cursorules、.cladecode等）。随着我们采用的每一个新的代理IDE或CLI工具，越来越多的这些零散的指令都会扰乱我们的代码库和思维。

DevBox旨在通过为所有代理工作流程提供通用的真理来源来解决这个问题。

至少，我希望它能提供一些启示。

DevBox是什么（不是什么）

✅ 是

  • A. 合同 促进地方发展
  • A. 确定性执行面
  • 代理安全 刻意为之
  • 语言和框架无关
  • 与MCP（模型上下文协议）兼容

❌ 不是

  • Docker、Bazel或Make的替代品
  • CI系统
  • 生产运行时
  • 神奇的抽象

DevBox 包裹 你已经拥有的东西，并不能取代它。

核心概念

1.命令

所有项目操作都规范化为命名命令。

示例：

  • up –启动本地系统
  • down -住手
  • test –验证正确性
  • health –检查准备情况
  • logs –检查执行情况

每个命令都映射到一个 单一的、确定性的实现.

2.政策

政策定义 代理人可以做什么.

它们规定：

  • 允许的命令
  • 可读路径
  • 可写路径
  • 执行限制

这可以防止意外或恶意行为，同时实现自主性。

策略通过命名配置文件进行管理（例如： readonly, safe-write, admin) 储存在 .box/policies/一次只有一个配置文件处于活动状态。

您可以使用以下方式检查或切换活动策略：

devbox policy show
devbox policy list
devbox policy set readonly|safe-write|admin

3.信号

信号是系统产生的机器可读输出：

  • 健康检查
  • 日志
  • 报告
  • 状态快照

代理商消费 信号不是人类的直觉。

4.MCP集成（可选）

DevBox可以通过MCP暴露于AI代理：

  • 工具(box-run, box-health, box-read-logs)
  • 资源（配置、状态）
  • 提示（可选）

MCP是 可选的 并明确选择加入。
DevBox不依赖于MCP；MCP适配器依赖于DevBox。

要启用VS代码的MCP接线：

devbox mcp enable

这创造了 .vscode/mcp.json 指向DevBox MCP服务器 .box/并安装和构建MCP服务器。

# (optional) start the MCP server manually (foreground, stdio)
# Useful for debugging or non-editor hosts
devbox mcp start

编辑支持

  • VS代码/光标：通过原生MCP支持 mcp.json
  • IntelliJ/JetBrains：还没有原生MCP支持
    使用DevBox命令行界面(devbox up, devbox test等）或IDE外部工具集成

DevBox本身与编辑器无关；MCP是支持的可选适配器。

目录布局

.box/
├── box.yaml           # Source of truth (commands, env, signals)
├── policies.yaml      # Agent execution limits
├── scripts/           # Command implementations
├── state/             # Runtime state (pids, ports, metadata)
├── contracts/         # Invariants, APIs, schemas
└── mcp/               # MCP server + tool specification (optional)

示例流程

人机交互：

Agent
  ↓
box-run("up")
  ↓
.box/scripts/up.sh
  ↓
Local system starts
  ↓
Signals emitted (logs, health)

同样的流程适用于：

  • 人类
  • CI
  • AI代理
  • 自动化

DevBox命令行界面

当 devbox 在你的 PATH，所有核心命令都可以从存储库中的任何位置获得：

devbox doctor
devbox up
devbox health
devbox test
devbox logs
devbox down
devbox policy show
devbox policy set safe-write

CLI通过查找以下位置自动发现repo根目录 .box/.

设计原则

  • 单一真相来源
  • 快速失败
  • 的确定性行为
  • 明确合同
  • 最小表面积

如果它不在DevBox中，则不受支持。

状态

DevBox是一个 显露模式，不是正式的标准。 它代表了以下方面的融合：

  • 密封开发环境
  • 策略导向执行
  • 代理操作系统

期待进化，而不是动荡。

哲学

人类设计和编排。
系统执行具有确定性。
特工在护栏内迭代。

DevBox定义了意图和执行之间的界限。

DevBox合规性： 核心
（通过配置支持扩展和代理就绪）

许可证

麻省理工学院

相关 MCP