Skip to content

Commit 937c1d0

Browse files
github-actions[bot]github-actions[bot]
committed
chore: auto-convert Claude Code plugins via acplugin
1 parent 4256d97 commit 937c1d0

9 files changed

Lines changed: 569 additions & 0 deletions

File tree

‎.agent/skills/add-converter/SKILL.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: add-converter
3+
description: >-
4+
Add a new resource type converter to acplugin (e.g., adding support for
5+
converting a new Claude Code resource type)
6+
---
7+
8+
# 添加新资源类型转换器
9+
10+
当需要支持转换新的 Claude Code 资源类型时，按以下步骤操作。
11+
12+
## 步骤
13+
14+
### 1. 定义类型 (`src/types.ts`)
15+
16+
添加新资源的接口定义和 frontmatter 类型（如果有），以及在 `ScanResult` 中添加字段。在 `ConvertedFile.type` 联合类型中添加新值。
17+
18+
### 2. 添加扫描函数 (`src/scanner/claude.ts`)
19+
20+
创建并导出可复用的扫描函数（如 `scanXxxDir()`），这样 `plugin.ts` 也能使用。
21+
22+
在 `scanClaudeProject()` 中调用新函数。
23+
24+
### 3. 集成 Plugin Scanner (`src/scanner/plugin.ts`)
25+
26+
在 `scanPlugin()` 中调用新扫描函数，注意 plugin 目录结构与 .claude/ 不同：
27+
- 项目: `.claude/xxx/`
28+
- Plugin: `xxx/`（直接在 plugin 根目录下）
29+
30+
更新 `countResources()` 包含新资源。
31+
32+
### 4. 创建 Converter (`src/converter/xxx.ts`)
33+
34+
实现 `convertXxx(item, platform)` 函数，处理三个平台：
35+
36+
```typescript
37+
export function convertXxx(item: Xxx, platform: Platform): ConvertedFile {
38+
switch (platform) {
39+
case 'codex': return convertToCodex(item);
40+
case 'opencode': return convertToOpenCode(item);
41+
case 'cursor': return convertToCursor(item);
42+
}
43+
}
44+
```
45+
46+
**关键原则**：
47+
- Converter 无副作用，只返回 `ConvertedFile`
48+
- 不支持的功能用降级策略（合并到 AGENTS.md 或 rules）
49+
- 返回 warnings 告知用户不兼容项
50+
51+
### 5. 集成 Writer (`src/writer/*.ts`)
52+
53+
在三个 writer 文件中调用新 converter，处理合并逻辑。
54+
55+
### 6. 更新 CLI 输出 (`src/index.ts`)
56+
57+
更新 `printScanResult()` 和 `convertSingleScan()` 中的资源计数。
58+
59+
### 7. 添加测试 (`src/__tests__/xxx.test.ts`)
60+
61+
为新 converter 创建测试，覆盖三个平台的转换逻辑。
62+
63+
### 8. 更新 test-fixture/
64+
65+
在 `test-fixture/` 中添加新资源类型的示例文件，确保 `scanner.test.ts` 覆盖。
66+
67+
## Frontmatter 解析容错
68+
69+
社区插件的 YAML 可能格式不规范。扫描函数中必须 try-catch `parseFrontmatter()`，解析失败时用空 frontmatter + 原始内容兜底。

