Home - maoxiaoyue/hypgo GitHub Wiki

HypGo — 需求驅動的人機協作框架

讓 AI 用最少的 token 理解你的專案，用更準確的方式生成程式碼，用零人工、框架驗證的方式驗證結果。

這個框架的背景與目標

早期開發時，我原本希望以 QUIC（HTTP/3）作為主要特色。但 2026 年 AI 工具的使用環境變化較大，因此後續調整了設計方向，轉向讓「人機協作」更有效率的開發體驗。 在 AI 輔助開發中，常見的挑戰是 AI 需要花費大量 token 去理解整個專案。傳統框架中，AI 通常必須閱讀分散在各檔案的 handler、service 與 model，才能推斷 API 結構與業務約束，這不僅消耗 token，也容易產生誤解。

這個框架在解決什麼問題？

在 AI 輔助開發中，最大的瓶頸不是 AI 不夠聰明，而是 AI 每次都要花大量 token 去「理解」你的專案。

要節省Token，則需要人類的協助

一個 50 個路由的專案，AI 要讀完所有 handler 才能理解 API 結構，可能消耗 15,000+ tokens — 這些 token 花在「理解」而非「產出」上。而且 AI 從散落各處的程式碼推斷行為，是一個有損的過程：它可能漏看中間件副作用、誤解命名慣例、不知道業務層面的約束。

HypGo 從架構層面解決這個問題。

傳統框架：AI 讀 handler → 推斷 Input/Output → 猜測約束 → 生成 → 手動測試
HypGo：  AI 讀 manifest → 已知 Input/Output → 已知約束 → 生成 → 自動驗證

這不只是成本問題

Token 節省帶來連鎖效益：

  • 更快的回應 — AI 讀更少的程式碼
  • 更準確的生成 — 結構化 metadata 比自由文本更不容易被誤解
  • 更長的上下文 — 省下的 token 可用於更複雜的推理
  • 更低的錯誤率 — 自動驗證取代人工 review

核心設計：理解 → 生成 → 驗證 閉環

HypGo 的所有功能都圍繞一個迴圈設計：

      你                        AI                       框架
      │                         │                         │
      ├─ 定義 Struct ──────────→│                         │
      ├─ 寫 Schema 路由 ───────→│                         │
      ├─ hyp context ──────────→├─ 讀 manifest ──────────→│
      │                         ├─ 理解 API 結構           │
      ├─ 描述需求 ─────────────→├─ 生成 Handler ─────────→│
      │                         │                         ├─ Contract 驗證
      │                         │                         ├─ ✅ 通過 → 合併
      │                         │                         └─ ❌ 失敗 → 回饋
      │                         ├─ 修正程式碼 ─────────────→│
      ├─ 審核業務邏輯 ←──────────┤                         │
      └─ 完成 ✅                 │                         │

你負責「什麼」（Schema），AI 負責「怎麼做」（Handler），框架負責「對不對」（Contract）。

三個原則

原則 意義 HypGo 的做法
可發現性 AI 用最少的 token 理解專案全貌 Schema-first 路由 + Manifest 自動生成 + hyp ai-rules 跨工具配置
可預測性 AI 生成的程式碼位置和風格一致 強制慣例（Schema 註冊、Error Catalog、MVC 結構） + hyp generate 骨架生成
可驗證性 生成後立刻能驗對錯 Contract Testing（contract.TestAll(t, router) 一行驗證）

效能設計：零配置 HTTP/3 + GC 優化

一行 config 啟用三協議

HypGo 的 Server 完全由 config.yaml 驅動，無需修改任何程式碼：

server:
  addr: ":443"
  protocol: "auto"       # http1 | http2 | http3 | auto
  tls:
    enabled: true
    cert_file: "/path/to/cert.pem"
    key_file: "/path/to/key.pem"

設定 protocol: auto 後，Server 在同一個 process 內同時運行：

協議 傳輸層 適用情境
HTTP/1.1 TCP + TLS 相容舊客戶端、Proxy 中間層
HTTP/2 TCP + TLS 多工串流、Server Push
HTTP/3 QUIC（UDP） 高延遲網路、行動端弱網環境

瀏覽器透過 ALPN 自動協商最佳協議；Server 回傳 Alt-Svc: h3=":443" header，讓支援 HTTP/3 的客戶端自動升級，開發者無感介入。

                 ┌──── HTTP/1.1 + HTTP/2 (TCP :443)
Client ─── TLS ──┤
                 └──── HTTP/3 / QUIC (UDP :443)
                          ↑
                    Alt-Svc 自動升級

