publish-release - SKILL.md Agent Skill

name: publish-release description: Full release workflow for openclaw-web-search. Use when the user wants to publish a new version to npm and GitHub. Triggers include: "发布新版本", "publish release", "打包发布", "推送 npmjs", "出一个版本", "release", or any mention of publishing/releasing this plugin. ALWAYS use this skill instead of making up a release process from scratch — this captures the exact conventions and security requirements for this project.

openclaw-web-search 发布规范

完整的版本发布流程，按顺序执行以下各步骤。

0. 准备工作

确认当前目录为项目根目录 /path/to/openclaw-web-search/
确认工作树干净或只有预期修改：git status --short
确认当前分支为 main：git branch --show-current
确认版本号（今日日期格式 YYYY.M.D，例如 2026.3.30）

1. 安全检查（必做，不可跳过）

1.1 扫描真实 API Key

# 扫描已跟踪文件中的秘钥格式
git grep -rn "mk-[A-Z0-9]\{30,\}" -- ':!*.test.ts'
git grep -rn "sk-[A-Za-z0-9]\{20,\}" -- ':!*.test.ts'

# 扫描 git 历史
git log --all -p | grep -E "mk-[A-Z0-9]{30,}|sk-[A-Za-z0-9]{20,}" | head -5

预期：无输出（无匹配）。如有输出，立即停止，清理泄露的秘钥后再继续。

1.2 检查 .env 文件是否已 gitignore

ls -la .env* 2>&1
git check-ignore -v .env .env.local 2>&1

预期：无 .env* 文件存在，或已被 .gitignore 排除。

1.3 验证测试文件中的 key 均为占位符

grep -rn "apiKey.*\"" src/ | grep -v "mk-test\|sk-test\|placeholder\|vi.fn\|mockReturnValue\|searchConfig"

预期：无真实 key 格式的输出。

2. 运行测试

npm test

预期：所有测试通过（Tests X passed (X)）。失败则修复后再继续。

也运行类型检查：

npm run check

预期：无输出（无 TypeScript 错误）。

3. 更新版本号

版本号格式为 YYYY.M.D（例如 2026.3.30）。

3.1 更新 package.json 中的 version 字段。

3.2 如果当前 version 已是今日日期，且尚未在 npm 上发布，则直接跳过（无需更改）。

3.3 确认 npm 上不存在同版本：

npm view @ww-ai-lab/openclaw-web-search versions --json

4. 更新 CHANGELOG.md

在 CHANGELOG.md 文件顶部新增版本章节。重要规则：

日期：## YYYY.M.D
内容：条目列表（-），说明本版本的新功能、修复和变更
语言：中文
不要删除旧版本的内容

5. 更新 README.md（如有必要）

检查以下内容是否需要更新：

Provider 支持表格（已实现 / 规划中 状态）
路线图（标记已完成阶段为 ✅）
故障排除章节（新增已知问题说明）
安装说明（更新版本要求说明）

6. 验证 npm 打包内容

npm pack --dry-run

检查清单：

无 *.test.ts 文件
无 .env* 文件
无 node_modules/
无 openspec/、docs/、AGENTS.md
包含：index.ts、src/providers/**/*-provider.ts、src/providers/shared/*.ts、openclaw.plugin.json、README.md、CHANGELOG.md

如发现测试文件：更新 package.json 的 files 字段为精确文件列表（而非简单的 "src"），确保仅列生产代码文件。

注意：files 字段是白名单，.npmignore 对 files 白名单内的目录不生效；必须在 files 字段中精确控制。

7. 提交发布前变更

如有文件修改（README、CHANGELOG、package.json 等），先提交：

git add README.md CHANGELOG.md package.json .npmignore   # 按实际修改文件
git commit -m "chore: prepare v<VERSION> release

- 简述本版本的主要变更"

8. 发布到 npm

npm publish --access public

预期输出包含：+ @ww-ai-lab/openclaw-web-search@<VERSION>

如遇 403 Forbidden，检查 npm 登录状态：npm whoami

9. 打 Tag 并推送 GitHub

git tag v<VERSION>
git push origin main
git push origin v<VERSION>

预期：main 分支和 tag 均推送成功。

10. 创建 GitHub Release

将 release notes 写入临时文件（避免多行字符串在 shell 中的编码问题），再调用 gh：

cat > /tmp/release-notes-<VERSION>.md << 'NOTES'
## 新增功能

### （在这里描述新功能）

## 问题修复

### 修复：（在这里描述修复内容）

## 其他变更

- （条目列表）

## 安装

```bash
openclaw plugins install @ww-ai-lab/openclaw-web-search
openclaw plugins enable openclaw-web-search
openclaw gateway restart

要求 OpenClaw >= 2026.3.28

npm

@ww-ai-lab/openclaw-web-search@ NOTES

gh release create v
--title "v - <简短标题>"
--notes-file /tmp/release-notes-.md
--repo WW-AI-Lab/openclaw-web-search


**验证**：

```bash
gh release list --repo WW-AI-Lab/openclaw-web-search | head -3

11. 验证发布结果

# 验证 npm
npm view @ww-ai-lab/openclaw-web-search versions --json

# 验证 GitHub release
gh release view v<VERSION> --repo WW-AI-Lab/openclaw-web-search

常见问题

npm publish 403

npm whoami 确认已登录
npm login 重新认证

gh release create 无输出

检查 tag 是否已推送：git ls-remote origin v<VERSION>
检查 gh auth status

版本已存在于 npm

npm 版本不可覆盖发布，需改用新版本号（如同日发布多次可用 YYYY.M.D-1）

@sinclair/typebox 插件加载失败

参见 README 故障排除章节，创建 symlink 解决。

快速参考：版本号规范

场景	版本示例
常规功能发布	`2026.3.30`
同日第二次发布	`2026.3.30-1`
Beta 版	`2026.3.30-beta.1`

版本格式应始终与 OpenClaw 主体版本风格保持一致。