f2s-kb-distill

name	f2s-kb-distill
description	从问答过程中提取可复用知识事实并自动入库；根据下钻深度与命中主题判断新增主题或补充既有主题；触发：f2s-kb-distill、问答知识提取、从对话中提取知识

执行口径：本技能只维护 .Knowledge，默认不改配置根 rules/skills。

编排（主 / 子 agent）

• subAgent / switchAgentVerification 两字段语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md（与上同源，flow2spec init 镜像）。
• 本技能默认不拆子：问答知识提取是单轮聚焦任务，由主 agent 全流程完成效率更高。
• 写权硬约束：manifest-routing.json 与 .Knowledge/index.md 恒由主 agent 单点落盘。
• 校验：落盘侧自验。

f2s-kb-distill：问答驱动的知识提取与入库

使用时机

• 用户提问 → agent 下钻源码回答 → 需要将发现的知识沉淀到 KB
• 通常由 f2s-kb-feedback-closing 规则自动建议，也可用户主动调用
• 与 f2s-kb-sync 区分：sync 适合批量同步多个能力；distill 专注单次问答的知识提取

输入

参数	必填	说明
用户问题	自动获取	上一轮用户的提问（自动从对话历史提取）
agent 回答	自动获取	上一轮 agent 的回答内容（自动从对话历史提取）
命中主题	可选	如由 f2s-kb-feedback-closing 触发，会携带命中的 topicId
下钻文件	自动分析	从回答中提取引用的文件/函数（自动分析）

无有效问答上下文时中止并提示用户。

执行挡位（轻量 / 严格，agent 自动判）

f2s-kb-distill 只有一个入口（无 --fast 参数），进入流程第一件事是判挡：

判挡依据（4 个维度，全满足才走轻量挡）

维度	取值方式	走「轻量挡」的条件
上游 f2s-kb-feedback-closing case	看本轮 / 上一轮 agent 回答末尾的收口块	case 2 或 case 3（case 1 / 无收口 → 严格挡）
本轮 Read 业务源码文件数	agent 回顾本轮自己的工具调用	≤ 3 个
本轮回答引用的函数 / 类名数	数回答里反引号包裹的 xxx() / 类名	≤ 5 个
用户追问是否否定上游结论	看用户最新输入是否含"不对 / 重新分析 / 那条不准"等	否

4 项全满足 → 轻量挡：跳过步骤 2.1（量化打分）/ 2.4（既有 topic 描述程度评估）/ 步骤 3（决策矩阵）/ 步骤 4.1 的「读近邻 topic 风格对齐」；直接采上游「本轮将入库：<概要>」做策略与目标 topicId 判定，进入步骤 4 生成内容。

任一不满足 → 严格挡：跑完整 6 步。

业务源码定义：路径不在 .claude/ / .cursor/ / .codex/ / .Knowledge/ / .task/ 这 5 个目录下的 Read 才计数；规则文件 / topic / config / 任务清单都不算。

为什么这几个维度够（设计意图）

• case 类型挡掉「新增 topic」场景：新建必须读近邻 topic 学风格、必须配 matcher includeAny、必须更新 taskToTopicRules，跳不得；
• Read 文件数 + 函数引用数反映本轮知识够不够"轻"：轻量补充才能跳决策，深度入库（多文件 + 多函数）跳了会撞「描述程度差 ≥ 2 级」事故；
• 用户否定信号兜底"上游 case 判错了"的边界。

步骤 5 / 6 永不省

无论哪一挡，步骤 5 路由 / matcher / index 同步与步骤 6 落盘 + 自检都跑完整版——这是入库正确性的硬约束。

强制流程（不可颠倒）

步骤 0：读取配置与规则

1. 读取 flow2spec.config.json（获取 subAgent / switchAgentVerification）
2. 读取 .codex/topics/f2s-kb-feedback-closing.md（获取"可复用知识事实"定义）
3. 读取 .codex/topics/f2s-topic-authoring.md（获取 topic 创作准则）

步骤 1：提取问答上下文

从上一轮对话中提取：

1. 用户问题：原始问题文本
2. agent 回答：完整回答内容
3. 命中主题：如果 f2s-kb-feedback-closing 已分析，提取命中的 topicId；否则根据问题重新路由
4. 下钻文件：从回答中提取所有引用的文件路径、函数名、行号
5. 引用源码：提取回答中引用的代码片段

步骤 2：分析下钻深度与知识性质

****轻量挡跳过：本步骤的 2.1 / 2.4 整段跳过；2.2（提取知识事实）必须执行；2.3（本次知识描述深度）改为简短标注（一行写"摘要级 / 详细级 / 实现级"即可，不再多维评估）。

