support agentic message in chatwitheino

[tangchaojun-bytedance]

Summary

• Make chatwitheino generic over schema.Message and schema.AgenticMessage.
• Add runtime MESSAGE_KIND selection plus separate session storage for message and agenticmessage.
• Reuse official Eino/Eino-Ext model implementations for OpenAI, Ark, agenticopenai, and agenticark.
• Update tutorial chapters and docs for both message kinds.

Validation

• go test ./... in quickstart/chatwitheino.
• Ark live smoke: ch01-ch09, cmd/ch10, and root server passed for message and agenticmessage with doubao-seed-2-0-code-preview-260215.
• OpenAI live smoke: ch01-ch09, cmd/ch10, and root server passed for message and agenticmessage after spacing requests to avoid QPM limits.

[shentongmartin]

PR #222 Review Summary

Overall Assessment: 可以合并，无 Blocker。

这是一个高质量的 PR，设计原则清晰（泛型 M adk.MessageType 贯穿全栈 + msgops 统一抽象层），实现正确（编译通过、现有 7 个测试全部 PASS、额外 16 个攻击测试全部 PASS，未发现 confirmed bug）。

---

Design Review Scorecard

Dimension	Rating	Notes
Concept Coherence	⭐⭐⭐⭐	msgops.Kind 是清晰的新概念
API Usability	⭐⭐⭐⭐	NewUser[M](), Text[M]() 直观
Minimum API Surface	⭐⭐⭐	AssistantDeltaText = AssistantText 可合并
Backward Compatibility	⭐⭐⭐⭐⭐	独立 module，不影响其他
Module Separation	⭐⭐⭐⭐	msgops / chatmodel / a2ui 职责清晰
Cohesion vs. Tension	⭐⭐⭐	ch05-ch09 大量代码重复
Elegance vs. Complexity	⭐⭐⭐⭐	泛型方案简洁
Naming	⭐⭐⭐⭐	KindMessage/KindAgentic 语义明确
Readability	⭐⭐⭐	msgops.go 568 行可拆分
Duplication	⭐⭐	safeToolMiddleware × 6, printAndCollect × 8
Documentation	⭐⭐⭐⭐	每个导出函数有 GoDoc
Internal Comments	⭐⭐⭐⭐	关键逻辑有注释

---

Top 3 Suggestions

1. 🟡 减少跨 chapter 的代码重复：safeToolMiddleware × 6 份、printAndCollectAssistantFromEvents × 8 份副本。建议提取到共享包（如 helpers/），降低维护成本。
2. 🟡 合并或文档化 AssistantDeltaText / AssistantText：两者实现完全相同（msgops/msgops.go L169-171），对用户而言名字暗示不同语义。如果是预留未来分化空间，建议添加注释说明。
3. 🟡 为 ModelRetryConfig 仅限 Message 类型的设计添加注释：代码中多处 if msgops.KindOf[M]() == msgops.KindMessage { cfg.ModelRetryConfig = ... }，应说明 Agentic 模式不启用重试的原因。

---

Attack Review: 16/16 PASS ✅

核心 msgops 抽象层在以下维度全部验证通过：

• Nil 安全（不 panic）
• 类型断言安全
• JSON 往返正确
• ValidateKind 边界条件健壮
• 角色标签正确（Tool vs You）
• 空消息/空工具结果处理正确

Additional Suggestions

4. 🟢 考虑将 msgops.go 拆分为多个文件（kind.go + construct.go + extract.go + variant.go）以提高可读性。
5. 🟢 为核心 msgops 包添加单元测试。

[shentongmartin]

Inline suggestions — see individual file comments below.

[shentongmartin]

Review Suggestions

🟡 Suggestion 1: Reduce cross-chapter code duplication

printAndCollectAssistantFromEvents is duplicated 8 times (ch02-ch09), truncate 7 times (ch04-ch09 + smoketest), and handleInterrupt 3 times (ch07-ch09). This results in ~800 LOC of duplication (30% of additions).

Suggested fix: Extract to helpers/eventloop.go with an options struct:

type PrintOptions struct {
    ShowToolCalls   bool
    ShowToolResults bool
    CaptureInterrupt bool
}

func PrintAndCollect[M adk.MessageType](
    events *adk.AsyncIterator[*adk.TypedAgentEvent[M]],
    opts PrintOptions,
) (string, *adk.InterruptInfo, error) { ... }

Each chapter can then call helpers.PrintAndCollect(events, helpers.PrintOptions{ShowToolCalls: true, CaptureInterrupt: true}) — keeping readability while reducing maintenance burden. If a bug is found in the event loop, it only needs to be fixed once.

---

🟢 Suggestion 3: Split msgops.go (746 lines) into multiple files

The single file mixes constructors, extractors, normalization, and validation. Suggested split for navigability:

File	Contents
kind.go	Kind, KindOf, KindFromEnv, ValidateKind, DefaultSessionDir
construct.go	NewUser, NewSystem, NewAssistant, NewToolResult
extract.go	Text, AssistantText, AssistantDeltaText, UserText, ToolCalls, ToolResults, RoleLabel, HasContent
normalize.go	NormalizeForSession, NormalizeMessagesForModelInput, normalizeAgenticMessage, normalizeAgenticContentBlock, etc.
variant.go	VariantRoleLabel, VariantIsToolResult, DrainToolResult, ConcatChunks, UnmarshalMessage, IsNil

Not a blocker — purely a readability/navigability improvement.