lqcode-sdk 1.1.9
绿旗编程AI课程SDK
Requires Python: >=3.6

# 绿旗编程AI课程项目

本仓库包含两个独立的项目：

## 1. 绿旗编程AI课程SDK (`lqcode_sdk`)

这是绿旗编程AI课程的Python SDK包，提供了与AI课程交互的API。

### 安装

```bash
cd lqcode_sdk
pip install -e .
```

### 使用

```python
from sdk import LqcodeAI

lqcode = LqcodeAI()
token = lqcode.getAIToken(password='lqcode')
```

## 2. 绿旗编程AI课程Streamlit应用 (`lqcode_streamlit`)

这是绿旗编程AI课程的Web界面，基于Streamlit构建。

### 安装

```bash
cd lqcode_streamlit
pip install -r requirements.txt
```

### 运行

```bash
cd lqcode_streamlit
streamlit run Home.py
```

### 功能

- 用户进度跟踪
- 课程展示
- 教学内容管理

## 聊天室功能使用说明

### 作为服务器（主机）

```python
from lqcode_sdk.lqcodeAI import ChatRoomAI

# 创建聊天室实例
chatroom = ChatRoomAI()

# 设置消息接收回调
def on_message(message):
    print(f"收到消息: {message}")

chatroom.set_message_callback(on_message)

# 启动服务器
result = chatroom.start_server(5000)
print(result["message"])

# 发送消息
result = chatroom.send_message("大家好！")
print(result["message"])

# 停止服务器
result = chatroom.stop()
print(result["message"])
```

### 作为客户端（从机）

```python
from lqcode_sdk.lqcodeAI import ChatRoomAI

# 创建聊天室实例
chatroom = ChatRoomAI()

# 设置消息接收回调
def on_message(message):
    print(f"收到消息: {message}")

chatroom.set_message_callback(on_message)

# 加入聊天室
result = chatroom.join_chatroom("192.168.1.100", 5000)  # 替换为主机的IP地址
print(result["message"])

# 发送消息
result = chatroom.send_message("大家好！")
print(result["message"])

# 停止客户端
result = chatroom.stop()
print(result["message"])
```

### 注意事项

1. 确保主机和从机在同一个网络中
2. 主机需要开放指定的端口（默认5000）
3. 从机需要知道主机的IP地址和端口号
4. 消息以JSON格式传输，包含type和content字段
5. 使用回调函数处理接收到的消息
6. 记得在程序结束时调用stop()方法

## 许可证

本项目基于MIT许可证开源。

# LqcodeSDK 开发指南

## 项目概述

LqcodeSDK是一个基于Coze平台的AI功能开发框架，提供了统一的接口和基础功能，方便开发者快速实现各种AI功能。

## 开发新AI功能的步骤

### 1. 创建新的AI功能类

1. 在`lqcode_sdk/lqcodeAI`目录下创建新的Python文件，例如`ai_newfeature.py`
2. 创建继承自`BaseAI`的类：

```python
from typing import Any, Dict
from .base import BaseAI
from .types import NewFeatureResult  # 需要先定义返回类型

class NewFeatureAI(BaseAI):
    """新功能AI类"""
    
    def ai_newfeature(self, password: str, input_param: str) -> NewFeatureResult:
        """新功能的主要方法
        
        Args:
            password: 访问密码
            input_param: 输入参数
            
        Returns:
            NewFeatureResult: 包含结果的字典
        """
        if not password or not isinstance(password, str):
            raise ValueError("password必须是有效的字符串")
        if not input_param or not isinstance(input_param, str):
            raise ValueError("input_param必须是有效的字符串")
            
        parameters = {
            "input": input_param,
            "choose": "NEW_FEATURE",  # 对应Coze工作流中的选择
        }
        result = self._execute_workflow(password, parameters)
        if "error" in result:
            return {"result": result["error"]}
        return result

    def _parse_output(self, output: Any) -> NewFeatureResult:
        """解析工作流输出
        
        Args:
            output: 工作流返回的输出
            
        Returns:
            NewFeatureResult: 解析后的结果
        """
        if isinstance(output, dict):
            return {
                "result": output.get('result', "")
            }
        return {"result": str(output)}
```

### 2. 定义返回类型

在`lqcode_sdk/lqcodeAI/types.py`中添加新的返回类型：

```python
from typing import TypedDict

class NewFeatureResult(TypedDict):
    """新功能的返回类型"""
    result: str
```

### 3. 注册新功能

在`lqcode_sdk/lqcodeAI/__init__.py`中注册新功能：

```python
from .ai_newfeature import NewFeatureAI

__all__ = [
    # ... 其他功能 ...
    'NewFeatureAI',
]
```

### 4. 配置Coze工作流

1. 在Coze平台创建新的工作流
2. 配置工作流参数：
   - 输入参数：`input`（必选）
   - 选择参数：`choose`（必选，值为"NEW_FEATURE"）
3. 在`lqcode_sdk/lqcodeAI/config.py`中添加新的工作流ID：

```python
class Config:
    # ... 其他配置 ...
    NEW_FEATURE_WORKFLOW_ID = "your-workflow-id"
```

### 5. 编写测试用例

在`lqcode_sdk/tests`目录下创建测试文件：

```python
import unittest
from lqcode_sdk.lqcodeAI import NewFeatureAI

class TestNewFeatureAI(unittest.TestCase):
    def setUp(self):
        self.ai = NewFeatureAI()
        
    def test_ai_newfeature(self):
        result = self.ai.ai_newfeature("your-password", "test-input")
        self.assertIsInstance(result, dict)
        self.assertIn("result", result)
```

### 6. 使用示例

```python
from lqcode_sdk.lqcodeAI import NewFeatureAI

# 创建实例
ai = NewFeatureAI()

# 调用功能
result = ai.ai_newfeature("your-password", "input-param")
print(result)
```

## 注意事项

1. 所有AI功能类必须继承自`BaseAI`
2. 必须实现`_parse_output`方法来解析工作流输出
3. 输入参数必须进行类型检查
4. 错误处理要统一使用`_execute_workflow`的返回格式
5. 确保在Coze平台正确配置工作流
6. 编写完整的测试用例
7. 遵循项目的代码风格和规范

## 调试技巧

1. 使用`print`或日志记录关键步骤
2. 检查工作流返回的原始数据
3. 验证参数传递是否正确
4. 测试错误处理机制
5. 使用断点调试复杂逻辑

## 常见问题

1. 工作流ID配置错误
2. 参数类型不匹配
3. 网络连接问题
4. 令牌过期
5. 工作流返回格式不符合预期

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 创建Pull Request
5. 等待代码审查