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、预算、状态和结果，避免两套状态模型。

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 和输入验证。

发布与撤销清单

Repo 设定正确 type、owner、restricted/public policy。
Commit 使用 parent hash，CI 保存完整新 hash。
跑固定 Dataset version 的离线评估和安全扫描。
推 staging environment，验证 traces 上报 commit SHA。
观察成本、错误与 feedback 后原子提升 prod。
Webhook 接收方按事件 ID 幂等，并监控死信。
若启用 public share，记录 token owner/范围/到期日；撤销后验证旧 token 和缓存。

Dataset 的 share/unshare 生命周期见 01-Dataset版本实验共享与导入导出；优化 job 与 Playground OAuth 见 04-Evaluator实验视图优化与Playground配置。