cannbot-knowledge 贡献指南

本文只说明贡献流程和交付要求。环境安装与 contributor 模式见安装与使用指南；字段、路径与受控值的完整定义由 governance/ 维护，Skill 的内部命令与参数由各 Skill 自身文档维护，避免在多处复制同一规则。

贡献包含两条常规流程，以及缺陷修复与轻量修订的简化路径，均由贡献者提交材料、committer 检视后合入。本文中的 committer 指本仓有合入权限、负责评审的维护者。

贡献类型	流程	评审重点
知识建设（缺陷修复除外）：新增、补充、合并、拆分或废弃知识	提交知识 Issue → 生产知识并验证效果 → 提交关联 PR → committer 检视、合入	缺口是否真实、知识如何产生、证据是否充分、能解决什么问题
公共组件新增、优化或主动行为调整（缺陷修复除外）：检索 Skill、索引、摄入、校验、安装、评测等公共能力	提交 RFC → 实现方案并完成 A/B test → 提交关联 PR → committer 检视、合入	修改是否必要、方案是否合理、实验是否可复现、收益与回归是否可接受
缺陷修复：知识错误、检索脚本 bug 等；轻量文档修订	直接提交 PR → committer 检视、合入	问题与修复依据是否清楚，验证是否证明问题得到修复，有无引入回归

RFC（Request for Comments）使用本仓 Issue 承载，标题包含 [RFC]，正文按第 5 节组织。首版沿用现有 Issue/PR 表单，在正文中补齐对应贡献类型的材料。已有 Issue 可以补齐材料后复用；同时涉及常规知识建设和公共组件变更时，分别说明验收依据并关联对应 Issue/RFC，可独立交付的改动拆成 PR。缺陷修复与轻量修订按第 2.1 节直接提交 PR。

1. 规则从哪里读取

需要确认的内容	事实源
字段类型和顶层白名单	`governance/schemas/frontmatter.schema.json`
各路径 Profile 的 OKF `type` 和字段组合	`governance/schemas/profiles.yaml`
domain、technology/scope、platform、tag 和路径分类	`governance/schemas/registries.yaml`
跨字段、跨文件和路径校验	`governance/contracts/`
规则语义和贡献边界	`governance/specs/`
OKF 设计来源和兼容边界	`governance/specs/okf.md`
Skill 触发、流程和内部执行接口	`.agents/skills/<skill>/`

Schema、Profile、Registry 和 Contract 共同构成机器规则，Spec 是解释层。两层不一致时，应先在同一变更中修正规则、消费者和测试，再继续写卡；不得通过单个 Skill 的临时例外绕过契约。

2. 通用原则

可追溯：技术结论能回到官方文档、固定提交源码、测试或可复核实验。
经过蒸馏或受控转换：知识卡通常表达可复用结论；Registry 文档归档的官方 API/Guide 只保留含独立技术事实的来源页，并按声明省略冗余章节。
范围明确：正文和 Frontmatter 共同说明技术栈、平台、版本、验证范围和失效边界。
DSL 隔离：一个 DSL 的接口、编译器行为和实验结果不能直接写成另一个 DSL 的事实。
最小变更：只修改相关知识、导航、规则、Skill 和测试。
可复现：提供实际完成的查询、校验、测试或最小实验结果。
安全：不得提交密钥、Token、账号、内网地址、私有路径或不可公开数据。
许可合规：根目录 Shell、governance/ 与 evals/ 中的非空 Python/YAML 文件使用仓库标准 CANN 2.0 许可头；带 shebang 的文件保持 shebang 为首行。
不自动发布：仓库脚本和 Skill 不得自动 commit、push、合并或发布。

集合型目录使用复数，例如 references/、scripts/、schemas/、specs/、evals/、artifacts/ 和 logs/。

2.1 缺陷修复与轻量修订

知识错误修正、检索脚本 bug 等纠正错误或恢复既定行为的贡献，可直接提交修复 PR，无需先提交 Issue/RFC，也不要求完整 A/B 实验。PR 说明问题、修复内容和影响，并提供相应证据与定向验证结果：

知识修正：指出错误结论及修正依据，提供支持新结论的来源或可复核观测，并验证受影响场景。
工具或脚本修复：提供复现方式、预期行为、修复结果及相关回归结果。
纯排版、错别字和不改变组件行为的说明文档修订：说明修订内容，运行适用的文档检查。

