Ansible 生成器

触发短语

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

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

当请求仅涉及验证/调试（如语法错误、lint 失败、Molecule/测试失败）时，**不得**将本技能作为主工作流。此类场景请使用 ansible-validator。

确定性执行流程

按顺序执行以下阶段。除非 验证异常矩阵 明确允许，否则不得跳过任一阶段。

阶段 0：识别请求模式

首先确定唯一一种模式：

阶段 1：收集最小输入

若缺少必要细节，请简要询问；若用户未提供，则采用安全默认值，并明确声明所做假设。

阶段 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.*）。
• 当需要 OS 特定行为时，至少捕获一种适配该 OS 的软件包安装模式。
• 捕获所需前置条件（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：验证（默认）或应用异常（回退）

使用下方矩阵确保验证过程确定且非阻塞。

验证异常矩阵

资源生成指南

Playbook

• 以 assets/templates/playbook/basic_playbook.yml 为结构基础。
• 包含：头部注释、按需使用的 pre_tasks/tasks/post_tasks、handlers、tags。
• 若涉及服务部署/配置，应添加健康检查逻辑。

Role

• 基于 assets/templates/role/ 结构构建。
• 将默认变量置于 defaults/main.yml；将高优先级 role 变量置于 vars/main.yml。
• 在必要时，添加 OS 特定变量文件（如 vars/Debian.yml、vars/RedHat.yml）。
• 通过 meta/argument_specs.yml 实现变量校验。
• 为生产就绪的 role 添加 molecule/default/ 脚手架（源自 assets/templates/role/molecule/）。

Task 文件

• 保持作用域窄、可复用性强。
• 在注释中明确定义所需输入变量。
• 对环境/OS 敏感的操作使用条件判断（when）。

Inventory

• 构建逻辑清晰的主机组，可选支持组层级关系。
• 有意使用变量分层机制：group_vars/all.yml → 组级变量 → 主机级变量。
• 简单拓扑默认使用 INI 格式（hosts）；当用户明确要求或层级复杂时，改用 YAML 格式（hosts.yml）。

项目配置

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

自定义模块与 Collections

当请求依赖非内置模块/collections 时：

1. 识别所需 collection + module 及其版本敏感性要求。
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）

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

1. 判定为 full-generation 模式。
2. 收集/确认必需输入（目标主机、证书路径、become 设置、服务名）。
3. 提取必需参考文档（best-practices.md、module-patterns.md）及 playbook 模板。
4. 生成完整 playbook，含 OS 条件分支（apt/dnf）、handlers、配置模板校验逻辑。
5. 运行 ansible-validator。
6. 修复问题并重试，直至全部检查通过（或在工具不可用时应用矩阵回退策略）。
7. 输出结果需包含验证摘要、使用命令及前置条件。

流程 B：快速代码片段（Task Block）

用户提示：“给我一个创建用户并配置 SSH 密钥的代码片段。”

1. 判定为 snippet-only 模式。
2. 提取 ansible.builtin.user 和 ansible.builtin.authorized_key 的最小模块模式。
3. 生成简洁代码片段，含 FQCN、幂等性保障及变量占位符。
4. 执行内联合理性检查（YAML 结构、FQCN、明显幂等性/安全性）。
5. 输出代码片段，并注明因处于 snippet-only 模式而跳过了完整 validator 运行。

输出要求

对于生成的可执行产物，须采用如下响应结构：

## 生成的 [资源类型]：[名称]

**验证状态：** [通过 / 部分验证 / 因原因跳过]
- YAML 语法：[状态]
- Ansible 语法：[状态]
- Lint：[状态]

**摘要：**
- [生成了什么]
- [关键实现决策]

**假设：**
- [默认值或推断值]

**使用方法：**
```bash
[精确命令]
```

前置条件：

• [collections、二进制依赖、环境需求]

## 完成标准

本技能执行仅在满足以下全部条件时视为完成：

- 触发决策明确（为 full-generation、snippet-only 或 docs-only 之一）。
- 已针对选定产物类型查阅必需的参考文档/模板。
- 生成输出中无未解析的占位符。
- 验证过程遵循默认行为，或严格依据矩阵中记录的例外情形执行。
- 所有跳过的检查均附带具体原因及对应的延迟验证命令。
- 最终输出包含摘要、假设、使用方法及前置条件。