susumutomita/TenkaCloudChallenge

# TenkaCloudChallenge [](https://github.com/susumutomita/TenkaCloudChallenge/actions/workflows/ci.yml) [](./LICENSE) [](#contributing) [](https://bun.sh) [](https://aws.amazon.com/cloudformation/) TenkaCloud 在真实的 AWS 账户上运行面对面的 **Battles** 和自定进度的 **Challenges**。一个问题 = 本仓库下的一个目录。平台将此仓库作为 git submodule 挂载，将其打包为 `source.zip`，并将每个问题的 `template.yaml` 部署到参与者的账户中。**您只需向此仓库提交 PR 即可发布新问题** — 无需更改 platform 仓库。 ## ✨ 本仓库存在的原因 - **无需 platform 上下文即可编写。** 添加问题只需要 `metadata.json` + `template.yaml`（+ 可选的 portal slot UI 和 side services）。其他所有内容 —— 评分、portal 渲染、中断调度 —— 都由 platform 根据您的 metadata 通用驱动。 - **单一事实来源。** `metadata.json` 为目录 UI、评分引擎和参与者 portal 连接提供支持。平台端是一个通用的调度器 (ADR-012)。 - **在 CI 中进行 schema 验证。** 每次推送和 PR 时都会根据 [`SCHEMA.json`](./SCHEMA.json) 检查每个问题。 - **设计上保持开源。** 本仓库包含在 Apache 2.0 下发布的基础问题集（与 TenkaCloud platform 仓库相匹配）。包含剧透的私有问题将通过 ADR-008 S3 路径放入单独的私有仓库中。 每个问题都附带针对该问题的 README（以英文为主，日文为镜像），描述了背景故事、解题路径和学习目标。浏览 [`battles/`](./battles/) 和 [`challenges/`](./challenges/) 以查看实时目录。 ## 🚀 快速开始 ``` # 1. 安装 Bun（一次性） curl -fsSL https://bun.sh/install | bash # 2. 克隆并安装 git clone https://github.com/susumutomita/TenkaCloudChallenge.git cd TenkaCloudChallenge bun install # 3. 根据 schema + cross-refs 验证每个问题 bun run validate ``` 这就是编写问题所需的全部内容。仅在运行 *platform*（CDK / Lambda）时才需要 AWS 凭证 —— 本仓库中的目录工作不需要。 ## ➕ 添加新问题 ``` bun install bun run setup # one-time: enable the auto-reindex git hook bun run new battles my-cool-battle # scaffold from a working sample (validates immediately) ``` `bun run new ` 会复制一个已知良好的示例（因此它从一开始就能通过验证），并为您重新生成目录索引。然后： 1. **编辑 `metadata.json`。** 遵守 [`SCHEMA.json`](./SCHEMA.json)。关键字段：`id`、`name`、`category`、`difficulty`、`scoring`、`endpoints`、`disruptions`。（使用 `--from ` 可以从一个更接近的示例开始。） 2. **编辑 `template.yaml`。** 这是一个单页 CloudFormation 模板（部署主体）。必须接受 `NamePrefix` / `TenkaCloudAccountId` / `ExternalId` 参数，并创建所需的 `ParticipantViewerRole`。 3. **（可选）添加 `portal/.tsx`** 用于参与者 portal 中针对特定问题的 UI，并添加 **`services/`** 用于您的模板拉取的任何 docker-compose / Lambda 代码（例如通过 EC2 UserData）。 4. **`bun run validate`**，将 `status` 设置为 `ready`，然后提交 PR。 您永远不需要手动编辑 `index.json` / `cost-report.json` —— `bun run new` 会重新生成它们，并且在执行 `bun run setup` 之后，pre-commit hook 会在每次提交时保持它们最新。 （跳过了 hook？在提交之前运行 `bun run reindex` —— CI 会使用 `--check` 验证目录是否与您的 metadata 匹配。） platform 仓库的维护者随后会更新 submodule 指针，下一次 `make deploy` 就会发布您的问题。 ## 🏗️ 仓库布局 ``` . ├── battles/ # Battle (real-time, head-to-head) │ └── / │ ├── metadata.json # Source of truth (catalog + scoring + portal wiring) │ ├── template.yaml # Single-page CFn template (the deploy body) │ ├── portal/ # Optional: .tsx (participant portal UI) │ └── services/ # Optional: docker-compose / Lambda code ├── challenges/ # Challenge (self-paced) │ └── / │ ├── metadata.json │ └── template.yaml ├── SCHEMA.json # JSON Schema for metadata.json (synced with platform) ├── index.json # Catalog index (built from every metadata.json) ├── CATALOG.md # Full catalog docs + schema walkthrough ├── scripts/validate-problems.ts # Local + CI validator └── .github/workflows/ci.yml # Schema + cross-ref CI ``` ## 🎮 设计标准 —— 趣味性，而非练习 新的竞赛问题需符合一个标准：玩家应该称之为**有趣**，而不是家庭作业。四个属性 —— 已编纂在 [`new-problem`](./.claude/skills/new-problem/SKILL.md) 编写技能中： 1. **发现的 flag，永远不是死记硬背的。** flag 是每次部署时生成的随机值，您只能通过*执行预期的 AWS 操作*来获取 —— 永远不是凭记忆打出的概念名称。 2. **通过设置修复，永远不要手动创建。** 模板部署的资源处于损坏状态；解决方法是*修改*现有资源。玩家永远不需要创建顶层资源，因此 `delete-stack` 不会留下孤立的、产生费用的垃圾。 3. **真正的“顿悟”时刻。** 一种切实体会到的生产技能 —— *挂起*与*拒绝*的 `curl` 调用，从证据中重建的事故 —— 而不是抽认卡。 4. **充满悬念的故事。** 共享的 TenkaCloud 世界（前一位 SRE 的遗留物，CTO），每次都有新的事件。 ## 🎯 目录 实时目录是问题目录的集合：浏览 [`challenges/`](./challenges/) 和 [`battles/`](./battles/) —— 一个目录 = 一个问题，每个目录都有自己的 `metadata.json` + `template.yaml`。`index.json` 是生成的机器索引（添加/删除问题后运行 `bun run reindex`；请勿手动编辑）。本 README 刻意不重复每个问题的列表，因此目录永远不会偏离原始来源。 ## 🔄 交付流程 ``` [contributor] open a PR that adds or updates problems │ ▼ [merge to main] CI runs `bun run validate` against every metadata.json │ ▼ [platform repo (= TenkaCloud) bumps the submodule pointer] │ git submodule update --remote problems │ ▼ [make deploy] prepare-source-bundle.sh bundles `problems/` into source.zip → S3 → CodeBuild deploys template.yaml ``` ## 🧠 架构参考（平台端） 这些 ADR 位于 [platform 仓库](https://github.com/susumutomita/TenkaCloud) 中，解释了本仓库接入的运行时契约： - **ADR-008** — 私有问题 payload 分离（包含剧透的附加问题的 S3 路径） - **ADR-010** — API 优先的运维路径 (CLI / MCP) - **ADR-012** — 一个问题 = 一个插件（3-asset 模型：`metadata.json` + `template.yaml` + 可选的 `portal/services`） ## 📜 License [Apache License 2.0](./LICENSE) —— 问题集和工具 alike。与 [TenkaCloud platform 仓库](https://github.com/susumutomita/TenkaCloud) 的 License 相匹配，以便贡献可以在两者之间无阻碍地流动。如果您发布包含剧透内容的问题，请将其托管在单独的私有仓库中，并通过 ADR-008 S3 路径进行交付。 ## 🔗 相关 - **Platform 仓库 (CDK / Lambda / 3 SPAs):** - **JSON Schema:** [`SCHEMA.json`](./SCHEMA.json) - **完整的目录文档:** [`CATALOG.md`](./CATALOG.md) - **编写设计标准 (skill):** [`.claude/skills/new-problem/SKILL.md`](./.claude/skills/new-problem/SKILL.md)

标签：AWS, CloudFormation, DPI, 特权提升, 自动化攻击, 自动化部署, 请求拦截, 题库