ansible-generator

Ansible 生成器

触发短语

当请求是生成或搭建 Ansible 内容时，使用此技能，例如：

• “创建一个通过 TLS 部署 nginx 的 playbook。”
• “生成一个用于 PostgreSQL 备份的 Ansible role。”
• “编写 prod 和 staging 的 inventory 文件。”
• “构建用于用户配置的可复用 Ansible 任务。”
• “使用 ansible.cfg 和 requirements.yml 初始化 Ansible 项目。”
• “给我一段快速安装 Docker 的 Ansible 代码片段。”

如果请求仅涉及验证/调试（语法错误、lint 失败、Molecule/测试失败），请勿将此技能用作主要工作流。这些情况请使用 ansible-validator。

确定性执行流程

按顺序运行以下阶段。除非 Validation Exceptions Matrix 明确允许，否则不要跳过任何阶段。

阶段 0：确定请求模式

首先确定一种模式：

模式	用户通常的意图	交付内容
full-generation	“创建/构建/生成”一套完整的 playbook/role/inventory/项目文件	完整文件，可用于生产环境
snippet-only	“快速代码片段/示例”，不需要完整文件上下文	精简的任务/play 代码片段
docs-only	仅需说明、模式对比或概念指导	说明内容，可附示例

阶段 1：收集最低限度的输入

如果缺少详细信息，请简要询问。如果用户未提供，则使用安全默认值，并说明假设。

资源类型	必需输入	缺失时的安全默认值
Playbook	目标主机、权限（become）、操作系统系列、目标	hosts: all、become: false、与操作系统无关的模块
Role	role 名称、主要服务/软件包、支持的操作系统	根据任务领域确定 role 名称，使用 Debian + RedHat 变量
Tasks 文件	操作范围、必需变量、执行上下文	独立可复用的任务，并附有变量说明
Inventory	环境、主机组、主机名/IP	使用占位符的 production/staging 组
项目配置	collections/role 依赖项、lint 策略	最精简的 ansible.cfg、requirements.yml、.ansible-lint

阶段 2：参考资料提取清单

起草内容之前，从本地参考资料/模板中提取以下内容。

必需的参考资料

• references/best-practices.md
  • 提取内容：FQCN 要求、幂等性规则、命名、安全要求。
• references/module-patterns.md
  • 提取内容：适用于确切任务类型的正确模块/参数模式。

按输出类型划分的必需模板

• Playbook：assets/templates/playbook/basic_playbook.yml
• Role：assets/templates/role/（包括用于测试脚手架的 meta/argument_specs.yml 和 molecule/default/）
• Inventory（INI）：assets/templates/inventory/hosts
• Inventory（YAML）：assets/templates/inventory/hosts.yml
• 项目配置：assets/templates/project/ansible.cfg、assets/templates/project/requirements.yml、assets/templates/project/.ansible-lint

提取检查项

• 找出所有必须替换的 [PLACEHOLDER]。
• 确定模块选择优先级（优先使用 ansible.builtin.*）。
• 需要特定操作系统行为时，至少记录一种适用于该操作系统的软件包模式。
• 记录必需的前置条件（collections、二进制文件、目标假设）。

阶段 3：生成

遵循以下生成标准：

1. 使用 FQCN 模块名称（首选 ansible.builtin.*）。
2. 确保任务具有幂等性（必要时使用 state、creates/removes、changed_when）。
3. 使用描述性且以动词开头的任务名称。
4. 使用 true/false 布尔值（不要使用 yes/no）。
5. 对敏感值添加 no_log: true。
6. 展示输出前替换所有占位符。
7. 对于 RHEL 8+/CentOS 8+，优先使用 ansible.builtin.dnf（仅对较旧系统使用旧版 yum）。

阶段 4：验证（默认）或应用例外（备用）

使用下表，让验证过程保持确定性且不阻塞。

验证例外矩阵

场景	默认行为	允许的回退方案	报告内容
full-generation	生成后以及每轮修复后运行 ansible-validator	如果验证器／工具不可用，则运行手动静态检查（YAML 结构、占位符扫描、FQCN／幂等性／安全性审查），并提供确切的延期验证命令	明确列出已运行、已跳过的检查及原因
snippet-only	默认跳过完整验证器；进行内联健全性检查	仅在用户提出要求或片段升级为完整文件时运行完整验证器	说明由于输出仅为片段，验证范围有限
docs-only	不进行运行时验证	无需回退	说明未生成任何可执行产物
离线环境（无法访问 Web／文档）	使用本地参考资料和模板继续操作	跳过外部文档查询；优先采用内置模块实现；提供后续外部验证说明	说明离线限制及受影响的检查／查询

