Skip to content

Commit d75ea27

Browse files
liueicliueic
committed
feat: GitHub Action Workflows
1 parent a15f6a1 commit d75ea27

File tree

4 files changed

+261
-4
lines changed

4 files changed

+261
-4
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Publish to npm
2+
3+
on:
4+
# Git Tag 触发自动发布 (格式: v1.0.1, v1.1.0, v2.0.0)
5+
push:
6+
tags:
7+
- 'v*'
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: 检出代码
15+
uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0 # 获取完整历史记录以检测标签
18+
19+
- name: 设置 Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '18'
23+
registry-url: 'https://registry.npmjs.org'
24+
25+
- name: 检测版本号
26+
id: version
27+
run: |
28+
# 从 Git Tag 提取版本号
29+
TAG_NAME="${GITHUB_REF#refs/tags/}"
30+
# 移除 'v' 前缀（如果存在）
31+
VERSION="${TAG_NAME#v}"
32+
33+
# 验证版本号格式 (x.y.z)
34+
if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
35+
echo "错误: 版本号格式无效: $VERSION"
36+
echo "版本号必须是 x.y.z 格式 (例如: 1.0.1)"
37+
exit 1
38+
fi
39+
40+
echo "检测到 Git Tag: $TAG_NAME"
41+
echo "提取版本号: $VERSION"
42+
echo "version=$VERSION" >> $GITHUB_OUTPUT
43+
44+
- name: 更新 package.json 版本号
45+
run: |
46+
VERSION="${{ steps.version.outputs.version }}"
47+
npm version $VERSION --no-git-tag-version
48+
echo "已更新 package.json 版本号为: $VERSION"
49+
50+
- name: 安装依赖
51+
run: npm ci
52+
53+
- name: 运行测试 (如果存在)
54+
run: |
55+
if npm run test 2>/dev/null; then
56+
echo "测试通过"
57+
else
58+
echo "跳过测试 (测试脚本不存在或失败)"
59+
fi
60+
continue-on-error: true
61+
62+
- name: 发布到 npm
63+
env:
64+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
65+
run: |
66+
echo "开始发布版本 ${{ steps.version.outputs.version }} 到 npm..."
67+
npm publish
68+
echo "成功发布版本 ${{ steps.version.outputs.version }} 到 npm"
69+

‎.npmignore‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# 开发文件
2+
.env
3+
.env.example
4+
.env.*
5+
*.log
6+
7+
# 测试文件
8+
test/
9+
tests/
10+
*.test.js
11+
*.spec.js
12+
13+
# 文档和配置
14+
docs/
15+
demo/
16+
config/
17+
.cursor/
18+
*.md
19+
!README.md
20+
21+
# Git 相关
22+
.git/
23+
.gitignore
24+
.github/
25+
26+
# IDE 配置
27+
.vscode/
28+
.idea/
29+
*.swp
30+
*.swo
31+
*~
32+
33+
# 缓存目录
34+
cache/
35+
36+
# 操作系统文件
37+
.DS_Store
38+
Thumbs.db
39+
40+
# 构建和临时文件
41+
node_modules/
42+
.npm
43+
dist/
44+
build/
45+
*.tmp
46+
47+
# 其他
48+
coverage/
49+
.nyc_output/
50+

