企业官网建设流程全解析

cannbot-knowledge公共组件变更机制：RFC与A/B实验流程完全讲解

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

cannbot-knowledge 是 CANNBot 智能体的知识底座仓库，它为 AscendC/PyPTO/TileLang/Triton 等算子开发场景提供统一、可追溯的知识卡与检索货架。当你要改动它的公共组件——比如检索 Skill、索引、治理规则或安装器——就必须走一套严格的变更机制：先提交 RFC 说明方案，再完成可复现的 A/B 实验，最后提交关联 PR。本文把这套流程拆成可照做的步骤，帮你一次理解、一次做对。

一、先判断走哪条贡献路径：3 类贡献 3 条路 🧭

cannbot-knowledge 的贡献入口分三类，选错路径会浪费大量时间。完整定义见 CONTRIBUTING.md：

只有第二类需要 RFC + A/B。知识错误、检索脚本 bug 等缺陷修复可直接提交 PR，无需前置 Issue/RFC 或完整 A/B 实验；纯排版、错别字修订同样适用简化路径。

💡 注意：如果一次修复里混入了新增能力或主动流程调整，必须拆分——新能力部分另走 RFC 流程。

二、公共组件边界：哪些改动算“公共组件变更”

RFC 流程覆盖的是多人共用的机器能力，包括：

• 检索 Skill 的触发条件、流程与权限边界；
• Query 的过滤、排序与索引；
• Ingest/Lint 行为、治理机器规则；
• 安装器、图谱、评测或 CI 工具。

这些组件的规范源分布在 governance/contracts/（校验实现）、governance/schemas/（机器可读规则）和 evals/（治理、安装、检索与 CI 回归）。修改它们时遵循一条总原则——扩展优先、保持兼容：

• 新增能力优先通过现有扩展点或可选配置接入，保留原有默认流程和对外契约；
• 内部重构可以改原实现；
• 确需主动调整默认流程、接口或既有行为时，RFC 必须单列：扩展方式为何不足、受影响场景、迁移与回退方案。

三、RFC 提交指南：3 个必答板块 ✍️

RFC 使用本仓 Issue 承载，标题包含[RFC]。RFC 阶段可以先提交问题和方案；采用 RFC 流程的组件 PR 提交前，须回填已完成的实验报告。正文按三大板块组织：

1. 当前问题与修改必要性受影响的组件、用户与具体场景；当前行为、复现输入、基线版本和证据；问题的频率或影响——为什么现有能力、配置或工作流不能满足需求？

2. 目标与方案期望改变的行为、范围与不包含的范围；设计与实现（输入输出、依赖、涉及的事实源和消费者）；扩展接入方式；替代方案取舍；如适用，既有行为变更的迁移与回退。

3. A/B 实验计划与结果假设与验收标准、A 基线与 B 候选、数据集、执行方法、实测结果与结论。

一个细节值得留意：新增组件时，A 基线是“当前完成同一任务的方式”；如果当前根本无法完成，就记录失败行为和成本，避免只展示 B 的成功样例。

四、A/B 实验 6 步法：让结果可复现 🔬

A/B test 指旧方案与候选方案在同一任务集上的对照实验，可以离线进行。实验报告至少交付 6 项材料：

三条红线：

• 未执行、仅有实验计划或只报告 B 的结果，都不能标为实验通过；
• 不得事后降低验收标准而不解释；
• 可复用评测用例放在 evals/，本地可重建报告放在 Git 忽略的artifacts/，RFC/PR 中保留结果摘要和评审者可访问的完整报告。

五、检索 Skill 指标怎么选：4 维口径速查 📊

修改检索、排序、过滤这类 Skill 时，按以下口径组织对照，并按 RFC 目标选定主指标：

• 检索质量：固定 k，报告 Hit@k（前 k 个结果至少命中一张期望卡的查询占比）和/或 MRR（首张期望卡排名倒数的均值，未命中记 0）；目标问题和既有成功问题分别报告。
• 过滤与边界：错误平台、错误技术、draft/deprecated 默认范围、无匹配结果、缺失/损坏/过期索引的处理，报告违反次数。
• 开销：相同机器、语料和负载下报告查询耗时 p50/p95；索引变更补构建时间和体积，涉及 Agent 调用补 token 成本。
• 下游效果：影响证据召回、排序、查询改写的变更，须补代表性端到端算子生成对照——固定模型、提示词、语料、任务与生成预算，只替换待评估的检索模块，报告编译通过率、数值正确率等，失败与超时保留在分母内。

记住一条边界：检索指标提升不能直接推导任务成功。仅索引、缓存等工程优化若能证明检索结果和行为一致，可只做检索回归与性能对照；无法证明时补端到端验证。

其他组件按职责选指标：Lint 规则比较同一批合法/非法输入的接受与拒绝行为；安装器比较成功率、幂等性和失败时的文件保护；Ingest 比较有效产物比例、内容保真和写入边界。

六、PR 提交与 committer 检视：最后的门禁 🚦

实现完成后按 5 步交付：

1. 关联 RFC，按方案修改规范源；涉及治理规则时先改唯一机器事实源，再同步消费者；
2. 更新受影响的文档和测试；
3. 验证结构、触发条件、原有路径、新增能力、错误路径和权限边界；
4. 完成 A/B test 并回填 RFC，记录当天变更日志（见 logs/）；
5. 提交关联 RFC 的 PR，由 committer 检视后合入。

PR 材料要让评审者沿“问题 → 方案 → 产物 → 证据”核对：RFC 方案、A/B 版本、实验报告链接、关键指标与验收结论，以及默认流程/接口/行为是否变化。提交前统一运行质量门禁：

bash check.sh

committer 重点核对：RFC 是否解释必要性与方案取舍、主动行为调整是否说明迁移与回退、原有路径与新增能力是否均有验证、A/B 是否达到预设标准。自动检查通过只证明所覆盖的检查通过，不能代替内容与效果检视。

七、快速自查清单 ✅

• 这次改动属于公共组件变更，而不是知识建设或缺陷修复？
• RFC 说明了问题、必要性和“扩展为何不足”？
• 实验阈值是实验前设定的，不是事后调整的？
• A、B 两组控制变量一致，失败样本也保留了？
• 原有默认路径和新增能力都有验证证据？
• 当天logs/记录了实质变更？
• bash check.sh通过？

更多背景可阅读：README 贡献与检查、设计原则、Agent 工作约定 和 OKF 规范说明。

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