KnowPilot — 分析化学行业知识图库

将专业技术文档（技术手册、备件手册、故障诊断手册、用户手册等）转化为结构化、可查询、可展示的知识图库。面向分析化学行业，遵循专业词汇与专有名词规范。

五层架构

┌───────────────────────────────┐
│  L5  ima.copilot 交互层       │  ← 只读问答、备件图展示、笔记同步
│      (知识库 + 笔记)           │
├───────────────────────────────┤
│  L4  Karpathy LLM Wiki 百科   │  ← 结构化百科页面，跨引用，矛盾标记
│      (wiki/*.md)              │
├───────────────────────────────┤
│  L3  Graphify 知识图谱        │  ← 实体 & 关系抽取，Leiden 聚类，查询
│      (graphify-out/graph.json)│
├───────────────────────────────┤
│  L2  统一文档格式 (Markdown)   │  ← MarkItDown 转换产物
│      (converted/*.md)         │
├───────────────────────────────┤
│  L1  原始手册 (只读)          │  ← 哈希锁定，绝不修改
│      (sources/)              │
└───────────────────────────────┘

分层原则

L1 只读：原始文件存入 sources/，立即计算 SHA-256 写入 sources/manifest.jsonl。任何层不得修改原始文件。
L2 衍生：由 markitdown 从 L1 自动生成，可随时从 L1 重新生成。
L3 抽取：由 graphify 从 L2 构建图谱，包含实体（设备、备件、故障、操作步骤）及其关系。
L4 编译：由 Agent 基于 L2+L3 编写和交叉引用百科页面，遵循 Karpathy LLM Wiki 规范。
L5 展示：从 L4 选取内容同步到 ima.copilot 知识库和笔记，供用户交互查询。

目录结构

KnowPilot-data/                 ← 数据根目录（默认 ~/KnowPilot-data）
├── sources/                    ← L1: 原始手册（只读）
│   ├── manifest.jsonl          ← 文件清单 & SHA-256 哈希
│   ├── technical/              ← 技术手册
│   ├── spare-parts/            ← 备件手册
│   │   └── images/             ← ⚠️ 备件图片（按备件号命名）
│   ├── troubleshooting/         ← 故障诊断手册
│   └── user-guides/            ← 用户手册
├── converted/                  ← L2: MarkItDown 转换后的 Markdown
│   └── <source-sha>/.md       ← 按源文件哈希分目录
├── graphify-out/               ← L3: Graphify 知识图谱输出
│   ├── graph.json              ← 持久化可查询图谱
│   ├── graph.html              ← 交互式可视化
│   └── GRAPH_REPORT.md         ← 图谱审计报告
├── wiki/                       ← L4: Karpathy LLM Wiki 百科
│   ├── index.md                ← 百科总索引
│   ├── log.md                  ← 操作日志
│   ├── entities/               ← 实体页面
│   │   ├── equipment/          ← 设备实体
│   │   ├── spare-parts/        ← 备件实体
│   │   ├── faults/             ← 故障实体
│   │   └── procedures/         ← 操作步骤实体
│   ├── concepts/               ← 概念页面
│   └── mappings/               ← 映射页面
│       ├── en-zh-glossary.md   ← 英中专业词汇对照表
│       └── part-image-map.md   ← 备件号-图片对照表
└── config.yaml                 ← KnowPilot 配置

知识约束与出处规范

⚠️ 核心原则 — 必须遵守，不可违反

1. 知识来源限制

仅使用知识图库：所有回答必须完全基于已摄入的 L1-L4 层数据（sources/、converted/、graphify-out/、wiki/）
禁止杜撰：不得编造、推测或生成知识图库中不存在的信息
禁止幻觉：当知识图库中没有相关信息时，必须明确告知用户"知识库中未找到相关信息"，而非猜测答案

2. 出处标注规范

所有输出的信息必须标注出处，格式如下：

标注格式：

## 回答内容

[实体/备件/故障信息]

**出处**：
- 源文件：[文件名](../../sources/类别/文件名.pdf) — 页码/位置
- 知识图谱：graphify-out/graph.json — 实体 ID
- 百科页面：[[wiki/entities/类别/页面名.md]]

示例：

Agilent 7890B GC 的进样口密封垫备件号是 **12345-67890**。

**出处**：
- 源文件：[agilent-7890b-spare-parts.pdf](../../sources/spare-parts/agilent-7890b-spare-parts.pdf) — 第 23 页
- 知识图谱：graphify-out/graph.json — entity_id: pn-12345-67890
- 百科页面：[[wiki/entities/spare-parts/pn-12345-67890.md]]

3. 网络资源查询限制

默认禁止：不得随意查询网络资源（WebSearch、WebFetch 等）
例外情况：仅当用户明确要求搜索网络时才可查询，且：
必须先声明"将查询网络资源"
查询后必须将结果存入知识图库（L1→L2→L3→L4），避免重复查询
网络资源仅作为补充，不能替代知识图库

4. 查询工作流约束

执行 query 工作流时，必须遵循以下步骤：

检查知识库：首先查询 wiki/index.md 和 graphify-out/graph.json
判断是否可答：

有相关信息 → 标注出处后回答
无相关信息 → 明确告知用户，并询问是否：

a. 导入相关手册到知识库

b. 允许查询网络资源（仅此次）

禁止补偿性回答：不得因为"想帮助用户"而编造答案

5. 违规处理

如违反上述规则（杜撰、无出处、随意查询网络），必须：

立即停止当前回答
声明"刚才的回答可能包含不准确信息"
重新基于知识图库回答，或明确告知无法回答

核心工作流

1. ingest — 文档摄入

⚠️ 关键：备件图片必须与备件号、备件名称对应

将技术文档导入系统，自动完成 L1→L2 转换，并提取图片。

触发：用户说"导入手册"、"添加文档"、"ingest"等。

步骤：

接收源文件：用户指定文件路径或 URL
分类存放：按文档类型存入 sources/ 对应子目录

备件手册 → sources/spare-parts/
技术手册 → sources/technical/
故障诊断手册 → sources/troubleshooting/
用户手册 → sources/user-guides/

哈希锁定：计算 SHA-256，追加到 sources/manifest.jsonl
格式转换：运行 MarkItDown 将文档转为 Markdown，存入 converted//

MarkItDown 会自动提取图片到 converted//_files/ 目录

图片提取与重命名（⚠️ 关键步骤）：

解析转换后的 Markdown 文件，识别图片引用
使用 AI 分析图片上下文（周围的文本、表格、标题）
将图片重命名为 <备件号>.（如 12345-67890.png）
将重命名后的图片保存到 sources/spare-parts/images/ 目录
更新 Markdown 文件中的图片引用路径

注册到 Wiki：在 wiki/log.md 记录摄入操作，包含：

源文件路径
提取的备件号列表
对应的图片文件路径列表

命令：

# MarkItDown 转换（自动提取图片）
markitdown "<source-file>" -o "converted/<sha>/<filename>.md"

# 图片提取与重命名（关键步骤）
python3 scripts/extract-part-images.py \
  --input "converted/<sha>/<filename>.md" \
  --output "sources/spare-parts/images/" \
  --manifest "sources/manifest.jsonl"

# 哈希计算与注册
python3 scripts/ingest.py --source "<file>" --type spare-parts

图片命名规范：

格式：<备件号>.<扩展名>
示例：12345-67890.png、5182-0835.jpg
存储位置：sources/spare-parts/images/

验证步骤：

摄入完成后，检查 sources/spare-parts/images/ 目录
确保每个备件号都有对应的图片文件
确保 wiki/mappings/part-image-map.md 已更新（或在 build-wiki 阶段更新）

2. build-graph — 构建知识图谱

⚠️ 关键：必须抽取备件号与备件图片的对应关系

从 L2 的 Markdown 文件构建 L3 知识图谱。

触发：用户说"构建图谱"、"build graph"、"解析文档"等。通常在 ingest 之后自动执行。

步骤：

运行 Graphify：对 converted/ 目录执行图谱构建
领域微调：对分析化学行业实体进行二次抽取

设备实体（GC、HPLC、FTIR、ICP-MS 等）
备件实体（备件号、备件名称、规格、适用设备）
故障实体（故障代码、现象、原因、解决方案）
操作步骤实体（步骤编号、描述、注意事项）

关系抽取：建立实体间关系

备件 → 适用于 → 设备
故障 → 涉及 → 备件
故障 → 解决方案 → 操作步骤
备件英文名 → 对应 → 备件中文名
备件号 → 对应 → 备件图片（⚠️ 关键关系）

图片关系验证（⚠️ 新增验证步骤）：

检查每个备件实体是否有对应的图片关系
验证图片文件是否存在于 sources/spare-parts/images/ 目录
如无对应关系，标记为"缺失图片"并记录到 GRAPH_REPORT.md

生成报告：Graphify 输出 GRAPH_REPORT.md，包含：

实体统计
关系统计
图片映射完整性报告（新增）

命令：

# Graphify 构建
graphify ./converted --output ./graphify-out

# 领域实体二次抽取（包含图片关系）
python3 scripts/extract-entities.py \
  --input converted/ \
  --output graphify-out/entities.json \
  --extract-images  # ⚠️ 关键参数：抽取图片关系

# 验证图片映射
python3 scripts/verify-image-mappings.py \
  --graph graphify-out/graph.json \
  --images-dir sources/spare-parts/images/

图片关系抽取逻辑：

从 Markdown 文件中提取图片引用（!...）
分析图片周围的文本，识别备件号
建立 备件号 → 对应 → 备件图片 关系
将关系存储到 graphify-out/graph.json

3. build-wiki — 编译百科页面

⚠️ 关键：必须生成正确的备件号-图片对照表

基于 L2+L3 的内容，编写和更新 L4 百科页面。

触发：用户说"编译百科"、"build wiki"、"生成百科"等。通常在 build-graph 之后自动执行。

步骤：

读取图谱：加载 graphify-out/graph.json 中的实体和关系
创建/更新实体页面：为每个实体类型编写百科页面

备件实体页面必须包含"备件图片"章节（见下方格式）

建立交叉引用：使用 [[wiki-link]] 格式连接相关页面
标记矛盾：如发现不一致信息，用 > ⚠️ Contradiction with [[source]] 标记
更新索引：刷新 wiki/index.md
生成映射页面（⚠️ 关键步骤）：

mappings/en-zh-glossary.md：英中专业词汇对照
mappings/part-image-map.md：备件号-图片对照（必须基于图谱关系自动生成）

验证映射表（⚠️ 新增验证步骤）：

检查 part-image-map.md 是否包含所有备件实体
检查每个备件号是否有对应的图片路径
检查图片文件是否存在于 sources/spare-parts/images/ 目录
如有缺失，记录到 wiki/log.md

实体页面格式（备件）：

# 备件: P/N 12345-67890

> 进样口密封垫（Injection Port Septum），适用于 Agilent 7890B GC

## 基本信息
- **备件号**: 12345-67890
- **英文名称**: Injection Port Septum
- **中文名称**: 进样口密封垫
- **规格**: 11mm, PTFE-coated
- **适用设备**: [[agilent-7890b-gc]], [[agilent-7890a-gc]]

## 备件图片
⚠️ **图片必须与备件号对应**
![P/N 12345-67890](../sources/spare-parts/images/12345-67890.png)

## 安装说明
1. 关闭进样口加热（→ [[gc-inlet-shutdown-procedure]]）
2. 冷却至室温
3. 拧开进样口螺母，更换密封垫

## 替代备件
- [[pn-5182-0835]]（替代型号，兼容）

## 相关故障
- [[fault-inlet-leak]] — 进样口泄漏（→ [[troubleshooting-inlet-leak]]）

## Sources
- [Agilent 7890B 备件手册](../../sources/spare-parts/agilent-7890b-spare-parts.pdf) — 第 23 页

映射页面格式（⚠️ 必须自动生成，不得手动编写）：

# 备件号-图片对照表

> 备件号与对应图片的映射关系（自动生成，基于知识图谱）

| 备件号 | 英文名称 | 中文名称 | 图片路径 | 验证状态 |
|--------|----------|----------|----------|----------|
| 12345-67890 | Injection Port Septum | 进样口密封垫 | sources/spare-parts/images/12345-67890.png | ✅ 已验证 |
| 5182-0835 | Splitter Liner | 分流衬管 | sources/spare-parts/images/5182-0835.png | ✅ 已验证 |
| 56789-01234 | Column Nut | 色谱柱螺母 | sources/spare-parts/images/56789-01234.png | ⚠️ 图片缺失 |

自动生成逻辑：

从 graphify-out/graph.json 中提取所有 备件号 → 对应 → 备件图片 关系
对于每个备件实体，获取：

备件号（实体 ID）
英文名称（实体属性）
中文名称（实体属性或通过 备件英文名 → 对应 → 备件中文名 关系）
图片路径（关系指向的图片文件）

验证图片文件是否存在
生成 Markdown 表格，包含验证状态

生成命令：

python3 scripts/generate-part-image-map.py \
  --graph graphify-out/graph.json \
  --output wiki/mappings/part-image-map.md \
  --images-dir sources/spare-parts/images/

4. query — 知识查询

⚠️ 必须遵守"知识约束与出处规范"

从知识图库中查询信息。禁止杜撰，必须标注出处，不得随意查询网络。

触发：用户问关于设备、备件、故障、操作步骤等问题。

步骤：

检查知识库：

读取 wiki/index.md 定位相关页面
查询 graphify-out/graph.json 获取实体关系
检查 wiki/mappings/ 中的映射表（英中对照、备件号-图片）

判断是否可答：

✅ 有相关信息 → 标注完整出处后回答
❌ 无相关信息 → 立即停止，明确告知用户"知识库中未找到相关信息"

综合回答（仅当有相关信息时）：

基于百科页面和图谱关系
必须标注出处（格式见"知识约束与出处规范"）：
源文件 + 页码/位置
知识图谱实体 ID
百科页面 [[wiki-link]]
涉及备件时，展示备件图片（来自 sources/ 或 wiki/mappings/part-image-map.md）

禁止行为（违反将导致错误回答）：

❌ 不得编造、推测或生成知识图库中不存在的信息
❌ 不得使用 WebSearch/WebFetch 查询网络资源（除非用户明确要求且你已事先声明）
❌ 不得基于"常识"或"一般经验"回答
❌ 不得因为"想帮助用户"而给出未经验证的答案

记录查询：追加到 wiki/log.md，包含：

查询时间
查询内容
是否找到答案（是/否）
出处列表（如果找到）

正确回答示例：

"7890B GC 的进样口密封垫备件号是 **12345-67890**。

**出处**：
- 源文件：[agilent-7890b-spare-parts.pdf](sources/spare-parts/agilent-7890b-spare-parts.pdf) — 第 23 页
- 知识图谱：graphify-out/graph.json — entity_id: pn-12345-67890
- 百科页面：[[wiki/entities/spare-parts/pn-12345-67890.md]]

备件图片：![P/N 12345-67890](sources/spare-parts/images/12345-67890.png)

错误回答示例（禁止）：

"7890B GC 的进样口密封垫备件号通常是 5182-0835 或类似型号..."
（杜撰，无出处，未确认知识库中是否存在）

无相关信息时的正确回答：

"知识库中未找到关于『7890B GC 进样口密封垫备件号』的信息。

**建议**：
1. 您可以导入 Agilent 7890B 备件手册到知识库（使用 `ingest` 工作流）
2. 或者明确允许我查询网络资源（仅此次）"

5. sync-ima — 同步到 ima.copilot

将 L4 百科内容同步到 ima.copilot，供用户在知识库和笔记中交互。

触发：用户说"同步到ima"、"发布到知识库"、"sync"等。

步骤：

选择同步内容：从 L4 选取需要同步的百科页面
上传到知识库：将原始手册文件上传到 ima 知识库（文件保持原样，不走 MarkItDown）
同步笔记：将百科页面和映射表写入 ima 笔记
确认完成：报告同步结果

ima 同步规则：

原始手册文件 → 上传到 ima 知识库（二进制上传，保持原格式）
百科页面 → 写入 ima 笔记（Markdown 格式，content_format: 1）
映射表（英中对照、备件号-图片）→ 写入 ima 笔记
笔记写入前必须执行 UTF-8 编码校验（见 ima-skill 规范）

命令：

# 同步百科到 ima 笔记
python3 scripts/sync-ima.py --scope wiki --target notes

# 上传原始手册到 ima 知识库
python3 scripts/sync-ima.py --scope sources --target knowledge-base --kb-name "KnowPilot"

6. lint — 健康检查

⚠️ 关键：必须检查备件图片映射完整性

检查知识图库的完整性和一致性。

触发：用户说"健康检查"、"lint"、"检查知识库"等。

检查项：

矛盾检测：不同来源的信息冲突
孤立页面：没有被其他页面引用的百科页面
缺失页面：被引用但未创建的页面
缺失交叉引用：应关联但未关联的页面
索引完整性：index.md 是否覆盖所有页面
映射完整性（⚠️ 关键检查项）：
wiki/mappings/part-image-map.md 是否包含所有备件实体
每个备件号是否有对应的图片路径
图片文件是否存在于 sources/spare-parts/images/ 目录
图片文件名是否与备件号对应（如 12345-67890.png）
原始文件完整性：manifest.jsonl 中的哈希是否与实际文件匹配

新增检查步骤（⚠️ 关键）：

检查 part-image-map.md 存在性：

如果 wiki/mappings/part-image-map.md 不存在 → 报错，建议运行 build-wiki

检查映射表完整性：

从 graphify-out/graph.json 获取所有备件实体
检查每个备件实体是否出现在 part-image-map.md 中
如有缺失，记录到报告

检查图片文件存在性：

遍历 part-image-map.md 中的每一行
检查图片路径是否指向存在的文件
如文件不存在，标记为"图片缺失"

检查图片命名规范性：

检查图片文件名是否为 <备件号>.<扩展名> 格式
如不符合规范，建议重命名

命令：

# 健康检查（包含图片映射检查）
python3 scripts/lint.py --data-root ~/KnowPilot-data --check-images

# 专项检查图片映射
python3 scripts/verify-image-mappings.py \
  --graph graphify-out/graph.json \
  --mapping wiki/mappings/part-image-map.md \
  --images-dir sources/spare-parts/images/

lint 报告格式（新增图片映射检查部分）：

# 知识图库健康检查报告

## 图片映射完整性
- ✅ 备件实体总数：150
- ✅ 有图片映射的备件：145
- ⚠️ 缺失图片映射的备件：5
  - pn-99999-99999
  - pn-88888-88888
  - ...
- ❌ 图片文件缺失：2
  - sources/spare-parts/images/77777-77777.png（文件不存在）
  - ...

## 其他检查项
...

分析化学行业专业词汇规范

遵循以下术语规范，所有百科页面、映射表、查询回答必须使用规范术语：

缩写对照

缩写	英文全称	中文名称
------	----------	----------
GC	Gas Chromatography	气相色谱法
HPLC	High Performance Liquid Chromatography	高效液相色谱法
FTIR	Fourier Transform Infrared Spectroscopy	傅里叶变换红外光谱法
ICP-MS	Inductively Coupled Plasma Mass Spectrometry	电感耦合等离子体质谱法
UV-Vis	Ultraviolet-Visible Spectroscopy	紫外-可见分光光度法
FID	Flame Ionization Detector	氢火焰离子化检测器
ECD	Electron Capture Detector	电子捕获检测器
TCD	Thermal Conductivity Detector	热导检测器
MS	Mass Spectrometry / Mass Spectrometer	质谱法 / 质谱仪
DAD	Diode Array Detector	二极管阵列检测器
RID	Refractive Index Detector	示差折光检测器
ELSD	Evaporative Light Scattering Detector	蒸发光散射检测器

专有名词

品牌名称保持原文：Agilent, Shimadzu, Waters, Thermo Fisher, PerkinElmer
型号名称保持原文：7890B, 1260 Infinity II, Nexera LC-40, Vanquish
备件号保持原文格式：如 5182-0835, 12345-67890
方法名称使用中文+英文注释：如"梯度洗脱法（Gradient Elution）"

详细词汇表见 references/glossary.md。

前置依赖

工具链

KnowPilot 基于以下三大工具构建完整知识图库 pipeline：

工具	用途	安装
------	------	------
MarkItDown	文档转 Markdown	`pip install 'markitdown[all]'`
Graphify	知识图谱构建	`pip install graphifyy && graphify install`
Karpathy LLM Wiki	百科页面维护	参考 `karpathy-llm-wiki` skill

ima.copilot 凭证配置

# 方式 A — 配置文件
mkdir -p ~/.config/ima
echo "your_client_id" > ~/.config/ima/client_id
echo "your_api_key" > ~/.config/ima/api_key

# 方式 B — 环境变量
export IMA_OPENAPI_CLIENTID="your_client_id"
export IMA_OPENAPI_APIKEY="your_api_key"

数据目录初始化

python3 scripts/init.py --data-root ~/KnowPilot-data

配置文件

KnowPilot-data/config.yaml 示例：

# KnowPilot 配置
data_root: ~/KnowPilot-data

# 文档分类
categories:
  - technical        # 技术手册
  - spare-parts      # 备件手册
  - troubleshooting  # 故障诊断手册
  - user-guides      # 用户手册

# 行业词汇
glossary_file: references/glossary.md

# Graphify 配置
graphify:
  output_dir: graphify-out
  languages: [python, markdown]  # Tree-sitter 语言

# ima.copilot 同步
ima:
  default_kb_name: "KnowPilot"
  sync_notes: true
  sync_knowledge_base: true

# 安全
security:
  source_hash_algorithm: sha256
  source_readonly: true
  max_file_size_mb: 200

安全规则

数据保护规则

原始文件不可变：sources/ 目录下的文件只可追加，不可修改或删除。每次摄入都计算哈希并存入 manifest.jsonl。
哈希校验：lint 时自动比对 manifest.jsonl 中的哈希与实际文件，不一致则告警。
ima 上传：上传原始手册到 ima 知识库时，保持文件原格式，不转码。
ima 笔记写入：写入笔记前必须执行 UTF-8 编码校验（PowerShell 5.1 环境需特殊处理，见 ima-skill 规范）。
敏感信息：不在百科页面中存储密钥、令牌等敏感信息。

知识约束规则（⚠️ 强制）

禁止杜撰：不得编造、推测或生成知识图库中不存在的信息。当知识库中没有相关信息时，必须明确告知用户"知识库中未找到相关信息"。
必须标注出处：所有输出的信息必须标注来源（源文件 + 页码/位置、知识图谱实体 ID、百科页面链接）。格式见"知识约束与出处规范"。
限制网络查询：不得随意使用 WebSearch/WebFetch 查询网络资源。仅当用户明确要求时才可查询，且必须事先声明"将查询网络资源"。
禁止幻觉式回答：不得因为"想帮助用户"而给出未经验证的答案。无信息时，拒绝回答比错误回答更好。

违规处理

如违反上述规则（特别是规则 6-9），必须：

立即停止当前回答
声明"刚才的回答可能包含不准确信息"
重新基于知识图库回答，或明确告知无法回答

SkillHub 发布

KnowPilot 可发布到 skillhub.cn（ClawHub）。

> ⚠️ 重要限制：SkillHub 不支持 .pyc 文件。发布前必须删除所有 __pycache__ 目录和 .pyc 文件。

发布前准备

# 1. 删除 __pycache__ 和 .pyc 文件
cd KnowPilot
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -name "*.pyc" -delete

# 2. 确认目录结构（无 __pycache__）
ls -la scripts/
# 应显示：ingest.py, sync-ima.py, extract-entities.py, init.py, lint.py

打包与发布

# 打包（排除 __pycache__ 和 .pyc）
zip -r ../KnowPilot.zip . -x "*.pyc" "__pycache__/*"

# 或使用 Python 打包脚本
python3 scripts/package_skill.py . ./dist

发布命令

npx clawhub publish ./KnowPilot --namespace knowpilot

操作决策表

用户意图	操作	工作流	关键输出
----------	------	--------	----------
导入/添加文档	ingest	接收→分类→哈希→MarkItDown→图片提取与重命名	sources/spare-parts/images/<备件号>.
解析文档、构建图谱	build-graph	Graphify→领域抽取→图片关系抽取→报告	graph.json（含备件号→图片关系）
编译百科	build-wiki	读取图谱→编写页面→交叉引用→更新索引→生成映射表	wiki/mappings/part-image-map.md
查询设备/备件/故障	query	读索引→查图谱→展示图片	答案+出处+备件图片
同步到 ima	sync-ima	选内容→上传知识库/写笔记→确认	ima 知识库+笔记
健康检查	lint	矛盾/孤立/缺失/映射/哈希→图片映射检查	健康检查报告（含图片映射完整性）
全流程（一键）	full-pipeline	ingest→build-graph→build-wiki→sync-ima	完整的知识图库
初始化数据目录	init	创建目录结构+配置文件+初始wiki	KnowPilot-data/ 目录结构
验证图片映射	verify-images	检查 part-image-map.md→验证图片文件→生成报告	图片映射验证报告

常用命令速查

# 初始化
python3 scripts/init.py --data-root ~/KnowPilot-data

# 摄入文档（⚠️ 包含图片提取与重命名）
python3 scripts/ingest.py --source "/path/to/manual.pdf" --type spare-parts
python3 scripts/extract-part-images.py \
  --input "converted/<sha>/<filename>.md" \
  --output "sources/spare-parts/images/" \
  --manifest "sources/manifest.jsonl"

# 构建图谱（⚠️ 包含图片关系抽取）
graphify ./converted --output ./graphify-out
python3 scripts/extract-entities.py \
  --input converted/ \
  --output graphify-out/entities.json \
  --extract-images

# 验证图片映射（⚠️ 新增）
python3 scripts/verify-image-mappings.py \
  --graph graphify-out/graph.json \
  --images-dir sources/spare-parts/images/

# 生成 part-image-map.md（⚠️ 新增）
python3 scripts/generate-part-image-map.py \
  --graph graphify-out/graph.json \
  --output wiki/mappings/part-image-map.md \
  --images-dir sources/spare-parts/images/

# 编译百科（⚠️ 会自动生成 part-image-map.md）
python3 scripts/build-wiki.py --graph graphify-out/graph.json --output wiki/

# 同步到 ima 笔记
python3 scripts/sync-ima.py --scope wiki --target notes

# 上传原始手册到 ima 知识库
python3 scripts/sync-ima.py --scope sources --target knowledge-base --kb-name "KnowPilot"

# 健康检查（⚠️ 包含图片映射检查）
python3 scripts/lint.py --data-root ~/KnowPilot-data --check-images

KnowPliot

概述