| name | kb-onboard |
|---|---|
| description | 一个利用现有知识库的认知地图自动生成新人引导路径和理解测验的技能。 |
将知识库中沉淀的"死文档"转化为有引导性的学习路径。为新加入项目的开发者自动生成一份阅读计划、核心概念速览和理解检验测验，输出为一份可交付的 ONBOARDING.md。
- 项目中存在由
kb-build技能构建的知识库（含GLOSSARY.md）。 - 项目中存在
KB_PLAN.md蓝图（用于理解模块划分）。
- 快速扫描所有 KB 文件的 Frontmatter
fingerprint，与当前 Git 记录对比，统计过期率。 - 如果过期率 ≥ 30%：在后续生成的
ONBOARDING.md头部插入醒目警告：⚠️ 警告：当前知识库有超过 30% 的文档已过期。建议先运行 kb-update 刷新知识库后再生成入门指南，以避免新人接收到过时信息。 - 无论是否过期，继续执行后续步骤（但确保警告被保留在最终输出中）。
- 扫描所有 KB 文件中的 SSOT 内部链接（
[text](path)模式），构建一张有向引用图。 - 计算每个 KB 文档的被引用次数 (In-degree)——被引用越多的文档，通常代表越底层、越基础的概念。
- 按拓扑排序生成推荐阅读顺序：先读"被引最多"的基础模块，再读"引用别人最多"的上层业务模块。
- 读取
GLOSSARY.md，提取所有术语及其同义词。 - 读取
KB_PLAN.md，理解模块划分。 - 为每个推荐阅读的 KB 文档，生成一段 2-3 句话的"你需要知道什么 (What You Need to Know)"摘要，聚焦于：
- 该模块在整个系统中的角色（它负责什么）。
- 它与其他模块的关键交互点（它和谁打交道）。
- 新人常见的误区或陷阱（新人容易踩的坑）。
为每个核心模块设计 1-2 个理解检验问题，复用 kb-build 中 3D 对抗验证的问题设计思路：
- 架构理解："如果需要为系统增加 XXX 功能，你会修改哪些模块？它们之间的调用顺序是怎样的？"
- 设计意图："为什么 XXX 组件选择了 A 方案而不是 B 方案？"
- 边界认知："当 XXX 输入不合法时，系统会如何处理？错误会传播到哪里？"
在每个问题后附上参考答案和对应的 KB 文档引用链接。
在知识库目录中输出 ONBOARDING.md，格式如下：
# 🎓 新人入门指南 (Onboarding Guide)
## 📖 推荐阅读顺序 (Reading Path)
按照从基础到应用的顺序排列，建议按此顺序阅读。
| 序号 | KB 文档 | 核心角色 | 预计阅读时间 |
|---|---|---|---|
| 1 | [database.md](./core/database.md) | 数据持久层，所有服务的基础 | ~5 min |
| 2 | [auth.md](./api/auth.md) | 认证与授权，中间件链的起点 | ~8 min |
| ... | ... | ... | ... |
## 💡 核心概念速览 (Key Concepts at a Glance)
### 模块 1: <模块名>
<2-3 句摘要>
- **常见误区**: <新人易踩的坑>
### 模块 2: <模块名>
...
## ✅ 理解检验 (Comprehension Check)
完成阅读后，请尝试回答以下问题来验证你的理解：
### Q1: <架构理解问题>
<details>
<summary>点击查看参考答案</summary>
<参考答案>
📚 参考: [xxx.md](./xxx.md)
</details>
### Q2: <设计意图问题>
...如果用户指定了新人将要负责的具体模块或领域：
- 在阅读路径中标注重点：对相关模块标记 ⭐ 并优先排列。
- 在测验中增加针对该模块的更深层问题（增加到 3 个）。
- 在文档末尾添加"深入阅读 (Deep Dive)"区块，列出该模块的结构和子文件。