My shell使用技巧

ShellAgent Custom Widgets 开发

前置准备

  1. 从 https://github.com/myshell-ai/ShellAgent/actions/runs/14076253431 下载 ShellAgent 压缩包（内测版，暂不支持自动更新）

  2. 可通过各平台对应的启动文件直接运行 ShellAgent，无需额外环境配置

开发流程

1. 文件结构：

├── custom_widgets           # Folder for custom widgets
│   └── widgets_A            # Example widgets folder, folder name must match git repository name
│       └── __init__.py      # Python initialization file
│       └── [xxx.py]         # Core widget file
│       └── requirements.py  # Python dependencies file
│   └── widgets_B 
│       └── ...
│   └── ...
├── custom_widget_info.json  # Contains git URL, commit and other info (only needed for myshell platform deployment)

  • custom_widgets 目录中每个文件夹对应一个git repo，可以包含一个或多个 widget

  • 当 ShellAgent 启动时，会自动扫描 custom_widgets 文件夹下的所有目录，并通过各自的 __init__.py 导入 widget，使其可在 ShellAgent 中直接使用

  • 系统检测到新的 widget 时，会自动通过 requirements.txt 安装相应的依赖

2. 开发流程

以 https://github.com/Cherwayway/custom_widget_demo 示例作为参考，必须包含的文件有：

image.png

  • __init__.py：用于导入所需的widget类

from .demo import DemoCustomWidget

  • demo.py：核心 widget 类实现文件，文件名可自定义

    • custom widget必须继承BaseWidget，并使用@WIDGETS.register_module()装饰器

    • CATEGORY和NAME为必填项

    • 必须使用标准pydantic定义InputsSchema和OutputsSchema，只能包含标准类别的类，且需要设置默认值。部署到myshell主站前需通过测试验证

    • 需要注意的是，execute 函数中传入的参数 config 会被转换为 easydict 类型。因此在此例子中，应使用 config.prompt 而不是 config['prompt'] 来获取 input schema 中的 prompt 值

from pydantic import Field
from typing import Any

from proconfig.widgets.base import WIDGETS, BaseWidget

@WIDGETS.register_module()
class DemoCustomWidget(BaseWidget):
    CATEGORY = "Custom Widgets/Custom Widgets"
    NAME = "Demo Custom Widgets"
    
    class InputsSchema(BaseWidget.InputsSchema):
        prompt: str = Field("test prompt", description="the prompt")
    
    class OutputsSchema(BaseWidget.OutputsSchema):
        reply: str
        
    def execute(self, environ, config):
        return {
            "reply": "Hello world! Welcome to try custom widgets"
        }
        
        
if __name__ == "__main__":
    widget = DemoCustomWidget()
    config = {
        "prompt": "hello",
    }
    output = widget({}, config)
    import pdb; pdb.set_trace()

  • requirements.txt：Python依赖包清单

numpy

完成开发后，启动 ShellAgent 即可自动导入相应的 custom widget，并可在本地环境中查看和调试

3. 部署到 myshell 主站（可选）

要将 widget 部署到 myshell 主站，需要完成以下步骤（部署流程与普通 app 相同）：

  • 将代码推送到 GitHub（或其他代码托管平台）的公开仓库，并确保本地代码没有未保存的更改

  • 在 custom_widget_info.json 中填写对应的 git URL、commit、branch 和 description，示例如下

{
    "custom_widget_demo": {
        "git": "<https://github.com/Cherwayway/custom_widget_demo.git>",
        "commit": "651f1c69cad4921d09e705802733aadae1aa9058",
        "branch": "main",
        "description": "A demo widget for custom widgets"
    }
}

4. 常见错误

  • 若要进行测试，请将测试函数写在 if __name__ == "__main__" 代码块中。注意：运行 Python 代码时，必须位于 ShellAgent 根目录下，并确保测试环境中已安装 shellagent 包的所有依赖。例如，要测试 custom_widget_demo，请在 ShellAgent 根目录执行

    cd ShellAgent && pip install -e .
python custom_widgets/custom_widget_demo/demo.py

Appendix

  • 一个使用 Cursor 开发 custom widget 的完整示例（包含 cursor rule）

https://www.notion.so/myshellai/Cursor-Custom-Widget-1bf3f81ff51e801ca666f9e57530a61b?pvs=4


评论区

我要分享

热门分享