cli-backend-testing

CLI + 后端集成测试

使用 LobeHub CLI（lh）针对本地开发服务器验证后端更改的标准工作流。

适用场景

• 端到端验证 TRPC 路由器、服务或模型更改
• 测试新增 API 字段或响应结构更改
• 验证后端修改后 CLI 命令的输出
• 调试服务器与 CLI 之间的数据流问题

前置条件

要求	详情
开发服务器	localhost:3011（Next.js）
CLI 源码	lobehub/apps/cli/
CLI 开发模式	使用 LOBEHUB_CLI_HOME=.lobehub-dev 隔离凭据
身份验证	使用 Device Code Flow 登录本地服务器

快速参考

所有 CLI 开发命令均从 lobehub/apps/cli/ 运行：

# Shorthand for all commands below
CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"

工作流

步骤 1：确保开发服务器正在运行

检查开发服务器是否已在运行：

curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null

• 如果可访问（返回任意 HTTP 状态）：服务器正在运行。跳至步骤 2。
• 如果无法访问：启动服务器：

# From cloud repo root
pnpm run dev:next

如需重启（应用服务器端代码更改）：

lsof -ti:3011 | xargs kill
pnpm run dev:next

重要： 子模块（lobehub/src/server/、lobehub/packages/）中的服务器端代码更改需要重启服务器。Next.js 热重载可能不会应用子模块包中的更改。

步骤 2：检查 CLI 身份验证

检查开发凭据是否已存在：

cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null

• 如果文件存在且包含 "serverUrl": "http://localhost:3011"：已完成身份验证。跳至步骤 3。
• 如果文件不存在或指向错误的服务器：需要登录。请让用户运行：

! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011

登录需要通过交互式浏览器授权（OIDC Device Code Flow），因此用户必须使用 ! 前缀自行运行。登录后，凭据会保存到 lobehub/apps/cli/.lobehub-dev/，并在会话之间保留。

步骤 3：使用 CLI 命令进行测试

CLI 从源码运行（bun src/index.ts），因此 CLI 端代码更改无需重新构建即可立即生效。

cd lobehub/apps/cli
LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>

步骤 4：清理测试数据

删除验证过程中创建的所有测试数据：

LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts task delete < id > -y
LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y

常见测试模式

任务系统

# List tasks
$CLI task list

# Create test data with nesting
$CLI task create -n "Root Task" -i "Test instruction"
$CLI task create -n "Child Task" -i "Sub instruction" --parent T-1

# View task detail (tests getTaskDetail service)
$CLI task view T-1

# View task tree
$CLI task tree T-1

# Test lifecycle
$CLI task edit T-1 --status running
$CLI task comment T-1 -m "Test comment"

# Clean up
$CLI task delete T-1 -y

Agent 系统

# List agents
$CLI agent list

# View agent detail
$CLI agent view <agent-id>

# Run agent (tests agent execution pipeline)
$CLI agent run <agent-id> -m "Test prompt"

文档和知识库

# List documents
$CLI doc list

# Create and view
$CLI doc create -t "Test Doc" -c "Content here"
$CLI doc view <doc-id>

# Knowledge base
$CLI kb list
$CLI kb tree <kb-id>

模型和提供商

# List models and providers
$CLI model list
$CLI provider list

# Test provider connectivity
$CLI provider test <provider-id>

开发测试周期

后端开发的标准周期：

1. Make code changes (service/model/router/type)
         |
2. Run unit tests (fast feedback)
   bunx vitest run --silent='passed-only' '<test-file>'
         |
3. Restart dev server (if server-side changes)
   lsof -ti:3011 | xargs kill && pnpm run dev:next
         |
4. CLI verification (end-to-end)
   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
         |
5. Clean up test data

需要重启服务器的情况

更改位置	是否重启？
lobehub/src/server/（路由器、服务）	是
lobehub/packages/database/（模型）	是
lobehub/packages/types/	是
lobehub/packages/prompts/	是
lobehub/apps/cli/（CLI 代码）	否
src/（云端覆盖）	是

无需重启服务器的情况

CLI 通过 bun src/index.ts 从源码运行，因此对 lobehub/apps/cli/src/ 的任何更改都会在下次调用命令时立即生效。

故障排除

问题	解决方案
No authentication found	运行 login --server http://localhost:3011
API 调用时出现 UNAUTHORIZED	Token 已过期；重新运行 login
ECONNREFUSED	开发服务器未运行；使用 pnpm run dev:next 启动
CLI 显示旧数据/旧行为	需要重启服务器以应用代码更改
端口 3011 上出现 EADDRINUSE	服务器已在运行；使用 lsof -ti:3011 | xargs kill 终止
登录时打开了错误的服务器	必须使用 --server http://localhost:3011 标志（环境变量不起作用）

凭据隔离

模式	凭据目录	服务器
开发	lobehub/apps/cli/.lobehub-dev/	localhost:3011
生产	~/.lobehub/	app.lobehub.com

这两个环境完全隔离。开发模式凭据已加入 gitignore。