pkg/manifest — Project Manifest 自動生成

設計理念

❌ AI 讀 20 個檔案才理解 API 結構(數千 token)
✅ AI 讀 1 個 manifest 就掌握全貌(數百 token)

快速上手

從程式碼中生成

import (
 "os"
 "github.com/maoxiaoyue/hypgo/pkg/manifest"
 "github.com/maoxiaoyue/hypgo/pkg/router"
 "github.com/maoxiaoyue/hypgo/pkg/config"
)
// 1. 建立 Collector(從 Router + Config 收集)
c := manifest.NewCollector(myRouter, myConfig)
// 2. 生成 Manifest
m := c.Collect()
// 3. 輸出 YAML 到 stdout
manifest.WriteYAML(os.Stdout, m)
// 4. 或儲存到檔案
manifest.SaveToFile(".hyp/manifest.yaml", m, "yaml")
manifest.SaveToFile(".hyp/manifest.json", m, "json")

從 Server 直接生成

srv := server.New(cfg, logger)
// 註冊路由後...
m := srv.Manifest()
manifest.WriteYAML(os.Stdout, m)

透過 CLI

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

輸出範例

YAML

version: "1.0"
framework: HypGo
generated_at: 2026年03月26日T20:00:00+08:00
server:
 addr: ":8080"
 protocol: http2
 tls: true
routes:
 - method: POST
 path: /api/users
 handler_names:
 - controllers.CreateUser
 summary: "建立使用者"
 tags:
 - users
 input_type: CreateUserRequest
 output_type: UserResponse
 responses:
 201: "User created"
 400: "Invalid input"
 - method: GET
 path: /api/users/:id
 handler_names:
 - controllers.GetUser
 summary: "依 ID 取得使用者"
 tags:
 - users
 output_type: UserResponse
 - method: GET
 path: /health
 handler_names:
 - main.healthHandler
database:
 driver: postgres
 has_replicas: true

JSON

{
 "version": "1.0",
 "framework": "HypGo",
 "server": {
 "addr": ":8080",
 "protocol": "http2",
 "tls": true
 },
 "routes": [
 {
 "method": "POST",
 "path": "/api/users",
 "handler_names": ["controllers.CreateUser"],
 "summary": "建立使用者",
 "tags": ["users"],
 "input_type": "CreateUserRequest",
 "output_type": "UserResponse",
 "responses": { "201": "User created" }
 }
 ]
}

核心型別

Manifest

type Manifest struct {
 Version string // 固定 "1.0"
 Framework string // 固定 "HypGo"
 GeneratedAt time.Time // 生成時間
 Server ServerInfo // 伺服器配置
 Routes []RouteManifest // 所有路由
 Middleware []string // 全域中間件
 Database *DatabaseInfo // 資料庫配置(可選)
}

RouteManifest(支援多協議)

type RouteManifest struct {
 // 多協議支援
 Protocol string // "rest", "grpc", "bot", "mcp", "websocket", "cli"
 Command string // 非 REST 命令標識
 Platform string // bot 專用平台(telegram, line, discord...)
 // REST 欄位
 Method string // HTTP 方法
 Path string // 路由路徑
 HandlerNames []string // handler 函式名(透過 runtime 反射)
 // 共用 metadata
 Summary string // 路由描述(來自 schema)
 Description string // 詳細描述(來自 schema)
 Tags []string // 分類標籤(來自 schema)
 InputType string // 請求型別名稱(來自 schema)
 OutputType string // 回應型別名稱(來自 schema)
 Responses map[int]string // 狀態碼 → 描述(來自 schema)
}

資料來源

Collector 流程

Router.Routes()
 │
 ├──→ 每個 RouteInfo
 │ │
 │ └──→ schema.Global().Get(method, path)
 │ │
 │ └──→ 合併為 RouteManifest
 │
 ├──→ sort by Path + Method
 │
config.Config ──→ ServerInfo + DatabaseInfo
 │
 └──→ 組裝 Manifest

Writer API

// 寫入 io.Writer
manifest.WriteYAML(w, m) // YAML 格式,2 空格縮排
manifest.WriteJSON(w, m) // JSON 格式,2 空格縮排
// 儲存到檔案(自動建立目錄)
manifest.SaveToFile(path, m, "yaml")
manifest.SaveToFile(path, m, "json")

LLM 智慧增強

Layer 1:純 Go 推斷(預設,零成本)

// handler 名 → Summary
"(*UserController).Create" → "Create User"
// 路徑 → Tags
"/api/users/:id" → ["users"]

Layer 2:LLM 增強(可選,需配置)

使用方式

1. 建立配置檔 config/llm.yaml

# 最簡配置 — 連接本地 Ollama
mode: ollama
ollama:
 model: llama3

# API 模式 — 使用 OpenAI
mode: api
api:
 provider: openai
 model: gpt-4o-mini
 api_key: "${OPENAI_API_KEY}" # 支援環境變數

# RAG 模式 — 向量檢索 + LLM 生成
mode: rag
rag:
 embedding_model: nomic-embed-text
 vector_store: chroma
 vector_store_url: "http://localhost:8000"
 collection: my_codebase
 generator_model: llama3

2. 從程式碼使用

// 載入 LLM 配置
llmCfg, err := config.LoadLLMConfig("config/llm.yaml")
// 建立帶 LLM 增強的 Collector
c, err := manifest.NewCollectorWithLLM(myRouter, myConfig, llmCfg)
m := c.Collect()

3. 從 CLI 使用

# 自動偵測 config/llm.yaml 或 .hyp/llm.yaml
hyp context
# 指定配置檔
hyp context --llm config/llm.yaml
# 搭配輸出選項
hyp context --llm config/llm.yaml -o .hyp/manifest.yaml -f yaml

模式對照:精確度 vs 成本

mode: none ┃ 零成本 ┃ ★★☆ 基礎推斷
mode: ollama ┃ 零費用 ┃ ★★★ 本地模型生成
mode: api ┃ 按量付費 ┃ ★★★★ 雲端模型生成
mode: rag ┃ 按量付費 ┃ ★★★★★ 結合程式碼上下文

安全設計

EnrichConfig 完整設定

cfg := manifest.EnrichConfig{
 InferSummary: true, // 從 handler 名推斷 Summary
 InferTags: true, // 從路徑推斷 Tags
 IncludeFields: true, // 包含 InputFields/OutputFields
 LLMEnricher: myLLMEnricher, // LLM 增強器(可選)
}
c := manifest.NewCollectorWithEnrich(router, config, cfg)

架構

pkg/manifest/
├── manifest.go Manifest、ServerInfo、RouteManifest、DatabaseInfo 型別
├── collector.go Collector:從 Router + Config + Schema Registry 收集
├── enricher.go EnrichConfig、純 Go 推斷邏輯、LLMEnricher 介面
├── llm_enricher.go OllamaEnricher、APIEnricher、RAGEnricher 實作
├── writer.go WriteYAML、WriteJSON、SaveToFile 輸出
├── manifest_test.go Collector + Writer 測試
└── llm_enricher_test.go LLM Enricher 測試(含 httptest 模擬)

依賴關係

pkg/manifest → pkg/router(Routes() 取得路由清單)
 → pkg/config(取得伺服器/資料庫設定)
 → pkg/schema(取得 schema metadata)
 → gopkg.in/yaml.v3(YAML 輸出)

AutoSync 自動同步

// Server.Start() 內部自動執行:
sync := autosync.New(autosync.Config{Enabled: true}, router, config, logger)
sync.SyncSafe() // 失敗不 panic,僅 log warning