To Reference

To Reference

先验知识注入入口，与案例知识（/skill:to-postmortem）并列。reference 是独立于任何具体事故的领域事实与方法论——不是 case，不携带 symptoms/diagnosis/fix 闭环。本 skill 的产物以 status: active 直接落入正式 type 目录（references/<type-dir>/），PR review 即审核闸门——合入即生效：词条随 PR 提交，review 通过合入 = active 进入诊断上下文。未合入的 PR 分支不 main，天然不进诊断上下文——安全性语义由"合入动作"承担，不再需要 draft 中间态隔离。

⚠️ 质量原则（比 case 更严）：reference 是知识库的浓缩资产，一旦错误，污染的是所有引用它的诊断。本 skill 的产出不是"录进去"，是"提交审核"——先与用户反复确认意图（grill），再产出 active 词条随 PR 提交，由 maintainer 在 PR review 审核。环节缺一不可。

输入方式

接受四种输入，来源类型决定信任基础与后续审核深度：

1. 内联粘贴（工程师经验 / 手册片段，engineer-input）：

/skill:to-reference "在 A2 上排查通信问题，别查 HCCL_BUFFSIZE，查 NPU 驱动版本：cat /proc/driver/npu/version，期望 >= 23.0"

2. 单个文件路径（来源类型由 --source 指定，不默认绑定）：

/skill:to-reference --file ~/notes/npu-smi-fields.md --source engineer-input
/skill:to-reference --file ~/ascend/昇腾950_NPU架构白皮书.md --source official-doc

--source 是必填判断项（engineer-input / official-doc）：来源类型由内容权威性决定，不由输入通道决定——同一份文件可能是工程师笔记（engineer-input）也可能是官方文档（official-doc）。本地 PDF 用工具提取文本（如 pymupdf）后再走本模式；.docx/.doc/.pptx/.xlsx/.rtf/.epub 先转 Markdown（见 §1「二进制文档与截图」）。verification 状态见 §1。

3. URL 爬取（官方文档，official-doc）：

/skill:to-reference --ingest https://www.hiascend.com/document/.../plog-error-codes

4. 从 case 集合归纳（case-derived，最常见——工程师没有专门写先验知识的习惯，但案例里反复出现共性）：

/skill:to-reference --ingest-cases "[VLLM-ASC-9596, VLLM-ASC-12989, VLLM-ASC-9507]"

5. 修订已有 reference（--update <ref-id>——内容有误/过时/不完整时更新，不是新增）：

/skill:to-reference --update cann-runtime-error-codes --ingest <新来源 url>

• agent 读现有词条 + 新材料，产出修订 diff 建议（改了什么/为什么），人确认后落 PR；
• 修订 active 内容 = 修改已生效知识 → kb/high-risk 双签（对齐 case 层 knowledge_modification）；
• 修订前先确认该 ref 已被标 pending-review 或 draft（降级中修订；diagnose 只读 active 天然隔离）；
• 小修（错别字/补一句/改一个错误码含义）→ 不启动 --update，维护者直接改 YAML + PR 更轻（git diff 可追溯）；--update 留给大修（methodology 流程重写/错误码表按新官方文档整体更新）。

流程

0. 识别来源类型（决定流程分支）

1. 提取（按来源类型）

official-doc（URL 爬取 / 本地官方文档文件）：

• 抓取/读取目标章节（只读相关部分，不全量载入——日志裁剪原则的翻版；本地 PDF 用工具提取文本如 pymupdf）；
• 长字段（description/meaning）不硬截断——截断到字符数会产生不完整句子（"在第一…"式残缺），语义完整性优先于体积；需要精简时提炼要点而非截断原文；
• 抽取为 reference 草稿，保留原文出处：url（来源定位符——公开 URL 优先；本地文档无公开 URL 时用可移植文档引用如"昇腾950 NPU 架构白皮书（华为技术有限公司）"，禁止写 ~/ 或绝对路径，CI 会红）+ version（文档版本 / CANN 版本，从页面元数据或内容推断，拿不准就标 unknown）+ fetched_at；
• 必须标注 sources[].verification，二选一：
  • auto-extracted——模型从源材料抽取、未经 agent 对源逐字核验（如一次 URL 抓取后直接归纳），reviewer 必须 spot-check 语义是否被扭曲；
  • cross-checked-source——agent 已直接对源原文（如 PDF 文本提取）逐字核验，reviewer 抽查即可。只有当你真的逐字对照过源才标这个；拿不准一律标 auto-extracted（诚实退化，宁低估不高估）。

