Reference Ingest

把上游文档仓里的官方文档批量吸收成先验知识。适合：组织（如 GitCode 的 cann）下有几十个仓，每个仓的 docs/ 里散着真正专业的定位手册、错误码表、FAQ、调优指南，而人工一篇篇读不现实、读完也记不住读过哪些。

与相邻 skill 的分工（先分清再动手）

产出规则不在本 skill 里：怎么归类（type 选择）、怎么写（schema 完整性、零注释、symptom 可 grep）、grill 强度、深审门槛——全部以 skills/to-reference/SKILL.md 为准，本 skill 只负责把候选正文以最低成本、可追溯、不重复的方式交到那一步。

前置

无外部 CLI 依赖：scripts/gc_docs.py 直连 GitCode API（读公开仓不需要 token）。任务开始前先确认它可用（python3 scripts/gc_docs.py repos --org cann | head -3）；报错就先修脚本而不是改走手工路径。

输入方式

/skill:reference-ingest cann/hccl                    # 指定仓：扫全仓文档面并给候选
/skill:reference-ingest --org cann --status          # 看台账：各源决策分布（哪些仓扫过、多少未评）
/skill:reference-ingest cann/hccl --prefix docs/zh/user_guide/fault_diagnosis   # 指定子面（推荐：先吃结构化手册）
/skill:reference-ingest "继续沉淀"                    # 续接：读台账找 pending 与未扫的源，按优先级推进

状态文件是唯一台账（reference-ingest-state.json）

结构与字段含义见 docs/guide/reference-ingest-pipeline.md。执行侧只需记住三条：

1. 写入口只有 mark，别手工编辑 JSON（scan 会更新扫描游标，mark 写判定）；
2. skipped 必须带 --note：一句话理由，下一轮不再复核这篇（脚本强制，缺 note 直接报错退出）；
3. 同一克隆内串行：fetch/mark 是 read-modify-write，与 ingest-state.json 同一纪律，别并发跑。

流程

0. 选源与仓级判定（先给整仓一个结论，再决定要不要扫）

整仓不纳入的仓（算子库/模板库、治理与竞赛、行业 SIG、agent 知识仓、框架适配仓）不需要扫树——扫大仓可能几分钟，而结论早由仓的类别确定。用仓级判定记账，下一轮不必再扫、也不必再判：

python3 scripts/gc_docs.py triage <repo> --decision rejected --note "算子库/模板库：文档以 API 参考与样例为主，非独立于事故的先验知识"
python3 scripts/gc_docs.py triage <repo> --decision candidate --note "文档面大或含工具/库文档，留待后续批次按价值排序评估"
python3 scripts/gc_docs.py triage <repo> --decision selected --note "已按价值优先级纳入并完成沉淀"

三种取值：selected（已纳入并沉淀）/ candidate（候选待评估，进下一轮选源池）/ rejected（不纳入，理由必填）。仓级判定与文档级 mark 并存、互不覆盖：仓级说"这个仓要不要看"，文档级说"这一篇沉不沉"。

0.1 选源排序（哪些仓值得吃）

判据是"仓里有没有面向问题定位的文档"，不是 star 数：

• 先看 gc_docs.py repos（组织全仓 + star + 描述）；
• 再看文档面结构：scan <repo> --prefix docs/（只拉目录树，成本≈0）；
• 高价值形态：分级故障诊断手册（fault_diagnosis/）、FAQ 集、错误码参考（error_code_ref/）、调优/精度方法页、profiling 采集与解读、appendix/faq_failure_cases 一类实战集合；
• 低价值形态（默认不碰）：API 参考面（逐接口罗列，无判据）、教程/训练营、竞赛与治理文书、算法/编程范式教程、源码与模板库。

已确认的优先级（前批已吃 cann/cann-samples）：hccl（通信故障诊断手册）→ runtime（FAQ + 错误码参考）→ oam-tools（asys 故障收集与解析）→ docs（CANN 公共文档仓，按判据摘取）→ cann-recipes-* / asc-tools / ops-test-kit / shmem / cann-learning-hub。

1. scan：增量扫描（零模型成本）

只对 selected/candidate 的仓做这一步；rejected 的仓在第 0 步就结束了。

python3 scripts/gc_docs.py scan hccl --prefix docs/zh/user_guide/fault_diagnosis --top 40
python3 scripts/gc_docs.py scan runtime --json > /tmp/cand.json     # 供 fetch --from-scan

