cardmsg

package
v1.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package cardmsg owns the server-side authoritative handling of InteractiveCard (ContentType=17) message payloads.

card-message-protocol P1(spec: .octospec/tasks/card-message-protocol/brief.md, 交互契约见 sibling .octospec/tasks/card-message-interaction/brief.md): 卡片消息信封 {type:17, card:<标准 Adaptive Cards 1.5 JSON, octo/v1 白名单子集>, plain:<server 权威纯文本>, card_version:"1.5", profile:"octo/v1"}。

本包与 pkg/richtext 同构(Validate 入站 gate + Finalize enrich 后收尾),是 octo/v1 白名单的唯一强制权威(docs/card-protocol.md 只是它的镜像):

  1. Validate —— 入站 write-strict 校验:profile/card_version 协商(Decision 10)、 512KiB 上限作用在「完整」payload 字节(Decision 3a)、元素/动作白名单 (TextBlock/Image/Container/ColumnSet/Column/FactSet + Action.OpenUrl + selectAction 仅限 OpenUrl)、递归节点数/嵌套深度上限(Decision 3c)、 http(s) 正向 URL allowlist 含 TextBlock markdown 链接(Decision 3d/6)。
  2. Finalize —— 所有 server 端 enrich 之后调用:按 Decision 8 派生规则重算权威 plain 覆盖端上不可信 plain(永不为空),并对真实出站完整 payload 复检 512KiB 上限。

P1 纪律(Decision 2/2b/7):普通用户 ingress、bot OBO 路径、以及所有编辑路径 (user /v1/message/edit、robot、bot_api /v1/bot/message/edit)一律拒绝 type=17 —— P1 卡片不可变;P2 才对 bot 编辑路径开放(cardmsg 对称校验 + card_seq CAS)。

Index

Constants

View Source
const (
	// ProfileV1 是 P1 唯一接受的 profile 值(Decision 10;P2 增加 octo/v2)。
	ProfileV1 = "octo/v1"
	// CardVersion 是 P1 唯一接受的 card_version / 卡内 version 值。
	CardVersion = "1.5"

	// MaxPayloadBytes 完整 payload 序列化后的硬上限(512KiB,Decision 3a)——
	// 严格低于 modules/message 同步路径的 1MiB hardParsePayloadLimit 占位线。
	MaxPayloadBytes = 512 << 10
	// MaxSendBodyBytes 是 bot/robot send+edit 路由的 pre-decode HTTP body 上限
	// (Decision 3b)。BindJSON 在校验前完整解码,必须先钉住请求体大小。
	//
	// **不变量:必须 > 同路由上最大的合法 payload。** 这些路由同时承载 RichText
	// (octo-lib RichTextMaxPayloadBytes = 1MiB payload 上限)——若 body 上限取
	// 1MiB 会把一条恰好 1MiB 的合法 RichText(叠加信封/JSON 转义后 body > 1MiB)
	// 在 pre-decode 就 413 掉,即回归既有非卡片流量。取 2MiB 给 1MiB RichText +
	// 512KiB 卡片都留足信封余量,同时仍把无界滥用挡在解码前。voice 路由沿用
	// 自己的 5MiB。
	MaxSendBodyBytes = 2 << 20
	// MaxNodes 卡片树的递归节点数上限(Decision 3c)。
	MaxNodes = 200
	// MaxDepth 卡片树的嵌套深度上限(Decision 3c)。
	MaxDepth = 16

	// MaxCopyTextBytes Action.CopyToClipboard.text 的字节上限(octo/v1 自定义本地动作;
	// 复制到剪贴板的明文,4KiB 与单条 Input.Text 同量级)。text 逐字复制、不渲染,无
	// URL/markdown 面,故只做「必填 + 大小」结构校验。
	MaxCopyTextBytes = 4 << 10

	// PlaceholderCard 空卡兜底 / 内容型展示占位(Decision 8:plain 永不为空)。
	PlaceholderCard = "[卡片]"
	// PlaceholderImage Image 元素在 plain 里的占位,与 RichText 的 [图片] 一致。
	PlaceholderImage = "[图片]"

	// EnvEnabled 部署级开关(Decision 2 rollout gate,默认关闭)。
	// 前缀用 OCTO_(维护者决策:DM_ 为历史遗留,新开关不再使用)。
	EnvEnabled = "OCTO_CARD_MESSAGE_ENABLED"

	// EnvBotEnabled bot 侧卡片生成子开关(OCTO_ 前缀,同 EnvEnabled 约定)。
	// 与部署级总开关 EnvEnabled 的关系是「AND 且从属」:默认(未设/非法值)视为开启,
	// 只有显式 false 才单独禁掉 bot 发/改卡——语义见 BotEnabled。
	EnvBotEnabled = "OCTO_BOT_CARD_ENABLED"
)
View Source
const (
	// MaxInputTextBytes 单个 Input.Text 值上限(UTF-8 字节,D11)。
	MaxInputTextBytes = 4 << 10
	// MaxInputsBytes inputs 序列化总量上限(D11)。
	MaxInputsBytes = 16 << 10
)
View Source
const (
	// ProfileV2 octo/v2:在 v1 展示集之上增加 Action.Submit(含 selectAction 携带)
	// 与 Input.Text / Input.Toggle / Input.ChoiceSet(P2 D1/D2)。Action.Execute /
	// auto-refresh 仍拒绝(P3)。
	ProfileV2 = "octo/v2"

	// EventTypeCardAction bot 事件队列里的卡片动作事件类型(P2 D5,增量事件类型,
	// event_data 形状由 brief 冻结:只许增字段)。bot SDK 必须容忍未知 event_type。
	EventTypeCardAction = "card_action"
)
View Source
const (
	// CatalogProvenanceKey / CatalogTemplateRefKey 是 type-17 信封的
	// server-only 顶层键。raw ingress 检测/拒绝时统一引用这两个常量。
	CatalogProvenanceKey  = "catalog_provenance"
	CatalogTemplateRefKey = "template_ref"

	// CatalogProvenanceVersion 是 v1 标记版本;未来演进 bump 该值并保持
	// 旧版本可解析(额外形状仍然 strict)。
	CatalogProvenanceVersion = 1

	// Wire principal 类型。只有可认证的发送主体能成为 wire principal;
	// space 是 discover-only grant principal(D2),system 是内部保留值,
	// 二者都不会出现在存储帧里。
	CatalogPrincipalWireBot              = "bot"
	CatalogPrincipalWireInternalProducer = "internal_producer"
)
View Source
const InteractiveCard common.ContentType = 17

