Nansen General Search Skill 实战指南：用 nansen research search 完成代币与实体的名称检索-育师

【免费下载链接】internet-court-skill

The trust layer for agent-to-agent commerce — natural-language mandates, ERC-7710 delegated permissions, x402 payments, escrow, and dispute resolution as one open, catch-all Agent Skill / Claude Code plugin.

项目地址：https://gitcode.com/gh_mirrors/in/internet-court-skill

点击查看免费下载

本文围绕互联网法院技能仓库中 vendored 的nansen-general-searchSkill（SKILL.md），系统讲解nansen research search命令的完整用法：如何仅凭一个代币名称就拿到完整合约地址，如何按实体（如知名钱包/人物）反向检索，以及如何用链、数量、字段等参数精确控制输出。读完本文，你将能在一个命令内完成"名称 → 地址/实体画像"的标准化查询，并为后续代币深度研究、持有人质量分析等下游步骤打好数据基础。

一、Skill 是什么：它解决的问题与适用场景

nansen-general-search是 Nansen 系列 Skill 中负责"名称检索"的入口级组件。它的定位非常明确：当你手上只有一个代币名称（如 "jupiter"、"bonk"）或一个实体名称（如 "Vitalik"），而不知道其完整合约地址时，用它完成查询。这在 Agent 工作流里是第一跳——几乎所有后续的链上分析（价格、持仓、资金流、DEX 交易）都需要先用地址去调用其他接口。

该 Skill 的官方描述（SKILL.md frontmatter）写得十分直白：

Search for tokens or entities by name. Use when you have a token name and need the full address, or want to find an entity.

从仓库结构看，它是 Nansen 七件套（nansen-general-search、nansen-token-research、nansen-wallet-profiler、nansen-smart-money-tracker、nansen-holder-analysis、nansen-prediction-markets、nansen-mpp-payment，见 vendored/README.md）中的"寻址"模块，与其余 Skill 是明确的上下游协作关系，而非孤立命令。

二、环境准备：安装与鉴权

Skill 的运行依赖两条元数据约定（见 SKILL.md frontmatter 的metadata.openclaw段）：

依赖	说明
`NANSEN_API_KEY`	环境变量，Skill 的主鉴权凭据（`primaryEnv`）
`nansen`	可执行文件，来自 npm 包`nansen-cli`（`bins: [nansen]`）

安装方式与仓库内其他 Nansen Skill 完全一致：通过 npm 全局安装 CLI 工具，并在环境中注入 API Key：

npm install -g nansen-cli export NANSEN_API_KEY=your_key_here nansen --help # 验证安装与鉴权

此外，该 Skill 在 OpenClaw/Claude Code 插件体系下声明了allowed-tools: Bash(nansen:*)，即仅授权 Agent 执行nansen前缀的命令，属于最小权限约束；这意味着工作流中所有查询都应通过nansenCLI 完成，而不是绕过它直接拼 HTTP 请求。仓库中的 vendored 副本是通过 skills-lock.json 锁定来源、路径与哈希后从上游固定下来的（参见 vendored/README.md），因此本文所有命令语法均与当前仓库内文档完全一致。

三、核心命令：`nansen research search`的三种典型用法

SKILL.md 给出的命令基座是nansen research search，并配有三个覆盖不同场景的示例，构成了"名称 → 结果"的完整骨架：

# 场景 1：按名称查代币，返回完整地址 nansen research search "jupiter" --type token # 场景 2：按名称查实体，并限制只返回 5 条 nansen research search "Vitalik" --type entity --limit 5 # 场景 3：查代币并同时限定链与输出字段 nansen research search "bonk" --chain solana --fields address,name,symbol,chain

三个示例分别对应三种实战诉求：

代币寻址（最常用）：用户说"查一下 jupiter 这个代币"，Agent 用--type token拿到合约地址，作为后续nansen research token ...系列接口的入参。
实体检索：按人物/机构/标签名查找实体画像，--limit 5控制返回条数，避免结果过载。
多链消歧：同一代币名称在 Solana、Ethereum、Base 等多条链上可能对应不同合约（例如 meme 币名常被多链复制），用--chain直接锁定目标链，再用--fields只取address,name,symbol,chain四个关键列，输出干净利落。

四、Flags 参数详解

SKILL.md 将参数浓缩为一张四行参数表，逐项展开如下：

