Skip to content

Commit 514d33e

Browse files
吴师兄claude
andcommitted
[readme-conversion] README 二期转化层草稿 + 数字段脚本接管 + HOW-TO-INTERACT
草稿落 docs/readme-revamp/(README.draft.md/build-readme.js/CHANGES.md/utm-links.md), 线上 README.md 未动,未 push。徽章/近况/GIF直达/折叠/Star区为转化层(人手), 当前索引数字交 build-readme.js 注入(标记区)+stats.json徽章。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent e3001f4 commit 514d33e

5 files changed

Lines changed: 472 additions & 0 deletions

File tree

docs/HOW-TO-INTERACT.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# 这个仓库怎么用(大白话备忘)
2+
3+
> 给吴师兄本人和未来任何接手会话看。一句话:**网站是源头,这个 GitHub 仓库是它的公开索引和门面。**
4+
> 网站上新增/改了动画 → 跑同步脚本,仓库的索引和数字就自动更新;README 的门面文案人手维护。
5+
6+
## 1. 三件事各归谁管
7+
8+
| 东西 | 谁说了算 | 怎么变 |
9+
| :-- | :-- | :-- |
10+
| 动画内容本身(题目、步骤、语音) | **网站** algomooc.com | 在网站侧改,GitHub 不直接编辑动画 |
11+
| 题目索引、数量、专题分类 | **同步脚本**(据网站侧 `study_index.js` 实算) |`npm run sync`,别手敲数字 |
12+
| README 的门面(徽章、近况、Star 区、文案) | **人手** | 直接改 `README.md` 标记区**之外**的部分 |
13+
| README 里的数字(题数/难度分布) | **脚本**`build-readme.js`|`--write` 注入,`<!-- LCA-AUTOGEN:STATS -->` 标记**之间**别手改 |
14+
15+
## 2. 网站加了新题,怎么同步到这里
16+
17+
在仓库根目录(`/Users/wuzhibo/Desktop/Claude/LeetCodeAnimation-github`)依次跑:
18+
19+
```bash
20+
npm run review:site # 先看:网站侧有哪些题需要同步,会建议 commit message
21+
npm run sync # 同步:更新 manifest / 题号索引 / 专题索引 / sync-log
22+
npm run validate # 校验:manifest 没问题
23+
node tools/scripts/build-readme.js --write # 把 README 数字段 + stats.json 刷新
24+
git add docs README.md
25+
git commit -m "docs: sync 最新 LeetCode 动画索引"
26+
```
27+
28+
> 单题新增就单题一个 commit(读者能看到仓库持续更新);批量小修复攒 3~5 个再同步。
29+
> 详细规则见 [`docs/sync-workflow.md`](sync-workflow.md)
30+
31+
## 3. 想改 README 门面(徽章 / 近况 / 文案),怎么发布
32+
33+
1. **先在 `docs/readme-revamp/` 出草稿**,不直接动线上 `README.md`
34+
2. 吴师兄过目,给「**发布**」原话。
35+
3. 才执行 `docs/readme-revamp/CHANGES.md` 里的「发布步骤」(替换 README → 脚本注入数字 → commit)。
36+
4. **push 远端要单独再给一次原话** —— 默认只在本地 commit,不动 `github.com/MisterBooo/LeetCodeAnimation`
37+
38+
> 铁律:这个仓库**不在没拿到「发布」原话时 push**。所有改动先落本地分支等过目。
39+
40+
## 4. README 里那两个数字(256 / 299)是什么意思
41+
42+
- **256**:已**同步到本仓库**的 LeetCode 题动画数。脚本据网站侧 `study_index.js` 实算,写进 `manifest.json``stats.json`**禁止手写**
43+
- **299****algomooc.com 全站**动画内容总数(含进阶题、专题,比本仓库的 LeetCode 子集大)。口径来自站内 `content-stats` 单一数据源;本仓库的 `stats.json``siteTotal` 字段留给它回填,同样**禁止手写**
44+
- 一句话:**两个数字都由脚本管**。增删题只要跑同步脚本,README 全站数字自动对上,不用回来手改。
45+
46+
## 5. 「299 役」收官后,新题怎么并进来
47+
48+
299 役(全站动画质量清算)收尾、网站侧题目列表定型后:
49+
50+
1. 确认网站侧 `study_index.js` 已是最终列表。
51+
2. 跑第 2 节那套同步流程 —— `manifest` / 索引 / 数字会一次性对齐到最终态。
52+
3. 若有特别适合展示的新题,再往 `docs/assets/previews/` 补 1~2 张精选 GIF,更新 README GIF 区(README 预览保持 4~6 张精选,不必每题都放)。
53+
4. 站内 `content-stats` 给出全站总数后,把 `stats.json``siteTotal` 回填,README 口径里的 299 即对齐到真实全站数。
54+
55+
## 6. 红线(别犯)
56+
57+
- ❌ 不在 `<!-- LCA-AUTOGEN:STATS -->` 标记之间手敲数字。
58+
- ❌ 不在没拿到「发布」原话时 push 这个仓库。
59+
- ❌ 不直接编辑由脚本生成的 `manifest.json` / `leetcode-animation-index.md` / `index-by-topic.md` / `stats.json`(改网站侧源头再同步)。
60+
- ✅ 门面文案(标记区外)随便改,改完按第 3 节走发布流程。

