Telegram adapter
解析 Bot API updates、校验 secret token 与入口类型，保持平台细节与客户业务逻辑分层。
Customer project architecture
把 Telegram Bot API updates 转换成客户业务意图。
项目适配层接收 Bot API updates 并校验 Webhook secret token，客户领域层处理经过验证的用户意图、许可上下文和业务动作。
Consent context
记录用户是否主动进入、允许处理的数据和撤回状态。
Customer workflow
根据客户业务规则选择回答、动作、Mini App 或回退。
Delivery & handoff
返回目标响应，或把完整上下文转交客户人工系统。
Event contract
从许可状态开始组织客户项目事件。
事件合同把 Telegram 入口、许可范围、用户意图与回退策略放在同一上下文中，让客户领域工作流保持稳定。
安全基线：Bot Token、Webhook secret token、客户系统 API 密钥与用户标识由客户部署配置管理，字段结构和业务事件保持清晰分层。
event.contract.json
// Customer workflow event contract
{
"type": "user.intent.submitted",
"source": {
"channel": "telegram_bot",
"entry": "user_initiated"
},
"consent": {
"state": "active",
"scope": ["current_task"]
},
"intent": "check_build_status",
"fallback": "human_handoff"
}Workflow handler
先检查许可，再执行有限动作。
业务处理器按入口、授权和输入校验事件，再选择自动化结果或带上下文人工接管。
- 校验事件许可与可信来源
- 使用完成当前任务所需的数据
- 对超时、平台失败和低置信度显式回退
- 日志聚焦节点结果、状态与错误码
workflow.handler
on user_intent(event):
if event.entry != "user_initiated":
return ignore()
if not consent.allows(event.intent):
return explain_and_stop()
result = workflow.run(event.intent)
if result.needs_human:
return handoff(with_context=True)
return respond(result.safe_view)Engineering gates
四个工程门禁，贯穿构建与运行。
平台权限、数据最小化、回退机制和可观察性共同支撑稳定的自动化工作流。
平台与权限
确认账号能力、平台条款、Webhook secret token 校验和可用入口。
数据最小化
处理完成当前任务所需的数据，并设计删除路径。
失败与接管
覆盖超时、限流、规则异常与人工队列状态。
可观察性
记录节点结果、错误与责任路径。