readmeaudit

Name: readmeaudit
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords开发工具01 天前更新

代码仓库

关于 readmeaudit

readmeaudit 是面向 JavaScript 包维护者的离线 README 审计工具，可发现文档与实际内容不一致之处。它将安装命令名称和 CLI 参数与 package.json 及 TypeScript 源码比对，并给出证据和 IN-SYNC 或 DRIFT 结论。

主要功能

01核对安装名称与 package.json
02比对文档和源码中的参数
03检查已声明服务是否提及 MCP
04报告包含文件和行号证据
05提供确定性的 CLI 和 JSON 报告

适用场景

01发布前检查 README 准确性
02查找文档中过时的 CLI 参数
03在发布工作流中执行审计

MCP 相关

它可作为 MCP 服务运行，并提供 audit_readme(path) 工具，以 JSON 返回审计报告。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-readmeaudit": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/readmeaudit"
      ]
    }
  }
}

启动命令npx -y @reneturcios/readmeaudit

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

安装包

npm@reneturcios/readmeaudit0.1.0stdio

ocighcr.io/cloudcorprecords/readmeaudit:0.1.0stdio

工具

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

参数	类型	必填	说明
path	string	是	要检查的目标路径

详细介绍

readmeaudit

README 会逐渐与实际情况脱节。安装命令指向已重命名的包，使用说明记录了 CLI 两个版本前就已移除的标志，而直到用户复制了一个不存在的命令，才有人发现问题。

readmeaudit 会将包的 README 与其旁边的两个事实来源进行比对：package.json 和 src/ 下的 CLI 源码。它会检查安装命令中使用的包名是否与 package.json 中的名称一致、README 记录的每个长标志是否实际出现在源码中、源码中的每个长标志是否都已记录，以及声明了 MCP 服务的包是否在 README 中说明了这一点。结果是一份确定性报告，并给出判定：IN-SYNC 或 DRIFT；对于每项不一致，报告都会提供证据（规则、严重程度、文件、行号）。

它可离线运行，只读取静态文本，绝不会执行目标包中的任何内容。它既可通过 CLI 调用，也可作为 MCP 服务运行，因此可在发布工作流和 Agent 会话中执行检查，而不只是手动检查。

安装

npx @reneturcios/readmeaudit

这条命令无需全局安装即可运行工具。使用下方所示的 audit 命令，指定一个包目录。

CLI 用法

readmeaudit audit [path] [--json]
readmeaudit mcp
readmeaudit --version

audit 检查指定路径下的包（默认：当前目录），并输出人类可读的报告。添加 JSON 选项则会改为输出相同报告的 JSON 格式。
mcp 通过标准输入输出启动 MCP 服务。
版本选项会输出工具版本并退出。

退出码：判定为 IN-SYNC 时为 0，判定为 DRIFT 时为 1，用法错误或目标不可读取时为 2。若读取方提前关闭输出管道，进程会以 141 退出，绝不会返回 0。

以下是文档与实际情况一致的包的示例输出：

readmeaudit 0.1.0
Target: .
Verdict: IN-SYNC
Counts: flagsDocumented=3, flagsInSource=3, phantom=0, undocumented=0, nameDrift=0
Findings: none
IN-SYNC: no high or medium findings; 0 low or info finding(s) noted.

每份报告中的计数都会统计 README 中记录的 --flags 和源码中找到的 --flags，以及记录的标志中有多少是虚构的、源码中的标志有多少未记录，还有多少条安装命令写错了包名。

检查内容

规则	严重程度	含义
`NAME-DRIFT`	high	README 中的安装命令所写的包名与 package.json 中的 name 字段不同。此发现会提供行号，并将问题所在行作为证据。
`NO-INSTALL`	medium	README 中完全没有安装命令，因此新用户没有可复制且包含包名的命令。
`FLAG-PHANTOM`	medium	README 中记录了某个长标志，但它没有出现在 src/ 下的任何源文件中。
`FLAG-UNDOCUMENTED`	low	src/ 下的源码中出现了某个长标志，但 README 从未记录该标志。
`MCP-UNDOCUMENTED`	low	package.json 声明了 mcpName，说明该包提供 MCP 服务，但 README 从未提及 mcp。
`CMD-UNKNOWN`	info	围栏代码块中的某一行以一个未声明为该包 bin 名称的裸命令词开头，且该行还包含一个长标志或单词 mcp。

