understand-onboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/understand-onboard

Generate a comprehensive onboarding guide from the project's knowledge graph.

从项目的知识图谱生成全面的入职指南。

Graph Structure Reference

知识图谱结构参考

The knowledge graph JSON has this structure:

```
project
```
— {name, description, languages, frameworks, analyzedAt, gitCommitHash}
```
nodes[]
```
— each has {id, type, name, filePath, summary, tags[], complexity, languageNotes?}
- Node types: file, function, class, module, concept
- IDs:
```
file:path
```
  ,
```
func:path:name
```
  ,
```
class:path:name
```
```
edges[]
```
— each has {source, target, type, direction, weight}
- Key types: imports, contains, calls, depends_on
```
layers[]
```
— each has {id, name, description, nodeIds[]}
```
tour[]
```
— each has {order, title, description, nodeIds[]}

知识图谱JSON的结构如下：

```
project
```
— {名称, 描述, 编程语言, 框架, 分析时间, Git提交哈希值}
```
nodes[]
```
— 每个节点包含 {id, 类型, 名称, 文件路径, 摘要, 标签[], 复杂度, 语言说明?}
- 节点类型：file（文件）、function（函数）、class（类）、module（模块）、concept（概念）
- ID格式：
```
file:path
```
  ,
```
func:path:name
```
  ,
```
class:path:name
```
```
edges[]
```
— 每条边包含 {源节点, 目标节点, 类型, 方向, 权重}
- 主要类型：imports（导入）、contains（包含）、calls（调用）、depends_on（依赖）
```
layers[]
```
— 每个层级包含 {id, 名称, 描述, 节点ID列表[]}
```
tour[]
```
— 每个引导步骤包含 {顺序, 标题, 描述, 节点ID列表[]}

How to Read Efficiently

高效阅读方法

Use Grep to search within the JSON for relevant entries BEFORE reading the full file
Only read sections you need — don't dump the entire graph into context
Node names and summaries are the most useful fields for understanding
Edges tell you how components connect — follow imports and calls for dependency chains

在读取完整文件前，使用Grep在JSON中搜索相关条目
只读取你需要的部分——不要将整个图谱都加载到上下文里
节点名称和摘要是理解内容最有用的字段
边信息展示组件之间的关联——通过imports和calls追踪依赖链

Instructions

操作步骤

Check that

.understand-anything/knowledge-graph.json

exists. If not, tell the user to run

/understand

first.

Read project metadata — use Grep or Read with a line limit to extract the
```
"project"
```
section (name, description, languages, frameworks).
Read layers — Grep for
```
"layers"
```
to get the full layers array. These define the architecture and will structure the guide.
Read the tour — Grep for
```
"tour"
```
to get the guided walkthrough steps. These provide the recommended learning path.
Read file-level nodes only — use Grep to find nodes with
```
"type": "file"
```
in the knowledge graph. Skip function-level and class-level nodes to keep the guide high-level. Extract each file node's
```
name
```
,
```
filePath
```
,
```
summary
```
, and
```
complexity
```
.
Identify complexity hotspots — from the file-level nodes, find those with the highest
```
complexity
```
values. These are areas new developers should approach carefully.
Generate the onboarding guide with these sections:
- Project Overview: name, languages, frameworks, description (from project metadata)
- Architecture Layers: each layer's name, description, and key files (from layers + file nodes)
- Key Concepts: important patterns and design decisions (from node summaries and tags)
- Guided Tour: step-by-step walkthrough (from the tour section)
- File Map: what each key file does (from file-level nodes, organized by layer)
- Complexity Hotspots: areas to approach carefully (from complexity values)
Format as clean markdown
Offer to save the guide to
```
docs/ONBOARDING.md
```
in the project
Suggest the user commit it to the repo for the team

检查
```
.understand-anything/knowledge-graph.json
```
文件是否存在。如果不存在，告知用户先运行
```
/understand
```
命令。
读取项目元数据——使用Grep或带行数限制的读取方式提取
```
"project"
```
部分（名称、描述、编程语言、框架）。
读取层级信息——使用Grep搜索
```
"layers"
```
获取完整的层级数组。这些信息定义了项目架构，将作为指南的结构基础。
读取引导流程——使用Grep搜索
```
"tour"
```
获取引导式学习步骤。这些步骤提供了推荐的学习路径。
仅读取文件级节点——使用Grep在知识图谱中查找
```
"type": "file"
```
的节点。跳过函数级和类级节点，保持指南的高层视角。提取每个文件节点的
```
name
```
、
```
filePath
```
、
```
summary
```
和
```
complexity
```
字段。
识别复杂度热点——从文件级节点中找出
```
complexity
```
值最高的节点。这些是新开发者需要谨慎处理的区域。
生成入职指南，包含以下部分：
- 项目概述：名称、编程语言、框架、描述（来自项目元数据）
- 架构层级：每个层级的名称、描述和关键文件（来自层级信息和文件节点）
- 核心概念：重要模式和设计决策（来自节点摘要和标签）
- 引导学习：分步学习流程（来自引导流程部分）
- 文件映射：每个关键文件的作用（来自文件级节点，按层级组织）
- 复杂度热点：需要谨慎处理的区域（来自复杂度值）
整理为简洁的Markdown格式
可将指南保存到项目中的
```
docs/ONBOARDING.md
```
文件
建议用户将其提交到代码仓库，供团队使用