lqcodeAI 1.2.9

绿旗编程AI课程SDK

🎯 一个文件搞定：AI功能插件开发指南

🎉 终极简化：真正的"一个文件搞定"

经过最新架构优化，现在添加新的AI功能真的只需要创建一个文件！每个插件完全独立，包含自己的类型定义、业务逻辑和注册信息。

✨ 完全自动化的功能

• ✅ 自动发现插件 - 无需手动导入
• ✅ 自动注册功能 - 无需修改注册表
• ✅ 自动生成CLI - 无需配置命令行
• ✅ 插件内部类型定义 - 完全独立，无外部依赖
• ✅ 动态导出 - 自动添加到包的导出列表
• ✅ 完整的类型检查 - 支持TypedDict和IDE智能提示

🆕 最新架构优势

插件完全独立

• 🔒 零外部依赖 - 每个插件都是自包含的
• 📦 类型定义内置 - 不再依赖全局types.py
• 🔧 一文件完整 - 类型、逻辑、配置全在一个文件
• 🚀 即插即用 - 创建文件立即可用

开发体验优化

• 💡 IDE友好 - 完整的类型提示和自动补全
• 🐛 调试简单 - 所有相关代码都在同一文件
• 📝 维护容易 - 修改功能只需要编辑一个文件
• 🔄 版本独立 - 每个插件可以独立更新

🚀 超简单步骤

步骤1：创建插件文件（唯一步骤！）

在 lqcodeAI/plugins/ 目录下创建 ai_你的功能名.py 文件：

"""
你的功能描述
"""
from typing import Any, Dict, TypedDict
from ..core.base import BaseAI
from ..core.plugin_registry import ai_plugin

# 插件内部定义返回类型（推荐做法）
class YourFeatureResult(TypedDict):
    """你的功能结果类型"""
    content: str
    explanation: str

@ai_plugin(
    name="yourfeature",                    # 功能名称
    description="你的功能描述",             # 功能描述
    cli_args=[                            # CLI参数（可选）
        {"name": "input_text", "help": "输入文本", "default": "默认值"},
        {"name": "style", "help": "处理风格", "default": "标准"}
    ],
    result_type=YourFeatureResult          # 返回类型（可选但推荐）
)
class YourFeatureAI(BaseAI):
    """你的功能AI类"""
    
    def ai_yourfeature(self, password: str, input_text: str = "默认值", style: str = "标准") -> YourFeatureResult:
        """你的功能实现
        
        Args:
            password: 访问密码（必需）
            input_text: 输入文本
            style: 处理风格
            
        Returns:
            YourFeatureResult: 返回结果
        """
        # 参数验证
        if not password or not isinstance(password, str):
            raise ValueError("password必须是有效的字符串")
            
        # 准备工作流参数
        parameters = {
            "input": f"用户输入: {input_text}，风格: {style}",
            "choose": "AI_YOUR_TYPE",  # 根据实际工作流类型修改
        }
        
        # 调用工作流
        result = self._execute_workflow(password, parameters)
        
        # 错误处理
        if "error" in result:
            return {"content": result["error"], "explanation": ""}
        
        return result

    def _parse_output(self, output: Any) -> YourFeatureResult:
        """解析输出结果"""
        if isinstance(output, dict):
            return {
                "content": output.get('content', str(output)),
                "explanation": output.get('explanation', "")
            }
        return {"content": str(output), "explanation": ""}

步骤2：完成！

没有步骤2！创建文件后，系统会自动：

• 🔍 发现新插件
• 📋 注册到系统
• 🐍 提供Python接口: lq.ai_yourfeature()
• 🖥️ 生成CLI命令: lqcodeAI yourfeature
• 📖 生成帮助: lqcodeAI yourfeature --help

📝 真实示例：藏头诗生成器

以下是一个完整的真实插件示例：

文件：ai_poetry.py

from typing import Any, Dict, TypedDict
from ..core.base import BaseAI
from ..core.plugin_registry import ai_plugin

class PoetryResult(TypedDict):
    """藏头诗结果类型"""
    poem: str
    explanation: str

@ai_plugin(
    name="poetry",
    description="生成藏头诗功能",
    cli_args=[
        {"name": "message", "help": "藏头诗内容", "default": "李梅"}
    ],
    result_type=PoetryResult
)
class PoetryAI(BaseAI):
    """藏头诗AI功能"""
    
    def ai_poetry(self, password: str, message: str = "李梅") -> PoetryResult:
        """生成藏头诗"""
        if not password or not isinstance(password, str):
            raise ValueError("password必须是有效的字符串")
        if not message or not isinstance(message, str):
            raise ValueError("message必须是有效的字符串")
            
        parameters = {
            "input": message,
            "choose": "AI_POETY",
        }
        result = self._execute_workflow(password, parameters, max_retries=5)
        if "error" in result:
            return {"poem": result["error"], "explanation": ""}
        return result

    def _parse_output(self, output: Any) -> PoetryResult:
        """解析藏头诗输出"""
        if isinstance(output, dict):
            return {
                "poem": output.get('poety', ""),
                "explanation": output.get('explain', "")
            }
        return {"poem": str(output), "explanation": ""}

自动获得的功能：

Python接口:

from lqcodeAI import lq

# 生成藏头诗
result = lq.ai_poetry('lqcode', message='绿旗编程')
print(result['poem'])
print(result['explanation'])

