saidake/code-trace-tree-jetbrains

Code Trace Tree

建立並顯示程式碼工作流程，以巢狀樹狀結構呈現行、檔案和目錄追蹤點。使用提供的 Python 指令碼來操作 Code Trace Tree IDE 外掛程式使用的混合儲存，然後要求 IDE 重新載入。

僅在使用者明確要求時才編輯或同步追蹤點（例如：產生與主題相關的節點、在某一行程式碼新增提示、編輯後重新綁定）。請勿在每次對話回合自動同步。除非使用者明確要求移除，否則永遠不要 delete 現有的追蹤點（包含 rebind 回報為 "invalid" 的節點）。

如何使用此技能

僅需閱讀此 SKILL.md。請勿列出、搜尋或瀏覽此技能的 scripts/ 或 references/ 資料夾，也不要開啟指令碼原始碼來學習 API。請使用絕對路徑執行文件中記載的 Python 命令。

僅在遭遇關鍵問題（例如指令碼遺失或崩潰、儲存損毀，或此文件未涵蓋的錯誤）時，才開啟 scripts/ 或 references/。

技能指令碼位置

輔助指令碼位於 <Agent Skill Path>/code-trace-tree/scripts/ 目錄下。

Agent Skill Path 是你正在執行的代理的技能目錄（即 code-trace-tree/ 的父目錄）——如果存在專案本地目錄則使用它，否則使用全局目錄。此路徑以 skills 結尾，而非 code-trace-tree。路徑與 npx skills 相符。下方表格列出常見範例；其他列出的代理運作方式相同。

代理（範例）	全局代理技能路徑	專案本地代理技能路徑
Claude Code	~/.claude/skills	<repo>/.claude/skills
Cursor	~/.cursor/skills	<repo>/.agents/skills
GitHub Copilot	~/.copilot/skills	<repo>/.agents/skills
Codex	~/.codex/skills	<repo>/.agents/skills
Gemini CLI	~/.gemini/skills	<repo>/.agents/skills

在 Windows 上，~ 表示 %USERPROFILE%。在每次工作階段解析一次 Agent Skill Path。使用 python（或 python3，視 PATH 環境變數而定）並以絕對路徑呼叫指令碼。保持處理程序的 CWD 在 IDE 專案目錄中（請勿 cd 進入 skills 資料夾）。直接呼叫請參閱追蹤樹操作。若使用 PowerShell，另請參閱 Windows PowerShell。

追蹤樹操作

所有技能指令碼的呼叫。將絕對的 Agent Skill Path 替換為此代理的實際路徑。保持處理程序的 CWD 在 IDE 專案目錄中（請勿 cd 進入技能資料夾）。若使用 PowerShell，請參閱 Windows PowerShell。

• resolve_storage.py
• create_tree.py
• trace_tree.py
• request_refresh.py
• request_refresh_profile.py
• request_refresh_settings.py
• select_trace_points.py

resolve_storage.py

解析專案 ID 並綁定全局 XML。如果儲存不存在，則建立它（情況 C）。如果 .idea/code-trace-tree.project.id 存在但 XML 遺失，則使用相同的 projectId 重新建立 XML。不會建立或覆寫 .idea 的 id 檔案。變動性的 create_tree 和 trace_tree add / ensure / move / delete / rebind 也會自動建立儲存。trace_tree search 不會自動建立。

用法

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" [project_path]

可選參數：

• [project_path]：用於發現 IDE 專案根目錄的路徑（預設值：CWD）。傳遞專案根目錄以確保 XML 中的 <path> 正確。

回傳值

標準輸出為 JSON（indent=2，UTF-8）。錯誤訊息會以 ERROR： … 格式輸出至 stderr。

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<OS Config Dir>/code-trace-tree",
  "project_id": "<uuid or null>",
  "storage_xml": "<abs xml path>"
}

如果寫入新的 XML，則 created 為 true。成功時退出碼為 0；如果找不到專案根目錄，則退出碼為 1。

範例：

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py"
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" /path/to/project

create_tree.py

在一次呼叫中建立巢狀的追蹤點樹。僅確保有效載荷的根節點（以及已存在根節點的子節點）。節點建立後，其子孫節點會新增（不對每個子節點執行 ensure）。請勿在不需要時執行 search——此指令碼已確保現有節點。當你需要 ID 以進行 select/move/delete 或檢查時，才使用 search。LINE 定位器與 trace_tree.py 相同（file + line + content）。忽略行內容的出現次數（occurrenceIndex / totalOccurrences）——指令碼會自動計算。在 PowerShell 上，偏好在 --tree-file 使用。

