Graphify 技能 Step 1 自举解析POSIX 解释器探测、自动安装与 .graphify_python 持久化机制【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphifygraphify 的技能skill被注入 Claude Code、Cursor、Codex 等数十种 Agent 宿主后第一步不是建图而是先找到那个真正装有 graphify 的 Python 解释器——因为它可能是 uv tool 环境、pipx 环境、venv也可能是系统 Python 或 PEP 668 管理的发行版解释器。本文以仓库中tools/skillgen/fragments/shell/posix.md这一 POSIXbash安装片段为骨架深入讲解其三级探测、自动回退安装、解释器路径持久化与二次进入时的守护逻辑并对照源码渲染管线与 Windows 变体让你彻底理解这条自举链路的来龙去脉读完可直接用于排障与二次开发。这个片段在仓库中的位置与角色在 graphify 仓库中tools/skillgen/fragments/shell/posix.md不是一份独立运行的脚本而是一块被拼装进技能正文的渲染片段fragment。其完整生命周期如下唯一编辑源single source of truthtools/skillgen/gen.py的模块文档明确写着tools/skillgen/fragments/下的片段是人工编辑的唯一事实源而graphify/skill*.md与graphify/skills/platform/references/都是由这些片段生成并提交committed的产物见 gen.py。槽位填充gen.py中的_render_core()会读取核心模板 fragments/core/core.md并把INSTALL槽位替换为本片段的内容install _read_fragment(fshell/{platform.shell}.md)见 gen.py。按宿主声明 Shelltools/skillgen/platforms.toml为每个平台声明shell posix | powershell默认posix。例如claude、codex、kilo、trae、vscode等都使用 POSIX 版本只有windows平台声明shell powershell见 platforms.toml。产物落点渲染结果会写入对应宿主的技能文件例如 Claude Code 的 graphify/skill.md 中 ### Step 1 - Ensure graphify is installed 一节就是本片段渲染后的真实样子。因此阅读本片段时脑中要有这条链路posix.md源头→gen.py渲染 →graphify/skill.md等提交产物生效→graphify/skills/*/注入到各 Agent 宿主运行。解决的核心问题多安装方式下的解释器漂移graphify 的分发包名为graphifyy见 pyproject.toml 中name graphifyy安装后提供graphify命令、import graphify模块。但同一个包可能有多种落点uv tooluv tool install graphifyy解释器藏在~/.local/share/uv/tools/graphifyy/的隔离环境里系统中可能根本没有暴露该 Python 到 PATHpipxpipx install graphifyy环境位于PIPX_HOME管理的 venvs 下venv / conda解释器位于项目或 conda 环境的目录里系统 pip直接装进系统 Python还可能遇到 PEP 668externally-managed-environment拒绝安装的情形。更隐蔽的问题是即便graphify命令在 PATH 上which graphify找得到也不能保证当前默认的python3就能import graphify。如果后续步骤用裸python3执行 Python 代码块会直接ModuleNotFoundError。本片段正是为了消解这种不确定性而设计的一道解释器护栏。片段逐段拆解三级探测 自动安装第一步探测顺序的三个优先级片段开头逐级尝试三种来源只要命中就停止变量PYTHON即最终选定的解释器绝对路径# Detect the correct Python interpreter (handles uv tool, pipx, venv, system installs) PYTHON GRAPHIFY_BIN$(which graphify 2/dev/null) # 1. uv tool installs — most reliable on modern Mac/Linux if [ -z $PYTHON ] command -v uv /dev/null 21; then _UV_PY$(uv tool run --from graphifyy python -c import sys; print(sys.executable) 2/dev/null) if [ -n $_UV_PY ]; then PYTHON$_UV_PY; fi fi # 2. Read shebang from graphify binary (pipx and direct pip installs) if [ -z $PYTHON ] [ -n $GRAPHIFY_BIN ]; then _SHEBANG$(head -1 $GRAPHIFY_BIN | tr -d #!) case $_SHEBANG in *[!a-zA-Z0-9/_.-]*) ;; *) $_SHEBANG -c import graphify 2/dev/null PYTHON$_SHEBANG ;; esac fi # 3. Fall back to python3 if [ -z $PYTHON ]; then PYTHONpython3; fi三个优先级的取舍意图非常清晰第 1 级uv tooluv tool run --from graphifyy python -c import sys; print(sys.executable)会借用 uv 的管理能力直接问出 graphifyy 工具环境里的真实解释器路径。注释标明这是现代 Mac/Linux 上最可靠的一级——只要uv命令存在且能解析出路径就采纳。第 2 级shebang 回读pipx与直接 pip 安装都会在 PATH 上放置一个graphify启动脚本其首行 shebanghead -1去掉#!恰恰指向拥有这个入口点的解释器。这里用case做了一次字符白名单校验只有解释器路径只含[a-zA-Z0-9/_.-]这类安全字符时才继续否则视作不可信来源跳过随后用$_SHEBANG -c import graphify实测导入只有成功才采纳。第 3 级兜底 python3前两级都失败时退化为python3交由后续的导入实测去判断是否真的可用。注意一个工程细节case $_SHEBANG in *[!a-zA-Z0-9/_.-]*)这种写法是反向过滤——模式中的[!…]是否定字符类只要路径里出现白名单之外的字符比如 shebang 里夹带了空格和参数如#!/usr/bin/env -S python3 -I就落入该分支什么都不做避免把带参数/带空格的整行误当成解释器路径执行。第二步探测失败后的自动安装链如果最终的解释器实测import graphify失败说明虽然探测到了 Python但包并未安装进去片段会依据可用工具走两条安装路径并再次探测if ! $PYTHON -c import graphify 2/dev/null; then if command -v uv /dev/null 21; then uv tool install --upgrade graphifyy -q 21 | tail -3 _UV_PY$(uv tool run --from graphifyy python -c import sys; print(sys.executable) 2/dev/null) if [ -n $_UV_PY ]; then PYTHON$_UV_PY; fi else $PYTHON -m pip install graphifyy -q 2/dev/null \ || $PYTHON -m pip install graphifyy -q --break-system-packages 21 | tail -3 fi fi有 uv执行uv tool install --upgrade graphifyy静默升级安装随后立刻用uv tool run重新解析解释器路径无 uv先用$PYTHON -m pip install graphifyy失败后再追加--break-system-packages重试一次——这正是为 PEP 668 管控的发行版如较新 Ubuntu、Debian、Fedora 的系统 Python准备的退路它绕过externally-managed-environment的拒绝同时21 | tail -3只把尾部几行错误/摘要带出来避免刷屏。这条探测 → 缺失即装 → 装完重探测的闭环保证了首次进入/graphify全流程时 Step 1 必然收敛到存在可用 graphify 的解释器。持久化.graphify_python 与 .graphify_root探测与安装完成后片段把两个供后续所有步骤共享的元数据写入graphify-out/# Write interpreter path for all subsequent steps (persists across invocations) mkdir -p graphify-out $PYTHON -c import sys; open(graphify-out/.graphify_python, w, encodingutf-8).write(sys.executable) # Save scan root so graphify update (no args) knows where to look next time echo $(cd INPUT_PATH pwd) graphify-out/.graphify_rootgraphify-out/.graphify_python写入最终解释器的sys.executable绝对路径。它是整个流程的单点事实。核心模板随后的每一个 Python 代码块都不再用裸python3而是通过$(cat graphify-out/.graphify_python) -c ...来调用——即片段末尾那句强调的约定In every subsequent bash block, replacepython3with$(cat graphify-out/.graphify_python)。在渲染产物 graphify/skill.md 的 Step 2 起所有代码块都以$(cat graphify-out/.graphify_python) -c 开头正是这条约定的实际体现。graphify-out/.graphify_root把INPUT_PATH用户传入的扫描根目录的绝对路径存下来供后续无参graphify update直接找回上次的扫描位置。这里用$(cd INPUT_PATH pwd)而非直接$PWD是为了把相对路径解析成不含符号链接歧义的规范绝对路径。为何统一写入graphify-out/该目录是每次建图的标准输出目录graph.html、graph.json、GRAPH_REPORT.md都落在这里把运行时状态与产物放在同一目录天然实现了同一份产物对应同一份解释器/扫描根的绑定避免跨调用串号。另外注意编码细节写入.graphify_python时显式指定encodingutf-8。在跨平台场景中如果解释器路径含非 ASCII 字符或换行符处理不当会污染后续读取而 POSIX 侧始终用 UTF-8 无 BOM 写入这也为与 Windows 变体保持字节一致埋下了伏笔见下文 Windows 一节。二次进入的守护interpreter-guard-posixposix.md面向的是首次完整建图流程。但当用户再次进入并运行子命令--update、--cluster-only、query、path、explain、add时graphify-out/可能已被删除或.graphify_python丢失。为此仓库还维护了配套片段 tools/skillgen/fragments/shell/interpreter-guard-posix.md其逻辑是只有文件缺失时才重建if [ ! -f graphify-out/.graphify_python ]; then GRAPHIFY_BIN$(which graphify 2/dev/null) if [ -n $GRAPHIFY_BIN ]; then PYTHON$(head -1 $GRAPHIFY_BIN | tr -d #!) case $PYTHON in *[!a-zA-Z0-9/_.-]*) PYTHONpython3 ;; esac else PYTHONpython3 fi mkdir -p graphify-out $PYTHON -c import sys; open(graphify-out/.graphify_python, w, encodingutf-8).write(sys.executable) fi这里复用了 shebang 回读的思路但做了轻量化不引入 uv 探测子命令路径要快直接读graphify二进制首行 shebang白名单校验失败就退回python3。它渲染到核心模板的 ## Interpreter guard for subcommands 一节槽位INTERP_GUARD见 core.md保证后续任何子命令运行前解释器引用仍然有效——是安装自举在时间维度上的延续。Windows 对照同一设计的 PowerShell 镜像理解 POSIX 片段的最好参照是它的孪生兄弟 tools/skillgen/fragments/shell/powershell.md。两者解决同一问题但实现分叉点体现了三个平台差异路径位置差异Windows 用uv tool dir与pipx environment --value PIPX_LOCAL_VENVS显式查询环境目录再拼graphifyy\Scripts\python.exeuv/pipx/venv 在 Windows 上解释器统一位于Scripts\下还额外覆盖了当前激活的 venv/conda 里恰好装了 graphify这一第 3 级来源。函数化与探测顺序PowerShell 版把探测封装成Find-GraphifyPython函数按 uv → pipx → 活动环境依次尝试实测 $py -c import graphify通过即返回。BOM 陷阱powershell.md用大段注释记录了Out-File -Encoding utf8在 Windows PowerShell 5.1 下会写 BOM、导致后续读取路径时出现 WinError 123对应 issue #3028因此改用[System.IO.File]::WriteAllText配New-Object System.Text.UTF8Encoding $false显式写无 BOM字节与 POSIX 侧写出的内容逐字节对齐。PowerShell 版的渲染产物可见 graphify/skill-windows.md。它同时也保留了.graphify_python与.graphify_root的持久化语义以及配套的轻量守护片段interpreter-guard-powershell.md解释器从graphify入口点同目录的python.exe推断。从源码结构看两套实现刻意维持行为等价正是为了把后续步骤无脑读.graphify_python这条契约做成跨平台一致的。渲染机制片段如何变成各宿主技能posix.md的价值最终要落进每个宿主的技能文件里才能生效这依赖tools/skillgen/gen.py的模板引擎。理解几个关键点有助于你阅读任何一份渲染产物确定性渲染输出强制 LF 换行、文件末尾恰好一个换行_normalise不写入时间戳或版本号因此渲染是幂等的——同一份片段永远产出同一份产物见 gen.py。漂移防护python -m tools.skillgen --check会对渲染结果与提交产物、以及 tools/skillgen/expected 下的快照做字节级比对任何手工改了生成文件或快照过期都会使 CI 失败并提示重跑或--bless见 gen.py。这意味着你在graphify/skill.md里看到的 Step 1 内容理论上永远与posix.md保持一致。POSIX → PowerShell 自动翻译gen.py还内置了_core_to_powershell翻译器对声明shell powershell的平台把核心模板里的 bash 代码块逐行改写成 PowerShellbashfence →powershellfence、$(cat …) -c …→ 单引号 here-string 管道喂给python -、rm -f→Remove-Item、mkdir -p→New-Item等并有禁止 token清单兜底未识别的 bash 行直接渲染期报错避免未来核心模板改动时把未翻译的 bash 悄悄发往 Windows 变体对应 issue #2528见 gen.py。何时重渲染从仓库根目录运行python -m tools.skillgen重新生成全部平台产物--platform claude只生成单个平台--bless刷新快照见 gen.py。这些操作是面向仓库维护者的普通使用者无需触碰片段。实际使用要点与排障路径结合片段与渲染产物在真实环境中把这条链路用起来时有几条实操要点首次建图的自举时机当你在某个宿主导入技能后运行/graphify .Step 1 会先执行上述探测/安装逻辑若探测成功且import graphify通过按片段尾部约定应不打印任何输出、直接进入 Step 2保持流程安静。确认解释器指向想看实际选中的解释器读取graphify-out/.graphify_python文件内容即可它是后续每个 Python 代码块的调用方。常见排障后续步骤报python: command not found或ModuleNotFoundError: No module named graphify——多半是某个代码块没用$(cat graphify-out/.graphify_python)而走了裸python3先检查该块是否遵守了替换约定删掉了graphify-out/后运行graphify query报错——先跑子命令守护片段重建.graphify_python或重新执行一次完整建图系统 Python 拒绝 pip 安装externally-managed-environment——对应片段的--break-system-packages回退分支或改用uv tool install graphifyy。包名细节可安装的分发包名为graphifyy见 pyproject.toml 与其中uv tool install graphifyy的注释而导入名、命令名分别为graphify模块与graphify命令——探测逻辑中uv tool run --from graphifyy、pip install graphifyy、import graphify三处对应三个不同命名维度不要混淆。总而言之tools/skillgen/fragments/shell/posix.md以不足 40 行的 bash 完成了解释器探测 → 自动安装 → 路径持久化的全部自举职责并通过渲染管线、快照防护、跨平台翻译把同一份契约同时交付给十几个 Agent 宿主。它既是 graphify 全流程可靠的第一块基石也是一个值得借鉴的、在多安装方式并存的 Python 生态中编写 Agent 技能引导逻辑的范本。【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
