# LuckyApple

**Repository Path**: jpc_chenjianping/lucky-apple

## Basic Information

- **Project Name**: LuckyApple
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-04-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!--
Lucky-Apple 智能对话工具 - 项目文档

用途：
    Lucky-Apple 是一个基于 OpenAI SDK 的智能对话工具的完整使用文档。

使用方法：
    1. 直接阅读本文档了解项目功能
    2. 按照"安装教程"部分进行环境配置
    3. 参考"使用说明"部分进行实际操作

主要章节：
    - 介绍：项目概述和主要特性
    - 软件架构：项目结构和设计原理
    - 安装教程：环境配置和依赖安装
    - 使用说明：详细的使用方法和示例
    - 参与贡献：开源协作指南
    - 特技：项目亮点和优势

注意事项：
    1. 本文档与代码版本保持同步
    2. 如有疑问请参考"使用说明"部分
    3. 建议先阅读"软件架构"了解设计思路

作者：Lucky-Apple Team
版本：1.0.0
更新日期：2026-03-24
-->

# LuckyApple

#### 介绍
LuckyApple 是一个基于 OpenAI SDK 的智能对话工具，支持会话管理、多轮对话、Skills 能力和自动执行功能。该工具设计简洁，易于使用和扩展，提供完整的会话历史记录和命令系统。

#### 软件架构

**项目结构：**
```
lucky-apple/
├── chat.py              # 主程序文件
├── action_parser.py     # 操作解析器
├── security.py          # 安全管理器
├── action_executor.py   # 操作执行器
├── config.ini           # 配置文件
├── sessions/            # 会话历史存储目录
│   ├── session_xxx.json
│   └── ...
└── README.md            # 项目文档
```

**架构设计：**
- **配置层**：从 config.ini 文件读取 API 配置（api_key、base_url、model）和 Skills 路径
- **Skills 层**：加载和管理开源 Skills，提供专业领域的工作流程和知识
- **会话层**：管理会话生命周期，支持创建新会话和恢复已有会话
- **存储层**：将会话历史以 JSON 格式持久化到本地文件系统
- **命令层**：处理以 `/` 开头的系统命令
- **自动执行层**：解析 LLM 应答中的操作指令，安全执行命令和代码
- **安全层**：验证操作安全性，防止危险命令执行
- **输入层**：支持多种输入方式
  - 交互式输入
  - 文件路径读取（自动检测并读取文件内容）
  - 命令系统（以 `/` 开头）
- **调用层**：使用 OpenAI SDK 进行 API 调用，携带完整会话历史和 Skill 指导
- **输出层**：将 LLM 响应直接输出到控制台

**数据流程：**
1. 加载配置文件 → 2. 加载 Skills → 3. 创建/恢复会话 → 4. 获取用户输入 → 5. 处理命令或构建 API 请求 → 6. 调用 LLM（含历史上下文和 Skill 指导） → 7. 解析操作指令 → 8. 安全验证 → 9. 执行操作 → 10. 保存会话历史 → 11. 输出响应

#### 安装教程

1. 确保已安装 Python 3.7+
2. 安装依赖包：
   ```bash
   pip install openai pyyaml
   ```
3. 克隆或下载项目到本地
4. 配置 config.ini 文件，填入您的 API 信息

#### 使用说明

**配置文件格式（config.ini）：**
```ini
api_key=your_api_key_here
base_url=https://your-api-endpoint.com/api/v3
model=your_model_name
skills_path=/path/to/skills/directory
auto_execute=false
```

**配置参数说明：**
- `api_key`: OpenAI API 密钥
- `base_url`: API 基础 URL
- `model`: 使用的模型名称
- `skills_path`: Skills 目录路径（默认：`/home/chenjianping/01_code/17_code_buddy/skills/skills`）
- `auto_execute`: 是否自动执行操作（默认：false，建议保持 false 以确保安全）

**使用方式：**

1. **创建新会话：**
   ```bash
   python chat.py
   ```
   程序会自动生成一个基于时间戳的会话 ID（如：session_20260323_193617）

2. **恢复已有会话：**
   ```bash
   python chat.py session_20260323_193617
   ```
   程序会加载指定会话的历史记录，继续对话

3. **交互式对话：**
   ```bash
   python chat.py
   # 然后根据提示输入您的请求
   ```

4. **从文件读取请求：**
   ```bash
   # 创建一个包含请求的文本文件
   echo "请介绍一下西湖" > request.txt
   
   # 在对话中输入文件路径
   python chat.py
   # 然后输入：request.txt
   ```

**命令系统：**

- `/sessions` - 查看所有会话列表，显示会话 ID、消息数量、最后更新时间和最后一条消息
- `/switch <session_id>` - 切换到指定的会话，加载该会话的历史记录
- `/new` - 创建一个新的会话并切换到新会话
- `/delete <session_id>` - 删除指定的会话（不能删除当前正在使用的会话）
- `/skills` - 查看所有可用的 Skills 列表
- `/skill <skill_name>` - 查看指定 Skill 的详细信息，并可选择加载使用
- `/log` - 查看操作执行日志
- `/xxx` - 其他以 `/` 开头的输入会被识别为命令，未知命令会显示帮助信息

