# 小医建档流程与架构分析报告

> 版本：v1.0  
> 生成时间：2026-04-28 10:53  
> 分析范围：/home/admin/.openclaw/workspace  
> 文档数量：277 个 .md 文件

---

## 📋 执行摘要

本报告基于小医（健康之路医生助理）项目 workspace 的全部文档，对**用户建档流程**和**系统架构**进行全面分析，识别当前存在的问题并提出改进建议。

### 核心发现

| 类别 | 状态 | 说明 |
|------|------|------|
| 建档流程 | ⚠️ 部分完善 | 新用户流程已定义，但存在执行不一致问题 |
| 数据同步 | 🔴 存在风险 | user_index.json 与档案目录存在不同步风险 |
| 身份核验 | ✅ 已自动化 | API 核验流程完整，支持手机号验证 |
| 权限控制 | ✅ 清晰 | owner/employee/other-contacts 三级权限明确 |
| 渠道激活 | ⚠️ 依赖用户 | tutu-aggchat 需用户主动发消息才能激活 |

---

## 一、建档流程分析

### 1.1 流程总览

```
用户添加小医微信
    ↓
系统自动解析 contactId（从会话标识）
    ↓
检查 user_index.json（判断新老用户）
    ↓
┌─────────────────────┬─────────────────────┐
│   新用户流程        │   老用户流程        │
│  (contactId 不存在)  │  (contactId 存在)    │
└─────────────────────┴─────────────────────┘
    ↓                         ↓
创建档案目录                 加载 SESSION_STATE
    ↓                         ↓
发送欢迎词 + FAQ              加载用户权限
    ↓                         ↓
引导提供信息（姓名 + 手机号）   正常会话
    ↓
调用 API 核验身份
    ↓
建档完成（verified=true）
    ↓
同步到 user_index.json
```

---

### 1.2 新用户建档详细流程

#### 步骤 1：contactId 解析

**来源：** 从会话标识自动解析
```
会话标识格式：
agent:main:tutu-aggchat:direct:jkzl:vgw9nk8r:7v1xmj9q
                                        ↓
                                    contactId
```

**方法：**
- 方法 1（推荐）：session_status → 解析 sessionKey 最后 8 位
- 方法 2（备用）：从 user_index.json 反查（已知姓名时）

---

#### 步骤 2：档案创建

**档案目录：** `other-contacts/{contactId}/`

**档案文件：**
```
other-contacts/{contactId}/
├── profile.json              # 基本信息
├── {contactId}_SESSION_STATE.md  # 会话状态（可选）
└── memory/                   # 短期记忆（可选）
    └── YYYY-MM-DD.md
```

**profile.json 格式：**
```json
{
  "contactId": "q29m0gev",
  "name": "陈美华",
  "role": "other-contacts",
  "verified": true,
  "phone": "13559110806",
  "doctorUid": 710558434,
  "createdAt": "2026-04-27 15:51",
  "lastUpdate": "2026-04-27 18:15"
}
```

---

#### 步骤 3：欢迎词发送

**触发条件：** 新用户（contactId 不在 user_index.json 中）

**欢迎词内容：** 加载自 `skills/activity-faq/doctor-faq.md`

**发送规则：**
1. 按微信友好格式发送（纯文本，用【】强调，空行分段）
2. 可个性化称呼（如档案中有姓名，用"李医生您好"）
3. 发送后等待用户回复
4. 同步到 user_index.json：调用 `scripts/sync_user_index.py` 脚本

---

#### 步骤 4：信息收集（简化版）

**仅需 2 项信息：**
1. 姓名
2. 手机号

**说明：** 医院、科室、省份等信息通过 API 核验后自动获取，无需用户手动提供。

**话术示例：**
```
您好！为了为您提供精准的查询服务，需要为您建立医生档案。

请您提供以下信息：
1. 姓名
2. 手机号

例如：张三，13559110806
```

---

#### 步骤 5：身份核验

**调用 API：** `UserMgmt.Account.getUserInfoByLoginID`

**请求参数：**
```json
{
  "loginID": "13559110806",
  "loginType": "1",
  "needDepartment": "false"
}
```

**核验结果处理：**

| API 返回 | 处理方式 |
|---------|---------|
| Code=10000，有 UserID | ✅ 核验通过，更新档案 |
| Code=-9999，无此用户 | ❌ 核验失败，引导重新提供 |
| 其他错误 | ⚠️ 记录日志，人工介入 |

