deep-trace

Deep Trace — 逐行执行路径追踪器

Codex 兼容性

在 Codex 中运行此技能时，请先转换仅适用于 Claude Code 的原语，再执行操作：AskUserQuestion -> chat/request_user_input，TodoWrite -> update_plan，Task/TaskCreate/TeamCreate/SendMessage -> 在可用且允许时使用 spawn_agent/send_input/wait_agent，EnterPlanMode/ExitPlanMode -> 简洁的聊天计划并明确征求批准。 将 Read/Write/Edit/Bash/WebSearch/WebFetch 解析为 Codex 文件/命令行/网页工具，并将 ~/.claude/... 路径映射到 ~/.agents/... 或 ~/.codex/...，除非任务明确针对 Claude Code。

Cursor 兼容性

在 Cursor Agent 中运行此技能时，请先转换仅适用于 Claude Code 的原语，再执行操作：AskUserQuestion -> AskQuestion；TodoWrite -> Cursor TodoWrite 或等效的检查清单；Task/TaskCreate/TeamCreate/SendMessage/多 Agent 流程 -> 在允许时使用 Cursor Task（子 Agent）、并行 Tasks 或 run_in_background（TeamCreate/SendMessage 可能没有完全对应的功能）；EnterPlanMode/ExitPlanMode -> Plan mode（SwitchMode / CreatePlan）并明确征求用户批准。 通过 Cursor Composer 或 Agent 的对应功能解析 Read/Write/Edit/StrReplace/Bash/网页/搜索/MCP。写作 mcp__server__tool 的 MCP 名称通常映射到 call_mcp_tool，并使用已配置的服务标识符。将 ~/.claude/... 映射到 ~/.cursor/skills/、.cursor/skills/ 和 .cursor/rules/，除非任务明确针对 Claude Code。

<essential_principles>

核心概念

像调试器逐行执行代码一样追踪代码，同时补充以下信息：

• 屏幕：代码运行时用户看到的内容
• URL：代码执行所在的页面/API 路由
• 数据流：进入、转换和输出的数据
• 触发条件：导致此行代码执行的事件/操作

追踪表格格式

每次追踪都输出结构化表格：

## Trace: [description]

| # | File:Line | Code | Screen/URL | Data Flow | Trigger |
|---|-----------|------|------------|-----------|---------|
| 1 | page.tsx:15 | `const router = useRouter()` | /drawings | — | Page mount |
| 2 | page.tsx:16 | `const { id } = router.query` | /drawings?id=123 | id: string | URL params |
| 3 | hook.ts:8 | `const { data } = useQuery(...)` | /drawings?id=123 | id → API call | React render |
| ... | ... | ... | ... | ... | ... |

原则

1. Diff 优先：从变更行开始，向外追踪到入口点和下游影响
2. 逐行粒度：每个有意义的行单独占一行（跳过空行、导入和仅包含类型的行）
3. 屏幕映射：始终指出代码运行时用户所在的屏幕/URL
4. 双向追踪：同时向上追踪（谁调用了它？）和向下追踪（它调用了什么？）
5. 应用边界：用一行概述库调用，不要追踪进入 node_modules
6. 文件:行号不得缩写：绝不截断文件名或用省略号代替。始终显示完整文件名（例如，useSetFormValuesFromQueryStrings.tsx:77，而非 useSetFormValues...:77）。代码列超过 80 个字符时可以缩写，但文件名必须准确。

</essential_principles>

工作流

步骤 1：确定目标

根据用户参数确定输入来源：

输入	检测方式	操作
PR 编号	#1234 或数字	gh pr diff <number>
分支差异	--diff 或无参数	git diff HEAD~1 或 git diff dev...HEAD
文件路径	.ts、.tsx 等	读取文件，从导出项开始追踪
函数名称	不含路径的文本	Serena find_symbol

步骤 2：提取变更代码

对于 PR/差异输入：

1. 解析差异，获取变更文件和行范围
2. 按文件归类变更
3. 按优先级排序：组件 > 钩子 > 工具函数 > 类型

对于文件/函数输入：

1. 读取目标代码
2. 找出导出的函数/组件

第 3 步：查找入口点

对于每个有变更的代码段，向上追溯以查找入口点：

