LobeHub CLI 全局搜索与用户配置命令实战：lh search、lh whoami 与 lh usage 详解

本篇指南聚焦 LobeHub CLI（lh）中用于"资源检索"与"账户/用量自省"的两组核心命令：lh search 全局搜索命令，以及 lh whoami / lh usage 用户配置与用量查询命令。基于 CLI 的源码实现与对应测试用例，本文将完整覆盖各命令的语法、参数、可搜索资源类型、输出格式及 JSON 字段过滤等实战细节，并深入到服务端 tRPC 路由层面解释搜索与用量数据的底层链路，帮助读者在终端与 Agent 自动化脚本中稳定、可解析地查询 LobeHub 的本地资源与账户用量。

命令在 CLI 中的注册位置

LobeHub CLI 的所有子命令统一在 program.ts 中通过 Commander 框架注册，其中 registerSearchCommand 与 registerConfigCommand 分别挂载了本文讨论的搜索命令和用户配置命令。从源码结构看，search 被实现为一个带子命令的复合命令（支持 search view），而 whoami 与 usage 则直接挂在根程序上，这与文档中"lh whoami / lh usage 作为顶级命令"的描述一致。

全局搜索命令 lh search

基本语法与参数

lh search 用于跨全部 LobeHub 资源类型执行搜索，其命令实现位于 search.ts。文档给出的基本调用形式为：

lh search "meeting notes" [-t <type>] [-L <n>]

选项	说明	默认值
-t, --type <type>	按资源类型过滤	所有类型
-L, --limit <n>	每种类型的结果数量上限	10

从源码看，--limit 在 CLI 侧默认值为 10（见 search.ts），该值会被转换为服务端入参 limitPerType（search.ts）。此外，若未提供查询词，命令会直接打印帮助信息而不是执行搜索（search.ts）。

可搜索的资源类型

CLI 侧对合法类型做了白名单校验（SEARCH_TYPES，见 search.ts），非法类型会报错并以退出码 1 终止：

类型	说明
agent	AI Agent
topic	会话主题
file	上传的文件
folder	文件目录
message	聊天消息
page	文档/页面
memory	用户记忆
mcp	MCP 服务器
plugin	已安装的插件
communityAgent	社区市场的 Agent
knowledgeBase	知识库

输出格式

默认表格模式下，结果按类型分组输出，每个分组包含 ID、标题/名称、描述三列。这一行为由 renderResultGroup 实现：分组标题形如 ── agent (3) ──，标题列取 title/name/content 字段并截断到 80 字符，描述列截断到 40 字符。无结果时输出 No results found.。

服务端实现：tRPC 搜索路由

CLI 的本地搜索通过 tRPC 客户端调用 search.query 接口（search.ts），服务端实现位于 search.ts。有几个值得注意的实现细节：

1. 未指定类型时会顺带查询市场（Marketplace）：communityAgent、mcp、plugin 属于市场类型集合，无类型过滤的搜索默认包含市场结果；延迟敏感的调用方（如命令菜单）可通过 includeMarketplace: false 关闭市场查询（search.ts）。
2. limitPerType 的服务端默认值：CLI 未传时服务端默认每种类型返回 5 条（search.ts），而 CLI 显式默认传 10，因此实际生效的默认上限取决于是否走 CLI 的 -L 默认值。
3. 空查询提前返回：空白查询直接返回空数组，不发起任何检索（search.ts）。
4. 市场结果相关性打分：市场项按标题匹配度打分（完全匹配=1、前缀匹配=2、包含匹配=3、否则=4）用于排序（search.ts）。

网络搜索与结果查看（源码扩展能力）

文档主体覆盖本地搜索，但从 search.ts 的完整定义看，lh search 还支持一组网络搜索选项：

选项	说明
-w, --web	切换到网络搜索（而非本地资源）
-e, --engines <engines>	搜索引擎（逗号分隔，需配合 --web）
-c, --categories <categories>	搜索类别（逗号分隔，需配合 --web）
-T, --time-range <range>	时间范围过滤，如 day, week, month, year

网络搜索走工具侧 tRPC 客户端的 search.webSearch 接口；若所有搜索提供方失败，命令会打印 errorDetail 并以退出码 1 退出，JSON 模式下则会先输出完整 JSON 再退出（search.ts）。

此外还有一级子命令 lh search view <target>：

• 本地结果传 type:id（如 agent:abc123），目前支持查看详情的是 agent、file、knowledgeBase 三种类型（search.ts）；
• 网络结果直接传 URL，会通过 search.crawlPages 抓取页面正文，可用 -i, --impl 指定抓取实现（browserless, exa, firecrawl, jina, naive, search1api, tavily，见 search.ts）。

