源码架构

本页帮助贡献者先确定修改应落在哪个包。Alice 当前是一个 pnpm 工作区，Java Adapter 另用 Gradle 构建；不要把设计文档中的目标架构当作已经存在的扩展 API。

需求

适用对象

需要阅读源码、修复问题或选择扩展位置的开发者。

组件边界

组件	源码位置	当前职责
Agent Core	`packages/agent-core/`	Electron 主进程、React 界面、模型调用、工作区、记忆、任务、触发器、QQ 与 TCP 服务端
Shared	`packages/shared/`	TypeScript 共享类型与协议结构
Java Adapter	`packages/adapter-java/`	Fabric + Carpet 服务端世界执行端、假人和 Java 工具
Bedrock Adapter	`packages/adapter-bedrock/`	Legacy Script Engine Node.js 插件、模拟玩家与目录式工具
NapCat	`packages/napcat/`	Alice 托管 QQ 接入所需组件
文档站	`web/`	Next.js 14 + Nextra 3 用户文档

架构

用户 / QQ
    │
    ▼
Agent Core（Electron 主进程 + React 渲染进程）
    │  TCP，换行分帧的 JSON-RPC 2.0
    ├──────────────────┐
    ▼                  ▼
Java Adapter       Bedrock Adapter
Fabric + Carpet    LSE Node.js + BDS

Agent Core 在 packages/agent-core/src/main/ 中组合主要能力：

llm/：Provider、模型路由与配置；
workspace/：实例与动态工具注册；
tcp/：连接、握手和心跳；
agent/、pipeline/：智能体执行与工具调度；
trigger/：事件触发器与适配器；
orchestration/：计划、进度、Markdown skill；
memory/、task/、qq-bot/：本地业务能力。

两个 Minecraft Adapter 都主动连接 Agent Core，并在连接后注册自己的工具 Schema。可用工具由工作区、Adapter 和 Agent Core 本地工具共同决定，不是固定数量。

选择扩展机制

目标	应使用的机制
Java 世界中新工具	`alice-mod:plugin` Java 附属模组
Bedrock 世界中新工具	Adapter 内 `tools/<category>/<tool>/index.ts`
新模型服务商	实现 `LLMProvider` 并接入 ProviderRegistry
新事件来源	实现并接线 `TriggerAdapter`
不依赖 Minecraft 的能力	Agent Core 本地工具
调整编排阶段提示	Markdown skill
第三方 Adapter	按源码验证通信协议

执行

按开发环境安装 Node.js、pnpm 与所需 Java 工具链。
从仓库根目录运行 pnpm install。
只构建或测试正在修改的包，减少原生依赖和游戏环境带来的干扰。
修改协议或共享类型时，同时核对 Agent Core、Java Adapter 与 Bedrock Adapter。
提交前执行测试与调试中的对应命令，并按贡献流程整理变更。

当前限制

Java 附属模组有明确 Fabric entrypoint；Agent Core 和 Bedrock 没有等价的、可独立安装的通用插件包格式。
Bedrock 工具扫描是 Adapter 内部目录约定，不代表已有成熟的第三方插件市场或兼容性承诺。
协议实现仍在演进，尤其是批量工具调用在 Java 与 Bedrock 返回形状上存在差异。

开发环境 Java 附属模组