# 采购询比价与注塑件核价 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

```bash
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，避免破坏提示缓存。

配置验证：

```bash
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。