**核验通过后更新档案：**
```json
{
  "contactId": "q29m0gev",
  "name": "陈美华",
  "role": "other-contacts",
  "verified": true,
  "phone": "13559110806",
  "doctorUid": 710558434,
  "hospital": "福州协和医院",
  "department": "心内科",
  "lastUpdate": "2026-04-27 18:15"
}
```

---

#### 步骤 6：同步到 user_index.json

**同步脚本：** `scripts/sync_user_index.py`

**同步方式：**
```bash
# 手动同步所有档案
python3 scripts/sync_user_index.py

# 自动同步（新用户建档后调用）
scripts/sync_user_index.py
```

**user_index.json 格式：**
```json
{
  "q29m0gev": {
    "name": "陈美华",
    "callName": "陈美华",
    "role": "other-contacts",
    "verified": true,
    "phone": "13559110806",
    "doctorUid": 710558434,
    "createdAt": "2026-04-27 15:51",
    "lastUpdate": "2026-04-27 18:22"
  }
}
```

---

### 1.3 老用户流程

#### 识别逻辑
```python
if contactId in user_index and user_index[contactId]['verified'] == true:
    # 老用户 → 加载权限
    role = user_index[contactId]['role']
    load_session_state(role, contactId)
```

#### SESSION_STATE 加载

| 角色 | 加载文件 |
|------|---------|
| owner | `memory/SESSION_STATE.md` |
| employee | `employees/{姓名}_{contactId}/{姓名}_{contactId}_SESSION_STATE.md` |
| other-contacts | `other-contacts/{contactId}/{contactId}_SESSION_STATE.md` |

---

### 1.4 员工身份核验（特殊流程）

**触发条件：** 用户在 `employees/employee_list.json` 预置名单中

**处理流程：**
1. 查询 `employees/employee_list.json`
2. 匹配姓名或手机号
3. 匹配成功 → 问手机后四位核验
4. 核验通过 → role=employee，创建员工档案

**员工档案目录：** `employees/{姓名}_{contactId}/`

---

## 二、系统架构分析

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                     用户交互层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  企业微信   │  │   个人微信   │  │  Web 界面   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┴────────────────┘                 │
│                          │                                  │
│                  tutu-aggchat 通道                           │
└──────────────────────────┼──────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     应用服务层                               │
│  ┌───────────────────────┴───────────────────────┐         │
│  │            OpenClaw Agent (小医)              │         │
│  │  ┌─────────────┐  ┌─────────────┐            │         │
│  │  │  会话管理   │  │  技能调度   │            │         │
│  │  └─────────────┘  └─────────────┘            │         │
│  │  ┌─────────────┐  ┌─────────────┐            │         │
│  │  │  记忆系统   │  │  权限控制   │            │         │
│  │  └─────────────┘  └─────────────┘            │         │
│  └───────────────────────────────────────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     数据持久层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ user_index  │  │  档案目录   │  │   记忆文件   │         │
│  │   .json     │  │  (JSON)     │  │   (.md)     │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  技能清单   │  │   配置中心   │  │   工单系统   │         │
│  │ manifest    │  │  config/    │  │  tickets/   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     外部 API 层                               │
│  ┌─────────────────────────────────────────────────┐        │
│  │     健康之路开放平台 API                         │        │
│  │  - UserMgmt.Account.getUserInfoByLoginID        │        │
│  │  - DoctorIncomeUI.DoctorCashApi.query...        │        │
│  │  - DoctorIncomeUI.UserEnterInfoApi.get...       │        │
│  └─────────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘
```

---

### 2.2 用户分类与权限

| 角色 | 标识 | 说明 | 档案目录 | 权限 |
|------|------|------|----------|------|
| **owner** | role: owner | 系统所有者（高祖峰） | employees/{姓名}_{contactId}/ | 全部权限 |
| **employee** | role: employee | 内部运营人员 | employees/{姓名}_{contactId}/ | 员工权限 |
| **other-contacts** | role: other-contacts | 外部用户（医生） | other-contacts/{contactId}/ | 医生权限 |

**重要规则：**
- owner 仅高祖峰一人（contactId: 7v1xmj9q）
- 其他任何人（包括杨小明、运营人员、全科医生）都不是 owner
- 只有 owner 可以查看技能详情、API 配置、系统信息

---

### 2.3 数据隔离机制

```
workspace/
├── user_index.json              # 全局索引（所有用户可见）
├── employees/                   # 内部员工档案
│   ├── employee_list.json      # 员工预置名单
│   └── {姓名}_{contactId}/     # 员工个人档案（隔离）
├── other-contacts/              # 外部用户档案
│   └── {contactId}/            # 用户档案目录（隔离，不带姓名）
├── memory/                      # 全局记忆
│   ├── SESSION_STATE.md        # 全局活跃状态
│   └── YYYY-MM-DD.md           # 每日记忆
└── tickets/                     # 工单系统
    └── ticket-{date}-{num}.json # 工单文件
