代码审查器

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

工作流程

步骤 1:确定要查看的包 如果上下文中尚未明确,请询问用户要查看哪个仪器 该包位于 java/instrumentation/openinference-instrumentation-<name>/ 读取仪器源、build.gradle 和 src/test/ 目录 步骤 2:使用已检测的库源作为基本事实

第 1 部分:Gradle 设置

读取乐器的build.gradle和根java/build.gradle。检测库必须是 compileOnly(不是 implementation) — 高 openinference-instrumentation 必须是 api 版本常量应该位于根 ext 块中,而不是硬编码 — 中模块必须位于 java/settings.gradle — 如果丢失则至关重要

详尽的属性断言

这是最重要的测试模式。测试必须验证所有跨度属性,而不是抽查少数属性。删除并验证模式可以捕获意外添加和静默删除:缺少空值检查 - 高。

其他所需的测试覆盖率

错误处理:异常 -> span 有 StatusCode.ERROR + 记录的异常 — 高上下文属性传播:session_id、user_id、元数据、标签 TraceConfig 屏蔽:验证 hideInputMessages 等实际上抑制属性 完全丢失测试文件 — 严重

第 3 节:OpenInference 语义约定

请阅读 SemanticConventions.java 了解完整的属性目录: java/openinference-semantic-conventions/src/main/java/com/arize/semconv/trace/SemanticConventions.java 另请阅读 spec/(semantic_conventions.md、traces.md、llm_spans.md、embedding_spans.md、tool_calling.md)下的规范文件以了解预期行为。对于正在审查的库类型,验证仪器设置所有适用的

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@Arize-ai · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Java Code Reviewer for OpenInference Instrumentors

Review a Java OpenInference instrumentation package against the project's established
patterns and conventions. Report findings with file paths and line numbers, organized
by severity (Critical / High / Medium / Low).

## Workflow

**Step 1: Identify the package to review**
- Ask the user which instrumentor to review if not already clear from context
- The package lives under `java/instrumentation/openinference-instrumentation-<name>/`
- Read the instrumentor source, `build.gradle`, and `src/test/` directory

**Step 2: Use the instrumented library source as ground truth**

Before flagging any finding, verify it against the actual library code. Do NOT assume
how the instrumented library works — read it. Do NOT present findings without having
read the library source first.

- Find the library version from `java/build.gradle` `ext` block
- Check `~/.gradle/caches/modules-2/files-2.1/` for cached sources
- If not cached, download the sources jar from Maven Central (`repo1.maven.org`).
  Some libraries split across multiple artifacts — check `build.gradle` dependency
  declarations and fetch all relevant ones.
- If you cannot obtain the source through any means, explicitly tell the user you
  were unable to verify against the library source before presenting findings.
- Calibrate severity by what the library actually does: a bug on a common code path is
  High/Critical; an edge case for a type that can't appear at runtime is Low

**Step 3: Run all review sections below**

**Step 4: Present findings** in a severity table, list what's working well, then ask
the user: fix issues, run tests (`./gradlew :instrumentation:...:test`), or done.

---

## Section 1: Gradle Setup

Read the instrumentor's `build.gradle` and the root `java/build.gradle`.

- Instrumented library must be `compileOnly` (not `implementation`) — **High**
- `openinference-instrumentation` must be `api`
- Version constants should be in root `ext` block, not hardcoded — **Medium**
- Module must be in `java/settings.gradle` — **Critical** if missing
- Run `cd java && ./gradlew spotlessCheck` (Palantir Java Format)

---

## Section 2: Testing Patterns

### Exhaustive attribute assertions

This is the most important testing pattern. Tests must verify ALL span attributes, not
spot-check a few. The remove-and-verify pattern catches both unexpected additions and
silent removals:

```java
Map<String, Object> attributes = new HashMap<>();
span.getAttributes().forEach((key, value) -> attributes.put(key.getKey(), value));

assertThat(attributes.remove("openinference.span.kind")).isEqualTo("LLM");
assertThat(attributes.remove("llm.model_name")).isEqualTo("gpt-4");
// ... remove and assert all remaining attributes ...
assertThat(attributes).isEmpty();  // Nothing unexpected left
```

Missing emptiness check — **High**.

### Other required test coverage

- Error handling: exception -> span has `StatusCode.ERROR` + recorded exception — **High**
- Context attribute propagation: session_id, user_id, metadata, tags
- TraceConfig masking: verify `hideInputMessages` etc. actually suppress attributes
- Missing test files entirely — **Critical**

---

## Section 3: OpenInference Semantic Conventions

Read `SemanticConventions.java` for the full attribute catalog:
`java/openinference-semantic-conventions/src/main/java/com/arize/semconv/trace/SemanticConventions.java`

Also read the spec files under `spec/` (`semantic_conventions.md`, `traces.md`,
`llm_spans.md`, `embedding_spans.md`, `tool_calling.md`) for expected behavior.

For the library type being reviewed, verify the instrumentor sets all applicable
attributes. Key checks:

- Every span needs `OPENINFERENCE_SPAN_KIND`, `INPUT_VALUE` + `INPUT_MIME_TYPE`,
  `OUTPUT_VALUE` + `OUTPUT_MIME_TYPE`. Missing MIME type when value is set — **High**
- All attributes should use constants from `SemanticConventions`, not hardcoded strings — **Medium**
- Read `TraceConfig.java` for the full list of hide flags; verify each is respected
  where applicable — **Medium** if missing

---

## Section 4: Span Lifecycle and Hierarchy

- `span.end()` must ALWAYS be called — **Critical** if missing
- `Scope` from `context.makeCurrent()` must be closed (try-with-resources) — **High**
- For multi-span instrumentors: verify parent-child nesting and shared `traceId`
- The instrumentor should use `OITracer` (not raw `Tracer`) to get TraceConfig support

---

## Presenting Results

Organize findings into a table:

| Severity | Section | Finding | Location |
|----------|---------|---------|----------|
| Critical | 4 | span.end() not called in error path | `SomeListener.java:142` |
| High | 2 | Tests don't verify all span attributes | `SomeTest.java:85` |
| ... | ... | ... | ... |

Then list what's working well — positive findings help the user understand what doesn't
need to change.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。