harveyz-skill 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-06-16
+
+### Added
+- `learn-paper` skill：基于三遍阅读法的论文精读 skill（首次以 `read-paper` 命名引入，后改名为 `learn-paper`）
+- `init-skill` skill：从设计文档脚手架生成新 skill
+- `probe-chrome-session` skill（experiment bundle）：Chrome profile cookie/session 探测与注入，支持 per-domain 加载策略
+- `experiment` bundle：用于 staging 实验性 skill
+- `publish-skill` F8：基于内容哈希的版本号检查，hash mismatch 时自动 bump
+
+### Changed
+- `extract-vision`：overhaul 至 v1.2.0（PaddleOCR v3 API、lang options 修复）
+- `capture-insight`：通过 `~/.hskill` 配置保存到 Writing Agent project
+- release-profile.md 迁移到 `.hskill/release-project/`
+
+### Removed
+- 归档 `npm-release` skill（被 `release-project` 取代）
+- 退役 `p-launch` 与 `todo-tool`（被 `hub` 取代），移除对应测试
+
+### Fixed
+- `publish-skill`：audit 违规修复
+- `read-paper`：真实论文测试后发现的 5 个问题修复
+
 ## [0.17.1] - 2026-06-15
 
 ### Fixed

package/README.md

@@ -71,10 +71,10 @@ Shell 工具，安装到 `~/.local/bin/`。
 
 | 工具 | Bundle | 说明 |
 |------|--------|------|
-| **p-launch** | shell-tools | 交互式项目启动器 — 从多个目录中快速选择并跳转到项目 |
+| **hub** | tools | 开发者 OS — 项目管理 + git 状态 + 任务跟踪 |
 
 ```bash
-hskill install --tool p-launch
+hskill install --tool hub
 ```
 
 ---
@@ -94,7 +94,7 @@ hskill                          # 交互式选择安装
 hskill                                          # 交互式选择
 hskill install --bundle dev                     # 安装整个 bundle
 hskill install --skill git-workflow-init        # 安装单个 skill
-hskill install --tool p-launch                  # 安装 shell 工具
+hskill install --tool hub                       # 安装 shell 工具
 hskill list                                     # 查看可用 skill
 hskill update                                   # 更新到最新版
 hskill --help                                   # 查看帮助

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "prepack": "node scripts/generate-npmignore.js",
-    "test": "bats tests/ && cd tools/p-launch && python3 -m pytest tests/test_p_launch.py -v && cd ../.. && bash scripts/run-skill-tests.sh"
+    "test": "bats tests/ && bash scripts/run-skill-tests.sh"
   },
   "files": [
     "bin/",
@@ -34,6 +34,7 @@
     "skills/design/scout-brand/",
     "skills/design/build-style/",
     "skills/design/sync-design/",
+    "skills/meta/init-skill/",
     "skills/meta/analyze-skill/",
     "skills/meta/clean-git/",
     "skills/meta/archive-skill/",
@@ -42,8 +43,8 @@
     "skills/meta/publish-skill/",
     "skills/meta/runby-opencode/",
     "skills/meta/release-project/",
-    "tools/p-launch/",
-    "tools/todo-tool/",
+    "skills/experiment/probe-session/",
+    "skills/experiment/learn-paper/",
     "tools/hub/",
     "hooks/check-similar-branch/"
   ],

package/skills/creative/capture-insight/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: capture-insight
-version: "1.1.0"
+version: "2.0.0"
 user_invocable: true
-description: "Capture and record a fleeting insight or observation. Triggers immediately when the user expresses an observation, judgment, or idea — phrases like 'I noticed', 'just an observation', 'record this', 'insight', 'I have a judgment', or tossing out an opinionated thought. Distinct from 'I have an idea to execute' (that's a task). Clarifies the core with 2-3 quick Q&As, then saves to the insights/ folder. Trigger early — insights are fragile."
+description: "Capture and record a fleeting insight or observation. Triggers immediately when the user expresses an observation, judgment, or idea — phrases like 'I noticed', 'just an observation', 'record this', 'insight', 'I have a judgment', or tossing out an opinionated thought. Distinct from 'I have an idea to execute' (that's a task). Clarifies the core with 2-3 quick Q&As, then saves to the Writing Agent project's insights/ folder. Trigger early — insights are fragile."
 ---
 
 # Capture Insight