已有 Issue 可按需关联，不作为前置要求。简化路径仍需满足适用的来源、导航、日志和检查要求，上库前执行 bash check.sh，由 committer 检视后合入。修复中若包含新增能力或主动流程调整，应拆分后按对应流程贡献。

3. 贡献知识

以下内容规范和检查适用于知识建设与知识错误修复；第 3.1 节的前置 Issue 仅用于常规知识建设，缺陷修复直接在 PR 中提供第 2.1 节要求的材料。

3.1 先提交知识 Issue：缺什么、怎么产生、有什么效果

先搜索同主题知识和已有 Issue，阅读相关卡片，再提交或补充知识 Issue。可以在现有“知识需求”表单中补充以下正文；仅反馈缺口但暂不认领实现时，将未知项标为待补充，不能把推测写成已验证结果。

### 知识缺口

- 使用场景：谁在什么任务中遇到了什么问题？
- 适用范围：领域、技术、平台和必要的版本信息。
- 现有检索：查询词、筛选条件、命中卡片；现有内容缺失、错误或不足之处。
- 当前影响：缺口导致哪些无法回答的问题、失败或重复工作？

### 知识生产方案

- 处理方式：create / update / merge / split / deprecate / defer 及理由。
- 候选来源：官方文档、固定提交源码、可复核实验或开发轨迹；注明版本和获取方式。
- 生产方法：人工整理或使用哪个 Skill，如何从来源得到结论，如何复核。
- 预期产物：目标知识卡或主题范围，需要同步的导航和链接。
- 证据缺口：尚未确认的结论、范围，以及补证方法。

### 预期效果与验收

- 预期效果：贡献后应能回答什么问题、完成什么操作或避免什么错误？
- 验收场景：具体问题或任务、输入条件、预期答案要点或行为。
- 验证方法：如何核对来源、验证召回；必要时如何复现技术结论。
- 效果证据：实施后回填相同场景下的实际结果、证据位置和仍未覆盖的边界。

“增加若干张卡”只能说明工作量，不能单独说明效果。至少给出一个可复核的目标场景，例如在指定平台和技术条件下，用某个真实问题能找到支持答案的卡片，并从正文确认适用条件。声称提升成功率、减少耗时或改善性能时，应给出对应的测量方法和实际证据；尚未测量的收益保留为预期。

Issue 建立后，按下列步骤生产知识，在关联 PR 中回填实际产物和验收结果。来源不足时可继续在 Issue 中讨论或选择 defer，不以占位卡代替知识。

3.2 决定如何处理现有知识

写卡前先使用 knowledge-query 搜索同一主题，并明确本次决定：

create：没有同主题卡，新增一张；
update：原卡职责不变，补充或修正内容；
merge：多张卡职责重叠，合并为一个稳定入口；
split：一张卡混合多个独立职责，拆分后分别维护；
deprecate：结论仍可解释历史行为，但不再推荐；
defer：来源、范围或验证仍不足，暂不落库。

已确认错误的结论也使用 deprecated，并在正文和当天日志明确说明撤回原因；Git 历史保留原结论和更改过程。

不要仅因标题不同就创建新卡，也不要用自动覆盖替代对原卡的完整审阅。

3.3 选择路径

知识正文只能进入 knowledge/。常规路径为：

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

部分 domain 允许直辖 Profile；内容型 Profile 可以增加主题 section，Operator 和 Runbook 则使用受控附加层级。完整 domain-route 矩阵、Profile 说明和合法示例见知识路径。

选择路径时遵守：

目录表达知识适用于哪里，不按来源网站或生产批次分类；
slug 使用稳定的小写 snake_case；
Registry 中注册的所有 domain 根目录由 Contract 统一维护；只有 ops 和 model 预建注册 route。其他下一层路径随首张真实知识创建，不要提前铺设空 route/Profile；
operators/ 使用受控 family/category；
runbooks/ 使用受控问题域；
concepts/、apis/、examples/、guides/ 和 optimizations/ 的主题 section 使用小写 snake_case，并逐层维护索引；
稳定原理进入 concepts/，接口事实进入 apis/，任务型教程进入 guides/，完整算子进入 operators/，性能方法进入 optimizations/，处置流程进入 runbooks/。