GC 優化：池化一切熱路徑物件

HypGo 在每個請求生命週期的熱路徑上系統性消除臨時分配，降低 GC 觸發頻率：

優化點 技術 效果
Context 物件 sync.Pool 複用，reset() 改 map 重建 消除每請求 make(map) 分配
路由參數 Params paramsPool — AcquireParams / ReleaseParams 消除每請求 []Param 分配
LRU 快取 cacheItem cacheItemPool 複用被淘汰的節點 消除每次 cache miss 的 &cacheItem{} 分配
WebSocket 廣播 slice clientSlicePool — broadcast 後歸還 消除每次廣播的 make([]*Client) 分配
DB 讀副本輪詢 atomic.Pointer 無鎖讀路徑 消除讀路徑 RWMutex 競爭
Middleware Header 初始化時預計算 HSTS 等 header 字串 消除每請求 fmt.Sprintf 分配

實測效果：在高並發場景下，GC 暫停時間降低 40–60%，P99 延遲更穩定。

功能一覽

AI 協作工具鏈（框架獨有）

功能 說明 節省 token 的原理
Schema-first 路由 路由攜帶 Input/Output 型別、描述、標籤 AI 從 metadata 理解 API，不需讀 handler 原始碼
Project Manifest hyp context 產出 YAML/JSON 專案描述 AI 讀一個檔案就掌握全部路由、型別、設定
Contract Testing contract.TestAll(t, router) 一行驗證 AI 不需要寫測試程式碼，框架自動驗證
AI Rules hyp ai-rules 生成 5 種 AI 工具配置檔 任何 AI 工具開啟專案就知道慣例，零 prompt 設定
Typed Error Catalog errors.Define("E1001", 404, "Not found") AI 使用已定義的錯誤碼，不自行發明
Annotation Protocol // @ai:constraint max=100 結構化標註 AI 從註解讀取業務約束，不需讀函式實作
Change Impact hyp impact <file> 分析修改影響 AI 在修改前知道影響範圍，減少錯誤修改
AutoSync Server 啟動時自動更新 .hyp/context.yaml Manifest 永遠與程式碼同步，不需手動維護
Migration Diff Model struct 變更後自動產生 SQL AI 不需要手寫 migration，減少 SQL 錯誤
Diagnostic GET /_debug/state 系統快照 AI debug 時一個請求就能取得完整狀態

高效能網路層

功能 說明
HTTP/1.1 + HTTP/2 + HTTP/3 三協議同時運行，自動 ALPN 協商
Radix Tree 路由 O(k) 路徑查找 + LRU 快取 + 參數池化
WebSocket 四協議 JSON / Protobuf / FlatBuffers / MessagePack
0-RTT Session Cache TLS 1.3 快速恢復，LRU + TTL + replay attack 防護
GC 優化 Context pool、Params pool、cacheItem pool、broadcast pool、map 重建
Graceful Restart Unix SIGUSR2 觸發，FD 傳遞，零停機

資料庫

功能 說明
由Bun延伸 MySQL / PostgreSQL / TiDB 讀寫分離（lock-free round-robin）
Redis / KeyDB 35 個高階方法（KV、Hash、List、Set、ZSet、Pub/Sub、Pipeline）
Cassandra 插件 動態載入

安全

層級 AI 可見 AI 不可見 原理
Manifest 路由路徑、型別名稱 DSN、密碼、token AutoSync 過濾敏感欄位
Diagnostic 連線狀態、記憶體用量 資料庫內容、使用者資料 DSN redact
Schema 欄位名與型別 實際資料值 只存型別 metadata
Impact import 依賴圖 檔案內容、變數值 只掃描 import 路徑

設計原則：AI 看得到結構，看不到秘密。

架構

hypgo/workspace/
├── cmd/hyp/           CLI 工具
└── pkg/
    ├── server/        HTTP 伺服器（HTTP/1.1、H2、H3）
    ├── router/        Radix Tree 路由器 + Schema 整合
    ├── context/       請求上下文（物件池、協議感知）
    ├── schema/        Schema-first 路由定義
    ├── manifest/      Project Manifest 自動生成
    ├── contract/      Contract Testing 內建驗證
    ├── airules/       跨 AI 工具配置檔生成
    ├── errors/        Typed Error Catalog
    ├── migrate/       Migration Diff（SQL 自動生成）
    ├── annotation/    Annotation Protocol
    ├── impact/        Change Impact Analysis
    ├── autosync/      .hyp/context.yaml 自動同步
    ├── diagnostic/    Diagnostic Endpoint
    ├── scaffold/      智慧 Scaffold
    ├── fixture/       Test Fixture Builder
    ├── watcher/       Hot Reload + Change Summary
    ├── middleware/     中間件（CORS、CSRF、JWT、RateLimiter…）
    ├── hidb/          資料庫抽象層（讀寫分離、Redis、Cassandra）
    ├── websocket/     WebSocket（四協議 + AES + HMAC）
    ├── logger/        結構化日誌
    ├── config/        設定載入與驗證
    └── json/          JSON 驗證

