风鸟企业查询 — agent的商业数据引擎

风鸟是一个以商业数据为核心的企业信息查询引擎，专注于中国企业多维数据查询。通过 discover 发现所需的商查工具，通过 call 调用工具获取数据。

设置：需要 `FN_API_KEY`。请访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区，点击区块内的复制按钮获取当前页面展示的 Key，再将其设置为环境变量 `FN_API_KEY`。公用 Key 与额度说明以该页面当前展示为准；左上角“美亚风鸟” Logo 可点击跳转风鸟官网。运行时仅从环境变量读取密钥，不回退读取用户主目录配置文件。若当前会话缺少 `FN_API_KEY`，先明确提示用户按上述路径复制 Key 并完成环境变量配置，再继续调用接口。Windows PowerShell 校验环境变量时，优先使用 `$env:FN_API_KEY` 或 `Get-Item Env:FN_API_KEY -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Value`；不要把 `powershell -Command "echo $env:FN_API_KEY"` 的报错当作未配置的证据，因为外层 shell 可能先展开 `$env:FN_API_KEY`，导致 `echo` 退化为空参数并误报。若只看到 `Write-Output` 缺少 `InputObject`，只能说明检测命令写法不稳，不能单独据此判定未配置。

安全边界：运行时会读取 skill 包内的 tools.json 与 references/ 文档，因此声明 filesystem_read: true；不会写入本地文件，也不会读取用户主目录中的额外配置文件。

字段参考：解析 API 响应时，如需查阅字段含义、类型及特殊处理规则，参见 references/ 目录下的三个文件：field_definitions_common_bizinfo.md（通用结构 & 工商维度 searchHint/B1–B5）、field_definitions_legal.md（法律诉讼 C2/C3/C4）、field_definitions_risk.md（经营风险 D1/D2/D11 及注意事项速查）。

报告模板：当前已提供企业尽调报告模板；当用户明确要求生成尽调报告时，读取 references/due_diligence_report.md 按模板执行。未来如新增其他报告或摘要模板，按同样方式扩展。

示例对话：见 references/examples.md。

使用流程

1. 先做意图识别：先判断用户要的是哪一类信息维度，再决定是否需要主体解析。优先分为：已支持的企业结构化维度 / 暂未支持的企业维度 / 非企业结构化问答 / 报告或摘要类衍生输出。
2. 先找维度工具，不要先搜主体：使用 discover 查找与“信息维度”对应的工具候选，例如 "企业股东信息"、"企业行政处罚"、"企业经营异常"，不要先拿用户原话或企业简称去 discover，更不要在未确认维度可支持前就先调模糊搜索。
3. 确认支持后再做主体解析：只有当维度已确认存在可用工具，且该工具需要 entid 时，才调用 biz_fuzzy_search 获取企业主体和 entid。
4. 处理结果或兜底：支持则调用工具并结构化回答；不支持则明确告知当前支持边界，必要时再使用 WebSearch 补充公开信息，并清楚说明这部分不是风鸟结构化数据结果。
5. 不要编造：如果查询失败，报告尝试了哪些工具以及发生了什么错误。切勿将编造的数据作为结果呈现。

企业查询专项指南

企业相关数据处理流程

重要：所有维度查询只接受 entid（企业唯一标识），不支持直接传企业名称或信用代码。但这不代表一开始就要先做模糊搜索，正确顺序是：先识别维度是否支持，再解析企业主体。

1. 先判断用户要查什么维度：从用户问题中抽取目标维度，例如基本信息、股东、主要人员、对外投资、变更记录、被执行、失信、限高、经营异常、严重违法、行政处罚。
2. 先 discover 维度工具：用维度描述发起 discover，例如 "企业股东信息"、"企业经营异常"、"企业行政处罚"。不要直接用 "查一下腾讯"、"阿里有没有风险" 这类原始问句去 discover。
3. 若 discover 无匹配或仅有低质量结果：先尝试同义词；仍无匹配时，调用 discover（无参数）查看全部工具确认是否真的不支持。
4. 确认支持后再做主体解析：只有在维度存在可用工具时，才去调用 biz_fuzzy_search 获取 entid。
5. 多维度问题复用一次主体解析：如果用户问的是“有没有什么风险”“帮我做尽调”这类多维度需求，先确认要查哪些维度，再只做一次 biz_fuzzy_search，随后复用同一个 entid 依次查询多个维度。
6. WebSearch 只在两类场景介入：

