KnowPitch 球知

用足球阵型把知识领域拆解成一支球队来深入学习与讲透。触发 kp11/kpt/kpitch/knowpitch 加主题；产出阵型图 SVG、ELI5 风格球员卡与教练战术板。Do NOT use for 快速概念解释（用 ELI5）、思维导图、闪卡、非知识类主题（情感/咨询）、需要精确数据的报告。

KnowPitch — 阵型学习法

Put your knowledge on the pitch.

（把你的知识放上球场）

适用边界

✅ 适合： 系统学习、知识梳理、备考复习、教学准备、概念深度理解

❌ 不适合： 快速问答、情感咨询、精确数据分析、代码调试、纯事实查询

前置条件

• Python 3.8+（用于生成阵型图 SVG）。本机按 python3 → python → py -3 的顺序取第一个可用命令（Windows 通常只有 python）

• 主题必须是 "知识类"（有明确概念体系），非情感 / 观点类

• 如需外部事实，先检索 / 读资料，确保知识点有来源、不编造

核心思维模式

排阵型前先问自己： 这个主题的 "门将" 是什么？

（最底层、丢了就全崩的基础） 这个主题的 "前锋" 是什么？

（最终要回答的核心结论） 中间的 "中场" 如何把基础变成结论？

（机制 / 方法 / 思想）

这个技能是什么

把任何知识领域当作一支足球队来理解：知识点是球员，按职能排进 4-3-3、4-2-3-1 等阵型，

再配一个主教练（一句话核心思想）、一个门将（底线基础）和替补席（进阶知识点）。

每个 "球员" 都用 ELI5 的方式讲成大白话。最后交付：阵型图（SVG）+ 球员卡 + 教练战术板。

它内化了 ELI5 技能的内核，因此所有讲解遵循：

假设零背景，不是零智商（assume zero background, not zero intelligence） 用 5 岁小孩也能懂的大白话 + 日常类比，但不牺牲准确性。 每个专业词第一次出现时，紧跟一句大白话解释。 短句、短段、口语化；先讲 "它是干嘛的"，再讲 "怎么做到"，最后讲 "为什么重要"。

工作流

按顺序执行：

Step 1: 识别主题与深度需求

• 解析用户请求，确定要学习的主题

• 解析受众参数（--age/--job/--grade），调整语言难度和类比方向

• 判断用户需要的深度：

  • kpt / 快速模式：≤ 5 个知识点，精简阵容

  • kp11 / 默认模式：6-11 个知识点，标准阵容

  • kpitch / 完整模式：> 20 个知识点，启用 B 队

• 如需外部事实，先检索 / 读资料，确保知识点有来源、不编造；拿不准的标 "待考证"。

Step 2: 盘点知识点与职能分类

• 列出该主题的主流知识点

• 每个先写好 "一句大白话解释 + 一个日常类比"

• 打上职能标签：地基 (守)/ 机制 (转)/ 思想 (想)/ 应用 (打)/ 结论 (进)

• 根据受众参数调整类比方向（--age 5 用玩具类比，--job manager 用商业类比）

Step 3: 选择阵型（决策树）

按以下决策树选择阵型：

text

知识点数量？

├─ ≤ 5 个 → 精简阵（主教练 + 门将 + 能放的位置，不硬凑）

├─ 6-11 个 → 一套主力阵型

├─ 12-20 个 → 主力 + 替补席

└─ > 20 个 → 主力 + B 队

知识结构形态？

├─ 基础/机制/应用三层均衡 → 4-3-3

├─ 有一个非常清晰的主结论 → 4-2-3-1（单箭头+三前腰）

├─ 主结论+两个衍生结论 → 4-3-2-1（圣诞树）

├─ 理论 vs 实践两大板块 → 4-4-2

├─ 一个关键机制托底 → 4-1-4-1（单后腰）

├─ 机制/方法特别多 → 4-5-1 或 3-5-2

└─ 应用/案例非常多 → 3-4-3

阵型选择权衡：

• 4-3-3 最通用，但对 "单一主结论" 的主题表达力弱

• 4-2-3-1 适合 "目标导向" 主题，但中场防守（基础）可能薄弱

• 3-5-2 中场最厚，但后卫（基础）只有 3 人，不适合基础概念多的主题

Step 4: 排位置

• 按 references/positions.md 的角色映射，把知识点放进对应位置：

  • 主教练 = 一句话核心思想

  • 门将 = 最底层基础

  • CB = 核心基础

  • LB/RB = 背景前置

  • CDM = 机制

  • CM = 方法 / 流程

  • AMD (CAM) = 核心思想 / 理论

  • LW/RW = 应用 / 案例

  • CF = 核心结论

  • SS = 衍生结论

  • 替补 = 进阶 / 边角

• 人不够 11 个就留空位（= 可继续深挖的位置）

Step 5: 写球员卡（ELI5 风格）

• 每个首发球员按下方【球员卡模板】用 ELI5 写法输出

