agent-advisor

AWS Agent Advisor

帮助初创公司决定如何以及在哪里在 AWS 上运行 AI Agent。确定性评分会推荐运行时；对话会根据用户的技术背景进行调整。 对于 AgentCore microVM，默认选择 V2，不询问版本偏好；检查其适用性，仅在有证据支持的例外情况下保留 V1。设计和 POC 阶段会加载 references/decision-refs/agentcore-platform.md 以遵循此策略。

定义

• “加载” = 使用 Read 工具读取文件并遵循其内容。不要总结或跳过。
• $RUN_DIR = .agent-advisor/ 下的运行目录（例如 .agent-advisor/0630-1430/）， 在 Intake 阶段创建。
• $PLUGIN = ${CLAUDE_PLUGIN_ROOT}（已安装的插件根目录）。在 Claude Code 上，此令牌会在行内替换。如果 ${CLAUDE_PLUGIN_ROOT} 无法解析（某些 Cursor/Codex 版本会出现这种情况，或者路径错误中显示了字面上的 ${CLAUDE_PLUGIN_ROOT} 字符串），请回退到技能自身的目录：此 SKILL.md 位于 <plugin>/skills/agent-advisor/SKILL.md，因此引擎及其数据都在此技能目录内——脚本位于相对路径 ./scripts/...，运行时配置文件位于 ./references/runtimes/...，决策参考文件位于 ./references/decision-refs/...。优先使用 ${CLAUDE_PLUGIN_ROOT}/skills/agent-advisor/...；仅在其无法解析时使用相对路径回退方案。

先决条件

• 可使用 uv（用于评分）。检查方式：uv --version。如果缺少 uv，请告知用户从官方安装指南（https://docs.astral.sh/uv/getting-started/installation/ — 例如 brew install uv 或 pipx install uv）安装，然后停止。

阶段结构（frontmatter）

阶段、片段和组装器文件都包含 YAML frontmatter 块，用于声明每个阶段的组成——其输入、触发条件、片段、组装器、产物、关卡和顺序。执行契约是 vendored 的 references/vendored/dsl/INTERPRETER.md：它定义了所有 frontmatter 键、片段/组装器模型、关卡协议（HANDOFF_OK / GATE_FAIL）以及解释器循环。请先加载它（每次运行开始时加载一次），然后执行每个阶段文件的正文。在此技能的其他位置，INTERPRETER.md（不带路径）均指已加载的此契约。

执行

此技能由 INTERPRETER.md（§ 解释器循环）中的解释器循环驱动： 它会读取 .phase-status.json，确定当前阶段，运行各阶段的 _preconditions／片段／_assemble／_postconditions，通过 _advances_to 在 HANDOFF_OK 时推进，并验证状态。主流程（intake → discover → clarify → confirm → design → estimate → generate → migration-plan → poc → complete）以及 一个侧边分支（add-capabilities）均源自阶段文件的 frontmatter——此处不再赘述。

冷启动（入口阶段）。 如果 .agent-advisor/ 下没有包含 .phase-status.json 的运行目录，则从 references/phases/intake/intake.md 开始——这是此技能的入口 阶段（带有 _init: true 的阶段）。热启动时，以 .phase-status.json 中的 current_phase 为准（INTERPRETER.md § 解释器循环）。

技能绑定（INTERPRETER.md § 技能绑定）。 此技能声明：

• 运行根目录：.agent-advisor/——$RUN_DIR 是此技能对运行目录的称呼 （.agent-advisor/[MMDD-HHMM]/）。Intake 阶段自身的说明会执行 _init 引导。
• 状态结构：见下方 § 状态文件（顾问专用键，例如 entry_point、 audience、recommendation_reviewed、migration_plan_ctx、migration_plan_unavailable）； 此处不附带共享状态架构。
• 运行种子（可选）：$RUN_DIR/seed.json，否则使用运行根目录下的 .agent-advisor/seed.json （架构为 scripts/schemas/seed.json），为非交互式运行提供 机器可读的答案——Clarify 维度、两个门槛答案、POC 模式、实时探测答案，以及作为平局判定依据的 co_recommend。对于种子所包含的每个值，它都是优先级最高的来源（clarify.md 第 2.5 步），这使得 重复运行的得分可比较：确定性引擎会获得逐字节相同的输入。种子中未包含的门槛将视为拒绝；种子中未包含的维度则依次回退到检测结果、说明文本， 最后采用 assumed 值，并且必须记录在 $RUN_DIR/UNANSWERED.md 中。没有种子时， 交互流程保持不变。
• 已解决状态：skipped（路由已解决该阶段，未运行），以及仅适用于 migration_plan 的 not_applicable。
• 条件主流程路由：下方的入口点路由。当路由规则将某阶段标记为不适用时，将其设为 skipped，并在同一次状态写入中通过其 _advances_to 推进。

