lolly/.agents/skills/update-generate-config.md

Skill: 更新 -g 默认配置模板

当 config struct 新增/修改字段时，同步更新 GenerateConfigYAML 输出模板。

涉及文件

文件	职责
internal/config/*.go	struct 定义（改字段）
internal/config/defaults.go	DefaultConfig() 默认值 + GenerateConfigYAML() 模板
internal/config/defaults_test.go	TestGenerateConfigYAML* 覆盖率测试

更新流程

1. 修改 struct

在对应的 *_config.go 文件中添加/修改字段，确保：

• 有 yaml tag
• 有中文注释说明字段用途和有效值

2. 更新 DefaultConfig()

在 defaults.go 的 DefaultConfig() 函数中为新字段设置合理默认值。

3. 更新 GenerateConfigYAML()

在 defaults.go 的 GenerateConfigYAML() 函数中，找到对应区块，添加/修改模板行。

规则：

1. 格式一致性：使用 buf.WriteString 写注释行，fmt.Fprintf 写带默认值的行
2. 注释行前缀：可选配置用 # 注释，必填/有默认值的配置直接输出
3. 注释规范：每行末尾 # 注释说明用途，新字段加 # 有效值: a, b, c 格式的可选值说明
4. 默认值来源：使用 cfg.Servers[0].Xxx 读取 DefaultConfig() 的值，不硬编码
5. 缩进层级：
   • 顶层配置无缩进（logging:, http3:）
   • server 内配置 4 空格（ listen:）
   • server 子配置 6-8 空格（ access:）
   • 注释中的示例配置也保持正确缩进

4. struct 字段 → GenerateConfigYAML 区块对照表

struct 文件	GenerateConfigYAML 区块
config.go → Config.Mode	mode 注释块（~L254）
config.go → Config.Mode	servers 开头（~L263）
server_config.go → ServerConfig	servers 列表内（L264-288）
server_config.go → TypesConfig	types 注释块（~L292）
server_config.go → LimitRateConfig	limit_rate 注释块（~L302）
monitoring_config.go → CacheAPIConfig	cache_api 注释块（~L310）
variable_config.go → LuaMiddlewareConfig	lua 注释块（~L324）
variable_config.go → CompressionConfig	compression 块（~L607）
variable_config.go → RewriteRule	rewrite 注释块（~L598）
server_config.go → StaticConfig	static 块（~L349）
proxy_config.go → ProxyConfig	proxy 注释块（~L385）
proxy_config.go → ProxyTimeout	proxy.timeout（~L413）
proxy_config.go → ProxyBufferingConfig	proxy.buffering（~L418）
proxy_config.go → HealthCheckConfig	proxy.health_check（~L403）
proxy_config.go → ProxyHeaders	proxy.headers（~L424）
cache_config.go → ProxyCacheConfig	proxy.cache（~L435）
cache_config.go → ProxyCacheValidConfig	proxy.cache_valid（~L448）
proxy_config.go → ProxySSLConfig	proxy.proxy_ssl（~L454）
proxy_config.go → NextUpstreamConfig	proxy.next_upstream（~L464）
proxy_config.go → BalancerByLuaConfig	proxy.balancer_by_lua（~L467）
proxy_config.go → RedirectRewriteConfig	proxy.redirect_rewrite（~L472）
ssl_config.go → SSLConfig	ssl 注释块（~L486）
ssl_config.go → SessionTicketsConfig	ssl.session_tickets（~L506）
ssl_config.go → ClientVerifyConfig	ssl.client_verify（~L511）
performance_config.go → HTTP2Config	ssl.http2（~L517）
security_config.go → SecurityConfig	security 块（~L534）
security_config.go → AccessConfig/GeoIPConfig	security.access/geoip（~L537）
security_config.go → RateLimitConfig	security.rate_limit（~L555）
security_config.go → AuthConfig	security.auth（~L564）
security_config.go → SecurityHeaders	security.headers（~L573）
security_config.go → ErrorPageConfig	security.error_page（~L581）
security_config.go → AuthRequestConfig	security.auth_request（~L587）
performance_config.go → ShutdownConfig	shutdown 块（~L623）
server_config.go → StreamConfig	stream 注释块（~L631）
monitoring_config.go → LoggingConfig	logging 块（~L662）
performance_config.go → PerformanceConfig	performance 块（~L676）
performance_config.go → HTTP3Config	http3 块（~L693）
monitoring_config.go → MonitoringConfig	monitoring 块（~L703）
performance_config.go → ResolverConfig	resolver 块（~L723）
variable_config.go → VariablesConfig	variables 块（~L737）
variable_config.go → IncludeConfig	include 注释块（~L745）

5. 运行验证

# 测试模板覆盖率（检查 struct 字段是否都在模板中出现）
go test -v -run TestGenerateConfigYAML ./internal/config/...

# 测试 app 层 generateConfig 函数
go test -v -run TestGenerateConfig ./internal/app/...

# 完整测试 + lint
make test
make lint

添加新字段的模板示例

简单字符串字段（可选，注释形式）

buf.WriteString("    #   new_field: \"\"           # 新字段说明（有效值: a, b, c）\n")

带默认值的字段（使用 fmt.Fprintf）

fmt.Fprintf(&buf, "    #   new_field: %d          # 新字段说明\n", cfg.Servers[0].NewField)

新的嵌套结构体

buf.WriteString("    # new_section:                 # 新区块说明\n")
buf.WriteString("    #   enabled: false            # 是否启用\n")
buf.WriteString("    #   option: \"\"               # 选项说明\n")
buf.WriteString("\n")

常见遗漏检查清单

添加新字段后，逐项确认：

• struct 有 yaml tag
• DefaultConfig() 有默认值
• GenerateConfigYAML() 有注释行（可选字段）或输出行（有默认值的字段）
• 注释中包含 有效值: 说明（枚举类字段）
• fmt.Fprintf 使用 cfg.Servers[0].Xxx 而非硬编码数字
• TestGenerateConfigYAMLFieldsCoverage 通过（它会检查 struct 字段是否出现在模板中）
• make lint 无新增 warning