为AI Agent设计的英国公司数据CLI工具：companies-house-cli深度解析

马迪姐

301人浏览 · 2026-05-06 12:01:08

马迪姐 · 2026-05-06 12:01:08 发布

1. 项目概述：一个为AI Agent设计的英国公司数据CLI工具

如果你在英国工作，或者你的业务与英国公司有交集，那么“Companies House”（英国公司注册处）这个名字你一定不陌生。它是英国所有注册公司的官方数据库，从大名鼎鼎的汇丰银行到街角新开的咖啡馆，只要是在英国注册的有限公司，其核心信息——公司编号、注册地址、董事名单、财务报告、实益拥有人（PSC）等——都存储在这里。对于从事金融、法律、咨询、市场研究甚至商业拓展的人来说，快速、准确地查询这些信息是日常工作的刚需。

传统的查询方式是通过Companies House的官方网站，手动输入公司编号或名称进行搜索。这种方式对于偶尔查询一两家公司尚可，但一旦需要批量处理、数据整合，或者将公司信息查询能力嵌入到自动化工作流中，就显得力不从心了。你需要一个更高效、更程序化的工具。

这就是 companies-house-cli 诞生的背景。它不是一个简单的网页爬虫，而是一个基于官方REST API构建的、功能完整的命令行工具。它的设计初衷非常明确： 为AI智能体（AI Agent）提供稳定、结构化的数据接口 。想象一下，你的AI助手需要分析一家潜在合作伙伴的背景，或者自动生成一份公司的尽职调查报告，它可以直接调用这个CLI工具，获取标准化的JSON数据，而无需你手动打开浏览器、复制粘贴。当然，这个工具对“人类用户”同样友好，它提供了色彩丰富、排版清晰的终端输出，让命令行查询变得直观易懂。

项目作者 @shan8851 将其构建为一个Node.js的全局命令行工具，使用TypeScript编写，确保了代码的健壮性和类型安全。它几乎封装了Companies House公开API的所有核心端点，让你在终端里就能完成复杂的公司信息检索。接下来，我将带你深入拆解这个工具，从安装配置到核心命令，再到如何将其无缝集成到你的自动化脚本或AI Agent中，分享我在使用和类似工具开发中的实战经验。

2. 核心设计与架构思路解析

2.1 为什么选择CLI，而非库或Web应用？

在决定构建一个数据查询工具时，开发者通常面临几个选择：开发一个Web应用、发布一个软件库（Library）、或者创建一个命令行工具。 companies-house-cli 坚定地选择了CLI路径，这背后有深刻的考量。

首先， CLI具有极致的轻量化和无头（Headless）特性 。它不需要图形界面，不依赖浏览器，可以在服务器、持续集成（CI）环境、乃至Docker容器中无缝运行。这对于自动化任务和AI Agent集成来说是天然的优势。AI Agent本质上是一个程序，它更擅长调用命令行指令并解析其输出，而非模拟人类去操作图形界面。

其次， CLI遵循Unix哲学“只做一件事，并做好” 。这个工具的核心职责就是查询Companies House数据。它通过清晰的子命令（ search , info , officers 等）暴露功能，每个命令的输出（无论是给人看的文本还是给机器读的JSON）都高度专注。这种单一职责的设计，使得它可以很容易地被组合到更复杂的Shell脚本或工作流中。例如，你可以用 ch search “Tech Startup” | head -5 | awk ‘{print $1}’ | xargs -I {} ch info {} 这样的管道命令，批量获取前5家科技初创公司的详细信息。

第三， 面向AI Agent的标准化输出是核心创新点 。早期的CLI工具可能只考虑人类可读的输出。而 companies-house-cli 从设计之初就考虑了“双模输出”：当检测到输出是终端（TTY）时，它提供美观的、带ANSI颜色的文本；当输出被重定向到管道或文件（非TTY）时，它默认输出结构化的JSON。这个设计非常巧妙，它省去了用户在调用AI Agent时频繁添加 --json 参数的麻烦，让AI Agent能以一种最自然的方式（管道）获取机器可读的数据。

