RFC-0001: Storyline Format¶

摘要¶

Storyline 是 pChronicle 的枢纽 interchange：以 Harbor ATIF-v1.7 的 Trajectory / Step 折叠语义为基准，加上少量 hub 便利字段（短名 wire、性能顶栏、可选子会话外链）。

外围格式（agenticmd / openai_msg / atif / actf）只与 Storyline 互转。 Storyline 是存储与查询管线使用的轨迹模型，可直接写入三表 Lance。

设计原则¶

1. ATIF-first：根对象 ≈ Trajectory，turns[] ≈ steps[]；能 1:1 的字段保持同义。
2. Hub-only：A→B MUST 经 storyline。
3. 来源可追溯：保留 Source 与 Snapshot 身份，不推断输入中缺失的执行记录。

相对 ATIF 仅保留这些增量：

格式映射的权威边界¶

本 RFC 只定义 Storyline wire schema。外围格式到 Storyline 的字段映射由对应格式 RFC 负责，设计文档和实现说明不得另行维护一份竞争性映射表：

• RFC-0004 § ACTF → Storyline JSON Pointer 映射
• RFC-0008 § ATIF → Storyline JSON Pointer 映射
• RFC-0009 § OpenAI Messages → Storyline JSON Pointer 映射

同源恢复使用 unknown_fields 保留 Storyline 不认识的源字段。跨外围格式转换只保证输出 目标格式能够表达的 Storyline 语义；不能由目标格式表达的外来 residual 使用受控 _storyline envelope 携带。

Wire schema¶

编码：UTF-8 JSON。根对象 MUST 包含 schema_version: "storyline/v1"、session、 agent 和 turns。所有拥有字段的对象都拒绝未声明 key；扩展只能进入显式 extra 或受限 unknown_fields。

Wire 短名¶

JSON 序列化和解码都使用短名；长名仅用于说明字段概念，不作为兼容输入。

保持全名：agent / task / env / llm / result / response / prompt / started_at / finished_at / final_metrics / continued_trajectory_ref / tool_calls / observation / metrics / extra / meta / latency_ms / ttft_ms / duration_ms，以及 id / name / notes / kind / turns / parent。tool_calls[].kind 与 turns[].kind 同名不同槽。

根对象¶

origin¶

agent¶

parent（可选外链）¶

对应 ATIF 内嵌 subagent_trajectories 的轻量替代；不是必填叙事层。

完整子轨迹 SHOULD 作独立 storyline.json；导出单文件 ATIF 时转换器 MAY 再内嵌。

turns[]¶

task.env 与 turns[].env 形状相同：name / endpoint / id / event_type / request_id 为可选字符串；state 为开放 JSON object。重建某 turn 的有效 env 时，先取 /task/env 再浅合并该 turn 的 env（state 也浅合并）。落盘保持未合并形态。

task.llm 目前只有可选正整数 k。task.result 承载通用评测：correct / final_answer / ground_truth / status / score / max_score / error / artifacts。ACTF 私货（task_correct、category、attempts_tried、solved_at、retry_count、retry_counts）不是强类型 hub 字段；读写旧 Storyline JSON 时这些键进入 task.result extra（与 typed 字段同级 flatten），不得静默丢弃。RFC-0004 的 JSON Pointer 不变，ACTF 转换层从 extra 还原。空字符串、空 object、null 视为缺省。

prompt 与 turns[].prompt 形状相同：可选字符串 system / user。有效 prompt 取该 turn 的 /prompt，缺省则用文档 /prompt；turn 一旦出现 /prompt 就整段替换，缺省键视为空字符串，不从文档继承。copied == true 的 turn 不得写 prompt。文档 /prompt 不能是空对象。turn 上唯一允许的双空对象是显式 {"system":"","user":""}，用来清空文档基线。

tool_calls[]¶

unknown_fields 与 unknown_key_counts¶

unknown_fields 只保存外围格式中无法映射到 Storyline 已知字段的值：

/unknown_fields/sources/{source}/source_document_id = string
/unknown_fields/sources/{source}/fields/{E(P)}       = any

P 是源文档中的完整 RFC 6901 JSON Pointer；E(P) 是把整个 P 作为 fields 对象 key 后执行一次 RFC 6901 token 转义。unknown_key_counts 按 source 和规范化 pointer 记录出现次数，必须能由 unknown_fields 确定性重算。已知业务扩展写入 extra，文档级元数据写入 meta，不得混入 unknown_fields。

校验（Normative）¶

MUST 拒绝：缺失或无法识别的 schema_version；空 session / 空 agent.id；重复的 turns[].id；全局重复或空的 tool_calls[].tcid；空 fn；既非 RFC3339 字符串、也非 可精确表示为纳秒的 Unix epoch 秒数的 ts；未声明的 拥有字段；不匹配的 unknown_key_counts。

turns 数组顺序具有语义，MUST 原样保留；id 只用于身份和关联，不用于排序。 导出 ATIF 时 step_id = turns[].id；未知 extra 透传。

枢纽 API¶

into_storyline(format, input)  → StorylineDocument
from_storyline(format, story)  → serialized
convert(from, to, input)       ≡ from_storyline(to, into_storyline(from, input))

文件与探测¶

实现：into_storyline / from_storyline / convert。

History¶