‎.agent/skills/add-platform/SKILL.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
name: add-platform
3+
description: 'Add support for a new target platform to acplugin (e.g., Windsurf, Zed, etc.)'
4+
---
5+
6+
# 添加新目标平台
7+
8+
当需要支持新的 AI 编程工具作为转换目标时，按以下步骤操作。
9+
10+
## 前置调研
11+
12+
1. 了解目标平台的配置格式：
13+
- Skills/技能文件格式和路径
14+
- 自定义指令文件（类似 CLAUDE.md / AGENTS.md）
15+
- MCP 服务器配置格式
16+
- Agent 定义方式（如果有）
17+
- 命令/斜杠命令格式
18+
- Hooks 系统（如果有）
19+
20+
2. 确认格式差异和降级策略
21+
22+
## 实施步骤
23+
24+
### 1. 类型注册 (`src/types.ts`)
25+
26+
在 `Platform` 联合类型中添加新值：
27+
```typescript
28+
export type Platform = 'codex' | 'opencode' | 'cursor' | 'newplatform';
29+
```
30+
31+
### 2. 每个 Converter 添加分支
32+
33+
在所有 `src/converter/*.ts` 文件中，给 `switch (platform)` 添加新的 case。
34+
35+
参考现有平台的转换逻辑，特别关注：
36+
- **路径映射**：新平台的目录结构
37+
- **Frontmatter 差异**：新平台是否需要特殊字段
38+
- **降级策略**：不支持的功能如何处理
39+
40+
### 3. 创建 Writer (`src/writer/newplatform.ts`)
41+
42+
复制 `cursor.ts` 作为模板，修改平台名：
43+
```typescript
44+
export function generateNewPlatform(scan: ScanResult): ConvertResult { ... }
45+
```
46+
47+
### 4. CLI 注册 (`src/index.ts`)
48+
49+
- `generateForPlatform()` 添加新 case
50+
- `validPlatforms` 数组添加新值
51+
- import 新 writer
52+
53+
### 5. TUI 注册 (`src/tui.ts`)
54+
55+
在 `selectPlatforms()` 的 choices 中添加新选项。
56+
57+
### 6. 测试
58+
59+
- 每个 converter 测试文件添加新平台的用例
60+
- 新增 `src/__tests__/newplatform-writer.test.ts`（可选）
61+
62+
### 7. 文档
63+
64+
- 更新 README.md 和 README.zh-CN.md 的支持矩阵表格
65+
- 更新 llmdoc/reference/conversion-matrix.md
66+
67+
## 降级策略参考
68+
69+
| 场景 | 推荐策略 |
70+
|------|---------|
71+
| 平台无 Agent 系统 | 降级为指令/规则文件 |
72+
| 平台无 Hooks | 记录为文档 + 输出 warning |
73+
| 平台 MCP 格式不同 | 做字段映射转换 |
74+
| 平台无 Skills 概念 | 转为命令或规则文件 |
75+
| Claude 特有字段 | 保留为 HTML 注释 |

‎.agent/skills/npm-publish/SKILL.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
name: npm-publish
3+
description: 'Publish acplugin to npm with version bump, build, test, and 2FA handling'
4+
disable-model-invocation: true
5+
---
6+
7+
# npm 发布流程
8+
9+
## 步骤
10+
11+
1. **版本升级**
12+
```bash
13+
npm version <major|minor|patch> --no-git-tag-version
14+
```
15+
16+
2. **构建 + 测试**
17+
```bash
18+
npm run build && npm test
19+
```
20+
21+
3. **检查打包内容**（确认无测试文件）
22+
```bash
23+
npm pack --dry-run
24+
```
25+
26+
4. **发布**
27+
账号有 2FA，需要用户手动输入 OTP：
28+
```
29+
提示用户运行: ! npm publish --access=public
30+
```
31+
32+
5. **Commit + Push**
33+
```bash
34+
git add package.json package-lock.json
35+
git commit -m "chore: bump version to $(node -p 'require("./package.json").version')"
36+
git push
37+
```
38+
39+
## 注意事项
40+
41+
- 包名是 `@disdjj/acplugin`（scoped），必须加 `--access=public`
42+
- 不要尝试在脚本中自动发布，2FA 会阻塞
43+
- `prepublishOnly` 脚本会自动编译
44+
- `files` 字段已排除 `dist/__tests__/`

‎.cursor-plugin/plugin.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"name": "converted-plugin",
3+
"description": "Converted from Claude Code plugin via acplugin",
4+
"version": "1.0.0",
5+
"skills": "./skills/",
6+
"rules": "./rules/"
7+
}

