
Echoproof
io.github.est57由 GitHub 账号 est57 发布v0.4.0更新于 Oct 27, 2026
Replay real HTTP traffic against base and changed builds; flag behavior changes the intent omits.
概览
Echoproof 把录制的真实 HTTP 流量回放到基准版本与改动版本上,报告助手可对照改动意图判断的行为变化。
- 可以做什么
- 执行行为检查:把录制的快照回放到目标版本,可选地对比基准版本与改动版本,返回结构化报告和运行标识。
- 比较两个已有快照,按端点和字段分组,把每处变化归类为 breaking、behavior 或 additive。
- 查看某次运行中的单条请求,获取完整请求、两份响应以及逐字段差异。
- 对照给定的改动意图评判变化,意图未解释的变化会被标记为回归。
- 适用场景
- 适合编码助手修改 API 服务后,在宣布任务完成前用真实录制的流量自查;也适合作为合并门禁,捕捉单元测试和代码审查发现不了的非预期行为变化。
- 运行要求
- 以本地 stdio 进程运行,通过 echoproof mcp 子命令启动,需先安装 echoproof 可执行文件(Homebrew、发布包,或 Rust 1.85 及以上用 cargo install)。检查需要已录制的流量快照文件,以及可访问的基准版本和目标版本地址。仅在为检查提供改动意图时才需要 ANTHROPIC_API_KEY。仅限桌面端编码助手,网页版助手无法访问本机构建。
安装
在 SourceWeft 中
- 打开 控制台中的 Echoproof,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
Echoproof
[CI] [crates.io] [Release] [License: MIT OR Apache-2.0]
Bahasa Indonesia | English
Verifikasi perilaku API untuk setiap perubahan kode, berdasarkan traffic nyata.
Echoproof merekam request dan response asli dari service Anda, memutarnya ulang ke build hasil perubahan kode, lalu melaporkan apa yang berubah, di endpoint dan field mana, pada berapa persen request, dan apakah perubahan itu memang diniatkan. Hasilnya bisa dipakai sebagai gate di CI atau langsung oleh coding agent (Claude Code, Cursor, dan sejenisnya) untuk memeriksa pekerjaannya sendiri.
[Echoproof menangkap regresi harga yang tidak dijelaskan oleh niat perubahan]
Daftar isi
- Mengapa Echoproof
- Fitur utama
- Instalasi
- Mulai cepat
- Demo
- Konsep
- Referensi perintah
- Konfigurasi
- Membaca laporan
- Integrasi CI
- Integrasi coding agent (MCP)
- Keamanan dan privasi
- Batasan
- Pengembangan
- Lisensi
Mengapa Echoproof
Saat sebagian besar kode ditulis oleh AI agent, jumlah perubahan naik jauh lebih cepat daripada kemampuan manusia untuk meninjaunya. Tes yang lulus dan diff yang tampak rapi belum menjamin perilaku sistem tetap benar, karena tes ditulis dari asumsi, sedangkan bug sering muncul dari kombinasi data nyata yang tidak terpikirkan.
Echoproof menjawab satu pertanyaan yang tidak dijawab oleh tes unit maupun code review:
Apakah perubahan ini mengubah perilaku sistem terhadap traffic nyata, dan apakah perubahan itu memang yang dimaksud?
Contoh yang ditangkap Echoproof: sebuah PR berniat "menambah field currency di katalog", tetapi tanpa sengaja salah menempatkan satu argumen. Akibatnya harga 3 dari 8 menu berubah, sementara 5 menu lainnya tetap benar. Tes unit lulus dan diff kode terlihat wajar. Echoproof melaporkan products[*].price: 18000 -> 22000 pada setiap request katalog dan menandainya sebagai regresi.
Fitur utama
- Rekam dari traffic nyata. Reverse proxy yang merekam setiap request dan response, dengan data sensitif disamarkan sebelum ditulis ke disk.
- Diff semantik. JSON dibandingkan per field, bukan per baris teks. Perubahan dikelompokkan per endpoint dan field, lalu diklasifikasikan sebagai
breaking,behavior, atauadditive. - Tahan noise. UUID, timestamp, dan nilai acak dikenali otomatis. Field yang berubah sendiri antar-run dipelajari dengan me-replay build lama dua kali.
- Aman terhadap state. Request tulis tidak di-replay kecuali diizinkan per endpoint. Build lama dan baru dibandingkan di atas data yang sama, dengan perintah reset di antara setiap putaran.
- Sadar niat perubahan. Setiap kelompok perubahan bisa dinilai oleh Claude terhadap deskripsi PR atau tugas agent. Perubahan yang tidak dijelaskan oleh niat ditandai sebagai regresi.
- Siap untuk CI dan agent. Exit code untuk gate merge, laporan Markdown untuk komentar PR, JSON untuk otomasi, dan server MCP untuk coding agent.
Instalasi
Homebrew (macOS dan Linux)
Binary siap pakai (disarankan)
Unduh arsip untuk platform Anda dari halaman rilis, atau lewat terminal:
Dengan Cargo
Jika Rust 1.85 atau lebih baru sudah terpasang:
Dari source code
Kebutuhan: Rust 1.85 atau lebih baru. curl diperlukan untuk menjalankan demo.
Binary echoproof dipasang di ~/.cargo/bin. Pastikan folder itu ada di PATH:
Mulai cepat
Langkah berikut memeriksa sebuah perubahan kode pada service yang berjalan di lingkungan uji Anda.
1. Buat file konfigurasi (opsional, semua pengaturan punya nilai default):
2. Rekam traffic. Jalankan proxy di depan service, lalu arahkan aplikasi, Postman, atau tes otomatis ke alamat proxy:
Hentikan dengan Ctrl-C setelah traffic yang representatif terkumpul.
Aplikasi Laravel bisa merekam tanpa proxy dengan echoproof/laravel: jalankan composer require echoproof/laravel, isi ECHOPROOF_RECORD=true di .env, dan traffic ditulis ke storage/echoproof/traffic.jsonl dengan aturan sensor yang sama.
3. Jalankan dua build, versi sebelum perubahan (base) dan sesudahnya (PR), memakai database yang sama.
4. Bandingkan:
5. Baca hasilnya. Exit code 0 berarti tidak ada perubahan yang tidak diharapkan, 1 berarti ada regresi, 2 berarti terjadi error. Lihat Membaca laporan.
Untuk menilai perubahan terhadap niatnya, tambahkan deskripsi PR dan diff kodenya:
Demo
Demo lengkap berjalan sekitar 10 detik dan tidak membutuhkan service Anda sendiri:
Demo memakai backend POS kecil (examples/demo-shop) yang memiliki state, yaitu stok produk yang berkurang setiap ada order. Sebuah "PR dari agent" berniat menambah field currency pada produk, tetapi juga mengubah cara diskon promo dan voucher digabungkan.
Konsep
Snapshot
Snapshot adalah file JSONL berisi satu pasangan request dan response per baris. Header dan field sensitif sudah disamarkan sebelum ditulis. Snapshot yang sama dapat dipakai berulang kali untuk memeriksa banyak PR.
Dua mode perbandingan
Pada mode base vs PR, response hasil rekaman tidak dipakai sebagai acuan. Echoproof memutar traffic yang sama ke kedua build di atas data yang sama:
Alamat server masing-masing build (misalnya http://127.0.0.1:8001 di URL gambar atau link pagination) dinormalkan otomatis, sehingga dua build yang berjalan di port berbeda tetap sebanding.
Mode aman
Secara default, hanya method GET, HEAD, dan OPTIONS yang di-replay. Request tulis dilewati dan tidak dihitung lulus: laporan menyebut jumlahnya dan memperingatkan bahwa perilakunya belum terverifikasi.
Izinkan request tulis per endpoint, hanya terhadap lingkungan yang boleh diubah atau dapat di-reset:
Gunakan --reset (atau replay.reset) untuk mengembalikan state sebelum setiap putaran, misalnya dengan me-restore dump database atau memanggil endpoint reset di lingkungan uji. Echoproof menolak me-replay request tulis tanpa reset bila noise sedang dipelajari, karena perubahan state di antara run akan ikut dianggap noise dan menyembunyikan regresi.
Diff semantik
-
JSON dibandingkan per field.
5dan5.0dianggap sama, dan urutan key diabaikan. -
Setiap perubahan diklasifikasikan:
-
Path dinormalkan:
/products/42menjadiGET /products/{id}, danitems[3].pricemenjadi$.items[*].price. Setiap perubahan dihitung sekali per request. -
UUID, ULID, dan date-time dengan bentuk yang sama dianggap noise. Tanggal saja (misalnya
2026-10-14) tetap dibandingkan.
Niat perubahan
Ada dua cara memberi tahu Echoproof perubahan apa yang diharapkan.
--expect meloloskan semua perubahan di endpoint yang disebut. Jika sebuah PR memang mengubah katalog tetapi tanpa sengaja juga merusak harga di katalog, --expect "GET /catalog" tidak akan menangkapnya.
Dengan --intent, setiap kelompok perubahan dinilai oleh Claude dan diberi verdict intended, regression, atau unclear, beserta alasan yang mengutip nilai contoh. Bahan penilaiannya meliputi niat perubahan, diff kode (opsional), persentase request yang terdampak, contoh request yang berubah beserta nilai sebelum dan sesudah, serta contoh request di endpoint yang sama yang tidak berubah sebagai pembanding. Verdict unclear dan kelompok yang tidak dinilai diperlakukan sebagai regresi (fail closed).
Penilaian niat membutuhkan API key Anthropic. Satu run melakukan satu panggilan API, dan hanya jika ada perubahan. Biaya tipikal sekitar USD 0,01 sampai 0,02 per run dengan model default.
Panggilan ke pihak ketiga
Service yang memanggil payment gateway, layanan pesan, atau API lain tidak boleh benar-benar menghubunginya saat replay. Dengan echoproof/laravel, panggilan itu direkam bersama setiap request, dan build yang dijalankan dengan ECHOPROOF_REPLAY=true menjawabnya dari rekaman serta memblokir semua panggilan lain. Kedua build menerima jawaban pihak ketiga yang identik, lalu Echoproof membandingkan apa yang dikirim setiap build:
Pada contoh ini response checkout identik; hanya nominal yang dikirim ke gateway yang berubah. Panggilan yang tidak pernah terekam dilaporkan sebagai call added dengan tingkat breaking. Kalau sebuah build melaporkan panggilan yang tidak bisa dibaca Echoproof, request itu gagal dalam check, bukan lolos tanpa verifikasi.
Bahasa apa pun: proxy keluar
Untuk service yang bukan Laravel, atau yang memanggil pihak ketiga lewat SDK dengan klien HTTP sendiri, Echoproof dapat menjadi proxy untuk panggilan keluar service:
Pasang setting proxy dan CA hanya pada service yang diuji. Echoproof sendiri mengabaikan variabel proxy dari environment. Saat replay, proxy tidak punya jalur ke tujuan asli. Klien yang mengabaikan setting proxy (Node sebelum 22.21 tanpa NODE_USE_ENV_PROXY=1, atau kode yang menetapkan proxy sendiri) tetap memanggil service asli, tetapi terlihat sebagai call removed, tidak pernah sebagai lulus; bila memungkinkan, jalankan build uji tanpa jalur jaringan ke luar. Nilai rahasia yang dipantulkan pihak ketiga (API key di URL yang dikembalikan, token di header yang dikembalikan) ikut disensor. Perekaman hanya mengatribusikan panggilan dengan tepat selama request datang satu per satu, jadi rekamlah di staging atau dari traffic hasil skrip.
Referensi perintah
Opsi umum:
Pola endpoint: POST /orders, GET /products/* (* cocok dengan satu segmen), /admin/** (** cocok dengan banyak segmen), atau * untuk semua.
Exit code: 0 lulus atau hanya perubahan yang diharapkan, 1 ada regresi, 2 error (konfigurasi, jaringan, reset gagal, atau penilaian niat gagal).
Konfigurasi
Semua pengaturan bersifat opsional. Jalankan echoproof init untuk membuat file berisi seluruh pengaturan beserta penjelasannya.
Pola ignore: nama saja (updated_at) cocok di kedalaman mana pun. Pola yang diawali $ atau mengandung titik ($.meta.trace_id, items[*].etag) dihitung dari akar body.
Variabel lingkungan:
Membaca laporan
Contoh laporan di terminal:
Format lain:
--format markdownmenghasilkan laporan yang siap dipakai sebagai komentar PR.--format jsonmenghasilkan data terstruktur, termasukfindings: satu kalimat per masalah yang siap dikembalikan ke coding agent.
Setelah perubahan ditinjau dan disetujui, jadikan hasilnya baseline baru:
Integrasi CI
Gunakan GitHub Action Echoproof. Action ini memasang binary rilis, menjalankan echoproof check, menulis laporan ke ringkasan job, dan menyediakan verdict sebagai output:
Regresi menggagalkan step dan memblokir merge. Pakai fail-on-regression: false bila hanya ingin melapor. Di sistem CI lain, pasang binary-nya dan jalankan echoproof check langsung; exit code 1 berarti regresi.
Integrasi coding agent (MCP)
Dalam rekaman ini, Claude Code (Sonnet) diminta merapikan nama kasir di service order. Sebelumnya, bug diskon sudah ditanam di file yang sama. Pemeriksaan gagal, agent menelusuri regresi itu sampai ke bug yang bukan buatannya, memperbaikinya, dan baru menyatakan tugas selesai setelah pemeriksaan lulus.
echoproof mcp menjalankan server Model Context Protocol melalui stdio, sehingga coding agent dapat memeriksa perubahan yang dibuatnya sendiri sebelum menyatakan pekerjaan selesai.
Pasang di coding agent Anda
Pasang binary echoproof lebih dulu (brew install est57/tap/echoproof atau cargo install echoproof). Setiap agent di bawah menjalankan echoproof mcp di folder proyek Anda, sehingga dapat menjangkau build lokal dan file snapshot.
Claude Code, sebagai plugin (disarankan). Plugin ini memasang server MCP dan skill verify-behavior yang memberi tahu Claude kapan dan bagaimana memeriksa perubahannya, sehingga tidak perlu instruksi tambahan di CLAUDE.md:
Dari shell: claude plugin marketplace add est57/echoproof dan claude plugin install echoproof@echoproof.
Claude Code, hanya server MCP:
Cursor (.cursor/mcp.json di proyek, atau ~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), dan klien lain yang membaca peta mcpServers:
VS Code dengan Copilot agent mode (.vscode/mcp.json):
Codex CLI: codex mcp add echoproof -- echoproof mcp, atau di ~/.codex/config.toml:
Gemini CLI: gemini mcp add echoproof echoproof mcp, yang menulis .gemini/settings.json di proyek.
Integrasi Claude Code sudah diuji dari ujung ke ujung. Klien lain memakai MCP stdio standar yang sama tetapi belum diuji; laporan pemakaian sangat diterima. Asisten berbasis web seperti ChatGPT dan Claude.ai tidak dapat memakai Echoproof, karena berjalan di server penyedianya dan tidak dapat menjangkau build di komputer Anda.
Echoproof terdaftar di MCP Registry resmi dengan nama:
mcp-name: io.github.est57/echoproof
Tool
Alur kerja agent: mengubah kode, menjalankan build, memanggil echoproof_check dengan tugasnya sebagai intent, lalu jika hasilnya regresi, membuka contoh dengan echoproof_exchange, memperbaiki kode, dan memeriksa ulang. Server sengaja tidak menyediakan accept, karena menyetujui baseline baru tetap keputusan manusia.
Keamanan dan privasi
Data yang direkam
- Header dan field yang terdaftar di
[sanitize]disamarkan menjadi[REDACTED]sebelum ditulis ke disk. Tambahkan field yang memuat data pribadi di domain Anda, misalnya nomor telepon, email, atau nomor identitas. - Snapshot berisi data bisnis. Simpan di luar repository publik atau pastikan masuk
.gitignore.
Data yang dikirim ke Anthropic saat memakai --intent
Teks niat, diff kode (jika diberikan), nama endpoint dan field, jumlah request yang terdampak, serta contoh body request dan nilai sebelum dan sesudah, setelah disamarkan. Body contoh di atas 4.000 karakter dipotong. Tidak ada data yang dikirim jika --intent tidak dipakai.
Pengaman bawaan
- Request tulis tidak di-replay tanpa izin eksplisit per endpoint.
- Path dari snapshot divalidasi agar request dan kredensial yang disisipkan tidak dapat diarahkan ke host lain.
- Response dibatasi 32 MB.
- API key hanya dikirim melalui
https, kecuali kelocalhost. - Teks dari luar (niat, diff, traffic) tidak dapat mengubah struktur prompt penilai, dan tidak dapat merusak tabel di laporan Markdown.
Pengaman untuk coding agent (MCP)
targetdanbasehanya bolehlocalhost, kecuali host didaftarkan di[mcp] allowed_hosts. Replay membawa header darireplay.headers, sehingga agent tidak boleh dapat mengirimnya ke host lain.- Path file (
snapshot,save,code_diff_file) harus berada di dalam folder proyek. Symlink ke luar folder ditolak. - Perintah reset hanya dibaca dari
echoproof.toml, tidak pernah dari agent.
Batasan
- Request tulis membutuhkan lingkungan uji yang dapat di-reset. Tanpa itu, gunakan mode aman, yang hanya memverifikasi request baca.
- Panggilan ke pihak ketiga dijawab dari rekaman lewat echoproof/laravel (klien
HttpLaravel) atau proxy keluar (klien apa pun yang mematuhi setting proxy). Klien yang mengabaikan setting proxy dan dependency non-HTTP (SMTP, antrean, gRPC lewat socket mentah) masih dipanggil sungguhan; yang pertama terlihat sebagaicall removed. - ID antar-request: pada replay berurutan (
concurrency = 1), ID yang dibuat replay berbeda dari rekaman (order 9812 di rekaman, order 57 saat replay) dibawa ke request berikutnya untuk entitas yang sama (/orders/9812,order_id). ID data yang sudah ada saat traffic direkam tidak dapat dipetakan; dengan--base, request seperti itu dilaporkan sebagai not reproduced, bukan dihitung tidak berubah. Matikan pemetaan dengan--no-id-mappingatau[replay] map_ids = false. - Urutan request dijaga dengan replay berurutan (
concurrency = 1). Traffic besar bisa lambat, dan replay paralel hanya aman untuk endpoint tanpa state. - Perubahan yang seharusnya terjadi tetapi tidak terjadi sulit dideteksi, karena Echoproof melaporkan request yang berubah.
- Noise yang jarang muncul dapat lolos dari satu run pembelajaran. Naikkan
--noise-runsatau tambahkan polaignorebila perlu.
Pengembangan
Struktur repository
Menjalankan tes
Eval penilai niat
eval/judge berisi 26 skenario PR berlabel (54 kelompok perubahan) yang mengukur seberapa akurat penilai membedakan perubahan yang diniatkan dari regresi. Pada konfigurasi default, penilai mencatat 100% gate benar pada 78 run, tanpa false alarm. Skenario saat ini sudah tidak cukup sulit untuk membedakan konfigurasi yang lebih baik, sehingga kasus dari sistem nyata sedang ditambahkan. Daftar kasus ada di eval/judge/CASES.md.
Runner menolak berjalan sampai harness disetujui sekali dengan --approve-harness, dan meminta persetujuan ulang setiap kali kode runner, kasus, atau penilai berubah.
Lisensi
Echoproof dilisensikan di bawah salah satu dari dua lisensi berikut, sesuai pilihan Anda:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
Kecuali dinyatakan lain, setiap kontribusi yang Anda kirimkan untuk disertakan dalam proyek ini dilisensikan ganda dengan cara yang sama, tanpa syarat tambahan.
来源:README.md,提交 63d2485
工具
0版本历史
4- v0.4.0最新Oct 15, 2026
- v0.2.1Oct 15, 2026
- v0.1.2Oct 14, 2026
- v0.1.1Oct 14, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分