harveyz-skill 0.17.1 → 0.19.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-06-22
+
+### Added
+- `sync-agent`：Syncthing 多设备同步工具与 skill — REST API 客户端、launchd 安装、CLI（start/stop/status/setup）、运行时管理同步 folder/device、为含 `.gitignore` 的目录自动创建 `.stignore`
+- `hub`：TODO.md → SQLite 同步（启动时同步所有项目，ctrl+r 同步当前项目）；`hub git` CLI 子命令（status/fetch/branches）与 TUI 对等；`hub projects remove` 命令 + TUI ctrl+d 快捷键
+- `scout-philosophy`：skill 设计哲学研究 skill（meta bundle）
+- `extract-url`：代码块支持；付费墙站点 cookie 重试；`HSKILL_EXTRACT_URL_CONFIG` 环境变量覆盖配置路径
+- `learn-video`：新增字幕翻译步骤（translate_subs）
+
+### Changed
+- `learn-skill` → v2.0.0：报告持久化到全局 skill 库、四维度归纳式重构、新增 Step 4 跨 skill 索引摘要
+- `analyze-skill` → `survey-skillrepo`：重命名并移至 research bundle，泛化到任意 skill 仓库并集成 learn-skill
+- `extract-url`：重构为从 `~/.hskill/config.json` 读取配置，各脚本不再依赖位置参数
+- `init-skill`：迁移至 experiment bundle；description 移除中文以符合 F3；支持可切换参考标准用于 A/B 实验
+- `publish-skill`：新增 R4 installScope 检查与修复引导
+- 13 篇设计 spec 迁移为正式文档（hub、sync-agent、opencode、init-skill 等）
+- 修正多个 skill 内容哈希与版本号，并为 10 个 skill 补充 `installScope`
+
+### Fixed
+- `extract-url`：playwright_xcom 图片下载 SSL 验证、脚本路径/setup 顺序/超时/权限等修复
+- `hub`：TUI remove 行为与 CLI 对齐、footer category map、remove 快捷键改为 ctrl+d
+- `sync-agent`：平台感知的 Syncthing 配置路径（macOS/Linux）
+- `learn-skill`：audit findings 修复，移除 reference/script 200 行读取上限
+- 测试：survey-skillrepo fixture 版本同步至 2.0.1，修复 test_config.py 导入与 bats meta-bundle 断言
+
+## [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.19.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,7 +34,8 @@
     "skills/design/scout-brand/",
     "skills/design/build-style/",
     "skills/design/sync-design/",
-    "skills/meta/analyze-skill/",
+    "skills/experiment/init-skill/",
+    "skills/research/survey-skillrepo/",
     "skills/meta/clean-git/",
     "skills/meta/archive-skill/",
     "skills/meta/dedup-skill/",
@@ -42,8 +43,10 @@
     "skills/meta/publish-skill/",
     "skills/meta/runby-opencode/",
     "skills/meta/release-project/",
-    "tools/p-launch/",
-    "tools/todo-tool/",
+    "skills/meta/sync-agent/",
+    "skills/experiment/probe-session/",
+    "skills/experiment/learn-paper/",
+    "skills/meta/scout-philosophy/",
     "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/init-skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: init-skill
