AI 教学资料搜索 Skill（teaching-material-search）

核心定位（不可违背）

1. 不堆链接、只给成品可用教学资料——直接输出结构化成品内容，可直接用于备课/上课/出题/复习；来源仅在文末统一标注。
2. 固定检索偏好、消除随机误差——所有检索、筛选、输出、纠错逻辑均为固定规则，每次执行严格统一。
3. 校验内容真伪、处理信息冲突——知识点必校验、版本必校验、学段必校验、冲突必处理。
4. 一切输出以「教师直接可用」为第一标准。
5. 防卡顿优先——多智能体并行检索 + 通道熔断降级，单一信源/通道故障绝不阻塞整体产出。

固定规则文件（按需加载，勿全量读入）

记忆机制（多层，跨会话生效，每次必用）

偏好应用规则：偏好记忆的优先级高于默认规则、低于用户本次明示要求（本次说了算 > 记忆偏好 > 默认规则）。信源类自定义约束（如「只用广东省教育厅推荐资源」）除 set default_region 外，同步追加到 references/sources.md 的「用户自定义规则」小节。标准偏好键清单见 scripts/prefs.py 文件头注释。

说明：内容记忆由两层承载——rag_kb.py 是 BM25 知识库（可跨会话复用）、index.py 是 SQLite FTS5 数据库式倒排索引（检索更快、支持布尔/字段过滤）。二者数据互通（index.py rebuild --from-kb / export）。

执行总流程（主 Agent 编排）

> 约定工作区变量（可在会话内固定，跨会话复用）：
> bash > # 库文件真实默认位置说明（重要，已与代码默认值对齐）： > # - rag_kb.py 的 --db 为必填参数，运行时应显式传入； > # - index.py 默认落到当前目录的 .teaching_idx.db； > # - collect.py / prefs.py / learn.py 默认落到 ~/.workbuddy/teaching-*.json。 > # 为避免「换目录/换会话找不到刚才入库的资料」，统一显式指定 --db 到固定位置（推荐 ~/.workbuddy/）： > KB=~/.workbuddy/teaching-kb.json # RAG 知识库（JSON，rag_kb.py 用 --db 显式传入） > IDX=~/.workbuddy/.teaching_idx.db # 数据库式索引（SQLite，index.py 用 --db 显式传入） >

阶段 0：需求解析 + 记忆读取（主 Agent 自己做，不派发）

先读记忆（真实命令）：

python scripts/prefs.py list                              # 读全部长期偏好
python scripts/prefs.py get --key default_version          # 取默认教材版本
python scripts/prefs.py context-get                       # 读跨轮次工作集（上次主题/已检索doc/笔记）
python scripts/prefs.py history-list --match "分数乘法"     # 同主题近期是否检索过（命中→优先复用库与历史产出）
python scripts/learn.py rules --format text                # 导出自学习规则：PREFER_SOURCE / AVOID_SOURCE / PREFER_KW

再从用户请求中提取：学科、学段/年级、教材版本、知识点/章节、资料类型、教学场景。
- 教材版本未指定 → 先用偏好记忆 default_version；无记忆再默认该学科该学段最主流通用版本（报告中注明依据）。
- 场景判断：备课（默认全量）/ 授课（精简）/ 出题（专项）/ 复习（应试）/ 教研比赛（高阶），对照 references/scenarios.md 确定标配输出内容。
- 应用自学习规则调整检索策略：
- PREFER_SOURCE: 国家智慧教育平台 → 该信源优先级上调，分配更多子 Agent 配额；
- AVOID_SOURCE: 某失效镜像站 → 临时并入黑名单，本批跳过；
- PREFER_KW: 分数乘法 教学设计 → 检索关键词组合直接复用，提升命中率。
- 非英语学科默认不检索英文资料。

阶段 1：多智能体并行采集（看板 + 看门狗 + 通道熔断）

1.1 建任务看板（看板核心）

用 TaskCreate 把本次检索拆解为独立子任务并建立依赖关系，例如：

#1 检索官方权威源（一级信源）        [无依赖]
#2 检索教研平台/学术源（二级信源）    [无依赖]
#3 检索多媒体/补充源（三级信源）      [无依赖]
#4 入库沉淀与去重整合               [依赖 #1 #2 #3]
#5 冲突判定与内容校验               [依赖 #4]
#6 生成标准化报告                  [依赖 #5]
#7 记忆更新（历史+偏好+上下文）      [依赖 #6]

1.2 生成采集任务 + 通道体检

用 collect.py plan 按信源层级生成「方法组合 + 降级链」的采集任务，已自动跳过熔断通道（拒绝堵塞）：

python scripts/collect.py plan --topic "分数乘法" --tier 1 --scenario 备课 --allowed "basic.smartedu.cn,pep.com.cn"
python scripts/collect.py channel-status      # 看一眼当前各通道健康度

