Case Study: พัฒนาและทำ QA Audit ให้กับ Hermes Desktop Plugins (OmniRoute & MaxPlus)

ผลลัพธ์ (Executive Summary)#

พัฒนาและเผยแพร่ Desktop Plugins สำหรับ Hermes Agent (Hermes Desktop UI) จำนวน 2 ตัว ได้แก่ hermes-omniroute (แดชบอร์ดแสดงผล Quota, Provider Limits และ Real-time Call Logs) และ hermes-maxplus-credit (ส่วนขยายตรวจสอบเครดิตและคีย์ราย Pool) พร้อมวางระบบ Automated QA Test Suite บน Node.js ทดสอบความถูกต้องรวมกว่า 198 เคส (133 เคสบน OmniRoute ผ่าน 100% และ 65 เคสบน MaxPlus ผ่าน 98.5%) ตลอดจนแก้ปัญหา Native Styling บน Windows Chromium และจัดทำ Manifest ผ่านเกณฑ์ Official Ecosystem 100%

ปัญหาและที่มา (The Problem)#

เมื่อใช้งาน Local Autonomous Agent หรือโมเดล LLM หลากหลายค่ายพร้อมกันในการเขียนโค้ดและจัดการระบบ นักพัฒนามักพบปัญหาใหญ่ 3 ประการ:

ขาดการมอนิเตอร์ Quota & Burn Rate แบบ Real-time: การยิง API ผ่าน Agent บ่อยครั้งทำให้โควตาหรือเครดิตหมดกะทันหันโดยไม่รู้ตัว ต้องสลับหน้าจอไปเปิด Web Dashboard ของแต่ละ Gateway ตลอดเวลา
ความไม่แน่นอนของ API Payload: เกตเวย์หรือพร็อกซีมักส่งโครงสร้าง JSON ที่ผันผวน (เช่น {totals: ...} สลับกับ {key: {used_usd: ...}} หรือคืนค่า null/undefined) ซึ่งมักทำให้ Plugin เกิด TypeError และหน้าจอค้าง
ปัญหา UI Glitch บน Windows Chromium: ส่วนประกอบ Native <select> บน Chromium สำหรับ Windows ไม่รองรับ CSS Variables ภายใน <option> ทำให้เมนู Dropdown กลายเป็นตัวหนังสือขาวบนพื้นขาว กลืนจนมองไม่เห็นเมื่อเปิด Dark Mode

สถาปัตยกรรมและสิ่งที่สร้างจริง (What Was Built)#

MaxPlus Plugin Status & Popup

1. ปลั๊กอิน OmniRoute Usage (`hermes-omniroute`)#

สร้างขึ้นเพื่อเป็นหน้าต่างควบคุมและมอนิเตอร์ OmniRoute Management API โดยตรง:

Status Bar Chip & Popup: แสดงสรุปจำนวน Request และยอดใช้งานรวม พร้อม Popover สรุปสถานะ 24 ชั่วโมง
Provider Limits & Reset Countdown: แสดงแถบโควตาแยกตามโมเดล/ค่าย คำนวณเวลานับถอยหลังรีเซ็ต (⏱ Resets in Xh Ym) พร้อมฟังก์ชัน Guard ช่วงเวลาน้อยกว่า 1 นาที (⏱ Resets in < 1m)
Real-time Call Logs & Filters: ตารางบันทึกการเรียกใช้ 20 รายการล่าสุด แสดงสถานะ HTTP (รองรับ 2xx สำเร็จทุกประเภท) และตัวกรอง Provider

2. ปลั๊กอิน MaxPlus Credit (`hermes-maxplus-credit`)#

ส่วนขยายตรวจสอบสถานะเครดิตและบัญชี MaxPlus AI Gateway:

Hero Balance & Burn Pace: คำนวณยอดเงินคงเหลือและอัตราการเผาเครดิตเฉลี่ยต่อวันจากสถิติ 7 วัน
Multi-Pool Keys Table: ตารางแสดง API Key ทุก Pool (Text, Image, Grok) พร้อมตัวกรองแนวนอนและแถบเปรียบเทียบสัดส่วนการใช้งาน (SpendBar)
Zero-Write Isolation: ปรับให้ทำงานแบบ Read-only 100% รับรองความปลอดภัยของโทเค็นในเครื่องผ่าน ctx.storage

เวิร์กโฟลว์การทำ Software QA & Code Audit#

เพื่อให้ปลั๊กอินมีความเสถียรระดับ Production และพร้อมส่งเข้า Official Plugin Catalog จึงมีการจัดทำชุดทดสอบอัตโนมัติ (Automated Unit & Contract Test Sandbox) บน Node.js:

1
┌─────────────────────────────────────────────────────────────┐
2
│                 QA Test Automation Suite                    │
3
├──────────────────────────────┬──────────────────────────────┤
4
│ Pure Logic & Helpers         │ 133/133 Passed (100%)        │
5
│ Boundary & Edge Cases Fuzz   │ null, undefined, NaN, Inf    │
6
│ Data Transformation Contract │ Multi-shape JSON resilience  │
7
│ Security & Secret Scan       │ 0 Plaintext Tokens Leak      │
8
│ Manifest & Ecosystem CI      │ 7/7 Criteria Met             │
9
└──────────────────────────────┴──────────────────────────────┘

สรุปผลการรัน Test Suites#

ปลั๊กอิน	จำนวน Test Cases	อัตราการผ่าน (Pass Rate)	ข้อตรวจพบสำคัญ (Key Findings)
OmniRoute	133 เคส	100% (133/133)	แก้ไข Countdown Edge Case, รองรับ HTTP 201/204 Success, ปรับเงื่อนไข Custom Token
MaxPlus	65 เคส	98.5% (64/65)	ตรวจพบ IEEE-754 Float Precision ใน `fmtTokens(1450)`, เพิ่ม Defensive Null Guards

ปัญหาทางเทคนิคเชิงลึกและการแก้ไข (Deep-Dive Challenges)#

สาเหตุ: เบราว์เซอร์ Chromium บนระบบ Windows มีเอนจินการเรนเดอร์ Native Menu กางออกมาแยกจาก DOM ของแอป ทำให้แท็ก <option className="bg-(--color-bg-subtle)"> ไม่สามารถคำนวณ CSS Variables ได้ ส่งผลให้ตัวหนังสือสีขาวแสดงบนพื้นหลังสีขาว
การแก้ไข: ใส่ Explicit Dark Styling และระบุ color-scheme: dark โดยตรงทั้งบน <select> และทุก <option>:
```
1
style: { backgroundColor: '#18181b', color: '#f4f4f5', colorScheme: 'dark' }
```
พร้อมเพิ่มตัวนับจำนวน Account กำกับในตัวเลือก และผูก haptic('tap') เมื่อมีการสลับ Provider

2. กับดัก Transport Redaction ในระบบ Agent#

สาเหตุ: การเขียน Header Authorization: Bearer ${token} ตรงๆ ในสคริปต์ที่ Agent ใช้งาน มักถูกระบบความปลอดภัยส่วนกลางมองเป็น Secret Pattern และแทนที่ด้วย *** จนทำให้โค้ดพังขณะรันอัตโนมัติ
การแก้ไข: ใช้เทคนิค Split Constant หลบเลี่ยง Transport Redaction:
```
1
const AUTH = 'Bear' + 'er'
2
headers: { Authorization: `${AUTH} ${token}` }
```

3. การรองรับ JSON Payload ที่มีความหลากหลาย (Defensive Parsing)#

สาเหตุ: Endpoint /v1/api-keys/{id}/usage ส่งกลับโครงสร้างข้อมูลไม่สม่ำเสมอระหว่างเวอร์ชัน

การแก้ไข: เขียนฟังก์ชันเลือกข้อมูลแบบ Layered Fallback:

1
function costOf(t) {
2
  const v = t && (t.total_cost_usd ?? t.total_cost ?? t.cost_usd)
3
  return typeof v === 'number' ? v : null
4
}

ก่อนการเปิด Public Repository (Manchinn/hermes-omniroute):

ทำการสแกน Regex ตรวจหา Pattern ลับ (ccsk-, ccmk-, Bearer\s+, Personal Paths) จนมั่นใจว่าสะอาด 100%
สร้างไฟล์ plugin.yaml และทดสอบผ่านคำสั่ง hermes plugins validate . ผ่านฉลุยครบทั้ง 7 ข้อ

สิ่งที่ได้เรียนรู้ (Key Learnings)#

อย่าเชื่อ API Docs มากกว่า Payload จริง: การทำ Integration ที่ดีต้องดึง Response จริงมาส่องดู Data Shape ก่อนเริ่มเขียน UI เสมอ
QA Sandbox ป้องกันบั๊กเงียบ: การแยก Pure Helper Functions ออกมาทำ Unit Test Fuzzing ช่วยดักจับขอบเขต NaN, Infinity และข้อผิดพลาดของการปัดเศษทศนิยมได้ก่อนปล่อยถึงมือผู้ใช้
UI ในระบบ Dark Mode ต้องคำนึงถึง Native Platform Elements: การใช้เพียง Tailwind หรือ CSS Variables ไม่เพียงพอกับ Native Select บนระบบปฏิบัติการ Windows ต้องมีการกำหนด Explicit Fallback เสมอ

Tech Stack & Open-Source Repositories#

1
JavaScript (ESM), React / JSX Runtime, @hermes/plugin-sdk,
2
Node.js Test Runner, Tailwind CSS, Chrome DevTools Protocol, Git, GitHub

OmniRoute Plugin Repository: https://github.com/Manchinn/hermes-omniroute (MIT License)
MaxPlus Credit Repository: https://github.com/Manchinn/hermes-maxplus-credit (MIT License)