add-announcement

添加公告卡片

此技能可帮助你在 Agenta 侧边栏横幅系统中添加公告卡片。公告卡片显示在侧边栏底部，用户可以将其关闭。

系统概览

侧边栏横幅系统位于 web/oss/src/components/SidebarBanners/，并使用：

• 基于优先级的队列：一次只显示一个横幅
• 自动切换：横幅关闭后，显示下一个优先级最高的横幅
• 持久化关闭状态：使用 localStorage 记住已关闭的横幅
• Jotai atoms：用于响应式状态管理

两种公告类型

1. 简单的更新日志公告（最常见）

对于标准产品更新、功能和变更，只需在 changelog.json 中添加内容：

文件：web/oss/src/components/SidebarBanners/data/changelog.json

格式：

{
    "id": "changelog-YYYY-MM-DD-feature-name",
    "title": "Feature Title (Short)",
    "description": "Brief description of the feature or change.",
    "link": "https://agenta.ai/docs/changelog/feature-name"
}

ID 约定：changelog- + 日期（YYYY-MM-DD）+ 功能标识

• 示例：changelog-2026-01-09-chat-sessions
• 必须唯一，以避免冲突

标题指南：

• 不超过 40 个字符
• 清晰且具有可操作性
• 突出用户收益
• 示例："可观测性中的聊天会话"、"Playground 中的 PDF 支持"

描述指南：

• 用一句话说明，不超过 100 个字符
• 描述用户可以做什么，而非技术细节
• 示例："通过会话分组和成本分析跟踪多轮对话。"

链接约定：

• 始终指向 https://agenta.ai/docs/changelog/[feature-slug]
• 需要创建对应的更新日志文档页面

2. 自定义横幅（高级）

对于带有自定义 UI、交互或逻辑的复杂横幅（试用警告、升级提示等），你需要：

1. 在 types.ts 中添加横幅类型
2. 在 state/atoms.ts 中添加优先级
3. 在 activeBannersAtom（OSS）或 eeBannersAtom（EE）中创建横幅

何时使用自定义横幅：

• 不可关闭的横幅（例如，试用期到期）
• 自定义交互（带有 onClick 处理程序的按钮）
• 动态内容（取决于用户状态）
• 条件显示（仅在特定条件下显示）

分步指南：添加简单的更新日志公告

步骤 1：读取当前的 changelog.json

# View current entries to understand the structure
cat web/oss/src/components/SidebarBanners/data/changelog.json

步骤 2：添加条目

编辑 web/oss/src/components/SidebarBanners/data/changelog.json，并将新条目添加到数组中：

[
    {
        "id": "changelog-2024-12-16-pdf-support",
        "title": "PDF Support in Playground",
        "description": "You can now upload and test PDFs directly in the playground.",
        "link": "https://agenta.ai/docs/changelog/pdf-support-in-playground"
    },
    {
        "id": "changelog-2026-01-09-your-feature",
        "title": "Your Feature Title",
        "description": "Brief description of what users can do.",
        "link": "https://agenta.ai/docs/changelog/your-feature-slug"
    }
]

步骤 3：验证格式

• 确保 JSON 有效（没有尾随逗号，且引号正确）
• 检查 ID 是否唯一
• 确认链接 URL 与将要创建的文档页面一致

步骤 4：在本地测试

横幅会在下一次加载页面时自动显示在侧边栏中。查看方法：

1. 清除 localStorage：localStorage.removeItem('agenta:dismissed-banners')
2. 刷新页面
3. 横幅应显示在侧边栏底部

横幅优先级系统

横幅按优先级顺序显示（数字越小，越先显示）：

Priority 0: star-repo (GitHub star prompt for new users)
Priority 1: changelog (product updates) ← Most changelog entries
Priority 2: upgrade (upgrade prompts)
Priority 3: trial (trial/billing warnings)

更新日志条目的优先级会自动设为 1。

常见模式和示例

示例 1：功能公告

{
    "id": "changelog-2026-01-15-batch-evaluation",
    "title": "Batch Evaluation Available",
    "description": "Evaluate multiple test sets simultaneously with batch processing.",
    "link": "https://agenta.ai/docs/changelog/batch-evaluation"
}

示例 2：集成公告

{
    "id": "changelog-2026-01-20-langchain-support",
    "title": "LangChain v0.3 Support",
    "description": "Full support for LangChain v0.3 with auto-instrumentation.",
    "link": "https://agenta.ai/docs/changelog/langchain-v03"
}

示例 3：改进公告

{
    "id": "changelog-2026-01-25-faster-traces",
    "title": "10x Faster Trace Loading",
    "description": "Observability page now loads traces up to 10x faster.",
    "link": "https://agenta.ai/docs/changelog/faster-trace-loading"
}

相关文件

核心系统文件

• web/oss/src/components/SidebarBanners/index.tsx - 主容器
• web/oss/src/components/SidebarBanners/SidebarBanner.tsx - 显示组件
• web/oss/src/components/SidebarBanners/types.ts - 类型定义
• web/oss/src/components/SidebarBanners/state/atoms.ts - 状态管理
• web/oss/src/components/SidebarBanners/data/changelog.json - 更新日志数据

集成位置

• web/oss/src/components/Sidebar/Sidebar.tsx - 横幅的渲染位置

EE 覆盖（企业版）

• web/ee/src/components/SidebarBanners/index.tsx - EE 包装器
• web/ee/src/components/SidebarBanners/state/atoms.ts - EE 横幅（试用、升级）

最佳实践

1. 时机：功能已全面部署并完成文档编写后，再添加公告
2. 以用户为中心：从用户视角撰写（“您现在可以……”），而不是从技术视角撰写
3. 简洁：标题和描述要简短，用户通常会快速浏览横幅
4. 链接：始终链接到完整的文档，而不只是博客文章
5. 测试：清除 localStorage，并确认横幅显示正常
6. 唯一性：使用基于日期的 ID，避免与过去或未来的公告冲突

故障排除

横幅没有显示？

• 检查 JSON 语法（使用 JSON 验证器）
• 清除 localStorage：localStorage.removeItem('agenta:dismissed-banners')
• 确认您查看的是正确的环境（OSS 或 EE）
• 检查浏览器控制台中是否有错误

横幅重复显示？

• 确保 ID 唯一（未出现在已关闭列表中）
• 检查 changelog.json 中是否有重复条目

横幅样式异常？

• SidebarBanner 组件会自动处理所有样式
• 不要在描述中添加自定义 HTML 或样式——描述会以纯文本形式呈现

添加公告后的后续步骤

将公告添加到 changelog.json 后，您应该：

1. 创建更新日志文档页面，路径为 docs/docs/changelog/[feature-slug].mdx
2. 在文档中添加截图或演示视频
3. 在更新日志页面中链接相关功能文档
4. 在 OSS 和 EE 环境中测试横幅
5. 提交更改，并附上描述明确的提交消息

示例工作流

# 1. Edit changelog.json
code web/oss/src/components/SidebarBanners/data/changelog.json

# 2. Create documentation page
code docs/docs/changelog/your-feature.mdx

# 3. Test locally (if running dev server)
# Clear localStorage in browser console:
# localStorage.removeItem('agenta:dismissed-banners')

# 4. Commit
git add web/oss/src/components/SidebarBanners/data/changelog.json
git add docs/docs/changelog/your-feature.mdx
git commit -m "docs: add changelog announcement for [feature name]"

---

注意：此技能侧重于简单的更新日志公告。对于具有复杂逻辑的自定义横幅，请查阅 SidebarBanners README，或寻求创建自定义横幅组件的指导。