harveyz-skill 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +85 -39
  3. package/bin/cli.js +459 -51
  4. package/hooks/check-similar-branch/check-similar-branch.sh +75 -0
  5. package/lib/bundles.js +74 -7
  6. package/lib/installer.js +256 -30
  7. package/lib/targets.js +22 -13
  8. package/package.json +8 -6
  9. package/skills/analysis/git-cleanup/SKILL.md +189 -0
  10. package/skills/design/sync-design-html/SKILL.md +354 -0
  11. package/skills/design/sync-design-html/references/stack-electron.md +119 -0
  12. package/skills/design/sync-design-html/references/stack-nextjs.md +101 -0
  13. package/skills/design/sync-design-html/references/stack-react.md +117 -0
  14. package/skills/design/sync-design-html/references/stack-swiftui.md +115 -0
  15. package/skills/design/sync-design-html/references/stack-vue.md +142 -0
  16. package/skills/design/sync-design-html/references/stacks.md +45 -0
  17. package/skills/web-fetch/article-fetcher/SKILL.md +95 -509
  18. package/skills/web-fetch/article-fetcher/references/__pycache__/article_utils.cpython-314.pyc +0 -0
  19. package/skills/web-fetch/article-fetcher/references/article_utils.py +32 -5
  20. package/skills/web-fetch/article-fetcher/scripts/playwright_web.py +172 -0
  21. package/skills/web-fetch/article-fetcher/scripts/playwright_xcom.py +221 -0
  22. package/skills/web-fetch/article-fetcher/scripts/validate_article.py +36 -0
  23. package/skills/web-fetch/article-fetcher/tests/test_security.py +257 -0
  24. package/skills-index.json +18 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,89 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.7.0] - 2026-05-24
11
+
12
+ ### Added
13
+ - `hskill hooks` 子命令：`install` / `uninstall` / `list`
14
+ - Claude Code hooks 统一管理：支持 user 和 project 两种 scope
15
+ - Hook 版本追踪：脚本头部 `# version:` 注释，安装时区分 up-to-date / outdated
16
+ - `hskill hooks list` 展示 VER 列及 user/project 安装状态
17
+ - `hskill status` HOOKS 区块显示版本号
18
+ - 内置 hook：`check-similar-branch`（LLM 语义分析检测相似分支，防止重复建分支）
19
+ - `prepack` 阶段验证 skills / tools / hooks 的目录和关键文件存在性，索引和磁盘不一致时构建失败
20
+
21
+ ### Changed
22
+ - `generate-npmignore.js` 现在自动从 `skills-index.json` 生成 `package.json files[]`，新增 skill/tool/hook 无需手动维护
23
+ - hooks 目录结构对齐 skills/tools：`hooks/<name>/<name>.sh`
24
+ - `skills-index.json` hooks 条目的 `path` 指向目录，脚本文件名由约定（`<name>.sh`）决定
25
+ - `generate-npmignore.js` 对 `exclude` 中不存在的目录打印警告，防止遗留配置静默通过
26
+
27
+ ### Fixed
28
+ - `resolveHookDisplayVersion` 定义在 hooks 块内但被 status 块调用导致的 `ReferenceError`
29
+ - `hskill hooks --json` 子命令路由失败（Unknown subcommand）
30
+ - 无效 scope 参数静默使用默认值的问题
31
+
32
+ ## [0.6.2] - 2026-04-28
33
+
34
+ ### Fixed
35
+ - fzf 未安装时显示清晰的错误信息和安装指引
36
+
37
+ ## [0.6.1] - 2026-04-20
38
+
39
+ ### Added
40
+ - `hskill version`、`hskill status`、`hskill outdated`、`hskill info` 子命令
41
+
42
+ ## [0.6.0] - 2026-04-15
43
+
44
+ ### Added
45
+ - 工具版本统一检测（shell tools 通过 `tool.json` 管理版本）
46
+ - 交互式 skill 选择列表展示版本号
47
+ - 用 fzf 替代 checkbox 作为交互式选择界面
48
+
49
+ ### Changed
50
+ - skill-analyzer 重构至 v1.0.0，规范 references 和输出路径
51
+
52
+ ## [0.5.0] - 2026-03-30
53
+
54
+ ### Added
55
+ - skill 安装支持 user / project 两种 scope 选择
56
+
57
+ ## [0.4.0] - 2026-03-15
58
+
59
+ ### Changed
60
+ - CLI 重命名为 `hskill`，采用子命令结构
61
+
62
+ ## [0.3.0] - 2026-03-01
63
+
64
+ ### Added
65
+ - `p-launch` 工具：在 Ghostty 中打开项目
66
+
67
+ ### Fixed
68
+ - p-launch 多项路径、osascript 调用和动态检测问题
69
+
70
+ ## [0.2.1] - 2026-02-15
71
+
72
+ ### Added
73
+ - OpenClaw 和 Hermes 作为支持的安装目标
74
+
75
+ ## [0.1.2] - 2026-01-20
76
+
77
+ ### Added
78
+ - 初始 skill 管理器，支持安装到 Claude / Cursor / Codex
79
+
80
+ [Unreleased]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.7.0...HEAD
81
+ [0.7.0]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.6.2...v0.7.0
82
+ [0.6.2]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.6.1...v0.6.2
83
+ [0.6.1]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.6.0...v0.6.1
84
+ [0.6.0]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.5.0...v0.6.0
85
+ [0.5.0]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.4.0...v0.5.0
86
+ [0.4.0]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.3.0...v0.4.0
87
+ [0.3.0]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.2.1...v0.3.0
88
+ [0.2.1]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.1.2...v0.2.1
89
+ [0.1.2]: https://github.com/harveyzhang814/harveyz-skill/compare/v0.1.1...v0.1.2
package/README.md CHANGED
@@ -1,44 +1,48 @@
1
- # Harvey Skills
1
+ # harveyz-skill
2
2
 
