AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载导读moonshot-ai/transcript是 Kimi Code下一代 Agent CLI仓库中的一个核心私有包职责是为会话转录transcript提供一套同构isomorphic的渲染数据层从 Agent 粒度的内存存储、幂等操作模型、按粒度门控的订阅到框架无关的视图注册表四层架构层层递进。阅读本文后你将理解 transcript 包的 L1–L4 分层设计、14 种操作operation与幂等追加append机制、off / turn / block / delta四级订阅粒度的实现原理以及它如何被 kap-server 的 v2 REST 路由与 v1 WebSocket 通道消费从而支撑转录实时渲染、断线重连冷重建、按需分页回放三类核心场景。1. 包定位一个同构的转录渲染数据层在 Kimi Code 仓库中packages/transcript/package.json将该包描述为Isomorphic transcript rendering data layer: agent-granular L1 store, idempotent L2 operations, granularity-gated L3 subscriptions, framework-free L4 view registry.四个关键词揭示了它的设计意图Isomorphic同构同一套数据模型与操作逻辑可同时运行在服务端kap-server与客户端Web 前端不因运行环境不同而分叉Agent-granularAgent 粒度转录按agent_id隔离存储与订阅主 Agent 与子 Agentsubagent各自拥有独立的转录流Idempotent幂等所有 upsert 与 append 操作可重复投递而不产生重复内容天然适配断线重连后的补发catch-up场景Framework-free框架无关视图层只是注册表不绑定任何 UI 框架渲染器由消费方自行注入。该包的全部 wire 类型传输层类型定义都由 transcript 包自身持有依据 0.0.1 变更记录并通过 入口文件 统一导出涵盖模型、操作、存储、粒度、视图、分页、历史折叠等全部子模块。2. L1–L4 四层架构总览从源码目录结构可以清晰看到四层职责的落位层级职责源码位置L1 StoreAgent 粒度的转录内存存储、快照与变更通知store/agentTranscript.ts、store/transcriptStore.tsL2 Operations幂等操作定义与纯函数应用逻辑ops/operation.ts、ops/apply.tsL3 Subscriptions按off/turn/block/delta粒度过滤操作与快照granularity/grade.ts、granularity/filterOps.tsL4 View框架无关的渲染器注册与解析view/registry.ts数据流方向是上游产生操作 → L2 幂等应用进 L1 存储 → L1 通知变更 → L3 按订阅粒度过滤 → 投递给 WebSocket 订阅者 → L4 负责把转录条目渲染成 UI。REST 分页读取则直接查询 L1 存储或冷快照详见第 8 节。3. 数据模型与 wire 类型3.1 核心 ID 规范contract/schema.ts 定义了全部 ID 的 zod 校验规则turnId、stepId、frameId、taskId、agentId均为非空字符串其中agent_id有更严格的约束const AGENT_ID_PATTERN /^[A-Za-z0-9._-]{1,128}$/; export function isPlainAgentId(agentId: string): boolean { return AGENT_ID_PATTERN.test(agentId) agentId ! . agentId ! ..; }该函数在服务端路由中被复用用于拒绝携带路径分隔符或..的非法agent_id见 routes/transcript.ts 的校验逻辑从入口杜绝了路径穿越类问题。3.2 转录条目Itemturn / marker / taskref转录的主体是items数组由三种条目组成schema.tsturn一轮对话轮次包含turnId、ordinal、statequeued/running/completed/failed/cancelled、origin、prompt、attachmentIds、steps等marker用户自定义标记点如阶段分隔可携带任意payloadtaskref指向任务列表的引用。3.3 Turn 的来源originturnOriginSchemaschema.ts用 discriminated union 区分了 7 类轮次来源kind含义可选字段user用户直接发起payloadcron定时任务触发taskId、payloadtask任务驱动taskId必填、payloadhook钩子触发payloadcompaction压缩/整理触发payloadside旁路触发payloadother兜底payload用户来源还可以进一步投影project出技能激活信息projectTranscriptUserOrigincontract/origin.ts会把原始的user来源规整为kind: user或kind: skill_activationtrigger: user-slash并提取skillName、skillArgs与clientMetadata——这意味着转录数据层能够区分真实用户输入与通过/技能触发的输入对前端渲染用户消息的形态非常关键。3.4 帧Frame转录的最小渲染单元一个 step步骤由若干 frame 组成schema.ts共有四种帧类型kind用途关键字段text文本含用户/助手角色、附件引用、prompt 引用roleuser/assistant、text、attachmentIds、promptIdsthinking思维链文本texttool工具调用含完整生命周期name、staterunning/done/error、input/output/display、progress、agentRefs、approvalId、todoIdnotice提示/告警/错误levelerror/warning/info、message、detail工具帧还支持流式进度toolFrameProgressSchemakind 为stdout/stderr/progress/status/custom这是终端工具实时输出能边跑边刷的数据基础。3.5 旁挂实体与元数据除 items 外快照还携带多类旁挂实体schema.tstasks后台任务shell/subagent/tool/other含outputTail任务输出尾部支持 append 操作、状态机running/completed/failed/timed_out/killed/lostinteractions审批/提问approval/question状态含pending/approved/rejected/cancelled/answered/dismissedpending 集合被单独维护attachments附件实体url/file/session_media 三类 sourcetodos待办列表promptsprompt 生命周期running/queued/blocked/completed/failed/abortedmeta目标goal、模式plan/swarm/tower、Agent 状态phase、usage、permission 等。这些实体在 store/agentTranscript.ts 中均以Map或Set维护便于 O(1) 查询getTurn、getTask、getInteraction等访问器一应俱全。4. 幂等操作模型L24.1 14 种操作全集ops/operation.ts 定义了转录状态的唯一合法变更方式——操作对象TranscriptOperation共 14 种操作作用说明reset整体重置以快照替换整个 Agent 状态turn.upsert新建/更新轮次幂等内容相同则跳过step.upsert新建/更新步骤幂等frame.upsert新建/更新帧幂等append追加文本基于偏移量的流式追加支持间隙检测marker.upsert插入标记可选beforeTurn定位taskref.upsert插入任务引用可选beforeTurn定位task.upsert更新任务幂等interaction.upsert更新审批/提问同步维护 pending 集合attachment.upsert更新附件幂等todo.upsert更新待办幂等prompt.upsert更新 prompt幂等meta.merge合并元数据支持 null 语义的字段级覆盖items.remove删除条目级联清理悬挂交互applyOperationops/apply.ts是一个针对操作类型的纯函数分发器返回ApplyResult包含新状态、changed标志与可选的gap信息。4.2 幂等性的三重保障第一重字段级比较。每个 upsert 都先与现有对象做逐字段比较如turnEquals、stepEquals、frameEquals、taskEquals、promptEquals等内容完全一致时返回changed: false不触发任何状态变更与通知。第二重骨架自动补齐。上游操作可能乱序到达例如先收到frame.upsert再收到turn.upsert。applyStepUpsert/applyFrameUpsert会通过skeletonTurn/skeletonStepapply.ts自动生成运行中的骨架 turn/step 并插入正确序位保证无序投递也能收敛。第三重偏移量追加append。流式文本的核心是appendAtOffsetapply.tsexport function appendAtOffset(local, offset, chunk) { if (offset local.length) return { text: local, changed: false, gap: { expected: local.length, got: offset } }; if (local.slice(offset, offset chunk.length) chunk) { return { text: local, changed: false }; // 完全重复直接忽略 } const overlap local.length - offset; if (local.slice(offset) ! chunk.slice(0, overlap)) { return { text: local, changed: false, gap: { expected: local.length, got: offset } }; // 偏移不匹配报 gap } const novel overlap 0 ? chunk.slice(overlap) : chunk; if (novel.length 0) return { text: local, changed: false }; return { text: local.slice(0, offset) chunk, changed: true }; }这个函数保证同一段文本重复追加被忽略断点续传时允许重叠只追加新片段偏移量超前gap时返回expected/got供上层定位。append操作既作用于 text/thinking 帧也作用于任务的outputTailapplyTaskAppend是转录永不丢字、重连不重复的关键。4.3 删除操作的级联语义applyItemsRemoveapply.ts在删除轮次时会扫描其所有 tool 帧的toolCallId找出挂在这些工具调用上的 pending 交互并一并清除——避免工具调用已消失但审批还悬空的脏状态。这是转录一致性中容易忽略、但实现得很完整的细节。5. L1 内存存储与快照窗口store/agentTranscript.ts 的AgentTranscript类以AgentId为粒度持有内部状态对外暴露apply(ops)批量应用操作返回{ accepted, gap }accepted是真正产生变更的操作gap是首个间隙并以TranscriptChangeEvent通知所有监听者agentTranscript.tsonChange(listener)注册变更监听返回可dispose()的句柄snapshot(window?: { tailTurns })导出快照。当指定tailTurns窗口时只保留最近 N 个轮次含其附属条目并置hasMoreOlder true标记还有更早内容agentTranscript.ts——这是先渲染最近 N 轮、再按需回放更早内容的实现基础一组只读访问器getItems、getTurn、getTasks、getInteractions、getAttachments、getTodos、getPrompts、getMeta、listPendingInteractions、hasMoreOlder。服务端通过TranscriptService把这些内存 store 与会话生命周期绑定并维护操作日志journal与seq水位线用于后续的增量补发见第 8、9 节。6. L3 订阅粒度off / turn / block / delta6.1 四级粒度与等级排序granularity/grade.ts 定义了四个订阅等级及其偏序export const GRADE_RANK: ReadonlyRecordTranscriptGrade, number { off: 0, turn: 1, block: 2, delta: 3, };等级含义接收内容off不订阅不接收任何转录事件turn轮次级只收轮次头含 prompt步/帧内容一律不推送block块级追加step.upsert/frame.upsert但append流式增量仍被过滤delta增量级额外接收append可渲染字符级流式输出订阅规格是一个RecordagentId, grade支持*通配默认值gradeFor(spec, agentId)先查精确 agent再回落*都没有则视为offgrade.ts。6.2 升级触发重置needsResetOnTransition(prev, next)grade.ts返回GRADE_RANK[next] GRADE_RANK[prev]——当订阅从低粒度升级到高粒度时说明客户端之前缺失了更细的内容服务端必须下发一次完整快照transcript.reset而非增量这就是升级必重置协议规则的来源。6.3 操作与快照的双重过滤granularity/filterOps.ts 提供两套过滤函数function admits(grade, op) { switch (op.op) { case append: return GRADE_RANK[grade] GRADE_RANK.delta; // 仅 delta 接收 case step.upsert: case frame.upsert: return GRADE_RANK[grade] GRADE_RANK.block; // 仅 block 接收 default: return true; // 其余全量透传 } }redactSnapshotForGrade则负责在快照层面脱敏block以下等级会把每个 turn 的steps置空只保留轮次头——与升级必重置配合保证低粒度订阅者拿到的快照也严格符合其粒度。7. L4 视图注册表框架无关的渲染解析view/registry.ts 的ViewRegistryC是一个泛型注册表C是消费方自定义的渲染器类型如 React 组件或渲染函数。它维护三张映射registerTool(key, renderer)为工具注册渲染器解析时resolveTool优先用帧的view字段、否则用name均转为小写匹配支持fallbackTool兜底registerInput(originKind, renderer)按轮次来源 kinduser、cron等注册输入渲染器resolveInput按origin.kind查找registerMarker(marker, renderer)按标记名注册渲染器。这套设计让转录数据层与 UI 框架彻底解耦服务端只负责推送结构化数据前端无论用 React、Vue 还是原生渲染都只需注册自己的渲染器。8. 分页查询v2 REST 的冷热双路径8.1 分页原语pagination/paginate.ts 的paginateTurns(items, query)实现了轮次级分页先把 items 按 turn 边界切成段splitSegments再依据游标方向选取页before_turn向更早方向翻页默认行为after_turn向更新方向翻页page_size每页轮次数Math.max(1, pageSize)保证至少为 1。两种游标是互斥的这一约束同时体现在 schema 的superRefine校验schema.ts与服务端路由的 zod coercion 中。8.2 服务端路由GET /sessions/{session_id}/transcriptkap-server/src/routes/transcript.ts 实现了该端点逻辑分两条路径热会话live从transcriptService.forSessionLive(session_id)取内存 storeensureAgentHistory等待该 Agent 的历史回填再用paginateTurns分页并返回响应同时携带tasks/interactions/attachments/todos/prompts/meta/agents/pending_interactions/seq其中seq来自服务端水位线供客户端做增量同步锚点冷会话cold会话已退出时调用readColdSnapshot从持久化的 wire 记录重建该 Agent 的转录并合并冷 rosterAgent 名册找不到则返回SESSION_NOT_FOUND。默认page_size为 20transcript.ts合法范围 1–100。8.3 增量补发与用户消息端点同文件还提供两个配套端点GET /sessions/{session_id}/transcript/ops按since_seq返回该 Agent 的操作日志批次seq since_seq旧→新complete: false表示会话已不在线或日志回溯不到该水位调用方必须回退到全量刷新transcript.tsGET /sessions/{session_id}/transcript/user-messages聚合会话内所有开启轮次的输入真实用户文本、user-slash技能命令、cron 提示等可经 origin 区分agent_id缺省时读取所有已注册 Agent附件只携带元数据transcript.ts。这三条路由共同构成全量分页 增量追平 输入聚合的完整读取面。9. v1 WebSocket 订阅通道按连接粒度控制按 0.0.1 变更记录客户端通过 v1 WebSocket 订阅按 Agent 的转录更新且支持按连接per-connection的粒度控制。传输侧的实现位于 transport/ws/v1/wsConnectionV1.ts订阅帧负载用transcriptSubscribeV2PayloadSchemaschema.ts校验结构为{ session_id: string; transcript: RecordagentId, off | turn | block | delta; // 含 * 通配 transcript_since?: RecordagentId, seq; // 断线续传水位 }服务端解析后依据每个 Agent 的粒度等级第 6 节过滤操作流并通过transcript.reset完整快照含has_more_older与seq与transcript.ops增量批次两类事件投递contract/events.tstranscript_since让重连的客户端可以直接从上次的seq追平配合 REST 的/ops端点形成断线 → 增量追平 → 粒度升级重置的闭环。10. 版本演进0.0.1 与 0.0.2 的关键变化10.1 0.0.1数据层的诞生PR #18880.0.1 是包的初始版本奠定全部骨架新增统一、Agent 粒度的转录渲染数据层并由 v2 server 对外服务客户端可通过GET /sessions/{id}/transcript拉取轮次分页转录可通过 v1 WebSocket 按连接订阅各 Agent 的转录更新粒度支持off / turn / block / delta所有转录 wire 类型归属 transcript 包自身即本文第 3 节的全部 schematurn.started事件开始携带轮次的 prompt 文本使实时转录在轮次一开启就能渲染用户输入。10.2 0.0.2子 Agent 轮次携带编排者 promptPR #32890.0.2 针对子 Agent 转录看不到用户原始意图的问题做了修补isDisplayablePromptOrigin现在接受system_trigger/subagent来源——即由主 Agent 编排、通过 subagent run 消息开启的轮次因此实时场景下turn.started事件会包含该轮次的 prompt冷重建场景下开启轮次时的输入文本与附件会被折叠进由 subagent run 消息打开的轮次中保证冷会话回放与实时体验一致其他系统触发来源goal_continuation、stop_hook、loadable-tools仍然不带 prompt避免把内部机制文本污染进用户可见的转录。这一变更的意义在于转录数据层不仅要记录谁说了什么还要在系统触发轮次中保留用户真正的诉求让多 Agent 协同的回放依然围绕用户的意图展开。11. 测试与验证该包自带 vitest 测试覆盖数据层核心行为test/layers.test.ts侧重四层架构存储/操作/粒度/视图的组合行为test/store.test.ts侧重AgentTranscript存储语义包括操作应用、快照窗口与变更通知。在仓库根目录运行pnpm --filter moonshot-ai/transcript test对应 package.json 的vitest run即可执行全部用例pnpm --filter moonshot-ai/transcript typecheck可做类型检查。服务端侧的集成行为则在 kap-server 测试套件如transcript.test.ts、transcriptContract.e2e.test.ts中进一步验证 REST 契约与 e2e 链路。12. 总结moonshot-ai/transcript用四个小而专的层次回答了多 Agent 会话转录如何高效、一致地传输与渲染这一工程问题L1 存储负责状态与快照窗口L2 操作负责幂等收敛与流式追加L3 粒度负责按需降载与升级重置L4 视图负责渲染解耦而seq水位线 操作日志 冷重建则把实时、断线追平与历史回放统一到同一条数据契约之上。对于希望深入 Agent 会话基础设施的读者contract/schema.tswire 契约、ops/apply.ts幂等核心与 kap-server 的 transcript 路由服务端整合是最值得继续阅读的三份文件。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐qwen-code Daemon 共享 UI Transcript 层从 SSE 事件流到多端 Transcript 渲染的统一架构qwen code Daemon 共享 UI Transcript 层从 SSE 事件流到多端 Transcript 渲染的统一架构 导读 qwen code人工智能AI Agent代码智能体工具调用交互助手CLIQwenInvenTree 0.4.6 版本解析模态表单分组机制与创建部件时内联录入制造商/供应商信息InvenTree 0.4.6 版本解析模态表单分组机制与创建部件时内联录入制造商/供应商信息 本篇文章以 InvenTree 开源库存管理系统的 0.4.6AI Agent代码智能体人工智能大模型CLI深度解析 Kimi Code 终端 UI 框架 moonshot-ai/pi-tui从差分渲染到全屏交互的演进之路深度解析 Kimi Code 终端 UI 框架 moonshot ai/pi tui从差分渲染到全屏交互的演进之路 导读 moonshot ai/pi tAI Agent代码智能体人工智能大模型CLI上一篇XCOM 2模组管理器完整上手教程用AML启动器十分钟搞定模组冲突、乱序与崩溃下一篇魔兽世界宏编辑器 GSE 快速上手指南10 分钟做出第一个技能循环创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从存储到订阅：Kimi Code 的 @moonshot-ai/transcript 转录渲染数据层架构解析
AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载导读moonshot-ai/transcript是 Kimi Code下一代 Agent CLI仓库中的一个核心私有包职责是为会话转录transcript提供一套同构isomorphic的渲染数据层从 Agent 粒度的内存存储、幂等操作模型、按粒度门控的订阅到框架无关的视图注册表四层架构层层递进。阅读本文后你将理解 transcript 包的 L1–L4 分层设计、14 种操作operation与幂等追加append机制、off / turn / block / delta四级订阅粒度的实现原理以及它如何被 kap-server 的 v2 REST 路由与 v1 WebSocket 通道消费从而支撑转录实时渲染、断线重连冷重建、按需分页回放三类核心场景。1. 包定位一个同构的转录渲染数据层在 Kimi Code 仓库中packages/transcript/package.json将该包描述为Isomorphic transcript rendering data layer: agent-granular L1 store, idempotent L2 operations, granularity-gated L3 subscriptions, framework-free L4 view registry.四个关键词揭示了它的设计意图Isomorphic同构同一套数据模型与操作逻辑可同时运行在服务端kap-server与客户端Web 前端不因运行环境不同而分叉Agent-granularAgent 粒度转录按agent_id隔离存储与订阅主 Agent 与子 Agentsubagent各自拥有独立的转录流Idempotent幂等所有 upsert 与 append 操作可重复投递而不产生重复内容天然适配断线重连后的补发catch-up场景Framework-free框架无关视图层只是注册表不绑定任何 UI 框架渲染器由消费方自行注入。该包的全部 wire 类型传输层类型定义都由 transcript 包自身持有依据 0.0.1 变更记录并通过 入口文件 统一导出涵盖模型、操作、存储、粒度、视图、分页、历史折叠等全部子模块。2. L1–L4 四层架构总览从源码目录结构可以清晰看到四层职责的落位层级职责源码位置L1 StoreAgent 粒度的转录内存存储、快照与变更通知store/agentTranscript.ts、store/transcriptStore.tsL2 Operations幂等操作定义与纯函数应用逻辑ops/operation.ts、ops/apply.tsL3 Subscriptions按off/turn/block/delta粒度过滤操作与快照granularity/grade.ts、granularity/filterOps.tsL4 View框架无关的渲染器注册与解析view/registry.ts数据流方向是上游产生操作 → L2 幂等应用进 L1 存储 → L1 通知变更 → L3 按订阅粒度过滤 → 投递给 WebSocket 订阅者 → L4 负责把转录条目渲染成 UI。REST 分页读取则直接查询 L1 存储或冷快照详见第 8 节。3. 数据模型与 wire 类型3.1 核心 ID 规范contract/schema.ts 定义了全部 ID 的 zod 校验规则turnId、stepId、frameId、taskId、agentId均为非空字符串其中agent_id有更严格的约束const AGENT_ID_PATTERN /^[A-Za-z0-9._-]{1,128}$/; export function isPlainAgentId(agentId: string): boolean { return AGENT_ID_PATTERN.test(agentId) agentId ! . agentId ! ..; }该函数在服务端路由中被复用用于拒绝携带路径分隔符或..的非法agent_id见 routes/transcript.ts 的校验逻辑从入口杜绝了路径穿越类问题。3.2 转录条目Itemturn / marker / taskref转录的主体是items数组由三种条目组成schema.tsturn一轮对话轮次包含turnId、ordinal、statequeued/running/completed/failed/cancelled、origin、prompt、attachmentIds、steps等marker用户自定义标记点如阶段分隔可携带任意payloadtaskref指向任务列表的引用。3.3 Turn 的来源originturnOriginSchemaschema.ts用 discriminated union 区分了 7 类轮次来源kind含义可选字段user用户直接发起payloadcron定时任务触发taskId、payloadtask任务驱动taskId必填、payloadhook钩子触发payloadcompaction压缩/整理触发payloadside旁路触发payloadother兜底payload用户来源还可以进一步投影project出技能激活信息projectTranscriptUserOrigincontract/origin.ts会把原始的user来源规整为kind: user或kind: skill_activationtrigger: user-slash并提取skillName、skillArgs与clientMetadata——这意味着转录数据层能够区分真实用户输入与通过/技能触发的输入对前端渲染用户消息的形态非常关键。3.4 帧Frame转录的最小渲染单元一个 step步骤由若干 frame 组成schema.ts共有四种帧类型kind用途关键字段text文本含用户/助手角色、附件引用、prompt 引用roleuser/assistant、text、attachmentIds、promptIdsthinking思维链文本texttool工具调用含完整生命周期name、staterunning/done/error、input/output/display、progress、agentRefs、approvalId、todoIdnotice提示/告警/错误levelerror/warning/info、message、detail工具帧还支持流式进度toolFrameProgressSchemakind 为stdout/stderr/progress/status/custom这是终端工具实时输出能边跑边刷的数据基础。3.5 旁挂实体与元数据除 items 外快照还携带多类旁挂实体schema.tstasks后台任务shell/subagent/tool/other含outputTail任务输出尾部支持 append 操作、状态机running/completed/failed/timed_out/killed/lostinteractions审批/提问approval/question状态含pending/approved/rejected/cancelled/answered/dismissedpending 集合被单独维护attachments附件实体url/file/session_media 三类 sourcetodos待办列表promptsprompt 生命周期running/queued/blocked/completed/failed/abortedmeta目标goal、模式plan/swarm/tower、Agent 状态phase、usage、permission 等。这些实体在 store/agentTranscript.ts 中均以Map或Set维护便于 O(1) 查询getTurn、getTask、getInteraction等访问器一应俱全。4. 幂等操作模型L24.1 14 种操作全集ops/operation.ts 定义了转录状态的唯一合法变更方式——操作对象TranscriptOperation共 14 种操作作用说明reset整体重置以快照替换整个 Agent 状态turn.upsert新建/更新轮次幂等内容相同则跳过step.upsert新建/更新步骤幂等frame.upsert新建/更新帧幂等append追加文本基于偏移量的流式追加支持间隙检测marker.upsert插入标记可选beforeTurn定位taskref.upsert插入任务引用可选beforeTurn定位task.upsert更新任务幂等interaction.upsert更新审批/提问同步维护 pending 集合attachment.upsert更新附件幂等todo.upsert更新待办幂等prompt.upsert更新 prompt幂等meta.merge合并元数据支持 null 语义的字段级覆盖items.remove删除条目级联清理悬挂交互applyOperationops/apply.ts是一个针对操作类型的纯函数分发器返回ApplyResult包含新状态、changed标志与可选的gap信息。4.2 幂等性的三重保障第一重字段级比较。每个 upsert 都先与现有对象做逐字段比较如turnEquals、stepEquals、frameEquals、taskEquals、promptEquals等内容完全一致时返回changed: false不触发任何状态变更与通知。第二重骨架自动补齐。上游操作可能乱序到达例如先收到frame.upsert再收到turn.upsert。applyStepUpsert/applyFrameUpsert会通过skeletonTurn/skeletonStepapply.ts自动生成运行中的骨架 turn/step 并插入正确序位保证无序投递也能收敛。第三重偏移量追加append。流式文本的核心是appendAtOffsetapply.tsexport function appendAtOffset(local, offset, chunk) { if (offset local.length) return { text: local, changed: false, gap: { expected: local.length, got: offset } }; if (local.slice(offset, offset chunk.length) chunk) { return { text: local, changed: false }; // 完全重复直接忽略 } const overlap local.length - offset; if (local.slice(offset) ! chunk.slice(0, overlap)) { return { text: local, changed: false, gap: { expected: local.length, got: offset } }; // 偏移不匹配报 gap } const novel overlap 0 ? chunk.slice(overlap) : chunk; if (novel.length 0) return { text: local, changed: false }; return { text: local.slice(0, offset) chunk, changed: true }; }这个函数保证同一段文本重复追加被忽略断点续传时允许重叠只追加新片段偏移量超前gap时返回expected/got供上层定位。append操作既作用于 text/thinking 帧也作用于任务的outputTailapplyTaskAppend是转录永不丢字、重连不重复的关键。4.3 删除操作的级联语义applyItemsRemoveapply.ts在删除轮次时会扫描其所有 tool 帧的toolCallId找出挂在这些工具调用上的 pending 交互并一并清除——避免工具调用已消失但审批还悬空的脏状态。这是转录一致性中容易忽略、但实现得很完整的细节。5. L1 内存存储与快照窗口store/agentTranscript.ts 的AgentTranscript类以AgentId为粒度持有内部状态对外暴露apply(ops)批量应用操作返回{ accepted, gap }accepted是真正产生变更的操作gap是首个间隙并以TranscriptChangeEvent通知所有监听者agentTranscript.tsonChange(listener)注册变更监听返回可dispose()的句柄snapshot(window?: { tailTurns })导出快照。当指定tailTurns窗口时只保留最近 N 个轮次含其附属条目并置hasMoreOlder true标记还有更早内容agentTranscript.ts——这是先渲染最近 N 轮、再按需回放更早内容的实现基础一组只读访问器getItems、getTurn、getTasks、getInteractions、getAttachments、getTodos、getPrompts、getMeta、listPendingInteractions、hasMoreOlder。服务端通过TranscriptService把这些内存 store 与会话生命周期绑定并维护操作日志journal与seq水位线用于后续的增量补发见第 8、9 节。6. L3 订阅粒度off / turn / block / delta6.1 四级粒度与等级排序granularity/grade.ts 定义了四个订阅等级及其偏序export const GRADE_RANK: ReadonlyRecordTranscriptGrade, number { off: 0, turn: 1, block: 2, delta: 3, };等级含义接收内容off不订阅不接收任何转录事件turn轮次级只收轮次头含 prompt步/帧内容一律不推送block块级追加step.upsert/frame.upsert但append流式增量仍被过滤delta增量级额外接收append可渲染字符级流式输出订阅规格是一个RecordagentId, grade支持*通配默认值gradeFor(spec, agentId)先查精确 agent再回落*都没有则视为offgrade.ts。6.2 升级触发重置needsResetOnTransition(prev, next)grade.ts返回GRADE_RANK[next] GRADE_RANK[prev]——当订阅从低粒度升级到高粒度时说明客户端之前缺失了更细的内容服务端必须下发一次完整快照transcript.reset而非增量这就是升级必重置协议规则的来源。6.3 操作与快照的双重过滤granularity/filterOps.ts 提供两套过滤函数function admits(grade, op) { switch (op.op) { case append: return GRADE_RANK[grade] GRADE_RANK.delta; // 仅 delta 接收 case step.upsert: case frame.upsert: return GRADE_RANK[grade] GRADE_RANK.block; // 仅 block 接收 default: return true; // 其余全量透传 } }redactSnapshotForGrade则负责在快照层面脱敏block以下等级会把每个 turn 的steps置空只保留轮次头——与升级必重置配合保证低粒度订阅者拿到的快照也严格符合其粒度。7. L4 视图注册表框架无关的渲染解析view/registry.ts 的ViewRegistryC是一个泛型注册表C是消费方自定义的渲染器类型如 React 组件或渲染函数。它维护三张映射registerTool(key, renderer)为工具注册渲染器解析时resolveTool优先用帧的view字段、否则用name均转为小写匹配支持fallbackTool兜底registerInput(originKind, renderer)按轮次来源 kinduser、cron等注册输入渲染器resolveInput按origin.kind查找registerMarker(marker, renderer)按标记名注册渲染器。这套设计让转录数据层与 UI 框架彻底解耦服务端只负责推送结构化数据前端无论用 React、Vue 还是原生渲染都只需注册自己的渲染器。8. 分页查询v2 REST 的冷热双路径8.1 分页原语pagination/paginate.ts 的paginateTurns(items, query)实现了轮次级分页先把 items 按 turn 边界切成段splitSegments再依据游标方向选取页before_turn向更早方向翻页默认行为after_turn向更新方向翻页page_size每页轮次数Math.max(1, pageSize)保证至少为 1。两种游标是互斥的这一约束同时体现在 schema 的superRefine校验schema.ts与服务端路由的 zod coercion 中。8.2 服务端路由GET /sessions/{session_id}/transcriptkap-server/src/routes/transcript.ts 实现了该端点逻辑分两条路径热会话live从transcriptService.forSessionLive(session_id)取内存 storeensureAgentHistory等待该 Agent 的历史回填再用paginateTurns分页并返回响应同时携带tasks/interactions/attachments/todos/prompts/meta/agents/pending_interactions/seq其中seq来自服务端水位线供客户端做增量同步锚点冷会话cold会话已退出时调用readColdSnapshot从持久化的 wire 记录重建该 Agent 的转录并合并冷 rosterAgent 名册找不到则返回SESSION_NOT_FOUND。默认page_size为 20transcript.ts合法范围 1–100。8.3 增量补发与用户消息端点同文件还提供两个配套端点GET /sessions/{session_id}/transcript/ops按since_seq返回该 Agent 的操作日志批次seq since_seq旧→新complete: false表示会话已不在线或日志回溯不到该水位调用方必须回退到全量刷新transcript.tsGET /sessions/{session_id}/transcript/user-messages聚合会话内所有开启轮次的输入真实用户文本、user-slash技能命令、cron 提示等可经 origin 区分agent_id缺省时读取所有已注册 Agent附件只携带元数据transcript.ts。这三条路由共同构成全量分页 增量追平 输入聚合的完整读取面。9. v1 WebSocket 订阅通道按连接粒度控制按 0.0.1 变更记录客户端通过 v1 WebSocket 订阅按 Agent 的转录更新且支持按连接per-connection的粒度控制。传输侧的实现位于 transport/ws/v1/wsConnectionV1.ts订阅帧负载用transcriptSubscribeV2PayloadSchemaschema.ts校验结构为{ session_id: string; transcript: RecordagentId, off | turn | block | delta; // 含 * 通配 transcript_since?: RecordagentId, seq; // 断线续传水位 }服务端解析后依据每个 Agent 的粒度等级第 6 节过滤操作流并通过transcript.reset完整快照含has_more_older与seq与transcript.ops增量批次两类事件投递contract/events.tstranscript_since让重连的客户端可以直接从上次的seq追平配合 REST 的/ops端点形成断线 → 增量追平 → 粒度升级重置的闭环。10. 版本演进0.0.1 与 0.0.2 的关键变化10.1 0.0.1数据层的诞生PR #18880.0.1 是包的初始版本奠定全部骨架新增统一、Agent 粒度的转录渲染数据层并由 v2 server 对外服务客户端可通过GET /sessions/{id}/transcript拉取轮次分页转录可通过 v1 WebSocket 按连接订阅各 Agent 的转录更新粒度支持off / turn / block / delta所有转录 wire 类型归属 transcript 包自身即本文第 3 节的全部 schematurn.started事件开始携带轮次的 prompt 文本使实时转录在轮次一开启就能渲染用户输入。10.2 0.0.2子 Agent 轮次携带编排者 promptPR #32890.0.2 针对子 Agent 转录看不到用户原始意图的问题做了修补isDisplayablePromptOrigin现在接受system_trigger/subagent来源——即由主 Agent 编排、通过 subagent run 消息开启的轮次因此实时场景下turn.started事件会包含该轮次的 prompt冷重建场景下开启轮次时的输入文本与附件会被折叠进由 subagent run 消息打开的轮次中保证冷会话回放与实时体验一致其他系统触发来源goal_continuation、stop_hook、loadable-tools仍然不带 prompt避免把内部机制文本污染进用户可见的转录。这一变更的意义在于转录数据层不仅要记录谁说了什么还要在系统触发轮次中保留用户真正的诉求让多 Agent 协同的回放依然围绕用户的意图展开。11. 测试与验证该包自带 vitest 测试覆盖数据层核心行为test/layers.test.ts侧重四层架构存储/操作/粒度/视图的组合行为test/store.test.ts侧重AgentTranscript存储语义包括操作应用、快照窗口与变更通知。在仓库根目录运行pnpm --filter moonshot-ai/transcript test对应 package.json 的vitest run即可执行全部用例pnpm --filter moonshot-ai/transcript typecheck可做类型检查。服务端侧的集成行为则在 kap-server 测试套件如transcript.test.ts、transcriptContract.e2e.test.ts中进一步验证 REST 契约与 e2e 链路。12. 总结moonshot-ai/transcript用四个小而专的层次回答了多 Agent 会话转录如何高效、一致地传输与渲染这一工程问题L1 存储负责状态与快照窗口L2 操作负责幂等收敛与流式追加L3 粒度负责按需降载与升级重置L4 视图负责渲染解耦而seq水位线 操作日志 冷重建则把实时、断线追平与历史回放统一到同一条数据契约之上。对于希望深入 Agent 会话基础设施的读者contract/schema.tswire 契约、ops/apply.ts幂等核心与 kap-server 的 transcript 路由服务端整合是最值得继续阅读的三份文件。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐qwen-code Daemon 共享 UI Transcript 层从 SSE 事件流到多端 Transcript 渲染的统一架构qwen code Daemon 共享 UI Transcript 层从 SSE 事件流到多端 Transcript 渲染的统一架构 导读 qwen code人工智能AI Agent代码智能体工具调用交互助手CLIQwenInvenTree 0.4.6 版本解析模态表单分组机制与创建部件时内联录入制造商/供应商信息InvenTree 0.4.6 版本解析模态表单分组机制与创建部件时内联录入制造商/供应商信息 本篇文章以 InvenTree 开源库存管理系统的 0.4.6AI Agent代码智能体人工智能大模型CLI深度解析 Kimi Code 终端 UI 框架 moonshot-ai/pi-tui从差分渲染到全屏交互的演进之路深度解析 Kimi Code 终端 UI 框架 moonshot ai/pi tui从差分渲染到全屏交互的演进之路 导读 moonshot ai/pi tAI Agent代码智能体人工智能大模型CLI上一篇XCOM 2模组管理器完整上手教程用AML启动器十分钟搞定模组冲突、乱序与崩溃下一篇魔兽世界宏编辑器 GSE 快速上手指南10 分钟做出第一个技能循环创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