搜索命令的测试覆盖

search.test.ts 验证了：查询词与 --type、-L 参数的透传（limitPerType）、--json 的格式化输出、空结果提示、按类型分组的表格渲染（兼容数组与对象两种响应形态）、非法类型的退出码，以及网络搜索失败时非 JSON 与 JSON 两种输出路径的错误处理。

用户配置命令 lh whoami

lh whoami 显示当前已认证用户的信息，实现在 config.ts：

lh whoami [--json [fields]]

显示内容：姓名（Name）、用户名（Username）、邮箱（Email）、用户 ID（User ID）、订阅套餐（Plan）。数据来源是 tRPC 的 user.getUserState 查询。

从源码结构看，还有一个文档未提及但非常实用的扩展：工作区作用域（Scope）报告。whoami 会调用 resolveWorkspaceId() 解析当前生效的 LOBEHUB_WORKSPACE_ID 环境变量，并在输出中报告当前命令作用域是 workspace <id> 还是 personal（config.ts）。源码注释明确说明了这一设计意图：让调用者（通常是编辑自身配置的 Agent）能够区分"资源真的不存在"与"查错了工作区"。--json 输出中同样会携带 scope 与 workspaceId 两个附加字段（config.ts），相关行为由 config.test.ts 中的工作区作用域用例锁定。

用量查询命令 lh usage

lh usage 用于查看指定月份的 Token 用量、费用与模型分布，同样实现在 config.ts：

lh usage [--month <YYYY-MM>] [--daily] [--agent-id <id>] [--json [fields]]

选项	说明	默认值
--month <YYYY-MM>	要查询的月份	当月
--daily	按天分组	false（按月合计）
--agent-id <id>	仅统计指定 Agent	全部 Agent

输出内容：指定周期的 Token 用量（输入/输出/总计）、请求次数、费用（USD）与按天汇总的模型列表。

输出细节与数据链路

源码层面，usage 命令区分两种输出路径：

• JSON 模式：--daily 时调用 usage.findAndGroupByDay，否则调用 usage.findByMonth（config.ts）；
• 表格模式：始终拉取按天分组的数据（findAndGroupByDay），过滤掉零活动日，按 Date / Models / Input / Output / Total Tokens / Requests / Cost(USD) 七列渲染，并追加加粗的 Total 汇总行（config.ts）。

表格之后还会自动渲染一张过去 12 个月的活动热力图：优先调用 usage.findAndGroupByDateRange 一次性取数，失败时回退为并发请求 12 个月度数据再合并（config.ts）。--month 参数会被映射为服务端的 mo 入参，这一契约在 config.test.ts 中有明确断言。

全局选项与 JSON 字段过滤

以下选项在多数 lh 命令中可用（引自 search-config.md）：

选项	说明
--json [fields]	以 JSON 输出；可选地以逗号分隔字段列表做投影
--yes	跳过破坏性操作的确认提示
-L, --limit <n>	列表类命令的分页数量上限
-v, --verbose	开启详细/调试日志
--help	显示命令帮助
--version	显示 CLI 版本

其中 --version 由根程序统一注册（program.ts），版本号来自 CLI 包自身。

JSON 字段过滤

--json 支持不带值（完整 JSON）或带逗号分隔字段（投影）两种用法：

# 完整 JSON 输出
lh agent list --json

# 只取指定字段
lh agent list --json "id,title,model"

在 search、whoami、usage 等命令的实现中，该参数被统一处理为 string | boolean：传字符串时按字段投影，仅加 flag 时输出完整结构（例如 search.ts、config.ts）。对 Agent 自动化场景，这意味着可以用 lh search "..." --json "id,title" 获得轻量、可管道解析的输出，再用 lh search view agent:<id> 下钻详情。

小结

本文基于 search-config.md 文档，结合 search.ts、config.ts 的源码实现与 search.test.ts、config.test.ts 的测试契约，梳理了 LobeHub CLI 中三类自省命令的完整用法：lh search 提供跨 11 种资源类型（含市场资源）的分组检索、可选网络搜索与结果下钻；lh whoami 报告用户身份与当前工作区作用域；lh usage 提供月度/按天 Token 用量、费用与模型分布，并附带 12 个月活动热力图。所有命令均支持 --json [fields] 投影输出，适合在终端人工查看与 Agent 脚本化调用两种场景中使用。