Engineering Copilot — wiki 之上的对象 / 关系层

LLM Wiki v1 用 234 个 markdown 页堆出散文知识,AI 搜索 + 索引能查"哪些页讲了 DESAT"。但有些查询 markdown 答不了:

• "什么 mitigate SC type 1?" — 答案在多个 wiki 页里,要 LLM 综合多个 prose 段才能给完整 list
• "DESAT 的依赖链是什么?" — wiki 用散文讲,没有结构化依赖图
• "改了 ISO5852S 性能 spec,影响哪些 SG?" — wiki 没记录这种跨页因果关系

根因:markdown 把关系埋进散文。机器查不出来。

v2.0 加法:同一份知识用 YAML object 再写一遍结构化骨架,只记 id / type / relations / 关键参数,不复述 prose。markdown 仍是人读真相;object 是机器查真相。

两层是并行存在而非替换 — wiki 优化人读节奏(故事 / 推理 / trade-off),knowledge 优化机器查询(关系 / 一致性 / 图谱)。同一份知识两边各写一遍 ≠ 重复,因为优化目标不同:

关键:两层互引用——wiki 页 evidence 字段引用 wiki 路径,wiki 页底自动注入"## Engineering Objects"区列出引用它的 object。改了 wiki,跑一次 inject_wiki_links 即同步。

按 spec 锁定,不准自创:

id 命名规则:{type}_{name},全小写 + 下划线,id 前缀必匹配 type。validator 自动校。

forward 11 种 + 自动派生 11 种 inverse,总共 22 个语义方向:

schema 自动校方向:写错(如 component implemented_by mechanism)立刻报警。

加 object 的标准:这件事会被多次引用,且有结构化属性。

原则:object 是真理的骨架,不是 prose 的替代。所有细节、推理、tradeoff 仍在 wiki。

Phase 1 严格按 spec 圈定的范围(gate driver + DESAT + SC + functional safety)收口,目标是 schema 稳 + 闭环可查,不追求对象数:

• ✅ 30 对象全 schema valid,0 errors
• ✅ 139 relations(含 inverse 派生)
• ✅ schema v0.1 锁定:8 type / 11 relation
• ✅ validator + graph builder + query CLI 三套工具
• ✅ AI 搜索接入对象图
• ✅ 17 wiki 页底反向链注入

Phase 2 把对象层从 gate driver + FS 主域扩到 power electronics + HV safety + standards + functional safety + metrics + motor control + packaging + communication + cooling + cases 十大新域,并补完 mitigation / diagnostic 失衡。对象数 + 483%,8 type 均衡:

• ✅ 175 对象(+145 from Phase 1),全 schema valid 0 errors
• ✅ 330 relations(+191 from Phase 1)
• ✅ 0 ghost
• ✅ 108 wiki 页底反向链 (+91 from Phase 1, 46% of 234 页)
• ✅ schema v0.1 不变 — 8 type / 11 relation 全程不需扩
• ✅ pre-commit hook 自动验证 5 batch 实跑,抓住 1 个 ghost
• ✅ 类型分布:component 34 / mechanism 29 / failure_mode 28 / standard 24 / mitigation 18 / diagnostic 18 / case 15 / metric 9

Phase 2 Batch 1 (Power Electronics) — 加 10 对象:

• mechanism: SR / ACF / phase_interleaving / FCML / spread_spectrum_emi
• component: sic_mosfet / gan_hemt / dc_link_capacitor
• failure_mode: leakage_inductance_spike / rhp_zero_oscillation

Phase 2 Batch 2 (HV Safety + BMS) — 加 13 对象:

• component: hv_contactor / pre_charge_resistor / pyro_fuse / imd_bender
• mitigation: 3step_precharge / emergency_hv_shutoff / cell_balancing_active
• failure_mode: inrush_current / contactor_welding / insulation_degradation / cell_imbalance
• diagnostic: contactor_weld_check / imd_dc_injection / soc_ekf_estimation

