progress-summary

进度摘要

以精心撰写的 PR 描述为风格，生成关于进行中工作的对话式摘要。

要用通俗易懂的方式解释架构，请使用 notebook-explanation 作为格式：简短的工作笔记、精炼的定义、ASCII 图示、具体示例和简明规则。

核心原则

先讲动机

每份摘要都要从 WHY 开始。不是改了哪些文件，也不是工作原理，而是这项工作为何重要。

好的开场：

我们一直在处理会导致用户在上传过程中途被登出的问题。根本原因是，只有在页面导航时才会触发会话刷新，后台活动期间不会触发。

不好的开场：

我们在上传处理程序中添加了 keepalive 调用，并更新了会话刷新逻辑。

读者应先理解问题，再看到解决方案。

展示思考过程

摘要应展现决策过程：

• “我们考虑过 X，但 Y 更合理，因为……”
• “一开始尝试了 A，由此发现 B，于是转向 C”
• “棘手之处在于找出该如何接入现有流程”

对话式但准确

像是和同事喝咖啡时解释事情一样写。直接、坦诚。

• 说“这事一直很难受”，而不是“这带来了挑战”
• 说“我们在……上碰了壁”，而不是“我们遇到了困难”
• 协作工作用“我们”，个人观察用“我”

摘要类型

快速状态（口头同步）

适用于“你在做什么”或简短进度更新：

Working on the auth timeout issue. Found the root cause: session refresh
only fires on navigation, not background activity. Currently implementing
a keepalive mechanism in the upload handler.

2-4 句话。说明问题、发现和当前行动。

工作阶段回顾（工作阶段结束时）

适用于“总结一下我们做了什么”或收尾：

结构：

1. 我们处理了什么问题
2. 做出了哪些关键决策（以及原因）
3. 现在有哪些进展
4. 还有哪些工作待完成

示例：

We tackled the nested reactivity problem in state management. Users found
it cumbersome to create deeply reactive state with manual get/set properties.

After exploring several approaches, we landed on proxy-based reactivity
because it lets you write idiomatic JavaScript while we get the performance
benefits of immutability under the hood.

The core implementation is working. Still need to optimize for large arrays
and update the migration guide.

架构概览（解释复杂改动）

对于大型工作的“这里发生了什么”，请使用 notebook-explanation。它负责建立心智模型并规范图示：归属关系、边界、流程、正反示例、持久规则以及图示形状分类。

progress-summary 仍会围绕它来组织回顾：改了什么、为何改动，以及还有哪些问题待解决。

应避免的内容

• 罗列改动文件：“更新了 auth.ts、session.ts 和 upload.ts”——直接解释改了什么以及原因
• 企业套话：“此增强利用了我们现有的基础设施”
• 营销用语：“改变游戏规则”“革命性”“无缝”
• 夸张渲染：“令人痛苦不堪的痛点”——只陈述事实
• 事事都用项目符号：尽可能使用连贯的段落
• 过度解释简单改动：根据复杂程度调整解释深度

收集摘要所需的上下文

生成摘要时，请收集相关上下文：

# Current branch state
git status
git log --oneline -10

# What changed from main
git diff main...HEAD --stat
git log main..HEAD --oneline

# Recent activity
git log --oneline --since="1 hour ago"

如果环境提供专用的工作区差异工具，请使用该工具。否则，请使用 git diff --stat、git diff 和针对性的文件读取。

阅读已修改的关键文件，以了解改动的实质，而不只是差异统计。