---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - prompt-hub
  - tags
topic: LangSmith Smith API Prompt 评论、Tags 与 Tag 迁移审计
sources:
  - https://docs.langchain.com/langsmith/smith-api/comments/create-comment
  - https://docs.langchain.com/langsmith/smith-api/comments/create-sub-comment
  - https://docs.langchain.com/langsmith/smith-api/comments/get-comments
  - https://docs.langchain.com/langsmith/smith-api/comments/get-sub-comments
  - https://docs.langchain.com/langsmith/smith-api/comments/like-comment
  - https://docs.langchain.com/langsmith/smith-api/comments/unlike-comment
  - https://docs.langchain.com/langsmith/smith-api/tag-transitions/get-tag-transition-history
  - https://docs.langchain.com/langsmith/smith-api/tags/create-tag
  - https://docs.langchain.com/langsmith/smith-api/tags/delete-tag
  - https://docs.langchain.com/langsmith/smith-api/tags/get-tag
  - https://docs.langchain.com/langsmith/smith-api/tags/get-tags
  - https://docs.langchain.com/langsmith/smith-api/tags/update-tag
last_verified: 2026-08-11
---

# Prompt 评论、Tags 与 Tag 迁移审计

这一组 API 作用于 Prompt Hub repository：评论是协作对话，Tag 是指向某个 prompt commit 的可变别名，Tag transition 是别名指向变更的审计链。Tag 不等于不可变版本；生产调用需要固定 commit hash/ID 或验证 Tag 迁移。

## Comments 和 likes

| 操作 | 方法与路径 |
|---|---|
| 创顶层评论 | `POST /api/v1/comments/{owner}/{repo}` |
| 创子评论 | `POST /api/v1/comments/{owner}/{repo}/{parent_comment_id}` |
| 列顶层 / 子评论 | 两个对应 `GET`，`limit=20, offset=0` |
| Like / Unlike | `POST` / `DELETE .../{parent_comment_id}/like` |

创建 body 只要求 `content`。Comment 响应包含 id、comment_on、parent ID、content、创建/更新时间、评论人、子评论数、like 数和当前用户是否已 like。展示 content 时做 Markdown/HTML 严格消毒、禁止任意 URL scheme 和活动内容；列表页对 owner/repo 与评论身份仍做服务端授权。

Like/Unlike 应按 `(comment_id,user_id)` 幂等，客户端不用本地加减后的瞬时数字作为最终真相；重连后从服务端刷新。OpenAPI 中未覆盖评论更新/删除，产品不应自行拼猜端点。

## Tag CRUD

| 操作 | 方法与路径 | 请求 |
|---|---|---|
| 创建 | `POST /api/v1/repos/{owner}/{repo}/tags` | `tag_name + commit_id`，可 `skip_webhooks` |
| 列表 | `GET /api/v1/repos/{owner}/{repo}/tags` | 数组 `RepoTag` |
| 读单个 | `GET /api/v1/repos/{owner}/{repo}/tags/{tag_name}` | tag path |
| 更新 | `PATCH .../tags/{tag_name}` | 必填新 `commit_id` |
| 删除 | `DELETE .../tags/{tag_name}` | 200 |

变更端点要求 repo owner、`prompts:tag` permission 或 ABAC grant。`skip_webhooks` 可为 boolean 或 webhook ID 数组；这是改变外部通知语义的高风险开关，只能由受权后台调用并写审计原因。更新 Tag 前验证 commit 属于同 repo，先展示 from/to hash 和下游影响，对生产 Tag 使用双人审批或环境保护规则。

## Tag transition 审计

`GET /repos/{owner}/{repo}/tags/{tag_name}/history` 注意路径没有 `/api/v1` 前缀。它使用 `limit=50, offset=0`，返回 `total` 与 transitions；每项有 from/to commit ID/hash、tag/repo、操作人/名称与时间。

审计应将 transition 按服务端 ID 去重，完整分页拉取，并将“当前 tag 指向”与“历史最后一条 to commit”对账。操作人名称只是展示字段，审计主键用稳定 ID。

## 当前 OpenAPI 的生成客户端风险

`GET` 单 Tag 和 Tag 列表的 path 模板都含 `{owner}`，但当前 operation parameters 没有声明 owner；变更端点则正常声明。这是文档/OpenAPI 层已验证的契约不一致，不是运行时已验证行为。自动生成 SDK 后必须添加 contract test：调用方仍应构造 owner/repo 完整路径，不要因生成方法缺 owner 就绕过 repo scope。

## 发布不变式

一个可回滚的 Prompt 发布应记录：`owner/repo`、tag、from/to commit ID+hash、操作人、审批、webhook 是否被跳过、验证结果和回滚 commit。运行时服务优先拉取已校验 commit，不在每个请求中无条件跟随可变 Tag。