docs: 更新 AGENTS.md 文档

添加各模块的 AGENTS.md 文档文件，记录模块职责和代码结构 Co-Authored-By: Claude <noreply@anthropic.com>
2026-04-03 14:07:42 +08:00 · 2026-04-03 14:07:42 +08:00 · 95030cd68a
commit 95030cd68a
parent c70ab305b7
16 changed files with 421 additions and 9 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,4 +1,4 @@
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # lolly

@ -14,6 +14,7 @@
 | `go.sum` | 依赖版本锁定 |
 | `Makefile` | 构建脚本，支持多平台编译、测试、覆盖率 |
 | `lolly.yaml` | 默认配置文件示例 |
+| `config.example.yaml` | 完整配置文件示例（所有字段枚举） |
 | `.gitignore` | Git 忽略规则 |

 ## Subdirectories
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # docs

@ -32,6 +32,17 @@
 | `10-nginx-stream-tcp-udp.md` | TCP/UDP Stream 代理参考 |
 | `11-nginx-mail-proxy.md` | 邮件代理参考 |
 | `12-nginx-performance-tuning.md` | 性能调优参考 |
+| `14-nginx-grpc-uwsgi.md` | gRPC/uWSGI/SCGI 代理参考 |
+| `15-nginx-advanced-features.md` | 高级特性参考 |
+| `16-nginx-internal-redirect.md` | 内部重定向参考 |
+| `17-nginx-mirror-slice.md` | 镜像与切片参考 |
+| `18-nginx-memcached.md` | Memcached 集成参考 |
+| `19-nginx-http-modules-detail.md` | HTTP 功能模块详解 |
+| `20-nginx-rate-limiting.md` | 限流与连接控制参考 |
+| `21-nginx-http2-http3.md` | HTTP/2 与 HTTP/3 参考 |
+| `22-nginx-third-party-modules.md` | 第三方扩展模块参考 |
+| `23-nginx-special-modules.md` | 特殊功能模块参考 |
+| `24-nginx-core-events.md` | 核心与事件模块参考 |

 ## For AI Agents

--- a/docs/update-prompts.md
+++ b/docs/update-prompts.md
@ -9,6 +9,8 @@

 ## 单元测试

+/ultrawork 分析下当前测试覆盖率
+
 ## 注释

 /ultrawork 参考 @docs/comments.md，分析项目注释是否完善
--- a/internal/AGENTS.md
+++ b/internal/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # internal

@ -11,11 +11,16 @@
 | Directory | Purpose |
 |-----------|---------|
 | `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） |
+| `cache/` | 文件缓存模块（缓存存储、过期管理） |
 | `config/` | 配置解析、验证和默认值生成 |
-| `handler/` | HTTP 请求处理器（路由、静态文件） |
+| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） |
+| `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
 | `logging/` | 日志系统（zerolog 初始化、访问日志） |
 | `middleware/` | 中间件框架（接口定义、链式组合） |
