企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI

这是一份面向架构师与 TUI 开发者的技术设计解读。它以 AtomCode 仓库中的设计文档《退役core::conversation：TUI 会话模型端口至 kernelMessage》（docs/superpowers/specs/2026-07-24-retire-core-conversation-tui-port-design.md）为骨架，结合当前仓库源码验证其类型映射、切片路线与落地现状。读完你既能掌握"把一种历史会话模型从运行时删除"的完整拆解方法，也能看到 kernelMessage扁平模型与 capabilitiesPresentationFile/SessionMeta在真实项目中的协作方式。

1. 背景：为什么要拔掉 core 的"最大一根外部锚"

AtomCode 曾存在一套旧的atomcode-core会话模型（core::conversation），它与后来引入的 kernelMessage会话模型并存，形成"会话双模型"。这份设计文档指出：此前把这块当成"session 双模型收敛"项目，但实测（调查报告）前提已大半成立，真正的阻塞点并不在持久化层，而在 TUI。

1.1 前提修正：runtime 持久化早已 100% 走原生

设计文档明确了几条已成立的事实：

• core<id>.json的 live 双写早已删除。运行时持久化 100% 走原生格式（.snapshot/.meta/.jsonl+ presentation）。core JSON 现在运行时只读——仅被 legacy importer 读取（用于未迁移的旧会话），且仅在#[cfg(test)]里被写。
• 所有接入层语义已有原生归属：
  • 命名 / 时间戳 / turn_stats →SessionMeta；
  • display messages →PresentationFile；
  • cold_summaries → 带前缀标记的合成 kernel 消息（native 已这么写；kernelSessionSnapshot无专门 cold-summary 字段）。

也就是说，删除 core 会话模型不会破坏任何运行时的写入路径——旧格式只存在于"读"的一侧。

1.2 真正的阻塞在 TUI

