---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, engine, evaluation, security]
topic: LangSmith Engine 问题发现、修复、评估闭环与安全边界
sources:
  - "https://docs.langchain.com/langsmith/engine"
  - "https://docs.langchain.com/langsmith/engine-github"
  - "https://docs.langchain.com/langsmith/engine-issue-categories"
  - "https://docs.langchain.com/langsmith/engine-overview"
  - "https://docs.langchain.com/langsmith/engine-security"
  - "https://docs.langchain.com/langsmith/engine-self-hosted"
  - "https://docs.langchain.com/langsmith/engine-webhooks"
last_verified: 2026-08-11
---

# LangSmith Engine 闭环修复与安全

## 工作闭环

Engine 每约 6 小时扫描已连接的生产 Trace，聚类重复问题并排序：发现 → 结合 Trace/源码诊断 → 提议修复/PR → 生成 Evaluator 与 ground-truth Dataset example → 关闭后持续监控，复发则重开。

它是 advisory 系统，不会自动把代码推到生产。Branch protection、人工 Review、测试和发布门禁仍是最终控制面。

## 问题分类

16 类包括 Agent looping、context explosion、failed error recovery、feature gap、flawed plan、guardrail bypass、hallucination、incorrect tool args、missing capability awareness、PII leak、response truncation、silent tool error、system prompt drift、task evasion、tracing quality、wrong tool。

分类是诊断起点，不是事实标签。误分类可 Ignore 并给理由；修复前要回到具体 Trace、工具返回与用户意图确认根因。

## 启用与费用

Organization Admin 先为 Workspace 启用 Engine，成员再为具体 tracing project 配置。Engine 以 LCU 计费，工作量取决于 Trace 数量、复杂度、问题与修复内容；应同时设置 Organization 与 Project spend limit，并监控异常扫描量。关闭 Organization 开关会停止后续自动运行与计费，但不等于删除已生成 Issue/PR/Dataset。

## GitHub 权限

Cloud 使用 LangChain-managed GitHub App；Self-hosted 必须创建自己的 GitHub App。只授权 Engine 要分析的 Repository：读源码、创建 PR 所需最小写权限，禁止 “All repositories”。Organization 安装可能需 owner 批准。

Self-hosted GitHub App 的 callback、App ID、private key 与 webhook secret 进入 Secret Manager/Helm Secret。Webhook secret 至少 32 bytes、定期轮换；Private key 不可写入 values 或日志。

## 数据边界

Cloud Engine 读取 Workspace 中已存在的 Trace/Prompt/Evaluator 与已授权 GitHub 源码。源码在隔离 Sandbox 中按分析运行处理后丢弃；推理只发送任务所需内容给零数据保留模型 provider。Engine 不用客户数据训练。

但 ZDR 不等于“内容不离开环境”：Trace 可能含 user message、tool output 和 PII，会被发送给模型 subprocessor。必须在 Trace 进入 LangSmith 前做 client-side masking，并限制 Engine Project 范围。

Self-hosted Engine 需要 chart 0.16.0+ 与 entitlement。编排、Trace/源码读取在客户 VPC 内，但诊断推理依赖 LangSmith Intelligence（LSI）ZDR 服务，当前文档列 AWS US、GCP US 可用，其他区域规划中；air-gapped 环境不能使用。上线前做数据出境、subprocessor、region 与 DPA 审查。

## Webhook

Engine 在 `issue.created`、`issue.trace.added`、`issue.agent_run.failed` 等事件 POST。最长 20 秒，transport、408/425/429/5xx 最多重试 3 次，payload 重试字节相同且 event `id` 不变。

- 用 `X-LangSmith-Signature` 验签，支持 signing secret 滚动；
- 先持久化 event ID 再异步处理，按 ID 去重；
- 自定义 header 是辅助，不替代签名；
- 过滤最低 severity 与 event type，避免告警风暴；
- 返回 2xx 后再做慢操作，永久 4xx 不会重试。

## 安全上线门禁

1. 先在脱敏的低风险 Project shadow 运行，评估误报、LCU 与 PR 质量。
2. GitHub App 仅授权选定 Repository，禁止 direct push，所有 PR 走 CODEOWNERS/CI。
3. Evaluator 和 Dataset example 也要人工检查，防止把错误诊断固化为回归标准。
4. Trace masking、项目 retention 与 Engine 数据路径经过隐私/法务评审。
5. Webhook 验签、幂等、重放和 secret rotation 做端到端测试。
6. Self-hosted 明确 LSI 出站、区域、ZDR 与故障降级；LSI 不可用时不影响核心 Agent 服务。