Skip to content

kali20gakki/msAgent / skills/host-cpu/msagent-perf-cpu-perf-triage

msagent-perf-cpu-perf-triage

Verified

昇腾 Host 侧性能异常归因编排:训练/推理出现症状(变慢、抖动、利用率低)且原因 不明时,按「配置复核 → 归因量化」编排 config-audit 完成配置判型,并输出按 代价×收益排序的 Action。触发:训练变慢、step 抖动、性能下降、利用率低、查根因、 瓶颈在哪。 不用于:只要配置检查(→ perf-cpu-config-audit)、只要绑核方案 (→ perf-cpu-bind-tune)——窄诉求直接用对应技能更快;本技能用于症状不明、 需多源归因的场景。

msagent-perf-cpu-perf-triage — 性能异常归因编排

回答「训练慢 / step 抖动 / 利用率低的根因在哪」:把 host 侧异常归因到 配置 / 系统打扰 / 等待 / 代码效率 四类,并给出量化占比与可执行动作。

本期交付配置维(判型 + 影响面)与动作编排;打扰 / 等待两维依赖运行时采集, 随 tracing 技能合入后启用(quantify.py 已兼容其产物格式,无需改代码)。

本 Skill 是唯一编排者:本身不带 discover / topology,不重实现基础 Skill 的 采集与判定,全部通过子进程调用其 CLI 并消费结构化产物。

职责边界

  • 做:阶段调度、跨源归因、两级口径量化、Action 排序、汇总页与索引;
  • 不做:精确绑核方案(→ bind-tune)、配置判定阈值(→ config-audit)、 运行时事件域采集与事实计算(后续版本接入)、PMU 效率定量(→ perf-collect,第二期)、 代码改写(只给建议,交开发)。

流程

flowchart TD
    S(["症状:变慢 / 抖动 / 利用率低"]) --> S0["阶段0 配置复核<br/>audit_or_reuse.py"]
    S0 -->|配置告警 / 高置信 R 规则| R0["结论:配置主因候选<br/>动作:L0/L1 试证"]
    S0 -->|无配置主因| R4["运行时 / 效率维<br/>本期未接入(not_observable)"]
    R0 & R4 --> M["quantify.py 两级口径量化"]
    M --> A["action_build.py 动作装填与排序"]
    A --> P["report.py 汇总页 index.html + manifest.json"]

执行顺序固定:配置优先(成本最低、即时可回滚)→ 运行时打扰/等待(后续接入)→ 效率(第二期),不得跳阶段(降级矩阵允许的除外)。

命令行用法

所有脚本在 scripts/,统一 python3 <script> --session <dir> ...,stdout 输出 JSON。

0) 会话目录

会话根由首个子命令自动建立(workspaces/<host>/<yyyymmdd-hhmmss>/),也可显式传 --session /path/to/session 复用已有会话。本期创建 00-config/ 02-perf/ actions/, 汇总页与 manifest.json 在根。运行时产物目录 01-trace/ 由后续 tracing 技能产出, quantify.py 检测到后会自动消费。

1) 阶段0 配置复核

python3 scripts/audit_or_reuse.py --session <S> [--findings <f.json>] \
    [--max-age-min 30] [--config-audit-dir <skill_dir>] [--skip-audit]
  • 候选 findings 在 30min 内 → REUSED(直接消费,不重复审计);
  • 缺失或过期 → 子进程调 config-audit 快检 → RERUN;
  • 找不到 config-audit → UNAVAILABLE(配置维缺失,进降级)。

产出 00-config/config_triage.json:判型结论(config_primary_candidate / impact_level)+ 引用 Finding 与 Action 原文(不重判定)。

2) 量化 + 动作 + 汇总

python3 scripts/quantify.py     --session <S>
python3 scripts/action_build.py --session <S>
python3 scripts/report.py       --session <S>

产出:

  • attribution.json(AttributionResult:config_typing / disturb_pct / wait_pct + wait_breakdown / efficiency / residual_pct / converged)
  • actions/action_plan.json(Action[] 8 字段 + 编排层扩展)
  • index.html(汇总页)+ manifest.json(机读索引)

产物组织

workspaces/<host>/<ts>/
├── index.html                  # 汇总页(唯一入口,只导航不合并内容)
├── manifest.json               # 机读索引:run_id / 阶段状态 / 产物路径 / 结论
├── attribution.json            # 归因量化结果
├── 00-config/
│   ├── config_triage.json
│   ├── findings.json           # config-audit 产物(复用或重跑)
│   └── hostcpu_config_report_<host>_<ts>.html
├── 02-perf/                    # 第二期(perf-collect 交付后)
└── actions/
    └── action_plan.json

运行时数据(可选):若后续 tracing 接入并在会话内产出 01-trace/phase_verdict_1.json,quantify.py 会自动读取并量化打扰 / 等待两维。

量化口径(简述,细则见 references/quant-rules.md)

维度本期状态口径
配置类可用判型定性排除(影响面 高/中/低,不硬折算数值)
打扰类未接入运行时数据(01-trace/phase_verdict_1.json)合入后启用;缺数据记 null
等待类未接入同上,按唤醒源细分(标 inference)
效率类not_observable第二期 perf-collect 启用
残余随运行时数据运行时可归因时 100% − 已归因,> 30% 标「未收敛」;无数据记 null

动作映射模板(运行时 action_hint → Action、等待唤醒源 → Action)以 resources/action-templates.json 为唯一来源,scripts/action_build.py 只查表; 调整动作文案改该 JSON 即可,不在代码或 references 中重复维护。

降级

见 references/degradation.md。核心几条:

  • 无 config-audit → 配置维缺失,结论为「无法归因」,需补齐依赖后重跑;
  • 运行时数据缺失(本期默认)→ 打扰/等待为 null,结论降级为「仅完成配置判型」;
  • 运行时产物缺 accounting(版本不匹配)→ 两维按不可观测处理并显式标注。

与其他 Skill 的协作

上游消费方式
config-audit子进程调 audit.py(快检)或复用其 findings.json;产出只引用不重判
下游转出方式
bind-tuneAction 标 bind_tune_handoff + suggested_cpuset,由主会话转出出 plan
config-audit中断亲和类动作标 config_audit_handoff,转出生成命令
Profiler / 通信域Host 侧无法直接消除的阻塞类问题,只给建议 + 转出引导

执行协议

本 Skill 只产出动作契约(含命令、回滚、验证),不自动执行。 高风险动作逐条展示「动作 / 影响 / 风险 / 回滚」后由用户确认(L0 可代执行试证, L1/L2 出命令,L3 交运维),执行后复采同窗验证。

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall