1. 项目概述：当AI助手成为你的AWS云管家

如果你和我一样，管理着几个甚至几十个AWS账户，每天在控制台、CLI、不同配置文件之间反复横跳，那一定对那种“琐碎感”深恶痛绝。查个成本要跑好几个报表，给新同事开权限得手动组合一堆IAM策略，做安全审计更是像在玩“大家来找茬”——费时、易错，还特别消耗心力。

最近，我把这套烦人的日常彻底交给了AI。不是那种需要复杂API集成的“智能平台”，而是一个纯粹由文件构成的工具箱： aws-manager 。它的核心思想简单到有点“复古”：用AI能直接读懂和执行的脚本、配置和工作流，把那些重复的AWS管理任务自动化。你只需要用自然语言告诉你的AI编程助手（比如Claude Code、Cursor）你想做什么，它就能自己找到对应的“操作手册”（Markdown工作流），调用正确的“工具”（Bash脚本），然后干净利落地把事情办妥。

这个项目没有Web界面，没有数据库，也不需要你学任何新工具。它本质上是一套高度结构化的、面向AI的“操作契约”。所有东西都是文件：配置是JSON，指令是Markdown，逻辑是Shell脚本，状态也是JSON。AI代理天生就擅长阅读和处理文件，所以它能无缝接入，成为你在云端的“副驾驶”。

注意 ：这套工具的核心是“增强”，而非“替代”。它不处理核心业务逻辑，也不做复杂的决策判断。它的价值在于把那些确定性的、流程化的运维操作标准化、自动化，让你和你的AI助手能把精力集中在更有价值的事情上。

2. 核心设计思路：为什么是“文件优先”和“AI原生”

在决定构建aws-manager时，我评估过很多方向。市面上有Terraform、Pulumi这样的IaC工具，也有AWS Control Tower、Organizations这样的原生服务，还有各种第三方SaaS管理平台。但它们要么学习曲线陡峭，要么不够灵活，要么无法与AI助手进行“深度对话”。

2.1 摒弃复杂抽象，回归可读性

我最终选择了“文件优先”的架构，原因有三：

第一， 极致的透明度和可调试性 。所有操作逻辑都平铺在 scripts/ 目录下的Shell脚本里。AI执行了哪条命令，输入输出是什么，一目了然。如果结果不符合预期，你可以直接打开脚本查看逻辑，甚至手动执行一遍来复现问题。这比去理解一个封装了多层抽象的黑盒SDK要直观得多。

第二， 无状态和可移植性 。整个工具集就是一堆文本文件，用 git clone 就能完整复制。没有运行时依赖（除了AWS CLI和jq），没有需要维护的服务状态。你可以在本地开发机、CI/CD流水线、甚至临时启动的容器里使用它，环境一致性极高。

第三， 对AI的天然亲和力 。当前主流的AI编码助手，其核心能力是理解和生成文本（代码、配置、文档）。让AI去调用一个专用的REST API，它需要学习接口规范；但让它读一个Markdown文件然后执行里面的Shell命令，这几乎是它的“母语”。这种设计极大地降低了AI的使用门槛。

2.2 工作流与脚本的分离：清晰的关注点

项目结构清晰地划分了“做什么”（Workflow）和“怎么做”（Script）。

workflows/ 目录下的每个 .md 文件，都是一个完整的任务指南。比如 onboard-user.md ，它会详细描述：“要为新用户John开通开发权限，你需要依次完成以下步骤：1. 确认目标账户。2. 运行 create-iam-user.sh 创建用户。3. 运行 grant-policy.sh 附加开发策略。4. 安全地传递凭证。” AI助手阅读这个文件，就能理解任务的全貌和步骤间的依赖关系。

scripts/ 目录下的每个 .sh 文件，则是一个原子操作。比如 create-iam-user.sh ，它只负责一件事：接收用户名、策略等参数，调用AWS CLI创建IAM用户，生成访问密钥，并输出结构化的JSON结果。它不关心这个用户是为何创建，也不关心后续还要做什么。

这种分离带来了巨大的灵活性。你可以让人工根据工作流手动执行，也可以让AI自动串联。你甚至可以基于现有的原子脚本，组合出全新的工作流，而无需修改任何脚本代码。

