开源作者 / 仓库蒸馏术

提炼作者在代码里反复兑现的工程判断，而非复刻说话方式。

核心目标

生成可运行的工程顾问 Skill，不是聊天人格。Skill 必须能指导：写代码、改代码、code review、API/架构设计、重构、debug、性能分析和 maintainer 决策。

生成的 Skill 必须能回答：

它如何定义复杂度？如何切分边界、接口和状态？
它如何在性能、可读性、兼容性、可维护性之间取舍？
它会拒绝什么样的抽象、依赖和功能请求？
在什么证据不足时必须诚实收口？

关键区分：捕捉的是 HOW they build，不是 WHAT they tweeted。

优先采集一手材料：代码、PR / issue 讨论、设计文档、邮件列表 / 技术博客。

默认输出偏好：面向 patch / module / interface 级判断和可执行建议，而非人物口吻复刻或空泛价值观。

执行流程

Phase 0: 入口分流

收到请求后，先判断属于哪条路径：

用户输入	路径	示例
明确作者/仓库/团队	直接路径 → Phase 0A	「蒸馏 Linus」「做个 Vue 仓库 skill」
明确的软件开发难题，但未指定对象	诊断路径 → Phase 0B	「我想优化前端工具链 API 设计」

Phase 0A: 需求澄清（直接路径）

收到明确作者、仓库或维护团队后，确认：

蒸馏对象：是单个作者、作者+核心仓库、单个开源仓库，还是一个维护团队/组织？
聚焦维度：全面蒸馏，还是聚焦架构/API/性能/代码审查/维护决策？
用途：代码评审顾问、架构顾问、重构顾问、调试/性能顾问、maintainer视角，还是仅在明确要求时做轻度角色模拟？
新建 or 更新：是否已有该对象的 Skill？
本地语料：是否已有本地仓库、patch、issue dump、邮件列表归档、design doc？

默认行为：

用户只说「做个XX作者skill」→ 全面蒸馏 + 工程顾问用途 + 无本地仓库则走公开资料模式
用户只说「做个 XX 仓库 skill」→ 按仓库/团队 Skill 处理，重点提炼维护共识、公共 API 边界、版本策略、review 标准和典型开发路径
用户给了仓库/代码/issue 导出 → 标记为本地仓库优先模式
用户说「只分析这个仓库」→ 标记为单仓库模式
未明确要求角色扮演 → 默认不做第一人称模仿

确认后 → 进入 Phase 0.5。

Phase 0B: 需求诊断（模糊路径）

用户不知道蒸馏谁，但已经有明确的软件开发问题。此时要做的是：从工程困境反推适合蒸馏的作者、仓库或工程流派。

Step 1: 需求定位

通过 1-2 轮追问定位工程维度（最多追问 2 轮，目标是定位工程场景，不收集背景故事；如果用户已经明确到具体问题则直接推荐）：

需求维度	典型表达	推荐方向
复杂度控制	「系统越来越乱」「越修越臃肿」	极简抽象、状态压缩、约束优先
API / 库设计	「接口越来越不好用」「兼容性很痛苦」	API surface 克制、breaking change 哲学、版本策略
性能与系统编程	「热点很多」「资源约束强」	热路径优先、零成本抽象、测量先于优化
可维护性	「接手的人看不懂」「补丁越来越危险」	invariants、模块边界、测试策略
Maintainer 决策	「feature request 太多」「不会拒绝 PR」	范围控制、演进纪律、兼容性原则
前端 / 框架设计	「抽象太重」「状态流失控」	声明式边界、约束式 API、逃逸口设计
工具链 / 编译器 / 基础设施	「系统复杂但必须稳定」	明确分层、错误模型、向后兼容

追问原则：

最多追问 2 轮
追问的目标是定位工程场景，不是收集背景故事
如果用户已经明确到「我要学 maintainer 如何处理 breaking changes」，直接推荐，不再追问

Step 2: 候选推荐

推荐 2-3 个作者、仓库或流派，必须说清楚：

这个对象解决的是哪类工程问题
它的一套方法在哪些场景有效
盲区是什么

展示格式：