每项检查的工作方式

名称。 名称检查仅针对安装行：包含包运行器命令或标准 JavaScript 包管理器安装命令的行。在这些行中，命令词后的第一个非选项词条就是调用的包名称，任何版本后缀都会被去除。带作用域名称和普通名称都能识别。调用的名称与 package.json 中的名称不同时，即为 NAME-DRIFT。将检查范围限定为安装行是有意为之：正文和对比表中合理地会提到其他工具名称，而这些提及并非安装命令。

标志。 标志检查会从 README 以及 src/ 下的所有 TypeScript 文件（递归遍历）中收集长标志词条（两个连字符，后接一个字母，再接字母、数字或连字符）。两侧使用相同的收集器；当 --flags 这样的词条以文本形式出现时，收集器会将其识别出来。随后会对这两个集合进行双向差异比较，每个标志产生一条发现。

MCP。 当 package.json 包含 mcpName 字段时，包会以该名称向 MCP 客户端呈现，而 README 至少应提及该协议。此检查会在 README 中不区分大小写地搜索单词 mcp。

命令。 按设计，命令检查是本工具中最谨慎的一项检查。它只检查围栏代码块，只检查每行的第一个词条，并且仅当该词条是裸词，既不是已声明的 bin 名称，也不是常见的 shell 或程序词时才会检查（包管理器、运行时、容器工具、版本控制工具和基本 shell 词均会排除）。即便如此，它也只会以 info 严重级别报告，和其他发现一样计数，但绝不会改变判定结果。用法代码块中的未知命令词条通常是辅助工具、别名或旧版本中更名后的二进制文件；这条发现只是为了提醒人工查看，而不是让门禁失败。

判定规则

IN-SYNC：没有高或中严重级别的发现。低和 info 级别的发现会报告，但不会改变判定结果。退出代码为 0。
DRIFT：至少有一条高或中严重级别的发现。退出代码为 1。
发现按规则排序，其次按相关标志或名称排序，再按行号排序。报告不含时间戳，因此对同一目录树运行两次会产生字节完全相同的输出。

MCP 服务

在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "readmeaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/readmeaudit", "mcp"]
    }
  }
}

工具：audit_readme(path) 会以 JSON 格式返回完整审计报告，与 CLI 使用 JSON 选项时打印的对象相同。

明确说明限制

这是静态文本比较。readmeaudit 可以检查名称、标志和命令，因为它们都是具体词条，并且在 package.json 和 src/ 中有可供核对的依据。它无法判断正文描述是否属实：如果 README 用流畅的句子描述了代码并不具备的行为，但其中没有错误名称或标志，检查仍会通过。
标志是文本词条。源代码注释或字符串字面量中的标志会被视为存在于源代码中；运行时动态拼接的标志（由多个部分构成，或从配置中读取）则会漏检。
源代码覆盖范围仅限 src/ 下的 TypeScript 文件。以其他语言实现的 CLI，或位于目录树其他位置的文件，不会被标志检查发现，其中的标志会被视为虚假标志。
名称检查只查看安装行。正文、徽章 URL 或标题中的过时包名称不会被标记。
bin 名称来自 package.json 的 bin 字段。没有 bin 字段的包，除了已知词条排除规则外，不会获得任何命令检查保护；CMD-UNKNOWN 之所以始终为 info 严重级别，正是因为本工具宁可少报告命令，也不愿凭猜测指责 README。
缺少输入属于错误，而非发现：目标目录没有 package.json，或既没有 README.md 也没有 README 时，检查会显示清晰的消息并以退出代码 2 结束。