2.2 技术栈选型：TypeScript与Node.js的权衡

项目采用TypeScript + Node.js的技术栈，这是一个经过市场长期检验的、用于构建可靠CLI工具的黄金组合。

Node.js的优势 ：其最大的优势在于包管理（npm/yarn/pnpm）生态和跨平台能力。一个 npm install -g 命令就能完成全球安装，在Windows、macOS和Linux上行为一致。对于需要与网络API大量交互的CLI工具，Node.js内置的异步I/O和非阻塞特性处理起来非常高效。
TypeScript的必要性 ：对于CLI工具，尤其是需要处理复杂、嵌套的API响应数据时，类型安全至关重要。TypeScript能在编译阶段就捕获许多潜在的错误，比如访问不存在的字段、类型不匹配等。这对于维护一个稳定的、面向机器输出的数据契约（JSON Schema）是不可或缺的。你可以看到项目中的 pnpm typecheck 命令，就是利用TypeScript来保证代码质量。
构建与打包 ：项目使用 pnpm 作为包管理器，并配有 build 脚本。这意味着源码很可能通过TSC或ESBuild等工具被编译/打包成纯JavaScript，最终发布的npm包中是可直接运行的JS代码，用户无需安装TypeScript环境即可使用。这是一种非常专业的做法，平衡了开发体验和用户体验。

2.3 面向AI Agent的输出契约设计

这是本项目最值得深入学习的部分。一个随意的JSON输出和一个为AI精心设计的输出契约，有着天壤之别。 companies-house-cli 的输出结构堪称范本：

{
  "ok": true,
  "schemaVersion": "1",
  "command": "search",
  "requestedAt": "2026-03-25T17:00:00.000Z",
  "data": { ... },
  "error": { ... }
}

这个设计遵循了几个关键原则：

明确的成功/失败标识 ：顶层的 ok 布尔字段让调用方（尤其是AI）无需解析HTTP状态码或猜测字符串内容，一眼就能判断请求是否成功。
版本化契约 ： schemaVersion 字段为未来的格式变更留出了空间。如果未来API有重大更新，可以通过升级版本号来保持向后兼容，避免破坏现有集成。
请求上下文自包含 ： command 和 requestedAt 字段记录了“这是什么请求”和“何时发生的”，对于日志记录、审计和调试非常有价值。
统一的数据与错误容器 ：成功时，数据放在 data 对象中；失败时，错误详情放在 error 对象中。两者互斥，结构清晰。错误对象中还包含了 code （错误码）、 message （人类可读信息）和 retryable （是否可重试）字段，这对实现自动重试逻辑的AI Agent极其友好。
标准化的分页信息 ：对于列表类命令，分页数据（ startIndex , itemsPerPage , totalResults 等）被统一放在 data.pagination 下。AI Agent可以据此判断是否已获取全部数据，并决定是否发起下一次请求（使用 --all 参数或调整 --start-index ）。

实操心得：设计机器接口的黄金法则 在设计给AI或程序调用的接口时，一定要记住： 机器不擅长“猜” 。所有关键信息都必须显式地、结构化地提供。像 ok 这种字段就是“显式”的典范。同时，要为可能的失败和扩展做好规划， schemaVersion 和结构化的 error 对象就是“规划”的体现。这套输出契约，完全可以作为你设计其他类似CLI或微服务API的参考模板。

3. 环境准备与核心配置详解

3.1 安装方式的选择与最佳实践

项目提供了两种安装方式：通过npm全局安装，以及从源码构建安装。对于绝大多数用户，我强烈推荐第一种。

npm install -g @shan8851/companies-house-cli

这条命令会将 ch 这个可执行文件安装到你的系统全局路径下（如 /usr/local/bin ），之后你可以在任何终端窗口中使用它。这是最干净、最便捷的方式。

那么，什么时候需要从源码安装呢？主要有两种情况：

你想为项目贡献代码 ：你需要克隆仓库，运行 pnpm install 安装依赖，然后进行开发。
你需要一个尚未发布到npm的特定版本或分支 ：例如，你想测试一个刚修复了某个bug的版本。