2.3 状态管理：为连续性会话提供记忆

AI助手的一个局限是“健忘症”，每次会话都是新的开始。aws-manager通过 state/ 目录巧妙地解决了这个问题。

每次执行资源扫描（ scan-resources.sh ）或成本分析（ scan-costs.sh ），结果都会以JSON格式保存到 state/<account-alias>/ 下。当AI助手在新会话中接手时，它可以先读取这些状态文件，立刻获得当前云环境的全景视图，比如“账户A下有10台EC2，其中3台最近一周CPU利用率低于5%”，而不需要重新扫描一遍，节省了大量时间和API调用。

state/history.jsonl 文件则记录了所有的操作历史，格式为JSON Lines。这不仅是审计日志，更是AI的“经验记忆”。AI可以回顾：“上次为项目‘web-app’创建Terraform后端是在什么时间？谁操作的？” 这为问题排查和变更追溯提供了可靠依据。

3. 实战部署与核心脚本解析

理论说得再多，不如动手搭一遍。下面我就带你从零开始，部署并使用aws-manager，并深入看看几个核心脚本是怎么工作的。

3.1 环境准备与快速启动

前提条件非常简单：

1. AWS CLI v2 ：确保已安装并配置了至少一个拥有适当权限的AWS Profile（例如通过 aws configure sso 或 aws configure ）。
2. jq ：一个轻量级的命令行JSON处理器，用于解析脚本输出。macOS用户可通过 brew install jq 安装。

部署就是一行命令：

git clone https://github.com/cyphercodes/aws-manager.git
cd aws-manager

接下来，最“AI原生”的启动方式就是直接告诉你的AI助手：“请为我的当前AWS账户初始化aws-manager。” 它会自动执行 scripts/init-account.sh 。

不过，理解背后发生了什么很重要。我们可以手动执行一下：

./scripts/init-account.sh my-prod

这个脚本做了以下几件关键事：

1. 身份验证 ：它调用 aws sts get-caller-identity ，获取当前CLI凭证对应的账户ID、用户ARN等信息。这是所有操作的安全基石。
2. 信息收集 ：它会尝试获取账户别名、默认区域等信息。
3. 配置生成 ：基于收集的信息，在 accounts/ 目录下生成一个如 my-prod.json 的配置文件。这个文件 默认被 .gitignore ，确保你的账户敏感信息不会误提交。
4. 上下文切换 ：它最后会调用 use-account.sh my-prod ，将当前Shell的AWS上下文切换到新配置的账户。

实操心得 ：我强烈建议在初始化任何生产环境账户前，先在一个沙盒或测试账户上操作。你可以通过 aws sso login --profile sandbox 切换profile，再运行初始化脚本。这能帮你熟悉流程，并验证你的IAM权限是否足够（脚本需要 sts:GetCallerIdentity 等基础权限）。

3.2 核心脚本深度剖析

aws-manager的威力来自于它的脚本。我们挑三个最常用的来看看其设计精妙之处。

scan-resources.sh ：你的云资源清单生成器

这是使用频率最高的脚本之一。它的目标不是替代AWS Config或第三方监控工具，而是提供一个快速、轻量、可脚本化的资源盘点方式。

#!/bin/bash
# 简化后的核心逻辑
source ./scripts/common.sh

account_alias=${1:-$(get_current_account_alias)}
region=${2:-$(get_primary_region $account_alias)}

# 使用AWS CLI并借助jq构造结构化输出
echo "Scanning EC2 instances..."
instances=$(aws ec2 describe-instances --region $region \
  --query 'Reservations[].Instances[].[InstanceId, InstanceType, State.Name, LaunchTime]' \
  --output json | jq -c 'map({id: .[0], type: .[1], state: .[2], launched: .[3]})')

# 扫描其他服务：RDS, Lambda, S3 Buckets等...
# ...

# 合并所有结果，并保存状态
final_output=$(jq -n \
  --argjson ec2 "$instances" \
  --arg scanned_at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
  '{account: $account_alias, region: $region, scanned_at: $scanned_at, resources: {ec2: $ec2, rds: $rds, lambda: $lambda, s3: $s3}}')

echo $final_output | jq '.' # 漂亮打印到终端
echo $final_output > "state/$account_alias/resources-$(date +%Y%m%d).json" # 保存快照

