fmeca

fmeca-mcp

fmeca-mcp 是一个以 MCP 服务形式提供的结构化 FMECA 引擎。你向它提供失效模式及描述这些模式的观测结果；它会推导严重度／概率评分，根据固定矩阵计算关键度，按照预防→检测→快速失效的原则跟踪缓解措施，并告知分析是否已准备好签核。任何 MCP 客户端（Claude Code、Cursor 或自定义编排器）都可通过标准协议驱动它。

面向 AI Agent： 若要为你的客户端安装此服务及其技能，请参阅 docs/AGENT-INSTALL.md。

什么是 FMECA

失效模式、影响与关键度分析是一种结构化的风险分级方法：列举事物可能发生的失效，评估每种失效的严重程度和发生概率，并对综合关键度进行排序，以便优先处理最严重的风险。随后逐层添加缓解措施，并重新评估剩余风险。fmeca-mcp 负责该流程的结构和计算；调用方负责领域判断。

设计原则：确定性、离线、不使用大模型提供的数字

该引擎是一个纯函数，输入为 (events in)，输出为 (criticality + residual + gaps + readiness out)。除仅追加的事件日志外，它不执行任何 I/O，不发起网络调用，也不运行模型。

关键在于，调用方绝不提供评分。 调用方（通常是大模型）负责模糊判断——命名失效模式、说明其原因和影响，并提出缓解措施——然后提供从固定目录中选取的观测结果（例如 data_loss、happens_in_normal_use）。内核通过锁定的证据→评分映射，将这些观测结果映射到严重度／概率等级，并根据固定且锁定的 S×P 矩阵读取关键度。模型负责提出建议；代码负责评分。由于关键度、剩余风险、状态和准备就绪度都是通过对事件日志进行折叠运算计算得出的——绝不存储，也绝不接受为输入——因此，同一分析始终会得出相同结果，任何模型都无法诱导矩阵给出更宽松的答案。

安装

npx（无需安装）

npx -y @matthew-cochran/fmeca

npm 启动器会下载匹配的发布二进制文件、验证其校验和、缓存并运行它。该软件包会安装两个命令别名：fmeca 和 fmeca-mcp，二者运行的是同一个启动器。将你的 MCP 客户端指向任一命令即可（参见 MCP 客户端配置）。

预构建二进制文件（无需 Rust、Cargo 或 Git）

# Linux / macOS
curl -fsSL https://github.com/praxec/fmeca/releases/latest/download/install.sh | sh

# Windows (PowerShell)
irm https://github.com/praxec/fmeca/releases/latest/download/install.ps1 | iex

安装程序会检测你的操作系统和 CPU 架构，下载匹配的发行版资源，将其 SHA-256 值与发行版的 checksums.sha256 进行验证，安全地解压，并将二进制文件原子地安装到用户本地的托管目录中（Linux/macOS 上为 $HOME/.local/bin，Windows 上为 %LOCALAPPDATA%\Programs\fmeca-mcp）。它不会从源代码编译；如果遇到不支持的操作系统或架构，会明确报错。

固定安装某个特定发行版，而非当前最新稳定版：

curl -fsSL https://github.com/praxec/fmeca/releases/latest/download/install.sh \
  | sh -s -- --version v0.1.0

也可以从指定发行版获取安装程序，例如 https://github.com/praxec/fmeca/releases/download/v0.1.0/install.sh。

安装程序脚本会与二进制文件一同作为发行版资源发布。

也可以直接下载归档文件。每个发行版都会发布 checksums.sha256 和机器可读的 release-manifest.json，其中列出了各个目标、资源、摘要、版本和源代码 SHA：

操作系统	架构	目标三元组	资源	构建支持	运行时冒烟测试
Linux	x86_64	x86_64-unknown-linux-gnu	fmeca-mcp-x86_64-unknown-linux-gnu.tar.gz	原生 CI	原生 CI
Linux	arm64	aarch64-unknown-linux-gnu	fmeca-mcp-aarch64-unknown-linux-gnu.tar.gz	原生 CI	原生 CI
macOS	x86_64	x86_64-apple-darwin	fmeca-mcp-x86_64-apple-darwin.tar.gz	原生 CI	原生 CI
macOS	Apple Silicon	aarch64-apple-darwin	fmeca-mcp-aarch64-apple-darwin.tar.gz	原生 CI	原生 CI
Windows	x86_64	x86_64-pc-windows-msvc	fmeca-mcp-x86_64-pc-windows-msvc.zip	原生 CI	原生 CI
Windows	arm64	aarch64-pc-windows-msvc	fmeca-mcp-aarch64-pc-windows-msvc.zip	原生 CI	原生 CI

“原生 CI”表示每个资源都在对应平台自己的运行器上构建，并通过 MCP initialize/tools/list 握手冒烟测试。不保证支持其他 CPU/操作系统组合；不支持的平台会被拒绝，而不会静默地进行交叉编译。