```

**隔离规则：**
- 用户之间数据互不可见
- 只有 owner 可访问所有数据
- 员工只能查看工作相关数据
- 外部用户档案目录不带姓名（隐私保护）

---

### 2.4 技能架构

#### 技能分层

| 层级 | 说明 | 技能数量 | 路径 |
|------|------|----------|------|
| Layer 2 | 公共技能池 | 4 个 | /workspace/skills/ |
| Layer 3 | 医生助理专属 | 11 个 | ./skills/ |

#### 核心技能清单

| 技能名称 | 层级 | 用途 |
|---------|------|------|
| user-onboard | Layer 2 | 用户身份核验 |
| other-contacts-onboard | Layer 2 | 外部用户建档 |
| activity-query | Layer 3 | 活动查询 |
| activity-reg-link | Layer 3 | 报名链接查询 |
| activity-push | Layer 3 | 活动报名推送 |
| audit-notify | Layer 3 | 审核结果通知 |
| order-query | Layer 3 | 提现订单查询 |
| get-doctor-uid | Layer 3 | 手机号核验 + 获取 UserID |
| sms-clear | Layer 3 | 短信发送次数清空 |
| ticket-escalation | Layer 3 | 工单转接 |

---

### 2.5 记忆系统

| 类型 | 位置 | 说明 |
|------|------|------|
| 全局短期 | memory/YYYY-MM-DD.md | 每日记忆 |
| 全局长期 | MEMORY.md | 长期沉淀 |
| 全局活跃状态 | memory/SESSION_STATE.md | WAL 协议写前日志 |
| 员工短期 | employees/{姓名}_{contactId}/memory/YYYY-MM-DD.md | 员工个人记忆 |
| 外部用户短期 | other-contacts/{contactId}/memory/YYYY-MM-DD.md | 用户个人记忆 |

**WAL Protocol（写前日志）触发条件：**
- ✏️ 纠正 — "不对"、"其实应该"、"错了"
- 📍 专有名词 — 人名、医院名、药品名
- 🎨 偏好 — "我喜欢/不喜欢"
- 📋 决策 — "决定做 X"
- 🔢 具体数值 — 数字、日期、ID

---

## 三、存在的问题

### 3.1 🔴 严重问题

#### 问题 1：user_index.json 同步风险

**问题描述：**
档案创建后，依赖脚本同步到 user_index.json，存在不同步风险。

**根本原因：**
1. `call_update_script` 函数没有重试机制
2. subprocess 调用可能超时或失败
3. 失败后没有回滚 user_index.json 的修改
4. 建档流程仍标记为成功，导致数据不一致

**影响：**
- 新用户会话启动时无法识别
- 欢迎流程无法正确执行
- 权限加载失败

**历史案例：**
- 杨小明（contactId: q0338m5q）档案已创建，但 user_index.json 中无记录
- 修复方式：手动执行同步脚本

**当前缓解措施：**
- 已创建 `sync-all-to-user-index.py` 全量同步脚本
- HEARTBEAT.md 配置每 30 分钟运行一次同步检查

**建议改进：**
1. 在建档流程中增加同步状态检查
2. 同步失败时回滚档案创建
3. 增加监控告警（同步失败数 > 0 时通知 owner）

---

#### 问题 2：渠道激活依赖用户主动发消息

**问题描述：**
tutu-aggchat 通道需要用户主动发消息才能激活，导致：
- 新用户添加后不发消息 → 无法发送欢迎词
- 员工建档后不发消息 → 无法接收工单通知

**影响：**
- 新用户欢迎流程执行率 < 100%
- 工单通知可能发送失败
- 全科医生团队无法接收审核催促通知

**历史案例：**
- 问题 #004：企业微信通知发送失败（接收方渠道未激活）
- 问题 #005：全科医生团队渠道未激活（高巧津、黄达、郑小丹）

**当前缓解措施：**
- 引导用户主动发消息（如"你好"）
- 在 issue-tracker 中记录待激活用户

**建议改进：**
1. 研究 tutu-aggchat API 是否支持主动激活渠道
2. 增加渠道状态监控（未激活用户列表）
3. 运营人员手动引导新添加用户发消息

---

### 3.2 ⚠️ 中等问题

#### 问题 3：档案目录结构不统一

**问题描述：**
不同用户的档案目录结构存在差异：

**示例 1（标准）：**
```
other-contacts/q29m0gev/
└── profile.json
```

**示例 2（带 SESSION_STATE）：**
```
other-contacts/test_new_01/
├── test_new_01_SESSION_STATE.md
└── ...
```

**示例 3（旧格式）：**
```
other-contacts/phone-59152902/  # 目录名使用手机号
other-contacts/59152902/        # 目录名使用 contactId
```

**影响：**
- 档案查询逻辑复杂
- 同步脚本需要处理多种格式
- 增加维护成本

**建议改进：**
1. 统一档案目录结构（仅使用 contactId 作为目录名）
2. 制定档案目录规范文档
3. 迁移旧格式档案到新格式

---

#### 问题 4：活动名称映射维护成本高

**问题描述：**
用户搜索的活动名称（品牌名）与系统实际活动名称不一致，需要维护映射表。

**当前映射关系：**
| 用户搜索关键词 | 实际活动名称 | 报名链接 |
|---------------|-------------|---------|
| 医道微光 | 精准免疫肿瘤诊疗管理 | https://fjhma.com/1DL8uI |
| 精准免疫 | 精准免疫肿瘤诊疗管理 | https://fjhma.com/1DL8uI |
| 跨学科 | 跨学科综合健康管理 | https://fjhma.com/1DL53Y |
| 泪液动力 | 泪液动力防治养护健康管理 | https://fjhma.com/1DLUBj |

**影响：**
- 新活动上线时需要手动更新映射表
- 映射表位置分散（config/activity-name-mapping.json + AGENTS.md）
- 容易遗漏或过时

**建议改进：**
1. 统一映射表位置（仅 config/activity-name-mapping.json）
2. 增加映射表管理界面（运营人员可自助更新）
3. 支持模糊匹配 + 人工确认流程

---

#### 问题 5：SESSION_STATE 文件分散

**问题描述：**
SESSION_STATE 文件分布在多个位置：
- `memory/SESSION_STATE.md`（全局）
- `employees/{姓名}_{contactId}/{姓名}_{contactId}_SESSION_STATE.md`
- `other-contacts/{contactId}/{contactId}_SESSION_STATE.md`
- `SESSION-STATE.md`（根目录）

**影响：**
- 加载逻辑复杂
- 容易加载错误文件
- 增加维护成本

**建议改进：**
1. 统一 SESSION_STATE 文件位置
2. 制定加载优先级规则
3. 增加文件不存在时的降级处理

---

### 3.3 ℹ️ 低优先级问题

#### 问题 6：文档版本管理不规范

**问题描述：**
- 部分文档有版本号（如 AGENTS.md v2.7）
- 部分文档无版本号（如 SOUL.md）
- 更新时间记录不一致

**建议改进：**
1. 所有核心文档增加版本号
2. 统一更新时间格式（ISO 8601）
3. 增加变更日志（CHANGELOG.md）

---

#### 问题 7：测试档案未清理

**问题描述：**
存在多个测试档案：
- `other-contacts/test_new_01/`
- `employees/测试员工_test001/`
- `employees/测试员工_test003/`

**影响：**
- 干扰统计数据
- 增加同步脚本负担

**建议改进：**
1. 定期清理测试档案
2. 测试档案使用独立目录（如 `test-contacts/`）
3. 同步脚本自动跳过测试目录

---

## 四、改进建议

### 4.1 短期改进（1-2 周）

#### 建议 1：增强同步脚本健壮性

**目标：** 确保 user_index.json 与档案目录 100% 同步

**措施：**
1. 在 `sync_user_index.py` 中增加重试机制（最多 3 次）
2. 同步失败时回滚档案创建
3. 增加同步日志（记录每次同步结果）
4. 同步失败时通知 owner

**实施步骤：**
```bash
# 1. 修改 sync_user_index.py
nano skills/user-onboard/scripts/sync_user_index.py