二进制文档与截图（本地官方文档）：约束是不变量、不是工具——词条只写源里确有的内容、出处可核验可移植、材料不外传。工具选择（含装不上时的替代路线）都在这个约束之下。

• 文本提取（首选）：.docx/.doc/.pptx/.xlsx/.rtf/.epub 用 npx -y @firecrawl/anydoc <file> -o <file>.md（Node ≥ 20，首次自动下载，保留表格/公式）；无 Node 但有 Python ≥ 3.10 → pip install firecrawl-anydoc + python -c "import anydoc,sys; print(anydoc.to_markdown(sys.argv[1]))" <file>；PDF 用 pymupdf。
• 首选装不上就自己找路，别直接判失败：这些格式本质是 zip + XML——.docx 读 word/document.xml 的 <w:t>；.pptx 读 ppt/slides/slide*.xml；.xlsx 读 xl/sharedStrings.xml + xl/worksheets/sheet*.xml；.odt/.ods/.odp 读 content.xml（python -m zipfile -e <file> out/ 解包，Windows 无 Python 用 [System.IO.Compression.ZipFile]::ExtractToDirectory）。丢掉的表格/排版如实记进 PR body，不假装完整。探索出的新路线跑通了值得固化 → 交给收尾的伴随演进评估（见 /skill:evolve-check），不要在这里自己加卡。真的都抽不出来 → 请用户转成 md 或贴文本，不静默跳过附件。
• 截图：纯文本通道（anydoc 或 XML 提取）只出文字，架构图 / 报错截图会被丢掉（anydoc 无占位、无告警）。.docx/.pptx/.xlsx/.odt 都是 zip，用 python -m zipfile -e <file> out/ 取 word/media/（pptx 为 ppt/media/，xlsx 为 xl/media/），再用自己的图片识别能力直接读图（模型支持图片输入时）。
• 读不了图 → 不提取、不推测：词条只写文本里确有的内容，未提取的截图列进 PR body 的「来源与验证状态」区块交 reviewer 补——不要从截图的标题或上下文反推内容。
• 确定性提取才可逐字核验：anydoc 或 XML 直读都是确定性解析（不经模型改写），逐字对照原文后可标 cross-checked-source；未逐字对照的仍标 auto-extracted。
• 出处仍须可移植：本地 docx 的 sources[].url 用可移植文档引用（标题 + 出品方 + 版本），禁止写 ~/ 或绝对路径（CI 会红）。
• 不外传：不要用 --ocr hosted（把整份文档上传第三方服务）；内部文档一律本地处理。

内联 / 文件（engineer-input）：

• 从工程师描述中抽取事实/方法论，判断 type（见 §2）；
• 判断它独立于具体事故（是 reference）还是绑定事故（是 case，引导走 /skill:to-postmortem）；
• 缺失的信息（适用平台？适用版本？出处？）记下来，grill 阶段逐项问。

case 归纳（case-derived）：

• 读取指定 case 的 root_cause / diagnosis / fix；
• 找共性模式——重复出现的根因对象、相似的诊断步骤、相似的 fix 模板；
• 归纳为 reference 草稿，保留证据：cases: [<case-id>, ...] + extracted_at；
• 区分两类产物：事实共性 → platform-fact/error-code/tool；流程共性 → methodology。

2. 归类（type 判定）

按 references/_types.yaml 注册表判定 type：

区分 platform-fact 与 software-fact：绑定具体硬件平台/芯片规格（如 "A5 HBM 64GB"）→ platform-fact；CANN 软件栈或运行时系统的可验证事实（如日志路径、格式、机制，跨平台成立）→ software-fact。

