1. 项目概述：一个面向基础设施即代码的智能体技能库

最近在搞基础设施即代码（IaC）自动化，发现一个挺有意思的项目叫 terramate-io/agent-skills 。这名字乍一看有点抽象，但如果你用过 Terraform、Terramate 或者关注过 AI 智能体在 DevOps 领域的应用，就能立刻嗅到它的价值。简单来说，这是一个为“智能体”（Agent）准备的“技能包”（Skills），专门用来操作和管理以 Terramate 组织的基础设施代码。

Terramate 本身是一个 Terraform 项目编排和管理工具，它通过引入堆栈（Stack）、全局代码（Globals）等概念，解决了大型 Terraform 项目中模块复用、环境隔离和依赖管理的痛点。而 agent-skills 项目，则是为了让 AI 驱动的自动化智能体（比如你基于 LangChain、AutoGPT 或者 CrewAI 搭建的助手）能够“理解”并“执行”对 Terramate 项目的各种操作。它本质上是一套标准化的工具调用接口和上下文构建规范，让智能体不再只是生成文本，而是能真正去 cd 到某个堆栈目录、运行 terramate run terraform plan 、解析输出、并根据结果决定下一步动作。

这个项目解决的核心问题是“连接”与“赋能”。在传统的 CI/CD 流水线中，步骤是预设且僵化的。而一个配备了 agent-skills 的智能体，可以根据实时情况（如 plan 输出的资源变更列表、前序步骤的成功与否）动态决策，实现更灵活、更智能的 IaC 运维流程。它适合正在探索 AIOps、希望将 AI 智能体引入基础设施变更审批、日常巡检、多环境部署等场景的 DevOps 工程师和平台团队。即使你不直接开发智能体，理解这个项目的设计思路，也能帮你更好地规划未来的自动化体系。

2. 核心设计思路：如何让智能体“学会”操作基础设施

2.1 技能（Skill）的抽象与封装

agent-skills 的核心设计思想是将对 Terramate 项目的操作抽象为一个个独立的“技能”。一个“技能”不是一个简单的 Shell 命令封装，而是一个具备完整输入、输出、执行逻辑和错误处理的可执行单元。这类似于给智能体提供了一套标准化的“瑞士军刀”，每把刀都有明确的用途。

例如，一个“运行 Terramate 脚本”的技能，其输入可能包括：目标堆栈的路径、要执行的命令、环境变量列表。其输出则不是简单的退出码，而是结构化的 JSON，包含命令的标准输出、标准错误、退出码、执行耗时，甚至可能包括从输出中提取的关键信息（如 terraform plan 生成的资源变更摘要）。这样的设计让智能体能够以编程方式“理解”操作结果，而不是去费力解析一段人类可读的文本。

这种封装带来了几个关键优势：

  1. 安全性 ：智能体只能通过预定义的技能接口与系统交互，避免了直接执行任意命令带来的安全风险。你可以在技能内部实现严格的路径检查、参数校验和权限控制。
  2. 可观测性 ：每个技能的调用都可以被记录、追踪和审计，输入输出都是结构化的数据，便于纳入现有的监控和日志体系。
  3. 可组合性 ：智能体可以像搭积木一样，将多个技能组合起来完成复杂工作流。例如，先调用“列出变更堆栈”技能，再对每个堆栈依次调用“生成执行计划”和“应用变更”技能。

2.2 上下文的构建与传递

智能体要做出合理决策，离不开丰富的上下文信息。 agent-skills 的另一个设计重点是构建和维护一个与 Terramate 项目紧密相关的上下文。这个上下文可能包括：

  • 项目结构 ：整个 Terramate 项目的根目录在哪里？有哪些堆栈？堆栈之间的依赖关系如何？
  • 堆栈状态 ：某个堆栈上一次 terraform apply 是什么时候？当前工作区是什么？有哪些输出变量？
  • 变更集 ：在 Git 中，当前分支与目标分支相比，哪些堆栈的代码发生了变更？
  • 执行历史 ：智能体本次会话已经执行了哪些技能？结果如何？

这些上下文信息，一部分通过专门的“技能”来获取（例如“获取堆栈依赖图”技能），另一部分则在技能执行过程中自动更新和维护。智能体框架（如 LangChain）可以利用这些上下文来填充工具的调用参数，或者让大语言模型基于更全面的信息进行推理。例如，当智能体被要求“部署有变更的堆栈”时，它内部的工作流可能是：1) 调用“检测变更堆栈”技能获取列表；2) 根据依赖关系上下文对列表进行排序；3) 依次对每个堆栈调用“运行计划”和“确认并应用”技能。

