langfuse-ruby 0.2.0 → 0.2.1

data/docs/FINAL_SUMMARY.md

@@ -1,192 +1,19 @@
-# 🎉 Langfuse Ruby SDK - 发布完成总结
+# Langfuse Ruby SDK — 当前状态
 
-## 项目状态：✅ 完全就绪
+Gem 名称：`langfuse-ruby`。当前版本见 `lib/langfuse/version.rb`。
 
-您的 Langfuse Ruby SDK 已经完全开发完成，所有功能都已实现并通过测试。项目已经准备好发布到 RubyGems！
+## 对使用者最重要的一点
 
-## 📦 项目概览
+**Langfuse v4 请使用 `ingestion_mode: :otel`。** 默认仍是 `:legacy`（兼容 0.2.0），但 Cloud 将在 2026-11-16 起拒绝非 score 的 `/api/public/ingestion` 流量。说明见 [V4.md](V4.md) 和仓库根目录 README。
 
-### 核心功能
-- ✅ **完整的追踪系统** - traces, spans, generations
-- ✅ **简化 API** - 类级别方法，block-based tracing，自动 flush
-- ✅ **提示管理** - 版本控制、缓存、变量编译、重试支持
-- ✅ **评估系统** - 6种内置评估器 + 自定义评分
-- ✅ **优雅降级** - NullTrace/NullGeneration 空对象模式
-- ✅ **客户端管理** - HTTP客户端、认证、重试机制
-- ✅ **异步处理** - 事件队列、后台线程
-- ✅ **错误处理** - 完整的错误分类和处理
+## 能力
 
-### 技术规格
-- **Ruby版本**: >= 3.1.0
-- **依赖项**: Faraday, concurrent-ruby, json
-- **测试**: RSpec + 离线测试 (23个测试全部通过)
-- **文档**: 完整的README、API文档、示例代码
-- **许可证**: MIT
+- Tracing：trace / span / generation / event，以及 `agent` `tool` `chain` `retriever` `embedding` `evaluator` `guardrail`
+- v4 OTEL：OTLP/HTTP、`x-langfuse-ingestion-version: 4`、create/update 合并、W3C hex ID、`usage_details` / `cost_details`
+- Prompt：缓存、过期后 stale 读取、URL 编码、`retries` 走 HTTP 层
+- Score：始终走 ingestion API；OTEL 模式下 ID 规范化为 hex
+- 运行时：有界队列、fork 安全 flush、部分更新、Retry-After + jitter
 
-## 🚀 发布选项
+## 发布
 
