MCP代理工具包

Name: MCP代理工具包
Author: paiml

作者：paiml103 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

PMAT - 实用人工智能实验室多语言代理工具包

零配置AI上下文生成适用于任何代码库。分析17种以上编程语言的代码质量、复杂性和技术债务，采用极端质量控制和丰田方式标准。

📖 https://paiml.github.io/pmat-book/ - 完整文档、教程和指南

快速开始

安装

# Rust（推荐）
cargo install pmat

# macOS/Linux
brew install pmat

# Windows
choco install pmat

# npm（全局）
npm install -g pmat-agent

基本用法

# 分析代码库并生成AI可用上下文
pmat context

# 分析复杂性
pmat analyze complexity

# 评估技术债务（从A+到F）
pmat analyze tdg

# 评分仓库健康（0-110分）
pmat repo-score .              # 快速：仅扫描HEAD
pmat repo-score . --deep       # 彻底：扫描整个git历史

# 查找自我承认的技术债务
pmat analyze satd

# 测试套件质量（变异测试）
pmat mutate --target src/

Git钩子设置

安装预提交钩子以自动执行质量控制：

# 安装git钩子（bashrs质量检查，pmat-book验证）
pmat hooks install

# 检查钩子状态
pmat hooks status

# 干运行查看将要检查的内容
pmat hooks install --dry-run

钩子强制执行：

Bash/Makefile安全性（bashrs代码检查）
pmat-book验证（多语言示例）
文档准确性（零幻觉）

功能

17种以上语言：Rust, TypeScript, Python, Go, Java, C/C++, Ruby, PHP, Swift, Kotlin等
AI准备上下文：为Claude, GPT和其他LLMs生成深度上下文
技术债务评分（TDG）：A+到F评分，基于6个正交指标
仓库健康评分✨新功能：定量评估（0-110分），涵盖6个类别及额外特性
Rust项目评分（v2.0）✨新功能：基于证据的Rust质量评分（0-211分），集成CI/CD
工作流提示✨新功能：11个预配置AI提示，强制执行极端TDD和丰田方式原则
Git-提交关联：跟踪特定提交的TDG评分，进行质量考古
语义代码搜索：通过混合搜索实现自然语言代码发现
质量门控：预提交钩子、CI/CD集成、变异测试
MCP集成：19种工具支持Claude Code, Cline及其他MCP客户端
零配置：开箱即用，适用于任何代码库

文档

📖 PMAT手册 - 完整指南，含教程

关键章节：

示例

# 为Claude/GPT生成上下文
pmat context --output context.md --format llm-optimized

# 分析TypeScript项目
pmat analyze complexity --language typescript

# 技术债务评分，包括组件
pmat analyze tdg --include-components

# 语义搜索（自然语言）
pmat embed sync ./src
pmat semantic search "错误处理模式"

# 验证文档中的幻觉
pmat validate-readme --targets README.md

工作流提示（v2.194.0+）

预配置AI工作流提示，强制执行极端TDD和丰田方式质量原则。适合传递给Claude Code、ChatGPT或其他AI助手。

# 列出所有可用提示
pmat prompt --list

# 显示特定提示（YAML格式）
pmat prompt code-coverage

# 获取用于AI助手的提示文本
pmat prompt debug --format text | pbcopy

# JSON格式，供程序化使用
pmat prompt quality-enforcement --format json

# 自定义非Rust项目
pmat prompt code-coverage \
  --set TEST_CMD="pytest" \
  --set COVERAGE_CMD="pytest --cov"

# 保存到文件
pmat prompt continue -o workflow.yaml

可用提示（共11个）：

关键优先级：

code-coverage - 使用极端TDD强制85%以上的覆盖率
debug - 五问法根本原因分析
quality-enforcement - 运行所有质量门控（12个门控）
security-audit - 安全分析和修复

高优先级：

continue - 使用极端TDD继续下一步最佳操作
assert-cmd-testing - 验证CLI测试覆盖
mutation-testing - 在弱代码上运行变异测试
performance-optimization - 加快编译和测试速度
refactor-hotspots - 重构高TDG代码

