Manifest 機制詳解:專案的壓縮表示

Manifest 是什麼?

你的專案(20 個 handler、10 個 model、5 個 service)
 │
 │ 傳統做法:AI 讀全部原始碼 → ~15,000 tokens
 │
 ▼
.hyp/context.yaml(200 行)
 │
 │ HypGo 做法:AI 讀一個檔案 → ~500 tokens
 │
 ▼
AI 理解你的專案(壓縮比 30:1)

第一部分:Manifest 結構

完整範例

version: "1.0"
framework: HypGo
generated_at: "2026年04月03日T14:30:00+08:00"
server:
 addr: ":8080"
 protocol: http2
 tls: true
routes:
 - method: GET
 path: /api/users
 handler_names:
 - controllers.(*UserController).List
 summary: "List all users"
 tags:
 - users
 output_type: UserListResp
 - method: POST
 path: /api/users
 handler_names:
 - controllers.(*UserController).Create
 summary: "Create user"
 tags:
 - users
 input_type: CreateUserReq
 output_type: UserResp
 responses:
 201: "User created"
 400: "Invalid input"
 - method: GET
 path: /api/users/:id
 handler_names:
 - controllers.(*UserController).Get
 summary: "Get user by ID"
 tags:
 - users
 output_type: UserResp
 responses:
 200: "User found"
 404: "User not found"
 - method: GET
 path: /health
 handler_names:
 - main.healthHandler
database:
 driver: postgres
 has_replicas: true

結構定義

type Manifest struct {
 Version string // 固定 "1.0"
 Framework string // 固定 "HypGo"
 GeneratedAt time.Time // 生成時間
 Server ServerInfo // 伺服器設定
 Routes []RouteManifest // 所有路由(含 schema metadata)
 Middleware []string // 已註冊的中間件(可選)
 Database *DatabaseInfo // 資料庫設定(可選,無 DB 則 nil)
}

每個路由包含的資訊

第二部分:Manifest 如何產生

收集流程

Collector.Collect()
 │
 ├─ 1. collectRoutes()
 │ │
 │ ├─ router.Routes()
 │ │ → 遍歷所有 Radix Tree
 │ │ → 每個 leaf node 提取:method, path, handlers
 │ │ → 用 runtime.FuncForPC 取得 handler 函式名
 │ │ → 回傳 []RouteInfo
 │ │
 │ └─ 對每個 RouteInfo:
 │ schema.Global().Get(method, path)
 │ → 有 schema?加入 summary, tags, input_type, output_type, responses
 │ → 無 schema?只保留 method, path, handler_names
 │
 ├─ 2. collectServer()
 │ → config.Server.Addr
 │ → config.Server.Protocol
 │ → config.Server.TLS.Enabled
 │
 └─ 3. collectDatabase()
 → config.Database.Driver(空字串則回傳 nil)
 → config.Database.Replicas 數量 > 0?
排序:Routes 按 Path 字母序 + Method 字母序

Handler 名稱提取

// 從 handler 函式指標取得名稱
func nameOfFunction(f interface{}) string {
 full := runtime.FuncForPC(reflect.ValueOf(f).Pointer()).Name()
 // "github.com/myapp/app/controllers.(*UserController).Create-fm"
 // ↓
 // 取最後一段 + 移除 -fm 後綴
 // → "controllers.(*UserController).Create"
}

三個產生 Manifest 的方式

第三部分:AutoSync 自動同步

運作流程

Server.Start()
 │
 ├─ autosync.New(config, router, appConfig, logger)
 │
 └─ autosync.SyncSafe()
 │
 ├─ config.Enabled == false?→ 跳過
 │
 ├─ os.MkdirAll(".hyp/", 0755)
 │
 ├─ manifest.NewCollector(router, appConfig).Collect()
 │ → 收集所有路由、設定、schema metadata
 │
 ├─ manifest.SaveToFile(".hyp/context.yaml.tmp", m, "yaml")
 │ → 寫入暫存檔(不直接覆蓋目標檔案)
 │
 ├─ os.Rename(".hyp/context.yaml.tmp", ".hyp/context.yaml")
 │ → 原子替換(防止寫入中途損壞)
 │
 └─ logger.Info("AutoSync: manifest saved to .hyp/context.yaml")

為什麼用原子寫入?

❌ 直接寫入(危險):
 os.Create(".hyp/context.yaml") ← 此刻檔案被清空
 writer.Write(data) ← 寫入中途斷電 → 檔案損壞
 file.Close()
✅ 原子寫入(安全):
 os.Create(".hyp/context.yaml.tmp") ← 暫存檔
 writer.Write(data) ← 寫入暫存檔
 file.Close()
 os.Rename(".tmp", ".yaml") ← 原子替換,全有或全無

AutoSync 設定

autosync.Config{
 Enabled: true, // 預設 true
 Path: ".hyp/context.yaml", // 預設路徑
 Format: "yaml", // "yaml" 或 "json"
}

第四部分:Manifest 不包含什麼

安全設計:結構 vs 資料

✅ Manifest 包含(結構資訊) ❌ Manifest 不包含(敏感資料)
───────────────────────────── ────────────────────────────
路由路徑 /api/users 資料庫密碼
HTTP 方法 POST DSN 連線字串
型別名稱 CreateUserReq API key / token
欄位名稱 name, email 使用者資料
Handler 名稱 controllers.Create 環境變數值
Server addr :8080 TLS 證書內容
Protocol http2 Redis 密碼
Database driver postgres Session 資料
HasReplicas true Request/Response 實際值