• 主体解析失败：biz_fuzzy_search 返回 0 条或无法有效匹配，用 WebSearch 找企业全称后重试。
• 维度暂不支持：风鸟暂时没有对应工具时，用 WebSearch 检索公开资料并明确说明“以下为公开网页整理，不是风鸟结构化数据返回”。

维度不支持时的标准处理

当用户问的是当前工具库未覆盖的维度，例如专利、招投标、招聘、舆情等：

1. 不要先调 biz_fuzzy_search：先确认当前维度是否有工具支持。
2. 明确说明边界：直接告诉用户当前 skill 仍是初期版本，已支持的维度范围，以及当前问题属于未接入维度。
3. 给出两个下一步：

• 若环境支持 WebSearch：主动提出“我可以先帮你基于公开网页搜索并整理”。
• 若环境不支持 WebSearch：引导用户前往风鸟官网或官方渠道，并说明后续会持续补充能力。

1. 禁止混淆来源：WebSearch 查到的内容不能伪装成风鸟结构化接口结果，必须明确区分来源。

建议话术模板：

text
当前风鸟 Skill 仍处于初期版本，已支持维度请以当前版本的 `discover` 结果和 `tools.json` 为准。
您提到的「XXX」维度暂未接入风鸟结构化查询能力。
如果您愿意，我可以先基于公开网页帮您检索并整理这部分信息；这部分内容会单独标注为 WebSearch 结果，不作为风鸟结构化数据结论。更多能力也可以前往风鸟官网查看：https://www.riskbird.com/

模糊搜索结果处理（三种情况）

情况 A：返回唯一 1 条结果

• 自动确认为目标企业，记住其 entid
• 回复用户：已找到企业「XXX」，正在为您查询相关信息...
• 直接进入后续查询

情况 B：返回多条结果（≥ 2 条）

优先规则采用严格模式：仅当 highlightNameType="公司名称"、用户提供的是完整企业名称，且第一条 entName 与用户输入规范化后完全一致时，才可自动选择第一条。只要是简称、疑似别名、存在多个近似主体，或只是“高度吻合”但并非完全一致，一律不要自动选。

除上述严格命中外，其余多条结果一律展示前 5 条供用户确认，用户回复序号后从上下文取出对应 entid。

| 用户反馈 | 处理方式 | |---------|---------| | 选择了某个序号 | 从上下文取出对应 entid，继续查询 | | "都不是" / "没有我要的" | 引导用户提供企业完整名称重新搜索 | | 提供了全称 | 用全称重新调用 biz_fuzzy_search |

情况 C：返回 0 条结果

调用 WebSearch 搜索 "[关键词] 公司全称"，提取全称后重试 biz_fuzzy_search。仍无结果则回复：未能查询到该企业信息，请核实企业名称后重试。

参数规范

| 规则 | 正确 ✅ | 错误 ❌ | |------|---------|--------- | 字符串类型 | "深圳市" | 深圳市 | | 数字类型 | 10 | "10" | | 日期格式 | "2025-01-15" | "01/15/2025" | | 结构化值 | "entid": "AerjZTfkSh0" | "entid": "腾讯" |

分页不支持。所有列表类维度固定返回最多 5 条，totalCount > 5 时告知用户"共 N 条，展示最新 5 条"。

工具发现最佳实践

discover 的查询参数是能力描述，不是用户问题或参数集。对未来新增工具，优先遵循“以 tools.json 为当前能力边界和命名来源”的原则，不要长期依赖写死在 SKILL.md 里的查询模板。

