mcp-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Loop (Auto-Fix)

Điều kiện tiên quyết

先决条件

MCP server của Dart/Flutter (
```
mcp_flutter
```
) đã được cấu hình và cấp quyền chạy
```
flutter run
```
, đọc devtools, widget tree, log, chụp screenshot. Nếu không có quyền này, báo cho user cấu hình trước — không đoán kết quả build mà không chạy thật.

已配置Dart/Flutter的MCP服务器（
```
mcp_flutter
```
），并授予其运行
```
flutter run
```
、读取devtools、widget tree、日志、截取屏幕截图的权限。如果没有此权限，请告知用户先进行配置——不要在未实际运行的情况下猜测构建结果。

Vòng lặp (tối đa 5 lần)

循环（最多5次）

Lần 1..5:
  1. flutter run / hot reload qua MCP
  2. Đọc log build + runtime log
  3. Nếu compile error → đọc message lỗi cụ thể → sửa file liên quan → quay lại bước 1
  4. Nếu build pass → chụp screenshot qua MCP
  5. Đọc widget tree, kiểm tra: text overflow, widget lỗi layout, exception runtime
  6. Nếu phát hiện lỗi → sửa → quay lại bước 1
  7. Nếu sạch lỗi → DỪNG vòng lặp, chuyển sang ui-checkpoint

第1..5次:
  1. 通过MCP执行flutter run / hot reload
  2. 读取构建日志 + 运行时日志
  3. 如果出现编译错误 → 读取具体错误信息 → 修改相关文件 → 返回步骤1
  4. 如果构建通过 → 通过MCP截取屏幕截图
  5. 读取widget tree，检查：文本溢出、布局错误组件、运行时异常
  6. 如果发现错误 → 修复 → 返回步骤1
  7. 如果无错误 → 停止循环，进入ui-checkpoint

Khi nào dừng và báo user (không lặp vô hạn)

何时停止并通知用户（避免无限循环）

Sau 5 lần vẫn còn lỗi compile → thử
```
rag-fallback/SKILL.md
```
(fetch doc mới nếu nghi lỗi do API/package deprecated), tối đa 2 lần thử thêm.
Sau khi thử cả rag-fallback vẫn lỗi → DỪNG hẳn, xuất toàn bộ log lỗi gần nhất cho user, không tiếp tục đoán mò (tránh đốt token vô ích).
Nếu lỗi thuộc dạng thiếu API key/credential → dừng ngay lập tức (không thuộc phạm vi tự sửa), báo user cần cấu hình
```
.env
```
.

5次循环后仍存在编译错误 → 尝试
```
rag-fallback/SKILL.md
```
（如果怀疑是API/包已弃用导致的错误，获取新文档），最多额外尝试2次。
尝试rag-fallback后仍报错 → 完全停止，向用户输出最新的完整错误日志，不再继续猜测（避免浪费token）。
如果错误属于缺少API密钥/凭证类型 → 立即停止（不在自动修复范围内），告知用户需要配置
```
.env
```
。

Phân loại lỗi để quyết định hướng sửa

错误分类以确定修复方向

Loại lỗi	Cách xử lý
Compile error do sai cú pháp/import	Tự sửa trực tiếp
Compile error do API deprecated	→ `rag-fallback`
Runtime exception (null check, type error)	Đọc stack trace, sửa logic liên quan
UI overflow / layout lỗi	Sửa widget, đối chiếu lại `design-system`
Lỗi do thiếu package đã duyệt nhưng chưa `pub get`	Chạy `flutter pub get` , thử lại
Lỗi do thiếu package CHƯA duyệt	Dừng, hỏi user (không tự thêm)

错误类型	处理方式
语法错误/导入错误导致的编译错误	直接自动修复
API已弃用导致的编译错误	→ 使用 `rag-fallback`
运行时异常（空检查、类型错误）	读取堆栈跟踪，修改相关逻辑
UI溢出 / 布局错误	修改组件，对照 `design-system`
已确认但未执行 `pub get` 导致的包缺失错误	运行 `flutter pub get` ，重试
未确认的包缺失错误	停止，询问用户（不自动添加）

Ghi chú tiết kiệm token

节省token的注意事项

Chỉ gửi phần log/error liên quan vào context, không dán toàn bộ log verbose của
```
flutter run
```
nếu không cần thiết.
Dùng widget tree/screenshot only khi nghi ngờ lỗi UI, không cần chụp ảnh nếu chỉ đang sửa lỗi compile thuần logic.

仅将相关的日志/错误信息发送至上下文，如果不需要，不要粘贴
```
flutter run
```
的完整详细日志。
仅在怀疑存在UI错误时使用widget tree/截图，若仅修复纯逻辑编译错误则无需截图。