# cozyengine

**Repository Path**: xingmulee/cozyengine

## Basic Information

- **Project Name**: cozyengine
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CozyEngine 文档中心

> **最后更新**: 2026-02-09  
> **文档规范**: [文档规范-v1.0](./standards/文档规范-v1.0-2026-01-09.md)

---

## 📂 目录结构

### 📋 PRD（产品需求文档）- `prd/`

产品需求定义和需求变更记录。

| 文档 | 版本 | 说明 |
|------|------|------|
| [CozyEngine-PRD-完整需求文档](./prd/CozyEngine-PRD-完整需求文档-v1.0-2026-02-09.md) | v1.0 | **主需求文档**，包含 7 大业务场景、Voice Engine、Realtime API 等完整需求 |
| [CozyEngine-PRD-v1.0-更新说明](./prd/CozyEngine-PRD-v1.0-更新说明.md) | v1.0 | PRD 更新记录和变更说明 |

### 🏗️ 架构设计（主设计依据）- `engine-v2/`

CozyEngine v2.0 核心设计文档，**开发必须严格对齐这些文档**。

| 文档 | 版本 | 说明 |
|------|------|------|
| [INDEX-v2.0](./engine-v2/INDEX-v2.0-2026-01-09.md) | v2.0 | **设计文档索引** |
| [00-愿景与范围](./engine-v2/00-愿景与范围-v2.0-2026-01-09.md) | v2.0 | 项目目标和边界 |
| [01-现状分析-CozyChat后端](./engine-v2/01-现状分析-CozyChat后端-v2.0-2026-01-09.md) | v2.0 | CozyChat 现状分析 |
| [02-总体架构](./engine-v2/02-总体架构-v2.0-2026-01-09.md) | v2.0 | **核心架构设计** |
| [03-核心概念与术语](./engine-v2/03-核心概念与术语-v2.0-2026-01-09.md) | v2.0 | 术语表 |
| [04-目录结构与分层规范](./engine-v2/04-目录结构与分层规范-v2.0-2026-01-09.md) | v2.0 | 代码目录结构 |
| [05-插件系统设计](./engine-v2/05-插件系统设计-v2.0-2026-01-09.md) | v2.0 | **插件架构设计** |
| [06-引擎接口规范](./engine-v2/06-引擎接口规范-v2.0-2026-01-09.md) | v2.0 | 引擎接口定义 |
| [07-编排与上下文构建](./engine-v2/07-编排与上下文构建-v2.0-2026-01-09.md) | v2.0 | **核心编排逻辑** |
| [08-API设计（OpenAI兼容+CozyChat兼容）](./engine-v2/08-API设计（OpenAI兼容+CozyChat兼容）-v2.0-2026-01-09.md) | v2.0 | API 规范 |
| [09-数据与存储设计](./engine-v2/09-数据与存储设计-v2.0-2026-01-09.md) | v2.0 | 数据库设计 |
| [10-配置与环境变量](./engine-v2/10-配置与环境变量-v2.0-2026-01-09.md) | v2.0 | 配置管理 |
| [11-错误处理与可观测性](./engine-v2/11-错误处理与可观测性-v2.0-2026-01-09.md) | v2.0 | 错误处理和监控 |
| [12-性能与缓存策略](./engine-v2/12-性能与缓存策略-v2.0-2026-01-09.md) | v2.0 | 性能优化 |
| [13-测试策略](./engine-v2/13-测试策略-v2.0-2026-01-09.md) | v2.0 | 测试方案 |
| [14-迁移与实施计划](./engine-v2/14-迁移与实施计划-v2.0-2026-01-09.md) | v2.0 | 实施路线图 |
| [15-部署与运行手册](./engine-v2/15-部署与运行手册-v2.0-2026-01-09.md) | v2.0 | 部署指南 |
| [16-安全与权限模型](./engine-v2/16-安全与权限模型-v2.0-2026-01-09.md) | v2.0 | 安全设计 |
| [17-插件开发指南](./engine-v2/17-插件开发指南-v2.0-2026-01-09.md) | v2.0 | 插件开发文档 |
| [CozyEngine-数据库设计详细规范](./engine-v2/CozyEngine-数据库设计详细规范-v1.0-2026-02-09.md) | v1.0 | **数据库详细设计** ⭐ |
| [CozyEngine-安全加固方案](./engine-v2/CozyEngine-安全加固方案-v1.0-2026-02-09.md) | v1.0 | **安全加固方案** ⭐ |

