crossmatrix

crossmatrix

多维质量屋（QFD）——用于结构化权衡与需求分析的跨维度关系矩阵。一个 Rust 工作区：crossmatrix（引擎）+ crossmatrix-mcp（MCP 服务）。属于 Praxec。

安装

npm / npx（推荐用于 MCP 客户端）

npx -y @matthew-cochran/crossmatrix --version
claude mcp add crossmatrix --scope user -- npx -y @matthew-cochran/crossmatrix

@matthew-cochran/crossmatrix 包是一个轻量级启动器：首次运行时，它会下载适用于你平台的发布二进制文件，根据发布版本的 checksums.sha256 验证文件，将其缓存，然后通过标准输入输出运行（信号会转发；标准输出用于 MCP）。CROSSMATRIX_MCP_BINARY 可指定你自行安装的二进制文件。此包也捆绑了 Agent 技能。

预编译二进制文件（无需 Rust、Cargo 或 Git）

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

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

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

固定到指定发布版本，而不是当前最新稳定版本：

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

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

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

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

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

更新

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

从源代码构建

cargo build --release

会生成 crossmatrix-mcp MCP 标准输入输出服务。

仓库提交的模型：.crossmatrix/

crossmatrix 将一个模型保存为三个通过稳定的 id@version（ADR-0004）关联的文档，以及一个仅追加的审计日志，存放在你提交到仓库的目录中：

crossmatrix-mcp init            # creates .crossmatrix/ in the current directory
crossmatrix-mcp check           # validates every document and cross-reference

.crossmatrix/
  config/<configId>@<version>.json            # methodology: scales, relations, contractions
  dimensions/<dimensionSetId>@<version>.json  # dimensions and their members
  state/<stateId>.json                        # cells/observations + revision
  audit/<stateId>.jsonl                       # one line per accepted mutation (merge=union)

写入内容为规范 JSON（键已排序、缩进 2 个空格、末尾带换行符），并采用原子写入，因此差异保持精简。每次读取时都会计算问题发现项，且不会将其保存。check 遇到错误时会以非零状态码退出，并提供特定路径的诊断信息（例如 state/demo.json: cells[3].to: unknown member 'x' in dimension 'dim_part'）；请在 CI 中运行。

服务会按以下顺序查找其存储目录：CROSSMATRIX_DIR、包含 .crossmatrix/ 的最近祖先目录、$XDG_DATA_HOME/crossmatrix（或 ~/.local/share/crossmatrix），最后是 ./crossmatrix-state。model.status 会报告解析出的 root。

命令行

命令	作用
crossmatrix-mcp	通过标准输入输出提供 MCP 服务
crossmatrix-mcp init [--dir D]	创建 D/.crossmatrix/（幂等）
crossmatrix-mcp check [--dir D]	验证存储；遇到任何问题时退出码为 1
crossmatrix-mcp skills install --target <t> (--project D | --user) [--dry-run] [--force]	安装捆绑的 Agent 技能
crossmatrix-mcp skills uninstall --target <t> (--project D | --user) / skills list	移除 / 列出安装项
crossmatrix-mcp --version / --help	版本 / 用法

工具

两个 MCP 工具：crossmatrix.command（写入）和 crossmatrix.query（读取）。 每个响应（包括拒绝响应）都带有指向合法后续操作的 links； 拒绝响应的 structuredContent 为 {ok: false, error: {code, message}, links}。

写入（crossmatrix.command）

{"request": {"schemaVersion": "0.2.0", "requestId": "r-17", "modelId": "checkout",
  "expectedVersion": 16, "actor": {"actorType": "llm", "persona": "observer"},
  "op": {"kind": "observe", "relationId": "rel_need_char", "from": "need_fast",
         "to": "char_latency", "observation": "strong", "provenanceClass": "normative"}}}

操作	层	用途
model.open	—	打开（或创建）state/<stateId>.json；重启后仍保留
model.status	—	版本、存储根目录、计数
scale.declare	配置	观测令牌 → 值表
relation.declare	配置	from/to 维度、relationType、量表、coveragePolicy
contraction.declare	配置	用于派生视图的关系链
dimension.register	维度	一个轴（dimensionKind 可以是任意 snake_case 单词）
members.sync	维度	更新名册；缺失的成员会被弃用，而非删除；未变化的名册不执行任何操作
member.propose	维度	添加一个成员
observe	状态	单元格上的令牌 + 证据（绝不是数字）
evidence.attach	状态	为观测添加证据
deprecate	任意	退役一个成员或关系（supersededBy）

仅限观测：只有带有 sourceRef.system（确定性导入）的数值型成员 weight 才会被接受；只有带有 provenanceClass: observed 和 sourceRef 的 measuredValue 才会被接受。expectedVersion 是一种乐观锁；requestId 可使命令具备幂等性，重启后仍然有效。每个被接受的变更都会追加一行审计记录 {ts, requestId, actor, op, beforeVersion, afterVersion, summary}。

旧版单次调用流程仍然有效：携带完整 model 的命令会将其导入会话（内存中），供后续查询使用。

读取（crossmatrix.query）

model.status、describe、slice、trace、explain、coverage、 gaps.orphans、gaps.next、stale、conflicts、analyze.marginalize、 analyze.contract、analyze.findings、validate、report、export。

