# 企业数据与知识 Agent 接入网关

把磁盘上的异构文件编目成 **Agent 可调用的工具契约**（MCP + 独立 CLI）。  
这不是阿里式数据中台；生产上把 DuckDB 换成 Doris/Hive 时，**工具名和参数可以保持不变**。

- **知识层**：本机生财 JSON 语料（不进 Git）+ 仓库内 3 篇自写 SOP
- **业务层**：180 天合成电商数仓（CSV / XLSX / Parquet → DuckDB）
- **12 个工具**：`kb_*` / `biz_*` / `catalog_*`，设计语言对齐 scys MCP（何时用、ID 链、分页、禁猜 ID）

## 快速开始

```powershell
cd D:\SCYS-data\gateway
uv venv --python 3.12.13 .venv
uv pip install -p .venv -e ".[dev]"
.\.venv\Scripts\agent-gateway-ingest
.\.venv\Scripts\agent-gateway demo
.\.venv\Scripts\agent-gateway-eval
```

在线模型（可选）：复制 `.env.example` 为 `.env`，填 OpenAI 兼容网关，然后：

```powershell
.\.venv\Scripts\agent-gateway ask "上周 GMV 最高的 SKU 有没有对应 SOP？" --live
```

Cursor 里装 MCP：参考 [docs/cursor.mcp.example.json](docs/cursor.mcp.example.json)。

## 工具地图

| 前缀 | 工具 | 作用 |
| --- | --- | --- |
| kb | list_tags / search / get_doc / get_outline / read_section | 标签 → 检索 → 分页正文 |
| biz | list_metrics / query_sales / get_sku / get_order / anomaly_scan | 结构化过滤，禁止任意 SQL |
| catalog | list_assets / lineage | 资产与血缘 |

跨层演示（`agent-gateway demo`）：

1. 上周 GMV 最高 SKU → 3C 充电 SOP
2. 音频退款率异常 → 售后复盘
3. 抖音花费升、转化平 → 投放排查清单

## 目录

```
gateway/
  src/agent_gateway/   # 接入、存储、工具、MCP、CLI Agent、评测
  fixtures/internal_sops/  # 可公开的自写 SOP
  eval/cases.yaml      # 20 道离线黄金题
  docs/INTERVIEW.md    # 面试讲稿
```

生成物在 `.local/`（已 gitignore）。社区 JSON 原文只留在 `D:\SCYS-data`，不要提交。

## 简历表述

> 设计并实现企业数据/知识 MCP 网关与独立 Agent：将磁盘侧多格式文档与主题域指标以工具契约暴露；支持检索、口径查询、异常扫描与跨源引用。演示语料为社区知识库 + 合成电商数仓，接口按可替换生产引擎设计。

面试怎么讲见 [docs/INTERVIEW.md](docs/INTERVIEW.md)。