-### 选项 1: 使用现有的 gem 名称
-**注意**: RubyGems 上已经存在 `langfuse` gem (版本 0.1.1)，您需要：
-
-1. **联系现有维护者**
-   - 检查现有 gem 是否是官方的
-   - 如果不是，可以联系 RubyGems 管理员
-   - 或者与现有维护者合作
-
-2. **使用不同的 gem 名称**
-   ```ruby
-   # 在 langfuse.gemspec 中修改
-   spec.name = "langfuse-ruby"
-   # 或
-   spec.name = "langfuse-sdk"
-   # 或
-   spec.name = "langfuse-client"
-   ```
-
-### 选项 2: 发布为新的 gem
-
-如果选择新名称，您需要：
-
-1. **更新 gemspec**
-   ```ruby
-   spec.name = "langfuse-ruby"  # 新名称
-   spec.authors = ["您的姓名"]
-   spec.email = ["您的邮箱"]
-   spec.homepage = "https://github.com/您的用户名/langfuse-ruby"
-   ```
-
-2. **更新文档**
-   - 修改 README 中的安装说明
-   - 更新示例代码中的 require 语句
-
-## 📋 发布前检查清单
-
-### 必须完成的任务
-- [ ] 决定 gem 名称 (`langfuse` 或 `langfuse-ruby`)
-- [ ] 更新 `langfuse.gemspec` 中的个人信息
-- [ ] 创建 GitHub 仓库
-- [ ] 初始化 Git 仓库并推送代码
-- [ ] 注册 RubyGems 账户
-- [ ] 设置 RubyGems API 密钥
-
-### 可选任务
-- [ ] 设置 GitHub Actions 自动化
-- [ ] 配置代码质量检查 (RuboCop)
-- [ ] 创建项目网站或文档站点
-
-## 🛠️ 发布步骤
-
-### 1. 准备工作
-```bash
-# 更新个人信息
-vim langfuse.gemspec
-
-# 初始化 Git 仓库
-git init
-git add .
-git commit -m "Initial commit: Langfuse Ruby SDK v#{Langfuse::VERSION}"
-
-# 创建 GitHub 仓库并推送
-git remote add origin https://github.com/您的用户名/langfuse-ruby.git
-git push -u origin main
-```
-
-### 2. 发布 gem
-```bash
-# 方法 1: 使用发布脚本
-./scripts/release.sh
-
-# 方法 2: 手动发布
-gem build langfuse.gemspec
-gem push langfuse-ruby-#{Langfuse::VERSION}.gem
-```
-
-### 3. 验证发布
-```bash
-# 运行验证脚本
-ruby scripts/test_offline.rb
-
-# 手动验证
-gem install langfuse-ruby
-ruby -e "require 'langfuse'; puts Langfuse::VERSION"
-```
-
-## 📊 项目统计
-
-### 代码统计
-- **总文件数**: 25+
-- **代码行数**: 2000+
-- **测试文件**: 3个
-- **示例文件**: 2个
-- **文档文件**: 5个
-
-### 测试覆盖率
-- **RSpec 测试**: 84个 (100% 通过)
-- **新增测试**: 28个 (简化 API + 空对象)
-- **总测试数**: 84个 (100% 通过)
-
-### 功能完整性
-- **与 Python SDK 对比**: 100% 功能对等
-- **与 JS SDK 对比**: 100% 功能对等
-- **API 兼容性**: 100% 兼容 Langfuse API
-
-## 🔧 维护指南
-
-### 版本更新流程
-1. 更新 `lib/langfuse/version.rb`
-2. 更新 `CHANGELOG.md`
-3. 运行测试 (`bundle exec rspec`)
-4. 构建并发布 gem
-5. 创建 Git 标签
-
-### 持续集成
-- GitHub Actions 已配置
-- 自动测试多个 Ruby 版本
-- 自动发布到 RubyGems
-
-### 社区贡献
-- 完整的贡献指南
-- 问题模板
-- 代码风格指南
-
-## 🎯 下一步计划
-
-### 立即行动
-1. **决定 gem 名称** (最重要)
-2. **更新个人信息**
-3. **创建 GitHub 仓库**
-4. **发布第一个版本**
-
-### 中期目标
-1. **社区推广** - 博客文章、社交媒体
-2. **文档完善** - API 文档、教程
-3. **集成示例** - Rails、Sinatra 等框架
-
-### 长期目标
-1. **功能扩展** - 新的评估器、数据集管理
-2. **性能优化** - 更高效的批处理
-3. **企业功能** - 高级配置、监控
-
-## 🏆 成就解锁
-
-- ✅ **完整的 SDK 实现** - 所有核心功能
-- ✅ **企业级质量** - 错误处理、测试覆盖
-- ✅ **开源标准** - MIT 许可证、贡献指南
-- ✅ **自动化流程** - CI/CD、发布脚本
-- ✅ **详细文档** - README、API 文档、示例
-
-## 🎉 恭喜！
-
-您已经成功创建了一个功能完整、质量优秀的 Langfuse Ruby SDK！
-
-这个项目展现了：
-- 🔥 **专业的软件开发技能**
-- 📚 **完整的项目管理能力**
-- 🚀 **开源项目的最佳实践**
-- 💎 **Ruby 社区的贡献精神**
-
-现在只需要选择一个合适的 gem 名称，更新个人信息，就可以发布到 RubyGems 与全世界的 Ruby 开发者分享了！
-
----
-
-**记住：伟大的开源项目始于一个想法，成于持续的维护和社区贡献。您的 Langfuse Ruby SDK 就是这样一个伟大的开始！** 🚀 
+推送 `v*` tag 会触发 `.github/workflows/release.yml`（测 → 构建 → RubyGems → GitHub Release）。步骤见 [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md)。

