Skip to content
Conduit

skill

ascend-sleuth

知识驱动的昇腾训练/推理诊断 skill 套件 — Ascend training/inference diagnosis skill suite (5 skills + 3-tier knowledge base, Agent Skills standard)

pillumina/ascend-sleuthcommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/pillumina/ascend-sleuth itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 25, 2026

训练或推理在昇腾 NPU 上中断、精度异常、性能退化时，把日志与版本信息交给 agent。它按症状路由，查先验知识（官方文档与已沉淀事实）框定方向，再加载候选 case 逐条验证。未命中时继续深度排查，可按版本拉源码分析。输出定位结论与修复方案。

定位结束后，新知识进待审队列，每周例行维护去重、升格为 case，同类问题下次直接命中。共性另归纳成先验知识。系统也按使用记录演进：未命中、执行出错、条目过期都记为改进卡。改动按影响面验证，提 PR 人审。

skill 按 Agent Skills 标准打包。可在 pi、Claude Code、Codex、DeepSeek Harness（DSH）等支持该标准的 agent 中运行。

快速开始

安装

git clone https://github.com/pillumina/ascend-sleuth.git
cd ascend-sleuth
python3 scripts/enable_agent_skills.py

脚本检测本机已安装的 agent，为它们建项目级 skills 链接（幂等，可重复执行）。Linux 与 macOS 上 DSH 不跑这个脚本也够用：.dsh/skills 是仓库跟踪的 symlink，clone 后即可用。git pull 更新 SKILL.md 即时生效。

诊断开单会自动同步知识库：trace_begin.py 建单时 fetch 远端，条件满足时做一次快进合并。

配置与开关（sync.remote / sync.branch / sync.enabled / sync.auto_merge / sync.check_enabled / sync.check_minutes / sync.check_full_access）在 .local/settings.json。sync.enabled 与 sync.auto_merge 只管诊断读侧的自动路径，groom 不受影响；sync.check_enabled / sync.check_minutes 是诊断状态条的知识库提醒开关与检查间隔（可在「Ascend Sleuth · 知识库」页设置）。没有这个文件时用默认值：origin、当前分支上游（取不到用 main）、同步开、自动合并开。

当前状态用 python3 scripts/kb_sync.py --show 查看（只读，不联网）。

Windows 上 Git 默认不还原 symlink，.dsh/skills 会落成一个内容为 ../skills 的文本文件，agent 发现不了 skills，而 git status 此时可能是干净的。脚本会把这条 symlink 建好；自动检测认不出的 agent 用 --all。--check 只读自检状态（不写盘），--fix-copy 把 Git Bash 建出的目录副本换成链接。自检与两条修法见 windows-setup.md。

装完在 agent 中调用 /skill:<name>。

使用示例

在 agent 中调用 /skill:diagnose，把客户给的症状、框架版本与日志片段粘贴给它：

/skill:diagnose

客户 A5-950 训练在 step ~3000 hang，all_to_all timeout，world_size=128。
框架 mindspeed-llm 2.5.0。报错栈尾：
[粘贴相关 rank 的日志片段]

agent 按症状路由到 training/mindspeed-llm/，匹配并验证 case。命中时输出四段：结论、依据链（含命中的 <CASE-ID>、历史 hits 与 misdiagnoses）、修复方案与 rollback、可靠度与残余风险。未命中时转深度排查。信息不足时，agent 指出还要向客户补什么。

诊断全程写 trace。被打断时可用 /skill:resume-diagnosis 续接。

在其他项目中试用

npx skills@latest add pillumina/ascend-sleuth -s diagnose -s to-postmortem -s to-reference -s issue-ingest -s knowledge-groom -s resume-diagnosis

该方式安装的是 skills/ 副本，更新需重新安装，也不沉淀回本仓。要在其他仓库中沉淀知识，按 知识获取：三种起步形态 配置。

背景

昇腾训练与推理的日常问题集中在三类：中断（hang、crash、OOM）、精度异常（loss 发散、FP8 衰减）、性能退化（吞吐下降、通信占比过高）。根因高度重复，相关知识却散落在个人笔记、IM 聊天与各处 wiki。新 case 每周都在出现，A2-910B / A3-910C / A5-950 三代平台的差异还在扩大，靠个人手工维护的知识库跟不上这个速度。

ascend-sleuth 把这些经验沉淀为结构化知识库。诊断时按症状路由到已验证的 case。定位结束后，新知识进入待审队列，由例行维护完成去重、升格与退休。人工沉淀按周批处理，自动化导入源可以直接升格。

工作原理