更新

重新运行安装程序即可更新。只会原子地替换托管安装目录中的二进制文件；应用状态和配置存放在该目录之外，绝不会被覆盖。状态存放位置请参阅配置。

Docker

docker run -i --rm ghcr.io/praxec/fmeca:0.1.0

挂载你的项目，以便将分析结果保存在项目的 .fmeca/ 文件夹中（如果不挂载，容器退出时状态会丢失）。即使 fmeca-mcp init 尚未创建该文件夹，FMECA_STATE_DIR 也会让服务使用该文件夹：

docker run -i --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work -e FMECA_STATE_DIR=/work/.fmeca -e OPENROUTER_API_KEY ghcr.io/praxec/fmeca:0.1.0

从源代码构建

cargo install fmeca-mcp

crate 发布到 crates.io 后，即可使用 cargo install。在此之前，请从检出目录运行 cargo build --release 进行构建。

MCP 客户端配置

它通过 stdio（标准传输方式）使用 MCP。像配置其他 MCP 服务一样，将其接入你的编辑器。Claude Code（.mcp.json）和 Copilot（.mcp.json）可以使用相同的条目（Cursor 需要 "type": "stdio"；请参阅 AGENT-INSTALL 中的对应部分）：

{
  "mcpServers": {
    "fmeca": {
      "command": "npx",
      "args": ["-y", "@matthew-cochran/fmeca"]
    }
  }
}

二进制文件使用 "command": "fmeca-mcp"（或其别名 "command": "fmeca"），并将 "args": [] 作为参数。Codex 使用 TOML：

[mcp_servers.fmeca]
command = "npx"
args = ["-y", "@matthew-cochran/fmeca"]
env_vars = ["OPENROUTER_API_KEY"]

所有客户端的配置以及每个客户端对应的 skills 安装说明（包括 Cursor 的 .cursor/mcp.json 条目）都在 docs/AGENT-INSTALL.md 中。密钥是可选的（只有 vet 会用到），且绝不会写入配置文件：如果客户端支持变量展开，请通过 "env": { "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}" } 传入；也可以让服务从环境中继承该变量。

工具概览

工具	功能
session.open	启动或恢复会话；可选择矩阵策略，并记录分析元数据（title、level、aspect、scope_paths、parent），这些内容在整个会话生命周期内固定不变。
append	添加失效模式（add_failure_mode）、添加缓解措施（add_mitigation），或重新评估现有失效模式（rescore）。set_mitigation_status 可将缓解措施状态改为 planned、implemented、verified 或 abandoned（verified 需要提供注释以外的证据）。set_failure_mode_disposition 可接受失效模式的剩余风险（需要审批人），或将其排除并标记为不可信（需要证据）；失效模式永远不会被删除。返回重新计算后的状态。
state.get	只读的会话视图：列出每种失效模式及其计算得出的严重性、剩余风险和状态。
risk.next	返回尚未缓解且严重性最高的失效模式，即接下来应处理的问题。
readiness.assess	就绪门槛：是否已降低所有高/中等级的剩余风险，并清除所有阻碍因素？
report.export	导出会话的完整 FMECA 表。
scoring.catalog	策略固定的观察项词汇表，即调用方可选用的 ID。
analyze	无状态的一次性分析：提交完整分析，获取完整的计算报告。无需会话，也不进行持久化。
session.list	列出状态目录中的所有分析（若项目中存在，则为项目的 .fmeca/），包含其元数据、状态计数（单独统计已排除的失效模式）、ready、ready_verified 和解决情况计数。可按 level、aspect、parent 过滤。无法重放的日志会连同错误一并列出。
vet	提供建议：通过 OpenRouter 向 Jev（需要 OPENROUTER_API_KEY）询问观察项、缓解措施、覆盖范围和就绪情况是否经得起检验，并在确定性门槛旁返回概率。绝不会写入或更改评分；没有密钥时会报告 vet_unavailable。
actions.suggest	只读。根据风险策略读取会话（或内联分析），并建议操作：为每种失效模式划分风险等级、评估证据可信度、给出处理意见、标记操作并作出签核结论。绝不会更改分析或日志。
policy.list	只读。列出内置策略预设和项目的 .fmeca/policies/ 文件，以及每项的名称、哈希值和类别。无法加载的项目文件会连同其 error 一并列出。

analyze 工具会复用与会话路径完全相同的内核计算，因此两者的结果绝不会出现偏差。

将分析保存在你的代码库中（.fmeca/）

fmeca-mcp init                 # at the project root: creates .fmeca/
git add .fmeca && git commit -m "chore: add .fmeca"
fmeca-mcp check --dir .fmeca   # in CI: replays every log, catches duplicate ids

从项目根目录启动服务（或设置 FMECA_STATE_DIR），它会在 .fmeca/ 中为每项分析保留一个日志，命名为 <aspect>-<level>。设置、合并行为、Docker 挂载以及每个级别对应的技能详见 docs/AGENT-INSTALL.md。

