Local first, community second, web last — one call resolves a user intent to the cheapest capable tier本地优先、社区其次、Web 兜底——一次调用把用户意图解析到最低成本的可用层级
When a user asks the agent to do something, the required capability may live in three places: already on the machine (platform tools, installed skills), in the community (installable skills, paid x402 marketplace services), or nowhere — requiring web research and custom code. The discovery system enforces a strict resolution order across these tiers inside a single search_skills call: results are grouped by tier with a soft recommended pick, and the agent is guided — not hard-blocked — toward the lowest tier that fits. Free and instant always beats installable; installable beats paid; paid beats building from scratch.用户提出一个需求时，所需能力可能存在于三个地方：机器本地（平台工具、已安装 skills）、社区（可安装 skills、x402 marketplace 付费服务）、或者哪儿都没有——需要 Web 调研加自写代码。发现系统在一次 search_skills 调用内部强制执行严格的解析顺序：结果按层级分组，附带软性 recommended 推荐，通过引导而非硬拦截让 agent 选择能满足需求的最低层级。免费即时优于可安装，可安装优于付费，付费优于从零构建。
Tier 0 is checked synchronously and is free; Tier 1 fans out to four remote sources concurrently (~1s wall time); Tier 2 is guidance only — never auto-executed.Tier 0 同步检查、零成本；Tier 1 对四个远程源并发检索（墙钟 ~1s）；Tier 2 仅给出指引，从不自动执行。
Fig. 1 · Resolution flow: one call descends through tiers; each arrow is a decision point, not an automatic fall-through.解析流程：一次调用逐层下探；每个箭头都是决策点，而非自动穿透。
Six rules govern how results are ranked, when installation is intercepted, and how empty results escalate.六条规则决定结果排序、何时拦截安装、以及空结果如何升级。
| Rule规则 | Behavior行为 |
|---|---|
| Pre-install interception装前拦截 | Before any auto-install, check local capabilities first. If an installed skill or platform tool matches with relevance ≥ 0.5, skip installation and return auto_install_skipped with the local alternative.任何 auto-install 之前先查本地能力。已装 skill 或平台工具相关度 ≥ 0.5 命中，则跳过安装，返回 auto_install_skipped 并给出本地替代。 |
| Explicit request显式请求 | Query exactly equal to a skill name is treated as an explicit install request — interception is bypassed and the skill installs normally.query 精确等于 skill 名视为显式安装请求——绕过拦截，正常安装。 |
| Cross-tier threshold跨层升级门槛 | A higher tier overrides a lower tier's recommendation only when Δscore > 0.25 — mild remote advantage never displaces a free local hit.仅当 Δscore > 0.25 时高层级才覆盖低层级推荐——远程的轻微优势不足以取代免费的本地命中。 |
| Empty-result upgrade chain空结果升级链 | No skill found → check paid services → check platform tools → suggest web_search. A platform tool hit is presented as the primary guidance; paid services only as lower-priority alternatives.skill 未命中 → 查付费服务 → 查平台工具 → 建议 web_search。平台工具命中作为首选引导，付费服务只作低优先级备选。 |
| Permission filtering权限过滤 | denied_tool_names always applies; allowed_tool_names acts as a whitelist only when tool_access_restricted=True. Full agents see newly-registered / hot-reloaded tools without friction (lenient-by-default).denied_tool_names 始终生效；allowed_tool_names 仅在 tool_access_restricted=True 时作为白名单。full agent 对新注册 / 热更新工具无摩擦可见（默认宽松）。 |
| Trust labeling信任标注 | Official skills and platform-granted verified marketplace services are labeled trust=high; community and skills.sh sources trust=low. The verified tag is reserved — publishers cannot self-assign it (gateway write-path enforcement, admin-only grants).官方 skills 与平台授予 verified 的 marketplace 服务标注 trust=high；社区与 skills.sh 来源为 trust=low。verified 为保留标签——发布者无法自封（gateway 写入层强制，仅 admin 可授予）。 |
The tool returns information-presenting output rather than hard decisions: results grouped under tiers, paid services under a separate services key, and a single soft recommended pick. The agent — guided by its prompt — makes the final call.工具返回信息呈现式输出而非硬性决定：结果按 tiers 分组，付费服务单列 services，附带一个软性 recommended 推荐。最终选择由 agent 依据 prompt 自行判断。
{
"tiers": {
"tier0_local": { "skills": [...], "platform_tools": [...] },
"tier1_community": { "official": [...], "community": [...], "skills_sh": [...] },
"tier2_build": { "suggestion": "web_search + custom code", ... }
},
"services": [ { "name": ..., "price": ..., "trust": "high|low" } ], // x402 · never auto-purchased
"recommended": { "tier": 0, "name": ..., "reason": ... }, // soft pick, not enforcement
"auto_install_skipped": { "local_alternative": ... } // present when intercepted
}
Guide, don't gate. Earlier designs hard-blocked installs when a local tool existed; this punished legitimate edge cases and fought the agent's judgment. The current system presents tiered evidence and lets the prompt-level protocol ("prefer the lowest tier that fits") do the enforcement. Related distinction: platform tools are capabilities of the platform itself, while skills are outward extensions (community and marketplace) — searching them is one call, but their cost profiles differ, and the tier ordering encodes exactly that.引导，而非拦截。早期设计在本地工具存在时硬性阻止安装，误伤了合理的边缘场景，且与 agent 的自主判断相冲突。当前系统呈现分层证据，由 prompt 层协议（"优先满足需求的最低层级"）完成实际约束。相关区分：平台工具是平台自身的能力，skills 是向外的扩展（社区与 marketplace）——检索合并在一次调用，但成本特征不同，层级顺序编码的正是这一点。
Representative queries and their expected resolution, used as the post-deploy acceptance set (59 unit tests cover the underlying logic).代表性 query 及其预期解析结果，作为部署后的验收集（底层逻辑由 59 个单元测试覆盖）。
| Query | Expected resolution预期解析 |
|---|---|
| "查一下积分余额" | Tier 0 platform tool (quest/credit) — no remote installTier 0 平台工具（quest/credit）——不装任何远程 skill |
| "BTC 现在多少钱" | Tier 0 installed skill (coingecko) used directlyTier 0 已装 skill（coingecko）直接使用 |
| "agent-import" | Exact name → explicit request → installs despite interception精确名 → 显式请求 → 绕过拦截照常安装 |
| "OCR 识别发票" | No local hit → Tier 1 remote skills / paid services本地未命中 → Tier 1 远程 skills / 付费服务 |
| "订酒店" | All empty → upgrade chain message → Tier 2 web_search guidance全空 → 升级链文案 → Tier 2 web_search 指引 |