jfox-cli 1.4.0__tar.gz → 1.6.0__tar.gz

{jfox_cli-1.4.0 → jfox_cli-1.6.0}/.claude/skills/release/SKILL.md

@@ -138,13 +138,24 @@ git pull origin main
 
 ### Step 9: 创建 GitHub Release
 
+**先跑 verify 校验**（#333：核对 `last_tag..HEAD` 功能 commit 的 PR 号是否都进了 CHANGELOG 顶段，防 bump 后被外部 PR 抢先合入致漏项——v1.1.0/v1.5.0 踩过）：
+
+```bash
+uv run python .claude/skills/release/release_helper.py verify
+```
+
+退出码非 0 → 打印 missing 条目，**停止**，按下面流程修复后重跑（**不能直接重跑**——本地 main 须先拉取补丁，否则 verify 仍会失败）：
+
+1. 开 `docs(changelog)` PR，把 missing PR 号补进 CHANGELOG.md 顶段（首个 `## [...]` 版本段），合并到 main。
+2. `git checkout main && git pull origin main`（拉取刚合并的 CHANGELOG 补丁）。
+3. 重跑 `uv run python .claude/skills/release/release_helper.py verify`，退出码 0 才继续。
+
+退出码 0 → 创建 Release。**release notes 必须取自当前 CHANGELOG.md 的顶段**（首个 `## [{new_version}]` 版本段的全部条目）——若中间经过 verify 补丁，顶段已含新增条目，**不要复用 Step 2/3 缓存的 `{changelog_preview}`**：
+
 ```bash
 gh release create v{new_version} \
   --title "v{new_version}" \
-  --notes "$(cat <<'EOF'
-{changelog_preview}
-EOF
-)"
+  --notes "<CHANGELOG.md 顶段（## [{new_version}] ... 到下一个 ## [ 之间）的全部条目>"
 ```
 
 告知用户：

{jfox_cli-1.4.0 → jfox_cli-1.6.0}/.claude/skills/release/release_helper.py