-| `server/` | HTTP 服务器核心和虚拟主机管理 |
+| `proxy/` | 反向代理模块（HTTP/WebSocket 代理） |
+| `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
+| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） |
+| `stream/` | TCP/UDP Stream 代理模块 |

 ## For AI Agents

--- a/internal/cache/AGENTS.md
+++ b/internal/cache/AGENTS.md
@ -0,0 +1,38 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# cache
+
+## Purpose
+文件缓存模块，提供静态文件的内存缓存和过期管理功能。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `file_cache.go` | 文件缓存核心：FileCache 结构体、Get/Set/Delete、TTL 管理、LRU 淘汰 |
+| `cache_test.go` | 缓存单元测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 缓存项包含文件内容、MIME 类型、最后修改时间
+- TTL 默认 5 分钟，可配置
+- LRU 淘汰策略，最大缓存大小可配置
+- 支持缓存失效和手动清除
+
+### Testing Requirements
+- 运行测试：`go test ./internal/cache/...`
+- 测试缓存存取、过期淘汰、并发安全
+
+### Common Patterns
+- 使用 `sync.RWMutex` 保证并发安全
+- 缓存键为文件路径的哈希值
+- 缓存命中时直接返回内容，避免磁盘 I/O
+
+## Dependencies
+
+### Internal
+- `../config/` - 缓存配置参数
+
+<!-- MANUAL: -->
--- a/internal/handler/AGENTS.md
+++ b/internal/handler/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # handler

@ -12,6 +12,7 @@ HTTP 请求处理器，包含路由管理和静态文件服务功能。
 |------|-------------|
 | `router.go` | 路由器封装：基于 fasthttp/router，支持 GET/POST/PUT/DELETE/HEAD |
 | `static.go` | 静态文件处理器：文件路径安全检查、索引文件支持 |
+| `sendfile.go` | Sendfile 支持：X-Sendfile 头处理、高效文件传输 |

 ## For AI Agents

--- a/internal/loadbalance/AGENTS.md
+++ b/internal/loadbalance/AGENTS.md
@ -0,0 +1,44 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# loadbalance
+
+## Purpose
+负载均衡模块，提供多种负载均衡策略和健康检查功能。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `balancer.go` | 负载均衡核心：Balancer 接口、Upstream、Target 管理 |
+| `algorithms.go` | 负载均衡算法：RoundRobin、LeastConn、Weighted |
+| `health.go` | 健康检查：HealthChecker、被动/主动检查 |
+| `balancer_test.go` | 负载均衡测试 |
+| `health_test.go` | 健康检查测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- `Balancer` 接口定义：Select()、AddTarget()、RemoveTarget()
+- 支持 RoundRobin（轮询）、LeastConn（最少连接）、Weighted（加权）
+- 健康检查支持被动（请求失败计数）和主动（定期探测）
+- 不健康 Target 自动剔除，恢复后自动加入
+
+### Testing Requirements
+- 运行测试：`go test ./internal/loadbalance/...`
+- 测试各算法的正确性、健康检查逻辑
+
+### Common Patterns
+- Target 权重默认为 1
+- 健康检查间隔默认 10 秒
+- 不健康阈值：连续 3 次失败
+
+## Dependencies
+
+### Internal
+- `../config/` - 负载均衡配置
+
+### External
+- `github.com/valyala/fasthttp` - HTTP 客户端用于健康探测
+
+<!-- MANUAL: -->
--- a/internal/middleware/AGENTS.md
+++ b/internal/middleware/AGENTS.md
@ -1,10 +1,10 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # middleware

 ## Purpose
-中间件框架，定义统一的中间件接口和链式组合机制。
+中间件框架，定义统一的中间件接口和链式组合机制，包含多个具体中间件实现。

 ## Key Files

@ -12,6 +12,15 @@
 |------|-------------|
 | `middleware.go` | 中间件接口和链：Middleware 接口、Chain 结构体、Apply 方法 |

+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `accesslog/` | 访问日志中间件（请求记录、响应统计） |
+| `compression/` | 响应压缩中间件（Gzip、Deflate） |
+| `rewrite/` | URL 重写中间件（正则替换、路径转换） |
+| `security/` | 安全中间件（访问控制、认证、限流、安全头部） |
+
 ## For AI Agents

 ### Working In This Directory
--- a/internal/middleware/accesslog/AGENTS.md
+++ b/internal/middleware/accesslog/AGENTS.md
@ -0,0 +1,43 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# accesslog
+
+## Purpose
+访问日志中间件，记录每个请求的详细信息，包括方法、路径、状态码、响应时间和客户端地址。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `accesslog.go` | 访问日志中间件：AccessLog 结构体、Process() 方法、日志格式化 |
+| `accesslog_test.go` | 访问日志测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 记录请求信息：method、path、status、size、duration、remote_addr
+- 支持自定义日志格式
+- 响应时间单位为毫秒
+- 日志级别为 info
+
+### Testing Requirements
+- 运行测试：`go test ./internal/middleware/accesslog/...`
+- 测试日志格式化、字段提取
+
+### Common Patterns
+- 使用 zerolog 的链式 API
+- duration 通过 ctx.Time() 获取
+- 可配置排除路径（如健康检查）
+
+## Dependencies
+
+### Internal
+- `../` - 中间件接口定义
+- `../../logging/` - 日志实例
+
+### External
+- `github.com/rs/zerolog` - 日志库
+- `github.com/valyala/fasthttp` - HTTP 框架
+
+<!-- MANUAL: -->
--- a/internal/middleware/compression/AGENTS.md
+++ b/internal/middleware/compression/AGENTS.md
@ -0,0 +1,42 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# compression
+
+## Purpose
+响应压缩中间件，支持 Gzip 和 Deflate 压缩，自动根据 Accept-Encoding 头选择压缩方式。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `compression.go` | 压缩中间件：Compression 结构体、Process() 方法、压缩级别配置 |
+| `compression_test.go` | 压缩测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 支持 Gzip 和 Deflate 压缩
+- 自动检测 Accept-Encoding 头选择压缩方式
+- 压缩级别可配置（1-9，默认 6）
+- 小于 1KB 的响应不压缩
+
+### Testing Requirements
+- 运行测试：`go test ./internal/middleware/compression/...`
+- 测试压缩检测、响应处理、级别配置
+
+### Common Patterns
+- 使用 fasthttp 的内置压缩支持
+- Content-Type 过滤：仅压缩 text/* 和 application/json
+- Vary: Accept-Encoding 头自动添加
+
+## Dependencies
+
+### Internal
+- `../` - 中间件接口定义
+- `../../config/` - 压缩配置
+
+### External
+- `github.com/valyala/fasthttp` - HTTP 框架（内置压缩）
+
+<!-- MANUAL: -->
--- a/internal/middleware/rewrite/AGENTS.md
+++ b/internal/middleware/rewrite/AGENTS.md
@ -0,0 +1,39 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# rewrite
+
+## Purpose
+URL 重写中间件，支持正则表达式匹配和替换，实现 URL 路径转换。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `rewrite.go` | 重写中间件：Rewrite 结构体、Rule 定义、正则匹配替换 |
+| `rewrite_test.go` | 重写测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 使用正则表达式匹配 URL 路径
+- 支持捕获组替换（$1、$2 等）
+- 重写后继续处理，不终止请求
+- 可配置多条规则，按顺序匹配
+
+### Testing Requirements
+- 运行测试：`go test ./internal/middleware/rewrite/...`
+- 测试正则匹配、捕获组替换、多规则处理
+
+### Common Patterns
+- 规则格式：Pattern（正则）→ Replacement（替换字符串）
+- 重写后更新 ctx.Path()，不影响路由匹配
+- 匹配失败时跳过该规则
+
+## Dependencies
+
+### Internal
+- `../` - 中间件接口定义
+- `../../config/` - 重写规则配置
+
+<!-- MANUAL: -->
--- a/internal/middleware/security/AGENTS.md
+++ b/internal/middleware/security/AGENTS.md
@ -0,0 +1,46 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# security
+
+## Purpose
+安全中间件集合，提供访问控制、认证、限流和安全头部功能，保护服务器免受常见攻击。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `access.go` | 访问控制：IP 白名单/黑名单、地理位置限制、allow/deny 规则 |
+| `auth.go` | 认证中间件：Basic Auth、Bearer Token、JWT 验证 |
+| `ratelimit.go` | 限流中间件：请求限流、连接限流、令牌桶算法 |
+| `headers.go` | 安全头部：X-Frame-Options、X-Content-Type-Options、CSP、HSTS |
+| `*_test.go` | 各模块单元测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 访问控制支持 CIDR 格式 IP 范围
+- Basic Auth 使用 bcrypt 密码哈希
+- 限流使用令牌桶算法，支持按 IP/全局限流
+- 安全头部可配置启用/禁用
+
+### Testing Requirements
+- 运行测试：`go test ./internal/middleware/security/...`
+- 测试 IP 匹配、密码验证、限流逻辑、头部设置
+
+### Common Patterns
+- 访问控制按顺序匹配：先检查黑名单，再检查白名单
+- 限流阈值：请求速率（req/s）、并发连接数
+- 认证失败返回 401，限流触发返回 429
+
+## Dependencies
+
+### Internal
+- `../` - 中间件接口定义
+- `../../config/` - 安全配置
+
+### External
+- `golang.org/x/crypto/bcrypt` - 密码哈希
+- `github.com/valyala/fasthttp` - HTTP 框架
+
+<!-- MANUAL: -->
--- a/internal/proxy/AGENTS.md
+++ b/internal/proxy/AGENTS.md
@ -0,0 +1,45 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# proxy
+
+## Purpose
+反向代理模块，提供 HTTP 和 WebSocket 代理功能，支持连接池和超时控制。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `proxy.go` | HTTP 反向代理核心：Proxy 结构体、Forward()、请求/响应处理 |
+| `websocket.go` | WebSocket 代理：握手升级、双向数据转发、连接管理 |
+| `health.go` | 健康检查集成：与 loadbalance 模块协作 |
+| `proxy_test.go` | HTTP 代理测试 |
+| `health_test.go` | 健康检查测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- HTTP 代理使用 fasthttp 的 HostClient 进行转发
+- WebSocket 代理支持双向数据流，处理 Upgrade 请求
+- 连接池配置：MaxConns、MaxIdleConnDuration
+- 超时配置：ReadTimeout、WriteTimeout、IdleTimeout
+
+### Testing Requirements
+- 运行测试：`go test ./internal/proxy/...`
+- 测试请求转发、WebSocket 升级、超时处理
+
+### Common Patterns
+- 代理请求时复制原始头部，添加 X-Forwarded-For
+- WebSocket 使用 goroutine 双向转发
+- 错误响应返回 502（Bad Gateway）或 504（Gateway Timeout）
+
+## Dependencies
+
+### Internal
+- `../loadbalance/` - 目标选择和健康检查
+- `../config/` - 代理配置
+
+### External
+- `github.com/valyala/fasthttp` - HTTP 客户端/服务器
+
+<!-- MANUAL: -->
--- a/internal/server/AGENTS.md
+++ b/internal/server/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-03 -->

 # server

@ -12,6 +12,9 @@ HTTP 服务器核心，提供服务器创建、启动、停止和虚拟主机管
 |------|-------------|
 | `server.go` | 服务器核心：Server 结构体、Start()、Stop()、GracefulStop() |
 | `vhost.go` | 虚拟主机管理：VHostManager、VirtualHost、按 Host 头匹配 |
+| `pool.go` | 连接池管理：Worker 池、连接复用、并发控制 |
+| `upgrade.go` | 热升级：UpgradeManager、USR2 信号处理、平滑交接 |
+| `status.go` | 状态监控：健康端点、统计信息、Prometheus 格式 |

 ## For AI Agents

--- a/internal/ssl/AGENTS.md
+++ b/internal/ssl/AGENTS.md
@ -0,0 +1,44 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# ssl
+
+## Purpose
+SSL/TLS 模块，提供证书加载、OCSP Stapling 和 TLS 配置管理功能。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `ssl.go` | SSL/TLS 核心：证书加载、TLS 配置、SNI 支持、会话缓存 |
+| `ocsp.go` | OCSP Stapling：在线证书状态查询、缓存、自动刷新 |
+| `ssl_test.go` | SSL/TLS 测试 |
+| `ocsp_test.go` | OCSP 测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- 支持多证书加载，按 SNI 匹配
+- OCSP Stapling 提升 TLS 握手性能
+- TLS 配置强制使用安全参数（TLS 1.2+、强密码套件）
+- 会话缓存减少握手开销
+
+### Testing Requirements
+- 运行测试：`go test ./internal/ssl/...`
+- 测试证书加载、OCSP 查询、TLS 配置
+
+### Common Patterns
+- 证书格式支持 PEM
+- OCSP 响应缓存 1 小时
+- 会话票据自动轮换
+
+## Dependencies
+
+### Internal
+- `../config/` - SSL 配置
+
+### External
+- `crypto/tls` - Go 标准库 TLS 实现
+- `golang.org/x/crypto/ocsp` - OCSP 协议支持
+
+<!-- MANUAL: -->
--- a/internal/stream/AGENTS.md
+++ b/internal/stream/AGENTS.md
@ -0,0 +1,39 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-03 | Updated: 2026-04-03 -->
+
+# stream
+
+## Purpose
+TCP/UDP Stream 代理模块，支持四层代理和会话管理。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `stream.go` | Stream 代理核心：TCP/UDP 服务器、连接转发、会话管理 |
+| `stream_test.go` | Stream 代理测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- TCP 代理：监听端口、转发连接、支持多上游
+- UDP 代理：会话管理、超时控制、NAT 穿透
+- 会话跟踪：源地址+端口作为键
+- 超时配置：连接超时、空闲超时
+
+### Testing Requirements
+- 运行测试：`go test ./internal/stream/...`
+- 测试 TCP/UDP 监听、连接转发、会话管理
+
+### Common Patterns
+- TCP 使用 net.Conn 进行双向数据拷贝
+- UDP 使用会话映射表管理客户端连接
+- 负载均衡策略与 HTTP 代理共享
+
+## Dependencies
+
+### Internal
+- `../loadbalance/` - 目标选择
+- `../config/` - Stream 配置
+
+<!-- MANUAL: -->