Macro Skills Crate 深度解析:为 AI Agent 构建技能发现、检索与读取的六边形架构

原创2026-10-31 12:02:461,879 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

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 暴露,而 skills crate 实际注册的工具名是 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 })
}

两个关键点:

  1. 内置技能先行短路。若 id 命中 system_skill,直接渲染静态内容返回,完全不触碰 reader——也就没有任何文档权限要求。测试 listed_system_skills_can_be_read_without_document_access 正是断言了 reader.calls 为空。
  2. 三重条件校验:未删除、子类型为 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:

  1. authorize 调用 generate_entity_access_receipt(user_id, None, &document_id.to_string(), EntityType::Document),失败映射为 AccessDenied;
  2. metadata 通过 internal_get_basic_document(&receipt.entity().entity_id) 取基础文档,把 document_name、sub_type、file_type、deleted_at.is_some() 投影成 SkillDocumentMetadata;
  3. 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 给出的"配方"是四步,源码完全对得上:

  1. 加端口方法:crates/skills/src/domain/ports.rs——若需要新的数据能力,优先新增出站 trait 或在 SkillService 上加入站方法;
  2. 实现用例:crates/skills/src/domain/service.rs——在 impl SkillService for SkillServiceImpl 中实现,注意保留 #[tracing::instrument(skip(self), err)];
  3. 编写工具:在 src/inbound/toolset/ 下新建文件,仿照 read_skill.rs 实现 AsyncTool<SkillToolContext<Svc>>,并同时提供 schemars 元数据与 ToolAnnotated 注解;
  4. 注册:在 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_tools feature 下走真实 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 匹配算法保证两条检索路径行为一致。理解了这三点,无论是要新增一个技能工具,还是排查"为什么模型找不到某个技能",都能直接落到具体文件与函数上。

登录后查看全文
macro