+description: "Initialize a new skill from scratch in the harveyz-skill repo — scaffolds SKILL.md, directory structure, and a feature branch from a design spec or free-form notes. Applies the condensed skill design standard (16 philosophies + system mechanisms). Triggers: 'create new skill', 'scaffold a skill', 'init skill', 'bootstrap skill from notes', 'create skill from spec', 'help me start a new skill', 'initialize a skill'."
+user_invocable: true
+version: "1.2.0"
+---
+
+# 从设计文档初始化新 Skill
+
+将设计文档（结构化 spec 或自由格式笔记）转化为符合规范的 SKILL.md，创建目录结构和功能分支，交棒给 `publish-skill` 完成注册。
+
+---
+
+## 触发条件
+
+触发本 skill：
+- "创建新 skill"、"初始化一个 skill"、"新建 skill"
+- "从这份 spec 生成 skill"、"help me start a new skill"
+- "scaffold skill"、"bootstrap skill"
+
+不触发（其他 skill 负责）：
+- 从其他项目**导入**已有 skill → 使用 `contribute-skill`
+- **校验格式或注册** index → 使用 `publish-skill`
+- **修改**已有 skill 内容 → 直接编辑对应 SKILL.md
+
+---
+
+## 参考标准
+
+本 skill 使用 `references/skill-standard.md` 作为单一标准——精简版（约 200 行），含 16 条设计哲学 + 系统机制 + 张力点。Step 2 加载该文件并对照检查。
+
+---
+
+## 执行流程（6 步）
+
+### Step 0 — 需求澄清
+
+在任何操作之前，确认以下信息是否完整：
+
+- **核心用途**：要创建的 skill 做什么？（哪怕一句话）
+- **设计文档**：是否有 spec 文件路径或可粘贴的描述？还是完全从对话出发？
+- **命名偏好**：是否有指定名称，或由 Claude 根据内容推断？
+
+澄清策略：
+- 每次只问一个问题，不堆叠
+- 上下文能推断的不再问
+- 持续提问直到需求完整、无歧义为止
+
+只有需求明确后才进入 Step 1。
+
+### Step 1 — 定位设计文档
+
+按优先级定位输入来源：
+
+1. 用户在对话中粘贴的描述文本 → 直接使用
+2. 用户指定的文件路径 → 用 Read 工具读取
+3. 自动扫描最近修改的 spec：
+   ```bash
+   ls -t docs/superpowers/specs/*.md | head -5
+   ```
+   列出候选文件供用户选择。
+
+### Step 2 — 提炼要素 + 标准检查
+
+**2a. 加载标准：** 用 Read 工具读取 `references/skill-standard.md`（精简版，约 200 行）。
+
+**2b. 提炼要素：** 从设计文档中提取以下字段：
+
+| 字段 | 提取值 | 规范约束 |
+|------|--------|---------|
+| `name` | `<verb>-<noun>` 格式 | 动词必须在标准词表中 |
+| `bundle` | 从现有 bundleMeta 中选 | 可新建 |
+| `description` | 英文，含触发短语 | ≥ 10 字符，仅英文 |
+| 正文大纲 | 中文，核心步骤列表 | — |
+| `category` 目录 | 对应 bundle 的目录名 | — |
+
+读取现有 bundle 列表：
+```bash
+node -e "const i=JSON.parse(require('fs').readFileSync('skills-index.json','utf8')); Object.entries(i.bundleMeta).forEach(([k,v])=>console.log(k+': '+v))"
+```
+
+**2c. 适用哲学识别：** 对照标准的 16 条哲学，识别本 skill 涉及的（通常 3–10 条）。每条按"触发"条件判断是否成立。
+
+**2d. 标准检查：** 逐条核对相关哲学的"必做"和"检查"项，输出：
+
+```
+[✓] Φ1 可回退      — 破坏性 step 前有 y/n 确认
+[✓] Φ5 配置就地    — 路径 .hskill/<name>/ 正确
+[!] Φ12 输入清洁化 — URL 输入缺少控制字符剥离，建议加 re.sub(...)
+```
+
+涉及多哲学冲突时查标准末尾"张力点"表消歧。
+
+**等用户明确确认后才进入 Step 3。**
+
+### Step 3 — 生成 SKILL.md
+
+根据确认后的要素，生成完整 SKILL.md，遵循以下结构：
+
+```
+---
+name: <name>
+description: "<英文，含触发短语列表>"
+user_invocable: true
+version: "1.0.0"
+---
+
+# <正文标题（中文）>
+
+## 触发条件
+（覆盖"触发"和"不触发"两种情况）
+
+## 执行步骤（Step 0 — Step N）
+
+### Step 0 — 需求澄清
+（如适用）
+
+### Step 1 — ...
+...
+
+## 不在范围内
+（2-4 条明确边界）
+```
+
+若 skill 有参考材料（查找表、模板、禁忌清单）且超过 20 行，按标准 Φ18 提取到 `references/` 子目录，而非全部内联在 SKILL.md 中。
+
+将生成内容展示给用户预览。**等用户明确确认后才进入 Step 4。**
+
+### Step 4 — 创建目录并写入文件
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+mkdir -p "${REPO_ROOT}/skills/<category>/<name>/"
+```
+
+若目标路径已存在：停止并报错，提示用户使用 `publish-skill` 更新已有 skill，不覆盖任何文件。
+
+用 Write 工具写入 `skills/<category>/<name>/SKILL.md`。
+
+### Step 5 — 创建功能分支并初始 commit
+
+执行前检查：
+```bash
+git status --short
+```
+若有未提交的修改（输出非空）：停止并提示用户先提交或暂存当前变更，再重新运行 Step 5。
+
+```bash
+git checkout -b feature/init-<name>
+git add skills/<category>/<name>/
+git commit -m "feat(skill): scaffold <name>"
+```
+
+输出摘要：
+```
+✓ SKILL.md 已生成：skills/<category>/<name>/SKILL.md
+✓ 分支：feature/init-<name>
+下一步：运行 /publish-skill 完成格式校验和 skills-index.json 注册
+```
+
+---
+
+## 不在范围内
+
+- 注册到 `skills-index.json`（由 `publish-skill` 负责）
+- 修改或更新已有 skill（目标路径已存在时直接报错）
+- 批量创建多个 skill（每次只处理一个）
+- 编写 skill 的实际业务逻辑（只生成符合规范的骨架）

package/skills/experiment/init-skill/references/skill-authoring-guide.md

@@ -0,0 +1,156 @@
+# Skill Authoring Guide
+
+init-skill 使用本文件作为生成新 skill 时的规范检查清单。内容分两类：**显性规范**（硬性要求，不符合则 publish-skill 报错）和**隐性模式**（从现有优质 skill 提炼的最佳实践）。
+
+---
+
+## 显性规范
+
+### 命名
+
+- 目录名格式：`<verb>-<noun>`（2 段，连字符分隔，全小写）
+- 动词必须在词表中：
+
+```
+extract  learn    forge    draw     manage   migrate  scout
+build    sync     publish  archive  contribute  analyze  clean
+release  validate init     dispatch close    setup    capture
+runby    dedup    survey
+```
+
+特殊：以 `runby-` 开头的目录直接视为合规。
+
+### Frontmatter 必填字段
+
+| 字段 | 要求 |
+|------|------|
+| `name` | 非空，值 == 目录名 |
+| `description` | 英文，≥ 10 字符，不含中文字符 |
+| `user_invocable` | 显式声明 `true` 或 `false` |
+| `version` | semver 格式 `X.Y.Z`，初始值 `"1.0.0"` |
+
+### description 格式
+
+```
+"<动词短语说明功能>. Triggers when <触发条件>. e.g. '<示例指令1>', '<示例指令2>'."
+```
+
+触发词宁宽勿窄，但要避免与现有 skill 触发场景重叠。举例比描述更精确。
+
+### 正文语言
+
+frontmatter 结束后的正文应为中文（含至少一个中文字符即合规）。
+
+---
+
+## 隐性模式
+
+### 正文结构
+
+推荐节顺序：**触发条件 → 执行步骤（Step N） → 边界说明（不在范围内）**
+
+- 每个 Step 对应一个可验证的原子操作，不要把两个动作塞进同一步
+- 边界说明必须有，明确列出 2-4 个常见误用场景，防止 skill 在对话中被过度扩展
+
+### 状态与配置
+
+**1. `.hskill/<skill-name>/` 配置缓存**（7 个 skill 使用此模式）
+
+有状态的 skill 将配置持久化到 `$HOME/.hskill/<skill-name>/`，每次运行 Step 1 先读此目录，未找到时落到默认值或询问用户。
+
+```
+clean-git → ~/.hskill/clean-git/branch-cleanup.md
+init-workflow → ~/.hskill/init-workflow/workflow-config.yml
+```
+
+**2. "读取配置"作为第一执行步骤**（6 个 skill 使用此模式）
+
+有状态 skill 的第一个实质步骤总是：检测配置文件存在性 → 不存在则用默认或询问 → 解析校验 → 才进入业务步骤。
+
+**3. Lock / snapshot 文件做变更检测**（3 个 skill 使用此模式）
+
+维护 `.lock` 或 manifest 快照，记录"上次运行状态"，实现 delta 操作（只处理变化部分）。
+
+```
+init-workflow → .githooks/.workflow-config.lock.yml
+sync-design → manifest.json 含 lastSyncCommit
+publish-skill → skills-index.json 中的 contentHash
+```
+
+**4. 多源配置覆盖链**（3 个 skill 使用此模式）
+
+多个配置源按固定顺序读取，后读优先级更高。明确注明"后读内容优先级更高"。
+
+### 错误处理与边界
+
+**5. "边界情况"表格放在步骤末尾**（5 个 skill 使用此模式）
+
+复杂多分支步骤末尾用表格列出所有边界条件和处理方式，便于一眼看全所有路径。
+
+```markdown
+| 情况 | 处理 |
+|------|------|
+| 目标路径已存在 | 停止报错，不覆盖 |
+| generate-npmignore.js 失败 | 报错，不执行 git 操作 |
+```
+
+**6. 冲突解决：批量收集，统一决策**（3 个 skill 使用此模式）
+
+出现冲突时，先收集所有冲突再分组展示，让用户一次性逐条决策。不要边发现边问。
+
+### 扩展与组合
+
+**7. references/ 承载平台/技术栈特定文档**（5 个 skill 使用此模式）
+
+Skill 顶层逻辑保持技术中立，平台/格式特定内容放进 `references/`，运行时按检测结果动态读取。扩展通过加文件而非改 SKILL.md。
+
+```
+setup-debug → references/tech-stacks/<stack>.md
+extract-url → platforms/SKILL.<platform>.md
+```
+
+阈值：references/ 内单文件 > 20 行时才提取；小内容直接内联。
+
+**8. Subagent 委派 + 变量注入**（2 个 skill 使用此模式）
+
+Skill 委派 subagent 时用环境变量注入运行时值（不是字符串拼接），并加载平台特定 patch 文件。
+
+### 输出格式
+
+**9. Emoji 与状态标记规范化**（5 个 skill 使用此模式）
+
+统一视觉符号：`✓` / `✅`（通过）、`⚠️`（注意）、`❌`（失败）、`━━━`（分组分隔）。状态标签：`UPDATED` / `UNCHANGED` / `NEW` / `OK` / `FAIL`。
+
+**10. 时间戳化 delta 报告**（3 个 skill 使用此模式）
+
+批量操作后每个条目标注状态（NEW / UPDATED / UNCHANGED），用户可跳过未变项。
+
+```markdown
+| 文件 | 状态 |
+|------|------|
+| .githooks/pre-commit | UPDATED |
+| .githooks/commit-msg | UNCHANGED |
+```
+
+**11. "下一步"交棒提示**（4 个 skill 使用此模式）
+
+Skill 完成后给出明确的下一步建议：调用下一个 skill，或询问用户是否深入某部分。
+
+```
+scout-brand: "确认后可运行 /build-style"
+init-skill:  "下一步：运行 /publish-skill 完成注册"
+```
+
+### 安全与规范
+
+**12. Bash 安全：禁止字符串拼接**（3 个 skill 使用此模式）
+
+Skill 中嵌入 bash/Python 时，禁止用 shell 字符串拼接传值。使用 `subprocess` 列表参数或环境变量；URL 净化用正则替换。
+
+**13. 版本字段在内容 hash 计算中视为占位**（2 个 skill 使用此模式）
+
+计算 SKILL.md 内容 hash 时，将 `version:` 行替换为固定占位符再计算，避免单纯改版本号触发"内容变更"误报。
+
+```bash
+sed 's/^version:.*$/version: __HASH_PLACEHOLDER__/' SKILL.md | sha256sum | cut -c1-16
+```