本页面为首次接触 Acidify 代码仓库的读者提供文档阅读指南。通过本页面，您将了解项目的整体定位、模块划分以及建议的文档阅读顺序。本指南帮助您根据使用场景（协议端使用者、库开发者、协议研究者）选择合适的学习路径。
有关具体模块的职责划分，请参阅 系统架构与模块边界。
Acidify 代码仓库包含两个核心产品：
acidify-core 的定位：提供类型安全的 Kotlin DSL，封装 NTQQ 协议的底层细节（SSO 通信、包签名、消息编解码、媒体上传等），对外暴露 Bot/AndroidBot 等高层接口。库本身不包含 HTTP 服务器或事件分发机制，适合集成到自定义应用中。
yogurt 的定位：在 acidify-core 之上构建完整的协议端服务，通过 Ktor 提供 HTTP REST API、WebSocket、SSE 等接口，实现 Milky 协议标准。内置配置管理、脚本扩展系统、多通道事件推送等功能，可作为独立可执行程序运行。
Sources: README.md15-21 acidify-core/build.gradle.kts13-14 yogurt/build.gradle.kts14
| 模块名称 | 类型 | 平台支持 | 主要职责 | 入口类/函数 |
|---|---|---|---|---|
acidify-core | Library | JVM, JS, Native | NTQQ 协议实现，Bot API | Bot.create, AndroidBot.create |
acidify-core-js | JS 导出 | Node.js | acidify-core 的 JavaScript 绑定 | @acidify/core npm 包 |
yogurt | Application | Native (Win/Mac/Linux) | Milky 协议端实现 | org.ntqqrev.yogurt.main |
yogurt-jvm | Application | JVM | yogurt 的 JVM 平台适配 | org.ntqqrev.yogurt.jvm.Main |
yogurt-scripting | Types Package | TypeScript | yogurt 脚本类型定义 | @acidify/yogurt-scripting |
acidify-docs | Documentation | Web | Next.js 文档站 + Dokka API 文档 | acidify.ntqqrev.org |
依赖关系：yogurt 和 yogurt-jvm 依赖 acidify-core，但 acidify-core 本身是独立库，不依赖 yogurt。构建系统使用 Gradle Version Catalog (gradle/libs.versions.toml) 统一管理版本。
Sources: README.md15-21 gradle/libs.versions.toml1-90 acidify-core/build.gradle.kts16-25 yogurt/build.gradle.kts16-51
本 Wiki 按照由外到内、由浅入深的原则组织：
Sources: Based on TOC structure from author's context
目标：通过 Milky 协议对接其他 Bot 框架，无需了解内部实现。
| 顺序 | 章节 | 关注点 |
|---|---|---|
| 1 | 系统架构与模块边界 | 理解 yogurt 在整体架构中的位置 |
| 2 | Yogurt 应用层 | yogurt 功能总览 |
| 3 | 启动流程与运行时生命周期 | 如何启动和配置 yogurt |
| 4 | 配置与安全策略 | YogurtConfig 配置项说明 |
| 5 | Milky API 与处理器分层 | HTTP/WebSocket/SSE 接口使用 |
| 6 | 事件推送通道 | 选择合适的事件订阅方式 |
| 7 | 脚本扩展系统 | 可选：编写 JavaScript 扩展 |
跳过章节：第 3 章（Acidify Core 设计）和第 5 章（工程化）可暂时跳过。
Sources: acidify-docs/content/yogurt/start.md (implied from README reference)
目标：将 acidify-core 集成到自定义 Kotlin/JVM 或 Node.js 应用中。
| 顺序 | 章节 | 关注点 |
|---|---|---|
| 1 | 系统架构与模块边界 | acidify-core 的能力边界 |
| 2 | Acidify Core 设计 | acidify-core 整体设计 |
| 3 | 公开 API 与对象模型 | Bot/AndroidBot 接口使用 |
| 4 | 登录流程与会话凭据 | SessionStore 与 SignProvider |
| 5 | 消息体系与段构建管线 | BotIncomingMessage/BotOutgoingSegment DSL |
| 6 | 事件流、日志与缓存策略 | AcidifyEvent 处理与日志配置 |
| 7 | Yogurt 应用层 | 可选：参考 yogurt 的集成实践 |
参考实现：yogurt 源码是使用 acidify-core 的最佳实践示例。
Sources: acidify-docs/content/core/kotlin.md1-101 acidify-docs/content/core/nodejs.md1-62
目标：理解 NTQQ 协议实现细节，参与协议层开发。
| 顺序 | 章节 | 关注点 |
|---|---|---|
| 1 | 系统架构与模块边界 | 完整系统架构 |
| 2 | 公开 API 与对象模型 | 理解公开接口设计 |
| 3 | 网络客户端与上下文状态机 | LagrangeClient/PacketContext 实现 |
| 4 | 服务调用框架与业务服务 | internal.service 层组织 |
| 5 | 协议数据定义与编码层 | proto/tlv 结构与编解码 |
| 6 | 密码学与底层工具集 | internal.crypto/math/util 实现 |
| 7 | 消息体系与段构建管线 | 消息解析与构建的完整流程 |
| 8 | 实体转换与消息桥接 | yogurt 的 Acidify ↔ Milky 转换 |
关键入口：LagrangeClient 是理解网络通信的核心，PacketLogic 是理解业务逻辑的入口。
Sources: High-level diagrams provided in context
| 类型 | 位置 | 作用 |
|---|---|---|
Bot | org.ntqqrev.acidify | PC 协议 Bot 实例，主要公开接口 |
AndroidBot | org.ntqqrev.acidify | Android 协议 Bot 实例 |
AbstractBot | org.ntqqrev.acidify | Bot 抽象基类，实现共享逻辑 |
SessionStore | org.ntqqrev.acidify.common | PC 协议会话凭据存储 |
AndroidSessionStore | org.ntqqrev.acidify.common | Android 协议会话凭据存储 |
SignProvider | org.ntqqrev.acidify.common | 包签名提供者接口 |
UrlSignProvider | org.ntqqrev.acidify.common | 通过 URL 获取签名的实现 |
AppInfo | org.ntqqrev.acidify.common | 客户端模拟信息（版本、OS 等） |
LagrangeClient | org.ntqqrev.acidify.internal.client | SSO 通信客户端 |
PacketContext | org.ntqqrev.acidify.internal.client | 连接状态管理 |
BotIncomingMessage | org.ntqqrev.acidify.message | 接收消息的统一结构 |
BotOutgoingMessageBuilder | org.ntqqrev.acidify.message | 发送消息的 DSL 构建器 |
AcidifyEvent | org.ntqqrev.acidify.event | 事件基类 |
MessageReceiveEvent | org.ntqqrev.acidify.event | 消息接收事件 |
Sources: acidify-docs/content/core/kotlin.md44-88
| 类型 | 位置 | 作用 |
|---|---|---|
YogurtApp | org.ntqqrev.yogurt | Ktor 应用主类 |
Initialization | org.ntqqrev.yogurt | 启动初始化逻辑 |
YogurtConfig | org.ntqqrev.yogurt.config | 配置数据类 |
HttpRoutes | org.ntqqrev.yogurt.api | API 路由注册 |
MilkyApiContext | org.ntqqrev.yogurt.api | API 上下文（DI、鉴权等） |
toMilkyEntity | org.ntqqrev.yogurt.transform | Acidify 实体 → Milky 实体 |
transformSegment | org.ntqqrev.yogurt.transform | Milky 段 → Acidify 段 |
transformAcidifyEvent | org.ntqqrev.yogurt.transform | Acidify 事件 → Milky 事件 |
WebSocketEventHandler | org.ntqqrev.yogurt.event | WebSocket 事件推送 |
SSEEventHandler | org.ntqqrev.yogurt.event | SSE 事件推送 |
WebhookEventHandler | org.ntqqrev.yogurt.event | Webhook POST 事件推送 |
ScriptLoader | org.ntqqrev.yogurt.script | JavaScript 脚本加载器 |
Sources: Inferred from high-level diagrams and yogurt module description
npm install @acidify/corenpm install @acidify/yogurt-scriptingSources: acidify-docs/content/index.md1-24
详细信息参见 工程化与发布体系。
| 发布目标 | 触发方式 | 版本来源 | 相关 Workflow |
|---|---|---|---|
| Maven Central | 手动触发 | acidify-core/build.gradle.kts14 | publish-acidify-core.yml |
| npm @acidify/core | 手动触发 | acidify-core/build.gradle.kts14 | publish-acidify-core.yml |
| npm @acidify/yogurt | 自动推送 | yogurt/build.gradle.kts14 | build-yogurt.yml |
| GitHub Releases | 自动推送 | yogurt/build.gradle.kts14 | build-yogurt.yml |
Sources: acidify-core/build.gradle.kts13-14 yogurt/build.gradle.kts14 High-level diagram 4 from context
完成本页面阅读后，建议按照以下顺序继续：
提示：本 Wiki 的每个页面底部都会列出"Sources"，指向该页面内容所依据的源代码文件位置。您可以通过这些链接直接定位到相关代码进行阅读。
Sources: acidify-core/build.gradle.kts97-120 (Dokka configuration)
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.