它的价值在于输出是结构化的JSON。AI助手可以直接解析这个JSON，回答诸如“我们有多少台运行中的 t3.micro 实例？”或者“列出所有没有 Project 标签的S3桶”这类问题。保存的快照文件，则使得下一次扫描后可以进行 diff ，轻松发现资源的新增、减少或配置变更。

scan-costs.sh ：成本洞察与异常预警

云账单不可预测是常态。这个脚本通过AWS Cost Explorer API，把成本数据变得可查询、可分析。

./scripts/scan-costs.sh my-prod --month 2024-04

关键功能点：

1. 本月至今（MTD）总成本 ：快速了解当前消费水平。
2. 月度预测 ：基于已发生的成本，预测本月结束时的总费用。这是控制预算的早期警报。
3. 按服务细分 ：列出消费最高的前5项AWS服务。你经常会发现，某个不起眼的服务（如Data Transfer或Secrets Manager）才是真正的“成本刺客”。
4. 每日趋势 ：输出本月每天的消费折线图数据，便于发现异常峰值。
5. 异常检测（核心） ：脚本内嵌了一个简单的逻辑：与上月同期相比，如果任何服务的成本增长超过 config.yaml 中设定的阈值（默认20%），它会在输出中高亮标记 ANOMALY 。AI助手可以据此立即向你报告：“警告：四月份EC2成本同比上月增长35%，建议检查是否有实例未关机。”

create-iam-user.sh ：安全、标准的用户创建流程

手动创建IAM用户容易出错，比如忘记启用控制台密码、漏加MFA、或者把密钥直接打印在终端历史里。这个脚本将最佳实践固化了下来。

./scripts/create-iam-user.sh alice --policy policies/developer.json --create-login-profile

它执行的操作序列是：

1. 创建IAM用户 alice 。
2. 生成一个随机的、符合复杂性要求的初始密码（如果你指定了 --create-login-profile ）。
3. 创建一组编程访问密钥（Access Key / Secret Key）。
4. 将指定的策略（如 policies/developer.json ）附加到用户。
5. 输出一个清晰、安全的总结 ：用户名、ARN、密码（仅显示一次）、Access Key ID。它会明确提示用户保存Secret Key，并建议立即登录控制台更改密码和设置MFA。
6. 自动记录 ：通过 log-action.sh 将此次创建行为记录到历史中。

重要安全提示 ：尽管脚本简化了流程，但凭证的传递必须通过安全渠道（如公司内部的密码管理器、加密邮件等）。绝对避免通过不安全的聊天工具发送Secret Key。 config.yaml 中的 safety.require_confirmation: true 设置，可以强制AI在执行此类操作前与你二次确认。

4. 工作流驱动：让AI理解复杂任务

单个脚本能力有限，真正的威力在于通过工作流（Workflow）将它们串联起来，完成一个多步骤的、有上下文的目标。工作流文件是写给AI（和人）的详细说明书。

4.1 剖析一个典型工作流： workflows/onboard-user.md

我们以“ onboarding a user”这个常见任务为例，看看工作流如何指导AI。

# Onboard a New Teammate

## Purpose
To securely provision AWS access for a new team member with appropriate permissions.

## Prerequisites
- You have already initialized the target AWS account using `init-account.sh`.
- You know the new user's username (e.g., `john.doe`).
- You have decided on the access level (Developer, Read-Only, etc.).

## Steps

### 1. Determine Target Account and Context
- Run `./scripts/whoami.sh` to confirm current AWS context.
- If needed, switch to the correct account using `./scripts/use-account.sh <alias>`.

