Kode-cli/docs/PUBLISH_GUIDE.md

发包脚本使用指南

Kode 项目提供了两套发包流程，专注于npm发布，不涉及git操作：

🚀 快速使用

开发版本发布 (测试用)

npm run publish:dev

正式版本发布

npm run publish:release

📦 发包策略

1. 开发版本 (dev tag)

• 目的: 内部测试和预发布验证
• 版本格式: 1.1.16-dev.1, 1.1.16-dev.2
• 安装方式: npm install -g @shareai-lab/kode@dev
• 特点:
  • 自动递增 dev 版本号
  • 不影响正式版本的用户
  • 可以快速迭代测试
  • 临时修改package.json，发布后自动恢复

2. 正式版本 (latest tag)

• 目的: 面向最终用户的稳定版本
• 版本格式: 1.1.16, 1.1.17, 1.2.0
• 安装方式: npm install -g @shareai-lab/kode (默认)
• 特点:
  • 语义化版本控制
  • 严格的发布流程
  • 包含完整的测试和检查
  • 永久更新package.json版本号

🛠️ 脚本功能详解

开发版本发布 (scripts/publish-dev.js)

自动化流程:

1. 🔢 读取当前基础版本
2. 📊 查询npm上现有的dev版本，自动递增
3. 📝 临时更新package.json版本号
4. 🔨 构建项目
5. 🔍 运行预发布检查
6. 📤 发布到npm的dev tag
7. 🔄 恢复package.json到原始版本

使用场景:

• 功能开发完成，需要内部测试
• PR验证前的最终测试
• 快速修复验证

安全特性:

• 临时修改package.json，发布后自动恢复
• 失败时自动回滚
• 不会改变本地版本状态

正式版本发布 (scripts/publish-release.js)

交互式流程:

1. 📦 显示当前版本
2. 🔢 选择版本升级类型:
   • patch (1.1.16 → 1.1.17): 修复 bug
   • minor (1.1.16 → 1.2.0): 新功能
   • major (1.1.16 → 2.0.0): 破坏性变更
   • custom: 自定义版本号
3. ✅ 检查版本是否已在npm上存在
4. 🤔 确认发布信息
5. 📝 更新package.json版本号（永久）
6. 🧪 运行测试和类型检查
7. 🔨 构建项目
8. 🔍 运行预发布检查
9. 📤 发布到npm (默认latest tag)
10. 💡 提示后续git操作建议

安全特性:

• 交互式确认，避免误发布
• 检查版本冲突
• 测试失败时自动回滚版本号
• 永久保留版本更改供git提交

🎯 最佳实践

开发流程建议

# 1. 开发功能
# ... 开发代码 ...

# 2. 发布开发版本测试
npm run publish:dev
# 安装测试: npm install -g @shareai-lab/kode@dev

# 3. 测试通过后发布正式版本
npm run publish:release

# 4. 手动处理git操作（如需要）
git add package.json
git commit -m "chore: bump version to x.x.x"
git tag vx.x.x
git push origin main
git push origin vx.x.x

版本号管理

• 开发版: 基于当前正式版本自动递增 (1.1.16-dev.1 → 1.1.16-dev.2)
• 正式版: 遵循 语义化版本 规范
• 版本检查: 自动检查npm上是否已存在相同版本

标签管理

# 查看所有版本
npm view @shareai-lab/kode versions --json

# 查看 dev 版本
npm view @shareai-lab/kode@dev version

# 查看最新正式版本  
npm view @shareai-lab/kode@latest version

🔧 故障排除

常见问题

发布失败怎么办？

• 开发版本：脚本会自动回滚package.json
• 正式版本：检查错误信息，修复后重新运行

版本号冲突？

• 开发版本会自动递增，不会冲突
• 正式版本发布前会检查是否已存在

权限问题？

• 确保已登录npm: npm whoami
• 确保有包的发布权限: npm owner ls @shareai-lab/kode

测试失败？

• 正式版本发布会自动回滚版本号
• 修复测试问题后重新运行

手动操作

# 查看当前登录用户
npm whoami

# 登录npm
npm login

# 查看包信息
npm view @shareai-lab/kode

# 手动发布（不推荐）
npm publish --tag dev  # 开发版本
npm publish            # 正式版本

📊 监控和分析

# 查看包下载统计
npm view @shareai-lab/kode

# 查看所有版本的详细信息
npm view @shareai-lab/kode versions --json

# 测试安装
npm install -g @shareai-lab/kode@dev
kode --version

⚙️ Git集成建议

虽然发包脚本不包含git操作，但建议的git工作流程：

开发版本发布后:

# 开发版本不需要git操作，package.json已自动恢复
# 继续开发即可

正式版本发布后:

# package.json已更新版本号，建议提交
git add package.json
git commit -m "chore: bump version to $(node -p "require('./package.json').version")"
git tag "v$(node -p "require('./package.json').version")"
git push origin main
git push origin --tags

---

通过这套纯npm发包系统，你可以：

• 🚀 快速发布开发版本进行内部测试
• 🛡️ 安全发布正式版本给最终用户
• 📈 保持清晰的版本管理
• ⚡ 专注于包发布，git操作完全可控
• 🔄 灵活的版本回滚和恢复机制