‎docs/GITHUB_ACTIONS_PUBLISH.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# GitHub Actions 自动发布到 npm 使用指南
2+
3+
本项目已配置 GitHub Actions 工作流，支持基于 Git Tag 的自动打包并发布到 npmjs 仓库。
4+
5+
## 🚀 快速开始
6+
7+
### 前置条件
8+
9+
1. **npm 账号和 Token**
10+
- 在 [npmjs.com](https://www.npmjs.com/) 注册账号（如果还没有）
11+
- 创建 Access Token：
12+
- 访问 https://www.npmjs.com/settings/your-username/tokens
13+
- 点击 "Generate New Token" → "Automation"
14+
- 复制生成的 token
15+
16+
2. **配置 GitHub Secrets**
17+
- 进入你的 GitHub 仓库
18+
- 点击 `Settings` → `Secrets and variables` → `Actions`
19+
- 点击 `New repository secret`
20+
- 名称：`NPM_TOKEN`
21+
- 值：粘贴你的 npm Access Token
22+
- 点击 `Add secret`
23+
24+
## 📦 发布方式
25+
26+
### Git Tag 自动触发（唯一方式）
27+
28+
工作流完全自动化，只需推送 Git Tag 即可触发发布：
29+
30+
1. **在本地创建并推送 Git Tag**：
31+
```bash
32+
git tag v1.0.1
33+
git push origin v1.0.1
34+
```
35+
36+
2. **GitHub Actions 会自动执行**：
37+
- ✅ 检测到 Tag 推送
38+
- ✅ 提取版本号（自动移除 `v` 前缀）
39+
- ✅ 更新 `package.json` 版本号
40+
- ✅ 安装依赖
41+
- ✅ 运行测试（如果存在）
42+
- ✅ 发布到 npm
43+
44+
**Tag 命名规则**：
45+
- 必须以 `v` 开头（例如：`v1.0.1`）
46+
- 版本号格式：`x.y.z`（例如：`1.0.1`, `1.1.0`, `2.0.0`）
47+
- 工作流会自动验证版本号格式
48+
49+
## 🔍 工作流说明
50+
51+
### 工作流步骤
52+
53+
1. **检出代码** - 获取最新代码和完整 Git 历史
54+
2. **设置 Node.js** - 安装 Node.js 18 并配置 npm registry
55+
3. **检测版本号** - 从 Git Tag 中提取版本号（移除 `v` 前缀）
56+
4. **验证版本号** - 确保版本号格式为 `x.y.z`
57+
5. **更新 package.json** - 自动更新版本号
58+
6. **安装依赖** - 运行 `npm ci`
59+
7. **运行测试** - 如果存在测试脚本（可选，失败不阻止发布）
60+
8. **发布到 npm** - 自动发布到 npmjs 仓库
61+
62+
### 版本号验证
63+
64+
工作流会自动验证版本号格式，必须是 `x.y.z` 格式（例如：`1.0.1`），否则会报错并停止工作流。
65+
66+
## 📝 发布清单
67+
68+
发布前请确认：
69+
70+
- [ ] `package.json` 中的 `name` 字段正确（确保 npm 包名可用）
71+
- [ ] `package.json` 中的 `repository` URL 已更新为实际仓库地址
72+
- [ ] `package.json` 中的 `author` 信息已更新
73+
- [ ] GitHub Secrets 中已配置 `NPM_TOKEN`
74+
- [ ] 代码已通过测试（如果有）
75+
- [ ] 版本号遵循语义化版本规范（SemVer）
76+
- [ ] 已提交所有代码更改到主分支
77+
78+
## ⚠️ 注意事项
79+
80+
1. **npm 包名唯一性**
81+
- 确保 `mcp-pubmed-llm-server` 这个包名在 npm 上可用
82+
- 如果已被占用，需要修改 `package.json` 中的 `name` 字段
83+
84+
2. **版本号递增**
85+
- 每次发布必须使用比当前版本更高的版本号
86+
- npm 不允许发布相同或更低版本号的包
87+
88+
3. **Git Tag 与版本号**
89+
- 版本号会自动从 Git Tag 中提取
90+
- Tag 格式：`v1.0.1` → 版本号：`1.0.1`
91+
- 推送 Tag 后会自动触发发布，无需手动操作
92+
93+
4. **自动发布**
94+
- 推送 Git Tag 后，工作流会自动执行发布流程
95+
- 无需在 GitHub Actions 界面手动触发
96+
- 如果发布失败，可以在 Actions 标签页查看详细日志
97+
98+
## 🔧 故障排除
99+
100+
### 问题：发布失败，提示 "You cannot publish over the previously published versions"
101+
102+
**解决方案**：版本号已存在，需要创建新的更高版本号的 Tag（例如：从 `v1.0.0` 改为 `v1.0.1`）
103+
104+
### 问题：发布失败，提示 "Invalid package name"
105+
106+
**解决方案**：检查 `package.json` 中的 `name` 字段，确保符合 npm 命名规范
107+
108+
### 问题：GitHub Actions 提示 "NPM_TOKEN not found"
109+
110+
**解决方案**：在 GitHub 仓库的 Settings → Secrets 中添加 `NPM_TOKEN`
111+
112+
### 问题：Git Tag 触发失败或未触发
113+
114+
**解决方案**：
115+
- 确保 Tag 格式正确（必须以 `v` 开头，如 `v1.0.1`）
116+
- 确保 Tag 已推送到 GitHub（`git push origin v1.0.1`）
117+
- 检查 GitHub Actions 工作流是否启用（Settings → Actions → General）
118+
119+
### 问题：版本号格式验证失败
120+
121+
**解决方案**：
122+
- Tag 必须符合 `vx.y.z` 格式（例如：`v1.0.1`）
123+
- 版本号必须是数字格式（例如：`1.0.1`，不能是 `1.0.1-beta`）
124+
125+
## 📚 相关资源
126+
127+
- [npm 发布文档](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
128+
- [GitHub Actions 文档](https://docs.github.com/en/actions)
129+
- [语义化版本规范](https://semver.org/lang/zh-CN/)
130+

‎package.json‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
"research",
2121
"openai"
2222
],
23-
"author": "Your Name <your.email@example.com>",
23+
"author": "PancrePal-xiaoyibao Team",
2424
"license": "MIT",
2525
"dependencies": {
2626
"@modelcontextprotocol/sdk": "^0.4.0",
@@ -33,12 +33,20 @@
3333
"engines": {
3434
"node": ">=18.0.0"
3535
},
36+
"files": [
37+
"src/",
38+
"README.md",
39+
"LICENSE"
40+
],
41+
"publishConfig": {
42+
"access": "public"
43+
},
3644
"repository": {
3745
"type": "git",
38-
"url": "https://github.com/yourusername/mcp-pubmed-llm-server.git"
46+
"url": "https://github.com/PancrePal-xiaoyibao/mcp-pubmed-server-pancrpal.git"
3947
},
4048
"bugs": {
41-
"url": "https://github.com/yourusername/mcp-pubmed-llm-server/issues"
49+
"url": "https://github.com/PancrePal-xiaoyibao/mcp-pubmed-server-pancrpal/issues"
4250
},
43-
"homepage": "https://github.com/yourusername/mcp-pubmed-llm-server#readme"
51+
"homepage": "https://github.com/PancrePal-xiaoyibao/mcp-pubmed-server-pancrpal#readme"
4452
}

0 commit comments

Comments
 (0)