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 路径	项目本地 Agent Skill 路径
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）以绝对路径调用脚本。保持进程的当前工作目录（CWD）在 IDE 项目中（不要 cd 进入技能文件夹）。直接调用：Trace Tree 操作。在 PowerShell 上，另请参阅 Windows PowerShell。

Trace Tree 操作

所有技能脚本调用。将绝对 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: … 的形式打印到标准错误输出。

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

在一次调用中创建一个嵌套的追踪点树。仅确保 有效负载的根节点（以及已存在的根节点的子节点）。一旦创建了一个节点，其后代节点将被添加（不对每个子节点进行 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 文件（- 代表标准输入）。优先于 --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 找到了它；该节点的子节点仍然会被 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。一个文件中重复的修剪行是不同的，因为 --line 会选择哪个副本。忽略出现次数： 不要读取、传递或计算 occurrenceIndex / totalOccurrences。在 PowerShell 上，使用 --% 保护带引号的 --content（请参阅 Windows PowerShell），或使用子字符串提示加上 --line。切勿在名称包含 $Args 参数的帮助程序中包装 CLI。

提示	结果
精确的行 + 完整的修剪文本	按原样使用
该行的独特子字符串（例如 `.handleEmailTriggerRequest(`）	需要 `--line`；存储完整的修剪行
2 行以上有相同的修剪文本	为目标副本传递 `--line`；脚本设置出现次数
多行调用	优先选择最独特的物理行（通常是 `.methodName(` 续行）

add 与 ensure 的区别： add 总是创建一个新的 UUID（与 IDE 插件相同）。用于在同一行上使用不同标签或父节点的第二个节点。ensure 是获取或创建：相同身份 -> "skipped": true（退出码 0）。对于 LINE，身份是文件 + 修剪后的 lineContent + 由 --line 选择的副本（脚本存储出现次数；不要传递它）。FILE/DIRECTORY 的身份是路径 + 类型。--trace-name、description 和 parent 不是身份。

生成树： 优先使用 create_tree.py。如果不需要，请不要进行 search——此脚本会确保现有节点并添加新的子树。当您需要 ID 用于 select/move/delete 或进行检查时，请使用 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 已存在则 ensure）

磁盘编辑后重新绑定： 代理不通过 IDE 编辑器进行编辑，因此行号移位不适用。在修改了项目源代码的每个交互回合之后，在依赖定位器或 select/navigate 之前，运行 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 节点。

返回值

标准输出是 JSON（indent=2，UTF-8）。错误信息以 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"）

…

Code Trace Tree（代码追踪树）