@@ -12,6 +12,7 @@ jfox release 辅助脚本
     python release_helper.py 0.5.0          # 指定版本
     python release_helper.py ... --dry-run  # 只计算不修改文件
 """
+
 import json
 import re
 import subprocess
@@ -145,8 +146,16 @@ def parse_commits(last_tag: str) -> list[dict]:
 
     # -c core.quotepath=false 确保 git 输出中文不被转义
     result = subprocess.run(
-        ["git", "-c", "core.quotepath=false", "-c", "i18n.logoutputencoding=utf-8",
-         "log", range_spec, "--format=%s"],
+        [
+            "git",
+            "-c",
+            "core.quotepath=false",
+            "-c",
+            "i18n.logoutputencoding=utf-8",
+            "log",
+            range_spec,
+            "--format=%s",
+        ],
         cwd=str(PROJECT_ROOT),
         capture_output=True,
         text=True,
@@ -204,7 +213,9 @@ def parse_commits(last_tag: str) -> list[dict]:
     return entries
 
 
-def generate_changelog(new_version: str, current_version: str, entries: list[dict], last_tag: str = "") -> str:
+def generate_changelog(
+    new_version: str, current_version: str, entries: list[dict], last_tag: str = ""
+) -> str:
     """生成 CHANGELOG Markdown 内容"""
     today = date.today().isoformat()
 
@@ -244,8 +255,7 @@ def generate_changelog(new_version: str, current_version: str, entries: list[dic
     # 底部比较链接
     tag_prev = last_tag.lstrip("v") if last_tag else current_version
     lines.append(
-        f"[{new_version}]: https://github.com/zhuxixi/jfox/compare/"
-        f"v{tag_prev}...v{new_version}"
+        f"[{new_version}]: https://github.com/zhuxixi/jfox/compare/" f"v{tag_prev}...v{new_version}"
     )
 
     return "\n".join(lines)
@@ -289,9 +299,131 @@ def summarize_entries(entries: list[dict]) -> str:
     return ", ".join(parts) if parts else "0 changes"
 
 
+def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
+    """git 调用封装（verify 用，cwd 可注入便于测试）。"""
+    return subprocess.run(
+        ["git", "-c", "core.quotepath=false", "-c", "i18n.logoutputencoding=utf-8", *args],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def _repo_has_v_tag(root: Path) -> bool:
+    """仓库是否存在任意 v* tag（locale 无关地判定「有无 tag」）。
+
+    用 `git tag --list v*` 而非 stderr 文本——非英文 locale 下 git 的报错文案会被本地化，
+    靠 "No names found" 之类子串匹配会误判。tag --list 自身失败则 raise（真正 git 错误）。
+    """
+    out = _git(["tag", "--list", "v*"], root)
+    if out.returncode != 0:
+        raise RuntimeError(f"git tag --list 失败: {out.stderr.strip()}")
+    return bool(out.stdout.strip())
+
+
+def functional_commits_since_last_tag(root: Path) -> list[str]:
+    """last v* tag..HEAD 的功能类 commit subject（白名单：feat/fix/refactor/docs/perf）。
+
+    白名单比黑名单更抗格式偏差（非 conventional 提交 ctype='' 不入选）；额外跳过
+    merge commit、含 "bump version" 的提交，以及 docs(changelog) 这类 CHANGELOG 维护
+    提交（其 PR 号本身就是补 CHANGELOG 的，不应反过来要求进 CHANGELOG，否则 verify 陷入
+    无限修复循环）。支持 conventional 破坏性标记（feat!:/feat(scope)!:）。
+    无 v* tag（首次发版）时返回 []——没有上一版基线，无从谈漂移。
+    git log 失败时 raise RuntimeError，由 verify() 捕获转 fail-closed。
+    """
+    out = _git(["describe", "--tags", "--abbrev=0", "--match", "v*"], root)
+    if out.returncode != 0:
+        # 区分「无 v* tag」（合法，首次发版）与真正 git 错误。
+        # 用 tag --list（locale 无关）判定——非英文 locale 下 git stderr 会被本地化，不能靠文本匹配。
+        if not _repo_has_v_tag(root):
+            return []
+        raise RuntimeError(f"git describe 失败: {out.stderr.strip()}")
+    tag = out.stdout.strip()
+    out = _git(["log", f"{tag}..HEAD", "--format=%s"], root)
+    if out.returncode != 0:
+        raise RuntimeError(f"git log 失败（{tag}..HEAD）: {out.stderr.strip()}")
+    functional = {"feat", "fix", "refactor", "docs", "perf"}
+    result = []
+    for line in out.stdout.splitlines():
+        s = line.strip()
+        if not s or "bump version" in s.lower():
+            continue
+        if s.startswith("Merge "):
+            continue
+        # conventional: type[(scope)][!]:  —— 捕获 type/scope，容忍破坏性标记 !
+        m = re.match(r"^(\w+)(?:\(([^)]*)\))?!?:", s)
+        if not m:
+            continue
+        ctype = m.group(1).lower()
+        scope = (m.group(2) or "").lower()
+        if ctype not in functional:
+            continue
+        if ctype == "docs" and "changelog" in scope:
+            continue  # docs(changelog) 是补 CHANGELOG 的维护提交，跳过防 verify 死循环
+        result.append(s)
+    return result
+
+
+def changelog_top_prs(root: Path) -> set[int]:
+    """解析 CHANGELOG.md 最新版本段（首个 ## [ ... 到下一个 ## [）内的 (#NNN) 集合。"""
+    cl = root / "CHANGELOG.md"
+    if not cl.exists():
+        return set()
+    text = cl.read_text(encoding="utf-8")
+    m = re.search(
+        r"^##\s*\[[^\]]+\][^\n]*\n(.*?)(?=^##\s*\[|\Z)",
+        text,
+        re.MULTILINE | re.DOTALL,
+    )
+    section = m.group(1) if m else text
+    return {int(x) for x in re.findall(r"\(#(\d+)\)", section)}
+
+
+def verify(root: Path | None = None) -> dict:
+    """#333：创建 Release 前核对 last_tag..HEAD 功能 commit 的 PR 号是否都被 CHANGELOG 顶段收录。
+
+    返回 {"ok": bool, "missing": sorted[int], "extra": sorted[int], "functional_commits": int}。
+    ok=False 表示有功能 commit 的 PR 未进 CHANGELOG（漂移），应阻止发 Release。
+    数据源出错（git log 失败等）时 fail-closed：返回 ok=False + error，迫使流程停而非误判通过。
+    """
+    root = Path(root) if root else PROJECT_ROOT
+    try:
+        func_prs: set[int] = set()
+        for s in functional_commits_since_last_tag(root):
+            # 只取 subject 末尾的 (#NNN)（squash 标题里的本提交 PR 号），
+            # 避免正文引用多个 PR（如协作）把非本提交 PR 误判为必须进 CHANGELOG。
+            m = re.search(r"\(#(\d+)\)\s*$", s)
+            if m:
+                func_prs.add(int(m.group(1)))
+        cl_prs = changelog_top_prs(root)
+    except (RuntimeError, OSError, UnicodeDecodeError, ValueError) as e:
+        return {
+            "ok": False,
+            "error": f"verify 失败: {e}",
+            "missing": [],
+            "extra": [],
+            "functional_commits": 0,
+        }
+    missing = sorted(func_prs - cl_prs)
+    extra = sorted(cl_prs - func_prs)
+    return {
+        "ok": not missing,
+        "missing": missing,
+        "extra": extra,
+        "functional_commits": len(func_prs),
+    }
+
+
 def main():
