-
Notifications
You must be signed in to change notification settings - Fork 0
en\home_en.md
maoxiaoyue edited this page Apr 10, 2026
·
1 revision
Let AI understand your project with minimal tokens, generate code with maximum accuracy, and validate results with zero manual effort.
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
| Scenario | Traditional | HypGo | Savings |
|---|---|---|---|
| AI understands API structure | Read all handlers (~5,000 tokens) | Read manifest.yaml (~500 tokens) | 90% |
| AI understands single route | Read handler + service + model (~2,000 tokens) | Read schema metadata (~200 tokens) | 90% |
| AI validates generated code | Manually write tests (~1,500 tokens) |
contract.TestAll() one line (~50 tokens) |
97% |
| AI assesses change impact | Search imports file by file (~3,000 tokens) |
hyp impact (~100 tokens) |
97% |
For a 20-route project, each AI interaction saves 4,000–8,000 tokens.
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) |
| 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 |
| 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 |
|---|---|
| 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 |
| 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
├── 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 → 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 .
hyp new grpc userservice && cd userservice && go mod tidy make proto 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 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 | 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 |
| 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 |
| 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 |
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
設計文件
套件
- 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