AI 与 MCP 智能体开发总览 (AI & Agentic Engineering)
在企业级软件系统全面迈向 AI-Native 的时代，让大语言模型（LLM）具备“行动能力（Action / Function Calling）”已成为现代架构的核心命题。传统的做法通常是人工为每一个 API 手写 OpenAPI 规范、编写胶水层代码、或直接将数据库连接串暴露给智能体，这种方式存在严重的接口漂移、逻辑重复侵入、零安全审计与多租户越权泄露隐患。
BitzOrcas.Modern 采取了根本性的架构创新：深度原生集成 Anthropic 开源的 Model Context Protocol (MCP) 工业级开放标准，通过 C# 编译期 Roslyn 源码生成技术（Source Generator），将框架现有的 CQRS 垂直切片（Vertical Slices）以“零运行时反射开销、零胶水代码”的形式直接暴露为标准 MCP Tools。
1. 架构核心范式：业务切片即 Agent 工具
在 BitzOrcas 中，开发者不需要为 AI 重新编写一套专有服务。每一个经过严格领域校验、具备多租户上下文、受 Mediator 管线保护的 ICommand 或 IQuery，均可通过一个编译期属性声明直接变为 AI 智能体可调用的工具：
2. 核心技术支柱与设计原则
BitzOrcas 的 AI 智能体体系由 4 大设计原则奠定：
| 核心支柱 | 传统 AI 集成做法的痛点 | BitzOrcas.Modern 的工程解法 |
|---|---|---|
| 元数据提取 | 运行时反射扫描程序集，启动慢且无法通过 Native AOT 编译 | 编译期 Roslyn 源码生成：BitzOrcas.Mcp.SourceGenerator 在编译时从 C# 类注释与主构造参数推导出符合 JSON Schema 规范的工具元数据。 |
| 执行通道 | 为 AI 单独写一套 Controller 或 RPC，代码碎片化严重 | 统一 Mediator 管线：MCP 请求进入系统后，反序列化为真实的 Command/Query 消息，完整经历租户隔离、参数校验、事务发件箱与领域事件派发。 |
| 多租户安全 | 智能体容易发生跨租户数据串扰与越权未决操作 | 双层防护闸门：请求期由 McpTenantAccessGate 阻断非授权租户；工具清单期根据租户已购 Feature 动态修剪工具列表，不可见即不可调用。 |
| 操作可追溯 | AI 自主执行了业务写操作，事后无法追踪是哪个 Agent 调用的 | 专用审计链：McpToolInvocationAuditor 完整记录模型会话 Id、工具名称、参数 SHA256 哈希、执行耗时与业务执行结果。 |
3. 本专题章节导航
为了帮助团队快速落地 Agentic AI 能力，本专题划分为以下关键实践篇章：
快速开始
BitzOrcas.Modern 开发者上手总览：从架构哲学认知、前置依赖审查、Docker 容器基础设施拉起，到执行首个多租户垂直切片业务用例。
实战教程
BitzOrcas.Modern 官方进阶实战通关地图。通过 6 个循序渐进的工业级真实业务场景（案件立案、合同模块、利冲校验、合伙人审批流、实时通知与集成测试），系统掌握 .NET 10 模块化单体开发技能。
开发指南
BitzOrcas.Modern 核心开发指南目录：涵盖垂直切片编写、前端元数据充水、功能与模块新增、六边形适配器扩展、本地 Aspire 基础设施与代客模拟沙箱。
核心构建块
全景梳理 BitzOrcas.Modern 核心构建块武器库，从统一聚合根、QueryShape 列表查询内核、CAP Outbox 到多级缓存与 S3 存储。
横切关注点
理解 BitzOrcas 如何在 HTTP 中间件、Mediator 管线和生产适配器之间分配横切职责。
安全与授权
从认证、授权、租户隔离、请求完整性、数据保护和审计理解 BitzOrcas 的纵深防御。
架构体系
全面解析 BitzOrcas.Modern 企业级架构体系：模块化单体物理边界、垂直切片架构、10 级执行管道、编译期零反射双 ORM 与 Native AOT 架构支点。
架构决策 (ADR)
BitzOrcas ADR 索引——分类法、生命周期、编号，以及与交付、安全、运维和模块化最相关的已选决策。
全景架构图
BitzOrcas.Modern 系统架构的可视化图表集合。
工程治理
让一次 BitzOrcas 发布具备可交付性的质量门禁、生产就绪棘轮、扩展接入、模块治理、就绪矩阵与行业中立规则。
平台能力中心
BitzOrcas.Modern 平台级专业业务子系统、跨模块核心引擎与规则治理中心。
业务模块扩展
深入解析 BitzOrcas.Modern 业务模块架构规范、ADR 0203 物理隔离准则、ADR 0205 平台扩展模式与 Sandbox 黄金样例。
工作流引擎
从可视化设计器、定义 DSL、部署绑定、实例与任务，到通知、历史、迁移、嵌入和生产运维的源码校验导航。
AI 与智能体
深入解析 BitzOrcas.Modern 原生 AI-Native 架构：基于 Model Context Protocol (MCP) 与编译期代码生成，将企业垂直切片无缝转变为智能体工具。
前端架构
BitzOrcas 前端是一个 Yarn 4 单仓。Web 管理端是 React 19 + Vite；移动端是 Taro 4 + Capacitor。两侧都经唯一的类型化契约抵达 .NET 后端。
Design Token
BitzOrcas Design System 1.2 的冻结范围、权威顺序、稳定主题、体验 Profile 与代码实现状态。
CLI 工具
选择 Consumer Solution 模板、代码生成、Schema、Seed、Workflow 与数据库维护入口，并理解每个工具的写入面、权限和证据边界。
测试体系
从单元测试到商业发布证据，理解 BitzOrcas 的五层测试体系，并按改动选择正确验证集。
生产部署
从本地 Aspire 到生产 Host、配置、数据库、可观测性和商业 GA，规划 BitzOrcas 部署。
商业交付
从产品仓库、NuGet 包、Consumer Solution 到正式 GA，理解 BitzOrcas 的商业交付边界和证据链。
其他
查阅代码提交约定、文档维护方式、版本记录和后续投资方向。
4. 相关架构决策与进阶推荐 (Related Deep Dives)
- 架构决策：ADR 0103：源生成器完全替代运行时反射
- 安全规范：生产安全核对清单与敏感操作保护
- 测试用例：阅读
tests/BitzOrcas.Framework.Tests/Mcp/查看工具生成与参数提取的断言验证 - CLI 提效：使用 bitz generate-slice 一键生成打标
[GenerateMcpTool]的业务切片