loop-polish Skill 全能力拆解：自动化全栈联调、浏览器测试与代码修复

Clf丶忆笙

165人浏览 · 2026-08-16 16:10:28

Clf丶忆笙 · 2026-08-16 16:10:28 发布

文章目录

一、Skill 定位

loop-polish 是 TRAE IDE（对标 Cursor / Claude Code 的 AI IDE）的一个 Skill，本质是一份结构化 prompt（SKILL.md），由 TRAE 的 Agent 引擎执行。

它的核心功能用一句话概括：

自动启动你的项目 → 全量跑前后端联调 → 5 个维度打分 → 自动修复问题 → 循环直到达标 → 生成质量报告。

官方描述：Not perfect, don’t ship.（不完美，不上线。）

GitHub: https://github.com/lqclf/loop-polish-skills

二、它解决什么问题

针对开发流程中三类高频痛点：

2.1 上线前的"差不多得了"问题

项目自测时看着没问题，上了联调就翻车：分页参数类型不对、必填校验漏写、删除按钮接错事件、软删除字段写错位置……

人工联调依赖经验和耐心，疏漏是常态。loop-polish 把这套"必查清单"程序化。

2.2 重构后的回归盲区

改了 20 个文件，不知道会不会牵连别的模块。靠人肉测成本高、覆盖不全。loop-polish 通过 git diff 自动圈定改动影响范围，只重测受影响的 case。

2.3 接手老代码的风险

新接手的项目不知道哪里有坑，扫一遍是必要的。loop-polish 跑一遍能列出所有接口的可达性、所有页面的可用性。

三、核心能力清单

loop-polish 的能力矩阵，按执行阶段划分：

3.1 项目识别（自动）

不依赖用户输入，能从文件存在性自动识别项目类型：

识别文件	项目类型
pom.xml / build.gradle	Java（Maven / Gradle）
package.json + express/koa/nest	Node.js
requirements.txt / pyproject.toml	Python（Flask / FastAPI / Django）
go.mod	Go
Cargo.toml	Rust

前后端可独立识别，纯前端项目（无后端代码）自动跳过接口扫描。

3.2 接口扫描（无需人工配置）

从源码 grep 注解 / 装饰器，识别所有 HTTP endpoint：

语言 / 框架	识别模式
Java Spring	`@RestController` 下的 `@GetMapping` / `@PostMapping` / `@PutMapping` / `@DeleteMapping`
Node Express / Koa	`router.get(...)` / `app.post(...)` 等
Python Flask / FastAPI	`@app.route(...)` / `@router.get(...)` 等
Go Gin / Echo	`r.GET(...)` / `r.POST(...)` 等

对每个接口反向解析请求体 DTO，自动提取字段名和类型，无需手写接口文档。

3.3 接口验证（6 类用例）

每个接口自动跑以下 6 种测试：

类型	验证目标	预期状态码
正常值	合法参数完整请求	200 / 201
边界值	空串、0、负数、超长字符串	200 或合理错误
必填缺失	去掉必填字段	400
无 Token	访问受保护接口	401
越权	普通用户 Token 访问管理接口	403
异常数据	SQL 注入、特殊字符、恶意 payload	400 或清洗后 200

每个接口最多 2 次重试，避免网络抖动造成误判。

3.4 前端页面验证（基于 Playwright）

通过 Skill 工具 playwright-master 驱动真实浏览器，扫描每个路由并执行交互：

检查项	具体动作
加载	检查白屏、JS 报错（console.error）、首屏时间
表单	必填校验、空值、合法值、提交成功
列表	分页、搜索、删除
弹窗 / Drawer	打开、操作、关闭
导航	菜单点击、tab 切换、面包屑

失败时自动截图并采集控制台日志与失败的网络请求。

3.5 数据库状态验证（可选）

对每一个写操作（POST / PUT / DELETE），不只信 HTTP 响应，还直连数据库二次确认：

POST /api/users  body:{name:"test"}  → 201 {id:123}
   ↓
SELECT * FROM users WHERE id=123
   ↓
断言:name == "test" && created_at != null

支持 MySQL、PostgreSQL、SQLite。连接信息从 application.yml / .env / config.json 等配置文件按优先级自动获取。

安全细节：数据库密码全程不写入报告或日志，自动脱敏为 [REDACTED]。

3.6 五维评分体系

每个测试点都按 5 个维度独立打分：

维度	权重	衡量目标
Completeness 完整性	0.40	接口能调通、页面能加载
Correctness 正确性	0.25	返回数据符合预期
UX 用户体验	0.15	交互流畅、错误提示友好
Error Handling 错误处理	0.10	边界 / 权限 / 异常输入正确拒绝
Performance 性能	0.10	API < 2s、页面 < 3s

加权总分 100 分制，target_score 默认 100。

3.7 自动修复（3 级策略）

