企业官网建设流程全解析

cannbot-knowledge贡献指南：从提交知识Issue到PR合入的完整流程教程

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

cannbot-knowledge 是 CANN 社区的算子开发知识库，为 CANNBot 提供统一的知识底座。这篇贡献指南教程带你走完完整流程：从提交知识 Issue、生产 Markdown 知识卡，到通过质量门禁提交 PR，最终由 committer 检视合入，7 个步骤即可上手。

CANNBot知识库cannbot-knowledge仓库群结构示意图，cannbot-knowledge作为知识库检索货架

1️⃣ 三种贡献类型，先选对路径

动手前先判断你要做的是哪类贡献，流程要求完全不同（详见 CONTRIBUTING.md）：

本文聚焦最常见的知识建设路径，这也是大多数新手第一次贡献的入口。

2️⃣ 准备环境：安装 contributor 模式

贡献者需要安装contributor模式，它比查询模式多了knowledge-ingest、knowledge-lint等写入类 Skill：

git clone --branch master https://gitcode.com/cann/cannbot-knowledge cd cannbot-knowledge bash install.sh claude /path/to/project contributor

更多安装选项（自定义位置、Python 环境、离线安装）见 安装与使用指南。

3️⃣ 第一步：提交知识 Issue——缺什么、怎么产生、有什么效果

写卡前先搜索同主题知识和已有 Issue，再用"知识需求"表单提交 Issue，核心回答三部分：

• 知识缺口：谁在什么任务中遇到什么问题？现有检索缺了什么？当前影响是什么？
• 知识生产方案：处理方式（create / update / merge / split / deprecate / defer）、候选来源（官方文档、固定提交源码、可复核实验）、生产方法与复核方式；
• 预期效果与验收：贡献后能回答什么问题，给出至少一个可复核的目标场景（输入条件 + 预期结果）。

💡 "增加若干张卡"只说明工作量，不能说明效果。未测量前，收益要保留为"预期"，不要写成已验证结论。

4️⃣ 搜索已有知识，决定处理方式

用knowledge-query搜索同一主题，明确本次是哪种操作：

不要仅因标题不同就创建新卡，也不要自动覆盖原卡。

5️⃣ 编写知识卡：路径、Frontmatter 与正文

选择路径——知识正文只能进入knowledge/，常规形态为：

knowledge/<domain>/<technology-or-scope>/<profile>/<slug>.md

例如knowledge/ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division.md：ops是领域，ascendc是技术，apis是路径 Profile，文件名用稳定的小写snake_case。完整规则见 知识路径规范。

填写 Frontmatter——所有非index.md卡片必须包含 8 个公共字段：type、title、description、tags、status、sources、created_at、updated_at。type由路径 Profile 唯一决定，不要自行创造类型。字段语义见 Frontmatter 与证据。

编写正文——让读者不依赖来源原文也能判断结论，覆盖 5 点：

1. 核心结论或适用场景；
2. 必要的机制、参数或操作步骤；
3. 平台、版本、shape、dtype 等边界；
4. 验证方式及证据强度；
5. 与其他卡片的显式相对链接。

⚠️ 两张"红线"：一个 DSL 的经验不能直接写成另一个 DSL 的事实；搜索摘要、聊天记录或模型记忆不能单独作为技术来源，每张卡的sources必须能定位到支持结论的证据。

6️⃣ 更新导航与日志，跑通质量门禁

写完卡不等于完成，还要同步：

• 新增、删除或移动卡片时，逐层更新受影响的index.md导航；
• 实质知识变更记录到当天logs/；
• 运行全库检查，修复路径、字段、导航、链接、来源问题。

提交前在仓库根目录执行统一质量门禁：

bash check.sh

它执行知识 Lint、导航检查、索引与检索回归、单元测试与静态检查，入口脚本见 check.sh。

7️⃣ 验证效果，提交关联 PR

回到 Issue 中的验收场景验证：保留原始问题、查询条件、贡献前的缺口、贡献后命中的卡片与正文依据，确认新知识能被检索到、且不会出现在错误范围内。

PR 正文按"问题 → 方案 → 产物 → 证据"组织，三部分缺一不可：

• 关联与范围：贡献类型、关联 Issue、实际改动文件；
• 交付与效果：处理决定、来源、生产方法、验收场景及实际结果；
• 检查与评审重点：执行的检查与结果、已同步的导航/日志、需要 committer 重点判断的风险。

✅ committer 检视与合入条件

committer 会核对：Issue 中的缺口是否真正解决、来源与平台版本范围是否支撑结论、有无重复或过度泛化、目标场景效果是否可复核。合入前必须满足：

• 对应贡献类型的材料完整，验收标准达成；
• 阻断性评审意见已解决；
• 当前版本的bash check.sh通过；
• 获得 committer 明确认可后由其执行合入，并回填关联 Issue。

🚫这些贡献会被拒绝：无可靠来源的性能或默认行为结论、大段复制上游文档、把单一技术经验过度泛化为 shared、把一个 DSL 的行为写成另一个 DSL 的事实、静默删除过时知识。

按以上 7 步完成你的第一张知识卡，你的工程经验就能被 CANNBot 和整个社区持续检索复用。完整操作清单见 贡献知识最佳实践，设计取舍可延伸阅读 知识库设计原则。

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