2.1 计算下钻深度得分

累加以下指标（每项 0-10 分，总分 0-50）：

• 读取文件数：

  • 0 个文件：0 分
  • 1-2 个文件：3 分
  • 3-5 个文件：7 分
  • 6+ 个文件：10 分

• 分段读取次数（同一文件多次读取不同行范围）：

  • 0-1 次：0 分
  • 2-4 次：3 分
  • 5-8 次：7 分
  • 9+ 次：10 分

• 函数/类引用数：

  • 0-2 个：0 分
  • 3-5 个：3 分
  • 6-10 个：7 分
  • 11+ 个：10 分

• 代码片段长度：

  • 0-50 行：0 分
  • 51-150 行：3 分
  • 151-300 行：7 分
  • 301+ 行：10 分

• 回答篇幅：

  • 0-200 字：0 分
  • 201-500 字：3 分
  • 501-1000 字：7 分
  • 1001+ 字：10 分

下钻深度分级：

• 浅（0-15 分）：简单问答，少量源码引用
• 中（16-30 分）：中等复杂度，多文件查阅
• 深（31-50 分）：深度探索，大量源码分析

2.2 提取可复用知识事实

从回答中提取以下类型的知识（参考 f2s-kb-feedback-closing）：

• 核心机制（缓存语义、重试策略、降级逻辑）
• 状态流转（状态机、生命周期）
• 返回值/错误码契约
• 配置开关影响
• 失败回退策略
• 模块边界或调用约定
• 数据模型与字段语义

提取结果：

• 每条知识事实包含：类型、描述、来源（文件:行号）
• 按重要性排序

2.3 判断本次提取知识的描述深度

评估提取出的知识事实的详细程度（与长度无关，看内容特征）：

• 摘要级：只有结论性描述（"是什么"、"做什么"），无条件、流程、函数细节
  • 示例：缓存优先、失败回退 OCR
• 详细级：包含机制说明、流程步骤、关键判断条件（"当X时"、"如果Y则"、"先...再..."）
  • 示例：缓存优先：坐标缓存命中时直接使用；失败回退条件：弹窗未消失、坐标超出边界
• 实现级：包含函数调用关系、状态转换细节、边界条件处理、代码示例
  • 示例：缓存读取：调用 _get_cached_point_in_bounds("chat.input")，返回 None 时回退；失败判定：VisualSearchPopup.find(timeout=0.08) is None

2.4 评估既有 topic 的描述程度（仅当"有命中"时）

如果命中了既有 topic，需要评估它的描述程度（与长度无关）：

1. 读取目标 topic 内容
2. 随机抽取 3-5 条内容（不同段落）
3. 判断每条的描述程度：
   • 摘要级特征：只说"是什么"、"做什么"，列举式，无条件/流程/函数细节
   • 详细级特征：包含"当X时"、"如果Y则"、"先...再..."、判断条件、机制说明
   • 实现级特征：包含函数名 xxx()、类名、文件路径、参数、代码示例、状态转换逻辑
4. 大部分条目的级别 = topic 的整体描述程度

判断示例：

Topic 内容	判定	原因
- 缓存优先、失败回退 OCR - 发送消息动作链判定	摘要级	只说"做什么"，无细节
- 缓存优先：坐标缓存命中时直接使用 - 失败回退：弹窗未消失时清除缓存并重新 OCR	详细级	有条件说明（"当...时"）
- 缓存读取：_get_cached_point_in_bounds("chat.input") - 失败判定：VisualSearchPopup.find(timeout=0.08) is None	实现级	有函数名、参数

重要：一个 300+ 行的 topic，如果每条都是"模块 X：负责 YYY"，仍然是摘要级；一个 50 行的 topic，如果每条都有"条件判断 + 函数调用"，就是实现级。

步骤 3：决策入库策略

****轻量挡跳过整段决策矩阵：直接采用上游 f2s-kb-feedback-closing「本轮将入库：<概要>」给出的结论：

• 概要含「补充 / 补到 / 补齐 <topicId> 的某段」→ 策略 = 补充既有 topic，目标 topicId = 概要点名的 topic；
• 概要含「首次入库」「新增 <能力>」「新增 <模块>」→ 策略 = 新增 topic（默认小型 topic；下钻深 + 模块独立时升级为「新增独立模块 topic」由步骤 4.3 内部判断）；
• 概要含「修正 <topicId> 的某条」→ 策略 = 补充既有 topic（覆盖式追加，原表述在生成内容时改写）。

根据以下决策矩阵判断：