中等优先级：

clean-repo-cruft - 移除临时文件
documentation - 更新和验证文档

关键特性：

丰田方式原则（自働化、安灯绳、五问法）
多语言支持的变量替换
质量门控和时间限制
零容忍政策
简短别名：pmat p --list

文档： 工作流提示指南

变异测试

通过引入代码变异并检查测试是否检测到这些变异来评估测试套件的质量。

# 基本变异测试
pmat mutate --target src/lib.rs

# 带有质量门控（得分低于85%时失败）
pmat mutate --target src/ --threshold 85

# 仅失败（CI/CD优化）
pmat mutate --target src/ --failures-only

# JSON输出，便于集成
pmat mutate --target src/ --output-format json > results.json

变异分数 = (被杀死的变异体 / 总有效变异体) × 100%

支持的语言： Rust, Python, TypeScript, JavaScript, Go, C++

关键特性：

多语言变异操作符（算术、比较、逻辑、边界）
CI/CD集成（GitHub Actions, GitLab CI, Jenkins）
性能优化（并行执行，差异测试）
带可配置阈值的质量门控

文档：

用户指南 - 完整指南，含示例
API参考 - 所有CLI标志和选项
最佳实践 - 团队采纳策略
CI/CD集成 - GitHub Actions, GitLab CI, Jenkins

示例项目：

Rust示例 - 8个函数，8个测试，约90%变异分数
Python示例 - 8个函数，24个测试，全面覆盖
TypeScript示例 - 8个函数，24个测试，Jest集成

TDG强制系统（v2.180.0+）

零退步质量强制贯穿本地开发、git工作流程和CI/CD管道。

快速开始

# 1. 创建质量基线
pmat tdg baseline create --output .pmat/tdg-baseline.json --path .

# 2. 安装git钩子（可选）
pmat hooks install --tdg-enforcement

# 3. 检查退步
pmat tdg check-regression \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --max-score-drop 5.0 \
  --fail-on-regression

# 4. 强制新代码的质量标准
pmat tdg check-quality \
  --path . \
  --min-grade B+ \
  --new-files-only \
  --fail-on-violation

特性

基线系统：

基于Blake3内容哈希的重复数据删除
整个项目范围的质量快照
差异检测（改进、退步、未变文件）

质量门控：

退步检测（防止质量下降）
最低等级强制（确保新代码质量）
语言特定阈值

Git钩子：

预提交质量检查
提交后基线更新
可配置强制模式（严格、警告、禁用）

CI/CD模板：

GitHub Actions工作流
GitLab CI流水线
Jenkins声明式流水线

配置

创建.pmat/tdg-rules.toml：

[quality_gates]
rust_min_grade = "A"
python_min_grade = "B+"
max_score_drop = 5.0
mode = "strict"  # 严格、警告或禁用

[baseline]
baseline_path = ".pmat/tdg-baseline.json"
auto_update_on_main = true

CI/CD集成

GitHub Actions：

cp templates/ci/github-actions-tdg.yml .github/workflows/tdg-quality.yml

GitLab CI：

cp templates/ci/gitlab-ci-tdg.yml .gitlab-ci.yml

Jenkins：

cp templates/ci/Jenkinsfile-tdg Jenkinsfile

参见完整指南： docs/guides/ci-cd-tdg-integration.md

Rust项目评分v2.0（新功能）

基于证据的Rust项目质量评分（0-211分），灵感来自顶级项目（tokio, serde, clap, syn, regex），学术基础来自15篇以上同行评审论文。

快速开始

# 快速模式分析（约3分钟）
pmat rust-project-score

# 全面模式，带综合检查（约10-15分钟）
pmat rust-project-score --full

# 指定项目路径，输出JSON
pmat rust-project-score --path /path/to/rust/project --format json

# Markdown报告，用于文档
pmat rust-project-score --verbose --format markdown --output SCORE.md

