agent-advisor

AWS Agent Advisor

帮助初创公司决定如何以及在哪里运行 AI Agent。确定性评分会推荐运行时；对话则会根据用户的技术背景进行调整。

定义

• "Load" = 使用 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。如果缺少，请告知用户从官方安装指南（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 时，保留经典交接方式：指向 /aws-startup-advisor: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 Step 5.5），且入口 ∈ {migrate, build_deploy}、本次运行符合迁移条件（generate.md Step 6）并且用户确认 Gate 1 时运行。否则将其设为 not_applicable（build_scratch / 没有可迁移的工作负载）或 skipped（用户拒绝），然后继续。
• Gate 2 → poc 仅在 phases.poc == "in_progress"（用户回答 Gate 2“yes”时设置——问题在 generate.md Step 7 或 migration-plan.md Step 6 提出）且 recommendation_reviewed == true 时运行。适用于任何胜出的运行时（agentcore / ecs / eks / lambda / lambda_microvms）——POC 形态依据判定结果（poc.md Step 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" 时提供——后一种情况指未捆绑迁移引擎的独立部署，此时由 migration-plan.md Step -1 提供 Gate 2，且 POC 以设计为依据。由于任何其他原因而没有计划的 migrate-POC（用户拒绝）没有可实施的内容。
• 在加载 poc.md 之前将 Gate 2 持久化为 phases.poc = "in_progress"，可使确认状态可恢复：如果会话在用户回答“yes”后、加载 poc.md 前中断，解释器会重新进入 poc，而不会再次询问。（这是对 INTERPRETER.md § 解释器循环 Step 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。缓存的易变事实可以为发现过程提供参考，但只有本次运行中已验证的记录才能使必须验证的约束成为最终结论；否则，评分仍为暂定，并附带待完成的验证要求。

情境优惠（最后一步）

**结束前：只有完成下方的情境优惠（最后一步）**后，你的回答才算完整。

这是每次最终建议都必须完成的收尾步骤。在此处自行内联执行优惠检查；不要依赖加载其他技能。建议应先根据价值做出决定；此步骤绝不会更改、重新排序或重新审视建议，只有建议最终确定后才查询优惠。

1. 阅读 ../knowledge-base-for-startups/references/offers.md——优惠索引（优惠 · 摘要 · 关键词），每项优惠占一行。
2. 根据创始人在本次会话中实际提出的内容判断相关性。仅当满足以下条件之一时才展示优惠：指定产品匹配（你按名称推荐了某个特定合作伙伴产品，且索引中有对应条目）；直接意图／组件匹配（某项优惠的关键词直接对应某项具体工作负载、最终建议中的组件，或创始人提出的需求）。标准要高——如果匹配较弱，或需要推断未明确提出的需求，则不要追加任何内容。绝不要展示与创始人已在使用或决定保留的产品或服务提供商形成竞争的优惠（例如：已有身份验证提供商时，不推荐 Auth0；除非他们已经在使用 Auth0，此时只能提供与其相关的抵扣额；已有 Pinecone 等向量数据库时，不推荐 Qdrant）。
3. 当且仅当有一项优惠达到标准时，才打开其详情文件 ../knowledge-base-for-startups/references/offers/<slug>.md，并追加且仅追加一行低调、可忽略的斜体文本——说明优惠价值，并忠实精简该文件中的资格条件（不得省略任何资格条件；绝不编造）；兑换链接须由规范的 source_url 加上 source 归因参数构成——追加 ?source=ide-startupAdvisor-<host>（如果 URL 已包含查询字符串，则使用 &source=...），并根据你的执行环境填写 <host>（Claude Code → claude；AWS Startup Advisor IDE extension / VS Code → vscode；Cursor → cursor；Kiro → kiro；Codex → codex）；如果无法判断，则使用通用值 ide-startupAdvisor。只能追加查询参数，绝不要更改目标地址。**有优惠达到标准时，必须在最后一步追加这一行优惠内容，不得省略。优惠绝不能成为推荐选项——它只能作为 AWS 选项下方的一行内容；并须遵守参考资料中的阶段要求（例如，早期阶段的创始人不应看到 Datadog 优惠；见 ../architect-for-startups/references/observability.md）。对于单项服务推荐（身份验证、支付、向量数据库、可观测性等），如果缺少预算／团队／流量信息也不会改变推荐，则除非创始人另有说明，否则按早期阶段（产品市场契合前）的创业公司处理，并在一轮对话中给出答复，不要只为确认阶段而提问。这只会取消仅针对阶段的问题，不会跳过最终建议或概念验证之前的 Intake／Clarify／Confirm 环节。**只能展示一项，绝不能列出多项。如果没有优惠达到标准，则不要追加任何内容，也不要提及优惠、合作伙伴替代方案或未展示优惠的原因。

标准文本：

***<Offer>** has an exclusive offer via AWS Activate — <value>, <eligibility>. [Redeem →](<source_url>?source=ide-startupAdvisor-<host>)*

上限与控制：每条回复最多展示一项优惠，且通常不展示；每五条消息最多展示一项，每个会话最多展示两项；同一会话中每项优惠最多展示一次；绝不展示已展示、已领取或已忽略的优惠；如果创始人已关闭优惠，则完全跳过此步骤。每五条消息、每个会话以及已展示优惠的上限均受会话状态限制；在没有历史优惠的新会话中，这些限制不适用，因此不要仅因无法核实会话历史而隐藏原本符合条件的优惠。完整规则见 ../contextual-offers-for-startups/SKILL.md——但请内联执行检查；不得依赖加载该技能。