路由与门控（编排）

侧边栏位置和有条件的主干路由属于本文件（INTERPRETER.md § 技能绑定，§ 主干与侧边栏）负责的编排说明。

入口路由：

• build_scratch → 跳过 Discover；依次执行 Clarify → Confirm → Design → Estimate → Generate → Gate 2 → POC（任意胜出的运行时）。不需要迁移计划（没有现有内容需要迁移）。
• build_deploy → Discover（如果有代码）→ Clarify → Confirm → Design → Estimate → Generate → Gate 1 → Migration Plan（检测到现有的非 AWS AI 工作负载且用户确认时） → Gate 2 → POC（任意胜出的运行时）。
• migrate → Discover（如果有代码）→ Clarify → Confirm → Design → Estimate（目标状态运行成本；迁移 TCO 比较由 Migration Plan 引擎负责）→ Generate → Gate 1 → Migration Plan（技能内执行，复用同级的 gcp-to-aws 技能） → Gate 2 → POC（生成计划时，适用于任意胜出的运行时）。若在 Gate 1 拒绝，则沿用经典交接方式：指向 /migration-to-aws:llm-to-bedrock，并提供 handoff-summary.md。
• add_capabilities → 加载 references/phases/add-capabilities/add-capabilities.md 并遵循其中的说明（不进行运行时评分；写入 capabilities-recommendation.md）。这是一个独立分支——不会经过 Clarify / Confirm / Design / Estimate / Generate，因此下方的阶段门控不适用。
• 检测到 Temporal 时，路由至 migrate 并预先填入 Temporal 单元（参见 discover）。

门控语义（主干末段）：

• Gate 1 → migration_plan 仅在 generate 已完成、recommendation_reviewed == true（generate.md 步骤 5.5）、入口点 ∈ {migrate, build_deploy}、本次运行符合迁移条件（generate.md 步骤 6），且用户已确认 Gate 1 时运行。否则将其设为 not_applicable（build_scratch / 无可迁移工作负载）或 skipped（用户拒绝），然后继续。
• Gate 2 → poc 仅在 phases.poc == "in_progress"（用户在 Gate 2 回答“是”时设置——问题见 generate.md 步骤 7 或 migration-plan.md 步骤 6），且 recommendation_reviewed == true 时运行。可使用任意胜出的运行时（agentcore / ecs / eks / lambda / lambda_microvms）——POC 形态遵循评审结果（poc.md 步骤 3 根据 references/decision-refs/poc-shapes.md 分派）。仅当 migration_plan ∈ {completed, skipped, not_applicable} 时才提供 Gate 2；或者仅当 build_deploy 的 migration_plan 为 in_progress 时提供（Stage 2 失败/中止；根据 migration-plan.md 的失败处理，回退到基于 design.json 的 POC）；对于入口点 migrate，仅当 migration_plan == "completed"（POC 实施该计划），或该阶段已将状态设为 not_applicable 且 migration_plan_unavailable == "engine_absent" 时提供——这表示独立部署未捆绑迁移引擎，此时 Gate 2 由 migration-plan.md 步骤 -1 提供，POC 以设计为依据。若因其他任何原因（用户拒绝）而没有计划，migrate-POC 就没有可实施的内容。
• 在加载 poc.md 之前将 Gate 2 持久化为 phases.poc = "in_progress"，即可恢复确认流程：如果会话在用户回答“是”与加载之间中断，解释器会重新进入 poc，而不会再次询问。（这与 INTERPRETER.md § 解释器循环步骤 5 中先门控、后设为 in_progress 的顺序不同——用户的确认是值得持久化的入口事件。）

