docs: 新增模块 AGENTS.md 文档，更新目录索引

- 新增 http2、integration、resolver、variable 模块 AGENTS.md - 更新 internal/AGENTS.md 目录表，补充新模块条目 - 更新 docs/prompts.md 添加 generate-config 缺失项分析提示 - 同步更新日期戳至 2026-04-09 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-09 13:35:29 +08:00 · 2026-04-09 13:35:29 +08:00 · 392d0b3449
commit 392d0b3449
parent a298ca7254
7 changed files with 196 additions and 3 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -1,4 +1,4 @@
-<!-- Generated: 2026-04-02 | Updated: 2026-04-07 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-09 -->

 # lolly

--- a/docs/prompts.md
+++ b/docs/prompts.md
@ -7,7 +7,9 @@ ulw 深度分析下 @docs/ 下的 nginx 文档，看看当前项目实现的怎

 ulw 深度分析 https://nginx.org/en/docs/ nginx 的功能，@docs/ 目录下已经有一些分析过的文档了，看看有没有能完善的

-ulw 深度分析下当前的 --generate-config，是否有配置文件描述了，但代码未实现的功能。同时也分析下有没有代码实现了，但是配置文件缺失的地方
+ulw 深度分析下当前的 --generate-config，是否有配置文件描述了，但代码未实现的功能。
+
+ulw 深度分析下有没有代码实现了，但是 --generate-config 缺失的地方

 ulw 逐行分析下当前的 --generate-config，看看代码中是否都实现了

--- a/internal/AGENTS.md
+++ b/internal/AGENTS.md
@ -1,5 +1,5 @@
 <!-- Parent: ../AGENTS.md -->
-<!-- Generated: 2026-04-02 | Updated: 2026-04-07 -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-09 -->

 # internal

@ -15,15 +15,19 @@
 | `cache/` | 文件缓存模块（缓存存储、过期管理） |
 | `config/` | 配置解析、验证和默认值生成 |
 | `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） |
+| `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） |
 | `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） |
+| `integration/` | 集成测试（多模块端到端协作验证） |
 | `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） |
 | `logging/` | 日志系统（zerolog 初始化、访问日志） |
 | `middleware/` | 中间件框架（接口定义、链式组合） |
 | `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） |
 | `proxy/` | 反向代理模块（HTTP/WebSocket 代理） |
+| `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） |
 | `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 |
 | `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） |
 | `stream/` | TCP/UDP Stream 代理模块 |