3
- Harvey 的个人 Claude Code 技能仓库。
3
+ Harvey 的个人 Claude Code / Cursor / Codex 技能管理器，当前版本 **v0.6.2**。
4
+
5
+ 通过 `hskill` 命令将技能安装到 `~/.claude/skills/`，按 bundle 分组管理。
6
+
7
+ ---
4
8
 
5
9
  ## 技能清单
6
10
 
7
- 按 bundle 分组，`hskill install --bundle <bundle>` 安装对应分组。
11
+ 按 bundle 分组，用 `hskill install --bundle <bundle>` 安装对应分组，或用 `hskill install --skill <name>` 安装单个技能。
8
12
 
9
13
  ### analysis — 分析工具
10
14
 
11
15
  | 技能 | 说明 |
12
16
  |------|------|
13
- | **skill-analyzer** | 系统化分析 Skill 仓库的框架，基于洋葱模型四层结构 |
17
+ | **skill-analyzer** | 对 Skill 仓库进行系统性分析，基于洋葱模型四层结构输出分析报告 |
14
18
 
15
19
  ### brainstorming — 设计与规划工具
16
20
 
17
21
  | 技能 | 说明 |
18
22
  |------|------|
19
- | **brainstorming** | 设计前强制探索阶段 — 在实现任何功能前，先理解意图、需求和设计方案（HARD-GATE） |
20
- | **writing-plans** | 将设计拆解为可执行的小任务（2–5 分钟/任务），含精确文件路径和验证步骤 |
23
+ | **brainstorming** | 实现前强制探索阶段（HARD-GATE）— 在创建功能、修改代码前，先理解意图、需求和设计方案 |
24
+ | **writing-plans** | 将设计拆解为可执行的小任务（2–5 分钟/任务），含精确文件路径、完整代码和验证步骤 |
21
25
 
22
26
  ### dev — 开发工作流
23
27
 
24
28
  | 技能 | 说明 |
25
29
  |------|------|
26
- | **git-workflow-init** | 初始化或更新 git 分支管理规范，差量部署 git hooks，生成工作流文档 |
27
- | **executing-plans** | 执行书面实施计划，含两阶段 review（规格合规性 → 代码质量） |
28
- | **systematic-debugging** | 系统化 debug — 必须先找到根本原因，再提修复方案 |
29
- | **using-git-worktrees** | 创建隔离 worktree 进行特性开发，验证干净的测试基线后再开始 |
30
+ | **git-workflow-init** | 初始化或更新 git 分支管理规范：读取 `workflow-config.yml`，差量部署 git hooks，生成工作流文档 |
31
+ | **executing-plans** | 执行书面实施计划，含两阶段 review（规格合规性 → 代码质量），需先通过 `using-git-worktrees` 建立隔离工作区 |
32
+ | **systematic-debugging** | 系统化 debug — 禁止在未完成根本原因调查前提出修复方案 |
33
+ | **using-git-worktrees** | 创建隔离 worktree 进行特性开发，验证干净测试基线后再开始 |
30
34
 
