综合实战项目

从Spec到上线的完整企业级项目实战

引言

学了 17 章的知识，是时候把它们串起来了。

本章将带你用 CodeBuddy 从零开始完成一个完整的企业级项目：在线协作文档平台。我们将完整走一遍规范驱动编程的全流程，展示如何将 Spec-Kit、Plan 模式、智能体模式、Skills、Hooks 协同使用。

目标：不是做一个完美的产品，而是展示一个完整的工作流。

一、阶段 1：Spec-Kit 规范驱动

1.1 写项目宪法（Constitution）

# 协作文档平台 - 项目宪法

## 核心原则
1. 实时协作优先：多人同时编辑不冲突
2. 数据安全不可妥协：端到端加密
3. 用户体验简洁直观：3 秒内理解如何使用

## 技术栈
- 前端：React 18 + Tiptap 编辑器 + Yjs（CRDT）
- 后端：Node.js + WebSocket（ws 库）
- 数据库：PostgreSQL + Redis（在线状态）
- 部署：Docker + Docker Compose

## 编码规范
- TypeScript strict 模式
- 测试覆盖率 > 80%
- 所有 API 有 OpenAPI 文档
- 错误码统一管理

1.2 写功能规范（Specification）

# 实时编辑功能规范

## 用户故事
- 作为用户，我可以创建新文档
- 作为用户，我可以邀请他人协作编辑
- 作为用户，我可以看到他人的光标位置
- 作为用户，我的修改会实时同步给所有人

## 技术要求
- 使用 Yjs CRDT 算法解决冲突
- WebSocket 连接断开后自动重连
- 离线编辑，联网后自动同步
- 文档历史版本保留 30 天

## 接口定义
### WebSocket /ws/doc/:docId
- 客户端发送：{ type: "update", data: YjsUpdate }
- 服务端广播：{ type: "update", data: YjsUpdate, userId: string }
- 光标同步：{ type: "cursor", data: { line: number, col: number } }

### REST API
- POST /api/docs - 创建文档
- GET /api/docs/:id - 获取文档
- POST /api/docs/:id/invite - 邀请协作者

## 验收标准
- [ ] 两人同时编辑，双方实时看到对方修改
- [ ] 断网后编辑不丢失，重连后自动同步
- [ ] 光标位置实时同步（延迟 < 100ms）
- [ ] 文档历史可回溯

二、阶段 2：Plan 模式设计

2.1 AI 提出澄清问题

AI: 关于实时协作的冲突解决策略，需要确认：

    1. 协作算法：
       A) OT（Operational Transformation）- 适合富文本
       B) CRDT（Conflict-free Replicated Data Type）- 去中心化
       C) 简单的后写入覆盖 - 适合低冲突场景

    2. 文档大小限制：
       A) 无限制
       B) 最大 1MB
       C) 最大 10MB

    3. 历史版本保留：
       A) 保留所有版本（存储成本高）
       B) 保留 30 天
       C) 保留最近 100 个版本

你: 选 B（CRDT），B（1MB），B（30天）

2.2 AI 输出实现方案

实现方案：

1. 数据模型设计（30分钟）
   - Document 模型（id, title, content, createdAt）
   - DocumentVersion 模型（docId, content, timestamp）
   - Collaborator 模型（docId, userId, role）

2. WebSocket 服务（60分钟）
   - Yjs WebSocket Provider 服务端
   - 房间管理（docId → Set<WebSocket>）
   - 光标同步

3. 前端编辑器（45分钟）
   - Tiptap + Yjs 集成
   - 光标渲染
   - 离线支持

4. REST API（30分钟）
   - CRUD 接口
   - 邀请协作者

5. 测试（45分钟）
   - 多人协作测试
   - 断线重连测试

总计：约 3.5 小时

三、阶段 3：智能体模式实现

3.1 AI 自动执行

你：方案没问题，开始执行

AI：开始实现...

✅ Task 1/8: 创建 Prisma schema
   - Document 模型
   - DocumentVersion 模型
   - Collaborator 模型
   - 运行 migration

✅ Task 2/8: 实现 WebSocket 服务
   - 创建 wss 服务器
   - 实现房间管理
   - 集成 Yjs Provider

✅ Task 3/8: 实现光标同步
   - 客户端光标采集
   - 服务端广播
   - 光标渲染组件

✅ Task 4/8: 创建 Tiptap 编辑器
   - 集成 Yjs
   - 工具栏（加粗/斜体/标题/列表）
   - 协作光标显示