可選的 --parent-id 可將有效載荷附加到現有節點下（該父節點會被解析，但不會被確保）。

用法

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

必要參數（恰好一個樹來源）：

• --tree-file <path>：JSON 文件（- 表示 stdin）。優先於 --tree。
• --tree <json>：JSON 字串。
• 位置參數 <path>：與 --tree-file 相同。

參數（共享；全部可選）：

• --project <path>：專案路徑（預設：CWD）。
• --profile <name>：設定檔名稱覆蓋（預設：<activeProfileName>）。
• --dry-run：不寫入 XML 或重新整理。
• --no-refresh：跳過 IDE 重新整理信號。
• --parent-id <uuid>：現有父節點；從根方向重複指定直到直屬父節點。對於設定檔根節點則省略。
• --parent <json>：現有父節點路徑 JSON（請勿與 --parent-id 合併使用）。

樹狀結構 JSON（一個節點物件，或一個節點物件的陣列）。每個節點使用相同的結構，包括 children（description 存在於每個節點，而不僅僅是根節點）：

{
  "file": "src/A.java",
  "line": 10,
  "content": "void methodA() {",
  "name": "methodA",
  "description": "",
  "type": "LINE",
  "children": [
    {
      "file": "src/B.java",
      "line": 40,
      "content": "void methodB() {",
      "name": "methodB",
      "description": "",
      "type": "LINE",
      "children": [
        {
          "file": "src/C.java",
          "line": 20,
          "content": "void methodC() {",
          "name": "methodC",
          "description": "",
          "type": "LINE"
        },
        {
          "type": "FILE",
          "file": "src/Util.java",
          "name": "Util",
          "description": ""
        }
      ]
    }
  ]
}

欄位（每個節點，包括子節點）：file（必要）；type（LINE | FILE | DIRECTORY；省略時由系統推斷：有 line/content 則為 LINE，否則依據磁碟上路徑判定）；LINE 類型需要 line + content；name / description / children 可選。請勿包含 occurrenceIndex / totalOccurrences。children 是相同物件類型的陣列。

回傳值

標準輸出為 JSON（indent=2，UTF-8）。節點上的 skipped： true 表示 ensure 找到該節點；該節點的子節點仍會被確保。created： true 表示新增；該節點的子孫節點會在不經 ensure 的情況下新增。

{
  "action": "create_tree",
  "profile": "<profile-name>",
  "storage_xml": "<abs>",
  "parentId": "<uuid or empty>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <node-object>, "children": [ … ] } ],
  "refreshed": true
}

成功時退出碼為 0。

範例：

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file tree.json

trace_tree.py

搜尋、新增、確保、移動、刪除和重新綁定節點。忽略行內容的出現次數（occurrenceIndex / totalOccurrences）——永遠不要傳遞這些欄位；指令碼會自行計算。

用法

python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" <subcommand> [flags…]
python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" [shared-flags] <subcommand> [flags…]

共享標誌（--project、--profile、--dry-run、--no-refresh）可以出現在子命令之前或之後。當 CWD 已經在 IDE 專案目錄內時，可省略 --project（指令碼會向上搜尋 .vscode / .idea / .git 或其他常見專案標記）。預設設定檔：<activeProfileName>。

LINE 定位器： 儲存的提示為 [file, line, full-trimmed-line]。--line 是必填的。指令碼會檢查該行的修剪後文字，儲存完整的修剪後行（--content 的子字串會被擴展），然後透過掃描檔案來設定 occurrenceIndex / totalOccurrences。忽略出現次數： 不要讀取、傳遞或計算 occurrenceIndex / totalOccurrences。在 PowerShell 上，使用 --% 保護帶引號的 --content（請參閱 Windows PowerShell），或使用子字串提示加上 --line。永遠不要將 CLI 包裝在使用名為 $Args 參數的輔助程式中。