### 📊 评审报告 - `reports/`

一次性分析报告、技术评估、可行性分析等（不作为主设计依据）。

| 文档 | 版本 | 说明 |
|------|------|------|
| [CozyEngine-需求可行性评审报告](./reports/CozyEngine-需求可行性评审报告-v1.0-2026-02-09.md) | v1.0 | **可行性评审**，综合评分 8.7/10，识别 3 个高风险项 |
| [CozyEngine-架构评审报告](./reports/CozyEngine-架构评审报告-v1.0-2026-02-09.md) | v1.0 | 架构设计评审 |
| [FastRTC-技术评估报告](./reports/FastRTC-技术评估报告-v1.0-2026-02-09.md) | v1.0 | **FastRTC 技术评估**，综合评分 9.3/10，推荐采用 ⭐ |
| [CozyEngine-高风险技术解决方案](./reports/CozyEngine-高风险技术解决方案-v2.0-基于FastRTC-2026-02-09.md) | v2.0 | **高风险解决方案**（基于 FastRTC），节省 10-12 人天 ⭐⭐ |

### 🏛️ 架构图 - `architecture/`

系统架构图和架构说明文档。

| 文档 | 版本 | 说明 |
|------|------|------|
| [CozyEngine-系统架构图](./architecture/CozyEngine-系统架构图-v1.0-2026-02-09.png) | v1.0 | **系统架构图**（PNG 格式） |
| [CozyEngine-系统架构图说明](./architecture/CozyEngine-系统架构图说明-v1.0-2026-02-09.md) | v1.0 | 架构图详细说明 |

### 📅 开发计划 - `plans/`

项目计划、任务分解、里程碑等。

| 文档 | 版本 | 说明 |
|------|------|------|
| [CozyEngine-v2-开发任务计划书](./plans/CozyEngine-v2-开发任务计划书-v1.1-2026-02-09.md) | v1.1 | 开发任务计划 |

### 📝 草稿 - `drafts/`

早期设计草稿和实验性文档。

| 文档 | 版本 | 说明 |
|------|------|------|
| [CozyEngine-插件式人格化聊天引擎架构设计](./drafts/CozyEngine-插件式人格化聊天引擎架构设计-v1.0-2026-01-09.md) | v1.0 | 早期架构草稿 |

### 📐 规范 - `standards/`

团队开发规范、文档规范、代码规范等。

| 文档 | 版本 | 说明 |
|------|------|------|
| [文档规范](./standards/文档规范-v1.0-2026-01-09.md) | v1.0 | **文档管理规范**（MUST 遵守） |

### 🔧 运维手册 - `runbooks/`

部署、运维、故障排查等操作手册。

| 文档 | 版本 | 说明 |
|------|------|------|
| _（待补充）_ | - | - |

### 🎯 架构决策记录 - `adr/`

重要架构决策记录（Architecture Decision Records）。

| 文档 | 版本 | 说明 |
|------|------|------|
| _（待补充）_ | - | - |

### 📡 API 文档 - `api/`

对外/对内 API 详细说明。

| 文档 | 版本 | 说明 |
|------|------|------|
| _（待补充）_ | - | 当前 API 规范在 [08-API设计](./engine-v2/08-API设计（OpenAI兼容+CozyChat兼容）-v2.0-2026-01-09.md) |

---

## 🚀 快速导航

### 新成员入门

