code-trace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<essential_principles>

How Code Tracing Works

代码追踪工作原理

This skill traces code execution paths interactively, letting you navigate through the codebase like a debugger stepping through code - but with rich explanations at each step.

本工具以交互式方式追踪代码执行路径，让你像调试器单步执行代码一样浏览代码库，且每一步都配有详细的解释。

Principle 1: Application Boundary

原则1：应用边界

Trace ONLY application code. External dependencies (node_modules, vendor/) receive:

A summary of what they do
Link to official documentation
NOT deep-traced into their internals

Why: External libraries can be 100K+ lines. Tracing into them wastes context and obscures the actual application logic. The goal is understanding YOUR code, not library internals.

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

功能概述
官方文档链接
不深入追踪其内部实现

原因：外部库可能包含超过10万行代码，深入追踪会浪费上下文，掩盖实际的应用逻辑。我们的目标是理解你的代码，而非库的内部细节。

Principle 2: Interactive Navigation

原则2：交互式导航

Every conditional branch becomes a user choice:

Code Pattern	Presentation
`if/else`	"Path A: condition true" vs "Path B: condition false"
`switch`	One choice per case
`try/catch`	"Success path" vs "Error path"
`async/await`	Option to trace into called functions

Why: Linear traces miss important paths. Interactive navigation lets users explore exactly what they're interested in.

每个条件分支都将作为用户可选选项呈现：

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

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

Principle 3: Progressive Explanation

原则3：渐进式解释

Each step includes:

Location: File + line range + function name
Code: Full source (no abbreviation)
What: Brief summary of what the code does
Why: Why this step exists in the flow
Next: What happens next (or choices if branching)

Use thinking markers (🤔🎯⚡📊💡🔐) for clarity.

每一步包含以下内容：

位置：文件 + 行号范围 + 函数名
代码：完整源代码（不缩写）
内容：代码功能的简要概述
原因：该步骤在流程中的存在意义
下一步：后续操作（若存在分支则展示选项）

使用思考标记（🤔🎯⚡📊💡🔐）提升清晰度。

Principle 4: State Persistence

原则4：状态持久化

Trace state is stored in Serena Memory to enable:

Resuming interrupted traces
Backtracking to previous decision points
Saving completed traces for future reference </essential_principles>

追踪状态存储在Serena Memory中，支持：

恢复中断的追踪会话
返回至之前的决策点
保存已完成的追踪记录供后续参考 </essential_principles>

What would you like to trace?

你想要追踪什么？

Trace a request flow - Follow HTTP request from receipt to response
Trace a function call - Follow a specific function through the codebase
Resume previous trace - Continue from where you left off

Please provide additional context:

For request tracing: Which endpoint? (e.g., "POST /api/users")
For function tracing: Which function? (e.g., "validateUser" or "src/utils/auth.ts:checkToken")

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "request", "HTTP", "route", "API", "endpoint", "POST", "GET" | `workflows/trace-request.md` | | 2, "function", "call", specific function name | `workflows/trace-function.md` | | 3, "resume", "continue", "previous" | Read Serena memory for `trace_session_*` |

追踪请求流 - 跟随HTTP请求从接收至响应的完整流程
追踪函数调用 - 追踪特定函数在代码库中的执行路径
恢复之前的追踪 - 从中断处继续追踪

请提供额外上下文：

若追踪请求流：指定哪个端点？（例如："POST /api/users"）
若追踪函数调用：指定哪个函数？（例如："validateUser" 或 "src/utils/auth.ts:checkToken"）

等待用户回复后再继续。 </intake>

<routing> | 回复内容 | 工作流 | |----------|----------| | 1、"request"、"HTTP"、"route"、"API"、"endpoint"、"POST"、"GET" | `workflows/trace-request.md` | | 2、"function"、"call"、具体函数名 | `workflows/trace-function.md` | | 3、"resume"、"continue"、"previous" | 读取Serena内存中的`trace_session_*`记录 |

Before Starting Any Workflow

启动任何工作流之前

Detect Framework: Run
```
scripts/detect-framework.sh
```
to identify:
- Express, Next.js (App/Pages), Fastify, Hono, NestJS, Koa, or generic
Load Framework Patterns: Read
```
references/framework-patterns.md
```
section for detected framework
Prepare Serena: Ensure Serena MCP is available for:
- ```
find_symbol()
```
  - Locate functions/handlers
