摘要

主线分 6 段：启动校验 → prefill → HiSparse staging → decode batch 重建 → MTP draft/verify → accepted KV finalize。

1. 启动阶段：确认组合合法，建 HiSparse 管理器

ServerArgs.validate
→ ModelRunnerKVCacheMixin.init_memory_pool
→ ModelRunner init path
→ HiSparseCoordinator.__init__
→ ModelRunner.init_attention_backend

函数	作用
`ServerArgs.validate`	拒绝非法配置：draft tokens 不能超过 extra page 容量；`topk > 1 && page_size > 1` 直接报错。
`init_memory_pool`	普通 KV allocator 被包成 `HiSparseTokenToKVPoolAllocator`，形成 logical loc 与 physical HiSparse slot 的双层映射。
`HiSparseCoordinator.__init__`	建 HiSparse 全局状态：device buffer、host pool、LRU slots、token metadata、异步 stream。
`init_attention_backend`	DSA attention backend 拿到 `hisparse_coordinator`，后续 attention 可走 HiSparse 查 KV。

核心状态：

req_to_device_buffer              req → physical HiSparse slots
req_device_buffer_tokens          slot 当前代表哪个 token position
req_device_buffer_token_locs      slot → physical KV loc
req_to_host_pool                  token position → host KV loc
full_to_hisparse_device_mapping   logical loc → physical HiSparse slot

2. prefill 阶段：target 先跑，再准备 draft 初始状态

Scheduler.run_batch
→ EAGLEWorkerV2.forward_batch_generation
→ target_worker.forward_batch_generation
→ EagleDraftWorker._draft_extend_for_prefill

函数	作用
`EAGLEWorkerV2.forward_batch_generation`	如果 batch 是 extend/prefill，就先跑 target model。
`target_worker.forward_batch_generation`	正常 target prefill，产生首 token、hidden states、KV。
`_draft_extend_for_prefill`	用 target hidden states + next token 跑 draft model，填 draft KV，并产出下一轮 `EagleDraftInput`。

EagleDraftInput 里保存：

bonus_tokens    target prefill 产出的 token
hidden_states   给 draft model 下一步用
topk_p/index    draft 下一轮起点

3. HiSparse staging：prefill KV 先搬到 host，再进入 decode

SchedulerBatchResultProcessor.process_batch_result_prefill
→ _stash_hisparse_spec_info
→ HiSparseCoordinator.admit_request_into_staging
→ HiSparseCoordinator.collect_ready_reqs
→ Scheduler._build_hisparse_decode_batch

函数	作用
`process_batch_result_prefill`	prefill 结束后，把 req 从 prefill 阶段转入 decode/staging。
`_stash_hisparse_spec_info`	把 batch 级 spec state 切成 per-req state，挂到 `req.hisparse_spec_info`。
`admit_request_into_staging`	把 prefill 期间在 GPU 上的 KV 异步 backup 到 host pool。
`collect_ready_reqs`	轮询 backup event，完成后给 req 分配 HiSparse device buffer。
`_build_hisparse_decode_batch`	staging 完成后重新拼 decode batch，并把 per-req spec state merge 回 batch。

为什么要 stash？

HiSparse prefill→decode 不是普通 last_batch merge。