subagent-dispatch

name	subagent-dispatch
description	subagent 派发规范——派发配方（任务文件+纪律母版+产物格式约定+知识卡+块数据的固定组装顺序）、纪律母版（全局纪律单一权威）、任务导航表（任务→任务文件）。约束 subagent 不过度思考、一次性产出（不展示中间态/不重读重写）、只报结构化结果、禁止参考其它工作文件。任何需要拆给 subagent 的任务派发时参考。

subagent 派发模板

背景：subagent 是无状态的

每次派发的 subagent 都是全新上下文，看不到主会话已加载的术语/陷阱词/ASR 修正。因此先验知识必须显式写进 subagent 的 prompt，不能指望"主流程加载过一次就延续"。

派发边界（哪些派 subagent / 哪些主会话）

原则：粗粒度、少打扰——派发是执行机制，是否派由任务性质决定，不需逐步骤报告（考量沿用 PIPELINE_ISOLATION.md §3）。

一律派 subagent（reflow 阶段二补标点/翻译/分句、preprocess §1.1 第一次遍历 + 术语识别）：统一路径，块数由骨架决定，无需报告"用/不用"——直接按派发配方派发。

查证（preprocess §1.2）→ 研究型 agent 分批派发：L3 术语查证待查列表按 30 条/块 拆 term_pending_<i>.md 后逐块派 term-researcher（研究型 agent，tools 含 read/search/edit + wiki MCP）——非任务处理 agent：允许推理/判断/多步查证，但页面原文只进一次性上下文、只返回每词一行压缩总结；任务文件即完整 prompt（term-scan/task-term-resolve.md，规则静态内联），派发时「任务文件 + 该块 term_pending_<i>.md」双引用，不走渲染脚本、不追加执行型纪律母版（研究型纪律由 agent 系统提示词承载）。

不派 subagent（主会话）：需用户交互（术语确认 §1.3、审核循环 阶段二½）——能力约束；需全貌的跨切面决策（如 r03 分句对应、回填判断）。

translate（2026-08-24 已重构）：阶段二合并断句 / 翻译一律派 subagent（与 reflow 对齐，对齐 translate-redstone 阶段二）——块数由分块骨架决定，无需报告"用/不用"，直接按派发配方派发。

主会话读写最小化（token 纪律）

作用域：本节仅约束 translate / reflow 派发-校验阶段的主会话调度行为（两工作流经本 skill 派发时加载）；maintain-knowledge / wiki-tools 等日常维护工作流不适用——那些工作流主会话的正常读写不受本节限制。 背景：主会话历史只增不减、每轮都付——无论多小的读/写/验证动作都进入对话历史（流程越长越明显）。凡能由脚本/subagent 完成的读、写、验证一律下沉，主会话只保留「路由 + 决策必需」动作。

• 读：数据文件读取 → 渲染脚本/校验脚本/subagent（主会话不 read 块数据、不读 wiki 页面全文）；大内容（Wiki 页面/长产物）→ 研究型 agent 读取、只返回压缩总结；校验告警已带「文件:行号 + 上下文」→ 直接打包进 task-fix 清单派发（B 档），主会话不 read 定位、不自行定点修（A 档已废弃，见「定点修正」）
• 写：产物全部由 subagent（create_file 直接写盘）或脚本（--out）产出；主会话不 create_file 中间产物，只发命令触发；主会话唯一写 = 需用户确认的交付物（02_terms、_output/）+ 小量路由产物（如 term_pending.md 全量待查列表 + 分块 term_pending_<i>.md）
• 验证：存在性验证（收信号即验）用 list_dir 一次校验，不 read_file；行数/非空由脚本统计（text_merge 报告 / (Get-Content).Count），主会话不数
• 例外（决策必需，允许）：用户交互展示（§1.3 确认表、审核对象）——校验告警定位后的定点编辑不再例外，一律下放 B 档 task-fix（主会话零定点编辑，见「定点修正」）

