@lark-project/cli/skills/meegle-plugin/references/checkpoint.md

飞书项目插件开发工具

# Checkpoint 更新协议

> **前置**：本段是 shared 主文件"Checkpoint（进度追踪）"的完整规则。子 skill 在被 workflow phase 编排且需要写 checkpoint 时按需 Read。

## 读写走 `lpm ai state`（路径由 CLI 锚定到插件根）

state.json 的读写一律走 CLI，路径经 `workspacePaths()` 解析到插件根、`assertPluginRoot` 守卫，配合 `--cwd` 在任意 cwd 都落到插件的 `.lpm-cache/state.json`：

```bash
# 读（输出空 = 无 checkpoint）
lpm --cwd "<projectRoot>" ai state get

# 写（接 inline JSON / @file / @- 读 stdin；每次写全量对象，覆盖式）
lpm --cwd "<projectRoot>" ai state set '<完整 state JSON>'
```

`set` 是覆盖式——每次把完整 state 对象写回（与既有约定一致）；构造新对象时在上一次 `get` 的结果上改字段。

## 适用条件

子 skill 执行前用 `lpm --cwd "<projectRoot>" ai state get` 读 checkpoint：
- **有输出** → 当前处于 workflow 编排中，每步 CLI 前后用 `lpm ai state set` 更新（走本文件协议）
- **空输出** → 子 skill 被独立调用，不需要写 checkpoint（跳过本文件）

## 更新协议

每次更新都用 `lpm --cwd "<projectRoot>" ai state set '<完整 JSON>'` 写回完整对象：

```
CLI 命令执行前：
  → 写入 nextCommand、nextStep，lastCommandStatus 设为 "running"

CLI 命令执行后（成功）：
  → lastCommand = 刚执行的命令
  → lastCommandStatus = "success"
  → nextCommand/nextStep 更新为下一步

CLI 命令执行后（失败）：
  → lastCommand = 刚执行的命令
  → lastCommandStatus = "failed"
  → 保留 nextCommand/nextStep 不变（重试时使用）
```

## 恢复语义

当 workflow 从 checkpoint 恢复并调用子 skill 时，子 skill 应检查 `lastCommand` + `lastCommandStatus`：
- 上一步 `"success"` → 跳过该步，执行下一步
- 上一步 `"failed"` → 重试该步
- 上一步 `"running"` → 未知状态，重新执行该步