# https://github.com/gigaverse-app/langsmith-cli 项目说明书

生成时间：2026-07-27 01:58:07 UTC

## 目录

- [项目概述与安装指南](#page-1)
- [命令参考与功能详解](#page-2)
- [系统架构与实现细节](#page-3)
- [AI Agent 集成、Skill 与发布运维](#page-4)

<a id='page-1'></a>

## 项目概述与安装指南

### 相关页面

相关主题：[命令参考与功能详解](#page-2), [AI Agent 集成、Skill 与发布运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/README.md)
- [scripts/install.sh](https://github.com/gigaverse-app/langsmith-cli/blob/main/scripts/install.sh)
- [scripts/install.ps1](https://github.com/gigaverse-app/langsmith-cli/blob/main/scripts/install.ps1)
- [scripts/install.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/scripts/install.py)
- [.env.example](https://github.com/gigaverse-app/langsmith-cli/blob/main/.env.example)
- [.claude-plugin/plugin.json](https://github.com/gigaverse-app/langsmith-cli/blob/main/.claude-plugin/plugin.json)
</details>

# 项目概述与安装指南

## 项目概述

`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]()）。

| 平台 | 推荐脚本 | 入口命令 |
| --- | --- | --- |
| macOS / Linux | `install.sh` | `langsmith` |
| Windows | `install.ps1` | `langsmith.exe` |
| CI / 容器 | `install.py` | `langsmith` |

## 环境配置

安装完成后，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]()）。

---

<a id='page-2'></a>

## 命令参考与功能详解

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [系统架构与实现细节](#page-3), [AI Agent 集成、Skill 与发布运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/langsmith_cli/main.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/main.py)
- [src/langsmith_cli/cli.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/cli.py)
- [src/langsmith_cli/commands/runs/_group.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/_group.py)
- [src/langsmith_cli/commands/runs/list_cmd.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/list_cmd.py)
- [src/langsmith_cli/commands/runs/get_cmd.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/get_cmd.py)
- [src/langsmith_cli/commands/runs/search_cmd.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/search_cmd.py)
- [src/langsmith_cli/commands/runs/stats_cmd.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/stats_cmd.py)
- [src/langsmith_cli/commands/runs/export_cmd.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/runs/export_cmd.py)
- [src/langsmith_cli/commands/datasets/__init__.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/datasets/__init__.py)
- [src/langsmith_cli/commands/traces/__init__.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/commands/traces/__init__.py)
</details>

# 命令参考与功能详解

`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` 组内部进一步拆分为多个子命令文件，每个文件对应一个独立的功能：

| 子命令文件 | 对应命令 | 主要职责 |
| --- | --- | --- |
| `list_cmd.py` | `runs list` | 列举项目下的 Run 列表 |
| `get_cmd.py` | `runs get` | 按 ID 获取单个 Run 详情 |
| `search_cmd.py` | `runs search` | 基于过滤条件搜索 Run |
| `stats_cmd.py` | `runs stats` | 输出 Run 的聚合统计信息 |
| `export_cmd.py` | `runs export` | 将 Run 数据导出为本地文件 |

资料来源：[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]()

## 命令调用流程图

```mermaid
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](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.10.3) 资料来源：[v0.10.0 Release](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.10.0)

## 小结

`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]()

---

<a id='page-3'></a>

## 系统架构与实现细节

### 相关页面

相关主题：[命令参考与功能详解](#page-2), [AI Agent 集成、Skill 与发布运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/langsmith_cli/main.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/main.py)
- [src/langsmith_cli/cache.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/cache.py)
- [src/langsmith_cli/field_analysis.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/field_analysis.py)
- [src/langsmith_cli/filtering.py](https://github.com/gigaverse-app/langsmith-cli/filtering.py)
- [src/langsmith_cli/filters.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/filters.py)
- [src/langsmith_cli/output.py](https://github.com/gigaverse-app/langsmith-cli/blob/main/src/langsmith_cli/output.py)
</details>

# 系统架构与实现细节

`langsmith-cli` 是一个面向 LangSmith 平台的命令行工具，提供了 traces、runs、datasets 等实体的查询、过滤、缓存与格式化输出能力。截至 `v0.10.3` 版本（[v0.10.3 Release](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.10.3)），项目已迭代十余次，整体形成了“入口调度 + 业务模块 + 数据格式化”的清晰分层结构。

## 整体架构概览

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

```mermaid
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](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.6.3)、[v0.7.0 Release](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.7.0)、[v0.8.0 Release](https://github.com/gigaverse-app/langsmith-cli/releases/tag/v0.8.0)），主要变更集中在过滤器表达式语法、缓存失效策略与输出格式扩展。模块边界保持稳定，使得新增子命令时无需改动过滤、缓存、输出三层的接口约定。

---

<a id='page-4'></a>

## AI Agent 集成、Skill 与发布运维

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [命令参考与功能详解](#page-2), [系统架构与实现细节](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/langsmith/SKILL.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/SKILL.md)
- [skills/langsmith/docs/reference.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/docs/reference.md)
- [skills/langsmith/docs/examples.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/docs/examples.md)
- [skills/langsmith/references/runs.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/references/runs.md)
- [skills/langsmith/references/datasets.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/references/datasets.md)
- [skills/langsmith/references/examples.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/skills/langsmith/references/examples.md)
- [.github/workflows/release.yml](https://github.com/gigaverse-app/langsmith-cli/blob/main/.github/workflows/release.yml)
- [pyproject.toml](https://github.com/gigaverse-app/langsmith-cli/blob/main/pyproject.toml)
- [README.md](https://github.com/gigaverse-app/langsmith-cli/blob/main/README.md)
</details>

# AI Agent 集成、Skill 与发布运维

本页面向 AI Agent 开发者、平台集成工程师与发布运维人员，介绍 `langsmith-cli` 如何以「Skill」形式被 AI Agent 调用、Skill 的内部结构与文档体系，以及仓库的版本发布与运维流程。

## 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]()

加载流程如下图所示：

```mermaid
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/` 目录按领域对象划分：

| 文件 | 覆盖对象 | 典型用途 |
|------|----------|----------|
| runs.md | Trace / Run | 检索、过滤、导出运行轨迹 |
| datasets.md | Dataset | 数据集管理与版本控制 |
| examples.md | Example | 样例的增删改查与批量操作 |

资料来源：[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]()

---

通过上述「Skill + 参考文档 + 自动化发布」三层结构，`langsmith-cli` 既能被 AI Agent 安全调用，也保留了传统 CLI 工具的可运维性，是面向 LLM 应用场景下「工具可观测、可版本化」的典型实现。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: gigaverse-app/langsmith-cli; human_manual_source: deepwiki_human_wiki -->