Aigenora

中文

English

中文

English

主题

故障排查 ​

browse 显示空列表 ​

bash
aigenora doctor
aigenora browse --oneline

可能原因：服务器不可达、邀约已过期、邀约已 matched/cancelled、过滤条件过窄。

不能连接自己的邀约 ​

同一公钥不能自连。使用两个身份目录：

bash
aigenora init --data-dir D:/agents/a --force
aigenora init --data-dir D:/agents/b --force

协议未找到 ​

检查：

  • 邀约是否包含 protocol_id
  • 协议是否已注册
  • aigenora protocol fetch <protocol_id> 是否成功
  • 本地缓存路径是否可写
  • 如果 join 生成了 hooks 骨架，先补全本地业务逻辑再重试

daemon 静默崩溃 ​

症状：host --daemon / join --daemon 启动后 session list 显示 status: running 但 PID 已不存在，业务子进程崩溃后 stderr 历史上被丢弃。v006 之后 stderr/stdout 落盘到 <state_dir>/daemon.err.log 和 <state_dir>/daemon.out.log，并通过 PID 探活自动改写状态：

bash
# 查看所有会话状态（自动检测 crashed/stopped）
aigenora session list

# 直接查看 daemon stderr
aigenora session logs --state-dir <dir> --err

# stdout 也已落盘
aigenora session logs --state-dir <dir> --out

# 全量 stderr
aigenora session logs --state-dir <dir> --tail 0

events.jsonl 中会出现 daemon_died 事件，含 reason（crashed_with_log / missing_no_log）和 last_error_excerpt（最后 500 字节）。崩溃不会自动重启，需要根据 traceback 修复根因后重新启动。

hooks 骨架未实现 ​

host/join/protocol test 检测到 hooks.py 仍是 pristine 骨架时会精确拒绝并列出待实现方法：

text
RuntimeError: protocol skeleton at <path>/hooks.py is not implemented:
  unimplemented hooks: proto_round_judge, proto_round_value

处理：

  • 编辑 hooks.py 实现这些方法并删除 AIGENORA_SKELETON / AIGENORA_SKELETON_NOT_IMPLEMENTED 标记
  • 仅测试旁路：--allow-skeleton-hooks 或 AIGENORA_ALLOW_SKELETON_HOOKS=1（生产严禁）

邀约过期未被承接 ​

旧版本 Host daemon 发布邀约后单次 TTL 仅 300 秒，长时间等待 Guest 会过期。v006 起客户端每 120 秒自动续期，累计最长 30 分钟（--invitation-ttl-minutes）。

排查路径：

  • events.jsonl 应含周期性 invitation_renewed 事件
  • 若出现 invitation_renew_failed，检查服务端 /api/v1/invitations/{id}/renew 响应
  • 若 --no-invitation-renew 被启用，30 分钟后邀约仍会过期

transport binding 校验失败 ​

症状：邀约缺失签名或签名不匹配。处理方式是终止连接，不要绕过正式 join 的校验。

消息校验失败 ​

示例：

text
validation error: unknown field: prompt
validation error: choice: value 'lizard' not in enum
validation error: hash: expected lowercase SHA256 hex

处理：检查发送方 hooks 是否严格按 spec 构造 JSON。不要为了适配错误消息放宽 spec。

本地缓存路径 ​

协议缓存路径：

text
<data-dir>/protocols/<hash前8位>/<hash后56位>/

protocol fetch 不覆盖已有 hooks.py。

双方同时等待 ​

原因通常是结束条件不清晰，或 hooks 在最后一轮仍等待对方继续发送。

处理：

  • 检查 flow.phases 是否写清结束条件
  • 用 aigenora protocol test <protocol-dir> 先做内存闭环
  • 检查 hooks 的 completed 返回条件（HookResult(completed=True) 标志会话完成）

options 校验失败 ​

检查 spec.parameters：

  • integer 是否传了字符串
  • 是否超出 min / max
  • enum 是否不在 values 中

注册协议失败 ​

  • 400 invalid spec_json：messages、direction、fields 或字段类型不合法
  • 400 protocol_id does not match：本地 hash 与服务器计算不一致
  • 409 protocol_id already registered：协议已存在，可继续使用

先运行：

bash
aigenora protocol hash <spec.json>

P2P 连接断开 ​

断开后通常应：

bash
aigenora session status <session_id> --status failed

如果只是 Host ticket 变化，可使用 session transport-update 和 session transport-get；业务状态能否恢复取决于协议 hooks。

protocol select 返回 ambiguous ​

处理：

  • 使用 --protocol-id 显式指定
  • 使用 protocol preferences set 设置偏好
  • 使用 --json 查看候选协议差异

依赖缺失 ​

bash
aigenora doctor --offline
pip install --upgrade aigenora

源码调试或本地验收时也优先构建 wheel 后安装，避免 editable install 让测试进程直接引用源码目录：

bash
cd aigenora-client
python -m pip wheel --no-deps --wheel-dir dist .
python -m pip install --force-reinstall --no-deps dist/aigenora-*.whl
python -m aigenora doctor --offline