black-souls-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

black-souls-mcp 是一个本地 stdio MCP 服务器，让 AI 代理通过 36 个 black_souls_* 工具与运行中的 BLACK SOULS（RPG Maker VX Ace / RGSS3）游戏交互。服务器与游戏之间的通信完全基于文件系统（无网络、无 socket）。AGENTS.md 是面向所有代理的仓库准则；本文件补充 Claude Code 视角的操作细节，两者冲突时以 AGENTS.md 为准。

常用命令

本项目只在 Windows 上开发运行。在 bash 中请使用 npm.cmd 而非 npm。

npm.cmd run check             # 提交前标准命令：清理 + 构建 + smoke + unit
npm.cmd run build             # 清理 dist/ 后编译 TypeScript
npm.cmd run typecheck         # 仅类型检查
npm.cmd test                  # 只跑 smoke + unit（依赖已有 dist/，改源码先 build）
npm.cmd run test:integration  # 需要已准备好的 runtime/game
npm.cmd run test:live         # 会真的启动游戏并发送键盘输入
node scripts/call_tool.mjs black_souls_status '{}'   # 手动调用单个工具（调试用）
node evals/runner.mjs menu_navigation                # 跑一个评测场景（需真实游戏）
.\check.ps1 -IncludeRuntime   # 源码 + 游戏副本 + Codex 注册整体校验

CI（.github/workflows/ci.yml）在 windows-latest + Node 18/22 上运行 npm run check、npm audit --audit-level=high 和 npm pack --dry-run。

Python 维护脚本（仅在写入游戏数据时使用）

# 从 RGSSAD v3 归档提取单个文件（纯标准库，支持 SHA-256 门禁）
python scripts/extract_rgss3a_file.py Game.rgss3a "Data/Scripts.rvdata2" out.rvdata2

# 把 rgss/BlackSoulsBridge.rb 注入 Scripts.rvdata2（纯标准库、字节保持，优先使用）
python scripts/patch_rvdata2_binary.py Scripts.rvdata2 rgss/BlackSoulsBridge.rb --title Main --backup backup.rvdata2

注入语义是整体替换标题为 Main 的脚本条目；BlackSoulsBridge.rb 末尾自带 rgss_main { SceneManager.run }，它就是新的 Main，绝不能删除这一行。重复注入是幂等安全的。备选 patch_rvdata2.py 需要 pip install -r requirements-tools.txt（rubymarshal）。

架构

源码结构（src/）

文件	职责
index.ts	MCP 入口；注册全部 36 个工具；execute()/result() 统一响应封装
bridge.ts	文件 IPC 全部逻辑：快照读取、sendSequence、sendQuery、save/load/situation/health/wait
game.ts	启动（含 Game.exe SHA-256 门禁）、强制结束、存档列表、完整性信息
config.ts	路径解析（环境变量覆盖）
memory.ts	AI 持久记忆：scratchpad / longterm / goals / session log（<ROOT>/memory/，原子写）
navigation.ts	BFS 寻路 findPath（导出可单测）、navigate、interact
battle.ts	battleAction 一次完成战斗回合