# 2. 增加重试逻辑
def call_update_script(contact_id, *args):
    max_retries = 3
    for i in range(max_retries):
        try:
            # 调用 update_user_index.py
            ...
            return True
        except Exception as e:
            if i == max_retries - 1:
                return False
            time.sleep(1)

# 3. 测试验证
python3 skills/user-onboard/scripts/sync-all-to-user-index.py
```

---

#### 建议 2：增加渠道状态监控

**目标：** 实时掌握渠道激活状态

**措施：**
1. 创建渠道状态监控脚本
2. 每日生成未激活用户列表
3. 运营人员手动引导激活

**监控脚本示例：**
```bash
#!/bin/bash
# check_channel_status.sh

echo "=== 渠道激活状态检查 ==="
echo ""

# 读取 user_index.json 中的所有 contactId
contactIds=$(cat user_index.json | jq -r 'keys[]')

for contactId in $contactIds; do
    # 调用 tutu API 检查渠道状态
    status=$(curl -s -X POST https://tutu-gateway.lovebenefits.com/... \
        -d "{\"contactId\":\"$contactId\"}" | jq -r '.status')
    
    if [ "$status" != "active" ]; then
        echo "⚠️  $contactId: 渠道未激活"
    fi
done
```

---

#### 建议 3：统一档案目录结构

**目标：** 所有档案使用统一格式

**措施：**
1. 制定档案目录规范
2. 迁移旧格式档案
3. 更新同步脚本

**规范示例：**
```
# 标准格式
other-contacts/{contactId}/profile.json
employees/{姓名}_{contactId}/{姓名}_{contactId}_profile.json

