Graphify 安裝驗證 · Graphify

簡介

本 Harness 驗證 graphify 是否能在本機正確安裝、CLI 可執行，並能向目前的 AI 助理註冊 always-on 圖譜諮詢能力。所有步驟都與官方 Graphify-Labs/graphify v0.9.32 README 對齊。

🔑 關鍵命名：graphify 的 PyPI 套件名是 graphifyy（雙 y），CLI 指令才是 graphify。兩者容易混淆，本 Harness 每一步都會明確標示。

工具	版本	安裝指令
Python	3.10+	`python --version`
uv（推薦）	any	`curl -LsSf https://astral.sh/uv/install.sh \| sh`（macOS/Linux）或 `winget install astral-sh.uv`（Windows）
pipx（替代）	any	`pip install pipx`

# 推薦：使用 uv 安裝到隔離環境（避免系統 Python 污染）
uv tool install graphifyy

# 或使用 pipx
pipx install graphifyy

⚠️ graphify 不是 npm 套件。不要使用 npm install -g @graphify/cli，該套件與官方無關。

graphify --version

預期輸出：版本號等同於 theme.yaml 中記錄的 version（撰寫時為 0.9.26）。如果後續 graphify 升版，請同步更新 theme.yaml。

通過條件：

如果 graphify 指令找不到：

# uv：將工具 bin 加入 PATH
uv tool update-shell

# pipx：檢查 PATH
pipx ensurepath

然後開一個新的終端機再試一次。

graphify 透過 graphify install <platform> 對 20+ AI 助理平台寫組態檔，讓助理優先用 graphify 圖譜而不是 grep 原始檔。

# 列出可用的 platform install 子指令
graphify --help

預期輸出：在 help 文字中應能看到 install、claude、cursor、codex、gemini、copilot、kilo、aider、amp、agents（cross-framework）等多個子指令。

# 進入要使用的專案目錄
cd path/to/your/project

# 對 Claude Code 做 project-scoped 註冊
graphify claude install --project

預期結果：

在 .claude/skills/graphify/ 建立 SKILL.md
在 .claude/settings.json 寫入 PreToolUse hook（在 Bash search 與 Read/Glob 之前 nudge 助理先 graphify query）
終端機印出 git add 提示，列出可 commit 的檔案

# Claude Code 的 strict 模式：第一個原始檔讀取前強制 redirect 到 graphify query
graphify claude install --project --strict

可隨時切換（不需重新安裝）：

export GRAPHIFY_HOOK_STRICT=1   # 啟用
export GRAPHIFY_HOOK_STRICT=0   # 停用（回軟性 nudge）

strict 模式只對 Claude Code 有效（Bash/Glob 仍是軟性 nudge；Gemini/Codex/OpenCode 無法硬擋）。

步驟	測試項目	狀態	預期結果
1	安裝 `graphifyy` PyPI 套件	🔲	`uv tool install graphifyy` 成功
2	`graphify --version` 輸出版本	🔲	版本號 ≥ `theme.yaml.version`
3	`graphify --help` 列出 platform install 子指令	🔲	出現 `install`、`claude`、`cursor`、`codex`、`gemini` 等
4	`graphify <platform> install --project` 寫入組態	🔲	`.claude/skills/graphify/SKILL.md`（或其他平台對應路徑）存在
5	strict 模式可切換（可選）	🔲	設 `GRAPHIFY_HOOK_STRICT=1` 後 hook deny 行為不同

若所有測試均通過 🟢，表示 graphify 已可用於正式建圖與查詢。若有任何 🔴 失敗，先排查安裝或 PATH 問題再進行後續操作。