project-understanding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Understanding

项目理解

Overview

概述

Automated repository intelligence via Tree-sitter indexing and PUI commands. Core principle: index once, then use focused packs (repomap/find/zoom/impact) instead of manual grep.

通过Tree-sitter索引和PUI命令实现自动化仓库智能分析。核心原则：只需索引一次，之后使用聚焦命令包（repomap/find/zoom/impact）替代手动grep。

When to Use

适用场景

Entering new codebase: Rapidly map structure and entry points
Planning refactors or hotfixes: Find callers and assess blast radius
Budgeting context: Fit repository summaries into LLM token limits
Time pressure: Reduce risk of missing indirect dependencies
Verification: Ensure changes don't violate architectural boundaries

When NOT to Use

Tiny repos: Manual reading is faster than indexing
Unsupported languages: Avoid relying on symbol graphs (see
```
skills/project-understanding/references/LANG_SUPPORT.md
```
)

接入新代码库： 快速映射结构和入口点
规划重构或热修复： 查找调用方并评估影响范围
控制上下文成本： 将仓库摘要压缩至LLM的token限制内
时间紧迫时： 降低遗漏间接依赖的风险
验证变更： 确保修改不会违反架构边界

不适用场景

小型仓库： 手动阅读比索引更快

不支持的语言： 避免依赖符号图（详见

skills/project-understanding/references/LANG_SUPPORT.md

）

Language Support (Read This Early)

语言支持（请提前阅读）

Full symbol/call graph support: Python, JavaScript, TypeScript, Go, Rust
C/C++: Expect mostly file-level results;
```
zoom
```
/
```
graph
```
may show "Symbol not found"

Reference:

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

Command Guardrails (No Exceptions)

命令约束（无例外）

Repo selection is the working directory. There is no
```
--repo
```
flag.
Always call
"$PUI"
from the target repo. Do not run
```
./scripts/pui.sh
```
inside the target repo.
zoom
target is positional. There is no
```
--target
```
or
```
--file
```
flag.
zoom
does not accept file paths. Use a symbol id/name or
```
file:line
```
.

仓库选择基于工作目录，没有
```
--repo
```
参数。
始终从目标仓库中调用
"$PUI"
，不要在目标仓库内运行
```
./scripts/pui.sh
```
。
zoom
的目标为位置参数，没有
```
--target
```
或
```
--file
```
参数。
zoom
不接受文件路径，请使用符号ID/名称或
```
file:line
```
格式。

Core Workflow

核心工作流

Set tool path once:

PUI="/path/to/skills/project-understanding/scripts/pui.sh"

(use

pui.ps1

on Windows). Do NOT run

./scripts/pui.sh

from the target repo.

From the repo root (no
--repo
flag):

```
"$PUI" index
```
(or
```
"$PUI" index build
```
after big changes)

"$PUI" repomap --depth 2 --max-tokens auto

Locate symbols:

```
"$PUI" find "SymbolName"
```
to get a symbol id (avoid guessing generic names)
```
"$PUI" zoom <symbol-id|name|file:line>
```
(file paths alone will fail)

"$PUI" graph --symbol <symbol-id|name> --depth 2

Assess impact:

"$PUI" impact --files path/to/file --include-tests

```
"$PUI" impact --git-diff HEAD~1..HEAD
```

一次性设置工具路径：
```
PUI="/path/to/skills/project-understanding/scripts/pui.sh"
```
（Windows系统使用
```
pui.ps1
```
）。不要从目标仓库中运行
```
./scripts/pui.sh
```
。
在仓库根目录下执行（无需
--repo
参数）：
- ```
"$PUI" index
```
  （或在重大变更后使用
```
"$PUI" index build
```
  ）
- ```
"$PUI" repomap --depth 2 --max-tokens auto
```
定位符号：
- 使用
```
"$PUI" find "SymbolName"
```
  获取符号ID（避免猜测通用名称）
- 使用
```
"$PUI" zoom <symbol-id|name|file:line>
```
  （单独的文件路径会执行失败）
- 使用
```
"$PUI" graph --symbol <symbol-id|name> --depth 2
```

评估影响范围：

"$PUI" impact --files path/to/file --include-tests

```
"$PUI" impact --git-diff HEAD~1..HEAD
```

Example (Lean Boost)

示例（Lean Boost）

From the

project-understanding-skill

repo root:

bash

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

在

project-understanding-skill

仓库根目录下执行：

bash

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

Installation

安装

The skill works out of the box. On first run it bootstraps a shared virtual environment in

~/.local/share/pui/venv

(or a local fallback). Repository indexes are stored in

.pui/

under the project root.

本工具开箱即用。首次运行时，会在

~/.local/share/pui/venv

中创建共享虚拟环境（或使用本地备用路径）。仓库索引存储在项目根目录下的

.pui/

文件夹中。

Quick Reference

快速参考

Command	Purpose	Key Flag
`index`	Build/update index	`build` , `--force`
`repomap`	Directory + top files	`--depth` , `--max-tokens`
`find`	Symbol search	`--limit` , `--format`
`zoom`	Symbol detail	`--max-tokens`
`graph`	Call/dependency graph	`--symbol` , `--depth`
`impact`	Blast radius analysis	`--files` , `--git-diff` , `--include-tests`
`architecture`	High-level architecture summary	`--format`
`depgraph`	Module dependency graph	`--scope` , `--format`

