用途
System & Environment Setup 是一个用于构建可复现开发者环境的技能，作为仓库中更广泛的环境搭建锚点。它的目标是让项目在开发者机器和环境之间可运行且可重复，通常涵盖运行时/工具版本固定、本地服务与容器、引导脚本、入职步骤、本地与生产一致性权衡、密钥/配置交接边界，以及自动化漂移时的搭建诊断。
主要能力
- 将环境搭建请求归类为可运行本地仓库、标准化入职、本地服务一致性、工具链可复现、搭建诊断或混合等目标。
- 从五种主要操作模式中选择一种：bootstrap-and-onboarding、toolchain-reproducibility、local-services-and-parity、containerized-dev-environment、setup-diagnosis-and-hardening。
- 根据问题选择最小的可复现栈，优先使用运行时/版本固定，在需要支撑服务或共享本地拓扑时使用 Docker Compose，在编辑器/运行时标准化和入职速度更重要时使用 devcontainer。
- 输出结构化的“Environment Setup Brief”，包含推荐模式、当前搭建面、推荐环境栈、需创建或验证的命令/文件、一致性差距和注意事项。
- 提供各模式的具体指导，例如定义清晰的首次运行路径、显式固定运行时版本、命名哪些服务必须本地运行、决定 Compose 与 devcontainer 的取舍、比较文档与脚本与容器文件以找出权威来源。
使用方式
该技能通过读取请求并执行以下步骤来工作：
- 分类搭建面：将请求规范化为环境摄入结构，包括主要目标、当前状态、运行时形态、主机策略、配置策略、主要痛点和置信度。
- 选择一种主要操作模式。
- 选择最小的可复现栈。
- 构建环境计划，返回指定的“Environment Setup Brief”结构。
- 应用模式特定指导。
- 保持边界清晰。
在异常情况或决定任务归属时，应先阅读 references/operating-modes.md 和 references/scope-boundaries.md。
适用场景
- 让仓库在新机器上以一致的工具链可运行。
- 在多个贡献者之间标准化本地开发设置。
- 在本地主机、Docker Compose、devcontainer 或混合工作流之间选择。
- 固定运行时/工具版本并减少跨机器漂移。
- 设置本地支撑服务，如数据库、缓存、队列或搜索。
- 设计引导命令、搭建检查或入职流程。
- 诊断本地搭建文档、脚本、容器与实际运行时行为为何脱节。
- 在不假装本地与生产完全相同的前提下改善本地一致性。
限制
- 如果主要任务是应用级 .env 组织、环境模式验证或框架环境规则，应使用 environment-setup。
- 如果主要任务是生产部署、云发布或 CI 编排，应使用 deployment-automation。
- 如果主要任务是托管基础设施安全审查，应搭配 security-best-practices。
- 如果任务只是安装一个包且没有更广泛的环境决策面，应使用更窄的安装/设置技能（如果可用）。
- 不应将 .env / 环境验证细节埋在此处。
- 不应将搭建指导变成云部署教程。
- 如果认证、密钥或平台怪癖仍需手动处理，不应声称完全一致。
- 不应让引导脚本成为无法解释的魔法。
最佳实践
- 优化可运行仓库，而非最大工具复杂性。
- 选择一个规范的可复现故事，并明确替代方案。
- 保持密钥/配置指导与机器/运行时设置相连但不混淆。
- 添加验证步骤，使入职可测试。
- 命名一致性差距，而不是假装容器解决一切。
- 将更窄的应用配置问题路由到 environment-setup。
参考
- Scope boundaries: references/scope-boundaries.md
- Operating modes: references/operating-modes.md
- Docker Compose docs: https://docs.docker.com/compose/
- VS Code dev containers: https://code.visualstudio.com/docs/devcontainers/containers
- GitHub dev containers intro: https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers