make-env-setup

make-env-setup

为这台机器做好构建 Make App 的准备：选择合适的工具链，验证 Make 登录状态，并且仅在创建新 App 时初始化项目文件夹。在新机器上运行此流程；需要更新工具时也再次运行。使用 makecli 执行资源和部署操作，并使用负责实现的技能。

安全规则

• 不要打印或存储令牌、Cookie、Authorization 标头、密码或机密信息。
• 不要手动创建 PRD、DSL、Service 或 UI 文件；只能在选定目录中运行 makecli app init。
• 交互式输入机密信息必须由用户完成。不要要求用户在聊天中粘贴机密信息。
• 不要通过 npm 安装 pnpm。对于新 App 或明确迁移的 App，使用下方固定的 Corepack/pnpm 基线。已有且兼容的 npm 或 Yarn App 应保留其声明的安装器和锁文件；此环境技能不得将其切换为 pnpm。

选择项目模式

• 对于新 App 或用户明确要求迁移运行时的情况，遵循下方固定的 Node.js/Corepack/pnpm 基线。运行时迁移本身由 make-app-runtime 负责；不要在此设置流程中更改现有仓库的清单或锁文件。
• 对于未明确要求迁移的现有 Make App，在选择工具前，检查其工作区的 packageManager、Node engines、Node 版本选择文件、锁文件以及 CI/安装工作流。保留兼容的 Node 和包管理器声明，包括 npm 或 Yarn。不要仅为更新本地环境而添加 Corepack 或 pnpm。如果这些声明彼此不一致、所需运行时不明确，或目标平台的构建映像不兼容，请停止操作，并将问题报告给 make-app-runtime，不要猜测或创建另一个锁文件。
• 如果目标文件夹或新建与现有项目模式不明确，请先询问用户，再选择项目运行时或初始化文件夹。

安装或更新工具链

此技能支持 macOS、Linux 和 Windows。对于新 App 或明确迁移的 App，运行时固定为：Node.js 22.20.0、其内置的 Corepack 0.34.0，以及 [email protected]。以下步骤 1–3 仅适用于此模式。不要替换为持续更新的 LTS 版本、Homebrew 或全局 pnpm 二进制文件，或更新版本的 Corepack。

对于未迁移的现有 Make App，请使用当前 Node 二进制文件验证其声明的 Node 版本，并沿用其既有的 npm、Yarn 或由 Corepack 管理的 pnpm 工作流。如果未安装其声明的 Node 版本，请先征求用户同意，再安装该版本；不要自动改装为 22.20.0。继续执行共用的 git、makecli 和 Skill 检查，不要改写 App 文件。

1. 确保 Node.js 22.20.0 和 git 可用。如果缺少其中任何一项，只有在用户确认后，才使用该平台自己的方法安装。

   平台	Node.js 22.20.0	git
   macOS	使用 nvm install 22.20.0 安装，然后使用 nvm use 22.20.0 选择该版本；如果无法使用 nvm，则使用用户选择的精确版本管理器	xcode-select --install，或使用已安装的 Homebrew
   Linux	使用 nvm install 22.20.0 安装，然后使用 nvm use 22.20.0 选择该版本；如果无法使用 nvm，则使用用户选择的精确版本管理器	发行版软件包，例如 apt install git
   Windows	使用 nvm-windows 等精确版本管理器安装并选择 22.20.0，或使用官方的 Node.js 22.20.0 安装程序	winget install Git.Git

   Make App 运行时不要使用持续更新的软件包管理器公式，例如 brew install node、apt install nodejs 或 winget install OpenJS.NodeJS.LTS。如果没有可用的精确版本 Node 管理器，请暂停并让用户选择一个。

2. 安装 pnpm 之前，先验证固定的 Node.js 和 Corepack 基线。以下检查适用于所有平台，且必须全部通过：

   node -e 'if (process.versions.node !== "22.20.0") { throw new Error(`Make Apps require Node.js 22.20.0; got ${process.versions.node}`) }'
   node -e 'const { execFileSync } = require("node:child_process"); const actual = execFileSync("corepack", ["--version"], { encoding: "utf8" }).trim(); if (actual !== "0.34.0") { throw new Error(`Corepack must report 0.34.0; got ${actual}`) }'
   

3. 启用 Corepack，并缓存新建或已迁移 App 固定版本的 pnpm 基线。不要通过 npm、Homebrew 或其他全局软件包管理器安装 pnpm。请使用 corepack install -g，而不是已弃用的 corepack prepare。

   corepack enable
   corepack install -g [email protected]
   node -e 'const { execFileSync } = require("node:child_process"); const actual = execFileSync("corepack", ["pnpm", "--version"], { encoding: "utf8" }).trim(); if (actual !== "10.20.0") { throw new Error(`pnpm must report 10.20.0; got ${actual}`) }'
   

4. 安装或更新 makecli。如果已安装 makecli，请运行 makecli update --skip-skills；否则运行 npm install -g @qfeius/makecli。makecli update 会识别其安装方式：通过 npm 或 pnpm 安装的版本会由相应的软件包管理器升级，其他安装方式则会原位替换二进制文件。

   如果 npm 全局安装在 macOS 或 Linux 上因 EACCES 失败，请勿使用 sudo。将 npm 的全局前缀指向用户拥有的目录，将其添加到 PATH，然后重试：

   npm config set prefix "$HOME/.npm-global"
   export PATH="$HOME/.npm-global/bin:$PATH"   # also add this line to the shell profile
   