提示	結果
確切行號 + 完整修剪後的文字	直接使用
該行的獨特子字串（例如 .handleEmailTriggerRequest(）	需要 --line；儲存完整的修剪後行
2 行以上有相同的修剪後文字	為預期的副本傳遞 --line；指令碼設定出現次數
多行程式碼	偏好使用最獨特的物理行（通常是 .methodName( 接續行）

add 與 ensure 的區別： add 總是建立一個新的 UUID（與 IDE 外掛程式相同）。用於在同一行程式碼上建立具有不同標籤或父節點的第二個節點。ensure 是 get-or-create：相同身份 → "skipped"： true（退出碼 0）。對於 LINE，身份由 file + trimmed lineContent + 透過 --line 選擇的副本共同決定（指令碼儲存出現次數；不要傳遞它）。FILE/DIRECTORY 的身份是路徑 + 類型。--trace-name、描述和父節點不屬於身份。

產生樹狀結構： 偏愛 create_tree.py。不要在不需要時執行 search——此指令碼會確保現有節點並新增子樹。當你需要 ID 以進行 select/move/delete 或檢查時，才使用 search。對於單一節點，使用 ensure（get-or-create；無需搜尋）或 add（總是建立新的 UUID）。

父路徑： 偏愛從祖先根節點到直屬父節點重複指定 --parent-id。對於 add / ensure 的根節點則省略。不要將 --parent-id 與 --parent 合併使用。--parent JSON 內部的裸字串僅為 UUID，不能使用 traceName 標籤。

--parent 形式	範例
根節點	--parent []（move 到根節點需要此參數；add / ensure 預設為根節點）
JSON 中的節點 ID	--parent '["3d41c2d1-…"]'
[file, line, content]	--parent '[["src/A.java",10,"void methodA() {"]]'

method A def
  method B call
    method C call   ← 使用 --parent-id idA --parent-id idB 進行 add（或如果 B 已存在則使用 ensure）

磁碟編輯後的重新綁定： 代理不會透過 IDE 編輯器進行編輯，因此即時的行號偏移不適用。在每一個修改了專案原始碼的對話回合之後，在依賴定位器或 select/navigate 之前，執行 rebind（可選用 --file 指定受影響的路徑）。重新綁定會從修剪後的 lineContent 修復 lineNumber 並重新計算出現次數。"invalid" 陣列表示那些 LINE 定位器未被找到——將這些節點保留在樹中；不要 delete 它們，除非使用者要求移除。

對於多個變動性呼叫，請在每個呼叫中使用 --no-refresh，然後在最後執行一次 request_refresh.py。

必要子命令：

• <subcommand>：search | add | ensure | move | delete | rebind

參數（共享；全部可選）：

• --project <path>：專案路徑（預設：CWD）。
• --profile <name>：設定檔名稱覆蓋（預設：<activeProfileName>）。
• --dry-run：不寫入 XML 或重新整理。
• --no-refresh：跳過 IDE 重新整理信號。

參數（search；全部可選）：

• --id <uuid>：節點 UUID。
• --file <path>：相對的檔案/目錄路徑。
• --line <n>：基於 1 的行號。
• --content <text>：對 lineContent 的子字串比對。
• --trace-name <text>：對 traceName 的子字串比對。
• --type <LINE|FILE|DIRECTORY>：按類型過濾。

參數（add / ensure）：

• 定位器（必要）：對於 LINE 類型為 --file + --line + --content（該行的子字串也可以）；對於 FILE/DIRECTORY 為 --file。或者使用位置參數 FILE LINE CONTENT，或路徑。
• --parent-id <uuid>（可選）：父節點 UUID；從根方向重複指定直到直屬父節點（偏愛此方式）。對於根節點則省略。
• --parent <json>（可選）：JSON 父路徑（請勿與 --parent-id 合併使用）。
• --trace-name <text>（可選）：追蹤點標籤。
• --description <text>（可選）：描述。
• --type <LINE|FILE|DIRECTORY>（可選）：類型覆蓋（預設：LINE）。

參數（move）：

• 定位器（必要）：--id，或 --file + --line + --content，或單獨 --file（用於 FILE/DIRECTORY）。
• 新父節點（必要）：--parent-id（從根方向重複直到直屬父節點）或 --parent JSON。對於根節點，使用 --parent []。請勿將 --parent-id 與 --parent 合併使用。

參數（delete）：

• 定位器（必要）：--id，或 --file + --line + --content，或單獨 --file（用於 FILE/DIRECTORY）。

參數（rebind；全部可選）：

• --file <path>：限制為相對路徑；可重複。預設：設定檔中的所有 LINE 節點。

回傳值

標準輸出為 JSON（indent=2，UTF-8）。錯誤訊息會以 ERROR： … 格式輸出至 stderr 並以非零退出碼結束。

node-object：

{
  "id": "<uuid>",
  "parentId": "<uuid or empty>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<relative path>",
  "line": "<n or empty>",
  "content": "<trimmed lineContent>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search：

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<profile-name>",
  "matches": [ <node-object>, … ]
}

add（總是建立；無 "skipped"）

…[翻譯時已截斷]