Phase 2 Batch 3 (Standards 工业) — 加 11 standards:

• standard: aec_q100 / aec_q101 / aec_q104 / cispr_25 / iso_11452 / iso_15118 / ece_r100 / iatf_16949 / aspice / apqp / vda_6_3

Phase 2 Batch 4 (Functional Safety Standards) — 加 10 standards:

• standard: iso26262_part2 / part6 / part7 / part8 / part9 / part10 / part11 / iec_61508 / iso_21434 / iso_21448

Phase 2 Batch 5 (Metrics) — 加 8 metrics (新 type 类别):

• metric: spfm / lfm / pmhf / dc / fit / cpk / ppk / grr

Phase 2 Batch 6 (More PE + EMC) — 加 8 objects:

• mechanism: llc_resonance / psfb_zvs / dual_active_bridge / vienna_pfc
• failure_mode: emi_conducted_overlimit / emi_radiated_overlimit / immunity_failure / dc_bus_overvoltage

Phase 2 Batch 7 (Real-world Cases) — 加 5 cases:

• case: main_drive_inverter_asil_d / obc_v2g_22kw / precharge_failure_incident / battery_thermal_runaway_5min / smps_short_protection

Phase 2 Batch 8 (Motor Control) — 加 7 objects:

• mechanism: foc / mtpa / field_weakening / svpwm / sensorless_back_emf
• component: resolver
• failure_mode: position_sensor_fault
• mitigation: three_phase_short

Phase 2 Batch 9 (BMS + IC components) — 加 5 objects:

• component: aurix_tc3xx / battery_cell_lfp / battery_cell_ncm / ntc_thermistor
• diagnostic: temperature_sensing / current_sensing

Phase 2 Batch 10 (Motor Control deeper) — 加 7 objects:

• mechanism: dtc / dead_time_compensation / observer_pll_sensorless
• component: hall_sensor / incremental_encoder
• failure_mode: dead_time_distortion
• diagnostic: motor_parameter_id

Phase 2 Batch 11 (BMS deeper) — 加 6 objects:

• metric: soh
• mechanism: coulomb_counting / ocv_soc_calibration
• failure_mode: battery_overcharge / battery_overdischarge
• component: shunt_resistor

Phase 2 Batch 12 (PE diversity) — 加 6 objects:

• component: film_capacitor / litz_wire / planar_transformer / y_capacitor
• mechanism: common_mode_choke
• failure_mode: cap_esr_aging

Phase 2 Batch 13 (More cases) — 加 4 cases:

• case: usb_pd_100w_gan_acf / cpu_vrm_48v_fcml / dc_fast_charge_350kw / aircon_pmsm_compressor

Phase 2 Batch 14 (Power Module Packaging) — 加 8 objects:

• component: dbc_substrate / wire_bond / tim / baseplate_pin_fin / infineon_hybridpack
• mechanism: silver_sintering
• failure_mode: dbc_delamination / wire_bond_fatigue

Phase 2 Batch 15 (Communication) — 加 7 objects:

• component: can_transceiver / ethernet_phy
• mechanism: can_fd / secoc / e2e_protection
• failure_mode: can_bus_off
• diagnostic: can_bus_health

Phase 2 Batch 16 (Cooling System) — 加 6 objects:

• component: liquid_cold_plate / coolant_pump / heat_exchanger
• mechanism: active_cooling_control
• failure_mode: coolant_pump_failure
• mitigation: thermal_derating

Phase 2 Batch 17 (More cases) — 加 5 cases:

• case: server_psu_3kw_titanium / eps_asil_d_steering / solar_mppt_inverter / 48v_mild_hybrid / dc_dc_400v_to_12v

Phase 2 Batch 18 (Mitigations 补全) — 加 9 mitigations:

• mitigation: active_discharge / safe_torque_off / uvlo_protection / overcurrent_foldback / can_fail_silent / msd_manual_disconnect / charging_thermal_pause / overspeed_safety / comm_timeout_safe