3.4 区分 shared、技术专属和 interoperability

技术专属目录保存依赖该 DSL、框架、编译器或 API 的知识。只有不依赖单一技术实现、且能明确说明复用条件的结论才能进入同领域 shared/。

两种技术之间的对应关系进入 shared/interoperability/，必须说明：

来源技术与目标技术；
可以保留的设计意图；
必须重新推导或验证的部分；
目标技术上的验证证据和当前信任层级。

其他技术栈中的成功经验只能作为线索，不能自动成为目标技术的已验证证据。

3.5 准备来源

每张卡都必须填写 sources。轨迹沉淀的 Runbook 可以使用 sources: []，但正文必须保留与结论强度相匹配的触发、探针、原始观测和验证信号，且不能把中间整理仓或会话轨迹伪装成权威 resource；其他非 draft 卡至少有一个精确 resource。

Git 来源固定到提交；普通文档来源优先使用稳定版本页，Registry 登记的滚动文档归档则使用其官方归档 URL。仓库相对来源必须位于 Registry 登记的本地来源根目录，并由登记的文档归档 URL 或 Git repository/40 位 commit 获取流程恢复；不能指向未登记根目录、工作区外部或包含路径穿越。性能、精度、平台限制、默认行为和经验性结论必须有与结论强度相匹配的证据。

搜索摘要、PR 标题、聊天记录或模型记忆不能单独作为技术来源。来源角色、固定格式和人工审阅要求见 Frontmatter 与证据。

3.6 填写 Frontmatter

所有非 index.md 卡片统一包含八个公共必选字段：

type
title
description
tags
status
sources
created_at
updated_at

额外字段由路径 Profile 决定。type 必须写入，但其值由 Profile 的 okf_type 唯一决定；不要在卡片中自行创造类型，也不要重复填写可从路径推导的 domain、technology/scope 或 Concept ID。

模型推理知识先区分机制、优化决策、任务流程和故障诊断，再按路径规范选择入口。同一规则只维护一份正文，案例保留具体实现及证据，其他视图通过链接引用。Guide 与 Optimization 不再使用 experience 层。可选 scope 只填写来源支持的场景条件；未知字段留空缺失，不以 any 代替未知，也不因移动卡片或通过 Lint 补造 verified。

具体字段语义、生命周期、平台表示、OKF verified 事件、信任层级、标签和各 Profile 允许字段见 Frontmatter 与证据。

3.7 编写正文

知识卡应让读者不依赖来源原文也能判断“结论是什么、何时适用、何时失效”。正文通常需要覆盖：

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

不要求所有卡片使用同一模板：概念卡应突出定义和边界，API 卡应突出语义和约束，Runbook 应突出信号、判断和处置步骤，优化卡应突出触发条件、收益来源和失效边界。Registry 文档归档的官方 API/Guide 过滤导航页，以 index.md 作为唯一目录入口；保留页只删除 Registry 声明的冗余章节、添加 Frontmatter、修正失效链接目标，可在文末追加普通卡片链接，或在这些链接之后增加「配套 API 与常见组合」小节。小节内每条链接可以在同一行用「——」附加一句不超过 110 个字符的机制说明；说明只描述两张卡如何配合、适用条件或失效边界，不新增来源正文没有的接口约束，不换行，也不再包含链接或标题。镜像同步只保留这种文末导航。产品支持范围只保存在 Frontmatter platforms 中。

3.8 更新导航与记录

index.md 只用于 knowledge/，且只列所在目录的直接子项；bundle 根索引声明 okf_version: "0.2"；
新增、删除或移动卡片时，同步受影响的每一级 index.md；
卡片移动时在同一变更中更新正文链接；Concept 与索引链接必须留在 knowledge/ Bundle 内；知识卡可额外链接登记的固定提交本地源码文件作为证据导航，不生成源码 Concept；
实质知识或治理变更记录到当天 logs/，纯排版和错别字修复不记录；
图谱按需从知识卡之间的普通 Markdown 链接生成，包括 API 与算子卡片的关联。日常入库不构图、不做全库关系判定，不维护专用区块；没有链接的卡片也可入库。Index 仅提供导航，固定源码仅用于来源；图谱产物保存在 Git 忽略的 artifacts/graphs/。

3.9 验证效果并提交 PR

用知识 Issue 或修复 PR 中说明的场景验证贡献：保留原始问题、查询条件、贡献前的缺口、贡献后的命中卡片和正文依据。修正或废弃知识时，还要确认原错误结论已被纠正或退出默认检索范围。检索命中只证明可找到内容；技术结论本身仍需来源核对或相应实验。

提交知识 PR 前完成以下适用检查；committer 按第 6 节检视后合入。

常规知识建设已关联 Issue；知识错误修复已在 PR 说明问题与修正依据。两者均已提供实际验证结果和未覆盖边界。
已明确 create/update/merge/split/deprecate/defer 决定。
路径符合 domain-route、Profile 和附加层级规则。
shared 或 interoperability 的复用边界清楚。
八个公共字段齐全，type 与路径 Profile 一致。
tags 来自注册表，并至少包含 task 和 topic 维度。
sources 能定位到支持正文结论的证据。
平台和版本没有超出证据范围；verified 如存在，actor 与时间真实可核验。
正文说明结论、适用条件和失效边界。
index.md、Bundle 内相对链接和当天日志已按需更新。
knowledge-lint 通过，已按 Query Skill 的维护流程重建并验证检索索引，目标查询能够召回新知识。
bash check.sh 通过。

4. 贡献治理和文档

新增、优化或主动调整机器规则、Skill 或公共工具行为时，按第 5 节提交 RFC 和 A/B 实验材料；缺陷修复按第 2.1 节直接提交 PR。仅修改说明文档时，在 PR 中说明修订原因、影响范围并检查链接。

治理变更必须从唯一事实源开始，并同步所有消费者：

变更	至少同步
Frontmatter 字段	JSON Schema、Profile、Contract、Spec、测试
domain/technology/scope/platform/tag	Registry、路径或字段测试、Query 回归、Schema 文档
路径 Profile 或层级	Profile、Registry/Contract、路径文档、样板卡、导航
Query/Ingest/Lint 行为	对应 Skill、Skill 文档、测试和平台中立的触发契约
安装契约	本仓安装器、Skill 文档和用户文档
OKF 对应关系	OKF、Frontmatter、Path 文档和 conformance 回归

仓库级文档描述能力、输入输出语义和边界；Skill 内部脚本、命令和参数只在对应 SKILL.md 或 references/ 中说明。修改文档时检查所有本地链接，并确认示例描述的是已实现行为。

CI 的知识检查使用目标分支的受信规则和实现读取 PR 的知识树；同一 PR 中新增的 Schema、Profile 或 Contract 不会自动成为该检查的规则。知识依赖尚未合入的治理能力时，先提交兼容现有知识的基础治理 PR，由 committer 检视并验证新实现，再提交或同步依赖它的知识变更。删除旧目录或收紧旧字段的规则与对应迁移一起生效，避免基础能力尚未接入就拒绝现有知识。

5. 贡献公共组件（含检索 Skill）

5.1 适用范围与兼容性原则

本节适用于公共能力的新增、优化或主动行为调整，包括 Skill 的触发、流程与权限边界，Query 的过滤、排序与索引，Ingest/Lint、治理机器规则、安装器、图谱、评测或 CI 工具。先在 RFC 中说明当前问题、修改必要性、方案和实验计划，再通过 A/B test 证明结果，最后提交关联 PR 供 committer 检视。纠正错误、恢复既定行为的缺陷修复按第 2.1 节直接提交 PR。

组件贡献遵循扩展优先、保持兼容：新增能力优先通过现有扩展点或可选配置接入，保留原有默认流程和对外契约，避免为新能力复制整套流程。扩展仍使用相同的治理事实源和权限边界，不另建一套局部规则。

内部重构可以修改原实现；确需主动调整默认流程、接口或既有行为时，RFC 必须单列扩展方式为何不足、受影响的使用场景、迁移与回退方案，并由 committer 明确检视。验证同时覆盖原有路径和新增能力。缺陷修复可以直接修改原实现，在 PR 中说明问题和预期行为并验证，不能为了兼容保留已确认的错误。

情形	处理要求
新增可选能力，默认行为兼容	说明接入点，验证原有路径、新能力及错误边界，提供对应 A/B 证据
知识错误或工具/脚本缺陷修复	直接提交 PR，提供问题、修复依据及定向验证；无需前置 Issue/RFC 或完整 A/B
内部重构	可以修改实现；主动改变默认流程或对外行为时补齐 RFC 专项说明
直接切换默认流程或删除接口，未说明迁移影响	材料不足，补齐必要性、受影响场景、迁移与回退及验证后再申请合入

5.2 提交 RFC

RFC 阶段可以先提交问题、方案和实验计划；采用 RFC 流程的组件 PR 提交前须回填已完成的实验报告。讨论中发生方案或验收标准变更时，保留变更理由，并说明是否需要重跑实验。

### 当前问题与修改必要性

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

### 目标与方案

- 期望改变的行为、本次范围和不包含的范围。
- 设计与实现：输入输出、关键逻辑、依赖，以及涉及的规则事实源和消费者。
- 扩展接入：复用的扩展点或可选配置，原有默认流程、接口和行为是否变化。
- 替代方案：保持现状、调整配置或其他实现的取舍。
- 既有行为变更（如适用）：扩展方式为何不足、受影响场景、迁移与回退方案。
- 兼容性、资源成本、权限影响，以及原有路径和新增能力的验证范围。

### A/B 实验计划与结果

- 假设与验收标准：主指标、回归约束、预先设定的通过阈值。
- A 基线与 B 候选：版本、差异、环境、控制变量。
- 数据集：来源、固定版本、样本数、分组、期望结果与调参隔离方式。
- 执行方法：复现入口、配置、重复次数、随机性与缓存处理。
- 实测结果：A/B 对照表、逐样本记录、失败样本、波动和证据链接。
- 结论：哪些目标达成、哪些未达成、适用范围、风险和处理决定。

新增组件的 A 是当前完成同一任务的方式；当前无法完成时，记录失败行为和成本，避免只展示 B 的成功样例。新增 Skill 还需说明现有 Skill 职责为何无法承载，并完成下述架构和发布评审。

5.3 完成可复现的 A/B test

A/B test 指旧方案与候选方案在同一任务集上的对照实验，可以离线进行。本节适用于采用 RFC 流程的组件变更；第 2.1 节的缺陷修复不要求完整 A/B 或端到端生成对照，但仍须提供与问题相匹配的定向验证和相关回归结果。实验报告至少包含：

项目	必须交付的内容
假设和验收标准	先定义要解决的问题、主指标、不得退化的行为和通过阈值；阈值由场景决定，并说明依据
A/B 版本	A 的固定基线 commit、B 的候选 commit 或可应用补丁及基线、依赖与配置；记录唯一待检验的变更，多个独立改动需拆分对照或补充消融
样本与期望结果	固定数据集版本、来源、规模、样本 ID、分组和人工核对的期望结果；覆盖原有默认路径、新增扩展路径（如有）、目标场景、错误输入与边界；区分调参集和未参与调参的验收集
控制变量	保持知识语料、输入、平台条件、环境、资源限制和非实验配置一致；若索引实现改变，两组从同一语料分别构建并记录构建方式；涉及模型时记录模型版本、提示词和采样配置
执行与统计	给出可运行的评测入口、依赖和配置；记录重复次数、随机种子和执行顺序，耗时测试区分冷/热缓存并采用配对或交替运行；确定性结果可逐例对照，随机或耗时指标报告波动范围或置信区间
完整结果	同时报告 A、B、差值、样本数、指标口径及分组结果；保留逐例输出、失败和超时，注明缺失值处理；不得只选择改善的样本
结论与复现材料	对照预设阈值逐项判定，解释退化和代价；提供版本、数据、运行记录与复现步骤，使 committer 能复跑或抽查

检索 Skill 的实验可按以下口径组织，按 RFC 的目标选定主指标，并保留正确性约束：

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

仅索引、缓存等工程优化，若证明检索结果和行为一致，可只做检索回归与性能对照；无法证明时补端到端验证。较大版本更新运行完整端到端任务集。任务集、重复次数、性能标准和退化上限在实验前固定，保留代码与验证日志；检索指标提升不能直接推导任务成功。

例如修改排序时，可假设“目标查询 Hit@5 提升且既有场景不退化”，在实验前填写最低提升值、允许的耗时增幅和过滤违规上限，完成实验后填入实测值。该例是实验设计示意，不是仓库已有测量结果或统一阈值。

结果摘要可使用下表，每行注明样本数与统计口径，按实际指标增删。所有“待填”均须替换为实测记录；比例变化区分百分点和相对变化，缺少证据时填写“未验证”及原因。

场景/指标	样本数/重复次数	A 基线	B 候选	差值与波动	预设验收标准	是否达成	证据
目标场景的主指标	待填	待填	待填	待填	待填	待填	待填
既有成功场景	待填	待填	待填	待填	待填	待填	待填
错误输入与边界行为	待填	待填	待填	待填	待填	待填	待填
耗时或资源成本	待填	待填	待填	待填	待填	待填	待填

其他公共组件按职责选择指标：Lint/治理规则在 A/B 两组对同一批合法、非法输入比较接受、拒绝行为与误报；安装器比较受支持环境下的成功率、幂等性和失败时对用户文件的保护；Ingest 比较有效产物比例、内容保真和写入边界。确定性规则可以逐例对照，不要求所有组件都证明性能提升。常规单元测试和 bash check.sh 结果应一并提供，但不能代替 A/B 报告。

未执行、仅有实验计划或只报告 B 的结果，都不能标为实验通过。样本不足或结果波动大时如实说明结论限制，补充实验后再申请合入；未达到预设标准时说明原因、调整方案并重新验证，不能事后降低标准而不解释。

可复用评测用例和驱动放在 evals/；本地可重建报告放在 ignored 的 artifacts/。RFC/PR 中保留结果摘要，并附上评审者可访问的完整报告或复现材料，不能只提供作者机器上的绝对路径。Skill 内部命令仍由对应 SKILL.md 或 references/ 维护，RFC/PR 引用这些说明并记录本次实际执行配置。

Scope A/B 的人工标注可用评审输入校验器核对：评审记录绑定冻结用例、迁移等价映射与两组检索快照，并完整覆盖实际返回项。运行方式见 python3 -m evals.scope_review --help；缺少人工标注时输出待评审状态，不生成精度结果。该工具只计算检索指标，不能代替工作流评审、仓库门禁或 committer 检视。

5.4 实现、验证并提交 PR

当前维护 knowledge-ingest、knowledge-query、knowledge-lint 三项基础 Skill、复用 Query 的只读专用消费流程 ascendc-api-knowledge-query、知识仓内的 ops-knowledge-trace-ingest（trace → runbooks 生产），以及 ops-knowledge-vv-ingest、ops-knowledge-cv-ingest 两项源码级 Operator producer。VV 用于全部可达 Device 节点均不含 Cube/AIC 或 MIX_CV 的算子，CV 用于至少存在一个可达 Cube/AIC 或 MIX_CV 节点的算子；两者都由任务决定入口，并按现有 call-mode 落库。仅 Host/Tiling 内部入口目前没有对应分类，须先报告缺口，不能套用 ACLNN 或 Direct Invoke 路径；完整边界见 Knowledge Skills。新增其他 Skill 需要先证明现有职责无法合理承载，并完成架构和发布评审。

本仓 Skill 的规范源位于 .agents/skills/，其中维护完整的 SKILL.md、references/、scripts/ 及其他运行所需资源。治理、安装、检索与 CI 回归集中于 evals/；Ingest 使用全库确定性命令和仓库级回归，trace producer 保留专用脚本回归。规范源不包含 agents/openai.yaml 等单一客户端元数据。

采用 RFC 流程的公共组件实现与交付步骤（缺陷修复见第 2.1 节）：

关联 RFC，按方案修改规范源；涉及治理规则时先修改唯一机器事实源，再同步消费者。
更新受影响的文档和测试；Skill 变更同步内部说明、Frontmatter 触发描述和必要参考资料。
验证结构、触发条件、原有路径、新增能力、错误路径和权限边界；治理规则覆盖接受与拒绝案例，Query 覆盖过滤、排序或失败关闭语义；按变更范围完成下游验证。
完成 A/B test 并回填 RFC，记录实质治理或 Skill 契约变更的当天日志；提交前运行仓库统一质量门禁。
提交关联 RFC 的 PR，按第 6 节提供交付材料，由 committer 检视后合入。

Skill 中只保存完成工作所需的流程、工具和小型参考资料。可被多个 Skill 消费的 CANN、DSL、API、算子、调试和优化知识必须进入 knowledge/。

6. PR 提交、committer 检视与合入

6.1 PR 交付材料

PR 应让评审者沿“问题 → 方案 → 产物 → 证据”核对本次贡献。可在现有 PR 表单中补充以下内容，不适用项说明原因：

### 关联与范围

- 贡献类型：知识建设 / 公共组件新增或优化 / 缺陷修复（知识或工具）/ 说明文档。
- 关联知识 Issue / RFC：常规贡献填写，缺陷修复与轻量修订可填“无”。
- 解决的问题、实际改动文件与范围：

### 交付与效果

- 知识建设：处理决定、来源、生产方法、验收场景及实际结果。
- 采用 RFC 流程的公共组件：RFC 方案、A/B 版本、实验报告链接、关键指标与验收结论。
- 缺陷修复：问题、修复内容和影响；知识修正的证据，或工具问题的复现方式；定向验证与回归结果。
- 公共组件兼容性：默认流程/接口/行为是否变化及相关验证；新增能力说明扩展接入点，主动行为调整补充影响及迁移方案（如适用）。
- 与原计划的差异、剩余限制及回退方法（如适用）：

### 检查与评审重点

- 实际执行的检查、对应版本和结果；未执行或失败项及原因。
- 已同步的导航、链接、日志、规则消费者、文档与测试。
- 对检索、Schema、图谱、安装或兼容性的影响，以及需要 committer 重点判断的风险。

6.2 committer 检视与合入条件

检视对象	committer 核对内容
常规知识建设 PR	Issue 中的缺口是否得到解决；生产方法、来源、平台与版本范围是否支撑结论；有无重复或错误泛化；目标场景的实际效果是否可复核
采用 RFC 流程的公共组件 PR	RFC 是否解释必要性、扩展接入和方案取舍；主动行为调整是否说明扩展方式不足、影响及迁移/回退；原有路径与新增能力是否均有验证；A/B 是否达到预设标准，回归、成本和权限边界是否可接受
缺陷修复 PR	问题与修复依据是否清楚，证据或复现材料能否核对；定向验证是否证明修复有效，相关回归是否通过；无前置 Issue/RFC 或完整 A/B 不影响按简化路径检视
所有 PR	改动是否限于目标范围；文档、导航和日志是否按需同步；检查结果是否对应当前差异；评审意见是否解决

贡献者负责补充证据和处理评审意见，committer 负责判断内容与方案是否可接受、要求必要的复跑或抽查，并记录通过或需修改的意见。自动检查通过只证明所覆盖的检查通过，不能代替内容与效果检视。

合入前必须满足：对应贡献类型的材料完整、适用的验收标准达成、阻断性评审意见已解决、当前待合入版本的 bash check.sh 通过，并获得 committer 的明确认可。采用 RFC 流程且主动调整默认流程、接口或既有行为时，评审结论应明确记录对兼容性、迁移与回退方案的判断；缺陷修复检视问题、影响与修复证据。评审后修改了影响验证结论的内容，应更新对应检查及适用的 A/B 结果。由 committer 执行合入；有关联 Issue/RFC 时回填 PR 与处理结果，仍有缺口时保留未完成范围。材料不足时继续补充或记录 defer/关闭原因，不先合入再补证据。

7. 不接受的贡献

无可靠来源的 API、平台、精度、性能或默认行为结论；
在文档归档 API/Guide 受控转换之外大段复制上游文档、源码、日志或其他 Skill references；本条款不禁止受控归档自有项目（如 cannbot 组织技能参考）来源的整卡 verbatim 迁移——前提是来源固定到提交、sources.resource 指向该提交的可核验 URL、正文逐字节保留且以 logs/ 记录归档动作与校验结果；
只适用于个人环境且无法复现或界定范围的经验；
把单一技术实现过度泛化为 shared；
把一个 DSL 的行为写成另一个 DSL 的事实；
静默删除仍需要解释的错误或过时知识；
自动提交、推送、发布或修改用户全局环境的行为。