cannbot-knowledge知识卡生命周期与信任层级：draft、stable、deprecated与verified全解

cannbot-knowledge知识卡生命周期与信任层级：draft、stable、deprecated与verified全解

【免费下载链接】cannbot-knowledgecannbot算子开发知识库插件依赖的知识库本体仓，给cannbot提供统一的知识底座。项目地址: https://gitcode.com/cann/cannbot-knowledge

cannbot-knowledge 是 CANN 社区 CANNBot 算子开发知识库的"本体仓"，为算子开发智能体提供统一的知识底座。本文带你一次看懂它治理知识卡的两个核心字段：status（draft / stable / deprecated 生命周期）与verified（unverified / machine-confirmed / human-reviewed 信任层级），以及它们如何被自动检查守住。

1. 什么是知识卡：cannbot-knowledge 的统一知识底座

cannbot-knowledge 不把算子工程代码当正文提交，而是把可追溯的工程结论整理成 Markdown知识卡：正文讲结论、适用条件与失效边界，文件开头的 Frontmatter 保存类型、平台、版本、生命周期和来源等结构化信息。CANNBot 通过knowledge-query等 Skill 检索这些卡片，复用经过治理的结论。

中可见，本仓是整个 CANNBot 仓群中唯一保存技术知识正文的地方，所有卡片都位于knowledge/目录下。

仓库整体工作流是：官方文档 / 固定版本源码 / 可复现实验 → Ingest 生产 Markdown 知识卡 →knowledge-lint检查结构与治理规则 →knowledge-query检索 → CANNBot 阅读正文并核对来源。理解这条链路后，再看生命周期与信任层级就不难了。

2. 生命周期：draft、stable、deprecated 三种状态怎么定

每张非index.md知识卡都必须显式填写status字段，且只允许三个取值（机器事实源见 frontmatter.schema.json）：

几个新手最容易踩的点：

• draft 不等于"质量差"，只是"还不能被检索到"——platforms: []（适用范围未确认）只允许出现在 draft 卡上；
• 确认错误但仍需解释历史行为的卡片也用deprecated，并在正文和当天日志说明原因，而不是直接删除；
• 完整规则见 Frontmatter 与证据。

2.1 deprecated 卡片必须用replaced_by指路

一旦填写replaced_by，Lint 会强制以下约束（实现见 lifecycle.py）：

• status必须是deprecated，否则报status.replaced_by错误；
• 值必须是 Bundle 内不带.md的规范 Concept ID，如ops/ascendc/apis/new_api，不能以/或knowledge/开头、不能含..；
• 目标必须是一张真实存在的知识卡，不能指向自身、index.md，也不能经符号链接越出 Bundle。

也就是说：废弃不是终点，而是一次"带路"——读者总知道去哪里找当前结论。仓库中真实的 deprecated API 卡片例如 v1版本TilingData（废弃），正文顶部直接标注了"该结构体废弃，请使用 HCCL Tiling 提供的接口"。

3. 信任层级：verified 字段与三级可信度

status回答"这张卡能不能被检索"，verified回答"这张卡被谁核实过"。它使用 OKF verification event，记录真实发生过的复核：

verified: - by: human:reviewer_id at: "2026-08-15T08:00:00Z"

• by（actor）只允许三种形式：human:<id>、process:<id>或<producer>/<version>；
• 单个事件可写成 mapping，多个事件用数组；查询侧会统一解释为事件列表。

根据事件内容，卡片落入三个信任层级：

两条红线值得记住：

1. status与信任层级相互独立——stable+ 有sources不等于人工复核过；
2. 不能伪造验证：Lint（trust.py）只校验 actor 格式，"Lint 通过""固定来源"都不能自动转换成 verified 事件。

4. 实战：如何读懂一张真实知识卡的 Frontmatter

拿一张 API 卡看完整生命周期字段，一目了然：

type: API title: v1版本TilingData（废弃） tags: [task.lookup, topic.implementation.api_layer.high_level_api] status: draft # 生命周期：草稿，默认查询不返回 sources: # 证据入口：本地登记来源，指向原始文档 - resource: cann-docs-raw/asc-devkit/docs/zh/api/SIMD-API/adv_api/HCCL_communication/HCCL_Tiling/v1_TilingData_deprecated.md role: primary created_at: '2026-08-18T14:51:00Z' updated_at: '2026-09-12T03:09:26Z' platforms: [] # 空数组只允许 draft

对照 lifecycle 检查规则 就能推出它的状态：无replaced_by、无verified→ 这是一张draft + unverified的卡，等待来源补齐和范围确认后升级为stable。

写卡时的建议顺序：先 draft 立卡 → 补全 sources 与平台范围 → 人工复核写入 verified → 升 stable → 结论过期后标 deprecated 并填 replaced_by。贡献流程详见 贡献知识。

5. 自动检查如何守住这些规则：knowledge-lint

规则不止写在文档里，而是被 Contract 统一执行，且每条规则只在一个机器文件中定义：

提交前运行仓库统一入口即可触发全部检查：

bash check.sh

它执行知识 Lint、导航检查、索引与检索回归、单元测试等，保证生命周期与信任字段"写了就合规"。规则体系总览见 Schema、Registry 与 Contract，设计动机见 设计原则——其中明确写道："稳定""有来源""经过复核"不是一回事。

6. 常见疑问（FAQ）

Q1：stable的卡片可以直接照抄结论吗？不能。Query 只按平台和技术范围过滤并返回候选，当前不按 CANN 版本过滤；使用前仍需打开正文核对版本边界、平台适用范围和来源。

Q2：为什么我搜不到刚写的卡？大概率status还是draft（或deprecated）。两者默认都不被 Query 返回，补齐来源和范围后升为stable即可被检索。

Q3：卡片结论错了怎么办？标deprecated、填replaced_by指向修正后的卡片，在正文和当天日志说明原因——历史引用不断链。

Q4：sources有内容就能算"已验证"吗？不算。sources回答"结论能回到哪里核验"，verified才记录"谁在何时复核过"，两者独立。

7. 延伸阅读

• Frontmatter 与证据（生命周期/信任/来源/标签完整规范）
• OKF Bundle 与 CANNBot Profile
• 形成可追溯回答（检索与证据实践）
• 安装与使用指南

掌握status三态与verified三级信任后，你既能看懂每张知识卡"现在能不能用、被谁信过"，也能在贡献知识时一次通过 Lint，成为 CANNBot 知识底座上可靠的写作者 🚀

【免费下载链接】cannbot-knowledgecannbot算子开发知识库插件依赖的知识库本体仓，给cannbot提供统一的知识底座。项目地址: https://gitcode.com/cann/cannbot-knowledge