luminae-helper 0.0.14 → 1.0.1

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.
package/README.md CHANGED
@@ -1,50 +1,174 @@
1
1
  # luminae-helper
2
2
 
3
- Install public AI agent commands/skills into local AI coding tools.
3
+ AI 编程工具的 skills/commands 管理 CLI。一键将公共 AI agent 技能安装到 Claude Code、Cursor、Codex、Hermes Agent、OpenCode、Trae 等工具中。
4
4
 
5
- The package bundles a build-time snapshot from `evenweiss/ai-agent-skills`; runtime installation is local-only and does not fetch GitHub.
5
+ npm 包在构建时将所有内容打包,运行时纯本地操作文件系统,不访问网络。
6
6
 
7
- ## Install
7
+ ## 前置条件
8
+
9
+ - Node.js >= 18.0.0
10
+ - 至少一个目标 AI 工具已安装
11
+
12
+ ## 安装
8
13
 
9
14
  ```bash
10
- npm install -g luminae-helper --registry https://registry.npmjs.org/
15
+ npm install -g luminae-helper
11
16
  ```
12
17
 
13
- ## Use
18
+ 安装后全局可用 `luminae-helper` 命令。
19
+
20
+ ## 使用
21
+
22
+ ### 安装技能
14
23
 
15
24
  ```bash
16
25
  luminae-helper
17
- luminae-helper --version
18
- luminae-helper outdated
19
26
  ```
20
27
 
21
- ## Supported tools
28
+ 进入交互式菜单,分四步:
22
29
 
23
- | Tool | command source | skill source |
24
- |---|---|---|
25
- | Claude Code | `~/.claude/commands/` | `~/.claude/skills/` |
26
- | Codex | — | `~/.codex/skills/` |
27
- | Cursor | — | `~/.cursor/skills/` |
28
- | Hermes Agent | — | `~/.hermes/skills/` |
29
- | OpenCode | — | `~/.opencode/skills/` |
30
- | Trae | `~/.trae/commands/` | — |
30
+ 1. **选择内容** — 勾选要安装的 commands / skills
31
+ 2. **选择工具** — 勾选要安装到哪些 AI 工具(自动检测本机已安装的)
32
+ 3. **预览确认** — 确认后执行
33
+ 4. **执行安装** — 复制文件到各工具目录,汇总结果
31
34
 
32
- ## Build-time skill source
35
+ ### 卸载技能
33
36
 
34
- For local development, keep `ai-agent-skills` as a sibling directory or set:
37
+ 再次运行 `luminae-helper`,在第一步主菜单中选择「卸载」。
38
+
39
+ 卸载时只会删除带有 `managed-by: luminae-helper` 标识的文件,不会误删用户手动创建或 AI 工具自带的同名文件。
40
+
41
+ ### 其他命令
35
42
 