1. **了解项目**：[00-愿景与范围](./engine-v2/00-愿景与范围-v2.0-2026-01-09.md)
2. **理解架构**：[02-总体架构](./engine-v2/02-总体架构-v2.0-2026-01-09.md)
3. **查看需求**：[CozyEngine-PRD-完整需求文档](./prd/CozyEngine-PRD-完整需求文档-v1.0-2026-02-09.md)
4. **开发规范**：[文档规范](./standards/文档规范-v1.0-2026-01-09.md)

### 开发指南

1. **核心编排逻辑**：[07-编排与上下文构建](./engine-v2/07-编排与上下文构建-v2.0-2026-01-09.md)
2. **插件开发**：[17-插件开发指南](./engine-v2/17-插件开发指南-v2.0-2026-01-09.md)
3. **API 开发**：[08-API设计](./engine-v2/08-API设计（OpenAI兼容+CozyChat兼容）-v2.0-2026-01-09.md)
4. **数据库设计**：[CozyEngine-数据库设计详细规范](./engine-v2/CozyEngine-数据库设计详细规范-v1.0-2026-02-09.md)

### 重点技术方案

1. **Realtime 语音**：[CozyEngine-高风险技术解决方案 v2.0](./reports/CozyEngine-高风险技术解决方案-v2.0-基于FastRTC-2026-02-09.md) ⭐⭐
   - 基于 FastRTC 实现
   - 节省 10-12 人天
   - 延迟 120-150ms（降低 50%）
   - 技术风险：高 → 低

2. **FastRTC 评估**：[FastRTC-技术评估报告](./reports/FastRTC-技术评估报告-v1.0-2026-02-09.md) ⭐
   - 综合评分：9.3/10
   - Gradio 官方库
   - 220+ 用户验证

3. **安全加固**：[CozyEngine-安全加固方案](./engine-v2/CozyEngine-安全加固方案-v1.0-2026-02-09.md) ⭐
   - 五层工具安全防护
   - 完整审计日志
   - 熔断器与降级策略

---

## 📋 文档维护规范

### 版本策略

- **patch (v2.0 → v2.0.1)**：错别字、非行为变化、补充示例
- **minor (v2.0 → v2.1)**：接口/行为/边界变化，但总体架构不变
- **major (v2.x → v3.0)**：架构级变化或兼容性断裂

### 文件命名

格式：`<主题>-vX.Y-YYYY-MM-DD.md`

示例：`编排与上下文构建-v2.0-2026-01-09.md`

### 文档头部

每个文档必须包含：

```markdown
> **文档版本**: vX.Y  
> **更新日期**: YYYY-MM-DD  
> **状态**: draft|active|deprecated  
> **适用范围**: CozyEngine backend / docs / ...
```

### 设计变更纪律 ⚠️

**开发必须严格对齐 `docs/engine-v2/`！**

如果实现需要偏离设计：
1. 先修改对应设计文档（原文件）并升级版本
2. 必要时新增 ADR 记录关键决策
3. 再修改代码

禁止随意新建设计文档分叉主题。

---

## 📞 联系方式

- **文档维护者**：架构团队
- **最后更新**：2026-02-09
- **规范文档**：[文档规范-v1.0](./standards/文档规范-v1.0-2026-01-09.md)

---

## 📈 项目状态

| 指标 | 状态 |
|------|------|
| **项目阶段** | 设计完成，开发启动 |
| **核心架构** | ✅ 完成（v2.0） |
| **PRD** | ✅ 完成（v1.0） |
| **技术方案** | ✅ 完成（v2.0 基于 FastRTC） ⭐ |
| **数据库设计** | ✅ 完成（v1.0） |
| **安全方案** | ✅ 完成（v1.0） |
| **开发计划** | ✅ 完成（v1.0） |
| **预计开发周期** | 14-20 天（节省 4-5 天） ⭐ |

**下一步**：启动 Phase 1 开发（基础框架）