用途:确定归档范围并更新“last record”状态,使“自上次记录以来”的含义明确、分支安全且易于更新;同时通过记录指针旁存储基线锚点来支持变更检测工作流。
主要能力:定义规范指针文件(全局回退指针 .archive/pointers/HEAD.yaml,可选按分支指针 .archive/pointers/branches/<branch_key>.yaml);分支键编码规则为 / 替换为 __、空格替换为 -、其余不在 [A-Za-z0-9._-] 的字符替换为 _,并始终在指针文件的 git.branch 字段保存原始分支名。指针 YAML 必填 last_record(记录 ID 字符串),推荐至少一个基线锚点:git(branch、head 提交 sha)或 opencode(session_id、message_id)。
使用方式:读取时先查找分支指针,不存在则回退 HEAD.yaml,都没有则视为“缺失”(归档未初始化);写入时先确定单个新头记录 ID,仅在记录文件校验通过且 graph.dot 派生成功后更新分支指针与全局指针的 last_record,并刷新可用基线锚点。初始化时创建 parents 为空、type 为 Design(或 Decide)、标题为“Archive initialized”的根记录,写入指针后派生 graph.dot。新记录默认使用 parents: [<last_record>],合并可用多父级。
变更判定:git 场景下 git.head 等于当前 HEAD 视为无变化,否则记录 git.range 为“<baseline_head>..<current_head>”;仅有 opencode 基线时优先使用插件提供的差异而非猜测;无基线锚点时视为未知并询问调用方范围。重复调用且无变化时优先输出 Briefing 不写入,仅当调用方明确要求时才写简短检查点 Design 记录。
限制:资料未提供具体插件的实现细节、支持平台或版本要求。