知识分三层按需加载，控制进 agent 上下文的量：

层内容加载时机
Tier 1triage-tree.yaml：症状到命名空间的映射始终加载
Tier 2knowledge/ 下的 case 规则命中症状后两阶段加载：先读该命名空间与类别的读侧视图过滤候选，再加载全文验证
Tier 3postmortems/ 下的原始定位记录前两层未命中时关键词检索

知识库本体在 knowledge/，按框架与类别分目录：

knowledge/
├── _index.yaml / _index/   总表与读侧视图（scripts/build_index.py 生成；合入后由主干 job 重建）
├── training/{mindspeed-llm,mindspeed-mm,verl}/
├── inference/{vllm-ascend,sglang}/
├── common/                 多框架共用的权威记录（由 groom 提升）
└── _archive/               软退休的过期 case

命名空间下面按性质分目录（如 inference/vllm-ascend/interrupt/）。先验知识层在 references/，放官方文档与案例沉淀的事实、工具词条与流程，不参与候选路由。

问题按两个维度拆。在哪查：训练还是推理、用什么框架，决定命名空间（如 training/mindspeed-llm/）。什么性质：中断、精度还是性能，决定匹配形态（中断用错误签名 grep，精度用数值阈值断言，性能用 profiler 指标比对），三者不混用。

诊断全程写 trace：加载了哪些命名空间、按什么顺序做了哪些检查、工程师提供了什么证据。误诊归因靠它区分 case 错（改知识 YAML）与执行错（改 skill 正文）。两者的修法不同，混在一起会改坏本来正确的 case。

三个闭环驱动整个系统：

闭环什么时候发生入口产出
诊断闭环每次问题（分钟级）/skill:diagnose修复建议 + trace
沉淀闭环定位结束后 / 定期批量/skill:to-postmortem、/skill:to-reference、/skill:issue-ingest待审队列 → case / reference 词条
演进闭环内容流程收尾 / 全库体检轮/skill:evolve-check、/skill:self-evolve改进卡 → 验证 → 攒批 PR（人审）

自演进机制的完整流程（交互图，可切主题与导出 PNG）：

每个机制配了什么护栏、每周实际要做什么，见 自演进元机制。

适用范围与限制

  • 诊断 agent 不访问客户环境，也不改生产：日志、版本与报错由工程师提供，修复建议由人应用。
  • 诊断质量随 agent 变化：prompt 纪律是概率性的，换一个 agent 或换一次会话，结果与 trace 质量可能不同。团队内建议统一 agent。跨 agent 对比时先归因执行差异，再判断是不是知识本身错。
  • data-loss-risk 的根因不给修复方案，只输出停机、保留现场、通知 owner。
  • 版本匹配是软判据：compat 不匹配只降 confidence，不排除 case。
  • 输出是给人看的建议，不对接 on-call 或 IM 通知链路。

skill 清单

本仓共 13 个面向使用者的 skill，按使用场景分 4 组：

  • 日常问答（1）：ask（一句话能问完的问题直接答（码、变量值、某类怎么定位、术语、库里有吗），症状定位转 diagnose）
  • 日常诊断（2）：diagnose · resume-diagnosis
  • 知识沉淀（4）：to-postmortem · to-reference · issue-ingest · reference-ingest
  • 维护与演进（6）：knowledge-groom · self-evolve · evolve-check（内部协议，由内容流程收尾自动转接，不单独调用） · skill-review（内部协议，由用户显式触发做 skill 质量审视） · preload-panel（仅 DSH：按本机给模型的工具定装载路，有 cordis_define / cordis_run 热加载，有 plugin_manager 装常驻插件包，DSH Desktop 用安装目录自带的 dsh 命令行装（profile 记成 link），另有脚本经 /api 通路装与插件页粘贴两条备用路；含「装了但 tab 不出现」的排查顺序） · doctor（本机环境体检：一条命令报「哪些流程能跑、哪些会降级」并给修法；只读，不装包）

每个 skill 的触发条件与操作细节见各自的 skills/<name>/SKILL.md。

文档

  • 文档总目录：全部文档按"什么时候读"分层
  • 演示走查：从一次诊断到知识演化的完整演示，不需要动手
  • 诊断面板：DSH 会话中的可视化面板（可选增强）
  • 知识获取：三种起步形态与稀疏拉取白名单
  • 部署与协作：集中式与框架式 fork 两种部署、目录归属、审核与门控
  • 术语表：case / postmortem / groom / trace / reference 的规范定义

许可

MIT，见 LICENSE。

↑↓ navigate openesc close