Skip to content

Commit 8166184

Browse files
RinLit-233-shirokoRinLit-233-shiroko
committed
feat: 帮助功能
1 parent c56b93d commit 8166184

3 files changed

Lines changed: 221 additions & 26 deletions

File tree

‎ClassWidgets/SDK/tools/help.py‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
"""
2+
Class Widgets SDK Help Tool
3+
提供 SDK 工具的完整帮助信息
4+
"""
5+
import click
6+
import sys
7+
from pathlib import Path
8+
9+
from ClassWidgets.SDK import __version__ as sdk_version
10+
11+
12+
def print_header():
13+
"""打印帮助头部信息"""
14+
click.clear()
15+
click.secho("Class Widgets 2 Plugin SDK", fg='green', bold=True)
16+
click.secho(f"版本: {sdk_version}", fg='cyan')
17+
click.secho("=" * 50, dim=True)
18+
click.echo("")
19+
20+
21+
def print_section(title: str, description: str = ""):
22+
"""打印章节标题"""
23+
click.echo("")
24+
click.secho(f"📋 {title}", fg='yellow', bold=True)
25+
if description:
26+
click.secho(f" {description}", fg='white', dim=True)
27+
click.secho("-" * 30, dim=True)
28+
29+
30+
def print_command(name: str, usage: str, description: str, examples: list = None):
31+
"""打印命令信息"""
32+
click.echo("")
33+
click.secho(f"🔧 {name}", fg='cyan', bold=True)
34+
click.secho(f" 用法: {usage}", fg='white')
35+
click.secho(f" 描述: {description}", fg='white')
36+
37+
if examples:
38+
click.echo(" 示例:")
39+
for example in examples:
40+
click.secho(f" • {example}", fg='green', dim=True)
41+
42+
43+
def print_tip(title: str, content: str):
44+
"""打印提示信息"""
45+
click.echo("")
46+
click.secho(f"💡 {title}", fg='blue', bold=True)
47+
click.secho(f" {content}", fg='white')
48+
49+
50+
def show_commands_help():
51+
"""显示所有命令的帮助信息"""
52+
53+
print_section("可用命令", "以下是目前可用的所有 Class Widgets SDK 命令")
54+
55+
commands = [
56+
{
57+
"name": "cw-plugin-init",
58+
"usage": "cw-plugin-init [选项] [目录]",
59+
"description": "初始化一个新的 Class Widgets 插件项目",
60+
"examples": [
61+
"cw-plugin-init # 在当前目录创建插件",
62+
"cw-plugin-init my-plugin # 创建指定名称的插件",
63+
"cw-plugin-init --force # 强制覆盖现有文件"
64+
]
65+
},
66+
{
67+
"name": "cw-plugin-pack",
68+
"usage": "cw-plugin-pack [选项] 源目录",
69+
"description": "将插件项目打包成 .cwplugin 格式",
70+
"examples": [
71+
"cw-plugin-pack my-plugin # 打包插件",
72+
"cw-plugin-pack --zip my-plugin # 打包成 zip 格式",
73+
"cw-plugin-pack --output out/ my-plugin # 指定输出目录"
74+
]
75+
},
76+
{
77+
"name": "cw-help",
78+
"usage": "cw-help [命令]",
79+
"description": "显示帮助信息，或显示特定命令的详细帮助",
80+
"examples": [
81+
"cw-help # 显示完整帮助",
82+
"cw-help plugin-init # 显示 plugin-init 命令帮助"
83+
]
84+
}
85+
]
86+
87+
for cmd in commands:
88+
print_command(cmd["name"], cmd["usage"], cmd["description"], cmd["examples"])
89+
90+
91+
def show_detailed_help(command_name: str = None):
92+
"""显示详细帮助信息"""
93+
94+
if command_name:
95+
command_name = command_name.lower().replace('cw-', '')
96+
97+
if 'init' in command_name or 'plugin' in command_name:
98+
print_command(
99+
"cw-plugin-init",
100+
"cw-plugin-init [选项] [目录]",
101+
"初始化一个新的 Class Widgets 插件项目",
102+
[
103+
"cw-plugin-init # 交互式创建插件",
104+
"cw-plugin-init my-plugin # 创建指定名称的插件",
105+
"cw-plugin-init --force # 强制覆盖现有文件"
106+
]
107+
)
108+
109+
print_section("选项说明")
110+
click.echo(" --force, -f 覆盖现有文件")
111+
click.echo(" --help 显示帮助信息")
112+
113+
print_section("创建流程")
114+
click.echo(" 1. 选择创建目录")
115+
click.echo(" 2. 输入插件信息（名称、作者、描述等）")
116+
click.echo(" 3. 生成插件文件结构")
117+
click.echo(" 4. 指导安装和测试")
118+
119+
print_tip("提示", "创建后请使用 'pip install -e .' 安装插件到开发环境")
120+
121+
elif 'pack' in command_name:
122+
print_command(
123+
"cw-plugin-pack",
124+
"cw-plugin-pack [选项] 源目录",
125+
"将插件项目打包成可分发的格式",
126+
[
127+
"cw-plugin-pack my-plugin # 打包插件",
128+
"cw-plugin-pack --zip my-plugin # 打包成 zip 格式",
129+
"cw-plugin-pack --output out/ my-plugin # 指定输出目录"
130+
]
131+
)
132+
133+
print_section("选项说明")
134+
click.echo(" --output, -o 指定输出文件路径")
135+
click.echo(" --format, -f 指定打包格式 (cwplugin|zip)")
136+
click.echo(" --help 显示帮助信息")
137+
138+
print_tip("提示", "生成的 .cwplugin 文件可以直接在 Class Widgets 2 中安装")
139+
140+
else:
141+
click.secho(f"❌ 未知命令: {command_name}", fg='red', bold=True)
142+
click.echo("使用 'cw-help' 查看所有可用命令")
143+
return
144+
145+
else:
146+
show_commands_help()
147+
148+
print_section("插件开发流程")
149+
click.echo(" 1. 创建插件: cw-plugin-init my-plugin")
150+
click.echo(" 2. 开发插件: 编辑 my-plugin/main.py")
151+
click.echo(" 3. 测试插件: pip install -e .")
152+
click.echo(" 4. 打包插件: cw-plugin-pack my-plugin")
153+
click.echo(" 5. 分发插件: 安装 .cwplugin 文件")
154+
155+
print_section("重要提示")
156+
click.echo(" • 所有命令都支持 --help 参数查看详细用法")
157+
click.echo(" • 插件开发需要 Python 3.9+ 环境")
158+
click.echo(" • 建议使用虚拟环境进行开发")
159+
click.echo(" • 查看 SDK 文档获取更多信息")
160+
161+
162+
@click.command()
163+
@click.argument('command', required=False)
164+
def show_help(command: str = None):
165+
"""
166+
Class Widgets 2 Plugin SDK 帮助工具
167+
168+
使用方法:
169+
cw-help 显示完整帮助信息
170+
cw-help <命令> 显示特定命令的详细帮助
171+
172+
可用命令:
173+
plugin-init 初始化新插件项目
174+
plugin-pack 打包插件项目
175+
"""
176+
print_header()
177+
178+
if command:
179+
show_detailed_help(command)
180+
else:
181+
show_detailed_help()
182+
183+
click.echo("")
184+
click.secho("更多信息请访问: https://github.com/RinLit-233-shiroko/Class-Widgets-2", fg='blue', dim=True)
185+
186+
187+
def main():
188+
"""入口函数"""
189+
show_help()
190+
191+
192+
if __name__ == '__main__':
193+
main()