plan 输出含每个通道的 method（websearch/webfetch/column/rss/api）、domains、fallback_methods；skipped_tripped 列出被熔断跳过的通道。

1.3 并行派发子 Agent（同一条消息一次发多个）

每个子 Agent 的 prompt 必须自包含（子 Agent 看不到本会话），必须包含：
1. 检索目标（学科/年级/版本/知识点/资料类型）；
2. 分配的通道与采集方法（从 plan 结果摘取对应片段，含 fallback_methods 降级链）；
3. 黑名单信源一律不采集（references/sources.md）；
4. 压缩回传要求（省 token 核心）：子 Agent 严禁回传网页原文/HTML，采集到原文后用 compress.py handoff 压成紧凑块再回传：

# 子 Agent 抓取/读取到的原始页 → 先压缩再回传
python scripts/compress.py --file raw_page.html --mode handoff --topic "分数乘法" --source https://basic.smartedu.cn/xxx --max-chars 800

回传紧凑格式示例：

【资料N】名称|来源URL|信源层级(一级/二级/三级)|资源类型|适用年级版本|发布时间
要点: ≤200字核心内容摘要（教学目标/重难点/题目考点等干货）
正文精华: 仅保留可直接复用的成品片段（教案环节/题目原文/答案），去导航去广告去重复

回传总量限制：单个子 Agent 报告 ≤2000 字；黑名单信源内容一律不采集。

1.4 看门狗与通道健康维护（防卡顿核心）

看门狗规则（必须遵守）：
- 子任务 #1~#3 相互独立，必须在同一条消息中并行启动多个子 Agent（一次发多个 Agent 调用）。
- 每个子 Agent 领任务时先 TaskUpdate 标记 in_progress，完成即标 completed——所有 Agent 通过共享任务看板互相看到彼此进度，不互相等待。
- 主 Agent 对每个子 Agent 设超时看门狗；任一子 Agent 失败/超时 → 主 Agent 不阻塞，调用 channel-fail 记一次故障并标注该信源缺失，用其余结果继续推进，并在报告【补充建议】说明。
- 主 Agent 在等待期间不轮询、不空转；收到完成通知后再汇总。

通道健康维护（调用真实命令）：

# 子 Agent 在某通道采集失败/超时 → 记一次故障；连续 3 次 → 自动熔断(30分钟冷却)，期间被 plan/pick 跳过
python scripts/collect.py channel-fail --name "国家智慧教育平台"
# 子 Agent 在某通道采集成功 → 清零故障计数，恢复健康
python scripts/collect.py channel-ok --name "国家智慧教育平台"
# 通道熔断时降级选路：返回当前健康通道，熔断通道绝不返回（拒绝堵塞，不阻塞整体）
python scripts/collect.py channel-pick --tier 1
# 若某 tier 无健康通道 → 放宽到其他 tier 重试（plan 内部已自动放宽，此处用于主 Agent 兜底判断）

降级原则（拒绝堵塞）：熔断通道只被「跳过」或「降级到其他健康通道」，绝不拖住整体流水线——即使全部一级信源熔断，也降级到二级/三级继续产出，并在报告注明缺失。

阶段 2：检索优先级裁决（先库后网，省 token）

在派发大规模联网采集之前，先用已有索引/知识库快查；命中足够则跳过对应主题的联网采集，直接省掉整轮 token：

# 1) 数据库式索引（FTS5，快，支持布尔/字段过滤）
python scripts/index.py search --db $IDX --query "分数乘法 教学重难点" --topk 5 --mode or
# 2) RAG 知识库（BM25，跨会话复用）
python scripts/rag_kb.py search --db $KB --query "分数乘法 教学重难点" --topk 5

• 两者任一命中高质量记录 → 该主题不再重复联网；
• 仅对未命中/缺口部分，回到阶段 1 的 plan 派发子 Agent 联网补全；
• 若索引库为空（首次），先 python scripts/index.py init --db $IDX 初始化，再执行阶段 3 入库。

阶段 3：入库沉淀 + 去重整合 + 冲突校验

3.1 归一化与入库

每条采集结果先归一化为标准记录（带 source/tier/rtype/grade 必带元数据，可溯源），再入库两层：

# 单条：先把原始文本用 compress.py fields 抽字段，再归一化（或直接手写）
python scripts/compress.py --file raw.txt --mode fields --source https://x.com/a --tier 1 --max-chars 400
# 归一化为标准 JSON 记录（可直接入库）
python scripts/collect.py normalize --title "分数乘法教案" --source "https://basic.smartedu.cn/xxx" \
        --tier 1 --rtype 教案 --grade "六年级/人教版" --text "正文..." --method websearch