2.3 与智能体框架的集成模式

agent-skills 项目本身通常不包含智能体的“大脑”（即大语言模型推理部分），它提供的是“肢体”和“感官”。因此，它的设计需要考虑如何与各种主流的智能体框架无缝集成。

一种常见的模式是提供 OpenAI Functions/Tools 格式 或 LangChain Tool 格式的技能定义。这样，像 AutoGPT、LangChain 这样的框架就可以直接将这些技能注册为可用的工具。每个技能的定义会包含工具的名称、描述、参数 JSON Schema 以及对应的执行函数。当大语言模型决定调用某个工具时，框架就会执行对应的技能函数。

例如，一个“Terraform Plan 技能”在 LangChain 中可能被这样定义：

from langchain.tools import StructuredTool
from agent_skills.terraform import run_terraform_plan

plan_tool = StructuredTool.from_function(
    name="run_terraform_plan_for_stack",
    description="在指定的 Terramate 堆栈中运行 'terraform plan' 命令，并返回结构化的变更计划。",
    func=run_terraform_plan, # 这是 agent-skills 提供的函数
    args_schema=PlanArgsSchema # 定义参数，如 stack_path, refresh 等
)

然后，这个 plan_tool 就可以被加入到智能体的工具列表中，智能体在需要查看部署计划时，就会自动生成调用此工具的指令。

3. 关键技能拆解与实现要点

3.1 堆栈发现与变更检测技能

这是整个自动化流程的触发器。它的目标是准确找出需要被操作的堆栈。

实现要点：

  1. 依赖 Terramate CLI ：最可靠的方式是调用 terramate list 命令。可以通过 --changed 参数过滤出相对于某个 Git 引用（如 main 分支）发生变更的堆栈。例如： terramate list --changed --format json 。解析 JSON 输出即可获得堆栈路径列表。
  2. 处理依赖顺序 ：Terramate 堆栈间可能存在依赖（通过 stack 块中的 after 字段定义）。在部署时，必须按照依赖顺序进行。 terramate list 的 --order 参数可以确保输出顺序是正确的。这个技能需要返回有序的堆栈列表。
  3. 上下文感知 ：技能应该接受一个 base_ref 参数（如 origin/main ），用于对比变更。这允许智能体处理针对不同目标分支的变更检测。

注意事项：

注意：Git 工作树的状态（是否有未提交的更改）会直接影响 --changed 的结果。在 CI 环境中，通常是在干净的代码检出后运行，结果明确。但在开发或交互式环境中，智能体需要明确当前上下文，或者技能应提供是否包含未提交更改的选项。

3.2 Terraform 操作技能（Plan/Apply/Output）

这是最核心的一组技能，封装了 terraform plan , terraform apply , terraform output 等命令。

实现要点：

  1. 环境隔离 ：每个技能执行前，必须 cd 到目标堆栈的目录。这确保了 Terraform 操作在正确的上下文中进行，使用正确的 .tfstate 文件。
  2. 参数传递 ：技能需要支持 Terraform 命令的常用参数，如 -var-file , -target , -refresh-only , -auto-approve （对于 apply）等。这些参数应作为技能的结构化输入。
  3. 输出解析与标准化 ：这是价值所在。对于 plan 技能，不能只返回原始文本。应尝试解析输出，提取关键信息，如：
    • 变更摘要 ： Plan: X to add, Y to change, Z to destroy.
    • 资源变更列表 ：一个结构化的列表，包含每个资源的地址、操作（create, update, delete）、变更详情（旧值->新值）。这可以通过 terraform plan -json 来实现，它直接输出机器可读的 JSON。
    • 错误与警告 ：将错误和警告信息从普通输出中分离出来。
  4. 状态管理 ： apply 技能执行后，可以自动调用 output 技能，获取最新的输出变量，并更新到上下文中，供后续技能（如验证测试）使用。

实操示例（Plan技能伪逻辑）： 

import subprocess
import json
from pathlib import Path

