内容
# 企业名录
> **奥地利完整的企业名录，可通过AI代理以自然语言查询。** 官方主数据、年度财务报表和关键比率适用于每家企业 – 通过MCP提供，以真实数据而非虚构信息呈现。
**[试用 playground](https://www.agentic-firmenbuch.at/playground.html)** · **[获取免费密钥](https://www.agentic-firmenbuch.at)** · **[快速入门 ↓](#快速入门)**
一个实时、自动化的数据产品，涵盖奥地利 **企业名录**（免费的欧盟 **HVD** / 高价值数据集），通过 **多租户MCP服务器** 提供。 一个确定性的Azure管道摄取所有企业的年度财务报表（~200k+），按企业合并，计算比率/增长/趋势，并将其暴露给MCP客户端。 **版本 1** = 事实 + 清洁的派生数据（无评分，无第三方丰富，无NACE，无AI摘要）。
## 快速入门
**使用托管服务** – 从接受HTTP头密钥的MCP客户端查询官方企业名录数据（Claude Code，Microsoft Copilot in VS Code，Cursor等）：
1. 在 **[agentic-firmenbuch.at](https://www.agentic-firmenbuch.at)** 上获取免费API密钥 – 只需验证邮箱。
2. 添加服务器。 **Claude Code** （终端），一行：
```bash
claude mcp add --scope user --transport http agentic-firmenbuch https://mcp.agentic-firmenbuch.at/mcp --header "X-API-Key: <your-key>"
```
**GitHub Copilot / VS Code**：`code --add-mcp "{\"name\":\"agentic-firmenbuch\",\"type\":\"http\",\"url\":\"https://mcp.agentic-firmenbuch.at/mcp\",\"headers\":{\"X-API-Key\":\"<your-key>\"}}"`. 任何其他HTTP-MCP-Header客户端：URL `https://mcp.agentic-firmenbuch.at/mcp`，头部 `X-API-Key: <your-key>`。
3. 以自然语言提问，例如 *"活跃的奥地利上奥地利GmbHs，资产负债表总额超过500万欧元，按销售额排序。"* 代理调用 `search_companies` / `get_company_details` 并以官方数据回答 – 无需SDK。
> **Claude Cowork & claude.ai** （沙盒客户端）：这些不接受API密钥头部 – 它们仅通过 `设置 → 连接器` 与 **OAuth登录** 连接。 OAuth连接器正在开发中；在此之前，请使用Claude Code或其他具有头部能力的客户端。
想在注册前试用？使用 **[playground](https://www.agentic-firmenbuch.at/playground.html)**。
**或自行运行管道** – 克隆，`uv sync`，`uv run pytest`（离线，无Azure）。参见 [开发](#开发)。
## 文档
| 文档 | 内容 |
|---|---|
| [docs/Technische_Spezifikation_v1.md](docs/Technische_Spezifikation_v1.md) | 如何 – 架构、模块、模式、运行手册、边缘情况、构建顺序。 **主要。** |
| [docs/Fachliche_Spezifikation_v1.md](docs/Fachliche_Spezifikation_v1.md) | 什么/为什么 – 范围和业务规则。 |
| [docs/pipeline-step-samples.md](docs/pipeline-step-samples.md) | 每个管道阶段的文件格式 + 黄金样本。 |
| [docs/FIELD_REFERENCE.md](docs/FIELD_REFERENCE.md) | **提供的字段字典** – 每个MCP工具返回的字段，类型 + 空值规则。 公共页面： [felder.html](https://www.agentic-firmenbuch.at/felder.html)。 |
| [docs/appendix_position_mapping.json](docs/appendix_position_mapping.json) | 完整的317项规范位置分类 → 复制到 `core/mapping/`。 |
| [docs/reference/](docs/reference/) | 官方源材料（API参考，JAb 4.0 XSDs/Excel）。 |
## 管道（编号层，`90 → 10`）
```
99_registry (基础：所有企业) → 90_raw (Blob) → 70_parsed (Blob) → 50_consolidated → 30_derived → 10_presentation → MCP
(Cosmos) (Cosmos) (Cosmos)
侧： 00_accounts (MCP注册) 为v2保留： 40_enriched, 20_scored
```
`90_raw` 是 **不可变的真实来源** （每个下载的XML/PDF，永久保存）。 `70_parsed` 是 **写入缓存** 的每个申报的`ParsedFiling` JSON – 始终可从原始数据重新派生，因此可以安全删除/重建；它存在于重处理（逻辑更改后的重新合并/派生） **跳过重新解析** 所有申报，并且因此 `inputs[]` 在每个合并文档中的谱系解析为实际解析文档。 `50/30/10` 是可查询的Cosmos层； `10_presentation` 是MCP提供的内容。
## 层映射 – 哪个代码拥有哪一层
每个管道阶段包目录 **以其层编号为前缀** ，因此每个数据层的拥有者都很明显。 （Python模块名称不能以数字开头，因此可导入的包保留其 `fbl_*` 名称；编号也作为 **LAYER** 常量在每个阶段包中公开。）
| 层 | 包（目录） | 导入 | 存储/容器 | Pydantic模型 | 示例 |
|---|---|---|---|---|---|
| `99_registry` | [`99_registry`](packages/99_registry/README.md) | `fbl_registry` | Cosmos `99_registry` | `RegistryDoc` | §15a.0 文档 |
| `90_raw` | [`90_ingest`](packages/90_ingest/README.md) | `fbl_ingest` | Blob `90-raw` | 原始 `Meta` + 清单 | [阶段 0](docs/pipeline-step-samples.md) |
| `70_parsed` | [`70_parse`](packages/70_parse/README.md) | `fbl_parse` | Blob `70-parsed` | `ParsedFiling` | [阶段 1](docs/pipeline-step-samples.md) |
| `50_consolidated` | [`50_consolidate`](packages/50_consolidate/README.md) | `fbl_consolidate` | Cosmos `50_consolidated` | `ConsolidatedCompany` | [阶段 2](docs/pipeline-step-samples.md) |
| `30_derived` | [`30_derive`](packages/30_derive/README.md) | `fbl_derive` | Cosmos `30_derived` | `DerivedCompany` | [阶段 3](docs/pipeline-step-samples.md) |
| `10_presentation` | [`10_present`](packages/10_present/README.md) | `fbl_present` | Cosmos `10_presentation` | `PresentedCompany` | [阶段 4](docs/pipeline-step-samples.md) |
**未编号** （不是单个数据层）： [`core`](packages/core/README.md) (`fbl_core`，共享模型/映射/谱系/存储），[`firmenbuch_client`](packages/firmenbuch_client/README.md) (`fbl_firmenbuch_client`，HVD SOAP适配器），[`orchestration`](packages/orchestration/README.md) (`fbl_orchestration`， `--mode` 作业入口点），[`mcp_server`](packages/mcp_server/README.md) (`fbl_mcp_server`，服务），[`auth`](packages/auth/README.md) (`fbl_auth`， `00_accounts`)。
另外 [`infra/`](infra/README.md) （Bicep），[`tests/`](tests/README.md) （夹具），`docs/` （规范，包括 [API探测结果](docs/API_PROBE_FINDINGS.md))。
## 构建状态 – 版本 1 完成 ✅
所有十个§15构建阶段都已实施，每个阶段都已提交并通过合格标准。 **`ruff` + `mypy --strict` + `pytest` （带有80％覆盖率门控）均为绿色** 在CI中。 HVD API已进行实时探测（§16已解决），并且整个链 `raw→present` 已在实时数据上进行验证。
- **阶段 10：** 授权限制的 **覆盖** 工具（XML vs PDF-only vs none，按格式/状态 – §11）和 **GitHub Actions CI** （`uv sync` → ruff → ruff格式 → `mypy --strict` → pytest，带有80％覆盖率门控，以及Bicep编译作业）。
**剩余运营工作** （非代码）：在Azure中提供（`infra/setup.sh`，需付费），将FIRMENBUCH_API_KEY推送到Key Vault，构建/推送镜像，然后运行初始加载（`sync-registry → backfill-ingest → backfill-process`）并启用每日cron。
## 开发
```bash
uv sync # 创建工作区venv
uv run pytest # 所有夹具/单元/集成测试（离线）
uv run mypy packages # 严格类型
uv run ruff check packages # lint
```
**真正的端到端（实时）：** 一个单独的、由环境标志保护的测试运行几个真实的FNR通过每个层（API → `90_raw` → … → `10_presentation` → MCP）。 默认情况下跳过。
```bash
FBL_E2E=1 uv run pytest tests/e2e -q # 需要FIRMENBUCH_API_KEY（环境或.env）
```
参见 [`tests/e2e/`](tests/e2e/README.md)。 它使用内存存储 + 一个微小的真实拉取 – **无Azure，无完整回填** （部署在审查后手动进行）。
## 许可证和数据
在 **MIT许可证** 下许可（参见 [`LICENSE`](LICENSE))。
数据来源于 **奥地利企业名录** （BMJ – Justiz），一个欧盟高价值数据集，在 **CC BY 4.0** 下许可。 任何数据重新分发必须保留属性 *"来源：奥地利企业名录 / BMJ – Justiz（CC BY 4.0）"* （参见 [`NOTICE`](NOTICE))。
## 免责声明 – 无担保，自行承担风险
该软件及其产生的数据 **按原样提供，不做任何担保** ，不论是明示还是暗示（参见MIT许可证）。 处理的数据是从公共企业名录自动派生，并 **不提供任何正确性、完整性、及时性或特定用途的保证** 。 它 **不是** 法律、税务或财务建议，也不 **取代官方企业名录提取** – 官方注册始终优先。
**使用该软件和数据完全由您自行承担风险。** 在法律允许的最大范围内，作者和版权持有人 **不承担任何直接、间接、偶然或后果性损害** 因其使用而产生的责任。 您有责任遵守CC BY 4.0属性要求以及使用或重新分发数据时适用的所有数据保护、竞争和版权法律。