### 候选1: [作者名 / 仓库名 / 主题]  ⚡已有Skill / 🆕需要蒸馏

**核心判断维度**：[一句话]
**为什么适合你**：[和用户诉求的对应关系]
**局限**：[不适合什么团队/系统/阶段]

推荐原则：

不超过 3 个候选
候选之间必须有明显工程哲学差异
不说「他很厉害」，只说「他的哪种判断结构适合这个问题」

Step 3: 用户选择

选择已有 Skill → 直接激活
选择新候选 → 进入 Phase 0A / Phase 0.5
都不满意 → 继续推荐或由用户指定

Phase 0.5: 创建 Skill 目录

收到确认后立即创建：

skills/[target]-playbook/
├── SKILL.md
├── scripts/      # 可选
└── references/
    ├── research/
    │   ├── 01-repos-architecture.md
    │   ├── 02-commits-and-prs.md
    │   ├── 03-issues-and-reviews.md
    │   ├── 04-docs-talks-writings.md
    │   ├── 05-decision-cases.md
    │   └── 06-evolution-and-lineage.md
    └── sources/   # 可选：需要固化原始证据时再创建
        ├── repos/
        ├── docs/
        ├── issues/
        └── talks/

目录命名统一后，通过 SKILL.md frontmatter 区分对象：

name: [target]-playbook
metadata:
  subject_type: author | project | team

完成检查：

目录已创建
如果是更新模式，已读取现有 Skill 并标记待刷新的部分
如果用户提供了本地仓库、导出文件或需要固化原始证据，已归档到 sources/
已确认蒸馏对象是“作者主导风格”还是“仓库 / 团队维护共识”

关键规则：

所有调研结果必须落到 references/research/
Skill 必须自包含，复制目录即可使用
如果作者痕迹被团队稀释，必须明确写入边界，不能硬说“这就是他个人风格”
不绑定 Claude、Codex 或其他宿主目录，统一按 skills/... 组织
所有产物统一用 [target]-playbook
对象类型通过 SKILL.md frontmatter 的 metadata.subject_type 区分

Phase 1: 多源采集（代码优先）

模式判断

模式	触发条件	策略
纯本地语料模式	用户明确只用给定材料	只分析本地仓库/patch/doc，不做外部搜索
本地仓库优先	用户提供了仓库或可读取源码	先做代码直接读取，再用公开资料补缺
混合模式	有部分本地材料，但不完整	代码、commit、issue 为主，外部资料为辅
公开资料模式	没有本地仓库	先抓核心仓库、历史提交、公开讨论
单仓库模式	用户明确只蒸馏某个仓库	只围绕该仓库，不外推到整个人

网络搜索采集顺序

进入公开资料模式或混合模式后，不要无序广搜；按下面顺序推进：

先抓官方仓库与官方文档
- 核心仓库 README / docs / CONTRIBUTING / 包结构 / tests / benchmarks
- 官方 blog / release notes / migration guide / RFC / design discussion
再抓维护痕迹
- commit 历史
- PR / issue 讨论
- maintainer review comment
- 回滚、deprecate、breaking change 的处理记录
再抓生态与集成证据
- 官方 plugin / adapter / integration example
- ecosystem CI、兼容性矩阵、迁移案例
- 主要下游项目对该仓库的依赖与反馈
最后才用二手材料补线索
- 二手文章只能帮忙发现线索，不能替代原始代码、原始讨论和原始文档

搜索原则：

每个研究维度至少先拿到 1 份一手材料；要升级为“稳定结论”，至少满足以下三类证据中的两类：代码/仓库事实、维护讨论、文档/发布说明
如果某个判断只来自单一 README、单个 issue 或单篇博客，只能先记为「观察」或「推断」
对流行仓库，演化维度至少覆盖最近 12 个月的重要 release / breaking change，避免结论过时
对仍在活跃演进的仓库，架构 / 变更 / 评审 / 决策四个维度都要至少检查当前 major 版本周期内的材料
如果已经拿到足够一手证据，就停止继续堆来源，优先进入提炼

研究维度的检索配方

