ShockRock2004/kamar-taj

Wong — 每日学习指南（原 daily-log）

将一整天的 Claude Code 工作（跨所有会话和仓库）转化为一份带日期的 Markdown 文件，以教学指南的形式呈现，让用户能真正从工作中学习：亲手重新实现代码，理解为什么做出每个决定，并能解释其工作原理，因为他们是真正理解了。

输出不是变更日志。它是一本面向初学者的教科书——写得如此简单和对话化，以至于一个没有软件背景的人也能从头读到尾，理解做了什么以及为什么。每个技术术语首次出现时都用通俗语言定义；代码保持技术性，但会用通俗易懂的英文解释包裹。深度和“为什么”比琐事的完整性更重要。请参见步骤 4 中的完整写作风格——必读规则。

第 0 步：从命令中读取努力程度

用户可以通过第一个参数传递努力程度：light、medium 或 heavy。如果未指定，默认使用 heavy。（他们也可以传递一个日期；YYYY-MM-DD 格式的标记是日期，light/medium/heavy 标记是努力程度。顺序不限，两者都可选。例如：/wong medium，/wong light 2026-06-25。）

努力程度控制 token 使用量——它会调整摘要的大小（通过收集器的 --effort 参数）以及在撰写时的工作量：

• light — 最经济。仅记录前 2-3 项工作。不要运行 git show 或读取额外文件；依赖摘要和提交信息，总共最多包含一个短代码片段。保持每个部分简洁。但仍需包含 Git 技能部分、Slack 摘要、PDF 和上传。
• medium — 平衡。记录前约 5 项工作。仅对最重要的 2-3 项拉取真实代码（git show）。中等深度。
• heavy（默认）— 以下描述的完整处理：每个独立工作项，为每个拉取真实代码，完整深度。

在所有步骤中贯彻所选等级。

步骤

1. 收集当天的原始材料

使用所选努力程度运行收集器（它会读取磁盘上的每个会话记录，因此会捕获所有并发/已关闭的会话，而不仅仅是当前这一个）：

python3 ~/.claude/skills/wong/collect_day.py --effort heavy

将 heavy 替换为第 0 步中的等级。要记录过去某天，添加日期：python3 ~/.claude/skills/wong/collect_day.py --effort medium 2026-06-25

它会打印出摘要文件的路径（~/Daily Log/.digest-<date>.md）。请完整阅读该摘要。 其中包含每个仓库：当天的 git 提交映射、未提交的变更统计，以及每个会话中用户的提示、Claude 编辑的文件、Claude 的解释性文字，以及任何子代理的结果。

同时阅读术语表位于 ~/Daily Log/.glossary.md（如果不存在，则视为空）。它列出了之前几天已经解释过的琐碎/基础术语。你不会重复解释其中已有的内容——请参见步骤 4 中的“仅解释一次基础术语”。

如果摘要显示没有活跃的会话，请告知用户并停止。

2. 识别不同的功能/任务

将当天的工作分组为独立的工作项，而不是按会话划分。合并推进同一功能的会话/提交。一个“工作项”是用户可以指出的一个独立工作成果（例如“verto 代理呼叫传递错误修复”、“预测式拨号器放弃率上限”）。只关注真正重要的事项；不要用琐事填充。

3. 为每个工作项获取真实代码

努力程度门控： 在 light 等级下，完全跳过此步骤（不使用 git show 或读取文件——使用摘要和提交信息，最多一个代码片段）。在 medium 等级下，仅对最重要的 2-3 项执行此操作。在 heavy 等级下，对每个工作项执行。

摘要列出了提交 SHA 和编辑过的文件，但不是完整的差异。对于你正在记录的每个工作项，拉取实际代码，以确保代码片段是真实的，而非转述：

git -C <repo> show <sha>            # 一个提交的完整差异
git -C <repo> show <sha> -- <path>  # 一个文件的差异
git -C <repo> diff -- <path>        # 未提交的工作

或者在相关行读取当前文件。优先展示关键行（包含核心思想的行），而不是倾倒整个文件。

查阅仓库的 CLAUDE.md 和 docs/GOTCHAS.md（如果存在），获取与工作相关的地雷——这些对于“雷区与教训”部分非常有价值。

4. 撰写教学指南——增量更新，绝不覆盖

文件命名格式。 文件保存在 ~/Daily Log/ 目录下，并按如下格式命名：

<YYYY-MM> - <DD> - <我们那天所做工作的一句话摘要>.md

