故障排查

按症状分类。每条含 → 诊断 → 修复三段。

系统层 (Hermes / sage-wiki / systemd)

hermes-agent 服务 down

症状: systemctl status hermes-agent 显示 failed 或 inactive (dead)。

诊断:

bash

journalctl -u hermes-agent -n 100 --no-pager
hermes status 2>&1
ls /var/log/hermes/      # 如果配了日志路径

修复:

看错误是否与密钥相关 → op signin && op vault list 确认能拉密钥
端口冲突 → lsof -i :PORT 看占用, kill 或改 port
内存不足 → free -h, 重启释放
重启服务: sudo systemctl restart hermes-agent

sage-wiki ingest 不工作

症状: 改了 raw/clippings/ 中的文件, 但 _wiki/entities/ 没更新。

诊断:

bash

systemctl status sage-wiki-watch
sage-wiki doctor
ls -la _wiki/log.md       # 看最近编译时间

修复:

服务 down → sudo systemctl restart sage-wiki-watch
文件在 ignore 中 → 检查 config.yaml 的 ignore 列表
重新全量编译: sage-wiki recompile --all (约 30-60 分钟)

`/tian-judgement` 卡在 Phase 1

症状: 调用 5 分钟后无响应, 没有进入 Phase 2。

诊断:

bash

tail -100 ~/.hermes/logs/orchestrator.log
hermes skill status tian-judgement-orchestrator

修复:

mcp__sage-wiki__query 超时 → 看 sage-wiki 状态 (上一条)
Anthropic API 限流 → 看 Anthropic Dashboard, 改用 Haiku
临时 workaround: /tian-judgement <brand> --quick (跳过外部调研)

boss_server HTTP API (v0.6 认证)

所有 endpoint 返回 503

症状: 除 /v1/healthz 外全部 503 BOSS_API_TOKEN 未配置。

原因: v0.6 起认证 fail-close — 未配置 token 时拒绝服务而非裸奔 (设计行为)。

修复:

bash

export BOSS_API_TOKEN=$(openssl rand -hex 32)   # 或写入 .env (systemd EnvironmentFile)
sudo systemctl restart boss-hermes
curl -s -H "Authorization: Bearer $BOSS_API_TOKEN" localhost:8421/v1/panels   # 应 200

401 missing or invalid bearer token

症状: 配了 token 仍 401。

诊断: 依次检查 — ① 客户端是否带 Authorization: Bearer <token> 头 (scheme 必须是 Bearer, Basic 不行); ② 客户端与 server 的 token 是否同一份 (echo $BOSS_API_TOKEN 两边比对); ③ server 启动后是否改过 .env 未 restart。

Anthropic API

429 Too Many Requests

症状: Hermes 日志中频繁出现 rate_limit_exceeded。

诊断:

bash