def run_terraform_plan(stack_path: str, **tf_args) -> dict:
    """
    在指定堆栈路径执行 terraform plan。
    """
    original_cwd = Path.cwd()
    try:
        os.chdir(stack_path)
        # 构建命令，使用 -json 参数获取机器可读输出
        cmd = ["terraform", "plan", "-json", "-input=false"]
        # 添加额外参数，如 -var-file 等
        if tf_args.get("var_file"):
            cmd.extend(["-var-file", tf_args["var_file"]])
        
        process = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
        
        # 解析 JSON 行输出
        raw_lines = process.stdout.strip().split('\n')
        plan_data = {}
        changes = []
        for line in raw_lines:
            try:
                event = json.loads(line)
                if event.get("type") == "planned_change":
                    changes.append(event)
                elif event.get("type") == "change_summary"):
                    plan_data["summary"] = event
            except json.JSONDecodeError:
                # 记录非JSON行（如提示信息）
                pass
        
        plan_data["changes"] = changes
        plan_data["success"] = (process.returncode == 0)
        plan_data["raw_stderr"] = process.stderr
        return plan_data
    finally:
        os.chdir(original_cwd)

3.3 状态查询与验证技能

智能体需要知道基础设施的当前状态，才能做出明智决策。这类技能包括获取特定资源的属性、检查云资源是否健康、验证输出变量是否符合预期等。

实现要点：

  1. terraform show -json ：这是获取完整当前状态（包括资源属性和敏感值）的标准方式。可以封装一个技能，根据资源地址过滤，返回特定资源的详细信息。
  2. 云提供商原生 API ：对于更复杂的验证（如“检查 ELB 是否已将新实例加入后端”），可能需要绕过 Terraform，直接调用 AWS SDK、Google Cloud Client Library 等。这类技能需要集成云厂商的认证信息（通常从环境变量或智能体的秘密管理中获得）。
  3. 断言与健康检查 ：技能可以设计成执行一个验证脚本或一组断言，返回布尔值结果和详细的诊断信息。例如，一个“验证 Web 服务可访问”的技能，会去 curl 一个端点，检查 HTTP 状态码和响应内容。

注意事项：

直接调用云 API 的技能需要格外小心权限管理。应遵循最小权限原则，智能体使用的身份（如 IAM Role）只拥有执行必要技能所需的最低权限。避免使用全局管理员凭证。

3.4 工作流编排技能

这是更高阶的技能，它本身不直接操作 Terraform，而是协调其他技能的执行。例如，“部署所有变更堆栈”技能，内部会依次调用“变更检测”、“计划预览”、“人工审批（或自动策略审批）”、“应用变更”等一系列技能。

实现要点：

  1. 错误处理与回滚 ：工作流技能必须包含健壮的错误处理。如果某个堆栈的 apply 失败，是继续下一个，还是停止整个流程？是否需要触发一个预定义的回滚操作（例如，调用之前 plan 生成的备份）？这些策略需要在技能逻辑中体现。
  2. 用户交互点 ：在自动化流程中插入必要的审批或确认环节。例如，在 apply 之前，技能可以生成一个包含变更摘要的提示，等待用户（或另一个审批智能体）的确认指令。这可以通过更新智能体的对话上下文来实现。
  3. 并发控制 ：对于没有依赖关系的独立堆栈，是否可以并行部署以提高速度？工作流技能需要能解析堆栈依赖图，对可并行执行的步骤进行优化。

4. 实战：构建一个简单的智能体部署流程

假设我们要构建一个智能体，用于自动部署在 Pull Request 中发生变更的 Terramate 堆栈。我们将使用 agent-skills 作为工具库。

4.1 环境与依赖准备

首先，需要确保运行环境具备以下条件：

  1. Terramate & Terraform CLI ：已正确安装，并且版本与项目兼容。
  2. Git ：用于代码检出和变更检测。
  3. Python 环境 ：假设我们使用 LangChain 作为智能体框架。安装 langchain , openai （或其他 LLM 供应商 SDK）以及 agent-skills 包（或其代码）。
  4. 认证配置 ：Terraform 所需的云提供商认证（如 AWS 的 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY ，或更推荐的 IAM Role）已配置在环境变量中。
  5. 智能体框架初始化 ：设置 LLM 模型（如 GPT-4），并定义系统提示词，引导智能体专注于 IaC 部署任务。

4.2 技能工具的注册与装配

在 LangChain 中，我们需要从 agent-skills 导入或定义具体的技能函数，并将它们包装成 Tool 对象。