+    if len(sys.argv) >= 2 and sys.argv[1] == "verify":
+        res = verify()
+        output_json(res)
+        sys.exit(0 if res["ok"] else 1)
+
     if len(sys.argv) < 2:
-        output_error("用法: release_helper.py <version|patch|minor|major> [--dry-run]")
+        output_error("用法: release_helper.py <version|patch|minor|major|verify> [--dry-run]")
 
     version_arg = sys.argv[1]
     dry_run = "--dry-run" in sys.argv

jfox_cli-1.6.0/.claude/skills/release-all/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: release-all
+description: Release all three components (jfox CLI + cc-plugin + kimi-plugin) in one command. Detects per-component changes since last release, skips unchanged ones, batches bump PRs, then creates the jfox GitHub Release last (with CHANGELOG verify). Triggers on "全发", "release all", "三件套发版", "一起发版".
+---
+
+# Release-All Skill
+
+一条命令编排三条独立发版轨道：jfox CLI → cc-plugin → kimi-plugin。自动检测各组件自上次发版以来的改动，**跳过无改动者**；为有改动者批量建 bump PR；用户合并后，最后发 jfox GitHub Release（带 #333 verify 校验）。
+
+⚠️ 三组件版本轨道独立、语义各自不同。本 skill 不统一版本号，只统一编排。
+要单独发某一组件，用 `/release`、`/release-cc-plugin`、`/release-kimi-plugin`。
+
+## 用法
+
+```
+/release-all              # 逐组件确认 suggested_bump
+/release-all minor        # 统一指定 bump 类型（套用到所有 changed 组件）
+/release-all patch
+```
+
+## 编排模型
+
+**批量建 PR + 最后发 jfox Release**：detect 全部 → 展示计划 → 为每个 changed 组件 bump+建 PR → 用户依次合并全部 PR → 拉最新 main → verify → 建 jfox GitHub Release。
+
+## 执行流程
+
+### Step 1: 前置校验（任一不符即停）
+
+```bash
+git branch --show-current                       # 期望 main
+git status --porcelain                          # 期望 空
+git branch --list 'chore/bump-*'                # 期望 空（三组件任一 bump 分支都不能存在）
+# gh pr list --head 只支持精确分支名（不支持通配），改用 json+grep 列 open bump PR
+gh pr list --state open --json headRefName --jq '.[].headRefName' | grep 'chore/bump-'   # 期望无输出
+```
+
+### Step 2: 检测
+
+```bash
+uv run python .claude/skills/release-all/release_all_helper.py detect
+```
+
+### Step 3: 展示合并计划 + 确认 bump 类型
+
+展示 detect 结果：
+
+```
+📦 Release-All 计划:
+  jfox        1.5.0 → 1.6.0 (minor)  ✓ 有改动  [feat(backup)#339, feat(gem-synth)#335]
+  cc-plugin   0.6.0 → 0.6.1 (patch)  ✓ 有改动  [docs(promote)#342]
+  kimi-plugin 0.14.0                ✗ 无改动，跳过
+```
+
+- 命令带参数（`/release-all minor`）→ 统一套用到所有 changed 组件。
+- 否则逐组件确认 suggested_bump（用户可改 patch/minor/major 或指定 x.y.z）。
+- 全部 changed=false → 打印「三组件均无未发布改动，无需发版」并结束。
+
+### Step 4: 逐组件 bump + 建 PR（顺序 jfox → cc → kimi，仅 changed 者）
+
+detect 已算出 suggested_version 并经确认，跳过各单组件 skill 的 dry-run 预览步。
+
+⚠️ **每个组件开始前必须先 `git checkout main`**：上一组件的 bump 提交落在它自己的分支上，若不回 main，下一组件的 `git checkout -b` 会从上一组件分支拉出，导致 PR diff 串进别的组件文件（如 cc PR 里混入 jfox 的 pyproject.toml）。
+
+对每个 changed 组件，循环执行（helper 在 main 工作树改文件 → 从 main 拉 bump 分支 → commit → push → 开 PR）：
+
+1. `git checkout main`（确保下一组件从干净的 main 拉分支）
+2. 正式 bump + 建分支 + commit + push + 开 PR（每条都用完整命令，`git push` 须带 `-u` 设 upstream）：
+   - **jfox**：`uv run python .claude/skills/release/release_helper.py <v>` → `git checkout -b chore/bump-version-<v>` → `git add pyproject.toml jfox/__init__.py uv.lock CHANGELOG.md` → `git commit -m "chore: bump version to <v>"` → `git push -u origin chore/bump-version-<v>` → `gh pr create --title "chore: bump version to <v>" --body "<changelog_preview>"`
+   - **cc-plugin**：`uv run python .claude/skills/release-cc-plugin/release_cc_plugin_helper.py <v>` → `git checkout -b chore/bump-cc-plugin-<v>` → `git add packages/cc-plugin/.claude-plugin/plugin.json .claude-plugin/marketplace.json` → `git commit -m "chore(cc-plugin): bump version <cur> → <v>"` → `git push -u origin chore/bump-cc-plugin-<v>` → `gh pr create --title "chore(cc-plugin): bump version <cur> → <v>" --body "<changelog>"`
+   - **kimi-plugin**：`uv run python .claude/skills/release-kimi-plugin/release_kimi_plugin_helper.py <v>` → `git checkout -b chore/bump-kimi-plugin-<v>` → `git add packages/kimi-plugin/kimi.plugin.json` → `git commit -m "chore(kimi-plugin): bump version <cur> → <v>"` → `git push -u origin chore/bump-kimi-plugin-<v>` → `gh pr create --title "chore(kimi-plugin): bump version <cur> → <v>" --body "<changelog>"`
+
+三组件文件不冲突，PR 可并存。收集所有 PR URL。
+
+### Step 5: 告知用户合并
+
+```
+已创建 N 个 bump PR：
+  - jfox:       <URL>
+  - cc-plugin:  <URL>
+  - kimi-plugin: <URL>
+请依次合并后告知我，我将继续创建 jfox GitHub Release（cc/kimi 合 main 即生效，无需 Release）。
+```
+
+等待用户确认全部合并。**只有 jfox 在计划内时才需要合并后回流；若 jfox 被跳过，cc/kimi 合完即结束。**
+
+### Step 6: 发 jfox Release（仅当 jfox 在计划内）
+
+```bash
+git checkout main && git pull origin main
+uv run python .claude/skills/release/release_helper.py verify    # #333 兜底
+# verify 退出码 0 才继续：
+gh release create v<jfox_ver> --title "v<jfox_ver>" --notes "<changelog_preview>"
+```
+
+verify 非 0 → 打印 missing 条目，**停**，提示用户补 CHANGELOG（开 `docs(changelog)` PR 合并）后重跑 verify + release。**不自动建 Release。**
+
+## 跳过提示
+
+detect 阶段 changed=false 的组件，全程打印一次「<组件> 自 <ver> 以来无改动，跳过」后不再出现。
+
+## 错误处理
+
+- detect 某组件异常 → 该组件 changed=false + skip_reason，继续其他组件，不中断。
+- 某组件 bump 中途失败 → 已建的早期组件 PR 保留（独立），报告失败组件、停。
+- 用户只合并部分 PR → Step 6 不执行，提示「还有 X 个 PR 未合并」。
+- verify 非 0 → 不建 Release，打印 missing，停。
+
+## 与单组件 skill 的关系
+
+- `/release`、`/release-cc-plugin`、`/release-kimi-plugin` 不变其单组件职责。
+- 本 skill 是编排层，**委托**三组件 helper，自身只做 detect + 调度 + skip + verify 串接，无特判分支。

