lark-comment-loop

飞书文档评论闭环（lark-comment-loop）

拉一篇 docx 的未解决评论 → 按时间过滤到"今天的" → 归类 → 编号 propose 等确认 → 确认后逐条最小半径落改 → 逐条回复说明改法 → 按模式决定是否 resolve → 大改提议新版本。

两条线规矩相反，别弄反：

• PRD 迭代线 = 改完 resolve（模式 resolve；writing-prds 委托本 skill 时显式传）。
• 数据报告线 = 只回复不 resolve（模式 reply-only，本 skill 默认——更安全）。

铁律：propose-first——落改前一律先出编号清单等用户确认，绝不确认前动文档。

关键前置事实

• 飞书评论 API 无服务端时间过滤：file.comments list 不接受 since/until 参数， "只看今天"必须拉全量后客户端按 create_time 过滤（本 skill 的核心新增逻辑）。
• create_time 是 epoch 秒（字符串）。"今天 0 点"按本机时区算。
• 编辑 docx 正文的机制与坑（相对路径 @file、整表 block_replace、@人 cite）见 ~/.claude/skills/writing-prds/lark-editing.md——本 skill 只管评论回路，正文落改照那份。
• lark-cli 版本注记：1.0.52 skills 与 1.0.60 binary 不同步、1.0.65 可升——本波不升级， 遇命令行为异常先核 lark-cli skills read lark-doc 拿当前 schema，不要自行升级。

七步流程

1. 输入解析

• 文档：接受 docx token 或完整 URL（URL 取 /docx/ 后那段 token）。file_type 固定 docx。
• --since：默认今天 0 点（本机时区）。用户给别的（"这周""昨天起"）就换算成 epoch 秒。 取今天 0 点 epoch：

  SINCE=$(date -v0H -v0M -v0S +%s)   # macOS BSD date；本机时区
  

• 模式：resolve | reply-only，默认 reply-only。writing-prds 场景显式传 resolve。
• 可选 --verify：跑完派 codex 逐条核对闭环（见第 7 步）。

2. 拉取 + 客户端时间过滤

# 拉全部未解决评论（分页拉全）
lark-cli drive file.comments list \
  --params '{"file_token":"<docx_token>","file_type":"docx","is_solved":false}' \
  --page-all

拉回后客户端按 create_time >= SINCE 过滤（API 无服务端过滤）：

# 上一条命令的 JSON 存为 comments.json，SINCE 为今天 0 点 epoch
jq --arg since "$SINCE" \
  '[.data.items[] | select((.create_time|tonumber) >= ($since|tonumber))]' \
  comments.json

• create_time 是 epoch 秒。实测（2026-07-05，docx file.comments list）返回的是 JSON 数字（如 1781763012），并非字符串——故上面的 tonumber 是防御性写法（对数字幂等，对字符串也生效），两种类型都能正确比较，保留即可。分页路径 .data.items[] 已实测一致；返回结构为 {code,msg,data:{items[],has_more,page_token}}。
• 过滤后 0 条 → 直接汇报"今天无新评论"，结束，不进后续步骤。
• 每条评论保留 comment_id 与最新一条 reply 的正文/quote（定位文中位置）。

3. 归类

把过滤出的评论逐条归入四类（只决定风险标注，不决定是否跳过确认——四类全部进第 4 步统一 propose，确认后才落改）：

• 术语：改名、字段名口径统一 → 标注"低风险"。
• 格式：排版、表格列、双语并列、导航标签 → 标注"低风险"。
• 内容精度：公式、显示规则、跳转预填、数字口径 → 标注"改前核对"，不确定先问。
• 新需求：评论提了新范围/新模块 → 标注"可能大改"，进第 6 步提议新版本。