为避免“知道要搜什么，但不知道怎么搜”，按维度使用下列默认检索配方：

1 架构
- 先读：README、docs/、CONTRIBUTING、packages/、src/、tests/
- 再搜：architecture、design、monorepo、workspace、package boundary
2 变更
- 先读：CHANGELOG、releases、migration、deprecation
- 再搜：breaking change、revert、rollback、deprecated、release notes
3 评审
- 先读：有代表性的 issues、pull requests、review comments
- 再搜：not planned、wontfix、discussion、review comment、feature request
4 文档
- 先读：官方文档、设计说明、博客、RFC、演讲材料
- 再搜：RFC、proposal、design discussion、why、philosophy
5 决策
- 先读：重大迁移、架构提案、回滚记录、生态冲突案例
- 再搜：decision、tradeoff、why not、revert、migration path
6 演化
- 先读：时间线、版本历史、早期与近期仓库差异
- 再搜：initial release、major release、roadmap、deprecate、history

如果对象是组织 / 团队，还应额外检索：

template、starter、reference app
ecosystem、integration
agent、skill、schema、catalog
sandbox、workflow、observability

工作辅助与已安装 Skill

采集阶段优先使用这些工作辅助，而不是手工散搜：

调研合并：scripts/merge_research.py <skill目录路径>
视频 / 演讲材料存在时：
- scripts/download_subtitles.sh <YouTube_URL> [references/sources/talks/]
- scripts/srt_to_transcript.py input.srt [output.txt]
若当前环境已有合适的信息获取 Skill，可在命中场景时优先调用：
- pdf 类 Skill：读取 PDF 版设计文档、RFC、论文、白皮书
- 官方文档读取类 Skill：精读官方文档，而不是只看搜索摘要
- 网页精读 / 深度研究类 Skill：读取长文、长讨论、design doc
- 视频 / 字幕类 Skill：处理高价值演讲、会议分享、maintainer talk

使用原则：

脚本用于提速与规范输出，不替代判断
脚本输出仍需人工区分一手 / 二手 / 推断
若某个脚本不适用当前对象，不要为了“用工具”而用工具
不把宿主环境里的某个 Skill 写成硬依赖
优先使用“能提高一手信息提取质量”的 Skill，而不是泛泛增加工具数量
任何额外 Skill 的输出，都不能绕过本 Skill 的证据分级和黑名单规则

6 个研究维度（默认顺序执行，必要时再并行）

默认由当前代理顺序完成以下 6 个研究维度。只有在运行环境支持、任务规模确实需要，并且用户明确要求委派或并行时，才拆给多个 Agent。

研究维度	重点对象	提取重点	输出文件
1 架构	核心仓库、目录结构、核心模块	边界划分、状态管理、抽象深度、依赖策略	`01-repos-architecture.md`
2 变更	commit、PR、release	高频改动模式、重构方式、breaking change 处理、回滚习惯	`02-commits-and-prs.md`
3 评审	issue、review、讨论串	接受/拒绝 feature 的理由、对 bug 和兼容性的态度、review 关注点	`03-issues-and-reviews.md`
4 文档	README、design doc、博客、演讲	作者自己说出的原则、术语、设计目标	`04-docs-talks-writings.md`
5 决策	关键工程事件	重大取舍案例：为什么选 A 不选 B	`05-decision-cases.md`
6 演化	时间线、谱系、生态影响	风格何时形成、何时转向、受谁影响、影响了谁	`06-evolution-and-lineage.md`

如果蒸馏对象是仓库 / 团队，还要在这些维度里特别关注：

公共 API 稳定性与 breaking change 策略
目录与子包边界
插件 / 扩展点设计
贡献者协作方式与 review 门槛
文档、RFC、迁移指南、测试矩阵

每个研究维度的硬性要求

只把有证据链的内容写入 research 文件
区分：作者亲自写的/合并的 vs 团队其他成员代写或转述的 vs 根据代码行为做的推断
发现矛盾时保留矛盾
如果某结论只在一个仓库成立，不要外推出“这是他的通用风格”

证据记录格式

research 文件中的每条核心证据，至少记录：

