# fox-agent-framework

**Repository Path**: dongchenglin/fox-agent-framework

## Basic Information

- **Project Name**: fox-agent-framework
- **Description**: Java古法编程第4期：字节码插装与 Java Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fox Agent Framework

基于 Java Agent + ASM 字节码插装的方法耗时统计工具。

在**不修改源码**的情况下，在目标方法的入口和出口自动插入计时逻辑，运行时输出：

```
[Fox-Timing] com.fox.agent.example.BenchmarkTarget.doWork 耗时: 201ms
```

---

## 技术栈

| 组件 | 版本 |
|------|------|
| JDK | 17+ |
| ASM | 9.7 |
| 字节码版本 | 52 (Java 8) |

---

## 项目结构

```
src/main/java/com/fox/agent/
├── FoxAgent.java            # Agent 入口（premain）
├── TimingTransformer.java   # ClassFileTransformer 实现
├── TimingClassVisitor.java  # ClassVisitor：筛选需要插装的方法
└── TimingMethodVisitor.java # AdviceAdapter：在方法出入口插入计时字节码
```

---

## 构建

```bash
mvn clean package
```

构建产物：`target/fox-agent-framework-1.0-SNAPSHOT.jar`

---

## 运行方式

### 方式一：直接运行示例类

```bash
java -javaagent:target/fox-agent-framework-1.0-SNAPSHOT.jar \
     -cp target/fox-agent-framework-1.0-SNAPSHOT.jar \
     com.fox.agent.example.BenchmarkTarget
```

### 方式二：附加到任意 Java 进程

将 `-javaagent:...` 参数加入目标进程的 JVM 启动参数即可。

---

## 插装规则

`TimingClassVisitor` 中当前**严格限制**只插装 `void` 返回方法（`descriptor endsWith ")V"`），原因是非 void 方法在 return 前操作数栈顶有返回值，`AdviceAdapter.onMethodExit()` 会正确处理这种情况（当前版本已使用 `AdviceAdapter`，可解除此限制）。

---

## 核心设计

- **`AdviceAdapter`**：ASM 提供的便捷 `MethodVisitor`，自动处理局部变量分配时机，保证 `onMethodEnter()` / `onMethodExit()` 在所有退出路径（正常返回 + 异常）都被调用。
- **局部变量槽位计算**：`computeParamSlotCount()` 正确处理 `static` 方法（无 `this`）和 `long/double` 占两个槽的情况。
- **`onMethodExit(int opcode)`**：通过 `opcode` 区分正常返回与异常抛出，可扩展为异常时不计时或单独统计。

---

## 许可

MIT License