docs/readme-revamp/CHANGES.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# README 二期改造 · diff 说明
2+
3+
> 状态:**草稿待过目**。改动只落在 `docs/readme-revamp/``docs/HOW-TO-INTERACT.md`
4+
> **未触碰线上 `README.md`,未 push 远端**。你给「发布」原话后才执行下方「发布步骤」。
5+
6+
## 一句话
7+
8+
保留现有工程底座(manifest / 同步脚本 / 索引体系)完全不动,在 README **外层加装一层转化层**
9+
(徽章按钮 / 近况区 / GIF 直达 / 折叠维护块 / Star 区),并把所有**会变的数字交给脚本接管**
10+
11+
## 改了什么(草稿 vs 线上 README)
12+
13+
| # | 区块 | 线上现状 | 草稿改造 | 性质 |
14+
| :-- | :-- | :-- | :-- | :-- |
15+
| 1 | 第一屏 | 只有一个 stars 社交徽章 + 三条文字链接 |**last-commit / 题目数** 徽章 + **三个按钮式徽章**(🎬 在线交互版 / 📚 按专题刷 / 🤖 AI 私教小欧),全部带 `utm_source=github` | 转化层(人手) |
16+
| 2 | 近况区 || 新增「🚧 2026 大版本进行中」:三语言代码、AI 私教小欧、吴师兄声线语音、299 题质量清算 —— 只写已上线/进行中 | 转化层(人手) |
17+
| 3 | GIF 预览 | 4 张 GIF 有链接但**无 UTM** | 4 张 GIF 链接全部补 UTM;区下加一行「↑ 网站版还能单步、回看、变速、听讲解」+ 直达按钮 | 转化层(人手) |
18+
| 4 | 当前索引 | 手写表格(256/71/160/25 是手打的数字) | 改为 `<!-- LCA-AUTOGEN:STATS -->` 标记区,由 `build-readme.js` 注入;顶部题目数徽章读脚本产出的 `stats.json` | **数字段(脚本接管)** |
19+
| 5 | 数字口径 || 新增口径说明:256=本仓库已同步 LeetCode 题动画;299=全站动画总数(含进阶/专题,来自站内 content-stats),与 `[stats-single-source]` 对齐,两者均禁手写 | 转化层 + 口径 |
20+
| 6 | 运维内容 | 「同步方式 / 目录 / 仓库与网站关系」平铺占大半页 | 整段折叠进 `<details>「🛠 维护者:同步与数据说明」` | 降权(人手) |
21+
| 7 | 末尾 | 简短反馈段 | 换成 **Star 区**:star-history 曲线图 + 真诚引导 + 「内容持续同步自 algomooc.com」承诺 | 转化层(人手) |
22+
23+
## 转化层 / 数字段的边界(关键设计)
24+
25+
- **数字段**=README 里 `<!-- LCA-AUTOGEN:STATS START/END -->` 之间的「当前索引」表 + 顶部题目数徽章。
26+
- 表格由 `tools/scripts/build-readme.js --write` 注入,数据源 `docs/data/manifest.json`(脚本据网站侧 `study_index.js` 实算)。
27+
- 顶部徽章用 shields `dynamic/json` 直接读 `docs/data/stats.json``$.count`**连数字字符串都不出现在 README 里**
28+
- 标记区外脚本一律不碰 —— 转化层和数字段彻底解耦,改文案不会动数字,增删题不用改 README。
29+
- **转化层**=标记区之外的一切(徽章文案、近况、GIF、折叠块、Star 区),人手维护,自由改。
30+
31+
## 新增 / 改动的工程文件
32+
33+
| 文件 | 说明 | 现在在哪 |
34+
| :-- | :-- | :-- |
35+
| `tools/scripts/build-readme.js` | **升级**:旧版只 print 到 stdout;新版加 `--write`(注入 README 数字段 + 写 `stats.json`)/ `--check`(数字段过期 exit 1,可挂收尾闸门)。默认无参仍是旧行为,向后兼容。 | 草稿放 `docs/readme-revamp/build-readme.js`,发布时覆盖 `tools/scripts/build-readme.js` |
36+
| `docs/data/stats.json` | 脚本实算的计数(count/easy/medium/hard/siteTotal),供 README 徽章读 | 发布时由 `build-readme.js --write` 生成 |
37+
| `README.md` |`README.draft.md` 内容替换 | 草稿在 `docs/readme-revamp/README.draft.md` |
38+
| `docs/HOW-TO-INTERACT.md` | 维护者互动备忘(新交付) | 已写入 `docs/HOW-TO-INTERACT.md` |
39+
40+
> `siteTotal`(即 299)当前留 `null`:本仓库 manifest 只覆盖已同步的 LeetCode 子集,全站总数来自站内
41+
> content-stats 单一数据源,待 `[stats-single-source]` 落地后从网站侧同步回填,**不在 README 手写**
42+
43+
## 发布步骤(你说「发布」后我才执行)
44+
45+
```bash
46+
cd /Users/wuzhibo/Desktop/Claude/LeetCodeAnimation-github
47+
48+
# 1. 落地工程底座升级
49+
cp docs/readme-revamp/build-readme.js tools/scripts/build-readme.js
50+
51+
# 2. 用草稿替换线上 README,并由脚本注入数字段 + 生成 stats.json
52+
cp docs/readme-revamp/README.draft.md README.md
53+
node tools/scripts/build-readme.js --write
54+
node tools/scripts/build-readme.js --check # 应输出「数字段最新」
55+
56+
# 3. 同步 docs/sync-workflow.md 增补一行 build-readme 步骤(可选,发布时一并)
57+
# 4. 提交并(经你确认后)push
58+
git add README.md tools/scripts/build-readme.js docs/data/stats.json docs/HOW-TO-INTERACT.md docs/readme-revamp/
59+
git commit -m "docs: README 二期转化层改造(徽章/近况/GIF直达/折叠/Star区)+ 数字段脚本接管"
60+
# git push # ← 只有你再次给原话才推远端
61+
```
62+
63+
## 待你拍板的点
64+
65+
1. **三个按钮的落点 URL** 是否正确:🎬→`/leetcode-animation`、📚→`/topics`、🤖→`/ai-tutor`(均已确认路由存在)。
66+
2. **AI 私教对外是否就叫「小欧」**(与站内一致),README 里这样写是否 OK。
67+
3. **299 口径**:近况区写「299 题全量质量清算(进行中)」是否准确,或要改成别的措辞/数字。
68+
4. 顶部题目数徽章依赖 `docs/data/stats.json``master` 分支可被 raw 读取 —— 发布后首次 `--write` 提交才生效(之前会短暂显示 `invalid`)。

