fengniao-search

---
name: fengniao-search
description: >-
  风鸟企业数据查询引擎，用于查询中国企业的结构化工商、关系与风险信息，并在需要时生成报告、摘要等衍生输出。
  当用户想查询企业基本信息（如法定代表人、注册号、统一社会信用代码、成立日期、注册地址、经营范围及基础联系方式）、股东结构、主要人员、对外投资、工商变更，或查询被执行人、失信被执行人、限制高消费、经营异常、严重违法、行政处罚等风险信息时使用。
  也适用于合作方背景核查、供应商管理、客户风险识别等场景。支持输入企业简称并先做模糊搜索获取企业主体。
env:
  - FN_API_KEY
security:
  child_process: false
  eval: false
  filesystem_write: false
  filesystem_read: true
auto_invoke: true
examples:
  - "查询小米的工商基本信息"
  - "查一下腾讯的股东结构"
  - "恒大有没有经营异常或行政处罚"
  - "乐视网有没有司法风险和失信记录"
  - "帮我看看阿里最近有没有新的异动"
  - "帮我生成一份比亚迪的企业尽调报告"
---

# 风鸟企业查询 — 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：引导用户前往风鸟官网或官方渠道，并说明后续会持续补充能力。
4. **禁止混淆来源**：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` 为准。