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-writeCLI通过查找以下位置自动发现repo根目录 .box/.
______________________________________________________________________
设计原则
- 单一真相来源
- 快速失败
- 的确定性行为
- 明确合同
- 最小表面积
如果它不在DevBox中，则不受支持。
______________________________________________________________________
状态
DevBox是一个 显露模式，不是正式的标准。 它代表了以下方面的融合：
- 密封开发环境
- 策略导向执行
- 代理操作系统
期待进化，而不是动荡。
______________________________________________________________________
哲学
人类设计和编排。\ 系统执行具有确定性。\ 特工在护栏内迭代。 DevBox定义了意图和执行之间的界限。
______________________________________________________________________
DevBox合规性： 核心\ （通过配置支持扩展和代理就绪）
许可证
麻省理工学院