**Skills 功能：**

Skills 是模块化的专业能力包，每个 Skill 包含特定领域的工作流程、知识和工具。

**查看可用 Skills：**
```bash
python chat.py
# 输入：/skills
```

**使用 Skill：**
```bash
python chat.py
# 输入：/skill doc-coauthoring
# 确认使用：y
# 然后按照 Skill 指导进行对话
```

**Skill 工作原理：**
- 每个 Skill 是一个目录，包含 SKILL.md 文件
- SKILL.md 包含 YAML frontmatter（name, description, license）和详细指导内容
- 加载 Skill 后，其内容会作为 system message 插入到对话中
- LLM 会根据 Skill 指导提供专业领域的服务

**自动执行功能：**

LLM 可以在应答中嵌入可执行的操作指令，程序会自动解析并执行这些操作。

**操作格式：**
LLM 使用以下格式建议执行操作：

```bash:action_type
command_here
```

或

```python:action_type
code_here
```

**支持的 action_type：**
- `install`: 安装依赖包
- `run`: 运行脚本或代码
- `test`: 测试代码
- `setup`: 环境配置
- `check`: 检查状态

**使用示例：**

**示例1：安装依赖包**
```
用户：帮我安装 requests 包

金子：我来帮你安装 requests 包。

```bash:install
pip install requests
```

# 程序会提示用户确认，然后执行安装命令
```

**示例2：运行 Python 代码**
```
用户：用 Python 计算 1 到 100 的和

金子：我将使用 Python 来计算 1 到 100 的和。

```python:run
total = sum(range(1, 101))
print(f"1到100的和是: {total}")
```

# 程序会显示代码，确认后执行并输出结果
```

**示例3：执行 Bash 命令**
```
用户：列出当前目录的文件

金子：我来帮你列出当前目录的文件。

```bash:check
ls -la
```

# 程序会执行 ls 命令并显示结果
```

**执行确认机制：**

当检测到可执行操作时，程序会：
1. 显示操作详情（类型、操作类型、代码）
2. 询问用户是否执行
3. 用户可以选择：
   - `y`: 执行当前操作
   - `n`: 跳过当前操作
   - `a`: 执行当前及后续所有操作
   - `s`: 跳过当前及后续所有操作

**安全机制：**

**1. 操作白名单**
- 只允许执行安全的 Bash 命令（pip install、ls、cd、python 等）
- 禁止危险命令（rm -rf、format、shutdown 等）

**2. Python 代码沙箱**
- 限制可用的内置函数
- 禁止危险的 Python 操作（os.system、subprocess、eval 等）

**3. 用户确认**
- 默认需要用户确认才能执行操作
- 可通过配置文件设置自动执行（不推荐）

**4. 操作日志**
- 记录所有操作执行情况
- 可通过 `/log` 命令查看

**会话管理：**

- 每个会话的历史记录自动保存到 `sessions/{session_id}.json`
- 会话文件以 JSON 数组格式存储，包含所有 system、user 和 assistant 消息
- 每次对话都会自动更新会话文件，确保数据持久化
- 支持多会话并行，每个会话独立存储和管理
- 可以在对话过程中随时切换会话，无需重启程序
- 加载的 Skill 会保存到会话中，恢复会话时 Skill 指导仍然有效

**退出对话：**

输入以下任意命令退出当前会话：
- `exit`
- `quit`
- `退出`

**注意事项：**
- config.ini 文件必须与 chat.py 在同一目录下
- 确保 config.ini 中的配置信息正确无误
- sessions 目录会自动创建，无需手动创建
- 会话历史会持续累积，如需清空历史可删除对应的会话文件
- 删除会话前请确保该会话不是当前正在使用的会话
- Skills 路径默认为 `/home/chenjianping/01_code/17_code_buddy/skills/skills`，可在 config.ini 中自定义
- 建议保持 `auto_execute=false` 以确保安全
- 执行操作前请仔细检查代码内容

#### 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

#### 特技

1. **完整会话管理** - 支持多会话、会话切换、会话删除、历史持久化
2. **上下文连贯** - LLM 能理解之前的对话内容，实现真正的多轮对话
3. **Skills 能力** - 加载专业领域的工作流程和知识，提供专门化服务
4. **自动执行功能** - 解析并执行 LLM 建议的操作，提高效率
5. **安全机制** - 多层安全验证，防止危险操作
6. **灵活的命令系统** - 支持以 `/` 开头的系统命令，易于扩展
7. **多种输入方式** - 支持交互式输入、文件读取、命令输入
8. **配置与代码分离** - 便于管理和部署
9. **简洁的代码结构** - 易于理解和扩展