Plan → Execute → Inspect → Iterate
可以让 OpenCode 的 Agent 独立完成完整项目的自主编码引擎。 它不仅仅是一个工具集，更是一个拥有"宪法"和"自我纠错"能力的智能导演。
LoopCraft 的设计哲学是 "导演与演员" 模型：
- OpenCode Agent (演员): 拥有强大的编码、工具使用和推理能力，但容易"迷路"或偏离目标。
- LoopCraft Plugin (导演): 负责宏观调控。它不直接写代码，而是：
- 制定计划: 让 Agent 生成并遵循
ARCHITECTURE.md。 - 审核质量: 在 Agent 提交代码前进行双重检查。
- 纠正偏差: 当 Agent 陷入死循环或错误时，强制介入。
- 管理资源: 控制 Token 消耗和步骤数量。
- 制定计划: 让 Agent 生成并遵循
| 功能模块 | 详细说明 |
|---|---|
| 自主闭环 | 自动执行 Plan-Execute-Inspect-Iterate 循环，无需人工每一步干预。 |
| 宪法注入 | 强制 Agent 生成并遵守 ARCHITECTURE.md，确保代码风格和架构一致性。 |
| 自纠正 | 遇到错误时自动尝试修复；若修复失败，自动回滚或请求人工介入。 |
| 振荡检测 | 智能识别 "修好了A却坏了B" 的逻辑死循环，及时熔断。 |
| 预算熔断 | 双重熔断机制：动作数 (防止死循环) + 预估费用 (防止 Token 爆炸)。 |
| 双重审查 | Phase 1: 规则引擎 (ESLint/安全模式) Phase 2: LLM 深度审查 (可选，检查架构一致性)。 |
| 断点续传 | 所有状态持久化到 .opencode/loop-state.json，随时暂停/恢复。 |
| 即时提示 | 支持在运行时通过 loop_hint 注入提示，不打断当前的执行流。 |
┌───────────────────────────────────────────────────────┐
│ OpenCode Agent │
│ ┌─────────┐ ┌────────┐ ┌──────┐ ┌──────────────┐ │
│ │ Read │ │ Write │ │ Bash │ │ CodeSearch │ │
│ └─────────┘ └────────┘ └──────┘ └──────────────┘ │
│ ┌─────────┐ ┌────────┐ ┌──────┐ ┌──────────────┐ │
│ │ Edit │ │ Grep │ │ Glob │ │ WebSearch │ │
│ └─────────┘ └────────┘ └──────┘ └──────────────┘ │
└───────────────┬──────────────────────────┬────────────┘
│ session.idle (事件) │ tool 调用
▼ ▼
┌───────────────────────────────────────────────────────┐
│ LoopCraft Plugin │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ index.ts (入口) │ │
│ │ • 注册 9 个自定义工具 │ │
│ │ • 注册 3 个 Hook │ │
│ └──────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼───────────────────────────┐ │
│ │ orchestrator.ts (编排) │ │
│ │ • 事件驱动循环引擎 │ │
│ │ • Preflight 安全检查 │ │
│ │ • 步骤推进 & 生命周期 │ │
│ └────┬────────────┬───────────────┬────────────────┘ │
│ │ │ │ │
│ ┌────▼────┐ ┌────▼─────┐ ┌─────▼──────┐ │
│ │state.ts │ │planner.ts│ │corrector.ts│ │
│ │状态持久化│ │Prompt生成│ │错误分析 │ │
│ │预算控制 │ │Plan解析 │ │振荡检测 │ │
│ └─────────┘ └──────────┘ └────────────┘ │
│ │ │
│ ┌────▼────────────────────────────────────┐ │
│ │ inspector.ts (审查) │ │
│ │ Phase 1: 规则引擎 (ESLint/Pattern) │ │
│ │ Phase 2: LLM 架构一致性审查 (可选) │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────┘
插件是「导演」，OpenCode Agent 是「演员」。
LoopCraft 不重新实现 LLM 调用或工具执行（那是 OpenCode 的核心能力），
而是通过 SDK (client.session.prompt()) 向 Agent 发送指令，
通过 Hooks 监听事件和注入上下文。
| 机制 | OpenCode API | 用途 |
|---|---|---|
| 驱动循环 | client.session.prompt() |
向 Agent 发送编码指令 |
| 监听完成 | event: session.idle Hook |
检测 Agent 空闲，推进下一步 |
| 注入宪法 | experimental.chat.system.transform Hook |
将 ARCHITECTURE.md 注入 System Prompt |
| 保持记忆 | experimental.session.compacting Hook |
上下文压缩时注入状态摘要 |
| 工具通信 | 自定义 tool 注册 |
Agent 通过工具向插件汇报进度/错误 |
| 搜索/读写 | OpenCode 内置工具 | 不重复实现 (Read/Write/Grep/Bash) |
git clone https://github.com/your-username/opencode-loopcraft.git
cd opencode-loopcraft
bun install
bun run build
# 在 opencode.json 中使用本地路径
{
"plugin": ["file:///path/to/opencode-loopcraft/dist/index.js"]
}在 OpenCode 中输入：
/loop_start Build a REST API with user authentication using Express and JWT
Agent 将自动：
- 分析环境 — 读取现有代码和配置
- 创建 ARCHITECTURE.md — 定义技术栈和规范
- 生成执行计划 — 有序的步骤列表
- 等待审批 — 你确认后才开始编码
- 自主执行 — 编码 → 测试 → 审查 → 提交
- 自纠正 — 遇错自动修复，大问题找你
| 命令 | 说明 |
|---|---|
loop_start |
启动自主循环（需要 goal 参数） |
loop_status |
查看当前进度、预算和阶段 |
loop_approve |
审批计划并开始执行 |
loop_pause |
暂停循环 |
loop_resume |
恢复暂停的循环 |
loop_hint |
注入提示（不打断循环） |
loop_budget |
开启/关闭/配置预算熔断 |
运行时想给 Agent 一个提示但不想打断它？
/loop_hint 注意，那个 API 的参数格式变了，请参考 docs/api-v2.md
Agent 会在下一轮读取你的提示。
🚀 Start
│
▼
🏥 Health Check (git/node)
│
▼
💾 State Exists? ──Yes──► 📂 Resume Session
│ No │
▼ │
📡 Create Session │
│ │
▼ │
📋 Planning Phase │
│ Agent generates │
│ ARCHITECTURE.md + Plan │
▼ │
👤 User Approval ◄──────────────┘
│
▼
┌─────────────────────────────────┐
│ 🔄 Main Loop │
│ │
│ 💰 Budget Check ──exceed──► ⏸ │
│ 🛑 Interrupt? ──yes──────► ⏸ │
│ 💡 User Hint? ──inject──► │
│ │
│ 📡 Send Coding Prompt │
│ │ │
│ ▼ │
│ 🤖 Agent Executes │
│ │ │
│ ▼ │
│ ✅ Tests Pass? │
│ │ No ──► 🔧 Corrector │
│ │ │ │
│ │ ▼ │
│ │ 🌀 Oscillating? │
│ │ │ Yes ──► 🔴 Stop │
│ │ │ No │
│ │ ▼ │
│ │ Retry < Max? │
│ │ │ Yes ──► Retry │
│ │ │ No ──► 🔴 Stop │
│ │ │
│ ▼ │
│ 🔍 Inspector │
│ │ Issues? ──► Fix & Retry │
│ │ │
│ ▼ │
│ 📦 Git Commit │
│ │ │
│ ▼ │
│ 📋 More Steps? ──Yes──► Loop │
│ │
└──── No ──► 🏁 Graceful Exit │
为了防止 AI 消耗过多资源，LoopCraft 提供了双重预算控制。
注意: 默认情况下预算熔断是关闭的，需要手动开启。
# 开启预算 (默认: 200 动作 / $2.00)
/loop_budget action=on
# 自定义并开启
/loop_budget action=set maxActions=500 maxCostUsd=5.00- Max Actions: 限制 Agent 与环境交互的总次数。
- Max Cost: 估算 Token 消耗费用 (基于 LLM 定价)。
如果 Agent 陷入了 "修复 Bug A 导致 Bug B，修复 Bug B 又导致 Bug A" 的死循环，Corrector 会介入。
- 机制: 记录最近 20 次修复的
Hash(UserFile + ErrorMessage)。 - 触发: 如果同一错误组合在短时间内重复出现 3 次，循环自动暂停并请求人工介入。
在执行每一步之前，Orchestrator 会检查 git status。
- 如果有未提交的更改，插件会自动创建一个
chore(loopcraft): auto-backup的提交。 - 这确保了如果 Agent 搞砸了代码，用户总是可以回滚到上一个干净的状态。
cd opencode-loopcraft
npm install
npm run build在你的目标项目根目录下创建 opencode.json：
// .opencode/loop-state.json
{
"budget": {
"enabled": false,
"actionsCount": 0,
"maxActions": 200,
"estimatedCostUsd": 0,
"maxCostUsd": 2.00
}
}即使未开启熔断，动作数和费用仍然会被统计并可通过 loop_status 查看。
追踪最近 6 次修复的 file + errorHash。如果同一组合出现 ≥ 3 次 → 强制中断。
每步执行前检查 git status。如有未提交更改 → 自动创建备份 commit。
ARCHITECTURE.md 通过 Hook 注入到每次 LLM 调用的 System Prompt 中，
Agent 无法"遗忘"技术规范。
opencode-loopcraft/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md ← 你在这里
├── src/
│ ├── index.ts # 🔌 Plugin Entry & Tool Registration
│ ├── types.ts # 📐 Type Definitions
│ ├── orchestrator.ts # 🧠 Event-Driven Loop Engine
│ ├── state.ts # 💾 State Persistence & Budget
│ ├── planner.ts # 📋 Prompt Templates & Plan Parsing
│ ├── corrector.ts # 🔧 Error Analysis & Oscillation Detection
│ ├── inspector.ts # 🔍 Two-Phase Quality Inspector
│ ├── logger.ts # 📊 Structured Logging
│ ├── prompts/
│ │ ├── initializer.md # Planning phase prompt
│ │ └── constitution.md # System prompt injection template
│ └── README.md # Source directory documentation
└── tests/ # Unit & Integration Tests
# 安装依赖
bun install
# 开发模式 (热编译)
bun run dev
# 构建
bun run build
# 测试
bun testMIT © LoopCraft Contributors