harveyz-skill 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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
+- `extract-url`：用 per-article `meta.json` 索引替代 SQLite 索引，`article_utils`/`dedup_check`/`playwright_web(_arxiv)`/`playwright_xcom`/`validate_article` 全部切换到 meta.json 读写；提供旧数据迁移脚本（写 meta.json + 清理遗留文件）
+- `pdf-math-translate`：从其他项目贡献到 `research` bundle 的 PDF 数学翻译 skill
+- `explain-pm`：新增 skill，注册到 `coding` bundle
+- `rephrase`：新增 skill，单次改写用户陈述以提升精确度
+
+### Fixed
+- `extract-url`：放宽翻译文章的 author/publish_date 校验规则
+- `question-me`：补充决策树格式中 label 字段的示例与一致性规则（v3.0.1）
+- `publish-skill` 审计：修正 `learn-skill`/`survey-skillrepo`/`init-skill` 三个 skill 历史遗留的 contentHash 记录错误（内容本身未变更）
+
+### Changed
+- `extract-url`：SKILL.md 与 subagent prompt 更新以适配 meta.json 索引；skills-index.json 同步更新 contentHash
+
 ## [0.23.0] - 2026-07-09
 
 ### 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.23.0",
+  "version": "0.25.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "skills/research/learn-paper/",
     "skills/research/extract-cognition/",
     "skills/research/probe-session/",
+    "skills/research/pdf-math-translate/",
     "skills/creative/capture-todo/",
     "skills/creative/capture-insight/",
     "skills/coding/init-workflow/",
@@ -31,6 +32,8 @@
     "skills/coding/init-goal/",
     "skills/coding/question-me/",
     "skills/coding/capture-vocab/",
+    "skills/coding/rephrase/",
+    "skills/coding/explain-pm/",
     "skills/writing/forge-doc/",
     "skills/writing/draw-diagram/",
     "skills/writing/manage-dir/",

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

@@ -0,0 +1,34 @@
+---
+name: explain-pm
+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.1.1"
+---
+
+# explain-pm — PM 视角复述
+
+把一段技术性表述从 PM 视角复述：换成 PM 关注的分析维度，再视情况指出值得从产品角度重新考虑的地方。
+
+## 触发
+
+仅手动调用：`/explain-pm` 或 `/explain-pm <主题或文件路径>`。不自动检测触发，不主动插话。
+
+## PM 视角的关注维度
+
+不是语言转译——PM 本身熟悉基础技术语言。要转换的是关注点：
+
+- **用户体验**：这个决定最终会让用户感受到什么变化？
+- **产品哲学**：是否符合产品一贯的取舍和原则？
+- **执行机制与流程**：具体怎么落地——谁来做、分几步、影响什么协作节奏？
+- **架构健康度（次要）**：是否有明显的技术债或长期维护风险，只做提醒，不展开实现细节本身。
+
+## 执行
+
+1. **取材料**：带参数用参数指定的主题或文件；无参数则取调用前的最后一条 assistant 消息。
+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

package/skills/coding/question-me/SKILL.md

@@ -2,7 +2,7 @@
 name: question-me
 description: "Pre-task clarification skill — clarifies ambiguous or complex tasks before execution through structured Q&A with a live decision tree. One question at a time, each with at least 3 options + custom, in decision-dependency order. Triggers: '/question-me', 'help me clarify this', 'question me before starting', 'let's define this first'. Claude auto-triggers when detecting ambiguous or complex requests (multiple conflicting goals, vague keywords like 'optimize/refactor/clean up', missing success criteria, unstated context assumptions)."
 user_invocable: true
-version: "3.0.0"
+version: "3.0.1"
 ---
 
 # question-me — 执行前指令澄清