InteractiveCard 是卡片消息的 ContentType(=17)。

命名(Decision 1):显式叫 InteractiveCard —— octo-lib 已有 Card=7(名片), 两者无关,绝不可把新逻辑接到 common.Card 上。选号依据:15 是 Forward 的历史 保留槽、9/10 为历史空洞,17 经 octo-lib / octo-server / octo-im 三仓 grep 证明 未被占用(客户端仓复核是实现 PR 的 merge precondition)。 P1 常量先落本包,octo-lib 上游化是 companion PR(Decision 5)。

View Source
const RenderProfileOctoChatV1 = "octo-chat/v1"

RenderProfileOctoChatV1 is the stable runtime compatibility key for the first Forge-owned host configuration generation. Exact package versions stay in template manifests; message envelopes carry this stable key so clients do not need to retain every artifact version.

View Source
const (

	// VCSGitBranchIcon is Lucide git-branch@0.577.0, minified and URL-encoded
	// after changing its 24px size to 16px and currentColor to the fixed neutral
	// Forge header stroke #6b7075. NOTICE carries the upstream license text.
	VCSGitBranchIcon = "" /* 480-byte string literal not displayed */
)

chevronDownIcon / chevronUpIcon 是 ai.reasoning-process@0.4.0 折叠/展开箭头的 内联字节(Lucide chevron-down / chevron-up,stroke 取 #a1a6ab,1em 方形)。 与 handoff 模板里的字面量逐字节一致。

这个一致性是**结构性**保证的,不靠某条专门的测试:模板注册时 renderCore 会拿样本 渲染并跑 cardmsg.Validate(json_artifact.go 的 selfCheckCompiledJSON),所以任何 引用了未审字节的模板在注册那一刻就编译失败。V4 侧另有 TestSimplifiedSuccessorHasNoOutboundRuntimeDependency 把五个状态的渲染帧推过 生产回写用的严格校验器,正面确认这条。

Variables

View Source
var (
	// ErrCardPayloadTooLarge 完整 payload 超过 512KiB 上限。
	ErrCardPayloadTooLarge = errors.New("cardmsg: payload 超过 512KiB 上限")
	// ErrCardMissing 信封缺 card 字段 / card 不是非空 JSON 对象。
	ErrCardMissing = errors.New("cardmsg: card 必填且必须是非空对象")
	// ErrCardProfileUnsupported profile / card_version 不在接受集合(Decision 10)。
	ErrCardProfileUnsupported = errors.New("cardmsg: profile 或 card_version 不受支持")
	// ErrCardUnknownElement 卡片 body 中出现白名单之外的元素类型。
	ErrCardUnknownElement = errors.New("cardmsg: 元素类型不在 octo/v1 白名单")
	// ErrCardUnknownAction 动作类型不在白名单(P1 仅 Action.OpenUrl;selectAction 同)。
	ErrCardUnknownAction = errors.New("cardmsg: 动作类型不在 octo/v1 白名单")
	// ErrCardBadURLScheme URL 不满足正向 allowlist(仅绝对 http/https,Decision 3d)。
	// 覆盖 Image.url、Action.OpenUrl.url、selectAction 以及 TextBlock markdown 链接
	// (Decision 6)—— data:/javascript:/vbscript:/intent:/file:/相对路径 全部拒绝。
	ErrCardBadURLScheme = errors.New("cardmsg: url 只接受绝对 http/https")
	// ErrCardTooManyNodes 递归节点数超上限(Decision 3c)。
	ErrCardTooManyNodes = errors.New("cardmsg: 卡片节点数超过上限")
	// ErrCardTooDeep 嵌套深度超上限(Decision 3c)。
	ErrCardTooDeep = errors.New("cardmsg: 卡片嵌套深度超过上限")
	// ErrCardBadShape 结构性非法(body/actions/items/columns/facts 非期望形状)。
	ErrCardBadShape = errors.New("cardmsg: 卡片结构非法")
	// ErrCardInputInvalid card/action 上行 inputs 违反 D11 信任边界(未声明键 /
	// 类型不符 / 值超限 / 序列化总量超限)。端点侧统一映射到单一 400 invalid
	// (防枚举),细节只进日志。
	ErrCardInputInvalid = errors.New("cardmsg: inputs 不符合生效帧声明")
)

校验错误(sentinel,调用方用 errors.Is 判定;细节经 %w 包装携带)。

View Source
var ErrCatalogMarkerInvalid = errors.New("cardmsg: invalid catalog marker")

ErrCatalogMarkerInvalid 标识畸形/不一致的 server-authored catalog 标记。

Functions

func AcceptedProfiles

func AcceptedProfiles() []string

AcceptedProfiles 返回本 build 接受的 profile 值(有序,与校验器 interactiveByProfile 的接受集恒一致)。D12 能力清单据此下发 profiles;调用方 MUST 用它、而非重抄字面量 (单一权威,见 acceptedProfiles)。每次调用返回新切片,调用方改不到内部状态。

func BotEnabled added in v1.12.0

func BotEnabled() bool

BotEnabled 报告 bot 侧是否允许生成卡片。bot_api 的发卡(send)/改卡(card edit)、 legacy robot ingress,以及 /v1/bot/card/profile 的 `enabled` 字段共用这一个「有效 门禁」,三者永不背离——profile 是 bot 的能力清单,若它报 enabled 而发卡却被拒,就 等于清单撒谎,破坏 feature detection。

语义是「总闸 AND 子开关」,与全局卡片能力解耦但从属于它:

  • 部署级总开关 Enabled()(OCTO_CARD_MESSAGE_ENABLED)为假时恒为假——客户端渲染 门禁没放开,任何生产者都不该发卡,bot 不例外。
  • 总开关为真时再看 bot 子开关 OCTO_BOT_CARD_ENABLED:未设或非法值默认「开启」 (向后兼容,行为同历史上「总开关开 ⇒ bot 能发」),仅显式 false 才单独把 bot 发/改卡关掉;此时内部通知 / incoming webhook / card_action 仍按总开关照常发卡。

func BuildPlain

func BuildPlain(card map[string]interface{}) string

BuildPlain 按 Decision 8 从卡片派生权威纯文本:

  • 按文档序遍历 body:TextBlock 取剥离 markdown 后的文本;FactSet 逐条产出 "title: value" 行;Image 产出 [图片] 占位;容器类(Container/ColumnSet/ Column)递归;
  • 动作(按钮)不参与 —— 按钮是操作面不是内容;
  • 段落以换行拼接;结果为空时兜底 [卡片] —— plain 永不为空,推送/搜索/摘要/ 置顶永远有可显示文本。

func CardSeq

func CardSeq(payload map[string]interface{}) (int64, bool)

CardSeq 读取信封可选的单调帧序号 card_seq(P2 D9 乱序防护)。缺失/非数值 返回 (0, false) —— 无 card_seq 时行为退化为 last-write-wins(单写者 bot 零迁移)。

刻意不接受 float64(PR#548 review P2-d):float64 尾数仅 52 位,>2^53 的雪花号 / 纳秒 epoch 会被静默坍缩,令 D9 CAS 失真。所有实时调用方经 decodeEnvelope(UseNumber) → json.Number(见 CardSeqFromContentEdit);int/int64 仅供程序化构造,三者皆 int64 精确。若未来有调用方误用裸 json.Unmarshal(→float64),这里返回 (0,false) 退化为 LWW, 而非接受一个被截断的错误序号 —— fail-safe。

func CardSeqFromContentEdit

func CardSeqFromContentEdit(contentEdit string) (int64, bool)

CardSeqFromContentEdit 从编辑体 JSON 读取 card_seq。

func CardVariant added in v1.12.0

func CardVariant(envelopeRaw []byte) (string, bool)

CardVariant extracts card.metadata.octo.variant from a type-17 envelope. The variant is the authoritative card-family discriminator authored server-side (e.g. "docs.access_requested", "docs.access_granted"), so a caller can gate a mutation on the target card's own family even when the sender bot is shared across producers. Returns ("", false) when absent, blank, malformed, or the payload is not a card.

func CatalogMarkersPreserved added in v1.14.0

func CatalogMarkersPreserved(stored, next FrameCatalogMarkers) error

CatalogMarkersPreserved reports whether a replacement frame keeps the catalog identity a stored frame carries. It is the single definition of that rule: internal/carddispatch's mutation boundary enforces it on every replacement, and tests that stand in for that boundary call this rather than restating the comparison — an earlier version was hand-copied into a test fake, and the copy reproduced a bug in the original instead of catching it.

The rule is asymmetric on purpose, which is the part that was wrong when it was written as an equality check:

  • Losing a marker is refused. That is the erasure the boundary exists to stop; both identity guards in pkg/cardtmpl's updater begin `if markers.Has…`, so a dropped marker silently disables them for that message and returns the frame to the legacy population.
  • Gaining one is allowed. `template_ref` alone is a legal pre-PR-C Registry frame, and an edit is the only moment such a frame can acquire provenance. Refusing that made every already-delivered Registry card permanently uneditable, with no repair path, because the edit that would add the marker was the operation being refused. The gain is safe because only a server rendering boundary can author a marker and only the original sender can reach a mutation.
  • Changing one is refused. Identity does not change under an edit, so where both sides carry a marker the values must match. Presence alone would let a replacement keep both keys and rewrite principal_id or space_id.

func DisplayActions

func DisplayActions() []string

DisplayActions 返回 octo/v1 本地动作白名单副本(D12 清单据此下发 actions;单一权威,调用方 MUST 用它而非重抄字面量)。每次返回新切片,调用方改不到内部状态。

func DisplayElements

func DisplayElements() []string

DisplayElements 返回 octo/v1 展示元素白名单副本(D12 清单据此下发 elements;单一权威, 调用方 MUST 用它而非重抄字面量)。每次返回新切片,调用方改不到内部状态。

func DisplayText

func DisplayText() string

DisplayText 返回卡片消息的内容型占位文案,供会话摘要/置顶/引用等「按内容类型 描述消息」的服务端文案面使用(PR#525 round-2 finding #3 的本地 helper; octo-lib GetDisplayText 的 card 分支随 companion PR 上游化)。

func DisplayTextFor

func DisplayTextFor(senderTrusted bool, payloadRaw []byte) string

DisplayTextFor 是「按 plain 描述卡片消息」的所有服务端展示面(离线推送、 搜索命中投影、会话摘要、引用预览)的**单一执法点**(Decision 2 residual-risk 规则,round-3 P1-2 统一化):

  • senderTrusted(存储行 from_uid 是 bot / webhook 身份)→ 信任 server 权威 plain(PushDisplayText);
  • 否则(直连长连接发送者,plain 攻击者可控 —— Finalize 从未跑过)→ 一律 [卡片] 占位,绝不透出存储 plain。

调用方负责解析 sender 身份(robot 表 / iwh_ 前缀),不得在各展示面私开 type-17 分支。置顶 tips 等「内容类型占位」文案面不经过本函数 —— 用 DisplayText()(恒 [卡片],无 plain 信任问题)。

func Enabled

func Enabled() bool

Enabled 报告部署级卡片开关(Decision 2 rollout gate)。默认关闭:客户端渲染 门禁发布前不得在生产开启。非法取值按关闭处理(fail-closed)。

func Finalize

func Finalize(payload map[string]interface{}) error

Finalize 是 InteractiveCard(=17) 派发出口的权威收尾:必须在所有 server 端 enrich(space_id 注入 / mention 顶层键改写等)之后调用。

  • 非 type=17 的 payload 原样返回(no-op);
  • type=17 时按 Decision 8 派生规则重算顶层 plain 覆盖端上不可信 plain (永不为空),并对真正出站的「完整」payload(含 server 注入顶层字段)复检 512KiB 上限。

就地修改传入的 payload map(写入 payload["plain"])。Decision 9 保证 enrich 只发生在信封顶层键 —— card 树本身永不被 server 改写,故 plain 派生对 enrich 顺序不敏感,这里晚于 enrich 只为让大小复检覆盖真实出站字节(与 richtext 的 PR#232 口径一致)。

func HasCardTemplateMetadata added in v1.12.0

func HasCardTemplateMetadata(envelopeRaw []byte) bool

HasCardTemplateMetadata distinguishes a truly legacy card from a card that declares protocol/template metadata but cannot produce a complete trusted TemplateContext. Callers use this to fail closed on partial/corrupt identity.

func InputElements

func InputElements() []string

InputElements 返回 octo/v2 交互输入白名单副本(D12 清单据此下发 inputs;同上纪律)。

func IsAcceptedRenderProfile added in v1.12.0

func IsAcceptedRenderProfile(value string) bool

IsAcceptedRenderProfile validates a candidate runtime visual profile. An empty value means the owning authoring boundary has not selected its default yet and is intentionally valid here; a present wire value must be non-empty.

func IsCardContentEdit

func IsCardContentEdit(contentEdit string) bool

IsCardContentEdit 判断编辑体(content_edit JSON 字符串)是否为 type=17 卡片信封。

P1 Decision 7:卡片不可变 —— 所有编辑入口在调 richtext.NormalizeContentEdit 之前先用本函数拦截。背景(PR#525 round-2 finding #1):NormalizeContentEdit 以 IsRichTextPayload 为门,type=17 的编辑体会「原样、零校验」通过,使编辑通道 成为绕过 Validate 的卡片 ingress。非 JSON / 非 17 返回 false,老编辑路径不变。

func IsCardPayload

func IsCardPayload(payload map[string]interface{}) bool

IsCardPayload 判断 payload map 的 type 字段是否为 InteractiveCard(=17)。 兼容 json.Number / float64 / int(与 pkg/richtext.IsRichTextPayload 同口径); string "17" 不识别,避免误命中。

func IsCardRawPayload

func IsCardRawPayload(raw []byte) bool

IsCardRawPayload 是 IsCardPayload 的 []byte 便捷形态(消息表 / IM 查询返回的 原始 payload 字节 —— 编辑路径的「原消息是否卡片」判定用它)。解析失败视为非卡片。

func NormalizeContentEdit

func NormalizeContentEdit(contentEdit string) (string, error)

NormalizeContentEdit 是 bot 编辑路径的卡片收敛 gate(P2 D6 解锁;user/robot 编辑路径对卡片永久关闭,不得调用本函数放行)。与 richtext.NormalizeContentEdit 对称:

  • 非 type=17 编辑体:原样返回(老路径 / richtext 路径不变);
  • type=17:跑与 send 同一套 Validate(白名单/大小/URL/profile 协商,v2 帧 在此合法),随后 Finalize 重算权威 plain,返回 canonical JSON 供落库。

跨类型变异(D6 不变量 (a))由调用方比对原消息类型后拒绝 —— 本函数只看编辑体。

func PlainFromContentEdit

func PlainFromContentEdit(contentEdit string) string

PlainFromContentEdit 从编辑体 JSON 读取服务端权威 plain(Finalize 重算后的值), 供修订历史存列表摘要。缺失返回空串。

func PushDisplayText

func PushDisplayText(payloadRaw []byte) string

PushDisplayText 为「可信路径」产出卡片文案:优先信任 payload 里 server 已 生成的权威 plain(Decision 8 保证经校验路径永不为空);缺失/为空时现场从 card 重算兜底;再不行回退 [卡片]。展示面不要直接调它 —— 走 DisplayTextFor (sender 身份门在那里)。

func RecheckPayloadSize

func RecheckPayloadSize(payload map[string]interface{}) error

RecheckPayloadSize 对「真实出站」payload 复检 512KiB 上限(Decision 3a),供 Finalize 之后**仍会改写 payload** 的 server 端场景使用 —— 典型是 mention.ais 展开(mentionrewrite.ExpandAisToBotUIDs 把频道 bot 成员 UID 追加进 mention 子表,size-increasing)。Finalize 的复检发生在那次改写之前,覆盖不到最终字节; 调用方在最后一次 mutation 之后再调本函数,把校验钉在真正出站的 payload 上 (与 richtext 的 PR#232「在最后一次 mutation 后复检」不变量一致)。

序列化口径与出站一致:出站走 octo-lib util.ToJson(= json.Marshal),本函数 同用 json.Marshal,故字节数逐字节相等。非 type=17 为 no-op。

func RejectsCardEdit

func RejectsCardEdit(originalRaw []byte, contentEdit string) bool

RejectsCardEdit 报告一次消息编辑是否必须按 P1 Decision 7(卡片不可变)拒绝: 要么被编辑的目标消息本身已是卡片(originalRaw,把卡片改掉),要么编辑体本身 是卡片信封(contentEdit,把普通消息改写成卡片、绕过 Validate)。两个编辑入口 (bot_api、robot)都必须以本谓词单点门控,避免两条路各自拼守卫而漂移 —— PR#543 review 发现 robot 路径漏了「目标是卡片」这半边。P2(D6)以 cardmsg 对称校验 + card_seq CAS 解锁编辑,届时调用方移除本 reject。

func SubmitAction

func SubmitAction(envelopeRaw []byte, actionID string) (data map[string]interface{}, found bool)

SubmitAction 在「生效卡片」信封字节里按 id 查找一个 Action.Submit,返回其静态 data 对象与是否命中(P2 D3 防伪造 + D11 data 提取合一):

  • found=false:该 id 不是生效帧里任何 Action.Submit 的 id —— 调用方 fail-closed 拒绝(伪造 / 被重写移除的过期按钮天然落此分支)。
  • found=true, data=nil:命中但该动作未声明 data。
  • found=true, data≠nil:命中且带作者静态 data —— 服务端原样塞进 event_data.data (anti-forgery:绝不取请求里的 data)。

envelopeRaw 由调用方决定传哪份(content_edit 优先于原始 payload),据此过期帧 按钮天然 fail-closed。解析失败 / 无 card 返回 (nil, false)。

func Transient

func Transient(payload map[string]interface{}) bool

Transient 读取信封可选的 transient 标记(P2 D10.4)。transient 帧照常应用到 content_edit(D6/D9 不变),但不进修订历史 —— 进度帧(thinking/tool-state)不 淹没审批态变更。缺失/非布尔按 false(非 transient,入历史)。

func TransientFromContentEdit

func TransientFromContentEdit(contentEdit string) bool

TransientFromContentEdit 从编辑体 JSON 读取 transient。

func Validate

func Validate(payload map[string]interface{}) error

Validate 是 InteractiveCard(=17) 发送入口的 write-strict 校验 gate。

  • 非 type=17 的 payload 直接通过(no-op),老消息路径不变;
  • type=17 时依次执行:完整 payload 512KiB 上限(与 richtext 同口径,marshal 整个 map 而非子集,未知顶层字段一并计入)→ profile/card_version 协商 (Decision 10)→ card 结构白名单遍历(元素/动作/URL/节点数/深度)。

Validate 不修改 payload,只做 gate;plain 的权威生成在所有 enrich 之后由 Finalize 完成(与 pkg/richtext 的两步纪律对称)。

func ValidateInputs

func ValidateInputs(envelopeRaw []byte, inputs map[string]interface{}) error

ValidateInputs 按 D11 校验 card/action 请求的 inputs(fail-closed):

  • 每个键必须命中生效帧声明的 Input.* id;
  • 值必须是字符串;Input.Text ≤ 4KiB;Input.Toggle 必须等于 valueOn/valueOff; Input.ChoiceSet 必须命中声明的 choice value(multiSelect 为逗号分隔子集, 单选允许 "" 表示未选择);
  • P3-3:Input.Number 必须是合法 JSON 数字且有限;Input.Date 必须是 YYYY-MM-DD; Input.Time 必须是 HH:MM(24h);三者 "" 均视为未填放行。min/max 区间**不**服务端 强制(AC 规范定义为可忽略 hint,区间校验下放 bot,与 isRequired/regex 同);
  • 序列化总量 ≤ 16KiB。

envelopeRaw 是「生效卡片」信封字节(content_edit 优先,与 SubmitAction 的取帧 口径一致 —— 校验对象必须是用户实际看到的那一帧)。

Types

type CatalogProvenance added in v1.14.0

type CatalogProvenance struct {
	Version       int
	PrincipalType string
	PrincipalID   string
	SpaceID       string
}

CatalogProvenance 是 catalog_provenance 顶层标记的 typed 值对象。 字段与 wire 形状一一对应;SpaceID 允许为空(发送边界没有权威 Space 的 频道形态,如 Slice 3 之前的群聊 Bot 发送),非空值必须已 trim。

func ParseCatalogProvenance added in v1.14.0

func ParseCatalogProvenance(value interface{}) (CatalogProvenance, error)

ParseCatalogProvenance strict 解析一个 catalog_provenance 值。未知键、 缺键、类型错误、未知 principal、未 trim 值全部拒绝。

func (CatalogProvenance) MarshalMap added in v1.14.0

func (p CatalogProvenance) MarshalMap() map[string]interface{}

MarshalMap 输出 canonical wire map。key 集合与 ParseCatalogProvenance 的 strict 校验互为镜像;新增字段必须同时改两处并 bump version 语义评审。

func (CatalogProvenance) Validate added in v1.14.0

func (p CatalogProvenance) Validate() error

Validate 校验 canonical v1 形状。

type CatalogTemplateRef added in v1.14.0

type CatalogTemplateRef struct {
	ID      string
	Version string
}

CatalogTemplateRef 是顶层 template_ref 的 typed 值对象。

func ParseCatalogTemplateRef added in v1.14.0

func ParseCatalogTemplateRef(value interface{}) (CatalogTemplateRef, error)

ParseCatalogTemplateRef strict 解析顶层 template_ref:恰好 {id, version} 两个非空已 trim 字符串键(与 bot_api 的 caller-facing template_ref/v1 request 形状一致)。

type FrameCatalogMarkers added in v1.14.0

type FrameCatalogMarkers struct {
	Ref           CatalogTemplateRef
	Provenance    CatalogProvenance
	HasRef        bool
	HasProvenance bool
}

FrameCatalogMarkers 是一个有效帧的 server-authored catalog 身份快照。

func CatalogFrameMarkers added in v1.14.0

func CatalogFrameMarkers(envelopeRaw []byte) (FrameCatalogMarkers, error)

CatalogFrameMarkers 从一个有效 type-17 帧提取并校验顶层 catalog 标记。

兼容矩阵(D3 + invariant 7 static 历史兼容):

  • 两个标记都缺失 → legacy 帧,零值返回(不报错);
  • 只有 template_ref → pre-PR-C Bot Registry 帧,合法;
  • 两个都有 → 都 strict 校验;
  • 只有 catalog_provenance → 服务端从不产出该形状,拒绝;
  • 任一存在时,template_ref 必须与 metadata.octo.template 完全一致 (metadata 缺失/畸形同样拒绝 —— 标记只可能由 Registry 产出,而 Registry 必然写 metadata)。

非 type-17 payload 返回零值(调用方对非卡片本就不该看标记)。

type TemplateContext added in v1.12.0

type TemplateContext struct {
	Protocol string
	ID       string
	Version  string
}

TemplateContext is the immutable registry identity embedded by cardtmpl.Registry.Render in metadata.octo. It is read only from the effective server-authored card frame; clients never provide it to the action ingress.

func CardTemplateContext added in v1.12.0

func CardTemplateContext(envelopeRaw []byte) (TemplateContext, bool)

CardTemplateContext extracts a complete octo-card template identity from a type-17 envelope. Partial, malformed, or foreign-protocol metadata is absent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址