from langchain.agents import AgentExecutor, create_react_agent
from langchain.tools import Tool
from langchain_openai import ChatOpenAI
import agent_skills as skills

# 1. 定义技能工具
list_changed_stacks_tool = Tool(
    name="ListChangedStacks",
    func=skills.list_changed_stacks, # 返回变更堆栈列表
    description="列出相对于主分支发生变更的 Terramate 堆栈路径。"
)

terraform_plan_tool = Tool(
    name="TerraformPlan",
    func=skills.run_terraform_plan_for_stack, # 接收 stack_path 参数
    description="在指定堆栈路径运行 'terraform plan'，返回结构化的变更计划。"
)

terraform_apply_tool = Tool(
    name="TerraformApply",
    func=skills.run_terraform_apply_for_stack, # 接收 stack_path 和可选的 approval 参数
    description="在指定堆栈路径运行 'terraform apply'。需要在前置计划成功且获得批准后调用。"
)

# 2. 组合工具列表
tools = [list_changed_stacks_tool, terraform_plan_tool, terraform_apply_tool]

# 3. 初始化 LLM 和智能体
llm = ChatOpenAI(model="gpt-4", temperature=0)
prompt = """你是一个专业的 DevOps 智能体，负责管理 Terramate 项目的部署。
你的目标是安全、准确地部署发生变更的基础设施代码。
请按步骤思考，并使用提供的工具。在应用任何变更前，必须进行计划预览并确认。
"""
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

4.3 智能体执行与交互逻辑

现在，我们可以向智能体执行器发出一个自然语言指令，触发整个流程。

# 启动智能体工作流
result = agent_executor.invoke({
    "input": "请检查当前项目相对于 origin/main 分支的变更，并部署所有发生变更的堆栈。在应用每个堆栈前，需要向我展示计划并等待我的确认。"
})

在这个过程中，智能体会自主决定调用工具的次序：

  1. 首先调用 ListChangedStacks ，获取堆栈列表 ["./stacks/network", "./stacks/app"] 。
  2. 对于第一个堆栈 ./stacks/network ，调用 TerraformPlan 。它会将计划结果（以结构化或摘要文本形式）返回给智能体。
  3. 智能体“理解”了计划内容，然后生成一段话向用户（或交互界面）展示变更摘要，并请求确认。
  4. （关键交互点） 用户回复“确认部署网络堆栈”。这个确认信息被反馈给智能体。
  5. 智能体调用 TerraformApply ，并附带 ./stacks/network 作为参数。
  6. 应用成功后，智能体转向下一个堆栈 ./stacks/app ，重复步骤 2-5。

4.4 流程优化与策略注入

上述基本流程可以进一步优化：

  • 并行计划 ：对于无依赖的堆栈， TerraformPlan 可以并行执行，加快反馈速度。
  • 策略审批 ：替代人工确认，可以集成一个“自动审批策略”技能。该技能基于预定义规则（如“仅修改标签，无资源创建或销毁”）对 plan 结果进行评估，自动返回批准或拒绝。
  • 状态同步 ：在应用每个堆栈后，自动调用一个“更新部署状态”的技能，将结果写入外部系统（如 GitHub Commit Status、Slack 通知），实现闭环可观测。

5. 常见问题、排查技巧与经验之谈

在实际集成和使用 agent-skills 这类项目时，会遇到一些典型问题。

5.1 权限与安全问题

问题1：智能体权限过大。

  • 现象 ：智能体可以操作任何堆栈，包括生产环境，风险极高。
  • 排查与解决 ：
    • 环境隔离 ：为智能体设置不同的执行环境（如 Docker 容器或独立虚拟机），每个环境仅配置特定目标（如仅开发、仅预发）的凭证。
    • 动态凭证 ：不要使用长期静态密钥。集成云厂商的临时安全凭证服务（如 AWS STS）。智能体在需要执行操作前，先调用一个“获取临时凭证”的技能。
    • 技能级权限 ：在技能内部实现额外的校验。例如，在 apply 技能中，检查目标堆栈的路径或标签，如果包含 prod 字样，则要求更高级别的审批令牌。

问题2：敏感信息泄露。

  • 现象 ： terraform plan/apply 的输出或 state 中可能包含密码、密钥等敏感信息，这些信息被完整地传给了 LLM。
  • 排查与解决 ：
    • 输出过滤 ：在技能层对 Terraform 的 JSON 输出进行清洗，使用 sensitive 标记（Terraform 会标注）来过滤或替换敏感值。
    • LLM 上下文管理 ：避免将完整的、包含敏感数据的输出作为历史对话上下文传递给 LLM。只传递提炼后的摘要信息。