package/skills/coding/rephrase/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: rephrase
+description: "Single-pass rephrasing of a user statement into a more precise, less ambiguous, more actionable version, then either auto-proceeds or asks for confirmation based on Claude's own reliability judgment. Triggers: '/rephrase', '/rephrase <statement>', 'rephrase this', 'help me restate this more precisely'."
+user_invocable: true
+version: "1.0.1"
+---
+
+# rephrase — 单轮改写澄清
+
+对用户的一句话表述做单轮改写，让它更精确、更少歧义、更可执行。不预设"合格表述"的标准或清单，由 Claude 依据当前语境自行判断。
+
+## 触发
+
+仅手动调用：`/rephrase` 或 `/rephrase <表述>`。不自动检测、不主动建议。多轮追问式澄清是 `question-me` 的职责，不是本 skill。
+
+## 执行
+
+1. **取待改写内容**：带参数用参数；无参数用用户上一条消息；两者都没有就直接问用户要表述。
+2. **改写**：消歧义、补全隐含主语/宾语、明确动作对象，视原文缺什么而定——原文已经清楚就不用大改，也不要顺手加原文没提的验收标准/范围。
+3. **判断可靠性**：不是看"改写里有没有任何未明说的假设"（几乎总有），而是看**猜错的代价**——如果涉及在多个同权重候选（哪个文件、哪个服务）里武断选一个，选错会做错事，判不可靠；如果只是无关紧要的实现细节、执行风险低、改错了也好回退，判可靠。
+4. **分支**：可靠 → 展示改写结果，直接执行，不等确认。不可靠 → 展示改写结果和存疑点，等用户确认要不要改。
+
+## 不做
+
+多轮追问式澄清、强制补充验收标准/范围边界、自动触发。

package/skills/research/extract-url/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: extract-url
-version: "2.3.4"
+version: "2.6.0"
 description: "Use when a user provides a URL and wants to save, archive, fetch, or translate content to the local Obsidian Vault — even with vague phrasing like 'save this article', 'translate and save', 'put this in obsidian', 'archive this'. Skip when user only wants a summary, pastes raw text without a URL, asks about a site's tech stack, or wants to extract/list URLs from a page without saving an article."
 user_invocable: true
 ---
@@ -73,30 +73,30 @@ ls ~/.hskill/url-extract/config.json 2>/dev/null && echo "EXISTS" || echo "NOT_F
 ## 路径变量（脚本自读 config.json，无需 Agent 传参）
 
 ```
-Config:   ~/.hskill/url-extract/config.json
-Base:     VAULT_PATH   (脚本从 config.json 读取)
-Origin:   VAULT_PATH/Origin
-Image:    VAULT_PATH/Image
-DB:       VAULT_PATH/url-index.db
-SkillDir: 平台固定值（见平台补丁）
+Config:      ~/.hskill/url-extract/config.json
+Base:        VAULT_PATH   (脚本从 config.json 读取)
+ArticleDir:  VAULT_PATH/<hash8>   (hash8 = md5(source_url)[:8]，由 scripts/config.py 的 get_article_paths() 统一计算)
+Origin:      ArticleDir/Origin
+Translation: ArticleDir/Translation
+Image:       ArticleDir/Image
+Meta:        ArticleDir/meta.json
+SkillDir:    平台固定值（见平台补丁）
 ```
 
 ---
 
-## URL 去重索引（SQLite）
+## URL 去重索引（meta.json）
 
-**数据库路径：** `VAULT_PATH/url-index.db`
+**索引路径：** `VAULT_PATH/<hash8>/meta.json`（`hash8` 由 URL 派生，去重时直接检查该路径是否存在，无需数据库）
 
-```sql
-CREATE TABLE IF NOT EXISTS url_index (
-    source_url   TEXT PRIMARY KEY,
-    title        TEXT,
-    fetched_at   TEXT,
-    issues       TEXT,
-    category     TEXT,
-    origin_path  TEXT,
-    article_path TEXT
-);
+```json
+{
+  "source_url": "https://example.com/article",
+  "title": "文章标题",
+  "category": "分类",
+  "fetched_at": "2026-07-17",
+  "issues": ""
+}
 ```
 
 ---
@@ -149,7 +149,7 @@ url_safe = re.sub(r'[\x00-\x1f\x7f]', '', url).strip()[:2048]
 ```
 ── 完成 ──────────────────────────────
 标题  《文章标题》
-路径  /Vault/Reading/article.md
+路径  /Vault/Reading/a1b2c3d4/Translation/article.md
 字符  12,345
 代码  3 段
 图片  8 张
@@ -169,7 +169,7 @@ url_safe = re.sub(r'[\x00-\x1f\x7f]', '', url).strip()[:2048]
 ```
 ── 部分完成 ───────────────────────────
 标题  《文章标题》
-路径  /Vault/Origin/article.md（仅原文）
+路径  /Vault/Reading/a1b2c3d4/Origin/article.md（仅原文）
 原因  翻译超时，原文已保存
 ──────────────────────────────────────
 ```

package/skills/research/extract-url/references/article_utils.py

