planner

规划器技能

生成分阶段项目计划，将复杂项目拆分为易于管理、可恢复的步骤，涵盖从初始设计到编码、测试和云部署的全过程。

提示：如需全面了解所有可用技能，请参阅 根目录中的 SKILL.md。

---

全新项目与现有项目的检测

场景	检测方式	处理方式
全新项目	没有 Dockerfile，也没有 .do/app.yaml	从头创建工件
现有项目	存在 Dockerfile 和／或 .do/app.yaml	检查、验证并完善现有工件

AI 助手会自动检测项目状态。不要重新创建有效的工件。关键验证门槛是 doctl app dev build——如果该命令通过，工件就是正确的。

---

为什么要分阶段部署？

复杂的 App Platform 部署如果一次性执行，往往会失败：

1. 盲目部署会失败——未准备好基础设施就部署，会导致难以理解的错误
2. 上下文会丢失——会话之间的凭据、集群 ID 和进度容易遗忘
3. 更难调试——一次性部署所有内容时，很难判断哪个组件出了问题
4. 难以恢复——从头开始会浪费时间，也无法跟踪部分进度

---

先在本地构建

重要：云部署之前，务必先在本地验证构建。

doctl app dev build                    # Build using local app spec
doctl app dev build --app <APP_ID>     # Build using existing deployed app
doctl app dev build --env-file .env    # Build with environment overrides

构建位置	反馈时间	失败成本
云端	5-10 分钟	浪费一次部署周期，日志令人困惑
本地	30-60 秒	可立即修复，错误清晰明了

完整详情：请参阅 build-local-first.md

---

层级分类

根据用户描述检测

用户提及	层级
“静态”、“仅前端”、“无数据库”、“SPA”	Tier 1
“PostgreSQL”、“MySQL”、“数据库”、“API + 前端”	Tier 2
“Kafka”、“OpenSearch”、“工作进程”、“事件驱动”、“微服务”	Tier 3

决策树

Does user mention Kafka, OpenSearch, workers, or "event-driven"?
  YES → Tier 3 (Complex)
  NO → Does user mention database (PostgreSQL, MySQL, MongoDB)?
         YES → Tier 2 (Database-backed)
         NO → Tier 1 (Simple)

根据 app.yaml 检测（备用方式）

如果 .do/app.yaml 存在：

• 存在 workers → Tier 3
• 存在值为 KAFKA 或 OPENSEARCH 的 databases → Tier 3
• 存在 databases → Tier 2
• 两者都不存在 → Tier 1

---

层级结构

Tier 1：简单（5 个阶段）

标准：静态网站、单个服务、无数据库

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-deploy.md
└── 05-cloud-validate.md

示例：Next.js 静态导出、React SPA、Hugo 网站、Astro

Tier 2：数据库支持（7 个阶段）

标准：1-2 个服务、单个数据库（PostgreSQL/MySQL）

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database.md
├── 05-cloud-config.md
├── 06-cloud-deploy.md
└── 07-cloud-validate.md

示例：Rails + PostgreSQL、Django + MySQL、Node.js API + Postgres

Tier 3：复杂（9 个阶段）

标准：多服务、工作进程、Kafka/OpenSearch、VPC 网络

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database-clusters.md
├── 05-cloud-config-users-topics.md
├── 06-cloud-debug-validation.md
├── 07-cloud-secrets-cicd.md
├── 08-cloud-deploy-production.md
└── 09-cloud-end-to-end.md

示例：事件驱动的微服务、ML 流水线、实时分析

重要：Tier 3 应用必须使用 GitHub Actions 部署

Tier 3 应用包含 ${SECRET_NAME} 占位符，该占位符只能由 digitalocean/app_action/deploy@v2 解析。

• 在 .do/app.yaml 中设置 deploy_on_push: false
• 通过 git push 部署（触发 GitHub Actions），而非使用 doctl apps create

---

阶段模板

阶段模板位于 templates/ 目录中：

目录	用途
templates/local/	本地阶段 1-3（所有层级）
templates/tier-1-simple/	Tier 1 云端阶段
templates/tier-2-database/	Tier 2 云端阶段
templates/tier-3-complex/	Tier 3 云端阶段

每个阶段文件都遵循以下结构：

# Stage N: [Stage Name]

**Status**: TODO
**Prerequisites**: Stage N-1 complete

## Tasks
- [ ] Task description
- [ ] Expected outcome

## Verification
[Commands to verify completion]

## Next Steps
Proceed to Stage N+1

关键验证门槛：阶段 3 包含 doctl app dev build 和健康检查验证。

---

使用示例

示例 1：简单静态网站

用户：“部署一个 Next.js 静态网站”

1. 检测为 Tier 1（无数据库）
2. 在 Plan/ 中生成 5 个阶段文件
3. 返回：“已创建 5 阶段计划。请从阶段 1：本地设计开始。”

示例 2：带数据库的 API

用户：“使用 PostgreSQL 的 Node.js API”

1. 检测 Tier 2（PostgreSQL）
2. 在 Plan/ 中生成 7 个阶段文件
3. 返回：“已创建 7 阶段计划。在 Stage 4 中创建数据库集群。”

示例 3：事件驱动型微服务

用户：“使用 Kafka 和 OpenSearch 的事件驱动型应用”

1. 检测 Tier 3（Kafka + OpenSearch）
2. 在 Plan/ 中生成 9 个阶段文件
3. 返回：“已创建 9 阶段计划，并包含调试容器验证。”

---

主要功能

会话恢复

• 阶段文件保存在 git 中（仅跟踪状态）
• 所有捕获的值都存储在 .env.secrets 中（已加入 gitignore）
• AI 助手读取 .env.secrets，以从任意阶段恢复

构件存储

• 计划文件仅包含状态，不包含机密信息
• 所有 ID、密码和 URL 都存储在 .env.secrets 中
• 有关理念，请参阅 artifact-storage.md

暂停点

• 每个阶段都以验证清单结尾
• 明确说明“继续执行 Stage N+1”
• 针对常见故障提供故障排除部分

---

参考文件

• build-local-first.md — 完整的 doctl app dev build 工作流
• artifact-storage.md — 存储理念、AI 指令

---

与其他技能集成

• ← designer：如果存在 .do/app.yaml，则使用它检测复杂度
• → deployment：Plan/ 文件提供上下文；Stage 7 创建 GitHub Actions 工作流
• → troubleshooting：Plan/ 阶段有助于确定故障发生的位置
• → devcontainers：用于测试的本地开发环境设置