volcengine-prepare

火山引擎准备技能

分析代码仓库，说明可行的火山引擎部署路径，并确定资源管理路径。请将此技能视为决策支持，而非工作流引擎。不要把复杂的报告格式作为目标。

---

0. 核心行为

默认流程：

1. 从本地路径或 Git URL 解析代码仓库。
2. 运行分析器，识别语言、框架、端口、Docker/compose 结构、依赖项、迁移、入口点和可部署的服务范围。
3. 如果凭据可用，可选验证当前火山引擎身份和地域。
4. 只有在明确可部署的服务范围后，才给出 ECS / VKE / veFaaS 的排序列表。包含所有实质上可行的路径，并说明每条路径的优势或成本。使用 ecs | vke | vefaas 作为机器可读的模式值。
5. 根据 references/deploy-mode-heuristics.md 推荐资源管理路径（cli 或 iac），并请用户确认。
6. 仅询问产品/生命周期方面的歧义、资源复用情况以及资源管理选择。如果用户说“由你决定”，则使用排序第一的运行时路径、这些规则推荐的资源管理路径，以及新建的隔离资源。
7. 只有在工作会跨步骤继续时，才在 .volcengine/ 中保存最少量状态。

在对 ECS / VKE / veFaaS 排序前，先确定具体部署目标：代码仓库、子目录、命令、制品、静态输出，或现有云应用/函数；该路径必须能够实际运行、容器化、公开访问或提供服务。文件级信号是证据，而非结论。仅有 Dockerfile、compose 文件、package.json、框架依赖项或 build/dev/test 脚本，并不能证明代码仓库可部署。

推荐阶段不要运行严格的工具依赖检查。只有用户选择路径后，才检查该路径所需的工具。

状态目录：

.volcengine/
  deploy-choice.json       # chosen mode/resource strategy, when persistence is useful
  created-resources.json   # maintained by deploy only for CLI fast path
  terraform/               # IaC working files, only when infra_management=iac
  iac-outputs.json         # Terraform outputs consumed by deploy

仅将 /tmp 用于临时克隆或缓存。

---

1. 解析并分析代码仓库

对于 Git URL，将代码仓库克隆到临时缓存。对于本地路径，直接在原位置分析。

input="${1:-.}"
if [[ "$input" =~ ^(https?|git@) ]]; then
  repo_name=$(basename "$input" .git)
  cache_dir="/tmp/volcengine-prepare/$repo_name"
  mkdir -p "$cache_dir"
  [ -d "$cache_dir/src/.git" ] || git clone --depth 1 "$input" "$cache_dir/src"
  repo_dir="$cache_dir/src"
else
  repo_dir=$(cd "$input" && pwd)
  repo_name=$(basename "$repo_dir")
fi
git_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "unversioned")

运行：

analysis=$(bash scripts/analyze-repo.sh "$repo_dir")
echo "$analysis" | jq .

用通俗语言展示重要发现：

Project: <repo_name> @ <git_sha>
Runtime: <language> / <framework>
Deployable subdir: <deploy_subdir or repo root>
Deployable surface: <web service | rpc service | http api | static/html site | full-stack app | user-specified service | unclear>
Entrypoint: <entrypoint>
Port: <port>
Packaging signals: Dockerfile=<yes/no>, compose=<yes/no if detected>
Dependencies: <mysql, redis, ...>
Migrations: <paths or none>

如果分析器无法识别具体的 ECS/VKE/veFaaS 部署目标，则在推荐路径前，询问要部署哪个子目录、服务、命令、制品、静态输出或现有 veFaaS 应用/函数。如果代码仓库看起来主要是构建工具、打包内容、示例、文档或可复用代码，而非应用服务，则降低推荐力度，改为请用户确认。

部署目标是指 ECS、VKE 或 veFaaS 能够运行、容器化、公开访问或提供服务的对象。可参考的证据包括但不限于：