31
35
  ### document — 文档工具
32
36
 
33
37
  | 技能 | 说明 |
34
38
  |------|------|
35
- | **diataxis-docs** | 管理 `docs/` 目录 — 遵循 Diátaxis 方法论，写新文档、更新或删除时触发 |
39
+ | **diataxis-docs** | 管理 `docs/` 目录 — 遵循 Diátaxis 方法论，写新文档、更新或删除时触发，可防止内容重复 |
36
40
 
37
41
  ### harness — 测试工具
38
42
 
39
43
  | 技能 | 说明 |
40
44
  |------|------|
41
- | **full-stack-debug-env** | 多组件应用全栈日志监控环境搭建 — 为前端、后端、worker 等各层建立独立日志文件 |
45
+ | **full-stack-debug-env** | 多组件应用全栈日志监控环境 — 为前端、后端、worker 等各层建立独立日志文件，供 Agent 精确查询 |
42
46
 
43
47
  ### task — 任务管理
44
48
 
@@ -51,7 +55,7 @@ Harvey 的个人 Claude Code 技能仓库。
51
55
 
52
56
  | 技能 | 说明 |
53
57
  |------|------|
54
- | **article-fetcher** | 抓取 URL → 翻译为中文 → 存入 Obsidian；支持 X.com / Twitter（Playwright + Chrome Profile） |
58
+ | **article-fetcher** | 抓取 URL → 翻译为中文 → 存入 Obsidian；支持 X.com / Twitter（Playwright + Chrome Profile），支持批量列表 |
55
59
 
56
60
  ### writing — 写作工具
57
61
 
@@ -63,29 +67,33 @@ Harvey 的个人 Claude Code 技能仓库。
63
67
 
64
68
  ## 工具清单
65
69
 
66
- Shell 工具，通过 `hskill install --tool p-launch` 安装。
70
+ Shell 工具，安装到 `~/.local/bin/`。
67
71
 
68
- | 工具 | 说明 |
69
- |------|------|
70
- | **p-launch** | 交互式项目启动器 — 从多个目录中快速选择并跳转到项目 |
72
+ | 工具 | Bundle | 说明 |
73
+ |------|--------|------|
74
+ | **p-launch** | shell-tools | 交互式项目启动器 — 从多个目录中快速选择并跳转到项目 |
71
75
 
72
- ---
76
+ ```bash
77
+ hskill install --tool p-launch
78
+ ```
73
79
 
80
+ ---
74
81
 
75
82
  ## 安装
76
83
 
84
+ **推荐：全局安装**
85
+
77
86
  ```bash
78
87
  npm install -g harveyz-skill
88
+ hskill # 交互式选择安装
79
89
  ```
80
90
 
81
- 安装后使用 `hskill` 命令管理 skills。
82
-
83
- ### 常用命令
91
+ **常用命令**
84
92
 
85
93
  ```bash
86
- hskill # 交互式选择安装
87
- hskill install --bundle dev --target claude # 安装指定 bundle
88
- hskill install --skill git-workflow-init # 安装指定 skill
94
+ hskill # 交互式选择
95
+ hskill install --bundle dev # 安装整个 bundle
96
+ hskill install --skill git-workflow-init # 安装单个 skill
89
97
  hskill install --tool p-launch # 安装 shell 工具
90
98
  hskill list # 查看可用 skill
91
99
  hskill update # 更新到最新版
@@ -94,55 +102,93 @@ hskill --help # 查看帮助
94
102
 
95
103
  Skills 安装到 `~/.claude/skills/`，shell 工具安装到 `~/.local/bin/`。
96
104
 
97
- ### 本地源码开发
105
+ **本地源码开发**
98
106
 
99
107
  ```bash
100
- # 安装指定 skill
101
108
  node bin/cli.js install --skill mermaid-diagram --target claude
102
-
103
- # 安装整个 bundle
104
109
  node bin/cli.js install --bundle dev --target claude