• report {relationId?} 返回 Markdown 版质量屋：权重、关系矩阵、相关性屋顶（自关系）、技术重要度、目标（attributes.target）、覆盖情况和含贡献者信息的发现结果。不指定 relationId 时，会涵盖所有关系。
• export {format: model|report|findings} 返回合并后的模型 JSON。
• conflicts {relationId?} 列出按分离程度划分的效价张力和冲突。
• trace 和 slice 接受成员 ID 或 sourceRef.uri，支持使用 limit/cursor 分页；使用 rollup: true 时，会沿 contains 层级向上汇总叶级观测（如果目录下有任意文件实现某项功能，该目录就实现了该功能）。
• stale {hashes?, readFiles?} 将存储的来源哈希与当前哈希进行比较（readFiles 会对项目内的 file:// 来源进行哈希计算），并分页返回已变更的成员及引用这些成员的所有单元格。

AI 辅助（可选，默认关闭）

两个可选的 cargo 功能会添加由模型支持的辅助功能。除非启用这些功能进行构建，否则它们不会包含在默认构建或发行版二进制文件中；两者都需要明确选择启用 并且 提供密钥，而且都不会写入分析数值：建议会记录为待提议的观测值，在人工或 LLM 使用普通的 observe 确认该单元格之前，不会计入任何分析。

cargo build --release --features jev,rig
export CROSSMATRIX_ASSIST=jev,rig            # explicit opt-in (or `all`)
export TYPESAFE_JEV_API_KEY=...              # or OPENROUTER_API_KEY (also used by rig)

查询	功能	作用
assist.suggest {relationId, cells?, maxCells?, record?}	jev	为每个候选单元格（默认来自 gaps.next），向 Jev 提出一个选择问题，选项为关系的刻度词，并附上来自两个成员的标签、描述和证据的简要状态。每个单元格返回 {cell, token, probabilities, confidence}；record: true 会将其作为 actor {classifier, jev} 的 proposed 观测值存储。
gaps.next {rankBy: "uncertainty", relationId}	jev	按 Jev 的不确定性（1 − 置信度）对候选单元格排序。
proposals {relationId?}	—	列出等待确认的待提议观测值。
assist.members {dimensionId, sourceText, sourceUri?}	rig	根据提供的文本（README、访谈笔记、竞争对手页面）提出新成员，并为每个成员提供逐字摘录及其字符范围。不会添加成员；每个成员都会附带可直接使用的 member.propose 载荷。
assist.narrative {relationId?} / report {narrative: true}	rig	为报告生成一段简短的 analyze.findings 叙述。

配置：设置 TYPESAFE_JEV_API_KEY 后，Jev 会使用 https://api.typesafe.ai 和 jev-latest；否则会使用 OpenRouter 和 ~typesafe/jev-latest；可通过 CROSSMATRIX_JEV_BASE_URL、CROSSMATRIX_JEV_MODEL 和 CROSSMATRIX_JEV_TIMEOUT_SECS 覆盖。Rig 使用 OpenRouter，模型由 CROSSMATRIX_RIG_MODEL 指定（默认值为 openai/gpt-5-mini），超时时间由 CROSSMATRIX_RIG_TIMEOUT_SECS 指定。调用均有上限（超时时间、每次调用的单元格数、令牌预算），且每个响应都会报告 usage。如果未启用功能、未选择启用或未提供密钥，查询会返回 {ok: false, status: "assist_unavailable", reason, links}。

Agent 技能

crossmatrix 提供 Agent Skills，用于向 Agent 讲授此方法及常见用途。将它们安装到项目中（或使用 --user），即可供一个或所有客户端使用：

npx -y @matthew-cochran/crossmatrix skills install --target claude --project .
crossmatrix-mcp skills install --target all --project .      # .claude/skills + .agents/skills

目标：claude、codex、cursor、copilot、gemini、agents-md、all。.crossmatrix-skills.json 清单会记录文件哈希，因此重新安装时只会更新未编辑过的文件（--force 会覆盖文件），而 uninstall 只会移除未修改的文件。安装程序绝不会编辑 MCP 配置；它会改为打印注册命令 （claude mcp add crossmatrix --scope user -- npx -y @matthew-cochran/crossmatrix）。

技能	用途
crossmatrix	此方法：Configuration / Dimensions / State、仅写入观测值、驱动循环、限定范围的读取、.crossmatrix/
crossmatrix-hoq	经典质量屋：加权需求 × 特性、屋顶、技术重要性、目标
crossmatrix-jtbd	待完成的工作 × 用户细分 × 用户旅程，通过收缩关系连接
crossmatrix-competitive	需求 × 竞争对手基准比较，以及值得争取的差距
crossmatrix-test-coverage	需求/用户旅程 × 测试；孤立项代表未经测试的需求
crossmatrix-risk	故障模式 × 组件/需求（与 fmeca 配合使用）
crossmatrix-prioritize	交付项 × 价值驱动因素 → 供规划器使用的排序列表（与 cpm 配合使用）
crossmatrix-review	check、conflicts、stale、报告和签署清单

与 Praxec 搭配使用

这是由 Praxec pack 使用的 MCP 工具。通过一条命令安装此工具及使用它的工作流 pack，最快捷的启动方式是：

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

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

Releasing

Maintainers: see docs/releasing.md (version bump, dev → main, tag, scripts/npm-release.sh, crates.io, rollback).

License

Apache-2.0.