Skip to content

Commit 67b20a4

Browse files
Hongwei-MBHongwei-MB
authored
Merge pull request #20 from AGIBuild/feature/adopt-vsixmanifest-format
Feature/adopt vsixmanifest format
2 parents 09c8d6a + 9d81bb9 commit 67b20a4

File tree

7 files changed

+1400
-72
lines changed

7 files changed

+1400
-72
lines changed

‎README.md‎

Lines changed: 91 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,46 @@ Modulus is a modern, cross-platform, plugin-based application framework designed
66

77
### Multi-Host Architecture
88
- **UI-Agnostic Core**: Business logic independent of any UI framework
9-
- **Pluggable Hosts**: Currently supports Blazor Hybrid (MAUI) and Avalonia, extensible to other UI technologies
10-
- **Shared Core Logic**: Same Domain/Application code runs across all supported hosts
9+
- **Pluggable Hosts**: Supports Avalonia (desktop) and Blazor Hybrid (MAUI)
10+
- **Shared Core Logic**: Same Domain/Application code runs across all hosts
1111

12-
### Plugin System
13-
- Hot-reloadable and dynamically unloadable plugins (AssemblyLoadContext)
14-
- Manifest-driven module discovery and loading
15-
- Dependency injection for plugins (DI container isolation)
16-
- System module protection (prevent accidental unloading)
12+
### Extension System
13+
- **VS Extension Compatible**: Uses `extension.vsixmanifest` (XML) format
14+
- **Hot-Reloadable**: AssemblyLoadContext-based isolation for dynamic load/unload
15+
- **Explicit Installation**: Extensions installed via CLI or UI, not auto-discovered
16+
- **Type-Safe Entry Points**: `ModulusPackage` base class similar to VS VsPackage
1717

1818
### Developer Experience
19-
- Plugin development SDK with declarative attributes
19+
- Extension SDK with declarative attributes
2020
- AI Agent plugin support (LLM integration)
21-
- Plugin signature verification and version control
21+
- Signature verification and version control
2222
- Cross-platform: Windows / macOS / Linux
2323

2424
## 🏗️ Architecture
2525

2626
```
2727
src/
2828
├── Modulus.Core/ # Runtime, module loader, DI
29-
├── Modulus.Sdk/ # SDK base classes, attributes
30-
├── Modulus.UI.Abstractions/ # UI contracts (IMenuRegistry, IThemeService)
29+
├── Modulus.Sdk/ # SDK: ModulusPackage, attributes
30+
├── Modulus.UI.Abstractions/ # UI contracts (IMenuRegistry, INavigationService)
3131
├── Hosts/
32-
│ ├── Modulus.Host.Blazor/ # Blazor Hybrid (MAUI + MudBlazor)
33-
│ └── Modulus.Host.Avalonia/ # Avalonia desktop
32+
│ ├── Modulus.Host.Avalonia/ # Avalonia desktop (ID: Modulus.Host.Avalonia)
33+
│ └── Modulus.Host.Blazor/ # Blazor Hybrid (ID: Modulus.Host.Blazor)
3434
└── Modules/
3535
├── EchoPlugin/ # Example: Echo plugin
36-
└── SimpleNotes/ # Example: Notes module
36+
├── SimpleNotes/ # Example: Notes module
37+
└── ComponentsDemo/ # Example: UI components demo
3738
```
3839

39-
## 📦 Use Cases
40-
- Desktop data tools / UI automation tools
41-
- Rapid development of developer utilities (Log Viewer, Code Generator)
42-
- Task framework for AI plugin development
43-
- Internal tool platforms (multi-team collaboration)
40+
## 📦 Extension Structure
41+
42+
```
43+
MyExtension/
44+
├── extension.vsixmanifest # XML manifest (VS Extension format)
45+
├── MyExtension.Core.dll # Core logic (host-agnostic)
46+
├── MyExtension.UI.Avalonia.dll
47+
└── MyExtension.UI.Blazor.dll
48+
```
4449