110
+ node bin/cli.js install --skill mermaid-diagram --target claude --force # 覆盖已有安装
111
+ ```
112
+
113
+ **Git 保护钩子（可选）**
105
114
 
106
- # 覆盖已有安装
107
- node bin/cli.js install --skill mermaid-diagram --target claude --force
115
+ ```bash
116
+ bash scripts/git/install-git-hooks.sh
108
117
  ```
109
118
 
119
+ 钩子会阻止直接向 `main` 和 `staging` 提交 — 使用 feature/fix/chore/doc 分支，通过 staging 合并。
120
+
121
+ ---
122
+
123
+ ## Hook 管理
124
+
125
+ hskill 支持通过 `hooks` 命令管理 Claude Code hooks。查看可用 hooks、在全局或项目作用域安装/卸载：
126
+
127
+ ```bash
128
+ hskill hooks list # 查看可用 hooks 及安装状态
129
+ hskill hooks install --name check-similar-branch # 安装到全局（user scope）
130
+ hskill hooks install --name check-similar-branch --scope project # 安装到当前项目
131
+ hskill hooks uninstall check-similar-branch # 从全局卸载
132
+ hskill hooks uninstall check-similar-branch --scope project # 从当前项目卸载
133
+ ```
134
+
135
+ ---
136
+
110
137
  ## Skill 开发指南
111
138
 
112
- ### 命名规范
139
+ ### 目录结构
140
+
141
+ ```
142
+ skills/
143
+ <category>/
144
+ <skill-name>/
145
+ SKILL.md # 技能定义（必须）
146
+ references/ # 参考资料（可选）
147
+ ```
113
148
 
114
- - Flat skill：直接放 `skills/<category>/<skill-name>/SKILL.md`
115
- - Skill group：`skills/<group>/` 下多个子目录，每个含 `SKILL.md`
149
+ 两种模式：
150
+ - **Flat skill** — 单个 `SKILL.md`，如 `skills/writing/mermaid-diagram/`
151
+ - **Skill group** — 同一分类下多个子目录，每个含 `SKILL.md`
116
152
 
117
153
  ### SKILL.md 格式
118
154
 
119
155
  ```yaml
120
156
  ---
121
157
  name: skill-name
122
- description: "做什么。触发词..."
158
+ description: "做什么。触发词：..."
123
159
  user_invocable: true
124
160
  version: "x.x.x"
125
161
  ---
126
162
  ```
127
163
 
128
- ### 发布流程
164
+ ### 发布新技能
129
165
 
130
166
  1. 在 `skills/<category>/<skill-name>/` 下创建 `SKILL.md`
131
167
  2. 在 `skills-index.json` 的 `skills[]` 中添加条目，指定 `path` 和 `bundle`
132
- 3. 运行 `node scripts/generate-npmignore.js`（`prepack` 钩子会自动执行）
168
+ 3. 若 bundle 是新的，在 `bundleMeta` 中添加描述
169
+ 4. 运行 `node scripts/generate-npmignore.js`（`prepack` 钩子会自动执行）
170
+
171
+ `skills-index.json` 是唯一数据源，不在其中的技能不会被打包发布。
133
172
 
134
173
  ### 共享输出规范
135
174
 
136
175
  **Org-mode 输出：**
137
176
  - 加粗：`*text*`（单星号）
138
- - 文件名：`{时间戳}--{标题}__{type}.org`
177
+ - 文件名：`{YYYYMMDDTHHMMSS}--{标题}__{type}.org`
139
178
  - 输出目录：`~/Documents/notes/`
140
- - 时间戳：`date +%Y%m%dT%H%M%S`
141
179
 
142
180
  **ASCII Art：**
143
181
  - 允许：`+ - | / \ > < v ^ * = ~ . : # [ ] ( ) _ , ; ! ' "`
144
182
  - 禁止：Unicode 绘图符号
145
183
 
184
+ ### Git 工作流
185
+
186
+ 分支命名规范与合并流程详见 [docs/reference/git-workflow.md](docs/reference/git-workflow.md)。
187
+
188
+ 一个功能或迭代使用一个分支，积累所有相关改动，只在明确"合并"或"完成"时才合并到 staging。
189
+
190
+ ---
191
+
146
192
  ## 许可证
147
193
 
148
- Private — 仅供个人使用。
194
+ MIT