HypGo Framework — AI-Human Collaborative Design Patterns 版本:0.8.0 | 2026-03

這篇文檔不是使用手冊,而是設計哲學。它記錄了 HypGo 由 HTTP/3 為主軸在轉型為 AI-人機協作框架過程中,所形成的設計模式(Design Patterns)、背後的理論推導、以及對未來軟體開發方式的構想。

我相信:框架的職責正在改變。過去,框架服務的對象是「寫程式的人」。現在,框架必須同時服務「寫程式的人」和「理解程式的 AI」。這不是把 AI 當成附加功能,而是從根本上重新思考框架的資訊架構。

2025 年的 LLM 已經能寫出高品質的程式碼。但在真實專案中,AI 的主要障礙不是「不會寫」,而是「不知道該寫什麼」。具體來說:

上下文取得成本

AI 每次互動都需要消耗 token 來理解專案結構。專案越大,Token消耗越大,一個中等規模的 Go 專案(50 個檔案、10,000 行程式碼),AI 要理解它的 API 表面,可能需要讀取 5,000-15,000 tokens 的原始碼。這些 token 花在「理解」而非「產出」上。

上下文品質問題

即使 AI 讀了所有檔案,從散落在各處的 handler 函式中推斷出完整的 API 行為,仍然是一個有損的過程。AI 可能漏看某個中間件的副作用,可能誤解某個參數的命名慣例,可能不知道某個欄位有業務層面的約束。

驗證缺口

AI 生成了程式碼,但如何知道它是對的?傳統流程依賴人工 code review。但 reviewer 需要同時理解「AI 應該做什麼」和「AI 實際做了什麼」,這本身就是一個高認知負荷的任務。

傳統框架的職責:

開發者 → 寫程式碼 → 框架執行

AI 時代框架的職責:

AI 理解專案 → AI 生成程式碼 → 框架驗證 → 開發者審核
 ↑ │
 └──────────── 框架提供結構化資訊 ───────┘

框架不再只是「執行引擎」,它同時是:

1. 資訊提供者 — 讓 AI 快速理解專案
2. 合約定義者 — 定義什麼是「正確」
3. 驗證執行者 — 自動檢查 AI 的產出

問題:傳統路由註冊只記錄「路徑 → 函式」的對應,AI 要理解一個路由的行為,必須讀取整個 handler 的實作。

解法:路由註冊時同時攜帶結構化的 metadata,描述路由的語義。

傳統:router.POST("/api/users", createUserHandler)
 → AI 需要讀 createUserHandler 的 200 行程式碼
HypGo:router.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "建立使用者",
 Input: CreateUserReq{},
 Output: UserResp{},
 }).Handle(createUserHandler)
 → AI 只需讀 schema metadata:6 行

設計原則:

• 宣告式 > 推斷式 — 明確宣告 Input/Output 型別,不讓 AI 從程式碼推斷
• 非侵入式 — Schema 路由與傳統路由可並存,不強制遷移
• 型別安全 — Input/Output 是 Go struct,編譯器保證型別存在

理論基礎:

這借鑑了 OpenAPI / Swagger 的思想,但反轉了方向。Swagger 是從程式碼生成文檔(code-first),HypGo 是在註冊時同時定義合約(schema-first)。差異在於:Swagger 的文檔是派生物,可能與程式碼不同步;HypGo 的 schema 是註冊過程的一部分,不可能不同步。

問題:AI 每次對話都要「重新探索」專案結構,消耗大量 token。

解法:框架自動產出一份機器可讀的專案快照,AI 讀這一份就夠了。

# .hyp/manifest.yaml — 整個專案的「目錄」
version: "1.0"
framework: HypGo
server:
 addr: ":8080"
 protocol: http2
routes:
 - method: POST
 path: /api/users
 summary: "建立使用者"
 input_type: CreateUserReq
 output_type: UserResp
 handler_names: [controllers.CreateUser]

設計原則:

• 一次讀取 — AI 讀一個檔案就理解整個專案的 API 表面
• 自動同步 — Server 啟動時自動更新,不需要手動維護
• 安全過濾 — 不包含 DSN、密碼、token 等敏感資訊
• 原子寫入 — temp file + rename,防止寫入中途損壞

理論基礎:

Manifest 本質上是專案的「壓縮表示」(compressed representation)。一個 50 個路由的專案,handler 原始碼可能有 10,000 行(~30,000 tokens),但 manifest 只有 ~200 行(~600 tokens)。壓縮比約 50:1。

這不是有損壓縮 — manifest 包含了 AI 做出正確決策所需的全部結構資訊。它省略的是實作細節,而 AI 在大多數情況下不需要實作細節就能理解 API 的意圖。

問題:AI 生成了 handler,如何自動驗證它符合預期?

解法:Schema 不只是文檔,它同時是可執行的合約。框架內建驗證工具,根據 schema 自動測試。

