# user_index.json 同步问题修复报告

> 日期：2026-04-22  
> 问题：新联系人建档后未同步到 user_index.json  
> 状态：✅ 已修复

---

## 问题描述

杨小明（contactId: q0338m5q）的档案已创建在 `other-contacts/q0338m5q/` 目录下，但 `user_index.json` 中没有对应记录，导致会话启动时无法识别。

---

## 根本原因

1. **verify_user.py 和 archive.py 都调用 update_user_index.py**
2. **call_update_script 函数没有重试机制**
   - subprocess 调用可能超时或失败
   - 失败后没有回滚 user_index.json 的修改
   - 没有错误日志记录

3. **建档流程中 call_update_script 被调用但返回值未检查**
   - 即使调用失败，建档流程仍标记为成功
   - 导致档案创建成功但 user_index.json 未更新

---

## 立即修复（已完成）

手动同步杨小明到 user_index.json：

```bash
python3 update_user_index.py q0338m5q full "杨小明" "杨小明医生" "other-contacts" "健康之路" "医生" true
```

**结果：** ✅ 成功同步

---

## 长期修复（已完成）

### 1. verify_user.py 修改

**修改点：**
- `call_update_script` 函数增加重试机制（最多 3 次）
- 增加返回值检查（bool）
- `cmd_set_callname`、`cmd_verify_phone`、`cmd_archive_guest` 增加回滚逻辑

**代码变更：**
```python
# 旧代码
call_update_script(contact_id, "callname", callname)
return {"success": True}

# 新代码
success = call_update_script(contact_id, "callname", callname)
if not success:
    idx[contact_id] = old_data  # 回滚
    save_user_index(idx)
    return {"success": False, "error": "update_user_index 调用失败，已回滚"}
return {"success": True}
```

### 2. archive.py 修改

**修改点：**
- `call_update_script` 函数增加重试机制（最多 3 次）
- `archive_contact` 函数检查返回值并记录警告

**代码变更：**
```python
update_success = call_update_script(...)
if not update_success:
    result["warning"] = "档案创建成功，但 user_index.json 更新失败，需手动同步"
    result["update_user_index_success"] = False
else:
    result["update_user_index_success"] = True
```

### 3. 新增 sync-all-to-user-index.py

**功能：**
- 扫描 `employees/` 和 `other-contacts/` 目录
- 提取所有 profile.json 中的 contactId
- 检查是否在 user_index.json 中存在
- 缺失的自动同步

**用法：**
```bash
python3 sync-all-to-user-index.py
```

**输出示例：**
```
============================================================
全量同步脚本：检查并修复 user_index.json
============================================================

当前 user_index.json 中有 7 个联系人

📂 扫描 employees 目录...
  找到 0 个员工档案
📂 扫描 other-contacts 目录...
  找到 1 个外部联系人档案

总计：1 个档案

🔄 开始同步...

[other-contact] 杨小明 (q0338m5q)
  ✓ 已存在，跳过

============================================================
同步完成
============================================================
  总计档案：1
  已同步：0
  已存在：1
  失败：0

✅ 所有联系人同步成功
```

### 4. HEARTBEAT.md 更新

**新增任务：**
- 每 30 分钟运行 `sync-all-to-user-index.py`
- 检查是否有新增档案未同步
- 异常时记录到 `memory/YYYY-MM-DD.md`

---

## 测试验证

### 测试 1：杨小明同步
```bash
# 检查 user_index.json
cat user_index.json | jq '.q0338m5q'
```

**预期结果：**
```json
{
  "name": "杨小明",
  "callName": "杨小明医生",
  "role": "other-contacts",
  "verified": true,
  "organization": "健康之路",
  "position": "医生",
  "lastUpdate": "2026-04-22T17:10:07.425533+08:00"
}
```

### 测试 2：全量同步脚本
```bash
python3 projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/sync-all-to-user-index.py
```

**预期结果：** ✅ 所有联系人同步成功

---

## 后续维护

### 定期检查

**每周执行一次：**
```bash
cd /home/admin/.openclaw/workspace
python3 projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/sync-all-to-user-index.py
```

### 监控指标

| 指标 | 正常值 | 告警阈值 |
|------|--------|----------|
| user_index.json 联系人数 | = 档案总数 | < 档案总数 |
| 同步失败数 | 0 | > 0 |
| 回滚次数 | 0 | > 5/天 |

### 故障排查

**问题：联系人不在 user_index.json 中**

1. 检查 `other-contacts/{contactId}/{contactId}_profile.json` 是否存在
2. 检查 `logs/user_index/YYYY-MM-DD.log` 查看修改日志
3. 手动执行同步：
   ```bash
   python3 update_user_index.py <contactId> full "<姓名>" "<称呼>" "<role>" "<组织>" "<职位>" true
   ```

---

## 相关文件

| 文件 | 说明 |
|------|------|
| `projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/verify_user.py` | 身份核验脚本（已修复） |
| `projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/archive.py` | 建档脚本（已修复） |
| `projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/update_user_index.py` | user_index.json 更新脚本 |
| `projects/xiaoyi-assistant/instance/skills/user-onboard/scripts/sync-all-to-user-index.py` | 全量同步脚本（新增） |
| `user_index.json` | 联系人索引文件 |
| `HEARTBEAT.md` | 心跳任务配置（已更新） |
| `logs/user_index/YYYY-MM-DD.log` | 修改日志 |

---

_报告生成时间：2026-04-22 17:15_  
_修复状态：✅ 已完成_