下钻深度	命中主题情况	既有 topic 描述程度	本次知识描述深度	策略
浅	有命中	摘要级	摘要级	补充既有 topic（追加简短说明）
浅	有命中	摘要级/详细级	详细级	补充既有 topic（追加详细段落）
浅	有命中	摘要级	实现级	新增子主题（既有太简短，本次太详细）
浅	无命中	-	任意	新增 topic（小型 topic）
中	有命中	摘要级	摘要级/详细级	补充既有 topic（追加详细段落）
中	有命中	摘要级	实现级	新增子主题（差距 ≥ 2 级）
中	有命中	详细级/实现级	详细级/实现级	补充既有 topic（级别匹配）
中	无命中	-	任意	新增 topic（中型 topic）
深	有命中	摘要级	任意	新增子主题（独立 topic + stock-doc）
深	有命中	详细级/实现级	详细级/实现级	补充既有 topic 或 新增子主题（根据语义聚焦度判断）
深	无命中	-	任意	新增独立模块 topic（完整 topic + stock-doc）

决策关键：

• 描述程度差距 ≥ 2 级（摘要 vs 实现）→ 强制新增子主题，避免风格不协调
• 描述程度差距 = 1 级（摘要 vs 详细，或详细 vs 实现）→ 可以追加，但要写详细段落
• 描述程度匹配（同级）→ 正常追加
• 下钻深度 ≥ 深 → 倾向新增子主题，除非既有 topic 已经很详细且语义完全重合

决策输出：

• 策略类型：补充既有 topic / 新增子主题 / 新增独立模块 topic
• 目标 topicId：既有 topic 的 id 或新 topic 的建议 id
• 更新内容：要追加的内容或新 topic 的结构
• 描述程度匹配度：同级 / 差 1 级 / 差 ≥ 2 级

步骤 4：生成知识内容

创作侧准则：本步骤会触发新增 / 修改 topic 与可能的 topicDependencies，须遵循已读取的 f2s-topic-authoring 准则。

4.1 补充既有 topic

如果策略是"补充既有 topic"：

1. 读取目标 topic 当前内容
2. 读取近邻 2-3 个 topic 的风格样例（用于风格对齐）
   ****轻量挡跳过：不读近邻 topic，仅参考目标 topic 自身的列表 / 段落形态保持一致即可。
3. 生成要追加的内容：
   • 位置：找到最相关的段落，在其后追加
   • 格式：保持与既有 topic 一致的列表/段落风格
   • 长度：根据知识描述深度决定：
     • 摘要级：1-3 行
     • 详细级：5-10 行，包含机制说明
     • 实现级：10-20 行，包含流程步骤与关键函数
4. 追加内容示例：

   - 【机制】缓存只用于坐标定位与快速路径；缓存命中不等同于步骤完成
   - 【判定】添加好友在缓存点击后仍通过窗口出现、资料页状态、提交后状态分类判断进度
   - 【边界】发送消息在按 Enter 后返回成功，当前无 OCR 校验消息气泡或发送状态
   

4.2 新增子主题

如果策略是"新增子主题"：

1. 生成新 topicId（基于父 topic + 聚焦点）：
   • 例如：wxautocontrol-architecture → wxautocontrol-completion-detection
2. 创建新 topic 内容：
   • 标题与一句话意图
   • 适用场景/触发词
   • 核心机制详述（从提取的知识事实生成）
   • 依赖声明（依赖父 topic）
   • 边界与禁止项
3. 同步更新父 topic：
   • 在相关段落追加指向子 topic 的链接
   • 说明子 topic 的聚焦点
4. 更新 topicDependencies：
   • 添加 子 topic → 父 topic 的依赖边

4.3 新增独立模块 topic

如果策略是"新增独立模块 topic"：

1. 生成新 topicId（基于模块名或问题域）
2. 判断是否需要创建 stock-doc：
   • 下钻深度 ≥ 深：创建 stock-doc（<topicId>_终稿.md）
   • 下钻深度 < 深：仅创建 topic，不创建 stock-doc
3. 如果创建 stock-doc：
   • 结构：概述、核心机制、来源文件、关键函数与流程
   • 内容：基于提取的知识事实与引用的代码片段生成
   • 长度：根据下钻深度，100-500 行
4. 创建 topic：
   • 如有 stock-doc，topic 作为摘要 + 指针
   • 如无 stock-doc，topic 包含完整的机制说明

步骤 5：同步路由与索引

5.1 更新 manifest 与 matcher

• 如果新增 topic：

  • 在 manifest-routing.json.topicPaths 中添加条目
  • 创建对应的 matchers/<id>.json，包含：
    • 从用户问题中提取的关键词
    • 从回答中提取的术语
    • 建议 includeAny：5-10 个触发词
  • 在 taskToTopicRules 中添加路由规则

