create-changelog-announcement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Changelog Announcement

创建变更日志公告

This skill guides you through creating complete changelog announcements that include:

Detailed changelog documentation page in
```
/docs/blog/entries/
```
Summary entry in
```
/docs/blog/main.mdx
```

Sidebar announcement card in

/web/oss/src/components/SidebarBanners/data/changelog.json

Roadmap update in
```
/docs/src/data/roadmap.ts
```
GitHub discussion closure (if applicable)
Social media announcements (LinkedIn, Twitter, Slack)

此技能将引导你创建完整的变更日志公告，包括：

在
```
/docs/blog/entries/
```
路径下创建详细的变更日志文档页面
在
```
/docs/blog/main.mdx
```
中添加摘要条目

在

/web/oss/src/components/SidebarBanners/data/changelog.json

中添加侧边栏公告卡片

在
```
/docs/src/data/roadmap.ts
```
中更新路线图
关闭GitHub讨论（如适用）
发布社交媒体公告（LinkedIn、Twitter、Slack）

Your Core Responsibilities

核心职责

1. Complete Changelog Creation Workflow

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

For every changelog announcement, you create THREE coordinated entries:

A. Detailed Entry (

docs/blog/entries/[feature-slug].mdx

Comprehensive explanation of the feature or change
Code examples, screenshots, or embedded videos
Links to related documentation
User-focused benefits and use cases

B. Summary Entry (

docs/blog/main.mdx

Concise 1-2 paragraph summary
Version number and date
Link to detailed entry
Embedded media if significant feature

C. Sidebar Announcement (

web/oss/src/components/SidebarBanners/data/changelog.json

One-sentence description
Link to detailed documentation
Unique ID with date

对于每一份变更日志公告，你需要创建三个协同关联的条目：

A. 详细条目 (

docs/blog/entries/[feature-slug].mdx

对功能或变更的全面说明
代码示例、截图或嵌入视频
指向相关文档的链接
以用户为中心的收益和使用场景

B. 摘要条目 (

docs/blog/main.mdx

1-2段简洁的摘要
版本号和日期
指向详细条目的链接
若为重要功能，可添加嵌入媒体

C. 侧边栏公告 (

web/oss/src/components/SidebarBanners/data/changelog.json

一句话描述
指向详细文档的链接
带日期的唯一ID

2. Information Gathering

2. 信息收集

Before creating any entry, collect:

Feature name and description
Version number (if unclear, ask: "Which version is this changelog entry for?")
Release date (default to today if not specified)
Whether user has screenshots/videos (ask if mentioned but not provided)
Links to related documentation

Never proceed without a clear version identifier and feature description.

在创建任何条目之前，需收集以下信息：

功能名称和描述
版本号（若不明确，询问：“此变更日志条目对应的是哪个版本？”）
发布日期（若未指定，默认使用当前日期）
用户是否有截图/视频（若提及但未提供，需询问）
指向相关文档的链接

在未明确版本标识和功能描述的情况下，切勿继续操作。

3. Writing Style Guidelines

3. 写作风格指南

Apply these writing guidelines rigorously:

Clarity above all else: Use 11th grade English for non-technical terms
Active voice: "You can now track conversations" not "Conversations can now be tracked"
Short sentences: Default to punchy sentences; use longer ones only for flow
Complete sentences: Avoid fragments unless brevity clearly improves readability
No em dashes (—): Use periods, parentheses (), or semicolons ; instead
Minimal formatting: Use bold and bullets sparingly—only when they aid scanning
User-focused: Write "You can now..." not "We've added..."
Benefits over features: Explain what users can do, not what you built

Examples:

❌ Bad: "We've implemented a new session tracking system that enables users to group related traces—making it easier to analyze conversations."

✅ Good: "You can now group related traces into sessions. This helps you analyze complete conversations and track metrics across multiple turns."

严格遵循以下写作指南：

清晰至上：非技术术语使用相当于11年级英语水平的表达
主动语态：使用“你现在可以追踪对话”而非“对话现在可被追踪”
短句优先：默认使用简洁有力的句子；仅为保证流畅性时使用长句
完整句子：除非简洁性能明显提升可读性，否则避免使用不完整句
禁用破折号（—）：改用句号、括号()或分号;
最少格式化：仅在有助于快速浏览时才谨慎使用粗体和项目符号
以用户为中心：使用“你现在可以……”而非“我们新增了……”
突出收益而非功能：说明用户能做什么，而非我们构建了什么

示例：

❌ 错误示范：“我们已实现新的会话追踪系统，可让用户将相关追踪数据分组——便于分析对话。”

✅ 正确示范：“你现在可以将相关追踪数据分组为会话。这能帮助你分析完整对话，并跨多轮交互追踪指标。”

4. ID and Naming Conventions

4. ID与命名规范

Changelog Entry File Naming:

Use kebab-case with descriptive names

Examples:

chat-sessions-observability.mdx

pdf-support-in-playground.mdx

Keep under 60 characters

Sidebar Announcement IDs:

Format:
```
changelog-YYYY-MM-DD-feature-slug
```
Example:
```
changelog-2026-01-09-chat-sessions
```
Must be unique to prevent conflicts

Version Format:

Use semantic versioning:
```
v0.73.0
```
Include in summary entry

变更日志条目文件命名：

使用短横线分隔的小写格式（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
```
需包含在摘要条目中

5. Media Handling

5. 媒体处理

When user mentions videos or screenshots:

For YouTube videos (in detailed entry):

mdx

<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>

For images (in detailed entry):

mdx

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

Ask for specifics if unclear:

"Do you have the YouTube URL for the demo video?"
"How many screenshots should I add placeholders for?"
"Where should I place the images in the narrative?"

当用户提及视频或截图时：

YouTube视频（用于详细条目）：

mdx

<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>

图片（用于详细条目）：

mdx

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

若信息不明确，询问具体细节：

“你有演示视频的YouTube链接吗？”
“我需要为多少张截图添加占位符？”
“我应该在叙述的哪个位置插入图片？”

6. Feature Documentation Integration

6. 功能文档集成

Always search for related documentation:

Check if a dedicated feature page exists in
```
/docs/docs/
```
If found, link to it in both the summary and detailed entries
If not found, note this and ask: "Should we create documentation for this feature?"

Documentation links format:

Use relative paths:

/observability/trace-with-python-sdk/track-chat-sessions

Not absolute URLs unless external

务必搜索相关文档：

检查
```
/docs/docs/
```
路径下是否存在专门的功能页面
若存在，在摘要和详细条目中均添加指向该页面的链接
若不存在，记录此情况并询问：“我们是否需要为该功能创建文档？”

文档链接格式：

使用相对路径：

/observability/trace-with-python-sdk/track-chat-sessions

除非是外部链接，否则不使用绝对URL

7. Quality Assurance Checklist

7. 质量保证检查清单

8. File Locations Reference

8. 文件位置参考

Detailed changelog entries:

Path:
```
/docs/blog/entries/[feature-slug].mdx
```

Example:

/docs/blog/entries/chat-sessions-observability.mdx

Summary changelog:

Path:
```
/docs/blog/main.mdx
```
Add new entry at the TOP of the file (after imports, before other entries)

Sidebar announcements:

Path:

/web/oss/src/components/SidebarBanners/data/changelog.json

JSON array, add new entry at the TOP

详细变更日志条目：

路径：
```
/docs/blog/entries/[feature-slug].mdx
```

示例：

/docs/blog/entries/chat-sessions-observability.mdx

摘要变更日志：

路径：
```
/docs/blog/main.mdx
```
在文件顶部（导入语句之后，其他条目之前）添加新条目

侧边栏公告：

路径：

/web/oss/src/components/SidebarBanners/data/changelog.json

JSON数组，在顶部添加新条目

Step-by-Step Workflow

分步工作流

Step 1: Gather Information

步骤1：收集信息

Ask the user for any missing information:

- 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?

向用户询问任何缺失的信息：

- 对应的是哪个版本？
- 你有演示视频或截图吗？
- 用户将从该功能中获得的主要收益是什么？
- 是否存在我应该链接的该功能现有文档？

Step 2: Search for Related Documentation

步骤2：搜索相关文档

bash

undefined

bash

undefined

Search for related docs

搜索相关文档

grep -r "session" docs/docs/observability --include=".mdx" --include=".md"

undefined

grep -r "session" docs/docs/observability --include=".mdx" --include=".md"

undefined

Step 3: Create Detailed Entry

步骤3：创建详细条目

Create

/docs/blog/entries/[feature-slug].mdx

IMPORTANT: Use correct frontmatter format (no authors field):

mdx

---
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. */}

创建

/docs/blog/entries/[feature-slug].mdx

：

重要提示：使用正确的前置元数据格式（无需authors字段）：

mdx

---
title: "功能名称"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "功能的一句话描述。"
---

{/* 注意：此处请勿添加H1标题。前置元数据中的title会由Docusaurus自动渲染为H1标题。 */}

Overview

概述

[2-3 paragraphs explaining what this feature is and why it matters]

[2-3段文字，说明该功能是什么以及它的重要性]

Key Capabilities

核心功能

Capability 1: Description
Capability 2: Description
Capability 3: Description

功能1：描述
功能2：描述
功能3：描述

How It Works

工作原理

[Step-by-step explanation or code examples]

python

undefined

[分步说明或代码示例]

python

undefined

Code example if applicable

适用时添加代码示例

import agenta as ag ag.tracing.store_session(session_id="conversation_123")

undefined

import agenta as ag ag.tracing.store_session(session_id="conversation_123")

undefined

Use Cases

使用场景

[Real-world scenarios where this feature helps]

[该功能可发挥作用的真实场景]

Getting Started

快速开始

[Links to documentation, tutorials, or guides]

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

What's Next

后续规划

[Optional: What's coming next or related features]

undefined

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

undefined

Step 4: Add Summary to main.mdx

步骤4：向main.mdx添加摘要

Add to

/docs/blog/main.mdx

at the TOP (after imports):

mdx

undefined

在

/docs/blog/main.mdx

的顶部（导入语句之后）添加以下内容：

mdx

undefined

功能名称

DD Month YYYY

vX.Y.Z

[1-2 paragraph summary explaining what the feature does and why users should care. Focus on benefits and capabilities.]

[Optional: Add embedded video or image if this is a major feature]

undefined

DD Month YYYY

vX.Y.Z

[1-2段摘要，说明功能作用及用户为何应关注。重点突出收益和核心功能。]

[可选：若为重大功能，添加嵌入视频或图片]

undefined

Step 5: Add Sidebar Announcement

步骤5：添加侧边栏公告

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
]

向

/web/oss/src/components/SidebarBanners/data/changelog.json

中添加以下内容：

json

[
    {
        "id": "changelog-2026-01-09-feature-name",
        "title": "功能名称（控制在40字符以内）",
        "description": "用户可从该功能获得的一句话收益。",
        "link": "https://agenta.ai/docs/changelog/feature-slug"
    },
    // ... 现有条目
]

Step 6: Update Roadmap

步骤6：更新路线图

Update

/docs/src/data/roadmap.ts

If feature was in roadmap:

Find the feature in
```
inProgressFeatures
```
array
Move it to
```
shippedFeatures
```
array at the top
Convert from
```
PlannedFeature
```
format to
```
ShippedFeature
```
format:
- Remove
```
githubUrl
```
  field
- Add
```
changelogPath
```
  field pointing to your detailed entry
- Add
```
shippedAt
```
  field with ISO date (YYYY-MM-DD)

Example:

typescript

// 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"}],
}

更新

/docs/src/data/roadmap.ts

：

若功能已在路线图中：

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

示例：

typescript

// 从inProgressFeatures移至shippedFeatures顶部：
{
  id: "chat-session-view",
  title: "可观测性中的会话功能",
  description: "通过会话分组追踪多轮对话...",
  changelogPath: "/docs/changelog/chat-sessions-observability",
  shippedAt: "2026-01-09",
  labels: [{name: "Observability", color: "DE74FF"}],
}

Step 7: Check GitHub Discussion

步骤7：处理GitHub讨论

If the roadmap item had a

githubUrl

pointing to a GitHub discussion:

Note the discussion URL from the roadmap entry
Check if the discussion should be closed (ask user if unsure)

If using

gh

CLI:

gh issue close <number> --repo Agenta-AI/agenta --comment "Shipped in v0.73.0"

If CLI not available, note the discussion URL for manual closure

若路线图条目中的

githubUrl

指向GitHub讨论：

从路线图条目中获取讨论URL
确认是否应关闭该讨论（若不确定，询问用户）

若使用

gh

CLI：

gh issue close <number> --repo Agenta-AI/agenta --comment "已在v0.73.0版本发布"

若无法使用CLI，记录讨论URL以便手动关闭

Step 8: Create Social Media Announcements

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

Follow the guidelines in:

.claude/skills/write-social-announcement/SKILL.md

That skill contains comprehensive guidelines for writing authentic announcements that avoid common AI writing patterns. Key points:

Vary your openings (don't always start with "We just shipped")
Avoid AI vocabulary: "crucial", "pivotal", "showcases", "underscores", "landscape", "tapestry"
No superficial "-ing" analyses at end of sentences
No rhetorical questions ("Working with large test sets?")
No cliché closings ("Small changes, but they add up")
Be specific and direct

Create

SOCIAL_ANNOUNCEMENTS.md

with sections for LinkedIn, Twitter, and Slack

遵循以下路径中的指南：

.claude/skills/write-social-announcement/SKILL.md

该技能包含编写真实公告的全面指南，可避免常见的AI写作模式。核心要点：

多样化开头（不要总是以“我们刚刚发布了”开头）
避免AI常用词汇：“关键的”、“核心的”、“展示了”、“强调了”、“格局”、“图景”
句子末尾不要添加无意义的“-ing”式分析
不要使用反问句（“处理大型测试集时遇到困难？”）
不要使用陈词滥调的结尾（“虽为小改进，但积少成多”）
具体直接

创建

SOCIAL_ANNOUNCEMENTS.md

，包含LinkedIn、Twitter和Slack的公告内容

Step 9: Build and Verify

步骤9：构建与验证

CRITICAL: Always run the build to verify no errors before finishing.

Run the documentation build:

bash

cd docs && npm run build

If build fails, fix errors immediately:
- Common error: Missing authors field - Remove
```
authors: [agenta]
```
  from frontmatter
- Correct frontmatter format (example from existing entries):
  yaml
```
---
title: "Feature Name"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "Brief description"
---
```
- Invalid MDX syntax - Check for unclosed tags, incorrect JSX
- Broken links - Verify all relative paths exist
Verify checklist:

Build completed successfully (
```
npm run build
```
in docs/)
Read all files to ensure consistency
Check that links work (relative paths correct)
Verify JSON syntax in sidebar announcement
Ensure version numbers match across files
Confirm writing style follows guidelines
Roadmap updated correctly
Social announcements created

关键提示：完成前务必运行构建以验证无错误。

运行文档构建：

bash

cd docs && npm run build

若构建失败，立即修复错误：
- 常见错误：缺失authors字段 - 从前置元数据中移除
```
authors: [agenta]
```
- 正确的前置元数据格式（参考现有条目示例）：
  yaml
```
---
title: "功能名称"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "简要描述"
---
```
- 无效MDX语法 - 检查未闭合的标签、错误的JSX
- 链接失效 - 验证所有相对路径是否存在
验证检查清单：

构建成功完成（在docs/目录下运行
```
npm run build
```
）
通读所有文件以确保一致性
检查链接是否可用（相对路径正确）
验证侧边栏公告的JSON语法
确保所有文件中的版本号一致
确认遵循了写作风格
路线图已正确更新
已创建社交媒体公告

Common Patterns and Examples

常见模式与示例

Example 1: New Feature Announcement (Chat Sessions)

示例1：新功能公告（会话功能）

Detailed Entry (

docs/blog/entries/chat-sessions-observability.mdx

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. */}

详细条目 (

docs/blog/entries/chat-sessions-observability.mdx

mdx

---
title: "可观测性中的会话功能"
slug: chat-sessions-observability
date: 2026-01-09
tags: [v0.73.0]
description: "通过会话分组、成本分析和对话流可视化，追踪并分析多轮对话。"
---

{/* 注意：此处请勿添加H1标题。前置元数据中的title会由Docusaurus自动渲染为H1标题。 */}

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.

会话功能为Agenta带来了对话级别的可观测性。你现在可以将多轮对话中的相关追踪数据分组，便于分析完整的用户交互，而非单个请求。

该功能对于调试聊天机器人、AI助手及任何包含多轮对话的应用至关重要。你可查看整个对话流的可见性，包括成本、延迟和中间步骤。

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

自动分组：所有带有相同
```
ag.session.id
```
属性的追踪数据会自动分组
会话分析：追踪每个对话的总成本、延迟和令牌使用量
会话浏览器：专用UI展示所有会话，包含首次输入、最后输出和关键指标
会话抽屉：详细查看会话内的所有追踪数据及其父子关系
实时监控：自动刷新模式，用于监控活跃对话

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:

javascript

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

The UI automatically detects session IDs and groups traces together. You can use any format for session IDs: UUIDs, composite IDs (

user_123_session_456

), or custom formats.

通过Python SDK或OpenTelemetry为追踪数据添加会话ID：

Python SDK：

python

import agenta as ag

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

OpenTelemetry：

javascript

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

UI会自动检测会话ID并分组追踪数据。你可使用任意格式的会话ID：UUID、复合ID（

user_123_session_456

）或自定义格式。

Use Cases

使用场景

Debug Chatbots: See the complete conversation flow when users report issues
Monitor Multi-turn Agents: Track how your agent handles follow-up questions and context
Analyze Conversation Costs: Understand which conversations are expensive and why
Optimize Performance: Identify latency issues across entire conversations, not just single requests

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

Getting Started

快速开始

Learn more in our documentation:

在我们的文档中了解更多：

What's Next

后续规划

We're continuing to enhance session tracking with upcoming features like session-level annotations, session comparisons, and automated session analysis.


**Summary Entry** (add to `docs/blog/main.mdx`):
```mdx

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


**摘要条目**（添加至`docs/blog/main.mdx`）：
```mdx

Chat Sessions in Observability

可观测性中的会话功能

9 January 2026

v0.73.0

You can now track multi-turn conversations with chat sessions. All traces with the same session ID are automatically grouped together, letting you analyze complete conversations instead of individual requests.

The new session browser shows key metrics like total cost, latency, and token usage per conversation. Open any session to see all traces with their parent-child relationships. This makes debugging chatbots and AI assistants much easier. Add session tracking with one line of code using either our Python SDK or 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"
}

2026年1月9日

v0.73.0

你现在可以通过会话功能追踪多轮对话。所有带有相同会话ID的追踪数据会自动分组，让你能够分析完整对话而非单个请求。

新的会话浏览器展示每个对话的关键指标，如总成本、延迟和令牌使用量。打开任意会话即可查看所有追踪数据及其父子关系。这会让调试聊天机器人和AI助手变得更加容易。只需一行代码，即可通过我们的Python SDK或OpenTelemetry添加会话追踪。


**侧边栏公告**：
```json
{
    "id": "changelog-2026-01-09-chat-sessions",
    "title": "可观测性中的会话功能",
    "description": "通过会话分组和成本分析追踪多轮对话。",
    "link": "https://agenta.ai/docs/changelog/chat-sessions-observability"
}

Example 2: Integration Announcement

示例2：集成公告

For integrations, focus on:

What you can now integrate with
How easy it is to set up (mention "one line of code" if true)
Key benefits specific to that integration
Link to integration docs

对于集成类公告，重点关注：

现在可与哪些服务集成
设置的便捷性（若确实如此，提及“一行代码即可完成”）
该集成特有的核心收益
指向集成文档的链接

Example 3: Improvement Announcement

示例3：改进公告

For improvements, emphasize:

Quantifiable improvements (e.g., "10x faster", "50% reduction")
Before/after comparison if dramatic
How this helps users (time saved, better experience)

对于改进类公告，重点强调：

可量化的改进（如“速度提升10倍”、“减少50%”）
若改进显著，可进行前后对比
这对用户的帮助（节省时间、体验提升）

Decision-Making Framework

决策框架

When Information is Missing:

Version number unclear → Ask immediately before proceeding
Feature scope ambiguous → Request clarification and examples
Media availability uncertain → Confirm with user before adding placeholders
Categorization unclear → Ask whether it's a new feature, improvement, or bug fix

When Editing Existing Entries:

Always preserve factual accuracy and original intent
Improve clarity and style without changing meaning
Flag technical inaccuracies to the user rather than guessing

当信息缺失时：

版本号不明确 → 立即询问，再继续操作
功能范围模糊 → 请求澄清和示例
媒体可用性不确定 → 添加占位符前与用户确认
分类不明确 → 询问这是新功能、改进还是Bug修复

当编辑现有条目时：

始终保留事实准确性和原始意图
在不改变含义的前提下提升清晰度和风格
若发现技术不准确之处，标记给用户而非自行猜测

Output Format

输出格式

When creating a changelog announcement, provide:

Detailed entry content for
```
docs/blog/entries/[slug].mdx
```
Summary entry content to add to
```
docs/blog/main.mdx
```
Sidebar announcement JSON to add to
```
changelog.json
```
Confirmation that you checked for related documentation
Any questions or clarifications needed

Be proactive in identifying unclear requirements. Ask specific questions rather than making assumptions. Your goal is to produce changelog entries that are immediately publishable without requiring revision.

创建变更日志公告时，需提供：

```
docs/blog/entries/[slug].mdx
```
的详细条目内容
需添加至
```
docs/blog/main.mdx
```
的摘要条目内容
需添加至
```
changelog.json
```
的侧边栏公告JSON
确认信息：已检查相关文档
任何问题或需要澄清的内容

主动识别不明确的需求。提出具体问题而非做出假设。你的目标是生成可立即发布、无需修订的变更日志条目。

Tips for Success

成功技巧

Read existing entries first: Before creating new entries, read 2-3 recent entries in
```
main.mdx
```
and
```
entries/
```
to match the tone and structure
Be concise: Users skim changelogs. Front-load the benefit in every sentence.
Link generously: Help users find more information easily
Test your work: Read the entries out loud to catch awkward phrasing
Consistency matters: Ensure terminology matches across all three entries

Remember: You're creating user-facing documentation that represents a new feature to thousands of developers. Make it clear, compelling, and easy to understand.

先阅读现有条目：在创建新条目之前，阅读
```
main.mdx
```
和
```
entries/
```
中的2-3条近期条目，以匹配语气和结构
保持简洁：用户会快速浏览变更日志。每句话都要突出核心收益。
多添加链接：帮助用户轻松找到更多信息
测试你的工作：大声朗读条目，以发现拗口的表述
保持一致性：确保所有三个条目中的术语一致

请记住：你正在创建面向用户的文档，将向数千名开发者展示新功能。要做到清晰、有吸引力且易于理解。