例如：2026-06 - 26 - 修复了代理呼叫传递并启动了 Yotel 3D 登录页面.md。一句话部分是对当天工作的简短、通俗的标题（其中不要有连字符，因为日期分隔符已经是“ - ”形式；保持在约 12 个单词以内）。文件顶部的 # 标题必须与文件名（不含 .md）相同的字符串。

查找当天文件（对于追加逻辑很重要）。 由于一句话后缀会变化，永远不要寻找精确的 <date>.md。相反，通过日期前缀查找当天的文件——列出 ~/Daily Log/ 目录中的文件，并匹配以 <YYYY-MM> - <DD> - 开头的文件（例如 ls "~/Daily Log/" 并选择以 2026-06 - 26 - 开头的文件）。每天最多只有一个文件。

此技能可能在一天内运行多次。在第一次之后的每次运行中，你必须只添加尚未记录的工作——绝不覆盖或重复已有的内容。

流程：

1. 如果当天还没有文件（没有文件匹配日期前缀）：创建它，使用下面的完整结构（“当天概览” + 每个工作项一个部分，编号为 ## 1.、## 2.……），使用上述格式命名。
2. 如果当天的文件已存在（通过日期前缀找到）：首先读取它。通过扫描现有的 ## N. <title> 标题以及每个“参考文献”行中的提交 SHA 或会话 ID，构建一个已覆盖内容的集合。然后，从当天的摘要中识别其提交/会话尚未出现在该集合中的工作项。
   • 保持文件名的一句话摘要准确反映全天内容： 如果新添加的工作改变了当天应该使用的标题，则重命名文件（并更新其 # 标题以匹配），使一句话摘要仍然反映当天完成的所有工作。如果标题仍然合适，则保持文件名不变。
   • 如果没有新内容，告知用户文件已是最新并停止（不要重写它）。
   • 否则，追加新的 ## N. 部分（延续现有编号），仅针对新的工作，使用相同的每个功能模板。
   • 原地更新**“当天概览”**块：更新提交/会话计数，并扩展标题以提及新添加的工作。不要修改现有的功能部分。
   • 使用编辑（定向插入），而不是完全覆盖，以便先前的部分——包括你可能手动编辑过的任何部分——得以原样保留。

如果一个工作项的提交 SHA 或会话 ID 已出现在文件中，则视为已覆盖。通过这些标识符匹配，而不是通过措辞匹配，以便重新运行时不会产生近乎重复的部分。

写作风格——必读（这是重点）

将其写得像一本面向完全初学者的教科书章节——一个聪明但对软件一无所知的人。读者应该能够从上到下理解每个部分，而无需任何前期背景。

• 对话化和简单。 短句，通俗用词。像和朋友聊天一样解释，而不是写报告。叙述中避免行话。
• 在整个系列中只定义每个技术术语一次——不是每天一次。 当一个术语首次出现时，用日常语言在一个引用框中定义它：> **“X”是什么。** …（使用现实世界的类比）。但首先检查术语表（~/Daily Log/.glossary.md），绝不重复定义已列出的术语。 这对于琐碎的、重复出现的基础知识尤为重要——什么是仓库/提交/分支，什么是 Yotel，基本 git 操作——解释一次，然后直接使用。一个全新且确实是今天工作核心的术语仍然会得到它的定义框；一个之前已经解释过的基础术语则不会。参见下面的“仅解释一次基础术语”了解具体机制。
• 仅在技术精确性是重点时才保持技术性——例如实际的代码变更、确切的文件、真正的权衡。展示真实代码，但前后用通俗英文解释包裹，并用通俗语言注释代码片段。绝不要只是倾倒代码。
• 每个部分都以“日常版本”开头——用通俗语言讲述什么被破坏了/需要什么以及为什么它很重要——然后才是任何技术细节。
• 在最顶部使用简短的 “如何阅读本文档” 说明，以及一个 “大局观（先读这个）” 概览，用通俗术语解释项目（这是什么产品，谁使用它，为什么）。
• 保持“如何解释它”的要点以简洁、自信的一句话形式给出，然后是一个可以简单解释的巧妙见解。
• 诚实：清晰地将真正交付的代码与设置/探索分开，并用通俗语言说明。

与 ~/Daily Log/ 中最新现有文件的语气保持一致（如果存在，则将其作为参考示例阅读）。

仅解释一次基础术语（术语表）