fault-pattern 表形态（组织单元 = 验证单元）：官方手册的"现象→根因→处理"排障条目（非多步流程、非事故闭环）→ 按主题域成表（如 references/fault-patterns/dvpp-decode.yaml 承载 VDEC/JPEGD 解码故障）。symptoms 是可直接 grep 的日志签名/错误码（诊断时按签名命中根因），cause/fix 提炼自来源。

error-code 表形态（组织单元 = 验证单元）：错误码天然成族（CANN Runtime 507xxx / HCCL / aicpu / Driver），同族同源同验证——一个族一个文件（如 references/errors/cann-runtime.yaml 承载 507903/507018/507057...），表级共享 sources/status/applies_to，不逐码建文件。case 提炼的条目逐条验证 → 条目带可选 source_cases。检索时 agent 按族定位文件，表内 grep code 一次命中。数据集类的 applies_to 平台/版本应从来源的结构化字段映射（如官方文档的 models/support 字段），不靠 agent 猜测——来源没声明的平台不写。

tool 组织单元 = 一个「诊断用途面」（不是「一个可执行文件」，也不是「一个子命令」）——先查 references/tools/ 是否已有同用途面条目，有则追加到该条目的 content.commands，不新建文件。判据三问的实质：它们是不是一次动作的三个面（配置/执行/输出）——是则合，是两个独立动作则拆。三问：①同验证（同版本 pin + 同次 last_verified，可以是同一份文档，也可以是一份能力的配置面+执行面文档）；②同诊断（一次诊断会同时需要它们——同 category、同阶段）；③同动作（同一动作的三个面，各有自己的命令与输出面即为两个动作）。反例：一个产品有 20 个子命令 ≠ 20 个词条——按用途面归并（msprobe 的 dump+config.json 是「采集」这一次动作的配置面与执行面 → 合；compare 与 graph_visualize 是两个独立动作、两套输出语义 → 拆）。检索键前置：工具名 / 子命令名必须出现在 title / summary 开头——tool 走 summary 层（_summary-index.yaml）且该层会截断，键写在后面等于检索不到。

拿不准 type → 按最贴近的登记 type 落草稿，并在草稿里标注 type_uncertain: true 交 maintainer 定夺。不要自行发明未登记 type（CI 会红；登记是 maintainer 的动作，见 _types.yaml）。

3. Grill 阶段（关键——确保产物符合用户意图）

工程师输入（内联/文件）必须逐项确认，不是一次性"对吗"：

1. 意图确认：把你提取的核心事实/方法论用自己的话复述给用户："我理解你说的是：……，对吗？"——用户纠正就更新，直到用户明确认可；
2. 边界确认：适用平台？适用框架/版本？适用范围之外的情况是不是也成立？逐维问（platforms / frameworks / versions / categories），确认 applies_to 字段；
3. 出处确认："这条经验的来源是？——某次客户案例 / 某份内部文档 / 官方手册哪一章？"出处含糊 → 草稿标 source_vague: true，仍可进 inbox 但 maintainer 审时会重点查；
4. 排除确认："这条在什么情况下不成立？"——工程师最常漏掉反例，这是 reference 区别于 case 的关键（reference 是断言，必须有适用范围）。

case 归纳必须确认不失真：

1. 共性确认："这三条 case 的共同点是 X，我归纳为 Y，对吗？"——用户认可才继续；
2. 差异确认："这三条里有没有哪条是特例（根因不同但现象相似）？"——有特例就剔出，避免把偶然共性当规律；
3. 覆盖确认："这个归纳覆盖了你要沉淀的东西吗？还是你心里还有第 4 种场景？"

official-doc：不逐项 grill（来源明确），但必须在报告里显式告诉用户验证状态——auto-extracted 要说明"这是模型抽取的摘要，建议打开原文核对语义"；cross-checked-source 要说明"已对源原文核验，可抽查"。把 verification 写进草稿 sources[]。

grill 分级（体验瘦身——反复对齐是置信度增加过程，但按需分级，不是无差别多轮）：