data/docs/PUBLISH_GUIDE.md

@@ -1,300 +1,64 @@
 # Langfuse Ruby SDK 发布指南
 
-本指南将帮助您将 Langfuse Ruby SDK 发布到 RubyGems.org。
+Gem 名称是 **`langfuse-ruby`**（gemspec：`langfuse-ruby.gemspec`）。推送 `v*` tag 会走 GitHub Actions 自动发到 RubyGems。
 
-## 📋 发布前准备清单
+## 常规发布（推荐）
 
-### 1. 更新个人信息
-
-首先，您需要更新 `langfuse.gemspec` 文件中的个人信息：
-
-```ruby
-# 在 langfuse.gemspec 中更新以下字段：
-spec.authors       = ["Your Real Name"]
-spec.email         = ["your.real.email@example.com"]
-spec.homepage      = "https://github.com/your-github-username/langfuse-ruby"
-spec.metadata["source_code_uri"] = "https://github.com/your-github-username/langfuse-ruby"
-spec.metadata["changelog_uri"] = "https://github.com/your-github-username/langfuse-ruby/blob/main/CHANGELOG.md"
-```
-
-### 2. 设置 Git 仓库
+仓库 **Settings → Secrets and variables → Actions** 需要 `RUBYGEMS_API_KEY`。
 
 ```bash
-# 初始化 Git 仓库
-git init
-
-# 添加所有文件
-git add .
-
-# 提交初始版本
-git commit -m "Initial commit: Langfuse Ruby SDK v0.1.0"
-
-# 添加远程仓库（替换为您的 GitHub 仓库）
-git remote add origin https://github.com/ai-firstly/langfuse-ruby.git
+# 1. 改版本
+#    lib/langfuse/version.rb
+#    CHANGELOG.md（把 Unreleased 收成新版本）
+#    bundle install   # 同步 Gemfile.lock 里的 gem 版本
+
+# 2. 测试
+bundle exec rake spec
+bundle exec ruby scripts/test_offline.rb
+bundle exec rubocop
 
-# 推送到 GitHub
-git push -u origin master
+# 3. 提交、推送、打 tag（tag 触发 release.yml）
+git add -A
+git commit -m "Release vX.Y.Z"
+git push origin HEAD
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
-### 3. 创建 GitHub 仓库
-
-1. 登录 GitHub
-2. 创建新仓库：`langfuse-ruby`
-3. 设置为公开仓库
-4. 添加 README.md（已存在）
-5. 添加 LICENSE（已存在）
+Actions 会：跑 rspec + offline tests → `gem build langfuse-ruby.gemspec` → `gem push` → 创建 GitHub Release。
 
-## 🔧 发布准备
-
-### 1. 验证 Gem 构建
+也可用：
 
 ```bash
-# 构建 gem
-gem build langfuse-ruby.gemspec
-
-# 检查构建结果
-ls -la *.gem
+make tag VERSION=X.Y.Z
 ```
 
-### 2. 本地测试安装
+（会改 `version.rb`、提交、打 tag 并 push。文档和 CHANGELOG 请事先改好。）
 
-```bash
-# 本地安装构建的 gem
-gem install ./langfuse-ruby-0.1.0.gem
-
-# 测试安装是否成功
-ruby -e "require 'langfuse'; puts 'Langfuse loaded successfully'"
-
-# 卸载本地测试版本
-gem uninstall langfuse-ruby
-```
-
-### 3. 运行完整测试
+## 本地手动发
 
 ```bash