// 一行測試所有 schema 路由
contract.TestAll(t, router)
// 內部行為:
// 1. 遍歷 Schema Registry 的所有路由
// 2. 為每個路由生成最小有效的 Input JSON
// 3. 發送 HTTP 請求
// 4. 驗證 status code(POST → 201、GET → 200)
// 5. 驗證 response body 符合 Output struct 的欄位
// 6. 驗證必填欄位存在

設計原則:

• 零配置 — TestAll 不需要任何測試資料,自動生成
• Schema 即合約 — 同一份 Route 定義同時用於路由註冊、Manifest 生成和測試驗證
• 雙向驗證 — 同時驗證 Input(請求 body)和 Output(回應 body)

理論基礎:

這是 Contract Testing(合約測試)在 AI 上下文中的應用。傳統的 contract testing(如 Pact)用於微服務間的介面驗證。HypGo 將它應用於 AI-人機介面:Schema 是 AI 和 handler 之間的「合約」。

關鍵洞察:當 AI 生成 handler 時,它不需要保證「內部邏輯正確」(那是人的責任),它只需要保證「介面符合合約」(Input/Output 型別正確、狀態碼正確)。Contract Testing 恰好驗證這一點。

問題:程式碼註解是自由文本,AI 很難從中提取結構化的約束資訊。

解法:定義標準化的註解前綴 // @ai:,讓 AI 從註解中直接讀取業務約束。

// @ai:constraint max_items=100
// @ai:security requires_auth
// @ai:deprecated use V2 instead
func ListUsers(c *context.Context) { ... }

設計原則:

• 機器可讀 — @ai: 前綴 + key=value 格式,不是自由文本
• 人類友善 — 仍然是標準 Go 註解,不影響編譯
• 可審計 — hyp chkcomment 掃描所有 exported 區塊,報告缺少標註的位置
• 安全 — 純 AST 分析,不執行使用者程式碼

理論基礎:

這借鑑了 Java 的 Annotation 和 Python 的 Decorator,但刻意選擇了「註解」而非「程式碼」的形式。原因是:

1. 註解不改變程式行為 — 移除所有 @ai: 標註,程式完全不受影響
2. 註解是漸進式的 — 不需要一次標註所有程式碼,可以逐步添加
3. 註解是跨語言的 — 同樣的 @ai: 慣例可以移植到任何語言

問題:AI 修改一個檔案時,不知道會影響多少其他模組。

解法:框架提供 import graph 分析工具,在修改前顯示影響範圍。

$ hyp impact pkg/errors/catalog.go
Impact Analysis: pkg/errors/catalog.go
Package: pkg/errors
Direct dependents (import this package):
 → pkg/contract
 → pkg/diagnostic
 → pkg/scaffold