Phase 2 Batch 19 (Diagnostics 补全) — 加 7 diagnostics:

• diagnostic: voltage_sensing / watchdog / lockstep_compare / clock_monitor / memory_bist / uds_dtc / gate_driver_status

Phase 2 闭环后,Phase 3 转向查询能力,4 项全部完成:

• ✅ AI 搜索 1-hop 展开:worker expand1Hop() 给每个 top-5 命中对象拉 1-hop 邻居 (forward label 优先,inverse label 次之),每对象 ≤ 6 邻居,渲染为 → rel → [type] id 喂进 LLM context。实测:query "DESAT 怎么 detect SC" → 答案不只引用 mechanism_desat,还正确串出 failure_mode_sc_type_2/3 因果链。
• ✅ query CLI 多 hop:query.py 加 3 命令 — path A B (BFS 最短路径) / chain ID --hops N (树状展开) / deps ID --rel R (沿单 relation 递归闭包)。
• ✅ 对象 status 分级升级 + draft 长尾收口:promote_status.py 引入二级阈值 — verified (≥1 evidence + ≥1 入边) / verified_strict (≥2 evidence + ≥2 入边),单调批量升。schema 同步加 verified_strict 枚举 + requires.to_types 加 metric (打通 case/standard requires metric 通道)。补一轮 hub-yaml relations 把 77 个 incoming=0 叶子 wire 进图谱 (failure_mode→case violates、case→case derived_from、case→standard derived_from、case requires mitigation/component/metric、mechanism→mechanism depends_on)。2026-05-17 末态 → 58 verified_strict / 117 verified / 0 draft (共 175)。relations 330 → 531。
• ✅ /graph D3 前端力导向图谱:Next.js 客户端组件 + D3 v7,175 节点 + 330 边实时模拟。功能:8 类型上色 / 类型 chip 过滤 / 点击高亮 1-hop 邻居 / 双击跳 AI 搜索 / 缩放拖拽 / 节点大小按度数。Bundle +22 KB JS,build pipeline copy-copilot-graph.mjs 自动同步 graph/objects.json 到 public/。

Phase 2 仍可继续扩,后续 Batch 候选:

• 加 metric 类对象 (SPFM / LFM / PMHF / DC / FIT)
• 加 D3.js 前端图谱视图(graph/objects.json 已就绪)
• query CLI 加多 hop 查询(如 "what depends on what depends on X")
• AI 搜索把 object 的关系展开 1 hop,context 更厚

本节以一次 SiC 电机驱动短路保护的工程溯源查询为例,演示如何通过对象层的图谱遍历,在一次命令行操作中完成从失效模式到规范条款的完整因果链追踪。

对象层在长期维护过程中存在三类操作性陷阱,会逐渐降低知识图谱的查询可靠性和结果质量。

1. 在 wiki 深度页面完成前创建对象产生"幽灵节点":为尚未撰写对应 wiki 页面的主题创建对象,会留下"幽灵节点"——对象有 id 和关系,但没有 source_page 证据支撑,也没有人可读的上下文。查询结果中幽灵节点会出现无法链接的引用,AI 引用了对象但 wiki 页面为空或不存在。规则:只为已写到至少草稿状态、且被记录事实已出现在页面正文中的主题创建对象。
2. 关系方向颠倒导致因果链推断反转:schema 定义有方向的关系(如 failure_mode CAUSES mechanism,而非反向)。若意外将关系创建为反向——mechanism CAUSES failure_mode——则因果推断倒置:询问"什么导致了这个失效模式?"的查询反而返回"这个失效模式会导致什么?"。这会给出错误的设计指导。创建新边前须在 schema 定义文件中核查关系方向;运行 validate.py 可自动捕获方向性违规。
3. component 与 subsystem 类型混淆导致查询漏匹配:栅极驱动 IC 既可建模为 component(当作 BOM 中的叶子器件选型时),也可建模为 subsystem(当作包含内部子器件的功能块分析时)。若在 175 个对象图中两种类型混用,针对 component 类型使用 IS_PART_OF 关系的查询会漏掉同一栅极驱动器以 subsystem 形式出现的另一上下文。解决方案:建立类型层次约定(如栅极驱动 IC 始终用 component,栅极驱动电路始终用 subsystem),并全程一致执行。

