cannbot-knowledge

CANNBot 是 CANN 社区的 Infra 智能体层，用 Agent 完成 AscendC/PyPTO/TileLang/Triton 等各类语言的算子开发、模型迁移与推理优化，并延伸至图模式、Runtime 等更多 CANN 开发场景。

本仓（cannbot-knowledge）是其知识仓，提供知识库检索货架；仓群还包括 cannbot、cannbot-skills、cannbot-dsl、cann-bench、cannbot-sentry 等仓库，结构如下。

本仓不把算子工程或模型代码作为知识正文提交，而是把经过整理、能够追溯到登记的文档来源、固定版本源码或卡内原始观测的工程知识保存成 Markdown 知识卡，例如：

• 某个 CANN API 的语义和使用限制；
• 某种算子 DSL 的编程模型；
• 一个算子的设计、实现或优化方法；
• 某类编译、运行、精度或性能问题的排查步骤。

CANNBot 通过本仓提供的 Skill 生产、检索和检查这些知识，从而在回答问题或执行工程任务时复用经过治理、可以追溯来源的结论。

设计参考

本仓知识正文的文件化设计参考 Google 的 Open Knowledge Format（OKF）v0.2。知识使用带 YAML Frontmatter 的 Markdown 表达，通过目录和 index.md 渐进浏览，通过普通 Markdown 链接形成可重建关系，并使用 Git 分发和审计。

knowledge/ 是本仓唯一且符合 OKF v0.2 的 Knowledge Bundle 根目录，其下所有卡片共享同一个 Concept ID 命名空间。common/、ops/ 等只是 Bundle 内的分类，不是独立 Bundle；仓库根目录的 Skill、治理、测试和日志设施不属于 Bundle。详细边界见 OKF Bundle 与 CANNBot Profile。

当前知识状态

当前 knowledge/ 共有 5,040 张知识卡，覆盖 Ascend C、Triton-Ascend、公共平台与模型场景：

• 2,993 张 API 卡，其中 Ascend C 2,865 张、Triton 128 张；
• 465 张 Guide 卡，其中 Ascend C 274 张、Triton 157 张、模型场景 34 张；
• 611 张 Operator 卡，其中 559 张 ACLNN 全链路卡、52 张 Direct Invoke 卡；
• 565 张 Runbook 卡，其中 Ascend C 459 张、Triton 12 张、模型场景 94 张；
• 193 张 Concept 卡，其中公共平台 5 张、模型场景 188 张；
• 202 张 Optimization 卡，其中 Triton 92 张、模型场景 110 张；
• 11 张 Triton Example 卡；
• Ascend C API/Guide 来源指向 Registry 登记的 cann-docs-raw/ 文档归档，官方归档持续更新，恢复时不校验预登记的归档或内容树 SHA-256；模型 Guide 来源固定到托管仓 40 位 Commit 和具体文件，Operator 来源固定到 CANN 官方 Git 仓 40 位 Commit 和具体文件。

上述数量是当前版本快照。Registry 中注册的所有 domain 根目录始终保留；ops 和 model 额外预建已注册 route，其他领域的下一层路径随首批真实知识创建。只有 index.md 的结构入口不算正式知识卡，也不会出现在 Query 的覆盖统计中。“存在目录”不表示“已有知识”，实时数量以 Query 返回的实际覆盖为准。

本地来源不提交到 Git。需要核对卡片证据时，在仓库根执行：

bash get_resources.sh

脚本默认恢复滚动更新的官方文档归档，以及 ops-nn、ops-math、ops-transformer、ops-cv 的固定提交源码；也可用 --docs 或 --code 只恢复一类资源。文档缓存默认复用，需要获取当前归档时使用 bash get_resources.sh --docs --refresh；源码复用前会校验提交、来源和工作区。两类资源都保持 Git 忽略，脚本不会覆盖不完整目录或带本地修改的源码。

Operator 的本地 sources 使用相对于知识仓根的固定提交路径，缺失来源不会被自动替换成其他版本。官方 API/Guide 只为包含独立技术事实的来源页建卡，导航页由逐层 index.md 承载；“产品支持情况”转换为 Frontmatter platforms，其余保留正文按受控规则同步。

完整来源和转换约束见 Frontmatter 与证据与 Schema、Registry 与 Contract。

知识卡之间通过普通 Markdown 链接形成关系，图谱按需从这些链接生成。API 引用建议可以单独扫描固定源码，但建议不证明运行时可达性，也不会自动改写知识卡或成为入库前置步骤。

这个仓库如何工作

官方文档 / 固定版本源码 / 可复现实验
                    │
                    ▼
       Ingest 与专用 producer
                    │
                    ▼
               Markdown 知识卡
                 │        │
                 │        └── knowledge-lint 检查结构和治理规则
                 ▼
            knowledge-query
                    │
                    ▼
          CANNBot 读取正文并核对来源

