--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: standard status: verified tags: - study - langchain - langsmith - smith-api - prompt-hub - webhook - public-sharing topic: LangSmith Smith API Prompt Hub 版本、Webhook 与公开分享边界 sources: - https://docs.langchain.com/langsmith/smith-api/commits/create-a-commit - https://docs.langchain.com/langsmith/smith-api/commits/get-a-commit - https://docs.langchain.com/langsmith/smith-api/commits/list-commits - https://docs.langchain.com/langsmith/smith-api/hub_environments/create-hub-environments-model - https://docs.langchain.com/langsmith/smith-api/hub_environments/delete-hub-environments-model - https://docs.langchain.com/langsmith/smith-api/hub_environments/list-hub-environments - https://docs.langchain.com/langsmith/smith-api/hub_environments/update-hub-environments-model - https://docs.langchain.com/langsmith/smith-api/likes/like-repo - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/create-prompt-webhook - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/delete-prompt-webhook - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/get-prompt-webhook - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/list-prompt-webhooks - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/test-prompt-webhook - https://docs.langchain.com/langsmith/smith-api/prompt-webhooks/update-prompt-webhook - https://docs.langchain.com/langsmith/smith-api/prompts/invoke-prompt - https://docs.langchain.com/langsmith/smith-api/prompts/prompt-canvas - https://docs.langchain.com/langsmith/smith-api/public/count-shared-examples - https://docs.langchain.com/langsmith/smith-api/public/generate-query-for-shared-dataset-runs - https://docs.langchain.com/langsmith/smith-api/public/get-message-json-schema - https://docs.langchain.com/langsmith/smith-api/public/get-shared-run - https://docs.langchain.com/langsmith/smith-api/public/get-shared-run-by-id - https://docs.langchain.com/langsmith/smith-api/public/get-tool-def-json-schema - https://docs.langchain.com/langsmith/smith-api/public/query-shared-dataset-runs - https://docs.langchain.com/langsmith/smith-api/public/query-shared-runs - https://docs.langchain.com/langsmith/smith-api/public/read-shared-comparative-experiments - https://docs.langchain.com/langsmith/smith-api/public/read-shared-dataset - https://docs.langchain.com/langsmith/smith-api/public/read-shared-dataset-feedback - https://docs.langchain.com/langsmith/smith-api/public/read-shared-dataset-run - https://docs.langchain.com/langsmith/smith-api/public/read-shared-dataset-tracer-sessions - https://docs.langchain.com/langsmith/smith-api/public/read-shared-dataset-tracer-sessions-bulk - https://docs.langchain.com/langsmith/smith-api/public/read-shared-examples - https://docs.langchain.com/langsmith/smith-api/public/read-shared-feedbacks - https://docs.langchain.com/langsmith/smith-api/public/stats-shared-dataset-runs - https://docs.langchain.com/langsmith/smith-api/repos/create-repo - https://docs.langchain.com/langsmith/smith-api/repos/delete-repo - https://docs.langchain.com/langsmith/smith-api/repos/delete-repos - https://docs.langchain.com/langsmith/smith-api/repos/fork-repo - https://docs.langchain.com/langsmith/smith-api/repos/get-repo - https://docs.langchain.com/langsmith/smith-api/repos/list-repo-tags - https://docs.langchain.com/langsmith/smith-api/repos/list-repos - https://docs.langchain.com/langsmith/smith-api/repos/optimize-prompt-job - https://docs.langchain.com/langsmith/smith-api/repos/update-repo - https://docs.langchain.com/langsmith/smith-api/sessions/list-agent-versions-for-a-project last_verified: 2026-08-11 --- # Smith API：Prompt Hub 版本、Webhook 与公开分享边界 Prompt Hub 的核心不是“保存一段提示词”，而是 repository + immutable commit + environment/tag 的发布模型。公开分享接口又把 dataset、runs、feedback 和 schemas 暴露给持 token 的访问者，所以版本治理与数据发布必须同时设计。 ## Repository Repo 创建需要 handle、公开性，并支持 `prompt`、`file`、`agent`、`skill` 四种类型；还可设置 README、description、tags、tag value、source 与 `restricted_mode`。Repo 类型应在创建后视为稳定契约，因为 manifest 结构、执行方式和安全审查不同。 列表默认 20、最大 100，可按 tenant、名称查询、是否有 commit、tag、公开/归档状态、upstream、tag value、类型和 source 过滤，并可选择返回 latest manifest/owners。返回 manifest 可能很大且含敏感配置，普通列表不要开启。 Fork 会创建派生 repo，并记录 upstream 关系。Fork 不是自动同步；上游更新必须通过显式审查/合并流程进入生产。`like` 只改变社交计数，不能作为安全性或质量背书。 单删与批量删都是破坏性操作；批量最多 100，并支持 207 部分成功。`is_public`、`is_archived`、`restricted_mode` 可更新，改变公开性前需要重新做数据与 secret 扫描。 ## Commit 解析与发布 创建 commit 接受 manifest、description、parent commit，并可用 `skip_webhooks=true` 跳过全部 webhook，或给出 UUID 数组只跳过指定 webhook。跳过通知会绕过下游发布/审计链，权限应高于普通编辑。 读取 commit 的引用解析规则很重要： - `latest` 或空值取最新； - 少于 8 字符只按 tag 查找； - 8 字符及以上优先 commit hash，再查 tag。 部署必须保存完整 commit hash，不能使用 `latest`；短 tag 与 hash 前缀可能产生理解歧义。`include_model` 已 deprecated，应改用 `include`。列表默认计算下载/浏览统计；不需要时关闭 `include_stats` 可减少额外开销，并可按 tag 过滤。 `GET /platform/sessions/{sessionID}/agent-versions` 返回 tracing project 中出现过的 agent commit SHA，按首次出现时间倒序。它可用于把生产 trace 追溯到 Hub 版本，但前提是运行时确实上报 SHA；发布流水线应验证该字段，而不是事后猜测。 ## Hub environments 每个 tenant 的 environments model 包含 1–4 个环境；创建已有模型返回 409，更新会完整替换数组，删除后回到默认环境。环境应表达 dev/staging/prod 等 promotion 指针，而不是复制 prompt 文本。 发布流程建议：commit hash 通过离线评估 → staging tag/environment → 小流量在线验证 → prod 指针原子切换。回滚只把 prod 指针恢复到上一完整 hash；不要重写旧 commit。 ## Prompt Webhook Webhook 配置包括 URL、headers、触发器，以及 include/exclude prompt 列表。API 支持 CRUD 和在持久化前的 test payload。 安全与可靠性要求： - URL 仅允许 HTTPS 和批准域名/IP，防 SSRF、DNS 重绑定与内网探测； - headers 可能含签名密钥，写日志和 GET 响应都要脱敏； - 接收方验证签名、时间戳与 nonce； - 事件至少一次交付时，以 webhook/event/commit ID 幂等； - 设置超时、指数退避、死信和告警； - include/exclude 同时存在时锁定并测试优先级，不能靠猜； - test 只证明当前网络请求，不代表生产重试、签名和顺序都正确。 创建 commit 的 `skip_webhooks` 是风险例外开关，需审计操作者、理由和跳过列表。 ## Prompt 调用与 Canvas `invoke_prompt` 接受 messages、template format 和 inputs；OpenAPI 的 security 数组为空。不能据此断言所有部署都允许匿名公网调用，也不能因此省略网关保护；应在目标 LangSmith 版本做真实 401/403 契约测试。 Canvas 接受多种 LangChain message/chunk、highlight、artifact、reading level、自定义动作、`f-string`/`mustache` template format，以及 `secrets`。这些输入可同时形成模板注入、prompt injection 和 secret 泄露： - secrets 只从服务端 secret store 注入，禁止进入 trace/plain response； - template format 必须显式允许，变量按结构绑定而非拼字符串； - artifact 和消息内容视为不可信，输出不得直接执行； - Canvas 结果必须人工 review/评估后才能创建生产 commit。 ## Prompt 优化快捷入口 Repo 级 `optimize-job` 接受 prompt name、algorithm 和 Promptim/Demo config，返回 optimization job ID。它与完整 optimization-jobs CRUD 是同一异步领域的不同入口；客户端要统一追踪 job ID、预算、状态和结果，避免两套状态模型。 ## Public / share-token API 17 个 public 路由均没有标准 API Key security，主要依靠 URL 中的 UUID share token。可读取或查询： - shared run、指定 run 和 runs； - Dataset、examples、comparative experiments； - Dataset experiments 的 sessions/runs/feedback/stats； - 多 share token 的 sessions bulk； - message/tool definition JSON schema； - 自然语言生成 shared Dataset run filter。 share token 是 bearer secret，不是普通 ID。任何获得者都可能访问 token 允许的数据，且 token 出现在 URL 时容易进入浏览器历史、代理日志、Referer 和监控。不要放入查询日志或工单；公开页面设置严格 Referrer-Policy、缓存和撤销策略。 ## Public 查询细节 shared Dataset run query 支持 ID/trace/parent/run type/session/reference example、时间、error、全文与 DSL filters、trace/tree filters、cursor、select 等。默认一页最大 100；当设置 `trace` 时，limit/cursor 不生效，会一次返回整条 trace。长 trace 可能造成大响应和资源耗尽，网关需设置响应体与执行时间上限。 stats 可返回 run 数、P50/P99 latency/first token/tokens/cost、错误率、streaming rate、feedback 与 facets。公开指标也可能泄露业务量、模型价格和运行结构，应在分享前检查。 `generate-query` 把自然语言转为 filter，并返回 feedback URLs。生成的 filter 是模型产物，执行前要解析、限制字段/复杂度并展示给用户；不能直接把任意生成表达式当可信查询。 shared sessions bulk 把多个 share tokens 放在 query 参数数组中，特别容易被 access log 记录。若必须使用，确保日志脱敏；更稳妥的业务网关可改为受控 POST body，并在服务端代调官方接口。 ## Schema 端点 公开 message/tooldef schema 按 version 返回 JSON Schema。消费者必须固定 version 并缓存校验；运行时悄悄取“最新”会让消息/tool 格式漂移。schema 是结构约束，不代表内容安全，tool name/description/arguments 仍需 allowlist 和输入验证。 ## 发布与撤销清单 1. Repo 设定正确 type、owner、restricted/public policy。 2. Commit 使用 parent hash，CI 保存完整新 hash。 3. 跑固定 Dataset version 的离线评估和安全扫描。 4. 推 staging environment，验证 traces 上报 commit SHA。 5. 观察成本、错误与 feedback 后原子提升 prod。 6. Webhook 接收方按事件 ID 幂等，并监控死信。 7. 若启用 public share，记录 token owner/范围/到期日；撤销后验证旧 token 和缓存。 Dataset 的 share/unshare 生命周期见 [[01-Dataset版本实验共享与导入导出]]；优化 job 与 Playground OAuth 见 [[04-Evaluator实验视图优化与Playground配置]]。