从源码安装的步骤也很有代表性：

git clone https://github.com/shan8851/companies-house-cli.git
cd companies-house-cli
pnpm install && pnpm build  # 安装依赖并构建
pnpm link --global          # 将当前目录链接到全局环境，相当于“安装”

pnpm link --global 是一个非常有用的开发命令，它让你在本地修改代码后，能立即在全局生效，无需反复执行 npm install -g 。

3.2 API密钥的获取与安全配置

使用任何Companies House的API工具，第一步都是获取API密钥。这个过程是完全免费的，确实如文档所说，大约只需要30秒。

访问注册页面 ：打开 developer.company-information.service.gov.uk 。你需要一个邮箱进行注册。
创建应用 ：登录后，点击“Create an application”。给你的应用起个名字，比如 “My Due Diligence CLI”。
选择密钥类型 ：在“Which type of key do you need?”这一步， 务必选择“REST API key” 。这是用于程序化访问的标准密钥。另一个选项“Streaming API key”用于实时数据流，普通查询用不到。
获取密钥 ：创建成功后，你会在应用详情页看到你的API密钥（一串由数字和字母组成的字符串）。请立即复制并妥善保存。

安全配置是重中之重 。永远不要将API密钥硬编码在脚本中或提交到版本控制系统（如Git）。推荐以下两种方式：

环境变量（推荐用于临时会话或脚本） ：
```
export COMPANIES_HOUSE_API_KEY=your_actual_key_here
# 然后运行 ch 命令
ch search "Tesla"
```
这种方式设置的变量只在当前终端会话有效。关闭终端后即失效。
项目级 .env 文件（推荐用于长期项目） ：在你的项目根目录下创建一个名为 .env 的文件，内容如下：
```
COMPANIES_HOUSE_API_KEY=your_actual_key_here
```
然后，你需要确保你的Shell或运行环境能加载这个文件。对于Node.js项目，通常使用 dotenv 包。对于单纯的CLI使用，你可以使用 source .env 命令（在Bash/Zsh中）来加载变量。 切记将 .env 添加到你的 .gitignore 文件中，防止密钥泄露。

注意事项：API调用限制 Companies House的免费API密钥有调用频率限制。虽然对于个人和小规模使用通常足够，但如果你计划进行大批量查询（例如扫描某个行业的所有公司），务必先查阅官方文档了解具体的限流策略，并考虑在代码中实现适当的延迟（例如使用 setTimeout ），避免请求被阻断。

3.3 验证安装与配置

安装并设置好API密钥后，运行一个简单的命令来验证一切是否正常：

ch info 09215862

如果配置正确，你应该能看到Revolut Ltd公司的基本信息以整洁的表格形式输出在终端。如果看到“Authentication failed”或类似的错误，请检查你的 COMPANIES_HOUSE_API_KEY 环境变量是否已正确设置（可通过 echo $COMPANIES_HOUSE_API_KEY 查看），以及密钥本身是否有误。

4. 核心命令全解析与实战应用

companies-house-cli 提供了8个核心子命令，覆盖了公司信息查询的绝大部分场景。下面我们逐一拆解，并附上实战用例和技巧。

4.1 基础查询： `ch search` 与 `ch info`

这是两个最常用、最基础的命令。

ch search <query> 用于按公司名称进行模糊搜索。它非常灵活，不要求输入完整的、精确的公司名称。

ch search "Monzo"

这条命令会返回所有公司名称中包含“Monzo”字样的公司列表，包括“Monzo Bank Limited”、“Monzo Support Limited”等。输出默认以表格形式展示公司编号、名称、状态和注册地址所在地。

高级技巧 ：

使用引号 ：如果查询词包含空格，务必用引号包裹，如 ch search “British Airways” 。
分页控制 ：搜索结果可能很多。使用 --items-per-page 和 --start-index 进行分页查看。例如， ch search “London” --items-per-page 5 --start-index 10 会跳过前10条，显示第11到第15条结果。
获取全部 ：添加 --all 参数会让CLI自动遍历所有分页，获取全部搜索结果。 请谨慎使用 ，特别是对于“London”这种宽泛关键词，可能会返回海量数据，耗尽API调用限额。