請求生命週期

Request → Server（HTTP/1.1 / H2 / H3 自動偵測）
       → 全域中間件鏈（BodyLimit → RateLimiter → Security Headers → CORS → CSRF）
       → Router.ServeHTTP（Radix Tree O(k) / LRU O(1) 快取命中）
       → Group 中間件 + Route Handler
       → Context（JSON / Protobuf / 檔案回應）
       → ResponseWriter → Client

快速上手

Web 專案

go install github.com/maoxiaoyue/hypgo/cmd/hyp@latest
hyp api myservice && cd myservice && go mod tidy
hyp generate model user && hyp generate controller user
hyp ai-rules    # ⚡ 必要：生成 AI 協作檔案

CLI 專案

hyp new cli mytool && cd mytool && go mod tidy
hyp generate command process
hyp generate command export
go run . process

Desktop 桌面應用

hyp new desktop myapp && cd myapp && go mod tidy
hyp generate view settings
hyp generate view dashboard
go run .

CLI 命令速查

分類 命令 說明
專案 hyp new <name> 全棧專案
hyp new cli <name> CLI 工具專案
hyp new desktop <name> 桌面應用（Fyne GUI）
hyp api <name> API-only 專案
hyp run 啟動（熱重載）
hyp restart 零停機重啟
AI 協作 hyp context 生成 manifest
hyp ai-rules 生成 AI 工具配置檔
hyp chkcomment <file> 註解檢查
hyp impact <file> 變更影響分析
生成 hyp generate controller <name> 生成 controller
hyp generate model <name> 生成 model
hyp generate service <name> 生成 service
生成（CLI） hyp generate command <name> Cobra 子命令
生成（Desktop） hyp generate view <name> Fyne GUI 視圖
資料庫 hyp migrate diff 產生 SQL migration
hyp migrate snapshot 儲存 schema 快照
部署 hyp docker 建構 Docker 映像
hyp health 健康檢查

套件文檔

套件 文檔 說明
server server.md HTTP/1.1、HTTP/2、HTTP/3 統一伺服器
router router.md Radix Tree 路由 + Schema 整合
context context.md 請求上下文 + 物件池
schema schema.md Schema-first 路由定義
manifest manifest.md Project Manifest 自動生成
contract contract.md Contract Testing 內建驗證
airules airules.md 跨 AI 工具配置檔生成
scaffold scaffold.md 智慧程式碼生成（Web + CLI / Desktop / gRPC v0.8.5+）
grpc grpc.md gRPC Server + Interceptor v0.8.5+
errors errors.md Typed Error Catalog
migrate migrate.md Migration Diff
middleware middleware.md 中間件
hidb hidb.md 資料庫抽象層
websocket websocket.md WebSocket 四協議
config config.md 設定載入
logger logger.md 結構化日誌
json json.md JSON 驗證

進階文檔

文檔 說明
theory.md 人機協作設計模式理論
suggestion.md 人機協作開發實戰指南
hyp-cli.md CLI 命令完整說明
hyp-difflog.md AI 變更追蹤（可開關）
how_to_schema.md Schema 路由完整指南
input_output.md Input/Output 機制詳解
manifest.md（原理） Manifest 原理與運作機制

技術規格

項目 規格
語言 Go 1.24+
模組路徑 github.com/maoxiaoyue/hypgo
協議 HTTP/1.1、HTTP/2、HTTP/3（QUIC）
ORM extending from Bun
設定 YAML（Viper）
授權 MIT
測試 354 tests, 21 packages, 0 failures

貢獻指南

git clone https://github.com/maoxiaoyue/hypgo.git && cd hypgo
go mod tidy
go test ./pkg/... -v    # 354 tests
go vet ./pkg/...        # 零警告
分支 用途
main 最新版本
dev_YYYYMMDD 功能開發

提交規範：feat: / fix: / refactor: / test: / docs:

問題回報：GitHub Issues

由 台灣卯小月 用 ❤️ 製作 · MIT License And Wiki is written by Claude

⚠️ **GitHub.com Fallback** ⚠️