按问题严重程度分层处理：

优先级	类别	例子
P1	编译 / 语法错误	缺失 import、类型不匹配、空指针
P2	逻辑 / 数据错误	错误查询条件、字段不一致
P3	UX / 性能	缺 loading、错误提示不友好、N+1 查询

三档修复策略：

策略	允许修复	单轮最大文件	单轮最大处数
conservative	P1~P2	1	3
moderate	P1~P2	2	5
aggressive	P1~P3	跨模块	10

修复后单独跑回归用例验证。修坏自动回滚到原代码片段，标记为 unfixable。

3.8 报告生成

执行结束生成 Markdown / HTML 报告，内容包括：

Summary：总分、轮数、耗时、通过 / 失败 / 已修 / 剩余计数
Score Trend：每轮 5 维分数趋势表
Fix Details：每个修复的文件路径、diff、回归结果
Remaining Issues：未修项 + 原因 + 建议（加单元测试 / 加日志 / 人工 review）

报告里绝不出现原始请求体、token、数据库连接字符串。

3.9 模式与作用域

两种执行模式：

模式	行为	适用
`full`	测 + 修 + 循环	上线前最终打磨
`preflight`	只扫描不修改	CI 合并门禁

四种作用域：

作用域	范围
`all`	前端 + 后端 + DB
`backend`	后端 + DB
`frontend`	仅前端
`api`	仅后端接口

四、安全设计

loop-polish 是个会改你代码的工具，安全设计是重点。

4.1 Git 隔离

所有修改在 loop-polish/round-{timestamp} 分支上做，跑完自动切回原分支。git diff main 可清晰看到所有改动。

4.2 本地修改保护

执行前若工作区有未提交代码，自动 git stash 暂存，跑完 git stash pop 还原。

4.3 端口安全

不无脑 taskkill / kill -9。会先判断占用端口的进程是否属于当前项目，不是则警告并询问用户。

4.4 敏感信息脱敏

Authorization / Cookie header → [REDACTED]
请求 / 响应里的 password / token / secret → [REDACTED]
数据库连接字符串 → 不写入报告

4.5 高危操作确认

涉及以下变更时，停下来弹 AskUserQuestion 询问：

数据库 schema 变更
删除代码超过 10 行
鉴权 / 权限逻辑修改
跨模块联动修改
配置文件修改

4.6 中断可恢复

执行过程中若被 SIGINT / 异常中断，状态保存到 .loop-polish-state.json，下次跑自动从断点续跑。

五、典型适用场景

场景	推荐配置
个人项目上线前最终打磨	`mode=full, strategy=conservative, target_score=100`
团队 PR 合并门禁	`mode=preflight, target_score=95, scope=api`
重构后回归验证	`mode=full, scope=all, max_rounds=3`
接手陌生老项目	`mode=full, strategy=moderate, timeout_minutes=60`
性能专项检查	`scope=api, auto_fix.strategy=aggressive`

六、明确不能做的事

为避免误用，列清楚边界：

不能救跑不起来的项目：前置条件是项目本身能 build、能 run
不能修架构问题：只处理 P1~P3 的具体问题点
不能替代单元测试：它是集成验证，不是单元测试
不适合生产环境：会起本地服务、连数据库、读配置文件
不是银弹：复杂业务逻辑问题需要人工 review

七、与同类工具的差异

工具	类别	loop-polish 不同点
ESLint / Checkstyle	静态分析	不跑项目、不调接口
Postman / Apifox	接口测试	需手写用例，不会自动发现
Cypress / Playwright	浏览器自动化	需写脚本，不评分不修复
SonarQube	代码质量平台	重、要部署、不会改
Claude Code / Cursor	AI 编程	不主动找问题，需 prompt

loop-polish 的定位：项目上线前的最后一公里，不替代上面任何工具，而是站在它们后面做最后兜底。

八、安装与首次运行

一行命令安装：

# Mac / Linux
curl -fsSL https://raw.githubusercontent.com/lqclf/loop-polish-skills/main/install.sh | bash

# Windows PowerShell
iwr https://raw.githubusercontent.com/lqclf/loop-polish-skills/main/install.ps1 -UseBasicParsing | iex

或手动把 SKILL.md 放到项目的 .trae/skills/loop-polish/ 目录，重启 TRAE。

启动：在 TRAE 对话框输入 Run loop polish 或中文 跑一下 loop polish 即可。

九、配置示例

在项目根目录新建 .loop-polish.json：

{
  "mode": "full",
  "max_rounds": 5,
  "target_score": 95,
  "scope": "all",
  "auto_fix": {
    "enabled": true,
    "strategy": "conservative",
    "max_per_round": 3
  },
  "browser": { "headless": true },
  "db_verify": true,
  "report": {
    "format": "markdown",
    "output_dir": "./polish-reports/"
  },
  "timeout_minutes": 120
}