@@ -35,6 +35,33 @@ description: "Capture and record a fleeting insight or observation. Triggers imm
 
 ## 流程
 
+### 第〇步：确定写入项目路径
+
+在开始澄清前，先读取配置：
+
+```
+~/.hskill/capture-insight/config.json
+```
+
+**配置格式：**
+```json
+{ "writing_agent_path": "/path/to/writing-agent" }
+```
+
+**若配置文件不存在：**
+
+> "没找到 Writing Agent 项目配置。请确认项目路径（默认：`/Users/harveyzhang96/Projects/writing-agent`）？"
+
+用户确认后，创建目录并写入配置：
+```bash
+mkdir -p ~/.hskill/capture-insight
+echo '{"writing_agent_path": "/Users/harveyzhang96/Projects/writing-agent"}' > ~/.hskill/capture-insight/config.json
+```
+
+配置确认后，将 `writing_agent_path` 记为 `{project_path}`，insight 写入目标为 `{project_path}/insights/`。
+
+---
+
 ### 第一步：捕捉原始 insight
 
 用户说出 insight 后，**先用一句话复述你理解的核心**，让用户确认或纠正方向。这一步不算"问问题"，是对齐认知用的。
@@ -57,7 +84,7 @@ description: "Capture and record a fleeting insight or observation. Triggers imm
 澄清完成后：
 
 1. 给出一段 **insight 摘要**（3-5 句话），让用户确认是否准确捕捉到了核心
-2. 用户确认后，生成文件名并保存到 `insights/` 文件夹
+2. 用户确认后，生成文件名，按以下步骤写入 `{project_path}/insights/`
 
 ---
 
@@ -95,18 +122,73 @@ description: "Capture and record a fleeting insight or observation. Triggers imm
 
 ---
 
+## 写入 & Git 操作
+
+确认写入 `{project_path}/insights/YYYY-MM-DD-<slug>.md` 后：
+
+### 切换到 chore/insight 分支
+
+```bash
+cd {project_path}
+
+# 1. 记录当前分支
+ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# 2. 确定基准分支
+if git show-ref --verify --quiet refs/heads/staging; then
+  BASE_BRANCH=staging
+else
+  BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+                | sed 's@^refs/remotes/origin/@@' || echo "main")
+fi
+
+# 3. 切换到 chore/insight（不存在则从 BASE_BRANCH 创建）
+if git show-ref --verify --quiet refs/heads/chore/insight; then
+  git checkout chore/insight
+else
+  git checkout -b chore/insight "$BASE_BRANCH"
+fi
+```
+
+**非 git 仓库**：若 `{project_path}` 不在 git 仓库中，跳过 git 步骤，直接写入文件。
+
+### 写入文件
+
+将 insight 内容写入 `{project_path}/insights/YYYY-MM-DD-<slug>.md`。
+
+### 提交、合并、切回
+
+```bash
+cd {project_path}
+
+# 1. 在 chore/insight 上提交
+git add insights/YYYY-MM-DD-<slug>.md
+git commit -m "insight: add YYYY-MM-DD-<slug>"
+
+# 2. 合并到基准分支
+git checkout "$BASE_BRANCH"
+git merge --no-ff chore/insight -m "Merge chore/insight: YYYY-MM-DD-<slug>"
+
+# 3. 切回原分支
+git checkout "$ORIGINAL_BRANCH"
+```
+
+---
+
 ## 注意事项
 
 - **不要代替用户形成判断**。如果用户说"我觉得 XX 可能是个趋势"，摘要里写"你观察到 XX 可能是个趋势"，而不是"XX 是个重要趋势"。
 - **保留用户的语气和颗粒度**。用户用的是模糊语言（"感觉"、"好像"、"也许"），保存时也保留这种不确定性，不要帮他们"升级"成确定性判断。
 - **简洁优先**。insight 文件不是分析报告，核心价值是"快速找回当时的思路"，不是写详尽。