• 替补 / B 队可更简

• 根据受众参数调整语言难度（--age 5 每句≤10 字，--age 25+ 可用术语）

• 质量标准： 零背景读者能看懂、有日常类比、无未解释的术语

Step 6: 画战术板

• 写出学习路径（球路，如 GK→CB→CDM→AMD→CF）。flow 只写阵型中存在的位置代码；同名多槽位置（如两个 CB）默认连接第一个槽（详见 references/json-schema.md 渲染契约）

• 关键连线（谁和谁强相关）

• "三种输球方式"（最容易误解 / 出错的点）

Step 7: 渲染阵型图（fail loud，绝不忽略警告）

1. 把阵容写成 JSON（字段与渲染契约见 references/json-schema.md，渲染前必读）。
2. 运行渲染脚本（按本机可用命令，回退链 python3 → python → py -3）： python3 scripts/formation_diagram.py team.json output.svg
3. 必须检查 stderr：脚本对"内容可能丢失"的情况（同名位置超额、位置不在阵型、flow 含非法代码）只告警不报错（退出码仍为 0），多出的球员会转入替补席。逐条核对警告是否符合预期；不符合就改 JSON（换阵型 / 把多余球员挪进 bench / 修正 flow），不得带着意外警告交付。
4. 交付前用 --strict 再跑一次：python3 scripts/formation_diagram.py team.json output.svg --strict，退出码必须为 0（存在任何警告时退出码为 3）。
5. 校验输出 SVG 存在、非空，且所有球员（含替补）名字完整可见、无截断。
6. 退出码 2（文件缺失 / JSON 损坏 / 阵型不支持）时按中文报错修正输入后重跑；禁止用 ASCII 阵型图等降级形态替代 SVG 交付。

Step 8: 交付与质量自查

• 按【输出模板】组织正文

• 阵型图用 present_files 交付

• 完成 10 项质量自查清单

异常处理

情况	处理方式
知识点 < 3 个	提示用户主题太窄，建议扩展；只排 "主教练 + 门将 + 1 后卫"
知识点 > 50 个	自动拆分为多个子主题，每个子主题单独排阵型
阵型图生成失败（退出码 2）	读取 stderr 的中文错误（坏 JSON / 阵型不支持 / 文件缺失），修正输入后重跑；环境问题排查 Python 3.8+。不得用 ASCII 阵型图降级交付，修复前停止交付
退出码 0 但 stderr 有 ⚠️ 告警	逐条核对：超额球员转替补席、非法 flow 代码被跳过。意外告警必须改 JSON 重跑；--strict 下有告警即退出码 3
找不到主教练	如实说明 "本主题没有单一核心思想"，让门将承担统领角色
用户不满意阵型	提供 2-3 个备选阵型供选择，说明各阵型的表达差异

输入契约

用户输入格式：[触发词] [主题] [可选参数]

参数	类型	必填	说明
触发词	string	是	kp11/kpt/kpitch/knowpitch
主题	string	是	要学习的知识领域 / 概念
深度	enum	否	quick/standard/deep，默认由触发词决定
阵型	string	否	强制指定阵型（4-3-3/4-2-3-1 等）
语言	string	否	输出语言，默认中文
--age	int	否	受众年龄（5/10/15/18/25+），调整语言难度
--job	string	否	受众职业（manager/developer/student），调整类比方向
--grade	string	否	受众年级（5th/college/grad），调整专业深度

受众适配规则：

• --age 5：极简单词，玩具 / 动画类比，每句 ≤10 字

• --age 10：简单词汇，学校 / 游戏类比，每句 ≤15 字

• --age 15：日常词汇，生活 / 社交类比，正常句式

• --age 25+：专业词汇，职场 / 技术类比，可包含术语

• --job manager：商业框架，ROI / 风险 / 决策导向，避免代码

• --job developer：技术类比，代码 / 架构 / 性能导向

• --job student：学习类比，考试 / 笔记 / 课程导向

输入示例：

• kp11 讲一下机器学习（默认模式，4-3-3）

• kpt 什么是通货膨胀（快速模式，精简）

• kpitch 深入讲解 React Hooks（完整模式，B 队）

• kp11 神经网络 --阵型 4-2-3-1（指定阵型）

• kp11 数据库索引 --age 5（5 岁小孩能懂）

• kp11 代码库结构 --job manager（给经理解释，商务化）

• kp11 Git 合并冲突 --grade 5th（5 年级学生能懂）

输出契约

输出结构

text

\# 【主题】阵型学习卡（阵型：XXX）

├── 主教练的话（1 段 ELI5 总览 + 一句话核心思想）

├── 阵型图（SVG）

├── 首发阵容

│   ├── 门将 GK（1 人）

│   ├── 后卫（2-4 人）

│   ├── 中场（3-5 人）

│   └── 前锋（1-3 人）

├── 替补席（0-9 人）

├── 教练战术板