CLI命令:

# 使用默认参数
lqcodeAI poetry

# 指定参数
lqcodeAI poetry --message 绿旗编程

# 查看帮助
lqcodeAI poetry --help

🔧 开发模板

为了让开发更简单，这里提供一个通用模板：

"""
[功能名称]插件 - [功能描述]
"""
from typing import Any, Dict, TypedDict
from ..core.base import BaseAI
from ..core.plugin_registry import ai_plugin

# 插件内部定义返回类型（推荐做法）
class [功能名称]Result(TypedDict):
    """[功能名称]结果类型"""
    content: str
    explanation: str

@ai_plugin(
    name="[功能名称小写]",
    description="[功能描述]",
    cli_args=[
        {"name": "input_param", "help": "输入参数说明", "default": "默认值"},
        {"name": "style_param", "help": "风格参数说明", "default": "标准"}
    ],
    result_type=[功能名称]Result
)
class [功能名称]AI(BaseAI):
    """[功能名称]AI功能"""
    
    def ai_[功能名称小写](self, password: str, input_param: str = "默认值", style_param: str = "标准") -> [功能名称]Result:
        """[功能名称]实现"""
        # 参数验证
        if not password or not isinstance(password, str):
            raise ValueError("password必须是有效的字符串")
            
        # 准备工作流参数
        parameters = {
            "input": f"用户输入: {input_param}，风格: {style_param}",
            "choose": "AI_[功能名称大写]",
        }
        
        # 调用工作流
        result = self._execute_workflow(password, parameters)
        
        # 错误处理
        if "error" in result:
            return {"content": result["error"], "explanation": ""}
        
        return result

    def _parse_output(self, output: Any) -> [功能名称]Result:
        """解析输出结果"""
        if isinstance(output, dict):
            return {
                "content": output.get('content', str(output)),
                "explanation": output.get('explanation', "")
            }
        return {"content": str(output), "explanation": ""}

🎯 命名规范

文件命名

• 格式: ai_功能名.py
• 示例: ai_poetry.py, ai_translate.py, ai_summary.py

类命名

• 格式: 功能名AI
• 示例: PoetryAI, TranslateAI, SummaryAI

类型命名

• 格式: 功能名Result
• 示例: PoetryResult, TranslateResult, SummaryResult

方法命名

• 格式: ai_功能名
• 示例: ai_poetry, ai_translate, ai_summary

插件名称

• 格式: 小写，简洁明了
• 示例: poetry, translate, summary

📊 系统会自动处理

功能	自动化程度	说明
插件发现	✅ 100%	扫描plugins目录自动发现
功能注册	✅ 100%	@ai_plugin装饰器自动注册
Python接口	✅ 100%	动态生成lq.ai_xxx()方法
CLI命令	✅ 100%	根据cli_args自动生成
类型检查	✅ 100%	完整的TypedDict支持
帮助文档	✅ 100%	自动生成--help信息
错误处理	✅ 100%	统一的错误处理机制

✅ 最佳实践

类型定义

# ✅ 推荐：在插件内部定义类型
class MyFeatureResult(TypedDict):
    """功能结果类型"""
    content: str
    explanation: str

# ❌ 避免：使用过于通用的类型
def ai_feature(self, password: str) -> Dict[str, Any]:

参数设计

# ✅ 推荐：提供有意义的默认值
cli_args=[
    {"name": "theme", "help": "故事主题", "default": "科幻"},
    {"name": "length", "help": "故事长度", "default": "短篇"}
]

# ❌ 避免：没有默认值或帮助信息
cli_args=[
    {"name": "param1"},
    {"name": "param2"}
]

错误处理

# ✅ 推荐：完整的参数验证
if not password or not isinstance(password, str):
    raise ValueError("password必须是有效的字符串")

# ✅ 推荐：优雅的错误处理
if "error" in result:
    return {"content": result["error"], "explanation": "处理失败"}

🎉 当前插件展示

现在已经实现的插件，都是"一个文件搞定"：

• 📝 ai_poetry.py - 藏头诗生成（完整类型定义、CLI支持）
• 🛡️ ai_weapons.py - AI武器生成器（主题风格定制）
• 🍪 ai_snackprops.py - 零食推荐器（个性化推荐）

每个插件都自动拥有：

• 🐍 Python接口：lq.ai_xxx()
• 🖥️ CLI命令：lqcodeAI xxx
• 📖 帮助文档：lqcodeAI xxx --help
• 🔍 类型检查：完整的IDE支持

🚀 立即开始

想要添加新功能？就是这么简单：

1. 在 lqcodeAI/plugins/ 目录创建 ai_你的功能.py
2. 复制上面的模板代码
3. 修改功能名称和实现逻辑
4. 保存文件
5. 完成！🎉

🔧 调试和测试

快速测试新插件

# 测试插件是否正确加载
cd lqcodeAI
python -c "from lqcodeAI import lq; print(lq.get_available_functions())"

# 测试CLI命令
lqcodeAI list
lqcodeAI yourfeature --help

常见问题排查

1. 插件未被发现：检查文件名是否以ai_开头
2. CLI参数错误：检查cli_args格式是否正确
3. 类型错误：确保导入了TypedDict
4. 方法未找到：确保方法名以ai_开头

现在就去试试吧！你的新AI功能只需要一个文件！✨