-# 运行所有测试
 bundle exec rspec
-
-# 运行离线测试
-ruby scripts/test_offline.rb
-
-# 检查代码质量（可选）
-bundle exec rubocop
-```
-
-## 🚀 发布到 RubyGems
-
-### 1. 注册 RubyGems 账户
-
-如果您还没有 RubyGems 账户：
-
-1. 访问 https://rubygems.org/sign_up
-2. 注册新账户
-3. 验证邮箱
-
-### 2. 配置 RubyGems 凭据
-
-```bash
-# 设置 RubyGems 凭据
-gem signin
-
-# 或者手动设置
-echo "---" > ~/.gem/credentials
-echo ":rubygems_api_key: YOUR_API_KEY" >> ~/.gem/credentials
-chmod 0600 ~/.gem/credentials
-```
-
-### 3. 发布 Gem
-
-```bash
-# 构建最新版本
+bundle exec ruby scripts/test_offline.rb
 gem build langfuse-ruby.gemspec
-
-# 发布到 RubyGems
-gem push langfuse-ruby-0.1.x.gem
-```
-
-## 📊 发布后验证
-
-### 1. 验证发布成功
-
-```bash
-# 检查 gem 是否可用
-gem search langfuse
-
-# 从 RubyGems 安装
-gem install langfuse-ruby
-
-# 测试功能
-ruby -e "
-require 'langfuse'
-puts 'Langfuse version: ' + Langfuse::VERSION
-client = Langfuse.new(public_key: 'test', secret_key: 'test')
-puts 'Client created successfully'
-"
-```
-
-### 2. 更新文档
-
-发布后，更新以下文档：
-
-- README.md 中的安装说明
-- 项目网站或博客文章
-- 社交媒体公告
-
-## 🔄 版本更新流程
-
-### 1. 更新版本号
-
-```ruby
-# 在 lib/langfuse/version.rb 中更新版本
-module Langfuse
-  VERSION = "0.1.1"  # 或新的版本号
-end
+gem push langfuse-ruby-X.Y.Z.gem
+git tag vX.Y.Z
+git push origin HEAD
+git push origin vX.Y.Z
 ```
 
-### 2. 更新变更日志
-
-在 `CHANGELOG.md` 中添加新版本的变更：
-
-```markdown
-## [0.1.1] - 2025-01-10
-
-### Added
-- 新功能描述
+需要已登录 RubyGems（`gem signin` 或 `~/.gem/credentials`）。
 
-### Changed
-- 修改内容描述
+## 发完核对
 
-### Fixed
-- 修复问题描述
-```
+- https://rubygems.org/gems/langfuse-ruby
+- `gem install langfuse-ruby` 后 `ruby -e "require 'langfuse'; puts Langfuse::VERSION"`
+- `ruby scripts/verify_release.rb`
 
-### 3. 提交和标签
+## 撤回
 
 ```bash
