开发环境

需求

基础环境

范围	必需环境	事实来源
根工作区 / Agent Core / Bedrock	Node.js 20 及以上、pnpm 8 及以上	根 `package.json` 的 `engines`
Agent Core	Windows 开发环境；Electron 37；原生 `better-sqlite3` 构建能力	`packages/agent-core/package.json`
Java Adapter	Java 21、Gradle Wrapper	`gradle.properties` 与 `build.gradle`
文档站	Node.js 20+、pnpm；Next.js 14 / Nextra 3	`web/package.json`
Bedrock 运行验证	BDS 与兼容 Legacy Script Engine Node.js 环境	Bedrock Adapter 当前入口源码

Git、可用的 C/C++ 原生构建工具链和 PowerShell 也是 Windows 上安装 Electron 原生依赖时的常见前提。

架构

根目录使用 pnpm workspace 管理 packages/*。Java Adapter 不属于 npm 构建链，需在 packages/adapter-java 使用 Gradle Wrapper。文档站位于 web/，不是根 workspace 的 packages/* 成员，应在该目录单独执行脚本。

开发环境分为三档：

只改 Agent Core / Shared：Node.js + pnpm；
改 Java Adapter：再安装 Java 21，并准备 Fabric/Carpet 测试实例；
改 Bedrock Adapter：再准备 BDS/LSE Node.js 测试实例。

执行

1. 安装依赖

cd d:\McAgent
pnpm install
 
cd web
pnpm install

不要混用 npm 生成新的锁文件。仓库根目录以 pnpm-lock.yaml 和 pnpm-workspace.yaml 为准。

2. 启动 Agent Core

cd d:\McAgent
pnpm dev

pnpm dev 会运行 @mcagent/agent-core 的 Electron Vite 开发脚本。首次启动前置脚本会检查 Electron 对应的原生模块。

3. 构建各组件

# TypeScript 工作区
pnpm build
 
# Java Adapter
cd packages\adapter-java
.\gradlew.bat remapJar
 
# 文档站
cd d:\McAgent\web
pnpm build

Bedrock 的 build 会执行复制到 BDS 的脚本；若只想做静态检查，优先运行：

pnpm --filter @alice-mod/adapter-bedrock typecheck
pnpm --filter @alice-mod/adapter-bedrock test

4. 成功标志

pnpm typecheck 能遍历 workspace 包；
Agent Core Electron 窗口正常启动；
Java remapJar 在 build/libs/ 产生 JAR；
文档站生产构建通过；
需要游戏联调时，目标 Adapter 完成握手并注册工具。

常见失败

失败	处理
`better-sqlite3` ABI 不匹配	在 `packages/agent-core` 运行对应的 `rebuild:native` 或 `rebuild:node` 脚本
Java 编译器版本错误	确认 `java -version` 与 Gradle toolchain 都指向 Java 21
Bedrock build 意外复制文件	先检查 `scripts/copy-to-bds.js` 的本地目标，再运行完整 build
文档开发正常但生产失败	以 `web` 下 `pnpm build` 为最终 MDX/链接入口检查

源码架构