Engineering Copilot — wiki 之上的对象 / 关系层
本质与导读
本质:LLM Wiki v1 是 docs-centric — markdown 描述工程知识,AI 搜索 + 索引在 docs 上。Engineering Copilot v2.0 在 wiki 之上引入第二种真理形态:typed object + typed relation。同一份知识,wiki 给人读散文,object 图给机器查关系。Wiki 没动,但新增了可机器查询的结构化阴影层。设计灵感来自 topic-accellera-fs-data-model,但更小、更内敛、只覆盖 spec 圈定的 Phase 1 范围(gate driver + DESAT + SC + functional safety)。
主线坐标:元 · wiki 工具层 · ↑ 全景主线
1. 为什么再加一层
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 是机器查真相。
2. 两层职责对比
两层是并行存在而非替换 — wiki 优化人读节奏(故事 / 推理 / trade-off),knowledge 优化机器查询(关系 / 一致性 / 图谱)。同一份知识两边各写一遍 ≠ 重复,因为优化目标不同:
| 维度 | wiki(v1) | knowledge(v2) |
|---|---|---|
| 形态 | markdown + frontmatter | YAML object,8 type |
| 优化目标 | 人读 / AI 综合答案 | 机器查 / 关系图 / 一致性 |
| 关系 | 散文叙述 + cross-references list | 11 种 typed relation,带方向 + 反向自动 |
| 单元 | 主题页(覆盖 1 个域) | 对象(覆盖 1 个 fact) |
| 更新频率 | 几天 / 一次大改 | 增量,新事实就加新 object |
| 容量 | 234 页 | 175 object(Phase 2 收官 ✅) |
| 验证 | lint(style)+ 人工读 | schema validator(类型 + 关系方向自动校) |
关键:两层互引用——wiki 页 evidence 字段引用 wiki 路径,wiki 页底自动注入"## Engineering Objects"区列出引用它的 object。改了 wiki,跑一次 inject_wiki_links 即同步。
3. 8 类 Object Type
按 spec 锁定,不准自创:
| Type | 含义 | 例 |
|---|---|---|
component | 物理元件 / IC | component_iso5852s_gate_driver |
mechanism | 安全机制(detect + react 一体) | mechanism_desat |
diagnostic | 纯检测 | diagnostic_vce_monitoring |
mitigation | 纯反应 | mitigation_asc_hss |
failure_mode | 失效模式 | failure_mode_sc_type_1 |
standard | 标准条款 | standard_iso26262_part5 |
metric | 量化指标 | metric_spfm(待写) |
case | 应用案例 / SG / HARA 节选 | case_sg2_reverse_torque_asil_d |
id 命名规则:{type}_{name},全小写 + 下划线,id 前缀必匹配 type。validator 自动校。
4. 11 种 Relation
forward 11 种 + 自动派生 11 种 inverse,总共 22 个语义方向:
| Forward | 反向 | 语义 |
|---|---|---|
detects | detected_by | mechanism / diagnostic 检测 failure_mode |
causes | caused_by | failure_mode 引起 failure_mode |
mitigates | mitigated_by | mechanism / mitigation 减轻 failure_mode |
depends_on | depended_by | source 依赖 target 工作 |
sensitive_to | affects | target 影响 source 可靠性 |
monitors | monitored_by | 周期观测 |
violates | violated_by | failure_mode 违反 case / standard |
requires | required_by | case / standard 要求满足 |
verified_by | verifies | 被 X 验证 |
implemented_by | implements | mechanism / mitigation 在 component 上实现 |
derived_from | derives | case 从 standard 推导 |
schema 自动校方向:写错(如 component implemented_by mechanism)立刻报警。
5. 怎么用
5.1 命令行查询
scripts/copilot/query.py 提供 6 个子命令,覆盖最常用的图谱探索动作:
# 全局统计
python3 scripts/copilot/query.py stats
# 看某 object 完整内容 + 1-hop 关系
python3 scripts/copilot/query.py show mechanism_desat
# 反向查:什么 detect SC type 1?
python3 scripts/copilot/query.py what detects failure_mode_sc_type_1
# 所有 1-hop 关系
python3 scripts/copilot/query.py related case_sg2_reverse_torque_asil_d
# 列出某 type 全部对象
python3 scripts/copilot/query.py list mitigation
# 检查 ghost(被引用但没写)
python3 scripts/copilot/query.py ghost
5.2 AI 搜索自动注入
/api/ask worker 端命中 query 关键词 → top-5 相关 object 自动 prepend 到 LLM context,answer 里就会出现 "DESAT(mechanism_desat)..." 这种事实锚。用户感觉不到,但答案更结构化。
5.3 graph 可视化
3 种产物:
/graph前端力导向交互图 (2026-05-17 加)— Phase 3 上线,D3 + React 实现,8 类型上色 / 类型 chip 过滤 / 点击高亮 1-hop 邻居 / 双击跳 AI 搜索。175 节点 + 330 边在浏览器实时模拟。graph/relations.pngPNG 静态可视化,适合 README / wiki 嵌入graph/objects.jsonD3.js 兼容 JSON,前端 + 外部工具消费
python3 scripts/copilot/build_graph.py # 默认 kamada-kawai
python3 scripts/copilot/build_graph.py --layout shell # 同心圆按 type 分层
5.4 schema 校验
validator 校 id 格式 / type 合法 / relation 方向 / evidence 路径,同时检测 ghost 引用:
python3 scripts/copilot/validate.py # 校全部,只警告 ghost
python3 scripts/copilot/validate.py --strict # 警告也当错误
写新 object 必跑 validator,确保 id / type / relation 方向都对。
5.5 同步 wiki ↔ knowledge
evidence 字段是 object → wiki 的单向引用,反向链由这条脚本注入到 wiki 页底 ## Engineering Objects:
python3 scripts/copilot/inject_wiki_links.py # 给被引用的 wiki 页注入"## Engineering Objects"
幂等。新增 object 后必跑,否则 wiki 看不到反向链。
6. 何时该加 object,何时不该
加 object 的标准:这件事会被多次引用,且有结构化属性。
| 该加 object | 不必加 object |
|---|---|
| DESAT 机制 — 多个 SC 类引用 | 某次实测 VDS = 9.2V 的数据点 — 一次性事实 |
| ISO 26262 Part 5 — 多个 SG 引用 | "用 1200V IGBT 留 33% 余量" 的设计经验 — prose 即可 |
| SG2 反向扭矩 — 多种 mitigation 关联 | 某 OEM 的 SG 命名 |
原则:object 是真理的骨架,不是 prose 的替代。所有细节、推理、tradeoff 仍在 wiki。
7. Phase 1 现状(v2.0,2026-05-16)
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 页底反向链注入
8. Phase 2 收官(v2.0,2026-05-17 — Batch 1-19 完成,Phase 2 ✅ CLOSED)
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
9. Phase 3 ✅ CLOSED(查询能力,2026-05-17)
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。 - ✅
/graphD3 前端力导向图谱:Next.js 客户端组件 + D3 v7,175 节点 + 330 边实时模拟。功能:8 类型上色 / 类型 chip 过滤 / 点击高亮 1-hop 邻居 / 双击跳 AI 搜索 / 缩放拖拽 / 节点大小按度数。Bundle +22 KB JS,build pipelinecopy-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 更厚
核心要点
- v2.0 在 wiki 之上加结构化对象层,不动 wiki。
- 8 type / 11 relation 锁住 spec,validator 自动校方向。
- 4 个工具:validate / build_graph / query / inject_wiki_links。
- AI 搜索自动 prepend top-5 对象到 LLM context。
- wiki 页底自动注入"## Engineering Objects"反向链。
- Phase 2 ✅ CLOSED = 175 对象 + 330 relations + 0 ghost + schema 0 warnings + 108 wiki 反向链(2026-05-17)。
- 何时加 object:多次引用 + 有结构化属性。一次性事实不加。
Cross-references
- ← 索引
- topic-accellera-fs-data-model — 设计灵感来源
- topic-functional-safety — Phase 1 主战场
- topic-fmea — Phase 2 候选目标域