### 2. Create the IAM User
- Run the user creation script:
  ```bash
  ./scripts/create-iam-user.sh <username> --policy policies/<role>.json --create-login-profile

• Choose the right policy :
  • developer.json : For engineers who need to deploy and debug.
  • read-only.json : For auditors, managers, or analysts.
  • terraform-full-access.json : For infrastructure CI/CD pipelines.
• The script will output credentials. You must relay these securely to the user.

3. Verify and Log

• Run ./scripts/scan-iam.sh to confirm the user appears in the IAM list with the correct attached policies.
• The action is automatically logged by the script. You can also note the onboarding in your team's internal system.

Safety Notes

• Always confirm the username and account with the requester.
• Never store or send credentials over unencrypted channels.
• Remind the new user to enable MFA immediately upon first login.

当AI助手（如Claude Code）接收到指令“Onboard John as a developer on our production account”时，它会：
1.  在项目文件中搜索相关指南，找到`onboard-user.md`。
2.  阅读理解整个流程、前提条件和安全须知。
3.  开始逐步执行：先确认当前账户，切换到生产账户，然后运行创建用户的脚本，并选择合适的`developer.json`策略。
4.  在整个过程中，它会基于工作流里的提示，主动与你交互（“确认要为John使用developer策略吗？”、“这是生成的临时密码，请通过安全渠道发送”）。

### 4.2 工作流的设计哲学：确定性与灵活性

好的工作流像一份优秀的食谱，精确到克和秒，但也会告诉你“根据口味调整”。aws-manager的工作流遵循以下原则：

-   **步骤原子化**：每个步骤对应一个明确的、可执行的命令。避免“配置网络设置”这种模糊描述，而是“运行`create-subnet.sh --name app --cidr 10.0.1.0/24`”。
-   **决策点清晰**：在需要选择的地方（比如选择IAM策略），明确列出所有选项及其适用场景，帮助AI做出合理建议。
-   **安全前置**：在每个可能涉及资源变更或安全风险的工作流开头或关键步骤，加入“Safety Notes”或“Confirmation”提醒。这通过`config.yaml`的`safety.require_confirmation`设置得以强制执行。
-   **上下文衔接**：工作流会告诉AI如何获取必要信息（如先运行`scan-resources`了解现状），以及如何保存结果状态（如将扫描结果保存到`state/`），确保任务链的连续性。

## 5. 多账户管理与全局配置

对于拥有开发、测试、生产等多套环境的团队，aws-manager的多账户管理机制显得尤为重要。它的设计既保持了隔离性，又提供了统一的操作视图。

### 5.1 账户配置的隔离与共享

每个AWS账户在`accounts/`目录下都有一个独立的JSON配置文件，例如`accounts/acme-prod.json`和`accounts/acme-dev.json`。文件内容包含了该账户的元数据：

```json
{
  "name": "Acme Corp Production",
  "alias": "acme-prod",
  "account_id": "123456789012",
  "primary_region": "us-east-1",
  "additional_regions": ["eu-west-1", "ap-southeast-2"],
  "profile": "acme-prod-sso",
  "projects": [
    {
      "name": "customer-portal",
      "region": "us-east-1",
      "iac": "terraform",
      "services": ["ecs", "aurora", "cloudfront", "waf"]
    }
  ],
  "iam_users": ["alice", "bob", "charlie"],
  "tags": {
    "Owner": "PlatformTeam",
    "Environment": "Production"
  }
}

关键字段解析 ：

• alias ：这是你在aws-manager内部指代该账户的简短标识符，用于所有脚本的 [alias] 参数。
• profile ：对应你本地 ~/.aws/config 中的AWS CLI profile名称。脚本通过 --profile 参数来切换凭证。
• projects ：这是一个可选的、自定义的结构，用于记录该账户内的重要项目及其使用的技术栈。这帮助AI在后续操作中理解上下文，例如，“清理 customer-portal 项目”意味着要删除与之相关的特定资源集合。
• tags ：定义的全局标签，可以在资源创建脚本中被引用，确保资源标记的一致性。

账户配置文件被 .gitignore ，因此你可以放心地将aws-manager仓库在团队内共享，而不会泄露任何人的账户ID或Profile名称。每个成员克隆仓库后，需要用自己的凭证运行 init-account.sh 来生成自己的配置文件。

5.2 使用 use-account.sh 进行无缝切换

这是多账户操作的核心脚本。它的作用不仅仅是设置环境变量 AWS_PROFILE 。

./scripts/use-account.sh acme-prod

它实际执行了以下操作：

1. 验证配置 ：检查 accounts/acme-prod.json 文件是否存在。
2. 凭证验证 ：使用指定的profile调用 aws sts get-caller-identity ，确保凭证有效且未过期。如果失效，它会明确报错，提示你重新登录（ aws sso login ）。
3. 设置环境 ：导出 AWS_PROFILE 、 AWS_DEFAULT_REGION （从配置中读取）等环境变量，确保后续的所有AWS CLI命令都在正确的上下文中执行。
4. 输出上下文 ：打印出当前切换到的账户名、ID和区域，提供明确的视觉反馈。