+- **无论从哪个项目触发，始终写入 Writing Agent 项目**。`{project_path}` 来自配置，不受当前工作目录影响。
 
 ---
 
 ## 保存后告诉用户
 
 ```
-✓ 已保存到 insights/YYYY-MM-DD-<slug>.md
+✓ 已保存到 {project_path}/insights/YYYY-MM-DD-<slug>.md
+  提交到 chore/insight，合并到 {BASE_BRANCH}，当前回到 {ORIGINAL_BRANCH}。
 
 [如果发现这个 insight 与现有文章方向相关，可以顺带一提，但不要主动推销"你可以写篇文章"]
 ```

package/skills/experiment/learn-paper/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: learn-paper
+version: "0.1.0"
+description: "Deep-read a single academic PDF in three passes: 5C structural orientation, full content extraction, and critical reconstruction. Each pass produces a standalone Markdown file. Triggers: 'read this paper', 'deep-read paper', 'analyze this paper', 'take notes on this PDF', 'summarize paper', or when user provides a PDF path and wants to understand its content."
+user_invocable: true
+---
+
+# read-paper
+
+三遍精读单篇 PDF 论文。每遍独立产出一个 Markdown 文件。
+
+底层方法论说明见 `docs/superpowers/specs/2026-06-16-read-paper-design.md`。
+
+---
+
+## 路径变量
+
+```
+ConfigPath: ~/.hskill/read-paper/config.json
+```
+
+---
+
+## 执行流程
+
+### Step 0：初始化配置
+
+用 Read 工具读取 `~/.hskill/read-paper/config.json`。
+
+若文件不存在，询问用户：
+
+```
+论文分析笔记保存到哪个目录？（直接回车使用默认：~/Documents/papers）
+```
+
+用户回复后，用 Bash 工具写入配置（路径必须用 `$HOME` 展开，不可写字面量 `~`）：
+
+```bash
+mkdir -p "$HOME/.hskill/read-paper"
+output_dir="${用户指定路径/#\~/$HOME}"
+echo "{\"output_dir\": \"$output_dir\"}" > "$HOME/.hskill/read-paper/config.json"
+```
+
+若文件已存在，解析 JSON 取出 `output_dir` 字段，并将其中可能残留的 `~` 展开为 `$HOME` 后使用：
+
+```bash
+output_dir=$(python3 -c "import json,os; d=json.load(open('$HOME/.hskill/read-paper/config.json')); print(d['output_dir'].replace('~', os.environ['HOME'], 1))")
+```
+
+---
+
+### Step 1：提取 PDF 路径，准备输出目录
+
+从用户消息中提取 PDF 文件路径（绝对路径或 `~` 开头路径均可）。
+
+**安全净化（在 Bash 中执行）：**
+
+```bash
+pdf_path=$(echo "<用户提供路径>" | tr -d '\000-\037\177' | xargs)
+pdf_path="${pdf_path/#\~/$HOME}"
+```
+
+**验证文件存在：**
+
+```bash
+test -f "$pdf_path" || { echo "ERROR: 文件不存在: $pdf_path"; exit 1; }
+```
+
+若不存在，报错并终止。
+
+**生成 paper slug：**
+
+取 PDF 文件名（去掉扩展名），将空格和特殊字符替换为 `-`，转小写。汉字保留原样：
+
+```bash
+filename=$(basename "$pdf_path" .pdf)
+slug=$(echo "$filename" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9一-鿿]/-/g' | sed -E 's/-+/-/g' | sed 's/^-//;s/-$//')
+```
+
+示例：`Attention Is All You Need.pdf` → `attention-is-all-you-need`
+
+**创建输出目录：**
+
+```bash
+mkdir -p "<output_dir>/$slug"
+```
+
+**解析 `--pass` 参数（若用户在触发消息中指定）：**
+
+| 参数 | 行为 |
+|------|------|
+| `--pass 1` | 只执行第一遍 |
+| `--pass 2` | 只执行第二遍，需检查 `1-orientation.md` 已存在 |
+| `--pass 3` | 只执行第三遍，需检查 `2-extraction.md` 已存在 |
+| 无参数 | 执行全部三遍 |
+
+**依赖检查（单遍模式）：**
+
+```bash
+# --pass 2
+test -f "<output_dir>/$slug/1-orientation.md" || { echo "请先运行 --pass 1 生成前置文件"; exit 1; }
+
+# --pass 3
+test -f "<output_dir>/$slug/2-extraction.md" || { echo "请先运行 --pass 2 生成前置文件"; exit 1; }
+```
+
+---
+
+### Step 2：第一遍 — 5C 定向
+
+**读取范围：**
+
+先读前 5 页获取标题、摘要、引言：
+
+```
+Read(file_path="<pdf_path>", pages="1-5")
+```
+
+再从论文末尾向前搜索结论章节（最多尝试 3 次，每次窗口 4 页）：
+
+**策略：** 先读最后 4 页，若未见"Conclusion"/"结论"/"Discussion"关键词，则继续向前读前 4 页，如此最多 3 次。
+
+```
+# 第 1 次：读最后 4 页
+Read(file_path="<pdf_path>", pages="<total-3>-<total>")
+
+# 若未找到，第 2 次：再往前 4 页
+Read(file_path="<pdf_path>", pages="<total-7>-<total-4>")
+
+# 若仍未找到，第 3 次：再往前 4 页
+Read(file_path="<pdf_path>", pages="<total-11>-<total-8>")
+```
+
+`<total>` 通过读第 1 页时 PDF 工具返回的总页数判断，或从前 5 页内容中的页码推断。找到结论即停，不继续往前读。
+
+**分析任务：**
+
+基于读取内容完成 5C 评估：
+
+| 维度 | 分析问题 |
+|------|----------|
+| **Category（类别）** | 测量类 / 系统描述 / 理论分析 / 综述 / 其他？ |
+| **Context（背景）** | 解决什么问题？与哪些已知工作相关？ |
+| **Correctness（正确性）** | 核心假设是否明确合理？有无明显漏洞？ |
+| **Contributions（贡献）** | 主要创新点是什么？ |
+| **Clarity（清晰度）** | 结构是否清晰？摘要是否准确概括内容？ |
+
+**产出文件，用 Write 工具写入 `<output_dir>/<slug>/1-orientation.md`：**
+
+```markdown
+# {论文标题} — 定向
+
+**作者**: {从首页提取}
+**年份**: {从首页提取}
+**来源**: {期刊/会议/arXiv，从首页提取}
+**PDF**: <pdf_path>
+**分析日期**: YYYY-MM-DD
+
+---
+
+## 5C 评估
+
+- **Category（类别）**: 
+- **Context（背景）**: 
+- **Correctness（正确性）**: 
+- **Contributions（贡献）**: 
+- **Clarity（清晰度）**: 
+
+---
+
+## 初步印象
+
+（2-3 句话：论文整体质量判断，是否值得继续第二遍精读）
+```
+
+写完后告知用户：`✓ 第一遍完成 → <output_dir>/<slug>/1-orientation.md`
+
+---
+
+### Step 3：第二遍 — 全文内容提取
+
+**读取策略（分段处理，每次最多 10 页）：**
+
+```
+Read(file_path="<pdf_path>", pages="1-10")
+Read(file_path="<pdf_path>", pages="11-20")
+...循环直到读完全文
+```
+
+每段读取后立即提取，不等全文读完再汇总（避免 context 溢出）。
+
+**终止条件：** 每段读取后检查是否出现 References / Bibliography / 参考文献 的独立章节标题（通常单独成行、后面紧跟编号列表）。一旦检测到，立即停止继续读取后续页面——References 之后已无需提取的正文内容。
+
+**每段提取内容：**
+
+- **核心论点**：该段提出的主要主张（用自己的语言转述，非直接引用）
+- **实验与数据**：数据集名称、评估指标、关键数值、与基线的对比结果
+- **方法步骤**：算法/架构/流程的关键步骤描述
+- **图表**：图/表编号 + 标题 + 核心结论（图像内容用 vision 解读）
+- **引用标记**：反复出现或支撑核心论点的参考文献编号
+
+**产出文件，用 Write 工具写入 `<output_dir>/<slug>/2-extraction.md`：**
+
+```markdown
+# {论文标题} — 内容提取
+
+**作者**: {从首页提取}
+**PDF**: <pdf_path>
+**分析日期**: YYYY-MM-DD
+
+---
+
+## 核心论点与证据
+
+（每条论点附支撑来源：实验数据 / 理论推导 / 引用）
+
+## 实验设计与结果
+
+- **数据集**: 
+- **评估指标**: 
+- **关键数值**: 
+- **与基线对比**: 
+
+## 方法论摘要
+
+（核心方法的步骤/架构/算法，用自己的语言重述，不直接抄论文）
+
+## 图表解读
+
+| 图/表 | 标题 | 核心结论 |
+|-------|------|----------|
+| Fig.1 | ... | ... |
+
+## 作者承认的局限
+
+（作者在 Limitation / Future Work 章节明确说明的不足，非推断）
+
+## 值得追踪的关键引用
+
+（反复出现或支撑核心论点的参考文献，记编号和推测主题）
+```
+
+写完后告知用户：`✓ 第二遍完成 → <output_dir>/<slug>/2-extraction.md`
+
+---
+
+### Step 4：第三遍 — 批判性重构
+
+**读取来源（不重读 PDF）：**
+
+```
+Read(file_path="<output_dir>/<slug>/2-extraction.md")
+```
+
+**分析任务（针对 2-extraction.md 中每条核心论点）：**
+
+1. **假设审计**：该论点依赖哪些隐含假设？论文是否明确说明了这些假设？
+2. **缺陷识别**：
+   - 实验是否缺少重要对照组？
+   - 结论是否超出实验结果可支撑的范围？
+   - 评估指标是否存在选择偏差？
+3. **对比已知工作**：与训练知识中的相关方法相比，声称的创新点是否成立？有无遗漏的重要基线对比？
+4. **延伸方向**：若要改进或扩展，最有价值的研究方向是什么？
+
+**诚实性标注规则（每条批判意见必须标注）：**
+
+- `[基于论文]` — 直接来自论文内容，可直接引用
+- `[Agent推断]` — 基于训练知识的判断，可能存在时效性或准确性问题
+- `[需核实]` — 需要查阅外部文献才能确认，不可直接引用
+
+**产出文件，用 Write 工具写入 `<output_dir>/<slug>/3-critique.md`：**
+
+```markdown
+# {论文标题} — 批判性重构
+
+**作者**: {从 2-extraction.md 复制}
+**PDF**: <pdf_path>
+**分析日期**: YYYY-MM-DD
+
+> **注意：** 标注 `[Agent推断]` 的内容基于训练知识，非论文原文，存在时效性限制，请独立核实后引用。
+
+---
+
+## 隐含假设清单
+
+（每条注明：论文是否明确说明 → 是/否）
+
+## 已识别缺陷
+
+（每条附来源标注：[基于论文] / [Agent推断] / [需核实]）
+
+## 与已知工作对比
+
+（[Agent推断] 标注，对比训练知识中的相关方法）
+
+## 开放问题 / 延伸方向
+
+（值得未来研究的方向，[基于论文] 或 [Agent推断] 标注）
+```
+
+写完后总结：
+
+```
+✓ 三遍分析完成
+
+  <output_dir>/<slug>/
+  ├── 1-orientation.md   ← 5C 定向
+  ├── 2-extraction.md    ← 内容提取
+  └── 3-critique.md      ← 批判性重构
+```

