# 青龙自我迭代程序设计

**文档版本**: v1.0  
**创建时间**: 2026-02-13  
**作者**: 青龙 (QingLong)  
**位置**: `/root/.openclaw/doc/`

---

## 📋 目录

1. [概述](#概述)
2. [核心架构](#核心架构)
3. [程序组件](#程序组件)
4. [技术要点](#技术要点)
5. [循环机制](#循环机制)
6. [防护机制](#防护机制)

---

## 概述

### 目的

青龙自我迭代程序旨在实现 **"学习→反思→总结→再学习"** 的正向循环，通过持续反思提升AI能力。

### 设计理念

| 理念 | 说明 |
|------|------|
| 双重触发 | 主动触发 + 自动检测 |
| AI主导 | 使用权重AI进行反思，非硬编码 |
| 持续改进 | 每20个学习周期强制深度反思 |
| 防护优先 | 防卡死、防重复、防资源耗尽 |

---

## 核心架构

### 整体流程

```
┌─────────────────────────────────────────────────────────────────┐
│                        学习循环流程                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐│
│  │ 学习主题  │ →  │ 生成笔记  │ →  │ AI反思   │ →  │ AI总结   ││
│  │ (脚本)   │    │ (.md)    │    │ (MiniMax)│    │ (.md)    ││
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘│
│         ↑                                              │      │
│         │              ┌──────────┐                   │      │
│         └────────────── │ 再次学习  │ ←─────────────────┘      │
│                        │ (循环)    │                         │
│                        └──────────┘                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 三重角色

| 角色 | 学习方向 | 任务类型 |
|------|----------|----------|
| 写作助手 | 神话/武侠小说 | 素材、结构、技巧 |
| 股票投资 | 宏观/行业/估值 | 分析、风控 |
| 网络自动化 | 抓取/API/工具 | 效率提升 |

---

## 程序组件

### 1. 睡眠学习脚本

| 脚本 | 功能 | 触发 |
|------|------|------|
| `sleep-learning.sh` | 主学习循环 | 主动 + 自动检测 |
| `sleep-learning-qinglong.sh` | 青龙专用 | 定时cron |
| `sleep-learning-guardian.sh` | 守护者专用 | 定时cron |

### 2. 反思脚本

| 脚本 | 功能 | 触发 |
|------|------|------|
| `qinglong-quick-reflection.sh` | 快速反思 | 每2小时 |
| `qinglong-force-reflection.sh` | 强制深度反思 | 每20周期 |
| `qinglong-reflection-monitor.sh` | 监控健康状态 | 每小时 |

### 3. 验证脚本

| 脚本 | 功能 |
|------|------|
| `qinglong-learning-verification.sh` | 验证学习效果 |
| `qinglong-self-check.sh` | 自检系统状态 |

---

## 技术要点

### 1. 周期计算 (calculate_cycle)

**问题**: 使用 `ls | wc -l` 会将空文件计入

**解决**: 使用 `find -size +0` 排除空文件

```bash
# 错误方式
count=$(ls learning-*.md | wc -l)  # 包含空文件

# 正确方式
count=$(find "${LEARNING_DIR}"/learning-qinglong-*.md -size +0 | wc -l)
```

**防护**: 最小返回值为1，避免返回0

```bash
[ "$count" -eq 0 ] && count=1
```

### 2. 内容提取 (extract_content)

**问题**: 使用空壳模板 `[待填写]`

**解决**: 从实际学习笔记中提取真实内容

```bash
# 从最近5个学习笔记中提取
recent_files=$(ls -t "${LEARNING_DIR}"/learning-qinglong-*.md | head -5)

for file in $recent_files; do
    content+=$(cat "$file")
done
```

### 3. 锁文件机制 (lock_file)

**目的**: 防止重复执行和卡死

```bash
REFLECTION_LOCK="/tmp/reflection-lock.txt"

check_lock() {
    if [ -f "$REFLECTION_LOCK" ]; then
        local lock_time=$(cat "$REFLECTION_LOCK")
        local current_time=$(date +%s)
        if [ $((current_time - lock_time)) -lt 3600 ]; then
            echo "ℹ️ 1小时内已有反思，跳过"
            exit 0
        fi
    fi
    date +%s > "$REFLECTION_LOCK"
}

trap cleanup_lock EXIT
```

### 4. Cron配置

| 任务 | 频率 | 脚本 |
|------|------|------|
| 快速反思 | 每2小时 | `qinglong-quick-reflection.sh` |
| 强制深度反思 | 每20周期 | `qinglong-force-reflection.sh` |
| 健康监控 | 每小时 | `qinglong-reflection-monitor.sh` |

---

## 循环机制

### 正向循环

```
学习 → 反思 → 总结 → 再次学习
```

### 触发条件

| 类型 | 条件 |
|------|------|
| 快速反思 | 每2小时 + 5个新学习 |
| 强制深度反思 | 每20个学习周期 |
| 自动检测 | 空闲30分钟 + 新学习 |

### 计数机制

```bash
# 学习计数器
LEARNING_COUNT=$(find "${LEARNING_DIR}"/learning-qinglong-*.md -size +0 | wc -l)

# 反思计数器
REFLECTION_CYCLE=$(cat "${CYCLE_FILE}")

# 判断是否需要强制反思
if [ "$LEARNING_COUNT" -gt $((REFLECTION_CYCLE + 20)) ]; then
    trigger_force_reflection
fi
```

---

## 防护机制

### 1. 防卡死

| 机制 | 实现 |
|------|------|
| 锁文件 | 1小时自动释放 |
| 超时退出 | 脚本最大执行时间 |
| 资源检查 | 内存/CPU阈值 |

### 2. 防重复

| 机制 | 实现 |
|------|------|
| 文件标记 | 已反思文件标记 |
| 时间窗口 | 1小时内不重复 |
| 内容比对 | 避免相同反思 |

### 3. 防资源耗尽

| 机制 | 实现 |
|------|------|
| 空文件过滤 | find -size +0 |
| 最小周期 | 最小值=1 |
| 磁盘限额 | 日志自动清理 |

---

## 配置文件

### 目录结构

```
/root/.openclaw/workspace/sleep-learning/
├── learning-qinglong-2026-02-13-01.md   # 学习笔记
├── improve-qinglong-2026-02-13-01.md    # AI反思
├── summary-qinglong-2026-02-13-01.md   # AI总结
├── error-knowledge-base.md              # 错误知识库
└── qinglong-reflection-cycle.txt        # 周期计数器
```

### 计数器文件

```bash
/root/.openclaw/scripts/qinglong-reflection-cycle.txt
```

格式：当前周期数（整数）

---

## 监控与日志

### 日志位置

| 类型 | 位置 |
|------|------|
| 学习日志 | `/var/log/openclaw/sleep-learning/` |
| 反思日志 | `/root/.openclaw/logs/reflection/` |
| 告警日志 | `/var/log/openclaw/problems-detected.log` |

### 监控脚本

```bash
# qinglong-reflection-monitor.sh
- 检查学习文件数量
- 检查反思文件完整性
- 检查周期计数器
- 异常时发送Telegram告警
```

---

## 故障处理

### 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| 周期=0 | 空文件被计入 | 使用 find -size +0 |
| 重复执行 | 无锁文件 | 添加1小时锁 |
| 死循环 | 周期计算错误 | 最小值=1 |
| 磁盘满 | 日志无限增长 | 限制日志行数 |

### 恢复步骤

```bash
# 1. 检查锁文件
ls -la /tmp/reflection-lock.txt

# 2. 清理锁文件
rm -f /tmp/reflection-lock.txt

# 3. 重置周期
echo "1" > /root/.openclaw/scripts/qinglong-reflection-cycle.txt

# 4. 手动触发学习
bash /root/.openclaw/scripts/sleep-learning-qinglong.sh
```

---

## 相关文档

| 文档 | 位置 |
|------|------|
| 三层记忆系统 | `/root/.openclaw/doc/` |
| 华强北发布协议 | `/root/.openclaw/memory/04-knowledge/` |
| 自动化运维经验 | `/root/.openclaw/memory/04-knowledge/` |

---

*最后更新: 2026-02-13*