harness.md

maoxiaoyue edited this page May 22, 2026 · 1 revision

HypGo 與 Harness 工程

HypGo 是一個在 Go 應用層實踐 Harness 工程理念的框架。 Harness 解決「如何交付」,HypGo 解決「如何開發出值得交付的東西」——兩者共用同一套工程哲學,只是作用的層級不同。

什麼是 Harness 工程?

Harness 作為一個平台,體現了一套現代軟體工程實踐:

工程實踐	核心理念
Contract-first	先定義合約,再實作,驗證實作是否符合合約
Test Intelligence	測試不靠人寫,系統自動知道要跑哪些、怎麼跑
Change Intelligence	任何改動前,先知道影響範圍
Developer Portal	讓開發者在一個地方理解整個系統的結構
AI-Assisted Development	AI 輔助生成、驗證、解釋工程產物
Reliability Engineering	系統健康狀態隨時可見,主動發現問題
Database Lifecycle	資料庫 schema 變更可追蹤、可自動化

Harness 平台在基礎設施層(Pipeline、部署、監控)實踐這套理念。
HypGo 在 Go 應用層做同樣一件事。

HypGo 實踐了哪些 Harness 工程

Harness 工程實踐 HypGo 的應用層實作
─────────────────────────────────────────────────────
Contract-first → Schema-first 路由 + Contract Testing
Test Intelligence → contract.TestAll() 自動生成測試
Change Intelligence → hyp impact 靜態影響分析
Developer Portal → hyp context / AutoSync Manifest
AI-Assisted Development → hyp ai-rules + Annotation Protocol
Reliability Engineering → /_debug/state 診斷端點
Database Lifecycle → hyp migrate diff SQL 自動生成

Human Inside — 自動化的前提是人的判斷

Harness 工程與 HypGo 共用一個更根本的設計信念:

自動化負責執行機械性工作,人類判斷負責定義「什麼才算對」。

這不是「AI 取代人」,也不是「人工監控機器」——而是人的業務判斷被結構化地嵌入系統之中,成為自動化流程的基準與邊界。

在 Harness 平台層

Harness 的自動化不會無限延伸——它在幾個關鍵點刻意留給人決策:

決策點	為什麼是人?
SLO 定義(99.9% vs 99.99%)	業務可接受的風險,只有人知道
Feature Flag 控制(推出給哪些用戶)	商業策略判斷,不能自動化
Deployment Approval Gate	生產環境變更的最後把關
Change Freeze Window	哪些時段不能部署,由業務決定
Error Budget Policy	燒完 budget 要不要停止部署,是風險偏好

Harness 自動化做的是「按照人定義的規則執行」,不是「代替人定規則」。

在 HypGo 應用層

HypGo 的分工方式完全相同,只是作用在程式碼層級:

 你(人) AI 框架
 │ │ │
 ├─ 定義 Schema ────────→│ │
 │ (業務合約) │ │
 ├─ 寫 @ai:constraint ──→│ │
 │ (業務規則) │ │
 ├─ 定義 Error Catalog ─→│ │
 │ (錯誤語言) │ │
 │ ├─ 生成 Handler ─────→│
 │ │ (機械實作) ├─ Contract 驗證
 │ │ │ (符合人定的合約?)
 ←──── 審閱業務邏輯 ──────┤ ├─ ✅ 通過
 │ (不是語法,是意圖) │ └─ ❌ 回饋 AI 修正
 └─ Done ✅ │

人決策的三件事,對應三個工具:

人的決策	HypGo 工具	說明
這個 API 的輸入/輸出長什麼樣	`r.Schema(Input, Output)`	業務資料結構,AI 無法自行決定
這個 API 有哪些業務規則	`// @ai:constraint max=100`	業務約束,從需求文件來,不從程式碼推導
系統的錯誤語言是什麼	`errors.Define("E1001", 404, ...)`	錯誤碼代表業務語意,必須人工設計

這三件事決定了 Contract Testing 的驗證標準、AI 生成程式碼的品質邊界,以及整個系統的業務語言。它們不能被自動化,因為它們本身就是業務判斷的結晶。

為什麼叫 Human Inside?

傳統的「AI 輔助開發」容易落入兩個極端:

過度自動化:AI 從散落的程式碼推斷業務意圖 → 語法正確,業務錯誤
過度手動:開發者什麼都寫 → 速度慢,重複工作多

HypGo(和 Harness)選擇第三條路:把人的判斷結構化地放在系統的核心位置,讓自動化圍繞它展開。

❌ 錯誤模式:Human → AI → 產出(人在最外層,AI 黑盒決定一切)
❌ 錯誤模式:Human → Human → Human(完全手動,AI 沒有用武之地)
✅ HypGo 模式:Human(定義合約)→ AI(實作)→ 框架(驗證合約)→ Human(審閱業務邏輯)

開發者從「寫每一行實作」升級為「定義每一個業務合約」——更少的機械工作,更多的業務設計。

逐項說明

Contract-first → Schema-first + Contract Testing

Harness 的 Contract-first 理念是:先定義服務間的合約,再實作,驗證實作符合合約。

