harveyz-skill 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-07-20
+
+### Added
+- `hskill` install menu：新增按平台切换的循环视图（per-platform cycling view），一键升级快捷键
+- `pdf-math-translate`：重写 frontmatter，补充 Init/Execute 两阶段流程与最新 CLI 参考
+
+### Fixed
+- `explain-pm`：警示性意见调整为统一放在结尾，不再穿插
+- `init-workflow`：修正 force-push 检测逻辑，合并提交（merge commit）豁免检查
+
+### Changed
+- 记录不新增 meta.json 完整性检查的 ADR 决策
+
 ## [0.24.0] - 2026-07-18
 
 ### Added

package/bin/cli.js

@@ -802,15 +802,34 @@ function requireFzf() {
   }
 }
 
-// 用 fzf 交互式选择 skill/tool，返回选中的 item 列表
-function fzfSelect() {
-  requireFzf()
-  const skillItems  = getAllSkillItems()
+const G = '\x1b[32m', Y = '\x1b[33m', C = '\x1b[36m', D = '\x1b[2m', R = '\x1b[0m'
+function colorIcon(status) {
+  if (status === 'up-to-date') return G + '✓' + R
+  if (status === 'update')     return Y + '↑' + R
+  return D + '—' + R
+}
+function scopeHint(installScope) {
+  if (installScope === 'essential') return Y + '»' + R
+  if (installScope === 'global' || installScope === 'project') return C + '▸' + R
+  return D + '—' + R
+}
+
+// ── Hidden: fzf reload helper ─────────────────────────────────────────────────
+// 供 fzf 的 reload()/execute() 动作回调，重新打印某个视图的最新内容（不进入交互模式）
+if (subcommand === '__fzf-view') {
+  const key = args[1]
+  const content = key === 'skill' ? buildSkillViewInput() : buildSinglePlatformViewInput(key)
+  process.stdout.write(content + '\n')
+  process.exit(0)
+}
+
+// 构建"按 skill 维度"的 fzf 输入行（skill/tool/hook 都在同一列表里）
+function buildSkillViewInput() {
+  const skillItems = getAllSkillItems()
   const toolItems   = getAllToolItems()
   const hookItems   = getAllHookItems()
-  const previewPath = path.join(__dirname, 'preview.mjs')
 
-  // 构建 fzf 输入：每行 "NAME\tVERSION\tBUNDLE\tKIND\tSRCPATH\tINSTALLSCOPE"
+  // 每行 "NAME\tVERSION\tBUNDLE\tKIND\tSRCPATH\tINSTALLSCOPE"
   const lines = [
     ...skillItems.map(s => {
       const bundle = s.srcPath.split('/').slice(-2, -1)[0]
@@ -823,18 +842,6 @@ function fzfSelect() {
   const nameWidth    = Math.max(...lines.map(l => l.split('\t')[0].length))
   const versionWidth = Math.max(...lines.map(l => l.split('\t')[1].length))
 
-  const G = '\x1b[32m', Y = '\x1b[33m', C = '\x1b[36m', D = '\x1b[2m', R = '\x1b[0m'
-  function colorIcon(status) {
-    if (status === 'up-to-date') return G + '✓' + R
-    if (status === 'update')     return Y + '↑' + R
-    return D + '—' + R
-  }
-  function scopeHint(installScope) {
-    if (installScope === 'essential') return Y + '»' + R
-    if (installScope === 'global' || installScope === 'project') return C + '▸' + R
-    return D + '—' + R
-  }
-
   // fzf 展示格式：NAME   VERSION   U:?  P:?  BUNDLE
   const displayLines = lines.map(l => {
     const [name, ver, bundle, kind, srcPath, installScope] = l.split('\t')
@@ -857,29 +864,106 @@ function fzfSelect() {
     return `${name.padEnd(nameWidth)}  ${ver.padEnd(versionWidth)}  U:${uIcon}  P:${pIcon}  ${bundle}`
   })
 
-  // 把原始数据附在末尾（隐藏列，用于解析和 preview）
-  const fzfInput = displayLines.map((d, i) => `${d}\t${lines[i]}`).join('\n')
+  return displayLines.map((d, i) => `${d}\t${lines[i]}`).join('\n')
+}
 
-  const header = `  hskill  ·  U=user P=project  ${G}✓${R}=ok ${Y}↑${R}=update ${Y}»${R}=essential ${C}▸${R}=recommended ${D}—${R}=none  ·  tab 多选  ·  enter 确认`
+// 构建"单平台维度"的 fzf 输入行：每个 skill 一行，只展示该平台（user-scope）的安装状态
+function buildSinglePlatformViewInput(targetName) {
+  const skillItems = getAllSkillItems()
+  const nameWidth   = Math.max(...skillItems.map(s => s.skillName.length))
 
-  const result = spawnSync('fzf', [
-    '--multi',
-    '--ansi',
-    '--delimiter=\t',
-    '--with-nth=1',
-    '--prompt=  › ',
-    `--header=${header}`,
-    '--layout=reverse',
-    '--border=rounded',
-    '--color=header:italic:dim,prompt:cyan,pointer:cyan,hl:cyan,hl+:cyan:bold',
-    `--preview=node ${previewPath} {2} {3} {5} {6}`,
-    '--preview-window=right:42%:wrap',
-  ], {
-    input: fzfInput,
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'inherit'],
+  const lines = skillItems.map(s => {
+    const bundle = s.srcPath.split('/').slice(-2, -1)[0]
+    return `${s.skillName}\t${s.version ?? '—'}\t${bundle}\tskill\t${s.srcPath}\t${s.installScope ?? ''}`
+  })
+
+  const displayLines = skillItems.map(s => {
+    const installed = checkInstalled(s.skillName, s.version ?? '—')
+    const detail = installed.user[targetName]
+    const ver = detail.status === 'none' ? D + '—'.padEnd(7) + R : detail.version.padEnd(7)
+    return `${s.skillName.padEnd(nameWidth)}  ${colorIcon(detail.status)}  ${ver}`
   })
 
+  return displayLines.map((d, i) => `${d}\t${lines[i]}`).join('\n')
+}
+
+function platformPrompt(key) {
+  return `  ${key} › `
+}
+
+// 静态 header：不随视图切换而变化，避免把 ANSI/中文塞进 fzf 的 shell 动作字符串里
+const COMBINED_HEADER = `  hskill  ·  ${G}✓${R}=ok ${Y}↑${R}=update ${Y}»${R}=essential ${C}▸${R}=recommended ${D}—${R}=none  ·  ctrl-t 切平台  ctrl-u 一键升级本平台  ctrl-g 升级该 skill 全平台  ·  tab 多选  ·  enter 确认`
+
+// 用 fzf 交互式选择 skill/tool，返回选中的 item 列表
+function fzfSelect() {
+  requireFzf()
+  const previewPath = path.join(__dirname, 'preview.mjs')
+  const selfPath     = process.argv[1]
+  // 用不带 flag 的 read（bash/zsh 通用；-n/-p/-k 等 flag 在两者语义不同，混用会挂住）等待回车再回到 fzf
+  const pauseCmd     = `; printf '\\n  按 enter 返回…'; read _`
+
+  // 视图顺序：skill 维度 → 逐个平台维度（每次只显示一个平台）→ 循环回 skill
+  const viewKeys  = ['skill', ...SKILL_TARGETS]
+  const skillViewInput = buildSkillViewInput()
+  const viewFiles = Object.fromEntries(viewKeys.map(key => [key, `/tmp/hskill-view-${key}-${process.pid}.txt`]))
+
+  for (const key of viewKeys) {
+    const content = key === 'skill' ? skillViewInput : buildSinglePlatformViewInput(key)
+    writeFileSync(viewFiles[key], content)
+  }
+
+  // 每个视图对应的 preview 命令：单平台视图额外传入平台 key，让 preview.mjs 只输出该平台的状态
+  function previewCmdFor(key) {
+    const base = `node ${previewPath} {2} {3} {5} {6}`
+    return key === 'skill' ? base : `${base} ${key}`
+  }
+
+  // ctrl-t 循环切换：根据当前 prompt 找到下一个视图，reload 对应文件、更新 prompt 和 preview 命令
+  const cycleCases = viewKeys.map((key, i) => {
+    const next = viewKeys[(i + 1) % viewKeys.length]
+    return `"${platformPrompt(key)}") echo "reload(cat ${viewFiles[next]})+change-prompt(${platformPrompt(next)})+change-preview(${previewCmdFor(next)})" ;;`
+  }).join('\n')
+  const cycleScript = `case "$FZF_PROMPT" in\n${cycleCases}\nesac`
+
+  // ctrl-u：仅在单平台视图下生效，一键升级该平台上所有已装 skill（user scope），完成后刷新当前视图
+  const upgradeAllCases = viewKeys.map(key => {
+    if (key === 'skill') return `"${platformPrompt(key)}") echo "" ;;`
+    const upgradeCmd = `node ${selfPath} upgrade --target ${key} --scope user${pauseCmd}`
+    return `"${platformPrompt(key)}") echo "execute(${upgradeCmd})+reload(node ${selfPath} __fzf-view ${key})" ;;`
+  }).join('\n')
+  const upgradeAllScript = `case "$FZF_PROMPT" in\n${upgradeAllCases}\nesac`
+
+  // ctrl-g：任意视图下，把光标所在的 skill 升级到它已安装的所有平台（user scope），完成后刷新当前视图
+  const upgradeSkillScript = `if [ {5} = skill ]; then key=$(echo "$FZF_PROMPT" | awk '{print $1}'); echo "execute(node ${selfPath} upgrade --skill {2}${pauseCmd})+reload(node ${selfPath} __fzf-view $key)"; else echo ""; fi`
+
+  let result
+  try {
+    result = spawnSync('fzf', [
+      '--multi',
+      '--ansi',
+      '--delimiter=\t',
+      '--with-nth=1',
+      `--prompt=${platformPrompt('skill')}`,
+      `--header=${COMBINED_HEADER}`,
+      '--layout=reverse',
+      '--border=rounded',
+      '--color=header:italic:dim,prompt:cyan,pointer:cyan,hl:cyan,hl+:cyan:bold',
+      `--preview=node ${previewPath} {2} {3} {5} {6}`,
+      '--preview-window=right:42%:wrap',
+      `--bind=ctrl-t:transform:${cycleScript}`,
+      `--bind=ctrl-u:transform:${upgradeAllScript}`,
+      `--bind=ctrl-g:transform:${upgradeSkillScript}`,
+    ], {
+      input: skillViewInput,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'inherit'],
+    })
+  } finally {
+    for (const file of Object.values(viewFiles)) {
+      try { unlinkSync(file) } catch { /* ignore */ }
+    }
+  }
+
   if (result.status !== 0 || !result.stdout.trim()) return []
 
   return result.stdout.trim().split('\n').map(line => {

package/bin/preview.mjs

@@ -11,6 +11,7 @@ const skillName        = process.argv[2]?.trim()
 const availableVersion = process.argv[3]?.trim() || '—'
 const kind             = process.argv[4]?.trim()
 const srcPath          = process.argv[5]?.trim()
+const platformKey      = process.argv[6]?.trim() || null
 
 const G = '\x1b[32m', Y = '\x1b[33m', D = '\x1b[2m', R = '\x1b[0m', B = '\x1b[1m'
 
@@ -73,9 +74,7 @@ function statusLine(version, status) {
   return ver + '  ' + D + '— not installed' + R
 }
 
-const userTargets    = SKILL_TARGETS
-const projectTargets = SKILL_TARGETS.filter(t => !USER_ONLY_TARGETS.has(t))
-const home    = os.homedir()
+const home = os.homedir()
 
 function checkScope(targets, dirFn) {
   return targets.map(t => {
@@ -87,6 +86,38 @@ function checkScope(targets, dirFn) {
   })
 }
 
+// 单平台视图：只展示 ctrl-t 当前所在平台的状态，不展示全平台矩阵
+if (platformKey && SKILL_TARGETS.includes(platformKey)) {
+  const cwd = process.cwd()
+  const userDir    = path.join(home, `.${platformKey}`, 'skills')
+  const projectDir = path.join(cwd, `.${platformKey}`, 'skills')
+  const [userDetail]    = checkScope([platformKey], () => userDir)
+  const projectDetail   = USER_ONLY_TARGETS.has(platformKey) || cwd === home
+    ? { version: '—', status: 'none' }
+    : checkScope([platformKey], () => projectDir)[0]
+
+  console.log(B + skillName + R)
+  console.log(D + 'available: ' + R + availableVersion)
+  console.log('')
+
+  console.log(B + platformKey.toUpperCase() + ' STATUS' + R)
+  console.log('  ' + 'user'.padEnd(8)    + statusLine(userDetail.version, userDetail.status))
+  console.log('  ' + 'project'.padEnd(8) + statusLine(projectDetail.version, projectDetail.status))
+  console.log('')
+
+  if (userDetail.status === 'update' || projectDetail.status === 'update') {
+    console.log(Y + 'ACTION: update → ' + platformKey + R)
+  } else if (userDetail.status === 'none' && projectDetail.status === 'none') {
+    console.log(D + 'STATUS: not installed' + R)
+  } else {
+    console.log(G + 'STATUS: ok' + R)
+  }
+  process.exit(0)
+}
+
+const userTargets    = SKILL_TARGETS
+const projectTargets = SKILL_TARGETS.filter(t => !USER_ONLY_TARGETS.has(t))
+
 const cwd = process.cwd()
 const userDetails    = checkScope(userTargets,    t => path.join(home, `.${t}`, 'skills'))
 const projectDetails = cwd === home

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {

package/skills/coding/explain-pm/SKILL.md

@@ -1,23 +1,32 @@
 ---
 name: explain-pm
-description: "Restate a recent technical explanation in product-manager language: translate jargon into user/business impact, and flag product-perspective concerns like scope, over-engineering, priority, or drift from user need. Triggers: '/explain-pm', '/explain-pm <topic or file>', 'explain this like a PM', 'restate from a PM perspective'."
+description: "Restate a recent technical explanation from a product-manager's analytical lens — user experience, product philosophy, execution mechanics, and architectural health — rather than translating jargon, and flag product-perspective concerns like scope, over-engineering, priority, or drift from user need. Triggers: '/explain-pm', '/explain-pm <topic or file>', 'explain this like a PM', 'restate from a PM perspective'."
 user_invocable: true
-version: "1.0.0"
+version: "1.1.1"
 ---
 
 # explain-pm — PM 视角复述
 
-把一段技术性表述从 PM 视角复述：先转译成产品/业务语言，再视情况指出值得从产品角度重新考虑的地方。
+把一段技术性表述从 PM 视角复述：换成 PM 关注的分析维度，再视情况指出值得从产品角度重新考虑的地方。
 
 ## 触发
 
 仅手动调用：`/explain-pm` 或 `/explain-pm <主题或文件路径>`。不自动检测触发，不主动插话。
 
+## PM 视角的关注维度
+
+不是语言转译——PM 本身熟悉基础技术语言。要转换的是关注点：
+
+- **用户体验**：这个决定最终会让用户感受到什么变化？
+- **产品哲学**：是否符合产品一贯的取舍和原则？
+- **执行机制与流程**：具体怎么落地——谁来做、分几步、影响什么协作节奏？
+- **架构健康度（次要）**：是否有明显的技术债或长期维护风险，只做提醒，不展开实现细节本身。
+
 ## 执行
 
 1. **取材料**：带参数用参数指定的主题或文件；无参数则取调用前的最后一条 assistant 消息。
-2. **转译**：把技术语言换成产品/业务语言——这段话讲给 PM 听，PM 听到的是什么（用户能得到什么、解决了什么问题、有什么代价）。
-3. **提出关注点（视情况）**：判断原表述从 PM 角度是否有值得重新审视的地方，比如是否偏离用户实际需求、范围是否合理、是否过度工程化、优先级是否搞错了。如果原表述本身已经很贴近产品目标，挑不出问题，就只做转译，不硬造关注点。
+2. **换视角**：对照上面的关注维度重新审视材料——不必在回复里逐条列出，只是分析时的参考。
+3. **提出关注点（视情况）**：判断原表述从 PM 角度是否有值得重新审视的地方，比如是否偏离用户实际需求、范围是否合理、是否过度工程化、优先级是否搞错了。如果原表述本身已经很贴近产品目标，挑不出问题，就只做视角复述，不硬造关注点。关注点如果成立，放在回复最后，不要打断前面的视角复述。
 4. **输出**：在对话中直接回复，简短（几句话量级）。默认不写文件；仅当用户明确要求存档时，才把这段评论写入用户指定的文件。
 
 ## 不做

package/skills/coding/init-workflow/references/acceptance-test.md

@@ -60,14 +60,23 @@ rm -f /tmp/gwi-test-msg-${TIMESTAMP}.txt
 
 取 `push_rules.block_force_push` 第一个分支名作为 `PROTECTED_PUSH_BRANCH`。
 
+`pre-push/force-push` 块用 `git merge-base --is-ancestor` 判断非 fast-forward，因此必须用真实存在于仓库历史中的两个 commit 来构造"远端不是本地祖先"的场景，不能用假造的 SHA 字符串（假 SHA 在真实仓库里既不是祖先也不是非祖先，`git merge-base` 会因对象不存在报错，不代表 force push 语义）。用当前 `HEAD` 作为 remote_sha、`HEAD~1` 作为 local_sha：remote（较新）不是 local（较旧）的祖先，等价于历史被回退重写。仓库只有一个提交（无 `HEAD~1`）时跳过此场景。
+
 ```bash
-output=$(printf "refs/heads/%s abc1234 refs/heads/%s 0000000000000000000000000000000000000000\n" \
-    "$PROTECTED_PUSH_BRANCH" "$PROTECTED_PUSH_BRANCH" \
-    | sh .githooks/pre-push 2>&1)
-exit_code=$?
+if git rev-parse -q --verify HEAD~1 >/dev/null 2>&1; then
+    REMOTE_SHA=$(git rev-parse HEAD)
+    LOCAL_SHA=$(git rev-parse HEAD~1)
+    output=$(printf "refs/heads/%s %s refs/heads/%s %s\n" \
+        "$PROTECTED_PUSH_BRANCH" "$LOCAL_SHA" "$PROTECTED_PUSH_BRANCH" "$REMOTE_SHA" \
+        | sh .githooks/pre-push 2>&1)
+    exit_code=$?
+    SKIPPED=0
+else
+    SKIPPED=1
+fi
 ```
 
-**期望：** `exit_code = 1`。
+**期望：** 仓库提交数 ≥ 2 时 `exit_code = 1`；仅有一个提交时标记为 SKIP，不计入 PASS/FAIL。
 
 ---
 
@@ -114,7 +123,13 @@ pre-push      force push 到 <branch>（应拒绝）         PASS ✅
 pre-push      非法 tag 推送（应拒绝）                  PASS ✅
 post-checkout 不合规分支名（应有 ⚠️ 警告）             PASS ✅
 ──────────────────────────────────────────────────────
-✅ 全部通过（N/N）。继续 Step 7...
+✅ 全部通过（N/N，SKIP 不计入分母）。继续 Step 7...
+```
+
+若 force push 场景因仓库只有一个提交被跳过，对应行显示：
+
+```
+pre-push      force push 到 <branch>（应拒绝）         SKIP ⏭️（仓库提交数 < 2，无法构造历史）
 ```
 
 若有失败：

package/skills/coding/init-workflow/references/hook-templates.md

@@ -93,9 +93,22 @@ SUBJECT=$(printf '%s\n' "$SUBJECT" | sed '/^#/d' | sed 's/^[[:space:]]*//')
 ```
 
 **格式检查 MANAGED 块（`commit-msg/format`）：**
+块内首行固定豁免合并提交（`MERGE_HEAD` 存在即视为合并提交，直接放行，不做格式/长度校验）：
+```sh
+# --- BEGIN MANAGED: commit-msg/format (hash:<hash>) ---
+[ -f "$(git rev-parse --git-dir)/MERGE_HEAD" ] && exit 0
+if ! printf '%s\n' "$SUBJECT" | grep -qE "<pattern>"; then
+    echo "❌ 提交信息不符合 Conventional Commits 规范"
+    ...
+    exit 1
+fi
+# --- END MANAGED: commit-msg/format ---
+```
 - `format: conventional`：将 `types` 列表拼接为正则 `^(feat|fix|...)(\(.+\))?: .+`；`require_scope: false` 时 scope 部分为可选 `(\(.+\))?`
 - `format: regex`：使用配置的 `pattern` 字段直接作为 grep 表达式
 
+若不豁免合并提交，git 默认生成的 "Merge branch '...'" 信息永远无法通过 Conventional Commits 校验；而若强行要求合并提交也写成 conventional 格式，pre-commit 中 `merge_source_branch()` 依赖 git 默认 `MERGE_MSG` 文本解析来源分支，自定义信息会导致解析失败。豁免合并提交让两个 hook 同时成立。
+
 **长度检查 MANAGED 块（`commit-msg/length`）：**
 ```sh
 # --- BEGIN MANAGED: commit-msg/length (hash:<hash>) ---
@@ -145,15 +158,23 @@ while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
 # --- BEGIN MANAGED: pre-push/force-push (hash:<hash>) ---
         refs/heads/main|refs/heads/staging)
             if [ "$local_sha" = "0000000000000000000000000000000000000000" ]; then
-                echo "❌ 禁止 force push 到受保护分支：$remote_ref"
+                echo "❌ 禁止删除受保护分支：$remote_ref"
                 exit 1
             fi
+            if [ "$remote_sha" != "0000000000000000000000000000000000000000" ]; then
+                if ! git merge-base --is-ancestor "$remote_sha" "$local_sha" 2>/dev/null; then
+                    echo "❌ 禁止强制推送到受保护分支：$remote_ref"
+                    exit 1
+                fi
+            fi
             ;;
 # --- END MANAGED: pre-push/force-push ---
 ```
 
 `refs/heads/main|refs/heads/staging` 从 `push_rules.block_force_push` 列表动态生成。
 
+`local_sha` 全零表示删除远端分支，与 force push 是两码事，单独拦截并报出不同的提示。真正的非 fast-forward（force push）检测用 `git merge-base --is-ancestor "$remote_sha" "$local_sha"`：若远端当前 SHA 不是本地待推送 SHA 的祖先，说明历史被重写，即 force push；`remote_sha` 全零（推送全新分支）时跳过该判断，因为此时没有旧历史可比较。
+
 **固定尾部：**
 ```sh
     esac