package/skills/experiment/probe-session/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: probe-session
+version: "0.3.0"
+description: "Validate whether Chrome Profile cookie injection works for a target URL. Runs Playwright twice — anonymous vs injected Chrome session — compares title and body to determine if injection succeeded. Triggers: test Chrome cookie injection, verify login state for a URL, debug extract-url authentication issues."
+user_invocable: true
+---
+
+# probe-chrome-session
+
+验证 Chrome Profile cookie 注入机制是否对目标 URL 生效。
+
+底层机制说明见 `docs/explanation/chrome-profile-cookie-injection.md`。
+
+---
+
+## 路径变量
+
+```
+ScriptDir: SKILL_DIR/scripts
+```
+
+---
+
+## 执行流程
+
+### 步骤 1：从用户消息中提取 URL
+
+从用户消息中提取目标 URL，做净化：
+
+```python
+import re
+url_safe = re.sub(r'[\x00-\x1f\x7f]', '', url).strip()[:2048]
+```
+
+### 步骤 2：列出 Chrome Profile，让用户选择
+
+运行 list_profiles.py，解析 JSON，格式化成编号列表展示给用户：
+
+```python
+import subprocess, json, sys
+result = subprocess.run(
+    ['python3', 'SKILL_DIR/scripts/list_profiles.py'],
+    capture_output=True, text=True, timeout=30
+)
+profiles = json.loads(result.stdout)
+```
+
+向用户展示如下格式，**等待用户回复编号**：
+
+```
+请选择要使用的 Chrome Profile：
+
+[1] Default  (harvey@gmail.com)          ★ X.com 已登录  ← 推荐
+[2] Profile 1  (other@gmail.com)           · 无 X.com 登录态
+[3] Profile 9  (dev@gmail.com)            ★ X.com 已登录
+```
+
+格式规则：
+- `has_xcom_auth: true` → 显示 `★ X.com 已登录`，列表中第一个标注「← 推荐」
+- `has_xcom_auth: false` → 显示 `· 无 X.com 登录态`
+- `error` 非空 → 显示 `⚠ 读取失败: {error}`
+
+根据用户输入的编号取对应条目的 `path` 字段，作为 `selected_profile`。
+
+### 步骤 3：运行探针脚本
+
+```python
+import subprocess, sys
+result = subprocess.run(
+    ['python3', 'SKILL_DIR/scripts/probe.py', url_safe, selected_profile],
+    capture_output=True, text=True, timeout=120
+)
+print(result.stdout)
+if result.returncode != 0:
+    print(result.stderr, file=sys.stderr)
+```
+
+### 步骤 4：向用户报告
+
+将脚本输出原样展示，并解读"结论"一行：
+
+- `Cookie 注入有效 ✓` → 机制正常，登录态成功注入
+- `Title 相同` → cookie 未生效或页面无需登录，需进一步排查
+- `未提取到任何 cookie` → 该 Profile 尚未在 Chrome 中登录目标网站
+
+---
+
+## 前提条件
+
+```bash
+pip install pycookiecheat playwright
+playwright install chromium
+```

package/skills/experiment/probe-session/data/strategies.json

@@ -0,0 +1,26 @@
+{
+  "x.com": {
+    "id": "dce+ni",
+    "wait_until": "domcontentloaded",
+    "post_wait": "networkidle",
+    "post_wait_ms": 8000,
+    "fallback_ms": 2000,
+    "desc": "domcontentloaded + networkidle(8s)"
+  },
+  "google.com": {
+    "id": "dce+ni",
+    "wait_until": "domcontentloaded",
+    "post_wait": "networkidle",
+    "post_wait_ms": 8000,
+    "fallback_ms": 2000,
+    "desc": "domcontentloaded + networkidle(8s)"
+  },
+  "github.com": {
+    "id": "dce+ni",
+    "wait_until": "domcontentloaded",
+    "post_wait": "networkidle",
+    "post_wait_ms": 8000,
+    "fallback_ms": 2000,
+    "desc": "domcontentloaded + networkidle(8s)"
+  }
+}