5. 每次运行都要安装或更新 Make 平台技能。

   npx skills add qfeius/make-platform-skills --all -y
   

   根据命令输出，简要显示 Make 技能结果，例如已安装、已更新或已是最新。

验证版本

对于新建或明确迁移的 App，运行所有检查并简要汇总：

node --version
npm --version
corepack --version
corepack pnpm --version
git --version
makecli version

在此模式下，Node 必须准确报告 v22.20.0，Corepack 必须准确报告 0.34.0，pnpm 必须准确报告 10.20.0。如果任何检查失败，请暂停并修复当前运行时；不要继续使用其他版本。

对于未迁移的现有 Make App，请检查 node --version、git --version、makecli version，以及项目声明的包管理器命令（兼容 pnpm App 使用 corepack pnpm --version，npm App 使用 npm --version，Yarn App 使用 yarn --version）。将检查结果与已检查的清单文件、Node 版本选择文件以及 CI/安装工作流进行比较。不要要求新 App 固定的三版本组合，也不要对 npm/Yarn App 运行 Corepack 检查。如果版本不一致，请暂停，并将兼容性阻碍交由 make-app-runtime 处理。

通过引导式登录验证令牌

环境配置成功后，检查当前令牌：

makecli configure verify --output=json

如果验证成功，请根据情况继续选择或初始化项目文件夹。

如果验证失败，原因是令牌缺失、过期、无效或属于错误的环境：

1. 运行：

   makecli login --timeout=60s
   

   此命令会打开浏览器，等待登录回调，最长 60 秒，然后自动退出。如果命令打印出授权 URL，而不是打开浏览器，请将该 URL 转发给用户。
2. 如果命令成功退出，则表示登录已完成；请根据情况继续选择或初始化项目文件夹。
3. 如果命令因超时或回调错误而退出，请告知用户：

   请在浏览器中完成 makecli 登录。完成后回复“已经完成登录”。
   

   然后停止并等待用户回复 已经完成登录。
4. 用户回复后，运行 makecli configure verify --output=json。如果 valid 为 true，则表示登录成功；请继续。如果 valid 为 false，则返回步骤 1。

如果使用浏览器登录不方便，请提供令牌备用方案：

makecli configure token

用户必须在自己的终端中完成交互式密钥输入。用户完成后，运行 makecli configure verify --output=json 确认令牌。如果 valid 为 false，请让用户重新输入令牌，或改用上述引导式 makecli login 流程。

初始化 App 项目文件夹

对于已有的 Make App，如果用户没有要求重新初始化，请勿运行 makecli app init。保留其当前项目文件夹，并报告该位置。以下步骤仅适用于新 App 或用户要求初始化的情况。

makecli app init 会根据目标目录的基本名称生成 App 键，并自行验证名称；请勿在此技能中预先验证名称。

1. 选择一个候选项：
   • 如果用户已经描述了想要构建的 App，请根据描述推荐一个文件夹名称。
   • 否则，如果当前目录不是已有项目，请建议直接在当前目录中初始化。
   • 否则，请建议使用 make_app 之类的通用名称。
2. 向用户确认：

   是否使用 <app-folder> 作为 App 目录？请回复 “是” 或 “否”。
   

   如果用户的回复不是 是 或 否，请用相同的提示再次询问。
3. 如果用户回复 否，请询问：

   请输入 App 目录地址：
   

   接受用户提供的绝对路径或相对路径。
4. 运行 makecli app init <app-folder>；如果要在当前目录中初始化，则不带参数运行 makecli app init。该命令会在需要时创建目录，且可幂等执行。
5. 如果 init 因键无效而失败，错误消息会说明命名规则：根据所选名称生成符合规则的文件夹名称（例如，contract-ledger → contract_ledger），告知用户调整后的名称，然后重试。对于其他错误，请报告错误并询问用户是要重试还是选择其他目录。只有 init 成功后才能继续。

设置完成输出

只有在所选工具链已验证且令牌有效后，才能结束（初始验证通过或登录流程成功）。对于新 App，还必须成功运行 makecli app init；对于已有 App，必须验证其声明的运行时和文件夹，且不得重新初始化。请使用简洁的就绪报告：

• 工具版本：Node、git、makecli 和所选项目的包管理器；仅当该项目的工作流需要时才包含 Corepack。
• Make 技能结果。
• 登录状态：原本有效，或已通过 makecli login 刷新。
• App 文件夹：已初始化的新目录或已验证的现有目录。

完成输出应简洁，并聚焦于下一步。省略关于未执行操作的负面总结。

如果一切顺利，请说：

Make 开发环境已经准备好，可以进行下一步开发 App。

对于新初始化的 App，请提供以下简短示例：

App 参考示例：

我要做一个 Make App，用来演示合同台账管理。
角色包括管理员和业务人员。
核心流程是新建合同、维护付款计划、查看合同列表和详情。
请先和我确认需求细节，生成 apps/docs/PRD.md，再进行 DSL 建模；DSL 必须先 diff，等我确认后才 apply。