Changed line → containing function → caller → ... → page component / API route / event handler

使用 Serena 工具：

• find_symbol — 定位函数
• find_referencing_symbols — 查找调用方
• 重复以上步骤，直到到达页面／路由／事件边界

入口点类型：

类型	示例	屏幕／URL
页面组件	pages/drawings/index.tsx	/drawings
API 路由	pages/api/drawings.ts	POST /api/drawings
事件处理程序	onClick、onSubmit	当前页面上的按钮点击
Effect	useEffectOnMount	页面加载
Provider	_app.tsx 包装器	所有页面

第 4 步：构建追踪表

从入口点开始，逐行追踪：

1. 阅读入口点文件（使用 Serena 的 find_symbol，并设置 include_body=True）

2. 为每一行有意义的代码创建一行表格：

   • #：连续的步骤编号
   • File:Line：完整文件名 + 行号。绝不可缩写文件名或使用省略号
   • Code：实际代码（用反引号包裹；超过 80 个字符时可以缩写）
   • Screen/URL：当前活动的屏幕／页面／URL
   • Data Flow：正在读取／写入／转换的数据
   • Trigger：触发此行执行的事件（挂载、点击、API 响应等）

3. 遇到函数调用时：

   • 如果是应用代码 → 继续追踪进入其中（使用 3.1、3.2 等子步骤）
   • 如果是库调用 → 用一行并以 [lib] 前缀概述

4. 遇到条件语句时：标注两条路径，并追踪主要路径

第 5 步：添加上下文注释

在追踪表之后添加以下章节：

## Summary
- **When**: [user action / event that triggers this code]
- **Where**: [screen URL and component location]
- **What**: [1-2 sentence description of what the code accomplishes]
- **Data**: [key data entities involved, their sources and destinations]

## Key Observations
- [Notable patterns, potential issues, or design decisions]

第 6 步：生成兼容扩展的输出

在 Summary 之后，为 deep-trace-extension VS Code 扩展生成一份单独的可复制表格。

扩展格式（4 列，必须使用指定的表头）：

## 📋 Deep Trace Extension

| file | line | col | reason |
| --- | --- | --- | --- |
| src/components/FreewordSearchFilter.tsx | 40 | 1 | useFreewordSearchFormContext — Component render |
| src/components/FreewordSearchFilter.tsx | 54 | 1 | useWatch target values — Form state change |

追踪表 → 扩展表的转换规则：

追踪表列	→ 扩展表列	规则
File:Line	file + line	在最后一个 : 处分割——前面是文件路径，后面是行号
—	col	始终为 1（追踪中不记录列信息）
Code + Trigger	reason	组合：简短的代码说明 + — + 触发事件

要求：

• 追踪表中的每一行都必须有对应的一行
• file 必须是完整的相对路径（不能只有文件名）。如果追踪表中只有文件名，请使用 Serena 从项目根目录解析路径
• 将输出放在围栏代码块（```markdown ... ```）中，以便用户复制原始 Markdown

步骤 6.5：将扩展表复制到剪贴板（可选，因操作系统而异）

在打印完步骤 6 中的围栏扩展表区块后，还要将同一区块通过管道传给随附的辅助工具，这样用户就可以直接粘贴到 deep-trace-extension 中，无需手动选择：

cat <<'EOF' | bash skills/deep-trace/scripts/copy-to-clipboard.sh
| file | line | col | reason |
| --- | --- | --- | --- |
| src/components/FreewordSearchFilter.tsx | 40 | 1 | useFreewordSearchFormContext — Component render |
| src/components/FreewordSearchFilter.tsx | 54 | 1 | useWatch target values — Form state change |
EOF

辅助工具会自动检测主机上的剪贴板工具：

操作系统／环境	尝试使用的工具
macOS	pbcopy
Linux（Wayland 会话）	wl-copy
Linux（X11 会话）	xclip -selection clipboard → xsel
WSL	clip.exe
Cygwin／MinGW／MSYS	clip
无可用工具／未知操作系统	跳过，并在 stderr 中输出一行提示

行为约定（不得违反）：

