03 · 知识审核 · 落地方案
03 · 知识审核 · 落地方案
对应蓝图 §4。本文解决：通过 AI 审核的知识草稿，经过怎样的人工评审才能变为正式知识？
状态：草案（R1.3 / R1.4 / R2.2 / R3.3 / R3.4 / R4.1 / R4.2 待确认，见 §10）
前置依赖：02-知识验证（知识草稿已通过 AI 审核门控）
关联文档：02-知识验证（CI 校验）· 04-知识存储（状态字段与元数据）· 09-度量评价与落地路径（角色与兼任约束）
1. 定位与边界
审核采用 Owner 团队制——每条知识的归属团队负责审核其准确性与可操作性。审核通过 GitLab MR 流程完成，CODEOWNERS 自动分配 Reviewer，审核结果直接驱动 status: draft → active 的状态流转。
2. 审核架构
2.1 代码 MR 内夹带的草稿 vs 独立知识 MR
01-知识生成 D1.4 已确认「知识草稿与代码变更同一 MR 提交」，而本文审核流程假设独立知识 MR。两者必须显式分流，否则代码 MR 里夹带的草稿要么无人审核，要么把 §5.2 的 1–5 个工作日审核周期压到代码合并路径上：
| 场景 | 落点 | 是否走本文审核流程 | 理由 |
|---|---|---|---|
| 随代码 MR 产生的新草稿 | _drafts/{module}/{topic}.md，status: draft | 否，随代码 MR 直接合并 | 草稿不是可检索知识，索引 Pipeline 只收录 active；让它阻塞代码合并会把知识成本转嫁到交付路径上 |
| 草稿激活为正式知识 | 单独开「激活 MR」，移动到 docs/knowledge/ 并改 status: active | 是，走本文完整流程 | 激活即进入检索范围，必须经 Owner 审核 |
| 直接编写的正式知识 | docs/knowledge/，status: draft → 同 MR 内改 active | 是 | 见 §5.1 |
激活 MR 由谁在何时创建：由 §6.2 的周期扫描产出待激活清单，指派给条目 owner_group；不依赖作者主动记得。
3. Owner 团队制
3.1 责任模型
# frontmatter
owner_group: ocp/backend # 知识归属团队（权威）
steward: zhangsan # 知识管家（显式声明优先）Steward 回退规则：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | frontmatter steward 字段 | 显式声明，权威 |
| 2 | CODEOWNERS 派生 | 未声明时回落，派生结果必须写回 frontmatter 固化 |
为什么不能取「第一个 maintainer」：GET /groups/:id/members/all 的返回顺序不承载资历语义，官方文档也未承诺排序稳定性。组成员集合一变，被取到的「第一个」就可能换人，steward 随之无声漂移。结论只依赖「顺序无语义且不保证稳定」，不依赖具体排序字段。
3.2 CODEOWNERS 配置
# CODEOWNERS 文件
[Knowledge][1]
docs/knowledge/payment/** @ocp/payment-team @ocp/backend-maintainers
docs/knowledge/user/** @ocp/user-team @ocp/backend-maintainers
# 草稿目录必须显式覆盖：Code Owner 审核按路径匹配生效，
# 漏掉 _drafts/ 则草稿 MR 既不触发审核也不自动指派 Reviewer，
# 「草稿 → 审核 → active」链路的第一环没有机制承接
_drafts/payment/** @ocp/payment-team @ocp/backend-maintainers
_drafts/user/** @ocp/user-team @ocp/backend-maintainers
# 派生结果：
# owner_group → ocp/payment-team（从 frontmatter，权威）
# steward → frontmatter 的 steward 字段（权威）
# 未声明时回落：@ocp/payment-team 的 maintainer 列表
# 回落结果必须由 CI 写回 frontmatter 固化
# approvers → @ocp/backend-maintainers（从 CODEOWNERS）
# min_approvals → 1（从 [Knowledge][1] section 声明）CODEOWNERS 语义要点：
- 同一路径写多个 owner 时，GitLab 的 Code Owner 审核是任一批准即满足
- 需要多人会签时用
[Section][N]声明最少批准数——该能力属 Premium/Ultimate，Free 层写了也不生效，会形成静默失效的假门禁。R1.3 若选 B（2 人会签）须先确认许可证层级 - CODEOWNERS 审核与 MR 的常规 approval 规则是两套独立机制
- 「CODEOWNERS 自动分配 Reviewer」是项目设置项（Settings → Merge requests → Code Owner approval），需显式开启，不是配置了 CODEOWNERS 文件就自动生效
3.3 关键决策点
| # | 决策 | 已确认 | 说明 |
|---|---|---|---|
| R1.1 | Owner 归属 | ✅ 业务团队，非平台组 | 平台组不了解业务语义，代管等于无人负责 |
| R1.2 | Steward 来源 | ✅ frontmatter 显式声明优先 | 未声明时回落 CODEOWNERS，但必须写回固化 |
| R1.3 | 最少批准数 | 待确认 | 选项：A) 1 人批准即可；B) 2 人会签（Owner + 独立 Reviewer） |
| R1.4 | CODEOWNERS 路径粒度 | 待确认 | 选项：A) 按域（docs/knowledge/payment/**）；B) 按模块（docs/knowledge/payment/refund/**） |
4. 审核标准
4.1 五维审核清单
| 维度 | 通过标准 | 驳回标准 |
|---|---|---|
| 准确性 | 知识描述与 source_uri 指向的代码/文档一致 | 描述与实际实现不符 |
| 可操作性 | Agent 读后能做出正确的编码/设计决策 | 过于抽象，无法指导具体操作 |
| 完整性 | 包含背景、方案、正反例三要素 | 缺少关键边界条件或异常场景 |
| 必要性 | 填补了知识空白或显著改进了已有知识 | 与已有知识高度重复，或价值过低 |
| 时效性 | source_revision 指向最近的 commit | 源文件已大幅变更，知识可能过时 |
4.2 审核 Checklist（MR 评论模板）
## 知识审核 Checklist
- [ ] **准确性**：已核对 source_uri 指向的代码/文档，知识描述与实际一致
- [ ] **可操作性**：Agent 读后能做出正确决策（非泛泛而谈）
- [ ] **完整性**：包含背景、方案、正反例三要素
- [ ] **必要性**：填补了知识空白（非重复已有条目）
- [ ] **时效性**：source_revision 指向近期 commit
### 审核意见
<!-- Approve / Request Changes / Comment -->4.3 关键决策点
| # | 决策 | 已确认 | 说明 |
|---|---|---|---|
| R2.1 | 审核维度 | ✅ 五维（准确性/可操作性/完整性/必要性/时效性） | 与蓝图 §4.3 一致 |
| R2.2 | 审核 Checklist 模板 | 待确认 | 选项：A) 固定在 MR 模板中；B) 由 CI 自动生成评论 |
5. 审核流程
5.1 草稿 → 正式知识的流转
为什么不在 approve 后再「移动到 docs/knowledge/」：移动 = 改路径 = 改 CODEOWNERS 匹配结果，可能重置或重新触发审批；若改由 CI 在合并后移动，则需要第二个 MR（CI 无权直推保护分支）并额外配置机器人账号的写权限。推荐方案：条目直接提交到最终路径 docs/knowledge/{module}/{topic}.md，全程只改 status 字段不改路径；_drafts/ 仅用于「随代码 MR 夹带、尚未进入审核」的暂存草稿（见 §2.1 分流规则），索引 Pipeline 只收录 status: active，因此草稿落在正式目录也不会被检索到（蓝图 §5.4）。
5.2 审核周期管理
| 知识类型 | 期望审核周期 | 超期处理 |
|---|---|---|
| 安全/合规/资金/权限 | 1 个工作日 | 升级通知 owner_group 的 GitLab Owner 角色成员 |
| Contract（接口/表结构） | 2 个工作日 | 提醒 Reviewer |
| Procedure / Policy | 3 个工作日 | 提醒 |
| Concept / Decision / FAQ | 5 个工作日 | 不主动催促 |
本表以 R3.3 确认为准：R3.3 目前仍为「待确认」，推荐 B（超期升级）。在确认之前，「超期处理」列只是建议值，不构成已生效的机制。
期望周期本身是阈值待实测的量化目标，无外部依据，须按团队实际响应能力观测后校准（与蓝图 §10.4.2「审核周期 ≤ 2 工作日」同口径）。
「Owner 团队负责人」在 GitLab 数据模型中不存在——GitLab 只有 Owner / Maintainer / Developer 等角色，没有「负责人」概念。升级对象须落到可解析的数据源：owner_group 中具 Owner 角色的成员，或外部组织表。
5.3 关键决策点
| # | 决策 | 已确认 | 说明 |
|---|---|---|---|
| R3.1 | 草稿存放位置 | ✅ _drafts/ 目录 | 与 01-知识生成一致 |
| R3.2 | 审核通过后移动目标 | ✅ docs/knowledge/ | 与蓝图 §5.3 一致 |
| R3.3 | 审核周期是否强制 | 待确认 | 选项：A) 仅建议，不阻断；B) 超期自动升级；C) 超期阻断 MR |
| R3.4 | 审核驳回后的处理 | 待确认 | 选项：A) 作者自行修改后重新提交；B) Reviewer 直接修改后 Approve |
6. 离职资产转移
6.1 风险场景
当 Steward 离职或转岗时，其负责的知识条目变成「无人维护」状态。
6.2 检测机制
# 由 §7 S4 的 Pipeline Schedule 每日触发（非 MR 上下文，可安全写 flags）
for entry in knowledge_entries(status == "active"):
if not entry.steward:
# 空值不是孤儿：属「尚未派生」。先走蓝图 §4.1 的写回固化流程，
# 固化失败才升级为 owner_missing，否则每条新条目都会误报
entry.steward = derive_and_persist(entry.owner_group) # 提 MR 写回 frontmatter
if not entry.steward:
mark(entry, "owner_missing")
elif entry.steward not in gitlab_group_members(entry.owner_group):
mark(entry, "owner_missing")
else:
continue
# 告警通道须明确：GitLab Issue（打 owner_missing 标签并指派 owner_group）
# 或企业 IM Webhook。不能只写 alert() 而不落地到具体通道
notify(owner_group_of(entry), channel="gitlab_issue")
def mark(entry, flag):
entry.flags = sorted(set(entry.flags) | {flag}) # 幂等，避免每日重复追加
entry.flagged_at = now()本脚本只能由定时任务运行，不得放进 MR Pipeline：它要写 flags（蓝图 §7.4.1 规定由 CI 写入、人工不得手改），而在 MR 上下文写回 frontmatter 需要向源分支 push，会重新触发同一条 Pipeline 形成回环。
6.3 关键决策点
| # | 决策 | 已确认 | 说明 |
|---|---|---|---|
| R4.1 | 离职检测频率 | 待确认 | 选项：A) 每日 CI 检查；B) 每周定时任务 |
| R4.2 | 无人认领的知识处理 | 待确认 | 选项：A) 标记 owner_missing，等待新 Steward；B) 自动分配给团队新 maintainer |
7. 实施步骤
| 步骤 | 内容 | 产出物 | 前置条件 |
|---|---|---|---|
| S1 | 配置 CODEOWNERS 文件 | CODEOWNERS | 团队结构已确定 |
| S2 | 创建 MR 模板 | GitLab MR 模板（含审核 Checklist） | S1 完成 |
| S3 | 实现 Steward 有效性检查 + owner_group 存在性校验 | CI 脚本（Error 级） | S1 完成 |
| S4 | 实现审核周期监控 | Pipeline Schedule（经 GitLab UI/API 配 cron）+ rules: - if: '$CI_PIPELINE_SOURCE == "schedule"' 触发的 MR 龄期扫描脚本 + 告警通道 | S2、S3.1 完成。GitLab CI 没有 schedule: 关键字（蓝图 §7.4.3 已警示）；扫描 MR 龄期需调 GitLab API，凭据同 02-知识验证 S3.1 |
| S4.1 | 实现 owner_group 存在性校验 | 并入 S3 的 CI 脚本 | S1 完成。§9 风险表把此项列为缓解措施，但 S1–S5 原本无对应条目 |
| S5 | 端到端验证 | 草稿 → 审核 → 转 active 全流程 | S1-S4 完成 |
8. 度量
| 指标 | 计算方式 | 目标 | 性质 |
|---|---|---|---|
| 审核周期 | MR 提交到合并的平均时间 | ≤ 2 个工作日 | 阈值待实测 |
| 一次通过率 | 首次提交即被 Approve 的 MR 比例 | ≥ 70% | 阈值待实测 |
| 驳回原因分布 | 各驳回原因的占比 | 用于改进知识生成质量 | 趋势指标 |
| 知识活跃率 | status: active 的条目数 / 总条目数 | ≥ 80% | 阈值待实测 |
| 新增孤儿知识率 | 本次 MR 引入的 owner_group 无效条目比例 | = 0 | 机制保证（S4.1 的存在性校验为 Error 级合并门禁，无孤儿可入库） |
| 孤儿检出率 | 每日扫描检出的孤儿数 / 实际孤儿数 | 100% | 机制保证（扫描覆盖全部 active 条目，可脚本判定） |
| 存量孤儿收敛速度 | 存量孤儿条目数随时间的变化 | 趋势下降 | 趋势指标。原「孤儿知识率 = 0 / 机制保证」是标注拔高：§6.2 的机制只保证「孤儿会被发现并标记」，消除依赖 R4.2（推荐 A：标记等待新 Steward，仍待确认）与人工认领，不是机制能强制成立的量 |
9. 风险与依赖
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| Reviewer 响应慢 | 知识积压在草稿状态 | 审核周期监控 + 超期自动升级 |
| Steward 离职后知识无人维护 | 知识过期、漂移无法处理 | 离职检测 + owner_missing 标记 |
| 审核标准不一致 | 不同 Reviewer 判定不同 | 审核 Checklist 模板 + 定期校准 |
| CODEOWNERS 配置错误 | 审核请求发给错误的人 | CI 校验 owner_group 在 GitLab 中存在（S3）；CODEOWNERS 路径必须覆盖 _drafts/**（§3.2），否则草稿 MR 无人审核 |
10. 待确认决策汇总
| 编号 | 决策 | 选项 | 推荐 |
|---|---|---|---|
| R1.3 | 最少批准数 | A) 1 人；B) 2 人会签 | A（P0 先降低摩擦）。选 B 需 GitLab Premium+：[Section][N] 的 N>1 强制批准在 Free 层不生效 |
| R1.4 | CODEOWNERS 路径粒度 | A) 按域；B) 按模块 | A（P0 先粗粒度） |
| R2.2 | 审核 Checklist 模板 | A) MR 模板；B) CI 自动生成 | A |
| R3.3 | 审核周期是否强制 | A) 仅建议；B) 超期升级；C) 超期阻断 | B |
| R3.4 | 审核驳回后处理 | A) 作者修改；B) Reviewer 直接改 | A |
| R4.1 | 离职检测频率 | A) 每日；B) 每周 | A |
| R4.2 | 无人认领处理 | A) 标记等待；B) 自动分配 | A |