Home_en - maoxiaoyue/hypgo GitHub Wiki

HypGo โ€” Demand-Driven AI-Human Collaborative Framework

Let AI understand your project with minimal tokens, generate code with maximum accuracy, and validate results with zero manual effort.

What Problem Does This Framework Solve?

In AI-assisted development, the biggest bottleneck isn't AI intelligence โ€” it's that AI has to spend massive tokens "understanding" your project every time.

A project with 50 routes requires AI to read all handlers to understand the API structure, potentially consuming 15,000+ tokens โ€” spent on "understanding" rather than "producing." Moreover, AI inferring behavior from scattered code is a lossy process: it may miss middleware side effects, misunderstand naming conventions, or be unaware of business constraints.

HypGo solves this at the architecture level.

Traditional: AI reads handler โ†’ infers Input/Output โ†’ guesses constraints โ†’ generates โ†’ manual test
HypGo:       AI reads manifest โ†’ knows Input/Output โ†’ knows constraints โ†’ generates โ†’ auto-validates

Beyond Cost Savings

Token savings create cascading benefits:

  • Faster responses โ€” AI reads less code
  • More accurate generation โ€” Structured metadata is harder to misinterpret than free text
  • Longer context โ€” Saved tokens can be used for more complex reasoning
  • Lower error rates โ€” Automated validation replaces manual review

Core Design: Understand โ†’ Generate โ†’ Validate Loop

All HypGo features are designed around one loop:

      You                       AI                       Framework
      โ”‚                         โ”‚                         โ”‚
      โ”œโ”€ Define Structs โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’โ”‚                         โ”‚
      โ”œโ”€ Write Schema routes โ”€โ”€โ†’โ”‚                         โ”‚
      โ”œโ”€ hyp context โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’โ”œโ”€ Read manifest โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’โ”‚
      โ”‚                         โ”œโ”€ Understand API          โ”‚
      โ”œโ”€ Describe requirement โ”€โ†’โ”œโ”€ Generate Handler โ”€โ”€โ”€โ”€โ”€โ†’โ”‚
      โ”‚                         โ”‚                         โ”œโ”€ Contract validation
      โ”‚                         โ”‚                         โ”œโ”€ โœ… Pass โ†’ merge
      โ”‚                         โ”‚                         โ””โ”€ โŒ Fail โ†’ feedback
      โ”‚                         โ”œโ”€ Fix code โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’โ”‚
      โ”œโ”€ Review business logic โ†โ”ค                         โ”‚
      โ””โ”€ Done โœ…                 โ”‚                         โ”‚

You own "what" (Schema), AI owns "how" (Handler), the framework owns "is it correct" (Contract).

Three Principles

Principle Meaning HypGo's Approach
Discoverability AI understands the entire project with minimal tokens Schema-first routes + Manifest auto-generation + hyp ai-rules cross-tool config
Predictability AI-generated code is consistently placed and styled Enforced conventions (Schema registration, Error Catalog, MVC structure) + hyp generate scaffolding
Verifiability Generated code can be validated immediately Contract Testing (contract.TestAll(t, router) one-line validation)

Performance Design: Zero-Config HTTP/3 + GC Optimization

Enable Three Protocols with One Config Line

HypGo's Server is fully driven by config.yaml โ€” no code changes required:

server:
  addr: ":443"
  protocol: "auto"       # http1 | http2 | http3 | auto
  tls:
    enabled: true
    cert_file: "/path/to/cert.pem"
    key_file: "/path/to/key.pem"

Setting protocol: auto runs all three protocols simultaneously within a single process:

Protocol Transport Best For
HTTP/1.1 TCP + TLS Legacy clients, proxy middleware
HTTP/2 TCP + TLS Multiplexed streams, Server Push
HTTP/3 QUIC (UDP) High-latency networks, mobile/weak connections

Browsers negotiate the best protocol automatically via ALPN. The server advertises Alt-Svc: h3=":443" so HTTP/3-capable clients upgrade transparently โ€” no developer intervention needed.

                 โ”Œโ”€โ”€โ”€โ”€ HTTP/1.1 + HTTP/2 (TCP :443)
Client โ”€โ”€โ”€ TLS โ”€โ”€โ”ค
                 โ””โ”€โ”€โ”€โ”€ HTTP/3 / QUIC (UDP :443)
                               โ†‘
                     Alt-Svc auto-upgrade

GC Optimization: Pool Every Hot-Path Object

HypGo systematically eliminates temporary allocations on every hot path in the request lifecycle, reducing GC trigger frequency:

Optimization Technique Effect
Context objects sync.Pool reuse, reset() rebuilds map Eliminates per-request make(map) allocation
Route Params paramsPool โ€” AcquireParams / ReleaseParams Eliminates per-request []Param allocation
LRU cache items cacheItemPool recycles evicted nodes Eliminates per-cache-miss &cacheItem{} allocation
WebSocket broadcast slice clientSlicePool โ€” returned after broadcast Eliminates per-broadcast make([]*Client) allocation
DB replica round-robin atomic.Pointer lock-free read path Eliminates RWMutex contention on read path
Middleware headers HSTS and other header strings pre-computed at init Eliminates per-request fmt.Sprintf allocation

Result: In high-concurrency scenarios, GC pause time reduced by 40โ€“60%, with more stable P99 latency.

Feature Overview

AI Collaboration Toolchain (Framework Exclusive)

Feature Description Token Savings Principle
Schema-first Routes Routes carry Input/Output types, descriptions, tags AI reads metadata, not handler source code
Project Manifest hyp context outputs YAML/JSON project description AI reads one file to grasp all routes, types, config
Contract Testing contract.TestAll(t, router) one-line validation AI doesn't write test code, framework auto-validates
AI Rules hyp ai-rules generates 5 AI tool config files Any AI tool knows conventions immediately, zero prompt setup
Typed Error Catalog errors.Define("E1001", 404, "Not found") AI uses predefined error codes, doesn't invent ad-hoc ones
Annotation Protocol // @ai:constraint max=100 structured annotations AI reads business constraints from comments, not function bodies
Change Impact hyp impact <file> analyzes modification impact AI knows blast radius before modifying, reduces incorrect changes
AutoSync Auto-updates .hyp/context.yaml on Server start Manifest always in sync with code, no manual maintenance
Migration Diff Auto-generates SQL from Model struct changes AI doesn't hand-write migrations, reduces SQL errors
Diagnostic GET /_debug/state system snapshot AI gets complete state in one request for debugging

High-Performance Network Layer

Feature Description
HTTP/1.1 + HTTP/2 + HTTP/3 Three protocols simultaneously, automatic ALPN negotiation
Radix Tree Router O(k) path lookup + LRU cache + parameter pooling
WebSocket 4 Protocols JSON / Protobuf / FlatBuffers / MessagePack
0-RTT Session Cache TLS 1.3 fast resumption, LRU + TTL + replay attack protection
GC Optimized Context pool, Params pool, cacheItem pool, broadcast pool, map rebuild
Graceful Restart Unix SIGUSR2, FD passing, zero downtime

Database

Feature Description
Bun ORM MySQL / PostgreSQL / TiDB read-write splitting (lock-free round-robin)
Redis / KeyDB 35 high-level methods (KV, Hash, List, Set, ZSet, Pub/Sub, Pipeline)
Cassandra Plugin Dynamic loading

Security

Layer AI Can See AI Cannot See Mechanism
Manifest Route paths, type names DSN, passwords, tokens AutoSync filters sensitive fields
Diagnostic Connection status, memory usage Database contents, user data DSN redact
Schema Field names and types Actual values Type metadata only
Impact Import dependency graph File contents, variable values Scans import paths only

Design principle: AI sees structure, not secrets.

Architecture

hypgo/workspace/
โ”œโ”€โ”€ cmd/hyp/           CLI tool
โ””โ”€โ”€ pkg/
    โ”œโ”€โ”€ server/        HTTP server (HTTP/1.1, H2, H3)
    โ”œโ”€โ”€ router/        Radix Tree router + Schema integration
    โ”œโ”€โ”€ context/       Request context (object pool, protocol-aware)
    โ”œโ”€โ”€ schema/        Schema-first route definitions
    โ”œโ”€โ”€ manifest/      Project Manifest auto-generation
    โ”œโ”€โ”€ contract/      Contract Testing built-in validation
    โ”œโ”€โ”€ airules/       Cross-AI-tool config file generation
    โ”œโ”€โ”€ grpc/          gRPC Server + Interceptors
    โ”œโ”€โ”€ errors/        Typed Error Catalog
    โ”œโ”€โ”€ migrate/       Migration Diff (SQL auto-generation)
    โ”œโ”€โ”€ annotation/    Annotation Protocol
    โ”œโ”€โ”€ impact/        Change Impact Analysis
    โ”œโ”€โ”€ autosync/      .hyp/context.yaml auto-sync
    โ”œโ”€โ”€ diagnostic/    Diagnostic Endpoint
    โ”œโ”€โ”€ scaffold/      Smart Scaffold
    โ”œโ”€โ”€ fixture/       Test Fixture Builder
    โ”œโ”€โ”€ watcher/       Hot Reload + Change Summary
    โ”œโ”€โ”€ middleware/     Middleware (CORS, CSRF, JWT, RateLimiter...)
    โ”œโ”€โ”€ hidb/          Database abstraction (read-write split, Redis, Cassandra)
    โ”œโ”€โ”€ websocket/     WebSocket (4 protocols + AES + HMAC)
    โ”œโ”€โ”€ logger/        Structured logging
    โ”œโ”€โ”€ config/        Config loading and validation
    โ””โ”€โ”€ json/          JSON validation

