01 · 知识生成 · 落地方案

对应蓝图 §2。本文解决：知识从哪里来？怎么产生？产生什么格式？

状态：草案（D2.3 / D2.4 / D3.3 / D3.4 / D3.5 / D4.2 / D4.3 / D5.2 / D5.3 待确认，见 §11）
前置依赖：无（生命周期起点）
关联文档：02-知识验证（AI 审核门控）· 04-知识存储（元数据 Schema 与条目模板）· 06-知识维护与治理（漂移判定）

---

1. 定位与边界

本方案采用 Qoder 中心化生成架构——所有知识生成均通过 Qoder 在开发者日常工作流中完成，不依赖独立的生成 Pipeline。Qoder 在三种场景下产生知识：SDD 流程产出设计知识、编码过程中检测知识漂移并更新、权威事实源变更时提醒开发者同步知识。

---

2. 生成架构总览

核心原则：

• 知识生成嵌入开发者已有工作流，不额外派发写作任务
• 所有产出均为 status: draft，须经 §4 知识审核后方可转 active
• 知识条目与代码变更在同一 MR 中提交，保证知识随代码同步演进

---

3. 路径 1：SDD 流程生成

3.1 触发时机

在 SDD 工作流（java-backend-dev-guide §1）的需求分析和概要设计阶段，Qoder 自动识别当前任务是否涉及以下场景：

场景	知识产出	触发条件
新功能设计	架构决策记录（Decision）	涉及 3+ 文件或公共契约变更
接口契约变更	接口知识条目（Contract）	新增/修改 HTTP/RPC 接口
数据模型变更	表结构知识条目（Contract）	新增/修改数据库 Migration
配置项变更	配置知识条目（Procedure）	新增/修改 application.yml（配置中心见 D3.5，P0 不覆盖）
业务规则变更	业务规则知识条目（Policy）	涉及状态机、领域规则调整

3.2 生成流程

1. Qoder 检测到 SDD 场景（匹配 jbdg §6.1 路由表 #1 或 #2）
2. 加载 sdd-guide.md，产出 spec.md / plan.md
3. 识别涉及的知识类型（上表匹配）
4. 在 docs/sdd/{需求ID}--{特性}/ 下产出设计文档
5. 同时生成知识草稿到 _drafts/{module}/{topic}.md
6. 知识草稿遵循蓝图 §5.5.1 模板

3.3 知识草稿存放

草稿统一存放于仓库内 _drafts/ 目录（与代码变更同 MR 提交）：

_drafts/
├── {module}/
│   ├── {topic}.md          # 知识草稿
│   └── ...

草稿 frontmatter 标记 status: draft，CI 校验通过后由 Owner 审核决定是否转 active。

3.4 关键决策点

#	决策	已确认	说明
D1.1	SDD 场景识别方式	✅ 混合识别（D）	同时使用规则匹配（文件路径/注解）和 AI 判断（需求语义）
D1.2	知识条目模板	✅ 复用蓝图 §5.5.1	不另建模板，SDD 产出直接套用
D1.3	草稿存放位置	✅ _drafts/ 目录	与代码变更同 MR，不单独开分支
D1.4	草稿与代码变更的关系	✅ 同一 MR 提交	保证知识随代码同步，不产生滞后

---

4. 路径 2：编码 + 漂移检测生成

4.1 触发时机

在编码阶段，Qoder 检测到以下情况时触发知识更新：

检测信号	知识影响	处理方式
修改了已有 API 签名	对应知识条目可能过期	标记 drift_detected，生成更新草稿
修改了配置项默认值	配置知识可能过期	同上
删除了已有代码符号	引用该符号的知识失效	标记高优先级漂移
新增了公共接口	可能需要新增知识条目	生成候选草稿

4.2 漂移检测机制

采用 source_uri 映射（主）+ 启发式规则（辅） 双层检测。

与蓝图 §7.4 的分工：本节是编码时本地即时提示（在开发者还持有上下文时给出，成本低、可立即修正）；蓝图 §7.4.3 是每日 CI 兜底对账（覆盖本地被绕过、历史条目、跨仓变更）。两者共用同一套 source_uri 映射语义，但只有 CI 侧有权写 flags。

性质：本地/CI 双层分工为工程推导；下方启发式规则为自拟（无外部依据，误报率待实测） | 置信度：中

第一层：source_uri 精确映射