│   ├── 为什么用这个阵型

│   ├── 球路（学习路径）

│   ├── 关键连线

│   └── 三种输球方式

└── B 队（可选，>20 知识点时）

阵型图 JSON 结构

完整字段、位置代码与渲染行为契约（同名位置超额转替补、flow 非法代码告警、长名不截断、退出码 0/2/3）见 references/json-schema.md，Step 7 渲染前必读。

边界值输出

• 空主题： 提示 "请提供要学习的主题"

• 非知识类主题： 提示 "本技能适用于知识类主题，建议使用其他方式"

• 知识点 < 3： 精简阵型，明确标注 "主题较窄，建议扩展"

输出模板

按此结构组织最终回答（阵型图作为配图放在最前面）：

text

\# 【主题】阵型学习卡（阵型：XXX）

\## 主教练的话

\[一段 ELI5 大白话总览 + 主教练=一句话核心思想]

\## 阵型图

\[SVG]

\## 首发阵容

\### 门将 GK

\- 【知识点名】一句话大白话

\### 后卫（CB / LB / RB）

\- ...

\### 中场（CDM / CM / AMD）

\- ...

\### 前锋（CF / SS / LW / RW）

\- ...

\## 替补席

\- ...

\## 教练战术板

\- 为什么用这个阵型：一句话

\- 球路（学习路径）：GK → CB → CDM → AMD → CF ...

\- 关键连线：A 和 B 的关系一句话

\- 三种输球方式（最容易错/误解的点）：3 条

\## B 队（如果适用）

\[B 队阵型、B 队教练=次级核心思想、球员卡精简版]

球员卡模板（ELI5）

每个首发球员卡统一 4 行（默认 1–3 句；用户要求 "深入" 时可扩到 100–300 字）：

text

【位置代码｜知识点名】

\- 是什么：一句大白话（像对 5 岁小孩解释）

\- 像什么：一个日常类比（玩具/厨房/上学/手机……）

\- 传给谁：它和哪些队友联动（依赖/关系）

\- 为什么在这：一句话说明它为什么待在这个位置

NEVER 清单（不要做这些）

1. NEVER 硬凑 11 人 — 知识点不够时留空位，不要把边角料硬塞进首发。

• WHY：凑数的球员会稀释核心知识点，让阵型图失去重点。

• 错误示例：把 "历史背景" 这种边角料放进 CB 核心位置。

1. NEVER 按重要性排序位置 — 位置由 "职能" 决定，不是由 "重要性" 决定。

• WHY：重要的知识点可能是 "应用"（LW/RW），不是 "基础"（CB）。

• 错误示例：把最重要的结论放 GK（门将应该是最底层基础）。

1. NEVER 跳过阵型图生成 — 即使时间紧，也要生成 SVG。

• WHY：阵型图是本技能的核心差异化，纯文本输出和 ELI5 没有区别。

1. NEVER 用专业术语解释专业术语 — 球员卡必须用大白话。

• WHY：违反 ELI5 内核，零背景读者看不懂。

• 错误示例："梯度下降是一种一阶迭代优化算法"（应该说 "一步步往山下走，找到最低点"）。

1. NEVER 编造知识点 — 不确定的标 "待考证"，不要瞎编。

• WHY：错误知识比没有知识更有害。

1. NEVER 把 B 队当主力 — B 队是扩展，不是第二套核心。

• WHY：B 队应该是 "想再多学一点" 的内容，不能和主力抢重点。

1. NEVER 忽略 "三种输球方式" — 战术板必须包含常见误解 / 错误。

• WHY：知道 "什么是错的" 和知道 "什么是对的" 同样重要。

1. NEVER 在 description 里写 "I can" / "You can" — 用第三人称。

• WHY：第一人称会破坏 Skill 的发现机制。

完整示例

三个端到端完整范例（机器学习 4-2-3-1+B队 / 通货膨胀 kpt 精简 / 数据库索引 --age 5）见 references/examples.md，写球员卡、战术板、B 队和受众适配时对照。

质量要求（交付前自查）

• 主教练能一句话统领全队（找不到就如实说明，不硬编）

• 每个首发球员都满足 ELI5：零背景可懂、有类比、无未解释的术语

• 位置分配符合 positions.md 的职能逻辑，不按重要性硬排

• 知识点数量 > 20 时启用了 B 队；≤ 20 时没有强行凑满 11 人

• 知识点来自用户输入或已核实的来源，不编造；不确定的标 "待考证"

• 阵型图已生成、已交付，正文结构与输出模板一致

• 渲染脚本 stderr 无意外警告，--strict 退出码为 0；所有球员（含替补）名字完整无截断

• 用户要求深入时，关键球员卡有足够细节而不是只有一句话

• 战术板包含 "三种输球方式"（常见误解 / 错误）

• 没有违反 NEVER 清单中的任何一条

• 受众参数（--age/--job/--grade）已正确应用到语言难度和类比方向