| name | zxf-portable |
| description | 张雪峰转录结构化 skill（通用版 runner 薄壳，**无需 API key**）。当用户说"分类 N 份"、"跑 N 份对话片段"、"跑 N 份独白"、"跑 BVxxx"、"查进度"、或提及 zxftrans/phase_dialog/phase_monolog 时使用。runner 不调 LLM，由主 agent 用自身 AI 能力按工作包产出 JSON。 |
zxf-portable（Claude Code 适配，Mode B 默认）
定位
runner 只做工作包分发 + 校验 + 索引管理。真正"读原文、理解、产 JSON"由主 agent 用 Claude Code 内置 AI 完成——不需要 ANTHROPIC_API_KEY。
前置
第一次触发先跑：
python -m zxf_runner precheck
触发词 → 命令
| 用户说 | 执行 |
|---|
| "分类 N 份" | python -m zxf_runner classify --limit N --strategy keyword-first |
| "跑 N 份对话片段" | Mode B 对话流程（见下） |
| "跑 BVxxx" | Mode B 单 BV |
| "跑 N 份独白" | Mode B 独白流程（见下） |
| "切 BVxxx" / "分片 BVxxx" | Mode B 整场切片流程（见下） |
| "查切片计划 BVxxx" | python -m zxf_runner segment-plan --bv BVxxx |
| "回填" | python -m zxf_runner reconcile |
| "查进度" | python -m zxf_runner report |
N 默认：分类 20、结构化 5。
Mode B 对话全流程（主 agent 按步执行）
Step 1：取粗修工作包
python -m zxf_runner prepare-dialog-draft --limit N
stdout 返回 {count, instructions, packets: [{bv, system_prompt, user_content, target_path}, ...]}。
Step 2：对每个 packet 产粗修 JSON
主 agent 自己做（不派 subagent，顺序处理一份一份）：
- 读取
packet.system_prompt（当 system 理解）和 packet.user_content（里面含原文）
- 在自己的思考里按 system prompt 产出完整 JSON
- 用 Write 工具把 JSON 写到
packet.target_path（覆盖）
- Bash：
python -m zxf_runner check --path <target_path>
- 校验失败 → 看 errors，改 JSON 重写，再 check；连续 2 次失败则走 needs_review：
python -m zxf_runner finalize --bv <bv> --status needs_review --reason <errors 摘要>
Step 3：取精修工作包
粗修全过后：
python -m zxf_runner prepare-dialog-refine --bvs BV1,BV2,... --refine-model-name claude-code
返回一个 packet：{system_prompt, user_content, targets: [{bv, target_path}, ...]}。user_content 已经把 N 份 draft 按顺序拼好。
Step 4：产精修 JSON
主 agent 按 system_prompt 一次性精修 N 份：
- 先给用户输出问题清单（≤500 字纯文本，摘要即可）
- 为每份产出精修 JSON，Write 到对应
targets[i].target_path
- 每份里加
refined_by: "claude-code" 和 refine_notes
- 逐份
check
- 全过 → 逐份
finalize --bv <bv> --status done
Step 5：汇报
跑 python -m zxf_runner report，告诉用户：
本批：done {n} | needs_review {m}
累计：phase_dialog {D} / phase_monolog {M}（MVP 150）
剩余：对话片段 pending {p1} | 独白 pending {p2}
Mode B 独白流程（更简单）
python -m zxf_runner prepare-monolog --limit N
对每个 packet：产 JSON → Write → check → finalize --status done。无精修阶段。
Mode B 整场切片流程（把 segment_type=整场 切成 N 份片段）
适用场景：用户说"切 BVxxx"、"分片 BVxxx"，或想把 index 里 processed=skipped / segment_type=整场 的长文件盘活。
Step 1：看规则粗切报告
python -m zxf_runner segment-plan --bv BVxxx
返回 {filter: {...}, candidates: [...]}。噪声比率 > 50% 或候选段 < 2 时提醒用户可能是纯带货场，考虑标 skipped 不再切。
Step 2：取精修工作包
python -m zxf_runner prepare-segment-refine --bv BVxxx
返回 {system_prompt, user_content, target_path}。user_content 包含原文 + noise_segments + candidates。
Step 3：产最终切片 plan
主 agent 按 system_prompt 产出 plan JSON（含 segments: [{title, start, end, content_type_hint, rationale}]），Write 到 target_path。
Step 4：落盘
python -m zxf_runner finalize-segment --bv BVxxx --plan-json <target_path>
runner 自动：按 offset 切原文 → 写 N 个新 txt（命名 {date}_{title}_{BV}S{NN}.txt）到源目录 → classify 新片段入 index → 原整场标 processed=segmented。
Step 5：下游
新片段进 pending 队列，可立刻跑 prepare-dialog-draft / prepare-monolog。
注意：segment.py 的带货词表保守；若明显漏过带货，在 plan 的 dropped 字段补，不要强塞进 segments。
关键约束
- 一次对话处理 N 份，每份 1-2 次 LLM 思考 + 精修 1 次，context 会膨胀。N > 5 建议分多次用户指令。
- Mode B runner 从不调 LLM —— 看到 "API key" 相关报错就是用错了命令（可能误调
structure）。
finalize --status done 只在精修 + check 都通过后调。粗修通过不等于完成。- 不要用
structure 子命令（那是 Mode A，需 API key）。
汇报模板
已完成：{n}/{N} 份（{content_type}）
{若有失败} needs_review：{bv1, bv2}（原因：{reason}）
累计产品（phase_dialog {D} / phase_monolog {M}，MVP 150）
索引剩余：对话 {p1} | 独白 {p2}
边界
- 不改 prompts / config（让用户手改
portable/prompts/ 或 portable/config/）
- 不自动重跑 needs_review
- 不做分类判定（那是 runner 里
classify 的启发式逻辑，runner 自己能跑）
