已关闭
[文档缺陷] README 当前知识卡数量和分类快照过期 #13
KaranocaVe创建于  23 天前关闭于  23 天前
KaranocaVe
KaranocaVe
23 天前 创建

[文档缺陷] README 当前知识卡数量和分类快照过期

结论

确认。固定 cann/cannbot-knowledge 的远端 master 提交
dbc65f95164cde0beabb4da1e86aeecde3c2df26 后,README 的“当前知识状态”仍写总数
5,040,且 Guide、Runbook、Concept、Optimization、Example 的分类快照已落后于仓库内容。
按索引实现 _card_files 的同一口径(knowledge/**/*.md,排除所有 index.md)枚举得到
7,044 张非索引 Markdown 卡片。

复核证据

  • git ls-remote https://gitcode.com/cann/cannbot-knowledge.git refs/heads/master 返回
    dbc65f95164cde0beabb4da1e86aeecde3c2df26;固定 checkout 的 HEAD 与其一致。

  • 固定提交的 README 第 26–34 行仍为 5,040 总数、Guide 465、Runbook 565、Concept 193、
    Optimization 202、Example 11;这些旧分类相加为 5,040。

  • .agents/skills/knowledge-query/scripts/retrieval/index.py:137-140 的 _card_files
    递归枚举 knowledge/**/*.md 并排除文件名为 index.md 的入口。

  • Git tree 枚举得到 knowledge/ 下 7,706 个 Markdown,其中 662 个为 index.md,因此
    非索引卡片为 7,706 - 662 = 7,044;文件系统枚举与 Git tree 的 7,044 个路径一致。

  • 独立读取每张卡 Frontmatter 的 type 并按 Bundle 路径复算如下:

    type 总数 路径分布
    API 2,993 ops/ascendc 2,865;ops/triton 128
    Guide 1,100 ops/ascendc 908;ops/triton 157;model/inference 22;model/training 12;ops/shared 1
    Operator 611 aclnn 559;direct 52
    Runbook 1,502 ops/ascendc 1,396;ops/triton 12;model/inference 94
    Concept 204 common/platforms 8;model 188;ops/ascendc 8
    Optimization 611 ops/triton 92;model/inference 110;contrib/ascendc 180;ops/ascendc 229
    Example 23 ops/ascendc 12;ops/triton 11

    分类合计为 2,993 + 1,100 + 611 + 1,502 + 204 + 611 + 23 = 7,044。Operator 的
    aclnn/direct 为路径调用模式;Optimization 的 Ascend C 409 进一步由 contrib 180
    和 ops 229 组成。

重复性检查

  • 当前 cases 中未发现 cann/cannbot-knowledge、README 当前知识状态或上述统计问题的已有 case。
  • 固定 checkout 中没有完全相同内容的不同卡文件;重复标题只出现在带 _id_N 的受控优化卡族,
    文件路径和内容均不同,不构成本 README 统计问题的重复。
  • GitCode 只读检索未发现同题 Issue/MR。Issue #2 是公共硬件知识重复反馈,#3 是路线图,#7
    是 Markdown 表格格式问题,#8/#62 是贡献流程文档;MR !55 为检索分词与 IDF,MR !58 为索引
    导航摘要生成器且明确不含 knowledge/ 变更,均未更新 README 数量快照。相关对象均不覆盖本案。

影响和修复边界

README 的总数和分类数会误导贡献者、维护者和使用者对知识覆盖规模的判断。最小修复只更新
“当前知识状态”数量段,明确按 Frontmatter type 与 Bundle 路径统计所有非 index.md 卡片;
不改知识卡、索引生成器或运行时行为。

Validation

验证

固定边界

  • 仓库:cann/cannbot-knowledge
  • 远端分支:master
  • 源码提交:dbc65f95164cde0beabb4da1e86aeecde3c2df26
  • 固定 checkout 在检查时为 clean;本次没有修改源码 checkout。

只读复算

以下命令均在固定源码 checkout 执行,未修改源码文件:

  • git ls-remote origin refs/heads/master(退出码 0)→
    dbc65f95164cde0beabb4da1e86aeecde3c2df26。
  • git rev-parse HEAD(退出码 0)→ 与目标提交一致;git status --short 为空。
  • git ls-tree -r --name-only HEAD knowledge | rg '\.md$' | wc -l(退出码 0)→ 7,706。
  • git ls-tree -r --name-only HEAD knowledge | rg '(^|/)index\.md$' | wc -l(退出码 0)→ 662。
  • git ls-tree -r --name-only HEAD knowledge | rg '\.md$' | rg -v '(^|/)index\.md$' | wc -l
    (退出码 0)→ 7,044。

独立 Python 3 逐卡读取 Frontmatter type 并按 Bundle 路径归类,退出码 0:API 2,993、
Guide 1,100、Operator 611、Runbook 1,502、Concept 204、Optimization 611、Example 23,合计
7,044;Frontmatter 解析/缺失错误为 0。路径拆分见 report.md。索引实现
.agents/skills/knowledge-query/scripts/retrieval/index.py:137-140 递归枚举
knowledge/**/*.md 并排除 index.md,与上述分母一致。对 7,044 张卡计算 SHA-256 后,完全重复
内容组为 0。

Lint 与 patch

  • python3 .agents/skills/knowledge-lint/scripts/knowledge_lint.py --knowledge-root . --json
    → 退出码 0,checked=7706,findings=[]。
  • git diff --check → 退出码 0;固定源码 checkout 保持 clean。
  • 更新后的 fix.patch 是针对固定提交的零上下文 README-only 删除补丁,删除“当前知识状态”章节及其
    过期数量/来源说明;在更新后的源码 checkout 上执行反向应用检查退出码 0。
  • 未运行 knowledge_index build:只读树枚举与 Lint 已覆盖本案统计口径;索引构建会写入可重建产物,
    对确认 README 快照陈旧并非必要。

结论

统计口径、分类合计和公开 README 旧快照均可复核,候选为明确的文档缺陷;未宣称 NPU、构建或
索引运行时验证。

维护者跟进

  • 2026-09-24,维护者指出知识数量变化频繁、快照容易滞后,并明确建议删除 README 的“当前知识状态”章节。
  • 按请求删除该完整章节,保留相邻的 OKF 设计参考与“这个仓库如何工作”内容;源码变更仅涉及 README.md。
  • git diff --check 通过。更新后的补丁以固定源码提交 dbc65f95164cde0beabb4da1e86aeecde3c2df26 为基线,删除章节中的旧统计及相关说明。
  • 旧 PR head 的 CI 通过不适用于本次更新;新 head 推送后重新触发 CI。

关联 PR: https://gitcode.com/cann/cannbot-knowledge/merge_requests/64

likedislike
KaranocaVeKaranocaVe
23 天前 关联了pull request:[文档] 更新 README 当前知识卡数量统计
KaranocaVeKaranocaVe
23 天前 修改了issue 的描述
KaranocaVeKaranocaVe
23 天前 修改了issue 的描述
汪汪超成员
23 天前 issue状态由 进行中 改变为 已解决
汪汪超成员
23 天前 关闭了 issue
CANN-robotCANN-robot成员
23 天前 添加了label:resolved