36
43
  ```bash
37
- LUMINAE_SKILLS_SOURCE=/path/to/ai-agent-skills npm run sync-skills
44
+ luminae-helper --version # 查看版本
45
+ luminae-helper outdated # 检查 npm registry 是否有新版本
46
+ ```
47
+
48
+ ### 退出
49
+
50
+ 任何步骤按 `Ctrl+C` 或在导航行选择「退出」即可安全退出,不会产生残留文件。
51
+
52
+ ## 包含内容
53
+
54
+ ### Commands(命令)
55
+
56
+ | 命令 | 用途 |
57
+ |------|------|
58
+ | `git-push` | 代码审查 → 提交信息 → commit → push 完整工作流 |
59
+
60
+ ### Skills(技能)
61
+
62
+ | 技能 | 用途 |
63
+ |------|------|
64
+ | `identity` | 检测项目类型,自动设定 agent 身份(前端/后端/全栈等) |
65
+
66
+ ## 支持的工具
67
+
68
+ | 工具 | command 模式 | skill 模式 | 安装方式 |
69
+ |------|:-----------:|:---------:|------|
70
+ | Claude Code | ✓ | ✓ | `~/.claude/commands/*.md` / `~/.claude/skills/*/` |
71
+ | Codex | ✗ | ✓ | `~/.codex/skills/*/` |
72
+ | Cursor | ✗ | ✓ | `~/.cursor/skills/*/` |
73
+ | Hermes Agent | ✗ | ✓ | `~/.hermes/skills/*/` |
74
+ | OpenCode | ✗ | ✓ | `~/.opencode/skills/*/` |
75
+ | Trae | ✓ | ✗ | `~/.trae/commands/*.md` |
76
+
77
+ ### Command vs Skill
78
+
79
+ - **Command** — 以 `/command-name` 方式触发,安装为单个 `.md` 文件(Claude Code、Trae)
80
+ - **Skill** — 作为上下文注入到 agent,安装为完整目录(Codex、Cursor、Hermes、OpenCode)
81
+
82
+ 当技能类型与工具能力不匹配时,CLI 会自动做 fallback 转换(如 command 源安装到只支持 skill 的工具),并在结果中标注。
83
+
84
+ ### 兼容转换
85
+
86
+ | 场景 | 转换方式 |
87
+ |------|---------|
88
+ | Command → 仅支持 skill 的工具 | 将 `.md` 文件包装为 skill 目录安装 |
89
+ | Skill → 仅支持 command 的工具 | 将目录下的 `SKILL.md` 安装为 `.md` 文件 |
90
+
91
+ ## 工作原理
92
+
93
+ ### managed-by 标识
94
+
95
+ 安装时会在目标文件的 YAML frontmatter 中注入 `managed-by: luminae-helper`:
96
+
97
+ ```yaml
98
+ ---
99
+ name: git-push
100
+ description: ...
101
+ managed-by: luminae-helper
102
+ ---
38
103
  ```
39
104
 
40
- Publishing runs `scripts/fetch-skills.js --strict` and bundles `commands/` / `skills/` into the tarball.
105
+ 卸载时只删除带有此标识的文件/目录,保护用户手动创建的内容。
106
+
107
+ ### 安全设计
108
+
109
+ - **原子替换** — 目录安装先复制到临时路径,成功后再重命名替换,中途失败不影响已有文件
110
+ - **备份恢复** — 替换前保留旧目录备份,替换失败自动回滚
111
+ - **识别保护** — 卸载只移除标记过的内容,不会误删
112
+
113
+ ## 卸载 luminae-helper
114
+
115
+ ```bash
116
+ npm uninstall -g luminae-helper
117
+ ```
118
+
119
+ 注意:卸载 CLI 不会清除已安装到各工具目录的 commands/skills 文件。如需清理,使用 `luminae-helper` 的卸载流程(在第一步主菜单选择卸载),或手动删除对应目录下的文件。
120
+
121
+ ## 开发
122
+
123
+ ### 同步公共技能
124
+
125
+ `commands/` 和 `skills/` 是构建产物(gitignored)。本地开发时,保持 `ai-agent-skills` 为同级目录或设置环境变量:
126
+
127
+ ```bash
128
+ git clone https://github.com/evenweiss/ai-agent-skills.git ../ai-agent-skills
129
+ LUMINAE_SKILLS_SOURCE=../ai-agent-skills npm run sync-skills
130
+ ```
131
+
132
+ 脚本会扫描 `ai-agent-skills/commands/` 和 `ai-agent-skills/skills/`,将包含 `SKILL.md` 的子目录复制到本项目的对应目录。
133
+
134
+ ### 发布
135
+
136
+ ```bash
137
+ npm publish
138
+ ```
139
+
140
+ 发布前 `prepublishOnly` 钩子以 `--strict` 模式运行同步脚本,确保至少有一个 command 或 skill 被打包。
141
+
142
+ ### 项目结构
143
+
144
+ ```
145
+ luminae-helper/
146
+ ├── src/
147
+ │ ├── cli.js # 入口
148
+ │ ├── index.js # runCli() 导出
149
+ │ └── lib/
150
+ │ ├── constants.js # 工具定义、技能发现、安装目标生成
151
+ │ ├── installer.js # 安装/卸载逻辑
152
+ │ ├── ui.js # 交互式 TUI(inquirer)
153
+ │ └── checkbox-with-action-rows.js # 带功能行的多选组件
154
+ ├── scripts/fetch-skills.js # 构建时技能同步脚本
155
+ ├── commands/ # 构建产物(gitignored)
156
+ ├── skills/ # 构建产物(gitignored)
157
+ └── package.json
158
+ ```
41
159
 
