用途:ax:narrate 把智能体对当前会话的记忆转成可审阅的叙述工件,重点记录 PR 差异无法呈现的内容,如用户纠正、废弃尝试与恢复过程。工件需符合 apps/studio/src/routes/narration-types.ts 中的 SessionNarration 结构,并在 ax studio 中渲染。
主要能力:先确定会话,优先用 ax sessions here --days=1 --json 选取当前会话短 id;若 ax 不可用或会话尚未入库,则用 <repo>-<YYYYMMDD-HHmm> 生成 slug,并在 meta 中说明轮次序号为尽力估算。可用 ax sessions show <id> --json 获取真实轮次序号。随后从自身上下文重建故事:原始意图、前后状态、每次用户纠正、有影响的工具失败、被放弃的尝试。
使用方式:选择 3-7 个停靠点,按阅读流排序,入口点优先、因先于果、定义先于使用、验证最后,琐碎事项合并或省略。每个停靠点写 title、一句话 gist、2-4 句 detail、transition 及非空 anchors。锚点类型包括 file_hunk、code_state、turn、user_direction、correction、tool_failure、term。file_hunk 必须逐字复制真实改动片段,保持 5-15 行,纯插入 old_text 为 null,纯删除 new_text 为 null,不可两者皆空。每次用户纠正需 correction 锚点并给出具体结果;每次有影响的工具失败需 tool_failure 锚点并说明恢复方式。code_state 用于演进设计,保持同一 artifact id 与共享行逐字一致。
输出:写入 .ax/narrations/<session-id>.json,顶层包含 schema_version、kind、meta、title、intent、before、after、stops。完成后自检停靠点数量、锚点非空、gist 单句、纠正有结果、失败有恢复,并告知用户文件位置与两行摘要,不要把完整 JSON 贴进聊天。
限制:资料未提供安装命令、收费方式、支持平台或效果保证;轮次序号不得编造,无真实序号时需在 detail 中说明为估算。