‎ClassWidgets/SDK/tools/manifest.py‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
from typing import Optional
22
from pathlib import Path
3-
from pydantic import BaseModel, Field, validator, field_validator
3+
from pydantic import BaseModel, Field, field_validator, ConfigDict
44
import json
55

66
from ClassWidgets.SDK import __version__ as sdk_version
@@ -11,6 +11,23 @@ class PluginManifestModel(BaseModel):
1111
Data model for the plugin manifest file (cwplugin.json).
1212
插件清单文件的数据模型。
1313
"""
14+
model_config = ConfigDict(
15+
json_schema_extra={
16+
"example": {
17+
"id": "com.example.myplugin",
18+
"name": "My Plugin",
19+
"version": "1.0.0",
20+
"api_version": "~=2.0.0",
21+
"entry": "main.py",
22+
"author": "Developer Name",
23+
"description": "A useful plugin.",
24+
"url": "https://github.com/owner/repo",
25+
"readme": "README.md",
26+
"icon": "icon.png"
27+
}
28+
}
29+
)
30+
1431
# Required fields 必填字段
1532
id: str = Field(...,
1633
description="Unique plugin identifier (e.g., 'com.example.myplugin'). 唯一插件标识符")
@@ -48,34 +65,18 @@ def validate_id(cls, v: str) -> str:
4865

4966
@field_validator('entry')
5067
@classmethod
51-
def validate_entry_exists(cls, v: str, info):
68+
def validate_entry_exists(cls, v: str):
5269
# This validator is mainly for loading existing manifests.
5370
# 此验证器主要用于加载已存在的清单。
5471
# The scaffold tool will create the file later.
5572
# 脚手架工具会在之后创建该文件。
5673
return v
5774

58-
class Config:
59-
json_schema_extra = {
60-
"example": {
61-
"id": "com.example.myplugin",
62-
"name": "My Plugin",
63-
"version": "1.0.0",
64-
"api_version": ">=2.0.0",
65-
"entry": "main.py",
66-
"author": "Developer Name",
67-
"description": "A useful plugin.",
68-
"url": "https://github.com/owner/repo",
69-
"readme": "README.md",
70-
"icon": "icon.png"
71-
}
72-
}
73-
7475
def save(self, path: Path) -> None:
7576
"""Save the manifest to a JSON file. 将清单保存为JSON文件。"""
7677
with open(path, 'w', encoding='utf-8') as f:
77-
# Use the Pydantic model's dict and dump with json for prettier formatting
78-
# 使用Pydantic模型的dict方法，并用json库进行美化输出
78+
# Use the Pydantic model's model_dump and dump with json for prettier formatting
79+
# 使用Pydantic模型的model_dump方法，并用json库进行美化输出
7980
data = self.model_dump(exclude_none=True)
8081
json.dump(data, f, indent=2, ensure_ascii=False)
8182
f.write('\n') # Add newline at EOF
@@ -85,4 +86,4 @@ def load(cls, path: Path) -> 'PluginManifestModel':
8586
"""Load a manifest from a JSON file. 从JSON文件加载清单。"""
8687
with open(path, 'r', encoding='utf-8') as f:
8788
data = json.load(f)
88-
return cls(**data)
89+
return cls.model_validate(data)

‎pyproject.toml‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ dynamic = ["version"]
88
description = "Class Widgets 2 Plugin SDK Development tools and type stubs"
99
readme = "README.md"
1010
requires-python = ">=3.9"
11+
dependencies = [
12+
"pydantic",
13+
"click"
14+
]
1115

1216
[tool.hatch.version]
1317
path = "ClassWidgets/SDK/__init__.py"
@@ -17,10 +21,6 @@ classifiers = [
1721
"Development Status :: 3 - Alpha",
1822
"License :: OSI Approved :: MIT License",
1923
]
20-
dependencies = [
21-
"pydantic",
22-
"click"
23-
]
2424

2525
[project.optional-dependencies]
2626
test = [
@@ -41,4 +41,5 @@ include = [
4141

4242
[project.scripts]
4343
cw-plugin-init = "ClassWidgets.SDK.tools.scaffold:create_plugin"
44-
cw-plugin-pack = "ClassWidgets.SDK.tools.packager:pack_plugin"
44+
cw-plugin-pack = "ClassWidgets.SDK.tools.packager:pack_plugin"
45+
cw-help = "ClassWidgets.SDK.tools.help:show_help"

0 commit comments

Comments
 (0)