三个架构性边界条件定义了当前对象图设计在规模和性能上的极限,这些边界在图谱持续扩展的过程中将逐步显现。

1. 宽泛关系 IS_USED_IN 的查询结果集随对象数平方增长:IS_USED_IN 关系将器件链接到每个使用它的设计上下文。随着 wiki 从 175 增长到 500+ 个对象,对该关系不加类型过滤的查询每跳返回 O(n) 结果;两跳查询最多返回 O(n²) 条边。在 500 个对象、每个平均 5 条 IS_USED_IN 边的规模下,两跳遍历最多返回 2500 条结果,超出 LLM 上下文窗口。设计查询时必须按对象类型过滤并限制跳数;query.py deps --rel 命令已支持关系过滤,但实践者需主动使用。
2. 手动对象提取在 500+ 页面时成为流程瓶颈:Phase 2 收官时以半自动方式从 108 个 wiki 页面提取了 175 个对象(约 1.6 对象/页)。随着 wiki 增长到 300–500 页,按 1.6 对象/页计算需约 480–800 个对象,手动提取需约 160–320 人时。自动化对象提取(基于 NLP/LLM)是自然的下一步投入,但幻觉或低置信度的提取结果必须隔离为 draft 状态并经人工验证后方可接入图谱,否则图谱质量会急剧下降。
3. 全量对象注入在图谱规模扩大后会超出 LLM 上下文窗口:当前实现对每次 AI 搜索查询预注入前 5 个匹配对象作为结构化上下文,在 175 个对象规模时约增加 2000 token/query。若图谱增长至 500 个对象,前 5 个命中含有冗长的多段落对象时,上下文注入可能消耗 10,000+ token/query,压缩实际答案空间和用户追问的余地。此边界以上需要语义预过滤(嵌入全部对象,仅检索相似度相关的子集)或分层摘要(对象摘要 + 按需下钻)来替代当前的平铺注入方式。

工程经验表明,对象层系统在七个关键点最容易出错,每一条都曾在 Phase 2 扩张中真实发生过。

G1 — Type creep 冲破 8-type 锁死 spec 显式锁定 8 种 object type,validator 在 type 字段只接受枚举内的值。最常见失误是在 Phase 2 扩域时发明"subsystem"或"interface"等新 type,试图让关系图"更自然"。一旦 schema 膨胀,inverse 派生逻辑就面临方向对爆炸,validator 规则集要同步更新,历史 YAML 需要批量迁移。实际测试表明,8 type 已足以覆盖汽车电子主域的 175 对象,Phase 2 全程未触发一次 type 扩展需求。遇到"新概念",应先用 component / mechanism / diagnostic / mitigation 四个最通用 type 试着建模,再判断是否真的需要新 type。

G2 — Ghost 引用的静默破坏 object 的 evidence 字段引用 wiki 页路径(如 wiki/pages/topic-desat.md),但 wiki 页被重命名或移动后,引用就成 ghost。validate.py 默认模式只警告 ghost 而不 error,导致大批量 ingest 中 ghost 静默积累。Phase 2 Batch 5 实测发现:一次 wiki 大批重命名后,跑 validate.py --strict 才暴露 12 个 ghost,此前宽模式扫描完全没有报警。正确做法:每次 wiki 页大规模重命名后立即跑 validate.py --strict,使 ghost 变成硬错误,不让宽模式麻痹日常 CI。