# 伪代码：基于 source_uri 的漂移检测
for entry in knowledge_entries(status == active):
    source_path = resolve(entry.source_uri)  # gitlab:// → 本地路径
    if source_path in changed_files:
        # 源文件发生了变更，需要检查知识是否仍然有效
        if has_semantic_change(source_path, entry.knowledge_type):
            # 本地不写 entry.flags：蓝图 §7.4.1 规定 flags 由 CI 写入、人工不得手改。
            # 本地若写回，编码 MR 就要顺带修改知识条目 frontmatter，
            # 而跨仓写回路径（知识在哪个仓、走哪个 MR、谁审）未定义。
            # 本地只产出提示与更新草稿；flags 落库由蓝图 §7.4.3 每日定时任务承担。
            report_drift(entry, source_path)
            generate_update_draft(entry, source_path)

第二层：启发式规则（回落）

当知识条目缺少 source_uri 或源文件路径无法解析时，使用以下启发式规则：

启发规则	检测方式
模块名匹配	知识标题含模块名，且该模块有代码变更
符号引用匹配	知识正文引用了 ClassName#methodName，且该方法被修改
配置前缀匹配	知识涉及某配置前缀，且该前缀下的值被修改

4.3 关键决策点

#	决策	已确认	说明
D2.1	漂移检测主机制	✅ source_uri 映射	精确匹配，误报率低
D2.2	漂移检测辅机制	✅ 启发式规则	覆盖 source_uri 缺失的历史条目
D2.3	检测到漂移后的行为	待确认	选项：A) 自动标记 + 生成草稿；B) 仅标记，由开发者决定是否更新
D2.4	启发式规则的误报处理	待确认	选项：A) 误报也标记，Owner 审核时排除；B) 设置信度阈值，低置信度不标记

---

5. 路径 3：权威源变更生成

5.1 设计约束

团队使用 Qoder 企业版本地安装，GitLab Webhook 无法直接触达开发者本地机器（NAT 穿透问题）。因此 不采用 Webhook 被动触发，改为 pre-commit hook 主动检测。

5.2 触发机制：pre-commit hook

5.3 检测范围

权威源类型	检测路径模式	对应知识类型
Swagger/OpenAPI	**/openapi.yaml、**/swagger.yaml、**/api-docs/**	Contract（HTTP 接口）
Flyway Migration	**/db/migration/**/*.sql	Contract（表结构）
SpringBoot 配置	**/application*.yml、**/application*.properties	Procedure（配置项）
配置中心声明	**/bootstrap*.yml 中的配置中心引用	Procedure（配置项）

5.4 hook 脚本实现

#!/usr/bin/env python3
"""pre-commit hook：检测权威源文件变更，提醒开发者更新知识"""

import subprocess
import sys
import re

# 权威源路径模式
# git diff --name-only 输出的是仓库相对路径，根目录文件无前导斜杠，
# 因此每个模式都要允许「根目录」与「子目录」两种形态
AUTHORITATIVE_PATTERNS = [
    re.compile(r'(^|.*/)openapi\.ya?ml$'),
    re.compile(r'(^|.*/)swagger\.ya?ml$'),
    re.compile(r'(^|.*/)api-docs/.*'),
    re.compile(r'(^|.*/)db/migration/.*\.sql$'),
    re.compile(r'(^|.*/)application.*\.yml$'),
    re.compile(r'(^|.*/)application.*\.properties$'),
    # bootstrap*.yml（配置中心引用）：D3.5 推荐 C（P0 不覆盖配置中心）确认后应移除此行，
    # 否则 hook 会对无法闭环的变更发出提醒
    re.compile(r'(^|.*/)bootstrap.*\.yml$'),
]

def get_staged_files():
    result = subprocess.run(
        ['git', 'diff', '--cached', '--name-only'],
        capture_output=True, text=True
    )
    out = result.stdout.strip()
    return out.split('\n') if out else []

def check_authoritative_changes():
    staged = get_staged_files()
    changed = []
    for f in staged:
        for pattern in AUTHORITATIVE_PATTERNS:
            if pattern.match(f):
                changed.append(f)
                break
    return changed

def has_knowledge_update():
    """暂存区是否已包含配套的知识变更。有则放行——否则开发者
    补完草稿再提交时，权威源文件仍在暂存区，hook 会二次阻断，
    唯一逃逸方式是 --no-verify，闭环在工程上走不通。"""
    staged = get_staged_files()
    return any(f.startswith('_drafts/') or f.startswith('docs/knowledge/')
               for f in staged)