Affected tests:
 → pkg/errors/*_test.go (19 tests)
 → pkg/contract/*_test.go (24 tests)
 Total: 43 tests
Risk: MEDIUM (3 packages depend on this)

設計原則:

• 純讀取 — 不修改任何檔案,只分析
• 量化風險 — LOW / MEDIUM / HIGH 三級,依據依賴數和測試數
• 可行動 — 列出所有受影響的測試,修改後可直接跑

理論基礎:

軟體工程中的 Change Impact Analysis 已有數十年歷史。HypGo 的創新在於將它整合進 AI 工作流:AI 在修改前先跑 hyp impact,根據風險等級決定是「直接改」還是「先問人」。

這建立了一個自動化的「審慎修改」機制:高風險修改(5+ 依賴、50+ 測試)會被 AI 標記為需要人工確認,低風險修改可以直接執行。

問題:AI 協作功能會不會拖慢生產環境?

解法:所有 AI 協作機制要嘛在啟動時執行,要嘛只在開發時使用,不進入請求熱路徑。

啟動時(一次性成本):
 Schema Registry → 記憶體中的 map(O(1) 查找)
 Manifest 生成 → 寫一次檔案
 AutoSync → temp + rename 原子寫入
開發時(不進入生產):
 Contract Testing → go test
 Impact Analysis → hyp impact
 Annotation Check → hyp chkcomment
每請求(零額外成本):
 路由查找 → Radix Tree(與無 schema 時完全相同)
 中間件鏈 → 與無 AI 功能時完全相同
 回應生成 → 與無 AI 功能時完全相同

設計原則:

• 啟動成本 ≠ 運行成本 — Schema metadata 佔用啟動記憶體,但不影響每請求延遲
• 開發工具 ≠ 生產依賴 — Contract Testing、Impact Analysis 是 CLI 工具,不編譯進生產二進位
• 可測量 — 有 AI 功能和無 AI 功能的 benchmark 應該在誤差範圍內

理論基礎:

這借鑑了 C++ 的「零成本抽象」哲學:你不使用的功能不應該有成本,你使用的功能應該和手寫一樣高效。

在 HypGo 的語境中,這意味著:

• 如果你不使用 Schema(),路由的效能與傳統框架完全相同
• 如果你使用 Schema(),每請求的效能仍然與傳統框架完全相同(metadata 只在啟動時和測試時被存取)
• 唯一的成本是啟動時多花幾毫秒建構 Schema Registry 和寫 Manifest 檔案

六個模式不是獨立的功能,它們形成一個閉環:

 ┌──────────────────────────────────────┐
 │ │
 ▼ │
 1. Schema-first 註冊 │
 │ │
 ▼ │
 2. Manifest 自動生成 ──→ AI 讀取 │
 │ │
 ▼ │
 3. AI 理解專案 ──→ AI 生成程式碼 │
 │ │
 ▼ │
 4. Contract Testing 自動驗證 │
 │ │
 ├─ 通過 → 合併程式碼 │
 │ │
 └─ 失敗 → AI 修正 ──→ Impact Analysis │
 │ │
 ▼ │
 確認影響範圍 ─────────┘

每個環節都有明確的輸入和輸出:

閉環的關鍵特性:

1. 自動化 — 從 Schema 註冊到 Contract 驗證,無需人工介入
2. 增量 — 每次只需處理變更的部分,不需要重新理解整個專案
3. 可回溯 — 任何環節失敗,都有明確的上游原因和修復路徑

HypGo 的 Contract Testing 不是取代 TDD,而是補充它。

TDD: 寫測試 → 寫程式碼 → 測試通過
HypGo: 寫 Schema → AI 寫程式碼 → Contract 驗證 → 人寫業務測試

Contract Testing 驗證的是「介面合約」(型別對不對、狀態碼對不對),TDD 驗證的是「業務邏輯」(計算結果對不對、邊界條件對不對)。兩者互補。

Schema-first 路由和 Typed Error Catalog 與 DDD(Domain-Driven Design)的 Ubiquitous Language 有相似之處:它們都在程式碼中建立了一套共享的詞彙表。

差異在於 DDD 的詞彙表服務於「團隊溝通」,HypGo 的詞彙表服務於「AI-人溝通」。但兩者可以合一:一個好的 Schema 定義同時是好的 DDD 語言。

Bertrand Meyer 在 1986 年提出的 Design by Contract(契約式設計)強調前置條件、後置條件和不變式。HypGo 的 Contract Testing 是它在 AI 上下文中的現代實現:

• 前置條件 = Input Schema(請求 body 必須符合 struct 定義)
• 後置條件 = Output Schema + Status Code(回應必須符合宣告)
• 不變式 = Annotation Protocol(@ai:constraint 標註的業務約束)

我相信AI是工具,而人的角色必不可少

目前的流程是:人決定做什麼 → AI 執行 → 人驗證。

下一步可能是:AI 主動提議 → 人審核 → AI 執行。在這個模式下,框架需要提供更多「意圖推斷」的能力:

• Schema 中的 Tags 可以讓 AI 推斷「這個路由屬於哪個業務模組」
• Annotation 中的 @ai:owner team=backend 可以讓 AI 知道「誰負責這段程式碼」
• Impact Analysis 的風險等級可以讓 AI 自動決定「這個修改需不需要人工確認」

Manifest 的格式是標準化的。理論上,一個 AI 如果理解了 A 專案的 manifest,它對 B 專案的 manifest 的理解成本趨近於零。

這意味著 AI 可以在專案之間遷移「架構知識」:

• 「A 專案的 user 路由是這樣設計的,B 專案也需要 user 路由,那就用類似的結構」
• 「A 專案的 error catalog 用了 E1001 到 E1050,B 專案可以從 E2001 開始」

目前的安全設計是靜態的(所有路由共用同一套中間件)。未來可以根據 Schema 的 @ai:security 標註自動調整安全等級:

// @ai:security level=public
r.GET("/health", healthHandler) // 不需要 auth
// @ai:security level=authenticated
r.GET("/api/profile", profileHandler) // 需要 JWT
// @ai:security level=admin
r.DELETE("/api/users/:id", deleteHandler) // 需要 JWT + admin role

框架可以根據標註自動選擇中間件鏈,而不是讓開發者手動配置。

HypGo 的人機協作設計模式不是一套「AI 功能」,而是一種資訊架構的重新設計。

核心洞察只有一個:程式碼是給機器執行的,但理解程式碼的成本是給人(和 AI)承擔的。框架可以降低這個理解成本,方法是在程式碼旁邊放置結構化的 metadata。

六個模式的本質:

1. Metadata-First — 降低理解成本
2. Manifest — 降低探索成本
3. Contract — 降低驗證成本
4. Annotation — 降低約束發現成本
5. Impact — 降低風險評估成本
6. Zero-Cost — 以上所有都不增加運行成本

當這六個成本都趨近於零時,AI-人機協作就不再是「AI 幫你寫程式碼」,而是人和 AI 共同維護一個持續演進的系統。

HypGo · AI-Human Collaborative Design Patterns · 2026-03