grep -c "rate_limit" ~/.hermes/logs/*.log

修复:

短期: 把 Skill 的 model 从 Opus 改为 Sonnet 或 Haiku (修改 SKILL.md 中 model: 字段)
中期: 联系 Anthropic 升级 tier
长期: 加请求队列与 backoff (V1 增强)

invalid_api_key

症状: Authentication error: invalid x-api-key。

诊断:

bash

op read "op://boss-vault-prod/anthropic/credential" > /dev/null && echo "key 可读"
op item get anthropic --vault boss-vault-prod    # 查看 key 信息

修复:

key 过期 → 在 console.anthropic.com 生成新 key, 更新到 1Password
key 拼写错误 → 重新复制
vault 不对 → op vault list 确认 boss-vault-prod 存在

飞书

飞书卡片不推送

症状: 跑完 /tian-judgement 后项目主理 / 锚点没收到卡片。

诊断:

bash

# 看 Hermes 的飞书 outbound 日志
grep "feishu" ~/.hermes/logs/*.log | tail -20
# 测试飞书 webhook 是否在线
curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/$WEBHOOK_KEY -d '{"msg_type":"text","content":{"text":"test"}}'

修复:

webhook URL 失效 → 飞书后台 → App → webhook 重新生成
App scope 不够 → 飞书后台 → 增加 im:message scope
用户没加机器人 → 让用户在飞书搜机器人名称, 主动加好友

lark_oapi 集成不全

症状: mcp__feishu__send_card 失败, 报 "tool not found"。

诊断:

bash

hermes skill mcp-list | grep feishu
cat .mcp.json | jq '.mcpServers.feishu'

修复:

.mcp.json 缺 feishu server → 见 v3.4 vault skeleton 中的 .mcp.json 模板
env 变量未注入 → 用 op run --env-file=op.env -- hermes restart

飞书抓取工具 / 锚点 raw 材料过滤

飞书抓取工具 backup.py 报 auth 错

症状: 语料运维跑 python tools/feishu_backup/backup.py resume 报 401 / token expired。

诊断:

bash

lark-cli auth status
lark-cli auth check --scope "docs:document:readonly drive:file:download"

修复:

token 过期 (user_access_token 2h 过期) → lark-cli auth login 重新授权
scope 不够 → 在 lark-cli auth check --scope "..." 中加缺失的 scope, 重授权

feishu_sync_filter 不出文件

症状: 跑 make feishu-sync-filter 后 anchors/tian/raw/feishu-sync/docs/ 还是空。

诊断:

bash

ls backups/feishu/manifest.jsonl       # 应非空
wc -l backups/feishu/manifest.jsonl    # 看资源数
python scripts/feishu_sync_filter.py status
cat anchors/tian/raw/feishu-sync/_meta/filter_manifest.jsonl | jq -r '.tian_score' | sort -u

修复:

backups 为空 → 飞书抓取工具还没跑, 见 v3.3 §4.3 (W2 D2 6/2)
所有 tian_score 都 < 0.3 → config/feishu_sync_filter_rules.yaml 的 tian_identifiers 未填或填错 → 看 §3.1
通道 1/2 都不命中, 通道 3 LLM 兜底失败 → 看 Anthropic API 状态

.review/ 文件堆积

症状: anchors/tian/raw/feishu-sync/.review/ 里超过 30 份文件。

诊断:

bash

ls anchors/tian/raw/feishu-sync/.review/ | wc -l
python scripts/feishu_sync_filter.py review-list

修复:

项目主理跟不上抽审 → 提升频率到每周一次
thresholds 太松 → 调整 config/feishu_sync_filter_rules.yaml 的 thresholds.review_floor 从 0.3 → 0.4
text_patterns 漏太多 → 加入新的 mention pattern

git / commit

pre-commit 阻断

症状: git commit 输出 ❌ 阻断 commit (脱敏闸命中) 或 skill_lint FAIL。

诊断:

bash

cat /tmp/boss-redact.log    # 或 /tmp/boss-skill-lint.log

修复:

真敏感词 → 修改文件移除
误判 → 加到 scripts/redact_check.py 的 SAFE_PATTERNS 白名单 (需 CTO review)
紧急情况: git commit --no-verify (须在飞书群说明原因)

不可变 versions/ 被检测

症状: pre-commit 报 ❌ 试图修改不可变快照: reports/X/versions/v1_*.md。

诊断:

bash

git diff --cached reports/*/versions/

修复:

versions/v{n}_*.md 是判断历史的不可变 ground truth
应该生成 v{n+1}_*.md 而不是改 v
撤销修改: git restore --staged reports/.../versions/v1_*.md && git checkout -- ...

测试

pytest 找不到 scripts/ 模块

症状: ModuleNotFoundError: No module named 'redact_check'。

诊断:

bash

cat tests/conftest.py | head -20    # 应有 sys.path.insert(0, str(SCRIPTS_DIR))

修复:

必须从 vault 根目录跑: cd ~/boss-vault && pytest tests/
别从 tests/ 子目录跑

e2e test 超时

症状: tests/e2e/test_*.py 超过 600s timeout。

诊断:

bash

pytest tests/e2e/ -v -s --timeout=1200    # 临时延长

修复:

Hermes 没启动 → hermes start --daemon
Anthropic 慢 → 看 Anthropic 状态页
在 CI 中 → 把这个测试标 @pytest.mark.slow, 仅 main 分支跑

1Password

op CLI 不能登录

症状: op signin 报错或挂起。

诊断:

bash

op --version
op account list

修复:

CLI 版本太老 → 升级到 v2.x
网络问题 (公司代理) → 配 HTTPS_PROXY
账号不在企业 vault → 联系 CTO 邀请

密钥读不出

症状: op run --env-file=op.env -- ... 报 "item not found"。

诊断:

bash

op vault list                                    # 应有 boss-vault-prod
op item list --vault boss-vault-prod     # 应有 anthropic / lark / marsdata

修复:

vault 不存在 → op vault create boss-vault-prod
字段拼错 → 看 .env.example 中的 op://boss-vault-prod/<item>/<field> 是否与 1Password 中匹配

性能

全量 sage-wiki 重编译慢 (>1h)

正常: 500 文件全量编译需 30-60 分钟。

如果超过 1h:

看 Anthropic API 速率
减少并发: sage-wiki recompile --concurrency 4
把不需要的源 (例如 raw/archive/) 加到 ignore

attribution-checker 跑得慢

正常: 100 case 每日扫一遍 < 30 min。

如果超过 1h:

marsdata API 慢 → 看 dashboard
改为分批: 把 cases 分两个 cron job (上午/下午)

其他

我修改了 panels/default.yaml 后, 系统行为没变

诊断:

bash

hermes skill reload tian-judgement-orchestrator

修复:

Hermes 缓存了 yaml → 跑上面的 reload, 或重启 hermes-agent

sage-wiki recompile 卡在 0%

诊断:

bash

sage-wiki doctor
ls -la _wiki/

修复:

_wiki 目录权限错 → chmod -R u+w _wiki/
之前 ingest 死了 → 删 _wiki/.sage-state.json 后重编译

升级紧急 SOP

如果遇到本文档没列的问题, 按优先级:

飞书 PagerDuty 群 @CTO
看 ~/.hermes/logs/ 与 journalctl
v3.1 实施手册 §4.7 (回滚 SOP)
找语料运维 (如果是飞书抓取工具 / 飞书相关)

故障排查 ​

系统层 (Hermes / sage-wiki / systemd) ​

hermes-agent 服务 down ​

sage-wiki ingest 不工作 ​

/tian-judgement 卡在 Phase 1 ​

boss_server HTTP API (v0.6 认证) ​

所有 endpoint 返回 503 ​

401 missing or invalid bearer token ​

Anthropic API ​

429 Too Many Requests ​

invalid_api_key ​

飞书 ​

飞书卡片不推送 ​

lark_oapi 集成不全 ​

飞书抓取工具 / 锚点 raw 材料过滤 ​

飞书抓取工具 backup.py 报 auth 错 ​

feishu_sync_filter 不出文件 ​

.review/ 文件堆积 ​

git / commit ​

pre-commit 阻断 ​

不可变 versions/ 被检测 ​

测试 ​

pytest 找不到 scripts/ 模块 ​

e2e test 超时 ​

1Password ​

op CLI 不能登录 ​

密钥读不出 ​

性能 ​

全量 sage-wiki 重编译慢 (>1h) ​

attribution-checker 跑得慢 ​

其他 ​

我修改了 panels/default.yaml 后, 系统行为没变 ​

sage-wiki recompile 卡在 0% ​

升级紧急 SOP ​

故障排查

系统层 (Hermes / sage-wiki / systemd)

hermes-agent 服务 down

sage-wiki ingest 不工作

`/tian-judgement` 卡在 Phase 1

boss_server HTTP API (v0.6 认证)

所有 endpoint 返回 503

401 missing or invalid bearer token

Anthropic API

429 Too Many Requests

invalid_api_key

飞书

飞书卡片不推送

lark_oapi 集成不全

飞书抓取工具 / 锚点 raw 材料过滤

飞书抓取工具 backup.py 报 auth 错

feishu_sync_filter 不出文件

.review/ 文件堆积

git / commit

pre-commit 阻断

不可变 versions/ 被检测

测试

pytest 找不到 scripts/ 模块

e2e test 超时

1Password

op CLI 不能登录

密钥读不出

性能

全量 sage-wiki 重编译慢 (>1h)

attribution-checker 跑得慢

其他

我修改了 panels/default.yaml 后, 系统行为没变

sage-wiki recompile 卡在 0%

升级紧急 SOP