def main():
    changed = check_authoritative_changes()
    if not changed or has_knowledge_update():
        return 0

    print("\n" + "=" * 60)
    print("[知识库提醒] 检测到权威源文件变更：")
    for f in changed:
        print(f"  - {f}")
    print()
    print("请在提交前使用 Qoder 执行知识更新：")
    print("  /update-knowledge")
    print()
    print("或跳过此检查：")
    print("  git commit --no-verify")
    print("=" * 60 + "\n")

    # D3.3 推荐 B（仅提醒）：return 0；若确认 A（阻断）改为 return 1。
    # 注意：无论选哪个，--no-verify 都能无条件绕过 pre-commit hook，
    # 阻断模式只提高摩擦，不构成强制力。真正的兜底在 CI 侧（蓝图 §7.3）。
    return 0

if __name__ == '__main__':
    sys.exit(main())

5.5 Qoder Skill：/update-knowledge

开发者收到 hook 提醒后，在 Qoder 中执行 /update-knowledge，Skill 负责：

1. 读取 git diff --cached 获取权威源变更内容
2. 按源类型分发解析：
   • OpenAPI 变更 → 解析接口签名差异，更新对应 Contract 知识
   • Flyway SQL 变更 → 解析 DDL 差异，更新表结构知识
   • application.yml 变更 → 解析配置项差异，更新配置知识
3. 生成或更新 _drafts/{module}/{topic}.md
4. 将草稿 git add 到暂存区，允许开发者一次提交

5.6 关键决策点

#	决策	已确认	说明
D3.1	触发机制	✅ pre-commit hook	解决本地 Qoder 无法被 Webhook 触达的问题
D3.2	权威源检测范围	✅ openapi + flyway + application.yml	覆盖 API/数据库/配置三类核心权威源
D3.3	hook 行为	待确认	选项：A) 阻断提交；B) 仅提醒。当前脚本按 B 实现（return 0），确认 A 只需改最后一行返回值。注意两种模式都可被 --no-verify 绕过
D3.4	知识更新时机	待确认	选项：A) 必须同一次提交包含知识更新；B) 允许后续单独提交知识更新
D3.5	配置中心知识	待确认	配置中心的配置项如何同步到知识库？选项：A) 导出为 application.yml 格式统一管理；B) 单独维护配置中心知识条目；C) P0 不覆盖配置中心，仅覆盖本地配置文件

---

6. 知识条目标准

6.1 条目结构

每条知识必须包含以下要素（对应蓝图 §2.4）：

要素	要求	说明
背景	必须	为什么需要这条知识？不写会出什么问题？
方案	必须	技术方案的准确陈述，引用具体代码位置
正反例	必须	正确做法 + 错误做法 + 解释为什么
权威源绑定	必须	source_uri + source_revision（frontmatter）
Owner	必须	owner_group（frontmatter）
适用范围	建议	涉及哪些模块、服务、API
知识类型	必须	frontmatter knowledge_type（蓝图 §5.2 的 7 字段之一），枚举即 §6.2 的七类。必须是写入时采集的必填字段而非派生字段：分级复核周期、漂移语义过滤、主张抽取范围都以它为输入

6.2 知识类型分类

类型	说明	典型来源
Concept	设计背景、架构理念	SDD 流程的 spec.md
Decision	架构决策记录（ADR）	SDD 流程的 plan.md
Contract	接口契约、表结构、配置 Schema	OpenAPI、Flyway、application.yml
Procedure	操作步骤、部署指南	编码过程中的实践提炼
Policy	业务规则、架构约束	规范/制度文档
FAQ	常见问题解答	反馈闭环中的高频问题
IncidentLesson	事故复盘教训	事故/值班记录

6.3 关键决策点

#	决策	已确认	说明
D4.1	知识条目格式	✅ Markdown + YAML frontmatter	与蓝图 §5.5.1 模板一致
D4.2	知识类型枚举	待确认	蓝图 §2.3 列出 7 种类型，是否需要按 OCP 项目实际裁剪？
D4.3	正反例的代码语言	待确认	是否统一使用 Java？前端知识是否用 TypeScript？

---

7. 多源解析与预处理

7.1 P0 范围：仅 Git 仓库 Markdown

P0 阶段只处理已经在仓库中以 Markdown 形式存在的知识，以及通过权威源自动解析生成的结构化知识。

7.2 P1 范围：外部来源接入

来源	解析方式	产物	失真风险
Confluence / Wiki	REST API 导出 XHTML → 转 Markdown	Markdown + 页面版本号	宏、附件、页面树层级丢失
PDF	版面解析（保留标题层级）	Markdown + 页码锚点	表格与多栏版面极易错序
Office	转 Markdown	Markdown	公式、图表、批注丢失
IM / 会议记录	AI 提取候选事实	草稿（status: draft）	断章取义、上下文缺失

