saidake/code-trace-tree-vscode

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。下表列出常見範例；其他列出的代理運作方式相同。

代理 (範例)	全域 Agent Skill Path	專案本機 Agent Skill Path
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（或如果 PATH 上有 python3 則使用 python3）以及絕對路徑來執行腳本。保持處理程序的 CWD 在 IDE 專案中（不要 cd 進入技能資料夾）。直接執行：請參閱追蹤樹操作。在 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> 是正確的。

回傳值

Stdout 是 JSON（indent=2，UTF-8）。錯誤訊息會印在 stderr 上，格式為 ERROR: …。

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

created 在寫入新的 XML 時為 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

在一次呼叫中建立巢狀追蹤點樹。僅確保有效負載的根節點（以及已經存在的根節點的子節點）。一旦節點被建立，其後代會被新增（不進行逐子確保）。如果不需要，請勿 search——此腳本已確保現有節點。當您需要 ID（用於選擇/移動/刪除）或檢查時，請使用 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 檔案（- = 標準輸入）。優先於 --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 是相同物件的陣列。

回傳值

Stdout 是 JSON（indent=2，UTF-8）。節點上的 skipped: true 表示確保時已找到；該節點的子節點仍會被確保。created: true 表示已新增；該節點的子孫節點會在沒有確保的情況下被新增。

{
  "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。一個檔案中重複的修剪後行之所以不同，是因為 --line 選擇了哪一個副本。忽略出現次數： 請勿讀取、傳遞或計算 occurrenceIndex / totalOccurrences。在 PowerShell 上，使用 --% 保護加引號的 --content（請參閱 Windows PowerShell），或使用子字串提示加上 --line。永遠不要將 CLI 包裝在使用名為 $Args 的參數的輔助函數中。

提示	結果
精確行 + 完整修剪後文字	按原樣使用
該行的獨特子字串（例如 .handleEmailTriggerRequest(）	需要 --line；儲存完整的修剪後行
2 行以上有相同的修剪後文字	為預期的副本傳遞 --line；腳本設定出現次數
多行呼叫	偏好最具區別性的實際程式碼行（通常是 .methodName( 的延續行）

add 與 ensure 的比較： add 總是建立一個新的 UUID（與 IDE 外掛相同）。對於同一行上具有不同標籤或父節點的第二個節點，請使用它。ensure 是「取得或建立」：相同的身份 → "skipped": true（退出碼 0）。對於 LINE，身份是檔案 + 修剪後的 lineContent + 由 --line 選擇的副本（腳本儲存出現次數；不要傳遞它）。FILE/DIRECTORY 身份是路徑 + 類型。--trace-name、描述和父節點不是身份。

生成樹： 偏好使用 create_tree.py。如果不需要，請勿 search——腳本會確保現有節點並新增子樹。當您需要 ID 來選擇/移動/刪除或檢查時，請使用 search。對於單一節點，請使用 ensure（取得或建立；不需要搜尋）或 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() {"]]'

方法 A 定義
  方法 B 呼叫
    方法 C 呼叫   ← 使用 --parent-id idA --parent-id idB 新增（或如果 B 已存在則確保）

磁碟編輯後重新綁定： 代理不會透過 IDE 編輯器進行編輯，因此不會發生行位移。在任何修改了專案原始碼的回合之後，請在依賴定位器或選擇/導覽之前執行 rebind（可以選擇使用 --file 指定受影響的路徑）。Rebind 會從修剪後的 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 節點。

回傳值

Stdout 是 JSON（indent=2，UTF-8）。錯誤訊息會印在 stderr 上，格式為 ERROR: …，並以非零值退出。

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"）

…

[已截斷以進行翻譯]