• 有启动命令的长时间运行进程，
• 监听端口或 RPC/API/HTTP 路由，
• 用于提供服务的静态/HTML 网站入口或构建输出，
• 健康检查或冒烟测试端点，
• 具有明确服务边界的前端和后端/API 组件，
• 用户明确指定服务、子目录、命令、制品或运行时目标。

不要仅凭 Dockerfile、包脚本或构建工具推断其可部署。

---

2. 可选的云身份检查

如果已设置 VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY 和 VOLCENGINE_REGION，则验证身份：

ve sts GetCallerIdentity

不要读取 ~/.volcengine/config.json；其中可能包含机密信息。如果没有这些环境变量，请继续给出建议，并告知用户将在执行所选路径时检查凭据。

如果云服务可用性会影响近期选择，则运行只读探测：

services=$(bash scripts/check-region-services.sh)
echo "$services" | jq .

在对应选项中说明权限或地域方面的注意事项；不要隐藏该选项。

预检查仅供参考，并非准入条件。如果可以低成本检查配额或权限，请将检查结果作为风险提示：

<quota/permission> may be insufficient; continuing could fail when creating resources. Proceed anyway?

如果无法可靠查询账户实名验证状态或余额，请简短提醒，不要编造检查结果：

Creating cloud resources may require a real-name-verified account with sufficient balance/credit; if creation fails, resolve the account status in the console first.

---

3. 推荐部署路径

使用 references/deploy-mode-heuristics.md 中的详细决策规则。请给出排序后的列表，不要使用 recommended=true/false 标记或展示评分细节。如果可部署的对象不明确，请先说明歧义，并在排序前提出最少的后续问题。

列出所有实质上可行的选项；如果仓库或用户请求明确排除了某个路径，不要强行完整比较 ECS、VKE 和 veFaaS。只有在说明某个不可行路径为何被排除有助于用户决策时，才提及该路径。

• ECS：虚拟机路径。最适合可在 Linux 虚拟机上运行的目标，例如 Web/API/RPC 服务、全栈应用、静态站点服务进程、二进制文件、Docker/compose 应用、工作进程、定时命令，或需要操作系统／网络／磁盘／调试控制的应用。
• VKE：容器／Kubernetes 路径。最适合容器化或符合 Kubernetes 模式的目标，例如多服务应用、Web/API/RPC 容器、工作进程、Jobs/CronJobs、滚动更新、副本、HPA、Ingress/Service、GPU 工作负载或生产环境容器运维。
• veFaaS：无服务器路径。仅当目标符合 volcengine-vefaas 技能的工作流时适用：受支持的 Web/API 或前端／静态框架，或现有的 veFaaS 应用／函数。对于长时间运行的工作进程、多服务编排、复杂迁移、不受支持的事件／任务／触发器创建、自定义系统依赖，或没有可用 API Gateway 的情况，优先选择 ECS/VKE。如果用户选择此路径，请切换到／调用 volcengine-vefaas 技能进行部署；如果失败，则返回主流程，让用户重试或选择 ECS/VKE。

请说明：

• 该选项排名靠前或靠后的原因
• 大致成本等级（low、medium、medium-high）
• 运维方面的权衡
• 用户选择该选项时已知的阻碍或所需准备
• 资源管理建议（iac 或 cli）及原因

在用户作出选择前，不要检查所有工具。请将准备工作表述为决策建议。根据 references/deploy-mode-heuristics.md 填写资源管理建议，但不要向用户提及该内部参考路径：

Resource management recommendation: <iac|cli>. Reason: <one short user-facing reason>. Confirm `iac` or `cli`.
Choosing VKE will check kubectl; if you choose IaC it will also check terraform/provider availability.
Choosing veFaaS switches to / calls the `volcengine-vefaas` skill to check the vefaas CLI, login status, and framework detection; on failure it returns here so you can fix it and retry, or switch to ECS/VKE.

---

4. 只提出必要的问题

展示排序后的列表后，只询问无法安全推断的事项：