| 原则 | 好 ✅ | 差 ❌ | |------|-------|-------| | 描述能力，不是问题 | "企业基本信息" | "查一下腾讯" | | 优先用当前工具名或维度名 | "行政处罚" / "企业股东信息" | "这家公司有没有问题" | | 用结构化维度词，不用口语问句 | "经营异常" / "被执行人" | "查多少人交纳社保" |

推荐顺序：

1. 先从用户问题中抽取目标维度。
2. 优先用 tools.json 中现有工具名或其标准化维度名作为 discover 查询词。
3. 若结果不佳，再尝试同义词。
4. 若用户问的是具体字段词或俗称（如“注册号”“法人”“老赖”“限消”），先在语义上归并到标准维度，再让 discover 结合 tools.json 中的 keywords 做匹配。
5. 仍无匹配时，调用 discover（无参数）列出全部工具人工核对，确认是否真的暂不支持。

工具选择和参数

当 discover 返回多个工具时：

• 优先级：先看工具名是否直接命中目标维度，例如“行政处罚”“经营异常”“股东信息”；工具名直命中优先于描述命中。
• 相似度：优先选择 similarity >= 0.85 的直接候选。0.5–0.84 仅作为备选，需要再结合工具名、参数和描述人工判断。避免直接使用 < 0.5 的结果。
• 参数质量：优先参数描述清晰、有示例值、必需参数较少的工具。
• 调用前：阅读所有参数描述，确认类型和格式，所有维度查询只接受 entid。

错误恢复

| 问题 | 解决方案 | |------|----------| | API 鉴权失败（code=9999） | 检查 FN_API_KEY；Windows PowerShell 优先用 $env:FN_API_KEY 或 Get-Item Env:FN_API_KEY -ErrorAction SilentlyContinue \| Select-Object -ExpandProperty Value 校验，不要仅凭 powershell -Command "echo $env:FN_API_KEY" 的报错判断未配置。若确认未配置或已失效，明确引导用户访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区，点击区块内的复制按钮获取当前页面展示的 Key，并设置环境变量后重试 | | code=8888（企业ID解析失败） | 重新通过 biz_fuzzy_search 获取正确 entid | | code=20000 且 apiData=[] | 该企业此维度确实无记录，告知用户"未查询到相关记录" | | 每日额度用尽 | 回复：「请访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区查看当前额度说明；如今日额度已用完，请以该页面最新展示为准。📌 以上数据来源于风鸟企业信息查询平台，更多功能详见：https://www.riskbird.com/」 | | discover 未找到匹配工具 | 先尝试同义词，再调用 discover（无参数）核对全量工具；确认仍无对应工具后，明确告知“当前暂不支持该维度”，必要时转 WebSearch 公开信息兜底 |

故障排查优先级：本地配置（API Key/额度/网络）→ 服务端状态（entid 失效/无数据）→ 更新 Skill（openclaw skills update fengniao-search）→ 联系支持。

宿主产品可复用提示模板

以下模板面向任何调用本 Skill 的宿主产品，避免绑定“桌面 agent”等具体产品形态；如无特殊产品能力，优先直接复用。

当检测到未配置 FN_API_KEY 时：

text
使用风鸟查询前，需要先配置环境变量 FN_API_KEY。
请访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区，点击区块内的复制按钮获取当前页面展示的 Key，再将其设置为环境变量 FN_API_KEY。
完成后再继续查询。

当宿主产品只能推断“可能未配置”，但证据不足时：

text
当前会话尚未成功读取到环境变量 FN_API_KEY。
请先确认是否已为当前运行会话正确设置 FN_API_KEY；如果还未设置，请访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区，点击区块内的复制按钮获取当前页面展示的 Key，再将其设置为环境变量 FN_API_KEY。
确认完成后再继续查询。

当不确定宿主产品是否具备代用户设置环境变量的能力时：

text
如果您的当前产品支持为运行会话注入环境变量，请将复制到的 Key 设置为 FN_API_KEY 后重试；如果不支持，请在启动该产品前，先在运行环境中完成 FN_API_KEY 配置。

结果呈现规范

