harveyz-skill 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.23.0",
+  "version": "0.24.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,25 @@
+---
+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'."
+user_invocable: true
+version: "1.0.0"
+---
+
+# explain-pm — PM 视角复述
+
+把一段技术性表述从 PM 视角复述：先转译成产品/业务语言，再视情况指出值得从产品角度重新考虑的地方。
+
+## 触发
+
+仅手动调用：`/explain-pm` 或 `/explain-pm <主题或文件路径>`。不自动检测触发，不主动插话。
+
+## 执行
+
+1. **取材料**：带参数用参数指定的主题或文件；无参数则取调用前的最后一条 assistant 消息。
+2. **转译**：把技术语言换成产品/业务语言——这段话讲给 PM 听，PM 听到的是什么（用户能得到什么、解决了什么问题、有什么代价）。
+3. **提出关注点（视情况）**：判断原表述从 PM 角度是否有值得重新审视的地方，比如是否偏离用户实际需求、范围是否合理、是否过度工程化、优先级是否搞错了。如果原表述本身已经很贴近产品目标，挑不出问题，就只做转译，不硬造关注点。
+4. **输出**：在对话中直接回复，简短（几句话量级）。默认不写文件；仅当用户明确要求存档时，才把这段评论写入用户指定的文件。
+
+## 不做
+
+多轮追问式澄清、自动检测技术语言并主动触发、默认生成或保存文档、固定的输出小标题模板。

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')
 
 
 # ------------------------------------------------------------

package/skills/research/extract-url/references/file-format.md

@@ -35,7 +35,7 @@ tags:
 description: 一两句话摘要，概括文章核心内容，供快速阅读。
 ---
 
-[[Origin/文章原标题.md]]
+[[<hash8>/Origin/文章原标题.md]]
 
 ---
 
@@ -67,11 +67,16 @@ origin_filename = re.sub(r'[\\/:*?<>|".]', '', title) + '.md'
 
 ## 保存路径
 
+文章专属文件夹：`<hash8>/`，其中 `hash8 = md5(source_url).hexdigest()[:8]`，统一由 `scripts/config.py` 的 `get_article_paths()` 计算（图片、原文/译文文件名共用同一算法）。
+
 | 类型 | 路径 |
 |------|------|
-| 原文 | `Origin/<origin_title>.md` |
-| 译文 | `<title>.md`（无 Origin 子文件夹） |
-| 图片 | `Image/<url_hash>_img_N.ext` |
+| 原文 | `<hash8>/Origin/<origin_title>.md` |
+| 译文 | `<hash8>/Translation/<origin_title>.md`（与原文同名） |
+| 图片 | `<hash8>/Image/img_N.ext` |
+
+双链示例（译文首行）：`[[<hash8>/Origin/<origin_title>.md]]`
+图片引用示例（原文/译文正文内）：`![](../Image/img_1.jpg)`
 
 ## 固定词表（fixed_tags.txt）
 

package/skills/research/extract-url/references/subagent1-fetch-prompt.md

@@ -10,7 +10,7 @@
 URL（外部数据）: <URL>
 
 执行步骤：