- ```
find_referencing_symbols()
```
  - Find callers
- ```
get_symbols_overview()
```
  - Map module structure
- ```
write_memory()
```
  /
```
read_memory()
```
  - State persistence

After determining intent and framework, read the appropriate workflow and follow it. </routing>

<reference_index>

检测框架：运行
```
scripts/detect-framework.sh
```
识别框架类型：
- Express、Next.js（App/Pages）、Fastify、Hono、NestJS、Koa或通用型框架
加载框架模式：读取
```
references/framework-patterns.md
```
中对应已检测框架的部分
准备Serena：确保Serena MCP可提供以下功能：
- ```
find_symbol()
```
  - 定位函数/处理器
- ```
find_referencing_symbols()
```
  - 查找调用者
- ```
get_symbols_overview()
```
  - 映射模块结构
- ```
write_memory()
```
  /
```
read_memory()
```
  - 状态持久化

确定用户意图与框架后，读取对应的工作流文档并执行。 </routing>

<reference_index>

References

参考文档

All in

references/

File	Content
framework-patterns.md	Entry point detection and request flow for Express, Next.js, Fastify, etc.
control-flow-types.md	How to present if/switch/try/loops as interactive choices
explanation-style.md	Thinking markers, step format, summary format
</reference_index>

<workflows_index>

所有文档均位于

references/

目录下：

文件	内容
framework-patterns.md	Express、Next.js、Fastify等框架的入口点检测与请求流说明
control-flow-types.md	如何将if/switch/try/循环等转换为交互式选项
explanation-style.md	思考标记、步骤格式、概述格式说明
</reference_index>

<workflows_index>

Workflows

工作流

All in

workflows/

Workflow	Purpose
trace-request.md	Trace HTTP request from entry to response
trace-function.md	Trace a specific function's call chain
</workflows_index>

<scripts_index>

所有工作流均位于

workflows/

目录下：

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

<scripts_index>

Scripts

脚本

Script	Purpose
detect-framework.sh	Auto-detect project framework from package.json

Usage:

bash

./scripts/detect-framework.sh /path/to/project

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

使用方式：

bash

./scripts/detect-framework.sh /path/to/project

Output: express | nextjs-app | nextjs-pages | fastify | hono | nestjs | koa | generic

输出：express | nextjs-app | nextjs-pages | fastify | hono | nestjs | koa | generic

</scripts_index>

<success_criteria>
A successful code trace:
- [ ] Entry point correctly identified and explained
- [ ] Framework detected and appropriate patterns applied
- [ ] At least one branch point presented as interactive choice
- [ ] External dependencies summarized (not deep-traced)
- [ ] User navigated to terminal point OR chose to stop
- [ ] Path history shown in ASCII flowchart format
- [ ] Key insights collected and displayed
- [ ] Trace state available for resume (if user chose to save)
</success_criteria>

<boundaries>

</scripts_index>

<success_criteria>
成功的代码追踪需满足：
- [ ] 正确识别并解释入口点
- [ ] 检测到框架并应用了对应的模式
- [ ] 至少将一个分支点作为交互式选项呈现
- [ ] 对外部依赖进行了概述（未深入追踪）
- [ ] 用户导航至终点或选择停止追踪
- [ ] 以ASCII流程图格式展示路径历史
- [ ] 收集并展示关键见解
- [ ] 追踪状态可恢复（若用户选择保存）
</success_criteria>

<boundaries>

Boundaries

功能边界

Will:

Trace application code with full source display
Explain each step with thinking markers
Present conditional branches as interactive choices
Summarize external dependencies at the boundary
Persist trace state for resume capability

Will Not:

Deep-trace into node_modules or external libraries
Execute or run the code (read-only analysis)
Modify any source files
Make assumptions about runtime values (present all branches)

</boundaries>

支持的操作：

追踪应用代码并展示完整源代码
使用思考标记解释每一步
将条件分支作为交互式选项呈现
在边界处概述外部依赖
持久化追踪状态以支持恢复

不支持的操作：

深入追踪node_modules或外部库的内部实现
执行或运行代码（仅做只读分析）
修改任何源文件
假设运行时的值（展示所有可能分支）

</boundaries>