避坑技巧 ：如果你使用AWS SSO，可能会遇到会话过期问题。一个实用的做法是在团队中推广使用 aws sso login --profile xxx 来刷新登录。你甚至可以在 common.sh 中添加一个辅助函数，在 use-account.sh 验证失败时自动尝试重新登录（需谨慎，因为涉及凭证刷新）。

5.3 全局控制： config.yaml

config.yaml 是aws-manager的“大脑”，它定义了一些跨账户的全局策略和行为。

budget:
  mode: warn              # 可选：off（关闭）, warn（警告）, block（阻止-实验性）
  monthly_alert_usd: 1000 # 当月预测费用接近此值时触发警告

safety:
  require_confirmation: true   # 对任何可能创建、修改、删除资源的操作要求确认
  require_tags: true           # 在创建资源时，强制要求提供 Name 和 Project 标签
  log_all_actions: true        # 将所有脚本执行记录到 history.jsonl

scan:
  default_regions: ["us-east-1", "us-west-2"] # 执行跨区域扫描时的默认区域列表
  resource_types: ["ec2", "s3", "rds", "lambda"] # 资源扫描涵盖的服务

• 预算告警 ：当 scan-costs.sh 检测到月度预测费用超过 monthly_alert_usd 的90%时，如果 mode 设为 warn ，输出中会包含明显的 [BUDGET ALERT] 标记。AI助手可以捕获这个标记并立即通知你。
• 安全护栏 ： require_confirmation: true 是至关重要的安全网。当AI尝试运行 create-iam-user.sh 或 teardown-project.sh 时，脚本会暂停并输出“即将执行XXX操作，是否继续？(y/N)”。这防止了因AI误解指令而导致的意外变更。
• 标签策略 ： require_tags: true 与资源创建脚本配合，强制实施标签规范。这对于成本分摊、资源管理和自动化清理至关重要。

6. 常见问题排查与实战技巧

在实际使用中，你可能会遇到一些问题。下面是我总结的一些常见场景及其解决方法。

6.1 权限不足导致的脚本失败

这是最常见的问题。aws-manager的脚本需要调用AWS API，因此执行用户的IAM角色必须有相应权限。

症状 ：运行脚本时出现 An error occurred (AccessDenied) when calling the DescribeInstances operation: User: arn:aws:iam::... is not authorized to perform: ec2:DescribeInstances...

排查步骤 ：

1. 确认当前身份 ：立即运行 ./scripts/whoami.sh 。它会告诉你当前正在使用哪个AWS账户和IAM用户/角色。很可能你还在默认账户，而不是目标账户。
2. 切换账户 ：使用 ./scripts/use-account.sh <alias> 切换到正确的账户上下文。
3. 验证权限 ：如果账户正确，那问题在于当前身份权限不足。你需要检查该IAM实体（用户或角色）附加的策略。一个快速的方法是让有权限的用户运行 ./scripts/scan-iam.sh 来查看该用户的策略附件。
4. 补充权限 ：根据缺失的权限，更新对应的IAM策略。aws-manager的 policies/ 目录下的模板可以作为参考基准。例如， developer.json 通常包含了执行大多数脚本所需的基本只读和部分写入权限。

建议 ：为使用aws-manager的IAM角色附加一个包含必要权限的托管策略，或基于 policies/terraform-full-access.json 进行裁剪。确保权限范围最小化。

6.2 AI助手无法正确解析工作流或输出

症状 ：AI助手回复“我不确定该如何操作”或执行了错误的步骤。

排查步骤 ：

