供应链本地知识库与 Pi Agent

一个本地优先、可审核、可追溯的供应链知识库原型。它把公司制度、框架协议、SOP、业务链路图和手写笔记处理成可检索知识，并通过 Pi 工具返回文件名、页码和原文证据。

真实资料始终放在仓库外；本仓库只包含程序、模板和脱敏演示数据。

已实现

• kb init：创建 inbox/originals/derived/review/approved/reports 私有目录和模板；

• kb inventory：SHA-256 文件盘点、PDF页数、PPTX幻灯片数、重复文件报告；

• kb ingest：PDF逐页抽取与渲染、PPTX可见/隐藏页映射、DOCX真实页码、扫描页/图片视觉转录、XLSX/CSV/Markdown处理；

• kb structure apply/status/finalize：导入 Codex 离线结构草稿，强制验证源哈希、真实页/幻灯片/工作表范围、逐字引文和流程边；

• OpenAI兼容模型：文档分类、SOP步骤、协议条款、流程节点、候选联系人和缺失字段抽取；

• 风险分级审核：制度与协议默认高风险，审核状态同步到所有知识片段；

• kb index/search/ask/get/status：中文语义检索、精确匹配、LLM重排和带页码问答；

• Pi 工具：知识检索、SAP/CRM 内部故障诊断、SAP/Microsoft 官方文档兜底、MMSI 船舶动态和工作交接闭环；

• Pi 工作交接闭环：已审核证据收集、知识缺口识别、事项级来源、候选联系人隔离、JSON/Markdown 双格式草稿及人工批准快照；

• Obsidian-first Vault：把结构化知识、逐页来源、原始附件、流程 Mermaid 和交接记录迁移到人工可读 Vault，SQLite 保留为派生检索索引；

• 相同内容幂等跳过，同一路径发生变化时保留历史版本。

来源定位按格式保存：PDF/DOCX/图片使用页码，PPTX 使用原始幻灯片号并标记隐藏页，XLSX 使用工作表和单元格范围。确定性原文与视觉转录分别保存，视觉结果不会覆盖原文。

Related MCP server: Knowledge Base MCP Server (Qdrant)

环境要求

• Node.js 22.19 或更高版本；

• Poppler：提供 pdfinfo、pdftotext、pdftoppm；

• LibreOffice：用于 DOCX/PPTX 的逐页渲染和引用映射；

• 公司批准的 OpenAI 兼容文本、视觉及 Embedding 模型。

macOS：

brew install poppler
brew install --cask libreoffice
npm install
npm run build

快速开始

cp .env.example .env

填写 .env：

KB_DATA_DIR=/绝对路径/supply-chain-private-kb
KB_OBSIDIAN_VAULT=/绝对路径/supply-chain-private-kb/obsidian-vault
LLM_BASE_URL=https://approved-endpoint.example/v1
LLM_API_KEY=...
LLM_TEXT_MODEL=...
LLM_VISION_MODEL=...
EMBEDDING_MODEL=...

初始化并导入首批资料：

npm run dev -- init
# 将20到30份代表性资料复制到 $KB_DATA_DIR/inbox
npm run dev -- inventory
npm run dev -- ingest --limit 30
# 只重试失败文件，或重新处理指定文件
npm run dev -- ingest --file "文件名关键字" --retry-failed
npm run dev -- ingest --file "文件名关键字" --reprocess
npm run dev -- structure apply /绝对路径/结构草稿.json
npm run dev -- structure status
npm run dev -- structure finalize
npm run dev -- review list
npm run dev -- review approve <document-id> --note "已核对原文和版本"
npm run dev -- index
npm run dev -- ask "海运订舱需要核对哪些信息？"
npm run dev -- troubleshoot "CRM+" "有车号但没有发票" --stage "香港月结"
npm run dev -- eval troubleshoot
npm run dev -- vessel watch add 477123456 --label "示例船"
npm run dev -- vessel ports import ~/Downloads/UpdatedPub150.csv
npm run dev -- vessel ports status
npm run dev -- vessel watch run
npm run dev -- vessel lookup 477123456
npm run dev -- handoff prepare "香港月结交接" -q "SAP 月结" -q "报关异常"
npm run dev -- handoff create ./templates/handoff-input.json
npm run dev -- handoff list
npm run dev -- handoff approve <handoff-id> --note "接收人已确认"
npm run dev -- obsidian export
npm run dev -- obsidian check
npm run dev -- obsidian sync prepare
npm run dev -- obsidian sync list
npm run dev -- obsidian sync approve <review-id> --note "已核对修改和来源"
npm run dev -- obsidian rebuild

垂类 Agent 与 MCP

构建后可用 supply-chain-mcp 启动只读 MCP Server，向 Pi MCP Adapter、Gemini CLI 或其他 MCP 客户端提供：

• kb_search、kb_get、kb_status：带审核状态和真实来源定位的知识查询；

• system_troubleshoot：按系统、模块、事务码/页面、错误代码和现象检索 SAP/CRM/OA 故障证据；

• vendor_support_search：仅在内部证据不足后，实时检索 SAP Help Portal 或 Microsoft Learn 的公开官方文档候选；

• vessel_lookup：按9位 MMSI 查询 AIS 位置、航行状态和近期到离港事件。

