Imported from DragonCat1/DnsTube (AGENTS.md). Install upstream with npx skills add DragonCat1/DnsTube. Copyright stays with the author.

DnsTube — Agent / 贡献者指南

架构

• 单进程：cmd/dnstube 同时启动 UDP DNS（每实例一监听）与 HTTP 管理 API。
• 分层：internal/dns（解析、缓存、转发）→ 不直接写 SQL；internal/store（PostgreSQL）；internal/api（REST、DTO）；internal/auth（JWT、密码）。
• 配置：运行时以 PostgreSQL 为准；无配置文件热重载。

目录索引

Web 管理端（Vue）

• 日期时间展示：所有面向用户的日期+时间统一为 YYYY-MM-DD HH:mm:ss（24 小时制，浏览器本地时区）。使用 web/src/datetime.ts 的 formatDateTime / DATE_TIME_FORMAT，勿用 toLocaleString() 等与运行环境强绑定的格式。Cursor 规则见 .cursor/rules/dnstube-web.mdc。

已决行为（摘要）

• 并行转发：多上游竞速，取最快有效解析；超时/防投毒按通用实践。
• 顺序转发：组内顺序尝试，首个解析结果即停。
• 静态记录优先于转发。
• 上游协议：每条上游服务器可选 UDP / DoT / DoH；地址只接受 IP 字面量（IPv4/IPv6），DoH 端点路径与可选 SNI 在表单中按需显示，详见 .cursor/skills/dnstube-dns-forwarding。
• 首启管理员：无账号时创建用户 admin / 密码 admin，并 打日志（登录后请改密）。
• 查询日志：多字段、永久存 DB；管理端 查删；Dashboard 查询量 = 客户端请求次数。

常用命令

make tidy          # go mod tidy
make build         # 构建 dnstube 二进制
make dev-api       # 需本地 PostgreSQL 与 DATABASE_URL
make dev-web       # 前端开发服务器

环境变量见 .env.example。

API

• 前缀：/api/v1/
• 鉴权：Authorization: Bearer <JWT>（除 POST /api/v1/auth/login）
• 响应：success、code（0 成功，非 0 为 APICodeNum 数值）、message；对象接口 data 为对象或 null；列表接口另含 page、total，且 data 必为数组（见 .cursor/rules/dnstube-api.mdc）。字符串错误码仍定义在 internal/api/errcode.go，文案由 msgForCode 映射。

Agent 资产文档维护

• 资产范围：AGENTS.md、web/AGENTS.md、.cursor/rules/、.cursor/skills/、.cursor/agents/ 统一视为 Agent 资产。
• 变更同步：涉及流程约定、目录职责、接口规范、环境变量、常用命令或工作流变化时，必须同步更新对应 Agent 资产文档。
• 单一事实源：同一规则只保留一个主文档；其他文件通过引用指向，避免重复拷贝导致漂移。
• 最小必要更新：仅更新与本次需求直接相关的段落，不做无关重写；文档内容需可执行、可验证，避免空泛描述。
• PR 说明要求：若本次改动影响 Agent 行为，提交说明中需明确“已更新哪些 Agent 资产、为什么更新、如何验证生效”。

禁止

• 在 internal/dns 中写 SQL。
• 无必要的大范围重构；改动与 issue/计划对齐。