‎GEMINI.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# acplugin 项目规范
2+
3+
## 项目概述
4+
5+
acplugin 是一个 CLI 工具，将 Claude Code 插件（Skills、Instructions、MCP、Agents、Commands、Hooks）转换为 Codex CLI、OpenCode 和 Cursor 格式。
6+
7+
## 技术栈
8+
9+
- TypeScript + Node.js (CommonJS)
10+
- Commander.js (CLI)
11+
- @inquirer/prompts + chalk (TUI)
12+
- gray-matter (YAML frontmatter)
13+
- @iarna/toml (TOML 序列化)
14+
- vitest (测试)
15+
16+
## 项目结构
17+
18+
```
19+
src/
20+
├── index.ts # CLI 入口 + 交互式 wizard
21+
├── types.ts # 所有类型定义
22+
├── github.ts # GitHub 仓库下载
23+
├── tui.ts # TUI 交互（wizard、checkbox、彩色输出）
24+
├── scanner/
25+
│ ├── claude.ts # .claude/ 项目结构扫描（导出可复用函数）
26+
│ └── plugin.ts # .claude-plugin/ 插件格式扫描
27+
├── converter/
28+
│ ├── skill.ts # SKILL.md 转换
29+
│ ├── instructions.ts # CLAUDE.md → AGENTS.md / .mdc
30+
│ ├── mcp.ts # .mcp.json → TOML / JSON
31+
│ ├── agent.ts # Agent 定义转换（含降级策略）
32+
│ ├── command.ts # Command 转换
33+
│ └── hooks.ts # Hooks 转换（含兼容性报告）
34+
├── writer/
35+
│ ├── codex.ts # Codex 输出编排
36+
│ ├── opencode.ts # OpenCode 输出编排
37+
│ └── cursor.ts # Cursor 输出编排
38+
└── utils/
39+
├── frontmatter.ts # YAML frontmatter 解析/序列化
40+
├── toml.ts # TOML 工具
41+
└── fs.ts # 文件系统工具
42+
```
43+
44+
## 架构设计原则
45+
46+
- **三阶段 Pipeline**: Scanner → Converter → Writer
47+
- **Scanner 提取可复用函数**: `scanSkillsDir()`, `scanAgentsDir()` 等被 claude.ts 和 plugin.ts 共用
48+
- **Converter 无副作用**: 接收数据，返回 `ConvertedFile`，不直接写文件
49+
- **Writer 负责编排**: 调用多个 converter，处理合并逻辑（如多个 instruction 合并为一个 AGENTS.md）
50+
- **降级策略**: 目标平台不支持的功能降级为文档/规则，并输出 warning
51+
52+
## 开发规范
53+
54+
### 添加新资源类型
55+
1. 在 `types.ts` 添加类型定义
56+
2. 在 `scanner/claude.ts` 添加扫描函数（导出为可复用）
57+
3. 在 `scanner/plugin.ts` 集成
58+
4. 创建 `converter/xxx.ts`，实现三个平台的转换
59+
5. 在三个 `writer/*.ts` 中调用 converter
60+
6. 添加测试
61+
62+
### 添加新目标平台
63+
1. 在 `types.ts` 的 `Platform` 联合类型添加新值
64+
2. 每个 `converter/*.ts` 添加新平台的转换逻辑
65+
3. 创建 `writer/newplatform.ts`
66+
4. 在 `index.ts` 注册
67+
5. 在 `tui.ts` 的 `selectPlatforms()` 添加选项
68+
6. 添加测试
69+
70+
### Frontmatter 解析容错
71+
- 社区插件的 YAML frontmatter 可能格式不规范
72+
- `scanSkillsDir()` 和 `scanAgentsDir()` 已加 try-catch
73+
- 解析失败时保留原始内容，frontmatter 设为空对象
74+
75+
### 测试
76+
- 测试文件在 `src/__tests__/`
77+
- test-fixture/ 目录提供完整的 Claude Code 项目示例
78+
- 运行: `npm test` 或 `npx vitest run`
79+
- 每个 converter 模块有独立测试文件
80+
81+
### npm 发布
82+
- 包名: `@disdjj/acplugin`
83+
- 账号有 2FA，发布需要 OTP: `npm publish --access=public`
84+
- `prepublishOnly` 自动编译
85+
- `files` 字段排除了 `dist/__tests__/`
86+
87+
## Git 规范
88+
89+
- commit message 使用 conventional commits 格式
90+
- 仓库: https://github.com/TokenRollAI/acplugin
91+
- 主分支: main