G3 — Relation 方向写反导致语义反转 11 种 relation 都有明确的 source/target 类型约束,validator 自动校方向。最常见错误是把 implemented_by 写成正向:component implemented_by mechanism(component 被 mechanism 实现),实际语义要求 mechanism implements component(mechanism 在 component 上实现)。这类错误在图谱里表现为:查"mechanism_desat 的 component 是什么"得到空结果,而反向查 component 却意外出现了 mechanism。validator 会立刻报 invalid relation direction,但人工审查时容易把正确方向和错误方向搞反。建议每次写 relation 前先查 schema 中各 relation 的 source_types / target_types 约束字段。

G4 — 单一 evidence 使对象脆断 一个 object 若只有 1 条 evidence 引用,一旦那个 wiki 页被删除或重构,object 就变孤儿或 ghost。Phase 2 的 promote_status.py 设计了二级阈值:verified 要求 ≥1 evidence + ≥1 入边;verified_strict 要求 ≥2 evidence + ≥2 入边。把"≥2 evidence"设为 verified_strict 的硬门,就是为了让关键对象至少绑定 2 个 wiki 页,任一页重构不会让对象完全失根。批量加对象时,应优先把高度数对象(mechanism / component)的 evidence 补到 ≥2。

G5 — Object ID 大小写违反 validator 严格命名规则 object id 必须全小写 + 下划线,前缀必须匹配 type(component_* / mechanism_* 等)。用大写字母(如 Mechanism_DESAT)或短横线(如 component-iso5852s)的 id 会被 validator 当场拒绝(invalid id format)。批量生成 YAML 时,如果从 wiki 页 slug 直接复制,wiki slug 里的短横线会直接带进来。正确做法:所有 id 生成后立刻跑 validate.py,确认 0 errors 再 commit,不要积累到大批量才查。

G6 — inject_wiki_links.py 未重跑导致反向链过期 inject_wiki_links.py 把 object 的 evidence 引用反向注入到 wiki 页底部的"## Engineering Objects"区。每次新增 object 后必须重跑这个脚本,否则被引用的 wiki 页看不到新对象的反向链。Phase 2 Batch 19 收尾时发现:新增的 7 个 diagnostic 对象全部正确建模,但因为漏跑注入脚本,对应的 17 个 wiki 页底部没有更新,反向链空缺整整一轮。正确工作流:validate → build_graph → inject_wiki_links 三步必须按顺序全部完成,缺任何一步都是半成品。

G7 — Phase 2 大扩张稀释图密度 Phase 2 把对象从 30 扩到 175,边从 139 扩到 330,但边的增长比例(+137%)远低于节点增长比例(+483%),导致平均度数从 4.6 下降到 1.9。图谱越大,孤立叶节点越多,多跳查询路径越难找。Phase 3 通过 hub-yaml relations 补线把 77 个 incoming=0 叶子节点 wire 进图谱,relations 从 330 扩到 531 才把平均度数恢复到 3.0。经验:批量加对象时同步补 relation,比事后批量补线要省力得多——新对象至少要有 2 条 relation 才算有效接入图谱。

本节演示一个完整 5-step 查询流程,从全局统计到递归依赖闭包,均使用 Phase 3 收官后的真实数字(175 objects / 531 relations)。

Step 1 — 确认图谱健康:运行 python3 scripts/copilot/query.py stats,输出 175 objects / 531 relations / 58 verified_strict / 117 verified / 0 draft / 0 ghost。关系对象比 531/175 = 3.0,高于 Phase 2 末期的 1.9,确认 Phase 3 补线后图谱密度达标。

Step 2 — 查 mechanism_desat 完整档案:运行 python3 scripts/copilot/query.py show mechanism_desat,输出 type: mechanism / evidence: [topic-gate-driver-isolation.md, topic-desat-protection.md] / relations: detects failure_mode_sc_type_1 / detects failure_mode_sc_type_2 / implemented_by component_iso5852s / depends_on diagnostic_vce_monitoring。1 个节点 4 条出边,覆盖检测目标 + 物理载体 + 传感依赖,远比 wiki 散文里的一句话描述信息密度高。

