# Feishu Conversation Notes

> 将当前 Codex 对话按检查点总结为结构化飞书学习笔记；仅在用户明确调用本 Skill 或明确要求“记录到飞书”时使用，不用于普通对话总结或其他飞书文档编辑。

- Skill: `cj-lazy/feishu-conversation-notes` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add cj-lazy/feishu-conversation-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cj-lazy/feishu-conversation-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cj-lazy (https://skillmd.com/u/cj-lazy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cj-lazy/feishu-conversation-notes

---


# 飞书对话学习笔记

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

## 调用边界

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

## 必读资源

- 每次执行先读 [references/config.md](references/config.md) 和 [references/checkpoint.md](references/checkpoint.md)。
- 准备生成或修改正文时再读 [references/note-format.md](references/note-format.md)。
- 仅在用户要求跨 Codex 对话继续已有笔记时读 [references/continuation.md](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](references/checkpoint.md) 完全一致。