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 进入技能文件夹）。直接调用：跟踪树操作。在 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)。错误信息通过 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 为 true 表示已写入新的 XML。退出码 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（用于 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。永远不要将 CLI 包装在使用名为 $Args 的参数的帮助程序中。

提示	结果
精确行 + 完整修剪文本	按原样使用
该行的独特子字符串（例如 .handleEmailTriggerRequest(）	--line 是必需的；存储完整的修剪行
2行以上的相同修剪文本	传递 --line 以指定预期的副本；脚本设置出现次数
多行调用	偏好最独特的物理行（通常是 .methodName( 延续行）

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

生成树： 推荐使用 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() {"]]'

method A def
  method B call
    method C call   ← 使用 --parent-id idA --parent-id idB 添加（或确保，如果 B 已存在）

磁盘编辑后重新绑定： 代理不通过 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)。错误信息通过 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"）

...

[已因翻译而截断]