feat: add linear-state block manager and prefix cache (3/n).

[yingxudeng]

Description

Related Issues

Change Type

• Bug fix
• New feature
• Performance improvement
• Refactor
• Documentation
• Test
• Build or CI

Pull Request Checklist

Thank you for contributing to xLLM. Before requesting review, please make sure the following items are complete.

PR Title and Commit Messages

• The PR title and each commit message follow the xLLM commit format: <type>: <subject>.

Allowed types: feat, bugfix, docs, test, refactor, chore, style, revert, perf, model, build, release.
The subject should use clear English, start with a verb, include at least 4 words, and end with ..

Pre-commit Checks

• I have installed pre-commit by running pip install pre-commit or an equivalent command.
• I have installed the hooks with pre-commit install.
• I have run pre-commit run --all-files and fixed any reported issues.

If you are unsure how to set up pre-commit, see the pre-commit documentation.

Self Review

• I have self-reviewed the code according to .agents/skills/code-review/references/custom-code-style.md, especially code written or assisted by AI.
• I have rebased this PR onto the latest main branch.

Build and Test Coverage

• Tests have been added or updated as needed.
• CUDA: python setup.py build test has passed on a CUDA machine.
• NPU: python setup.py build test has passed on an NPU machine.
• MLU: python setup.py build test has passed on an MLU machine.

Reviewer Notes

pr说明如下：
https://yingxudeng.github.io/xllm-notes/reports/qwen35-linear-prefix-cache-pr1839/

[gemini-code-assist]

Code Review

This pull request introduces support for linear-state (Qwen3.5 GDN) live slots by adding the LINEAR block type and implementing corresponding state management methods in Sequence and KVCacheState. It also adds a MOVE_ONLY macro in macros.h. The feedback suggests using emplace_back instead of push_back when adding a slot to the block vector in sequence.h to avoid unnecessary copies, in accordance with the repository style guide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[yingxudeng]

[yingxudeng]

[yingxudeng]

pr说明如下：
https://yingxudeng.github.io/xllm-notes/reports/qwen35-linear-prefix-cache-pr1839/

[yingxudeng]

[Kang-Meng]

LGTM

[pjgao]

在最新 main（包含该 PR）验证 Qwen3.5 混合线性注意力模型时，发现一个 engine wiring 遗漏，会导致服务在 KV Cache 初始化阶段稳定退出。

现象

Check failed: options.linear_state_num_slots() > 0 (0 vs. 0)
linear_state_num_slots must be set when linear state is enabled

原因

当前链路中：

1. estimate_kv_cache_capacity() 已计算 num_linear_state_blocks。例如 max_concurrent_requests=32 时得到 34 个 slot，并据此预留 linear-state 内存、创建 Conv/SSM cache shape。
2. LLMEngine::allocate_kv_cache() 和 VLMEngine::allocate_kv_cache() 会对混合线性注意力模型设置 enable_linear_state=true。
3. 但两处创建 BlockManagerPool::Options 时都没有传入 linear_state_num_slots，所以默认值仍为 0。
4. 本 PR 新增的 build_composite_leaves() 在启用 LINEAR leaf 时要求 slot 数大于 0，因此服务在 ready 前退出。

该问题与 graph、MTP、prefix cache 开关无关；只要 has_linear_attention_layers(args_) 为 true 就会触发。目前主要影响 Qwen3Next、Qwen3.5 文本模型以及相应 VLM 路径，普通全注意力模型不受影响。单独设置 max_linear_state_cache_slots 也无法绕过，因为当前 main 尚未把该配置完整接到容量估算和 BlockManager wiring。

本地验证过，至少需要在 LLM/VLM engine 构造 BlockManagerPool::Options 时传入：

options.linear_state_num_slots(
    static_cast<int32_t>(kv_cache_cap.num_linear_state_blocks()));

这样可以恢复启动。完整接入还应同步传入 linear_chunk_stride，并把 max_linear_state_cache_slots 接到 estimation；PR #1940 当前主要补充 estimation/restore，完整 WIP #1839 中已经包含上述 engine wiring，可考虑优先拆出一个最小启动修复，或加速合入对应 wiring 提交。

建议补充一个 engine 级回归测试：使用 has_linear_attention_layers=true 的 ModelArgs 构造 KV capacity 和 BlockManagerPool，确保估算得到的 slot 数与 scheduler 侧 LINEAR pool 一致。现有 block manager 单测直接传入了非零 slot，因此没有覆盖到这处跨模块断链。