• 高置信（默认）：来源明确（official-doc）、内容自包含、无歧义 → 单次确认——一次复述"我理解你说的是：……，对吗？"，用户认可即过，不逐项追问；
• 中置信：工程师输入但表述清晰 → 确认意图 + 出处，边界/反例顺带一问；
• 低置信（必须多轮）：表述含糊、来源不明、边界不清 → 完整四轮（意图/边界/出处/反例）逐项确认。

判据：agent 自评置信度决定 grill 深度——高置信单次、低置信多轮；拿不准往高一档走（宁可多确认一次，不因省事产出歧义词条）。

grill 是人审的第一道过滤——确认过程中用户放弃/否认的条目，直接丢弃，不进 inbox。宁可少而准，不要多而疑。

4. 去重与聚类归属检查（进正式目录前）

扫 references/ 现有词条，分三种关系：

• 完全覆盖（现有词条已含本条全部内容）→ 不产草稿，告诉用户"这条已被 <ref-id> 覆盖"，列出比对；
• 变体（同主题不同平台/版本）→ 提示用户："现有 <ref-id> 覆盖 A3，你这条是 A5 场景——是要并进现有词条的 applies_to，还是独立词条？"按用户回答处理；
• 层级（现有词条是总览、本条是细节，或反之——如现有 a5-l2-cache 总览 vs 本条 a5-l2-cache-detail）→ 提示用户："现有 <ref-id> 是总览，你这条是同一主题的细节——建议独立词条并在两边 related_references 互指；或并进现有词条。哪种？"按用户回答处理。层级关系本身是合法结构（不是重复），但要显式互链，避免检索时只见其一；
• 查不到 → 新词条，继续。

聚类归属（追加不新建）——数据集类（error-code）在去重之外还要判定族归属：

• 提炼到错误码 → 先查 references/errors/ 现有文件，按组件判定归属（族划分跟随来源——CANN 错误码参考怎么分章，文件就怎么建）；
• 归属已有族（如 507xxx 进 cann-runtime.yaml）→ 追加到该表 errors 列表，标新 source_cases——不新建文件；
• 仅无对应族文件时才新建（如第一个 HCCL 错误码 → 建 references/errors/hccl.yaml）；
• 独立词条类：查 tags / related_references 是否可关联现有词条，不合并（关联不合并——主题聚合由标签承担，不是文件合并）。

5. 产出词条 → references/<type-dir>/（active，无 _inbox）

⚠️ 词条零注释（硬规则）：下面模板中的 # 注释是给作者看的写作指引，产出 YAML 时必须删除全部注释行——词条是给 agent 消费的数据，不是带元说明的文档；重复注释是 token 浪费（23 条 × 同一注释的教训）。语义解释（url 定位符规则、verification 含义、status 规则、字段含义）只存在于 SKILL.md / references/README.md 文档层，不进词条。值自解释就不加注释。

按 reference schema 产出完整 YAML（字段定义见 references/_types.yaml 与 references/README.md；基础元信息 + content 全部填齐，CI 强校验——词条必须 schema 完整，这是与 to-postmortem 草稿可残缺的差异）：

id: <kebab-case-slug>              # 唯一；如 plog-error-507903、a3-hccl-buffsize-check
type: <registered-type>            # 见 references/_types.yaml
title: <short>
summary: <one-liner>

sources:
  - type: <official-doc | engineer-input | case-derived>
    # official-doc: url + version + fetched_at [+ verification]
    # engineer-input: engineer + input_session + confirmed_at
    # case-derived: cases + extracted_at
    # verification（official-doc 必填，其余可选）:
    #   auto-extracted | cross-checked-source

applies_to:                        # 能确定就填，确定不了留待 grill 后补
  platforms: [...]                 # A2-910B | A3-910C | A5-950 | cross
  frameworks: [...]
  versions: {...}
  categories: [...]                # methodology 必填

