在一周内使用 Kiro IDE 构建我的第一个 RAG 系统 🎃

发布: 3天前 (2025年12月3日 GMT+8 02:26)

8 min read

Source: Dev.to

🎃 The Challenge

作为一名初级应用开发者，我从未构建过 RAG（检索增强生成）系统。这个概念看起来令人望而生畏：向量嵌入、语义搜索、分块策略——全部是陌生领域。但 Kiroween 黑客马拉松的 “Skeleton Crew” 类别激发了我的灵感：如果我能构建一个可复用的骨架，让它可以变身为任何 AI 人格怎么办？

七天后，我拥有了 Project Corpus：一个可投入生产的 RAG 聊天机器人，它可以变成专业的法律助理、神秘的灵体，或其他任何角色——只需更换一个配置文件。

🔗 Live Demo | GitHub Repo

🔮 What is Project Corpus?

Project Corpus 是一个带有特殊设定的文档聊天应用：相同的核心逻辑驱动截然不同的 AI 人格。

Two Personalities, One Skeleton

⚖️ Legal Eagle

专业的法律文档分析
正式的回复并附带精确引用
蓝色企业风格并带有打字机音效
适用于合同分析和法律研究

👻 Ouija Board

来自“彼岸”的神秘文档探索
隐晦、氛围感十足的回复并配以恐怖表情符号
暗黑哥特主题并带有血滴动画
环境无人机音效并伴随静态故障效果

两个应用共享同一个 skeleton_core 模块——只需更改配置即可。

🛠️ The Tech Stack

Backend

Python 3.13 + Flask 3.1.0
ChromaDB 0.5.20（向量数据库）
Google Gemini API 0.8.3（嵌入 + 生成）
pypdf 5.1.0（PDF 处理）

Frontend

原生 JavaScript（无框架）
使用主题变量的自定义 CSS
Server‑Sent Events 实现实时进度

Testing

pytest 7.4.3
hypothesis 6.92.1（基于属性的测试）

Development

Kiro IDE（秘密武器 🚀）

🤖 How Kiro Transformed My Development

1. 🎨 Vibe Coding: Learning While Building

作为初级开发者，我需要理解 RAG，而不仅仅是写代码。Kiro 的对话式方式让我在学习的同时完成构建。

示例对话

Me: "How do I chunk PDFs by page and preserve page numbers?"
Kiro: *Explains chunking strategies, then generates code that:*
- Extracts PDF pages individually
- Chunks each page with 500 char / 50 overlap
- Stores metadata with source, page, chunk_index
- Retrieves page numbers in search results

最令人印象深刻的生成

Kiro 在一次对话中完成了整个 Server‑Sent Events 上传管道，包括：

使用 Response(stream_with_context()) 的 Flask SSE 流式传输
四阶段进度计算（读取、解析、向量化、完成）
客户端 EventSource 监听器与进度条
优雅的错误处理

我之前从未使用过 SSE；Kiro 不仅写出了代码，还解释了为何 SSE 在此场景下优于轮询。

2. 📋 Specs: Systematic UI Polish

在使用 vibe coding 完成核心功能后，我在 .kiro/spec.md 中描述了期望的用户体验：

## 4. Implemented Features
1. **Document Upload (`/upload`):**
   - Real‑time progress tracking via SSE
   - Page‑aware chunking with metadata
   - File validation (type, size, content)

2. **Chat Interface (`/chat`):**
   - Semantic search with relevance filtering
   - Source citations with page numbers
   - Typewriter effect for responses

有了规范，我只需说 “implement section 4.1”，Kiro 就会系统性地添加所有功能——无需来回沟通。

Vibe Coding vs. Specs

Vibe Coding：探索式，适合学习和实现核心功能。
Specs：系统化，适合打磨和完整性。

3. 📚 Steering Docs: Teaching Kiro My Architecture

我创建了四份 steering 文档，向 Kiro 传授项目的 DNA。

structure.md – The game‑changer

### Skeleton + Config Pattern

The `skeleton_core` module contains all shared RAG functionality.  
Individual app folders provide configuration objects that customize behavior.

Each `app_*/config.py` must define:
- `APP_NAME`: String for branding  
- `THEME_CSS`: CSS theme identifier  
- `SYSTEM_PROMPT`: AI personality instructions  
- `CHUNK_SIZE`, `CHUNK_OVERLAP`, `TOP_K_RESULTS`, `RELEVANCE_THRESHOLD`

使用 steering 文档前

Me: “Add a delete document feature”
Kiro: 直接修改 app_legal/main.py ❌（破坏可复用性）

使用 steering 文档后

Me: “Add a delete document feature”
Kiro: 在 skeleton_core/vector_store.py 中添加 delete_document()，创建 /documents/ DELETE 路由，更新前端 ✅（保持骨架模式）

Steering 文档将 “错误建议” 减少了约 80%，让 Kiro 成为懂项目哲学而非仅懂语法的伙伴。

4. 🪝 Agent Hooks: Automated Quality Assurance

我构建了五个钩子，在部署前捕获 bug。

test-runner-on-save.kiro.hook

{
  "when": { "type": "fileEdited", "patterns": ["**/*.py"] },
  "then": { "type": "runCommand", "command": "pytest --tb=short -q" }
}

每次保存时自动运行测试，立即捕获破坏性更改。

config-validator.kiro.hook – 验证配置文件是否包含所有必需字段，防止运行时错误。

env-check-on-session.kiro.hook – 在会话启动时检查 GOOGLE_API_KEY 是否存在，省去大量调试时间。

Impact – 将工作流从被动调试转为主动验证，为初级开发者提供安全网。

🧟 The Biggest Challenges

1. RAG Learning Curve

向量嵌入、语义搜索和分块的概念让人不知所措。Kiro 成为我的老师，在搜索结果不相关时提供解释和解决方案。

Solution: 实现了相关性过滤，仅显示与最佳匹配距离在 0.3 单位以内的文档，确保引用准确。

2. Page‑Aware Chunking

在提取 → 分块 → 嵌入 → 存储 → 检索的整个链路中保留页码，需要细致的元数据管理。

Solution: 在每个阶段都添加页码元数据，例如：

metadata = {
    "source": filename,
    "page": page_num,
    "chunk_index": i
}

3. Theme Switching Architecture

从单一代码库支持截然不同的人格，需要强大的抽象层。

Solution: 采用基于配置的方式；现在添加新人格大约只需 10 分钟。

🏆 What I’m Proud Of

1. Learning RAG in One Week

从零基础到拥有向量搜索、嵌入和语义检索的生产级系统，仅用了 7 天。Kiro 的 vibe coding 让这一切成为可能。

2. The Skeleton Pattern Works

架构真正可复用。添加新人格的步骤简洁到：

mkdir app_detective
# Add config.py with Config class
# Add main.py entry point
# Done! 🎉

3. Production‑Quality UI

流畅的动画（打字机效果、血滴）
使用 SSE 的实时上传进度
带有筛选功能的文档库
可访问性（ARIA 标签、键盘导航）
主题专属音效（打字机、环境无人机）