session-summary

# session-summary - 会话学习总结器 > 在服务器上对话/开发结束时调用，将本次会话中学到的知识写成一篇**有深度、有温度、有干货**的文章。目标是：未来的自己能快速回忆起来，别人读了也能真正学到东西。 ## 触发条件 - 用户说"总结一下"/"帮我总结"/"wrap up"/"记录下来" → **默认风格（个人笔记）** - 用户说"写个专业版"/"正式版"/"给领导看的"/"汇报用" → **专业风格** ## 输出 在当前目录生成 md 文件：`summary-YYYYMMDD-主题slug.md` --- ## 风格选择 本 skill 支持两种写作风格，根据触发词自动判断，或在生成时询问用户： | 风格 | 触发词 | 适用场景 | 核心特征 | |------|--------|----------|----------| | **个人笔记**（默认） | 总结、wrap up、记录 | 自己回顾、分享给同事 | 有人味、有故事感、保留思考过程 | | **专业汇报** | 正式版、给领导看、汇报、专业 | 上传给领导/写入文档 | 逻辑严密、体系化、体现系统思维 | --- ## 风格一：个人笔记（默认） ### 写作哲学 **这不是填表，是写文章。** 生成的内容应该像一个技术功底深厚的人写给朋友看的学习笔记——有思考过程，有恍然大悟的瞬间，有踩坑的真实感受，偶尔也有调侃和吐槽。读起来不累，放下后有收获。 ### 反面教材（不要这样写） ```markdown ### 关键要点 - ✅ 要点 1：xxx - ✅ 要点 2：xxx ### 核心结论 xxx | 维度 | A | B | |------|---|---| ``` 这种写法的问题：看起来信息密度高，实际上**读完记不住**。因为没有上下文、没有推导过程、没有情感连接，大脑不会对此产生深刻记忆。 ### 正面示范（要这样写） ```markdown 之前一直有个困惑：为什么 vllm 的 DP 不像训练那样简单地各跑各的？今天终于想通了—— 训练时每个 batch 是提前切好的，大家自然同步；但推理时请求是随时涌进来的，你不知道 下一秒哪个 rank 有活干、哪个在发呆。偏偏集合通信要求所有人同时参与，一个人不到场 就全卡死。所以 vllm 发明了 wave 的概念：想象成冲浪，所有人必须在同一波浪上， 没浪可冲的人也得假装在冲（dummy batch），否则浪就过不去。 这个设计代价不小——空闲的 rank 要做无意义计算来"陪跑"，但好处是架构简单、不容易死锁。 比起让每个 rank 自由地异步跑（那样 all-reduce 怎么办？），这是一个务实的工程妥协。 ``` ## 写作规则 ### 1. 段落优先，结构化为辅 - **默认用段落叙述**，像讲故事一样展开 - 只在确实需要对比、查阅时才用表格 - 只在步骤确实是线性顺序时才用列表 - 代码片段保留，但必须有前后文解释**为什么看这段代码**、**它在解决什么问题** ### 2. 保留思考过程 - 写出"我原来以为是 A，后来发现其实是 B"的转折 - 写出"最初不理解 X，后来通过 Y 的类比才想通"的恍然大悟 - 写出"这里有个坑，表面上看起来是 P，但实际原因是 Q"的踩坑体验 - 这些才是让文章**有人味、有记忆点**的东西 ### 3. 干货要干到骨头里 - 不要"提到了 X"，要"解释清楚 X 是什么、为什么需要它、它怎么工作" - 不要浮于表面的概述，要深入到"读完这段就能跟别人讲明白"的程度 - 关键代码不仅要贴出来，还要逐行解释设计意图 - 如果某个概念有多种理解角度，选最直觉的那个展开 ### 4. 为"一周后的自己"写作 想象你一周后再看这篇文章，那时你已经忘了大部分细节。问自己： - 这篇文章能让我 3 分钟内回忆起当时学了什么核心东西吗？ - 如果我要给同事讲这个话题，这篇文章够用吗？ - 有没有哪些信息是"当时觉得显然、一周后就想不起来"的？（那些必须写下来） ### 5. 文章结构（灵活运用，不是死板模板） 一篇好的总结文章通常有这些元素（但顺序和形式可以根据内容灵活调整）： - **开头**：一两句话说清楚"今天搞的是什么、为什么要搞它" - **核心理解**：用自己的话把学到的东西讲清楚，这是文章的主体。像跟朋友聊天一样自然展开，遇到复杂概念就用类比、用图、用代码辅助解释 - **关键细节/代码**：贴出最核心的代码片段，配合解释。不是所有代码都贴，只贴那些"不看代码说不清楚"的 - **踩坑/易错点**：以叙述方式写，不是列表。"我最初以为...，结果发现..." - **还没搞懂的**：诚实地标出来，下次继续 ### 6. 语言风格 - 中文为主，技术术语保留英文（如 all-reduce、dummy batch） - 口语化但不随意——像技术博客，不是聊天记录 - 可以有个人感受（"这个设计真的很巧妙"、"这里的命名太容易误导了"） - 避免空洞的形容词（"非常重要"→ 说清楚为什么重要） ## Frontmatter ```yaml --- title: "具体的标题，不要泛泛" date: YYYY-MM-DDTHH:MM:SS+08:00 tags: [具体的技术标签] type: note status: draft source: server session_tool: claude-code|codex|cursor description: "一句话说清楚这篇文章讲了什么" --- ``` ## 文件命名 ``` summary-YYYYMMDD-具体主题slug.md # 好的命名 summary-20260505-vllm-dp-wave-and-dummy-batch.md summary-20260505-deepseek-moe-expert-parallel.md # 不好的命名 summary-20260505-learning.md （太泛） summary-20260505-vllm.md （不具体） ``` ## 处理流程 ### 个人笔记风格 1. 回顾会话中的所有对话，识别核心知识点 2. 在脑中构建"如果跟朋友讲这个话题，我会怎么展开"的叙事线 3. 按照写作规则，用段落式写作把内容展开 4. 关键代码和图表作为辅助穿插其中 5. 生成文件，输出摘要提示 ### 专业汇报风格 1. 回顾会话内容，提炼出**一条主线**（这次解决了什么问题 / 理解了什么系统） 2. 构建逻辑链：问题 → 约束 → 方案 → 实现 → 权衡 → 结论 3. 按逻辑链写作，确保每一段的存在都有前文铺垫 4. 精选代码和图表作为论据（不是装饰） 5. 结尾给出有判断力的结论和启发 6. 生成文件（文件名加 `-report` 后缀） ## 输出提示格式 ``` ✅ 已生成: ./summary-20260505-vllm-dp-wave-and-dummy-batch.md 这篇主要讲了：vllm 推理 DP 为什么需要 wave 同步机制——异步请求 vs 同步集合通信的矛盾， 以及 dummy batch、DP padding 这些工程妥协背后的设计思考。 💡 传到本地后用 server-digest 归档 ``` ## 与 server-digest 的配合 本 skill 在服务器端生成 md 文件 → 用户传到本地 → 本地用 server-digest skill 归档到 Obsidian 知识库 + 可选同步 iwiki。 --- ## 风格二：专业汇报 当用户说"写个专业版"、"正式版"、"给领导看的"、"汇报用的"时，切换到此风格。 ### 写作哲学 **这是写给上级和协作者看的技术文档——体现的是你的系统思维能力和工程判断力。** 读完这篇文档，领导应该能感受到：这个人不只是"学了个东西"，而是**理解了为什么这么设计、它解决什么问题、它的权衡是什么、对我们的工作有什么启发**。 ### 与个人笔记的区别 | 维度 | 个人笔记 | 专业汇报 | |------|----------|----------| | 读者 | 未来的自己、平级同事 | 领导、跨团队协作者 | | 语气 | 口语化、有个人感受 | 正式但不刻板、克制而有力 | | 结构 | 随叙事自然展开 | **严格的逻辑链：问题→分析→方案→权衡→结论** | | 重点 | 学到了什么、怎么想通的 | **为什么重要、对我们意味着什么、建议怎么做** | | 细节 | 保留踩坑和恍然大悟 | 只保留支撑结论的关键证据 | | 代码 | 核心片段 + 个人注释 | 精选片段 + 设计意图分析 | ### 写作规则 #### 1. 逻辑链必须完整且显性 每一段话都要让读者知道"我为什么在这里讲这个"。段与段之间的衔接关系要明确——是因果、是递进、是转折、还是并列。绝不允许出现"知识点的堆砌"，每个概念的引入都必须有前文铺垫。 好的衔接示例： ``` 上面解释了 wave 机制如何解决"异步请求 vs 同步通信"的矛盾。但这引出了一个新问题： 如果某个 rank 没有请求要处理，它怎么参与集合通信？这就是 dummy batch 的设计动机。 ``` 差的写法： ``` ## Wave 机制 （一段解释） ## Dummy Batch （另一段解释，跟上面没有显性连接） ``` #### 2. 先讲"为什么"，再讲"是什么" 领导不关心实现细节本身，他关心的是：**这个设计在解决什么工程问题？它做了什么取舍？有没有更好的方案？为什么选了这个？** 结构上要做到： - 先给出问题场景（一两句话就能让人理解痛点） - 再给出解决方案（核心思路，不是所有细节） - 最后分析权衡（代价是什么、在什么条件下成立） #### 3. 体现系统思维 不要孤立地描述单个组件，而要**展示组件之间的关系和互相约束**。让读者看到一个完整的系统是如何被一层层设计出来的，每一层为什么不能省略。 好的系统思维体现： ``` DP Coordinator 负责唤醒空闲 rank（异步安全），gloo all_reduce 负责判断 wave 结束 （同步屏障）。两者的分工不是任意的——Coordinator 只在没有 forward 运行时介入， 避免与 NCCL 通信冲突；而 wave 结束判断必须严格同步，因为判断之后的下一步就是 停止 forward，任何时序偏差都会导致集合通信死锁。 这种"异步唤醒 + 同步收尾"的组合模式，本质上是对"请求异步到达"和"forward 同步执行" 两种矛盾需求的分治处理。 ``` #### 4. 结论要有洞察，不只是总结 不要写"综上所述，我们了解了 X、Y、Z"。要写出**你的判断**： ``` vLLM DP 的核心 trade-off 是用工程复杂度换硬件并发。这个方案在当前阶段是务实的 选择——wave 机制虽然引入了 dummy batch 的算力浪费和单点故障传播风险，但它保证了 实现简单性和死锁不可能性。如果未来要优化，方向可能是更细粒度的异步调度 （如 per-layer 同步而非 per-step），但代价是极大的代码复杂度和更难调试的死锁场景。 ``` #### 5. 适度使用结构化元素 专业文档中，结构化是合理的——但要服务于逻辑，不是为了"看起来整齐"： - **架构图/流程图**：展示系统全貌时使用，配合文字说明 - **对比表**：展示设计权衡时使用（方案 A vs B，维度明确） - **代码片段**：只在"不看代码说不清设计意图"时使用，必须有上下文 - **编号列表**：只在确实有先后顺序或层级关系时使用 #### 6. 语言风格 - 正式但不官僚——像技术评审会上的发言，不是公文 - 有判断、有立场——"我认为"、"关键区别在于"、"这意味着" - 避免模糊表述——不说"比较复杂"，说清楚"复杂在哪里、为什么不可避免" - 可以有类比，但要精准——类比是为了让领导快速建立直觉，不是为了显得生动 ### 文章结构（专业汇报） ```markdown # 标题（明确主题 + 核心结论） ## 背景与问题 为什么要研究这个？它解决什么实际问题？跟我们的工作有什么关系？ （2-3 段，让领导在 30 秒内理解上下文） ## 核心设计 / 技术方案 系统是如何解决这个问题的？核心思路是什么？ （主体部分，按逻辑链展开，每引入一个概念都要交代"为什么需要它"） ## 关键实现细节 支撑上述设计的代码级证据（精选，不贪多） ## 设计权衡与局限 这个方案付出了什么代价？在什么条件下成立？有没有替代方案？为什么没选？ ## 结论与启发 对我们自己的项目/工作有什么参考价值？ （有判断、有建议、有前瞻） ``` ### 正面示范（专业风格开头） ```markdown # vLLM 数据并行的协调机制：如何在异步推理中实现同步通信 ## 背景与问题 推理服务的数据并行（DP）面临一个训练阶段不存在的矛盾：请求异步到达，但模型内部的 集合通信（all-reduce、all-to-all）要求所有参与 rank 同步执行。训练时这不是问题—— 每个 batch 提前切好，所有 rank 天然同步；但推理时请求流是完全异步的，任意时刻各 rank 的负载可能完全不同。 如果某个 rank 没有请求要处理，它无法参与集合通信，导致其他 rank 阻塞——这就是 推理 DP 必须解决的核心工程问题。vLLM v1 为此设计了一套完整的协调机制，本文分析 其设计思路和工程权衡。 ``` ### 文件命名（专业风格） ``` summary-YYYYMMDD-主题slug-report.md # 示例 summary-20260506-vllm-dp-coordination-report.md summary-20260506-moe-ep-communication-analysis-report.md ``` 后缀加 `-report` 以区分个人笔记版本。