mirdan (S Corkum)

米尔丹

AI代码质量编排器-- 节省30-45%的付费AI编码代币 通过运行一个处理分流、linting、类型检查、测试运行和验证的本地智能层，像Claude Opus这样昂贵的模型将重点放在编写代码上。

](https://pypi.org/project/mirdan/)  

uv tool install mirdan                  # Install mirdan
mirdan llm setup                        # Auto-installs backend, downloads model, configures
mirdan init --claude-code               # or --cursor
# Done. Quality enforcement + local intelligence is now automatic.

使用 克劳德代码, 光标IDE，以及 光标CLI。在16GB笔记本电脑上运行。一切都是本地的。

______________________________________________________________________

简要驱动计划管道（2.1.0中新增）

Mirdan 2.1.0增加了一个 简要的初步计划工作流程 这改变了前沿模型 令牌上游支出（简要编写），以便管道的其余部分可以运行 更便宜的型号。一个工件，三层，跨IDE奇偶校验。

/brief                       → author structured brief in docs/briefs/
/plan --brief 
               → three-layer plan (epic → stories → subtasks)
/plan-verify 
           → mechanical coverage check via local Gemma 4
/plan-review --stakes high 
  → escape hatch: judgment review on shared rubric
/plan-execute 
          → dispatch subtasks to Haiku (CC) / local LLM (Cursor)

示范例题

# 1. Author a brief (required before /plan runs)
/brief add-passkey-auth "Add passkey authentication for web sign-in"
# → prompts for Outcome, Users & Scenarios, Business ACs, Constraints, Out of Scope
# → writes docs/briefs/add-passkey-auth.md
# → auto-stores to enyal with content_type="brief"

# 2. Generate the plan (brief constraints merge into quality_requirements)
/plan --brief docs/briefs/add-passkey-auth.md
# → writes docs/plans/add-passkey-auth.md with frontmatter brief: docs/briefs/add-passkey-auth.md

# 3. Verify coverage mechanically (local Gemma 4, ≤30s on mid-tier hardware)
/plan-verify docs/plans/add-passkey-auth.md
# → ## Verification report with unmapped_acs, missing_grounding, ...

# 4. Execute (Claude Code dispatches to Haiku subagents; Cursor A/B routing)
/plan-execute docs/plans/add-passkey-auth.md
# → runs /plan-verify as pre-flight, then walks subtasks in dependency order

MCP工具参考

什么 /plan-verify 实际捕获量（基于证据）

机械测试结果——在任何硬件层都是可靠的，不需要LLM：

• phantom_files --子任务的 **File:** 指向一条不存在的路径；为了 NEW: 文件，父目录缺失
• dependency_errors — **Depends on:** 引用不在计划中的子任务ID；或循环依赖图
• vague_cross_references --“如前所述”、“像步骤N一样”、“以前”——廉价执行者无法解决的短语
• missing_grounding --子任务缺少6个所需接地场中的任何一个
• out_of_scope_violations --简要说明计划正文中出现的范围外项目
• invest_failures --缺少INVEST结构领域的故事

证据： tests/evidence/ --对种子缺陷进行100%检测，对干净计划进行0%误报，在20次运行中具有确定性。运行时间：在18个历史计划中，中位数为1.45毫秒，最大值为11.87毫秒。

语义发现——需要BRAIN层（31B+）局部模型：

• unmapped_acs --LLM评委信心≥0.6的简短商业AC未映射到任何故事AC

语义检查是 自动跳过 如果没有BRAIN层模型可用。Gemma 4 E2B/E4B是FAST级别，对于此任务没有区别——请参阅 docs/briefs/mirdan-brief-driven-pipeline.md 建立这一点的牙齿测试数据的“语义路径硬件要求”。

参考实施

docs/briefs/mirdan-brief-driven-pipeline.md 和 docs/plans/mirdan-brief-driven-pipeline.md 项目根中有 2.1.0版本自己的简报和计划对——在开发过程中被狗吃掉了。

2.1.0退休

/debug, /review, /quality, /gate, /scan 船作为废弃的残羹剩饭。 看 CHANGELOG.md 2.1.0部分为迁移表。2.2.0中的完全删除。

______________________________________________________________________

本地智能层（2.0中的新功能）

Mirdan 2.0将日常工作转移到您机器上运行的小型本地模型（Gemma 4）上。付费模式只专注于复杂的推理和编写代码。

在编码之前：

• 分诊 --对任务进行分类。琐碎的任务（修复导入、格式化文件）永远不会影响付费模式。零代币支出。
• 研究 --在本地收集代码库上下文、库文档和项目约定（仅限64GB+）。

编码后：

• 检查跑步者 --在本地运行ruff、mypy、pytest。LLM解析输出，自动修复lint，只报告复杂的故障。
• 智能验证 --64条质量规则+LLM假阳性过滤、根本原因分组和修复建议。
• 自动修正 — mirdan check --smart --fix 使用验证应用LLM生成的搜索/替换修复。

快速设置

mirdan llm setup              # Detects hardware, installs backend, downloads model, configures
mirdan init --claude-code     # or --cursor
mirdan llm status             # Verify it's working

一切都在本地运行。没有远程服务器。没有数据离开你的机器。

______________________________________________________________________

为什么是米尔丹？

AI编码助手生成代码很快，但没有护栏 污水：硬编码的秘密、SQL注入、占位符函数、幻觉导入、裸露的异常块，以及看似正确但在生产中失败的代码。

Mirdan通过在两点拦截你的AI工作流程来解决这个问题：

1. 编码前 — enhance_prompt 通过质量要求、安全约束和特定于框架的标准丰富您的任务，以便AI从一开始就生成更好的代码
2. 编码后 — validate_code_quality 抓住漏洞：涵盖安全漏洞、特定于AI的反模式和语言最佳实践的64条规则

一旦安装，它就会通过IDE挂钩隐形运行。你只是正常地编码。

它捕获了什么

以下是mirdan在典型AI生成代码的单个函数上标记的内容：

API_KEY = "sk-proj-abc123456789"           # SEC001: hardcoded API key
def get_users(user_id):
    query = f"SELECT * FROM users WHERE id={user_id}"  # SEC005 + AI008: SQL injection
    result = eval(user_input)              # PY001: code injection via eval()
    data = requests.get(url, verify=False) # SEC007: SSL verification disabled
    try:
        process(data)
    except:                                # PY003: bare except
        pass

结果： 得分0.0/1.0，6个错误，3个警告。通过自动修复，mirdan会自动解决其中的5个问题。

它为你的提示增加了什么

当你要求人工智能助手“在FastAPI中使用JWT令牌创建用户身份验证端点”时，mirdan enhance_prompt 检测到这会触及安全并注入：

• 框架标准： “使用 Depends() 和 Annotated 用于类型安全依赖注入”
• 安全约束： “检查是否没有硬编码机密或凭据”
• 质量要求： “对所有请求体和响应模式使用Pydantic模型”
• 验证步骤： “确保错误处理涵盖所有异步操作”

AI会得到结构化的指导，而不是简单的提示，在第一次尝试时就能生成更好的代码。

______________________________________________________________________

快速开始

安装

uv tool install mirdan                   # Install mirdan
mirdan llm setup                         # Auto-installs LLM backend + downloads model

# Optional extras:
uv tool install 'mirdan[ast]'            # + tree-sitter for TS/JS AST analysis
uv tool install 'mirdan[enterprise]'     # + truststore for corporate SSL inspection

# Upgrade:
uv tool upgrade mirdan

# Or with pip:
pip install mirdan

设置IDE

mirdan init --claude-code    # Claude Code: hooks, rules, skills, agents
mirdan init --cursor         # Cursor: hooks, rules, AGENTS.md, BUGBOT.md
mirdan init --all            # Both IDEs

这将生成所有内容——MCP服务器配置、质量挂钩、规则文件和代理定义。启用LLM时，钩子还配置本地分流和检查运行器。初始化后，IDE会自动：

1. 在编码任务之前，用质量要求丰富提示
2. 每次编辑后根据安全和质量规则验证代码
3. 在任务完成之前运行最终质量门

从命令行使用

mirdan validate --file src/auth.py     # Validate a file
mirdan validate --staged               # Validate git staged changes
mirdan fix --file src/auth.py          # Auto-fix violations (pattern-based)
mirdan check --smart                   # Run lint + typecheck + test with LLM analysis
mirdan check --smart --fix src/        # Run checks AND auto-fix with local LLM
mirdan gate                            # CI/CD quality gate (exit 0 or 1)
mirdan scan --dependencies             # Check deps for known CVEs
mirdan scan --directory src/           # Discover codebase conventions
mirdan llm setup                       # Configure local LLM
mirdan llm status                      # Show LLM health, model, hardware
mirdan llm metrics                     # Token savings dashboard

______________________________________________________________________

运作原理

米尔丹是一个 MCP服务器 --它连接到AI编码助手（Claude Code、Cursor、Claude Desktop或任何MCP客户端），并提供质量执行工具。

┌──────────────────────────────────────────────────┐
│  Your AI Assistant (Claude Code / Cursor / etc)  │
│                                                  │
│  1. You type a coding task                       │
│  2. Hook triages task via local LLM ────┐        │
│  3. AI generates code with guidance     │        │
│  4. Hook runs lint/typecheck/test ◄─────┘        │
│  5. AI fixes only complex issues                 │
│  6. Quality gate passes → task complete          │
└──────────────────────────────────────────────────┘
         │                        ▲
         ▼                        │
┌──────────────────────────────────────────────────┐
│  Mirdan MCP Server + Local Intelligence Layer    │
│                                                  │
│  MCP Tools (unchanged):                          │
│  enhance_prompt         → Quality requirements   │
│  validate_code_quality  → 64 rules + LLM enrich │
│  validate_quick         → Fast security checks   │
│  get_quality_standards  → Language/framework ref  │
│  get_quality_trends     → Historical analysis    │
│  scan_dependencies      → CVE detection (OSV)    │
│  scan_conventions       → Convention discovery   │
│                                                  │
│  Local LLM (Gemma 4, runs on your machine):      │
│  Triage          → Classify tasks, save tokens   │
│  Check Runner    → Run ruff/mypy/pytest locally  │
│  Smart Validator → FP filtering, root causes     │
│  Auto-Fix        → Search/replace code fixes     │
│  HTTP Sidecar    →  results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

预提交钩子

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: mirdan
        name: mirdan quality gate
        entry: mirdan validate --staged --quick
        language: system
        types: [python]

质量徽章

mirdan export --format badge > .mirdan/badge.json

______________________________________________________________________

配置

mirdan init 生成 .mirdan/config.yaml.关键部分：

version: "1.0"

project:
  name: "MyApp"
  primary_language: "python"
  frameworks: ["fastapi", "react"]

# Quality enforcement levels
quality:
  security: "strict"           # strict|moderate|permissive
  architecture: "moderate"
  documentation: "moderate"
  testing: "strict"

# Or use a named profile (overrides quality section)
quality_profile: "default"

# Semantic validation and dependency scanning
semantic:
  enabled: true
  analysis_protocol: "security"  # none|security|comprehensive

dependencies:
  enabled: true
  osv_cache_ttl: 86400           # 24 hours
  scan_on_gate: true
  fail_on_severity: "high"       # critical|high|medium|low|none

# Score thresholds
thresholds:
  severity_error_weight: 0.25
  severity_warning_weight: 0.08
  arch_max_function_length: 30
  arch_max_file_length: 300
  # Per-file threshold overrides (glob patterns)
  file_overrides:
    - pattern: "tests/**"
      arch_max_function_length: 60
    - pattern: "scripts/**"
      arch_max_file_length: 500

# Hook behavior
hooks:
  enabled_events: ["PreToolUse", "PostToolUse", "Stop"]
  quick_validate_timeout: 5000
  auto_fix_suggestions: true

LLM配置进入 .mirdan.yaml （作者： mirdan llm setup):