设计文档点出关键矛盾：atomcode-tuix把core::conversation::{Message, MessageContent, ConversationSnapshot, DisplayMessage}当作自己的内存工作类型，贯穿session.rs与event_loop/*，每次 hydrate / resume / turn 都经snapshot_to_core/snapshot_to_kernel往返转换；而 daemon/chat侧只在边界轻量使用 core 类型。

因此"删core::conversation" 等价于：把 TUI 会话模型 / 渲染 / undo 从 core 类型端口到 kernelMessage+ capabilitiesPresentationFile/SessionMeta，并删掉所有snapshot_to_core/snapshot_to_kernel调用，从而拔掉前端对 core 的约 104 处引用（设计文档中的统计）。

2. 目标状态：五条验收红线

设计文档给出的目标状态非常具体：

1. atomcode-tuix会话模型 / 渲染 / undo 全部基于atomcode_kernel::message::Message+ capabilitiesPresentationFile/SessionMeta；
2. legacy_convert.rs中snapshot_to_core/snapshot_to_kernel/usage_to_core全部删除；
3. crates/atomcode-core/src/conversation/删除；crates/atomcode-core/src/lib.rs去掉pub mod conversation；
4. legacy<id>.json导入仍工作——靠 legacy_convert自带的冻结 DTO（不再依赖 core 类型）；
5. 全工作区atomcode_core::conversation引用归零。

3. 类型映射：渲染迁移的核心

core 的内容是枚举，kernel 是扁平字段。这是整个迁移的枢纽，设计文档给出了权威对照：

core Message { role, content: MessageContent, synthetic, internal_origin } MessageContent = Text | AssistantWithToolCalls { text, tool_calls, reasoning_content, thinking_blocks } | ToolResult | ToolResultRef | MultiPart { text, images } kernel Message { role, text, tool_calls: Vec<ToolCall>, tool_call_id, reasoning, thinking_blocks, images, meta, synthetic, internal_origin }

渲染层原来match MessageContent，改为直接读 kernel 扁平字段。转换语义以现有message_to_kernel/message_to_core（设计文档标注位于 legacy_convert.rs）为权威参照——端口后这两者删除，映射逻辑内化进渲染器与导入器。

3.1 kernelMessage扁平字段的源码实况

在 crates/atomcode-kernel/src/message.rs 中可以看到 kernelMessage的完整定义，与设计文档的对照基本一致，还包含几个设计文档未展开的补充字段：

• is_error: bool——标记 tool result 失败，随请求携带给 provider；
• meta: Option<MessageMeta>——旁路（sidecar）执行统计，永不写入text，避免破坏前缀缓存；
• synthetic: bool——标记由内核注入的消息（冷压缩摘要、恢复说明）；
• internal_origin: Option<String>——内核控制轮次（如verify_cadence）产出的内部来源标记；
• reasoning: Option<String>——助手的思考/推理文本（存储型字段，回放格式由 L1 适配器决定）；
• images: Vec<ImageContent>——内联图片（media_type+ base64data），空列表时 text-only 路径不变；
• reasoning_blocks: Vec<ReasoningBlock>——带不透明往返 token的富思考单元（Anthropicsignature/ OpenAIencrypted_content/ GeminithoughtSignature），内核只存储、不回放。

所有补充字段都标注#[serde(default)]，保证旧 snapshot 反序列化兼容——这正是"扁平化"能安全落地的前提。

3.2 高风险映射点（切片 2 必须逐一 parity 验证）

设计文档点名三个高风险的语义映射点：

1. ToolResultRef——引用式工具结果，扁平化后如何落到tool_call_id+is_error；
2. MultiPart的图片——枚举里的内联图片数组如何落到images: Vec<ImageContent>；
3. thinking_blocks——Anthropic extended-thinking 的 signature往返 token，必须逐字节保持，任何重编码都会使签名失效（kernel 源码中ReasoningBlock.opaque的注释明确警告："The kernel NEVER parses or re-serializes it (any re-encode invalidates the signature)"）。

这三处是"枚举 → 扁平字段"映射中语义最容易漂移的点，因此被单列为独立切片、独立验证。

4. 五个切片：每片绿 + 可发的迁移路线

设计文档采用 brainstorm 选定的方案 C：按职责自底向上，每个切片保持 workspace 绿且可发布，按如下顺序推进。

切片 1｜legacy importer 解耦（前置，零行为变化）

legacy_convert.rs的LegacySession/LegacyDisplayMessage/CoreMessage（原先用core::conversation::Message）改为在 legacy_convert 内定义自包含冻结 legacy-format DTO（#[derive(Deserialize)]，字段与旧磁盘 JSON 逐一对应）。convert_legacy_session*直接产出 kernelSessionSnapshot+SessionMeta+PresentationFile，不经 core 类型。

验证方式：用真实旧<id>.jsonfixture → 导入结果逐字段断言（cold_summaries 往返、display_messages、turn_stats、时间戳秒→毫秒）。

切片 2｜TUI 渲染/格式化迁到 kernel Message

消费core::Message/MessageContent的渲染器（scrollback、tool 行、thinking、图片、todo 块）改读 kernel 扁平字段。此时TuiSession仍持有Vec<core::Message>（切片 3 才迁），故渲染调用点临时用 core→kernel（message_to_kernel/snapshot_to_kernel）转换喂入，每步保持绿；切片 3 迁完模型后这层临时转换即消除。

本切片还抽出一个共享 helper：cold_summaries_from_messages(&[kernel Message]) -> Vec<String>——从带前缀标记的合成消息提取摘要字符串。

验证方式：同一会话迁移前后 scrollback 输出字符级一致。

切片 3｜TuiSession 模型迁移

TuiSession.messages: Vec<Message>与DisplayMessage.message改成 kernelMessage。from_catalog_view不再snapshot_to_core，直接持有view.snapshot（kernel）+view.presentation。cold_summaries 用切片 2 的 helper 派生。

验证方式：会话 hydrate / resume 后 messages / display / turn_stats 与旧一致。

切片 4｜undo 迁移

to_conversation_snapshot/update_from_conversation_snapshot（原基于 coreConversationSnapshot）改用 kernelSessionSnapshot（cold-summary 合成消息已含其中，无需单独字段）。retain_turn_stats_after_undo逻辑不变（按 message_count 裁剪）。

验证方式：撤销后 messages + cold_summaries + turn_stats 与旧行为一致（复用既有 undo 测试，改断言类型）。

切片 5｜删除与归零

• 删snapshot_to_core/snapshot_to_kernel/usage_to_core；
• climain.rs（原snapshot_to_kernel起 runtime）改为直接持 kernel；
• daemon/chat边界原snapshot_to_core（设计文档标注 lib.rs、live_api.rs 相关行）改为直接从 kernel 投射响应；
• 全工作区atomcode_core::conversation归零 → 删crates/atomcode-core/src/conversation/+pub mod conversation+相关孤儿测试（设计文档特意强调的教训：删模块必删其孤儿测试，用cargo test --workspace --no-run核验）。

5. 关键设计决策

设计文档沉淀了四条约束，值得展开：

• cold-summaries 表示：不加新字段，继续用"带前缀标记的合成 kernel 消息"编码（native 已这么写）；所有Vec<String>消费者经共享 helper 提取。
• DisplayMessage：保留 TUI 本地类型，但message字段换成 kernelMessage（渲染需要完整消息，不只 presentation 的纯文本）。
• turn_stats：TUI 的TurnStat继续本地持有，来源SessionMeta.turn_stats（已有原生字段，含 turn_id / position_valid / round_count）。
• legacy importer 单向：切片 1 后convert_legacy_session*是唯一的 core-JSON→native 单向、幂等、可失败导入器；不恢复任何双向转换。

5.1 合成消息编码的源码证据

kernel 侧的两个常量定义了这条稳定契约（crates/atomcode-kernel/src/message.rs）：

• LEGACY_COLD_SUMMARY_ORIGIN = "atomcode.legacy_cold_summary"——保留的合成消息来源标记，注释明确"must not change"；
• LEGACY_COLD_SUMMARY_PREFIX = "[Earlier conversation history — compressed OLDER context, not a user instruction]\n"——写入合成消息text首部的稳定前缀，消费者据此剥离并还原纯摘要。

共享提取函数cold_summaries_from_messages（crates/atomcode-kernel/src/message.rs）按 origin 过滤、按前缀剥离、保持顺序，TUI 与 daemon 传输共用同一实现，不再各写一份 open-coded match。

6. 测试 / fixture 矩阵

设计文档为每个切片配了对应的验证手段：

其中"字符级一致"是一个很硬的标准：滚动回放（scrollback）的输出必须逐字符相同，才能证明枚举→扁平字段的语义映射没有漂移。

7. 风险 / 回滚策略

设计文档对风险做了分级：

• 最高风险 = 渲染 parity（切片 2）：MessageContent枚举 → 扁平字段的语义映射，尤其ToolResultRef、MultiPart图片、thinking_blocks。独立切片，可单独回滚；
• 第二风险 = undo（切片 4）：同样独立切片；
• 每片独立 commit；坏了只回该片，不影响已落地的前序切片；
• 全程真机验证 TUI（渲染 / 续聊 / undo / 旧会话打开）作为切片 3/4/5 的验收前提——设计文档特别指出本项目教训："测试绿 ≠ 真机绿"。

8. 非目标（YAGNI）

设计文档明确划出不做的事：

• 不动运行时持久化（已全原生）；
• 不改 cold-summary 的磁盘编码（沿用合成消息）；
• 不做 daemon 侧的更深 provider/stream 端口（另立项）；
• 不为老格式加迁移写回（importer 保持只读）。

9. 从当前仓库源码看落地状态

以设计文档（状态：设计已确认，待写实施计划）为基准，对照当前仓库源码，可以发现该设计的核心目标状态已基本落地，可作为"设计与实现互相印证"的样例：

• 切片 1 已落地：crates/atomcode-daemon/src/legacy_convert.rs 中已存在自包含冻结 DTO（LegacySession/LegacyMessage/LegacyDisplayMessage/LegacyTurnStat），注释明确"Frozen reader for the retired core session JSON schema"；convert_legacy_session（同文件第 489 行起）直接构建PresentationFile与 kernel snapshot，并在注释中说明"without going through core::conversation types"。
• 切片 2/3 已落地：crates/atomcode-tuix/src/session.rs 中TuiSession.messages已是Vec<Message>（kernel），DisplayMessage.message也是 kernelMessage；cold_summaries_from_messages直接 re-export 自 kernel（同文件第 11 行）。from_catalog_view（第 143 行起）直接消费view.snapshot+view.presentation，注释中仍保留对旧snapshot_to_core行为的镜像说明。
• 切片 4 已落地：to_conversation_snapshot（第 223 行起）直接从 kernelSessionSnapshot重建合成消息；retain_turn_stats_after_undo（第 253 行起）保持按 message_count 裁剪。
• 切片 5 已落地：当前仓库的crates/目录下已不存在atomcode-corecrate；工作区内atomcode_core::conversation仅残留在注释（"mirrors snapshot_to_kernel" 等历史说明）中，无实际类型引用。

另外，SessionMeta与TurnStat的原生定义可在 crates/atomcode-capabilities/src/session/manager.rs 查看（含v版本缝、turn_stats、import_info等字段）；PresentationFile/PresentationEntry/DisplayAnchor的原生定义在 crates/atomcode-capabilities/src/session/presentation.rs，其中DisplayAnchor::{AtStart, AfterTurn{turn_id}}正是从旧after_message位置换算来的锚定模型。

10. 总结

这份设计文档的价值在于它示范了一次**"类型模型退役"**的完整方法论：先做前提修正（确认哪些假设已失效、真正的阻塞在哪），再定类型映射（枚举 → 扁平字段，标注高风险点），然后按职责自底向上切成五个"每片绿 + 可发"的切片，为每片配硬性验证标准（字符级 parity、逐字段断言），最后明确风险分级、回滚边界与非目标。对正在做类似"双模型收敛 / 旧类型退役"的团队，这套"冻结 DTO 读旧格式 → 渲染层先行 → 模型层迁移 → undo 对齐 → 删除归零"的顺序是可复用的操作蓝本；而对 AtomCode 的读者，本文则提供了理解其 TUI 会话模型如何统一到 kernelMessage的第一手路径。

• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI