DevReady

---

DevReady 是什么？

DevReady 是一个命令行工具，用来告诉你电脑是否已配置好，可以着手处理某个项目。在项目文件夹中运行 devready check，它会：

1. 读取项目声明所需的版本（.nvmrc、.python-version、package.json 中的 engines、pyproject.toml 中的 requires-python）。
2. 比对这些版本与你机器上实际安装的版本（Python、Node.js、npm、Git 等）。
3. 报告每项检查的 PASS、WARN 或 FAIL，并说明需要修复什么。如果有要求未满足，退出代码为 1，因此也适用于 CI。

它只检查，不会安装、更改或删除任何内容，不会发起网络请求，也不会收集遥测数据。问题需要由你自行修复（例如切换 Node 版本）。

问题所在

你克隆了一个仓库。运行 npm install 时却崩溃了。README 写着“Node 20”，你的机器上装的是 16，错误消息却毫无用处。每次新员工、学生、CI 运行器和AI Agent都要猜测构建失败的原因，白白消耗 token；这样的情况还会不断发生。

解决方案

$ devready check

DevReady - Environment Check

[PASS ] Python       3.15.0 found
[PASS ] Git          2.52.0 found
[PASS ] Node.js      23.5.0 found
[PASS ] npm          11.14.1 found
[FAIL ] Node engines 23.5.0 does not satisfy package.json engines (>=99)
[WARN ] Python pin   3.15.0 does not satisfy .python-version (3.99)

No changes were made to your system.

上述输出来自一次真实运行（特意将版本固定为不可能的值，以展示失败情况）。如果有要求未满足，退出代码为 1，因此可以直接用于 CI。

DevReady 的优势

🎯 了解项目要求	读取你的项目声明的要求（.nvmrc、.node-version、.python-version、package.json 中的 engines、pyproject.toml 中的 requires-python），并与已安装版本进行比对。不只是检查“是否安装了 Node？”
🔒 专为只读而设计	不会安装、编辑或删除任何内容。不会输出环境变量值。不联网。不收集遥测数据。
🤖 适用于 Agent	提供稳定、带版本的 JSON schema、Claude Code 插件、MCP 服务和 AGENTS.md。Agent 可以先检查，而不是猜测。
🛡️ 可防范提示词注入	输出只包含解析后的版本和固定文本，不包含文件或命令的原始输出，因此恶意的 package.json 无法向你的 Agent 偷塞指令（已测试）。
📦 零依赖	纯 Python 标准库。只需一秒即可安装，可在任何支持 Python 3.10+ 的环境中运行。
⚙️ 适用于 CI	退出代码说明清晰，支持 JSON 输出，并已在 CI 中针对 Linux、macOS 和 Windows 完成测试。

适用对象

• 🧑‍🎓 学生和训练营学员：获取浅显易懂的结果，而不是晦涩的堆栈跟踪。
• 🧑‍💻 切换项目的开发者：一条命令就能在浪费一小时之前指出问题。
• 👩‍🏫 维护者和教育工作者：将 devready check 添加到 README 的设置步骤中，减少“它无法运行”之类的问题。
• 🏗️ CI 和平台团队：通过清晰的预检步骤，快速发现问题并失败。
• 🤖 AI Agent 用户：让 Claude Code / Codex 检查环境的真实状态。

安装

从 PyPI 安装：

pipx install devready-cli
# or run without installing:
uvx devready-cli check

从 npm 安装（通过 uvx 或 pipx 运行相同的 PyPI 版本，因此必须安装其中之一）：

npx devready-cli check

从克隆的仓库安装（用于开发）：

git clone https://github.com/Evalogical-Inc/devReady && cd devReady
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1    macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"

用法

devready check                    # human-readable report for the current directory
devready check --quiet            # only non-pass results (text format)
devready check --project ../app   # inspect another project's pins
devready check --format json      # machine-readable (see docs/schema.json)
devready explain docker.daemon    # what a check means and how to fix it
devready check --format junit     # or sarif, for CI
devready check --only project --skip project.ports   # filter by id or prefix
devready fix --plan               # suggested steps only; never runs them
devready check --format json > baseline.json   # save a snapshot (commit it for a team baseline)
devready check --baseline baseline.json          # show only what changed; fail only on new/worse failures
devready init > .devready.json    # optional config: skip ids, require node/python, required env names
devready mcp                      # run as an MCP server over stdio
devready --version

退出代码	含义
0	没有阻塞性失败
1	未满足项目要求
2	用法无效（例如，--project 路径错误）
3	内部错误

状态	含义
pass	已满足要求
warn	缺少工具，或软版本锁定（.nvmrc、.python-version）不一致
fail	未满足硬性要求（engines、requires-python）
skip	未评估（缺少工具，或无法理解要求语法）
error	DevReady 无法运行检查

JSON 输出

{
  "schema_version": 1,
  "results": [
    {
      "check_id": "project.node.engines",
      "title": "Node engines",
      "status": "fail",
      "summary": "23.5.0 does not satisfy package.json engines (>=99)",
      "suggestion": "Switch versions with your version manager (nvm, pyenv, mise, ...) or update the requirement.",
      "docs_url": ""
    }
  ]
}

在 CI 中使用（GitHub Actions）

- uses: Evalogical-Inc/devReady@main   # pin a release tag once published
  with:
    skip: project.ports                  # optional; also: only, format, project, version

如果未满足某项已声明的要求（fail），作业就会失败。它会从 PyPI 安装 devready-cli，因此，若要使用在当前已安装版本之后添加的标志（--only、--skip、junit/sarif），需要安装包含这些标志的版本；设置 version: 可固定版本。

添加徽章

告诉贡献者，你的项目声明了自身要求，并且可以通过一条命令进行检查。将以下内容粘贴到 README 中：

[![DevReady](https://img.shields.io/badge/DevReady-%E2%9C%93%20ready-2ea44f)](https://github.com/Evalogical-Inc/devReady)

与 AI 编码 Agent 配合使用

DevReady 通过三种方式提供同一套引擎，让你的 Agent 可以在安装、构建或测试之前验证环境。

Claude Code - 插件包含一项技能、/devready:doctor 命令和一个 MCP 服务（MCP 服务需要 uv；安装 devready-cli 后，其余功能无需 uv 即可运行）：

/plugin marketplace add Evalogical-Inc/devReady
/plugin install devready --marketplace Evalogical-Inc/devReady

任何 MCP 客户端（Codex、Cursor 等）- 一个只读工具 check_environment。也已作为 io.github.Evalogical-Inc/devready 收录在 MCP Registry 中：

# ~/.codex/config.toml (verify keys against your Codex version)
[mcp_servers.devready]
command = "uvx"
args = ["--from", "devready-cli", "devready", "mcp"]

其他任何情况 - 将 AGENTS.md 放入你的仓库，或复制 skills/devready。详情请参阅 docs/agents.md。

安全与隐私

• 使用带超时的固定命令列表；不使用 shell，也不运行用户构建的命令。
• 仅当项目文件是大小不超过 1 MB 的常规文件时才会读取（跳过符号链接），并且绝不会执行这些文件。
• 不会读取环境变量的值并将其输出。任何信息都不会离开你的设备。
• 检查报告通过 并不 保证项目可以构建。

有关模型，请参阅 docs/security.md；有关保持稳定的内容，请参阅 docs/versioning.md；有关所有检查，请参阅 docs/checks.md；如需报告漏洞，请参阅 SECURITY.md。

限制

• 当前检查项：Python、Git（已设置身份信息）、Node.js、npm、项目版本锁定（.nvmrc、.node-version、.python-version、.tool-versions、package.json 中的 engines、pyproject.toml 中的 requires-python）、.env.example 与 .env 的键名、Docker CLI 和守护进程（仅当项目包含 Dockerfile/compose 文件时检查）、可用磁盘空间，以及（仅当项目声明了这些内容时）Go、Ruby、Java、Rust、.NET、pnpm、Yarn 和 Bun 版本锁定、.env 未被 Git 忽略、node_modules 与锁文件是否匹配，以及已声明的端口是否已被占用。
• 版本范围匹配器支持常见的 npm/PEP 440 语法；对于预发布版本和特殊范围，会报告 skip，而不会猜测。
• 比较的 Python 版本是运行 DevReady 的解释器版本，不一定是项目虚拟环境的版本。

路线图

• Docker CLI + 守护进程连通性检查、.tool-versions、.env 键名差异、磁盘空间、Git 身份信息、devready explain
• 端口占用检查、支持更多生态（Go、Rust、Java、Ruby、.NET、pnpm/yarn/bun）、JUnit/SARIF 输出、fix --plan、GitHub Action
• .devready.json 配置、--baseline 快照
• 特定平台的检查（参见 ROADMAP.md）
• 独立二进制文件

遇到希望 DevReady 能发现的环境配置问题？提交 issue。早期反馈有助于制定路线图。

贡献

欢迎提交 PR，尤其是新增只读检查和平台修复。请从 CONTRIBUTING.md 和技术计划开始；背景研究见 docs/research.md。请遵守行为准则。

ruff check . && pytest

关于 Evalogical

DevReady 由 Evalogical 开发和维护。Evalogical 是一家提供 AI 驱动的产品工程、定制软件和 IT 服务的软件公司。需要产品或工程团队方面的帮助？联系我们。

许可证

MIT © Evalogical Inc