7.3 解析失败处置（Fail-Closed）

失败类型	处置	是否入库
解析器抛异常 / 超时	记录 parse_failed，告警 Owner	否
解析成功但标题层级为 0	标记 structure_degraded，进入人工确认队列	否，待人工
表格转换后单元格丢失率超阈值	标记 table_degraded，附原文件链接	是，但附带失真提示

7.4 关键决策点

#	决策	已确认	说明
D5.1	P0 是否接入外部来源	✅ 不接入	P0 只处理仓库内 Markdown 和权威源自动解析
D5.2	P1 外部来源优先级	待确认	选项：A) Confluence 优先；B) PDF 优先；C) 按团队实际使用频率排序
D5.3	解析失败阈值	待确认	表格单元格丢失率阈值、OCR 置信度阈值具体取值

---

8. 实施步骤

步骤	内容	产出物	前置条件
S1	实现 /update-knowledge Skill	Skill 定义 + 解析脚本	无
S2	实现 pre-commit hook 脚本并入库	scripts/hooks/pre-commit（入库，不直接放 .git/hooks/）	S1 完成
S2.1	配置 hook 分发	git config core.hooksPath scripts/hooks，写入新人上手脚本	S2 完成
S3	在 SDD Skill 中集成知识生成路由	更新 sdd-guide.md	无
S4	实现漂移检测 Skill	漂移检测脚本 + Skill 定义	source_uri 映射机制就绪
S5	端到端验证	三条路径均可产出草稿	S1-S4 完成

---

9. 度量

指标	计算方式	目标	性质
知识识别覆盖率	已有知识条目覆盖的模块数 / 总活跃模块数	≥ 80%	阈值待实测
种子知识完成率	核心模块种子知识条数 / 计划条数	100%	机制保证（计划条数由本团队定义，完成与否可直接判定；属冷启动里程碑判定项，机制位于蓝图 §10.1.2 的 C1/C2 阶段，不进 CI 硬门禁）
草稿转化率	从草稿到 active 的条目数 / 生成草稿总数	≥ 40%	阈值待实测（P1 起生效：蓝图 §2.3 定义的隐性知识来源为 IM/会议/事故/MR 讨论，本文三条路径均不产生此类草稿，P0 阶段分子分母都无从产生）
权威源变更响应率	含权威源变更的 MR 中，同时包含知识条目变更的比例（由 GitLab API 统计 MR 的 changes 列表得出）	≥ 90%	阈值待实测。原口径「hook 触发后执行更新的比例」不可测——hook 在开发者本地运行，无遥测采集通道；改为 CI 侧可直接观测的等价口径
漂移检测准确率	正确标记漂移的条目 / 全部标记条目	≥ 85%	阈值待实测

---

10. 风险与依赖

风险	影响	缓解措施
开发者跳过 hook 提醒（--no-verify）	知识更新滞后	pre-commit hook 无论提醒还是阻断模式，都能被 --no-verify 无条件绕过，阻断只提高摩擦。真正的兜底是 CI 侧契约变更检查（蓝图 §7.3），须在 P1 前落地
漂移检测误报过多	开发者忽略告警	启发式规则设置信度阈值，仅高置信度标记
SDD 流程中知识生成增加额外负担	开发者抵触	知识草稿自动生成，开发者只需确认和补充
权威源路径模式不完整	部分变更未被检测	定期审计 hook 检测规则，按实际项目结构调整
hook 未安装（.git/hooks/ 不受版本控制，clone 不带）	本地检测整体失效	core.hooksPath 指向入库目录 + 上手脚本自动配置；CI 侧蓝图 §7.3 契约变更检查作为兜底

---

11. 待确认决策汇总

编号	决策	选项	推荐
D2.3	检测到漂移后的行为	A) 自动标记+生成草稿；B) 仅标记	A
D2.4	启发式规则误报处理	A) 也标记，Owner 排除；B) 设阈值	B
D3.3	hook 行为	A) 阻断提交；B) 仅提醒	B（P0 阶段先提醒，成熟后升级阻断）
D3.4	知识更新时机	A) 必须同次提交；B) 允许后续提交	B（降低开发者摩擦）
D3.5	配置中心知识	A) 导出统一管理；B) 单独维护；C) P0 不覆盖	C
D4.2	知识类型裁剪	7 种全保留 or 按 OCP 实际裁剪	全保留
D4.3	正反例代码语言	统一 Java or 按知识类型选择	按知识类型选择
D5.2	P1 外部来源优先级	A) Confluence；B) PDF；C) 按使用频率	C
D5.3	解析失败阈值	具体数值待实测	—