✅ Task 5/8: 实现 REST API
   - POST /api/docs
   - GET /api/docs/:id
   - POST /api/docs/:id/invite

✅ Task 6/8: 实现离线支持
   - IndexedDB 存储
   - 联网后自动同步

✅ Task 7/8: 编写测试
   - 单元测试：12 个
   - 集成测试：5 个

✅ Task 8/8: Docker 配置
   - Dockerfile
   - docker-compose.yml
   - 环境变量配置

🎉 实现完成！共修改 15 个文件，新增 800+ 行代码

四、阶段 4：Skills 辅助

4.1 代码审查

你：/skill code-review

AI：代码审查结果：

### src/websocket/server.ts
🔴 第 45 行：WebSocket 连接未验证身份
  风险：任何人都能连接并编辑文档
  修复：添加 token 验证中间件

🟡 第 23 行：房间管理用 Set，断线后未清理
  风险：内存泄漏
  修复：添加 heartbeat + 超时清理

### src/api/docs.ts
🟡 第 67 行：未校验 docId 格式
  风险：SQL 注入（虽然用了 Prisma，但最好验证）
  修复：添加 UUID 格式校验

4.2 生成测试

你：/skill test

AI：为实时协作模块生成测试：

✅ tests/websocket/collaboration.test.ts
   - 两人同时编辑同一段落
   - 断线后重连同步
   - 光标位置同步
   - 10 人同时编辑性能测试

✅ tests/api/docs.test.ts
   - 创建文档
   - 获取文档
   - 邀请协作者
   - 权限验证

五、阶段 5：Hooks 自动化

5.1 配置 Hooks

{
  "preCommit": {
    "command": "npm run lint && npm test",
    "failOnError": true
  },
  "preDeploy": {
    "command": "npm run security-check && npm run test:e2e",
    "failOnError": true
  },
  "postDeploy": {
    "command": "curl -s http://localhost:3000/health | jq .status"
  }
}

5.2 自动化流程

你：提交代码并部署

AI：
  [Pre-Commit Hook]
  ✅ ESLint: 0 errors, 0 warnings
  ✅ Tests: 17 passed, 0 failed

  [Git Commit]
  ✅ feat: add real-time collaborative editing

  [Pre-Deploy Hook]
  ✅ Security check: no vulnerabilities
  ✅ E2E tests: 5 passed

  [Deploy]
  ✅ Build: 234KB
  ✅ Docker build: success
  ✅ Container started

  [Post-Deploy Hook]
  ✅ Health check: "ok"

  🎉 部署成功！访问 https://docs.example.com

六、项目成果

6.1 最终产出

文件	说明
`CONSTITUTION.md`	项目宪法
`specs/realtime-editing.md`	功能规范
`src/`	源代码（15 个文件）
`tests/`	测试用例（17 个）
`docker-compose.yml`	部署配置
`.codebuddy/skills/`	自定义 Skills
`.codebuddy/hooks.json`	Hooks 配置

6.2 核心收获

通过这个项目，你实践了：

能力	对应章节
规范驱动编程	第 11 章（Spec-Kit 全流程）
Plan 模式	第 12 章（需求澄清 + 方案设计）
智能体模式	第 3 章（自主执行复杂任务）
Skills 开发	第 9 章（代码审查 + 测试生成）
Hooks 配置	第 14 章（自动化质量保障）
部署上线	第 17 章（Docker + 健康检查）

七、课程总结

7.1 你学到了什么

基础篇（第 1-6 章）
  → CodeBuddy 是什么、怎么用、核心功能

核心篇（第 7-11 章）
  → Rules + Skills + Memory + Spec-Kit
  → 规范驱动编程的完整方法论

高级篇（第 12-17 章）
  → Plan 模式 + 子代理 + Hooks + MCP + 部署
  → 企业级开发的工程化实践

实战篇（第 18 章）
  → 把所有知识串联，完成一个完整项目

7.2 核心公式

你的价值 = 定义规范的能力

AI 可以写代码，但只有你能定义"什么是正确的代码"。

7.3 持续学习建议

实践：把 Spec-Kit 流程用到你的日常项目中
迭代：从轻量 Spec 开始，逐步升级到完整 Spec-Kit
分享：和团队分享规范驱动编程的方法论
关注：CodeBuddy 官方博客持续更新中

7.4 最后一句话

CodeBuddy 不是替代你，而是让你成为更强大的开发者。

写好规范，让 AI 写代码。 这就是规范驱动编程的本质。