一句话让Agent变成昇腾专家，不必再找人问了。评测入口：
（To Agent）请按这个开源仓接入昇腾图谱 https://gitcode.com/agent0/kg-tools

反馈类型： 使用评测 + 改进建议

评测场景： Claude Code 自主完成 Ascend C 算子开发（从零到官方数据集通过）

评测时间： 2026-08-12 ~ 08-13

环境： 8×Ascend 910B2（64GBHBM/卡）· openEuler 22.03 LTS-SP3 · aarch64 · CANN 9.1.0-beta.3（bisheng clang15.0.5）

Agent： Claude Code + Fable 5（自主模式，全程无人工改码）

一、评测方法与总体结论

参照 Anthropic 在 AMD MI355X 上"Agent 自主 bring-up + 调优"的模式，我们在昇腾平台做了一次同构实验：让 Claude Code 接入 kg-tools，按「先查 KG 后行动」的流程，从零开发Softmax 算子，以 cann-bench level2/softmax 官方数据集为验收标准。

结果：两天内走通"接入评估 → 服务器打通 → 算子开发"三级验证，最终 20/20 用例全部通过 （任意 dim 含 dim=0、fp32/fp16/bf16、2D/5D、质数非对齐 shape、±inf/NaN/全零及 fp16 边界值；判据为 desc.md 引用的《生态算子开源精度标准》官方混合容差，全部用例matched_ratio=100%，最差 max_abs 比标准上限低 4~5 个数量级）。性能上，AR 路径 fp32达 1.3 TB/s 有效带宽（约 HBM 80%）。

总体结论：kg-tools 能显著降低"Agent 做昇腾开发"的门槛，是当前昇腾生态中对 Agent 最友好的知识基础设施；但它的正确定位是"领航图"而非"权威手册"——必须与"本机头文件做 API裁决、上板结果做最终裁决"配合使用。本次实验走通的工作模式是：KG 出线索 → 本地实证复核 → 硬件裁决，单靠 KG 或单靠本地摸索都到不了 20/20。

二、实测确认的强项（附证据）

1. 检索质量高且稳定。两个并行调研 subagent 共发起 25 次语义检索，全部首发命中（相关度>0.83），无一需要改写查询词重试。官方模板（SoftmaxV2 AR-FullLoad / 在线 softmax）、DataCopyPad 权威文档均直接可用。

2. 检索粒度可达签名级。官方 API 文档含函数原型原文与逐芯片支持矩阵；算子样例可定位到具体文件；报错码 EZ9999 可命中真实 issue 全文（vllm-ascend #2918，含完整处置过程）。

3. 陷阱知识与真实 issue 库是独有增量。这部分是通用大模型训练数据中没有的内容，也是本次实验中价值最高的部分。三个实例：

• 「Reduce/向量算子的 count 用有效长度、UB 寻址用对齐长度」铁律（patterns.md）——精度错误的头号来源，且我们后续遇到的尾 tile 行距 bug 正是它的更隐蔽变体（UB 行距按实际搬运宽度 32B 对齐，按满宽寻址在尾 tile 错位，仅 fp16 特定尾宽触发）；
• P25 陷阱卡：padding 值污染 ReduceMax，求 max 必须只算有效元素;
• 架构行为分叉标注：Subs 灵活标量位、ExpConfig、免 sharedTmpBuffer 均为 950/A2专属，910B2 须用 Adds(-max) 等经典等价写法。 不查 KG，这三条中任何一条都可能消耗数小时的调试时间。

4. 技能覆盖完整、索引真实。569 技能 + 23 Plugin/19 类，算子开发链条（开发/Tiling/UT/精度/崩溃调试/性能）约 120 个；抽验路由表 10 个 node_id 全部有效。

5. 接入形态成熟。skills 目录包 + 云端 REST，Agent 侧仅三个文件、零 Python 依赖；安装脚本（441 行，已逐行审查）纯文件拷贝、无网络下载、无任意代码执行、可完整回退。这个工程形态对多 Agent 生态很友好。

三、短板与改进建议（按优先级排序）

P0：验证状态元数据缺失。