风险策略

风险策略会依据项目自己的风险等级读取分析，设定签核规则，并建议带标签的操作（设计、评审、测试、运维、流程、文档、安全）。系统会在你请求时计算结果，绝不会将其写入日志，因此同一项分析可以在多种策略下读取。fmeca 只提供建议，绝不执行操作。

预设包括：compat-0.1（默认；其签核结果与 readiness.assess 相同）、prototype、standard、business-critical、safety-critical 和 confidence-view。自定义策略采用 TOML 文件，存放于 .fmeca/policies/<name>.toml，其优先级高于预设。

fmeca-mcp policy list                                   # presets and project files
fmeca-mcp policy validate .fmeca/policies/team.toml     # ok <name> <hash>, or the error
fmeca-mcp suggest checkout-implementation --policy standard --format markdown

当策略的签核通过时，suggest 以 0 退出；不通过时以 1 退出（可用于 CI）；用法或策略出错时以 2 退出。Agent 使用 actions.suggest 和 policy.list 工具调用相同功能。模型、所有预设和操作目录详见 docs/policies.md。

配置

变量	默认值	作用
FMECA_STATE_DIR	最近的 .fmeca/，否则 $XDG_DATA_HOME/fmeca-mcp（或 $HOME/.local/share/fmeca-mcp），否则 ./fmeca-state	每个会话的日志存放位置。
OPENROUTER_API_KEY	未设置	启用可选的 vet 工具。仅从环境中读取。
FMECA_JEV_MODEL	typesafe/jev-1.13	vet 使用的模型。
FMECA_JEV_TIMEOUT_SECS	30	vet 请求超时时间，单位为秒。

矩阵策略

关键性矩阵是封闭的、驻留于代码中的策略，在 session.open 时选择（并在会话的整个生命周期内固定）。每种策略都带有一套 锁定的 S×P 矩阵和自己的评分目录：

策略	量表	说明
qualitative3x3	低 / 中 / 高	默认的 3×3 定性矩阵。
nasa8004_5x5	5×5 后果 × 可能性	NASA GSFC-HDBK-8004 风险矩阵。

调用方选择策略，但不会编辑策略的单元格。

将 fmeca 用作库

内核是一个纯 Rust 库，与 MCP 无关。无状态的 analyze 函数接收一种策略和一批故障模式，并返回完整的计算报告：

use fmeca::{
    analyze, AnalyzeInput, AnalyzeMitigation, Domain, EntityRef, MatrixStrategy, MitigationKind,
};

let failure_modes = vec![AnalyzeInput {
    id: "fm-1".into(),
    component: EntityRef::new("checkout-service"),
    description: "Payment double-charge on retry".into(),
    cause: Some("Non-idempotent charge endpoint".into()),
    effect: Some("Customer billed twice".into()),
    domain: Domain::Runtime,
    scope: None,
    // Observations, not scores — the kernel derives severity/probability.
    severity_observations: vec!["data_loss".into()],
    probability_observations: vec!["happens_in_normal_use".into()],
    mitigations: vec![AnalyzeMitigation {
        id: "m-1".into(),
        kind: MitigationKind::Prevention,
        description: "Idempotency key on the charge endpoint".into(),
        residual_severity_observations: vec![],
        residual_probability_observations: vec!["rare_edge_case".into()],
    }],
}];

let report = analyze(MatrixStrategy::default(), &failure_modes).unwrap();
println!("risk ranking: {:?}", report.risk_ranking);
println!("ready: {} blockers: {:?}", report.ready, report.blockers);
// report.failure_modes carries per-FM criticality / residual_criticality /
// standing / response_class / issues.

对于长期、多轮的分析，请通过 StateStore 使用 fmeca::Engine（提供了 FilesystemStore），它会持久化只追加的事件日志，并重放该日志以计算状态。请参阅 API 文档。

开发

cargo build
cargo test
cargo fmt --all
cargo clippy --all-targets -- -D warnings

skills/ 下的 Agent 技能会在构建时嵌入二进制文件中。添加或删除技能后，本地增量构建不会检测到更改；请运行 touch crates/fmeca-mcp/build.rs 并重新构建。

CI 会在 Linux/macOS/Windows 上运行构建和测试，还会运行 rustfmt 和 clippy （警告视为错误）。提交拉取请求前，请确保这些检查在本地均能通过。

与 Praxec 搭配使用

这是由 Praxec packs 使用的 MCP 工具。要启动并运行该工具及使用它的工作流 pack，最简单的方式是一键设置：

curl -fsSL https://raw.githubusercontent.com/praxec/packs/main/setup.sh | bash

请参阅 pack 注册表，了解此工具的提供方坐标 （容器镜像 / 发布二进制文件）以及依赖它的 pack。

许可证

Apache-2.0。