llm:
  enabled: true
  backend: llamacpp                # llamacpp (default) or ollama
  model_keep_alive: 5m             # Unload model after idle (saves RAM)

查看完整 LLM配置参考 或奔跑 mirdan llm setup 自动配置。

______________________________________________________________________

高级功能

基于AST的验证

Python规则PY001–PY004通过 ast 模块，消除字符串中eval/exec的误报、注释中的空异常等。另外两条AST规则：

• 第014页 （死导入）--检测未使用的导入，尊重 TYPE_CHECKING 阻碍， __all__，以及别名导入
• 2015年4月 （无法访问的代码）--检测以下代码 return/raise/break/continue，跳过 finally 块

对于Types/JavaScript，安装可选 ast 额外启用树保姆解析：

uv tool install 'mirdan[ast]'

这提供了精确的函数长度、嵌套深度和缺失返回类型检测，而不是正则表达式近似。当未安装树保姆时，优雅地回退到正则表达式。

完整文件差异验证

验证差异时（通过钩子或 validate_code_quality 和 input_type="diff")，mirdan在可用时从磁盘读取完整文件。这允许进行需要完整文件上下文的架构检查（函数长度、嵌套深度）。违规仅过滤到更改的行，文件范围规则（文件太长）从差异结果中排除。

自适应文件路径阈值