ch info <company_number> 用于获取指定公司的详细档案信息。公司编号是Companies House分配给每家公司的唯一标识，通常是8位数字（有时以0开头）。

ch info 09215862

输出信息非常丰富，包括：

公司状态 ：Active（活跃）、Dissolved（已解散）、Liquidation（清算中）等。这是判断公司是否正常运营的第一指标。
注册地址 ：公司的法定通信地址。
公司类型 ：如“Private limited Company”（私人有限公司）。
成立日期 ：公司注册的日期。
SIC代码 ：标准产业分类代码，揭示了公司的主要业务活动。例如，62012代表“商业及 domestic software development”（商业和家用软件开发）。

实操心得：公司编号的智能补零 工具的一个贴心设计是自动补零。英国公司编号通常是8位，但人们常常会省略前面的零。例如，Revolut的完整编号是 09215862 ，但输入 9215862 同样有效。CLI内部会自动处理这个转换，这避免了因格式问题导致的查询失败，提升了用户体验。

4.2 深度尽职调查： `ch officers` , `ch psc` , `ch filings`

这三个命令构成了商业尽职调查的核心。

ch officers <company_number> 查询公司的现任及历史官员信息，主要是董事（Director）和秘书（Secretary）。这是了解公司实际控制人和管理团队的关键。

ch officers 09215862

输出会列出每位官员的姓名、职务、任命日期、离职日期（如适用）以及国籍/居住地（如果公开）。通过分析董事的任职网络，可以挖掘出复杂的商业关联。

ch psc <company_number> 查询“有重大控制权的人士”（Persons with Significant Control）。这是英国为了增强公司所有权透明度而引入的制度，旨在揭示公司的实益拥有人（即最终控制人或“老板”）。

ch psc 09215862

PSC信息可能包括个人、其他法律实体（如另一家公司）或政府机构。对于个人，会显示姓名、出生年份、国籍、持股比例和权利性质（如“超过25%的股份”）。这是反洗钱和了解你的客户（KYC）流程中至关重要的环节。

ch filings <company_number> 查询公司的申报历史。英国公司有法定义务定期向Companies House提交文件，如年度财务报告（Accounts）、董事变更通知（Appointments）、抵押登记（Charges）等。

ch filings 09215862 --type accounts

使用 --type 过滤器可以快速定位特定类型的文件，最常用的就是 accounts （财务报告）。添加 --include-links 参数会在输出中显示该文件的PDF下载链接，你可以直接点击或使用 curl 、 wget 下载原始文件进行详细分析。

4.3 高级搜索与关联查询： `ch search-person` 与 `ch charges` , `ch insolvency`

ch search-person <name> 这是一个非常强大的功能，它不是在单个公司里找人，而是在 全英国所有公司 的官员记录中搜索特定姓名的人。

ch search-person “Nik Storonsky”

这条命令会返回名为“Nik Storonsky”的个人在所有英国公司中担任的职务列表。这对于调查某个企业家或投资人的商业版图、发现潜在的关联交易或利益冲突极具价值。输出结果会进行“任命丰富化”，即不仅列出公司，还会列出其在该公司的具体职务。

ch charges <company_number> 查询公司在Companies House登记的抵押和担保信息。当公司以资产（如房产、知识产权）作为抵押向银行借款时，这些“押记”（Charge）需要依法登记。

ch charges 09215862

查看公司的抵押情况，可以了解其资产负担和融资活动，是财务分析的一部分。

ch insolvency <company_number> 查询公司的破产清算历史。如果公司曾进入破产程序（清算、管理或破产），相关记录会在这里显示。

ch insolvency [一个曾破产的公司编号]

这对于评估与历史上有过财务困境的公司进行交易的风险非常重要。

4.4 输出格式控制与AI集成模式

这是本工具区别于普通CLI的精髓所在。它提供了三种输出模式：

