Macro Skills Crate 深度解析:为 AI Agent 构建技能发现、检索与读取的六边形架构
Macro Skills Crate 深度解析:为 AI Agent 构建技能发现、检索与读取的六边形架构
在 Macro 的统一工作空间里,Agent 之所以能"按需学会"一件事,靠的不是把所有指令塞进系统提示词,而是技能(Skill):一份 Markdown 文档,在被引用时由模型主动检索、读取并遵循。skills crate 正是这套能力的中枢,它把"技能是什么、如何被发现、谁能读取、如何读取"收敛成一组领域端口、一个领域服务和三个 AI 工具。本文以 crates/skills/AGENTS.md 的架构说明为骨架,结合源码逐层展开,读完后你将能够独立理解该 crate 的调用链,并按既有模式新增一个技能工具。
技能的本质:带 skill 子类型的 Markdown 文档
skills crate 的开篇模块注释给出了最精炼的定义:技能是 document sub type 为 skill 的 Markdown 文档,其中的指令在 AI 输入引用该技能时被阅读并遵循(见 crates/skills/src/lib.rs)。
这一定义在类型系统中有明确落点:crates/document_sub_type/src/lib.rs 中 DocumentSubType::Skill 的注释与之一致——"a markdown document containing instructions that AI can read and follow when referenced in an AI input"。因此,技能不是一种新的存储形态,而是复用了 Macro 已有的文档体系:同一套权限、同一套编辑器、同一套搜索索引。
与"用户自建技能"并列的,还有一类内置技能(system skills)。根据 crates/system_skills/src/lib.rs,它们完全以代码中的静态字符串定义(复用 prompt crate 的可组合 Section),并不是数据库里的文档:
- 每个技能一个模块,导出一个
SKILL静态量,并在SYSTEM_SKILLS数组中按展示顺序登记; - 技能 id 由 slug 通过 UUIDv5 在固定命名空间
SYSTEM_SKILL_NAMESPACE上派生,因此"稳定、不会与真实的 v4 文档 id 冲突",但重命名 slug 会改变 id,需视 slug 为永久标识; - 目前登记了
Catch Me Up、What I Did Yesterday、Configure Agent三个技能。
这一设计直接决定了后文所有分支逻辑:服务和工具必须同时对"文档技能"和"内置技能"生效,但两者的读取路径完全不同。
一处值得注意的细节:system_skills 的模块注释 称内置技能通过
ListSkills、SearchSkills、ReadContent暴露,而skillscrate 实际注册的工具名是ReadSkill(见 crates/skills/src/inbound/toolset.rs)。以源码为准,ReadContent是注释中的过时表述。
架构总览:domain / inbound / outbound 三层
skills 采用典型的六边形(端口—适配器)分层,模块声明本身即架构图(crates/skills/src/lib.rs):
| 层 | 目录 | 职责 |
|---|---|---|
| domain | src/domain/ |
领域模型、端口 trait、SkillService 默认实现 |
| inbound | src/inbound/ |
面向请求方的适配器,即 AI 工具集 |
| outbound | src/outbound/ |
面向外部依赖的适配器:搜索服务、soup、文档读取 |
三层通过 Cargo feature 解耦,Cargo.toml 中定义了三个 feature(crates/skills/Cargo.toml):
[features]
ai_tools = ["dep:ai_toolset", "dep:async-trait", "dep:schemars", "dep:serde", "ports"]
default = ["ai_tools", "outbound", "ports"]
outbound = [ ... "dep:search_service_client", "dep:soup", "ports"]
ports = []
这意味着:只依赖 ports 即可拿到纯 trait 定义与领域服务,无需拉入 documents、soup、search_service_client 等重量级依赖;outbound 才引入具体实现;ai_tools 才暴露工具定义。lib.rs 中 pub mod inbound 与 pub mod outbound 分别以 #[cfg(feature = ...)] 守卫,与此对应。
顶层依赖刻意保持精简(crates/skills/Cargo.toml):document_sub_type、entity_access(仅 ports)、macro_user_id、system_skills、anyhow、thiserror、tracing、uuid、chrono。按 AGENTS.md 的边界说明,本 crate 不负责技能文档自身的编辑/存储界面(属 documents),也不负责技能如何注入提示词(属 agent harness);它只拥有"发现、搜索、读取"这三件事及其适配器。
领域模型:小而精确的五个类型
crates/skills/src/domain/model.rs 只有五个公开类型,但每个都承载了明确的语义约束。
SkillSummary:检索结果的最小投影
pub struct SkillSummary {
pub document_id: uuid::Uuid,
pub name: String,
pub updated_at: Option<DateTime<Utc>>,
}
updated_at 是 Option,这是为内置技能留的位置——它们没有更新时间。这个"可空"直接影响了排序策略,后文会看到。
SkillMatchType:两种匹配语义
pub enum SkillMatchType {
#[default]
Partial, // 前缀匹配:单词项匹配以其开头的 token
Exact, // 整 token / 精确短语匹配,不做前缀扩展
}
Partial 是默认值,deplo 可以命中 deploy;Exact 则要求整词相等。
SkillError:面向模型的可读错误
错误枚举的 Display 文案明显是为"给模型看"而设计的:
| 变体 | 消息 | 触发场景 |
|---|---|---|
InvalidRequest |
{0}(透传内部消息) |
例如空查询 |
ReadFailed |
skill reading failed |
文档元数据或正文读取失败 |
AccessDenied |
skill not found or access denied |
权限回执签发失败 |
NotASkill |
document is not an active skill; use ListSkills to find skills |
目标文档被删除、子类型不是 skill、或不是 md |
SearchFailed |
skill search failed |
搜索后端失败 |
ListFailed |
skill listing failed |
列表后端失败 |
NotASkill 的文案甚至直接指示模型"改用 ListSkills 去找技能",这是一种把纠错策略写进错误信息的实用做法。
SkillContent 与 SkillDocumentMetadata
SkillContent 是独立于 agent harness 的最终产物:document_id(可为内置技能 id)、name、content(完整 Markdown 指令)。
SkillDocumentMetadata 则是"是否可作为技能读取"的判定依据:name、sub_type、file_type、deleted。注意它只有四个事实字段,不包含正文——这正是 read_skill 能够"先校验、后取正文"的基础。
端口定义:四条 trait 划清能力边界
crates/skills/src/domain/ports.rs 定义了全部端口,并把"权限由谁负责"写进了文档注释。
出站端口 SkillSearcher:按名称搜索当前用户可见的技能。注释明确"实现方负责执行按用户的访问控制:只能返回用户可查看的技能"。
fn search_skills_by_name(
&self,
user_id: &MacroUserIdStr<'_>,
query: &str,
match_type: SkillMatchType,
) -> impl Future<Output = Result<Vec<SkillSummary>, SkillError>> + Send;
出站端口 SkillLister:列出可见技能,最多 limit 条,最近更新优先。
入站端口 SkillService:面向 inbound 适配器的用例集合——read_skill、search_skills、list_skills。它是 SkillToolContext 唯一依赖的抽象,因此工具层完全不知道后端是搜索服务还是 soup。
出站端口 SkillReader:把"授权"与"读取"拆成三步,这是本 crate 最值得注意的安全设计:
fn authorize(&self, user_id, document_id) -> Result<EntityAccessReceipt<ViewAccessLevel>, SkillError>;
fn metadata(&self, receipt: &EntityAccessReceipt<ViewAccessLevel>) -> Result<SkillDocumentMetadata, SkillError>;
fn markdown(&self, receipt: EntityAccessReceipt<ViewAccessLevel>) -> Result<String, SkillError>;
metadata 与 markdown 的入参不是裸 document_id,而是 EntityAccessReceipt<ViewAccessLevel>——一个"已证明调用者可查看"的能力凭证。注释原话是"Read document facts only after access has been established"(仅在访问权确立后才读取文档事实)。这种把授权结果物化为类型的写法,使得"忘了鉴权"在编译期就难以发生。
SkillServiceImpl:三个用例的真实行为
crates/skills/src/domain/service.rs 的实现体是 SkillServiceImpl<S, L, R>,由 searcher、lister、reader 三个泛型参数组合而成,构造即 SkillServiceImpl::new(searcher, lister, reader)。
read_skill:内置技能短路 + 文档校验
async fn read_skill(&self, user_id, document_id) -> Result<SkillContent, SkillError> {
if let Some(skill) = system_skills::system_skill(document_id) {
return Ok(SkillContent {
document_id,
name: skill.name.to_string(),
content: skill.render_content(),
});
}
let receipt = self.reader.authorize(user_id, document_id).await?;
let document = self.reader.metadata(&receipt).await?;
if document.deleted
|| document.sub_type != Some(document_sub_type::DocumentSubType::Skill)
|| document.file_type.as_deref() != Some("md")
{
return Err(SkillError::NotASkill);
}
let content = self.reader.markdown(receipt).await?;
Ok(SkillContent { document_id, name: document.name, content })
}
两个关键点:
- 内置技能先行短路。若 id 命中
system_skill,直接渲染静态内容返回,完全不触碰 reader——也就没有任何文档权限要求。测试listed_system_skills_can_be_read_without_document_access正是断言了reader.calls为空。 - 三重条件校验:未删除、子类型为
Skill、文件类型为md。任一不满足即返回NotASkill,且此时只调用了authorize与metadata,正文不会被读取——测试non_skills_deleted_documents_and_non_markdown_are_rejected_before_content逐一覆盖了这三种非法输入。
search_skills:空查询拦截 + 内置技能本地匹配 + 统一排序
let query = query.trim();
if query.is_empty() {
return Err(SkillError::InvalidRequest("query must not be empty".to_string()));
}
let mut skills = self.searcher.search_skills_by_name(user_id, query, match_type).await?;
skills.extend(system_skill_summaries().filter(|s| system_skill_name_matches(&s.name, query, match_type)));
sort_most_recently_updated_first(&mut skills);
为什么内置技能要在这里本地匹配?源码注释给出理由:"System skills are static, so they are matched here rather than by the search backend."它们不在搜索索引里。
匹配算法 system_skill_name_matches 刻意与搜索服务保持同语义:查询 token 必须作为名称 token 的连续相邻片段出现;Partial 额外允许最后一个查询 token 做前缀匹配。
(0..=name_tokens.len() - query_tokens.len()).any(|start| {
query_tokens.iter().enumerate().all(|(offset, query_token)| {
let name_token = &name_tokens[start + offset];
let is_last = offset == query_tokens.len() - 1;
match match_type {
SkillMatchType::Exact => name_token == query_token,
SkillMatchType::Partial if is_last => name_token.starts_with(query_token),
SkillMatchType::Partial => name_token == query_token,
}
})
})
由此产生的可验证行为(均有测试覆盖):
- 查询
"catch me up"命中Catch Me Up; - 查询
"catch up"因跳过中间 token 不命中(system_skill_matching_requires_adjacent_tokens); - 查询
"yester"在Partial下命中What I Did Yesterday,在Exact下不命中(search_excludes_non_matching_system_skills)。
这也解释了工具描述为何反复强调"传 1–3 个会字面出现在技能名里的关键词,不要写自然语言描述"。
list_skills:固定上限 100,内置技能恒在
const LIST_LIMIT: u16 = 100;
let mut skills = self.lister.list_skills(user_id, LIST_LIMIT).await?;
skills.extend(system_skill_summaries());
sort_most_recently_updated_first(&mut skills);
排序函数是共享的:
fn sort_most_recently_updated_first(skills: &mut [SkillSummary]) {
skills.sort_by(|a, b| {
b.updated_at.cmp(&a.updated_at)
.then_with(|| a.document_id.cmp(&b.document_id))
});
}
由于 Option<DateTime<Utc>> 的 Ord 中 None < Some(_),内置技能(updated_at: None)会排在所有有时间戳的用户技能之后,同组内再按 document_id 升序稳定排列。测试 listed_skills_are_sorted_most_recently_updated_first 与 listing_always_includes_system_skills 断言了这两点。
三个 AI 工具:SearchSkills / ListSkills / ReadSkill
inbound 层只做"协议转换":把 JSON 参数转成领域调用,把领域结果转成 JSON 响应。工具集由 skill_toolset() 组装(crates/skills/src/inbound/toolset.rs):
pub fn skill_toolset<Svc: SkillService>() -> AsyncToolCollection<SkillToolContext<Svc>> {
AsyncToolCollection::new()
.add_tool::<SearchSkills, SkillToolContext<Svc>>()
.add_tool::<ListSkills, SkillToolContext<Svc>>()
.add_tool::<ReadSkill, SkillToolContext<Svc>>()
}
SkillToolContext 内部用 Arc<Svc> 包裹服务,并手写 Clone(而非 derive),以支持跨工具共享同一服务实例。
SearchSkills:关键词检索
定义见 crates/skills/src/inbound/toolset/search_skills.rs。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
name |
String |
必填 | 技能名关键词,整体作为单个相邻短语前缀匹配,过长短语不会命中 |
matchType |
"partial" | "exact" |
partial |
partial 每个词按前缀匹配;exact 整 token/短语匹配 |
注意入参枚举 SearchSkillsMatchType 使用 #[serde(rename_all = "lowercase")],而结构体字段使用 rename_all = "camelCase",所以模型调用时应写 {"name": "catch me up", "matchType": "exact"}。该枚举通过 From 转换为领域层的 SkillMatchType,两层模型没有互相污染。
响应结构:
{
"results": [
{ "documentId": "…", "name": "Catch Me Up", "updatedAt": "2026-10-30T12:00:00Z" }
]
}
updatedAt 带 skip_serializing_if = "Option::is_none",因此内置技能的条目不会出现该字段。
错误映射上有一处细节:仅 InvalidRequest 会把内部消息直接作为 description 暴露给模型,其余错误统一折叠为 "failed to search skills",原始错误留在 internal_error。
ListSkills:无参发现
ListSkills {} 是空结构体,也实现了 Default,因此模型传 {} 即可。其描述明确分工:"用它发现有哪些技能;按名称找特定技能或找不在列表中的旧技能时,改用 SearchSkills。"响应同样复用 SkillSearchResult 列表,最多 100 条用户技能 + 全部内置技能。
ReadSkill:按 id 取全文
请求体只有一个 documentId(Uuid),响应为 documentId + name + content:
{
"documentId": "…",
"name": "Review code",
"content": "# Review\n\nFollow every step.\n"
}
三个工具都通过 ToolAnnotated 标记为只读(ToolAnnotations::read_only(...)),这向宿主声明了它们没有副作用,可安全重试或并行调用。日志方面统一使用 tracing::instrument(skip_all, fields(user_id=...), err),把用户维度与错误同时写入 span。
端到端的分发行为由 discovery_and_reading_work_through_json_tool_dispatch 验证:先 ListSkills 拿到 results[0].documentId,再用同一 id 调 ReadSkill,断言名称与正文;最后用 {"documentId":"invalid"} 断言参数校验失败。
出站适配器:三个后端,三种访问控制路径
SearchServiceSkillSearcher:走统一搜索
crates/skills/src/outbound/search_service_searcher.rs 把领域调用翻译成一次统一搜索请求:
PAGE_SIZE: i64 = 50——单次搜索上限;- 过滤条件强制
sub_types: vec![DocumentSubType::Skill.to_string()]; search_on: models_search::SearchOn::Name——只搜名称;include_crm: false,且filters由entity_filters_from_include(vec![UnifiedSearchIndex::Documents], base_filters)限定在文档索引;collapse: None,即不做结果折叠。
匹配类型直接映射到 models_search::MatchType::Partial / Exact。适配器注释强调"搜索服务执行按用户访问控制",这正是端口契约中把权限责任下推给实现方的体现。响应里只保留 UnifiedSearchResponseItem::Document,其余项被 filter_map 丢弃;updated_at 取自 doc.metadata,因此缺失元数据时为 None。
SoupSkillLister:走工作流列表
crates/skills/src/outbound/soup_skill_lister.rs 的关键在于 skill_only_filter():除了给 document_filter 设置 DocumentLiteral::SubType(Skill),还把 project、chat、email thread、channel、channel thread、call、crm company、foreign entity、calendar event 全部强制过滤为 Uuid::nil(),从而让 soup "完全跳过"这些实体类型。源码注释对保留 None 的字段也给了理由:提醒、GitHub PR、initiative、agent session、database row、properties 都是"opt-in"的,留空即排除。
请求参数同样有讲究:
soup_type: SoupType::Expanded, // 含通过项目权限可达的文档;也是唯一支持 AST 过滤器的类型
cursor: SoupQuery::new_sort_simple(SimpleSortMethod::UpdatedAt, skill_only_filter()),
sort_direction: SoupSortDirection::default(), // 最近更新优先
email_preview_view: PreviewView::default(), // 邮件已被排除,预览视图无关
link_ids: Vec::new(),
若改用非 Expanded 的 soup 类型,会因"not implemented"被拒绝——这是注释里明确记录的实现约束。结果经 type_erase() 后只保留 SoupItem::Document,updated_at 为 Some(doc.updated_at)。
DocumentSkillReader:授权回执驱动的读取
crates/skills/src/outbound/document_skill_reader.rs 组合了 DocumentService、EntityAccessService 与 LexicalClient:
authorize调用generate_entity_access_receipt(user_id, None, &document_id.to_string(), EntityType::Document),失败映射为AccessDenied;metadata通过internal_get_basic_document(&receipt.entity().entity_id)取基础文档,把document_name、sub_type、file_type、deleted_at.is_some()投影成SkillDocumentMetadata;markdown调用lexical.get_markdown(entity_id, MarkdownTarget::Internal)取当前 Markdown。
也就是说,技能的"正文"实际来自 Lexical 文档模型渲染出的内部 Markdown,而不是某个纯文本字段——这保证了技能内容与用户在编辑器中看到的文档始终一致。
装配:AI 工具如何接入全量工具集
skills 自身不负责构造具体适配器,装配发生在 ai_tools。类型别名把三个具体实现钉死在泛型参数上(crates/ai_tools/src/tool_context.rs):
pub type ToolSkillService = skills::domain::service::SkillServiceImpl<
SearchServiceSkillSearcher,
SoupSkillLister<ToolSoupService>,
DocumentSkillReader<ToolDocumentService, ToolEntityAccessService>,
>;
pub fn build_skill_tool_context(
search_service_client: Arc<SearchServiceClient>,
soup_service: Arc<ToolSoupService>,
documents: &ToolDocumentToolContext,
) -> ToolSkillToolContext {
SkillToolContext::new(SkillServiceImpl::new(
SearchServiceSkillSearcher::new(search_service_client),
SoupSkillLister::new(soup_service),
DocumentSkillReader::new(
documents.service.clone(),
documents.entity_access_service.clone(),
documents.lexical_client.clone(),
),
))
}
随后在总工具集里挂载(crates/ai_tools/src/lib.rs):
.add_subtoolset::<ToolSkillToolContext>(skill_toolset())
add_subtoolset 意味着技能三个工具并非以平铺命名空间注入,而是作为一个子工具集注册——与 initiative、properties、databases 等模块一致。由此推断,宿主可按需启用/裁剪子工具集;具体裁剪策略属于 ai_tools 的 host 逻辑,不在本 crate 范围内。
扩展实践:新增一个技能工具
AGENTS.md 给出的"配方"是四步,源码完全对得上:
- 加端口方法:crates/skills/src/domain/ports.rs——若需要新的数据能力,优先新增出站 trait 或在
SkillService上加入站方法; - 实现用例:crates/skills/src/domain/service.rs——在
impl SkillService for SkillServiceImpl中实现,注意保留#[tracing::instrument(skip(self), err)]; - 编写工具:在
src/inbound/toolset/下新建文件,仿照 read_skill.rs 实现AsyncTool<SkillToolContext<Svc>>,并同时提供schemars元数据与ToolAnnotated注解; - 注册:在 crates/skills/src/inbound/toolset.rs 的
mod列表、pub use与skill_toolset()三处同步添加。
若新工具依赖新后端,还需在 Cargo.toml 的 outbound feature 中追加可选依赖——feature 列表本身就是依赖准入清单。命名上应遵循现有约定:入参结构体用 #[serde(rename_all = "camelCase")]、#[schemars(title = "...", description = "...")],字段逐个写 description,因为这些描述就是模型看到的唯一使用说明。
边界与排错:五类典型信号
| 现象 | 可能原因 | 定位 |
|---|---|---|
document is not an active skill; use ListSkills to find skills |
文档已删除 / sub_type 非 skill / file_type 非 md |
read_skill 的三重校验 |
skill not found or access denied |
权限回执签发失败 | DocumentSkillReader::authorize |
query must not be empty |
查询仅含空白字符 | search_skills 的 trim 拦截 |
| 搜索结果里没有某个内置技能 | 查询 token 不连续,或 exact 下未整词匹配 |
system_skill_name_matches |
ReadSkill 报参数错误 |
documentId 不是合法 UUID |
工具层反序列化 |
另有两个易被忽略的语义边界:其一,list_skills 的用户技能上限是 LIST_LIMIT = 100,更早的技能只能靠 SearchSkills 找到(这与工具描述中的指引一致);其二,技能 id 空间里混有两种来源,内置技能 id 是 UUIDv5 派生值,绝不要把它当作文档 id 去查权限或编辑。
验证方式
该 crate 自带一套不依赖数据库的领域测试(crates/skills/src/domain/service/test.rs),用 FakeSearcher / FakeLister / FakeReader 精确断言调用序列,例如:
read_returns_complete_markdown_after_authorization断言调用顺序严格为["authorize", "metadata", "markdown"];denied_reads_never_fetch_metadata_or_content断言鉴权失败后只剩["authorize"];searcher_errors_are_propagated/lister_errors_are_propagated断言错误不吞;discovery_and_reading_work_through_json_tool_dispatch在ai_toolsfeature 下走真实 JSON 分发。
按 AGENTS.md 的 Checks 章节执行:
cargo test -p skills
注意其括注:需 SQLX_OFFLINE 未设置("SQLX_OFFLINE unset")。原因可以从依赖关系推断:outbound feature 会引入 documents、soup 等含 SQL 查询的 crate,离线模式下的查询缓存可能无法覆盖测试期编译需求。
小结
skills crate 的价值不在于代码量,而在于它把一个容易被做散的功能收束成清晰的三段式:端口定义能力与权限责任,领域服务统一内置/用户技能的分支与排序语义,入站工具只做协议转换。三个设计决策尤其值得借鉴——用 EntityAccessReceipt 让鉴权成为类型前置条件、用 Option<updated_at> 自然表达内置技能的排序位置、用与搜索后端同构的 token 匹配算法保证两条检索路径行为一致。理解了这三点,无论是要新增一个技能工具,还是排查"为什么模型找不到某个技能",都能直接落到具体文件与函数上。