lark-workflow-prd-sync

PRD 文档工作流

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md（若存在），其中包含 lark-cli 的认证、权限处理

---

PRD 三件套定位

write-a-prd ────► [本 skill: prd-sync] ────► prd-to-userstory
   (创建)              (同步/维护)               (拆成 Story)

本 skill 是「同步/维护」环节，独立可用：

• 上游可以是 write-a-prd 生成的 PRD（自带 frontmatter），也可以是手写/历史 PRD（旧版本注释）
• 下游是 prd-to-userstory，通过 frontmatter 与 [HANDOFF] 块传递上下文

---

适用场景

• "帮我从飞书下载这个 PRD 并整理好"
• "把飞书文档里的评论整理成 Open Questions"
• "根据详细设计更新整体变更和功能清单"
• "把本地改好的 PRD 同步回飞书"
• "prd sync" / "prd同步"

所需 OAuth Scopes（user 身份）

# 读取文档
lark-cli auth login --scope "docx:document:readonly"

# 读取评论
lark-cli auth login --scope "docs:document.comment:read"

# 更新文档（同步回飞书时）
lark-cli auth login --scope "docx:document:write_only docx:document:readonly"

说明：多次 login 的 scope 会累积（增量授权），无需重复授权已有 scope。

---

Step 0：版本号自动维护规则

每次同步前先识别「本次变更规模」，按下表自动维护本地 PRD 顶部的「版本信息」与「变更日志」表：

变更规模	版本号增长	判定标准
大版本（major）	1.x → 2.0	§4 详细设计大幅重写、§5 功能清单新增/删除 ≥ 5 行、整体方案换路
小版本（minor）	1.0 → 1.1	局部章节微调、零散字段更新、评论解决/补充、OQ 状态变化、版本日志补登

操作清单：

1. 更新 frontmatter.version
2. 在「§1 版本信息」表的版本号字段更新为新版本号
3. 在「§2 变更日志」表追加一行新记录（时间、版本号、变更人、主要变更内容）
4. 同步飞书时也要替换飞书侧的「变更日志」表（用 block_replace）

---

完整工作流

飞书文档 URL 或本地 .md 路径
    │
    ▼
Step 0.5: 识别 PRD 元数据来源
          ├─► 有 frontmatter → 直接读 feishu_url / feishu_doc_token
          ├─► 有 <!-- 飞书文档：URL --> 注释（旧版本）→ 解析 URL，本次同步后补写 frontmatter
          └─► 都没有 → AskUserQuestion 让用户提供飞书 URL
    │
    ▼
Step 1: 下载文档 → 保存 .md 到 prd/YYYY/M/（保留/补全 frontmatter）
    │
    ▼
Step 2: 拉取所有评论
    ├─► 2.1 未解决评论 → 写入/更新 §6 Open Questions
    └─► 2.2 已解决评论 → 删除本地 ⚠️ [评论] 标记 + 更新 OQ 状态为「已解决」
    │
    ▼
Step 3: 分析 §4 需求详细设计
    │
    ├─► 更新 §3.1 整体变更（每条需求对应一行）
    └─► 更新 §5 功能清单（每个功能点对应一行）
    │
    ▼
Step 4: 如有未解决 OQ → 在文档标题末尾追加 -draft
    │
    ▼
Step 5: 按 Step 0 规则更新版本号 + 变更日志 + frontmatter.version
    │
    ▼
Step 6: 增量同步回飞书（只更新 §3.1 / §5 / §6 / §2 变更日志，不触碰 §4）
    │
    ▼
Step 7: 输出 [HANDOFF] 块 → 供下游 prd-to-userstory 消费