4550
## 🚀 Getting Started
4651

@@ -59,25 +64,79 @@ dotnet run --project src/Hosts/Modulus.Host.Blazor
5964
dotnet test
6065
```
6166

62-
## 🔌 Creating a Module
67+
## 🔌 Creating an Extension
68+
69+
### 1. Create Projects
70+
71+
```
72+
MyExtension/
73+
├── MyExtension.Core/
74+
├── MyExtension.UI.Avalonia/
75+
└── MyExtension.UI.Blazor/
76+
```
77+
78+
### 2. Define Entry Point
79+
80+
```csharp
81+
// MyExtension.Core/MyExtensionPackage.cs
82+
public class MyExtensionPackage : ModulusPackage
83+
{
84+
public override void ConfigureServices(IModuleLifecycleContext context)
85+
{
86+
context.Services.AddSingleton<IMyService, MyService>();
87+
}
88+
}
89+
```
90+
91+
### 3. Create Manifest
92+
93+
```xml
94+
<!-- extension.vsixmanifest -->
95+
<?xml version="1.0" encoding="utf-8"?>
96+
<PackageManifest Version="2.0.0"
97+
xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011">
98+
<Metadata>
99+
<Identity Id="your-guid" Version="1.0.0" Publisher="You" />
100+
<DisplayName>My Extension</DisplayName>
101+
<Description>My awesome extension</Description>
102+
</Metadata>
103+
<Installation>
104+
<InstallationTarget Id="Modulus.Host.Avalonia" Version="[1.0,)" />
105+
<InstallationTarget Id="Modulus.Host.Blazor" Version="[1.0,)" />
106+
</Installation>
107+
<Assets>
108+
<Asset Type="Modulus.Package" Path="MyExtension.Core.dll" />
109+
<Asset Type="Modulus.Package" Path="MyExtension.UI.Avalonia.dll"
110+
TargetHost="Modulus.Host.Avalonia" />
111+
<Asset Type="Modulus.Menu" Id="my-menu" DisplayName="My Tool"
112+
Icon="Home" Route="MyExtension.ViewModels.MainViewModel"
113+
TargetHost="Modulus.Host.Avalonia" />
114+
</Assets>
115+
</PackageManifest>
116+
```
63117

64-
1. Create three projects: `MyModule.Core`, `MyModule.UI.Avalonia`, `MyModule.UI.Blazor`
65-
2. Define your module class with `[Module]` attribute
66-
3. Add UI-specific menu attributes (`[AvaloniaMenu]`, `[BlazorMenu]`)
67-
4. Create `manifest.json` with module metadata
118+
### 4. Install Extension
68119

69-
See [Quickstart Guide](./specs/001-core-architecture/quickstart.md) for detailed instructions.
120+
```bash
121+
modulus install ./MyExtension
122+
```
70123

71124
## 📚 Documentation
72-
- [Core Architecture Spec](./specs/001-core-architecture/spec.md)
73-
- [Quickstart Guide](./specs/001-core-architecture/quickstart.md)
74-
- [Data Model](./specs/001-core-architecture/data-model.md)
75-
- [Runtime Contracts](./specs/001-core-architecture/contracts/runtime-contracts.md)
125+
126+
- [OpenSpec Specifications](./openspec/specs/)
127+
- [Project Context](./openspec/project.md)
128+
- [Contributing Guide](./CONTRIBUTING.md)
76129

77130
## Project Status
78-
- Current Branch: `001-core-architecture`
79-
- Phase: MVP Complete (User Stories 1-3)
80-
- Test Coverage: 30 tests passing
131+
132+
- **Phase**: Active Development
133+
- **Test Coverage**: 30+ tests passing
134+
- **Platforms**: Windows, macOS, Linux
81135

82136
## Contributing
137+
83138
Pull requests and issues are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
139+
140+
## License
141+
142+
[MIT License](./LICENSE)

‎README.zh-CN.md‎

Lines changed: 121 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,142 @@
1-
# Modulus 项目简介
1+
# Modulus
22

3-
Modulus 是一个现代化的跨平台插件式工具应用模板，旨在帮助开发者快速构建可扩展、可维护、支持 AI 的桌面工具类软件。
3+
Modulus 是一个现代化的跨平台插件式应用框架，帮助开发者快速构建可扩展、可维护、支持 AI 的工具类软件。
44

55
## ✨ 特性亮点
6-
- 插件热更新与动态卸载（基于 AssemblyLoadContext）
7-
- 插件配置支持（JSON-based）
8-
- 插件依赖注入（DI 容器隔离）
9-
- 多语言本地化（支持自动切换）
10-
- 插件签名验证与版本控制
6+
7+
### 多主机架构
8+
- **UI 无关核心**: 业务逻辑独立于任何 UI 框架
9+
- **可插拔主机**: 支持 Avalonia (桌面) 和 Blazor Hybrid (MAUI)
10+
- **共享核心逻辑**: 相同的 Domain/Application 代码运行在所有主机上
11+
12+
### 扩展系统
13+
- **VS Extension 兼容**: 使用 `extension.vsixmanifest` (XML) 格式
14+
- **热重载**: 基于 AssemblyLoadContext 的隔离，支持动态加载/卸载
15+
- **显式安装**: 通过 CLI 或 UI 安装扩展，不自动扫描目录
16+
- **类型安全入口点**: `ModulusPackage` 基类，类似 VS VsPackage
17+
18+
### 开发体验
19+
- 扩展 SDK，支持声明式属性
1120
- AI Agent 插件支持（可嵌入 LLM）
12-
- 提供插件开发 SDK 与模板工程
13-
- 跨平台支持：Windows / macOS（Avalonia UI）
21+
- 签名验证与版本控制
22+
- 跨平台: Windows / macOS / Linux
23+
24+
## 🏗️ 架构
25+
26+
```
27+
src/
28+
├── Modulus.Core/ # 运行时、模块加载器、DI
29+
├── Modulus.Sdk/ # SDK: ModulusPackage, 属性
30+
├── Modulus.UI.Abstractions/ # UI 契约 (IMenuRegistry, INavigationService)
31+
├── Hosts/
32+
│ ├── Modulus.Host.Avalonia/ # Avalonia 桌面 (ID: Modulus.Host.Avalonia)
33+
│ └── Modulus.Host.Blazor/ # Blazor Hybrid (ID: Modulus.Host.Blazor)
34+
└── Modules/
35+
├── EchoPlugin/ # 示例: Echo 插件
36+
├── SimpleNotes/ # 示例: 笔记模块
37+
└── ComponentsDemo/ # 示例: UI 组件演示
38+
```
39+
40+
## 📦 扩展结构
1441

15-
## 📦 用途场景
16-
- 构建桌面数据工具 / UI 自动化工具
17-
- 快速构建开发者辅助类应用（Log Viewer、Code Generator）
18-
- 面向 AI 插件开发的任务框架
19-
- 内部工具平台（多团队协作）
42+
```
43+
MyExtension/
44+
├── extension.vsixmanifest # XML 清单 (VS Extension 格式)
45+
├── MyExtension.Core.dll # 核心逻辑 (host-agnostic)
46+
├── MyExtension.UI.Avalonia.dll
47+
└── MyExtension.UI.Blazor.dll
48+
```
2049

2150
## 🚀 快速开始
51+
52+
### 运行 Avalonia 主机
53+
```bash
54+
dotnet run --project src/Hosts/Modulus.Host.Avalonia
55+
```
56+
57+
### 运行 Blazor 主机
2258
```bash
23-
dotnet new --install Modulus.Templates
24-
dotnet new modulus-plugin -n MyPlugin
59+
dotnet run --project src/Hosts/Modulus.Host.Blazor
2560
```
2661

27-
## 🤖 AI 辅助开发
28-
Modulus 内置了项目上下文引导系统，用于支持 GitHub Copilot 等 AI 工具：
62+
### 运行测试
63+
```bash
64+
dotnet test
65+
```
2966

30-
```powershell
31-
# 引导 AI 上下文（用于 GitHub Copilot）
32-
nuke StartAI
67+
## 🔌 创建扩展
3368

