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 不会重试。

安全上线门禁

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