‎rules/claude-instructions.mdc‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
description: Project instructions imported from Claude Code CLAUDE.md
3+
alwaysApply: true
4+
---
5+
# acplugin 项目规范
6+
7+
## 项目概述
8+
9+
acplugin 是一个 CLI 工具，将 Claude Code 插件（Skills、Instructions、MCP、Agents、Commands、Hooks）转换为 Codex CLI、OpenCode 和 Cursor 格式。
10+
11+
## 技术栈
12+
13+
- TypeScript + Node.js (CommonJS)
14+
- Commander.js (CLI)
15+
- @inquirer/prompts + chalk (TUI)
16+
- gray-matter (YAML frontmatter)
17+
- @iarna/toml (TOML 序列化)
18+
- vitest (测试)
19+
20+
## 项目结构
21+
22+
```
23+
src/
24+
├── index.ts # CLI 入口 + 交互式 wizard
25+
├── types.ts # 所有类型定义
26+
├── github.ts # GitHub 仓库下载
27+
├── tui.ts # TUI 交互（wizard、checkbox、彩色输出）
28+
├── scanner/
29+
│ ├── claude.ts # .claude/ 项目结构扫描（导出可复用函数）
30+
│ └── plugin.ts # .claude-plugin/ 插件格式扫描
31+
├── converter/
32+
│ ├── skill.ts # SKILL.md 转换
33+
│ ├── instructions.ts # CLAUDE.md → AGENTS.md / .mdc
34+
│ ├── mcp.ts # .mcp.json → TOML / JSON
35+
│ ├── agent.ts # Agent 定义转换（含降级策略）
36+
│ ├── command.ts # Command 转换
37+
│ └── hooks.ts # Hooks 转换（含兼容性报告）
38+
├── writer/
39+
│ ├── codex.ts # Codex 输出编排
40+
│ ├── opencode.ts # OpenCode 输出编排
41+
│ └── cursor.ts # Cursor 输出编排
42+
└── utils/
43+
├── frontmatter.ts # YAML frontmatter 解析/序列化
44+
├── toml.ts # TOML 工具
45+
└── fs.ts # 文件系统工具
46+
```
47+
48+
## 架构设计原则
49+
50+
- **三阶段 Pipeline**: Scanner → Converter → Writer
51+
- **Scanner 提取可复用函数**: `scanSkillsDir()`, `scanAgentsDir()` 等被 claude.ts 和 plugin.ts 共用
52+
- **Converter 无副作用**: 接收数据，返回 `ConvertedFile`，不直接写文件
53+
- **Writer 负责编排**: 调用多个 converter，处理合并逻辑（如多个 instruction 合并为一个 AGENTS.md）
54+
- **降级策略**: 目标平台不支持的功能降级为文档/规则，并输出 warning
55+
56+
## 开发规范
57+
58+
### 添加新资源类型
59+
1. 在 `types.ts` 添加类型定义
60+
2. 在 `scanner/claude.ts` 添加扫描函数（导出为可复用）
61+
3. 在 `scanner/plugin.ts` 集成
62+
4. 创建 `converter/xxx.ts`，实现三个平台的转换
63+
5. 在三个 `writer/*.ts` 中调用 converter
64+
6. 添加测试
65+
66+
### 添加新目标平台
67+
1. 在 `types.ts` 的 `Platform` 联合类型添加新值
68+
2. 每个 `converter/*.ts` 添加新平台的转换逻辑
69+
3. 创建 `writer/newplatform.ts`
70+
4. 在 `index.ts` 注册
71+
5. 在 `tui.ts` 的 `selectPlatforms()` 添加选项
72+
6. 添加测试
73+
74+
### Frontmatter 解析容错
75+
- 社区插件的 YAML frontmatter 可能格式不规范
76+
- `scanSkillsDir()` 和 `scanAgentsDir()` 已加 try-catch
77+
- 解析失败时保留原始内容，frontmatter 设为空对象
78+
79+
### 测试
80+
- 测试文件在 `src/__tests__/`
81+
- test-fixture/ 目录提供完整的 Claude Code 项目示例
82+
- 运行: `npm test` 或 `npx vitest run`
83+
- 每个 converter 模块有独立测试文件
84+
85+
### npm 发布
86+
- 包名: `@disdjj/acplugin`
87+
- 账号有 2FA，发布需要 OTP: `npm publish --access=public`
88+
- `prepublishOnly` 自动编译
89+
- `files` 字段排除了 `dist/__tests__/`
90+
91+
## Git 规范
92+
93+
- commit message 使用 conventional commits 格式
94+
- 仓库: https://github.com/TokenRollAI/acplugin
95+
- 主分支: main

0 commit comments

Comments
 (0)