understand-onboard

/understand-onboard

根据项目知识图谱生成一份全面的入门指南。

图谱结构参考

知识图谱 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[]}

高效阅读方法

1. 在阅读整个文件之前，先使用 Grep 在 JSON 中搜索相关条目
2. 仅阅读所需部分，不要将整个图谱都载入上下文
3. 节点名称和摘要是最有助于理解的字段
4. 边展示了组件之间的连接方式；沿着 imports 和 calls 追踪依赖链

说明

1. 解析数据目录 $UA_DIR。 运行 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua)——如果 .understand-anything/ 已存在，则使用这个旧目录；否则使用新的 .ua/。检查 $UA_DIR/knowledge-graph.json 是否存在。如果不存在，请告知用户先运行 /understand。

2. 在使用源自图谱的上下文前，检查图谱是否为最新：

   • 从图谱元数据中读取 project.gitCommitHash，记为 GRAPH_COMMIT_RAW。在将其用于任何 Git diff 前，先将其解析为一个提交，然后与 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 -- .
     

   • 必须使用 -- . 路径规范：如果提交只修改了单体仓库中的同级项目，不应据此判定图谱已过时。即使哈希不匹配，只要项目 diff 为空，也不代表图谱已过时。
   • 忽略所有命令输出中所选的数据目录（.ua/ 或旧版 .understand-anything/），因为其中是生成的图谱文件，而非项目源代码变更。
   • 如果已提交 diff 或任何工作树命令报告了项目文件，请在生成指南前警告用户，引导内容可能遗漏这些变更。建议：运行 /understand 刷新图谱。
   • 仅当 GRAPH_COMMIT_RAW 成功解析时才运行提交 diff。如果图谱提交或 Git 元数据缺失、无效或不可用，请简要发出尽力而为的警告，然后继续，不要因此阻塞。

3. 读取项目元数据——使用 Grep 或 Read，并限制行数，以提取 "project" 部分（名称、描述、语言、框架）。

4. 读取分层信息——使用 Grep 获取完整的 "layers" 数组。这些分层定义了架构，并将用于组织指南结构。

5. 读取导览——使用 Grep 获取 "tour" 中的引导式讲解步骤。这些步骤提供了推荐的学习路径。

6. 仅读取文件级结构节点——使用 Grep 在知识图谱中查找文件级类型的节点（file、config、document、service、pipeline、table、schema、resource、endpoint）。跳过函数级和类级节点，以保持指南的整体性。提取每个节点的 name、filePath、summary 和 complexity。

7. 识别复杂度热点——从文件级节点中找出 complexity 值最高的节点。这些是新开发者需要谨慎处理的部分。

8. 生成入门指南，包含以下部分：

   • 项目概览：名称、语言、框架、描述（来自项目元数据）
   • 架构分层：每一层的名称、描述和关键文件（来自分层信息和文件节点）
   • 关键概念：重要模式和设计决策（来自节点摘要和标签）
   • 引导式导览：逐步讲解（来自 "tour" 部分）
   • 文件索引：各关键文件的用途（来自文件级节点，按层组织）
   • 复杂度热点：需要谨慎处理的部分（根据复杂度值确定）

9. 使用清晰的 Markdown 格式

10. 提议将指南保存到项目中的 docs/UA_ONBOARDING.md

11. 建议用户将其提交到代码仓库，供团队使用