概览

Relevant source files

• .github/workflows/build-yogurt.yml
• README.md
• acidify-core/build.gradle.kts
• acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/event/MessageRecallEvent.kt
• acidify-core/src/jvmMain/kotlin/org/ntqqrev/acidify/logging/LogUtils.jvm.kt
• acidify-core/src/nativeMain/kotlin/org/ntqqrev/acidify/logging/LogUtils.native.kt
• buildSrc/settings.gradle.kts
• buildSrc/src/main/kotlin/kotlin-multiplatform.gradle.kts
• gradle/libs.versions.toml
• packages/docs/content/yogurt/start.md
• settings.gradle.kts
• yogurt-media-codec/src/macosX64Main/kotlin/org/ntqqrev/yogurt/codec/LoadCodecLibrary.macosX64.kt
• yogurt/build.gradle.kts
• yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt
• yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtConfig.kt
• yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/event/Webhook.kt
• yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/transform/EventTransform.kt
• yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/transform/MessageTransform.kt

本文档介绍 acidify 项目的整体架构、核心模块关系以及支持的平台。acidify 由两个主要部分组成：acidify-core 是 PC NTQQ 协议的底层实现库，yogurt 是基于 acidify-core 构建的 Milky API 服务器应用。关于 acidify-core 的详细实现，请参阅 Acidify Core；关于 yogurt 应用的详细配置和使用，请参阅 Yogurt 模块。

---

1. 项目简介与定位

1.1 acidify-core：协议实现库

acidify-core 是一个 Kotlin Multiplatform 库，实现了腾讯 QQ PC 端（NTQQ）的通信协议。它提供了完整的 Bot API，支持登录认证、消息收发、好友/群组管理、文件传输等核心功能。

核心特性：

• 多平台支持：JVM、Native（Windows/macOS/Linux）、JavaScript（Node.js）
• 完整的协议实现：SSO 包封装、Tea 加密、Protobuf 序列化
• 响应式事件系统：基于 Kotlin Flow 的异步事件流
• 可扩展架构：支持自定义 SignProvider、SessionStore

发布方式：

• Maven Central: org.ntqqrev:acidify-core:0.6.1 acidify-core/build.gradle.kts13-14
• npm: @acidify/core acidify-core/build.gradle.kts26

1.2 yogurt：Milky API 服务器

yogurt 是基于 acidify-core 的 Milky 标准 实现，将协议库封装为 HTTP/WebSocket/SSE API 服务器，使得任何编程语言的客户端都可以通过 RESTful API 或实时事件流与 QQ 交互。

核心特性：

• RESTful API：50+ 端点覆盖所有 Bot 操作 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/api
• 多通道事件分发：WebSocket、SSE、Webhook 三种实时推送方式
• 媒体处理：集成 LagrangeCodec 进行语音/视频编解码
• 配置化部署：通过 config.json 管理所有运行参数 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtConfig.kt17-26

发布方式：

• npm: @acidify/yogurt 及平台特定包（如 @acidify/yogurt-win32-x64）
• JVM Fat JAR: yogurt-jvm-all.jar
• Native 可执行文件：五个平台的预编译二进制

1.3 模块依赖关系

Sources: settings.gradle.kts19-23 acidify-core/build.gradle.kts32-42 yogurt/build.gradle.kts17-27

---

2. 核心模块架构

2.1 acidify-core 模块组成

包路径	功能描述	关键类型
org.ntqqrev.acidify	Bot 主接口	Bot, BotFactory
org.ntqqrev.acidify.message	消息模型	BotIncomingMessage, BotOutgoingMessageBuilder
org.ntqqrev.acidify.event	事件系统	AcidifyEvent, MessageReceiveEvent
org.ntqqrev.acidify.internal.client	协议客户端	LagrangeClient, PacketContext
org.ntqqrev.acidify.internal.service	业务服务层	50+ service implementations
org.ntqqrev.acidify.common	会话管理	SessionStore, AppInfo, SignProvider

2.2 yogurt 模块组成

Sources: settings.gradle.kts19-23 yogurt/build.gradle.kts1-74 README.md15-23

各子模块职责：

• yogurt: 包含 Ktor 服务器配置、API 路由、事件转换等核心逻辑 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt
• yogurt-jvm: 提供 JVM 平台的 main 函数入口和 UTF-8 控制台输出兼容性
• yogurt-media-codec: 封装 LagrangeCodec 的音视频编解码能力，支持 JVM 和 Native 平台 #4.1
• yogurt-qrcode: 精简自 qrcode-kotlin 的二维码矩阵生成器 #4.2

---

3. 平台支持与发布方式

3.1 支持平台矩阵