来源链接或文件路径
来源类型：code / commit / pr / issue / doc / release / talk / blog
时间点：提交时间、发布时间或版本号
事实摘要：发生了什么，不超过 2-4 行

没有这些字段的“印象性笔记”，不能直接作为 Phase 2 的主输入。

信息源优先级

来源类型	揭示什么	权重
用户提供的一手材料	当前任务最直接的证据	最高+
作者直接提交的代码与 commit	真实工程取舍	最高
作者主导的 PR / issue 回复	维护决策标准	最高
设计文档 / README / 技术博客	明示原则	高
release note / change log	演化方向	高
演讲 / 访谈 / 邮件列表	口头解释和背景	中
他人分析文章	外部观察	低
二手总结帖	只作线索	最低

仓库 / 团队 Skill 额外优先关注：

RFC / design discussion
官方 migration guide
官方 test / e2e / benchmark 目录
maintainer review comment
ecosystem integration example

补充原则：

对开源仓库蒸馏来说，代码、review、release、migration 的权重通常高于采访、媒体报道和技术解读
如果用户提供了本地一手材料，它的优先级高于任何网络二手总结
若公开发言与代码行为冲突，优先并列记录，不强行调和
同源转述不算多源验证；多个媒体转载同一个官方公告，仍只算一个来源
二手文章若不能回到原始 commit / PR / issue / RFC / release，不得为核心结论加权
同一事实被 README、博客、媒体解读反复引用时，按“原始来源 + 若干转述”处理，不得误算为多源共识
镜像站、搬运站、聚合页、缓存页默认视为同源副本；Phase 1.5 汇总时优先统计“独立来源数”，而不是页面总数

信息源黑名单

排除以下来源作为主证据：

没有贴原始代码或原始讨论链接的二手总结
纯情绪化吹捧/贬损内容
AI 洗稿式"某某代码风格解析"
只摘金句、不含上下文的短帖
搬运、镜像、聚合页中被截断上下文的讨论
只给结论、不贴 commit / PR / issue / RFC / release 原始链接的媒体解读
SEO 导向的“X vs Y”“10分钟看懂某仓库源码”式博客
中文互联网来源中的知乎、微信公众号、百度系内容，若不附原始仓库或原始讨论链接，只能作线索，不能作主证据

搜索超时与失败处理

单个研究维度若连续搜索一段时间仍拿不到新增一手证据，不要无限扩搜；记录“信息不足”并继续推进其他维度
若可用来源明显过少，及时降低期望：减少判断维度数量，增加诚实边界篇幅
若不同来源互相冲突，保留冲突与来源层级；矛盾本身就是结果
宁可交付一个明确写出证据缺口的保守 Skill，也不要用推测补齐成看似完整的版本

代码读取重点问题

调研时优先回答这些问题：

他在哪里主动减少状态、配置、抽象层？
他在哪里接受局部重复，换取全局简单？
他如何命名边界？
他何时引入新依赖，何时宁可自己实现？
他如何处理兼容性债务？
他在 review 中真正卡住别人的是什么？
当性能与可读性冲突时，他先保什么？

如果对象是 React、Vite 这类流行开源仓库，还要优先回答：

仓库如何保护公共 API 与生态兼容性？
maintainer 如何划分核心包、外围包、实验能力？
哪些扩展点被鼓励，哪些 hack 会被拒绝？
新功能进入主线前，需要经过哪些 RFC、测试或迁移门槛？

辅助脚本

采集演讲、访谈、conference talk 等视频材料时，可使用：

# 下载 YouTube 字幕（优先人工字幕，无则自动生成；中文优先）
scripts/download_subtitles.sh <YouTube_URL> [references/sources/talks/]

# 将 SRT/VTT 字幕清洗为可读纯文本
scripts/srt_to_transcript.py input.srt [output.txt]

Phase 1.5: 调研 Review 检查点

完成研究后，如任务复杂、证据分散，或需要向用户同步可信度，可展示调研质量摘要：

