角色重构与现状分析 | 阿的宝藏之地

1. 当前角色

当前默认角色集是：

角色	性质	主要职责
`lead`	structured_write	项目总控，ingest、长期上下文沉淀、后处理、打包
`explorer`	read_only	只读探索论文、笔记、素材，提取事实、公式、风险
`planner`	read_only	规划叙事结构、segment 优先级、媒介路线、审核点
`coordinator`	structured_write	生成旁白脚本、分镜、worker handoff
`html_worker`	structured_write	生成 HTML 科普片段，偏引子、桥接、弱科普
`manim_worker`	structured_write	生成/修复 Manim 数学动画，偏公式核心与推导
`svg_worker`	structured_write	生成 SVG 关系图、辅助动效
`reviewer`	verify_only	只出审核草案，不放行
`human_reviewer`	verify_only	人工审核关卡，负责最终 approve / return

2. 当前主调用链

现在的主链路大致是：

Manifest / 输入材料
  ↓
lead@INGEST
  ↓
explorer@SUMMARIZE
  ↓
lead@SUMMARIZE
  ↓
planner@PLAN
  ↓
coordinator@PLAN
  ↓
html_worker / manim_worker / svg_worker @DISPATCH
  ↓
reviewer@REVIEW
  ↓
human_reviewer@REVIEW
  ↓ approve
lead@POST_PRODUCE
  ↓
lead@PACKAGE
  ↓
DONE

也就是说，角色之间不是自由聊天，而是通过 ProjectPlan + ContextRecord + ExecutionTask + EventLog 交换信息。executor.py 里的 run_to_review 仍然是主链路的大调度函数：它顺序调用 explorer、lead、planner、coordinator，然后再进入 worker 渲染与 reviewer 草案。

所以当前架构的本质是：

中心调度器 executor
  ├─ 调 LLM：按角色生成 JSON / 文本 / 代码
  ├─ 写上下文：runtime/projects + runtime/sessions
  ├─ 推任务状态：task_board
  ├─ 记事件：events.jsonl
  └─ 调 worker adapter：HTML / SVG / Manim 本地落盘和渲染

3.现状分析

第一，run_to_review 仍然太大。虽然加了 role_executor.py，但主链路还是中心大函数调度。它能跑通 demo，但后期调试会痛苦。正确方向是把每个阶段拆成可独立运行的 stage runner。

第二，role_executor.py 里疑似有调用 bug。llm_client.generate_text_for_role 和 generate_json_for_role 是 keyword-only 参数形式，但 role_executor.py 里用 positional 方式传了 self._cfg, self.role_id。这会导致 role-exec 独立执行时很可能直接 TypeError。这个要优先修。

第三，后处理拼接逻辑存在媒介择一问题。虽然 HTML 和 Manim 都能正常渲染，但 post_produce.py 在收集 segment 视频时更像是“每个 segment 优先选择一种媒介”，而不是“按分镜顺序联合收集 HTML / Manim / SVG 多个片段”。这会导致最终成片只拼接 HTML 或 Manim 中的一类产物，无法形成“HTML 负责引子/桥接、Manim 负责公式核心”的联合成片效果。这个问题要优先修，因为它直接影响最终视频是否符合多媒介编排目标。

第四，planner/coordinator 的输出 schema 与 normalize 函数之间可能不完全匹配。例如新版 prompt 要求 semantic_type、cognitive_goal、why_this_worker，但 _normalize_segment_priorities 目前主要保留 objective / primary_worker_path / estimated_seconds，可能会丢掉关键字段。这会削弱你刚强化的 prompt。

第五，前端/文档存在版本不同步。README 说 /live 已接 backend，前端文档还说尚未真正连通。这个不影响运行，但会影响协作判断。

痛点比较详细，直接利用codex进行修复即可。

杂谈目录

1. 当前角色

2. 当前主调用链

3.现状分析