OpenHuman 调试命令指南：用 `pnpm debug` 为 Agent 提供有界输出与可追溯日志的测试运行器-开发者社区

OpenHuman 调试命令指南：用`pnpm debug`为 Agent 提供有界输出与可追溯日志的测试运行器

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

本文面向在 OpenHuman（本地优先的个人 AI，仓库根目录即项目根）中调试 Rust 核心、前端 Vitest 单测与 WDIO E2E 的开发者与 AI Agent。scripts/debug/是一组围绕项目既有测试运行器的轻量封装，核心价值在于：把完整输出 tee 到target/debug-logs/下的日志文件，同时让 stdout 只保留摘要与失败块，从而让 Agent 的上下文不被海量原始输出淹没。读完本文，你将掌握pnpm debug unit | e2e | rust | logs的完整用法、参数约定、日志组织方式与底层实现原理。

为什么需要一套"Agent 友好"的测试封装

OpenHuman 同时维护三套测试体系：

Vitest（前端单测），由app/test/vitest.config.ts配置，入口脚本见 app/package.json 中的test:unit；
WDIO E2E（端到端），spec 位于app/test/e2e/，底层由 app/scripts/e2e-run-spec.sh 委托给统一的会话运行器e2e-run-session.sh；
cargo 测试（Rust 核心），经由 scripts/test-rust-with-mock.sh 携带 mock 后端运行。

这些运行器直接跑通常会产生几千行输出。对 LLM Agent 而言，把整份原始输出塞进上下文既不经济也容易淹没关键失败信息。scripts/debug/封装的核心目标在 README.md 中明确为三点：

过滤——Vitest 支持位置参数（文件 pattern）+-t "<name>"按测试名过滤，WDIO 一次只跑一个 spec，Agent 不必每次改动都在整棵树里 grep；
有界输出——默认摘要体量可控、适配 Agent 上下文；完整输出只需一条pnpm debug logs last即可取回；
稳定接口——底层运行器的 flag 经常变动，而这组封装把契约收敛为"位置参数 + 少量 flag"，避免 Agent 提示词因底层参数变动而失效。

需要强调的是，这些封装不取代项目原有测试运行器，它们只是以日志捕获的方式调用底层工具，退出码透传底层结果。

快速上手：四条核心命令

在仓库根目录执行（pnpm debug由根 package.json 的"debug": "bash scripts/debug/cli.sh"注册）：

# Vitest 单测 pnpm debug unit # 全量跑 pnpm debug unit src/components/Foo.test.tsx # 只跑某个文件（位置参数） pnpm debug unit -t "renders empty state" # 按测试名过滤 pnpm debug unit Foo -t "renders empty" --verbose # WDIO E2E（一次一个 spec） pnpm debug e2e test/e2e/specs/smoke.spec.ts pnpm debug e2e test/e2e/specs/cron-jobs-flow.spec.ts cron-jobs --verbose # cargo 测试（内部调用 scripts/test-rust-with-mock.sh） pnpm debug rust pnpm debug rust json_rpc_e2e # 查看已保存的日志 pnpm debug logs # 列出最近 50 个 pnpm debug logs last # 打印最近一个（超长时默认显示末尾 400 行） pnpm debug logs unit # 打印匹配前缀 "unit" 的最近日志 pnpm debug logs last --tail 100

日志统一落在target/debug-logs/<kind>-<suffix>-<timestamp>.log。该目录按需创建（见下文lib.sh的debug_log_dir），没有其他进程往这里写，删除它是安全的。

参数一览

命令	位置参数	常用 flag	底层调用
`unit`	`[pattern]`（文件或模糊路径）	`-t "<name>"`、`--watch`、`--verbose`、`-- <vitest-args…>`	`pnpm exec vitest run --config test/vitest.config.ts`（在`app/`下执行）
`e2e`	`<spec>`（spec 路径）+`[log-suffix]`（可选）	`--verbose`	`app/scripts/e2e-run-spec.sh <spec> <suffix>`
`rust`	`[test-filter]`（可传给底层脚本）	`--verbose`、`-- <cargo-test-args…>`	`scripts/test-rust-with-mock.sh`
`logs`	`list`/`last`/`<run-id 或前缀>`	`--head N`、`--tail N`	内置脚本 scripts/debug/logs.sh

所有运行类命令的退出码均与底层工具一致，方便在 CI 或 Agent 工作流中直接按$?判断。

深入源码：分发器与共享日志机制

cli.sh：命令分发

入口 scripts/debug/cli.sh 是一个set -euo pipefail的 bash 分发器：unit|e2e|rust|logs直接exec同名脚本；harness-cache-audit、agent-prepare-context-audit、goals-live三个审计命令则转交node执行对应的.mjs。不带参数或传-h/--help时打印完整 usage。这意味着未来新增调试子命令只需在case中加一行。

lib.sh：日志落盘与摘要提取

共享逻辑在 scripts/debug/lib.sh，三个关键函数：