Flag	用途	取值与行为说明
`--type`	指定检索对象类型	`token`（代币）或`entity`（实体），二选一必填
`--chain`	按链过滤结果	传入链名即可缩小范围，如`--chain solana`；不传则跨链搜索
`--limit`	结果条数上限	默认 25，最大 50；超过 50 的值会被钳制或需要分页策略
`--fields`	选择输出字段	逗号分隔的字段名列表，如`address,name,symbol,chain`，用于裁剪冗余列

实战建议：--fields与--limit搭配使用效果最佳——先--limit 50扩大召回，再用--fields精简单条输出，可以显著降低下游解析成本；而在做实体检索时，--type entity --limit 5的组合足以快速定位目标，无需拉满。

五、关键行为特性：大小写与地址匹配的限制

SKILL.md 末尾明确记录了两条容易被忽略的行为约束，理解它们能避免大量无效调用：

大小写不敏感（Case-insensitive）：搜索 "JUPITER" 与 "jupiter" 结果一致，Agent 无需对用户输入做大小写归一化预处理，直接透传即可。
不支持按地址匹配：search只认名称，传入地址不会得到结果。若手上已有完整地址需要反向查询标签/画像，SKILL.md 明确指出应改用profiler labels子命令。

后一条是本文档与前文提到的 Nansen 七件套的关键衔接点：profiler labels属于nansen-wallet-profilerSkill 的范畴（见 nansen-wallet-profiler/SKILL.md），其标准调用形如：

nansen research profiler labels --address <addr> --chain ethereum

也就是说，"名称 → 地址"走search，"地址 → 标签/身份"走profiler labels，两条命令互为镜像，共同构成名称与地址之间的双向桥梁。顺带一提，profiler侧同样提供nansen research profiler search --query "Vitalik"这类查询入口（见 nansen-wallet-profiler/SKILL.md），说明 Nansen CLI 在 Entity 检索上有多个互补实现路径。

六、与下游 Skill 的串联：一次完整的代币研究工作流

search的价值在于作为流水线第一环。把通用搜索与仓库内其他 Nansen Skill 拼起来，可以形成一条可落地的完整链路：

# 第 1 步：名称 → 地址（本 Skill） nansen research search "bonk" --chain solana --fields address,name,symbol,chain # 得到 address 后存为变量 TOKEN=<查询得到的合约地址> CHAIN=solana # 第 2 步：代币深度数据（nansen-token-research） nansen research token info --token $TOKEN --chain $CHAIN nansen research token holders --token $TOKEN --chain $CHAIN --smart-money # 第 3 步：持有人质量判断（nansen-holder-analysis） nansen research token flow-intelligence --token $TOKEN --chain $CHAIN

其中第 3 步在 nansen-holder-analysis/SKILL.md 中有完整示例，其输出按smart_trader、whale、exchange、fresh_wallets等标签拆分净流入，用于回答"该代币是被优质钱包持有还是散户噪音"这类问题。可见，search虽短小，却是整个 Nansen Agent 分析栈的入口闸门。

七、注意事项与最佳实践小结

综合 SKILL.md 文档与仓库上下文，使用该 Skill 时建议遵循以下约定：

优先指定--chain：跨链同名代币是常态，先锁定链可以避免同名不同约的歧义，也让--fields输出中的chain字段与预期一致。
默认值与上限要心里有数：--limit默认 25、上限 50；需要更多结果时考虑换用更精确的名称或缩小--chain范围，而非盲目加大 limit。
地址反向查询走profiler labels：不要在search上尝试按地址检索，那是profiler的职责范围，二者通过 NANSEN_API_KEY 同一套鉴权即可切换。
鉴权与权限：所有命令都依赖NANSEN_API_KEY环境变量，且 Skill 以Bash(nansen:*)白名单约束 Agent 执行范围，环境中缺少 Key 时命令会直接失败，务必在运行前确认已导出。

总的来说，nansen-general-search是一个小巧但高频的"寻址利器"：它把"名称 → 合约地址/实体"这一链上分析中最常见的起步动作固化为一条稳定的 CLI 命令，配合--type、--chain、--limit、--fields四个参数即可应对绝大多数检索场景，再与仓库内其余六个 Nansen Skill 串成完整的数据管线，是 Agent 落地链上情报检索时性价比最高的第一跳。