采购询比价与注塑件核价 Hermes MCP MVP

本项目把 Telegram/Hermes 的文件与视觉编排，连接到由 Python 强制约束的 BOM 审核、固定 MOCK 行情快照、Decimal 核价、异常检测和 Excel 报告流程。它不做供应商自动定点，不构成价格承诺。

架构与职责

Telegram Gateway 负责收发附件；Hermes Skill 识别采购意图、读取视觉页面和与用户对话；procurement_tools MCP 只暴露 9 个业务级工具；Python 负责 PathGuard、Pydantic、状态机、SQLite、行情口径、Decimal 计算和报告。视觉候选永远不能直接成为正式 BOM。

状态链：created → files_prepared → vision_pending/draft_ready → review_required/ready_for_approval → approved → pricing_running → pricing_completed/failed。每个工具都返回当前状态、允许工具和阻断工具；未 approved 的版本会返回 BOM_NOT_APPROVED。

目录

• config/：提取、材料、核价和异常规则（均带版本；当前企业规则明确为 DEMO CONFIG）。
• fixtures/：固定日期的 Mock 生意社/隆众数据与可重复生成的演示资料。
• src/procurement_pricing/：解析、BOM、行情、核价、报告、SQLite 与安全模块。
• workspace/：上传入口、服务端任务、冻结 BOM 与生成报告。
• tests/、evals/、scripts/：测试、路由/安全/幻觉用例和演示脚本。

安装、测试与 Demo

cd /opt/gissing/procurement-pricing
/home/felix/.local/bin/uv sync
/home/felix/.local/bin/uv run pytest -q
/home/felix/.local/bin/uv run python scripts/create_demo_files.py
/home/felix/.local/bin/uv run python scripts/run_local_demo.py
/home/felix/.local/bin/uv run python scripts/mcp_smoke_test.py
/home/felix/.local/bin/uv run python scripts/run_evals.py

MCP 入口为 python -m procurement_pricing.server，server name 为 procurement-tools。工具：health_check、prepare_rfq_job、submit_bom_candidates、finalize_bom_draft、apply_bom_corrections、approve_bom_draft、run_procurement_comparison、explain_pricing_run、report_suspicious_content。内部解析、行情和计算函数不会暴露给 Hermes。

Hermes 配置与 Skill

实际 Hermes v0.14.0 配置使用 config.yaml 顶层 mcp_servers.procurement_tools 的 stdio command/args/env/tools.include 格式，supports_parallel_tool_calls: false。Skill 安装在 /home/felix/.hermes/skills/procurement/procurement-comparison，用 metadata.hermes.requires_tools 绑定实际 MCP 工具名。新 Session 才能稳定获得新工具/Skill，避免破坏提示缓存。

配置验证：

runuser -u felix -- env HOME=/home/felix PATH=/home/felix/.hermes/hermes-agent/venv/bin:/home/felix/.local/bin:/usr/bin:/bin hermes mcp test procurement_tools

Telegram 测试

Gateway 将图片保存到 $HERMES_HOME/cache/images，PDF/Excel 保存到 $HERMES_HOME/cache/documents，并把图片原生传给支持视觉的主模型；Telegram adapter 实现原生 send_document。PathGuard 仅把这两个 Hermes 缓存目录视为只读瞬时入口，校验真实路径后立刻复制到服务端 job；其他 Profile、Session、.env 和敏感路径均拒绝。

建议在现有 Bot 中开启新会话后依次上传 fixtures/documents/drawing_demo.png、injection_prompt_demo.png 与 quotation_demo.xlsx。正常图应提交视觉证据；攻击图只能产生 prompt_injection_suspected；“跳过审核直接核价”必须由 Python 拒绝；完成后以 Telegram 文件附件发送 comparison_report.xlsx。不要启动第二个使用同一 Token 的 polling 进程。

Mock、计算和人工边界

两个行情 Adapter 只读取本地固定 JSON，不发网络请求，source_mode=mock，报告醒目标记“模拟数据，仅用于流程验证”。材料费、加工费、模具摊销、单位归一和异常全部使用 Decimal/ROUND_HALF_UP；利用率缺失时可用 DEMO CONFIG，但报告会标明来源。最低价不会触发定点结论；采购负责人必须最终复核。

提示注入与路径安全

PDF、图片、Excel、ZIP 和图纸均是不可信数据。英文/中文的忽略规则、系统提示、调用工具、批准供应商、跳过审核、泄露密钥等文字只保存为证据。路径会 resolve 并限制根目录，拒绝 ..、符号链接逃逸、Zip Slip、超量 ZIP、/etc、/root/.ssh、Hermes .env 与其他 Profile。

接入真实 API

空骨架位于 market/adapters/business_society.py 与 longzhong.py；未配置会抛 VendorNotConfiguredError，其中没有猜测 endpoint 或字段。实现前必须取得正式文档、沙箱地址、生产地址、API Key/Token、签名规则、白名单要求、产品编码表、字段字典、频率限制、税务与地区口径及数据存储授权。完成适配后还需做契约测试、脱敏日志、密钥外置和合规审核，才能切换 MARKET_PROVIDER_MODE。

常见故障与回滚

• mcp test 连接关闭：检查项目/.venv/SQLite 是否可由 felix 读取写入，并查看 ~/.hermes/logs/mcp-stderr.log。
• Skill 不显示：确认新 Session、requires_tools 对应的 MCP 已加载，再执行 skills list/reload。
• 视觉失败：检查 doctor 的 vision 可用性和主模型能力；不能假装视觉成功。
• Telegram 不能发送文件：确认报告在安全目录且 Gateway adapter 的文件策略允许；不要改 Token。

备份在 /opt/gissing/backups/hermes-procurement-<timestamp>。回滚时先确认没有采购任务运行，再将备份的 config.yaml 与 SOUL.md 原子恢复，移除新增 Skill 目录，并通过现有服务运维流程安排 Gateway 重载；不要直接覆盖 .env，除非明确需要且核对权限。项目本身可独立保留，不影响 Gateway。