1. Deployment mode: defaults to the top-ranked option. Choose ECS / VKE / veFaaS (recorded as `ecs` / `vke` / `vefaas`).
2. Resource strategy: defaults to a new isolated project deploy-<repo> with new resources; you may also reuse existing resources.
3. Database product/engine, only when a managed database is detected or requested: choose `rds/mysql`, `rds/postgresql`, `rds/sqlserver`, `aidap/supabase`, or `aidap/postgresql`.
4. Resource management: recommend <cli|iac>; confirm whether to use the CLI resource ledger or Terraform/IaC.

对于 MySQL 依赖项，除非用户拒绝托管 RDS，否则使用 database_product=rds 和 database_engine=mysql。对于 SQL Server 依赖项，使用 database_product=rds 和 database_engine=sqlserver。对于 PostgreSQL 依赖项，优先遵循用户明确表达的意图：如果用户明确要求 RDS／托管 RDS 实例，则选择 RDS PostgreSQL；如果用户明确要求 AIDAP／无服务器 PostgreSQL，则选择 AIDAP PostgreSQL；如果用户明确要求 Supabase，则选择 AIDAP Supabase。当产品存在歧义且用户没有授权代为选择时，请先询问，因为 RDS PostgreSQL、AIDAP PostgreSQL 和 AIDAP Supabase 是不同的选项。

明确询问是否使用 Terraform/IaC。根据 references/deploy-mode-heuristics.md 给出建议，但不要将其设为默认选项。请用户确认使用 iac 还是 cli。

如果用户说“你来决定”，则使用：

• 部署模式：排名第一的选项
• 资源：新建隔离的 Volcengine 项目 deploy-<repo>
• 数据库产品／引擎：能明确推断时使用准确的引擎（mysql -> rds/mysql；sqlserver -> rds/sqlserver）；对于 PostgreSQL，如果项目中没有明确的 RDS/AIDAP PostgreSQL/Supabase 信号，则选择 AIDAP Supabase（database_product=aidap，database_engine=supabase）。
• 资源管理：应用 references/deploy-mode-heuristics.md 中的建议

如果用户选择复用资源，只询问该路径所需的资源 ID。清理时不得销毁复用的资源。

---

5. 仅在有用时保存用户的选择

如果在同一对话中继续执行，则无需文件。如果用户之后可能会继续，或下一步需要持久的交接记录，则只写入一份简短的选择记录：

{
  "schema_version": "1",
  "repo_dir": "/absolute/path",
  "repo_name": "my-app",
  "git_sha": "abc1234",
  "region": "cn-beijing",
  "mode": "ecs",
  "port": 8080,
  "dependencies": ["postgresql", "redis"],
  "database_product": "aidap",
  "database_engine": "supabase",
  "resource_strategy": "create-isolated-project",
  "project": "deploy-my-app",
  "infra_management": "cli"
}

将其写入 .volcengine/deploy-choice.json。

除非用户要求报告，否则不要写入评分表、理由数组或完整的推荐矩阵。

---

6. 摘要模板

Project detection:
- Runtime: <language>/<framework>
- Deployable surface: <surface or unclear, with evidence>
- Entrypoint/port: <entrypoint> / <port>
- Packaging signals: Dockerfile=<yes/no>, Compose=<yes/no>
- Dependencies: <deps or none>
- Database choice: <none | database_product=rds engine=mysql|postgresql|sqlserver | database_product=aidap engine=supabase|postgresql>
- Migrations: <paths or none>
- Resource management recommendation: <iac|cli>

Ranked order:
1. <mode>
   Reason: ...
   Tradeoff: ...
   Rough cost: ...

2. <mode>
   ...

3. <mode>
   ...

Please confirm:
1. Deployment mode: defaults to <first mode>
2. Resource strategy: defaults to a new isolated project deploy-<repo>; reuse is also possible
3. Resource management: recommend <iac|cli>; confirm `iac` or `cli`