本仓库是《空洞骑士：丝之歌》"纹章强化"大型 BepInEx Mod（基于 Needleforge）的实现仓库。项目当前处于开发中期（约 50%）：7 个纹章被动与丝母、全部 36 个蓝/黄工具等级与白槽功能、亡怒/超级亡怒、标记血、HUD 状态图标与快捷换纹章等核心玩法已接线并通过本地校验（当前版本 0.58.9，dotnet test 704 通过 / 0 失败，契约校验 PASSED），但仍有大量功能待本机游戏内验证、存在 U 级探针与未决问题，剩余纹章垂直切片尚未完成。
"完成约 50%"的含义：功能以"被动提供功能、纹章做门控"的架构大规模接线完成，但已接线 ≠ 已游戏内验收。哪些功能已本机验证、哪些仅探针确认、哪些仍有未决问题，一律以 docs/01_开发计划.md 与 docs/03_功能整合.md 为准，本文件不做状态跟踪。
docs/01_开发计划.md：唯一任务状态载体，含当前进度、已完成/未决事项与分阶段路线。docs/02_代码参考.md：游戏代码、BepInEx/Harmony API、前置 Mod、参考项目和许可证边界。docs/03_功能整合.md：唯一功能需求源，每个 Feature ID 的实现状态与未决问题。改需求先改这里。docs/04_实操辅助.md：本机需要完成的反编译、FSM/贴图检查、运行测试与资料投喂方法。docs/05_高难代码示例.md：状态机、伤害管线、丝线护盾、虚拟工具、输入组合键、动态补丁等示例。
本仓库新增 skills/crests-evolve/SKILL.md。本地 Agent 在修改任何代码前必须读取该 Skill 和其中的游戏 Key 注册表、冲刺换纹章安全协议与探针流程。根目录 AGENTS.md 提供自动发现入口。
静态契约检查：
python skills/crests-evolve/scripts/validate_contract.py .- 规则与游戏绑定分离：
Core只处理数值和状态，GameInterop才接触游戏类、FSM、Unity 对象与前置 Mod；反射集中封装在GameInterop，不在纹章模块散落。 - 单一所有者：换纹章、伤害、治疗、资源和无敌各自只有一个所有者（如
RageFeature是亡怒唯一所有者）；事件驱动而非到处打补丁——Harmony 补丁只采集事件或提交最终修改，被动效果订阅统一事件。 - 单一伤害/治疗/资源管线：暴击、燃爆、毒火、吸血、溢出血、丝线护盾统一排序，避免乘区和重复触发失控。
- 版本可诊断：游戏方法名、FSM 名、状态名、变量名放在
config/game-bindings.json；补丁失败时输出探针报告，而不是静默失效。未经验证的绑定与功能必须标记（U 级探针/待游戏内验证），不得声称"已完成"。 - 可回滚：每个纹章、每类护符增强、每种高风险补丁都能独立开关（
config/功能开关与配置节）。
.
├─ docs/ 五个核心交付文件（状态/参考/整合/实操/示例）
├─ spec/ 原文段落与功能目录
├─ config/ 游戏绑定、平衡参数、功能开关
├─ skills/crests-evolve/ Agent Skill、游戏 Key 注册表与契约校验脚本
├─ src/CrestsEvolve/
│ ├─ Bootstrap/ 插件启动与装配
│ ├─ Core/ 纯逻辑：状态机、事件、伤害管线、资源账本、平衡参数、时间/输入/缓冲
│ ├─ Features/
│ │ ├─ Passives/ 纹章被动（猎手/漫步者/收割者/野兽/女巫/建筑师/萨满 + 丝母）与门控
│ │ ├─ Tools/ 36 个蓝/黄工具定义与等级效果（Blue/ Yellow/）、白槽效果、白工具
│ │ ├─ Rage/ 亡怒状态机与各纹章行为（IRageBehavior）
│ │ ├─ Health/ 标记血（野兽红/女巫绿）
│ │ ├─ StatusIcons/ HUD 状态图标账本、计时器与宿主
│ │ └─ CrestSwitching/ 快捷换纹章入口
│ ├─ GameInterop/ BepInEx/Harmony/FSM/Unity 适配
│ │ ├─ Patches/ 55 个 Harmony 补丁文件
│ │ ├─ Binding/ 动态绑定解析与绑定报告
│ │ ├─ Input/ 原生输入适配
│ │ ├─ Reflection/ 反射封装
│ │ └─ CrestSwitching/ 换纹章互操作（冲刺安全策略等）
│ ├─ Patches/ 薄补丁层
│ └─ UI/ UI 投影接口与 HUD 宿主
├─ tests/ 纯逻辑测试（xUnit，704 通过）
└─ tools/ 构建部署脚本、规格校验与探针辅助
状态口径：以下均"已接线并通过本地构建/测试/契约校验"，但游戏内行为是否生效以本机验证为准，逐项证据见
docs/01与docs/03。
- 纹章被动与门控：猎手、漫步者、收割者、野兽、女巫、建筑师、萨满 7 个纹章被动 + 丝母全部实现，统一由
PassiveGate/PassiveCrestIds做"纹章 → 被动"门控（功能由被动提供、纹章只做门控），驱动内不硬编码纹章 ID。 - 工具系统：全部 36 个蓝/黄工具（蓝 23 + 黄 13）按文件登记等级 1/2/3 效果与白槽特殊功能（
ToolEffectSpec/BlueToolEffectPatches/WhiteToolSystem）；白槽、白色工具（艾欧尼亚/亡者之怒/虚空之心/蜂巢之血/国王之魂/编织者之歌）与工具专属功能：储备缚丝、碎面甲、记忆晶石（受伤补足冰像）、速射索白槽修饰、丝轴延展器、德鲁伊之眼、磁石骰、棘刺手环、爪镜、伏特丝、撬赃钩等。 - 亡怒系统：普通亡怒 + 超级亡怒（亡怒plus）覆盖全部纹章（
RageFeature/RageStateMachine/IRageBehavior/RageToolBridge），亡者之怒门控，上+治疗进入，超级亡怒血量上限投影为 1 格。 - 标记血系统：野兽红血、女巫绿血（
MarkedHealthService/BlueHealthTintBridge/MarkedHealthGamePatches，上限 8/8/99，阻断原版等离子化），碎面甲、溢出转蓝血、坐椅/死亡/换纹章生命周期。 - HUD 状态图标系统：
StatusIconLedger/StatusIconFeature/HudStatusIconHost克隆原生ToolHudIcon并自动排布，支持计时/充能/倒计时/实时上限图标，门控到原生TOOLS APPEAR后显示。 - 快捷换纹章：
CrestSwitchService等组件（原生输入适配、冲刺安全策略、纹章名称提供、状态缓存），配合白槽通用槽位同步与蓝/黄/白工具互串。 - 事件与生命周期：
GameEventHub（CrestChanged/ToolEquipsChanged/EnemyDamageResolved 等），统一ResetReason生命周期分发（换纹章/坐椅/死亡/切场景），IGameApi/ReflectionGameApi提供游戏动作入口。 - 工程化：
dotnet test704 通过 / 0 失败；契约校验 PASSED（4 个既有警告）；tools/build.ps1构建并部署到BepInEx\plugins\CrestsEvolve。
- 批量游戏内验收：大量功能待本机进游戏验证（入口：
tools/build.ps1 -RunGame），逐批验收清单见docs/01。 - U 级探针与待证据项：部分对象名/FSM 路径以近似方式接入或标注
U，需反编译/运行时探针确认后才算闭环（如记忆晶石地址 key、部分白槽效果、RageInputSource原生输入等）。 - 未决问题统一：如储备缚丝双写路径、克隆白框技能图标复刻等，见
docs/03未决问题清单与artifacts/plans/。 - 剩余纹章垂直切片与后续阶段：诅咒纹章、无用之人、丝母 12 阶段等，以及 Phase 5 之后共享系统扩展、UI/资源/本地化、发布工程化，见
docs/01分阶段路线。
按 Skill 约定：代码修改完成并通过本地校验后自动运行 tools/build.ps1 完成构建与部署；不再默认"只构建不部署"。本机游戏路径已写在 Directory.Build.props（SilksongPath），Visual Studio 打开 src/CrestsEvolve/CrestsEvolve.csproj 会自动引用游戏 Hollow Knight Silksong_Data\Managed\Assembly-CSharp.dll，无需手动加引用。
# 构建 + 部署 DLL/config 到游戏 BepInEx\plugins\CrestsEvolve
powershell -ExecutionPolicy Bypass -File tools\build.ps1
# 只构建不部署
powershell -ExecutionPolicy Bypass -File tools\build.ps1 -SkipCopy
# 构建 + 部署 + 启动游戏 + 实时跟踪日志（用户明确要启动游戏时使用）
powershell -ExecutionPolicy Bypass -File tools\build.ps1 -RunGame脚本会 dotnet build（引用 Hollow Knight Silksong_Data\Managed\Assembly-CSharp.dll），并把 DLL 与 config/*.json 复制到 BepInEx\plugins\CrestsEvolve\；找不到游戏目录时脚本报错。-RunGame 会先把旧 LogOutput.log 改名备份，再启动游戏并跟踪新日志（Ctrl+C 退出）。
- 批量游戏内验收：用
tools/build.ps1 -RunGame进游戏按批次验收最近接线的功能（门控/亡怒/白槽/工具等级/HUD 图标），逐项核对日志证据。 - 统一未决问题：先处理
docs/03未决问题（如储备缚丝双写路径统一）与已落盘的删除清单（artifacts/plans/删除清单-2026-08-11.md），再继续新功能。 - 继续剩余纹章垂直切片：以单纹章为单位按
docs/01分阶段路线推进，每个 Feature ID 完成 Definition of Done（状态更新、测试、日志证据、重置策略）后才算完成。 - 每次改动遵循交接规则：更新
docs/01当前状态、docs/03对应 Feature ID 与未决问题、CHANGELOG.md。