┌──────────────────────┬──────────┬────────────────────────────┐
│ 研究维度                │ 证据量    │ 关键发现                    │
├──────────────────────┼──────────┼────────────────────────────┤
│ 1 架构               │ N个模块   │ 边界偏好 / 状态策略         │
│ 2 变更               │ N个提交   │ 重构模式 / breaking change  │
│ 3 评审               │ N条讨论   │ 拒绝 feature 的理由         │
│ 4 文档               │ N篇文档   │ 作者明说的原则              │
│ 5 决策               │ N个案例   │ 关键取舍                    │
│ 6 演化               │ 完整/部分  │ 风格形成与演化              │
├──────────────────────┼──────────┼────────────────────────────┤
│ 稳定结论             │ N条       │ 多源验证通过                │
│ 推测性结论           │ N条       │ 证据不足                    │
│ 信息不足维度         │ N项       │ 例如 review 资料太少        │
└──────────────────────┴──────────┴────────────────────────────┘

除非用户明确要求逐阶段确认，否则展示后可直接进入 Phase 2。

可使用辅助脚本自动生成摘要表格：

scripts/merge_research.py <skill目录路径>
# 示例: scripts/merge_research.py skills/linus-playbook

Phase 2: 框架提炼

先读取 references/extraction-framework.md，按其中的方法论执行以下全部提炼。

该文件包含：三重验证标准、代码/评审/变更特征提炼方法、开发任务映射方法、矛盾处理原则、信息不足处理规则、作者 Skill vs 仓库/团队 Skill 差异、质量自检清单。

Phase 2 的交付物：

交付物	要求
工程判断维度	3-5 个，每个须通过三重验证（跨场景复现、有生成力、有排他性），写明名称、一句话定义、证据场景（≥2）、应用方式、失效条件
决策启发式	5-10 条，写成「如果 X 则优先 Y」「除非 Z 否则不接受 A」格式，每条有真实案例
代码特征	覆盖命名习惯、抽象深度、状态策略、错误处理、依赖偏好、测试观
评审特征	先抓什么、容易否决什么、如何表达拒绝
变更特征	改动粒度偏好、是否先补测试、风险改动推进策略
开发任务映射	至少覆盖 4 类真实开发任务（新功能/Bug/Review/重构/API设计/性能优化），每类写清先读什么、先问什么、倾向怎么改、如何验证、何时拒绝
反模式	最反感的设计错误、会直接拒绝的 PR 类型、长期债务模式、"看起来灵活实际有毒"的模式
演化与谱系	受谁影响、影响了谁、早期风格修正、长期稳定观点
诚实边界	单仓库局限、代码证据 vs 公开发言区分、团队归因问题、不同语言/阶段风格差异、信息截止日期

Phase 2.5: 提炼确认检查点

提炼完成后，如需要同步提炼质量，可展示摘要：

提炼结果摘要：
- 工程判断维度：N个（列名称）
- 决策启发式：N条
- 代码特征：[3个关键特征]
- 评审特征：[3个关键特征]
- 变更特征：[3个关键特征]
- 开发任务映射：覆盖哪些任务类型
- 反模式：N条
- 边界：N条

除非用户明确要求逐阶段确认，否则展示后可直接写最终 Skill。

Phase 3: Skill 构建

先读取 references/skill-template.md，按模板结构填充最终 Skill。

该模板包含：frontmatter 格式、激活规则、核心判断维度、决策启发式、代码/评审/变更特征、开发任务映射（6 类任务的完整协议）、反模式、编码任务工作流（Agentic Protocol 4 步：问题分类 → 取证 → 套用判断维度 → 输出）、适用/不适用场景、演化谱系、诚实边界、附录来源。

构建规则：

统一放在 skills/[target]-playbook/ 下
对象类型通过 metadata.subject_type: author | project | team 区分
SKILL.md frontmatter 里的 description 必须同时写清：它是什么、能解决什么开发问题、在什么用户表达下应触发；不能只写“这是某某的工程判断方式”
默认作为工程顾问，不做第一人称模仿
没看代码时不装作已看过，没有历史上下文时不虚构立场
对新问题做推断时，明确标注"这是基于判断维度的推断，不是作者明确说过的话"
通过标准是"能不能指导改代码"，不是"说得像不像"
必须能落到具体开发动作：先读哪些文件、先做哪类验证、最小改法是什么、风险在哪里