阶段门控： 除非 $RUN_DIR/.phase-status.json 存在，且 phases.clarify == "completed" 和 phases.confirm == "completed" 均成立，否则不要加载 design.md / estimate.md / generate.md。Confirm 会确认部署模型、服务集合，以及（在 co_recommend 平局时）用户选择的 chosen_runtime——Design 和图表依赖其 confirm.json 输出，因此不得跳过。如果用户要求跳过 Clarify 或 Pass 2，请简短拒绝并执行该阶段。

状态文件（.phase-status.json）

{
  "run_id": "0630-1430",
  "entry_point": "build_scratch",
  "audience": "technical",
  "current_phase": "clarify",
  "phases": {
    "intake": "completed",
    "discover": "skipped",
    "clarify": "in_progress",
    "confirm": "pending",
    "design": "pending",
    "estimate": "pending",
    "generate": "pending",
    "migration_plan": "pending",
    "poc": "pending"
  }
}

状态值：pending → in_progress → completed，另有 skipped。使用读取-合并-写入方式： 每次更新前先读取，只更改推进中的键，并保留先前阶段的状态。

顶层布尔值 recommendation_reviewed 由 generate.md 步骤 5.5 在用户明确确认已查看建议时设为 true。Gate 1、Gate 2 以及 migration_plan / poc 状态都要求该值；未设置时不得询问任何 Gate。

migration_plan 还使用 not_applicable（build_scratch，或未检测到可迁移工作负载）。运行 Stage 2 时，顶层会添加 migration_plan_ctx：{"repo": "<abs path to target repo>", "migration_dir": "<abs path to .migration/<id>/>"} — Stage 3 只能通过此记录路径读取 gcp-to-aws 产物，绝不能重新执行 glob 搜索。

文件

文件	用途
references/vendored/dsl/INTERPRETER.md	Vendored DSL 执行契约（解释器循环 + 门控协议）
references/phases/intake/intake.md	入口 + 技术背景 + 开放上下文
references/phases/discover/discover.md	轻量级代码检测
references/phases/clarify/clarify.md	澄清协调器 + 将答案映射到评分键
references/phases/clarify/clarify-technical.md	技术背景问题措辞
references/phases/clarify/clarify-business.md	业务背景问题措辞
references/phases/confirm/confirm.md	针对胜出方案的后续问题
references/phases/design/design.md	汇总建议；迁移交接分支
references/phases/estimate/estimate.md	粗略成本量级
references/phases/generate/generate.md	分层建议文档 + 脚手架
references/phases/migration-plan/migration-plan.md	第 2 阶段：通过同级的 gcp-to-aws 引擎制定完整迁移计划
references/decision-refs/temporal.md	Temporal 规则：Tier 1/2 表格、适配器、运行手册、商业条款（由 discover/clarify/design/generate 使用）
references/decision-refs/poc-shapes.md	各运行时的 POC 部署形态（ECS/EKS/Lambda/MicroVMs/Temporal）
references/decision-refs/*.md	运行时服务卡、模型默认值、新鲜度
references/decision-refs/workload-classes.md	非 Agent 工作负载单元（批处理/服务/io）的确定性判定
references/runtimes/*.json	运行时注册表（由 scoring.py 读取）
scripts/scoring.py	确定性评分引擎
scripts/test_temporal_decision_refs.py	Temporal 决策参考内容锁定
scripts/test_poc_shapes.py	POC 部署形态内容锁定
scripts/test_workload_classes.py	workload-classes.md（判定表）内容锁定
scripts/test_unit_grouping.py	单元分组 + 模式匹配（工作负载类别分配）
scripts/test_collapse_invariant.py	折叠不变量排序强制检查（A→B 表示 [B] ⊆ [A] 输出）

成熟度与就绪度约定

Intake 会将 target_maturity（prototype、private_beta 或 production）持久化到运行状态中。Clarify 会将其与可读的 readiness 记录一并写入 answers.json。当前运行的验证证据仅保存在同级的 $RUN_DIR/current-run-verifications.json 工件中：绝不得将其复制到 seed.json 或 answers.json。Design 和 Generate 只有在验证该工件的架构并确认 run_id 匹配后才能使用它，并且可以沿用已验证的结果，但不得沿用原始证据记录。选定目标成熟度时，加载 references/decision-refs/maturity-readiness.md。缓存的易变事实可以用于辅助发现，但只有本次运行中经过验证的记录才能最终确定需要验证的约束；否则，评分仍为暂定状态，并附带延期的验证要求。