chore: add github copilot instructions

Change-Id: I4eb3feb511a0ef3b149b0e11c143f92359e0dcbc
Co-developed-by: Cursor <noreply@cursor.com>

Author: ralf0131

copilot-instructions.md

@@ -0,0 +1,253 @@
+# LoongSuite Python 探针代码审查规范
+
+本代码仓库是基于 OpenTelemetry 针对 Python 应用进行可观测数据采集的探针。请根据以下原则 Review 代码，并给出修改建议。
+
+---
+
+## 1. 优先使用框架扩展机制
+
+埋点时请尽可能使用框架自带的扩展机制，比如 ASGI 的 middleware 机制。
+
+**避免**：使用 monkey patch 去 patch 某个具体的方法，因为这个方法可能在某个版本存在，在下一个版本就不存在了。
+
+---
+
+## 2. 避免引入三方依赖
+
+* 原则上不要引入三方的依赖库，需要用拷贝源码的方式 shadow 到项目中，但 requests 库例外。
+* 尽量复用已有的依赖，例如假如依赖 httpx 可以改为依赖 aiohttp，因为 aiohttp 是已有的依赖，而 httpx 需要新增
+
+---
+
+## 3. 保留业务语义
+
+埋点逻辑需要保留用户的业务语义。
+
+**例如**：在某个地方原本用户要抛出一个异常，探针就不可以吞掉这个异常，必须确保异常能够正常抛出。
+
+---
+
+## 4. 性能要求
+
+埋点的逻辑需要足够轻量，避免占用用户过多的 CPU。
+
+**禁止**：
+- `deepcopy` 操作
+- 流量链路禁止使用 info 及以上级别，建议使用 `logger.debug` 级别，仅在开启 DEBUG 模式时输出。原因是频繁打日志会占用用户过多的 CPU 和 I/O 资源。
+
+---
+
+## 5. 资源泄漏检查
+
+需要注意潜在的资源泄漏情况，包括但不限于以下几种：
+
+### 5.1 循环引用 + 不可回收对象（含 `__del__`）
+
+**问题**：引用计数无法处理循环引用，Python 会依靠循环垃圾回收器（gc）来清理。
+**风险点**：如果循环引用中的对象定义了 `__del__` 方法，Python 2 或早期版本可能无法自动回收（Python 3.4+ 已改进，但仍需注意）。
+**建议**：避免在可能产生循环引用的对象中定义 `__del__`；或显式断开引用。
+
+### 5.2 全局变量或模块级缓存无限增长
+
+**问题**：全局字典、列表、缓存等在程序生命周期内不会被释放。
+
+**典型场景**：
+- 手动实现的缓存未设置淘汰策略（如 LRU）
+- 使用 `functools.lru_cache` 装饰长期运行的函数，但未限制大小
+
+**建议**：使用 `functools.lru_cache(maxsize=...)` 或定期清理缓存。
+
+### 5.3 闭包引用外部变量导致对象无法释放
+
+**问题**：闭包可能无意中持有了大对象的引用。
+**建议**：在闭包中显式 `del` 不需要的变量，或重构避免捕获大对象。
+
+### 5.4 第三方 C 扩展模块的内存管理错误
+
+**问题**：C 扩展（如某些 numpy、pytorch、opencv 插件）若未正确释放内存，Python 的 gc 无法干预。
+
+**表现**：`tracemalloc` 或 `pympler` 无法追踪到泄漏，但系统内存持续增长。
+
+**建议**：
+- 检查 C 扩展文档或更新版本
+- 使用 `objgraph`、`memory_profiler` 或系统工具（如 valgrind）辅助诊断
+
+### 5.5 未关闭的资源（文件、连接、线程等）
+
+虽然严格来说不一定是"内存泄漏"，但未关闭的资源会持有内存或系统句柄。
+
+**示例**：
+
+```python
+f = open('huge_file.txt')
+# 忘记 f.close()，文件句柄和缓冲区内存可能长期占用
+```
+
+**建议**：始终使用 `with` 语句管理资源。
+
+### 5.6 异常捕获中保留 traceback
+
+**问题**：`traceback` 对象会持有栈帧，栈帧又引用局部变量，导致整个作用域的对象无法释放。
+
+**示例**：
+
+```python
+import sys
+
+exc_info = None
+try:
+    raise ValueError("oops")
+except Exception as e:
+    exc_info = sys.exc_info()  # 包含 traceback
+# exc_info 持有栈帧 → 持有所有局部变量
+```
+
+**建议**：避免长期保存 `exc_info`，使用后设为 `None`；或使用 `traceback.format_exc()` 代替。
+
+---
+
+## 6. 线程和定时任务限制
+
+**禁止**：创建新的线程以及定时任务。
+
+如果一定要创建，需要严格评估对应的资源开销。
+
+---
+
+## 7. 高基数属性检查
+
+检查指标中的各个属性是否有可能是高基数的，高基数的属性容易造成发散问题。
+
+**特别注意以下属性**：
+- `endpoint`
+- `destId`
+- `rpc`
+
+---
+
+## 8. 插件埋点范围
+
+请检查插件中是否只对这个插件本身的一些类进行埋点。
+**禁止**：对插件依赖的类进行埋点。
+**例如**：CrewAI 依赖了 litellm 框架，在 CrewAI 的埋点里面就不要对 litellm 相关的类进行埋点操作。
+
+---
+
+## 9. 异常相关
+
+建议统一使用 raise 来保留完整的异常堆栈，使用 raise e 会丢失原始堆栈信息。
+
+---
+
+## 10. 线程安全
+
+### 10.1 单例模式必须使用线程锁保护
+**问题**：在并发场景下，不加锁的单例检查可能会创建多个实例。
+
+### 10.2 全局变量读写需要注意线程安全
+
+多线程环境下修改全局变量可能导致竞态条件，建议：
+- 使用线程锁保护读写操作
+- 或将配置封装到单例类中
+
+---
+
+## 11. 导入语句规范
+
+### 11.1 导入顺序
+
+按照 PEP 8 规范，导入语句应按以下顺序排列：
+1. 标准库导入
+2. 第三方库导入
+3. 本地导入
+
+各组之间用空行分隔。
+
+### 11.2 避免重复导入
+
+同一个模块只应导入一次，检查文件中是否存在重复的 import 语句。
+
+### 11.3 延迟导入
+
+对于可能不存在的库（如用户未安装的框架），建议使用延迟导入或 try-except 方式，避免在模块级别直接导入可能不存在的模块，这会导致整个模块加载失败。
+
+---
+
+## 12. 异常处理规范
+
+### 12.1 避免捕获过宽的异常
+**禁止**：使用 `except BaseException`，这会捕获 `KeyboardInterrupt` 和 `SystemExit`。
+**建议**：使用 `except Exception`。
+
+### 12.2 使用 logger 而非 print
+
+---
+
+## 13. Python 版本兼容性
+
+* 避免使用 Python 3.8 以上才支持的语法
+
+---
+
+## 14. 代码格式规范
+
+* 文件末尾换行符：根据 PEP 8 规范，所有 Python 文件末尾应该有一个换行符。
+* 顶级函数和类定义之间应有**两个空行**。
+* 等号两侧应有空格
+* 枚举命名风格一致性，符合之前命名的习惯
+* 变量命名需要比较有意义，不要有一些很简单的字符
+
+---
+
+## 15. 单测测试覆盖要求
+
+* 新增的功能模块应该有对应的单元测试覆盖，特别是：
+  - 核心业务逻辑
+  - 边界情况处理
+  - 异常情况处理
+* 单元测试需要验证到响应的功能修改，例如新增一个插件的单元测试需要包含完成 trace 验证，metrics 验证，并且测试用例尽量真实，不能有太多的 mock 测试。
+
+---
+
+## 16. 字典和缓存的内存管理
+
+### 16.1 防止字典无限增长
+
+**建议**：
+1. 添加最大容量限制
+2. 添加定期清理机制（如基于时间的过期）
+3. 使用 `WeakValueDictionary` 允许 GC 自动回收
+
+---
+
+## 17. 拼写检查
+
+* 检查是否存在拼写错误
+
+---
+
+## 18. 方法存在性验证
+
+* 在重构代码后，请确保调用的方法确实存在。常见问题是重构后方法名变更或被移除，导致运行时 `AttributeError`。
+
+---
+
+## 19. 插件埋点对称性
+
+* 在插件的 uninstrument 的实现中，要保持 instrument 实现的对称性，例如在 instrument 中申请的资源，在 uninstrument 中释放
+* 在 instrument 中实现的逻辑，在 uninstrument 方法中进行倒序的清理。
+
+---
+
+## 20. 注释相关
+
+* 关键的方法，建议给出一些 input/output 的示例，提升代码可读性
+* 避免引入无意义的注释，例如一些开发过程中的注释，忘记删除
+* 有些代码被注释掉，这种情况建议直接删除
+
+---
+
+## 21. PR 规范
+
+* PR 的标题需要符合 conventional commits 规范
+* PR 中需要关联工作项