# ai-native

**Repository Path**: dats/ai-native

## Basic Information

- **Project Name**: ai-native
- **Description**: ai项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Native - 可进化的个人AI助手系统

本项目是一个渐进式开发的AI应用，目标是构建一个可进化的个人AI助手系统。

## 项目概览

- **Python版本**: 3.11+
- **前端框架**: React 18.x（Week 5+）
- **技术栈**: Python + React

## 开发计划

详见 [plan.md](./plan.md) 文件。

## 项目结构

```
ai-native/
├── backend/               # Python后端
│   ├── src/              # 源代码
│   │   ├── __init__.py
│   │   ├── utils.py      # 基础工具函数（Week 1 Day 1-2）
│   │   ├── simple_chat.py # 简单聊天程序（Week 1 Day 3-4）
│   │   └── agent_v1.py   # Function Calling Agent（Week 1 Day 5-7）
│   ├── tests/            # 测试文件
│   ├── pyproject.toml    # Python项目配置（uv 依赖管理）
│   └── README.md         # 后端使用说明
├── frontend/             # React前端（Week 5+）
├── docs/                 # 文档
├── scripts/              # 脚本
├── logs/                 # 日志目录
└── data/                 # 数据目录
```

## Week 1 进展

### ✅ Day 1-2: Python基础夯实

**交付物**: `backend/src/utils.py`

包含10个工具函数：
1. `read_json_file()` - 读取JSON文件
2. `write_json_file()` - 写入JSON文件
3. `read_text_file()` - 读取文本文件
4. `write_text_file()` - 写入文本文件
5. `parse_datetime()` - 解析日期时间
6. `format_datetime()` - 格式化日期时间
7. `sanitize_string()` - 清理字符串
8. `chunk_list()` - 列表分块
9. `deep_merge()` - 深度合并字典
10. `retry_with_backoff()` - 带退避的重试装饰器

**验收标准**:
- ✅ 所有函数有类型提示
- ✅ 所有函数有文档字符串
- ✅ 所有函数有异常处理
- ✅ 配套单元测试通过

### ⏳ Day 3-4: 第一次调用LLM

**交付物**: `backend/src/simple_chat.py`

一个最简单的命令行聊天程序。

**使用方法**:
```bash
# 1. 安装 uv（如果未安装）
# Windows PowerShell:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 安装依赖
cd backend
uv pip install -e ".[dev]"

# 3. 配置API密钥
cp .env.example .env
# 编辑 .env 文件，添加你的 OpenAI API Key

# 4. 运行
uv run python src/simple_chat.py
```

**验收标准**:
- 能正常对话
- Ctrl+C能优雅退出
- 有基本的错误处理

### ⏳ Day 5-7: 理解Function Calling

**交付物**: `backend/src/agent_v1.py`

支持天气查询的Agent，能自动决定何时调用工具。

**使用方法**:
```bash
cd backend
uv run python src/agent_v1.py
```

**示例对话**:
```
You: 北京天气怎么样？
[工具调用] get_weather({'city': '北京'})
AI: 北京今天晴天，25°C，湿度45%。

You: 你好
AI: 你好！我是天气助手，有什么可以帮你的吗？
```

## 快速开始

### 环境准备

1. 安装 Python 3.11+
2. 安装 [uv](https://github.com/astral-sh/uv):
```bash
# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

3. 安装依赖:
```bash
cd backend
uv pip install -e ".[dev]"
```

### 验证环境

使用验证脚本检查环境是否配置正确：

```bash
# 从项目根目录运行
python scripts/test_setup.py
```

这会检查：
- Python 版本 (>= 3.11)
- uv 是否已安装
- 依赖是否正确安装
- 项目结构是否完整
- 环境变量是否配置
- utils.py 功能是否正常

### 运行测试

```bash
cd backend

# 运行单元测试
uv run pytest tests/ -v

# 验证工具函数
uv run python verify_utils.py

# 运行聊天程序（需要配置 OPENAI_API_KEY）
uv run python src/simple_chat.py
```

## 规范

- 所有函数必须有类型注解
- 导入顺序：标准库 → 第三方库 → 本地模块
- Git 提交规范: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`

## 合作约定

详见 [docs/合作约定.md](./docs/合作约定.md)