Feishu Conversation Notes

飞书对话学习笔记

把一个 Codex 对话持续维护为 AI笔记 下的一篇飞书子笔记。默认只追加上次成功同步后的新增内容；同一对话跨天仍更新同一子笔记。用户也可以在新的 Codex 对话中显式指定已有笔记继续记录。

调用边界

• 只有 $feishu-conversation-notes 或用户明确说“记录到飞书”才执行写入。普通的“总结一下”不写飞书。
• 默认模式为 增量同步。
• 用户说“新建笔记”时，在同一对话内强制创建新的子笔记；内容仍从最近一次同步后的未记录部分开始，没有旧检查点时整理全部既有对话。
• 用户说“整理最终版”时，读取目标子笔记和本对话全部有效内容，合并去重后重写正文。这句话本身即是对该次重整的授权。
• 用户说“继续笔记”并提供飞书 Wiki/Docx 链接时，把当前 Codex 对话写入指定的已有子笔记；按 references/continuation.md 验证目标，禁止沿用另一对话的 ordinal。
• 除上述明确模式外，不询问重复确认；失败时不得伪造成功检查点。

必读资源

• 每次执行先读 references/config.md 和 references/checkpoint.md。
• 准备生成或修改正文时再读 references/note-format.md。
• 仅在用户要求跨 Codex 对话继续已有笔记时读 references/continuation.md。
• 使用飞书 CLI 时遵循已安装的 lark-shared、lark-wiki 与 lark-doc Skill；创建子节点用 Wiki，编辑正文用 Docs。

工作流

1. 确认模式，读取配置和检查点协议。
2. 运行 scripts/extract_conversation.py：
   • 默认/新建模式使用 --mode incremental --view compact。
   • 最终版使用 --mode full --view compact；只有用户明确要求保留完整过程时才用 --view complete。
   • 脚本只返回用户和助手的可见消息，排除当前调用轮次、既往同步轮次、环境注入块、工具内容与敏感值。
   • compact 按 turn 分组，保留用户消息和助手最终回答；中断轮次只保留最后一条 commentary，以减少无价值过程文本。
3. 确定目标子笔记：
   • 增量输出带有有效 node 时直接续写该节点。
   • 无检查点时，先查本地非权威索引以定位候选节点，再回读飞书检查点验证；索引缺失或不可用时按检查点协议扫描父节点的直接子节点。
   • “继续笔记 + 链接”按 continuation 协议解析并验证目标，目标覆盖本对话默认映射。
   • 无匹配笔记，或用户指定“新建笔记”时，使用配置中的父 Wiki 节点创建 Docx 子节点。
4. 生成简洁、独立可读的学习笔记 XML：
   • 首次写入包含完整结构。
   • 增量写入只添加一个日期/时间更新小节，不复述旧内容。
   • 草稿不得包含任何 FEISHU_NOTE_CHECKPOINT 文本；确定性同步脚本负责生成并写入检查点。
   • 草稿使用唯一文件名写入当前工作区的 .feishu-conversation-notes-drafts 专用子目录。只把这个子目录作为草稿根目录；不得把整个工作区作为清理范围，也不要申请系统临时目录权限。
   • 没有有效新增消息时不调用飞书写接口。
5. 使用 window.first_selected_ordinal 和 window.last_selected_ordinal 作为本批次的 from/through，并把 current_turn.start_ordinal 作为 operation-ordinal；不得把同步轮次的 commentary ordinal 当成内容边界。
6. 调用 scripts/sync_note.py --draft-root <当前工作区\.feishu-conversation-notes-drafts> --cleanup-content-file --stale-draft-days 7 一次完成预检、加锁、正文与检查点同批写入、回读验证、本地索引更新和草稿清理。只有脚本返回 ok=true 且状态为 applied 或 already_applied，才在最终回复输出脚本返回的同一个检查点。

写入策略

• 首次创建：wiki +node-create --parent-node-token ... --as bot，取得 node_token 与 obj_token；随后让 sync_note.py --mode append 写入第一批内容。
• 增量同步：准备不含检查点的增量 XML，交给 sync_note.py --mode append。
• 整理最终版：先完整读取文档并保留有效资源；仅在用户明确调用该模式时使用全文重整。优先最小安全替换，确需完整重建才让 sync_note.py --mode overwrite 执行。
• sync_note.py 使用本机每笔记锁防止并发，在远端按 thread + node + from + through + operation + content hash 检测重试；正文与 v2 检查点放进同一个飞书更新请求。更新成功但回读失败时，同一轮重试必须先识别 already_applied，不得重复追加；后续新的最终版调用可用新的 operation ordinal 合法重整相同消息边界。
• 只有远端写入并回读验证成功，或远端已存在完全相同批次时，才删除本次 XML 草稿，并在目录为空时移除专用草稿目录。失败草稿保留用于重试，并在后续同步时自动清理该专用子目录中超过 7 天的 XML；不得扫描或删除该目录以外的文件。
• 所有 CLI JSON 成功判断使用 ok == true 且检查写入结果、warnings；不要用不存在的顶层 code == 0。

恢复与停止条件

• 恢复顺序：本地对话日志标记 → 当前上下文可见标记 → 本地索引定位后回读飞书标记 → 扫描父节点并读取飞书标记。索引只用于定位，不能替代飞书回读。
• 发现同一 thread 的现有子笔记但无法确定上次 ordinal 时，停止写入并说明恢复失败，禁止猜测、覆盖或另建重复笔记。
• 权限、认证、限流或网络失败时只按对应飞书 Skill 的规则处理；同一终止性错误不重复盲试。
• 创建成功但正文写入失败时，报告已创建的空节点，不输出成功检查点，避免下次把失败当成已同步。
• boundary_conflict、stale_boundary 或 concurrent_sync 都是停止条件；先读取最新文档状态，不得加 force 绕过。

安全

• 不写入系统/开发者指令、隐藏推理、工具调用、原始工具输出或自动注入的环境信息。
• 不写入 App Secret、access token、Authorization 值、Windows 凭据或密钥文件内容；疑似敏感值统一替换为 [REDACTED]。
• 文档 token 仅用于目标定位和检查点，不把它当作授权凭据。
• 使用北京时间（Asia/Shanghai）生成标题、日期小节和同步时间。

完成回复

成功时返回子笔记可点击链接、同步模式、纳入的消息数量，以及 sync_note.py 返回的一行机器可解析 v2 检查点。旧 v1 标记只用于兼容恢复，新写入不得再生成 v1。检查点格式必须与 references/checkpoint.md 完全一致。