人機協作設計模式：理論與構想

HypGo Framework — AI-Human Collaborative Design Patterns 版本：0.8.1 | 2026-03

---

前言

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

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

---

第一部分：問題定義

1.1 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 實際做了什麼」，這本身就是一個高認知負荷的任務。

1.2 重新定義框架的職責

傳統框架的職責：

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

AI 時代框架的職責：

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

框架不再只是「執行引擎」，它同時是：

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

---

第二部分：六個設計模式

模式一：Metadata-First Registration（元數據優先註冊）

問題：傳統路由註冊只記錄「路徑 → 函式」的對應，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 是註冊過程的一部分，不可能不同步。

模式二：Project Manifest（專案快照）

問題：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 的意圖。

模式三：Contract-Driven Validation（合約驅動驗證）

問題：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 恰好驗證這一點。

模式四：Structural Annotation（結構化標註）

問題：程式碼註解是自由文本，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: 慣例可以移植到任何語言

模式五：Impact-Aware Modification（影響感知修改）

問題：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 標記為需要人工確認，低風險修改可以直接執行。

模式六：Zero-Cost Abstraction for AI（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   │
                                │              │
                                ▼              │
                          確認影響範圍 ─────────┘

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

環節	輸入	輸出	工具
註冊	Go struct + 路由路徑	Schema Registry 條目	router.Schema()
快照	Schema Registry + Config	YAML/JSON manifest	hyp context / AutoSync
理解	manifest.yaml	AI 的專案理解	LLM 讀取
生成	AI 的理解 + 需求	handler 程式碼	LLM 生成
驗證	handler + Schema	測試結果（pass/fail）	contract.TestAll()
影響	修改的檔案	依賴圖 + 風險等級	hyp impact

閉環的關鍵特性：

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

---

第四部分：與現有方法論的關係

與 TDD 的關係

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

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

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

與 DDD 的關係

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

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

與 Design by Contract 的關係

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

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

---

第五部分：對未來的構想

5.1 從「AI 輔助」到「AI 主導」

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

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

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

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

5.2 跨專案知識遷移

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

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

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

5.3 自適應安全等級

目前的安全設計是靜態的（所有路由共用同一套中間件）。未來可以根據 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