用途
understand-onboard 用于为新加入项目的团队成员生成一份全面的入职指南。它从项目已有的知识图谱中提取信息,帮助新人快速理解项目结构、架构分层、关键概念和推荐学习路径。
主要能力
- 基于知识图谱生成结构化入职指南,而非从零分析代码。
- 读取项目元数据(名称、描述、语言、框架)。
- 读取架构分层(layers),用于组织指南结构。
- 读取导览步骤(tour),提供推荐的学习路径。
- 读取文件级结构节点(file、config、document、service、pipeline、table、schema、resource、endpoint),跳过函数级和类级节点以保持高层视角。
- 识别复杂度热点,提示新开发者需谨慎对待的区域。
- 生成包含项目概览、架构分层、关键概念、引导式导览、文件地图、复杂度热点等章节的 Markdown 指南。
- 可保存指南到 docs/UA_ONBOARDING.md 并建议提交到仓库。
使用方式
- 解析数据目录 $UA_DIR:运行 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua),即优先使用已存在的旧目录 .understand-anything/,否则使用新目录 .ua/。
- 检查 $UA_DIR/knowledge-graph.json 是否存在。若不存在,提示用户先运行 /understand。
- 检查图谱新鲜度:读取 project.gitCommitHash 作为 GRAPH_COMMIT_RAW,解析为提交后与 git rev-parse HEAD 比较,并检查项目范围内的已提交、暂存、工作区及未跟踪文件变更。命令示例:
GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
git rev-parse HEAD
git diff --name-only "$GRAPH_COMMIT" HEAD -- .
git diff --cached --name-only -- .
git diff --name-only -- .
git ls-files --others --exclude-standard -- .
其中 -- . 路径规范是必需的,仅触及同级 monorepo 项目的提交不应使图谱过期。仅哈希不匹配但项目差异为空时不算过期。需在每条命令输出中忽略所选数据目录(.ua/ 或旧 .understand-anything/),因为其中包含生成的图谱产物而非项目源码漂移。若已提交差异或任何工作区命令报告了项目文件,应在生成指南前警告入职内容可能遗漏这些变更,并建议运行 /understand 刷新图谱。仅当 GRAPH_COMMIT_RAW 成功解析时才运行提交差异;若图谱提交或 Git 元数据缺失、无效或不可用,给出简短的最佳努力警告并继续,而非阻塞。 4. 读取项目元数据:使用 Grep 或带行数限制的 Read 提取 project 部分(名称、描述、语言、框架)。 5. 读取 layers:Grep "layers" 获取完整 layers 数组,用于构建指南结构。 6. 读取 tour:Grep "tour" 获取引导式导览步骤,提供推荐学习路径。 7. 仅读取文件级结构节点:Grep 查找文件级类型节点(file、config、document、service、pipeline、table、schema、resource、endpoint),跳过函数级和类级节点,提取名称、filePath、summary、complexity。 8. 识别复杂度热点:从文件级节点中找出复杂度最高的区域。 9. 生成入职指南,包含以下章节:项目概览(名称、语言、框架、描述)、架构分层(每层名称、描述、关键文件)、关键概念(重要模式与设计决策)、引导式导览(分步走查)、文件地图(按层组织的关键文件说明)、复杂度热点(需谨慎对待的区域)。格式为清晰的 Markdown。 10. 提供将指南保存到项目 docs/UA_ONBOARDING.md 的选项,并建议用户提交到仓库供团队使用。
知识图谱结构参考
知识图谱 JSON 结构如下:
- project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
- nodes[] — 每个节点包含 {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
- 代码节点类型:file、function、class、module、concept
- 非代码节点类型:config、document、service、table、endpoint、pipeline、schema、resource
- 领域/知识节点类型:domain、flow、step、article、entity、topic、claim、source
- ID 使用节点类型作为前缀,例如 file:path、function:path:name、config:path、article:path
- edges[] — 每条边包含 {source, target, type, direction, weight}
- 关键类型:imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites
- layers[] — 每层包含 {id, name, description, nodeIds[]}
- tour[] — 每步包含 {order, title, description, nodeIds[]}
高效读取建议
- 在读取完整文件之前,使用 Grep 在 JSON 中搜索相关条目。
- 只读取需要的部分,不要将整个图谱倒入上下文。
- 节点名称和摘要是最有用的理解字段。
- 边说明组件如何连接,可沿 imports 和 calls 追踪依赖链。
适用场景
- 新团队成员加入项目,需要快速上手。
- 项目已有知识图谱,希望自动生成结构化入职文档。
- 需要向新人展示架构分层、关键概念和推荐学习路径。
限制
- 依赖已有的知识图谱文件(knowledge-graph.json),若不存在需先运行 /understand。
- 若图谱提交与当前 HEAD 存在项目文件差异,生成的指南可能遗漏这些变更,需刷新图谱。
- 若图谱提交或 Git 元数据缺失、无效或不可用,只能给出最佳努力警告并继续。
- 仅读取文件级节点,不深入函数级和类级细节。