foxminchan/BookWorm

BookWorm – 一个演示云原生应用，展示如何将 AI 代理编织到现代微服务系统中

它是什么

• 一个参考实现，将典型的电子商务店面/后台与一套 AI 驱动的代理相结合。它旨在说明 Aspire（微软的云原生应用框架）以及一整套企业模式（DDD、垂直切片架构、CQRS、事件溯源、saga、outbox/inbox 等）。
• AI 方面使用 Microsoft Foundry 提供大语言模型和嵌入，并使用 Agent Framework 编排多个代理，这些代理可以通过 Model Context Protocol (MCP)、A2A（代理到代理）和 AG-UI（代理生成的 UI）协议相互通信。
• 该仓库明确标记为 仅演示 – 不用于生产环境。

关键能力

领域	演示包含的内容
架构	使用 Aspire 构建的云原生微服务、垂直切片架构、CQRS、事件溯源、saga 编排、outbox/inbox 模式，以及用于横切关注点的 chassis。
安全	使用 Keycloak 进行身份验证/授权，采用 OAuth2 授权码流程（带 PKCE）和令牌交换用于服务间调用。
AI 集成	• Microsoft Foundry 用于 LLM 调用和向量嵌入 • 由 Agent Framework 编排的多代理工作流 • 通过 MCP、A2A、AG-UI 协议实现标准化工具 • 基于策略的代理治理和监控 • 代理可以生成交互式 UI 组件（A2UI）。
API	REST 端点的 OpenAPI 规范，事件驱动契约的 AsyncAPI，基于 Pact 的契约测试。
前端	由 Turborepo 驱动的 monorepo；使用 Next.js 构建的客户店面和管理后台，符合 WCAG 2.1 AA 无障碍标准。
可观测性与运维	使用 FusionCache 进行缓存，CI/CD 管道（GitHub Actions），SonarCloud 质量门禁，SLSA-2 供应链保护，OpenSSF Scorecard。
测试	服务单元测试、契约测试（Pact）、架构测试、前端单元/组件测试、BDD 风格端到端测试。

技术栈概览

• 后端：.NET 8、Aspire、gRPC、Entity Framework、EventStore（事件溯源）、Keycloak、FusionCache。
• AI：Microsoft Foundry（LLM 和嵌入）、Agent Framework、MCP/A2A/AG-UI 协议。
• 前端：Next.js (React)、Turborepo、TypeScript、符合 WCAG 的 UI。
• 基础设施：Docker、Azure Container Apps（部署）、用于 Foundry 的 Azure 订阅、GitHub Codespaces 用于快速启动。
• 开发工具：mise（版本管理器）、Buf（gRPC 代码生成）、Spec-Kit、GitHub Copilot CLI（可选）、Azure CLI。

如何在本地尝试

# 克隆并进入仓库
git clone git@github.com:foxminchan/BookWorm.git && cd BookWorm

# 安装所需工具（dotnet、bun、jdk 等）
mise install

# 设置 Foundry 所需的 Azure 密钥（替换为你的 ID）
aspire secret set "Azure:SubscriptionId" "<your-sub-id>"
aspire secret set "Azure:Location" "<your-location>"

# 一次性准备（生成代码、构建容器等）
mise run prepare

# 启动所有服务（Docker 必须运行）
mise run run

该命令会启动后端服务、Next.js 前端以及用于电子邮件测试的本地 mail-pit 实例。启动后不久，你可以访问店面 http://localhost:5173（或控制台显示的端口）。

部署到 Azure

1. az login 登录你的 Azure 账户。
2. aspire deploy – 脚本会创建资源组、Container Apps 环境，并推送 Docker 镜像。
3. 使用 az containerapp show … 命令获取公共 URL。
4. 完成后，删除资源组以避免费用。

何时有用

• 学习如何使用新兴标准（MCP、A2A、AG-UI）将 AI 代理接入微服务生态系统。
• 查看一个全栈、DDD 驱动的示例，包括同步（gRPC/REST）和异步（事件溯源、saga）通信。
• 探索Azure 优先部署的云原生应用，同时使用微软的 LLM 平台。
• 在单个仓库中获取CI/CD、测试和安全加固（SLSA-2、OpenSSF Scorecard）的模板。

限制/注意事项

• 该项目未达到生产就绪 – 缺乏健壮的扩展性、多区域弹性和全面的性能调优。
• 它依赖于 Microsoft Foundry 订阅；没有它，AI 组件将无法工作。
• 一些可选工具（Buf、Spec-Kit、Copilot CLI）不是核心演示所必需的，但可能用于完整的代码生成工作流。
• UI 是简单的演示；真实世界的电子商务功能（支付、库存管理等）被存根或省略。

更多信息

• 完整文档位于仓库的 GitHub Wiki 中。
• 架构图（assets/BookWorm.png）可视化了服务网格和代理交互。
• 提供了贡献指南、行为准则和问题模板，供任何想要扩展演示的人使用。