SAP/CRM 故障接口只复述与当前症状匹配的原始页证据；存在 Obsidian 汇总笔记时优先引用 90-来源文档 的精确页。没有足够依据时返回 insufficient_evidence 和需要补充的信息，不会用普通系统流程冒充故障解法。明确为 SAP 或 Microsoft Dynamics 365/Dataverse 时，Agent 才可继续调用 vendor_support_search；厂商结果始终单列，保留官方 URL、产品/版本不确定性，绝不冒充企业内部处理路径。泛称 CRM、CRM+ 或自研系统不会自动映射到 Microsoft。所有故障工具都不会执行过账、冲销、重推、开票、权限或主数据修改。船舶动态采用 AISStream 全球免费采集、Digitraffic 芬兰水域免费即时查询与 VesselFinder 全球付费补查的混合方案，详见 船舶动态数据方案。

故障能力必须用真实问题持续验收。新增已解决故障时使用 templates/system-fault-case.md 记录现象、根因、处理步骤、验证和风险，经人工审核后再进入检索。将验收格式参考 templates/troubleshooting-gold.json，真实问题放入私有 reports/system-troubleshooting-gold.json；kb eval troubleshoot 会同时验证有答案案例的来源与关键要素，以及无依据案例是否正确拒答。

npm run build
node --env-file=.env dist/src/mcp-server.js

未配置模型时，文本型文件仍可解析并进入 needs_llm 状态，kb index 会使用 lexical-only 模式；扫描件不会被猜测，必须配置视觉模型后重新处理。带 E-SafeNet LOCK 等企业加密容器的文件需先在授权客户端解密导出。

也可以在一次受控的 Codex 任务中生成 processor=codex_bootstrap 离线结构包。导入器会用现有 Zod Schema 校验，并拒绝哈希不符、来源位置不存在、引文无法逐字命中、步骤编号不连续或流程边引用不存在节点的包。通过校验的结果仍为 draft，不会自动批准；Embedding 未配置时仍明确报告 lexical-only。

审核规则

• company_policy、framework_agreement：只有 approved 内容可进入最终回答；

• SOP、流程图、手写SOP：草稿可以被检索，但回答必须显示“未审核”；

• 候选联系人永远不是权威联系人，需在 $KB_DATA_DIR/approved/contacts.csv 中人工确认；

• LLM生成的摘要和结构不会覆盖页级原文；引用页码由解析程序固定；

• 协议问答只做条款检索，不构成法律意见。

Pi 安装

本仓库符合 Pi Package 目录约定。开发阶段可直接加载：

npm install
npm run agent

等价的直接命令是 pi -e ./extensions/supply-chain-kb.ts --skill ./skills。

也可以将发布后的仓库安装为包。Pi 启动后会发现知识问答与交接 Skills，并注册知识检索、故障诊断、厂商文档查询、船舶动态和交接工具。

交互模式下可直接使用：

/handoff 香港月结工作
/handoffs
/kb-status
/handoff-approve <handoff-id>

/handoff 会让 Agent 先检查知识库、检索已审核依据并补齐真正缺失的事实，然后展示完整交接内容。只有用户明确确认后，Agent 才能调用 create_handoff。草稿写入 $KB_DATA_DIR/review/handoffs；/handoff-approve 会再次要求人工确认，并将批准快照复制到 $KB_DATA_DIR/approved/handoffs。

交接中的每个事项都可以附 sourceChunkIds。有来源的内容标记为 [S#]，没有来源的当前工作事实会明确显示“当前会话提供，未由知识库验证”。声称已确认的联系人必须存在于 $KB_DATA_DIR/approved/contacts.csv，否则保存会被拒绝。

数据目录

$KB_DATA_DIR/
├── inbox/       # 用户复制进来的待处理文件
├── originals/   # 按内容哈希保存的只读工作副本
├── derived/     # PDF页面图、OCR和派生结果
├── review/      # LLM结构化结果和交接草稿
├── approved/    # 人工批准快照和联系人目录
├── reports/     # 文件盘点与黄金问题集
├── obsidian-vault/ # Obsidian 人工知识库（默认位置）
└── knowledge.sqlite

Obsidian 工作方式

运行 kb obsidian export 后，在 Obsidian 中选择“打开本地仓库”，指向 $KB_OBSIDIAN_VAULT。每份资料会生成一份结构化知识页和一份逐页来源页，原始文件复制到 Attachments/Originals。流程图会生成 Mermaid，制度和合同保留结构化条款与逐字引用。

Vault、原始附件和清单都属于私有数据，已经排除在 Git 之外。obsidian export 会记录受管笔记的内容哈希；再次导出时，已经人工编辑的笔记会被保留并报告冲突，不会静默覆盖。

日常维护流程是：在 Obsidian 编辑 → obsidian sync prepare 生成逐项差异审核 → obsidian sync approve 或 reject → obsidian rebuild 重建检索缓存。未经批准的修改会以 draft 进入检索，高风险制度和合同不能据此给出已确认结论。obsidian rebuild 只重建可删除的 obsidian_note_chunks 搜索缓存，不会反向猜测或改写原始页、证据引用、合同条款及流程节点/边。SQLite 仍是后台索引与审计数据库，Obsidian 才是日常人工维护入口。

关于 Gemini CLI、Pi MCP Adapter 和 Claudian 的接入判断见 工具集成评估。

建议先用 reports/gold-questions.yaml 记录30到50个真实问题。验收目标是正确来源进入前5条的比例不低于90%，所有实质性答案均带文件名和页码。

开发验证

npm run check
npm test
npm run build

测试覆盖重复检测、PDF逐页渲染与引用、幂等导入、版本保留、人工审核传播、高风险草稿隔离、损坏PDF错误记录、离线结构引用校验、Obsidian 编辑保护与批准同步、交接来源校验、联系人确认和交接批准快照。

开源边界

不要提交 .env、真实公司资料、联系人、SQLite数据库、页面渲染结果或审核产物。knowledge-demo/ 中的内容完全是脱敏演示数据。