企业官网建设流程全解析

• 示例工程
• 人工智能
• 大模型
• 模型推理服务
• 模型优化
• 模型量化
• CANN
• Ascend

本文围绕 model-infer-analyzer 的角色定义文件展开，说明它在 cann-recipes-infer 的"编排 Agent + 三类专业 SubAgent"协作体系中的定位、权限边界、工作场景识别规则与progress.md输出规范，并结合 端到端优化编排 skill、Hook 硬约束脚本 和各阶段 skill 的实现，还原一个分析专家 SubAgent 从被派发到输出结构化方案的完整工作链路。读完本文，你可以理解该 Agent 的只读分析边界如何被软、硬两层机制保障，以及它在阶段 0 架构分析、并行策略、KVCache 选型、融合算子匹配、量化初评估、图模式方案分析等场景下分别产出什么。

角色定位：分析/实施/验证三分工中的"分析专家"

在 Agent Skills 总览 中，cann-recipes-infer 的基础优化工作流采用"主 Agent 编排 + 三类专业 SubAgent"的协作模式，通过分析、实施、验证的职责隔离，降低单个 Agent 同时承担多角色导致的越界与漏检问题。四个角色的分工如下：

model-infer-analyzer在这三者中承担"先想清楚再动手"的角色：设计文档 的协作信息流规定，每个优化阶段主 Agent 先派发 analyzer 进行方案分析，结果写入progress.md，再由用户确认方案后才派发 implementer 实施。也就是说，analyzer 的产出质量直接决定后续改造方向，而它自身没有任何修改模型代码的权限。

角色定义文件 model-infer-analyzer.md 以 YAML frontmatter 声明了 SubAgent 的身份与能力装载：

--- name: model-infer-analyzer description: 模型优化分析专家，负责模型架构分析、并行策略推荐、优化方案设计和 Profiling 数据解读。适用于模型结构理解、部署策略决策、各优化阶段的方案评估等分析类任务。 mode: subagent skills: - model-infer-parallel-analysis - model-infer-kvcache - model-infer-fusion - model-infer-quantization - model-infer-graph-mode ---

mode: subagent表明它只能由主 Agent 派发启动，不能独立作为会话入口；skills列表则规定了它能加载的全部分析技能——注意其中刻意不包含 model-infer-migrator（框架适配）和 model-infer-parallel-impl（并行切分实施），因为这两类"动代码"的能力归属于 implementer。description中的触发场景描述（模型结构理解、部署策略决策、方案评估）则用于客户端的意图匹配。

权限边界：软约束 + 硬约束双层保障

角色定义正文开宗明义："只读模型代码和配置，仅写 progress.md。禁止修改模型代码（modeling_*.py）、配置文件（YAML/config）、推理脚本（runner_*.py、infer.py）和框架代码（executor/）。" 这属于"软约束"——写在定义文件中的规则 Agent 可能不遵守，设计文档 第 8 章明确将其与 Hook "硬约束"区分开。

硬约束落在 pre_tool_use.py 中：该脚本通过 .agents/settings.json 注册到PreToolUse钩子（匹配Edit|Write工具调用），在写文件前执行角色越界检查。其中PROTECTED_PATTERNS对 analyzer 的拦截规则为：

PROTECTED_PATTERNS = { "model-infer-analyzer": [ "modeling_*.py", "runner_*.py", "*.yaml", "executor/*", ], ... }

见 pre_tool_use.py#L14-L19。一旦 analyzer 尝试Edit/Write上述任一模式的文件，Hook 直接阻断并提示"禁止：model-infer-analyzer 不允许修改 {文件名}。模型代码修改请通过 implementer 执行。"这与角色定义中列举的四类禁止修改对象一一对应，形成从文档到运行时的闭环校验。

启动流程与状态文件读写规则

角色定义给出了 analyzer 的两步启动流程：

1. 定位模型与读取状态：从 dispatch prompt 中的"工作目录"确定模型路径，读取该目录下的progress.md，了解模型信息和当前阶段，优先从常驻区确认运行环境（NPU 型号、HBM 容量、部署卡数）。
2. 按指定 skill 分析：必须调用编排层指定的 skill，按 skill 流程进行分析。