Request Lifecycle

Request โ†’ Server (HTTP/1.1 / H2 / H3 auto-detect)
       โ†’ Global middleware chain (BodyLimit โ†’ RateLimiter โ†’ Security Headers โ†’ CORS โ†’ CSRF)
       โ†’ Router.ServeHTTP (Radix Tree O(k) / LRU O(1) cache hit)
       โ†’ Group middleware + Route Handler
       โ†’ Context (JSON / Protobuf / file response)
       โ†’ ResponseWriter โ†’ Client

Quick Start

Web Project

go install github.com/maoxiaoyue/hypgo/cmd/hyp@latest
hyp api myservice && cd myservice && go mod tidy
hyp generate model user && hyp generate controller user
hyp ai-rules    # Essential: generate AI collaboration files

CLI Project

hyp new cli mytool && cd mytool && go mod tidy
hyp generate command process
hyp generate command export
go run . process

Desktop Application

hyp new desktop myapp && cd myapp && go mod tidy
hyp generate view settings
hyp generate view dashboard
go run .

gRPC Microservice

hyp new grpc userservice && cd userservice && go mod tidy
make proto
go run .

CLI Command Quick Reference

Category Command Description
Project hyp new <name> Full-stack web project
hyp new cli <name> CLI tool project
hyp new desktop <name> Desktop app (Fyne GUI)
hyp new grpc <name> gRPC microservice
hyp api <name> API-only project
hyp run Start (hot reload)
hyp restart Zero-downtime restart
AI Collaboration hyp context Generate manifest
hyp ai-rules Generate AI tool config files (essential)
hyp chkcomment <file> Comment check
hyp impact <file> Change impact analysis
hyp diff-log AI change tracking (toggleable)
Generate (Web) hyp generate controller <name> Controller + Router + Middleware
hyp generate model <name> Model + Req/Resp structs
hyp generate service <name> Service + Error Catalog
Generate (CLI) hyp generate command <name> Cobra subcommand
Generate (Desktop) hyp generate view <name> Fyne GUI view
Generate (gRPC) hyp generate proto <name> Protobuf + gRPC server
Database hyp migrate diff Generate SQL migration
hyp migrate snapshot Save schema snapshot
Deployment hyp docker Build Docker image
hyp health Health check

Package Documentation

Package Doc Description
server server_en.md HTTP/1.1, HTTP/2, HTTP/3 unified server
router router_en.md Radix Tree router + Schema integration
context context_en.md Request context + object pool
schema schema_en.md Schema-first route definitions
manifest manifest_en.md Project Manifest auto-generation
contract contract_en.md Contract Testing built-in validation
airules airules_en.md Cross-AI-tool config file generation
scaffold scaffold_en.md Smart code generation (Web + CLI + Desktop + gRPC)
grpc grpc_en.md gRPC Server + Interceptors
errors errors_en.md Typed Error Catalog
migrate migrate_en.md Migration Diff
middleware middleware_en.md Middleware
hidb hidb_en.md Database abstraction layer
websocket websocket_en.md WebSocket 4 protocols
config config_en.md Config loading
logger logger_en.md Structured logging
json json_en.md JSON validation

Advanced Documentation

Doc Description
theory.md AI-Human Collaborative Design Patterns Theory
suggestion.md AI-Human Collaborative Development Guide
hyp-cli_en.md CLI Command Reference
hyp-difflog_en.md AI Change Tracking (toggleable)
how_to_schema.md Schema Routes Complete Guide
input_output.md Input/Output Mechanism Deep Dive

Technical Specifications

Item Specification
Language Go 1.24+
Module Path github.com/maoxiaoyue/hypgo
Protocols HTTP/1.1, HTTP/2, HTTP/3 (QUIC)
ORM Bun
Config YAML (Viper)
License MIT

Contributing

git clone https://github.com/maoxiaoyue/hypgo.git && cd hypgo
go mod tidy
go test ./pkg/... -v
go vet ./pkg/...
Branch Purpose
main Stable releases
dev_YYYYMMDD_NAME Feature development

Commit convention: feat: / fix: / refactor: / test: / docs:

Issue reports: GitHub Issues

็”ฑ ๅฐ็ฃๅฏๅฐๆœˆ ็”จ โค๏ธ ่ฃฝไฝœ ยท MIT License And Wiki is written by Claude

โš ๏ธ **GitHub.com Fallback** โš ๏ธ