如何快速排查Agnes Harness故障：错误码、运行时状态与Troubleshooting实战清单-平芜编程栈

【免费下载链接】agnes-harness

Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.

项目地址：https://gitcode.com/gh_mirrors/ag/agnes-harness

点击查看免费下载

Agnes Harness 是一个面向 Forward Deployed Engineering（FDE）场景的可插拔智能体运行框架。当 daemon 启动失败、模型调用报错或会话打开卡住时，这篇 Agnes Harness 故障排查指南带你用doctor诊断命令、错误码对照表和运行时审计日志三件套，快速完成 Troubleshooting 定位。

先判断问题位置：4 大故障场景

排错的第一步不是敲命令，而是先分辨问题发生在哪个环节。官方排错文档把问题归为四类：

场景	典型表现
🔨 构建环节	缺少`dist/local/agnes.mjs`、native helper 不兼容、Node 版本太旧
🔌 连接环节	daemon 启动后立即退出、`listen EPERM`、端口占用、Origin/Host 不匹配
🤖 模型配置	缺少 Provider、`RATE_LIMIT`/ HTTP 429、`TRANSPORT`/`TIMEOUT`
🧩 插件运行	插件装好了却没有工具、Skill 被 shadow、MCP 目录为空

💡 排查前先记下：当前 commit、Node 版本、执行的命令、错误码和所用的 home/profile——不要输出整个环境或凭据。

完整对照表见 troubleshooting.zh-CN.md 与 troubleshooting.md。

30 秒环境快照：doctor 诊断命令速查

doctor是 Agnes Harness 内置的只读体检命令，覆盖platform、provider、storage、credentials、profile、extensions、daemon、binary、code-runtime十个检查段（定义见 doctor.ts）。故障时的标准开场动作：

node packages/cli/dist/local/agnes.mjs --version node packages/cli/dist/local/agnes.mjs daemon status node packages/cli/dist/local/agnes.mjs doctor platform --json node packages/cli/dist/local/agnes.mjs doctor storage --json node packages/cli/dist/local/agnes.mjs doctor provider --json

几条容易踩坑的读法：

doctor platform会在每个低于full的能力下方输出<能力>.reason=…。看到sandbox.l1=unavailable且原因是awaiting sandbox backend full-boundary probe，说明沙箱后端只是尚未探测，并非平台不支持；真正的探测失败文案是no runnable OS sandbox backend passed its full-boundary probe。
doctor storage只建立并清理临时探测数据库，不会修复现有数据。
doctor provider --probe会真实调用模型（可能计费），排错时不要随手加上。
凭据目录权限不合格时，用doctor credentials做只读检查，它会列出每个不合格路径并给出可直接执行的chmod命令（详见 security.zh-CN.md）。

高频错误码实战对照表

Agnes Harness 的错误码是闭集：host 层固定 25 个（见 errors.ts），AI 装配层固定 6 个（见 errors.ts）。遇到报错先认码，再对下表动手：

错误码 / 现象	含义	下一步
`E_DAEMON_SOCKET_PATH`/ daemon 启动即退出	socket 路径过长、目录身份或权限不合格	核对 helper 与 home/profile；用短路径`/tmp/agh-*`实验 home 排除路径因素
`E_LEDGER_INTEGRITY`	会话历史哈希链不符：记录被改动或序号中断	先停后台、复制 dataDir 保留证据，再用备份恢复`sessions.db`，不要编辑数据库
`E_LEASE_EXPIRED`	工具行已卸载、撤权或被新版本替换	核对运行产物版本后按实际状态重新加载；旧版本曾有默认 24 小时到期问题
`SECRET_UNRESOLVED`（Windows，reason 为`private-file`）	密钥存储被拒绝而非缺失	`icacls <目录> /inheritance:r`关闭继承，再授予当前用户与`SYSTEM`
`RATE_LIMIT`/ HTTP 429	模型服务限流	稍后重试；持续出现则检查账号限额
`max_tokens`/`OUTPUT_LIMIT`	输出达到额度，本轮停止且不自动重试	要求模型分步继续，或配置 preset 的`model.max_tokens`
`TRANSPORT`/`TIMEOUT`	连接重置、DNS 失败、流式中断等，自动重试后仍失败	检查网络/代理/VPN；`CERT_HAS_EXPIRED`不重试，通常是代理拦截了 TLS
`TOOL_ARGS_INVALID`	工具参数不符合 schema	按错误中的参数路径补齐参数重试；被拒绝的调用不会写文件
`LOAD_STALLED`/ 卡在"正在准备会话"	后台 30 秒无消息；大会话打开可能要几分钟	先看`daemon status`，再看`audit/runtime.jsonl`的`session.open`记录
`E_FORMAT`	会话由更新版本写入	当前版本无法打开，见支持范围与已知限制

读懂运行时状态：两个审计日志文件

错误现场之外，daemon 会在所选 dataDir 下写两个脱敏日志，是运行时状态排查的核心：

audit/daemon.jsonl—— 请求审计：记录失败的请求和每个发起的批次。没有失败请求的行只代表"没有请求失败"，不代表 daemon 没有日志。
audit/runtime.jsonl—— 运行日志：工作进程退出/启动失败、会话中断、每次会话打开耗时、daemon 启动/停止/崩溃。超过 2 MiB 前轮转为runtime.jsonl.1。

🕵️ 意外错误常附带diagnosticId，用它匹配audit/daemon.jsonl中的记录即可还原失败请求；若返回diagnosticUnavailable，说明审计写入失败，不能据此断定没有错误。

一个实用技巧：audit/runtime.jsonl中的detail.session不是会话 ID，而是其 SHA-256 的前 16 位。找某会话的记录时，用同样方式对 ID 求哈希即可命中。

会话打开慢时，比较session.load的ms.open/ms.authorityReplay/ms.acpReplay三项，再看对应session.open的ms.read、ms.verify、ms.fold构成——checkpoint.used: false且ms.verify很大，说明正在完整核对很长的历史（原理见 sessions.zh-CN.md · 历史完整性校验）。