资源生成指南

Playbook

• 使用 assets/templates/playbook/basic_playbook.yml 作为结构模板。
• 根据需要包含：头部注释、pre_tasks／tasks／post_tasks、处理器和标签。
• 涉及服务部署／配置时添加健康检查。

角色

• 基于 assets/templates/role/ 结构构建。
• 将默认值放在 defaults/main.yml；将优先级较高的角色变量放在 vars/main.yml。
• 相关时添加特定于操作系统的变量（vars/Debian.yml、vars/RedHat.yml）。
• 添加 meta/argument_specs.yml 以验证变量。
• 添加 molecule/default/ 脚手架（来自 assets/templates/role/molecule/），以创建可用于生产环境的角色。

任务文件

• 保持范围精简且可复用。
• 在注释中说明必需的输入变量。
• 对环境／操作系统敏感的操作使用条件判断。

Inventory

• 构建逻辑主机组和可选的组层级结构。
• 有意设置变量层级：group_vars/all.yml -> 组 -> 主机。
• 简单拓扑默认使用 INI 格式（hosts）；用户提出要求或层级结构复杂时使用 YAML 格式（hosts.yml）。

项目配置

• 提供基础配置文件 ansible.cfg、requirements.yml 和 .ansible-lint。
• 默认设置应实用且易于编辑。

自定义模块和 Collections

当请求依赖非内置模块／Collections 时：

1. 确定 Collection、模块及所需的版本敏感性。
2. 首先检查本地的 references/module-patterns.md。
3. 如果仍未解决且网络／工具可用，则查询 Context7：
   • mcp__context7__resolve-library-id
   • mcp__context7__query-docs
4. 如果 Context7 不可用，则使用 Ansible 官方文档／Ansible Galaxy 页面。
5. 如果无法进行外部查询，则提供内置模块回退方案并说明限制。

使用 Collection 模块时，始终提供 Collection 安装指南。

规范示例流程

流程 A：完整生成（Playbook）

用户提示词：“创建一个 Playbook，在 Ubuntu 和 RHEL 上部署启用 TLS 的 nginx。”

1. 将请求归类为 full-generation。
2. 收集／确认必需的输入（主机、证书路径、become、服务名称）。
3. 提取所需参考资料（best-practices.md、module-patterns.md）和 Playbook 模板。
4. 生成完整 Playbook，包含操作系统条件判断（apt／dnf）、处理器，以及对配置模板的验证。
5. 运行 ansible-validator。
6. 修复问题并重新运行，直至检查通过（或在工具不可用时按矩阵采用回退方案）。
7. 提供输出，并附上验证摘要、用法命令和前置条件。

Flow B：快速代码片段（任务块）

用户提示词：“给我一段创建用户和 SSH 密钥的代码片段。”

1. 分类为 snippet-only。
2. 提取 ansible.builtin.user 和 ansible.builtin.authorized_key 的最简模块模式。
3. 生成简洁代码片段，包含 FQCN、幂等性和变量占位符。
4. 执行内联健全性检查（YAML 结构、FQCN、明显的幂等性和安全性）。
5. 展示代码片段，并注明因处于仅代码片段模式而跳过了完整验证器运行。

输出要求

对于生成的可执行产物，请使用以下响应结构：

## Generated [Resource Type]: [Name]

**Validation Status:** [Passed / Partially validated / Skipped with reason]
- YAML syntax: [status]
- Ansible syntax: [status]
- Lint: [status]

**Summary:**
- [What was generated]
- [Key implementation choices]

**Assumptions:**
- [Defaults or inferred values]

**Usage:**
```bash
[Exact command(s)]

前置条件：

• [Collections、二进制文件、环境需求]

## Done Criteria

This skill execution is complete only when all applicable items are true:

- Trigger decision is explicit (`full-generation`, `snippet-only`, or `docs-only`).
- Required references/templates were consulted for the selected artifact type.
- Generated output has no unresolved placeholders.
- Validation followed default behavior or a documented exception from the matrix.
- Any skipped checks include a concrete reason and deferred command(s).
- Final output includes summary, assumptions, usage, and prerequisites.