使用以下命令覆盖特定文件模式的阈值 file_overrides 在您的配置中：

thresholds:
  arch_max_function_length: 30
  file_overrides:
    - pattern: "tests/**"
      arch_max_function_length: 60    # Tests can be longer
    - pattern: "migrations/**"
      arch_max_file_length: 1000      # Migration files are naturally long

模式使用glob语法，并与文件路径匹配。覆盖仅替换它们指定的字段——所有其他阈值都继承自基本配置。

会议发现

扫描您的代码库以发现隐式模式并生成自定义规则：

mirdan init --learn              # During init
mirdan scan --directory src/     # Standalone

发现命名模式、导入样式、文档字符串约定和重复模式。生成 .mirdan/rules/conventions.yaml 根据项目特定规则。

依赖漏洞扫描

检查与的依赖关系 OSV数据库 （免费，不需要API密钥）：

mirdan scan --dependencies                # Standalone scan
mirdan gate --include-dependencies        # Quality gate + vuln check

支持PyPI、npm、crates.io、Go和Maven。结果将缓存24小时。导入包中的漏洞会在代码验证期间触发SEC014违规。

语义验证

validate_code_quality 回报 semantic_checks --由代码模式（SQL查询、身份验证逻辑、加密操作、文件I/O）生成的有针对性的审查问题。这些指导人工智能调查具体问题，而不是进行浅层模式匹配。对于安全关键代码 analysis_protocol 提供结构化的深度分析步骤。

质量预测

get_quality_trends 分析验证历史以跟踪随时间变化的分数，预测轨迹，检测会话之间的回归，并计算通过率。

会话跟踪和反馈循环

每 enhance_prompt 呼叫返回a session_id。将其传递给 validate_code_quality 在整个任务生命周期中跟踪质量。将其传递回 enhance_prompt 在下一次呼叫关闭反馈循环时：

enhance_prompt(task)                   → session_id, enhanced_prompt
  ↓ implement code
validate_code_quality(code, session_id) → violations, session_context
  ↓ fix issues, iterate
enhance_prompt(task, session_id=...)   → persistent violations injected
                                          as priority quality requirements

当违规在两个或多个连续验证中重复出现时，mirdan会将其作为优先级显示出来 quality_requirement 在下一个增强的提示中，确保人工智能解决根本原因，而不是在破碎的基础上添加新代码。

多智能体协调

钩子配置为自主代理（光标背景代理、克劳德代码子代理）提供了护栏，确保了在没有人为监督的情况下执行质量。

跨项目情报

当与 恩亚尔 （持久知识图MCP），mirdan将项目约定存储为知识条目，并在项目之间调用模式。

升级

uv tool upgrade mirdan     # Upgrade to latest version
mirdan init --upgrade      # Regenerate IDE integration files

