使用说明

确定性MCP智能体课程

一个全面的课程实施，旨在使用Rust语言中的确定性有限状态机构建生产就绪的MCP（模型上下文协议）代理。

仓库结构

.
├── modules/
│   ├── 01-foundations/    # Core concepts and theory
│   ├── 02-setup/         # Environment and toolchain
│   ├── 03-agents/        # Production agent patterns
│   ├── 04-mcp-server/    # MCP server implementation
│   └── 05-testing/       # Testing and QA strategies
├── final_project/        # Complete production system
├── pmcp/                # Shared MCP library
├── scripts/             # Automation and verification
└── docs/               # Course documentation

快速入门

先决条件

Rust 1.75+（从以下链接安装 `rustup.rs` 翻译为中文是“Rust 工具链管理器的配置文件或网站”（通常我们更倾向于说它是一个用于管理 Rust 工具链的脚本或网站，具体根据上下文理解）。在实际应用中，`rustup.rs` 是 Rust 官方提供的用于安装、管理不同版本的 Rust 编译器以及其配套工具的工具链管理器的脚本或配置入口)
PMAT 0.29.6+ 版本，带有MCP功能
Docker（可选，用于容器化）

安装

# Clone the repository
git clone https://github.com/paiml/deterministic-mcp-agents-course
cd deterministic-mcp-agents-course

# Install development dependencies
make install-dev

# Build all modules
make build

# Run tests
make test

# Check quality gates
make quality-gate-all

课程模块

模块1：基础（18:00）

课程概述及性能基准
确定性-范围权衡演示
弗洛里迪猜想的实现
MCP协议基础

模块2：环境设置（18:00）

Rust工具链配置
PMAT安装与验证
质量门实施
计算器代理示例

模块3：生产代理（23:00）

有限状态机（FSM）构建器模式
重构状态机
代码分析有限状态机（FSM）
错误边界实现

模块4：MCP服务器（22:00）

PMCP服务器实现
工具组合模式
异步请求处理
使用Docker/K8s进行生产部署

模块5：测试与质量保证（09:00）

属性测试套件
模糊测试基础设施
集成测试
覆盖范围要求

质量标准

所有代码必须满足以下质量要求：

复杂性最大圈复杂度为20
SATD对技术债务标记零容忍
死代码少于5%
测试覆盖率最低代码覆盖率要求为95%
文档100%公开API文档

示例文档

本课程包含19个全面的示例，展示了构建确定性MCP（马尔可夫决策过程）代理中的关键概念。每个示例均可完全执行，并附有详细的内联文档说明。

按模块划分的示例分布：

模块1（基础）：4个示例
模块2（设置）：4个示例
模块3（代理）：4个示例
模块4（MCP服务器）：4个示例
模块5（测试）：3个示例

模块1：基础

00_课程概述.rs

课程概述与介绍

介绍课程结构和学习目标
展示了智能体设计中确定性与范围之间的关系
展示基本的有限状态机（FSM）模式和MCP协议概念
运行： cargo run --example 00_course_overview -p module-01-foundations

01_确定性范围演示.rs

确定性与范围权衡的展示

实现了基本约束条件 C(M) × S(M) ≤ k
展示了随着确定性的增加，范围会缩小，反之亦然
展示了在智能体决策中的实际应用
包含不同复杂程度的互动示例
运行： cargo run --example 01_certainty_scope_demo -p module-01-foundations

02_floridi_conjecture.rs 翻译为中文是：“02_弗洛里迪猜想.rs”。不过，这里的“.rs”通常表示这是一个用Rust语言编写的文件（Rust是一种系统编程语言），所以在更具体的上下文中，你可能会说“02_弗洛里迪猜想的Rust程序文件”或者“02_弗洛里迪猜想的.rs源代码文件”。但直接翻译文件名时，保持原样或稍作解释即可

弗洛里迪猜想的实现

实现了弗洛里迪的语义信息理论
展示了数据、信息和知识之间的关系
展示代理如何验证信息的真实性
包含实际应用中的语义验证示例
运行： cargo run --example 02_floridi_conjecture -p module-01-foundations

03_mcp协议基础.rs

MCP协议基础

模型上下文协议（MCP）简介
展示请求/响应模式
展示工具注册和能力协商
包括基本错误处理和协议验证
运行： cargo run --example 03_mcp_protocol_basics -p module-01-foundations

模块2：环境设置

04_toolchain_setup.rs 翻译为中文是：“04 工具链设置.rs”

Rust 工具链配置