34-
# 特定角色的上下文
35-
nuke StartAI --role Backend
36-
nuke StartAI --role Frontend
37-
nuke StartAI --role Plugin
69+
### 1. 创建项目
70+
71+
```
72+
MyExtension/
73+
├── MyExtension.Core/
74+
├── MyExtension.UI.Avalonia/
75+
└── MyExtension.UI.Blazor/
76+
```
77+
78+
### 2. 定义入口点
79+
80+
```csharp
81+
// MyExtension.Core/MyExtensionPackage.cs
82+
public class MyExtensionPackage : ModulusPackage
83+
{
84+
public override void ConfigureServices(IModuleLifecycleContext context)
85+
{
86+
context.Services.AddSingleton<IMyService, MyService>();
87+
}
88+
}
89+
```
90+
91+
### 3. 创建清单
92+
93+
```xml
94+
<!-- extension.vsixmanifest -->
95+
<?xml version="1.0" encoding="utf-8"?>
96+
<PackageManifest Version="2.0.0"
97+
xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011">
98+
<Metadata>
99+
<Identity Id="your-guid" Version="1.0.0" Publisher="You" />
100+
<DisplayName>My Extension</DisplayName>
101+
<Description>My awesome extension</Description>
102+
</Metadata>
103+
<Installation>
104+
<InstallationTarget Id="Modulus.Host.Avalonia" Version="[1.0,)" />
105+
<InstallationTarget Id="Modulus.Host.Blazor" Version="[1.0,)" />
106+
</Installation>
107+
<Assets>
108+
<Asset Type="Modulus.Package" Path="MyExtension.Core.dll" />
109+
<Asset Type="Modulus.Package" Path="MyExtension.UI.Avalonia.dll"
110+
TargetHost="Modulus.Host.Avalonia" />
111+
<Asset Type="Modulus.Menu" Id="my-menu" DisplayName="My Tool"
112+
Icon="Home" Route="MyExtension.ViewModels.MainViewModel"
113+
TargetHost="Modulus.Host.Avalonia" />
114+
</Assets>
115+
</PackageManifest>
38116
```
39117

40-
更多信息，请参阅 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)。
118+
### 4. 安装扩展
119+
120+
```bash
121+
modulus install ./MyExtension
122+
```
41123

42124
## 📚 文档
43-
- [English Documentation](./docs/en-US/README.md)
125+
126+
- [OpenSpec 规格说明](./openspec/specs/)
127+
- [项目上下文](./openspec/project.md)
128+
- [贡献指南](./CONTRIBUTING.zh-CN.md)
44129

45130
## 项目状态
46-
- 进度报告见 [docs/reports/story-progress-report.zh-CN.md](./docs/reports/story-progress-report.zh-CN.md)
47131

48-
## Story 命名规则
49-
- 文件格式：`S-XXXX-标题.md`
50-
- 文档标题：`# S-XXXX-标题`
51-
- 必要元数据：包含优先级和状态标记
132+
- **阶段**: 活跃开发中
133+
- **测试覆盖**: 30+ 测试通过
134+
- **平台**: Windows, macOS, Linux
52135

53136
## 贡献
54-
欢迎提交 issue 和 PR！
137+
138+
欢迎提交 Issue 和 PR！请参阅 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)。
139+
140+
## 许可证
141+
142+
[MIT License](./LICENSE)

0 commit comments

Comments
 (0)