# ATOM-DOC-029 - 更新飞书原子动作清单

> 版本：V1.0  
> 状态：🆕 新建  
> 最后更新：2026-03-07 14:14

---

## 📋 动作定义

**名称：** 更新飞书原子动作清单  
**分类：** 文档层（Documentation Layer）  
**编号：** ATOM-DOC-029

**一句话描述：** 同步本地原子动作变更到飞书文档（版本记录 + 表格内容）

---

## 🎯 输入输出

### 输入
- **类型：** 原子动作变更信息
- **内容：** 
  - 动作编号（如 ATOM-DELIVERY-013）
  - 变更类型（新增/修改/删除）
  - 变更内容（名称/描述/偏好）
  - 变更时间
- **必填：** 是

### 输出
- **类型：** 布尔值
- **内容：** 飞书文档更新成功/失败
- **附加：** 更新后的版本号

---

## ⚙️ 偏好设置

### 版本管理
- **版本号格式：** V{主版本}.{次版本}（如 V1.1, V2.0）
- **版本记录位置：** 飞书文档开头
- **版本递增：** 次版本 +1（如 V1.0 → V1.1）

### 更新策略
- **分块写入：** ≤200 blocks/次（避免 400 错误）
- **增量更新：** 不覆盖历史内容
- **版本记录：** 每次更新添加新行

### 同步机制
- **触发时机：** 原子动作增删改后
- **同步范围：** 飞书文档 + MD 文件 + TXT 文件
- **一致性检查：** 三线同步完成确认

---

## 📝 操作步骤

```powershell
# 1. 读取本地原子动作信息
$actionInfo = Get-Content "atomic-actions/03-delivery/ATOM-DELIVERY-013.md" -Raw
$newVersion = "V1.1"
$changeTime = Get-Date -Format "yyyy-MM-dd HH:mm"
$changeDesc = "新增锁屏检测功能"

# 2. 读取飞书文档当前版本
$docToken = "GeG0dywMxof8dLx1tcUckSFNndh"
$currentContent = Invoke-RestMethod "https://open.feishu.cn/open-apis/docx/v1/documents/$docToken/raw_content"

# 3. 更新版本记录表（在开头添加新行）
$newVersionRow = "| $newVersion | $changeTime | $changeDesc | 阿福 |"
$updatedContent = $currentContent -replace "(\| V[\d.]+ \|.*\|.*\|)", "`n$newVersionRow`n`$1"

# 4. 更新原子动作表格（找到对应分类，添加/修改行）
# 查找对应分类表格，更新对应行

# 5. 更新总览信息（总数 + 最后更新时间）
$updatedContent = $updatedContent -replace "总数：\d+ 个", "总数：29 个"
$updatedContent = $updatedContent -replace "最后更新：.*", "最后更新：$changeTime"

# 6. 分块写入飞书文档（调用 ATOM-FEISHU-028）
# 第 1 块：版本记录 + 部分表格（write 模式）
# 第 2 块：剩余表格（append 模式）
# 第 3 块：说明 + 日志（append 模式）

Write-Host "✅ 飞书文档更新完成！"
return $true
```

---

## 🔄 使用场景

### 场景 1：新增原子动作
```
触发：创建 ATOM-FEISHU-028
  ↓
调用：ATOM-DOC-029
  ↓
更新：版本记录（V1.0→V1.1）+ 交付层表格（+1 行）
  ↓
同步：飞书文档 + MD + TXT
```

### 场景 2：修改原子动作
```
触发：修改 ATOM-DELIVERY-013（锁屏检测）
  ↓
调用：ATOM-DOC-029
  ↓
更新：版本记录（V1.1→V1.2）+ 交付层表格（更新偏好）
  ↓
同步：飞书文档 + MD + TXT
```

---

## 🔗 关联动作

### 前置动作
- 原子动作增删改操作（MD + TXT 已更新）

### 后置动作
- ATOM-FEISHU-028：写入飞书文档（分块）

### 常组合使用
- 原子动作更新 + ATOM-DOC-029 + ATOM-FEISHU-028
  （三线同步）

---

## ✅ 检查清单

执行前确认：
- [ ] 本地 MD/TXT 已更新
- [ ] 飞书文档 Token 正确
- [ ] 有编辑权限
- [ ] 版本号正确递增
- [ ] 版本记录格式正确

---

## ⚠️ 常见错误

### 错误 1：忘记更新飞书文档
```
❌ 错误：只更新本地 MD/TXT，飞书文档未同步
✅ 正确：调用 ATOM-DOC-029 自动同步
```

### 错误 2：版本号错误
```
❌ 错误：版本号不递增或格式错误
✅ 正确：V{主版本}.{次版本}，次版本 +1
```

### 错误 3：一次性写入太多
```
❌ 错误：一次性写入全部内容 → 400 错误
✅ 正确：分块写入（≤200 blocks/块）
```

---

## 💡 核心原则

> **线上线下同步更新，不能只更新一方！**

**三线同步：**
- ✅ 飞书文档（云端协作）
- ✅ MD 文件（本地模块）
- ✅ TXT 文件（人类可读）

**触发时机：**
- 原子动作增删改后立即触发
- 自动同步，不用手动

---

_模块化定义 | 可独立调用 | 三线同步 | 2026-03-07_
