项目概述

langsmith-cli 是一个面向 LangSmith 平台的命令行工具，主要用于在本地与 LangSmith 服务进行交互，支持追踪数据（trace）的拉取、评估（evaluation）任务的运行、提示（prompt）模板的同步，以及与 Claude 桌面/插件生态的集成。当前最新版本为 v0.10.3，项目经历了从 v0.6.3 到 v0.10.3 的快速迭代（资料来源：README.md:1-20），每个次版本都会带来新的命令或对现有子命令的重构。

该项目核心定位是：

• 为开发者提供脚本化的 LangSmith 访问能力，避免在浏览器中反复切换；
• 支持一键安装与跨平台部署，覆盖 macOS、Linux 与 Windows；
• 通过 .claude-plugin/plugin.json 注册为 Claude 的可识别插件，从而在 Claude 客户端中暴露相关命令（资料来源：.claude-plugin/plugin.json:1-10）。

安装方法

项目在 scripts/ 目录下同时提供了三种安装脚本，分别针对不同的操作系统和 Python 环境偏好。

Unix / macOS（bash）

install.sh 是 POSIX 兼容的一键安装脚本，适合 macOS 与 Linux 用户。脚本会执行以下步骤：

1. 检查或引导用户安装 Python 3.10+；
2. 创建虚拟环境（.venv）并激活；
3. 以可编辑模式（pip install -e .）安装本仓库代码；
4. 将可执行入口链接到 ~/.local/bin 下的 langsmith 命令（资料来源：scripts/install.sh:1-40）。

Windows（PowerShell）

install.ps1 提供了 PowerShell 等价的安装流程，适配 Windows 10/11 默认终端：

1. 通过 py -3 启动 Python；
2. 在当前目录创建并激活 .venv；
3. 安装依赖并将入口脚本放入 Scripts\ 目录（资料来源：scripts/install.ps1:1-40）。

跨平台（Python 直装）

install.py 是一个与平台无关的纯 Python 安装器，推荐在 CI 环境或不便运行 shell 脚本的容器中使用。它会自动探测操作系统并调用对应逻辑，最后将依赖写入 pyproject.toml 中声明的版本约束（资料来源：scripts/install.py:1-40）。

环境配置

安装完成后，CLI 需要一组环境变量才能与 LangSmith 后端通信。项目根目录提供了 .env.example 模板（资料来源：.env.example:1-10)，关键变量包括：

• LANGSMITH_API_KEY：LangSmith 项目的 API Key，必填；
• LANGSMITH_ENDPOINT：可选自定义端点，默认指向官方服务；
• LANGSMITH_PROJECT：指定默认项目 slug，用于在多条 trace 之间隔离数据；
• LANGSMITH_TRACING：布尔值，控制是否开启客户端自动上报。

用户可通过 cp .env.example .env 后填入真实凭据，CLI 在启动时会通过 dotenv 自动加载该文件。

Claude 插件集成

为了让 langsmith-cli 能在 Claude 桌面或 CLI 客户端中被识别，项目维护了一份符合 Claude 插件规范的清单文件。该文件声明了插件名称、版本、入口脚本以及所暴露的命令集合（资料来源：.claude-plugin/plugin.json:1-10）。当用户将该仓库克隆到 Claude 的插件目录后，重启客户端即可在命令面板中看到 langsmith 相关指令，从而把 LangSmith 操作纳入 AI 辅助的开发闭环。

版本演进

从社区证据可见，项目在 v0.6.x ~ v0.10.x 区间内保持高频发布（v0.6.3、v0.7.0、v0.8.0、v0.8.1、v0.9.0、v0.9.1、v0.10.0、v0.10.1、v0.10.2、v0.10.3）。这种节奏表明团队持续对命令表面与认证流程进行打磨，建议用户在升级前阅读对应 Release Notes，关注是否引入了破坏性变更（资料来源：README.md:1-20）。

langsmith-cli 是一个面向 LangSmith 平台的命令行工具，提供对追踪（runs/traces）、数据集（datasets）等 LangSmith 资源的查询、获取、导出与统计能力。其命令体系基于 Click 框架构建，主入口位于 main.py，通过分组（runs、datasets、traces）组织子命令。资料来源：src/langsmith_cli/main.py:1-80

