create-changelog-announcement

创建更新日志公告

本技能将指导你创建完整的更新日志公告，其中包括：

1. /docs/blog/entries/ 中的更新日志条目页面（/changelog 更新日志索引会自动从这些条目生成，并支持分页）
2. /web/oss/src/components/SidebarBanners/data/changelog.json 中的侧边栏公告卡片
3. /docs/src/data/roadmap.ts 中的路线图更新
4. 关闭 GitHub 讨论（如适用）
5. 社交媒体公告（LinkedIn、Twitter、Slack）

你的核心职责

1. 完整的更新日志创建工作流

对于每条更新日志公告，你都要创建两个相互配套的内容：

A. 更新日志条目（docs/blog/entries/[feature-slug].mdx）：

• 全面说明功能或变更

• 代码示例、截图或嵌入式视频

• 相关文档链接

• 面向用户的优势和使用场景

• 两段不同的文本：供 /changelog 索引使用的简短摘要，以及条目页面使用的完整说明。简短版本是精心撰写的 1–2 段摘要（可以与完整说明的开头不同；不要直接复制完整说明的前几行）。文件结构如下：

  ---frontmatter---
  
  import Image from "@theme/IdealImage"; {/* only if you use <Image> */}
  
  <Summary>
  
  {/* Optional hero video or screenshot, shown on the index */}
  
  Curated 1-2 paragraph summary shown on the /changelog index.
  
  </Summary>
  
  {/* truncate */}
  
  {/* Repeat the hero video/screenshot here so it also shows on the page */}
  
  Full write-up (## sections, videos, code) shown on the entry's page.
  

  <Summary> 只会在索引列表中呈现（作为预览，并带有“阅读更多”链接）；在条目页面中不会呈现任何内容，因此页面只会显示完整说明，不会重复内容。如果此功能有演示视频或截图，请将其放在 <Summary> 内，这样它会显示在索引中；同时也要将其放在下方标记之后的完整说明中，这样它也会显示在条目页面中。嵌入式视频和图片在 CSS 中的宽度上限为居中的 680px，因此请原样使用现有的 <iframe>/<Image> 标记。

B. 侧边栏公告（web/oss/src/components/SidebarBanners/data/changelog.json）：

• 一句话说明
• 指向详细文档的链接
• 带日期的唯一 ID

2. 信息收集

创建任何条目之前，请收集：

• 功能名称和描述
• 版本号（如果不明确，请询问：“这条更新日志对应哪个版本？”）
• 发布日期（如果未指定，则默认为今天）
• 用户是否有截图/视频（如果提到但未提供，请询问）
• 相关文档链接

如果没有明确的版本标识和功能描述，绝不要继续。

3. 写作风格指南

严格遵循以下写作指南：

• 清晰至上：非技术术语使用相当于 11 年级英语水平的表达
• 主动语态：“你现在可以跟踪对话”，而不是“现在可以跟踪对话”
• 短句：默认使用简洁有力的句子；只有为保证行文流畅时才使用较长句子
• 完整句子：避免使用残句，除非简短表达能明显提升可读性
• 不使用破折号（—）：改用句号、括号 () 或分号 ;
• 尽量少用格式：只在有助于快速浏览时使用粗体和项目符号
• 面向用户：写“你现在可以……”，而不是“我们新增了……”
• 强调优势而非功能：说明用户可以做什么，而不是说明你构建了什么

示例：

❌ 不佳：“我们实现了新的会话跟踪系统，让用户可以将相关跟踪记录分组，从而更轻松地分析对话。”

✅ 较好：“你现在可以将相关跟踪记录分组到会话中。这有助于你分析完整对话，并跟踪多个轮次中的指标。”

4. ID 和命名约定

更新日志条目文件命名：

• 使用描述性名称，并采用 kebab-case
• 示例：chat-sessions-observability.mdx、pdf-support-in-playground.mdx
• 长度不超过 60 个字符

侧边栏公告 ID：

• 格式：changelog-YYYY-MM-DD-feature-slug
• 示例：changelog-2026-01-09-chat-sessions
• 必须唯一，以防冲突

版本格式：

• 使用语义化版本号：v0.73.0
• 将其作为条目的标签包含在内（tags: [v0.73.0]）；更新日志索引会将其显示为日期旁的版本标记

5. 媒体处理

用户提及视频或截图时：

对于 YouTube 视频（在详细条目中）：

<div style={{display: 'flex', justifyContent: 'center', marginTop: "20px", marginBottom: "20px", flexDirection: 'column', alignItems: 'center'}}>
  <iframe
    width="100%"
    height="500"
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Feature Demo"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
  ></iframe>
</div>

对于图片（在详细条目中）：

<Image
  img={require('/static/images/changelog/feature-name.png')}
  alt="Feature description"
  style={{display: 'block', margin: '20px auto', textAlign: 'center'}}
/>

信息不明确时，请询问具体情况：

• “你有演示视频的 YouTube URL 吗？”
• “需要添加多少个截图占位符？”
• “应该把图片放在叙述的什么位置？”

6. 集成功能文档

始终搜索相关文档：

1. 检查 /docs/docs/ 中是否有专门的功能页面
2. 如果有，在摘要和详细条目中都链接到该页面
3. 如果没有，请注明这一点并询问：“我们应该为此功能创建文档吗？”

文档链接格式：

• 使用相对路径：/observability/trace-with-python-sdk/track-chat-sessions
• 除非是外部链接，否则不要使用绝对 URL

7. 质量保证检查清单

最终定稿前，请确认：

• 版本号已填写且正确
• 已创建条目和侧边栏公告
• 精选摘要已用 <Summary> 包裹，后接 {/* truncate */}，再接完整内容
• 尽可能使用主动语态
• 没有使用 em dash
• 适用时已链接功能文档
• 提及媒体时已添加媒体占位符
• 遵循写作风格指南
• ID 和文件名符合规范
• 已包含所有必需的 frontmatter

8. 文件位置参考

变更日志条目：

• 路径：/docs/blog/entries/[feature-slug].mdx
• 示例：/docs/blog/entries/chat-sessions-observability.mdx
• /changelog 变更日志索引页会自动根据这些文件构建（按 date 排序并分页）。无需维护单独的摘要文件。

侧边栏公告：

• 路径：/web/oss/src/components/SidebarBanners/data/changelog.json
• JSON 数组，在最顶部添加新条目

分步工作流

步骤 1：收集信息

向用户询问缺失的信息：

- What version is this for?
- Do you have a demo video or screenshots?
- What's the primary benefit users will get from this?
- Are there existing docs for this feature I should link to?

步骤 2：搜索相关文档

# Search for related docs
grep -r "session" docs/docs/observability --include="*.mdx" --include="*.md"

步骤 3：创建详细条目

创建 /docs/blog/entries/[feature-slug].mdx：

重要：使用正确的 frontmatter 格式（不包含 authors 字段）：

---
title: "Feature Name"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "One-sentence description of the feature."
---

{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}

<Summary>

[Curated 1-2 paragraph summary. This is the SHORT version shown on the
/changelog index. It can differ from the long write-up's opening.]

</Summary>

{/* truncate */}

## Key Capabilities

- **Capability 1**: Description
- **Capability 2**: Description
- **Capability 3**: Description

## How It Works

[Step-by-step explanation or code examples]

```python
# Code example if applicable
import agenta as ag
ag.tracing.store_session(session_id="conversation_123")

使用场景

[此功能可发挥作用的实际场景]

快速入门

[文档、教程或指南的链接]

• 功能文档
• 教程

后续计划

[可选：即将推出的内容或相关功能]

### Step 4: Write the Summary and Place the Truncate Marker

The `/changelog` index shows the `<Summary>` block (with a "Read more" link);
the entry page shows everything below `{/* truncate */}`. So:

- Put the curated short summary inside `<Summary>...</Summary>`, then the
  `{/* truncate */}` marker, then the full write-up.
- Leave blank lines inside the `<Summary>` tags so the content parses as
  Markdown (links and bold work).
- If there is a demo video or screenshot, include it inside `<Summary>` (so it
  shows on the index) and again in the write-up below the marker (so it shows
  on the entry page).
- Every entry needs content below the marker (the full write-up); that is what
  the entry page renders.

### Step 5: Add Sidebar Announcement
Add to `/web/oss/src/components/SidebarBanners/data/changelog.json`:

```json
[
    {
        "id": "changelog-2026-01-09-feature-name",
        "title": "Feature Name (Keep Under 40 Chars)",
        "description": "One-sentence benefit users get from this feature.",
        "link": "https://agenta.ai/docs/changelog/feature-slug"
    },
    // ... existing entries
]

步骤 6：更新路线图

更新 /docs/src/data/roadmap.ts：

如果路线图中已有该功能：

1. 在 inProgressFeatures 数组中找到该功能
2. 将其移到 shippedFeatures 数组的最顶部
3. 将格式从 PlannedFeature 转换为 ShippedFeature：
   • 移除 githubUrl 字段
   • 添加指向详细条目的 changelogPath 字段
   • 添加包含 ISO 日期（YYYY-MM-DD）的 shippedAt 字段

示例：

// Move from inProgressFeatures to top of shippedFeatures:
{
  id: "chat-session-view",
  title: "Chat Sessions in Observability",
  description: "Track multi-turn conversations with session grouping...",
  changelogPath: "/docs/changelog/chat-sessions-observability",
  shippedAt: "2026-01-09",
  labels: [{name: "Observability", color: "DE74FF"}],
}

步骤 7：检查 GitHub 讨论

如果路线图条目包含指向 GitHub 讨论的 githubUrl：

1. 记录路线图条目中的讨论 URL
2. 检查是否应该关闭该讨论（如不确定，请询问用户）
3. 如果使用 gh CLI：gh issue close <number> --repo Agenta-AI/agenta --comment "Shipped in v0.73.0"
4. 如果无法使用 CLI，请记录讨论 URL，以便手动关闭

步骤 8：创建社交媒体公告

请遵循以下指南：.claude/skills/write-social-announcement/SKILL.md

该技能包含全面的指南，帮助撰写真诚自然的公告，避免常见的 AI 写作模式。要点如下：

• 开场方式应有所变化（不要总是以“We just shipped”开头）
• 避免使用 AI 常用词汇：“crucial”“pivotal”“showcases”“underscores”“landscape”“tapestry”
• 不要在句末进行肤浅的“-ing”式分析
• 不要使用反问句（“Working with large test sets?”）
• 不要使用陈词滥调的结尾（“Small changes, but they add up”）
• 内容要具体、直接

创建 SOCIAL_ANNOUNCEMENTS.md，并包含 LinkedIn、Twitter 和 Slack 版块

步骤 9：构建并验证

重要：完成前务必运行构建，确认没有错误。

1. 运行文档构建：

cd docs && npm run build

2. 如果构建失败，立即修复错误：

   • 常见错误：缺少 authors 字段——从 frontmatter 中移除 authors: [agenta]
   • 正确的 frontmatter 格式（参见现有条目中的示例）：

     ---
     title: "Feature Name"
     slug: feature-name-slug
     date: YYYY-MM-DD
     tags: [vX.Y.Z]
     description: "Brief description"
     ---
     

   • 无效的 MDX 语法——检查是否有未闭合的标签或不正确的 JSX
   • 链接失效——确认所有相对路径均存在

3. 验证清单：

• 构建成功完成（在 docs/ 中运行 npm run build）
• 阅读所有文件，确保内容一致
• 检查链接是否有效（相对路径是否正确）
• 验证侧边栏公告中的 JSON 语法
• 确保各文件中的版本号一致
• 确认写作风格符合指南
• 路线图已正确更新
• 已创建社交媒体公告

常见模式和示例

示例 1：新功能公告（Chat Sessions）

详细条目（docs/blog/entries/chat-sessions-observability.mdx）：

---
title: "Chat Sessions in Observability"
slug: chat-sessions-observability
date: 2026-01-09
tags: [v0.73.0]
description: "Track and analyze multi-turn conversations with session grouping, cost analytics, and conversation flow visualization."
---

{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}

## Overview

Chat sessions bring conversation-level observability to Agenta. You can now group related traces from multi-turn conversations together, making it easy to analyze complete user interactions rather than individual requests.

This feature is essential for debugging chatbots, AI assistants, and any application with multi-turn conversations. You get visibility into the entire conversation flow, including costs, latency, and intermediate steps.

## Key Capabilities

- **Automatic Grouping**: All traces with the same `ag.session.id` attribute are automatically grouped together
- **Session Analytics**: Track total cost, latency, and token usage per conversation
- **Session Browser**: Dedicated UI showing all sessions with first input, last output, and key metrics
- **Session Drawer**: Detailed view of all traces within a session with parent-child relationships
- **Real-time Monitoring**: Auto-refresh mode for monitoring active conversations

## How It Works

Add a session ID to your traces using either the Python SDK or OpenTelemetry:

**Python SDK:**
```python
import agenta as ag

ag.tracing.store_session(session_id="conversation_123")

OpenTelemetry：

span.setAttribute('ag.session.id', 'conversation_123')

UI 会自动检测会话 ID 并将相关跟踪记录分组。会话 ID 可以采用任意格式：UUID、组合 ID（user_123_session_456）或自定义格式。

使用场景

• 调试聊天机器人：用户报告问题时，查看完整的对话流程
• 监控多轮 Agent：跟踪 Agent 如何处理后续问题和上下文
• 分析对话成本：了解哪些对话成本高，以及原因
• 优化性能：识别整个对话中的延迟问题，而不只是单个请求的问题

开始使用

在文档中了解更多信息：

• 跟踪 Chat Sessions（Python SDK）
• 会话跟踪（OpenTelemetry）
• 可观测性概览

后续计划

我们将继续增强会话跟踪功能，后续会推出会话级注释、会话对比和自动会话分析等功能。

**Sidebar Announcement**:
```json
{
    "id": "changelog-2026-01-09-chat-sessions",
    "title": "Chat Sessions in Observability",
    "description": "Track multi-turn conversations with session grouping and cost analytics.",
    "link": "https://agenta.ai/docs/changelog/chat-sessions-observability"
}

示例 2：集成公告

介绍集成时，请重点说明：

• 现在可以与哪些内容集成
• 设置有多简单（如果确实如此，请提及“一行代码”）
• 该集成带来的主要优势
• 集成文档链接

示例 3：改进公告

介绍改进时，请重点说明：

• 可量化的改进（例如，“快 10 倍”“减少 50%”）
• 如果改进显著，提供改进前后的对比
• 这能如何帮助用户（节省时间、带来更好的体验）

决策框架

信息缺失时：

• 版本号不明确 → 继续之前立即询问
• 功能范围不明确 → 请求澄清并索取示例
• 媒体资源是否可用不确定 → 添加占位符前先向用户确认
• 分类不明确 → 询问这是新功能、改进还是缺陷修复

编辑现有条目时：

• 始终确保事实准确，并保留原意
• 在不改变含义的前提下提升清晰度和文风
• 发现技术错误时应告知用户，而不是猜测

输出格式

创建更新日志公告时，请提供：

1. docs/blog/entries/[slug].mdx 的条目内容（在 <Summary> 中提供精心整理的摘要，然后是 {/* truncate */}，再接完整内容）
2. 要添加到 changelog.json 的侧边栏公告 JSON
3. 确认已检查相关文档
4. 需要提出的任何问题或澄清事项

主动识别不明确的要求。提出具体问题，而不要自行假设。目标是产出可立即发布、无需修改的更新日志条目。

成功提示

1. 先阅读现有条目：创建新条目之前，先阅读 entries/ 中 2-3 个近期条目，以保持语气和结构一致
2. 简洁明了：用户通常会快速浏览更新日志。每句话都要先说明带来的好处。
3. 多添加链接：帮助用户轻松找到更多信息
4. 测试你的内容：大声读一遍条目，检查措辞是否生硬
5. 保持一致很重要：确保条目与侧边栏公告中的术语一致

---

请记住：你正在编写面向用户的文档，向数千名开发者介绍一项新功能。务必让内容清晰、引人注目且易于理解。