project-understanding

项目理解

概述

通过 Tree-sitter 索引和 PUI 命令实现自动化代码库分析。核心原则：只需索引一次，然后使用聚焦的工具包（repomap/find/zoom/impact），而不是手动 grep。

适用场景

• 开始接触新的代码库： 快速了解结构和入口点
• 规划重构或热修复： 查找调用方并评估影响范围
• 控制上下文预算： 将代码库摘要控制在大模型 token 限制内
• 时间紧迫： 降低遗漏间接依赖的风险
• 验证： 确保变更不会违反架构边界

不适用场景

• 极小型代码库： 手动阅读比索引更快
• 不受支持的语言： 避免依赖符号图（参见 skills/project-understanding/references/LANG_SUPPORT.md）

语言支持（请尽早阅读）

• 完整的符号／调用图支持： Python、JavaScript、TypeScript、Go、Rust
• C/C++： 主要会得到文件级结果；zoom/graph 可能显示“Symbol not found”
• 参考： skills/project-understanding/references/LANG_SUPPORT.md

命令使用须知（无例外）

• 代码库选择由工作目录决定。 没有 --repo 标志。
• 始终在目标代码库中调用 "$PUI"。 不要在目标代码库中运行 ./scripts/pui.sh。
• zoom 的目标是位置参数。 没有 --target 或 --file 标志。
• zoom 不接受文件路径。 请使用符号 id／名称或 file:line。

核心工作流

1. 设置一次工具路径： PUI="/path/to/skills/project-understanding/scripts/pui.sh"（Windows 上使用 pui.ps1）。不要在目标代码库中运行 ./scripts/pui.sh。
2. 在代码库根目录中运行（不使用 --repo 标志）：
   • "$PUI" index（大幅变更后运行 "$PUI" index build）
   • "$PUI" repomap --depth 2 --max-tokens auto
3. 定位符号：
   • 运行 "$PUI" find "SymbolName" 获取符号 id（避免猜测通用名称）
   • 运行 "$PUI" zoom <symbol-id|name|file:line>（仅文件路径会导致失败）
   • 运行 "$PUI" graph --symbol <symbol-id|name> --depth 2
4. 评估影响：
   • "$PUI" impact --files path/to/file --include-tests
   • "$PUI" impact --git-diff HEAD~1..HEAD

示例（精简增强版）

在 project-understanding-skill 代码库根目录中：

PUI="$(pwd)/skills/project-understanding/scripts/pui.sh"
cd ./codebases/lean-boost

"$PUI" index
"$PUI" repomap --depth 3 --max-tokens 1200
"$PUI" find "services_manager"
"$PUI" graph --symbol 70 --depth 1 --format mermaid
"$PUI" impact --files src/uninstall/leftovers_scanner.cpp --max-tokens 800

安装

该技能开箱即用。首次运行时，它会在 ~/.local/share/pui/venv 中引导创建一个共享虚拟环境（或使用本地回退方案）。代码库索引存储在项目根目录下的 .pui/ 中。

快速参考

命令	用途	关键标志
index	构建／更新索引	build、--force
repomap	目录和顶层文件	--depth、--max-tokens
find	符号搜索	--limit、--format
zoom	符号详情	--max-tokens
graph	调用／依赖图	--symbol、--depth
impact	影响范围分析	--files、--git-diff、--include-tests
architecture	高层架构摘要	--format
depgraph	模块依赖图	--scope、--format

使用说明：

• zoom 的目标是位置参数；没有 --target 标志。
• zoom 不接受文件路径；请使用符号 id／名称或 file:line。
• 如果不确定符号 id，请先使用 find。

影响分析置信度

分数	含义	操作
0.9+	确定匹配	信任结果并继续
0.7-0.9	很可能（导入）	手动核实
<0.7	启发式／动态分析	仅作参考提示

置信度信号仅对支持符号提取的语言有意义。

常见错误

• 脚本路径错误： 从仓库根目录运行 ./scripts/pui.sh 会失败。请使用绝对路径或设置 PUI=...。
• 跳过索引： 命令会失败或显示过时数据。请定期运行 index；完整重建请使用 index build。
• 缩放目标错误： zoom 需要符号 ID/名称或 file:line。没有 --target 标志。
• 猜测符号： 在运行 zoom/graph 前先运行 find，尤其是在大型仓库中。
• 臆造标志： 没有 --repo 标志；请通过 cd 进入仓库来设置仓库。
• 假设存在 C/C++ 符号图： 请先查看 skills/project-understanding/references/LANG_SUPPORT.md。
• 忽略预算： 大型 repo-map 可能会消耗 20k+ 个 token。请使用 --depth 或 --max-tokens。

合理化借口表

借口	实际情况
“我直接 grep 导入项就行”	Grep 会漏掉间接依赖。索引后使用 impact 更准确。
“从文件夹名称就能看出结构”	文件夹名称不是依赖图。请使用 repomap 和 graph。
“索引耗时太久”	索引是增量式的；手动追踪更慢、风险也更高。
“我没用过这个工具，所以跳过吧”	首次运行的成本仅需承担一次；之后 find + impact 可以节省时间。
“我直接读大型文件就行”	阅读 600+ 行的文件会消耗 token 并分散注意力。zoom 可提取核心逻辑。
“工具应该就在这里的 ./scripts 里”	脚本位于技能目录中。请先设置 PUI。
“我可以缩放文件路径”	zoom 需要符号 ID/名称或 file:line。仅提供文件路径会失败。

危险信号——停止并建立索引

• 你正打算仅凭手动 grep 发布影响摘要。
• 你正在根据文件夹名称猜测架构。
• 你看到“Symbol not found”，却不检查语言支持或运行 find 就继续操作。
• 你正打算在目标仓库中运行 ./scripts/pui.sh。
• 你正打算向 zoom 传入文件路径。
• 你正在手动追踪跨越 2 个以上文件的导入项。
• 大型代码块正让你触及上下文窗口限制。

以上情况都意味着：运行 index，使用 repomap/find/impact，或先验证语言支持。