netra-best-practices

Netra 最佳实践

将此技能用作端到端指南，帮助你使用 Netra 集成、运行和改进 AI 系统。

第 1 步 — 检测项目语言

在执行任何操作之前，先确定项目使用的是 Python 还是 TypeScript/JavaScript。按以下顺序检查项目根目录：

指示文件	语言
pyproject.toml、setup.py、requirements.txt、Pipfile	Python
package.json、tsconfig.json、bun.lockb	TypeScript / JavaScript

如果两者都存在（单体仓库），请询问用户正在使用哪个子项目。如果两者都未找到，请询问用户。

从此处开始，只使用与检测到的语言对应的参考资料。切勿混用 Python 和 TypeScript 模式。

第 2 步 — 安装

安装 netra-sdk 前，先检测包管理器。按优先级顺序检查：

优先级	指示文件	命令
1	uv.lock	uv add netra-sdk
2	poetry.lock	poetry add netra-sdk
3	pyproject.toml（不存在上述锁定文件）	pip install netra-sdk
4	requirements.txt（不存在上述 Python 指示文件）	pip install netra-sdk
5	yarn.lock	yarn add netra-sdk
6	pnpm-lock.yaml	pnpm add netra-sdk
7	package-lock.json	npm install netra-sdk
8	bun.lockb	bun add netra-sdk
9	未找到	继续前请询问用户

不要运行多个安装命令，也不要全局安装。

第 3 步 — 加载正确的参考资料

根据检测到的语言和用户的使用场景，阅读相应的参考文件：

Python 参考资料（位于 references/python/ 下）

使用场景	参考文件
为大模型应用添加监测	python/instrumentation.md
运行评估 / 测试套件	python/evaluation.md
运行多轮模拟	python/simulation.md
自定义指标（计数器、直方图、仪表）	python/custom-metrics.md

TypeScript 参考资料（位于 references/typescript/ 下）

使用场景	参考文件
为大模型应用添加监测	typescript/instrumentation.md
运行评估 / 测试套件	typescript/evaluation.md
运行多轮模拟	typescript/simulation.md
自定义指标（目前不支持 TS）	typescript/custom-metrics.md

第 4 步 — 防幻觉规则

生成 Netra 代码时，请严格遵守以下规则：

1. 绝不要使用 Netra 官方文档中未列出的枚举值。不要猜测。

2. 绝不要混用 Python 和 TypeScript 的约定。具体来说：

   • Python 使用 snake_case 参数（as_type、module_name、app_name）
   • TypeScript 使用 camelCase 参数（asType、moduleName、appName）
   • Python 工具集：{InstrumentSet.OPENAI}（普通集合字面量）
   • TypeScript 工具集：new Set([NetraInstruments.OPENAI])（Set 构造函数）

3. 遵守生命周期差异：

   • Python：Netra.init(...) 是同步的
   • TypeScript：await Netra.init(...) 是异步的——务必使用 await
   • Python：with Netra.start_span(...) as span: 会自动关闭
   • TypeScript：必须在 finally 中手动调用 span.end()

4. 不确定某个 API 时，请遵循下面的文档获取流程，不要猜测。

第 5 步 — 获取文档的备用流程

如果参考文件未涵盖某个用例：

1. 获取文档索引：https://docs.getnetra.ai/llms.txt
2. 从索引中找到相关文档页面。
3. 获取该页面以查看详细指南。

反馈

如果用户对结果不满意，请让他们在 https://github.com/KeyValueSoftwareSystems/netra-skills/issues/new 提交问题。