整体架构与命令分组

CLI 的根入口在 main.py 中注册各命令组，其中最核心的是 runs 组，它封装了对 LangSmith Run 资源的所有操作。资料来源：src/langsmith_cli/main.py:30-60 资料来源：src/langsmith_cli/commands/runs/_group.py:1-40

runs 组内部进一步拆分为多个子命令文件，每个文件对应一个独立的功能：

资料来源：src/langsmith_cli/commands/runs/_group.py:20-80

`runs` 子命令详解

`runs list`：列举运行记录

list_cmd.py 实现了 runs list 命令，用于分页列举某个 LangSmith 项目中的 Run。其典型参数包括项目名称、Run 类型过滤、时间范围以及分页大小。命令会调用 LangSmith SDK 的列表接口，并将结果以表格或 JSON 形式输出。资料来源：src/langsmith_cli/commands/runs/list_cmd.py:1-60

`runs get`：获取单个 Run

get_cmd.py 提供 runs get <run_id> 命令，用于根据 Run 的唯一标识符拉取其完整信息，包括输入、输出、元数据、耗时和嵌套的子 Run 树。该命令在调试具体一次追踪时尤其有用。资料来源：src/langsmith_cli/commands/runs/get_cmd.py:1-50

`runs search`：条件搜索

search_cmd.py 实现了基于过滤表达式的 Run 搜索能力，允许用户指定状态（成功/失败）、标签、时间区间等条件，返回匹配的 Run 集合。资料来源：src/langsmith_cli/commands/runs/search_cmd.py:1-60

`runs stats`：聚合统计

stats_cmd.py 用于输出指定项目或过滤范围内的 Run 聚合指标，如总条数、平均耗时、错误率等，便于快速评估运行健康度。资料来源：src/langsmith_cli/commands/runs/stats_cmd.py:1-50

`runs export`：导出数据

export_cmd.py 将选中的 Run 数据导出为本地文件（通常为 JSONL），方便后续离线分析或归档。资料来源：src/langsmith_cli/commands/runs/export_cmd.py:1-50

其他命令组

除了 runs 组之外，CLI 还提供 datasets 和 traces 命令组，分别用于管理 LangSmith 数据集以及对追踪进行高层操作。资料来源：src/langsmith_cli/commands/datasets/__init__.py:1-30 资料来源：src/langsmith_cli/commands/traces/__init__.py:1-30

命令调用流程图

flowchart TD
    A["用户执行 langsmith-cli"] --> B["main.py 解析根命令"]
    B --> C{"选择命令组"}
    C -->|runs| D["commands/runs/_group.py 注册子命令"]
    D --> E1["list_cmd.py<br/>runs list"]
    D --> E2["get_cmd.py<br/>runs get"]
    D --> E3["search_cmd.py<br/>runs search"]
    D --> E4["stats_cmd.py<br/>runs stats"]
    D --> E5["export_cmd.py<br/>runs export"]
    C -->|datasets| F["datasets 命令组"]
    C -->|traces| G["traces 命令组"]
    E1 --> H["LangSmith SDK"]
    E2 --> H
    E3 --> H
    E4 --> H
    E5 --> H

版本演进与社区关注点

从社区发布记录来看，langsmith-cli 在 v0.6.3 至 v0.10.3 期间持续迭代，v0.8.0、v0.9.0、v0.10.0 等里程碑版本引入了多项功能增强与缺陷修复，表明该工具的命令体系正处于活跃演进阶段。用户在升级时应关注 runs 子命令参数与默认行为的变化。资料来源：v0.10.3 Release 资料来源：v0.10.0 Release

小结

langsmith-cli 通过 Click 子命令组将 LangSmith 平台能力映射为清晰的 CLI 接口：runs 组覆盖列举、查询、搜索、统计与导出五大场景，datasets 与 traces 组补充资源管理与高层追踪操作。其模块化设计使得新增命令只需在 commands/<group>/ 下添加独立文件并在 _group.py 中注册即可，具备良好的可扩展性。资料来源：src/langsmith_cli/cli.py:1-60 资料来源：src/langsmith_cli/commands/runs/_group.py:60-100

整体架构概览

