ww-ai-lab 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 主体版本风格保持一致。