穿孔卡片。人工智能
通过过去的触觉隐喻学习编程，由未来的智能驱动
  
⚠️ 重要提示：需要API密钥
在运行此应用程序之前，您必须添加您自己的Gemini API密钥：
- 创建一个
.env.local根目录中的文件 - 添加您的Gemini API密钥：
VITE_GEMINI_API_KEY=your_api_key_here - 获取免费API密钥，网址：https://aistudio.google.com/app/apikey
如果没有有效的Gemini API密钥，应用程序将无法运行。
概述
穿孔卡片。人工智能用现代人工智能复兴了20世纪60年代的穿孔卡片编程。学生拖动视觉“穿孔卡片”来构建程序，这些程序由Gemini AI编译成真实代码，并通过MCP安全执行。该系统生成个性化挑战，提供智能反馈，并适应每个学习者的旅程。
特性
核心学习体验
- 🎯 人工智能生成的主题：从每个教育级别的6个不同学习主题中进行选择，或根据您的兴趣创建定制科目
- 🎲 动态挑战：Gemini AI根据您选择的科目和技能水平生成的独特编程挑战
- 🃏 自适应卡库：符合您的学习环境和挑战要求的特定主题编程卡（每个挑战12-14张）
- ⚡ 真实代码执行：卡序列通过Gemini编译为实际的Python代码，并通过MCP在沙盒环境中安全执行
- 🤖 智能反馈：人工智能分析执行结果，并提供鼓励、教育指导和具体建议
- 📊 进度跟踪：持续的学习进度，包括绩效指标、成功率和挑战历史
教育程度
- 📚 小学（6-11岁）：带有视觉隐喻的简单、具体的概念
- 🎓 中学（11-14岁）：抽象思维和解决问题介绍
- 🏫 高中（14-18岁）：高级编程和实际应用
- 🎯 大学：AI/ML概念、复杂算法和系统设计
主题
每个级别提供6个跨不同领域的人工智能生成主题：
- 🤖 机器人学：机器人控制、自动化、传感器
- 🎨 艺术：绘画、音乐、创意编码
- 🔬 科学：实验、模拟、数据分析
- 🎮 游戏：游戏逻辑、机制、开发
- 📊 数据：统计、分析、可视化
- 🌐 网络：Web开发、API、交互式内容
- 🧠 AI/ML：神经网络、机器学习（大学水平）
快速开始
先决条件
- Node.js 18+
- npm或纱线
- Gemini API密钥
安装
# Clone the repository
git clone https://github.com/bbms2025/bbms2025-punchcard_repo.git
cd punchcard-ai
# Install dependencies
npm install
# CRITICAL: Set up your Gemini API key
# Create .env.local file and add:
# VITE_GEMINI_API_KEY=your_api_key_here
# Get your free API key at: https://aistudio.google.com/app/apikey
# Start development server
npm run devMCP设置（可选但推荐）
对于实际代码执行：
# MCP server will be automatically started by Kiro
# Or test manually:
npx @modelcontextprotocol/server-code-executor看 MCP_INTEGRATION.md 详细设置。
用法
入门指南
- 选择教育水平：从小学、中学、高中或大学中选择
- 选择您的主题:
- 浏览6个人工智能生成的主题，根据您的水平量身定制 - 或者根据您的兴趣创建自定义主题
- 接受挑战:
- 获得与您的主题相一致的独特编程挑战 - 审查目标和预期成果
- 构建您的计划:
- 将编程卡从库拖动到您的卡片组中 - 按顺序排列卡片以解决挑战 - 如果你遇到困难，请使用提示
- 运行和学习:
- 将卡片序列作为真正的Python代码执行 - 查看实际输出和性能指标 - 获得人工智能提供的具体建议反馈
- 进度和迭代:
- 完成挑战以解锁新的难度级别 - 跟踪你的成功率和学习进度 - 尝试新科目，探索不同的编程概念
工作流示例
初级-机器人指令科目
- 挑战：“帮助机器人穿越迷宫”
- 可用卡片：前进、左转、右转、重复
- 构建：排列卡片以创建移动序列
- 执行：查看机器人的可视化路径
- 反馈：“干得好！你的机器人用8步就达到了目标。你能找到一条更短的路径吗？”
大学水平-神经网络学科
- 挑战：“构建一个简单的神经网络进行分类”
- 可用卡：输入层、密集层、激活函数、训练模型、预测
- 构建：使用卡设计网络架构
- 执行：对样本数据进行培训，并查看准确性指标
- 反馈：“优秀的架构！你的模型达到了94%的准确率。尝试尝试不同的激活功能。”
文档
对于用户
对于开发者
- 文档_INDEX.md -完整的文档概述
- 规格说明 -要求和设计
- MCP集成 -代码执行设置
- 测试 -测试策略和指南
黑客马拉松评委
- KIROWEEN_SUBMISSION.md -主要黑客马拉松提交
- SPEC_RETROSPECTIVE.md -规范驱动的开发分析
- Kiro功能展示 -我们如何使用Kiro
Kiro功能展示
该项目展示了Kiroween黑客马拉松的所有四个关键Kiro功能：
1.规范驱动开发✅
我们建造了什么：完成规范工作流程，包括需求、设计和实施任务
文件:
.kiro/specs/dynamic-punchcard-ai/requirements.md-10项要求，50+验收标准.kiro/specs/dynamic-punchcard-ai/design.md-架构，11个正确性属性.kiro/specs/dynamic-punchcard-ai/tasks.md-19项任务（15项已完成，79%）
过程:
- 需求阶段：使用EARS语法、验收标准、术语表定义用户故事
- 设计阶段：创建架构图、接口定义、正确性属性
- 任务规划：分解为具有基于属性的测试子任务的可操作任务
- 实施：按顺序执行任务，根据验收标准进行验证
影响:
- 开发速度提高15%（节省5天）
- 91.6%的测试覆盖率
- 最小的技术债务（1次小重构）
- 从第一天开始完成文档
了解更多：参见 SPEC_RETROSPECTIVE.md 进行详细分析
2.指导文件✅
我们建造了什么：三个全面的人工智能行为指南
文件:
.kiro/steering/ai-behavior.md-挑战生成、反馈语气、代码质量.kiro/steering/card-patterns.md-卡片设计标准和类别.kiro/steering/subject-generation.md-主题多样性和验证规则
运作原理:
- 根据文件模式自动包含指导文档
- 生成过程中的AI服务参考指南
- 确保所有人工智能交互的质量一致
影响:
- 反馈一致性：95%（高于60%）
- 挑战质量：90%（高于70%）
- 主题多样性：100%（高于75%）
- 不适当内容：0%（低于5%）
示例：反馈从“错误。修复您的代码。”更改为“好的开始！您的代码成功读取了数据。但是，输出按原始顺序显示数字，而不是排序。请尝试添加排序步骤…”
3.胡克特工✅
我们建造了什么：自动测试和文件保存
文件:
.kiro/hooks/test-on-save.json-保存TypeScript文件时自动运行测试.kiro/hooks/lint-on-save.json-保存时自动修复代码样式
工作流程自动化:
- 连续测试：每次保存时都会自动运行测试，立即捕捉回归
- 代码质量：Linter自动修复问题，保持风格一致
- 回归预防：在开发过程中发现了15个以上的回归
影响:
- 节省时间：每天3-5小时
- 提交前捕获的Bug：15+
- 代码审查时间缩短：40%
- CI故障减少：60%
了解更多：参见 .kiro/hocks/README.md
4.MCP集成✅
我们建造了什么：通过模型上下文协议安全、真实地执行代码
配置: .kiro/settings/mcp.json -MCP代码执行器服务器设置
问题解决了：安全执行用户生成的代码并返回真实结果
功能已启用:
- 在隔离沙箱中安全执行（无文件/网络访问）
- 代码执行时的真实stdout/stderr输出
- 实际Python错误消息和堆栈跟踪
- 性能指标（执行时间、内存使用情况）
- 资源限制（5秒超时，128MB内存）
影响:
- 真实代码执行（非模拟）
- 用于学习的实际错误消息
- 高教育价值
- 简单设置（单
npx命令）
演出:
- 平均执行时间：150-300ms
- 成功率：99.5%
- 超时率：\<1%
了解更多：参见 MCP_INTEGRATION.md 获取完整指南
______________________________________________________________________
完整的Kiro功能文档
对于对我们如何使用Kiro感兴趣的黑客马拉松评委和开发人员：
📄 哈克顿.md -通过示例和指标完成Kiro功能演示
本文件提供：
- 每个Kiro功能的详细说明
- 实现示例和代码片段
- 显示影响的前后比较
- 效益指标和证据
- 功能如何协同工作
关键创新：人工智能生成的学习路径
问题
传统的教育平台提供静态的、一刀切的学习路径。学生无法探索他们热衷的话题，导致脱离接触。
我们的解决方案
动态主题生成 -学生选择他们想学习的内容，人工智能会生成个性化的学习体验。
运作原理
- 学生选择级别：小学、中学、高中或大学
- AI生成6个主题：机器人、艺术、科学、游戏、数据、网络、人工智能等主题多样
- 学生选择或创建：从生成的主题中选择或创建自定义主题
- 一切一致：挑战和卡片会自动匹配所选科目
示例：音乐科目（中学）
生成的主题:
- 🎵 名称：“音乐与声音”
- 描述：“创作旋律，探索声音节目”
- 关键词：音乐、声音、旋律、节奏、音符
生成的挑战:
- 标题：“谱写简单旋律”
- 目标：“创造一系列音符，形成悦耳的旋律”
生成的卡片:
- 🎵 播放音符（输入）-“播放音符”
- 🎼 创作旋律（过程）-“将音符组合成旋律”
- 🔊 调节音量（控制）-“更改音量”
- 📻 输出声音（Output）-“播放音乐”
为何这很重要
✅ 个性化学习：学生通过他们喜欢的主题学习 ✅ 无穷变化：AI生成无限的独特主题 ✅ 更高的参与度：基于兴趣的学习增加了动力 ✅ 适应性强：适用于任何主题、任何级别
技术实现
主题生成器 (services/subjectGenerator.ts):
- 使用具有结构化JSON输出的Gemini AI
- 确保多样性（没有重叠的关键字）
- 验证年龄水平的适当性
- 缓存性能结果
挑战生成器 (services/challengeGenerator.ts):
- 将挑战与主题关键字对齐
- 验证主题挑战的一致性
- 根据表现调整难度
卡片库管理员 (services/cardLibraryManager.ts):
- 生成主题卡片
- 按要求/可选/高级分类
- 确保卡片能够解决挑战
技术栈
- 前端：React 18、TypeScript、顺风CSS
- 构建：快
- 人工智能：Google Gemini 2.5 Flash API
- 代码执行：MCP代码执行器服务器
- 测试：Vitest，快速检查（基于属性的测试）
- 发展：Kiro IDE，带规格、挂钩、转向、MCP
项目结构
punchcard-ai/
├── .kiro/ # Kiro configuration
│ ├── specs/ # Specification documents
│ ├── steering/ # AI behavior guidelines
│ ├── hooks/ # Agent hooks
│ └── settings/ # MCP configuration
├── components/ # React components
├── services/ # Business logic services
├── test/ # Test utilities
├── MCP_INTEGRATION.md # MCP setup guide
├── SPEC_RETROSPECTIVE.md # Development analysis
└── KIROWEEN_SUBMISSION.md # Hackathon submission开发过程
规范驱动的开发工作流程
该项目是使用Kiro的规范驱动开发方法构建的：
1.需求阶段（2天）
# Created requirements document
.kiro/specs/dynamic-punchcard-ai/requirements.md- 定义了10个具有接受标准的用户故事
- 为了清晰起见，使用了EARS语法
- 创建技术术语表
- 已通过INCOSE质量规则验证
2.设计阶段（3天）
# Created design document
.kiro/specs/dynamic-punchcard-ai/design.md- 设计了6个核心服务的系统架构
- 定义了11个测试正确性属性
- 创建接口规范和数据模型
- 计划的错误处理和测试策略
3.任务规划（1天）
# Created task list
.kiro/specs/dynamic-punchcard-ai/tasks.md- 分解为19个可操作的任务
- 添加了基于属性的测试子任务
- 包括验证检查点
- 标记MVP焦点的可选任务
4.实施（10天）
# Executed tasks sequentially
# Completed 15/19 tasks (79%)
# Maintained 91.6% test coverage我们如何使用Kiro功能
指导文件
指导文档自动引导AI行为：
# When working on subjectGenerator.ts
# → .kiro/steering/subject-generation.md is automatically included
# When working on cardLibraryManager.ts
# → .kiro/steering/card-patterns.md is automatically included
# Always included
# → .kiro/steering/ai-behavior.md结果：一致的AI行为，无需手动提示
胡克探员
挂钩自动化测试和质量检查：
# Save a TypeScript file
# → test-on-save.json runs tests automatically
# → lint-on-save.json fixes code style
# Immediate feedback on every save
# Catches regressions before commit结果：每天节省3-5小时，捕获15次以上的回归
MCP集成
MCP支持实际代码执行：
# Start MCP server (automatic in Kiro)
npx @modelcontextprotocol/server-code-executor
# Code execution flow:
# 1. Student builds card deck
# 2. Gemini converts cards to Python code
# 3. MCP executes code safely in sandbox
# 4. Real output returned to student结果：从实际代码执行中真正学习
运行测试
# Run all tests
npm test
# Run tests in watch mode
npm test -- --watch
# Run with coverage
npm test -- --coverage
# Run property-based tests (800 iterations)
npm test -- --run代码质量
# Lint code (auto-runs on save via hook)
npm run lint
# Format code
npm run format
# Type check
npm run type-check建筑
# Build for production
npm run build
# Preview production build
npm run preview开发技巧
- 遵循规范：始终参考要求和设计文件
- 使用挂钩：让钩子自动捕捉问题
- 信任指导：指导文件确保一致的人工智能行为
- 使用MCP进行测试：使用真实代码执行进行真实测试
- 文档任务：在执行过程中更新任务完成文档
测试
- 单元测试：涵盖服务层的49个测试
- 基于属性的测试：8个属性，800次迭代
- 集成测试：6个端到端用户流
- 覆盖：总体91.6%
看 测试.md 详细的测试策略。
贡献
这是一个黑客马拉松项目，但欢迎投稿！
- 复刻仓库
- 创建要素分支
- 遵循规范驱动的开发流程
- 为新功能编写测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
- 开发 IDE：用于规范驱动的开发、挂钩、转向和MCP
- 谷歌双子座：用于AI驱动的代码生成和分析
- 模型上下文协议：用于安全执行代码
- Kiroween 黑客 马拉松：为了获得复活穿孔卡片的灵感
链接
- 现场演示 -即将推出
- 视频演练 -即将推出
- 开发 IDE
- Kiroween 黑客 马拉松
联系
如有疑问或反馈：
- 在GitHub上打开一个问题
- 检查 文档_INDEX.md 查看详细文档
______________________________________________________________________
内置于❤️ 使用Kiro IDE
Kiroween 2025-复活类别
*用现代人工智能让过时的技术起死回生*