collectDatabase 的過濾

func (c *Collector) collectDatabase() *DatabaseInfo {
 if c.config.Database.Driver == "" {
 return nil // 沒設定 DB → 不出現在 manifest 中
 }
 return &DatabaseInfo{
 Driver: c.config.Database.Driver, // "postgres"(只有 driver 名)
 HasReplicas: len(c.config.Database.Replicas) > 0, // true/false
 // ❌ 不包含 DSN
 // ❌ 不包含 Password
 // ❌ 不包含 Replica DSN
 }
}

第五部分:Manifest 如何被消費

5.1 AI 直接讀取

# AI 的第一個動作
cat .hyp/context.yaml

5.2 hyp ai-rules 讀取

func loadManifestIfExists(dir string) *manifest.Manifest {
 path := filepath.Join(dir, ".hyp", "context.yaml")
 data, err := os.ReadFile(path)
 if err != nil {
 return nil // 不存在 → AI 配置檔只有靜態慣例,沒有動態路由
 }
 var m manifest.Manifest
 yaml.Unmarshal(data, &m)
 return &m
}

## Current Routes
| Method | Path | Summary |
|--------|------|---------|
| GET | /api/users | List all users |
| POST | /api/users | Create user |
| GET | /health | - |

5.3 hyp context 手動生成

# YAML 到 stdout
hyp context
# JSON 格式
hyp context -f json
# 儲存到檔案
hyp context -o .hyp/context.yaml
hyp context -o manifest.json -f json

5.4 Server.Manifest() 程式碼存取

srv := server.New(cfg, log)
// 註冊路由後...
m := srv.Manifest()
// 輸出
manifest.WriteYAML(os.Stdout, m)
// 或直接存取欄位
for _, route := range m.Routes {
 fmt.Printf("%s %s → %s\n", route.Method, route.Path, route.InputType)
}

第六部分:Schema 路由 vs 傳統路由在 Manifest 中的差異

同一個 API,兩種寫法的 Manifest 比較

r.POST("/api/users", createUserHandler)

- method: POST
 path: /api/users
 handler_names:
 - main.createUserHandler
 # ← 沒有 summary、沒有 input_type、沒有 output_type

r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "Create user",
 Tags: []string{"users"},
 Input: CreateUserReq{},
 Output: UserResp{},
 Responses: map[int]schema.ResponseSchema{
 201: {Description: "User created"},
 400: {Description: "Invalid input"},
 },
}).Handle(createUserHandler)

- method: POST
 path: /api/users
 handler_names:
 - main.createUserHandler
 summary: "Create user"
 tags:
 - users
 input_type: CreateUserReq
 output_type: UserResp
 responses:
 201: "User created"
 400: "Invalid input"

差距量化

第七部分:Manifest 的壓縮原理

為什麼 30:1 壓縮比不是有損的

func (ctrl *UserController) Create(c *hypcontext.Context) {
 var req models.CreateUserReq
 if err := c.ShouldBindJSON(&req); err != nil {
 errors.AbortWithAppError(c, ErrUserInvalid.With("reason", err.Error()))
 return
 }
 user := &models.User{
 Name: req.Name,
 Email: req.Email,
 }
 if _, err := db.WriteHypDB().NewInsert().Model(user).Exec(ctx); err != nil {
 errors.AbortWithAppError(c, ErrUserInvalid.With("reason", "db error"))
 return
 }
 c.JSON(201, models.UserResp{
 ID: user.ID,
 Name: user.Name,
 Email: user.Email,
 })
}

- method: POST
 path: /api/users
 summary: "Create user"
 input_type: CreateUserReq
 output_type: UserResp
 handler_names: [controllers.(*UserController).Create]

第八部分:最佳實踐

何時生成 Manifest

是否加入版本控制?

搭配 hyp ai-rules 的工作流

# 1. 寫好 Schema 路由
# 2. 生成 manifest
hyp context -o .hyp/context.yaml
# 3. 生成 AI 配置檔(會讀取 manifest 注入路由表)
hyp ai-rules
# 4. 開啟 AI 工具 → AI 自動讀取 AGENTS.md → 知道所有路由

第九部分:Debug 與進階用法

查看當前 Manifest 內容

# YAML 到 stdout
hyp context
# JSON 格式
hyp context -f json
# 只看路由
hyp context | grep "path:"

程式碼中讀取 Manifest

import "gopkg.in/yaml.v3"
data, _ := os.ReadFile(".hyp/context.yaml")
var m manifest.Manifest
yaml.Unmarshal(data, &m)
fmt.Printf("Routes: %d\n", len(m.Routes))
for _, r := range m.Routes {
 fmt.Printf(" %s %s → %s\n", r.Method, r.Path, r.InputType)
}

比較兩個版本的 Manifest

# 在修改前後各生成一份,用 diff 比較
hyp context -o before.yaml
# ... 修改路由 ...
hyp context -o after.yaml
diff before.yaml after.yaml

驗證 Manifest 完整性

m := srv.Manifest()
for _, r := range m.Routes {
 if r.InputType == "" && (r.Method == "POST" || r.Method == "PUT") {
 fmt.Printf("⚠️ %s %s: missing Input type\n", r.Method, r.Path)
 }
 if r.Summary == "" {
 fmt.Printf("⚠️ %s %s: missing Summary\n", r.Method, r.Path)
 }
}