智能默认模式 ：当标准输出（stdout）连接到终端（TTY）时，输出美观的、带颜色的文本表格，方便人类阅读。
显式文本模式 ：使用 --text 参数强制输出文本格式。
显式JSON模式 ：使用 --json 参数强制输出JSON格式。

最关键的是第四种：管道自动JSON模式。 当CLI检测到它的输出被管道（ | ）重定向时， 它会自动切换到JSON输出 。这意味着以下两种写法是等价的，并且是AI Agent集成的推荐方式：

# 写法一：显式指定 --json
ch search “Revolut” --json | jq .
# 写法二：利用管道自动切换（更简洁）
ch search “Revolut” | jq .

jq 是一个强大的命令行JSON处理器，用于美化和解析JSON。对于AI Agent来说，它不需要 jq ，它只需要解析 ch 命令通过管道传来的原始JSON数据即可。

这种设计使得AI Agent的调用代码极其简洁：

# 伪代码示例：AI Agent调用CLI获取公司信息
import subprocess
import json

def get_company_info(company_number):
    result = subprocess.run(
        [‘ch’, ‘info’, company_number],
        capture_output=True,
        text=True
    )
    # 因为输出被capture_output捕获（相当于管道），所以得到的是JSON
    data = json.loads(result.stdout)
    if data[‘ok’]:
        return data[‘data’][‘company’]
    else:
        raise Exception(f“Query failed: {data[‘error’][‘message’]}”)

5. 与AI Agent及自动化工作流的深度集成

5.1 集成模式一：作为OpenClaw或Claude Desktop MCP工具

项目文档特别提到了与 OpenClaw 和 Claude Desktop MCP（Model Context Protocol）的兼容性。MCP是Anthropic为Claude桌面应用推出的一种协议，允许Claude安全地调用外部工具和资源。

在这种模式下， companies-house-cli 可以被配置为一个MCP服务器工具。当用户在Claude聊天窗口中提出诸如“查一下Revolut公司的董事是谁”这样的问题时，Claude不会去“想象”答案，而是会自动在后台调用配置好的 ch officers 09215862 命令，获取真实的、结构化的数据，并基于此生成回答。这极大地增强了AI回答的准确性和实时性。

集成步骤通常涉及编写一个简单的MCP服务器配置，将 ch 命令包装起来，并定义其输入（公司编号）和输出（JSON Schema）。由于 ch 命令已经有了完美的机器接口，这个包装过程会非常直接。

5.2 集成模式二：嵌入自动化脚本与数据管道

对于非对话式的自动化任务， companies-house-cli 可以成为数据管道中的一个强大组件。

场景一：批量公司监控报告 假设你需要每周监控一批竞争对手公司的董事变动和最新财务报告提交情况。

#!/bin/bash
# monitor_companies.sh
COMPANY_LIST=(“09215862” “12345678” “09876543”) # 公司编号数组

echo “Weekly Company Monitoring Report”
echo “===============================”
echo “”

for COMPANY in “${COMPANY_LIST[@]}”
do
  echo “### Company: $COMPANY ###”
  # 获取公司基本信息
  COMPANY_NAME=$(ch info $COMPANY --json | jq -r ‘.data.company.companyName’)
  echo “Name: $COMPANY_NAME”
  # 检查最近30天内是否有新的董事任命
  RECENT_OFFICERS=$(ch officers $COMPANY --json | jq ‘.data.officers[] | select(.appointed_on >= “2024-04-01”)’)
  if [ -n “$RECENT_OFFICERS” ]; then
    echo “⚠️ Recent director changes found!”
  fi
  # 检查是否提交了最新年度报告
  LATEST_ACCOUNTS_DATE=$(ch filings $COMPANY --type accounts --json | jq -r ‘.data.filings[0].date’)
  echo “Latest accounts filed on: $LATEST_ACCOUNTS_DATE”
  echo “”
done

这个脚本可以放入Cron作业，定期运行并通过邮件发送报告。

场景二：投资组合公司数据抓取 如果你管理着一个英国公司的投资组合，需要定期将它们的核心信息同步到自己的数据库或CRM中。

