测试与调试
需求
测试应与修改范围匹配。纯 TypeScript 单元测试不能替代 Fabric 服务端、BDS/LSE 或 Electron 原生模块的集成验证。
| 修改范围 | 最低检查 |
|---|---|
| Shared / Agent Core | typecheck + Vitest |
| Java Adapter | Gradle test；涉及世界行为时加真实服务端验证 |
| Bedrock Adapter | typecheck + Vitest；涉及游戏 API 时加 BDS/LSE 验证 |
| 通信协议 | Agent Core 与两个 Adapter 的握手、注册、调用回归 |
| 文档 | 站内链接检查 + web 生产构建 |
架构
测试分三层：
- 静态层：TypeScript 类型检查、Java 编译、MDX 构建；
- 模块层：Vitest / JUnit 单元与组件测试；
- 运行层：Electron、Fabric 服务端和 BDS 的真实连接与工具调用。
协议与工具扩展必须覆盖第三层，因为两端当前存在批量返回形状等实现差异。
执行
TypeScript 工作区
cd d:\McAgent
pnpm typecheck
pnpm test只检查目标包：
pnpm --filter @mcagent/agent-core typecheck
pnpm --filter @mcagent/agent-core test
pnpm --filter @alice-mod/adapter-bedrock typecheck
pnpm --filter @alice-mod/adapter-bedrock testJava Adapter
cd d:\McAgent\packages\adapter-java
.\gradlew.bat test
.\gradlew.bat remapJar仓库的 Java build 在非 CI 环境可能触发 deployToServer，自动复制 JAR 到测试服务器。只需产物时使用 remapJar，避免无意覆盖本地实例。
Agent Core 原生模块
若测试和 Electron 使用不同 ABI：
cd d:\McAgent\packages\agent-core
pnpm rebuild:node
pnpm test
pnpm rebuild:native
pnpm devpretest 与 predev 也会调用 scripts/ensure-native.cjs。不要把为 Node 重建的二进制直接用于 Electron，反之亦然。
运行时联调清单
- 启动 Agent Core，确认 TCP 服务启动。
- 启动一个 Java 或 Bedrock 测试实例。
- 确认握手成功且 token 未出现在日志正文。
- 确认
register_tools后工作区工具列表更新。 - 调用一个只读工具，再调用目标变更涉及的工具。
- 测试断线重连与重新注册。
- 协议变更同时测试单次与批量调用。
调试定位
| 现象 | 优先检查 |
|---|---|
| 实例离线 | TCP 端口、Adapter 实际目标、实例 id 与 token、握手错误 |
| 实例在线但无工具 | register_tools 通知、Schema 归一化、工作区映射 |
| 单次成功、批量失败 | Java 裸数组与 Bedrock 包装返回差异 |
| 本地工具可见但执行失败 | 是否同时注册 Schema 和本地 handler |
| Java 附属工具缺失 | Fabric entrypoint、同名冲突、注册阶段异常 |
| Bedrock 工具缺失 | 编译输出目录、默认导出 class、LSE require() 路径 |
文档检查
cd d:\McAgent\web
pnpm build构建前还应检查相对链接目标是否存在，以及代码围栏、表格和 JSX 大括号是否闭合。