AgentSkillsCN

add-telegram-update-field

【库贡献者】为 Update 类新增一个字段，并通过 ProcessedUpdate、UpdateType、ProcessUpdate、KSP（TypeConstants、TypeMapper）、以及 FunctionalDSLUtils 进行链路连接。适用于实现对全新 Telegram 更新类型的兼容支持（如 message_reaction、chat_boost），或新增更新处理器，又或是扩展机器人以应对更多类型的更新时使用。

SKILL.md
--- frontmatter
name: add-telegram-update-field
description: [Library contributor] Adds a new field to the Update type and wires it through ProcessedUpdate, UpdateType, ProcessUpdate, KSP (TypeConstants, TypeMapper), and FunctionalDSLUtils. Use when implementing support for a new Telegram update type (e.g. message_reaction, chat_boost), adding a new update handler, or extending the bot to handle additional update kinds.

Add Telegram Update Field

Workflow

1. Add Field to Update

  • •In Update.kt: add val myField: MyType? = null (camelCase, nullable)
  • •Add import for the payload type if needed

2. Add UpdateType Entry

  • •In UpdateType.kt: add enum entry with @SerialName("snake_case") matching Telegram API (e.g. MY_FIELD)

3. Add ProcessedUpdate Subclass

  • •In ProcessedUpdate.kt: add data class MyFieldUpdate(...) : ProcessedUpdate(...)
  • •Use @Serializable(MyFieldUpdate.Companion::class) and internal companion object : UpdateSerializer<MyFieldUpdate>()
  • •Implement UserReference when the update has a user; ChatReference when it has a chat; TextReference when it has text

4. Add processUpdate Clause

  • •In ProcessUpdate.kt: add myField != null -> MyFieldUpdate(updateId, this, myField)
  • •Add import for the new ProcessedUpdate subclass
  • •Place clause in a logical order (group with similar update types)

5. Update KSP Module

  • •In TypeConstants.kt: add val myFieldUpdateClass: TypeName = MyFieldUpdate::class.asTypeName()
  • •In TypeMapper.kt: add TypeConstants.myFieldUpdateClass to MyFieldUpdate::class to updateTypeMap

6. Regenerate FunctionalDSLUtils

  • •Run ./gradlew prepareRelease (or full build)
  • •api-sentinel KSP regenerates FunctionalDSLUtils.kt from UpdateType.entries; no manual edits needed

Handling: The new onXxx DSL function enables bot.setFunctionality { onXxx { ... } }. Both functional DSL and annotation approach (@UpdateHandler) use the same ActivityRegistry and ProcessingPipeline; see telegram-bot-handling.mdc.

Naming Conventions

  • •Update field: camelCase (e.g. callbackQuery, messageReaction)
  • •UpdateType: SCREAMING_SNAKE_CASE, @SerialName("snake_case") matching Telegram API
  • •ProcessedUpdate subclass: XxxUpdate (e.g. CallbackQueryUpdate)

Reference Examples

Validation

bash
./gradlew formatKotlin
./gradlew prepareRelease