# sync_portfolio.py
import subprocess
import json
import sqlite3

portfolio_numbers = [‘09215862’, ‘08804411’]

for number in portfolio_numbers:
    # 获取公司信息
    info_result = subprocess.run([‘ch’, ‘info’, number], capture_output=True, text=True)
    info_data = json.loads(info_result.stdout)
    
    # 获取董事信息
    officers_result = subprocess.run([‘ch’, ‘officers’, number], capture_output=True, text=True)
    officers_data = json.loads(officers_result.stdout)
    
    # 这里可以将 info_data 和 officers_data 解析后存入数据库
    # ... database insertion logic ...
    
    print(f“Synced data for company {number}”)

5.3 错误处理与稳健性设计

在与AI Agent或自动化脚本集成时，健壮的错误处理至关重要。 companies-house-cli 通过以下方式提供了支持：

结构化的错误输出 ：所有错误都以相同的JSON信封格式输出到stdout，并包含 ok: false 和详细的 error 对象。这使得调用程序可以一致地处理错误。
明确的退出码 ：CLI使用不同的退出码来区分错误类型，这对于Shell脚本尤其有用。
- 0 : 成功。
- 2 : 输入错误（如无效的公司编号）或资源未找到。这通常是客户端错误，重试无意义。
- 3 : 认证失败、上游API错误或速率限制。对于速率限制错误（ retryable: true ），程序可以实现指数退避重试。
- 4 : CLI内部意外错误。这可能是bug，需要开发者关注。

重试逻辑建议 ：在你的集成代码中，对于退出码为3且 error.retryable 为 true 的错误，应该实现重试逻辑。一个简单的策略是“指数退避”：

import time
def call_ch_with_retry(command_args, max_retries=3):
    for attempt in range(max_retries):
        result = subprocess.run([‘ch’] + command_args, capture_output=True, text=True)
        data = json.loads(result.stdout)
        if data[‘ok’]:
            return data[‘data’]
        elif data[‘error’][‘retryable’]:
            wait_time = (2 ** attempt) + random.uniform(0, 1) # 指数退避加随机抖动
            time.sleep(wait_time)
            continue
        else:
            raise Exception(f“Non-retryable error: {data[‘error’][‘message’]}”)
    raise Exception(“Max retries exceeded”)

6. 开发指南、贡献与进阶技巧

6.1 本地开发与测试

如果你想深入研究代码、修复bug或添加新功能，可以搭建本地开发环境。

克隆与安装 ：

git clone https://github.com/shan8851/companies-house-cli.git
cd companies-house-cli
pnpm install # 使用pnpm安装所有依赖

链接到全局 ：运行 pnpm link --global 。这会在你的全局node_modules中创建一个指向本地项目目录的符号链接。之后，你在任何地方运行的 ch 命令都将使用你本地正在开发的版本。
运行测试 ：项目使用Vitest作为测试框架。运行 pnpm test 执行单元测试。良好的测试覆盖率是保证CLI稳定性的关键，尤其是在输出契约对AI Agent如此重要的情况下。
代码质量检查 ：运行 pnpm check 会依次执行类型检查（TypeScript）、代码风格检查（ESLint）和测试，这是提交代码前的标准流程。

6.2 理解项目架构与扩展思路

浏览项目源码，你会发现其结构清晰，遵循了现代Node.js CLI的最佳实践：

src/commands/ ：每个子命令（search, info, officers等）通常对应一个独立的文件，负责参数解析、API调用和输出格式化。
src/api/ ：封装与Companies House REST API交互的底层HTTP客户端，处理认证、请求和响应解析。
src/output/ ：包含 jsonFormatter.ts 和 textFormatter.ts ，分别负责生成给机器和给人看的输出。这是“双模输出”功能的核心。
bin/ ：包含CLI的入口点脚本。

如果你想为其添加一个新命令（例如，查询公司的“Confirmation Statement”确认声明），通常需要：