@@ -1,8 +1,9 @@
 """
 共享工具函数：格式化 block、构建文章、修复 frontmatter
 """
-import re, os, json, sqlite3, yaml
+import re, os, json, yaml
 from datetime import datetime, timezone, timedelta
+from pathlib import Path
 
 # ------------------------------------------------------------
 # 公共常量
@@ -113,7 +114,7 @@ description: {description}
 # ------------------------------------------------------------
 # 4. repair_frontmatter: 自动修复 frontmatter 字段
 # ------------------------------------------------------------
-def repair_frontmatter(fp, url, defaults=None):
+def repair_frontmatter(fp, url, defaults=None, skip_remaining_fields=None):
     """
     尝试自动补全缺失字段，返回 (fm_dict, 修复了哪些字段, 剩余问题列表)
     """
@@ -236,35 +237,35 @@ def repair_frontmatter(fp, url, defaults=None):
         f.write(fm_str + content[m.end():])
 
     # 检查剩余问题
+    skip = set(skip_remaining_fields or ())
     for fld in ['publish_date', 'author', 'source_url']:
-        if not fm.get(fld, '').strip():
+        if fld not in skip and not fm.get(fld, '').strip():
             remaining.append(f'{fld}空')
-    if 'origin_title' not in fm or not fm.get('origin_title', '').strip():
+    if 'origin_title' not in skip and ('origin_title' not in fm or not fm.get('origin_title', '').strip()):
         remaining.append('origin_title空')
-    if 'description' not in fm or not fm.get('description', '').strip():
+    if 'description' not in skip and ('description' not in fm or not fm.get('description', '').strip()):
         remaining.append('description空')
 
     return fm, fixed, remaining
 
 
 # ------------------------------------------------------------
-# 5. record_issues: 写入 issues 字段
+# 5. record_fetch_issues: Subagent 1 阶段的问题写入临时文件，供 write_meta_json 合并
 # ------------------------------------------------------------
-def record_issues(url, issues_text, db_path=None):
-    """将 issues 写入 SQLite"""
-    if db_path is None:
-        raise ValueError("db_path is required")
-    conn = sqlite3.connect(db_path)
-    conn.execute('UPDATE url_index SET issues=? WHERE source_url=?',
-                 (issues_text, url))
-    conn.commit()
+def record_fetch_issues(issues_text, article_dir):
+    """将 Subagent 1 阶段校验问题写入 <article_dir>/.fetch_issues.tmp，供 write_meta_json 合并。"""
+    tmp_path = Path(article_dir) / '.fetch_issues.tmp'
+    if issues_text:
+        tmp_path.write_text(issues_text, encoding='utf-8')
+    elif tmp_path.exists():
+        tmp_path.unlink()
 
 
 # ------------------------------------------------------------
-# 6. write_url_index: 写入 SQLite url_index 表
+# 6. write_meta_json: 写入 <hash8>/meta.json
 # ------------------------------------------------------------
-def write_url_index(url, origin_path, article_path, db_path, category=''):
-    """Insert or replace a URL index entry after successful fetch+translate."""
+def write_meta_json(url, meta_path, article_path, category=''):
+    """Write (or overwrite) meta.json after successful fetch+translate, merging any pending fetch-stage issues."""
     fetch_date = datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d')
     fm = {}
     try:
@@ -277,14 +278,23 @@ def write_url_index(url, origin_path, article_path, db_path, category=''):
     except Exception:
         pass
     cat = category or (fm.get('category') or '')
-    conn = sqlite3.connect(db_path)
-    conn.execute(
-        "INSERT OR REPLACE INTO url_index "
-        "(source_url, title, fetched_at, issues, category, origin_path, article_path) "
-        "VALUES (?,?,?,?,?,?,?)",
-        (url, os.path.basename(article_path), fetch_date, '', cat, origin_path, article_path)
-    )
-    conn.commit()
+
+    meta_path = Path(meta_path)
+    meta_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_issues_path = meta_path.parent / '.fetch_issues.tmp'
+    issues = ''
+    if tmp_issues_path.exists():
+        issues = tmp_issues_path.read_text(encoding='utf-8').strip()
+        tmp_issues_path.unlink()
+
+    meta = {
+        'source_url': url,
+        'title': os.path.basename(article_path),
+        'category': cat,
+        'fetched_at': fetch_date,
+        'issues': issues,
+    }
+    meta_path.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding='utf-8')
 
 
 # ------------------------------------------------------------