1. HagiCode Skill 系统架构概览
HagiCode Skill 系统采用前后端分离的微服务架构设计,核心目标是实现AI技能的灵活扩展与管理。系统由四个主要功能模块构成:本地技能管理、技能市场搜索、智能推荐引擎和授信提供者管理。这种模块化设计使得系统具备良好的可维护性和扩展性,能够适应不同规模团队的需求。
前端部分基于现代Web技术栈构建,使用TanStack Start框架配合React实现动态用户界面。状态管理采用Redux Toolkit,确保复杂交互场景下的数据一致性。四个核心功能对应独立的Tab组件,通过统一的API网关与后端通信。
后端服务基于ASP.NET Core平台,采用ABP Framework作为基础开发框架。分布式状态管理通过Orleans Grain实现,这种基于Actor模型的方案特别适合处理高并发的技能管理请求。在线API客户端封装了统一的IOnlineApiClient接口,与远程技能目录服务进行安全通信。
系统设计遵循"命令执行与业务逻辑分离"原则,通过适配器模式将底层命令执行细节(如npm/npx调用)封装在独立模块中。这种设计显著提升了代码的可测试性和可维护性。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本地技能管理实现细节
2.1 技能安装与卸载机制
本地技能管理模块的核心是封装npm/npx命令的执行过程。系统通过LocalSkillCommandAdapter类提供统一的技能操作接口,内部处理所有与命令行交互的细节。安装流程包含以下关键步骤:
- 引用规范化:将各种格式的技能引用(如tanweai/pua、@opencode/docker-skill)转换为统一的内部表示
- 先决条件检查:验证Node.js版本、网络连接等运行环境
- 安装锁获取:确保同一技能同时只有一个安装/卸载操作在执行
- 命令执行:通过子进程执行npx skills add命令
- 元数据持久化:记录安装时间、来源版本等关键信息
csharp复制public async Task<SkillInstallResultDto> InstallAsync(
SkillInstallRequestDto request,
CancellationToken cancellationToken = default)
{
// 引用规范化处理
var normalized = _referenceNormalizer.Normalize(
request.SkillId,
request.Source,
request.SkillSlug,
request.Version);
// 获取分布式锁防止并发安装
using var installLock = await _lockProvider.AcquireAsync(normalized.SkillId);
// 执行安装命令
var result = await _installCommandRunner.ExecuteAsync(
new SkillInstallCommandExecutionRequest
{
Command = $"npx skills add {normalized.FullReference} -g -y",
Timeout = TimeSpan.FromMinutes(4)
},
cancellationToken);
// 记录安装元数据
await _metadataStore.WriteAsync(normalized.SkillPath, request);
return new SkillInstallResultDto { Success = result.Success };
}
2.2 实时进度反馈设计
为提升用户体验,系统采用Server-Sent Events(SSE)技术实现安装进度的实时推送。前端通过EventSource API订阅进度事件,后端在命令执行过程中实时输出日志信息:
csharp复制process.OutputDataReceived += async (sender, e) =>
{
await stream.WriteAsync(new SkillInstallProgressEventDto
{
EventType = "output",
Data = e.Data ?? string.Empty
});
};
这种设计使得用户可以在UI上看到类似终端的实时输出,显著提升了操作的可观测性。同时,系统会记录完整的安装日志,便于后续问题排查和审计。
3. 技能市场搜索功能实现
3.1 搜索架构与缓存策略
技能市场搜索功能依赖于远程API服务(api.hagicode.com/v1/skills/search)。为提高响应速度和降低API负载,系统实现了多级缓存机制:
- 内存缓存:使用IMemoryCache缓存热门查询结果,默认过期时间10分钟
- 分布式缓存:通过Orleans Grain实现集群节点间的缓存同步
- 本地存储:对用户历史搜索记录进行本地持久化
csharp复制private async Task<IReadOnlyList<SkillGallerySkillDto>> SearchCatalogAsync(
string query,
CancellationToken cancellationToken,
IReadOnlySet<string>? allowedSources = null)
{
// 构建复合缓存键
var cacheKey = $"skill_search:{query}:{string.Join(",", allowedSources ?? Array