# 禁止格式
other-contacts/phone-{phone}/  # 不使用手机号作为目录名
other-contacts/{name}/         # 不使用姓名作为目录名
```

---

### 4.2 中期改进（1-2 月）

#### 建议 4：建立档案管理界面

**目标：** 运营人员可自助管理档案

**功能：**
1. 查看档案列表（按角色筛选）
2. 手动同步档案到 user_index.json
3. 查看渠道激活状态
4. 导出档案数据

**技术选型：**
- 前端：简单 HTML 页面
- 后端：Python Flask/FastAPI
- 数据：直接读取 workspace 文件

---

#### 建议 5：优化活动名称映射管理

**目标：** 降低映射表维护成本

**措施：**
1. 统一映射表位置（仅 config/activity-name-mapping.json）
2. 增加映射表验证脚本
3. 支持运营人员自助更新

**映射表格式优化：**
```json
{
  "version": "1.0",
  "updatedAt": "2026-04-28",
  "mappings": [
    {
      "id": "map-001",
      "keywords": ["医道微光", "精准免疫"],
      "actualName": "精准免疫肿瘤诊疗管理",
      "shortUrl": "https://fjhma.com/1DL8uI",
      "active": true
    }
  ]
}
```

---

### 4.3 长期改进（3-6 月）

#### 建议 6：引入数据库存储

**目标：** 替代文件存储，提高数据一致性

**当前架构：**
```
文件存储：user_index.json + 档案目录
```

**目标架构：**
```
SQLite/PostgreSQL 数据库
├── users 表（contactId, name, role, verified, ...）
├── profiles 表（详细档案信息）
├── sessions 表（会话状态）
└── memories 表（记忆内容）
```

**优势：**
- 数据一致性保证（事务支持）
- 查询性能提升（索引支持）
- 备份恢复方便
- 支持复杂查询（如统计、分析）

---

#### 建议 7：建立自动化测试体系

**目标：** 确保建档流程稳定性

**测试覆盖：**
1. 新用户建档流程测试
2. 老用户会话启动测试
3. 身份核验 API 测试
4. 同步脚本测试
5. 渠道激活测试

**测试框架：**
- Python pytest
- 模拟 API 响应
- 自动化执行 + 报告生成

---

## 五、风险评估

### 5.1 风险矩阵

| 风险 | 可能性 | 影响 | 风险等级 | 缓解措施 |
|------|--------|------|----------|----------|
| user_index.json 不同步 | 中 | 高 | 🔴 高 | 增加重试 + 监控告警 |
| 渠道未激活导致通知失败 | 高 | 中 | ⚠️ 中 | 手动引导 + 状态监控 |
| API 调用失败 | 低 | 高 | ⚠️ 中 | 重试机制 + 降级处理 |
| 档案数据泄露 | 低 | 高 | ⚠️ 中 | 权限控制 + 数据隔离 |
| 映射表过时 | 中 | 低 | ℹ️ 低 | 定期审查 + 自助更新 |

---

### 5.2 应急预案

#### 预案 1：user_index.json 损坏

**症状：**
- 所有用户无法识别
- 会话启动失败

**应急步骤：**
```bash
# 1. 备份当前文件
cp user_index.json user_index.json.bak

