Practice019 趣味代码收录（fun-code-reverse）
目标与边界
做：把用户点名的一段有趣代码——通常是某个大文件里的一小部分——介绍清楚，并配一个最小可运行 demo，按七节模板收录成条目。
条目的三个部件，分工不许混：
| 部件 | 职责 | 回答的问题 |
|---|---|---|
| 条目 README 的「它是怎么做到的」 | 讲清机制与效果 | 为什么妙 |
| 「关键片段」（从原代码摘 10~40 行） | 原代码佐证 | 我没编 |
demo.<ext>（30 行内、能跑） |
最小可运行复现 | 你能跑 |
不做：
- ❌ 不写「复刻提示词」——不需要描述代码的第三份文本；demo 本身就是可执行的说明书
- ❌ 不搬运带噪声的原始文件——只留关键片段 + demo
- ❌ 不造 demo 之外的产物（截图、第二份独立版、测试脚本、性能报告、验证报告）
- ❌ 不追查缺失的工具或 skill——查一次不中就走本手册的手工流程
- ❌ 不写逐行翻译式讲解（讲解管机制与效果，片段管精确写法）
- ❌ 不交付没跑过的 demo
- ❌ 不主动 push
输入契约
一句话即可开工：收录 <代码或文件+行号>，加上用户觉得有趣的功能点原话。
| 要素 | 必需 | 缺失时怎么办 |
|---|---|---|
| 代码来源（路径+行号 / 粘贴片段 / URL） | ✅ | 问一次 |
| 用户点名的功能点（原话） | ✅ | 问一次，用其原话复述请其确认 |
| 出处（原项目 URL / 本地文件） | 可选 | 写「本地文件 X」 |
只有功能点缺失或模糊才追问，且只问一次——其余一切自行决定。 点名功能点必须来自用户原话：AI 不得用「代码客观亮点」自作主张替代——用户的兴趣点常与代码的客观亮点不同，自选功能点会让整条收录做无用功。
流程（默认路径，四步）
- 定位：在原文件里只保留点名功能的执行路径。判据：把一段删掉后，点名功能是否依然成立？成立即噪声。顺手记一句「核心机制占原文件的比例」——比例越小，越说明收录这个决定是对的。
- 写条目：
<snippet-name>/README.md（七节模板）+<snippet-name>/demo.<ext>（见「最小 demo 规范」），并跑一次 demo 确认能跑。 - 加索引行：根
README.md的「📌 收藏清单」表末尾加一行：| [<snippet-name>](<snippet-name>/) | 一句话简介 | <类型> / 逆向收录 | - 给 commit 命令：显式路径，不用
git add -A（见「仓库与提交」）。
命名：英文小写连字符，表达效果主题。同名条目已存在 → 先确认是更新还是新建。
第 5 件事（仅当用户明确要求）
只有用户说「我要一个完整可用的版本」「要能直接上线用」之类时，才在 demo 之外再产出完整实现。此时才扩展产物与验证范围；否则 demo 到此为止——它是演示，不是产品。
最小 demo 规范
demo 的验收标准只有一条：没读过原代码的人，跑起来就能亲眼看到那个效果。
- 30 行以内（硬上限 40，含注释）；demo 是「最小可运行」，不是完整实现
- 单文件、零依赖、零构建：HTML 直接双击打开 / 单文件脚本直接执行；不装包、不起服务、不要配置文件
- 只留点名功能的机制，砍掉一切配置项、日志、错误处理、兼容代码、业务字段
- 参数给确定值：随机策略给固定 seed，尺寸给固定数，路径写死——保证任何人跑出来看到一样的效果
- 必须跑过一次并看到效果：终端类在终端跑；浏览器类用无头浏览器跑一次确认无报错。跑不通就修 demo，不交付没跑过的 demo
- demo 是重写的最小版，不是原代码副本——README 必须写明这一点，原代码的佐证由「关键片段」一节承担
文件命名：demo.html / demo.py / demo.bat / demo.css，扩展名体现语言。
关键片段（从原代码摘）
- 10~40 行，可独立阅读；只留点名功能的机制
- 尽量保留原变量名与真实参数——这是片段作为佐证的价值；改名重写会让它失去「原代码佐证」资格
- 头部注明：
提炼自 <文件> 第 X-Y 行，节选有删减+仅作复刻参考 - 可补上下文注释（变量含义、调用前提），不得为可读性改写逻辑
- 用户直接粘片段 → 粘的就是关键片段，补一行来源标注即可，不要再去找原文件
条目 README 七节模板
# <snippet-name>
> 一句话：这个效果是什么、为什么有趣。
## 这是什么
（大白话讲清：用户看到什么现象、用在哪、为什么值得收藏）
## 它是怎么做到的
（**本条的讲解主体**：机制分点讲透——输入是什么、每步做了什么、关键数值多少、
为什么这么写能出这个效果。要让人读完后能自己复述出原理，而不是只知道"很酷"）
## 关键片段
（内联贴出从原代码摘的 10~40 行，注明提炼自哪个文件哪些行）
## 最小 demo
（本目录 `demo.xxx`：说明它演示了哪个机制、相对原代码砍掉了什么。
明确写「demo 为最小重写版，非原代码副本」）
## 怎么跑
（最小命令 / 双击哪个文件 / 打开后看哪里）
## 值得收藏/复刻的点
（最妙的地方：技巧、模式、坑——包括原代码的隐患与改良方向）
## 来源
（原链接/出处 + 提炼自哪个文件，注明仅供学习复刻参考）
一次点名多个功能点 → 每个效果主题一个条目，不塞进同一个 README。
自检（落笔前一次做完，禁止事后补丁轮）
在声称完成之前一次性过一遍，不做「写完再发现要核对」的返工：
- 七节齐全且每节都有真内容；
- 「它是怎么做到的」读完后能复述原理，不是形容词堆砌；
- 关键片段的行号与来源文件对得上（行号必须真实可回溯）；
- demo 实际跑过，而且跑出来的效果与「这是什么」描述的一致；
- demo 行数达标、单文件零依赖、参数都是确定值；
- README 已注明 demo 是最小重写版；
- 根 README 索引行已加，路径与文件夹名一致（不出现指向已删条目的行）；
- 讲解、片段、demo 三者无矛盾——这是替代"生成验证"的质量门。
仓库与提交
目标仓库：D:\project_GIT\fun-code-collection（默认收录库）
- 结构：一个条目 = 一个子文件夹，内含
README.md+demo.<ext>（+ 需要时保留关键片段文件） - 提交（显式路径）：
cd /d/project_GIT/fun-code-collection
git add <snippet-name>/ README.md
git commit -m "add: 新收藏 <snippet-name>"
禁止 git add -A：它会把工作区里与本任务无关的状态一并提交——例如某个条目正处于待删除状态、某个目录还是未跟踪。只 add 本次真正动过的路径。
- 不 push，用户明确要求时才推。
规则级进化（有则写，无则不动）
任务结束前自问一句：本次有没有一条去掉项目细节后依然成立的经验？
写入门槛，三问全过才写进 playbook.md（相对本技能目录）：
- 可泛化：表述里不出现具体项目名、文件名、一次性细节；
- 可执行：写成「遇到 X 类情况 → 做 Y」的指令，不是复盘叙事；
- 非重复：已有同类规则就合并增强原规则，不新增条目。
格式：- **R-xxx** ｜ 适用：<场景> ｜ <指令式规则> ｜ <一句理由>
无新规则就什么都不写——不为了写而写。playbook 总数 >40 或单节 >15 时，合并同类项、淘汰不再适用的规则。 若经验暴露的是本 SKILL.md 主流程本身的缺陷，直接修主流程，而不是只记一条规则。
双副本同步
SKILL.md 与 playbook.md 有两份内容必须一致的副本：
- 主副本（DSH）：
~/.dsh/skills/fun-code-reverse/ - 副本（ZCode）：
~/.zcode/skills/fun-code-reverse/
改动任一文件后，把两个文件复制到另一份。两份不一致就是没收尾。
（注意：~/.dsh 目录本身不受 git 管理，不要假定副本有版本控制兜底。）
常见坑
- demo 悄悄长大 → 一旦为了"更完整"加配置、加参数、加分支，它就从演示退化成小项目，跑不通的风险随行数非线性上升。行数超标就砍功能，不加解释。
- demo 与原代码不一致却不说 → 必须在 README 注明 demo 是最小重写版、砍掉了什么，否则读者会拿 demo 当原代码理解，形成错误认知。
- 依赖外部条件的效果 → 片段与 demo 只覆盖可复现部分，外部前提（服务、数据、硬件）写进「值得收藏/复刻的点」或「怎么跑」；不注明会让人把「缺前提」误判成「demo 坏了」。
- 索引行与目录脱节 → 加条目必须同时改根 README；删条目必须同时删行（README 还挂着已删条目，等于索引在撒谎）。
- 引用不存在的工具 → 文档里任何「已安装 / 已支持」的声称，先验证再写。
- AI 自选亮点 → 收录一律以用户点名为准；AI 自己觉得有趣但用户没点名的功能不收。