HypGo 把這個理念落地到 Go 的 API 開發層:

// 1. 先定義合約(你)
r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/orders",
 Summary: "建立訂單",
 Input: CreateOrderReq{}, // ← 合約:請求必須長這樣
 Output: OrderResp{}, // ← 合約:回應必須長這樣
 Responses: map[int]schema.ResponseSchema{
 201: {Description: "Order created"},
 },
}).Handle(createOrderHandler)
// 2. AI 實作 Handler(AI)
// 3. 框架自動驗證合約(框架)
contract.TestAll(t, router)
// → 自動生成測試資料、發送請求、驗證 Input/Output 結構
// → 不需要手寫任何測試 case

Schema 就是合約。Contract Testing 就是合約驗證器。這是 Harness Contract-first 在 Go 框架層的直接實作。

Test Intelligence → contract.TestAll()

Harness Test Intelligence 讓 CI 系統「知道這次變更需要跑哪些測試」,測試選擇由系統決定,不靠人工判斷。

HypGo 在更早的一個層次做同樣的事:測試內容由系統生成,不靠人工撰寫。

Harness Test Intelligence:
 分析 diff → 決定跑哪些測試 → 提交這批測試給 CI 執行
 重點:哪些測試要跑?
HypGo contract.TestAll():
 讀 Schema Registry → 自動生成每條路由的測試資料 → 執行驗證
 重點:測試從哪裡來?

兩者不衝突,而是串聯:

Harness CI 觸發
 → 用 Test Intelligence 選出需要跑的 job
 → 跑 go test(內含 HypGo 自動生成的 contract 測試)
 → 結果回報給 Harness

Change Intelligence → hyp impact

Harness Change Intelligence 讓團隊在部署後知道「哪個版本帶入了問題」。

HypGo 的 hyp impact 把這個能力前移到提交前,在靜態分析層做 Go 程式碼的影響範圍計算:

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

Harness Change Intelligence:程式碼已部署 → 這個版本的變更影響了什麼?
HypGo hyp impact: 程式碼提交前 → 這個改動會波及哪些地方?

同一個工程理念,作用在不同的時間軸上。

Developer Portal → hyp context / AutoSync

Harness IDP(Internal Developer Portal)讓開發者用一個入口理解整個組織的服務目錄。

HypGo 的 Manifest 系統做同一件事,但目標受眾是 AI:

hyp context # 輸出 .hyp/context.yaml
hyp context -f json # JSON 格式

# .hyp/context.yaml — AI 讀這個來理解你的專案
version: "1.0"
framework: HypGo
server:
 addr: ":8080"
 protocol: http2
routes:
 - method: POST
 path: /api/users
 summary: "建立使用者"
 input_type: CreateUserRequest
 output_type: UserResponse
 handler_names: ["controllers.(*UserController).Create"]

Server 啟動時自動同步(AutoSync),context.yaml 永遠與程式碼一致。

Harness IDP:讓人類開發者理解「整個組織有哪些服務」
HypGo Manifest:讓 AI 理解「這個 Go 專案的 API 結構」

兩者可以整合:HypGo Manifest 作為 Harness IDP 中單一服務的 API 元資料來源。

AI-Assisted Development → hyp ai-rules + Annotation Protocol

Harness AIDA 讓 AI 能理解 Harness Pipeline,幫助生成和除錯 Pipeline YAML。

HypGo 的 AI 協作工具讓各種 AI 工具(Claude、Cursor、Copilot)能理解你的 Go 專案慣例:

hyp ai-rules
# 生成:
# CLAUDE.md ← Claude Code 設定
# .cursorrules ← Cursor 設定
# .github/copilot-instructions.md
# .continue/config.json
# .aider.conf.yml

同時,Annotation Protocol 讓業務約束直接寫在程式碼中,AI 讀註解就能理解限制:

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

Harness AIDA:讓 AI 幫你用 Harness 平台
HypGo AI 工具:讓 AI 幫你開發 Go 應用

Reliability Engineering → /_debug/state

Harness SRM(Service Reliability Management)在生產環境追蹤 SLO、Error Budget,讓問題在影響到使用者之前被發現。

HypGo 的診斷端點把「系統狀態可見」的理念帶進開發與除錯階段:

GET /_debug/state
Authorization: Bearer <token>

{
 "goroutines": 42,
 "memory": { "alloc_mb": 18.3, "gc_cycles": 7 },
 "routes": [
 { "method": "POST", "path": "/api/users", "schema": true }
 ],
 "redis": { "connected": true, "latency_ms": 1.2 },
 "db": { "master": "ok", "replicas": 2 }
}

一個請求,AI 就能取得完整的系統快照,不需要到處翻 log。

Harness SRM:生產環境 → SLO 監控、Error Budget、告警
HypGo 診斷端點:開發 / 除錯 → 單次快照、AI 可讀的系統狀態

Database Lifecycle → hyp migrate diff

Harness DB DevOps 整合 Liquibase / Flyway,讓資料庫變更與 deployment 綁定、可追蹤、可回滾。

HypGo 解決這條鏈上的最前端問題:從 Go Model struct 自動推導出需要哪些 SQL 變更:

