# AGENTS.md —— 工作区 AI 协作契约（模板）
> **用法**：把这份文件放到**项目根目录**，按实际内容替换 `<>` 占位符。
> 它的作用是：**下一个 AI（或人）打开这个工作区时，不需要重新问一遍边界。**
>
> 三个已跑通的成品服务端都在仓库根放了等价文件 —— 这是它们「交接成本低」的关键原因。
> 建议在项目第 0 天就建立，并随项目演进更新。
---
## 项目范围
<一句话说清这是什么。>
- **工作区根目录**：包含 ``、``、``、`` 的目录
- **目标**：<例：客户端 ↔ 自建服务端 互操作性研究与本地部署>
- **目标客户端**：`<包名 / 版本>`
- **本仓库包含**：<服务端源码、工具、文档>
- **本仓库不包含**：<原始安装包、游戏资源、账号数据、密钥 —— 由使用者自备>
---
## 重要边界与合规
- **不提交专有二进制**：原始安装包、美术/音频资源、`build/`、`dist/` 一律 ignore。
- **工具只操作用户提供的原始包**：输出到独立的 `dist/`，不覆盖输入。
- **热更/CDN 隔离**：`` 视为**上游**，热更流量与本地业务服务**分开**，不指向局域网。
- **脱敏**：不要硬编码真实用户名、本机绝对路径、私网 IP（用 `127.0.0.1` / `192.168.1.100`）、
真实凭据或 token。抓包与日志进入文档前先脱敏。
- **非破坏性版本控制**：不要在公共分支上执行 `git reset --hard` 之类破坏性命令。
---
## 目录分区（读 / 写分离）
### 输入与分析目录（**只读**）
```
/ 反编译产物 / 解包结果（分析输入，ignore）
/ SDK dump / 元数据 dump（分析输入，ignore）
/ 运行时缓存、设备抓取的数据（分析输入，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：`<协议/端口>`
- 默认测试账号：``
> 注意: 环境权限失败（如回环端口不可用）**不能记作通过** —— 换环境重跑同一条命令。
---
## 证据档位（每个结论都要挂）
- **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 规则 / 地址文件>
最近一次验证：<日期 + 结论>
已知未完成： <条目>
```