AGENTS.md

AGENTS.md — 代理工作规范

项目定位

纯 Nim 实现的 HTTP 客户端，从零构建 TCP + TLS，支持 SSE 流式传输。目标 Nim 2.0+，零第三方依赖。

核心原则

1. 零第三方依赖: 仅用 Nim 标准库。SSL 通过 std/openssl 或 net 实现。
2. 协议正确性: HTTP/1.1 严格遵循 RFC 7230-7235。
3. 流式优先: SSE 和所有响应体都以流式方式处理，避免内存膨胀。
4. API 简洁: jQuery 风格链式调用，隐藏底层复杂度。

代码风格

• Nim 标准命名: camelCase 过程名, PascalCase 类型名
• 显式错误处理: 使用 Result[T, E] 模式或异常，不忽略错误
• 文档: 所有公开 API 必须带 ## 文档注释
• 测试: 每个模块对应测试文件

关键设计决策

• 使用 net.Socket 做 TCP，连接不复用（v0.1 无连接池）
• HTTPS 使用标准库 openssl 模块的 SslContext
• 证书验证默认严格，提供 insecureSkipVerify 开关
• SSE 解析器必须是增量式的（流式接收 chunk）
• 响应体支持 sync / async 两种消费模式

架构约定

• src/core/: 底层协议与连接
• src/protocols/: HTTP 协议实现
• src/streaming/: SSE 流式解析
• src/ssl/: TLS/SSL 封装
• tests/: 单元测试与集成测试
• examples/: 可运行示例