cannbot-knowledge 治理体系深度剖析Schema、Profile、Registry 与 Contract 的 5 层分工【免费下载链接】cannbot-knowledgecannbot算子开发知识库插件依赖的知识库本体仓给cannbot提供统一的知识底座。项目地址: https://gitcode.com/cann/cannbot-knowledgecannbot-knowledge 是 CANN 算子开发知识库的治理底座仓它为 cannbot 提供统一的知识底座。本文将带新手快速看懂它的 5 层治理分工Schema字段形状、Profile字段组合、Registry受控词表、Contract跨文件检查以及Checks Indexes分类执行与索引生成帮你彻底搞懂这张知识卡片背后的质量防线是怎么搭起来的 。为什么知识库需要一套治理体系想象一下几千张 Markdown 知识卡片概念、API、算子、Runbook散落仓库如果没人管——字段名五花八门搜索召回直接失效平台、标签随手乱写过滤结果不可信目录索引过期链接断掉读者迷失在知识迷宫里草稿和废弃结论混在一起下游工具拿到错误答案。cannbot-knowledge 的解法是把规则写成机器可执行的声明把检查收敛到唯一的 Contract 入口。核心原则只有一句同一规则只能有一个机器事实源——字段形状归 JSON Schema字段组合归 Profile受控值归 Registry跨字段/跨文件关系归 Contract。完整语义解释见 governance/specs/schemas.md。5 层治理架构一图总览层文件负责什么不负责什么① Schemafrontmatter.schema.jsonFrontmatter 字段白名单、数据类型、数组形状、基础枚举不按路径选择字段不保存平台/标签词表② Profileprofiles.yaml8 个公共必选字段、Profile→OKFtype映射、字段组合不定义字段类型不判断路径合法性③ Registryregistries.yamldomain、route、platform、标签等受控词表不保存知识正文或变更历史④ Contractknowledge.py加载声明为 Ingest/Query/Lint 提供统一入口不重复实现各检查类别⑤ ChecksIndexescontracts/checks/、indexes.py按路径、来源、导航等类别做确定性检查生成索引不保存平行枚举不决定 CI 展示第 1 层Schema——Frontmatter 的字段形状每张知识卡片头部都有 YAML Frontmatterfrontmatter.schema.json 基于 JSON Schemadraft 2020-12定义了它的形状白名单制additionalProperties: false未登记的字段直接拒绝类型与形状tags必须是 2–6 个不重复字符串status只能是draft/stable/deprecated嵌套对象约束sources[].resource必选verified的by/at必选。⚠️ 注意Schema 只认形状不认语义。比如title为空字符串Schema 管不了那要交给下一层的 Profile 检查。执行器是自研的 SchemaValidator采用失败即关闭fail-closed策略连 Schema 文件本身用了不支持的关键字都会被拒。第 2 层Profile——由路径决定字段组合Profile 的核心逻辑是你放在哪个目录就必须写哪些字段、声明什么类型。profiles.yaml 中common_required声明 8 个公共必选字段type、title、description、tags、status、sources、created_at、updated_at每个 Profileconcepts、apis、runbooks、operators等再追加自己的必选字段并映射到唯一的 OKFtype。举个例子 # 放在 apis/ 目录的卡片 → Profile 决定它 type: API # 必须是 API不能自由改成别的 platforms: [a3] # Profile 强制要求路径 ProfileOKFtype额外必选字段conceptsConceptplatformsapisAPIplatformsrunbooksRunbookplatformsinteroperabilityInteroperabilityplatforms 源/目标技术glossariesGlossary无这套路径即类型的设计来自 OKF Bundle 规范详解见 governance/specs/okf.md 和 governance/specs/frontmatter.md。第 3 层Registry——受控词表拒绝自由发挥registries.yaml 是多个工具共享的小型字典主要分区domainsops算子、model模型、common、graph、runtime五大知识域technologiesascendc、triton、tilelang、pypto等技术栈路由scopesshared、platforms、inference、training等非技术维度platformsa2、a3、950、310p、agnostic等平台 IDtagstask.*任务、topic.*主题、paradigm.*范式三维标签体系local_sources登记固定到具体 commit 的本地源码来源如cann-ops-raw/ascendc/ops-nn保证证据可回溯。已注册≠必须建目录注册只是让工具认识它。Registry 加载时的自检非常严格technology 与 scope 的 ID 不允许重叠、每个 route 必须声明所属 domain、标签前缀必须与维度一致详见 knowledge.py 中的注册表契约校验逻辑。第 4 层Contract——跨字段、跨文件的关系裁判JSON Schema 只能看单个对象的形状但很多规则是关系型的必须由 Contract 统一裁定从路径推导出 domain、technology/scope、Profile 和 Concept ID校验卡片type必须等于 Profile 声明的okf_type判断 route 与 domain 的组合是否被允许要求tags同时覆盖task.*和topic.*限制agnostic平台不能与具体平台混用比较created_at与updated_at的时间先后校验verified事件、replaced_by指针和跨技术端点。Contract 还内置了防坑细节YAML 解析使用 UniqueKeySafeLoader拒绝重复 key避免解析时静默覆盖规则。它只保留一个门面把 Ingest写前拒绝、Query加载失败关闭、Lint只读报告三个消费者统一接到同一套规则上杜绝各写一套例外。第 5 层Checks 与 Indexes——分类执行 索引生成最底层是干活的手contracts/checks/把检查拆成职责单一的模块path.py路径合法性、profile.pyProfile 字段、tags.py标签覆盖、links.py链接可达、lifecycle.py时间线、trust.pyverified 信任层级、images.py图片合规等并按 P0–P2 等级注册indexes.py负责生成并比较直接子项索引每个目录的index.md必须准确列出直接子卡片及摘要Ingest 与 Lint 共用同一份生成逻辑不写文件、不重复实现。这条分工链与 governance/specs/paths.md 中的路径规范互为表里Spec 解释语义和贡献边界机器文件才是事实源。5 层如何协作一次完整的校验之旅知识路径 Frontmatter │ ├─ Schema字段形状对不对 ├─ Profile这个目录该写哪些字段 ├─ Registry平台/标签/路由注册过吗 ├─ Contract跨字段、跨文件关系成立吗 └─ Checks Indexes分类检查 索引同步 │ ┌─────┴─────┬──────────┐ ▼ ▼ ▼ Ingest Query Lint 写前拒绝 加载失败关闭 只读报告日常维护时不需要逐个理解每个检查器直接运行仓库的统一质量入口 check.sh它依次执行知识 Lint、索引同步检查、检索索引构建与验证、检索回归和单元测试一次跑完所有治理层。新手贡献知识卡片的 3 条实用建议先选路径再写字段想好卡片属于concepts还是apisProfile 会自动决定你的type和必选字段别试图自己发明映射只用注册过的值平台、标签去 registries.yaml 里查找不到就提变更而不是随手造词贡献前读规范字段与证据的完整规则在 governance/specs/frontmatter.md贡献流程见 recipes/contribute_knowledge.md。总结cannbot-knowledge 的治理体系可以浓缩为一张图Schema 管形状Profile 管组合Registry 管取值Contract 管关系Checks 管执行。五层各司其职、单一事实源使得几千张知识卡片的结构一致、取值受控、引用可达——这正是它能作为 cannbot 可靠知识底座的原因。理解这 5 层分工后你再看任何一张卡片的 Frontmatter都会知道每个字段是被哪一层规则守护着的 ✅。【免费下载链接】cannbot-knowledgecannbot算子开发知识库插件依赖的知识库本体仓给cannbot提供统一的知识底座。项目地址: https://gitcode.com/cann/cannbot-knowledge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考