jfox_cli-1.6.0/.claude/skills/release-all/release_all_helper.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""
+release-all 编排辅助脚本：检测三组件（jfox CLI / cc-plugin / kimi-plugin）未发布改动，
+跳过无改动者。只做检测，不发版、不碰文件；发版动作由各组件 helper 负责。
+
+用法:
+    python release_all_helper.py [detect]    # 默认 detect
+"""
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# 项目根目录（脚本位于 .claude/skills/release-all/，向上 3 级）
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+
+PYPROJECT_TOML = "pyproject.toml"
+CC_PLUGIN_JSON = "packages/cc-plugin/.claude-plugin/plugin.json"
+CC_MARKETPLACE = ".claude-plugin/marketplace.json"
+KIMI_PLUGIN_JSON = "packages/kimi-plugin/kimi.plugin.json"
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def output_json(data: dict) -> None:
+    print(json.dumps(data, ensure_ascii=False))
+
+
+def _git(args: list[str], root: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [
+            "git",
+            "-c",
+            "core.quotepath=false",
+            "-c",
+            "i18n.logoutputencoding=utf-8",
+            *args,
+        ],
+        cwd=str(root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def _bump_version(current: str, spec: str) -> str:
+    major, minor, patch = (int(x) for x in current.split("."))
+    if spec == "patch":
+        return f"{major}.{minor}.{patch + 1}"
+    if spec == "minor":
+        return f"{major}.{minor + 1}.0"
+    if spec == "major":
+        return f"{major + 1}.0.0"
+    raise ValueError(f"非法 bump 规格: {spec}")
+
+
+def _repo_has_v_tag(root: Path) -> bool:
+    """仓库是否存在任意 v* tag（locale 无关地判定「有无 tag」）。tag --list 自身失败则 raise。"""
+    out = _git(["tag", "--list", "v*"], root)
+    if out.returncode != 0:
+        raise RuntimeError(f"git tag --list 失败: {out.stderr.strip()}")
+    return bool(out.stdout.strip())
+
+
+def _last_jfox_tag(root: Path) -> str:
+    out = _git(["describe", "--tags", "--abbrev=0", "--match", "v*"], root)
+    if out.returncode != 0:
+        # 用 tag --list（locale 无关）区分「无 v* tag」与真正 git 错误，不依赖 stderr 文本
+        if not _repo_has_v_tag(root):
+            return ""  # 无 v* tag（首次发版），合法
+        raise RuntimeError(f"git describe 失败: {out.stderr.strip()}")
+    return out.stdout.strip()
+
+
+def _find_last_bump_commit(root: Path, version: str, rel_path: str) -> str:
+    """定位引入该 version 的提交（git log -S），fallback 到最后改该文件的提交。
+
+    单次 git 错误不致命：-S 失败则试 fallback，-S 无命中也试 fallback。
+    仅当两次 git 调用都出错（returncode!=0）才 raise（fail-closed），不计 stderr 文本。
+    """
+    needle = f'"version": "{version}"'
+    errs: list[str] = []
+    for args in (
+        ["log", "-S", needle, "--format=%H", "--", rel_path],
+        ["log", "--format=%H", "-1", "--", rel_path],
+    ):
+        out = _git(args, root)
+        if out.returncode != 0:
+            errs.append(out.stderr.strip())
+            continue  # git 错误，试 fallback
+        hits = [ln for ln in out.stdout.splitlines() if ln.strip()]
+        if hits:
+            return hits[0]
+        # returncode 0 但无命中：继续试下一个 args（-S 无命中 → 试 fallback）
+    if len(errs) == 2:
+        raise RuntimeError(f"git log 失败（定位 bump commit）: {'; '.join(e for e in errs if e)}")
+    return ""
+
+
+def _read_json_version(root: Path, rel: str) -> str:
+    v = json.loads((root / rel).read_text(encoding="utf-8"))["version"]
+    if not VERSION_RE.match(v):
+        raise ValueError(f"非法版本号格式: {v!r}（{rel}）")
+    return v
+
+
+def _read_pyproject_version(root: Path) -> str:
+    m = re.search(
+        r'^version\s*=\s*"(\d+\.\d+\.\d+)"',
+        (root / PYPROJECT_TOML).read_text(encoding="utf-8"),
+        re.MULTILINE,
+    )
+    if not m:
+        raise ValueError("未在 pyproject.toml 找到 version")
+    return m.group(1)
+
+
+def detect_jfox(root: Path) -> dict:
+    """jfox CLI：last v* tag..HEAD 是否有非 bump 的功能性 commit。"""
+    # 阶段 1：读版本（文件缺失/格式错误）
+    try:
+        current = _read_pyproject_version(root)
+    except (OSError, ValueError) as e:
+        return {
+            "name": "jfox",
+            "changed": False,
+            "current_version": "",
+            "baseline": "",
+            "commits": [],
+            "skip_reason": f"读取版本失败: {e}",
+        }
+    # 阶段 2：git 操作（tag/log；RuntimeError=git 失败，OSError/SubprocessError=git 二进制缺失等）
+    tag = ""
+    try:
+        tag = _last_jfox_tag(root)
+        out = _git(["log", f"{tag}..HEAD" if tag else "HEAD", "--format=%s"], root)
+        if out.returncode != 0:
+            raise RuntimeError(f"git log 失败: {out.stderr.strip()}")
+    except (RuntimeError, OSError, subprocess.SubprocessError) as e:
+        return {
+            "name": "jfox",
+            "changed": False,
+            "current_version": current,
+            "baseline": tag,
+            "commits": [],
+            "skip_reason": f"git 操作失败: {e}",
+        }
+    subjects = [
+        s.strip() for s in out.stdout.splitlines() if s.strip() and "bump version" not in s.lower()
+    ]
+    if not subjects:
+        return {
+            "name": "jfox",
+            "changed": False,
+            "current_version": current,
+            "baseline": tag,
+            "commits": [],
+            "skip_reason": f"自 {tag or '起点'} 以来无改动",
+        }
+    bump = "minor" if any(s.startswith("feat") for s in subjects) else "patch"
+    return {
+        "name": "jfox",
+        "changed": True,
+        "current_version": current,
+        "baseline": tag,
+        "commits": subjects,
+        "suggested_bump": bump,
+        "suggested_version": _bump_version(current, bump),
+    }
+
+
+def _detect_plugin(
+    root: Path, name: str, version_source: str, baseline_file: str, watch_paths: list[str]
+) -> dict:
+    """cc/kimi 通用检测：自上次 bump commit 起是否有改 watch_paths 的提交。
+
+    - version_source：含顶层 version 字段的文件（读当前版本）。
+    - baseline_file：git log -S 定位上次 bump 的文件（cc=marketplace.json、
+      kimi=kimi.plugin.json）。
+    - watch_paths：检测改动的路径（cc/kimi 各自 packages/ 目录）。
+    """
+    # 阶段 1：读版本
+    try:
+        current = _read_json_version(root, version_source)
+    except (OSError, KeyError, ValueError) as e:
+        return {
+            "name": name,
+            "changed": False,
+            "current_version": "",
+            "baseline": "",
+            "commits": [],
+            "skip_reason": f"读取版本失败: {e}",
+        }
+    # 阶段 2：git 操作（baseline/log）
+    baseline = ""
+    try:
+        baseline = _find_last_bump_commit(root, current, baseline_file)
+        if baseline:
+            out = _git(["log", "--oneline", f"{baseline}..HEAD", "--", *watch_paths], root)
+        else:
+            out = _git(["log", "--oneline", "--max-count=30", "--", *watch_paths], root)
+        if out.returncode != 0:
+            raise RuntimeError(f"git log 失败: {out.stderr.strip()}")
+    except (RuntimeError, OSError, subprocess.SubprocessError) as e:
+        return {
+            "name": name,
+            "changed": False,
+            "current_version": current,
+            "baseline": baseline,
+            "commits": [],
+            "skip_reason": f"git 操作失败: {e}",
+        }
+    commits = [c for c in out.stdout.splitlines() if c.strip()]
+    if not commits:
+        return {
+            "name": name,
+            "changed": False,
+            "current_version": current,
+            "baseline": baseline,
+            "commits": [],
+            "skip_reason": f"自 {current} 以来无改动",
+        }
+    return {
+        "name": name,
+        "changed": True,
+        "current_version": current,
+        "baseline": baseline,
+        "commits": commits,
+        "suggested_bump": "patch",
+        "suggested_version": _bump_version(current, "patch"),
+    }
+
+
+def detect_cc(root: Path) -> dict:
+    # plugin.json 含顶层 version（读版本）；marketplace.json 用于 -S 定位 bump（与
+    # release_cc_plugin_helper 一致）；watch packages/cc-plugin/（skills + plugin.json）
+    # 外加 marketplace.json 本身——改其非 version 元数据也算 cc 改动，该发版。
+    return _detect_plugin(
+        root,
+        "cc-plugin",
+        CC_PLUGIN_JSON,
+        CC_MARKETPLACE,
+        ["packages/cc-plugin/", ".claude-plugin/marketplace.json"],
+    )
+
+
+def detect_kimi(root: Path) -> dict:
+    return _detect_plugin(
+        root, "kimi-plugin", KIMI_PLUGIN_JSON, KIMI_PLUGIN_JSON, ["packages/kimi-plugin/"]
+    )
+
+
+def detect(root: Path) -> dict:
+    comps = [detect_jfox(root), detect_cc(root), detect_kimi(root)]
+    return {"components": comps, "any_changed": any(c.get("changed") for c in comps)}
+
+
+def main() -> None:
+    # 仅支持 detect（默认）；无参数或参数为 detect 都走 detect
+    try:
+        output_json(detect(PROJECT_ROOT))
+    except (OSError, subprocess.SubprocessError, ValueError) as e:
+        output_json({"error": f"detect 失败: {e}"})
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()