-
Notifications
You must be signed in to change notification settings - Fork 0
Home_en
maoxiaoyue edited this page May 15, 2026
·
6 revisions
Let AI understand your project with minimal tokens, generate code with maximum accuracy, and validate results with zero manual effort.
AI won't replace humans — if humans learn to use AI smartly.
Early in development, my original focus was QUIC (HTTP/3) as the primary feature. But the AI tooling landscape shifted significantly through 2026, so I adjusted direction toward a development experience that makes AI-human collaboration more efficient.
In AI-assisted development, the challenges can be summarized as four core problems:
| # | Problem | How It Manifests |
|---|---|---|
| 1 | Token consumption | AI must read handlers, services, and models scattered across many files to infer API structure — large amounts of tokens spent on "understanding" rather than "producing" |
| 2 | Result validation | AI-generated code lacks automatic verification — teams rely on manual review or hand-written tests, which is slow and error-prone |
| 3 | Inability to correctly understand requirements | AI infers business logic from scattered code and may miss middleware side effects or business constraints, producing code that is "syntactically correct but logically wrong" |
| 4 | Communication misunderstandings | Free-form requirement descriptions are easily misinterpreted. Without explicit definitions for naming conventions, error code formats, and response structures, AI makes different choices every time |
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.
Saving tokens requires human assistance.
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
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
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).
| 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) |
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
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 | Description | Token Savings Principle |
|---|---|---|
| Schema-first Routes | Routes carry Input/Output types, descriptions, tags | AI reads metadata, no need to read handler source |
| 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 |
| 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 |
| Feature | Description |
|---|---|
| Extending from Bun | 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 |
| 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.
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
├── 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 → 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
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
hyp new cli mytool && cd mytool && go mod tidy hyp generate command process hyp generate command export go run . process
hyp new desktop myapp && cd myapp && go mod tidy hyp generate view settings hyp generate view dashboard go run .
| 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 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 | |
hyp chkcomment <file> |
Comment check | |
hyp impact <file> |
Change impact analysis | |
| Generate | hyp generate controller <name> |
Generate controller |
hyp generate model <name> |
Generate model | |
hyp generate service <name> |
Generate service | |
| Generate (CLI) | hyp generate command <name> |
Cobra subcommand |
| Generate (Desktop) | hyp generate view <name> |
Fyne GUI view |
| Database | hyp migrate diff |
Generate SQL migration |
hyp migrate snapshot |
Save schema snapshot | |
| Deployment | hyp docker |
Build Docker image |
hyp health |
Health check |
| 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 (multi-protocol) |
| 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 v0.8.5+
|
| scaffold | scaffold_en.md | Smart code generation (Web + CLI / Desktop / gRPC v0.8.5+) |
| grpc | grpc_en.md | gRPC Server + Interceptors v0.8.5+
|
| 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 |
| 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 |
| manifest_en.md | Manifest internals and mechanics |
| Item | Specification |
|---|---|
| Language | Go 1.24+ |
| Module Path | github.com/maoxiaoyue/hypgo |
| Protocols | HTTP/1.1, HTTP/2, HTTP/3 (QUIC) |
| ORM | extending from Bun |
| Config | YAML (Viper) |
| License | MIT |
| Tests | 354 tests, 21 packages, 0 failures |
git clone https://github.com/maoxiaoyue/hypgo.git && cd hypgo go mod tidy go test ./pkg/... -v # 354 tests go vet ./pkg/... # zero warnings
| Branch | Purpose |
|---|---|
main |
Latest release |
dev_YYYYMMDD |
Feature development |
Commit convention: feat: / fix: / refactor: / test: / docs:
Issue reports: GitHub Issues
設計文件
套件
- 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 命令
- hyp 總覽
- hyp new
- hyp api
- hyp run
- hyp restart
- hyp generate
- hyp migrate
- hyp context
- hyp ai-rules
- hyp chkcomment
- hyp impact
- hyp docker
- hyp health
- hyp version
- hyp difflog
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