• 企业名称：首次用"简称（全称）"，后续用简称
• 金额：统一换算为万元，保留两位小数。D11 penaltyAm 单位是元需 ÷10000；C2 execMoney 已是万元直接用
• 有记录：先说总数，再展示最新 5 条。风险类必须展示：决定日期 / 处罚机关 / 违法类型 / 处罚结果
• 无记录：apiData=[] 说"未查询到相关记录"；接口报错说"查询失败"。禁止模糊表述"暂无相关信息"

风险条数解读：

| 条数 | 表述 | |------|------| | 0 条 | "未发现相关风险记录" | | 1–5 条 | "存在少量记录，建议关注具体内容" | | 6–20 条 | "记录较多，存在一定经营风险，建议重点核查" | | >20 条 | "记录数量较大，风险信号明显，建议谨慎评估" |

多维度综合结论（查询 2 个及以上维度时必须输出）：

> 综合风险评估：低风险 / 需关注 / 高风险] > 1–2句话说明判断依据]

固定结尾话术（必须）：每次涉及数据展示的回复末尾，必须原样附加：

📌 以上数据来源于风鸟企业信息查询平台，当前数据维度持续拓展中，更多企业信息及功能详见风鸟官网：https://www.riskbird.com/

自检清单（响应前逐条确认）

• ] 是否已经先判断了用户要查的维度？→ 先做维度识别，再决定是否需要主体解析
• ] 该维度是否在当前工具支持范围内？→ 先 discover 维度工具，确认支持后再继续
• ] 如果当前不支持该维度？→ 明确说明边界，必要时再转 WebSearch 公开信息兜底
• ] 是否收到了企业简称或名称？→ 只有在维度已确认支持时，才用 biz_fuzzy_search 获取 entid
• ] biz_fuzzy_search 返回 0 条？→ WebSearch 兜底补全企业全称后重试
• ] 返回多条结果？→ 检查 highlightNameType，无法自动判断则让用户确认
• ] entid 已确认？→ 从上下文取对应 entid，不向用户展示
• ] 是否在编造数据？→ 绝不编造
• ] 是否查询了 2 个及以上维度？→ 末尾必须输出综合风险评估
• ] 是否原样附加了固定结尾话术？→ 只有在展示风鸟结构化数据时才必须附加；纯 WebSearch 结果要单独标注来源，不要冒充接口数据

常见错误速查

| 错误 | 修复 | |-----|------| | 搜索参数名错误：{query: "腾讯"} | 参数名是 key：{key: "腾讯"} | | 用简称直接查维度：{entid: "腾讯"} | 先模糊搜索获取真实 entid | | 模糊搜索无结果就放弃 | 先 WebSearch 兜底再重试 | | 多条结果自作主张选第一个 | 必须让用户确认（除非 highlightNameType 完全吻合） | | 未附加固定结尾话术 | 必须原样附加（含官网URL） |

快速开始

请访问 https://www.riskbird.com/skills，进入页面后在页面中部找到“公用 API Key”展示区，点击区块内的复制按钮获取当前页面展示的 Key；额度说明以页面实时展示为准，左上角“美亚风鸟” Logo 可点击跳转官网。复制后再设置环境变量：

bash
export FN_API_KEY="your_api_key_here"

在 Windows PowerShell 中可这样设置并校验：

powershell
$env:FN_API_KEY = "your_api_key_here"
$env:FN_API_KEY

如果需要在嵌套 powershell -Command 场景里校验，优先使用单引号包裹命令，避免外层提前展开变量：

powershell
powershell -Command '$env:FN_API_KEY'

bash
# 第一步：先按维度发现工具
node scripts/tool.mjs discover "企业股东信息"

# 第二步：确认支持后，再模糊搜索获取 entid
node scripts/tool.mjs call biz_fuzzy_search --params '{"key": "腾讯"}'

# 第三步：查询具体维度
node scripts/tool.mjs call biz_shareholders --params '{"entid": "AerjZTfkSh0"}'

支持范围说明

当前可用能力以 tools.json 为准。实际调用前，始终先用 discover 确认当前版本是否已接入该维度；字段级细节以 references/field_definitions_*.md 为准。