• 如果更新既有 topic：

  • 检查 matcher 是否需要补充新的触发词
  • 从用户问题中提取未覆盖的关键词，追加到 includeAny

5.2 更新 index.md

• 如果新增 topic：
  • 在 .Knowledge/index.md 中添加新条目
  • 格式：- **[topic 标题](topics/<topicId>.md)** - 一句话说明 | 关联文档：[终稿](stock-docs/<doc>.md)（如有）
• 如果更新既有 topic：
  • 检查 index 中的描述是否需要更新
  • 如果新增了 stock-doc，更新"关联文档"列

5.3 处理 topicMetadata（可选）

如果有明确证据，写入 topicMetadata：

• 从提取的知识事实判断 primary 类型：
  • 核心机制/状态流转/失败回退 → policy
  • 配置开关影响 → config
  • 模块边界/调用约定 → module
  • 已落地能力/业务逻辑 → feature
• confidence 设为 inferred
• 无明确证据时不写，在输出摘要中列为"未分类"

步骤 6：落盘与自检

按以下顺序落盘：

1. 如果有 stock-doc：写入 .Knowledge/stock-docs/<doc>.md
2. 写入或更新 .Knowledge/topics/<topicId>.md
3. 更新 .Knowledge/manifest-routing.json
4. 更新 .Knowledge/matchers/<id>.json
5. 更新 .Knowledge/index.md

自检清单：

1. topic 内容是否包含了提取的核心知识事实
2. 新增 topic 是否在 index.md 中有对应条目
3. manifest 中的 topicPaths / taskToTopicRules 是否引用有效路径
4. matcher 的 includeAny 是否覆盖用户问题的关键词
5. 如果新增子主题，topicDependencies 是否正确设置
6. 追加内容是否保持了既有 topic 的风格（如已读近邻 topic）

输出摘要格式

## 知识提取与入库结果

- 执行挡位：`严格挡（完整流程）` / `轻量挡（已跳过 2.1 / 2.4 / 3 / 4.1）` / `轻量挡 → 严格挡（降级原因：<原因>）`

### 问答分析
- 用户问题：<问题摘要>
- 命中主题：<topicId 或"无">
- 下钻深度：<浅/中/深> (<得分>)  ← **轻量挡**：`未评估`
- 知识描述深度：<摘要级/详细级/实现级>

### 提取的知识事实
- 【核心机制】<描述> (来源：<文件:行号>)
- 【状态流转】<描述> (来源：<文件:行号>)
- ...

### 入库策略
- 策略：<补充既有 topic / 新增子主题 / 新增独立模块 topic>
- 目标 topic：<topicId>
- 操作说明：<追加内容 / 新建 topic + stock-doc>

### 已修改文件
- .Knowledge/topics/<topicId>.md：<修改说明>
- .Knowledge/index.md：<修改说明或"未改动">
- .Knowledge/manifest-routing.json：<修改说明或"未改动">
- .Knowledge/matchers/<id>.json：<修改说明或"未改动">
- .Knowledge/stock-docs/<doc>.md：<修改说明或"未改动">

### 验证建议
- 下次遇到类似问题"<问题>"时，应命中 topic：<topicId>
- 建议验证触发词：<关键词列表>

约束

• 只维护 .Knowledge，不改配置根 rules/skills
• 不需要用户确认（问答已验证知识的正确性）
• 保持轻量，单次问答的知识提取在 30 秒内完成
• 避免过度拆分：除非下钻深度 ≥ 深且知识描述深度 ≥ 详细级，否则优先补充既有 topic
• 生成的 matcher includeAny 应覆盖用户实际会用的表述，不只是技术术语

完成后自检

1. 是否正确分析了下钻深度与知识描述深度（轻量挡：是否正确从上游概要解析出策略与目标 topicId）
2. 是否提取了所有"可复用知识事实"（参考 f2s-kb-feedback-closing 定义）
3. 入库策略是否符合决策矩阵（轻量挡：是否与上游概要点名的 case 一致）
4. 新增或更新的 topic 是否在 index.md 中有条目
5. manifest / matcher 是否正确配置路由规则
6. 生成内容是否保持了既有 topic 的风格（轻量挡：是否至少与目标 topic 自身列表/段落形态对齐）
7. 轻量挡专项：摘要顶部是否写明「调用模式」；若中途降级，是否注明降级原因
8. 本次回复末尾没有追加 f2s-kb-feedback-closing 的 case 1～4 任何一种收口块（必须为是；本技能就是 distill 入库本身，自指地再贴一遍提示既冗余又会让用户误以为没入库——f2s-kb-feedback-closing「适用范围」对此有专项禁令）