这里有两个值得注意的设计细节：

第一，progress.md是 analyzer 唯一的上下文来源。编排层的派发规范（见 model-infer-optimize/SKILL.md 的"subagent 派发规范"）要求 dispatch prompt 只包含工作目录、任务、必须使用的 skill 等模板字段，不附加任何分析结论或技术方案；analyzer 需要的模型信息、已确认决策、基线数据全部通过读取progress.md获得。progress.md的结构在 progress_template.md 中定义，分为两部分：

• 常驻区（阶段 0 写入，后续不清除）：运行环境（NPU 型号、单卡 HBM、部署卡数、执行模式）、模型架构（架构类型与关键参数、网络结构拆解、Prefill/Decode 差异、关键模块特性）、模型当前状态（可运行/不可运行/需多卡）、部署基线（migrator 采集的 Prefill/Decode 耗时）、量化接入常驻结论，以及按阶段 0~5 组织的一行式"进度概览"表。
• 工作区（当前阶段记录，阶段推进时归档清空）：各阶段的具体分析结论与实施记录。

第二，历史文件的读取被刻意收窄。定义文件明确规定："progress.md 直接 Read；progress_history.md 禁止 Read 全文，需要历史信息时用 Grep 关键字查找。" 阶段推进时工作区会被归档进progress_history.md（归档脚本见 archive_progress.py），随着优化阶段增多该文件会不断膨胀；禁止全文 Read 是为了避免历史噪声占满 analyzer 的上下文窗口，需要回溯某次决策时按关键字检索即可。设计文档 第 6.1 节将这种"用到哪层才加载哪层"的做法归纳为分层上下文策略，analyzer 的状态文件规则正是其在 SubAgent 层面的具体落地。

工作场景识别：四条优先级规则

analyzer 被派发时的任务并不总是一样的——它既要在阶段 0 做首次架构分析，也要在"精度达标但性能未提升"时做瓶颈排查。角色定义用一张优先级表规定了场景识别逻辑：

结合 model-infer-optimize 的完整编排流程，可以枚举出 analyzer 在主流程中的全部派发场景，每条都能对号入座：

这张表说明 analyzer 并不是"只在阶段 0 出场"的一次性角色，而是贯穿阶段 0 到阶段 5 的每个"分析 → 方案确认 → 实施 → 验证"循环的分析端。而规则 3（性能未提升排查）在编排层的每个阶段总结小节都被显式写入了回退路径，例如阶段 2 的"精度达标但性能未提升 → 派发 model-infer-analyzer（排查性能问题）→ 将分析和建议呈现给用户决策"。

核心原则：五条分析纪律及其仓库印证

角色定义列出了 analyzer 的五条核心原则，每一条都能在 skill 与 Hook 中找到对应实现。

1. 禁止编造解释

"遇到异常数据、分析结论不合理或用户质疑时，必须先用工具调查，用证据回答。" 设计文档将这条列为三个 SubAgent 的共享核心原则。与之配套的是编排层的"异常把控"规则：主 Agent 对各阶段 subagent 报告中的异常保持敏感，不接受未经调查的报告——分析结论不合理、性能数据与改动预期不符时要求重新调查。对 analyzer 而言，这意味着一份"看起来合理但没有工具调用证据支撑"的分析是不可交付的。

2. 严格按 skill 分析流程执行

"调用 skill 后按其定义的步骤逐步推进，不跳过；skill 中已有的参考模型、决策树等直接使用。" 以 model-infer-parallel-analysis 为例，该 skill 定义了"提取模型参数与模块链路 → 定性分类（三层决策树）→ 定量估算 → 方案审查 →（可选）Profiling 校准"的五步流程，并明文"禁止跳过前三步直接给配置、不做估算凭经验拍数"。analyzer 的职责是忠实执行这类流程，而不是自行发明捷径；决策树、速查表、参考配置索引 等资产直接复用。

