HagiCode Skill 系统技术解析：如何打造可扩展的 AI 技能管理平台
本文深入解析 HagiCode 项目中 Skill（技能）管理系统的架构设计与实现方案，涵盖本地全局管理、市场搜索、智能推荐、授信提供者管理四大核心功能的技术实现细节。
背景
在 AI 代码助手这个领域，如何扩展 AI 的能力边界，其实一直是个核心课题。Claude Code 本身的代码辅助能力是挺强的，只是不同开发团队、不同技术栈，往往需要针对特定场景的专业能力——比如处理 Docker 部署、数据库优化、前端组件生成之类的。这时候，Skill（技能）系统就显得尤为重要了。
HagiCode 项目在开发过程中也遇到了类似的挑战：怎么让 Claude Code 能够像人一样「学会」新的专业技能，同时保持良好的用户体验和工程可维护性？毕竟这个问题，说难也难，说简单也简单。围绕这个问题，我们设计并实现了一套完整的 Skill 管理系统。
本文将详细解析这个系统的技术架构和核心实现，适合对 AI 扩展性、命令行工具集成感兴趣的开发者阅读。或许对你有用，也或许没用，但总归是写出来了。
关于 HagiCode
本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，旨在帮助开发团队提升研发效率。项目的技术栈涵盖 ASP.NET Core、Orleans 分布式框架、TanStack Start + React 前端，以及本文要介绍的 Skill 管理子系统。
项目的 GitHub 地址是 HagiCode-org/site，如果你觉得本文介绍的技术方案有价值，欢迎给个 Star。毕竟Star多了，心情也会好一些。
系统架构概览
Skill 系统采用前后端分离的架构设计，说起来也没什么特别的。
前端部分 使用 TanStack Start + React 构建用户界面，通过 Redux Toolkit 管理状态，四个主要功能分别对应四个 Tab 组件：本地技能、市场画廊、智能推荐、授信提供者。这样设计，其实也是为了用户体验罢了。
后端部分 基于 ASP.NET Core + ABP Framework，使用 Orleans Grain 实现分布式状态管理。在线 API 客户端封装了 IOnlineApiClient 接口，用于与远程技能目录服务通信。
整体架构的设计原则是「命令执行与业务逻辑分离」，通过适配器模式将 npm/npx 命令执行的细节屏蔽在独立模块中。毕竟谁愿意看到一堆命令行散落在代码各处呢？
核心功能一：本地全局管理
本地全局管理是最基础的功能模块，负责列出已安装的技能并支持卸载操作。也没什么复杂的，就是把事情做好而已。
技术方案
实现位置在 LocalSkillsTab.tsx 和 LocalSkillCommandAdapter.cs。核心思路是封装 npx skills 命令，解析其 JSON 输出，转换为内部数据结构。说起来简单，做起来其实也简单。
public async Task<IReadOnlyList<LocalSkillInventoryResponseDto>> GetLocalSkillsAsync(
CancellationToken cancellationToken = default)
{
var result = await _commandAdapter.ListGlobalSkillsAsync(cancellationToken);
return result.Skills.Select(skill => new LocalSkillInventoryResponseDto
{
Name = skill.Name,
Version = skill.Version,
Source = skill.Source,
InstalledPath = skill.InstalledPath,
Description = skill.Description
}).ToList();
}
数据流非常清晰：前端发起请求 → SkillGalleryAppService 接收 → LocalSkillCommandAdapter 执行 npx 命令 → 解析 JSON 结果 → 返回 DTO 对象。一环扣一环，也没什么好说的。
卸载技能使用 npx skills remove -g <skillName> -y 命令，系统会自动处理依赖关系和清理工作。安装元数据存储在技能目录的 managed-install.json 中，记录了安装时间、来源版本等信息，便于后续更新和审计。毕竟有些东西，记下来总是好的。
安装流程详解
技能安装涉及多个步骤的协调，怎么说呢，其实也不算太复杂：
public async Task<SkillInstallResultDto> InstallAsync(
SkillInstallRequestDto request,
CancellationToken cancellationToken = default)
{
// 1. 规范化安装引用
var normalized = _referenceNormalizer.Normalize(
request.SkillId,
request.Source,
request.SkillSlug,
request.Version);
// 2. 检查先决条件
await _prerequisiteChecker.CheckAsync(cancellationToken);
// 3. 获取安装锁
using var installLock = await _lockProvider.AcquireAsync(normalized.SkillId);
// 4. 执行安装命令
var result = await _installCommandRunner.ExecuteAsync(
new SkillInstallCommandExecutionRequest
{
Command = $"npx skills add {normalized.FullReference} -g -y",
Timeout = TimeSpan.FromMinutes(4)
},
cancellationToken);
// 5. 持久化安装元数据
await _metadataStore.WriteAsync(normalized.SkillPath, request);
return new SkillInstallResultDto {
Success = result.Success };
}
这里用到了几个关键的设计模式：引用规范化器 负责将各种输入格式（如 tanweai/pua、@opencode/docker-skill）转换为统一的内部表示；安装锁机制 确保同一技能同时只有一个安装操作在进行；流式输出 通过 Server-Sent Events 向前端实时推送安装进度，用户可以看到类似终端的实时日志。
这些设计模式，说到底，也还是为了让事情变得简单罢了。
核心功能二：市场搜索
市场搜索让用户能够发现和安装来自社区的技能。毕竟一个人的能力是有限的，众人的智慧才是无穷的。
技术方案
搜索功能依赖在线 API https://api.hagicode.com/v1/skills/search。为了提升响应速度，系统实现了缓存机制。缓存这东西，就像记忆一样，有些东西记住了，下次就不用再费劲去想。
private async Task<IReadOnlyList<SkillGallerySkillDto>> SearchCatalogAsync(
string query,
CancellationToken cancellationToken,
IReadOnlySet<string>? allowedSources = null)
{
var cacheKey = $"skill_search:{query}:{string.Join(",", allowedSources ?? Array.Empty<string>())}";
if (_memoryCache.TryGetValue(cacheKey, out var cached))
return (IReadOnlyList<SkillGallerySkillDto>)cached!;
var response = await _onlineApiClient.SearchAsync(
new SearchSkillsRequest
{
Query = query,
Limit = _options.LimitPerQuery,
},
cancellationToken);
var results = response.Skills
.Where(skill => allowedSources is null || allowedSources.Contains(skill.Source))
.Select(skill => new SkillGallerySkillDto {
... })
.ToList();
_memoryCache.Set(cacheKey, results, TimeSpan.FromMinutes(10));
return results;
}
搜索结果支持按授信来源过滤，只显示用户信任的技能源。预置的种子查询用于初始化目录，比如「popular」、「recent」等，让用户在首次打开时就能看到推荐的热门技能。毕竟第一印象还是重要的。
核心功能三：智能推荐
智能推荐是系统中最复杂的功能，它能根据用户当前项目的情况，自动推荐最适合的技能。复杂归复杂，但做出来还是值得的。
推荐流程
整个推荐流程分为五个阶段：
1. 构建项目上下文
↓
2. AI 生成搜索查询
↓
3. 并行搜索在线目录
↓
4. AI 对候选进行排名
↓
5. 返回推荐列表
首先，系统分析项目的技术栈、编程语言、域名结构等特征，构建一个「项目画像」。这个画像，就像一个人的简历一样，记录着所有的特征。
然后，使用 AI Grain 生成针对性的搜索查询。这里的设计其实挺有意思——不是直接问 AI「推荐什么技能」，而是让它先思考「什么样的搜索词能找到相关技能」。毕竟有时候，问问题的方法比答案本身更重要：
var queryGeneration = await aiGrain.GenerateSkillRecommendationQueriesAsync(
projectContext, // 项目上下文
locale, // 用户语言偏好
maxQueries, // 最大查询数量
effectiveSearchHero); // AI 模型选择
接着，并行执行这些搜索查询，获取候选技能列表。并行处理，说到底也是为了节省时间罢了。
最后，使用另一个 AI Grain 对候选技能进行排名。这一步会综合考虑技能与项目的相关性、授信状态、用户历史偏好等因素：
var ranking = await aiGrain.RankSkillRecommendationsAsync(
projectContext,
candidates,
installedSkillNames,
locale,
maxRecommendations,
effectiveRankingHero);
response.Items = MergeRecommendations(projectContext, candidates, ranking, maxRecommendations);
回退机制
AI 模型可能出现响应慢或暂时不可用的情况。毕竟再好的系统，也有掉链子的时候。为此，系统设计了确定性回退机制：当 AI 服务不可用时，使用基于规则启发式算法生成推荐，比如根据 package.json 中的依赖推断可能需要的技能。
这个回退机制，说穿了，也就是给系统留了一条后路罢了。
核心功能四：授信提供者管理
授信提供者管理允许用户控制哪些技能源是可信的。毕竟信任这东西，还是要自己把握的。
匹配规则
授信提供者支持两种匹配规则：精确匹配（exact）和前缀匹配（prefix）。
public static TrustedSkillProviderResolutionSnapshot Resolve(
TrustedSkillProviderSnapshot snapshot,
string source)
{
var normalizedSource = Normalize(source);
foreach (var entry in snapshot.Entries.OrderBy(e => e.SortOrder))
{
if (!entry.IsEnabled) continue;
foreach (var rule in entry.MatchRules)
{
bool isMatch = rule.MatchType switch
{
TrustedSkillProviderMatchRuleType.Exact
=> string.Equals(normalizedSource, Normalize(rule.Value),
StringComparison.OrdinalIgnoreCase),
TrustedSkillProviderMatchRuleType.Prefix
=> normalizedSource.StartsWith(Normalize(rule.Value) + "/",
StringComparison.OrdinalIgnoreCase),
_ => false
};
if (isMatch)
return new TrustedSkillProviderResolutionSnapshot
{
IsTrustedSource = true,
ProviderId = entry.ProviderId,
DisplayName = entry.DisplayName
};
}
}
return new TrustedSkillProviderResolutionSnapshot {
IsTrustedSource = false };
}
预置的授信提供者包括 Vercel、Azure、anthropics、Microsoft、browser-use 等知名组织和项目。自定义提供者可以通过配置文件添加，指定提供者 ID、显示名称、徽章标签、匹配规则等。毕竟世界那么大，不可能只有几家是可信的。
持久化实现
授信配置使用 Orleans Grain 持久化存储：
public class TrustedSkillProviderGrain : Grain<TrustedSkillProviderState>,
ITrustedSkillProviderGrain
{
public async Task UpdateConfigurationAsync(TrustedSkillProviderSnapshot snapshot)
{
State.Snapshot = snapshot;
await WriteStateAsync();
}
public Task<TrustedSkillProviderSnapshot> GetConfigurationAsync()
{
return Task.FromResult(State.Snapshot);
}
}
这种方式的好处是配置变更会自动同步到所有节点，无需手动刷新缓存。毕竟自动化，说到底也是为了让人少操心罢了。
关键技术设计
命令执行适配器模式
Skill 系统需要执行各种 npx 命令，如果把这些逻辑散落在各处，代码会变得难以维护。因此我们设计了适配器接口。设计模式这东西，说到底，也还是为了让代码更好维护而已：
public interface ISkillInstallCommandRunner
{
Task<SkillInstallCommandExecutionResult> ExecuteAsync(
SkillInstallCommandExecutionRequest request,
CancellationToken cancellationToken = default);
}
不同的命令有不同的执行器实现，全部实现同一个接口，便于测试和替换。
SSE 流式输出
安装进度通过 Server-Sent Events 实时推送到前端：
public async Task InstallWithProgressAsync(
SkillInstallRequestDto request,
IServerStreamWriter<SkillInstallProgressEventDto> stream,
CancellationToken cancellationToken)
{
var process = new Process
{
StartInfo = new ProcessStartInfo
{
FileName = "npx",
Arguments = $"skills add {request.FullReference} -g -y",
RedirectStandardOutput = true,
RedirectStandardError = true,
UseShellExecute = false
}
};
process.OutputDataReceived += async (sender, e) =>
{
await stream.WriteAsync(new SkillInstallProgressEventDto
{
EventType = "output",
Data = e.Data ?? string.Empty
});
};
process.Start();
process.BeginOutputReadLine();
await process.WaitForExitAsync(cancellationToken);
}
用户在前端可以看到类似终端的实时输出，体验非常直观。毕竟实时反馈，让人安心。
实践指南
安装社区技能
以安装 pua 技能为例（这是一个流行的社区技能）：
- 打开 Skills 抽屉，切换到「Skill Gallery」标签
- 输入「pua」进行搜索
- 点击搜索结果查看技能详情
- 点击「Install」按钮安装
- 切换到「Local Skills」标签确认安装成功
安装命令是 npx skills add tanweai/pua -g -y，系统会自动处理所有细节。其实也没那么多步骤，一步步来就是了。
添加自定义授信来源
如果你的团队有自己的技能仓库，可以添加为授信来源：
providerId: "my-team"
displayName: "My Team Skills"
badgeLabel: "MyTeam"
isEnabled: true
sortOrder: 100
matchRules:
- matchType: "prefix"
value: "my-team/"
- matchType: "exact"
value: "my-team/special-skill"
这样来自你团队的所有技能都会显示授信徽章，用户可以更放心地安装。毕竟有标记的东西，总是让人安心一些。
技能开发基础
创建自定义技能需要遵循以下结构：
my-skill/
├── SKILL.md # 技能元数据（YAML front matter）
├── index.ts # 技能入口
├── agents/ # 支持的代理配置
└── references/ # 参考资源
SKILL.md 的格式示例：
---
name: my-skill
description: A brief description of what this skill does
---
# My Skill
Detailed documentation...
注意事项
- 网络要求：技能搜索和安装需要能访问
api.hagicode.com和 npm registry - Node.js 版本：建议使用 Node.js 18 或更高版本
- 权限要求：需要全局 npm 安装权限
- 并发控制：同一技能同时只能有一个安装或卸载操作在执行
- 超时设置：安装操作默认超时时间为 4 分钟，复杂场景可能需要调整
这些注意事项，说到底，也还是为了让事情顺利进行罢了。
总结
本文介绍了 HagiCode 项目中 Skill 管理系统的完整实现。这个系统通过前后端分离的架构、适配器模式、Orleans 分布式状态管理等技术手段，实现了：
- 本地全局管理：通过封装 npx skills 命令，提供统一的技能管理接口
- 市场搜索：利用在线 API 和缓存机制，快速发现社区技能
- 智能推荐：结合 AI 能力，根据项目上下文推荐最合适的技能
- 授信管理：灵活的配置系统，让用户掌控信任边界
这套设计思路不仅适用于 Skill 管理，对于任何需要集成命令行工具、兼顾本地存储和在线服务的场景，都有参考价值。
如果本文对你有帮助，欢迎来 GitHub 给个 Star：github.com/HagiCode-org/site。也可以访问官网了解更多：hagicode.com。
或许你也会觉得，这套系统设计得还行，或许你不会。但这都罢了，毕竟代码写出来，总有人会用，也总有人不会用......
参考资料
- HagiCode 项目地址：github.com/HagiCode-org/site
- HagiCode 官网：hagicode.com
- Claude Code 官方技能文档：docs.anthropic.com
- Orleans 框架文档：dotnet.github.io/orleans
- TanStack Start：tanstack.com/start
原文与版权说明
感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: newbe36524
- 原文链接: https://docs.hagicode.com/go?platform=aliyun-community&target=%2Fblog%2F2026-03-24-hagicode-skill-system-technical-analysis%2F
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