# 2. 从档案目录重建
python3 skills/user-onboard/scripts/sync-all-to-user-index.py

# 3. 验证重建结果
cat user_index.json | jq 'keys | length'
```

---

#### 预案 2：API 调用大面积失败

**症状：**
- 身份核验失败
- 活动查询失败
- 订单查询失败

**应急步骤：**
```bash
# 1. 检查 API 状态
curl -X POST https://api.yihu.com/OpenPlatform/cgiBin/1.0/...

# 2. 切换备用 API（如有）
# 修改 config/api-config.json

# 3. 降级处理
# 告知用户"系统繁忙，请稍后再试"
# 记录失败日志，后续补偿
```

---

#### 预案 3：渠道大面积未激活

**症状：**
- 工单通知发送失败
- 欢迎词无法发送

**应急步骤：**
```bash
# 1. 生成未激活用户列表
./scripts/check_channel_status.sh > unactivated_users.txt

# 2. 运营人员手动引导
# 通过短信/电话通知用户主动发消息

# 3. 验证激活结果
# 重新运行检查脚本
```

---

## 六、总结

### 6.1 架构优势

1. **权限清晰**：owner/employee/other-contacts 三级权限明确
2. **数据隔离**：用户之间数据互不可见，隐私保护好
3. **流程自动化**：身份核验、建档、同步流程已自动化
4. **灵活扩展**：技能分层架构支持快速扩展

---

### 6.2 主要问题

1. **同步风险**：user_index.json 与档案目录存在不同步风险
2. **渠道依赖**：tutu-aggchat 需用户主动发消息才能激活
3. **文档分散**：映射表、SESSION_STATE 等文件位置不统一
4. **测试缺失**：缺乏自动化测试体系

---

### 6.3 优先级建议

| 优先级 | 改进项 | 预计工时 |
|--------|--------|----------|
| P0 | 增强同步脚本健壮性 | 1 天 |
| P0 | 增加渠道状态监控 | 1 天 |
| P1 | 统一档案目录结构 | 2 天 |
| P1 | 优化活动名称映射管理 | 2 天 |
| P2 | 建立档案管理界面 | 1 周 |
| P2 | 引入数据库存储 | 2 周 |
| P3 | 建立自动化测试体系 | 1 周 |

---

## 附录

### A. 相关文件清单

| 文件 | 说明 |
|------|------|
| `AGENTS.md` | 小医工作指南（主文档） |
| `docs/user-service-flow.md` | 用户服务全流程 |
| `docs/user-index-sync-fix.md` | user_index.json 同步问题修复报告 |
| `docs/issue-tracker-20260427.md` | 问题执行清单 |
| `docs/history-issues-tracker.md` | 历史问题追踪 |
| `skills/user-onboard/SKILL.md` | 用户身份核验技能 |
| `skills/other-contacts-onboard/SKILL.md` | 外部用户建档技能 |
| `config/skill-manifest.json` | 技能清单 |
| `config/activity-name-mapping.json` | 活动名称映射表 |
| `employees/employee_list.json` | 员工预置名单 |
| `config/operators.json` | 运营人员配置 |

---

### B. 关键脚本清单

| 脚本 | 用途 |
|------|------|
| `skills/user-onboard/scripts/check_contactId.py` | 身份核验脚本 |
| `skills/user-onboard/scripts/sync-all-to-user-index.py` | 全量同步脚本 |
| `skills/user-onboard/scripts/update_user_index.py` | user_index.json 更新脚本 |
| `skills/user-onboard/scripts/verify_user.py` | 身份核验（含重试） |
| `skills/user-onboard/scripts/archive.py` | 建档脚本 |

---

### C. 术语表

| 术语 | 说明 |
|------|------|
| contactId | tutu-aggchat 分配的用户短 ID（8 位） |
| user_index.json | 全局用户索引文件 |
| verified | 身份核验状态（true/false） |
| SESSION_STATE | 会话状态文件（WAL 协议） |
| tutu-aggchat | 企业微信聚合聊天通道 |
| WAL Protocol | Write-Ahead Logging 写前日志协议 |

---

_报告生成时间：2026-04-28 10:53_  
_分析范围：/home/admin/.openclaw/workspace（277 个 .md 文件）_  
_版本：v1.0_