3. 充分了解后再决策

原则将"了解模型"拆成两个具体的读文件动作：

• 模型参数（层数、hidden size、头数、专家数等）→ 读config.json/configuration_*.py；
• 模块链路拆解（Attention 结构、MoE routing、FFN 组合等）→ 读modeling_*.py代码。

并强调"不跳过分析直接给结论，不确定的信息明确标注"。这与 model-infer-optimize 0.2 派发模板中的要求互相印证："架构识别必须基于实际 config 值（config.json / model.config），不能仅从代码类定义推断——注意可配置开关（如 use_mla、n_routed_experts）"。以仓库中的 deepseek_r1 配置 或 gemma_4 的 configuration_gemma4.py 为例，同一份 modeling 代码在不同 config 下可能走 MLA 或 GQA、MoE 或 Dense 完全不同的路径，因此"参数以 config 为准、链路以代码为准"是 analyzer 建立模型基线认知的基本功。

4. 方案有量化依据，优先参考已有实现

"参数量、FLOPs、通信量、显存等需计算；优先查仓库中最接近的模型作为参照。" parallel-analysis skill 的第三步给出了完整的定量方法论：参数量计算（GQA Attention、MLA Attention、FFN/MoE/Embed 各自的公式）、单卡显存估算（参数权重按各模块独立 TP/EP 度分摊 + KV Cache 单独计算，含 MLA absorb 需额外计入qk_rope_head_dim否则会低估约 12% 的细节）、通信量分析（按"是否跨节点 > 热路径高频 > 原语类型 > 字节量 > 可否 overlap"四层排序）。"优先参考已有实现"则对应 skill 中"已验证的并行模式"表——如大规模高吞吐场景参考 R1/V3.2/GLM-5/Kimi-K2 的 128 卡配置，长序列 CP 场景参考 models/deepseek_v3_2_exp/ 与 models/longcat_flash/。注意 skill 同时约束：仓库已验证配置"只作为候选种子和 sanity check，不作为默认结论"，目标模型与参考模型存在模块差异时必须以当前模型的模块拆解为准。

5. 输出结构化方案文档

分析结果必须按统一格式写入progress.md对应阶段，且"格式区分阶段 0 和后续阶段"。具体模板见下一节。

输出规范：progress.md 的两类写入格式

角色定义明确规定写入规则：只追加不清空；写入前先读取现有内容，追加到对应 section 末尾，避免覆盖其他角色的记录。这一"追加式协作"是三个 SubAgent 共用同一状态文件的前提——analyzer 写方案决策、implementer 写实施记录、reviewer 写验证结果，谁都不能清空别人的记录。

阶段 0 专用模板（模型分析）

首次分析使用专用模板，要求记录运行环境、模型架构与基线三部分：

## 阶段 0：模型分析 ### 运行环境 - NPU 型号:（通过 `asys info -r=status` 确认） - 单卡 HBM: - 部署卡数:（注意Atlas A3 系列为单卡双die模式，部署时以 die 数为单位（world_size = 物理卡数 × 每卡 die 数）） - 量化模式: - 执行模式: ### 模型架构 - 模型路径 - 架构类型（Dense / MoE） - 层数、hidden size、FFN 中间维度 - Attention 类型（GQA/MHA/MLA）、头数、KV 头数、head dim - MoE 信息（如有）：专家数、每 token 激活专家数 - 词表大小 ### 性能与精度基线 - Prefill 耗时、Decode 单步耗时、显存占用 （若无法运行则标注"无基线"及具体原因）

模板中的两条提示值得留意：其一，NPU 型号必须通过asys info -r=status实测确认（运行前需sourceCANN 的setenv.bash，见编排 skill 0.2 派发模板），而不是从用户描述中抄录；其二，对 Atlas A3 系列，部署卡数要按"单卡双 die"折算成 die 数（world_size = 物理卡数 × 每卡 die 数），因为该框架的并行度以 world_size 为单位推导。这一环境结论会落入progress.md常驻区，后续所有阶段的 implementer 和 reviewer 启动时都"优先从常驻区确认运行环境"，保证三方对环境认知一致——例如 implementer 的自验证要求"与常驻区环境一致（如常驻区有 NPU 环境则推理项不应为空）"。

