install-script-generator

安装脚本生成器

生成健壮、跨平台的安装脚本，用户可以通过 GitHub raw URL 使用一条 bash 命令运行。本 SKILL.md 是精简索引——较长的模板和表格位于 references/ 下，以节省 Agent 的上下文预算。

适用场景

• 用户请求为其项目提供一条 curl | bash 命令。
• 仓库需要一个能自动检测操作系统、架构和包管理器的 install.sh。
• Python/Go/Node/Rust 模块需要支持在全新机器上通过一条命令安装。

Dockerfile、CI/CD 流水线或一次性本地 shell 脚本不适用此技能。

前置条件

• 仓库有明确的 <owner>/<repo>（检查 git remote -v），并且有默认分支。
• 可以识别目标软件的构建系统（Makefile、package.json、setup.py、Cargo.toml、go.mod 等）。
• 本地可使用 python3 来运行 scripts/ 下的辅助脚本。如果缺少 python3，则跳过每个辅助脚本步骤，记录为 not run (python3 not found)，然后继续；最终运行状态为 PARTIAL。

参考文件（按需阅读以节省 token）

文件	阅读时机
references/install-template.md	生成 install.sh 时——包含检测辅助函数、依赖安装程序和主入口的完整 bash 模板
references/readme-snippet.md	更新 README 时——可复制粘贴的安装区块和 URL 格式说明
references/edge-cases.md	处理特殊操作系统、sudo、路径场景及编写步骤报告时
references/final-report.md	编写最终报告时——四个部分、状态规则、结果表格、示例和读者检查项
scripts/env_explorer.py	本地环境探测（操作系统、架构、包管理器、sudo）
scripts/plan_generator.py	根据环境和目标生成 installation_plan.yaml
scripts/executor.py	在第 3 阶段生成前，对 installation_plan.yaml 进行试运行并回滚
scripts/doc_generator.py	生成面向用户的 USAGE_GUIDE.md

不要将这些文件的内容直接写入对话；请链接到它们，以节省上下文窗口。

编辑前同步仓库（必需）

在第 1 阶段之前运行一次。在现有仓库中创建、更新或删除文件之前，先将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，先运行 git stash push -u -m pre-sync，然后同步，再运行 git stash pop。如果缺少 origin，或 rebase/stash 时发生冲突，请停止并询问用户后再继续。

工作流

一次修复尝试是指进行一次编辑，然后重新运行失败的检查。同一项检查最多尝试修复 3 次；之后将该检查记为失败，并继续下一阶段。若要以 BLOCKED 状态停止，请跳过剩余阶段并输出最终报告。

第 1 阶段——探索

1. 确定目标软件、模块或工具。如果用户未说明目标，且仓库中有多个可构建项目，请询问用户要处理哪一个。
2. 检查仓库中的构建文件（Makefile、package.json、setup.py、Cargo.toml、go.mod 等）。
3. 记录安装方式：如果目标已发布到包管理器中，则记录包名；否则记录其构建文件中的构建和复制命令。如果两者都没有，请询问用户。如果用户未提供安装方式，则以 BLOCKED 状态停止。
4. 列出软件构建和运行所需的依赖项。
5. 运行 git remote get-url origin，读取 <owner>/<repo>。
6. 运行 git symbolic-ref --short refs/remotes/origin/HEAD，并移除 origin/，以读取默认分支。
7. 如果第 5 步或第 6 步失败，请询问用户相关值。如果用户未作答，则以 BLOCKED 状态停止。
8. 运行 python3 scripts/env_explorer.py，将操作系统、架构、包管理器、shell 和 sudo 可用性记录到 env_info.json。

第 2 阶段 — 规划

1. 按依赖顺序排列，确保每项依赖都在需要它的内容之前安装。
2. 对每项依赖，记录 install.sh 用于跳过已安装依赖的 command -v <dep> 检查。
3. 运行 python3 scripts/plan_generator.py --target "<name>" --env-file env_info.json --deps <dep1> <dep2> ...（使用第 1 步中的依赖，并以空格分隔；只有在没有依赖时才省略 --deps），生成 installation_plan.yaml。
4. 如果目标软件未发布到检测到的软件包管理器中，请编辑 installation_plan.yaml 中的 Install <name> 步骤：将 command、verify 和 rollback 设为 install_<tool> 将运行的命令。
5. 替换计划中的所有 # TODO 占位符。为 plan_generator.py 警告其遗漏的每项依赖添加一个步骤。
6. 运行 python3 scripts/executor.py --plan installation_plan.yaml --dry-run。
7. 检查试运行结果：退出码为 0，最后一行摘要以 DRY RUN: 开头，stderr 中没有 placeholder command 警告，步骤顺序与第 1 步一致，并且每个 Install ... 步骤都有非 null 的 rollback。按设计，软件包管理器检查步骤和最终验证步骤的 rollback 为 null。如果检查未通过，请修正计划并重新运行第 6 步。

试运行会跳过执行，因此它检查的是计划的结构，而不是安装或回滚是否确实可行。

第 3 阶段 — 生成（主要输出）

如果仓库根目录中已存在 install.sh，请向用户展示计划进行的更改，并在覆盖前征求同意。如果用户拒绝，请以 BLOCKED 结束。

使用 references/install-template.md 在仓库根目录生成 install.sh。该模板包含需要组合的四个部分：

1. 标头 + 颜色辅助函数（info、ok、warn、err、die）。
2. 检测辅助函数（detect_os、detect_arch、detect_package_manager、need_sudo）。
3. 涵盖 apt/dnf/yum/pacman/brew/zypper 的 install_deps 分支。
4. install_<tool>（根据目标定制）、verify_installation 和 main。

阅读 references/install-template.md 获取准确代码；不要将其粘贴到聊天中。如果需要支持 Windows，也请生成 install.ps1（单行命令：irm <raw_url> | iex）。