docs/readme-revamp/README.draft.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# LeetCodeAnimation
2+
3+
> 用动画把 LeetCode 题解过程拆开看:指针怎么移动、状态怎么转移、递归怎么展开、边界为什么成立。
4+
> GitHub 这份是公开索引与历史素材;**完整的单步、回看、变速、语音讲解在网站版**
5+
6+
<!-- 转化层:徽章组(人手维护)。题目数徽章读 docs/data/stats.json,数字由脚本接管,勿手改。 -->
7+
[![GitHub stars](https://img.shields.io/github/stars/MisterBooo/LeetCodeAnimation?style=social)](https://github.com/MisterBooo/LeetCodeAnimation)
8+
[![last commit](https://img.shields.io/github/last-commit/MisterBooo/LeetCodeAnimation?color=7c3aed)](https://github.com/MisterBooo/LeetCodeAnimation/commits/master)
9+
[![LeetCode 动画题数](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FMisterBooo%2FLeetCodeAnimation%2Fmaster%2Fdocs%2Fdata%2Fstats.json&query=%24.count&label=LeetCode%20%E5%8A%A8%E7%94%BB&suffix=%20%E9%81%93&color=7c3aed)](docs/leetcode-animation-index.md)
10+
11+
<!-- 三个转化主按钮:全部带 utm_source=github。链接清单见 docs/readme-revamp/utm-links.md -->
12+
[![🎬 在线交互版](https://img.shields.io/badge/🎬_在线交互版-可单步·变速·语音-7c3aed?style=for-the-badge)](https://www.algomooc.com/leetcode-animation?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=hero_interactive)
13+
[![📚 按专题刷](https://img.shields.io/badge/📚_按专题刷-数组·链表·DP·图论…-1f6feb?style=for-the-badge)](https://www.algomooc.com/topics?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=hero_topics)
14+
[![🤖 AI 私教小欧](https://img.shields.io/badge/🤖_AI_私教小欧-不会就问-16a34a?style=for-the-badge)](https://www.algomooc.com/ai-tutor?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=hero_ai_xiaoou)
15+
16+
如果这个项目帮到你,欢迎 **Star** 支持持续更新。
17+
18+
---
19+
20+
## 🚧 2026 大版本进行中
21+
22+
这个仓库不是一次性归档。2026 年正在做一轮大版本升级,**只列已上线 / 进行中的实话**
23+
24+
-**三语言参考代码**:每道题的题解配 **Python / C++ / Java** 三种实现,Python 为默认。
25+
-**AI 私教「小欧」**:吴师兄带的 AI 算法私教,做题卡住可随时追问思路与边界。
26+
-**吴师兄声线语音讲解**:动画边演示边讲,语音为 **AI 合成(吴师兄声线授权)**;点播放器里的 🔊 即可听。
27+
- 🚧 **299 题全量质量清算**:对全站动画题逐题做质量复核与重制,分批上线,持续同步回本仓库索引。
28+
29+
> 进度会随同步脚本更新到下方「当前索引」与 [`docs/sync-log.md`](docs/sync-log.md)
30+
31+
---
32+
33+
## 网站版动画预览
34+
35+
下面四张 GIF 取自网站播放器的关键帧,**点图直达对应题目页**(完整步骤播放、三语言代码、语音讲解都在网站版)。
36+
37+
<table>
38+
<tr>
39+
<td width="50%">
40+
<a href="https://www.algomooc.com/leetcode-animation/two-sum?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=preview_two_sum">
41+
<img src="docs/assets/previews/two-sum.gif" alt="两数之和动画预览" width="420">
42+
</a>
43+
<br>
44+
<strong>两数之和</strong>
45+
<br>
46+
边扫数组边维护哈希表,看清 complement 是怎么被找到的。
47+
</td>
48+
<td width="50%">
49+
<a href="https://www.algomooc.com/leetcode-animation/trapping-rain-water?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=preview_trapping_rain_water">
50+
<img src="docs/assets/previews/trapping-rain-water.gif" alt="接雨水动画预览" width="420">
51+
</a>
52+
<br>
53+
<strong>接雨水</strong>
54+
<br>
55+
用柱状图把左右边界和蓄水过程拆开,直观看懂为什么能接住水。
56+
</td>
57+
</tr>
58+
<tr>
59+
<td width="50%">
60+
<a href="https://www.algomooc.com/leetcode-animation/number-of-islands?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=preview_number_of_islands">
61+
<img src="docs/assets/previews/number-of-islands.gif" alt="岛屿数量动画预览" width="420">
62+
</a>
63+
<br>
64+
<strong>岛屿数量</strong>
65+
<br>
66+
DFS 染色过程一格一格展开,连通块边界会更容易看清。
67+
</td>
68+
<td width="50%">
69+
<a href="https://www.algomooc.com/leetcode-animation/linked-list-cycle?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=preview_linked_list_cycle">
70+
<img src="docs/assets/previews/linked-list-cycle.gif" alt="环形链表动画预览" width="420">
71+
</a>
72+
<br>
73+
<strong>环形链表</strong>
74+
<br>
75+
快慢指针在链表上同步移动,什么时候相遇一眼能看到。
76+
</td>
77+
</tr>
78+
</table>
79+
80+
**↑ 网站版还能单步、回看、变速、听讲解** —— [打开在线交互版 →](https://www.algomooc.com/leetcode-animation?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=preview_cta)
81+
82+
---
83+
84+
## 项目特点
85+
86+
- **动画题解**:先看清算法过程,再回到代码。很多题目保留了 GIF 或分步动画素材。
87+
- **三语言代码**:题解配 Python / C++ / Java 三种参考实现。
88+
- **结构化数据**[`docs/data/manifest.json`](docs/data/manifest.json) 可被脚本读取,用于生成索引、检查链接或二次整理。
89+
- **持续同步**:网站侧新增或调整动画后,通过脚本同步回 GitHub —— 仓库不是静态归档。
90+
91+
<!-- LCA-AUTOGEN:STATS START — 勿手改,数字由 tools/scripts/build-readme.js 注入 -->
92+
## 当前索引
93+
94+
> 下表数字由 `tools/scripts/build-readme.js``docs/data/manifest.json` 实算注入,**请勿手改**
95+
96+
| 项目 | 数量 / 位置 |
97+
| :-- | :-- |
98+
| LeetCode 动画题数 | **256** |
99+
| 简单 | 71 |
100+
| 中等 | 160 |
101+
| 困难 | 25 |
102+
| 数据文件 | [`docs/data/manifest.json`](docs/data/manifest.json) |
103+
| 按题号索引 | [`docs/leetcode-animation-index.md`](docs/leetcode-animation-index.md) |
104+
| 按专题索引 | [`docs/index-by-topic.md`](docs/index-by-topic.md) |
105+
| 网站路径 | <https://www.algomooc.com/leetcode-animation> |
106+
107+
<!-- LCA-AUTOGEN:STATS END -->
108+
109+
> **数字口径**:上表 **256****已同步到本仓库的 LeetCode 题动画数**(脚本据网站侧 `study_index.js``manifest.json` 实算)。
110+
> 近况区提到的 **299****algomooc.com 全站动画内容总数**(含进阶题与专题,口径来自站内 `content-stats` 单一数据源),范围比本仓库已同步的 LeetCode 子集更大。
111+
> 两个数字都**由脚本接管、禁止手写**:256 来自本仓库 manifest,299 随站内 content-stats 同步回填(见 [`docs/data/stats.json`](docs/data/stats.json)`siteTotal` 字段)。
112+
113+
---
114+
115+
## 内容地图
116+
117+
| 想找什么 | 从这里开始 |
118+
| :-- | :-- |
119+
| 按题号查动画 | [`docs/leetcode-animation-index.md`](docs/leetcode-animation-index.md) |
120+
| 按专题查动画 | [`docs/index-by-topic.md`](docs/index-by-topic.md) |
121+
| 用脚本处理题目数据 | [`docs/data/manifest.json`](docs/data/manifest.json) |
122+
| 查看早期题解文章 | [`docs/notes/`](docs/notes)[`problems/`](problems) 下各题的 `Article/` |
123+
| 查看早期动画素材 | [`problems/`](problems) 下各题的 `Animation/` |
124+
| 查看同步记录 | [`docs/sync-log.md`](docs/sync-log.md) |
125+
126+
---
127+
128+
<details>
129+
<summary><strong>🛠 维护者:同步与数据说明</strong>(点击展开 —— 普通读者可略过)</summary>
130+
131+
### 仓库和网站的关系
132+
133+
GitHub 仓库保存历史内容、公开索引和同步脚本;网站侧维护当前动画页面。交互播放、步骤切换、阅读体验以网站版本为准。同步脚本把网站题目列表写回仓库,方便在 GitHub 上审阅、检索和版本化。
134+
135+
### 同步方式
136+
137+
网站侧题目索引来自 `study_index.js`。同步前先审查:
138+
139+
```bash
140+
npm run review:site
141+
```
142+
143+
确认需要同步后运行:
144+
145+
```bash
146+
npm run sync # 更新 manifest / 题号索引 / 专题索引 / 同步记录
147+
npm run validate # 校验 manifest
148+
node tools/scripts/build-readme.js --write # 把 README 数字段 + stats.json 重新注入
149+
```
150+
151+
会更新:
152+
153+
- `docs/data/manifest.json`
154+
- `docs/leetcode-animation-index.md`
155+
- `docs/index-by-topic.md`
156+
- `docs/sync-log.md`
157+
- `docs/data/stats.json` 与 README 的 `当前索引` 标记区(数字段)
158+
159+
更完整的判断规则、commit 规范和数字接管机制见 [`docs/sync-workflow.md`](docs/sync-workflow.md)[`docs/HOW-TO-INTERACT.md`](HOW-TO-INTERACT.md)
160+
161+
### 目录
162+
163+
| 路径 | 说明 |
164+
| :-- | :-- |
165+
| `docs/data/manifest.json` | LeetCode 动画索引数据(数字单一数据源) |
166+
| `docs/data/stats.json` | 由脚本实算的计数,供 README 徽章读取 |
167+
| `docs/leetcode-animation-index.md` | 由 manifest 生成的题目列表 |
168+
| `docs/index-by-topic.md` | 由 manifest 生成的专题索引 |
169+
| `docs/sync-log.md` | 网站侧索引同步记录 |
170+
| `docs/sync-workflow.md` | 网站和 GitHub 联动流程 |
171+
| `tools/scripts/review-site-changes.js` | 判断网站侧改动是否需要同步 |
172+
| `tools/scripts/sync-algomooc-index.js` | 从网站侧 `study_index.js` 同步索引 |
173+
| `tools/scripts/validate-manifest.js` | 校验 manifest |
174+
| `tools/scripts/build-readme.js` | 注入 README 数字段 + 生成 `stats.json` |
175+
| `docs/assets/previews/` | README 使用的网站版动画预览 GIF |
176+
| `docs/notes/` · `problems/` | 早期题解文章、代码与动画素材 |
177+
178+
</details>
179+
180+
---
181+
182+
## ⭐ Star 一下,见证 299 役收官
183+
184+
[![Star History Chart](https://api.star-history.com/svg?repos=MisterBooo/LeetCodeAnimation&type=Date)](https://star-history.com/#MisterBooo/LeetCodeAnimation&Date)
185+
186+
这个项目从一张张手画动画走到今天,靠的是每一个 Star 的鼓励。
187+
如果它让你把某道题真正看懂了,**点个 Star** 就是对持续更新最实在的支持。
188+
189+
> 📌 内容持续同步自 **[algomooc.com](https://www.algomooc.com/leetcode-animation?utm_source=github&utm_medium=readme&utm_campaign=lca_revamp&utm_content=footer_site)** —— 网站更新,仓库索引随脚本同步。
190+
191+
## English
192+
193+
See [`docs/README-En.md`](docs/README-En.md).

0 commit comments

Comments
 (0)