阶段 1-N 标准格式（关键决策表）

后续各阶段的分析产出统一使用"关键决策"三列表：

## 阶段 N：标题 ### 关键决策 | 决策项 | 选择 | 理由 | |--------|------|------| | ... | ... | ... |

以并行策略分析为例，model-infer-parallel-analysis 第四步的输出格式要求更细：给出 2~3 个候选parallel_config（attn_tp_size/dense_tp_size/moe_tp_size/embed_tp_size/lmhead_tp_size/o_proj_tp_size/cp_size/kvp_size等），每个候选附带estimation（params_per_card_gb、kv_cache_per_card_gb、memory_feasible、cross_node_comm）与tradeoff（throughput / latency / long_context），并按"显存可行性 > 跨节点通信风险 > 预期性能 > 与已验证配置距离"的维度排序。这类结构化产出正是主 Agent 向用户逐条确认方案（如"各模块 TP 度：attn_tp / dense_tp / moe_tp / embed_tp / lmhead_tp / oproj_tp"）的基础——决策项、选择、理由一一对应，用户确认后 implementer 才能按同一份parallel_config实施。

运行环境准备与触发方式

在仓库中实际使用该 Agent，需要在仓库根目录执行初始化脚本，将.agents/下的 agents、skills、hooks 暴露给对应客户端：

bash scripts/init-agent.sh --codex # Codex 用户 bash scripts/init-agent.sh --claude # Claude Code 用户 bash scripts/init-agent.sh --opencode # OpenCode 用户

脚本会在.claude/下创建指向.agents/的 symlink 并复制 settings.json（因此 analyzer 的写保护 Hook 随客户端生效），在.codex/agents/下由 model-infer-analyzer.md 等角色定义生成*.toml，并在根目录创建CLAUDE.md → AGENTS.md软链；生成物均已加入.gitignore。

analyzer 本身不直接被用户触发，典型触发起点是向主 Agent 发出端到端优化请求（"对目标模型进行端到端 NPU 推理优化"），或单阶段请求（"使用 model-infer-parallel-analysis 分析并行策略"），主 Agent 再按各阶段的派发模板生成仅含工作目录、任务与指定 skill 的 dispatch prompt。完整的阶段调度关系见 .agents/README.md 的"调度关系"一节与 model-infer-optimize-design.md 的调度架构图。

小结

model-infer-analyzer是 cann-recipes-infer Agent 体系中"动代码之前先动分析"的关键角色，其设计要点可以归纳为四层：

• 职责单一：只读模型代码与配置，只写progress.md，frontmatter 中的 skills 列表只挂 5 个纯分析技能，天然排除实施类能力；
• 边界硬保障：pre_tool_use.py 的PreToolUseHook 在Edit/Write前拦截 analyzer 对modeling_*.py、runner_*.py、*.yaml、executor/*的修改，把"只读"从文档约定升级为运行时强制；
• 场景可枚举：四条优先级规则覆盖"首次架构分析 / 指定 skill / 性能瓶颈排查 / 按阶段上下文"四类场景，与编排层 0.2、0.5、1.2、2.1、3.1、4.1、5.1 及各阶段性能排查回退路径一一对应；
• 产出可验证：阶段 0 的"运行环境 + 模型架构 + 基线"专用模板和阶段 1-N 的"关键决策"三列表，配合追加式写入规则，使分析结论能够被用户逐条确认、被 implementer 精确消费、被 reviewer 对照验收。

对希望复用该模式的开发者而言，可参考 docs/agent/model-infer-optimize-design.md 中 Skill 标准化、分层上下文与 Hook 约束机制的完整设计，以及 .agents/skills/ 下各 skill 的SKILL.md与references/组织方式。

• 示例工程
• 人工智能
• 大模型
• 模型推理服务
• 模型优化
• 模型量化
• CANN
• Ascend