Phase 4: 质量验证

生成 Skill 后，用独立视角做 4 项测试：

4.1 已知案例测试

选 3 个作者公开处理过的问题（一个架构/API 取舍、一个性能/实现取舍、一个接受/拒绝 PR 的案例），让 Skill 回答，再与真实处理方式对比。

4.2 新问题推断测试

给一个作者没明确谈过、但风格相关的新问题。期望：有明确倾向、说明依据维度、有不确定性标记。

4.3 Coding / Patch Review 测试

给一个小功能或小 patch，让 Skill 给出改法或 review。检查是否真的抓到：先读哪些代码和约束、接口面、边界污染、状态复杂度、最小改动路径、测试回归点、兼容性或维护成本。而不只是泛泛说"代码可以更简洁"。

4.4 边界测试

给超出擅长领域的问题。期望：Skill 明确收口，不把单仓库偏好强行泛化成普世真理。

通过标准

读取 references/extraction-framework.md 末尾的质量自检清单，逐项核对。也可使用辅助脚本自动检查：

scripts/quality_check.py <生成的SKILL.md路径>
# 示例: scripts/quality_check.py skills/linus-playbook/SKILL.md

核心要求：

检查项	通过标准	不通过信号
判断维度数量	3-5 个，每个有多场景证据	太少或全是套话
决策启发式	每条有真实案例	只有空泛原则
代码/评审特征	能指导写代码、review 或设计判断	只有语气模仿
开发任务映射	≥4 类任务，写清先读/怎么改/怎么验	抽象理念无落地
反模式	≥3 条明确拒绝项	只写"追求质量"
诚实边界	标明单仓库/团队归因问题	全知全能设定
新问题推断	有倾向且有保留	斩钉截铁乱猜

Phase 5: 更新已有 Skill

当用户说「更新 XX 作者 skill」或「更新 XX 仓库 skill」时：

读取现有 Skill 的调研截止日期
重点更新：
- 新 release / breaking change
- 新的 maintainer 决策
- 新增代表性 commit / PR / issue
- 风格是否出现转向
如果只是新增案例 → 补充到已有判断维度
如果出现明显新原则 → 考虑新增判断维度
优先增量更新，不重写整个 Skill

品味守则

原则	含义
代码 > 访谈	代码行为比口头原则更可信
拒绝 > 宣言	拒绝什么比宣称什么更暴露底层偏好
演化 > 金句	风格变化比名言更有信息量
边界 > 技巧	守住系统边界比某个技巧更能定义作者
维护 > 首稿	改别人代码比自己首稿更暴露标准

绝不做的事：

把仓库流行写法误判成作者个人风格
把团队共识硬写成个人天才直觉
从一两个 commit 推出完整方法论
把通用工程常识包装成作者独特判断维度
没看代码就假装"某某一定会这样做"

特殊场景

单仓库作者

可以蒸馏，但必须标注「该 Skill 高度依赖此仓库证据」，不轻易外推到别的语言或系统。

团队主导项目

个人痕迹弱时优先做仓库/团队 Skill（如 vue-playbook），不强行做个人 Skill。

作者公开表达极少

更依赖代码、提交和 issue，判断维度缩减到 2-4 个，诚实边界加重，明确哪些结论主要来自行为推断。

作者横跨多个时代或技术栈

分阶段记录，以近期稳定风格为主，早期风格作演化线索，不揉成统一人格。

蒸馏开源团队

保留大流程，把"工程判断维度"改为"维护共识"，把"评审特征"提炼成团队标准，明确是组织风格而非个人风格。

蒸馏流行开源仓库

默认做 [target]-playbook，标明 metadata.subject_type: project。优先调研核心包结构、公共 API、扩展点、RFC、迁移文档、测试矩阵和 maintainer review。最终 Skill 要能回答"按这个仓库标准应该怎么写 patch / 设计插件 / 控制 breaking change / 补测试"，不是项目介绍或生态宣传。

oss-skill