评分类别（总211分）

Rust工具与CI/CD（130分）
- Clippy（分层：正确性 > 可疑 > 严谨）：10分
- Rustfmt合规性：5分
- cargo-audit（基于风险评分）：7分
- cargo-deny策略执行：3分
- 工作区级别代码检查：12分
- CI/CD集成（多平台，工作流，构建自动化）：37分
- 高级元数据（docs.rs，工作区，发布自动化）：35分
- MSRV追踪：10分
- 发布配置优化：11分
代码质量（26分）
- 圆周复杂度（≤20）：3分
- 不安全代码文档：9分
- 变异测试（≥80%）：8分
- 构建时间（<5分钟）：4分
- 死代码检测：2分
测试卓越（20分）
- 覆盖率（≥85%）：8分
- 集成测试：4分
- 文档测试：3分
- 变异覆盖：5分
文档（15分）
- Rustdoc覆盖率：7分
- README质量：5分
- 维护变更日志：3分
性能与基准测试（10分）
- Criterion基准测试：5分
- CI基准测试工作流：3分
- 自定义测试框架：2分
依赖健康（12分）
- 依赖项数量：5分
- 特性标志：4分
- 树修剪：3分
形式验证（8分 - 额外类别）

示例输出

🦀  Rust项目评分v2.0

📌  概要
  得分：100.5/211
  百分比：47.6%
  等级：B

📂  类别
  ✅ Rust工具与CI/CD：56.0/130（43.1%）
  ⚠️  代码质量：20.0/26（76.9%）
  ❌ 测试卓越：5.5/20（27.5%）
  ...

💡  建议
  • 运行 'cargo clippy --fix' 自动修复警告
  • 在Cargo.toml中添加工作区级别代码检查
  • 创建 .github/workflows 以实现多平台CI
  • 配置docs.rs元数据以改善文档
  ...

学术基础

15篇以上同行评审参考文献（IEEE, ACM, arXiv 2013-2025）：

复杂度权重减少（8→3分）：无bug相关性（arXiv 2204）
不安全代码强调（6→9分）：Rust内存安全关键
变异测试（5→8分）：测试质量验证（ICST 2024）
CI/CD集成：更快的发布（Hilton 2016 ASE）
构建时间影响：开发者生产力（Beller 2017 MSR）
工作区优势：较少冲突（ICSE 2024）

CI/CD集成

# .github/workflows/rust-quality.yml
name: Rust质量评分
on: [push, pull_request]

jobs:
  rust-score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install pmat
      - run: pmat rust-project-score --format json --output score.json
      - name: 检查最低得分
        run: |
          SCORE=$(jq '.total_earned' score.json)
          if (( $(echo "$SCORE < 80" | bc -l) )); then
            echo "得分 $SCORE 低于阈值"
            exit 1
          fi

快速模式 vs 全面模式

快速模式（默认，约3分钟）：

跳过：clippy, 变异测试, 构建时间测量
提供：跳过的检查适度信用
使用场景：快速CI检查，开发反馈

全面模式（--full，约10-15分钟）：

运行：所有检查全面
提供：基于证据，同行评审评分
使用场景：发布验证，全面审计

文档

规范：docs/specifications/learn-from-rust-giants-spec.md
实施状态：docs/implementation-status-rust-project-score.md
CLAUDE.md：详尽使用指南，超过200行

Git-提交关联（v2.179.0+）

在特定git提交处跟踪技术债务评分（TDG）分数，用于“质量考古”工作流程。

# 带git上下文分析
pmat tdg server/src/lib.rs --with-git-context

# 查询特定提交
pmat tdg history --commit v2.178.0

# 自参考以来的历史
pmat tdg history --since HEAD~10

# 提交范围
pmat tdg history --range v2.177.0..v2.178.0

# 按文件过滤
pmat tdg history --path server/src/lib.rs --since HEAD~5

# 脚本输出JSON
pmat tdg history --commit 60125a0 --format json
``