派发前主 Agent 准备

1. 生成/读取该视频的知识卡（02_terms.md：已确认术语 + 陷阱词命中项 + ASR 修正映射）
2. 用 scripts/text_chunk.py 分块（见 redstone-conventions#长视频分块；SRT 与非 SRT 统一，超阈值判定先跑 context_estimate.py）
3. 清理旧产物（重跑/重试前必做，mv 不删）：目标结果文件若已存在（校验打回重跑、整轮重跑等场景），用 Move-Item 移到同目录的 <结果目录>_bak_<时间戳>/（如 reflow/r01_results_bak_20260816_1530/，时间戳取当前时刻），只移动、不删除——subagent 纪律 #8 禁删，主会话亦用 mv 规避删除；示例 Get-ChildItem reflow/r01_results/chunk_*.txt | Move-Item -Destination "reflow/r01_results_bak_$(Get-Date -Format yyyyMMdd_HHmm)/" -Force。清理是写盘前提：create_file 只新建、遇已存在即报错；结果文件多为超长单行（read_file 截断、走"读后改"必死循环）——故必须保证 subagent 写盘时目标路径不存在。备份带时间戳即历史归档（每轮独立、不覆盖、可审计可恢复），不删除、无需清退
4. 跑渲染脚本生成每块 prompt：python scripts/render_subagent_prompt.py <task> --video <视频工作目录> [--chunk <k> | --all] [--prior-file <文件>]（渲染逻辑与任务映射见「派发配方」）——完整 prompt 落盘 _work/<视频名>/prompts/<task>-chunk_<k>.txt，不经主会话（完整 prompt 文本不进主会话历史，主会话只发短命令）；数据文件只验证、不读取：对引用的数据文件（块数据）用 list_dir 列目标目录验证存在（返回子项中命中 = 存在；不用 file_search——_work/ 被 .gitignore 忽略，glob 搜不到；块数据为主会话刚生成，非空必然），不 read_file 读取内容（块内容不入主会话，省上下文）；块数据引用路径由渲染脚本按任务注入 ## 本块数据
5. 渲染即存档：渲染脚本已把完整 prompt 落盘 prompts/（先存后发，供复盘回查），无需另行 create_file 落盘；派发时按「派发引用 prompt」只给引用路径（完整 prompt 内容不再进主会话）

派发配方

每个可派发任务 = 一份任务 prompt 文件（放所属 skill 目录，如 reflow-redstone/task-punctuate），内容是面向 subagent 的现成任务指令（目标 + 行为规则 + 输出契约）。完整 prompt 由渲染脚本 scripts/render_subagent_prompt.py 会话外组装落盘（_work/<视频名>/prompts/<task>-chunk_<k>.txt）：读模板正文（<k>/<视频名> 占位替换）+ 逐字追加纪律母版（_discipline.md 单一权威）+ 注入产物格式约定 + 注入先验知识（术语直读 02_terms.md / humanizer-inject / 空隙断句标记）+ 生成块数据引用——完整 prompt 文本不进主会话历史，主 agent 只发渲染命令 + 派发引用。任务特有规则直接内联在任务文件（不建独立规则文件）；通用纪律由 _discipline.md 单一权威；产物格式约定（格式查找路径）由渲染脚本注入（见下）。

渲染脚本覆盖范围：reflow 阶段二由 scripts/render_subagent_prompt.py 接入 task-punctuate / task-translate / task-split / task-match；translate 阶段二由同一脚本接入 task-merge / task-humanize / task-translate（同名任务多 skill：派发时 --skill translate-redstone 取 translate 版，默认 reflow 版）——派发只需发渲染命令 + 引用。preprocess 阶段一由独立脚本 scripts/render_preprocess_prompt.py 接入 task-term-recognition / task-en-preprocess（块级执行型任务）。§1.2 查证（task-term-resolve）不走渲染脚本——分批研究型任务（30 条/块）、规则静态内联于任务文件，派发时「任务文件 + 该块 term_pending_.md」双引用（见「派发边界」）。task-fix（reflow / translate 版）/ task-summary 未接入——错误清单 / 摘要为动态内容不走块级渲染，仍按旧方式：主 agent 读模板 + 手工组装 + 落盘存档（内容不大时也可直接内联派发）。

