# 故障排查 (Troubleshooting)

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

---

## 系统层 (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/      # 如果配了日志路径
```

**修复**:
1. 看错误是否与密钥相关 → `op signin && op vault list` 确认能拉密钥
2. 端口冲突 → `lsof -i :PORT` 看占用, kill 或改 port
3. 内存不足 → `free -h`, 重启释放
4. 重启服务: `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       # 看最近编译时间
```

**修复**:
1. 服务 down → `sudo systemctl restart sage-wiki-watch`
2. 文件在 ignore 中 → 检查 `config.yaml` 的 ignore 列表
3. 重新全量编译: `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](https://console.anthropic.com), 改用 Haiku
- 临时 workaround: `/tian-judgement <brand> --quick` (跳过外部调研)

---

## Anthropic API

### 429 Too Many Requests

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

**诊断**:
```bash
grep -c "rate_limit" ~/.hermes/logs/*.log
```

**修复**:
1. 短期: 把 Skill 的 model 从 Opus 改为 Sonnet 或 Haiku (修改 SKILL.md 中 `model:` 字段)
2. 中期: 联系 Anthropic 升级 tier
3. 长期: 加请求队列与 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 信息
```

**修复**:
1. key 过期 → 在 console.anthropic.com 生成新 key, 更新到 1Password
2. key 拼写错误 → 重新复制
3. 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"}}'
```

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

### 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`

---

## laotian / 锚点 raw 材料过滤

### laotian backup.py 报 auth 错

**症状**: zhanglu 跑 `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, 重授权

### laotian_filter 不出文件

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

**诊断**:
```bash
ls backups/feishu/manifest.jsonl       # 应非空
wc -l backups/feishu/manifest.jsonl    # 看资源数
python scripts/laotian_filter.py status
cat anchors/tian/raw/feishu-laotian/_meta/filter_manifest.jsonl | jq -r '.tian_score' | sort -u
```

**修复**:
1. backups 为空 → laotian 还没跑, 见 v3.3 §4.3 (W2 D2 6/2)
2. 所有 tian_score 都 < 0.3 → `config/laotian_filter_rules.yaml` 的 `tian_identifiers` 未填或填错 → 看 §3.1
3. 通道 1/2 都不命中, 通道 3 LLM 兜底失败 → 看 Anthropic API 状态

### .review/ 文件堆积

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

**诊断**:
```bash
ls anchors/tian/raw/feishu-laotian/.review/ | wc -l
python scripts/laotian_filter.py review-list
```

**修复**:
1. 项目主理 跟不上抽审 → 提升频率到每周一次
2. thresholds 太松 → 调整 `config/laotian_filter_rules.yaml` 的 `thresholds.review_floor` 从 0.3 → 0.4
3. 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
```

**修复**:
1. 真敏感词 → 修改文件移除
2. 误判 → 加到 `scripts/redact_check.py` 的 SAFE_PATTERNS 白名单 (需 CTO review)
3. 紧急情况: `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{n}
- 撤销修改: `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
```

**修复**:
1. CLI 版本太老 → 升级到 v2.x
2. 网络问题 (公司代理) → 配 HTTPS_PROXY
3. 账号不在企业 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

如果遇到本文档没列的问题, 按优先级:
1. 飞书 PagerDuty 群 @CTO
2. 看 ~/.hermes/logs/ 与 journalctl
3. v3.1 实施手册 §4.7 (回滚 SOP)
4. 找 zhanglu (如果是 laotian / 飞书相关)