1. 检查AI的上下文 ：确保AI助手（如Cursor、Claude Code）的当前工作区（workspace）已经打开了你本地的aws-manager项目根目录。这样它才能看到所有的脚本、工作流和配置文件。
2. 引导AI阅读入口文件 ：明确指示AI：“请先阅读并理解 .agent/workflows/aws-manager.md 文件中的指南。” 这个文件是AI的“总说明书”，定义了操作契约。
3. 提供结构化指令 ：给你的指令增加更多上下文。不要只说“扫描资源”，而是说“请遵循 resource-inventory.md 工作流，使用 scan-resources.sh 脚本，对 acme-prod 账户进行资源扫描，并将结果与上周的存档进行比较。”
4. 检查输出格式 ：如果AI无法解析脚本输出，可能是因为输出不是纯JSON。确保脚本被正确调用，并且没有将调试信息打印到标准输出。所有核心脚本都设计为在成功时输出干净的JSON，错误信息则打印到标准错误（stderr）。

6.3 状态文件冲突或过时

症状 ：AI基于旧的状态文件做出了错误判断，比如认为某个S3桶还存在，但实际上已被手动删除。

解决方案 ：

1. 定期更新状态 ：将资源扫描纳入日常或每周的自动化任务。你可以写一个简单的cron job或GitHub Actions工作流，定期执行 scan-resources.sh 和 scan-costs.sh ，并提交状态文件到git（注意忽略敏感信息）。这样能保证状态文件相对新鲜。
2. 强制刷新 ：在给AI下指令时，明确要求“请先刷新状态”，即先运行扫描脚本生成最新的状态文件，再基于新数据进行分析。
3. 理解状态文件的局限性 ： state/ 目录下的文件是 快照 ，不是 事实来源 。AWS控制台或CLI才是权威来源。对于关键操作（如删除资源），AI应被工作流要求在执行前进行实时验证（例如，先运行 aws s3 ls 确认桶是否存在）。

6.4 在团队中协作使用

挑战 ：如何让团队成员共享工作流，但又隔离各自的AWS账户配置？

最佳实践 ：

1. 共享仓库 ：将aws-manager的代码库（不包括 accounts/ 和 state/ 目录，它们已被 .gitignore ）放在团队的版本控制系统中（如GitHub、GitLab）。
2. 个人配置 ：每个团队成员在本地克隆仓库后，独立运行 init-account.sh 来生成自己的 accounts/ 配置文件。
3. 标准化策略模板 ：团队共同维护 policies/ 目录下的IAM策略模板，确保不同角色（开发、运维、审计）的权限基线一致。
4. 自定义工作流 ：团队可以根据常用的运维场景，在 workflows/ 下创建自己的定制化工作流（例如 deploy-canary.md , respond-to-security-alert.md ）。
5. 中央状态存储（可选） ：对于需要团队共享的状态（如所有账户的资源清单摘要），可以考虑将 state/ 下非敏感的分析结果（如聚合的成本报告、资源计数）定期上传到一个安全的、团队可访问的位置（如一个加密的S3桶），但 绝对不要 上传包含账户ID或资源标识符的详细状态文件。

7. 扩展与定制：让工具适应你的团队

aws-manager的开箱即用功能已经很强大了，但它的真正潜力在于其可扩展性。你可以轻松地定制它，以适应你团队独特的工作流程和技术栈。

7.1 编写自定义脚本

假设你的团队大量使用Amazon ECS，你需要一个快速列出所有ECS集群和服务状态的脚本。只需在 scripts/ 目录下创建一个新文件，例如 list-ecs-services.sh 。

#!/bin/bash
# scripts/list-ecs-services.sh
source ./scripts/common.sh

account_alias=${1:-$(get_current_account_alias)}
region=${2:-$(get_primary_region $account_alias)}
cluster_name=${3:-""} # 可选参数，指定特定集群

echo "Listing ECS services in $region for account $account_alias..." >&2

# 获取集群列表
if [[ -z "$cluster_name" ]]; then
  clusters=$(aws ecs list-clusters --region $region --query 'clusterArns[]' --output text)
else
  clusters="arn:aws:ecs:$region:$(get_account_id $account_alias):cluster/$cluster_name"
fi

result="[]"
for cluster_arn in $clusters; do
  cluster_short=$(echo $cluster_arn | awk -F'/' '{print $2}')
  services=$(aws ecs list-services --cluster $cluster_short --region $region --query 'serviceArns[]' --output text)
  for service_arn in $services; do
    service_short=$(echo $service_arn | awk -F'/' '{print $3}')
    # 获取服务详情
    service_desc=$(aws ecs describe-services --cluster $cluster_short --services $service_short --region $region)
    # 使用jq提取关键信息并合并到结果中
    result=$(echo $result | jq --argjson desc "$service_desc" '. += [$desc.services[0] | {cluster: .clusterArn, serviceName: .serviceName, status: .status, runningCount: .runningCount, desiredCount: .desiredCount}]')
  done
