From ed284833feeae2c162e4018ab545415395736d90 Mon Sep 17 00:00:00 2001
From: FanstyNight <qhanyu666@gmail.com>
Date: Wed, 3 Jun 2026 17:34:09 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0harness?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d64e2a9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,103 @@
+# AGENTS.md
+
+本文件是本仓库给 AI 编码代理使用的项目 harness。开始修改前先读本文件和 `README.md`。
+
+## 项目概况
+
+- 项目名：`ManaPetWorld`
+- 类型：C++20 2D 冒险 / 宠物战斗游戏原型
+- 主要依赖：CMake、raylib、pugixml、pkg-config/pkgconf
+- 主程序：`src/app/main.cpp`
+- 可执行文件：`build/mana_pet_world`
+- 资源根目录：`assets/`
+- 存档文件：`savegame.txt`，位于仓库根目录，除非用户明确要求，不要修改或删除。
+
+## 目录职责
+
+- `src/app/`：主循环、运行时状态、输入、渲染入口。
+- `src/core/`：宠物、元素、成长、核心数据模型。
+- `src/battle/`：战斗界面、战斗资源、战斗布局。
+- `src/world/`：TMX 地图加载、世界连接、传送、野外生成、地图审计。
+- `src/dialogue/`：对话脚本、脚本化交互和对话效果。
+- `src/quest/`：任务定义和任务进度。
+- `src/save/`：存档读写。
+- `src/assets/`：资源路径、图标、动画、音乐和音效索引。
+- `src/ui/`：背包等 UI 模型和交互视觉辅助。
+- `src/content/`：内置道具等内容表。
+- `assets/maps/`：Tiled TMX 地图与 world 文件。
+- `assets/presets/`：实体、任务、物品、调色板等预设。
+- `assets/scripts/`：地图 / NPC 交互脚本。
+- `assets/minimap/`：小地图资源。
+
+## 构建和运行
+
+优先使用仓库自带脚本：
+
+```bash
+./run.sh
+```
+
+手动构建：
+
+```bash
+cmake -S . -B build
+cmake --build build --target mana_pet_world
+./build/mana_pet_world .
+```
+
+修改 C++ 后至少运行：
+
+```bash
+cmake --build build --target mana_pet_world
+```
+
+修改地图、传送、小地图、任务目标或相关资源后运行：
+
+```bash
+./build/mana_pet_world --audit-world .
+```
+
+也可以通过脚本转发：
+
+```bash
+./run.sh --audit-world
+```
+
+## 开发规则
+
+- 优先保持现有架构：通用游戏逻辑放进 `mana_core`，raylib 窗口和强渲染耦合逻辑放在可执行目标相关代码中。
+- 新增 `.cpp` 文件时同步更新 `CMakeLists.txt`，否则不会参与构建。
+- 头文件放在对应模块目录，沿用现有 include 风格。
+- 保持 C++20，避免引入新第三方库，除非用户明确要求并说明构建影响。
+- 代码应能通过现有编译选项：`-Wall -Wextra -Wpedantic`。
+- 不要把生成的 `build/`、本地存档、临时文件或 IDE 产物加入版本控制。
+- 不要大规模重排资源目录或重命名资产文件。很多路径由 TMX、预设、脚本或代码字符串引用。
+- 修改二进制图片、字体、音乐、音效前必须确认这是用户要求的一部分。
+- 修改 `.tmx`、`.tsx`、`.tres`、`.gd` 时，尽量保持原文件格式和命名约定，不做无关格式化。
+
+## 内容修改注意事项
+
+- 地图入口、传送对象、任务目标和小地图覆盖互相关联，改动后必须跑 `--audit-world`。
+- 资源路径通常相对项目根目录解析，运行程序时传入 `.` 或项目绝对路径。
+- 新增图标、精灵、音乐、音效后，检查对应的 catalog 或 asset 索引文件是否需要更新。
+- 新增实体或任务时，检查 `assets/presets/`、`assets/scripts/`、地图对象引用和 C++ 内容加载逻辑是否一致。
+
+## 验证要求
+
+根据改动范围选择验证命令：
+
+- 只改文档：无需构建，检查 Markdown 内容即可。
+- 改 C++：运行 `cmake --build build --target mana_pet_world`。
+- 首次构建或 `build/` 不存在：先运行 `cmake -S . -B build`。
+- 改世界内容：运行 `./build/mana_pet_world --audit-world .`。
+- 改启动流程：运行 `./run.sh --audit-world` 或说明为什么不能运行图形程序。
+
+如果验证命令因缺少系统依赖失败，报告缺少的依赖和失败命令，不要伪造通过结果。
+
+## 代理行为约束
+
+- 修改前先用 `rg`、`rg --files` 或相关源码阅读确认现有模式。
+- 保持改动小而集中，不做无关重构。
+- 不回滚用户已有改动。
+- 不执行破坏性命令，除非用户明确要求。
+- 最终回复必须说明改了哪些文件、是否运行验证、验证结果或未运行原因。