ovs-notes

Skill：ovs-notes

即时查看发行说明——输入后显示可供选择和阅读的版本列表。只读查看器，不负责发布版本（那是 /ship）。

WHAT

目的和上下文

• 目的： 让用户即时、只读地查看发行说明（默认查看 overstack 框架，或当前项目）。
• 触发条件（何时使用）：
  • 用户想查看发行历史：“release notes”“changelog”“已发布的版本”“最新版本有什么内容”“/ovs-notes”。
• 非目标： 不要用于创建或推送发行版本——那是 /ship。不要根据 CWD 推断来源。

心智模型

来源（默认框架 · --here 项目 · --repo 其他仓库）→ 按从新到旧排列、带来源标签的 vX.Y.Z 列表 → 用户选择版本 → 完整打印内容。

名称 ovs- = 承诺“属于 overstack” → 默认查看框架的变更日志（Rheinmir/setup，通过 gh），无论你当前位于哪个项目——不要根据 CWD 推断来源（避免冒名顶替：把框架发行版本误认为项目发行版本）。每次打印时，header 中都必须标注来源（council-advisory 030726）。

输入和输出约定

	字段	必填？	含义
输入	version | latest	否	未提供 → 打印列表，然后询问要选择哪个版本
输入	--here / --repo owner/name	否	当前项目的发行版本（本地 git tag，可离线使用）/ 其他 GitHub 仓库
输出	vX.Y.Z <日期> <标题> 列表或某个版本的内容	是	header 中始终带有来源标签
输出	exit≠0 +“无法确认”	gh 缺失/离线时	不要假装结果为空

规则和能力

• RULE-01（MUST）：绝对只读——绝不创建或修改 tag、release 或文件。创建发行版本是 /ship 的工作。
• RULE-02（MUST）：必须标注来源——每次输出都明确说明当前查看的是框架，还是哪个项目（防止冒名顶替——Taleb）。
• RULE-03（MUST）：明确失败，不要假装结果为空——gh 缺失/离线时 → 提示“无法确认” + exit≠0；不要打印空列表，装作没有任何版本。
• RULE-04（MUST）：组合使用，不要重复造轮子：所有逻辑都放在 harness/scripts/ovs-notes.py（自包含 stdlib，可向下游移植）——skill 只负责协调调用。
• 能力：读取远程仓库的发行版本（通过已认证的 GitHub 工具）或本地 git tag；不写入任何内容。

故障边界

• gh 缺失/离线/尚未登录 → 受阻：明确打印 “无法确认——空结果不代表没有版本”，exit≠0。
• 用户未指定版本 → 澄清：显示列表，然后询问要选择哪个版本。
• 用户实际上想创建发行版本 → 转到 /ship，不要在此处处理。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出状态	失败/后续
W01	确定性	来源	列出：运行 python3 harness/scripts/ovs-notes.py（项目时加上 --here）	带有来源标签、按从新到旧排列的变更日志	gh 缺失 → 受阻，exit≠0
W02	判断	用户表述	选择版本：用户指定 → 使用 `<version	latest>` 运行；未指定 → 询问	版本内容
W03	确定性	输出	仅打印供用户阅读	用户可阅读	—

各步骤的详细说明（W01–W03 的事实来源）：

1. 列出（默认）： 运行 python3 harness/scripts/ovs-notes.py → 按从新到旧排列的框架变更日志（vX.Y.Z <日期> <标题>），带有来源标签。用户想查看项目的发行版本 → 添加 --here。
2. 选择版本阅读： 用户指定版本（“v1.0.5”/“最新版本”）→ 运行 python3 harness/scripts/ovs-notes.py <version|latest>（如果是项目，加上 --here）。未指定 → 显示列表，然后询问用户要选择哪个版本。
3. 仅打印供用户阅读。不要修改、打 tag 或 push。

来源：默认框架，项目使用 --here（council-advisory 030726）

• --here → 当前项目的发行版本（本地 git tag，可离线使用）。
• --repo owner/name → 其他 GitHub 仓库。
• gh 缺失/离线/尚未登录 → 明确打印 “无法确认——空结果不代表没有版本”，exit≠0（不要假装结果为空）。

Zero-model：直接运行，不消耗 token

全部逻辑都在 harness/scripts/ovs-notes.py 中（位于 harness/scripts，因此会 随之迁移到所有安装了 overstack 的项目中——下游路径不会断裂）。想要与 Claude CLI 客户端侧的 /release-notes 完全一致（即时、0 token），请使用 bang 前缀直接输入：

!python3 harness/scripts/ovs-notes.py            # changelog framework (list)
!python3 harness/scripts/ovs-notes.py latest     # bản framework mới nhất
!python3 harness/scripts/ovs-notes.py --here     # release project hiện tại

此技能是自然语言入口（当用户说“查看 release notes”时）——需要经过模型一步来调用脚本；若想要 0-token，请使用上面的 !。

分支

ID	类型	条件	行为	跳过 / 失败	汇合
B01	user_optional	用户想查看当前项目的发行版本	添加 --here（本地 git tag，支持离线）	—	W02
B02	user_optional	用户指定了其他 GitHub 仓库	添加 --repo owner/name	缺少 gh → 阻塞	W02
B03	user_optional	用户想要 0 token	直接输入 !python3 harness/scripts/ovs-notes.py …	—	结束（不经过模型）

验证与停止

ovs-notes.py 打印的内容是权威内容；模型只会转交给用户。打印后即停止；没有写入步骤。

示例

• 正向：“最新版本有什么新内容” → python3 harness/scripts/ovs-notes.py latest → 完整打印最新框架版本的 notes，标头注明来源 Rheinmir/setup。
• **边界/失败：**机器尚未执行 gh auth login → 脚本打印“无法确认——为空不代表没有版本”，退出码≠0；不会打印空列表。