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。