42
160
  ## Library API
43
161
 
162
+ 可作为 npm 包引入,自定义包装器(如 `kfz-skills-helper`)复用 CLI 引擎:
163
+
44
164
  ```js
45
165
  import { runCli } from "luminae-helper";
46
166
 
47
- await runCli({ argv: process.argv.slice(2), packageRoot: import.meta.dirname });
167
+ const code = await runCli({
168
+ argv: process.argv.slice(2),
169
+ packageRoot: import.meta.dirname, // 指向你自己的 commands/ skills/
170
+ });
171
+ process.exit(code);
48
172
  ```
49
173
 
50
- `packageRoot` lets wrapper packages provide their own bundled `commands/` and `skills/` while reusing the CLI engine.
174
+ `packageRoot` 让包装器提供自己的 `commands/` 和 `skills/`,复用相同的交互式安装引擎。参见 [kfz-skills-helper](https://github.com/evenweiss/kfz-skills-helper)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "luminae-helper",
3
- "version": "0.0.14",
3
+ "version": "1.0.1",
4
4
  "description": "Install public AI agent skills to coding tools",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -1,99 +0,0 @@
1
- ---
2
- name: git-commit
3
- description: 根据 git diff 生成 Conventional Commits 规范的提交信息并直接执行 git commit
4
- ---
5
-
6
- # git-commit
7
-
8
- > Generate commit message from git diff and execute git commit
9
-
10
- **触发条件:** 当需要"提交代码"、"帮我 commit"、"提交一下"、"commit 一下"时调用。
11
-
12
- ## 使用方式
13
-
14
- 1. 执行 `git diff` 获取变更内容
15
- 2. 分析变更文件路径和内容,判断变更类型
16
- 3. 根据 Conventional Commits 规范生成 commit message
17
- 4. 输出生成的 commit message 供用户知悉
18
- 5. 直接执行 `git commit`(无需用户确认)
19
-
20
- **如只需生成 commit message 而不执行提交,请使用 `git-commit-msg`。**
21
-
22
- ## Conventional Commits 类型
23
-
24
- | type | 使用场景 |
25
- |------|---------|
26
- | feat | 新功能 |
27
- | fix | 修复 bug |
28
- | docs | 文档更新 |
29
- | style | 代码格式(不影响功能)|
30
- | refactor | 重构(不影响功能)|
31
- | perf | 性能优化 |
32
- | test | 测试相关 |
33
- | chore | 构建/工具/依赖更新 |
34
- | wip | 开发中(未完成)|
35
-
36
- ## 判断规则
37
-
38
- - 变更文件在 `docs/` → `docs`
39
- - 变更包含 `*.test.ts` / `*.spec.ts` / `__tests__/` → `test`
40
- - 变更包含 `package.json` / `pnpm-lock.yaml` / `go.mod` → `chore`
41
- - 变更修复了某个问题 → `fix`
42
- - 变更添加了新功能点 → `feat`
43
- - scope 优先取变更最集中的模块目录名
44
-
45
- ## 输出格式
46
-
47
- ```
48
- ## 提交信息建议
49
-
50
- **type:** feat
51
- **scope:** auth
52
- **subject:** 添加 JWT 登录功能
53
-
54
- **body:**
55
- 实现基于 JWT 的用户登录鉴权流程,包含 token 生成、验证和刷新机制。
56
-
57
- 变更文件:
58
- - src/auth/login.ts
59
- - src/auth/jwt.ts
60
- - src/middleware/auth.ts
61
-
62
- ---
63
-
64
- 原始 diff 摘要:
65
- +120 行 / -30 行
66
- ```
67
-
68
- ## 执行提交
69
-
70
- 生成 commit message 后,直接执行以下命令(无需用户确认):
71
-
72
- ```bash
73
- git commit -m "<type>(<scope>): <subject>" -m "<body>"
74
- ```
75
-
76
- - 如果 body 为空,省略第二个 `-m` 参数
77
- - 执行前先告知用户生成的 commit message 内容
78
- - 执行后输出 commit 结果(含 commit hash)
79
- - 如果 commit 失败,输出错误信息供用户排查
80
-
81
- ### 注意事项
82
-
83
- - 提交前先确认 `git add` 已完成(检查 `git status` 是否有未暂存变更)
84
- - 如果有未暂存变更,提醒用户是否需要 `git add`,不要自动执行
85
- - 不要使用 `git commit -a`,避免意外提交不相关的文件
86
-
87
- ## Conventional Commits 格式规范
88
-
89
- ```
90
- <type>(<scope>): <subject>
91
-
92
- <body>
93
- ```
94
-
95
- - `type` 小写
96
- - `scope` 可选,用小写字母
97
- - `subject` 首字母小写,结尾不加句号
98
- - `body` 使用中文,描述变更背景、原因和关键实现
99
- - 标题和 body 之间空一行
@@ -1,70 +0,0 @@
1
- # git-commit-msg
2
-
3
- Smart commit message generator with Conventional Commits format.
4
-
5
- ## 触发条件
6
-
7
- 需要"生成提交信息"、"写 commit message"、"帮我写 commit"时调用。
8
-
9
- ## 功能
10
-
11
- 分析 `git diff` 输出,生成符合 Conventional Commits 规范的 commit message。
12
-
13
- ## Conventional Commits 类型
14
-
15
- | type | 使用场景 |
16
- |------|---------|
17
- | feat | 新功能 |
18
- | fix | 修复 bug |
19
- | docs | 文档更新 |
20
- | style | 代码格式(不影响功能)|
21
- | refactor | 重构(不影响功能)|
22
- | perf | 性能优化 |
23
- | test | 测试相关 |
24
- | chore | 构建/工具/依赖更新 |
25
-
26
- ## 判断规则
27
-
28
- - 变更文件在 `docs/` → `docs`
29
- - 变更包含 `*.test.ts` / `*.spec.ts` → `test`
30
- - 变更包含 `package.json` / `pnpm-lock.yaml` / `go.mod` → `chore`
31
- - 变更修复了某个问题 → `fix`
32
- - 变更添加了新功能点 → `feat`
33
- - scope 优先取变更最集中的模块目录名
34
-
35
- ## 输出格式
36
-
37
- ```
38
- ## 提交信息建议
39
-
40
- **type:** feat
41
- **scope:** auth
42
- **subject:** 添加 JWT 登录功能
43
-
44
- **body:**
45
- 实现基于 JWT 的用户登录鉴权流程,包含 token 生成、验证和刷新机制。
46
-
47
- 变更文件:
48
- - src/auth/login.ts
49
- - src/auth/jwt.ts
50
- ```
51
-
52
- ## 安装
53
-
54
- ```bash
55
- # Claude Code
56
- cp commands/git-commit-msg/SKILL.md ~/.claude/commands/git-commit-msg.md
57
-
58
- # Cursor
59
- cp commands/git-commit-msg/SKILL.md ~/.cursor/commands/git-commit-msg.md
60
-
61
- # OpenCode
62
- cp -r commands/git-commit-msg ~/.opencode/skills/
63
-
64
- # Trae
65
- cp commands/git-commit-msg/SKILL.md ~/.trae/commands/git-commit-msg.md
66
- ```
67
-
68
- ## License
69
-
70
- MIT
@@ -1,104 +0,0 @@
1
- ---
2
- name: git-commit-msg
3
- description: 根据 git diff 生成 Conventional Commits 规范的提交信息,由用户决定是否执行 git commit
4
- ---
5
-
6
- # git-commit-msg
7
-
8
- > Generate commit message from git diff, and optionally execute git commit
9
-
10
- **触发条件:** 当需要"生成提交信息"、"写 commit message"、"帮我写 commit"、"生成几个 commit 建议"时调用。
11
-
12
- ## 使用方式
13
-
14
- 1. 执行 `git diff` 获取变更内容
15
- 2. 分析变更文件路径和内容,判断变更类型
16
- 3. 根据 Conventional Commits 规范生成 commit message
17
- 4. 输出生成的 commit message 供用户审阅
18
- 5. 询问用户是否以当前生成的 message 进行 commit
19
- 6. 如果用户回复"是"、"同意"、"确认"等肯定词,则执行 `git commit`;否则不执行
20
-
21
- **注意:** 如需生成后直接提交(无需询问),请使用 `git-commit`。
22
-
23
- ## Conventional Commits 类型
24
-
25
- | type | 使用场景 |
26
- |------|---------|
27
- | feat | 新功能 |
28
- | fix | 修复 bug |
29
- | docs | 文档更新 |
30
- | style | 代码格式(不影响功能)|
31
- | refactor | 重构(不影响功能)|
32
- | perf | 性能优化 |
33
- | test | 测试相关 |
34
- | chore | 构建/工具/依赖更新 |
35
- | wip | 开发中(未完成)|
36
-
37
- ## 判断规则
38
-
39
- - 变更文件在 `docs/` → `docs`
40
- - 变更包含 `*.test.ts` / `*.spec.ts` / `__tests__/` → `test`
41
- - 变更包含 `package.json` / `pnpm-lock.yaml` / `go.mod` → `chore`
42
- - 变更修复了某个问题 → `fix`
43
- - 变更添加了新功能点 → `feat`
44
- - scope 优先取变更最集中的模块目录名
45
-
46
- ## 输出格式
47
-
48
- ```
49
- ## 提交信息建议
50
-
51
- **type:** feat
52
- **scope:** auth
53
- **subject:** 添加 JWT 登录功能
54
-
55
- **body:**
56
- 实现基于 JWT 的用户登录鉴权流程,包含 token 生成、验证和刷新机制。
57
-
58
- 变更文件:
59
- - src/auth/login.ts
60
- - src/auth/jwt.ts
61
- - src/middleware/auth.ts
62
-
63
- ---
64
-
65
- 原始 diff 摘要:
66
- +120 行 / -30 行
67
- ```
68
-
69
- ## 可选提交
70
-
71
- 生成 commit message 后,询问用户:`是否以该 message 进行 commit?`
72
-
73
- - 用户回复"是"、"同意"、"确认"、"好"等肯定词 → 执行提交
74
- - 用户回复否定或要求修改 → 不执行,等待用户进一步指示
75
-
76
- 执行命令:
77
-
78
- ```bash
79
- git commit -m "<type>(<scope>): <subject>" -m "<body>"
80
- ```
81
-
82
- - 如果 body 为空,省略第二个 `-m` 参数
83
- - 执行后输出 commit 结果(含 commit hash)
84
- - 如果 commit 失败,输出错误信息供用户排查
85
-
86
- ### 注意事项
87
-
88
- - 提交前先确认 `git add` 已完成(检查 `git status` 是否有未暂存变更)
89
- - 如果有未暂存变更,提醒用户是否需要 `git add`,不要自动执行
90
- - 不要使用 `git commit -a`,避免意外提交不相关的文件
91
-
92
- ## Conventional Commits 格式规范
93
-
94
- ```
95
- <type>(<scope>): <subject>
96
-
97
- <body>
98
- ```
99
-
100
- - `type` 小写
101
- - `scope` 可选,用小写字母
102
- - `subject` 首字母小写,结尾不加句号
103
- - `body` 使用中文,描述变更背景、原因和关键实现
104
- - 标题和 body 之间空一行