# 批量入库（把多条 normalize 结果聚成 [{title,source,tier,rtype,grade,text},...] 文件）
python scripts/rag_kb.py add-batch --db $KB --file batch.json
python scripts/index.py init  --db $IDX          # 仅首次
python scripts/index.py add-batch --db $IDX --file batch.json

3.2 自学习信号积累（越用越聪明）

每完成一次采纳/拒绝，立即写入学习库，下次 learn.py rules 会反哺检索策略：

python scripts/learn.py feedback-add --topic "分数乘法" --rating good --source "国家智慧教育平台" --note "教案完整贴合新课标"
python scripts/learn.py source-score --source "国家智慧教育平台" --tier 1 --outcome hit
python scripts/learn.py kw-score --kw "分数乘法 教学设计" --outcome hit
# 失败/未采纳同样记录（outcome=miss），净分转负后自动进入 AVOID 规则

3.3 去重 + 冲突处理

• python scripts/rag_kb.py dedup --db $KB 或 python scripts/index.py dedup --db $IDX：同质内容按信源层级保最优（tier 小者优先、同 tier 保留更长正文）。
• 发现多来源内容不一致 → 严格按 references/conflict-rules.md 四步流程处理（罗列冲突点→可信度排序→择优采信+标准话术→无法判定则全展示提醒）。
• 三必校验：知识点核对教材定义与课标；版本核对教材版本；学段核对年级匹配。

阶段 4：标准化输出（固定 4 模块，排版零随机）

1. 先用骨架生成器锁定排版：
   bash python scripts/report.py --topic "分数乘法" --subject 数学 --grade "六年级上册" --version 人教版 --scenario 备课 --out 报告.md
2. 往骨架中填充成品内容，严格按 references/output-template.md 的固定 4 模块顺序：搜索摘要 → 推荐资料列表（含成品资料正文）→ 矛盾与争议点（无则填「无」）→ 补充建议，文末统一来源汇总。每个板块必须标注信息源（来源：XXX），正文不穿插链接。
3. 按格式偏好记忆交付。默认 Markdown 交付：report.py 输出 .md 骨架，填充成品后经 present_files 呈现；若确需 .docx 成品，可用外部工具（如 pandoc / Word）将 .md 转换得到（保持本技能零第三方依赖，不引入 python-docx）。

阶段 5：记忆更新（交付后必做）

# 检索历史
python scripts/prefs.py history-add --query "六年级分数乘法备课" --scenario 备课 --output 报告.md
# 上下文记忆（跨轮次工作集，便于下次续接）
python scripts/prefs.py context-set --key working_topic --value "分数乘法"
python scripts/prefs.py context-push --item "已检索到3条一级信源，RAG库命中2条，已入库沉淀"
# 自学习反馈（越用越聪明，与阶段3.2形成闭环）
python scripts/learn.py feedback-add --topic "分数乘法" --rating good --note "整体资料质量高"

本次会话中用户表达的新长期偏好 → prefs.py set 持久化；信源类约束同步写入 sources.md 用户自定义规则小节。

Token 节省策略（全程强制）

1. 子 Agent 隔离检索：网页原文只进子 Agent 上下文，主 Agent 只收压缩摘要（≤2000字/Agent）。
2. 上下文压缩脚本：
   bash python scripts/compress.py --file page.html --mode clean # 去HTML标签/导航/脚本 python scripts/compress.py --file text.txt --mode digest --max-chars 1500 # 要点压缩 python scripts/compress.py --file raw.txt --mode handoff --topic T --source U --max-chars 800 # 子Agent回传紧凑块 python scripts/compress.py --file raw.txt --mode fields --source U --tier 1 # 结构化字段抽取，便于归一化入库
3. 先库后网（双检索层）：阶段 2 先 index.py search + rag_kb.py search，命中足够则跳过整轮联网采集。
4. 按需加载 references：只在对应阶段读对应文件，不一次性全读。
5. 固定紧凑回传格式：结构化字段代替自然语言长段描述（见阶段 1.3）。
6. 通道熔断降级：故障通道直接跳过，不空转重试、不阻塞整体，避免无谓 token 消耗。

硬性约束（每次执行不可变通）

• 永久屏蔽黑名单信源；付费资源不直接使用，标注后征求用户同意。
• 输出不穿插链接，溯源统一放文末。
• 优先近3年资料（课标无重大更新可放宽至5年），淘汰废止课标旧资料。
• 资源类型优先级：教案 > 课件 > 习题 > 教学设计 > 微课视频 > 扩展阅读。
• 冲突不隐藏、不随机取舍；无法判定时全展示并提醒用户甄别。
• 单一信源/通道故障必须降级处理，绝不允许因某路卡顿而整体无产出。