在 src/commands/ 下创建一个新文件，例如 confirmation-statement.ts 。
实现命令逻辑：解析参数、调用对应的API端点、格式化输出。
在命令注册处添加新命令。
编写相应的单元测试和集成测试。

6.3 性能优化与高级使用技巧

并发请求与速率限制 ：虽然CLI本身是顺序执行命令，但在你自己的脚本中批量处理多个公司时，需要注意Companies House API的速率限制。避免使用简单的 for 循环一次性发起大量请求。可以考虑使用异步队列（如 p-queue 库）来控制并发数，或在请求间添加人工延迟。
缓存策略 ：公司基本信息（如名称、地址）不常变化，但申报记录（Filings）会更新。对于频繁查询的数据，可以考虑在本地实现一个简单的缓存层（例如使用SQLite或文件系统），并设置合理的过期时间（TTL），以减少API调用并提升响应速度。
结合其他数据源 ： companies-house-cli 提供了官方的、权威的基础数据。你可以将其与其他数据源结合，产生更大价值。例如，将查询到的公司编号与OpenCorporates的全球公司数据库进行关联，或者将董事姓名与LinkedIn等职业社交网络的信息进行交叉验证（需注意合规性）。

6.4 常见问题与排查实录

在实际使用和集成过程中，你可能会遇到以下问题：

问题1：命令执行报错 Error: Cannot find module ‘…’

原因：通常是由于全局安装的CLI与本地node_modules的依赖版本冲突，或者从源码安装后没有成功构建。
解决：
1. 尝试重新安装： npm uninstall -g @shan8851/companies-house-cli && npm install -g @shan8851/companies-house-cli 。
2. 如果是从源码运行，确保执行了 pnpm build 。
3. 检查Node.js版本是否符合要求（>=22）。

问题2：API请求返回 401 Unauthorized 或 Invalid authentication credentials

原因：API密钥未设置或设置不正确。
排查：
1. 运行 echo $COMPANIES_HOUSE_API_KEY 确认环境变量已设置且值正确。
2. 确保密钥是“REST API key”，而不是“Streaming API key”。
3. 尝试在命令行中临时设置密钥并运行命令： COMPANIES_HOUSE_API_KEY=your_key ch info 09215862 。

问题3：使用 --all 参数获取大量数据时进程被中断或速度很慢

原因： --all 参数会循环请求直到获取所有数据。如果结果集很大（例如搜索“Ltd”），可能会触发API速率限制，或者因网络问题导致中途失败。
解决：
1. 对于海量数据抓取，建议不要使用 --all ，而是手动使用 --items-per-page 和 --start-index 进行分页控制，并在脚本中实现错误处理和重试。
2. 在请求间添加延迟，例如 sleep 1 （在Shell中）或 setTimeout （在Node.js中）。

问题4：管道输出JSON时， jq 命令解析失败

原因：CLI可能输出了非JSON内容（如错误信息或警告），或者 jq 期望的路径不存在。
排查：
1. 首先不加 jq ，直接查看原始输出： ch search “test” | cat 。确认输出是否是完整的、正确的JSON。
2. 使用 jq ‘.’ 进行通用解析和美化，看是否报错。
3. 在脚本中，始终先检查 ok 字段是否为 true ，再访问 data 字段。

问题5：输出中缺少某些预期字段（如董事的居住地址）

原因：这不是CLI的bug。Companies House API本身基于法律和隐私规定，不会公开所有信息。例如，董事的居住地址通常是不公开的，只提供通常居住国家（Country of residence）。CLI只是API的镜像，无法提供API未返回的数据。
解决：查阅 Companies House API官方文档，了解每个端点返回的确切字段。

这个工具将原本需要通过网页手动点击查询的繁琐过程，压缩成一行简洁的命令。更重要的是，它通过精心设计的机器友好型输出，为AI Agent和自动化脚本打开了一扇大门，让程序化的商业情报分析、尽职调查和风险监控变得触手可及。无论是金融分析师、风险投资人、律师，还是软件开发者，都能从中找到提升效率的切入点。

亚马逊云科技技术品牌专区

更多推荐