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

Agent Guide — 星骸协议

本文件是进入仓库的首要上下文。开始修改前，依次阅读：

1. 本文件；
2. docs/DESIGN.md——产品方向、世界观、机制约束和路线图；
3. 实现星图师前阅读 docs/characters/ASTROGATOR.md 与 docs/reviews/ASTROGATOR_V1_REVIEW.md；
4. docs/DEBUGGING.md——构建、部署、日志、断点与测试；
5. 涉及模板或注册 API 时再阅读 README.md 和对应 RitsuLib 教程。

项目使命

本项目将开发《杀戮尖塔 2》的原创科幻角色系列，工作名为 《星骸协议》 / Astral Protocol。首发角色是“星图师”，核心机制为三槽位的“轨道牌堆”。角色不能只是换皮卡池：最终内容应覆盖卡牌、遗物、药水、事件、时间线和联机兼容。

当前状态（2026-08-01）

• 项目、程序集、manifest、namespace 与资源根目录已统一使用稳定 ID AstralProtocol。
• 当前纵向切片包含：打击、防御、发射探针、航线修正、破损星盘、可见的三槽轨道牌堆，以及第一批 8 张普通奖励牌。稀有牌“凯斯勒瀑布”也已提前实现，用于验证批量脱轨与群体伤害。
• 编译目标为本机正式分支 STS2 0.110.1，RitsuLib 编译与 manifest 下限为 0.5.2。2026-08-01 最新实机日志实际加载 Workshop RitsuLib 0.5.3（兼容分支 0.110.0）并成功进入主菜单；不要把该次向上兼容验证误写成已升级编译依赖。
• 2026-08-01 已完成 AstralProtocol 改名和轨道纵向切片，Debug 纯 C# 编译与完整 PCK 导出均为 0 warning / 0 error。旧 mods/STS2Mod 已移入 artifacts/legacy-deploy/STS2Mod-20260801；最新实机日志确认角色进入战斗，并完成发射探针的入轨、航线修正校准与周期归零结算。环绕布局、多卡交互和联机仍需专项验证。
• local.props 是本机配置并被 Git 忽略；不要提交或擅自改写其中的路径。
• 已提供 .vscode 构建任务和附加调试配置；Debug 构建会把 PDB 一并部署。
• 星图师 v1 规格已定稿于 docs/characters/ASTROGATOR.md。当前角色锚点已更新为更干净、偏二次元的精致手绘动画风；战斗母版是 docs/art/astrogator-combat-pose-v3-master.png，头像母版是 docs/art/astrogator-icon-v3-master.png。早期写实与破损版本只保留作身份演进参考。
• 卡牌主色已改为高饱和星轨钴蓝 #2D63E8，电光青 #26E1FF 用于高亮，深海军蓝仅作阴影/描边。不要退回灰白、米色或低饱和的“无色牌”观感。
• 轨道 UI 使用三条可见椭圆轨道；入轨牌会持续公转，并按纵深动态改变位置、缩放、旋转和层级。它仍是 2D 伪三维，但已不再是三个静态停靠点；需在游戏内验证悬停与不同分辨率。
• 2026-08-01 已实现第一批奖励牌核心代码和中英文本；打击、防御、两张机制初始牌、8 张普通奖励牌和凯斯勒瀑布均有独立卡面，提示词与映射见 docs/art/ASTROGATOR_V3_ASSET_PROMPTS.md。逻辑和资源仅通过构建验证，尚未逐张完成游戏内冒烟测试。
• 星图师的“入轨、轨道、周期、校准、脱轨”已接入 RitsuLib 自定义关键词；最新实机日志确认五个关键词和全部 13 张卡牌均注册成功，且 canonical model 初始化不再崩溃。原生 hover tip、金色高亮排版与双语切换仍待视觉验收。
• 星图师 D1–D4 已于 2026-08-01 全部获批，可以按 Review 中的顺序推进技术原型。

技术边界

• 当前只依赖 RitsuLib。不要因为用户机器上存在 BaseLib Mod，就给本项目新增 BaseLib 运行时依赖。
• 保留 Entry.Initialize() 中的 EnsureGodotScriptsRegistered 与 RegisterModAssembly；二者用途不同。
• Entry.ModId、manifest id、项目/程序集名、输出目录和 res://<ModId>/... 是一组跨文件约束。正式改名必须一次完成并验证旧输出目录不会被误加载。
• 新内容优先使用 RitsuLib 自动注册 attribute，不在入口中维护手工类型清单。
• 卡牌的固有自定义关键词必须通过 CardModel.CanonicalKeywords 声明；不要在卡牌构造函数中调用 AddKeyword、AddModKeyword 或其他可变实例 API，否则 ModelDb 创建 canonical model 时会导致启动崩溃。
• 所有玩家可见文本进入 AstralProtocol/localization/eng 与 zhs；逻辑代码中不要硬编码展示文案。
• 轨道状态必须按玩家隔离、可保存、确定性排序并支持联机同步；不要依赖客户端本地随机数或仅 UI 节点持有权威状态。
• 游戏和 RitsuLib 都在快速迭代。不要顺手升级依赖或 min_game_version；升级必须是明确任务，并记录兼容性测试。
• 不修改 bin/、obj/、.godot/、artifacts/ 中的生成文件。不要提交游戏 DLL、游戏 PCK、日志、存档或 local.props。

推荐工作顺序

1. 先做纯 C# 编译检查。
2. 逻辑改动用 Debug 构建部署 DLL/PDB；资源或本地化改动执行完整 PCK 导出。
3. 从游戏日志确认 manifest、RitsuLib 和本 Mod 均成功加载。
4. 用控制台直接生成待测卡牌/遗物或跳转战斗，不靠完整跑图验证单一效果。
5. 新机制至少覆盖：普通打出、升级、抽弃循环、保留/消耗/Replay、存读档、A0、A10、双人联机。
6. 行为或设计发生变化时，同步更新对应文档；交接时记录实际验证过的命令与尚未解决的问题。

当前优先级

1. 在游戏内验证星图师纵向切片和第一批奖励牌：三槽 UI、发射/推进/校准、槽满脱轨、破损星盘、Replay 与凯斯勒瀑布的逐张脱轨。
2. 优先验证碎片齐射的延迟 AOE、舷窗观测的弃牌后校准、测距脉冲升级周期，以及凯斯勒瀑布在 0–3 张轨道牌时的结算。
3. 先验证轨道生命周期和联机；当前游戏普通跑局存档不恢复战斗中状态，不要把战斗存档误报为已支持。稳定后再扩充其余罕见/稀有牌。
4. 星图师达到可完整通关的稳定状态后，才启动塑界师或中继体。

完成定义

一次改动只有在以下条件满足后才算完成：

• dotnet build .\AstralProtocol.csproj -c Debug /p:RunPckExport=false /p:CopyModOnBuild=false 通过；
• 涉及资源时，完整构建与 PCK 导出通过；
• 没有引入与本任务无关的格式化或生成文件；
• 文档、manifest、本地化和代码中的相关 ID 保持一致；
• 交接说明明确区分“已在游戏内验证”和“仅编译验证”。