5.2 执行环境与状态管理

问题3：技能执行状态不一致。

  • 现象 ：智能体在长时间对话中，可能忘记之前执行过 plan ，或者在不同技能调用间，工作目录、环境变量发生了意外的改变。
  • 排查与解决 ：
    • 上下文持久化 ：设计一个集中的上下文管理服务。每个技能执行前后，都将关键状态（如当前堆栈、上一个 plan 的结果 ID）写入该服务。下一个技能执行前，先读取上下文。
    • 技能设计的幂等性 ：确保技能可以安全地重复执行。例如， plan 技能在发现目标堆栈已存在最新计划文件时，可以直接读取该文件，而无需重新运行命令。
    • 隔离执行环境 ：每个技能调用都在一个干净的子进程或临时容器中执行，确保环境隔离。代价是会有一些性能开销。

问题4：命令执行超时或挂起。

  • 现象 ： terraform apply 某个资源时可能耗时极长（如创建 AWS RDS 实例），导致技能调用超时。
  • 排查与解决 ：
    • 异步执行与轮询 ：将长耗时操作改为异步。 apply 技能只负责启动一个部署任务，并立即返回一个任务 ID。然后提供一个“检查部署状态”的技能，供智能体后续轮询。
    • 设置合理超时 ：根据操作类型设置不同的超时时间。 plan 可以短一些（如2分钟）， apply 则需要更长（如30分钟）。在技能代码中明确设置 subprocess.run 的 timeout 参数。

5.3 与LLM的协同与提示工程

问题5：LLM 不理解技能或错误调用。

  • 现象 ：智能体在不需要的时候调用了 apply ，或者传递了错误的参数格式。
  • 排查与解决 ：
    • 清晰的工具描述 ：在定义 Tool 时， description 字段至关重要。要清晰、无歧义地说明工具的用途、输入参数和输出。例如，写明“此工具用于应用变更， 必须在成功的计划预览之后调用 ”。
    • 系统提示词优化 ：在给 LLM 的系统指令中，明确工作流规则。例如：“你必须严格遵守以下流程：1. 先列出变更；2. 对每个堆栈，先执行计划；3. 向我报告计划摘要；4. 获得我的明确批准后，才能执行应用。”
    • 输出格式引导 ：让技能的返回值更易于 LLM 理解。返回一个包含 summary_for_llm 字段的字典，这个字段是专门用自然语言写给 LLM 看的摘要，而不是只有机器可读的数据。

问题6：处理复杂或意外的 Terraform 输出。

  • 现象 ： terraform plan 可能因为配置错误而失败，输出复杂的错误信息。LLM 可能无法准确诊断。
  • 排查与解决 ：
    • 错误分类技能 ：实现一个“分析 Terraform 错误”的技能。它接收错误信息，尝试匹配常见错误模式（如 provider 认证失败、语法错误、资源限制等），并返回一个分类结果和修复建议。这个建议再提供给 LLM 或用户。
    • 让人类介入 ：对于无法分类的复杂错误，技能应返回一个标志，指示需要人工干预。智能体则停止自动化流程，将完整错误信息转给工程师。

从我的实践经验来看，成功的关键不在于让智能体完全取代人类，而是让它成为人类工程师的高效副驾驶。 agent-skills 这类项目提供了标准化的“操作手柄”，让我们能够将重复、繁琐、模式化的 IaC 操作任务委托给智能体，而工程师则专注于处理异常、制定策略和审核关键变更。初期投入在技能设计、上下文管理和提示工程上的时间，会在日后成百上千次的自动化执行中得到丰厚的回报。最重要的是，始终保持对自动化流程的监控和审计能力，确保智能体的每一步操作都在可控、可见的范围内。

# AI智能体
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

大 硬 仗14小时：用2009年的上古亮机卡跑完深度学习，CPU满载但代码没崩

avatar 亚马逊云科技技术品牌专区
cover

害虫检测和识别3：基于深度学习YOLO26神经网络实现害虫检测和识别(含训练代码、数据集和GUI交互界面）

avatar 亚马逊云科技技术品牌专区
cover

原来AI、画图、导航都在用向量！

avatar 亚马逊云科技技术品牌专区