status: active                      # 产出即 active——PR review 即审核闸门，合入即生效
last_verified: <今天>              # 人确认的日期（grill 认可即视为一次人核）
# 观测字段（可选；产出时**不填**，由 groom 在 reference 观测回写时有数据才填）：
#   hits: <int>                    # 被引用次数（trace.reference_lookup 计数）
#   last_hit: <date>               # 最后引用时间

content:
  # 按 type 的 schema_required 字段（见 _types.yaml / references/README.md）
  # error-code 是表形态：content.errors 列表，一个族一个文件，不逐码建文件
  #   errors:
  #     - code: "507903"
  #       meaning: "..."
  #       related_signatures: [...]
  #       source_cases: [<case-id>]   # case 提炼的证据（可选）

• status 写 active——产出即 active，PR review 即审核闸门，合入即生效；深审条件在产出时就满足（case-derived + methodology 需 ≥3 条 case 引用，CI 强校验，产出时不达标 PR 直接红——不允许以 active 提交未达深审门槛的词条）。未合入的 PR 分支不 main，天然不进诊断上下文；合入动作即审核通过；
• 初始 confidence 按来源类型（写进词条注释，供审核参考）：official-doc 0.6 / engineer-input 0.3 / case-derived 0.3–0.6（case 数与一致性越高越靠近 0.6）；
• last_verified 填今天——grill 阶段用户认可即视为一次人工确认，但这不替代 maintainer 审核；
• 产出前检查：词条文件里不得有任何 # 注释行（上模板中的注释全部删掉）——grep -c "#" <file> 应为 0。

6. 报告落点（生成后必须明确告知）

词条 → references/<type-dir>/<ref-id>.yaml（status: active）
来源类型：<engineer-input | official-doc | case-derived>
状态：active（PR review 即审核闸门——本词条随 PR 提交，合入即进入诊断上下文；case-derived + methodology 已按 ≥3 条 case 引用满足深审门槛）
审核建议：<按来源类型的审核深度提示>

别让用户去找自己的产出——报出具体路径，说明"随 PR 提交，review 合入即生效"。

7. 收尾 evolve-check（伴随演进评估，默认执行）

先落执行记录（evolve-check 读它作现场）： python3 scripts/log_skill_exec.py --skill to-reference --products "<ref-id>(active),..." --reason "<一句话：归纳 N case / 新增家族>" --source <来源> --tokens <估算>

词条产出、出最终报告前，执行一次伴随演进评估（read skills/evolve-check/SKILL.md 遵循）：本轮发现可跨词条归纳的共性（T1）、新错误码家族首次入表需扩覆盖（T5）、 或提取/归类环节有流程摩擦（T3/T4）时，agent 自动产 idea 卡并自行验证执行 （ev_proposal 产卡 → 验证 → 进攒批）；无信号则报告加一行"evolve-check：无演进 信号"。这是流程默认收尾，不需要用户另说"改进系统"——演进由数据触发，像人 学习。产出与流程报告一并给出。

产出落点

• references/<type-dir>/<ref-id>.yaml——词条（status: active；PR review 即审核闸门，合入即生效，无中间 draft 态）
• PR review：reject → 不合并（分支废弃，词条不进 main）；request changes → 修改后重新提交；approve + 合入 → active 生效
• 遗留 draft（历史旧态，修订 3 前产出）：由 /skill:knowledge-groom R1 按需清理或补审

与 to-postmortem 的分工：案例（事故闭环）→ /skill:to-postmortem → knowledge/；先验知识（独立事实/方法论）→ /skill:to-reference → references/。两条入口不互相覆盖——to-postmortem 不自动产 reference，to-reference 不反向产 case。

为什么先验知识要专门入口

案例沉淀（to-postmortem）解决"同类问题下次直接命中"；但工程师的通用经验（怎么查 plog、哪个命令看什么、这个错误码意味着什么）不绑定任何具体事故，散在个人脑子里，每次诊断都重新摸索。没有专门入口，这些知识永远进不了仓库——因为工程师不会为了沉淀"我知道怎么查设备日志"去写一份 postmortem。to-reference 把这个门槛降下来：工程师随口一句话，agent 提取 + grill 确认，30 秒产出可提交词条。