已合并
docs: 细化知识与公共组件贡献流程 #62
汪超创建于 9月23日
docs: 细化知识与公共组件贡献流程 #62
已合并
共 7 个文件变更+292-34
| @@ -18,6 +18,8 @@ | |||
| 18 | - 每个 PR 只修改当前任务明确要求的内容，以及完成该任务不可缺少的导航、日志、规则或测试；不得顺手更新与当前任务无关的知识（尤其例如官方团队维护的 `knowledge/**/apis/**`、`knowledge/**/operators/**` 等内容）。 | 18 | - 每个 PR 只修改当前任务明确要求的内容，以及完成该任务不可缺少的导航、日志、规则或测试；不得顺手更新与当前任务无关的知识（尤其例如官方团队维护的 `knowledge/**/apis/**`、`knowledge/**/operators/**` 等内容）。 |
| 19 | - 检查失败、官方来源更新或发现存量错误不构成扩大任务范围的授权。对无关问题只记录并反馈，不得为通过检查运行全库同步或批量更新。 | 19 | - 检查失败、官方来源更新或发现存量错误不构成扩大任务范围的授权。对无关问题只记录并反馈，不得为通过检查运行全库同步或批量更新。 |
| 20 | - 涉及当前任务之外的知识升级必须另行取得明确授权，并使用独立 PR。 | 20 | - 涉及当前任务之外的知识升级必须另行取得明确授权，并使用独立 PR。 |
| 21 | +- 对外贡献流程以 `CONTRIBUTING.md` 为准：常规知识建设先提交说明缺口、生产方法和预期效果的 Issue；公共组件新增、优化或主动行为调整先提交说明问题、必要性和方案的 RFC，完成 A/B 实验后提交关联 PR。知识错误、检索脚本 bug 等缺陷修复，以及轻量文档修订，可直接提交 PR，无需前置 Issue/RFC 或完整 A/B，但仍需修复依据、适用的定向验证和质量检查；修复中包含新增能力或主动流程调整时应拆分贡献。所有 PR 均由 committer 检视后合入。Agent 可在当前授权内准备本地改动与评审材料，外部提交、发布仍遵守“工作边界”，不得把尚未执行的实验写成结果。 | ||
| 22 | +- 公共组件贡献扩展优先、保持兼容：新增能力优先复用现有扩展点或可选配置，保留默认流程和对外契约，避免复制整套流程。允许缺陷修复和内部重构修改原实现；纠正错误或恢复既定行为适用修复简化路径，主动改变默认流程、接口或既有行为时，RFC 必须说明扩展方式不足的原因、影响、迁移与回退，由 committer 明确检视，并验证原有路径与新增能力。外层评审要求不增加 Skill 的运行权限。 | ||
| 21 | 23 | ||
| 22 | ## 维护本文件 | 24 | ## 维护本文件 |
| 23 | 25 | ||
| @@ -2,6 +2,16 @@ | |||
| 2 | 2 | ||
| 3 | 本文只说明贡献流程和交付要求。环境安装与 `contributor` 模式见[安装与使用指南](docs/installation_and_usage.md)；字段、路径与受控值的完整定义由 `governance/` 维护，Skill 的内部命令与参数由各 Skill 自身文档维护，避免在多处复制同一规则。 | 3 | 本文只说明贡献流程和交付要求。环境安装与 `contributor` 模式见[安装与使用指南](docs/installation_and_usage.md)；字段、路径与受控值的完整定义由 `governance/` 维护，Skill 的内部命令与参数由各 Skill 自身文档维护，避免在多处复制同一规则。 |
| 4 | 4 | ||
| 5 | +贡献包含两条常规流程，以及缺陷修复与轻量修订的简化路径，均由贡献者提交材料、committer 检视后合入。本文中的 committer 指本仓有合入权限、负责评审的维护者。 | ||
| 6 | + | ||
| 7 | +| 贡献类型 | 流程 | 评审重点 | | ||
| 8 | +|---|---|---| | ||
| 9 | +| 知识建设（缺陷修复除外）：新增、补充、合并、拆分或废弃知识 | 提交知识 Issue → 生产知识并验证效果 → 提交关联 PR → committer 检视、合入 | 缺口是否真实、知识如何产生、证据是否充分、能解决什么问题 | | ||
| 10 | +| 公共组件新增、优化或主动行为调整（缺陷修复除外）：检索 Skill、索引、摄入、校验、安装、评测等公共能力 | 提交 RFC → 实现方案并完成 A/B test → 提交关联 PR → committer 检视、合入 | 修改是否必要、方案是否合理、实验是否可复现、收益与回归是否可接受 | | ||
| 11 | +| 缺陷修复：知识错误、检索脚本 bug 等；轻量文档修订 | 直接提交 PR → committer 检视、合入 | 问题与修复依据是否清楚，验证是否证明问题得到修复，有无引入回归 | | ||
| 12 | + | ||
| 13 | +RFC（Request for Comments）使用本仓 Issue 承载，标题包含 `[RFC]`，正文按第 5 节组织。首版沿用现有 Issue/PR 表单，在正文中补齐对应贡献类型的材料。已有 Issue 可以补齐材料后复用；同时涉及常规知识建设和公共组件变更时，分别说明验收依据并关联对应 Issue/RFC，可独立交付的改动拆成 PR。缺陷修复与轻量修订按第 2.1 节直接提交 PR。 | ||
| 14 | + | ||
| 5 | ## 1. 规则从哪里读取 | 15 | ## 1. 规则从哪里读取 |
| 6 | 16 | ||
| 7 | | 需要确认的内容 | 事实源 | | 17 | | 需要确认的内容 | 事实源 | |
| @@ -30,9 +40,53 @@ Schema、Profile、Registry 和 Contract 共同构成机器规则，Spec 是解 | |||
| 30 | 40 | ||
| 31 | 集合型目录使用复数，例如 `references/`、`scripts/`、`schemas/`、`specs/`、`evals/`、`artifacts/` 和 `logs/`。 | 41 | 集合型目录使用复数，例如 `references/`、`scripts/`、`schemas/`、`specs/`、`evals/`、`artifacts/` 和 `logs/`。 |
| 32 | 42 | ||
| 43 | +### 2.1 缺陷修复与轻量修订 | ||
| 44 | + | ||
| 45 | +知识错误修正、检索脚本 bug 等纠正错误或恢复既定行为的贡献，可直接提交修复 PR，无需先提交 Issue/RFC，也不要求完整 A/B 实验。PR 说明问题、修复内容和影响，并提供相应证据与定向验证结果： | ||
| 46 | + | ||
| 47 | +- 知识修正：指出错误结论及修正依据，提供支持新结论的来源或可复核观测，并验证受影响场景。 | ||
| 48 | +- 工具或脚本修复：提供复现方式、预期行为、修复结果及相关回归结果。 | ||
| 49 | +- 纯排版、错别字和不改变组件行为的说明文档修订：说明修订内容，运行适用的文档检查。 | ||
| 50 | + | ||
| 51 | +已有 Issue 可按需关联，不作为前置要求。简化路径仍需满足适用的来源、导航、日志和检查要求，上库前执行 `bash check.sh`，由 committer 检视后合入。修复中若包含新增能力或主动流程调整，应拆分后按对应流程贡献。 | ||
| 52 | + | ||
| 33 | ## 3. 贡献知识 | 53 | ## 3. 贡献知识 |
| 34 | 54 | ||
| 35 | -### 3.1 先决定如何处理现有知识 | 55 | +以下内容规范和检查适用于知识建设与知识错误修复；第 3.1 节的前置 Issue 仅用于常规知识建设，缺陷修复直接在 PR 中提供第 2.1 节要求的材料。 |
| 56 | + | ||
| 57 | +### 3.1 先提交知识 Issue：缺什么、怎么产生、有什么效果 | ||
| 58 | + | ||
| 59 | +先搜索同主题知识和已有 Issue，阅读相关卡片，再提交或补充知识 Issue。可以在现有“知识需求”表单中补充以下正文；仅反馈缺口但暂不认领实现时，将未知项标为待补充，不能把推测写成已验证结果。 | ||
| 60 | + | ||
| 61 | +```markdown | ||
| 62 | +### 知识缺口 | ||
| 63 | + | ||
| 64 | +- 使用场景：谁在什么任务中遇到了什么问题？ | ||
| 65 | +- 适用范围：领域、技术、平台和必要的版本信息。 | ||
| 66 | +- 现有检索：查询词、筛选条件、命中卡片；现有内容缺失、错误或不足之处。 | ||
| 67 | +- 当前影响：缺口导致哪些无法回答的问题、失败或重复工作？ | ||
| 68 | + | ||
| 69 | +### 知识生产方案 | ||
| 70 | + | ||
| 71 | +- 处理方式：create / update / merge / split / deprecate / defer 及理由。 | ||
| 72 | +- 候选来源：官方文档、固定提交源码、可复核实验或开发轨迹；注明版本和获取方式。 | ||
| 73 | +- 生产方法：人工整理或使用哪个 Skill，如何从来源得到结论，如何复核。 | ||
| 74 | +- 预期产物：目标知识卡或主题范围，需要同步的导航和链接。 | ||
| 75 | +- 证据缺口：尚未确认的结论、范围，以及补证方法。 | ||
| 76 | + | ||
| 77 | +### 预期效果与验收 | ||
| 78 | + | ||
| 79 | +- 预期效果：贡献后应能回答什么问题、完成什么操作或避免什么错误？ | ||
| 80 | +- 验收场景：具体问题或任务、输入条件、预期答案要点或行为。 | ||
| 81 | +- 验证方法：如何核对来源、验证召回；必要时如何复现技术结论。 | ||
| 82 | +- 效果证据：实施后回填相同场景下的实际结果、证据位置和仍未覆盖的边界。 | ||
| 83 | +``` | ||
| 84 | + | ||
| 85 | +“增加若干张卡”只能说明工作量，不能单独说明效果。至少给出一个可复核的目标场景，例如在指定平台和技术条件下，用某个真实问题能找到支持答案的卡片，并从正文确认适用条件。声称提升成功率、减少耗时或改善性能时，应给出对应的测量方法和实际证据；尚未测量的收益保留为预期。 | ||
| 86 | + | ||
| 87 | +Issue 建立后，按下列步骤生产知识，在关联 PR 中回填实际产物和验收结果。来源不足时可继续在 Issue 中讨论或选择 defer，不以占位卡代替知识。 | ||
| 88 | + | ||
| 89 | +### 3.2 决定如何处理现有知识 | ||
| 36 | 90 | ||
| 37 | 写卡前先使用 `knowledge-query` 搜索同一主题，并明确本次决定： | 91 | 写卡前先使用 `knowledge-query` 搜索同一主题，并明确本次决定： |
| 38 | 92 | ||
| @@ -47,7 +101,7 @@ Schema、Profile、Registry 和 Contract 共同构成机器规则，Spec 是解 | |||
| 47 | 101 | ||
| 48 | 不要仅因标题不同就创建新卡，也不要用自动覆盖替代对原卡的完整审阅。 | 102 | 不要仅因标题不同就创建新卡，也不要用自动覆盖替代对原卡的完整审阅。 |
| 49 | 103 | ||
| 50 | -### 3.2 选择路径 | 104 | +### 3.3 选择路径 |
| 51 | 105 | ||
| 52 | 知识正文只能进入 `knowledge/`。常规路径为： | 106 | 知识正文只能进入 `knowledge/`。常规路径为： |
| 53 | 107 | ||
| @@ -67,7 +121,7 @@ knowledge/<domain>/<technology-or-scope>/<profile>/<slug>.md | |||
| 67 | - `concepts/`、`apis/`、`examples/`、`guides/` 和 `optimizations/` 的主题 section 使用小写 `snake_case`，并逐层维护索引； | 121 | - `concepts/`、`apis/`、`examples/`、`guides/` 和 `optimizations/` 的主题 section 使用小写 `snake_case`，并逐层维护索引； |
| 68 | - 稳定原理进入 `concepts/`，接口事实进入 `apis/`，任务型教程进入 `guides/`，完整算子进入 `operators/`，性能方法进入 `optimizations/`，处置流程进入 `runbooks/`。 | 122 | - 稳定原理进入 `concepts/`，接口事实进入 `apis/`，任务型教程进入 `guides/`，完整算子进入 `operators/`，性能方法进入 `optimizations/`，处置流程进入 `runbooks/`。 |
| 69 | 123 | ||
| 70 | -### 3.3 区分 shared、技术专属和 interoperability | 124 | +### 3.4 区分 shared、技术专属和 interoperability |
| 71 | 125 | ||
| 72 | 技术专属目录保存依赖该 DSL、框架、编译器或 API 的知识。只有不依赖单一技术实现、且能明确说明复用条件的结论才能进入同领域 `shared/`。 | 126 | 技术专属目录保存依赖该 DSL、框架、编译器或 API 的知识。只有不依赖单一技术实现、且能明确说明复用条件的结论才能进入同领域 `shared/`。 |
| 73 | 127 | ||
| @@ -80,7 +134,7 @@ knowledge/<domain>/<technology-or-scope>/<profile>/<slug>.md | |||
| 80 | 134 | ||
| 81 | 其他技术栈中的成功经验只能作为线索，不能自动成为目标技术的已验证证据。 | 135 | 其他技术栈中的成功经验只能作为线索，不能自动成为目标技术的已验证证据。 |
| 82 | 136 | ||
| 83 | -### 3.4 准备来源 | 137 | +### 3.5 准备来源 |
| 84 | 138 | ||
| 85 | 每张卡都必须填写 `sources`。轨迹沉淀的 `Runbook` 可以使用 `sources: []`，但正文必须保留与结论强度相匹配的触发、探针、原始观测和验证信号，且不能把中间整理仓或会话轨迹伪装成权威 resource；其他非 `draft` 卡至少有一个精确 `resource`。 | 139 | 每张卡都必须填写 `sources`。轨迹沉淀的 `Runbook` 可以使用 `sources: []`，但正文必须保留与结论强度相匹配的触发、探针、原始观测和验证信号，且不能把中间整理仓或会话轨迹伪装成权威 resource；其他非 `draft` 卡至少有一个精确 `resource`。 |
| 86 | 140 | ||
| @@ -88,7 +142,7 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 88 | 142 | ||
| 89 | 搜索摘要、PR 标题、聊天记录或模型记忆不能单独作为技术来源。来源角色、固定格式和人工审阅要求见 [Frontmatter 与证据](governance/specs/frontmatter.md)。 | 143 | 搜索摘要、PR 标题、聊天记录或模型记忆不能单独作为技术来源。来源角色、固定格式和人工审阅要求见 [Frontmatter 与证据](governance/specs/frontmatter.md)。 |
| 90 | 144 | ||
| 91 | -### 3.5 填写 Frontmatter | 145 | +### 3.6 填写 Frontmatter |
| 92 | 146 | ||
| 93 | 所有非 `index.md` 卡片统一包含八个公共必选字段： | 147 | 所有非 `index.md` 卡片统一包含八个公共必选字段： |
| 94 | 148 | ||
| @@ -105,7 +159,7 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 105 | 159 | ||
| 106 | 具体字段语义、生命周期、平台表示、OKF `verified` 事件、信任层级、标签和各 Profile 允许字段见 [Frontmatter 与证据](governance/specs/frontmatter.md)。 | 160 | 具体字段语义、生命周期、平台表示、OKF `verified` 事件、信任层级、标签和各 Profile 允许字段见 [Frontmatter 与证据](governance/specs/frontmatter.md)。 |
| 107 | 161 | ||
| 108 | -### 3.6 编写正文 | 162 | +### 3.7 编写正文 |
| 109 | 163 | ||
| 110 | 知识卡应让读者不依赖来源原文也能判断“结论是什么、何时适用、何时失效”。正文通常需要覆盖： | 164 | 知识卡应让读者不依赖来源原文也能判断“结论是什么、何时适用、何时失效”。正文通常需要覆盖： |
| 111 | 165 | ||
| @@ -117,7 +171,7 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 117 | 171 | ||
| 118 | 不要求所有卡片使用同一模板：概念卡应突出定义和边界，API 卡应突出语义和约束，Runbook 应突出信号、判断和处置步骤，优化卡应突出触发条件、收益来源和失效边界。Registry 文档归档的官方 API/Guide 过滤导航页，以 `index.md` 作为唯一目录入口；保留页只删除 Registry 声明的冗余章节、添加 Frontmatter、修正失效链接目标，可在文末追加普通卡片链接。产品支持范围只保存在 Frontmatter `platforms` 中。 | 172 | 不要求所有卡片使用同一模板：概念卡应突出定义和边界，API 卡应突出语义和约束，Runbook 应突出信号、判断和处置步骤，优化卡应突出触发条件、收益来源和失效边界。Registry 文档归档的官方 API/Guide 过滤导航页，以 `index.md` 作为唯一目录入口；保留页只删除 Registry 声明的冗余章节、添加 Frontmatter、修正失效链接目标，可在文末追加普通卡片链接。产品支持范围只保存在 Frontmatter `platforms` 中。 |
| 119 | 173 | ||
| 120 | -### 3.7 更新导航与记录 | 174 | +### 3.8 更新导航与记录 |
| 121 | 175 | ||
| 122 | - `index.md` 只用于 `knowledge/`，且只列所在目录的直接子项；bundle 根索引声明 `okf_version: "0.2"`； | 176 | - `index.md` 只用于 `knowledge/`，且只列所在目录的直接子项；bundle 根索引声明 `okf_version: "0.2"`； |
| 123 | - 新增、删除或移动卡片时，同步受影响的每一级 `index.md`； | 177 | - 新增、删除或移动卡片时，同步受影响的每一级 `index.md`； |
| @@ -125,8 +179,13 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 125 | - 实质知识或治理变更记录到当天 `logs/`，纯排版和错别字修复不记录； | 179 | - 实质知识或治理变更记录到当天 `logs/`，纯排版和错别字修复不记录； |
| 126 | - 图谱按需从知识卡之间的普通 Markdown 链接生成，包括 API 与算子卡片的关联。日常入库不构图、不做全库关系判定，不维护专用区块；没有链接的卡片也可入库。Index 仅提供导航，固定源码仅用于来源；图谱产物保存在 Git 忽略的 `artifacts/graphs/`。 | 180 | - 图谱按需从知识卡之间的普通 Markdown 链接生成，包括 API 与算子卡片的关联。日常入库不构图、不做全库关系判定，不维护专用区块；没有链接的卡片也可入库。Index 仅提供导航，固定源码仅用于来源；图谱产物保存在 Git 忽略的 `artifacts/graphs/`。 |
| 127 | 181 | ||
| 128 | -### 3.8 知识提交检查 | 182 | +### 3.9 验证效果并提交 PR |
| 129 | 183 | ||
| 184 | +用知识 Issue 或修复 PR 中说明的场景验证贡献：保留原始问题、查询条件、贡献前的缺口、贡献后的命中卡片和正文依据。修正或废弃知识时，还要确认原错误结论已被纠正或退出默认检索范围。检索命中只证明可找到内容；技术结论本身仍需来源核对或相应实验。 | ||
| 185 | + | ||
| 186 | +提交知识 PR 前完成以下适用检查；committer 按第 6 节检视后合入。 | ||
| 187 | + | ||
| 188 | +- [ ] 常规知识建设已关联 Issue；知识错误修复已在 PR 说明问题与修正依据。两者均已提供实际验证结果和未覆盖边界。 | ||
| 130 | - [ ] 已明确 create/update/merge/split/deprecate/defer 决定。 | 189 | - [ ] 已明确 create/update/merge/split/deprecate/defer 决定。 |
| 131 | - [ ] 路径符合 domain-route、Profile 和附加层级规则。 | 190 | - [ ] 路径符合 domain-route、Profile 和附加层级规则。 |
| 132 | - [ ] shared 或 interoperability 的复用边界清楚。 | 191 | - [ ] shared 或 interoperability 的复用边界清楚。 |
| @@ -141,6 +200,8 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 141 | 200 | ||
| 142 | ## 4. 贡献治理和文档 | 201 | ## 4. 贡献治理和文档 |
| 143 | 202 | ||
| 203 | +新增、优化或主动调整机器规则、Skill 或公共工具行为时，按第 5 节提交 RFC 和 A/B 实验材料；缺陷修复按第 2.1 节直接提交 PR。仅修改说明文档时，在 PR 中说明修订原因、影响范围并检查链接。 | ||
| 204 | + | ||
| 144 | 治理变更必须从唯一事实源开始，并同步所有消费者： | 205 | 治理变更必须从唯一事实源开始，并同步所有消费者： |
| 145 | 206 | ||
| 146 | | 变更 | 至少同步 | | 207 | | 变更 | 至少同步 | |
| @@ -154,31 +215,153 @@ Git 来源固定到提交；普通文档来源优先使用稳定版本页，Regi | |||
| 154 | 215 | ||
| 155 | 仓库级文档描述能力、输入输出语义和边界；Skill 内部脚本、命令和参数只在对应 `SKILL.md` 或 `references/` 中说明。修改文档时检查所有本地链接，并确认示例描述的是已实现行为。 | 216 | 仓库级文档描述能力、输入输出语义和边界；Skill 内部脚本、命令和参数只在对应 `SKILL.md` 或 `references/` 中说明。修改文档时检查所有本地链接，并确认示例描述的是已实现行为。 |
| 156 | 217 | ||
| 157 | -## 5. 贡献 Skill | 218 | +## 5. 贡献公共组件（含检索 Skill） |
| 219 | + | ||
| 220 | +### 5.1 适用范围与兼容性原则 | ||
| 221 | + | ||
| 222 | +本节适用于公共能力的新增、优化或主动行为调整，包括 Skill 的触发、流程与权限边界，Query 的过滤、排序与索引，Ingest/Lint、治理机器规则、安装器、图谱、评测或 CI 工具。先在 RFC 中说明当前问题、修改必要性、方案和实验计划，再通过 A/B test 证明结果，最后提交关联 PR 供 committer 检视。纠正错误、恢复既定行为的缺陷修复按第 2.1 节直接提交 PR。 | ||
| 223 | + | ||
| 224 | +组件贡献遵循**扩展优先、保持兼容**：新增能力优先通过现有扩展点或可选配置接入，保留原有默认流程和对外契约，避免为新能力复制整套流程。扩展仍使用相同的治理事实源和权限边界，不另建一套局部规则。 | ||
| 225 | + | ||
| 226 | +内部重构可以修改原实现；确需主动调整默认流程、接口或既有行为时，RFC 必须单列扩展方式为何不足、受影响的使用场景、迁移与回退方案，并由 committer 明确检视。验证同时覆盖原有路径和新增能力。缺陷修复可以直接修改原实现，在 PR 中说明问题和预期行为并验证，不能为了兼容保留已确认的错误。 | ||
| 227 | + | ||
| 228 | +| 情形 | 处理要求 | | ||
| 229 | +|---|---| | ||
| 230 | +| 新增可选能力，默认行为兼容 | 说明接入点，验证原有路径、新能力及错误边界，提供对应 A/B 证据 | | ||
| 231 | +| 知识错误或工具/脚本缺陷修复 | 直接提交 PR，提供问题、修复依据及定向验证；无需前置 Issue/RFC 或完整 A/B | | ||
| 232 | +| 内部重构 | 可以修改实现；主动改变默认流程或对外行为时补齐 RFC 专项说明 | | ||
| 233 | +| 直接切换默认流程或删除接口，未说明迁移影响 | 材料不足，补齐必要性、受影响场景、迁移与回退及验证后再申请合入 | | ||
| 234 | + | ||
| 235 | +### 5.2 提交 RFC | ||
| 236 | + | ||
| 237 | +RFC 阶段可以先提交问题、方案和实验计划；采用 RFC 流程的组件 PR 提交前须回填已完成的实验报告。讨论中发生方案或验收标准变更时，保留变更理由，并说明是否需要重跑实验。 | ||
| 238 | + | ||
| 239 | +```markdown | ||
| 240 | +### 当前问题与修改必要性 | ||
| 241 | + | ||
| 242 | +- 受影响的组件、用户和具体场景。 | ||
| 243 | +- 当前行为、复现输入、基线版本和证据。 | ||
| 244 | +- 问题的频率或影响；为什么现有能力、配置或工作流不能满足需求？ | ||
| 245 | + | ||
| 246 | +### 目标与方案 | ||
| 247 | + | ||
| 248 | +- 期望改变的行为、本次范围和不包含的范围。 | ||
| 249 | +- 设计与实现：输入输出、关键逻辑、依赖，以及涉及的规则事实源和消费者。 | ||
| 250 | +- 扩展接入：复用的扩展点或可选配置，原有默认流程、接口和行为是否变化。 | ||
| 251 | +- 替代方案：保持现状、调整配置或其他实现的取舍。 | ||
| 252 | +- 既有行为变更（如适用）：扩展方式为何不足、受影响场景、迁移与回退方案。 | ||
| 253 | +- 兼容性、资源成本、权限影响，以及原有路径和新增能力的验证范围。 | ||
| 254 | + | ||
| 255 | +### A/B 实验计划与结果 | ||
| 256 | + | ||
| 257 | +- 假设与验收标准：主指标、回归约束、预先设定的通过阈值。 | ||
| 258 | +- A 基线与 B 候选：版本、差异、环境、控制变量。 | ||
| 259 | +- 数据集：来源、固定版本、样本数、分组、期望结果与调参隔离方式。 | ||
| 260 | +- 执行方法：复现入口、配置、重复次数、随机性与缓存处理。 | ||
| 261 | +- 实测结果：A/B 对照表、逐样本记录、失败样本、波动和证据链接。 | ||
| 262 | +- 结论：哪些目标达成、哪些未达成、适用范围、风险和处理决定。 | ||
| 263 | +``` | ||
| 264 | + | ||
| 265 | +新增组件的 A 是当前完成同一任务的方式；当前无法完成时，记录失败行为和成本，避免只展示 B 的成功样例。新增 Skill 还需说明现有 Skill 职责为何无法承载，并完成下述架构和发布评审。 | ||
| 266 | + | ||
| 267 | +### 5.3 完成可复现的 A/B test | ||
| 268 | + | ||
| 269 | +A/B test 指旧方案与候选方案在同一任务集上的对照实验，可以离线进行。本节适用于采用 RFC 流程的组件变更；第 2.1 节的缺陷修复不要求完整 A/B 或端到端生成对照，但仍须提供与问题相匹配的定向验证和相关回归结果。实验报告至少包含： | ||
| 270 | + | ||
| 271 | +| 项目 | 必须交付的内容 | | ||
| 272 | +|---|---| | ||
| 273 | +| 假设和验收标准 | 先定义要解决的问题、主指标、不得退化的行为和通过阈值；阈值由场景决定，并说明依据 | | ||
| 274 | +| A/B 版本 | A 的固定基线 commit、B 的候选 commit 或可应用补丁及基线、依赖与配置；记录唯一待检验的变更，多个独立改动需拆分对照或补充消融 | | ||
| 275 | +| 样本与期望结果 | 固定数据集版本、来源、规模、样本 ID、分组和人工核对的期望结果；覆盖原有默认路径、新增扩展路径（如有）、目标场景、错误输入与边界；区分调参集和未参与调参的验收集 | | ||
| 276 | +| 控制变量 | 保持知识语料、输入、平台条件、环境、资源限制和非实验配置一致；若索引实现改变，两组从同一语料分别构建并记录构建方式；涉及模型时记录模型版本、提示词和采样配置 | | ||
| 277 | +| 执行与统计 | 给出可运行的评测入口、依赖和配置；记录重复次数、随机种子和执行顺序，耗时测试区分冷/热缓存并采用配对或交替运行；确定性结果可逐例对照，随机或耗时指标报告波动范围或置信区间 | | ||
| 278 | +| 完整结果 | 同时报告 A、B、差值、样本数、指标口径及分组结果；保留逐例输出、失败和超时，注明缺失值处理；不得只选择改善的样本 | | ||
| 279 | +| 结论与复现材料 | 对照预设阈值逐项判定，解释退化和代价；提供版本、数据、运行记录与复现步骤，使 committer 能复跑或抽查 | | ||
| 280 | + | ||
| 281 | +检索 Skill 的实验可按以下口径组织，按 RFC 的目标选定主指标，并保留正确性约束： | ||
| 282 | + | ||
| 283 | +| 维度 | 对照内容与口径 | | ||
| 284 | +|---|---| | ||
| 285 | +| 检索质量 | 固定 k，报告 Hit@k（前 k 个结果至少命中一张期望卡的查询占比）和/或 MRR（首张期望卡排名倒数的均值，未命中记 0）；分别报告目标问题和既有成功问题 | | ||
| 286 | +| 过滤与边界 | 错误平台、错误技术、默认范围中的 draft/deprecated、无匹配结果，以及缺失/损坏/过期索引的处理；以现有契约定义预期结果，报告违反次数 | | ||
| 287 | +| 开销 | 在相同机器、语料和负载下报告查询耗时 p50/p95；变更涉及索引时补充构建时间和体积，涉及 Agent 调用时补充调用量或 token 成本 | | ||
| 288 | +| 下游效果 | 影响算子生成所用证据的召回、排序、查询改写或证据选择变更，须补代表性端到端算子生成对照；固定模型、提示词、语料、任务、平台与生成/修复预算，只替换待评估检索模块，实际编译并在目标设备验证，报告编译通过率、数值正确率、任务完成率及适用的性能达标率和成本；失败与超时保留在分母中 | | ||
| 289 | + | ||
| 290 | +仅索引、缓存等工程优化，若证明检索结果和行为一致，可只做检索回归与性能对照；无法证明时补端到端验证。较大版本更新运行完整端到端任务集。任务集、重复次数、性能标准和退化上限在实验前固定，保留代码与验证日志；检索指标提升不能直接推导任务成功。 | ||
| 291 | + | ||
| 292 | +例如修改排序时，可假设“目标查询 Hit@5 提升且既有场景不退化”，在实验前填写最低提升值、允许的耗时增幅和过滤违规上限，完成实验后填入实测值。该例是实验设计示意，不是仓库已有测量结果或统一阈值。 | ||
| 293 | + | ||
| 294 | +结果摘要可使用下表，每行注明样本数与统计口径，按实际指标增删。所有“待填”均须替换为实测记录；比例变化区分百分点和相对变化，缺少证据时填写“未验证”及原因。 | ||
| 295 | + | ||
| 296 | +| 场景/指标 | 样本数/重复次数 | A 基线 | B 候选 | 差值与波动 | 预设验收标准 | 是否达成 | 证据 | | ||
| 297 | +|---|---|---|---|---|---|---|---| | ||
| 298 | +| 目标场景的主指标 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | | ||
| 299 | +| 既有成功场景 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | | ||
| 300 | +| 错误输入与边界行为 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | | ||
| 301 | +| 耗时或资源成本 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | | ||
| 302 | + | ||
| 303 | +其他公共组件按职责选择指标：Lint/治理规则在 A/B 两组对同一批合法、非法输入比较接受、拒绝行为与误报；安装器比较受支持环境下的成功率、幂等性和失败时对用户文件的保护；Ingest 比较有效产物比例、内容保真和写入边界。确定性规则可以逐例对照，不要求所有组件都证明性能提升。常规单元测试和 `bash check.sh` 结果应一并提供，但不能代替 A/B 报告。 | ||
| 304 | + | ||
| 305 | +未执行、仅有实验计划或只报告 B 的结果，都不能标为实验通过。样本不足或结果波动大时如实说明结论限制，补充实验后再申请合入；未达到预设标准时说明原因、调整方案并重新验证，不能事后降低标准而不解释。 | ||
| 306 | + | ||
| 307 | +可复用评测用例和驱动放在 `evals/`；本地可重建报告放在 ignored 的 `artifacts/`。RFC/PR 中保留结果摘要，并附上评审者可访问的完整报告或复现材料，不能只提供作者机器上的绝对路径。Skill 内部命令仍由对应 `SKILL.md` 或 `references/` 维护，RFC/PR 引用这些说明并记录本次实际执行配置。 | ||
| 308 | + | ||
| 309 | +### 5.4 实现、验证并提交 PR | ||
| 158 | 310 | ||
| 159 | 当前维护 `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](governance/specs/skills.md)。新增其他 Skill 需要先证明现有职责无法合理承载，并完成架构和发布评审。 | 311 | 当前维护 `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](governance/specs/skills.md)。新增其他 Skill 需要先证明现有职责无法合理承载，并完成架构和发布评审。 |
| 160 | 312 | ||
| 161 | 本仓 Skill 的规范源位于 `.agents/skills/`，其中维护完整的 `SKILL.md`、`references/`、`scripts/` 及其他运行所需资源。治理、安装、检索与 CI 回归集中于 `evals/`；Ingest 使用全库确定性命令和仓库级回归，trace producer 保留专用脚本回归。规范源不包含 `agents/openai.yaml` 等单一客户端元数据。 | 313 | 本仓 Skill 的规范源位于 `.agents/skills/`，其中维护完整的 `SKILL.md`、`references/`、`scripts/` 及其他运行所需资源。治理、安装、检索与 CI 回归集中于 `evals/`；Ingest 使用全库确定性命令和仓库级回归，trace producer 保留专用脚本回归。规范源不包含 `agents/openai.yaml` 等单一客户端元数据。 |
| 162 | 314 | ||
| 163 | -Skill 贡献流程： | 315 | +采用 RFC 流程的公共组件实现与交付步骤（缺陷修复见第 2.1 节）： |
| 164 | 316 | ||
| 165 | -1. 修改知识仓中的规范源； | 317 | +1. 关联 RFC，按方案修改规范源；涉及治理规则时先修改唯一机器事实源，再同步消费者。 |
| 166 | -2. 更新该 Skill 的内部说明、Frontmatter 触发描述和测试； | 318 | +2. 更新受影响的文档和测试；Skill 变更同步内部说明、Frontmatter 触发描述和必要参考资料。 |
| 167 | -3. 验证触发条件、正常路径、错误路径和权限边界； | 319 | +3. 验证结构、触发条件、原有路径、新增能力、错误路径和权限边界；治理规则覆盖接受与拒绝案例，Query 覆盖过滤、排序或失败关闭语义；按变更范围完成下游验证。 |
| 168 | -4. 运行仓库统一质量门禁。 | 320 | +4. 完成 A/B test 并回填 RFC，记录实质治理或 Skill 契约变更的当天日志；提交前运行仓库统一质量门禁。 |
| 321 | +5. 提交关联 RFC 的 PR，按第 6 节提供交付材料，由 committer 检视后合入。 | ||
| 169 | 322 | ||
| 170 | Skill 中只保存完成工作所需的流程、工具和小型参考资料。可被多个 Skill 消费的 CANN、DSL、API、算子、调试和优化知识必须进入 `knowledge/`。 | 323 | Skill 中只保存完成工作所需的流程、工具和小型参考资料。可被多个 Skill 消费的 CANN、DSL、API、算子、调试和优化知识必须进入 `knowledge/`。 |
| 171 | 324 | ||
| 172 | -## 6. PR 说明 | 325 | +## 6. PR 提交、committer 检视与合入 |
| 173 | 326 | ||
| 174 | -每个 PR 至少说明： | 327 | +### 6.1 PR 交付材料 |
| 175 | 328 | ||
| 176 | -- 贡献类型和影响范围； | 329 | +PR 应让评审者沿“问题 → 方案 → 产物 → 证据”核对本次贡献。可在现有 PR 表单中补充以下内容，不适用项说明原因： |
| 177 | -- 知识来源与验证证据； | 330 | + |
| 178 | -- 新增、更新、合并、拆分、废弃或延后的决定； | 331 | +```markdown |
| 179 | -- 实际完成的检查和结果； | 332 | +### 关联与范围 |
| 180 | -- 对检索、Schema、链接/图谱、安装或兼容性的影响； | 333 | + |
| 181 | -- 需要 reviewer 重点判断的风险。 | 334 | +- 贡献类型：知识建设 / 公共组件新增或优化 / 缺陷修复（知识或工具）/ 说明文档。 |
| 335 | +- 关联知识 Issue / RFC：常规贡献填写，缺陷修复与轻量修订可填“无”。 | ||
| 336 | +- 解决的问题、实际改动文件与范围： | ||
| 337 | + | ||
| 338 | +### 交付与效果 | ||
| 339 | + | ||
| 340 | +- 知识建设：处理决定、来源、生产方法、验收场景及实际结果。 | ||
| 341 | +- 采用 RFC 流程的公共组件：RFC 方案、A/B 版本、实验报告链接、关键指标与验收结论。 | ||
| 342 | +- 缺陷修复：问题、修复内容和影响；知识修正的证据，或工具问题的复现方式；定向验证与回归结果。 | ||
| 343 | +- 公共组件兼容性：默认流程/接口/行为是否变化及相关验证；新增能力说明扩展接入点，主动行为调整补充影响及迁移方案（如适用）。 | ||
| 344 | +- 与原计划的差异、剩余限制及回退方法（如适用）： | ||
| 345 | + | ||
| 346 | +### 检查与评审重点 | ||
| 347 | + | ||
| 348 | +- 实际执行的检查、对应版本和结果；未执行或失败项及原因。 | ||
| 349 | +- 已同步的导航、链接、日志、规则消费者、文档与测试。 | ||
| 350 | +- 对检索、Schema、图谱、安装或兼容性的影响，以及需要 committer 重点判断的风险。 | ||
| 351 | +``` | ||
| 352 | + | ||
| 353 | +### 6.2 committer 检视与合入条件 | ||
| 354 | + | ||
| 355 | +| 检视对象 | committer 核对内容 | | ||
| 356 | +|---|---| | ||
| 357 | +| 常规知识建设 PR | Issue 中的缺口是否得到解决；生产方法、来源、平台与版本范围是否支撑结论；有无重复或错误泛化；目标场景的实际效果是否可复核 | | ||
| 358 | +| 采用 RFC 流程的公共组件 PR | RFC 是否解释必要性、扩展接入和方案取舍；主动行为调整是否说明扩展方式不足、影响及迁移/回退；原有路径与新增能力是否均有验证；A/B 是否达到预设标准，回归、成本和权限边界是否可接受 | | ||
| 359 | +| 缺陷修复 PR | 问题与修复依据是否清楚，证据或复现材料能否核对；定向验证是否证明修复有效，相关回归是否通过；无前置 Issue/RFC 或完整 A/B 不影响按简化路径检视 | | ||
| 360 | +| 所有 PR | 改动是否限于目标范围；文档、导航和日志是否按需同步；检查结果是否对应当前差异；评审意见是否解决 | | ||
| 361 | + | ||
| 362 | +贡献者负责补充证据和处理评审意见，committer 负责判断内容与方案是否可接受、要求必要的复跑或抽查，并记录通过或需修改的意见。自动检查通过只证明所覆盖的检查通过，不能代替内容与效果检视。 | ||
| 363 | + | ||
| 364 | +合入前必须满足：对应贡献类型的材料完整、适用的验收标准达成、阻断性评审意见已解决、当前待合入版本的 `bash check.sh` 通过，并获得 committer 的明确认可。采用 RFC 流程且主动调整默认流程、接口或既有行为时，评审结论应明确记录对兼容性、迁移与回退方案的判断；缺陷修复检视问题、影响与修复证据。评审后修改了影响验证结论的内容，应更新对应检查及适用的 A/B 结果。由 committer 执行合入；有关联 Issue/RFC 时回填 PR 与处理结果，仍有缺口时保留未完成范围。材料不足时继续补充或记录 defer/关闭原因，不先合入再补证据。 | ||
| 182 | 365 | ||
| 183 | ## 7. 不接受的贡献 | 366 | ## 7. 不接受的贡献 |
| 184 | 367 | ||
| @@ -136,7 +136,13 @@ Operator 卡按 `operators/<aclnn|direct>/<cv|math|nn|transformer>/<category>/<o | |||
| 136 | 136 | ||
| 137 | ## 贡献和检查 | 137 | ## 贡献和检查 |
| 138 | 138 | ||
| 139 | -贡献知识前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。它说明如何查重、选择路径、准备来源、编写知识卡、更新导航和提交 Skill 变更。 | 139 | +贡献前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，按贡献类型准备材料： |
| 140 | + | ||
| 141 | +- **知识建设（缺陷修复除外）**：先提交 Issue，说明知识缺口、生产方法和预期效果；完成知识卡与效果验证后提交关联 PR，由 committer 检视后合入。 | ||
| 142 | +- **公共组件新增、优化或主动行为调整（如检索 Skill，缺陷修复除外）**：遵循“扩展优先、保持兼容”，先提交 RFC，说明当前问题、修改必要性和接入方案；主动改变既有行为时补充影响、迁移与回退说明。完成 A/B test 和原有路径/新增能力验证后提交关联 PR，由 committer 检视后合入。 | ||
| 143 | +- **缺陷修复与轻量修订**：知识错误、检索脚本 bug 等可直接提交 PR，无需前置 Issue/RFC 或完整 A/B 实验；提供修复依据与定向验证结果，满足适用检查并由 committer 检视后合入。纯排版、错别字和不改变组件行为的说明文档修订也适用；包含新增能力或主动流程调整时应拆分贡献。 | ||
| 144 | + | ||
| 145 | +贡献指南提供可填写的 Issue、RFC、PR 正文，以及 A/B 实验和合入要求；写卡操作可参照[贡献知识](recipes/contribute_knowledge.md)。 | ||
| 140 | 146 | ||
| 141 | 提交前运行： | 147 | 提交前运行： |
| 142 | 148 | ||
| @@ -144,7 +150,7 @@ Operator 卡按 `operators/<aclnn|direct>/<cv|math|nn|transformer>/<category>/<o | |||
| 144 | bash check.sh | 150 | bash check.sh |
| 145 | ``` | 151 | ``` |
| 146 | 152 | ||
| 147 | -该入口恢复并校验登记资源，再执行知识 Lint、归档复验、索引与检索回归、单元测试、Ruff 和 Shell 语法检查。图谱和 API 引用建议按需生成，不属于入库门禁。 | 153 | +该入口执行知识 Lint、导航检查、索引与检索回归、单元测试、Ruff、Shell 语法及归档镜像差异检查，不主动获取或严格复验滚动官方来源。图谱和 API 引用建议按需生成，不属于入库门禁。 |
| 148 | 154 | ||
| 149 | ## 治理规范 | 155 | ## 治理规范 |
| 150 | 156 | ||
| @@ -16,7 +16,9 @@ | |||
| 16 | | `ops-knowledge-vv-ingest` | 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 | 不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 | 只写任务指定的最终卡 | | 16 | | `ops-knowledge-vv-ingest` | 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 | 不含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 | 只写任务指定的最终卡 | |
| 17 | | `ops-knowledge-cv-ingest` | 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 | 含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 | 只写任务指定的最终卡 | | 17 | | `ops-knowledge-cv-ingest` | 固定版本源码、唯一逻辑算子、入口、平台和独占目标文件 | 含可达 Cube/AIC 或 MIX_CV 节点的源码级 Operator 卡 | 只写任务指定的最终卡 | |
| 18 | 18 | ||
| 19 | -典型贡献流程是先 Query 查重；通用来源由 Ingest 形成候选卡，本仓内的开发 trace 由 Ingest 路由到 trace producer，源码级完整算子由 VV/CV 中唯一匹配执行族边界的 producer 直接写目标卡；随后执行全库 Lint，最后用目标条件验证新卡可以被 Query 召回。只读问答不需要执行完整流程；人工编辑已有卡也可以不用创建能力，但仍应查重、Lint 和验证召回。 | 19 | +常规知识建设按[贡献指南](../../CONTRIBUTING.md)先用 Query 查重并提交知识 Issue，明确缺口、生产方法和预期效果；通用来源由 Ingest 形成候选卡，本仓内的开发 trace 由 Ingest 路由到 trace producer，源码级完整算子由 VV/CV 中唯一匹配执行族边界的 producer 直接写目标卡；随后执行全库 Lint，用目标条件验证召回和验收场景，再提交关联 PR，由 committer 检视后合入。知识错误修复可直接在 PR 中提供修正依据与场景验证，无需前置 Issue，仍须满足适用的知识检查。只读问答不需要执行完整流程；人工编辑已有卡也可以不用创建能力，但仍应查重、Lint 和验证召回。 |
| 20 | + | ||
| 21 | +Skill 等公共组件的新增、优化或主动行为调整按同一贡献指南提交 RFC、提供 A/B 实验报告，再提交关联 PR 供 committer 检视。新增能力扩展优先并保持兼容，优先复用现有接入点；内部重构可修改原实现，主动改变既有行为须说明影响、迁移与回退，并验证原有路径和新增能力。检索脚本 bug 等纠正错误或恢复既定行为的缺陷修复可直接提交 PR，无需前置 Issue/RFC 或完整 A/B，仍须提供复现方式、修复依据与相关回归结果；含新增能力或主动流程调整的改动应拆分贡献。具体材料与检视条件由贡献指南统一维护；这些外层评审要求不增加各 Skill 的执行和写入权限。 | ||
| 20 | 22 | ||
| 21 | ## Query | 23 | ## Query |
| 22 | 24 | ||
| @@ -0,0 +1,15 @@ | |||
| 1 | +# 2026-09-22 | ||
| 2 | + | ||
| 3 | +## [12:00] governance | 细化知识与公共组件贡献流程 | ||
| 4 | + | ||
| 5 | +### Summary | ||
| 6 | + | ||
| 7 | +将贡献流程明确为知识 Issue → 知识生产与效果验证 → PR → committer 检视合入，以及公共组件 RFC → 实现与 A/B 实验 → PR → committer 检视合入，并在贡献指南提供可填写的材料模板。 | ||
| 8 | + | ||
| 9 | +### Details | ||
| 10 | + | ||
| 11 | +- `CONTRIBUTING.md`：知识 Issue 覆盖缺口、已有检索、生产方法、来源、预期效果和验收场景；公共组件 RFC 覆盖问题、必要性、方案取舍、兼容性和回退。补充 A/B 的版本、数据集、控制变量、重复与统计口径、完整结果、复现材料和结果表，以及检索 Skill 的指标示例。PR 明确交付材料、committer 职责和合入条件。 | ||
| 12 | +- `README.md`、`recipes/contribute_knowledge.md`、`governance/specs/skills.md`：同步两类流程入口、知识贡献步骤和外层评审边界；`AGENTS.md` 增加长期贡献约定，保留外部提交授权要求，`CLAUDE.md` 继续通过原有符号链接保持一致。 | ||
| 13 | +- 模板直接放在贡献指南中供现有 Issue/PR 表单补充使用；未修改 `.gitcode/`、知识正文、Skill 实现、机器规则或测试实现，也未新增自动化审批能力。 | ||
| 14 | +- 已运行 `evals/test_documentation.py` 的 6 项定向检查：本次修改文件的本地链接、Markdown 结构、README 文档导航、治理 Spec 导航、外部文档的 Skill CLI 边界和 Agent 指令一致性，全部通过；`git diff --check` 通过。 | ||
| 15 | +- 本次仅修改流程文档，未运行组件 A/B 实验；文中的实验表格为待填写模板，没有声称实测收益。未执行 commit、push 或外部 Issue/PR 提交，未运行 `bash check.sh` 全库门禁，留待上库前执行。 | ||
| @@ -0,0 +1,43 @@ | |||
| 1 | +# 2026-09-23 | ||
| 2 | + | ||
| 3 | +## [11:24] governance | 贡献流程修改的提交前验证 | ||
| 4 | + | ||
| 5 | +### Summary | ||
| 6 | + | ||
| 7 | +按用户要求，将本地 `origin` 切换到 `https://gitcode.com/qq_41667743/cannbot-knowledge.git`，基于远端 `opt_contribution` 分支保留已有提交并准备贡献流程文档改动。运行完整门禁及其停止后的剩余检查，记录本次改动范围之外的失败。 | ||
| 8 | + | ||
| 9 | +### Details | ||
| 10 | + | ||
| 11 | +- 待提交范围为五份贡献流程文档与两份治理日志；相对目标分支没有知识正文、Skill 实现、机器规则、测试实现或 `.gitcode/` 差异。 | ||
| 12 | +- `bash check.sh`：全库 Lint 检查 7,706 个文件，P0/P1/P2 均为 0；662 个导航索引无过期项；检索索引构建和完整校验通过。检索回归 29 个功能用例全部通过，recall@k 与 MRR 均为 1.000，但 p95 为 1,706.4 ms，超过 1,000 ms 阈值，门禁在此停止。单独复跑功能结果不变，p95 为 1,693.5 ms，仍未通过耗时门禁。 | ||
| 13 | +- 单独补跑剩余门禁：仓库测试执行 266 项，2 项失败、1 项错误、1 项跳过。`test_knowledge_cards_use_okf_core_fields` 的 Frontmatter 切分解析在 `knowledge/ops/ascendc/optimizations/fa_cross_core_sync_workspacequeue.md` 报错；`test_knowledge_does_not_refer_to_retired_a5_card_suffix` 命中五处现有旧命名引用；`test_registered_structure_is_materialized` 的“不存在”断言与现有 `knowledge/contrib/ascendc` 目录冲突。已核对相关知识、测试、检索实现和配置与远端目标分支完全一致，未扩大范围修复这些问题。 | ||
| 14 | +- 36 项 trace producer 测试、1,396 张 Runbook 正文检查、Ruff、Shell 语法和官方归档差异检查均通过；暂存内容的 `git diff --cached --check` 通过。完整门禁未通过，不能将本次验证记录为全绿；完整输出保存在 Git 忽略的 `artifacts/validation/opt_contribution_*.log`。 | ||
| 15 | + | ||
| 16 | +## [10:56] governance | 为缺陷修复补充直接提交 PR 的贡献路径 | ||
| 17 | + | ||
| 18 | +### Summary | ||
| 19 | + | ||
| 20 | +按更新后的贡献流程 RFC，同步知识错误和检索脚本 bug 等缺陷修复的简化路径：无需前置 Issue/RFC 或完整 A/B，直接提交附修复依据与定向验证结果的 PR，由 committer 检视后合入。 | ||
| 21 | + | ||
| 22 | +### Details | ||
| 23 | + | ||
| 24 | +- `CONTRIBUTING.md`：新增缺陷修复与轻量修订说明，同步流程分类、知识检查清单、组件兼容性说明、A/B 适用范围、PR 材料及合入条件；保留适用检查与上库前 `bash check.sh`，修复包含新增能力或主动流程调整时应拆分贡献。 | ||
| 25 | +- `README.md`、`AGENTS.md`、`governance/specs/skills.md`、`recipes/contribute_knowledge.md`：同步简化路径，明确常规知识建设与组件优化仍按 Issue/RFC 流程；知识修复可在 PR 中记录问题、依据和场景结果，有关联 Issue 时再回填。现有 PR 表单已允许关联 Issue 填“无”，继续沿用。 | ||
| 26 | +- 人工走查流程边界：有证据和验证的知识错误或脚本 bug 修复可直接进入 PR 检视；新增知识覆盖与检索优化仍需各自的前置材料；混合修复与新增能力不能整体豁免。该走查不代表已完成真实贡献效率实验。 | ||
| 27 | +- 已运行 6 项现有定向文档检查，覆盖改动文件的本地链接、Markdown 结构、README 文档与 Spec 导航、Skill CLI 说明边界和 Agent 指令一致性，全部通过；`git diff --check` 通过。 | ||
| 28 | +- 保留原有工作区改动与历史日志。本次仅修改流程文档，未修改知识正文、机器规则、Skill 实现或 `.gitcode/`，未提交或推送；未运行 A/B、端到端算子生成或全库门禁，`bash check.sh` 留待上库前执行。 | ||
| 29 | + | ||
| 30 | +## [10:26] governance | 按贡献流程 RFC 完善组件扩展与兼容性要求 | ||
| 31 | + | ||
| 32 | +### Summary | ||
| 33 | + | ||
| 34 | +在已有贡献流程改动上落实“扩展优先、保持兼容”：允许缺陷修复和内部重构修改原实现，默认流程、接口或既有行为变化须说明必要性、影响、迁移与回退，并提供原有路径和新增能力的验证证据。 | ||
| 35 | + | ||
| 36 | +### Details | ||
| 37 | + | ||
| 38 | +- `CONTRIBUTING.md`：同步兼容性原则、接受与需补充材料的场景、RFC 和 PR 模板、A/B 样本范围及 committer 检视条件；明确实验计划与组件 PR 实测材料的交付时机，规则类改动可以对同一批合法/非法输入逐例比较。同步此前确认的检索变更端到端算子生成验证要求及工程优化的适用边界。 | ||
| 39 | +- `README.md`、`governance/specs/skills.md`、`AGENTS.md`：同步扩展接入、兼容性说明和原有路径/新增能力验证边界；核对 `check.sh` 后修正 README 中“自动恢复资源、严格归档复验”的不实说明。`CLAUDE.md` 保留原有符号链接。 | ||
| 40 | +- `recipes/contribute_knowledge.md`：验收场景和结果记录明确包含输入条件、预期结果、实际结果和证据。 | ||
| 41 | +- 人工按文档走查材料判定：知识贡献有来源及场景结果可进入内容检视，只有卡片数量或 Lint 结果不足；可选扩展需保留默认路径并验证两条路径；缺陷修复允许修改实现；未说明迁移影响的默认流程切换须补充材料。该走查不代表真实贡献效率实验或合入认可。 | ||
| 42 | +- 已使用 `evals/test_documentation.py` 运行 6 项定向检查，覆盖改动文件的本地链接、Markdown 结构、README 文档导航、治理 Spec 导航、外部文档的 Skill CLI 边界和 Agent 指令一致性，全部通过；`git diff --check` 通过。 | ||
| 43 | +- 保留此前工作区改动与 2026-09-22 日志；未修改知识正文、机器规则、Skill 实现、测试实现或 `.gitcode/`，未提交、推送或创建外部 Issue/PR。本次仅完善流程文档，未执行检索 A/B、端到端算子生成或 `bash check.sh` 全库门禁；完整门禁留待上库前运行。 | ||
| @@ -2,7 +2,7 @@ | |||
| 2 | 2 | ||
| 3 | ## 目标 | 3 | ## 目标 |
| 4 | 4 | ||
| 5 | -把一条有来源、有适用范围的工程知识放到仓库中的正确位置，并确认它能通过检查和查询。 | 5 | +把一条有来源、有适用范围的工程知识放到仓库中的正确位置，验证它能解决原始缺口或修复已有错误，再提交 PR 供 committer 检视、合入。常规知识建设从 Issue 出发，知识错误修复可直接提交 PR；正式流程和材料要求见[贡献指南](../CONTRIBUTING.md)。 |
| 6 | 6 | ||
| 7 | ## 适用场景 | 7 | ## 适用场景 |
| 8 | 8 | ||
| @@ -32,25 +32,30 @@ | |||
| 32 | 32 | ||
| 33 | 1. **先搜索已有知识。** 使用 `knowledge-query` 搜索相同主题并阅读候选卡。不要只比较标题，还要比较内容范围和来源。 | 33 | 1. **先搜索已有知识。** 使用 `knowledge-query` 搜索相同主题并阅读候选卡。不要只比较标题，还要比较内容范围和来源。 |
| 34 | 2. **选择处理方式。** 明确本次是 create、update、merge、split、deprecate 还是 defer。如果无法判断，先不要写文件。 | 34 | 2. **选择处理方式。** 明确本次是 create、update、merge、split、deprecate 还是 defer。如果无法判断，先不要写文件。 |
| 35 | -3. **选择保存位置。** 根据领域、技术和知识类型选择路径。只有不依赖单一技术的结论才能放进 `shared`。 | 35 | +3. **准备问题与验收材料。** 常规知识建设按贡献指南提交或补充 Issue，记录缺口、生产方法和预期效果，并选一个包含输入条件与预期结果的任务作为验收场景。知识错误修复按指南的简化路径，在 PR 材料中说明错误、修正依据和验证场景，无需先提 Issue。 |
| 36 | -4. **整理来源。** 完整阅读并固定来源。区分来源中明确写出的事实、合理推导和仍需验证的内容。 | 36 | +4. **选择保存位置。** 根据领域、技术和知识类型选择路径。只有不依赖单一技术的结论才能放进 `shared`。 |
| 37 | -5. **编写知识卡。** 使用 `knowledge-ingest` 或人工编辑。通常写清结论、适用条件、限制和验证方法，更新已有卡片时不要整体覆盖；Registry 文档归档的官方 API/Guide 则按声明过滤导航页和冗余章节，保留其余来源正文，只修改链接目标并添加 Frontmatter/可选的普通链接。 | 37 | +5. **整理来源。** 完整阅读并固定来源。区分来源中明确写出的事实、合理推导和仍需验证的内容。 |
| 38 | -6. **人工检查内容。** 检查标题、路径、文件开头的结构化信息、正文、来源和链接。脚本运行成功不代表内容正确。 | 38 | +6. **编写知识卡。** 使用 `knowledge-ingest` 或人工编辑。通常写清结论、适用条件、限制和验证方法，更新已有卡片时不要整体覆盖；Registry 文档归档的官方 API/Guide 则按声明过滤导航页和冗余章节，保留其余来源正文，只修改链接目标并添加 Frontmatter/可选的普通链接。 |
| 39 | -7. **更新导航和日志。** 新增、删除或移动卡片时更新各级 `index.md`。实质知识变更需要记录当天日志。 | 39 | +7. **人工检查内容。** 检查标题、路径、文件开头的结构化信息、正文、来源和链接。脚本运行成功不代表内容正确。 |
| 40 | -8. **运行全库 Lint。** 修复路径、字段、导航、链接、来源和日志问题。 | 40 | +8. **更新导航和日志。** 新增、删除或移动卡片时更新各级 `index.md`。实质知识变更需要记录当天日志。 |
| 41 | -9. **准备索引并验证查询。** 由知识仓维护者按 Query Skill 的索引维护流程重建并验证检索索引，再使用真实的平台和技术条件查询，确认新知识能被找到，也不会出现在错误范围中。Query 不自动重建索引，也不按 CANN 版本过滤，版本边界需要在命中正文中核对。 | 41 | +9. **运行全库 Lint。** 修复路径、字段、导航、链接、来源和日志问题。 |
| 42 | -10. **运行完整检查。** 确认仓库质量门禁通过。不要自动提交、推送或发布。 | 42 | +10. **准备索引并验证效果。** 由知识仓维护者按 Query Skill 的索引维护流程重建并验证检索索引，再使用真实的平台和技术条件查询，确认新知识能被找到，也不会出现在错误范围中。Query 不自动重建索引，也不按 CANN 版本过滤，版本边界需要在命中正文中核对。回到 Issue 或修复 PR 中的验证场景，记录卡片如何支持答案或操作，以及仍未覆盖的边界。 |
| 43 | +11. **运行完整检查并提交 PR。** 确认仓库质量门禁通过，按贡献指南整理关联 Issue（如有）、变更和实际验证结果。Agent 准备本地材料后，外部提交仍需遵守当前任务授权。 | ||
| 44 | +12. **处理检视意见。** 补充 committer 要求的证据或修订；检视通过后由 committer 合入，有关联 Issue 时回填处理结果。 | ||
| 43 | 45 | ||
| 44 | ## 预期产物 | 46 | ## 预期产物 |
| 45 | 47 | ||
| 46 | 可以使用下面的格式记录结果： | 48 | 可以使用下面的格式记录结果： |
| 47 | 49 | ||
| 48 | ```text | 50 | ```text |
| 51 | +关联 Issue：<常规知识建设必填；知识错误修复可填“无”> | ||
| 49 | 处理方式：<create / update / merge / split / deprecate / defer> | 52 | 处理方式：<create / update / merge / split / deprecate / defer> |
| 50 | 知识范围：<领域、技术、知识类型、平台和版本> | 53 | 知识范围：<领域、技术、知识类型、平台和版本> |
| 51 | 来源：<支持结论的材料> | 54 | 来源：<支持结论的材料> |
| 52 | 文件变化：<知识卡、导航、链接和日志> | 55 | 文件变化：<知识卡、导航、链接和日志> |
| 53 | 检查结果：<全库 Lint、目标查询和完整门禁> | 56 | 检查结果：<全库 Lint、目标查询和完整门禁> |
| 57 | +实际效果：<原问题、输入条件、预期结果、实际结果及可复核证据> | ||
| 58 | +关联 PR：<链接与 committer 检视状态；尚未提交则注明> | ||
| 54 | 剩余问题：<来源、范围或兼容性限制> | 59 | 剩余问题：<来源、范围或兼容性限制> |
| 55 | ``` | 60 | ``` |
| 56 | 61 | ||
| @@ -67,6 +72,7 @@ | |||
| 67 | - 相关 `index.md`、链接和日志已经更新。 | 72 | - 相关 `index.md`、链接和日志已经更新。 |
| 68 | - 全库 Lint 通过，目标查询能够找到新知识。 | 73 | - 全库 Lint 通过，目标查询能够找到新知识。 |
| 69 | - 完整质量门禁通过。 | 74 | - 完整质量门禁通过。 |
| 75 | +- Issue 或修复 PR 中的验证场景已有实际结果，PR 提供对应证据供 committer 检视。 | ||
| 70 | 76 | ||
| 71 | ## 失败与停止条件 | 77 | ## 失败与停止条件 |
| 72 | 78 | ||
| @@ -75,6 +81,7 @@ | |||
| 75 | - 来源或适用范围不满足所选 Profile 与生命周期的要求时，保留为 `draft`（草稿）或选择 defer，具体边界见 [Frontmatter 与证据](../governance/specs/frontmatter.md)。轨迹 Runbook 的 `sources: []` 例外不免除平台要求。 | 81 | - 来源或适用范围不满足所选 Profile 与生命周期的要求时，保留为 `draft`（草稿）或选择 defer，具体边界见 [Frontmatter 与证据](../governance/specs/frontmatter.md)。轨迹 Runbook 的 `sources: []` 例外不免除平台要求。 |
| 76 | - 规则文件、程序行为和文档互相矛盾：先修复规则体系。 | 82 | - 规则文件、程序行为和文档互相矛盾：先修复规则体系。 |
| 77 | - Lint 失败或目标查询找不到新知识：不能认为贡献已经完成。 | 83 | - Lint 失败或目标查询找不到新知识：不能认为贡献已经完成。 |
| 84 | +- 验收场景尚不能证明缺口已解决：如实回填剩余问题，继续补证或 defer，按贡献指南判断是否具备合入条件。 | ||
| 78 | - 材料包含密钥、账号、内网地址、私有路径或不可公开数据：停止写入并清理敏感内容。 | 85 | - 材料包含密钥、账号、内网地址、私有路径或不可公开数据：停止写入并清理敏感内容。 |
| 79 | 86 | ||
| 80 | ## 相关规则和延伸阅读 | 87 | ## 相关规则和延伸阅读 |