• 步骤 6 中的围栏 Markdown 区块始终先打印；复制到剪贴板只是附加操作，绝不能取而代之。
• 脚本始终以 0 退出，即使不存在剪贴板工具也不例外。剪贴板不可用不得导致技能工作流失败。
• 脚本会在 stderr 中报告所选工具（或跳过原因），例如 copy-to-clipboard: copied via pbcopy (macOS)。请将该行反馈给用户，让他们知道是否需要手动复制。

以下情况应完全跳过此步骤：

• 无头 CI／非交互式运行（没有人需要粘贴）
• 禁止访问剪贴板或剪贴板访问无意义的沙盒或远程环境
• 用户明确选择退出（例如，涉及敏感安全信息的场景）

步骤 7：保存到记忆中（可选）

如果用户想记住这条追踪记录：

Serena write_memory("trace_<descriptive_name>", traceContent)

示例

示例：追踪 PR 差异

/deep-trace #3548

输出：

## Trace: PR #3548 — フリーワード検索の種別フィルター追加

### Entry: FreewordSearchFilter.tsx (絞り込みPopover内)

| # | File:Line | Code | Screen/URL | Data Flow | Trigger |
|---|-----------|------|------------|-----------|---------|
| 1 | FreewordSearchFilter.tsx:40 | `const { control } = useFreewordSearchFormContext()` | /freeword_search?query=テスト | form context | Component render |
| 2 | FreewordSearchFilter.tsx:54 | `const targetValues = useWatch({ control, name: 'target' })` | same | target: SelectOption[] | Form state change |
| 3 | FreewordSearchFilter.tsx:65 | `useDocumentTypeSettingsQuery(...)` | same | API → document_type_settings | React Query cache/fetch |
| 4 | FreewordSearchFilter.tsx:70 | `const targetOptions = useMemo(...)` | same | settings → SelectOption[] | Deps change |
| 5 | FreewordSearchFilter.tsx:119 | `<MultiSelectRHF ... options={targetOptions}>` | same (Popover open) | targetOptions → UI | User opens filter |

### Summary
- **When**: User opens 絞り込み popover on freeword search page
- **Where**: /freeword_search (ファイルフリーワード検索モード)
- **What**: Shows multi-select filter for 種別 (drawing + document types)
- **Data**: document_type_settings API → SelectOption[] → form state → API search params

## 📋 Deep Trace Extension

```markdown
| file | line | col | reason |
| --- | --- | --- | --- |
| src/components/FreewordSearchFilter.tsx | 40 | 1 | useFreewordSearchFormContext — Component render |
| src/components/FreewordSearchFilter.tsx | 54 | 1 | useWatch target values — Form state change |
| src/components/FreewordSearchFilter.tsx | 65 | 1 | useDocumentTypeSettingsQuery — React Query cache/fetch |
| src/components/FreewordSearchFilter.tsx | 70 | 1 | useMemo targetOptions — Deps change |
| src/components/FreewordSearchFilter.tsx | 119 | 1 | MultiSelectRHF render — User opens filter |

## Tools Used

| Tool | Purpose |
|------|---------|
| `gh pr diff` | Get PR diff |
| `git diff` | Get branch diff |
| Serena `find_symbol` | Locate functions |
| Serena `find_referencing_symbols` | Find callers (trace UP) |
| Serena `get_symbols_overview` | Map file structure |
| Serena `write_memory` | Save trace for future reference |
| `scripts/copy-to-clipboard.sh` | OS-aware clipboard copy of the extension table (pbcopy / wl-copy / xclip / xsel / clip.exe / clip; graceful skip otherwise) |

## Success Criteria

- [ ] Entry point correctly identified (page/route/event)
- [ ] Every meaningful changed line has a trace row
- [ ] Screen/URL column populated for all rows
- [ ] Data flow shows inputs → transformations → outputs
- [ ] Trace is readable top-to-bottom as an execution story
- [ ] Summary captures when/where/what/data
- [ ] Extension-compatible table included with `file`, `line`, `col`, `reason` columns
- [ ] Extension table uses full relative paths (not just filenames)
- [ ] Extension table wrapped in fenced code block for easy copy
- [ ] Extension table also piped through `scripts/copy-to-clipboard.sh` (or step explicitly skipped with reason); helper's stderr status surfaced to the user