diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..43a16bd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,649 @@
+# AGENTS.md
+
+本文件是 NetStable 项目的维护入口。任何自动化代理、Codex 会话或人工维护者在改动本仓库前都应先读这里。
+
+## 基本原则
+
+- 用最简单、直接、改动最少的实现，优先复用现有文件、函数和类型。
+- 仅为当前实际需求或明显重复逻辑增加抽象，不为未来扩展提前设计。
+- 替换实现时移除旧路径，避免新旧双轨。
+- 不做顺手重构。除非它直接服务当前问题，否则不要改命名、目录结构、样式或部署流程。
+- 不回滚用户或其他维护者的改动。遇到不相关的脏工作区，忽略；遇到相关冲突，先读懂再处理。
+- 所有影响生产行为的改动都必须有验证证据：至少跑相关测试；改到公共路径时跑 `go test ./... -count=1`。
+- 完成代码改动后，提交并对齐 Gitea，除非用户明确要求不要提交或不要推送。
+
+## 项目概况
+
+NetStable 是一个独立 Go Web/CLI 测速项目，用于测试用户浏览器或 CLI 到部署服务器的网络质量。
+
+核心能力：
+
+- 浏览器测速：用户打开网页后测试下载、上传、延迟和稳定性。
+- CLI 测速：同一个二进制可作为客户端运行，支持 HTTP 和 `iperf3` 模式。
+- 全局锁：同一时间只允许一个用户真正测速，其它用户进入 FIFO 队列。
+- 半截记录：已经产生样本的中断/停止测试也必须保存为历史记录；还没轮到且没有样本的排队取消不生成空记录。
+- 历史记录：完整样本曲线、摘要、脱敏 IP、地区、运营商写入 JSONL。
+- 域名访问：生产主入口是 `https://speedtest.hzct.obscura.work/`。
+
+## 仓库信息
+
+- 本地路径：`/Users/kanshan/Documents/speedtest`
+- Gitea 仓库：`https://git.aiot.ml/kanshan/speedtest`
+- 远端名：`origin`
+- 远端主分支：`main`
+- 当前本地工作分支通常是：`codex/go-network-stability-tester`
+- 推送当前 HEAD 到 Gitea 主分支：
+
+```bash
+git push origin HEAD:main
+```
+
+提交前后检查：
+
+```bash
+git status --short --branch
+git log --oneline --decorate -5
+git remote -v
+git ls-remote origin refs/heads/main
+```
+
+不要提交 `dist/`、本地 JSONL 记录、日志或临时文件；这些已在 `.gitignore` 中排除。
+
+## 代码结构
+
+- `cmd/netstable/main.go`
+  - CLI 入口。
+  - 默认不带子命令时启动服务端。
+  - `serve` 启动 Web 服务。
+  - `client` 运行 HTTP/iperf3 客户端测速。
+
+- `internal/web/server.go`
+  - HTTP API、网页静态资源、队列、全局锁、记录完成、下载/上传接口、iperf3 会话。
+  - 这是生产行为最关键的文件，修改前必须读相关测试。
+
+- `internal/web/runner.go`
+  - 服务端 SSE/探测 runner。
+
+- `internal/client/client.go`
+  - HTTP CLI 客户端。
+  - 负责创建会话、排队等待、下载/上传阶段、complete/cancel。
+  - 已产生样本后中断，必须走 partial complete，不能只 cancel。
+
+- `internal/client/iperf3.go`
+  - CLI iperf3 模式。
+  - 服务端创建一次性高端口，客户端执行本机 `iperf3`，完成后回写记录。
+
+- `internal/probe`
+  - TCP/HTTP 探测样本和摘要计算。
+
+- `internal/store`
+  - JSONL 历史记录读写。
+  - 单条记录可能很大，读取端已提高到 64 MiB 单行上限。
+
+- `internal/geo`
+  - IP 地区/运营商解析。
+  - 优先内置 `ip2region_v4.xdb`，再走在线 fallback。
+
+- `internal/limit`
+  - 程序级带宽限速。
+  - 生产当前默认不限速。
+
+- `web/static`
+  - 前端 HTML/CSS/JS。
+  - 一键 CLI 命令由 `web/static/app.js` 根据当前 `window.location.origin` 生成。
+
+- `data/ip2region_v4.xdb`
+  - 内置 IPv4 数据库。
+
+- `deploy/netstable.service`
+  - systemd 服务模板。
+
+- `.gitea/workflows/ci.yml`
+  - Gitea Actions：测试、vet、release artifact。
+
+## 关键业务约束
+
+这些约束比局部代码风格更重要，不能破坏。
+
+1. 同一时间只能有一个真正测速会话。
+   - `Server.activeID` 是全局锁。
+   - 普通 Web/CLI HTTP 测试和 iperf3 测试必须共用同一个锁。
+   - 其它请求必须排队，而不是并发跑测速。
+
+2. 队列必须 FIFO。
+   - 新请求在有 active 会话时进入 `Server.queue`。
+   - active 完成、取消或过期后只提升队列头。
+   - 手动停止或 CLI 中断必须释放队列。
+
+3. 已产生样本的半截测试必须保存。
+   - CLI HTTP 中断：如果 `samples` 非空，先 complete partial，再返回原始中断错误。
+   - 浏览器停止/刷新：如果 `state.samples.length > 0`，优先 complete partial。
+   - 还没轮到、没有样本的取消只释放队列，不写空记录。
+
+4. complete 成功写入记录后才释放会话。
+   - 如果 `Store.Append` 失败，complete 应返回 500，并保留会话以便重试。
+   - 不能先 `takeSession` 再写盘，否则会丢记录。
+
+5. 历史记录必须保护隐私。
+   - API 输出的 IP 必须脱敏。
+   - ISP 缺失时显示 `未知运营商`。
+   - 不要在前端、日志或 API 输出完整用户 IP，除非用户明确要求调试且范围受控。
+
+6. 大样本记录必须可保存和读取。
+   - complete body 上限：64 MiB。
+   - JSONL 单行读取上限：64 MiB。
+   - 不要把限制改回 2 MiB 或默认 scanner 64 KiB。
+
+7. 峰值口径不能用单次极短请求直接当最大值。
+   - 现有逻辑使用持续窗口计算 max，避免计时误差导致几百 Mbps 的假峰值。
+
+8. 生产默认不限速。
+   - `-bandwidth-limit-mbps 0` 表示不限速。
+   - 如果用户要求限速，必须同时更新页面显示和服务启动参数。
+
+## 常用开发命令
+
+本地测试：
+
+```bash
+go test ./... -count=1
+go vet ./...
+```
+
+运行服务端：
+
+```bash
+go run ./cmd/netstable serve -listen 127.0.0.1:18080 -data /tmp/netstable-records.jsonl -geo-base ''
+```
+
+运行 CLI HTTP 测试：
+
+```bash
+go run ./cmd/netstable client -server http://127.0.0.1:18080 -duration 15
+```
+
+构建本机二进制：
+
+```bash
+make build
+```
+
+构建 Linux release 包：
+
+```bash
+make release VERSION=v0.1.0
+```
+
+生成文件：
+
+- `dist/netstable-v0.1.0-linux-amd64.tar.gz`
+- `dist/netstable-v0.1.0-linux-arm64.tar.gz`
+- `dist/checksums.txt`
+
+更新 IP 数据库：
+
+```bash
+make update-ip-db
+```
+
+更新数据库后必须检查 `THIRD_PARTY.md` 和 `LICENSES/ip2region-LICENSE.md` 是否仍然准确。
+
+## 测试要求
+
+最小规则：
+
+- 修改 Go 行为：跑对应 package 测试，再跑 `go test ./... -count=1`。
+- 修改公共服务端路径：同时跑 `go vet ./...`。
+- 修改 release/deploy/CI：跑 `make release VERSION=v0.1.0`。
+- 修改前端 JS：跑 `node --check web/static/app.js` 和 `go test ./web -count=1`。
+- 修改生产相关配置：先本地校验配置，再线上验证接口。
+
+重点回归测试名称：
+
+- `TestCompleteEndpointAcceptsLargeSamplePayload`
+- `TestCompleteEndpointCanRetryWhenPersistFails`
+- `TestRunPersistsPartialRecordWhenCanceledAfterSamples`
+- `TestRunCompletesBrowserCompatibleSpeedTest`
+- `TestRunIperf3CompletesOneOffServerSession`
+- `TestCancelActiveTestPromotesQueuedSession`
+- `TestCancelQueuedTestRemovesItAndUpdatesPositions`
+- `TestBrowserSummaryDoesNotTreatShortBurstsAsSustainedMax`
+- `TestStoreListsLargeRecordsWithFullSampleCurves`
+
+## API 速查
+
+- `GET /`
+  - Web UI。
+
+- `GET /api/config`
+  - 返回带宽限制标签。
+
+- `GET /api/records?limit=100`
+  - 返回历史记录，输出前会脱敏 IP。
+  - `limit` 范围：1 到 1000。
+
+- `GET /api/health/events?limit=1`
+  - SSE 心跳，用于页面连接状态。
+
+- `POST /api/tests`
+  - 创建 HTTP/Web 测速会话。
+  - 返回 queue/download/upload/complete/cancel URL。
+
+- `GET /api/tests/{id}/queue`
+  - 查询排队位置。
+
+- `POST /api/tests/{id}/complete`
+  - 提交浏览器或 HTTP CLI 样本并写历史。
+
+- `POST /api/tests/{id}/cancel`
+  - 取消还未产生样本的会话或释放队列。
+
+- `GET /api/download?testId={id}&bytes={n}`
+  - 下载测速数据。
+
+- `POST /api/upload?testId={id}`
+  - 上传测速数据。
+
+- `POST /api/iperf3/sessions`
+  - 创建一次性 iperf3 服务端会话。
+
+- `POST /api/iperf3/sessions/{id}/complete`
+  - 提交 iperf3 结果并写历史。
+
+- `GET /downloads/netstable-linux-amd64.tar.gz`
+  - CLI 一键下载包。
+
+- `GET /downloads/netstable-linux-arm64.tar.gz`
+  - CLI 一键下载包。
+
+## 生产环境概览
+
+最后核对时间：2026-09-15 Asia/Shanghai。
+
+### 主入口
+
+- URL：`https://speedtest.hzct.obscura.work/`
+- HTTPS：Caddy 自动申请 Let's Encrypt 证书。
+- 证书核对结果：
+  - Subject：`CN = speedtest.hzct.obscura.work`
+  - Issuer：`Let's Encrypt`
+  - 当前证书有效期：`2026-08-09` 到 `2026-11-07`
+- HTTP 会 308 跳转 HTTPS。
+
+### 生产节点
+
+| 节点 | 用途 | 状态备注 |
+| --- | --- | --- |
+| `103.46.93.244` | 主域名节点，Caddy 80/443 反代到本机 NetStable 18080 | HTTPS/API 正常；2026-09-15 检查时 SSH 连接被远端关闭，部署前先恢复 SSH |
+| `110.42.44.35` | 直连备用节点，`http://110.42.44.35:18080/` | 2026-09-15 HTTP/API 正常，SSH 可用 |
+| `103.46.93.38` | 历史直连节点，`http://103.46.93.38:18080/` | 2026-09-15 检查时 HTTP 空响应，SSH host key 变化；不要盲目信任或部署，必须先人工确认主机身份 |
+
+### 主节点端口
+
+`103.46.93.244` 预期监听：
+
+- `:80` Caddy HTTP，自动跳转 HTTPS。
+- `:443` Caddy HTTPS。
+- `:18080` NetStable 服务。
+- `127.0.0.1:2019` Caddy admin。
+
+### 主节点 Caddy 配置
+
+路径：
+
+```bash
+/etc/caddy/Caddyfile
+```
+
+关键站点块：
+
+```caddyfile
+speedtest.hzct.obscura.work {
+	reverse_proxy 127.0.0.1:18080
+}
+```
+
+最近已知备份：
+
+```bash
+/etc/caddy/Caddyfile.bak-20260610110050
+```
+
+修改 Caddy 后必须校验：
+
+```bash
+caddy fmt --overwrite /etc/caddy/Caddyfile
+caddy validate --config /etc/caddy/Caddyfile
+systemctl reload caddy
+systemctl is-active caddy
+```
+
+验证 HTTPS：
+
+```bash
+curl -fsS -I https://speedtest.hzct.obscura.work/
+curl -fsS https://speedtest.hzct.obscura.work/api/config | jq .
+echo | openssl s_client -servername speedtest.hzct.obscura.work -connect speedtest.hzct.obscura.work:443 2>/dev/null | openssl x509 -noout -subject -issuer -dates
+```
+
+查看 Caddy 证书日志：
+
+```bash
+journalctl -u caddy --no-pager -n 100
+```
+
+### systemd 服务
+
+模板文件：
+
+```bash
+deploy/netstable.service
+```
+
+线上预期服务名：
+
+```bash
+netstable.service
+```
+
+预期服务配置：
+
+```ini
+ExecStart=/usr/local/bin/netstable -listen 0.0.0.0:18080 -data /var/lib/netstable/records.jsonl -downloads-dir /var/lib/netstable/downloads
+```
+
+常用命令：
+
+```bash
+systemctl status netstable --no-pager -l
+systemctl restart netstable
+systemctl is-active netstable
+journalctl -u netstable --no-pager -n 100
+```
+
+注意：
+
+- 当前模板没有启用 `-trust-proxy-headers`。
+- 如果要通过 Caddy 获取真实客户端 IP，必须同时满足：
+  - NetStable 只接受可信代理流量，或公网 `18080` 被防火墙挡住。
+  - 服务启动参数显式加 `-trust-proxy-headers`。
+- 不要在 `18080` 仍公网直连时直接开启 `-trust-proxy-headers`，否则用户可伪造 `X-Forwarded-For`。
+
+### 生产路径
+
+- 二进制：`/usr/local/bin/netstable`
+- 历史记录：`/var/lib/netstable/records.jsonl`
+- CLI 下载包目录：`/var/lib/netstable/downloads`
+- amd64 下载包：`/var/lib/netstable/downloads/netstable-linux-amd64.tar.gz`
+- arm64 下载包：`/var/lib/netstable/downloads/netstable-linux-arm64.tar.gz`
+
+## 发布和部署手册
+
+### 1. 发布前检查
+
+```bash
+git status --short --branch
+go test ./... -count=1
+go vet ./...
+make release VERSION=v0.1.0
+```
+
+确认生成包：
+
+```bash
+ls -lh dist
+cat dist/checksums.txt
+```
+
+### 2. 部署到可 SSH 节点
+
+优先用 SSH 标准输入流上传。不要直接 `scp` 覆盖 `/usr/local/bin/netstable`，运行中的 Linux 二进制可能导致写入失败。
+
+单节点部署模板：
+
+```bash
+host=110.42.44.35
+ssh -o BatchMode=yes -o ConnectTimeout=10 root@$host 'mkdir -p /var/lib/netstable/downloads'
+ssh -o BatchMode=yes -o ConnectTimeout=10 root@$host 'cat > /tmp/netstable.new' < dist/netstable-v0.1.0-linux-amd64/netstable
+ssh -o BatchMode=yes -o ConnectTimeout=10 root@$host 'cat > /var/lib/netstable/downloads/netstable-linux-amd64.tar.gz' < dist/netstable-v0.1.0-linux-amd64.tar.gz
+ssh -o BatchMode=yes -o ConnectTimeout=10 root@$host 'cat > /var/lib/netstable/downloads/netstable-linux-arm64.tar.gz' < dist/netstable-v0.1.0-linux-arm64.tar.gz
+ssh -o BatchMode=yes -o ConnectTimeout=10 root@$host 'install -m 0755 /tmp/netstable.new /usr/local/bin/netstable && rm -f /tmp/netstable.new && systemctl restart netstable && systemctl is-active netstable'
+```
+
+多节点部署前先确认每台 SSH 身份和服务状态，不要无脑批量推。
+
+### 3. 部署后验证
+
+本地哈希：
+
+```bash
+shasum -a 256 dist/netstable-v0.1.0-linux-amd64/netstable
+```
+
+远端哈希：
+
+```bash
+ssh root@SERVER 'sha256sum /usr/local/bin/netstable'
+```
+
+直连节点检查：
+
+```bash
+curl -fsS "http://SERVER:18080/api/config" | jq .
+curl -fsS "http://SERVER:18080/api/records?limit=1" | jq .
+curl -fsS -r 0-127 "http://SERVER:18080/downloads/netstable-linux-amd64.tar.gz" >/tmp/netstable-range.bin
+wc -c /tmp/netstable-range.bin
+```
+
+域名检查：
+
+```bash
+curl -fsS -I https://speedtest.hzct.obscura.work/
+curl -fsS https://speedtest.hzct.obscura.work/api/config | jq .
+curl -fsS "https://speedtest.hzct.obscura.work/api/records?limit=1" | jq .
+curl -fsS "https://speedtest.hzct.obscura.work/api/health/events?limit=1"
+curl -fsS -r 0-127 "https://speedtest.hzct.obscura.work/downloads/netstable-linux-amd64.tar.gz" >/tmp/netstable-https-range.bin
+wc -c /tmp/netstable-https-range.bin
+```
+
+### 4. 推送 Gitea
+
+```bash
+git status --short --branch
+git add <changed-files>
+git commit -m "<message>"
+git push origin HEAD:main
+git ls-remote origin refs/heads/main
+```
+
+如果用户只要求文档变更，也要提交并推送，除非用户明确不要。
+
+## 回滚手册
+
+### 代码回滚
+
+优先回滚到上一个已知好提交，重新构建并部署。
+
+```bash
+git log --oneline --decorate -10
+git checkout <known-good-commit>
+go test ./... -count=1
+make release VERSION=v0.1.0
+```
+
+然后按“部署到可 SSH 节点”重新上传。
+
+不要对用户工作区执行 `git reset --hard`，除非用户明确要求。
+
+### Caddy 回滚
+
+先找备份：
+
+```bash
+ls -lh /etc/caddy/Caddyfile.bak-*
+```
+
+恢复：
+
+```bash
+cp /etc/caddy/Caddyfile.bak-YYYYMMDDHHMMSS /etc/caddy/Caddyfile
+caddy validate --config /etc/caddy/Caddyfile
+systemctl reload caddy
+systemctl is-active caddy
+```
+
+### 数据回滚
+
+历史记录是 append-only JSONL。修复坏记录时优先备份再处理：
+
+```bash
+cp /var/lib/netstable/records.jsonl /var/lib/netstable/records.jsonl.bak-$(date +%Y%m%d%H%M%S)
+```
+
+不要直接清空生产记录，除非用户明确要求。
+
+## 排障手册
+
+### 记录接口 500：`failed to load records`
+
+常见原因：
+
+- JSONL 单行超过读取限制。
+- 某行 JSON 损坏。
+- 文件权限或磁盘问题。
+
+检查：
+
+```bash
+journalctl -u netstable --no-pager -n 100
+ls -lh /var/lib/netstable/records.jsonl
+tail -n 3 /var/lib/netstable/records.jsonl
+```
+
+本项目已经把单行读取上限提高到 64 MiB；不要改回默认 scanner 行为。
+
+### complete 保存失败
+
+原则：
+
+- 写记录失败时，会话必须保留，客户端可以重试。
+- 如果重试变成 404，说明 complete 路径又被改坏了。
+
+优先跑：
+
+```bash
+go test ./internal/web -run TestCompleteEndpointCanRetryWhenPersistFails -count=1 -v
+```
+
+### 用户停止后队列不释放
+
+检查：
+
+- 浏览器停止时有没有调用 partial complete 或 cancel。
+- CLI 中断时有没有调用 partial complete 或 cancel。
+- `takeSession`、`finishSession`、`promoteNextLocked` 是否被绕过。
+
+优先跑：
+
+```bash
+go test ./internal/client -run TestRunCancelsQueuedSessionWhenContextStops -count=1 -v
+go test ./internal/web -run 'TestCancelActiveTestPromotesQueuedSession|TestCancelQueuedTestRemovesItAndUpdatesPositions' -count=1 -v
+```
+
+### 峰值速度明显虚高
+
+不要直接相信单个样本的 `mbps`。检查持续吞吐统计：
+
+```bash
+go test ./internal/web -run 'TestBrowserSummaryUsesSustainedTransferRatesForMax|TestBrowserSummaryDoesNotTreatShortBurstsAsSustainedMax' -count=1 -v
+```
+
+### 域名 HTTPS 失败
+
+检查：
+
+```bash
+curl -I https://speedtest.hzct.obscura.work/
+systemctl status caddy --no-pager -l
+journalctl -u caddy --no-pager -n 100
+caddy validate --config /etc/caddy/Caddyfile
+```
+
+如果证书过期或申请失败，先看 Caddy ACME 日志。不要手动复制不明来源证书覆盖 Caddy 管理目录。
+
+### 直连 18080 正常但域名记录 IP 不准
+
+原因通常是反向代理后没有启用可信代理头，或启用了但公网 18080 仍可被用户直连伪造。
+
+正确处理顺序：
+
+1. 先决定是否只允许通过 Caddy 访问主节点。
+2. 用防火墙限制公网直接访问 18080，或让 NetStable 只监听 `127.0.0.1:18080`。
+3. 再给服务加 `-trust-proxy-headers`。
+4. 测试 IP 脱敏、ISP 和地区显示。
+
+不要只加 `-trust-proxy-headers`。
+
+### SSH host key 变化
+
+`103.46.93.38` 在 2026-09-15 检查时出现 host key changed。处理方式：
+
+1. 不要直接 `ssh-keygen -R` 后继续部署。
+2. 先通过控制台或可信渠道确认服务器是否重装、迁移或 IP 复用。
+3. 确认无误后再更新 `~/.ssh/known_hosts`。
+4. 更新后先只跑只读检查，再部署。
+
+## 安全和隐私
+
+- 不要把完整用户 IP 写到公开 API 响应。
+- 不要把 Gitea token、密码、SSH 私钥写入仓库、日志或最终回复。
+- Gitea 凭据由本机 Git credential helper 管理；不要打印明文。
+- 生产记录包含用户网络信息，下载或复制前先确认用途。
+- 对外开放的下载文件名必须限制在已知二进制包名，不能做任意文件下载。
+
+## CI 和 Release
+
+Gitea Actions 文件：
+
+```bash
+.gitea/workflows/ci.yml
+```
+
+当前行为：
+
+- push 到 `main`、`master`、`codex/**`：运行测试和 vet。
+- pull request：运行测试和 vet。
+- tag `v*` 或手动触发：构建 release tar.gz 和 checksums，并上传 artifact。
+
+如果改 Makefile、release 包内容或运行时依赖，必须同步检查 CI。
+
+## 最终交付检查清单
+
+代码或文档改动完成后：
+
+```bash
+git status --short --branch
+go test ./... -count=1
+go vet ./...
+```
+
+按改动类型补充：
+
+- 前端 JS：`node --check web/static/app.js`
+- release：`make release VERSION=v0.1.0`
+- 域名/证书：`curl -I https://speedtest.hzct.obscura.work/`
+
+然后提交并推送：
+
+```bash
+git add <changed-files>
+git commit -m "<message>"
+git push origin HEAD:main
+```
+
+最终回复必须说明：
+
+- 改了什么。
+- 跑了哪些验证。
+- 是否已提交和推送 Gitea。
+- 如涉及生产，列出线上验证结果或明确说明未部署。