执行型纪律与模型：reflow 类执行任务派发 reflow-worker（执行型 agent），使用无思考模型——具体做法（派发入口 / agent 定义 / 模型名 / adapt）按你自己的编辑器执行，见 EDITOR_COMPAT（模型名读 configs/subagent_model.yaml 的 execution_model）。纪律母版 #0 与 agent 系统提示词同源，由渲染脚本随 prompt 整体注入（内联兜底 + 任务特定纪律 + 兜底）。研究型任务（§1.2 查证 term-researcher）不同：用主模型（非 execution_model）、不追加执行型纪律母版——见「派发边界」。

组装原则（内联 vs 引用，单一权威）：默认全部内联，仅数据文件例外——任务规则、纪律母版、## 先验知识（术语表/陷阱词/ASR 修正/humanizer 注入等）等一切规则与知识内容由渲染脚本直接内联进 prompt 文件；唯一例外 = 块数据（## 本块数据 单独注明数据文件路径，subagent 按引用读取）；subagent 侧只读边界见纪律母版 #8。

（以下各项均由渲染脚本 render_subagent_prompt.py 注入产出）
subagent prompt = 任务文件内容（含任务特有规则）
                + 纪律母版（_discipline.md 整体追加；通用纪律单一权威）
                + 产物格式约定（查找路径：PRODUCT_FORMATS 对应节，subagent 唯一允许的外部读取）
                + 知识卡（术语/陷阱词/ASR 修正映射；脚本直读 02_terms.md 等）
                + 块数据（## 本块数据 单独注明数据文件路径——唯一引用例外，其余全部内联，见「组装原则」）
                + 写盘/报告约定（输出路径 + 「已写入 <文件名>」；**不数行数**——行数/非空由脚本统计校验，见「合并」）

产物格式约定：输出文件格式/折行/标记的权威在 docs/PRODUCT_FORMATS.md 对应节（任务文件已内联关键规则，细节以该节为准）；渲染脚本按任务把查找路径注入 prompt（如 docs/PRODUCT_FORMATS.md 的 r01_results/chunk_<k>.txt（补标点块） 节），subagent 按需查阅——这是唯一允许的外部读取；内联/引用分工见「组装原则」与纪律母版 #8。无外部格式权威的任务（如 task-summary）此项省略。 ## 先验知识 内部顺序（渲染脚本按任务配置注入，高优先级靠前、紧贴对应任务规则，不得打乱）：如 task-punctuate 的空隙断句标记先于其他、task-translate 的 humanizer 注入版先于术语表；任务文件底部未注明的按「纪律 → 格式 → 知识 → 数据」序。需主会话判断的额外先验（块边界情况、前文摘要等）用 --prior-file 传文件追加到 ## 先验知识。

提示词渲染与存档（render_subagent_prompt.py 会话外落盘）

完整 prompt 由渲染脚本会话外组装落盘（_work/<视频名>/prompts/<task>-chunk_<k>.txt）——不经主会话，完整 prompt 文本不进主会话历史；存档既是复盘材料（会话会丢、不可重放），也是派发时 subagent 引用的唯一任务指令。

• 位置：_work/<视频名>/prompts/（与 reflow/ 等产物同级）；命名 <任务>-chunk_<k>.txt（如 task-translate-chunk_002.txt、task-split-chunk_003.txt）；不跨任务合并、不覆盖
• = 实际发给 subagent 的（任务文件内容 + 纪律母版 + 产物格式约定 + 先验知识 + 块数据引用路径 + 写盘/报告约定；复盘按路径读对应块文件）