mason

本地服务

github.com/adrianczuczka开发工具101 周前更新

代码仓库

关于 mason

Mason 是用于保存经审阅工程决策的仓库工具，帮助维护者和编码 Agent 重用决策依据。它可检索已采纳的指导、提示被引用代码的变更，并审计文档和已提交改动。

主要功能

01记录并审阅工程决策依据
02检索已采纳的项目指导
03提示被引用代码的变更
04审计 README 和 Agent 指令
05依据指定基准审查已提交改动
06保留发现以验证修复结果

适用场景

01保存变通方案或约束的缘由
02修改代码时查找相关测试和文件
03核对仓库指令与实际内容
04验证已提交改动中的文档修复

MCP 相关

Mason 在仓库初始化时配置 MCP，并作为 MCP 服务供受支持的编码 Agent 宿主使用。它还提供无需模型调用的只读审计和审查命令。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "com-adrianczuczka-mason": {
      "command": "npx",
      "args": [
        "-y",
        "mason-context"
      ]
    }
  }
}

启动命令npx -y mason-context

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmason-context0.23.1stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
dir	string	是	项目根目录的绝对路径
base	string	否	仅用于快速入门：用于已提交差异审查的 Git 引用。默认为首个可用的 main 分支引用。
host	enum	否	在 init/setup 模式下要配置的助手；仅在可明确判断时推断。codex \| claude
mode	enum	否	Quickstart 只检查，不做更改；init 准备共享配置；setup 在本地激活兼容配置。quickstart \| init \| setup
dryRun	boolean	否	仅用于 Init：预览共享配置更改，不写入文件。
evidence	array	否	仅用于快速入门：要纳入审查的仓库本地 CI 证据清单。导入 Vitest JSON、SARIF 和原生验证器 mason-check-json 结果，不会执行检查命令。

详细介绍

Mason

保留代码如此构建的原因。

记录原因 · 回顾经验 · 展示适用指南 · 随代码变化重新审视

Mason 会将经过评审的工程决策依据保存在代码库中，让未来的维护者和编码 Agent 能够查阅重要决策背后的证据。趁解决方法、被否决的方案和限制条件的原因尚且明确时记录下来；底层代码变更时，再重新审视这些内容。

开始使用

在 macOS 或 Linux 上安装：

curl -fsSL https://github.com/adrianczuczka/mason/releases/latest/download/install.sh | sh

Windows PowerShell：

irm https://github.com/adrianczuczka/mason/releases/latest/download/install.ps1 | iex

无需安装 Node 或 npm。需要 Git。安装程序会为 Bash、Zsh 和 Windows 配置 PATH。平台详情 · npm 安装

新的标准独立安装会在后台自动更新。现有 Mason MCP 服务退出后，更新会在之后启动 MCP 时生效。运行 mason updates 可查看或更改此偏好设置。现有安装需要手动升级一次，然后运行 mason updates enable。更新控制

在 Git 代码库中运行此命令（如果安装程序提示，请打开新的终端）：

mason init --host codex    # Maintainer: prepare shared configuration for review/commit
mason setup --host codex   # Each developer: activate locally
# For Claude Code, use --host claude.

如果代码库已有兼容的 Mason 配置，只需运行 mason setup。初始化会配置 MCP、钩子和项目说明；设置操作不会改动共享文件。检查主机的信任设置，启动新会话，然后给你的 Agent 一个常规任务。

检查 Mason 是否正在使用：

mason status

设置过程会使用已安装的 mason 命令——不需要项目启动脚本或运行时副本。状态信息会区分配置情况与实际观测到的使用情况。设置与升级 · 断开项目连接 · 其他 MCP 客户端

不设置即可试用检查

mason audit --dir .
mason review --dir . --base origin/main

审计会检查代码库中 README 和 Agent 说明文件里的声明。评审会根据你选择的基准检查已提交的更改。两者都只读，也不需要调用模型。

Mason 能发现什么

随着项目发展……	Mason 会……
指引落后于代码。	标记缺失的路径、错误的工作区计数，以及缺失的 npm 脚本。
补丁遗漏了相关更新。	揭示引用、相关测试，以及历史上经常同时变更的文件。
旧决策失去上下文。	检索已记录的理由和审核状态，并标记其适用代码的变更。
修复过程被打断。	保留最初的发现，并通过最终的文档提交进行验证。

解决事件或确定约束后，让你的 Agent 使用 Mason 记录一份有来源的提案。接受其作为项目指引前，请先审核。后续任务可以检索当前生效的已接受版本，而拟议的替代版本仍保持独立；对引用代码的变更则可以触发检查、修订或弃用。

Mason 可与测试、代码检查工具和代码审查互为补充。发现结果是需要检查的证据；无法执行的检查会明确标出。

目前的证据

早期只读决策检索评测中，Mason 得分为 9.0/10，不使用 Mason 时为 7.0/10。首轮十项任务的补丁对比结果持平，双方均为 10/10。补丁效果能否提升仍有待证明。结果、方法和局限

在复用试验中，维护的笔记也取得了成功。近期的 hook 实验验证了受支持的文件传递方式，但会增加上下文开销，且未证明能提升正确性；普通 Bash 工作流的直接传递方式仍有待探索。目前的重点是在日常工作中有效保留和复用工程推理，同时让记录和维护所需的投入物有所值。防止重复犯错是预期收益之一；是否具有比较优势尚未得到证实。定位与验证计划 · 当前证据

文档

开发

开发时，请使用 Node 20（20.19+）、Node 22（22.13+）或 Node 24+。运行 npm ci 后，运行 npm run format 格式化 TypeScript 源文件、测试和工具配置。 CI 使用 npm run format:check 检查格式，并运行 npm run lint、 npm run typecheck 和测试套件。在本地运行 npm test，检查行为。

ESLint 使用推荐的 TypeScript 规则，并启用针对未处理 Promise、误用异步回调和无效 await 的类型感知检查。Prettier 负责格式化。测试夹具和生成的输出不纳入格式检查和代码检查。生产代码还会禁止显式使用 any，以及不安全的赋值、属性访问、调用、参数传递和返回。外部数据在使用前会经过验证。测试替身采用较宽松的规则。

支持 Markdown

登录后评论