+| `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） |

 ## For AI Agents

--- a/internal/http2/AGENTS.md
+++ b/internal/http2/AGENTS.md
@ -0,0 +1,49 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
+
+# http2
+
+## Purpose
+HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN 协议协商、与 fasthttp handler 的集成、优雅关闭支持。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `server.go` | HTTP/2 服务器核心：Server 结构、NewServer、Start、GracefulStop |
+| `adapter.go` | fasthttp 适配层：FastHTTPHandlerAdapter、零拷贝头部转换、流式请求体处理 |
+| `server_test.go` | 服务器测试：创建、启动、关闭测试 |
+| `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 |
+| `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 |
+
+## For AI Agents
+
+### Working In This Directory
+- HTTP/2 服务器使用标准库 http.Handler 接口
+- 通过适配层转换 fasthttp.RequestHandler → http.Handler
+- 需要 TLS 配置进行 ALPN 协商（h2 协议标识）
+- 使用 sync.Pool 复用缓冲区实现零拷贝优化
+- 预估每请求 5-10µs 适配开销
+
+### Testing Requirements
+- 运行测试：`go test ./internal/http2/...`
+- 测试需要 TLS 配置（部分测试）
+- 集成测试验证完整请求流程
+
+### Common Patterns
+- NewServer(cfg, handler, tlsConfig) 创建服务器
+- Start() 在现有 TCP 监听器上启动
+- GracefulStop() 优雅关闭等待请求完成
+- FastHTTPHandlerAdapter.ServeHTTP 实现标准库接口
+
+## Dependencies
+
+### Internal
+- `../config/` - HTTP2Config 配置结构体
+- `../logging/` - 日志模块
+
+### External
+- `golang.org/x/net/http2` - HTTP/2 协议实现
+- `github.com/valyala/fasthttp` - fasthttp handler 类型
+
+<!-- MANUAL: -->
--- a/internal/integration/AGENTS.md
+++ b/internal/integration/AGENTS.md
@ -0,0 +1,43 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
+
+# integration
+
+## Purpose
+集成测试目录，测试多个模块之间的端到端协作，验证组件间的正确集成。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `resolver_test.go` | DNS 解析器集成测试：基本解析、缓存功能、网络依赖测试 |
+| `variable_test.go` | 变量系统集成测试：变量在日志、代理、重写中的端到端使用 |
+
+## For AI Agents
+
+### Working In This Directory
+- 集成测试验证多模块协作，不同于单元测试
+- 测试依赖真实网络环境（DNS 解析测试）
+- 测试可能因网络原因跳过（Skip）
+- 变量系统测试覆盖 nginx 风格格式展开
+
+### Testing Requirements
+- 运行测试：`go test ./internal/integration/...`
+- 网络测试可能需要外部环境支持
+- 测试验证端到端流程而非单个函数
+
+### Common Patterns
+- 使用真实配置结构体初始化测试
+- 模拟 fasthttp.RequestCtx 进行请求测试
+- Skip 处理网络不可用情况
+
+## Dependencies
+
+### Internal
+- `../resolver/` - DNS 解析器模块
+- `../variable/` - 变量系统模块
+- `../config/` - 配置模块
+- `../logging/` - 日志模块
+- `../middleware/rewrite/` - URL 重写中间件
+
+<!-- MANUAL: -->
--- a/internal/resolver/AGENTS.md
+++ b/internal/resolver/AGENTS.md
@ -0,0 +1,47 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
+
+# resolver
+
+## Purpose
+DNS 解析器模块，提供带缓存的 DNS 解析功能，支持动态解析后端服务域名、TTL 缓存、后台刷新。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `resolver.go` | DNS 解析器核心：Resolver 接口、DNSResolver 实现、LookupHost 方法 |
+| `cache.go` | DNS 缓存管理：缓存条目结构、TTL 过期、缓存命中统计 |
+| `stats.go` | 统计信息：ResolverStats 结构、缓存命中率、解析延迟追踪 |
+| `resolver_test.go` | 单元测试：解析功能、缓存行为、错误处理测试 |
+
+## For AI Agents
+
+### Working In This Directory
+- Resolver 接口定义：LookupHost、LookupHostWithCache、Refresh、Start、Stop
+- 使用 sync.Map 实现并发安全缓存
+- 后台刷新需要调用 Start() 启动
+- 停止使用时应调用 Stop() 释放资源
+- 用于代理模块动态解析 upstream 域名
+
+### Testing Requirements
+- 运行测试：`go test ./internal/resolver/...`
+- 测试覆盖缓存逻辑和错误处理
+- 集成测试在 `../integration/` 目录
+
+### Common Patterns
+- 接口设计支持多种解析器实现
+- 缓存条目包含 TTL 和过期时间
+- 统计信息使用 atomic 计数器
+
+## Dependencies
+
+### Internal
+- `../config/` - ResolverConfig 配置结构体
+
+### External
+- `net` - Go 标准库 DNS 解析
+- `sync` - 并发安全
+- `context` - 上下文超时控制
+
+<!-- MANUAL: -->
--- a/internal/variable/AGENTS.md
+++ b/internal/variable/AGENTS.md
@ -0,0 +1,48 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-09 | Updated: 2026-04-09 -->
+
+# variable
+
+## Purpose
+高性能变量系统，提供 nginx 风格的变量展开功能。用于访问日志格式模板、代理请求头设置、URL 重写规则。
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `variable.go` | 变量系统核心：VariableContext 结构、Expand 方法、变量存储接口 |
+| `builtin.go` | 内置变量定义：$remote_addr、$request_uri、$status、$time_local 等nginx 风格变量 |
+| `pool.go` | sync.Pool 复用：PoolGet、PoolPut、池统计信息 |
+| `ssl.go` | SSL 相关变量：$ssl_protocol、$ssl_cipher、$ssl_client_sni 等 |
+| `variable_test.go` | 单元测试：变量展开、内置变量获取、自定义变量 |
+| `variable_bench_test.go` | 基准测试：展开性能、池性能 |
+
+## For AI Agents
+
+### Working In This Directory
+- 支持两种变量格式：$var 和 ${var}（用于变量后有字符）
+- 使用快速字符串扫描（非正则表达式）提升性能
+- sync.Pool 复用 VariableContext 减少 GC 压力
+- 内置变量惰性求值并缓存结果
+- 自定义变量通过 Set 方法设置
+
+### Testing Requirements
+- 运行测试：`go test ./internal/variable/...`
+- 基准测试验证展开性能：`go test -bench=. ./internal/variable/...`
+- 集成测试在 `../integration/` 目录
+
+### Common Patterns
+- VariableContext 绑定到单个请求
+- 从池获取：PoolGet(ctx)，放回：PoolPut(vc)
+- 全局变量通过 SetGlobalVariables 设置
+- 上游变量：$upstream_addr、$upstream_status、$upstream_response_time
+
+## Dependencies
+
+### Internal
+- 无内部依赖，底层模块
+
+### External
+- `github.com/valyala/fasthttp` - RequestCtx 类型
+
+<!-- MANUAL: -->