# 開發者修改了 User struct,加了兩個欄位
hyp migrate diff
# 輸出:
# [up]
# ALTER TABLE "users" ADD COLUMN "bio" TEXT;
# ALTER TABLE "users" ADD COLUMN "avatar_url" TEXT;
#
# [down]
# ALTER TABLE "users" DROP COLUMN "bio";
# ALTER TABLE "users" DROP COLUMN "avatar_url";
hyp migrate snapshot # 儲存快照,作為下次 diff 的基準

HypGo hyp migrate diff:Go struct → 生成 SQL migration 腳本
Harness DB DevOps: SQL migration → 安全部署到生產環境

HypGo 的輸出是 Harness DB DevOps 的輸入。

層級分工

┌─────────────────────────────────────────────────────┐
│ Harness 平台層 │
│ │
│ CI Pipeline → CD 部署 → SRM 監控 → Feature Flags │
│ │
│ Test Intelligence Change Intelligence DB DevOps │
└─────────────────────────┬───────────────────────────┘
 │ go test / SQL / Docker image
┌─────────────────────────▼───────────────────────────┐
│ HypGo 應用框架層 │
│ │
│ Schema-first 路由 Contract Testing │
│ hyp context hyp ai-rules │
│ hyp impact hyp migrate diff │
│ /_debug/state Annotation Protocol │
│ │
│ → 讓「進入 Harness Pipeline 的程式碼」本身更可靠 │
└─────────────────────────────────────────────────────┘

Harness 工程的前提是:進入 Pipeline 的程式碼本身必須是高品質的。HypGo 負責這一層。

整合流程

開發者
 ├─ 定義 Schema(合約)
 ├─ hyp context → AI 讀 manifest 理解專案
 ├─ AI 生成 Handler
 ├─ contract.TestAll() → 合約驗證通過
 ├─ hyp impact → 確認影響範圍可接受
 ├─ hyp migrate diff → 生成 SQL migration
 └─ git push
Harness Pipeline
 ├─ Test Intelligence:選出需要跑的測試 job
 ├─ go test(含 contract.TestAll):合約驗證
 ├─ STO:Security 掃描
 ├─ DB DevOps:執行 migration SQL
 ├─ CD:Blue/Green 部署
 └─ SRM:SLO 監控,確認新版本穩定

摘要

HypGo 不是 Harness 的競品,也不只是 Harness 的補充工具——HypGo 是在 Go 應用框架層實踐 Harness 工程理念的具體方法。

Harness 工程實踐	Harness 平台做法	HypGo 框架做法
Human Inside	SLO / Approval Gate / Feature Flag	Schema / @ai:constraint / Error Catalog
Contract-first	Pipeline 合約驗證	Schema + Contract Testing
Test Intelligence	CI 智慧選測試	自動生成測試資料
Change Intelligence	部署後影響追蹤	提交前靜態影響分析
Developer Portal	IDP 服務目錄	AI-readable Manifest
AI Assistance	AIDA Pipeline 輔助	ai-rules + Annotation
Reliability	SRM / SLO 監控	診斷端點快照
DB Lifecycle	DB DevOps 部署	struct → SQL 自動生成

如果你認同 Harness 的工程哲學,HypGo 就是把這套哲學帶進你的 Go 程式碼的方式。
兩者都把人放在最關鍵的決策點上,讓自動化做剩下的事。

HypGo · v0.8.5 · harness.md

HypGo

繁體中文 | English

中文文件

設計文件

套件

config — 設定
context — 請求上下文
router — 路由器
server — 伺服器
middleware — 中介層
websocket — WebSocket
hidb — 資料庫 ORM
hidb/cassandra — Cassandra
logger — 日誌
json — JSON 處理
grpc — gRPC

AI 協作工具鏈

schema — Schema-first 路由
manifest — 專案 Manifest
contract — Contract Testing
errors — Typed Error Catalog
migrate — Migration Diff
scaffold — 智慧 Scaffold
airules — AI Rules

CLI 命令

English Docs

Design Docs

Packages

config — Configuration
context — Request Context
router — Router
server — Server
middleware — Middleware
websocket — WebSocket
hidb — Database ORM
hidb/cassandra - Cassandra 5.0
logger — Logger
json — JSON
grpc — gRPC

AI Collaboration Toolchain

schema — Schema-first Routing
manifest — Project Manifest
contract — Contract Testing
errors — Typed Error Catalog
migrate — Migration Diff
scaffold — Smart Scaffold
airules — AI Rules

CLI Commands

harness.md

HypGo 與 Harness 工程

什麼是 Harness 工程?

HypGo 實踐了哪些 Harness 工程

Human Inside — 自動化的前提是人的判斷

在 Harness 平台層

在 HypGo 應用層

為什麼叫 Human Inside?

逐項說明

Contract-first → Schema-first + Contract Testing

Test Intelligence → contract.TestAll()

Change Intelligence → hyp impact

Developer Portal → hyp context / AutoSync

AI-Assisted Development → hyp ai-rules + Annotation Protocol

Reliability Engineering → /_debug/state

Database Lifecycle → hyp migrate diff

層級分工

整合流程

摘要

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!