verify

验证 Honcho 中的更改

前置条件

Docker Compose 是运行整个服务栈的首选方式——仓库根目录中的 docker-compose.yml 会一并启动 Postgres（pgvector）、Redis、API 服务器和派生器 Worker。如果无法使用 Docker Compose，也可以直接在主机上运行整个服务栈（见下方“启动”）；你需要可访问的 Postgres（带有 pgvector）和 Redis，以及包含连接字符串和 LLM 提供商密钥的 .env，供任何会调用模型的流程使用（派生器、辩证分析、梦境生成器）。

在 worktree 中工作？其中既没有 .env，也没有 node_modules。从主检出目录复制 .env（提供商密钥存放在其中）；如果要运行完整测试套件，请在 sdks/typescript 中运行 bun install——否则，推送前检查会因一个并不存在的 Cannot find package 'zod' 错误而失败。

启动

首先检查 Docker Compose 是否已在运行整个服务栈：

docker compose ps          # look for api / deriver / database / redis
docker compose up -d       # start it if not

服务栈正在运行，不代表运行的是你这个分支的代码——请查看 CREATED 列；其中的镜像可能已经过时数周。要验证差异，最省事的办法是复用服务栈中的 Postgres/Redis 容器，同时在主机上的备用端口运行该分支的 API：

uv run uvicorn src.main:app --port 8901   # branch code, stack's DB/Redis
uv run python -m src.deriver              # if the diff touches the worker

这样既无需重建镜像，也能避免在 worktree 中启动第二个 Compose 服务栈时出现的端口/项目名称冲突。如果完全不使用 Docker，则以相同方式针对主机上的 Postgres + Redis 运行这两个进程（API 默认端口为 8000，通过 uv run fastapi dev src/main.py 启动）。

查看服务器日志时，请注意，使用主 .env 时，遥测发送器会因无法访问的端点而不断输出连接警告——查找真正的错误前，先运行 grep -v telemetry.emitter 进行过滤。

使用

优先通过 honcho-cli 技能进行操作；如果某个方法在较高层级不可用，再依次使用 SDK（sdks/python、sdks/typescript），最后直接通过 REST 访问 /v3。honcho-integration 技能介绍了如何使用 SDK。

如果更改更新了端点或修改了架构，请在所有三个界面上进行验证——CLI、SDK 和 REST 可能各自独立演变，彼此不一致。

对于 LLM 路径的更改，最快的同步验证方式是将辩证分析的推理级别设为 minimal：发送几条消息，然后调用 /v3/.../peers/{peer_id}/chat 并观察响应。

配置

配置对操作应用和运行测试都至关重要：API 密钥通过配置传入服务器，而与配置相关的更改也需要通过配置才能得到实际验证。设置可以来自环境变量或文件，优先级为 env > .env > config.toml > 默认值。要验证配置更改，请通过其中一个层级设置相关选项，重启受影响的进程，并观察相应界面上的行为变化——同样的机制也让你可以将提供商基础 URL、模型选项和超时设置为你实际拥有的凭据和代理。

两个具体的调整方式：深层嵌套设置（例如 [dialectic.levels.minimal.model_config.overrides.provider_params]）用环境变量设置非常麻烦——不如在仓库根目录放一个不完整的 config.toml。另外，要验证加载时的配置行为，运行 uv run python -c "import src.config; ..." 比启动服务器更快。

测试套件

这里有三种重要的测试类型。它们都会在 CI 中运行，也可以在本地使用你拥有的 API 密钥和配置运行——Honcho 的配置范围很广，因此可以将每 Agent 的超时和提供商基础 URL 等选项指向你自己的密钥/代理，以验证更改：

# Unit tests (pytest; spins up its own infra via fixtures)
uv run pytest tests/

# Unified tests — step-based end-to-end flows defined in JSON
# (config hierarchy, multi-turn interactions, LLM-as-judge assertions)
uv run python -m tests.unified.run
uv run python -m tests.unified.run --test-dir tests/unified/test_cases

# Live LLM tests — real provider calls, for testing specific backends.
# Needs provider API keys AND model vars — without LIVE_LLM_*_MODELS the
# tests silently deselect that provider. See tests/live_llm/README.md.
export LLM_ANTHROPIC_API_KEY=...
export LIVE_LLM_ANTHROPIC_45_PLUS_MODELS=claude-sonnet-4-5
uv run pytest tests/live_llm -n 0 --live-llm --no-header -q