平台	acidify-core	yogurt	发布渠道
Kotlin/JVM	✅	✅ (Fat JAR)	Maven Central, GitHub Actions
Kotlin/JS (Node.js)	✅	❌	npm (@acidify/core)
Windows x64	✅	✅	npm (@acidify/yogurt-win32-x64)
macOS x64	✅	✅	npm (@acidify/yogurt-darwin-x64)
macOS arm64	✅	✅	npm (@acidify/yogurt-darwin-arm64)
Linux x64	✅	✅	npm (@acidify/yogurt-linux-x64)
Linux arm64	✅	✅	npm (@acidify/yogurt-linux-arm64)

Sources: README.md31-38 acidify-core/build.gradle.kts16-29 buildSrc/src/main/kotlin/kotlin-multiplatform.gradle.kts10-29

3.2 构建与发布流程

Sources: acidify-core/build.gradle.kts54-87 .github/workflows/build-yogurt.yml1-278

关键配置：

• Maven 发布: 通过 com.vanniktech.maven.publish 插件自动化发布到 Sonatype acidify-core/build.gradle.kts54-56
• npm 版本同步: Python 脚本从 build.gradle.kts 提取版本号，结合 GITHUB_RUN_NUMBER 生成开发版本号 .github/workflows/build-yogurt.yml152-250
• Dokka 文档: 输出到 packages/docs/public/kdoc，部署到 GitHub Pages acidify-core/build.gradle.kts94-116
• TypeScript 定义: Kotlin/JS 自动生成 .d.ts 文件 acidify-core/build.gradle.kts21

---

4. 技术栈概览

4.1 核心技术依赖

技术栈	版本	用途
Kotlin	2.3.0	主开发语言
kotlinx-coroutines	1.10.2	异步并发框架
kotlinx-serialization	1.10.0-RC	JSON/Protobuf 序列化
Ktor Client	3.3.3	HTTP 客户端（Sign API、Highway 上传）
Ktor Server	3.3.3	HTTP/WebSocket/SSE 服务器（yogurt）
Milky Types	1.1.0	Milky 标准数据模型

Sources: gradle/libs.versions.toml5-23

4.2 协议通信架构

Sources: Diagram 6 from high-level system diagrams

协议层说明：

• PacketContext: 维护与 QQ 服务器的 TCP 长连接，处理 SSO 协议包的加密、签名、序列化 acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/internal/client/PacketContext.kt
• HighwayContext: 专用于大文件上传，支持 1MB 分块、断点续传 acidify-core/src/commonMain/kotlin/org/ntqqrev/acidify/internal/client/HighwayContext.kt
• SignProvider: 外部签名服务接口，用于通过反爬虫检测 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt95

---

5. 生态系统定位

5.1 与 Milky 标准的集成

yogurt 实现了 Milky v1.1.0 标准，提供三个主要接口层：

Sources: yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt138-163 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/transform

接口特性：

• 认证机制: Bearer Token 通过 accessToken 配置 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtConfig.kt37
• CORS 配置: 支持自定义允许的源列表或全部放行 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt122-130
• 登录保护: API 路由自动检查 Bot 登录状态 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/api

5.2 外部依赖关系

依赖类型	服务地址	用途	配置位置
Sign API	用户配置 URL	包签名服务，绕过反爬虫检测	YogurtConfig.signApiUrl yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtConfig.kt18
QQ MSF 服务器	msfwifi.3g.qq.com:8080	NTQQ 协议主服务器	内置在 PacketContext
Highway CDN	动态分配	媒体文件上传服务器	通过协议动态获取
LagrangeCodec	本地动态库	音视频编解码	./lib/{platform}/ yogurt-media-codec/src/macosX64Main/kotlin/org/ntqqrev/yogurt/codec/LoadCodecLibrary.macosX64.kt11

Sources: yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt51-59 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt95-105

---

6. 快速开始参考

6.1 作为库使用 (acidify-core)

JVM / Kotlin:

JavaScript / TypeScript:

6.2 作为应用部署 (yogurt)

通过 npm (推荐):

通过 JVM:

首次启动会在当前目录生成 config.json，需要配置 signApiUrl 后才能正常运行 yogurt/src/commonMain/kotlin/org/ntqqrev/yogurt/YogurtApp.kt51-59。

Sources: README.md11-38 packages/docs/content/yogurt/start.md1-49

---

7. 总结

acidify 项目采用分层架构设计：acidify-core 作为可重用的协议库，可以直接集成到任何 Kotlin 应用中；yogurt 作为开箱即用的 Milky API 服务器，为非 Kotlin 生态提供标准化接口。通过 Kotlin Multiplatform 技术，项目实现了跨 JVM、Native、JavaScript 的全平台覆盖，并通过多种包管理器（Maven Central、npm）降低了集成门槛。

关于 acidify-core 的详细实现架构和 API 设计，请参阅 Acidify Core；关于 yogurt 的配置、API 端点和事件系统，请参阅 Yogurt 模块。

Sources: README.md1-72 acidify-core/build.gradle.kts yogurt/build.gradle.kts settings.gradle.kts