Chronoclip

从直播转写中自动提取高光片段的工具。输入是转写文本（turns.v1.jsonl），输出是结构化的高光片段（highlights.v1.json）+ 人可读的摘要（summary.md）。

架构

三阶段并行流水线，基于 pi-coding-agent 框架：

Phase 1: 并行 S1 粗筛
  turns.v1.jsonl → build_turn_chunks → 6 个 chunk
  → 6 个独立 agent session 并行打分 → merge_chunk_candidates
  → hook_candidates.json（~100 条候选）

Phase 2: 主 session S2 细筛
  hook_candidates.json → LLM 按 finalHookScore 排序复审
  → write_stage_artifact 自动间距过滤（<90s 丢低分）
  → locked_hooks.json（12-15 条钩子）

Phase 3: 并行 S3 扩窗
  locked_hooks.json → compute_clip_windows（~400s 窗口）
  → N 个独立 agent session 并行裁剪 → 合并去重
  → merge_clip_drafts → export_highlights
  → highlights.v1.json + summary.md

核心原则

• LLM 只做语义判断（哪些 turn 有价值、哪些跑题了）
• 机械工作交给工具（时长校验、间距过滤、offset 计算、文件合并）
• turnId 是全链路唯一锚点（hookSentence 不做子串校验）

目录结构

inputs/turns/       标准输入 *.turns.v1.jsonl
inputs/raw/         可选原始转写 txt
outputs/highlights/ 最终输出 *.highlights.v1.json + *.summary.md
artifacts/runs/     中间阶段产物
src/agent/          流水线编排（run-highlight-agent, run-parallel-s1/s3）
src/tools/          pipeline 工具（write-stage-artifact, compute-clip-windows 等）
src/domain/         领域模型（types, schemas, validators, scoring, policies）
.pi/skills/         LLM skill 定义（hook-recall, hook-refine, highlight-funnel）

环境

npm install

ffmpeg（视频切片必需）：

winget install ffmpeg

安装后重启终端让 PATH 生效。程序也会自动检测 WinGet 安装路径。

在 ~/.pi/agent/models.json 和 ~/.pi/agent/auth.json 中配置模型。兼容 OpenAI 协议的模型都可以接（包括 DeepSeek）。

运行

Debug Workbench（推荐）

npm run dev

浏览器打开 http://localhost:3344，选择模型和 API key，上传转写文件即可。

CLI

npm run highlight:run -- --turns inputs/turns/demo.turns.v1.jsonl --out outputs/highlights/demo.highlights.v1.json --artifacts artifacts/runs/demo

测试

npm run check   # TypeScript 类型检查
npm run test    # Vitest 测试套件

工具清单

工具	作用
parse_transcript	原始 txt → turns.v1.jsonl
build_turn_chunks	长转写切成重叠 chunk
extract_turn_window	按 turnId 抽取局部上下文
write_stage_artifact	写入 + 校验文本层产物（含时长/间距/guest 范围校验）
compute_clip_windows	为每个 hook 预计算 ~400s 上下文窗口
merge_chunk_candidates	合并多个 chunk 的粗筛结果
merge_clip_drafts	按 Jaccard 相似度合并重叠片段（含时长保护）
export_highlights	拼装最终 highlights.v1.json + summary.md