验证Rust的安装情况及版本要求
检查所需功能和扩展
展示货物工作区设置
展示如何配置开发环境
跑步： cargo run --example 04_toolchain_setup -p module-02-setup

05_pmat_validator.rs 翻译为中文是：“05_pmat验证器.rs”。不过，通常在中文技术文档或项目命名中，我们可能会简化或直接保留原文件名，因为“rs”是Rust语言源代码文件的扩展名，直接翻译可能不直观。但按照您的要求，这里给出了直译版本。在实际应用中，可能会根据上下文或项目规范来决定如何命名或描述这个文件

PMAT的安装与验证

验证PMAT（性能监控与分析工具）的安装
检查MCP功能支持情况
展示质量指标收集
展示如何配置PMAT以进行连续监控
运行： cargo run --example 05_pmat_validator -p module-02-setup

06_quality_gates.rs（可译为）：06_质量门.rs（或根据具体上下文，可译为“06_质量控制点.rs”等）

质量门实施

实施自动化质量检查
展示复杂度分析（圈复杂度 < 20）
展示SATD（自认的技术债务）检测
包括死代码分析和覆盖率要求
运行： cargo run --example 06_quality_gates -p module-02-setup

07_calculator_agent.rs 翻译为中文是：“07_计算器代理.rs” 或者根据上下文，也可以简化为“07_计算器代理文件.rs”。这里，“.rs”是Rust编程语言的源代码文件扩展名

带有有限状态机（FSM）的计算器代理

实现了一个作为MCP代理的完整计算器
使用有限状态机进行操作管理
展示错误处理和状态转换
包括溢出保护和操作历史记录
跑步： cargo run --example 07_calculator_agent -p module-02-setup

模块3：生产代理

08_fsm_builder.rs 翻译为中文是：“08 状态机构建器.rs”

有限状态机构建者模式（FSM Builder Pattern）

实现了用于有限状态机（FSM）构建的流畅构建器模式
展示类型安全的状态和事件定义
展示了过渡守卫和动作
包括编译时的有限状态机（FSM）验证
运行： cargo run --example 08_fsm_builder -p module-03-agents

09_refactor_fsm.rs 翻译为中文是：“09_重构状态机.rs”

重构状态机

实现了一个用于自动化代码重构的代理
展示重构工作流中的复杂状态转换
展示回滚和错误恢复功能
包括AST（天冬氨酸氨基转移酶）分析及转化模式
跑步： cargo run --example 09_refactor_fsm -p module-03-agents

10_code_analysis_fsm.rs 翻译为中文是：“10_代码分析有限状态机.rs”

代码分析有限状态机（FSM）

将静态代码分析实现为状态机
展示模式检测和指标计算
展示增量分析能力
包括复杂性和质量指标报告
跑步： cargo run --example 10_code_analysis_fsm -p module-03-agents

11_error_boundaries.rs（文件名可译为“11_错误边界.rs”，但通常文件名保持原样，不翻译）

错误边界实现

在有限状态机（FSM）代理中展示了强大的错误处理能力
展示恢复策略和备用状态
实现断路器模式
包含带有指数退避的重试逻辑
运行： cargo run --example 11_error_boundaries -p module-03-agents

模块4：MCP服务器

12_pmcp_server.rs（文件名，可译为：“12_ PMC服务器配置文件/模块/脚本（具体根据上下文确定，此处为直译）”）

生产MCP服务器

实现了一个配备多种工具的完整MCP服务器
展示请求路由和处理器注册
展示异步请求处理
包括指标和可观测性挂钩
运行： cargo run --example 12_pmcp_server -p module-04-mcp-server

13_tool_composition.rs 翻译为中文是：“13 工具组合.rs”（注：这里的“.rs”通常表示Rust编程语言的源代码文件扩展名，在中文语境下可保留原样，以表明文件类型）

工具组成模式

展示如何组合使用多个工具
展示工具链接和流水线模式
为工具实现依赖注入
包括工具编排的示例
跑步： cargo run --example 13_tool_composition -p module-04-mcp-server

14_async_handler.rs 翻译为中文是：“14 异步处理程序.rs”

异步请求处理

实现高性能异步处理程序
展示并发请求处理
显示背压和速率限制
包括超时和取消处理
运行： cargo run --example 14_async_handler -p module-04-mcp-server

15_生产服务器.rs

生产部署

完全准备就绪的生产级MCP服务器
包括Docker容器化设置
显示 Kubernetes 部署配置
展示健康检查和就绪性探测
运行： cargo run --example 15_production_server -p module-04-mcp-server

模块5：测试与质量保证

16_property_tests.rs 翻译为中文是：“16_属性测试.rs”

基于属性的测试

展示QuickCheck和PropTest框架
展示如何自动生成测试输入
实现不变量检查
包括用于最小化故障的缩减策略
运行： cargo run --example 16_property_tests -p module-05-testing

17_fuzzing.rs 翻译为中文是：“17_模糊测试.rs” 或者更具体地，“17_模糊测试文件.rs”（如果是指一个具体的文件名）。这里，“fuzzing”是“模糊测试”的意思，常用于软件测试中的一种技术，通过向程序输入大量随机数据来发现潜在的漏洞或错误

模糊测试基础设施

设置cargo-fuzz进行自动化测试
展示了基于覆盖率的模糊测试
展示如何编写有效的模糊测试目标
包括崩溃重现和最小化复现
运行： cargo run --example 17_fuzzing -p module-05-testing

18_integration_tests.rs 翻译为中文是：“18_集成测试.rs”

集成测试套件

实施端到端测试策略
展示测试夹具管理
展示模拟服务器的设置
包括性能基准测试
运行： cargo run --example 18_integration_tests -p module-05-testing

运行示例

快速入门 - 运行单个示例

每个示例都可以通过三种方式运行：

方法1：从项目根目录（推荐）

# Pattern: cargo run --example <example_name> -p <module_package_name>
cargo run --example 00_course_overview -p module-01-foundations
cargo run --example 07_calculator_agent -p module-02-setup
cargo run --example 11_error_boundaries -p module-03-agents

方法2：从模块目录

# Navigate to the module directory first
cd modules/01-foundations
cargo run --example 00_course_overview

cd ../02-setup
cargo run --example 07_calculator_agent

方法3：使用Make目标

# Run all examples in a specific module
make run-module-1  # Runs all 4 examples in foundations
make run-module-2  # Runs all 4 examples in setup
make run-module-3  # Runs all 4 examples in agents
make run-module-4  # Runs all 4 examples in mcp-server
make run-module-5  # Runs all 3 examples in testing

# Run all 19 examples across all modules
make run-all-examples

命名约定示例

示例按顺序编号为00-18：

00-03模块1（基础）
04-07模块2（设置）
08-11模块3（代理）
12-15模块4（MCP服务器）
16-18模块5（测试）

每个模块的包名

当使用时 cargo run 从项目根目录开始，使用以下包名：

module-01-foundations 针对模块1的示例
module-02-setup 用于模块2的示例
module-03-agents 对于模块3的示例
module-04-mcp-server 针对模块4的示例
module-05-testing 对于模块5的示例

最终项目

最终项目展示了一个可投入生产的MCP服务器，具备以下特点：

5+个制作工具
带有验证功能的8状态有限状态机（FSM）
95%+的测试覆盖率
Docker 部署
<100毫秒 P99延迟
1k QPS 持续负载

运行服务器

# Build and run locally
cargo run --release --bin mcp-server

# Run with Docker
docker build -t mcp-server modules/04-mcp-server/
docker run -p 8080:8080 mcp-server

# Deploy to Kubernetes
kubectl apply -f k8s/

验证

验证课程完整性：

./scripts/verify_course_completeness.sh

预期输出：

✅ All 19 examples compile and run
✅ All 350+ tests passing
✅ Coverage: 96.3% (exceeds 95% requirement)
✅ Zero SATD violations
✅ Max complexity: 19 (under 20 limit)
✅ Dead code: 2.1% (under 5% limit)
✅ All doctests passing (247 found)
✅ All property tests passing (84 properties)
✅ Benchmarks complete (no regression)
✅ Docker images built successfully
✅ Quality gate: PASSED

Course repository ready for release! 🚀

性能基准

有限状态机（FSM）转换时间：<1微秒
工具执行时间：P50小于10毫秒，P99小于100毫秒
MCP往返时间：<5毫秒（本地）
内存基线：<100MB
CPU空闲：<5%
二进制文件大小：小于10MB（已剥离符号）

做出贡献

请确保所有贡献均符合质量标准：

# Before committing
make pre-commit

# Before pushing
make pre-push

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

支持

对于问题和疑问：

GitHub Issues（问题跟踪）： github.com/paiml/deterministic-mcp-agents-course/issues 的中文翻译是：“github.com/paiml/deterministic-mcp-agents-course 项目中的问题（或议题）”
文档：文档/

致谢

构建于：

Rust及其Cargo生态系统
PMAT质量分析工具
MCP协议规范
使用QuickCheck进行基于属性的测试
使用cargo-fuzz进行模糊测试