整个系列的读者不应该每天重复看到“什么是仓库”或“什么是 Yotel”的解释。所以：

1. 在写作之前， 读取 ~/Daily Log/.glossary.md（已经解释过的术语列表）。将列表中的所有内容视为已知——不要为列表中的任何术语编写 > **“X”是什么。** 框。只需正常使用该术语。
2. 在写作过程中， 仅为一个真正在该系列中新出现的术语（不在术语表中）添加定义框。强烈倾向于不为琐碎的基础知识重新定义；如果对一个基础术语有疑问，假设它已被覆盖并跳过它。
3. 在写作/追加之后， 更新 ~/Daily Log/.glossary.md：追加（每行一个）你今天首次定义的任何术语。永远不要删除现有条目。如果文件不存在，则创建它。

这尤其适用于琐碎的、重复出现的术语（仓库、提交、分支、worktree、产品是什么、基本 git 操作）。一个复杂的术语如果是某天工作的核心，仍然可以在那天解释，但一旦它出现在术语表中，以后就不再重新解释。

每个功能的模板和当天概览结构（将标题调整为上述面向初学者的语气——这些是要涵盖的内容，而不是要逐字复制的固定标签）：

# <YYYY-MM> - <DD> - <我们那天所做工作的一句话摘要>

> **如何阅读本文档。** （1-2 句话告诉初学者如何使用它。）

## 大局观（先读这个）

对当天完成工作的通俗语言概览。**仅在它们尚未出现在术语表中时**才在此处定义“项目/仓库”、“提交”以及产品（例如 Yotel）是什么——也就是说，仅在第一个日志中。在以后的每一天，跳过这些基础知识以及“这个产品是什么”的解释；只需命名它们并继续。

---

## 1. <工作项的通俗标题>   (<repo>)

### 日常版本

没有行话的故事——什么被破坏了或需要什么，以及为什么它对真实的人很重要。使用类比。

### 真正发生了什么/修复方案（技术部分）

现在精确的细节：真正的原因，真正的代码变更（用通俗英文展示和解释，并附有注释的代码片段），确切的文件路径。在每一个新技术词之前放置一个 `> **“术语”是什么。**` 框。

### 如何自己动手做，一步一步

编号的、具体的步骤，初学者可以遵循。

### 如何解释它（一旦你理解了）

- 关于该工作做什么的简单一句话摘要。
- 一个巧妙的见解，简单解释。
- 需要用日常语言捍卫的权衡。

### 值得记住的教训

通俗语言的可取之处 + 来自 `CLAUDE.md` / `docs/GOTCHAS.md` 的任何相关地雷。

**在哪里找到它：** 文件、提交 SHA、会话 ID。

---

## 2. <下一个工作项…>

---

## 今天使用的 Git 技能

（始终是文档的最后一个部分。从摘要的“Claude 运行的 Git 命令”块构建——请参见下面的专门说明。）

### <git 操作，例如 提交更改>   `git commit`

**它做了什么** — 用通俗语言，这个命令在今天完成了什么。
**为什么** — 为什么在工作流程的那个点需要这个步骤。
**如何自己操作** — 真实的命令，附有简短的说明，解释每个部分和标志的含义，以便读者可以手动执行。

### <下一个 git 操作…>

“今天使用的 Git 技能”部分——必读（始终是最后一个部分）

每天的文件都以一个 ## 今天使用的 Git 技能 部分结束，该部分由摘要中的 “Claude 运行的 Git 命令” 块构建（每个会话一个块）。

如何构建：

1. 从摘要的每个会话中收集所有 git 命令。捕获的条目可能是一个复合命令（例如 cd repo && git add ... && git commit ...）；提取出 git 部分。
2. 按 git 操作对它们进行分组（例如，提交、创建分支、创建 worktree、推送、暂存、stash、恢复、变基、使用 log/diff/show/status 进行查看）。每个不同的操作一个子部分——不要多次列出同一操作。如果许多命令只是只读检查（git status、git log、git diff、git show），将它们合并到一个简短的“浏览仓库”子部分中，而不是每个一个。
3. 对于每个操作，以文档中其他地方使用的面向初学者的语气写三件事：
   • 它做了什么 — 这在今天实际工作中实现了什么。
   • 为什么 — 为什么在那个工作流程点需要那个步骤。
   • 如何自己操作 — 真实的命令，附有简单的说明，解释每个部分和重要标志的含义，以便读者可以手动执行。 在第一次使用前放置一个 > **“X”是什么。** 框。