docs: AGENT.md

AGENTS.md

@@ -0,0 +1,43 @@
+
+
+
+# 代码库指南 (Repository Guidelines)
+
+## 项目结构与模块组织 (Project Structure & Module Organization)
+`OmniSocketGo` 是一个基于 Go 1.22 的小型模块，在 `cmd/` 目录下有三个命令行（CLI）入口点：`cmd/server`、`cmd/peer` 和 `cmd/latencysummary`。共享代码存放于 `cmd/internal/` 目录下：
+
+- `protocol` 用于消息的编码/解码
+- `server` 用于连接中心（hub）逻辑
+- `peer` 用于客户端的发送/接收与持久化
+- `transport` 用于 TCP 传输和 Linux 时间戳处理
+- `latencylog` 用于 JSONL 日志记录和摘要生成
+
+请将测试文件与它们覆盖的代码放在一起（即 `*_test.go`）。使用 `bin/` 目录存放本地构建输出，使用 `inbox/` 目录存放接收到的负载数据；这两个目录均已被忽略（不在版本控制内），不应提交到代码库中。
+
+## 构建、测试与开发命令 (Build, Test, and Development Commands)
+显式构建主要的二进制文件：
+
+- `go build -o bin/server ./cmd/server`
+- `go build -o bin/peer ./cmd/peer`
+- `go build -o bin/latencysummary ./cmd/latencysummary`
+
+在 Linux 上运行完整的测试套件：
+
+- `go test ./...`
+
+需要部署时进行交叉编译：
+
+- `CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/server-linux-amd64 ./cmd/server`
+
+在代码审查前格式化已编辑的文件：
+
+- `gofmt -w cmd/peer/main.go`
+
+## 编码风格与命名规范 (Coding Style & Naming Conventions)
+遵循标准的 Go 代码风格，让 `gofmt` 控制代码格式；请勿手动对齐代码。保持包名小写，导出的标识符使用大驼峰命名法（`CamelCase`），未导出的辅助函数/变量使用小驼峰命名法（`mixedCase`）。与现有的 CLI 标志（flag）命名保持一致，使用小写且带连字符的选项，例如 `-bind-device` 和 `-latency-log`。优先编写功能聚焦的包和简短的函数，而不是随意添加新的顶层二进制文件或包含过多杂项的通用工具文件。
+
+## 测试指南 (Testing Guidelines)
+使用 Go 内置的 `testing` 包。优先编写结合 `t.Run` 的表格驱动测试（table-driven tests），参考类似 `cmd/peer/interactive_test.go` 的文件。测试的命名应基于可观察到的行为，而不是内部实现细节。Linux 特有的行为测试应放在 `*_linux_test.go` 文件中。本项目未配置代码覆盖率门禁限制，但新增的协议、传输或持久化逻辑应当包含单元测试，并在相关的地方提供错误路径（error-path）的覆盖测试。
+
+## 平台与配置说明 (Platform & Configuration Notes)
+本项目以 Linux 为目标平台。传输层依赖于 Linux 特有的时间戳代码，因此完整构建和 `go test ./...` 应视为仅限 Linux 平台的验证操作。