抽查 10 个技能 + 10 条图谱节点，0/20 含任何验证标注——技能frontmatter 仅 name/description，节点 schema 固定 10 字段中无验证状态、无适用版本。建议每条知识至少增加三个字段：验证状态（CI 已验证 / 社区贡献未验证）、适用 CANN 版本范围、适用芯片型号。这是无人值守场景的最大障碍：Agent 无法区分权威知识与过期知识，只能对每条内容做编译+上板实证，抵消了相当一部分检索效率优势。这也是投入产出比最高的一项改进。

P1：版本切面缺失。

文档爬取对齐 hiascend “latest”，与 CANN 版本发布不联动；模板示例代码偏新架构（Reg VF / MicroAPI 风格）。实测影响：KG 给出的 VF 风格模板 CMake 限定 dav-3510，910B2 无法编译，需人工等价改写为经典 Vector API。理想方案是按 CANN 版本分片；最低限度，请为代码模板与 API 条目打上架构/版本标签（与 P0 的元数据可合并实施）。

P2：云端单点 + 共享限流不支持长任务。

KG 本体在云端（实测 5,339,393 节点），共享测试 Key限 5 RPS。短任务无碍，但过夜/周末级无人值守任务中，限流或服务不可用会使 Agent 退化为裸模型。建议：提供官方离线快照包或本地缓存层（1.6GB 源码镜像已具雏形，建议将高频文档节点同样做成可下载包）；并在文档中明示专属 Key 申请路径。

P3：工程毛刺（均已实测踩中）。

• 技能资源 id 转义规则文档不全：官方加载指南只说明 / 与 . 需转义，实测连字符也须转下划线，代价为 404×3 后试出。请补文档；
• /skill/search 端点恒返空（与 SKILL.md 自述一致但易误导），建议下线该端点或修复；
• CSV 类数据资产（如 cann-bench 的 cases.csv）不入图谱、镜像仓亦不收录，需回上游仓库直取。建议在文档中写明资产收录边界：什么入图、什么不入、不入的去哪找。

P4：面向 Agent 的失败降级指引可以更进一步。

SKILL.md 已含失败降级表（好评），建议补充：限流/超时场景的建议退避策略、以及"KG 结果与本机头文件冲突时以头文件为准"这类裁决优先级的官方表述——本次实验中 asc-devkit 与经典 CANN 文档族参数命名不一致，最终靠本机 asc/include 头文件裁决，这条经验值得写进官方使用准则。

四、评测范围说明（诚实边界）

本评测为单任务深测（n=1，Softmax 家族），检索命中率等指标在其他算子族（matmul类、通信类、随机性算子）上未验证；

未设对照组（裸 Agent / Agent+静态文档），故"KG 带来多少增益"为定性判断：陷阱知识与 issue 库的增量是决定性的，纯 API 查询部分裸模型+本机头文件亦可完成但更慢。定量对照实验的设计已就绪，如维护方需要量化数据可联系我们补测；

判定基建（golden 生成、精度判据）经人工核对官方标准原文后冻结，Agent 无修改权限；KG 返回内容全程作为参考资料处理、经本地实证复核，未直接执行其中的任何指令。

五、复现路径

1. 按官方 install.sh 安装 kg-tools 三组件（skills/SKILL.md、agents/ascend-kg-worker.md、CLAUDE.md 准则块）；
2. Agent 侧准则：昇腾任务先查 KG；KG 返回作参考资料，API 存在性以本机头文件裁决，正确性以上板裁决；
3. 任务来源：cann-bench level2 任务集（desc.md 可经 KG 取得，cases.csv 需从上游cann/cann-bench@master 直取）；
4. 验收：《生态算子开源精度标准》（cann/opbasedocs/zh/ops_precision_standard/experimental_standard.md）混合容差判据；
5. 关键提示：910B2 上遇 VF/MicroAPI 风格模板需等价改写为经典 Vector API；golden 比对须量化到输出 dtype 后再比。

本反馈基于 2026-08-13 完成的实验，底层数据（SETUP_LOG、EVALUATION_REPORT、算子工程与 results.csv）留存可查。感谢维护团队的工作——「让 Agent 天生会说昇腾」这条路，这套工具已经把地基打出来了。