Usage notes:

```
zoom
```
target is positional; there is no
```
--target
```
flag.
```
zoom
```
does not accept file paths; use a symbol id/name or
```
file:line
```
.
Use
```
find
```
first if you are unsure of symbol ids.

命令	用途	关键参数
`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
```
命令。

Impact Analysis Confidence

影响分析置信度

Score	Meaning	Action
0.9+	Definite match	Trust & proceed
0.7-0.9	Likely (imports)	Verify manually
<0.7	Heuristic/dynamic	Treat as hints

Confidence signals are meaningful only for supported languages with symbol extraction.

分数	含义	操作建议
0.9+	明确匹配	直接信任并执行后续操作
0.7-0.9	大概率匹配（基于导入关系）	手动验证
<0.7	启发式/动态推断结果	仅作为参考提示

置信度评分仅对支持符号提取的语言有效。

Common Mistakes

常见错误

Wrong script path: Running
```
./scripts/pui.sh
```
from the repo root fails. Use an absolute path or
```
PUI=...
```
.
Skipping index: Commands will fail or show stale data. Use
```
index
```
regularly; use
```
index build
```
for full rebuilds.
Wrong zoom target:
```
zoom
```
needs a symbol id/name or
```
file:line
```
. There is no
```
--target
```
flag.
Guessing symbols: Run
```
find
```
before
```
zoom
```
/
```
graph
```
, especially in large repos.
Inventing flags: There is no
```
--repo
```
flag; set the repo by
```
cd
```
into it.

Assuming C/C++ symbol graphs: Check

skills/project-understanding/references/LANG_SUPPORT.md

first.

Ignoring budget: Large repo-maps can burn 20k+ tokens. Use
```
--depth
```
or
```
--max-tokens
```
.

脚本路径错误： 从仓库根目录运行
```
./scripts/pui.sh
```
会失败，请使用绝对路径或设置
```
PUI
```
环境变量。
跳过索引步骤： 命令会执行失败或显示过期数据。请定期使用
```
index
```
，重大变更后使用
```
index build
```
进行完整重建。
错误的zoom目标：
```
zoom
```
需要符号ID/名称或
```
file:line
```
格式，没有
```
--target
```
参数。
猜测符号名称： 在大型仓库中，使用
```
zoom
```
/
```
graph
```
前请先运行
```
find
```
命令。
自定义参数： 没有
```
--repo
```
参数，请通过
```
cd
```
进入目标仓库来指定。

默认C/C++支持符号图： 请先查看

skills/project-understanding/references/LANG_SUPPORT.md

。

忽略token限制： 大型仓库的repomap可能消耗20k+ token，请使用
```
--depth
```
或
```
--max-tokens
```
参数控制。

Rationalization Table

误区澄清表

Excuse	Reality
"I can just grep for imports"	Grep misses indirect dependencies. `impact` is more accurate after indexing.
"Structure is obvious from folder names"	Folder names are not dependency graphs. Use `repomap` and `graph` .
"Indexing takes too long"	Indexing is incremental; manual tracing is slower and riskier.
"I haven't used the tool, so I'll skip it"	First run cost is one-time; `find` + `impact` save time after.
"I'll just read the big files"	Reading 600+ line files burns tokens and focus. `zoom` isolates the essential logic.
"The tool should be in ./scripts here"	The script lives in the skill directory. Set `PUI` first.
"I can zoom a file path"	`zoom` needs a symbol id/name or `file:line` . File paths alone fail.

借口	实际情况
"我可以直接用grep查找导入关系"	Grep会遗漏间接依赖。索引完成后， `impact` 命令的结果更准确。
"从文件夹名称就能看出结构"	文件夹名称不等于依赖关系图，请使用 `repomap` 和 `graph` 命令。
"索引太费时间"	索引是增量式的，手动追踪依赖更慢且风险更高。
"我没用过这个工具，所以跳过它"	首次运行成本是一次性的，之后 `find` + `impact` 命令能节省大量时间。
"我直接读大文件就行"	阅读600+行的文件会消耗大量token和精力， `zoom` 命令可以聚焦核心逻辑。
"工具应该在当前目录的./scripts里"	脚本存放在技能目录中，请先设置 `PUI` 环境变量。
"我可以用文件路径来zoom"	`zoom` 需要符号ID/名称或 `file:line` 格式，单独的文件路径会执行失败。

Red Flags - STOP and Index

危险信号 - 立即停止并执行索引

You are about to publish an impact summary from manual grep alone.
You are guessing architecture based on folder names.
You see "Symbol not found" and keep going without checking language support or
```
find
```
.
You are about to run
```
./scripts/pui.sh
```
inside the target repo.
You are about to pass a file path to
```
zoom
```
.
You are manually following imports through more than 2 files.
You are hitting context window limits with large code blocks.

All of these mean: run
index
, use
repomap
/
find
/
impact
, or verify language support first.

你打算仅通过手动grep就发布影响范围摘要。
你正通过文件夹名称猜测架构。
你看到“Symbol not found”却未检查语言支持或运行
```
find
```
命令就继续操作。
你打算在目标仓库内运行
```
./scripts/pui.sh
```
。
你打算将文件路径传递给
```
zoom
```
命令。
你手动追踪导入关系已超过2个文件。
你因大段代码块而遇到上下文窗口限制。

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