Step 3 — 反向查所有检测 SC Type 1 的手段:运行 python3 scripts/copilot/query.py what detects failure_mode_sc_type_1,返回 [mechanism_desat, diagnostic_vce_monitoring]。两条 forward 边汇入同一 failure_mode 节点,关系图比 wiki 散文更清楚地说明了检测手段不止一种,而且 DESAT 和 VCE 监测是并列而非从属关系。

Step 4 — 查 DESAT 到 SC Type 2 的最短路径:运行 python3 scripts/copilot/query.py path mechanism_desat failure_mode_sc_type_2,BFS 结果:1-hop 直接路径 mechanism_desat -[detects]→ failure_mode_sc_type_2;同时存在 2-hop 路径 mechanism_desat -[depends_on]→ diagnostic_vce_monitoring -[detects]→ failure_mode_sc_type_2。2-hop 路径揭示:DESAT 通过依赖 VCE 监测间接感知 SC Type 2,这在 wiki 散文里需要跨 2 个页才能串联。

Step 5 — 递归展开 mechanism_desat 的依赖闭包:运行 python3 scripts/copilot/query.py deps mechanism_desat --rel depends_on,输出闭包:mechanism_desat → diagnostic_vce_monitoring → component_iso5852s(最终叶节点,无继续 depends_on 出边)。3 节点 / 2 hop,明确说明 ISO5852S 是 DESAT 保护链的硬件基础。这个闭包查询替代了手工翻阅 3 个 wiki 页的过程,且结果是机器可校验的(validator 确保每条 depends_on 边都有正确方向)。

对象层在三个边界场景下会暴露设计极限,有明确的应对方法。

C1 — Schema 版本迁移 若发现 11 种 relation 无法表达新的语义(如"测试覆盖"或"替代品"),需要在 schema.yaml 里新增 relation 类型并补写 inverse。此时所有 175 个现有 YAML 文件需要重跑 validate.py 确认无冲突,历史 evidence 路径可能因新 type 引入额外的方向约束而出现误报。迁移窗口里,validate.py --strict 会短暂报出大量警告;正确做法是先用宽模式 validate 确认 schema 语义自洽,再批量修复警告,最后切回严格模式。Phase 2 全程未触发这个角——schema v0.1 的 11 relation 覆盖了所有 domain 需求,说明 8-type / 11-relation 的设计点选得足够保守。

C2 — 大批 wiki 页重构后的 ghost 雪崩 当 100+ wiki 页同批次重命名(如 campaign 批量改 slug 格式),每个 object 的 evidence 路径都可能同步失效,validate.py --strict 会抛出大量 ghost error。此时不能逐一修 YAML,正确做法是写一个批量替换脚本,对所有 YAML 文件做路径字符串替换,再跑 validate.py --strict 确认 0 error,最后重跑 inject_wiki_links.py 刷新反向链。Phase 2 Batch 3-4 加 standards 时做过一次此类批量 evidence 更新,脚本耗时不到 5 秒,无需人工逐一检查。

C3 — D3 图谱前端性能极限 175 节点 + 330 边的力导向模拟在低端 Android 手机上帧率约 12-15 fps,明显卡顿。Phase 3 的应对是类型 chip 过滤:初始只渲染当前选中 type 的节点,其余隐藏;用户点击 chip 时增量显示对应子图。但若对象数超过 500,即使用 chip 过滤,单个 type 的子图(如 failure_mode 28 个)仍会触发全量重算。此时应考虑切换到 WebGL 渲染或服务端预计算 layout 坐标,避免每次挂载组件都重跑 kamada-kawai。当前 Phase 3 上线的 175 节点方案在桌面 Chrome 流畅,移动端 200 节点以内可接受。

对象层的关键量化指标如下。