AGENTS.md@game-client-to-server-reverse/templates git:20260922.433a736A

Immutable. This exact content is served forever at /api/v1/blob/d9ed05b46e35353b.

# AGENTS.md —— 工作区 AI 协作契约（模板）

> **用法**：把这份文件放到**项目根目录**，按实际内容替换 `<>` 占位符。
> 它的作用是：**下一个 AI（或人）打开这个工作区时，不需要重新问一遍边界。**
>
> 三个已跑通的成品服务端都在仓库根放了等价文件 —— 这是它们「交接成本低」的关键原因。
> 建议在项目第 0 天就建立，并随项目演进更新。

---

## 项目范围

<一句话说清这是什么。>

- **工作区根目录**：包含 `<server/>`、`<tools/>`、`<docs/>`、`<tests/>` 的目录
- **目标**：<例：客户端 ↔ 自建服务端 互操作性研究与本地部署>
- **目标客户端**：`<包名 / 版本>`
- **本仓库包含**：<服务端源码、工具、文档>
- **本仓库不包含**：<原始安装包、游戏资源、账号数据、密钥 —— 由使用者自备>

---

## 重要边界与合规

- **不提交专有二进制**：原始安装包、美术/音频资源、`build/`、`dist/` 一律 ignore。
- **工具只操作用户提供的原始包**：输出到独立的 `dist/`，不覆盖输入。
- **热更/CDN 隔离**：`<CDN 域名>` 视为**上游**，热更流量与本地业务服务**分开**，不指向局域网。
- **脱敏**：不要硬编码真实用户名、本机绝对路径、私网 IP（用 `127.0.0.1` / `192.168.1.100`）、
  真实凭据或 token。抓包与日志进入文档前先脱敏。
- **非破坏性版本控制**：不要在公共分支上执行 `git reset --hard` 之类破坏性命令。

---

##  目录分区（读 / 写分离）

### 输入与分析目录（**只读**）

```
<input_dir>/        反编译产物 / 解包结果（分析输入，ignore）
<dump_dir>/         SDK dump / 元数据 dump（分析输入，ignore）
<runtime_dir>/      运行时缓存、设备抓取的数据（分析输入，ignore）
```

> **不要修改输入目录里的任何东西**。所有改动发生在输出目录或副本上。

### 产出目录

```
src/ 或 server/     服务端源码
tools/              辅助脚本与工具
docs/               结构化文档（见下方文档规范）
tests/              自动化测试
build/              构建中间产物（ignore）
dist/               最终导出的签名包与摘要（ignore）
data/               数据库、抓包、日志（ignore）
```

---

## 一键入口

```
<入口脚本 1>   启动
<入口脚本 2>   停止
<入口脚本 3>   打包/打补丁
<入口脚本 4>   管理 CLI
```

---

## 代码与编辑规范

- JSON / SQLite / protobuf wire / 包元数据 尽量用**结构化解析器**，不要正则硬切。
- 全仓库使用**相对路径**（代码、脚本、文档链接）。
- 代码标识符与文件路径用 ASCII；文档可写中文。
- **改动协议或状态模型时，必须同步更新 `tests/`**。

---

## 验证命令

```bash
# 从工作区根目录执行
<测试命令>
<编译检查命令>
<端到端冒烟客户端命令>
```

- 服务 A：`<协议/端口>`
- 服务 B：`<协议/端口>`
- 默认测试账号：`<user / password>`

> 注意: 环境权限失败（如回环端口不可用）**不能记作通过** —— 换环境重跑同一条命令。

---

## 证据档位（每个结论都要挂）

- **Confirmed by static analysis** —— 反编译代码 / 协议定义 / 服务端代码直接确认
- **Confirmed by packet capture or runtime observation** —— pcap、重组帧、logcat、运行时数据库确认
- **Inferred and still requiring validation** —— 由前两者推断，仍需实机验证

> 不确定的写 `Inferred`，**不要写「已实现」**。

---

## 文档规范

```
docs/analysis/      逆向与协议分析
docs/implementation/ 服务端实现说明
docs/decisions/     架构决策记录（ADR）
docs/evidence/      实机验收证据
docs/status/        支持矩阵 / 已知问题 / 验收进度
docs/todo/          兼容性清单与验收标准
```

写作纪律：

- **已修复的问题交给版本控制**，不要继续堆在「已知问题」里；
- 「已实现但未验收」必须单列，不能混进「已通过」；
- 每个模块文档末尾都要有「**本模块不包含**」。

---

## AI 工作时必须遵守的 8 条

1. **先规格后代码**：没有 `protocol.spec` / 项目档案 / 证据清单，不要写业务代码。
2. **不确定就标注**，不要猜字段、不要猜枚举语义；不支持的输入 **fail closed**。
3. **改动只在副本上做**，保留原始文件哈希与回滚命令。
4. **声明"通过"必须有产物**（日志、截图、trace、测试输出），不接受口头结论。
5. **一轮只改一个变量**，否则无法归因。
6. **改了配置要重启**（启动期冻结，运行中修改不生效）。
7. **不要为客户端不可能产生的状态**编假想业务流程 —— 标为 `server-boundary` 或待抓包。
8. **离开前更新**：`TRACKER`/支持矩阵、`docs/status/known-issues`、以及本文末尾的「当前环境状态」。

---

## 当前环境状态（每次收工前更新）

```
本地服务端： <未运行 / 运行中 + 端口>
客户端：     <未安装 / 已安装 + 包名 + 是否改包>
已生效的重定向：<无 / uid=N 的 DNAT 规则 / 地址文件>
最近一次验证：<日期 + 结论>
已知未完成：  <条目>
```