CLI 应用从 main.py 启动，解析命令行参数后按子命令路由到对应业务逻辑。各业务模块之间通过明确定义的函数接口协作：filtering.py 与 filters.py 负责表达式解析与过滤；cache.py 提供本地持久化加速；output.py 统一输出格式；field_analysis.py 用于动态字段探测。模块间依赖呈单向流动，避免循环耦合。

flowchart TD
    A[main.py<br/>入口与参数解析] --> B[filters.py<br/>过滤器定义]
    A --> C[filtering.py<br/>过滤表达式求值]
    A --> D[cache.py<br/>本地缓存]
    A --> E[field_analysis.py<br/>字段分析]
    A --> F[output.py<br/>格式化输出]
    B --> C
    D --> A
    E --> F
    C --> F

入口与命令调度

main.py 是 CLI 的总入口，负责构建 argparse 子命令树并执行全局初始化（如环境变量加载、日志配置）。所有对外命令都以函数形式注册到子命令分发器，命令行参数与运行时配置在此层完成转换。资料来源：src/langsmith_cli/main.py:1-80。

该模块同时承担两项工作：

• 解析 --filter、--limit、--format 等通用选项；
• 调用下层模块拼装完整的数据获取与处理流水线。

过滤系统设计

过滤能力是 CLI 的核心交互手段，分散在 filters.py 与 filtering.py 两个文件中：

• filters.py 定义字段级过滤原语（如等于、包含、范围比较），并提供可组合的过滤算子集合。资料来源：src/langsmith_cli/filters.py:1-60。
• filtering.py 负责把用户传入的 --filter key=value 字符串解析为过滤器实例，并执行求值与短路优化。资料来源：src/langsmith_cli/filtering.py:1-120。

二者通过统一的“过滤器协议”解耦，使新增字段类型时只需扩展 filters.py，无需修改调度层。

缓存层与字段分析

cache.py 实现本地 TTL 缓存，避免重复访问 LangSmith API 时产生不必要的网络往返和速率限制。缓存键通常由查询参数、过滤器和时间范围组合而成。资料来源：src/langsmith_cli/cache.py:1-90。

field_analysis.py 用于对返回的 run / dataset 数据进行字段统计和类型推断，辅助自动补全、默认列选择与字段级校验。其结果通常会被 output.py 复用，决定哪些列被渲染以及如何格式化时间、数值等字段。资料来源：src/langsmith_cli/field_analysis.py:1-70。

输出与格式化

output.py 抽象了多种输出目标（表格、JSON、NDJSON），同时负责列宽自适应、时间戳本地化以及 ANSI 颜色渲染。命令层只需要传入原始数据对象与目标格式，由该模块完成全部呈现细节。资料来源：src/langsmith_cli/output.py:1-110。

该模块在迭代过程中多次重构（参见 v0.8.0 至 v0.10.3 系列发布），以支持新增的 NDJSON 流式输出与多目标导出。

版本演进与架构稳定性

从社区记录可见，自 v0.6.3 起项目持续以小步快跑方式演进（v0.6.3 Release、v0.7.0 Release、v0.8.0 Release），主要变更集中在过滤器表达式语法、缓存失效策略与输出格式扩展。模块边界保持稳定，使得新增子命令时无需改动过滤、缓存、输出三层的接口约定。

1. AI Agent 集成模型

langsmith-cli 并非单纯的命令行工具，它以 Skill 包形式向 AI Agent 暴露能力。仓库根目录下的 skills/langsmith/ 是一个独立的 Skill 单元，可被 Claude Code 等 Agent 运行时直接加载。

1.1 Skill 的加载入口

SKILL.md 是 Skill 的元数据与能力描述文件，定义了：

• Skill 的名称、描述与适用范围；
• Agent 在何种场景下应优先调用该 Skill；
• Skill 所依赖的命令清单与参数约定。

资料来源：skills/langsmith/SKILL.md:1-40

加载流程如下图所示：

flowchart LR
    A[AI Agent 运行时] --> B{识别用户意图}
    B -- LangSmith 相关 --> C[加载 skills/langsmith/SKILL.md]
    C --> D[解析 commands 与参数]
    D --> E[调用 langsmith-cli 子命令]
    E --> F[LangSmith API]
    F --> E
    E --> A

1.2 与 LangSmith 的对接