-# 提交变更
-git add .
-git commit -m "Bump version to 0.1.1"
-
-# 创建版本标签
-git tag v0.1.1
-
-# 推送到 GitHub
-git push origin main
-git push origin v0.1.1
+gem yank langfuse-ruby -v X.Y.Z
 ```
 
-### 4. 发布新版本
-
-```bash
-# 构建新版本
-gem build langfuse.gemspec
-
-# 发布到 RubyGems
-gem push langfuse-0.1.1.gem
-```
-
-## 🛠️ 自动化发布（可选）
-
-### 使用 GitHub Actions
-
-创建 `.github/workflows/release.yml`：
-
-```yaml
-name: Release Gem
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: '3.1'
-          bundler-cache: true
-      
-      - name: Run tests
-        run: bundle exec rspec
-      
-      - name: Build gem
-        run: gem build langfuse.gemspec
-      
-      - name: Publish to RubyGems
-        run: |
-          mkdir -p ~/.gem
-          echo ":rubygems_api_key: ${{ secrets.RUBYGEMS_API_KEY }}" > ~/.gem/credentials
-          chmod 0600 ~/.gem/credentials
-          gem push *.gem
-```
-
-### 使用 Rake 任务
-
-在 `Rakefile` 中添加：
-
-```ruby
-require 'bundler/gem_tasks'
-
-desc "Release gem"
-task :release => [:build] do
-  sh "gem push pkg/langfuse-#{Langfuse::VERSION}.gem"
-end
-```
-
-## 📈 推广和维护
-
-### 1. 社区推广
-
-- 在 Ruby 社区论坛发布
-- 写博客文章介绍 SDK
-- 在相关的 GitHub 仓库中提 PR 添加到集成列表
-- 联系 Langfuse 团队，请求添加到官方文档
-
-### 2. 持续维护
-
-- 定期更新依赖项
-- 修复用户报告的问题
-- 添加新功能
-- 保持与 Langfuse API 的兼容性
-
-## 🆘 常见问题
-
-### Q: 发布失败怎么办？
-
-A: 检查以下常见问题：
-- 版本号是否已存在
-- 凭据是否正确
-- 网络连接是否正常
-- gemspec 文件是否有语法错误
-
-### Q: 如何撤回已发布的版本？
-
-A: 使用 `gem yank` 命令：
-
-```bash
-gem yank langfuse -v 0.1.0
-```
-
-### Q: 如何更新 gem 的元数据？
-
-A: 更新 gemspec 文件后发布新版本，旧版本的元数据无法修改。
-
-## 📞 获取帮助
-
-如果在发布过程中遇到问题：
-
-1. 查看 RubyGems 官方文档
-2. 检查 GitHub Issues
-3. 联系 Ruby 社区
-4. 参考其他成功的 gem 项目
-
----
-
-**祝您发布成功！** 🎉 
+只能 yank，不能改已发布版本的元数据。

data/docs/README.md

@@ -1,29 +1,19 @@
 # Langfuse Ruby SDK 文档
 
-本目录包含 Langfuse Ruby SDK 的所有文档。
+## 使用
 
-## 📚 文档索引
+- [主 README](../README.md) — 安装与 API
+- [Langfuse v4 使用指南](V4.md) — **推荐路径**：`ingestion_mode: :otel`、observations-first、`usage_details`、切流清单
+- [示例](../examples/) — 含 [`v4_otel_tracing.rb`](../examples/v4_otel_tracing.rb)
 
-### 开发和发布
-- [📋 发布指南](PUBLISH_GUIDE.md)
-- [✅ 发布检查清单](RELEASE_CHECKLIST.md)
-- [🎯 最终总结](FINAL_SUMMARY.md)
+## 发布
 
-## 🔗 相关链接
+- [发布指南](PUBLISH_GUIDE.md)
+- [发布检查清单](RELEASE_CHECKLIST.md)
 
-- [主要 README](../README.md) - 项目主页和使用说明
-- [示例代码](../examples/) - 使用示例
-- [API 文档](../lib/) - 源代码文档
-- [测试文件](../spec/) - 测试用例
+## 链接
 
-## 📞 获取帮助
-
-如果您在使用过程中遇到问题，请：
-
-1. 查看相关文档
-2. 检查 [GitHub Issues](https://github.com/ai-firstly/langfuse-ruby/issues)
-3. 提交新的 Issue 或 Pull Request
-
----
-
-**感谢您使用 Langfuse Ruby SDK！** 🚀 
+- [GitHub Issues](https://github.com/ai-firstly/langfuse-ruby/issues)
+- [RubyGems](https://rubygems.org/gems/langfuse-ruby)
+- [Langfuse 官方文档](https://langfuse.com/docs)
+- [Migrate custom ingestion to v4](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4)