uv tool upgrade 更新包。 mirdan init --upgrade 将新配置字段合并到现有配置字段中 .mirdan/config.yaml，重新生成集成文件，并保留您的自定义设置。

______________________________________________________________________

MCP工具参考

enhance_prompt

编码任务的入口点。用质量要求、安全约束和工具建议丰富提示。

Parameters:
  prompt (required)     — The coding task description
  task_type             — generation|refactor|debug|review|test|planning|auto
  context_level         — minimal|auto|comprehensive
  max_tokens            — Token budget (0=unlimited)
  model_tier            — auto|opus|sonnet|haiku
  session_id            — Resume an existing session to thread validation
                          feedback into this prompt. Persistent violations
                          from prior validate_code_quality calls are injected
                          as priority quality requirements.

Returns:
  enhanced_prompt       — Enriched prompt with quality guidance
  detected_language     — Primary language detected
  detected_frameworks   — Frameworks to query docs for
  task_type             — Primary detected task type
  task_types            — All detected task types (compound detection). A
                          prompt like "add tests for the new feature" returns
                          ["test", "generation"] and unions verification steps
                          from both types.
  touches_security      — Whether task involves security-sensitive code
  quality_requirements  — Constraints to follow during implementation
  verification_steps    — Checklist before marking complete. Compressed to a
                          single re-validation step when a prior session passed,
                          reducing context waste on iterative work.
  tool_recommendations  — Which MCPs to call for context. Session-aware:
                          targets enyal recall to failure patterns on re-calls
                          with errors; suppresses redundant recalls after a pass.

validate_code_quality

出口门——根据质量标准验证代码。返回分数、违规和语义审查问题。

Parameters:
  code (required)       — Code to validate
  language              — python|typescript|javascript|rust|go|java|auto
  check_security        — Enable security rules (default: true)
  check_architecture    — Enable architecture rules (default: true)
  check_style           — Enable style rules (default: true)
  severity_threshold    — error|warning|info
  input_type            — code|diff|compare
  session_id            — Session ID from enhance_prompt

Returns:
  passed                — Whether validation passed
  score                 — Quality score (0.0–1.0)
  violations            — List of rule violations with details. Each violation
                          includes verifiable: false when the check is
                          pattern-based (AI001–AI008) rather than AST-verified,
                          so the AI knows to confirm semantically before fixing.
  semantic_checks       — Targeted review questions from code patterns
  summary               — Human-readable summary

validate_quick

钩子集成的快速安全验证（\<500ms）。运行SEC001–SEC014、AI001和AI008。

get_quality_标准

查找语言/框架组合的质量标准。

get_quality_trends

验证历史中的质量分数趋势和预测。

扫描依赖性

通过OSV数据库扫描项目依赖关系以查找已知漏洞。

scan_惯例

发现隐式代码库约定并生成自定义规则。

______________________________________________________________________

CLI 参考

______________________________________________________________________

故障排除

服务器未连接

1. 检查uvx是否可用： uvx --version
2. 手动测试服务器： uvx mirdan （应该开始时没有错误）
3. 检查克劳德代码中的状态： /mcp

调试日志记录

{
  "mcpServers": {
    "mirdan": {
      "command": "uvx",
      "args": ["mirdan"],
      "env": { "FASTMCP_DEBUG": "true" }
    }
  }
}

常见问题

______________________________________________________________________

发展

git clone https://github.com/S-Corkum/mirdan.git
cd mirdan
uv sync --all-extras         # Includes tree-sitter for TS/JS AST
uv run pytest                # 3050+ tests
uv run mirdan                # Run server locally

______________________________________________________________________

许可证

麻省理工学院