Skill 调用 langsmith-cli 后，CLI 再通过 HTTP 与 LangSmith 服务交互，覆盖 Runs、Datasets、Examples 等核心对象。references/runs.md、references/datasets.md、references/examples.md 分别描述这些对象的字段语义与查询语义，使 Agent 在生成查询条件时拥有权威依据。

资料来源：skills/langsmith/references/runs.md:1-30、skills/langsmith/references/datasets.md:1-30、skills/langsmith/references/examples.md:1-30

2. Skill 文档体系

Skill 不仅包含可执行命令，还配套了完整的「参考 + 示例」文档，便于 Agent 进行少样本学习与稳健调用。

2.1 参考文档（reference.md）

docs/reference.md 提供 CLI 全局命令清单、参数语义、返回值结构与错误码说明。Agent 在解析用户自然语言请求时，会先在此文件中检索匹配的命令模板，再结合具体 references 子文件补充上下文。

资料来源：skills/langsmith/docs/reference.md:1-60

2.2 示例文档（examples.md）

docs/examples.md 收录典型工作流，例如：

• 按项目查询运行并按耗时排序；
• 批量上传数据集样例；
• 比对两个 Run 的输出差异。

这些示例同时也是对 Agent 的「调用示范」，降低 LLM 幻觉风险。

资料来源：skills/langsmith/docs/examples.md:1-60

2.3 引用资源（references/）

references/ 目录按领域对象划分：

资料来源：skills/langsmith/references/runs.md:1-20、skills/langsmith/references/datasets.md:1-20、skills/langsmith/references/examples.md:1-20

3. 发布与版本管理

langsmith-cli 采用语义化版本（SemVer），当前已发布到 v0.10.3，社区证据显示版本迭代节奏稳定（v0.6.3 → v0.10.3 共十余个版本）。

3.1 项目元数据

pyproject.toml 中定义：

• 项目名称、版本号与 Python 版本约束；
• 入口脚本（console_scripts），决定 langsmith 可执行命令的注入方式；
• 依赖列表，包含 LangSmith SDK 等核心库。

资料来源：pyproject.toml:1-40

3.2 自动化发布工作流

.github/workflows/release.yml 在推送标签（v*.*.*）时自动构建分发包并发布到 PyPI/GitHub Release。其典型步骤包括：

1. 检出代码并配置 Python 环境；
2. 安装构建工具（build、twine）；
3. 执行 python -m build 生成 sdist 与 wheel；
4. 校验产物并上传至包索引。

资料来源：.github/workflows/release.yml:1-50

3.3 升级与兼容性

README 中通常给出升级提示与迁移说明。由于 CLI 同时面向人类用户与 AI Agent，破坏性变更（命令改名、参数语义调整）需要同步更新：

• SKILL.md 中的能力描述；
• docs/reference.md 中的命令清单；
• references/*.md 中的字段映射。

资料来源：README.md:1-40、skills/langsmith/SKILL.md:1-20

4. 运维实践要点

面向生产环境的运维人员，建议关注以下事项：

1. API Key 管理：CLI 通过环境变量读取 LangSmith 凭证，部署到 CI 或 Agent 平台时需使用 Secret 管理，避免硬编码。
2. 速率限制：LangSmith API 存在速率约束，长时间批处理应实现退避重试，相关重试逻辑可在 references/runs.md 与 examples.md 中找到示范。
3. Skill 版本对齐：当 CLI 升级后，Agent 平台应同步刷新加载的 Skill 目录，确保 Agent 拿到的命令描述与最新 CLI 行为一致。
4. 可观测性：发布新版本后，可借助仓库内置的 Runs 查询能力，对接入该 CLI 的 Agent 工作流进行回溯分析。

资料来源：skills/langsmith/docs/reference.md:1-30、skills/langsmith/references/runs.md:1-30

Pitfall Log / 踩坑日志

项目：gigaverse-app/langsmith-cli

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/gigaverse-app/langsmith-cli | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/gigaverse-app/langsmith-cli | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/gigaverse-app/langsmith-cli | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/gigaverse-app/langsmith-cli | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/gigaverse-app/langsmith-cli | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/gigaverse-app/langsmith-cli | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/gigaverse-app/langsmith-cli | release_recency=unknown