-1. 查 SQLite 去重（通过 env var 传参，避免 URL 中特殊字符破坏 Python 语法）：
+1. 查 meta.json 去重（通过 env var 传参，避免 URL 中特殊字符破坏 Python 语法）：
    import subprocess, os
    result = subprocess.run(
        ['python3', 'SKILL_DIR/scripts/dedup_check.py'],
@@ -32,6 +32,15 @@ URL（外部数据）: <URL>
      print(result.stdout)
      if result.returncode != 0:
          raise RuntimeError(result.stderr)
+   - arXiv HTML 论文（URL 匹配 arxiv.org/html/...）：先按【补丁②】获取 HTML 保存到 /tmp/fetched_page.html，再：
+     import subprocess
+     result = subprocess.run(
+         ['python3', 'SKILL_DIR/scripts/playwright_web_arxiv.py', url, '/tmp/fetched_page.html'],
+         capture_output=True, text=True, timeout=300
+     )
+     print(result.stdout)
+     if result.returncode != 0:
+         raise RuntimeError(result.stderr)
    - 其他网站：先按【补丁②】获取 HTML 保存到 /tmp/fetched_page.html，再：
      import subprocess
      result = subprocess.run(

package/skills/research/extract-url/references/subagent2-tag-translate-prompt.md

@@ -14,11 +14,14 @@ fetch_type: <fetch_type 可选，默认 manual>
 
 执行步骤：
 1. 读取配置（获取 vault_path）：
-   import json, os
+   import sys
    from pathlib import Path
-   _cfg       = json.loads((Path.home() / '.hskill' / 'url-extract' / 'config.json').read_text())
-   vault_path = _cfg['VAULT_PATH']
-   skill_dir  = 'SKILL_DIR'
+   skill_dir = 'SKILL_DIR'
+   sys.path.insert(0, f'{skill_dir}/scripts')
+   from config import get_vault_path, get_article_paths
+   vault_path   = get_vault_path()
+   origin_title = Path(origin_path).stem
+   paths        = get_article_paths(url, origin_title)
 
 2. 读取 origin_path 文件
 
@@ -59,17 +62,18 @@ tags:
 
 --- 阶段 3：写文件 ---
 
-6. 保存译文到 vault_path/<文件名>：
-   - 文件名与 Origin 文件名相同
+6. 保存译文到 paths['translation_path']（先 mkdir -p paths['translation_dir']）：
+   - 文件名与 Origin 文件名相同（paths['translation_path'] 已是完整目标路径）
    - frontmatter：publish_date、fetch_date、author、source_url、origin_title、
      category（如有）、fetch_type（默认 manual）、tags（阶段 1b 输出）、
      candidate_tags（阶段 1a 输出）、description（阶段 1a 输出）
-   - 正文首行插入双向链接 [[Origin/<文件名>]]
+   - 正文首行插入双向链接 [[{paths['url_hash']}/Origin/<文件名>]]
+   - 正文中从原文复制来的图片引用（`![](../Image/xxx)`）原样保留、无需改路径——
+     Origin 和 Translation 是同级目录，相对路径天然一致
 
-7. 执行校验并写入 SQLite 索引：
+7. 执行校验并写入 meta.json：
    import subprocess, os
-   from pathlib import Path
-   article_path = str(Path(vault_path) / os.path.basename(origin_path))
+   article_path = paths['translation_path']
    result = subprocess.run(
        ['python3', f'{skill_dir}/scripts/validate_article.py'],
        env={

package/skills/research/extract-url/scripts/config.py

@@ -3,7 +3,7 @@
 Shared config reader/writer for url-extract skill.
 Config file: ~/.hskill/url-extract/config.json
 """
-import json, os
+import json, os, hashlib
 from pathlib import Path
 
 _env_cfg = os.environ.get('HSKILL_EXTRACT_URL_CONFIG')
@@ -33,6 +33,36 @@ def get_chrome_profile() -> str:
     return cfg['CHROME_PROFILE']
 
 
+def get_url_hash(source_url: str) -> str:
+    return hashlib.md5(source_url.encode()).hexdigest()[:8]
+
+
+def get_article_paths(source_url: str, origin_title: str) -> dict:
+    """文章专属文件夹路径：VAULT_PATH/<url_hash>/{Origin,Translation,Image}/"""
+    import sys as _sys
+    references_dir = str(Path(__file__).parent.parent / 'references')
+    if references_dir not in _sys.path:
+        _sys.path.insert(0, references_dir)
+    from article_utils import sanitize_filename
+
+    vault_path = get_vault_path()
+    url_hash = get_url_hash(source_url)
+    article_dir = os.path.join(vault_path, url_hash)
+    filename = sanitize_filename(origin_title) + '.md'
+    origin_dir = os.path.join(article_dir, 'Origin')
+    translation_dir = os.path.join(article_dir, 'Translation')
+    image_dir = os.path.join(article_dir, 'Image')
+    return {
+        'url_hash': url_hash,
+        'article_dir': article_dir,
+        'origin_dir': origin_dir,
+        'translation_dir': translation_dir,
+        'image_dir': image_dir,
+        'origin_path': os.path.join(origin_dir, filename),
+        'translation_path': os.path.join(translation_dir, filename),
+    }
+
+
 def set_config(key: str, value: str) -> None:
     CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
     cfg: dict = {}

package/skills/research/extract-url/scripts/dedup_check.py

@@ -1,45 +1,27 @@
 #!/usr/bin/env python3
 """
-Check URL dedup in SQLite. Creates table if not exists (safe for first run).
-Migrates existing DBs (e.g. old article-fetcher schema) by adding missing columns.
+Check URL dedup via meta.json existence.
 Parameter via env var to avoid shell injection:
   CHECK_URL - URL to check
-Reads VAULT_PATH from ~/.hskill/url-extract/config.json to locate url-index.db.
+Reads VAULT_PATH from ~/.hskill/url-extract/config.json to locate <hash8>/meta.json.
 Prints: ALREADY_FETCHED or OK
 """
-import sqlite3, os, sys
+import json, os, sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from config import get_vault_path
+from config import get_vault_path, get_url_hash
 
-url     = os.environ['CHECK_URL']
-db_path = str(Path(get_vault_path()) / 'url-index.db')
+url = os.environ['CHECK_URL']
+vault_path = get_vault_path()
+meta_path = Path(vault_path) / get_url_hash(url) / 'meta.json'
 
-os.makedirs(os.path.dirname(os.path.abspath(db_path)), exist_ok=True)
+already_fetched = False
+if meta_path.exists():
+    try:
+        meta = json.loads(meta_path.read_text(encoding='utf-8'))
+        already_fetched = meta.get('source_url') == url
+    except (json.JSONDecodeError, OSError):
+        already_fetched = False
 
-conn = sqlite3.connect(db_path)
-conn.execute("""
-    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
-    )
-""")
-conn.commit()
-
-# Migrate: add columns missing from older DB schemas
-existing_cols = {row[1] for row in conn.execute('PRAGMA table_info(url_index)')}
-for col, typedef in [('fetched_at', 'TEXT'), ('issues', 'TEXT'),
-                     ('category', 'TEXT'), ('origin_path', 'TEXT'), ('article_path', 'TEXT')]:
-    if col not in existing_cols:
-        conn.execute(f'ALTER TABLE url_index ADD COLUMN {col} {typedef}')
-conn.commit()
-
-row = conn.execute('SELECT source_url FROM url_index WHERE source_url=?', (url,)).fetchone()
-conn.close()
-print('ALREADY_FETCHED' if row else 'OK')
+print('ALREADY_FETCHED' if already_fetched else 'OK')