debug_log_dir()：定位仓库根，mkdir -p target/debug-logs并按需创建日志目录；
debug_run <log> <verbose> -- <cmd…>：核心执行函数。verbose=1时用tee同时写文件并流式输出，并借助${PIPESTATUS[0]}精确取回原始命令（而非tee）的退出码；非 verbose 时只把输出重定向到日志文件，随后打印摘要；
三个摘要函数分别针对三种工具的输出格式做 grep/awk 提取：
- debug_summarize_vitest：提取Test Files / Tests / Duration / Start at行与FAIL块（含 FAIL 之后前 200 行细节）；
- debug_summarize_wdio：提取 Mocha 风格的passing / failing / pending统计与编号失败详情；
- debug_summarize_cargo：提取test result:行与failures:段。

这套"完整日志落盘 + 摘要上屏"的设计正是 Agent 上下文管理的核心——原始输出永不丢失，只是延迟读取。

unit.sh：Vitest 封装细节

scripts/debug/unit.sh 的参数解析值得注意：

第一个非 flag 位置参数被当作 pattern，其余多余位置参数进入passthrough；
-t/-t=<name>映射到 Vitest 的-t测试名过滤；
--watch会去掉run参数（Vitest 默认即 watch 模式）；
--之后的所有参数原样透传给vitest；
执行时cd到app/，并以--config test/vitest.config.ts显式指定配置，保证无论从哪个目录调用都命中同一份配置。

e2e.sh：一次一个 spec

scripts/debug/e2e.sh 约束更严格：第一个位置参数是 spec 路径（必填），第二个是日志后缀；未提供后缀时自动取basename "$spec" .spec.ts，并将后缀中的非法字符替换为-（${safe_suffix//[^[:alnum:]._-]/-}），保证日志文件名安全。随后调用 app/scripts/e2e-run-spec.sh，后者是一个薄 shim，最终exec到统一会话运行器e2e-run-session.sh（当前 E2E 全部运行在 Appium Chromium driver 上、附着 CEF 的 CDP 端口，不再区分 Mac2 与 tauri-driver 路径——参见该脚本头部注释）。

rust.sh 与 logs.sh

scripts/debug/rust.sh 将第一个位置参数作为 test-filter 追加到scripts/test-rust-with-mock.sh之后，同样支持--透传 cargo 参数。日志文件名为rust-<timestamp>.log。

scripts/debug/logs.sh 是日志检索工具：list按修改时间倒序列出最近 50 个文件；last、精确文件名或前缀匹配均可解析到具体文件；默认若文件超过 400 行只显示末尾 400 行并给出提示，可用--head N/--tail N覆盖。解析失败（无匹配）时以非零码退出，便于脚本判断。

扩展：三只"活体审计"子命令

pnpm debug还暴露了三只基于 Node 的审计命令（见 cli.sh），它们面向真实运行环境做验证，与测试运行器互补：

harness-cache-audit（scripts/debug/harness-cache-audit.mjs）：通过 JSON-RPC（默认http://127.0.0.1:7788/rpc，可用OPENHUMAN_CORE_RPC_URL覆盖；token 默认取OPENHUMAN_CORE_TOKEN或 workspace 下core.token）跑真实 harness turn，审计 transcript 的 token/缓存增量，不打印 prompt、response 或凭据正文；
agent-prepare-context-audit：强制每轮调用agent_prepare_context工具，打印返回的上下文包（含recommended_skills）、scout 思考、所用 gathering 工具与 token/缓存/成本，并可通过种入 canary 事实 + transcript-recall 用例验证 scout 能检索历史会话（--no-seed-transcript可跳过）；
goals-live：活测memory_goals流程（list/add/edit/delete + reflect 丰富化），打印 goals_agent 的思考、工具调用与成本。

这些命令体现了同一设计哲学：原始数据进文件、摘要进上下文、凭据不进日志。

实践建议

Agent 工作流：先跑pnpm debug unit <改动文件> -t "<用例名>"，失败时仅凭摘要定位；需要完整栈时再pnpm debug logs last。
日志管理：target/debug-logs/可随时删除，它只属于本封装，不影响其他构建产物。
排查底层差异：若怀疑封装行为与直接运行不一致，用--verbose观察被 tee 的原始命令输出，或直接按上文表格执行底层脚本对比。
环境前提：E2E 需要项目既有的 WDIO/Appium 环境（spec 位于app/test/e2e/，配置见app/wdio.conf.ts）；rust 测试依赖 mock 后端脚本 scripts/test-rust-with-mock.sh；unit 依赖app/下已安装的 pnpm 依赖。

小结

scripts/debug/用不到百行 bash 就把 OpenHuman 的三种测试运行器统一成一套"过滤 + 有界输出 + 可追溯日志"的稳定接口，同时保留底层工具的全部能力（位置参数、-t、--watch、--透传、退出码透传）。对于需要在上下文预算内高效定位失败的 AI Agent 与追求可复现调试的开发者，这是一套开箱即用的模式——完整实现可在 scripts/debug/ 目录内逐文件阅读。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenHuman 调试命令指南：用 `pnpm debug` 为 Agent 提供有界输出与可追溯日志的测试运行器