本仓维护七项 Skill：六项可安装到业务项目，ops-knowledge-trace-ingest 只用于本知识仓内的 trace → Runbook 生产。

Skill	作用	是否修改知识仓
knowledge-query	查看实际知识覆盖，检索知识卡，并可保存不可覆盖的审计 receipt	除指定 receipt 外只读
ascendc-api-knowledge-query	复用 Query 按硬件平台检索 Ascend C API，阅读全文并按需追踪相关卡片和本地 CANN 头文件	否
knowledge-ingest	统一路由新来源、增量、版本升级和通用建卡，支持按需链接图谱	创建候选卡；构图只读正文，产物始终由 Git 忽略
knowledge-lint	检查目录、Frontmatter、来源、正文、导航和日志；整理 Issue 材料	否
ops-knowledge-trace-ingest	从算子开发 trace 蒸馏 Runbook，并按当前 Schema、导航、Lint 和检索门禁收口	仓内使用；只写经审查的 Runbook、导航和日志
ops-knowledge-vv-ingest	从固定版本源码提取不含可达 Cube/AIC 或 MIX_CV 节点的完整 Operator 卡	只写任务指定的最终卡
ops-knowledge-cv-ingest	从固定版本源码提取含可达 Cube/AIC 或 MIX_CV 节点的完整 Operator 卡	只写任务指定的最终卡

知识如何组织

大多数知识卡使用下面的路径：

knowledge/<领域>/<技术或作用域>/<路径 Profile>/<知识卡>.md

例如，当前 API 卡可以采用分层主题目录：

knowledge/ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division.md

其中：

• ops 表示算子领域；
• ascendc 表示这条知识只适用于 Ascend C；
• apis 是路径 Profile，表示它是一张 API 知识卡；
• utils_api/cpp_stdlib/math_functions 是便于浏览的主题 section；
• bundle 内的 ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division 是 OKF Concept ID；移动卡片会改变该标识；
• Frontmatter type: API 是路径 Profile 的确定性投影，供 OKF consumer 读取。

不同 DSL 的专属知识分开保存。只有确实不依赖某个 DSL 的结论才能进入 shared/；两种技术之间哪些内容可以复用、哪些必须重新推导，则写入 shared/interoperability/。

Operator 卡按 operators/<aclnn|direct>/<cv|math|nn|transformer>/<category>/<operator>.md 组织；aclnn 保存公开 ACLNN/API 到 Kernel 的完整链路，direct 保存独立 Direct Invoke 路线，category 沿用 Registry 登记的官方源码一级分类。

每张知识卡的正文解释结论、适用条件和失效边界；文件开头的 Frontmatter 保存检索、平台、版本、生命周期和来源等结构化信息。详细规则见治理规范。

仓库目录

路径	用途
knowledge/	知识卡和逐层导航，是唯一知识正文目录
governance/schemas/	机器可读的字段、路径 Profile 和受控值规则
governance/specs/	对治理规则的完整文字说明
governance/contracts/	Ingest、Query、Lint 和图谱共同使用的校验实现
.agents/skills/	三项基础 Skill、Ascend C API 专用消费流程、仓内 trace producer 与两项源码级 Operator producer 的规范源
docs/	知识库设计原则、安装与使用指南
recipes/	面向具体任务的知识库最佳实践
evals/	检索、治理、文档和安装回归
OAT.xml	GitCode 开源扫描使用的 CANN 2.0 许可策略和 matcher
install.sh	自动取得知识仓、补齐运行依赖、恢复资源、准备索引并把 Skill 安装到目标项目
check.sh	运行仓库完整质量检查
artifacts/	本地生成且可重建的产物，默认不提交
logs/	已实施的知识和治理变更记录

安装与使用

安装和使用方法见安装与使用指南。

设计取舍见设计原则；常见任务见形成可追溯回答、贡献知识、查询 API和使用知识库进行算子开发。

贡献和检查

贡献知识前阅读 CONTRIBUTING.md。它说明如何查重、选择路径、准备来源、编写知识卡、更新导航和提交 Skill 变更。

提交前运行：

bash check.sh

该入口恢复并校验登记资源，再执行知识 Lint、归档复验、索引与检索回归、单元测试、Ruff 和 Shell 语法检查。图谱和 API 引用建议按需生成，不属于入库门禁。

治理规范

• OKF Bundle 与 CANNBot Profile：Bundle 边界、OKF 对应关系和严格作者门禁。
• 知识路径：domain、technology/scope、路径 Profile、Concept ID 和索引规则。
• Frontmatter 与证据：字段组合、生命周期、来源、标签、平台和版本。
• Schema、Registry 与 Contract：机器事实源、受控词表和规则执行关系。
• Knowledge Skills：Query、通用 Ingest、仓内 trace producer、Operator producer、Lint 和安装模式。

本仓采用 CANN Open Software License Agreement 2.0。