code-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 Code，否则将 ~/.claude/... 路径映射到 ~/.agents/... 或 ~/.codex/...。

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/web/search/MCP。写作 mcp__server__tool 的 MCP 名称通常应映射到 call_mcp_tool，并使用已配置的服务标识符。除非任务明确针对 Claude Code，否则将 ~/.claude/... 映射到 ~/.cursor/skills/、.cursor/skills/ 和 .cursor/rules/。

<essential_principles>

代码追踪的工作方式

此技能以交互方式追踪代码执行路径，让你能够像调试器逐步执行代码一样浏览代码库，并在每一步获得详细说明。

原则 1：应用边界

仅追踪应用代码。对于外部依赖（node_modules、vendor/），提供：

• 功能摘要
• 官方文档链接
• 不深入追踪其内部实现

原因：外部库可能有 10 万行以上代码。深入追踪其中的实现会浪费上下文，并掩盖实际的应用逻辑。目标是理解你的代码，而不是库的内部实现。

原则 2：交互式导航

每个条件分支都会成为用户的选择：

代码模式	展示方式
if/else	“路径 A：条件为真”与“路径 B：条件为假”
switch	每个 case 对应一个选项
try/catch	“成功路径”与“错误路径”
async/await	提供追踪被调用函数的选项

原因：线性追踪会遗漏重要路径。交互式导航让用户能够探索自己真正感兴趣的内容。

原则 3：渐进式说明

每一步都包含：

1. 位置：文件 + 行范围 + 函数名称
2. 代码：完整源码（不省略）
3. 内容：简要概述代码的作用
4. 原因：说明这一步为何存在于流程中
5. 后续：接下来会发生什么（或分支时提供选项）

使用思考标记（🤔🎯⚡📊💡🔐），让内容更清晰。

原则 4：状态持久化

追踪状态存储在 Serena Memory 中，以便：

• 恢复中断的追踪
• 回溯到之前的决策点
• 保存已完成的追踪，供日后参考 </essential_principles>

## 你想追踪什么？

1. 追踪请求流程 - 跟踪 HTTP 请求从接收至响应的过程
2. 追踪函数调用 - 跟踪特定函数在代码库中的调用过程
3. 继续之前的追踪 - 从上次停止的位置继续

请提供更多背景信息：

• 对于请求追踪：具体是哪个端点？（例如，“POST /api/users”）
• 对于函数追踪：具体是哪个函数？（例如，“validateUser” 或 “src/utils/auth.ts:checkToken”）

继续前请等待回复。

| 回复 | 工作流 | |----------|----------| | 1、“request”、“HTTP”、“route”、“API”、“endpoint”、“POST”、“GET” | `workflows/trace-request.md` | | 2、“function”、“call”、具体函数名 | `workflows/trace-function.md` | | 3、“resume”、“continue”、“previous” | 读取 Serena memory 中的 `trace_session_*` |

开始任何工作流之前

1. 检测框架：运行 scripts/detect-framework.sh，以识别：

   • Express、Next.js（App/Pages）、Fastify、Hono、NestJS、Koa 或通用框架

2. 加载框架模式：阅读 references/framework-patterns.md 中与检测到的框架对应的部分

3. 准备 Serena：确保 Serena MCP 可用，以便使用：

   • find_symbol() - 定位函数/处理程序
   • find_referencing_symbols() - 查找调用方
   • get_symbols_overview() - 映射模块结构
   • write_memory() / read_memory() - 保存状态

确定意图和框架后，阅读相应的工作流并按其步骤操作。

<reference_index>

参考资料

均位于 references/：

文件	内容
framework-patterns.md	检测 Express、Next.js、Fastify 等框架的入口点及请求流程
control-flow-types.md	如何将 if/switch/try/循环呈现为交互选项
explanation-style.md	思考标记、步骤格式、摘要格式
mermaid-templates.md	根据追踪 path_history 生成 Mermaid.js 流程图
</reference_index>

<workflows_index>

工作流

均位于 workflows/：

工作流	用途
trace-request.md	从入口到响应追踪 HTTP 请求
trace-function.md	追踪特定函数的调用链
</workflows_index>

<scripts_index>

脚本

脚本	用途
detect-framework.sh	根据 package.json 自动检测项目框架

用法：

./scripts/detect-framework.sh /path/to/project
# Output: express | nextjs-app | nextjs-pages | fastify | hono | nestjs | koa | generic

</scripts_index>

<success_criteria> 成功的代码追踪应满足以下条件：

• 正确识别并解释入口点
• 检测框架并应用相应模式
• 至少将一个分支点呈现为交互选项
• 概述外部依赖（不深入追踪）
• 用户导航至终点或选择停止
• 以 ASCII 流程图格式显示路径历史
• 提供 Mermaid 流程图作为输出选项（追踪完成时）
• 收集并展示关键见解
• 可恢复追踪状态（用户选择保存时） </success_criteria>

## 范围

将会：

• 追踪应用代码并完整显示源代码
• 使用思考标记解释每个步骤
• 将条件分支呈现为交互选项
• 在外部依赖的边界处进行概述
• 保存追踪状态以便恢复

不会：

• 深入追踪 node_modules 或外部库
• 执行或运行代码（仅进行只读分析）
• 修改任何源文件
• 对运行时值作出假设（呈现所有分支）