输出 新增=N 变更=M 已定=K 未变待评=J 与候选表。新增与变更才是本轮工作量——已定（harvested/skipped）与未变的不会再来烦你，这就是"防止重复抓取"的落地方式。

2. 筛候选（用路径，不用正文）

先按路径名把明显不值得沉淀的批掉并记账（一次 mark 可传多个路径）：

python3 scripts/gc_docs.py mark hccl --decision skipped \
  --note "索引/导航页，正文在子页（已由子页覆盖）" \
  --path "docs/zh/user_guide/fault_diagnosis/README.md,docs/zh/user_guide/fault_diagnosis/_dump_a.md"

判据：这一页里有没有能当 grep 判据或处理动作的东西。只有链接列表的伞页/索引页、只有日志 dump 的证据页、只有接口清单的 API 页 → skipped（理由写清，供人审回看）；带"现象/原因/解决"或"判据/阈值/命令"的页 → 进候选。

两类东西不该出现在候选表里，脚本已按默认规则排除（AGENT_KB_DIRS 与 basename 规则）：各仓自带的 agent 知识目录（.claude/、.agents/、.codex/、.opencode/——只作线索、不作权威源）与构建/依赖清单（CMakeLists.txt、requirements*.txt）。若某个仓确有例外（例如正文就写在某清单里），用该仓的 config.exclude / config.exts 单独放宽，不要改全局默认。

3. fetch：按需抓正文（含逐字节校验）

python3 scripts/gc_docs.py fetch hccl --from-scan /tmp/cand.json

正文落到主检出的 ref-docs/<owner>/<repo>/<commit12>/<path>（git-ignored，同一克隆所有 worktree 共读；已存在则复用，不重抓）。抓取时按 git blob sha 与目录树逐字节比对：上游改过、或路径返回了 HTML 页壳，当场报错而不是静默入库。

4. 抽取（token 纪律的执行点）

剥码块的手法（日志 dump 占文档体积的一半以上，且本仓库本就要求日志裁剪）：

python3 - <<'EOF'
import re,glob
out=[]
for f in sorted(glob.glob('<缓存目录>/*.md')):
    t=open(f,encoding='utf-8').read()
    t=re.sub(r'```.*?```','[码块省略]',t,flags=re.S)
    out.append(f"\n===== FILE: {f} =====\n"+t.strip())
open('/tmp/bundle.md','w',encoding='utf-8').write(''.join(out))
EOF

码块里的内容按需再取：命令/阈值/枚举表只在需要写进词条时，针对那一篇单独 grep 出码块（grep -n -A6 "<关键字>" <缓存文件>），而不是把整篇码块读进来。

5. 产出词条（严格按 to-reference）

• 归类与写出规则全在 skills/to-reference/SKILL.md（本 skill 不重复）；产出前先查已有词条，能追加就不新建（append-don't-create），主题聚合走 related_references（relate-don't-merge）；
• sources 里 official-doc.url 用可点开的仓内路径（https://gitcode.com/cann/<repo>/blob/master/<path>；整面子面可用 tree/ 目录 URL），version 写「仓 + commit 短 sha + 抓取日期」以钉住版本；verification 按是否逐字核验如实标；
• 本批次真正读过的每一篇都要在状态里留下 refs（哪条词条消费了它）——这是"来源可追溯"与"下一轮不重评"的同一条记录。

6. grill 与 mark

• official-doc 属弱 grill：不必逐条确认，但批次范围与取舍要向用户交代一句（吃了哪个子面、跳过了什么、为什么）；
• 产出后回写判定：

python3 scripts/gc_docs.py mark hccl --decision harvested --refs hccl-comm-init-and-link-faults \
  --path "docs/zh/user_guide/fault_diagnosis/link_timeout_EI0006.md,..."

7. 收尾（本批的固定动作）

python3 scripts/verify_references.py --check
python3 scripts/build_ref_summary_index.py && python3 scripts/build_procedure_index.py
python3 scripts/gc_docs.py status          # 台账核对：本批 harvested/skipped/pending 是否归零

PR body 里必须写清的：吃了哪些源与子面、跳过了哪些、未提取的图（figures/*.png 一类）、verification 口径、以及 token 成本量级。批次结束接 /skill:evolve-check（流程摩擦与 miss 是演进信号）。

批次节奏

一批 = 一个主题（通常 = 某仓的一个子面），走一次 PR：批太小则 PR 噪声大，批太大则人审不动。同一主题跨仓时按主题聚合产出，但扫描与记账仍按仓。批与批之间不必等确认（除非选题有歧义）；进度以"台账 + 一句选题"呈报给用户。