done

echo $result | jq '.'
log_action "$account_alias" "list-ecs-services" "$cluster_name" "success"

关键点 ：

1. 遵循模式 ：开头 source ./scripts/common.sh 以加载辅助函数（如 log_action , get_account_id ）。
2. 参数处理 ：使用位置参数或 getopts 处理输入，并提供默认值。
3. 结构化输出 ：始终以JSON格式输出结果，方便AI解析和后续处理。
4. 错误处理 ：使用 set -e 或在关键命令后检查 $? ，确保脚本在失败时优雅退出。
5. 记录日志 ：最后调用 log_action 记录此次操作。

创建后，记得更新 .agent/workflows/aws-manager.md 文件，将你的新脚本添加到“可用脚本”列表中，并简要说明其用途和参数。

7.2 创建定制化工作流

工作流是连接业务需求和技术操作的桥梁。假设你的团队有一个标准的“新微服务部署”流程，涉及创建ECS任务定义、配置负载均衡器、设置CloudWatch告警等。你可以创建一个 deploy-new-microservice.md 工作流。

这个工作流会详细列出步骤：

1. 准备阶段 ：确认目标账户、区域、项目标签。
2. 基础设施 ：调用 create-secret.sh 存储数据库连接字符串；引用一个外部Terraform模块来创建ECS集群和ALB（或调用相应的AWS CLI命令脚本）。
3. 应用部署 ：构建Docker镜像并推送到ECR；创建或更新ECS服务定义。
4. 验证与监控 ：运行健康检查；创建CloudWatch仪表盘和告警规则。
5. 清理与回滚指南 ：附上遇到问题时如何回滚的步骤。

将这个工作流文档化，任何团队成员（或他们的AI助手）都可以遵循同样的、经过验证的流程进行操作，极大减少了人为错误和知识差异。

7.3 集成到CI/CD管道

aws-manager的脚本是无状态的、可脚本化的，这使其成为CI/CD流水线的理想组件。

场景 ：在每次部署后，自动运行安全审计和成本检查。

你可以在GitHub Actions工作流或GitLab CI .gitlab-ci.yml 中添加这样的步骤：

stages:
  - deploy
  - audit

post-deploy-audit:
  stage: audit
  script:
    - aws configure set region us-east-1
    - ./scripts/use-account.sh $AWS_ACCOUNT_ALIAS
    # 运行安全审计，输出结果
    - ./scripts/scan-iam.sh | tee iam-scan.json
    - ./scripts/scan-resources.sh | tee resource-scan.json
    # 检查是否有高风险发现（例如，没有MFA的用户）
    - if jq -e '.users[] | select(.mfa_active == false)' iam-scan.json > /dev/null; then echo "发现未启用MFA的用户！" && exit 1; fi
    # 检查成本异常
    - ./scripts/scan-costs.sh --month $(date +%Y-%m) | tee cost-scan.json
    - if jq -e '.anomalies | length > 0' cost-scan.json > /dev/null; then echo "发现成本异常！" && exit 1; fi
  only:
    - main # 仅在主分支部署后运行

这样，你就将安全性和成本管控直接嵌入到了交付流程中，实现了“左移”的安全和运维。

从我个人的使用体验来看，aws-manager最大的价值不是替代了某个具体工具，而是 建立了一种人与AI协同运维的新范式 。它把那些琐碎、重复但又必须谨慎执行的云管理任务，变成了可描述、可重复、可审计的流程。我不再需要记忆复杂的CLI命令参数，也不再担心给同事开通权限时漏掉某个策略。我只需要用自然语言说出我的意图，剩下的就交给这位不知疲倦的“AI副驾驶”去精确执行。

它可能不是最强大的自动化平台，但绝对是目前与AI编码助手结合最紧密、最轻量、也最易理解的一套方案。如果你也厌倦了在AWS控制台里反复点击，或者想让团队的运维操作更标准化，不妨试试把它引入你的工作流。