Acelogic/sharpemu-agentic-toolkit

# SharpEmu Agentic 工具包

一个用于有据可查的 SharpEmu 工作的可复现工具包：NID 研究与 实现验证关卡，KawaiiDRA 辅助的逆向工程，Context Mode 输出处理，以及将自动化模拟器截图组合成带时间戳的 缩略图，用于模型反馈。 ## 重要的法律与数据边界 **本仓库不包含任何 PS5 固件、游戏数据、密钥、解密的可执行文件或专有的 反编译产物。你必须从自己拥有的硬件/内容中自行提取，并在合法的情况下解密每一个 PS5 固件或游戏二进制文件。** 请勿要求贡献者提供受版权保护的提取内容、密钥或解密的系统文件。 不同司法辖区的法律有所不同；本仓库不提供法律建议。 请将这些本地输入文件保留在 Git 之外。参见 [`docs/legal-and-data-boundaries.md`](docs/legal-and-data-boundaries.md)。 ## 包含内容 | 路径 | 用途 | |---|---| | `skills/sharpemu-nid-swarm/` | 完整的 Codex skill，参考文档，agent 合约，以及 NID 清单工具 | | `sharpemu-overlay/scripts/game-test.py` | 与具体游戏无关的构建/启动/日志/截图/缩略图测试工具 | | `sharpemu-overlay/tests/test_game_test.py` | 针对截图、任意里程碑、时间线诊断和视觉序列的测试工具 | | `scripts/install_toolkit.py` | 用于安全安装 skill 和 SharpEmu overlay 的安装器 | | `integrations/kawaiidra-mcp/` | 固定版本的 KawaiiDRA MCP 子模块，包含其 Python 源码 | | `integrations/context-mode/` | 固定版本的 Context Mode 子模块 | | `docs/` | 设置、操作工作流、输出合约和法律边界说明 | 固定版本的集成包括 [`wagonbomb/kawaiidra-mcp`](https://github.com/wagonbomb/kawaiidra-mcp) 和 [`mksglu/context-mode`](https://github.com/mksglu/context-mode)。它们保留了 各自上游的历史记录和许可证。 ## 克隆 ``` git clone --recurse-submodules https://github.com/Acelogic/sharpemu-agentic-toolkit.git cd sharpemu-agentic-toolkit ``` 对于已存在的克隆： ``` git submodule update --init --recursive ``` ## 安装 skill 和测试工具 首先运行试运行。除非 提供了 `--force` 参数，否则安装器会拒绝替换不同的文件。 ``` python3 scripts/install_toolkit.py \ --sharpemu /path/to/sharpemu \ --dry-run python3 scripts/install_toolkit.py \ --sharpemu /path/to/sharpemu ``` Skill 将安装在 `${CODEX_HOME:-$HOME/.codex}/skills/sharpemu-nid-swarm` 下。overlay 会将 通用游戏测试工具、测试和指南安装到选定的 SharpEmu 检出目录中。 ## 生成带时间戳的模型证据 在 SharpEmu 的检出目录中，将测试工具指向你自己本地的游戏提取文件： ``` python3 scripts/game-test.py doctor \ --game /path/to/your/own/dump/eboot.bin python3 scripts/game-test.py test \ --game /path/to/your/own/dump/eboot.bin \ --game-label my-game \ --tag visual-baseline \ --milestone BOOT="GAME: boot complete" \ --milestone MENU="GAME: Level has started: main_menu" \ --timeout 180 \ --screenshot-interval 5 \ --screenshot-milestone-interval 0.5 \ --screenshot-milestone-tail 2 \ --screenshot-grid-columns 4 ``` `--game` 没有内置的默认值，里程碑标签/模式属于 特定游戏或测试用例。为语义帧重复使用 `--milestone LABEL=LOG_SUBSTRING`， 或者当生成的标签足够时使用 `--expect LOG_SUBSTRING`。没有任何单独的 游戏标题、关卡名称、发行商序列或游戏特定的环境标志被 硬编码。 每次运行都会写入一个被忽略的 `artifacts/game-runs//-/` 目录，其中包含： - `run.json`，包含构建、配置、尝试和结果； - `attempt-XX.log`，包含运行时证据； - `attempt-XX-timeline.json`，包含确切的流逝时间和截图诊断信息； - 原始帧 PNG 图片； - `attempt-XX-contact-sheet.png`，一个组合的带时间戳的网格图； - `attempt-XX-milestones.png`，一个用于模型审查的紧凑语义序列。 将里程碑/缩略图图片以及 `run.json` 和相关的日志 摘录附加给模型。图片的时间戳使得视觉回归能够与 运行时里程碑对齐，而不是依赖于没有日期的最终截图。 参见 [`docs/visual-feedback-harness.md`](docs/visual-feedback-harness.md) 了解 平台要求和即用型反馈提示词。 ## Agentic 工作流 1. 将未解析的导入和运行时检查点捕获到一个清单中。 2. 使用 SharpEmu 目录和 `name2nid()` 验证来解析名称。 3. 使用 KawaiiDRA 建立签名、调用者、输出、状态和错误行为。 4. 将大型 Ghidra/日志输出保留在文件中，并通过 Context Mode 进行查询。 5. 在实现 NID 之前通过 skill 的合约关卡。 6. 构建并测试隔离的子系统更改。 7. 运行带有截图工具的集成构建，并比较带时间戳的证据。 在进行完整运行之前，请阅读 [`docs/nid-swarm.md`](docs/nid-swarm.md)， [`docs/kawaiidra.md`](docs/kawaiidra.md) 和 [`docs/context-mode.md`](docs/context-mode.md)。 对于无人值守或委托设置，请向负责安装的 agent 提供 [`INSTALL-AGENTS.md`](INSTALL-AGENTS.md)。其中包含确切的引导顺序、 安全覆盖策略、验收检查和可复用的安装提示词。 ## 验证此工具包 ``` python3 scripts/verify.py ``` 这将编译 Python 工具，运行视觉测试工具测试，在临时目录中安全地执行 安装器，并验证生成的 NID 清单。 ## 艺术作品

主图和徽章是受 SharpEmu 棱角分明的霓虹灯 `S`、蓝色导轨和蓝紫色边框启发的原创艺术作品。它们将工具包的 证据到执行再到验证的循环可视化，没有使用主机品牌标识或受版权保护的 游戏图像。制作提示词和资产详细信息记录在 [`assets/readme/ARTWORK.md`](assets/readme/ARTWORK.md) 中。 ## 许可 本工具包和经过改编的 SharpEmu 测试工具遵循 GPL-2.0-or-later 许可证。这两个 集成子模块保留了它们各自的上游许可证；参见 [`NOTICE.md`](NOTICE.md)。

标签：AI智能体, SOC Prime, 云资产清单, 开发工具, 游戏主机模拟器, 逆向工具, 逆向工程