然后检查脚本。如果某项检查未通过，请修正 install.sh 并重新运行该检查：

1. bash -n install.sh 退出码为 0。
2. grep -nE '<owner>|<repo>|<branch>|<software_name>|<Software Name>|install_<tool>' install.sh 不打印任何内容。
3. 如果 shellcheck 在 PATH 中，运行 shellcheck -S error install.sh，退出码应为 0。否则记录 shellcheck not run (not on PATH)。

不要在用户的机器上运行 install.sh：它会安装软件，且可能调用 sudo。只有在用户要求本地运行，或批准在一次性容器中运行时，才运行它。运行时，最后一行必须是 [ OK ] Installation complete!。

第 4 阶段 — 文档

1. 将 references/readme-snippet.md 中的安装块插入项目 README，并替换 <owner>/<repo>/<branch>。如果仓库没有 README，则创建 README.md，其中仅包含该安装块。
2. 运行 python3 scripts/doc_generator.py --target "<name>" --plan installation_plan.yaml，生成 USAGE_GUIDE.md。
3. 使用真实值运行 grep -n "raw.githubusercontent.com/<owner>/<repo>/<branch>/install.sh" <README>；必须打印一行或多行。
4. 如果 git ls-tree --name-only origin/<branch> install.sh 打印 install.sh，则运行 curl -fsSI <raw-url> 并记录 HTTP 状态码。否则记录 raw URL not live until install.sh is pushed。
5. 输出最终报告。

最终报告

在最后一份阶段完成报告之后，以纯文本形式在聊天中打印一次。按顺序包含四部分：Result:（状态、目标、一句话总结）、Evidence:（仅列出已运行的检查及其结果）、Uncertainty:（未经测试的行为，包括 install.sh was not executed）和 Decision:（需要的批准，或 No approval needed.，然后列出推送和清理操作）。有关每部分的内容、结果表和示例，请阅读 references/final-report.md。

采用第一个符合条件的状态规则：

1. BLOCKED — <reason> — 未编写 install.sh。
2. PARTIAL — <reason> — 已编写 install.sh，但某项必需检查失败或未运行：bash -n、占位符 grep、shellcheck -S error（若在 PATH 中）、Phase 2 dry run、README 中的单行命令、USAGE_GUIDE.md，或获批运行的 install.sh 未以 [ OK ] Installation complete! 结束。
3. COMPLETE — 所有必需检查均已通过。COMPLETE 不代表运行过 install.sh。

输出文件

文件	说明
install.sh	主要输出——适用于 curl | bash 的独立安装程序
install.ps1	可选的 Windows PowerShell 安装程序
USAGE_GUIDE.md	面向用户的文档
env_info.json	本地环境探测信息（工作文件）
installation_plan.yaml	有序安装步骤（工作文件）
install_report.md	executor.py 生成的 dry run 报告（工作文件）

三个工作文件包含这台机器的 home 路径和 PATH。除非用户提出要求，否则不要提交这些文件；在 Decision: 下列出它们以便清理。

验收标准

• 仓库根目录下存在 install.sh，以 #!/usr/bin/env bash 和 set -euo pipefail 开头，并通过三个 Phase 3 检查。
• 自动检测 OS、架构和包管理器；遇到不支持的目标时，以非零状态退出并显示清晰消息。
• 妥善处理 sudo（使用 root、sudo，或快速失败）。
• 在末尾验证安装结果（command -v $TOOL_NAME，并在可用时运行 --version）。
• README 包含一条 curl -sSL ... | bash 单行命令，指向 <owner>/<repo>/<branch> 的 GitHub 原始文件 URL。
• install.sh 成功运行时，最后一行是 [ OK ] Installation complete!。
• 最终报告以 Result: 开头，状态符合上述规则，并满足 references/final-report.md 中面向读者的四项检查：结果易于查找、事实与假设分开、声明有据可查、后续决策明确。

边缘情况

完整列表请参阅 references/edge-cases.md。重点包括：

• 不支持的 OS／架构 — 使用 die 并显示检测到的值，让用户了解失败原因。
• 没有包管理器 — install_deps 中止并显示 Unsupported package manager 'unknown'。
• 没有 sudo — need_sudo 退出并显示 Requires root. Run as root or install sudo.
• 原生 Windows — 单独生成 install.ps1；在 MSYS/Cygwin 下，install.sh 会发出警告。
• 脚本位于子目录 — 调整原始 URL 路径；在 README 代码片段中注明。
• 包管理器中没有目标工具 — 编辑其计划步骤（Phase 2 第 4 步），并根据构建文件编写 install_<tool>。

阶段完成报告

每个阶段结束后，输出一个包含 √／× 检查项的 ◆ 区块，并附上一行 Result: PASS | FAIL | PARTIAL；格式和各阶段检查项见 references/edge-cases.md。

预期输出

完整运行时的最终报告（完整示例见 references/final-report.md）：

Result: COMPLETE — mytool installer
  curl -sSL https://raw.githubusercontent.com/owner/mytool/main/install.sh | bash
Evidence:
  bash -n install.sh: exit 0; placeholder grep: no matches; shellcheck -S error: exit 0
  executor.py --dry-run: "DRY RUN: 5 step(s) listed for mytool; nothing was executed."
Uncertainty:
  install.sh was not executed. Raw URL not live until install.sh is pushed to main.
Decision: No approval needed.
  Remaining action: commit and push install.sh; delete the three working files.

用户之后运行单行命令时，脚本横幅的结尾如下：

[INFO]  OS: linux | Arch: x86_64 | Package Manager: apt
[ OK ]  Dependencies installed
[ OK ]  mytool 1.2.0 installed
[ OK ]  Installation complete!