# https://github.com/ever-just/company-dossier 项目说明书

生成时间：2026-06-21 19:57:45 UTC

## 目录

- [Project Overview and Getting Started](#page-1)
- [Core Engine, Module Architecture and Data Flow](#page-2)
- [Data Collectors and the Nine Dossier Sections](#page-3)
- [MCP Server Deployment and AI Assistant Integrations](#page-4)

<a id='page-1'></a>

## Project Overview and Getting Started

### 相关页面

相关主题：[Core Engine, Module Architecture and Data Flow](#page-2), [Data Collectors and the Nine Dossier Sections](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/ever-just/company-dossier/blob/main/README.md)
- [packages/company-dossier/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)
- [packages/company-dossier/package.json](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/package.json)
- [packages/company-dossier/src/core.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/core.ts)
- [packages/company-dossier/src/cli.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/cli.ts)
- [packages/company-dossier/src/collectors/website.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/collectors/website.ts)
- [packages/company-dossier/src/mcp-server.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts)
- [integrations/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md)
- [integrations/chatgpt/apps-sdk/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/chatgpt/apps-sdk/README.md)
</details>

# Project Overview and Getting Started

## 项目定位与目标

`company-dossier` 是一个开源情报（OSINT）工具集，专门用于从**纯公开数据**汇编企业情报档案。它的核心理念区别于传统 OSINT 工具的"原始数据堆砌"，而是生成一份**结构化、带来源标注、带置信度标记**的可阅读情报文件，供分析师、开发者及 AI Agent 在尽职调查、竞争情报、销售线索筛选等场景中直接使用。

资料来源：[README.md:7-13](https://github.com/ever-just/company-dossier/blob/main/README.md)

根据 [README.md:7-13](https://github.com/ever-just/company-dossier/blob/main/README.md)，项目明确声明："No API keys. No private databases. No login. Free."（无需 API Key、无需付费数据库、无需登录、完全免费）。所有派生信息均回注其来源，对于无法访问或为空的数据源，会被记录为"gap"（缺口）而非伪造。

## 核心架构与交付形态

项目提供**四种使用形态**，覆盖从终端用户到 AI Agent 的完整链路：

| 形态 | 入口 | 适用场景 |
|---|---|---|
| 🌐 网站小部件 | [companydossier.lol/generate](https://companydossier.lol/generate/) | 无需安装，浏览器内生成 |
| 📦 npm 包（CLI + 库 + MCP） | `npx company-dossier <domain>` | 脚本、CI、AI Agent |
| 🧩 VS Code 扩展 | `@dossier /research` 命令 | 编辑器内即时研究 |
| 📚 方法论文档 | `methodology/` 目录 | 分析师与团队可复现的完整剧本 |

资料来源：[README.md:17-23](https://github.com/ever-just/company-dossier/blob/main/README.md)

仓库的目录结构按职责拆分：

```
methodology/        可复现的方法论剧本（流水线、架构、工具、技能、案例）
site/               companydossier.lol 站点源码
packages/
  company-dossier/  npm 包：CLI + 库 + MCP 服务器
integrations/       Claude Agent Skill + ChatGPT GPT / Apps-SDK (MCP) 配置
```

资料来源：[README.md:36-43](https://github.com/ever-just/company-dossier/blob/main/README.md)

## 快速开始

### CLI 安装与运行

最简洁的上手方式是通过 `npx` 直接运行，无需任何预安装步骤：

```bash
npx company-dossier acme.com
```

上述命令会在当前目录生成一个 `Acme DOSSIER/` 文件夹，内含九个分章节的 Markdown 文件以及一份机器可读的 `dossier.json`。

资料来源：[packages/company-dossier/README.md:21-27](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)

常用选项包括：

```bash
# 指定输出目录并静默运行
company-dossier acme.com --out ./research --quiet

# 仅按企业名称研究（无域名）
company-dossier "Acme Corporation"

# 将 JSON 输出到 stdout，便于管道处理
company-dossier acme.com --json > acme.json

# 仅构建指定章节
company-dossier acme.com --sections overview,tech,risk
```

资料来源：[packages/company-dossier/README.md:30-37](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)

CLI 帮助文档通过 [packages/company-dossier/src/cli.ts:5-30](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/cli.ts) 暴露完整选项列表，包含 `--out`、`--json`、`--sections`、`--max-pages`、`--no-social-probe`、`--quiet` 等开关。

### 作为库使用

对开发者而言，可直接通过 ESM 导入 `buildDossier` 与 `writeDossier`：

```ts
import { buildDossier, writeDossier } from 'company-dossier';

const result = await buildDossier('acme.com', {
  sections: ['overview', 'tech', 'risk'], // 可选子集
});

// result.meta  — 目标、公司名、来源及状态
// result.json  — 完整结构化数据 ({ meta, data })
// result.files — [{ path, content }] markdown + dossier.json

const folder = writeDossier(result, './research');
```

资料来源：[packages/company-dossier/README.md:62-75](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)

各采集器（collector）也可单独导出：`collectWebsite`、`collectDns`、`collectWayback`、`extractTechStack`、`collectSearch`。`BuildOptions` 接口定义于 [packages/company-dossier/src/core.ts:1-15](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/core.ts)，支持自定义 `progress` 回调、`maxPages` 与 `skipSocialProbe`。

### MCP 服务器集成

`company-dossier` 内置一个符合 [Model Context Protocol](https://modelcontextprotocol.io) 标准的 MCP 服务器，通过 stdio 暴露单一工具 `build_dossier`，允许 ChatGPT、Claude 等 AI Agent 直接调用：

```json
{
  "mcpServers": {
    "company-dossier": {
      "command": "npx",
      "args": ["-y", "company-dossier-mcp"]
    }
  }
}
```

工具输入参数示例：

```json
{ "target": "acme.com", "sections": ["overview", "tech", "risk"] }
```

资料来源：[packages/company-dossier/README.md:81-94](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)

工具注册逻辑由 [packages/company-dossier/src/mcp-server.ts:13-37](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts) 集中实现，使用 `zod` 进行入参校验，并返回包含 Markdown 与 JSON 的完整响应。除 stdio 版本外，项目还提供基于 Streamable HTTP 传输的远程 MCP 服务器（`company-dossier-mcp-http`），监听 `0.0.0.0:8787`，便于托管型助手（ChatGPT Apps SDK、Claude 连接器）通过网络调用。

## 九个章节概览

`company-dossier` 生成的档案固定由**九个结构化章节**组成，每一节都有清晰的来源标注：

1. **Overview & identity** —— 公司名、描述、schema.org、关键词
2. **People & org chart** —— 联系邮箱、个人模式邮箱（缺口已标注）
3. **Hiring radar** —— 招聘页与来自站点/sitemap 的职位 URL
4. **Money trail** —— USASpending.gov 联邦合同与义务
5. **Locations** —— 结构化地址与电话
6. **Tech fingerprint** —— CMS、分析、像素、CDN、框架、邮箱/DNS
7. **News & timeline** —— Wayback 历史、增长、已删除页面、归档 PDF
8. **Relationship web** —— 社交与外部档案
9. **Risk flags** —— 自动低置信度技术信号（SPF/DMARC、流失）

资料来源：[packages/company-dossier/README.md:40-50](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)

每个章节渲染器（如 `renderOverview`、`renderPeople`）定义于 [packages/company-dossier/src/core.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/core.ts)，统一通过 `sourceLine()` 追加来源行。当数据源不可达时，会写入 `_Gap: no public data found — requires manual research._` 占位文本，避免凭空捏造。

## 数据采集流水线

```mermaid
flowchart LR
    A[输入: domain 或公司名] --> B{是否域名?}
    B -- 是 --> C[解析域名]
    B -- 否 --> D[公开搜索推断]
    C --> E[collectWebsite<br/>首页+内页+sitemap]
    C --> F[collectDns<br/>MX/TXT/SPF/DMARC]
    C --> G[collectWayback<br/>历史快照]
    C --> H[extractTechStack<br/>CMS/CDN/分析]
    C --> I[collectSearch<br/>社交与USASpending]
    D --> I
    E --> J[renderSections]
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[Markdown + dossier.json]
```

网站采集器 [`collectWebsite`](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/collectors/website.ts) 的执行流程为：抓取首页 → 抓取 `sitemap.xml` → 解析内链 → 按 `maxPages`（默认 25）抓取内部页面，提取标题、描述、邮箱、电话、社交链接、schema.org JSON-LD 等。任一采集器失败都不会抛出异常，而是将错误记录在 `result.error` 中，最终汇总为档案中的"缺口"。

## 常见配置与失败模式

| 选项 | 默认值 | 说明 |
|---|---|---|
| `sections` | 全部九节 | 可指定子集，缩短生成时间 |
| `maxPages` | 25 | 单次会话最大抓取页数，过大可能触发反爬 |
| `skipSocialProbe` | `false` | 跳过对社交平台的 HEAD 探测可加速 |
| `--quiet` | 关闭 | 关闭进度输出 |
| `COMPANY_DOSSIER_ANTHROPIC_KEY` | 未设置 | 预留 AI 富化接口，无密钥也可正常工作 |

资料来源：[packages/company-dossier/src/cli.ts:18-25](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/cli.ts)

典型失败模式包括：网络受限的源（如被 GFW 阻挡的 Wayback、USASpending）会显示为 `failed` 状态而非崩溃；sitemap 不存在会被静默跳过；schema.org JSON-LD 缺失则在该章节渲染"未发现"。这些行为在 `collectWebsite` 与 `core.ts` 中通过 `try/catch` 与 `result.error` 显式处理。

## See Also

- [Knowledge Pipeline & Architecture](#) — `methodology/OVERVIEW.md` 中的七阶段流水线详解
- [MCP Integration Guide](#) — `integrations/chatgpt/apps-sdk/README.md` 中的 ChatGPT App 接入流程
- [Claude Agent Skill](#) — `integrations/claude-skill/company-dossier/SKILL.md` 中的技能定义

License: MIT © EVERJUST

---

<a id='page-2'></a>

## Core Engine, Module Architecture and Data Flow

### 相关页面

相关主题：[Project Overview and Getting Started](#page-1), [Data Collectors and the Nine Dossier Sections](#page-3), [MCP Server Deployment and AI Assistant Integrations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/company-dossier/src/core.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/core.ts)
- [packages/company-dossier/src/cli.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/cli.ts)
- [packages/company-dossier/src/mcp-server.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts)
- [packages/company-dossier/src/collectors/website.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/collectors/website.ts)
- [packages/company-dossier/package.json](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/package.json)
- [packages/company-dossier/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)
- [README.md](https://github.com/ever-just/company-dossier/blob/main/README.md)
- [integrations/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md)
</details>

# Core Engine, Module Architecture and Data Flow

## 1. 核心引擎的定位与职责

`company-dossier` 的核心引擎位于 `packages/company-dossier/src/core.ts`，是整个包的中枢。它对外暴露一个高层异步函数 `buildDossier(target, opts)`，接收一个域名（例如 `acme.com`）或公司名称，运行若干"公开数据采集器"（collectors），再把结果装配成九段式 Markdown 档案与一份 `dossier.json` 资料来源：[packages/company-dossier/src/core.ts:buildDossier]()。

核心引擎的明确职责有四点：

1. **归一化输入** — 通过 `looksLikeDomain` 与 `toDomain` 判断目标是域名还是公司名，并据此决定采集策略；
2. **编排采集** — 串行/并行调用 `collectWebsite`、`collectDns`、`collectWayback`、`extractTechStack`、`collectSearch` 等采集器；
3. **收集元数据** — 维护 `DossierMeta`，包括目标、公司名、域名、网站 URL、生成时间、`sources` 状态等；
4. **渲染九段式档案** — 由若干 `render*` 函数（如 `renderOverview`、`renderPeople`、`renderHiring` …）逐段输出 Markdown。

引擎被设计为"永不抛出"：当某个公开数据源不可达或失败时，会在结果里记录为 gap，而不是中断整次调用 资料来源：[packages/company-dossier/src/core.ts:buildDossier]()。

## 2. 模块化架构

整个包采用分层架构，可由下表概览。

| 层级 | 入口/代表文件 | 角色 |
|------|----------------|------|
| CLI 入口 | `packages/company-dossier/src/cli.ts` | 解析命令行参数，调用 `buildDossier` 并写文件 |
| MCP stdio 入口 | `company-dossier-mcp`（bin 名，见 `package.json`） | 通过 stdio 把 `build_dossier` 工具暴露给 MCP 客户端 |
| MCP HTTP 入口 | `company-dossier-mcp-http`（bin 名，见 `package.json`） | 用 MCP Streamable HTTP 传输在网络上暴露同一工具 |
| 核心引擎 | `packages/company-dossier/src/core.ts` | 编排采集、组装 `DossierResult` |
| 采集器 | `packages/company-dossier/src/collectors/website.ts` 等 | 与具体公开数据源交互，返回结构化数据 |
| 类型与常量 | `core.ts`（`SectionId`、`SECTIONS`、`SECTION_TITLES`、`SECTION_FILENAMES`） | 描述九段式档案的元数据 |
| 工具函数 | `packages/company-dossier/src/utils.ts` | HTML 抓取、URL 解析、节流（`sleep`）等通用方法 |

模块间通过纯函数 + 显式接口解耦：采集器只返回数据对象（如 `WebsiteData`），渲染器只读取数据对象并产生 Markdown，二者互不依赖 资料来源：[packages/company-dossier/src/collectors/website.ts:WebsiteData]()、[packages/company-dossier/src/core.ts:renderOverview]()。

`package.json` 把 `bin` 声明为 `company-dossier`、`company-dossier-mcp`、`company-dossier-mcp-http`，意味着同一个包同时承担 CLI、stdio MCP、HTTP MCP 三种分发形态 资料来源：[packages/company-dossier/package.json:bin]()。

## 3. 数据流：从输入到九段式档案

下面以 `buildDossier` 为主线，用 Mermaid 图展示端到端的数据流。

```mermaid
flowchart TD
  A[输入 target<br/>域名或公司名] --> B{looksLikeDomain?}
  B -- 是 --> C[toDomain + 拼装 websiteUrl]
  B -- 否 --> D[保留原始字符串作为公司名]
  C --> E[并行/串行调用采集器]
  D --> E
  E --> E1[collectWebsite<br/>首页 + sitemap + 内部页]
  E --> E2[collectDns]
  E --> E3[collectWayback]
  E --> E4[extractTechStack]
  E --> E5[collectSearch]
  E1 & E2 & E3 & E4 & E5 --> F[DossierData<br/>website / dns / wayback / tech / search]
  F --> G[renderOverview / renderPeople / ...<br/>九段式 Markdown]
  F --> H[序列化 dossier.json]
  G & H --> I[DossierResult<br/>meta + json + files]
  I --> J[CLI: writeDossier 到文件夹]
  I --> K[MCP: 工具返回 markdown + JSON]
```

关键点：

- `buildDossier` 返回 `DossierResult`，包含 `meta`（元信息）、`json`（结构化数据）、`files`（`[{ path, content }]` 形式的 Markdown 列表） 资料来源：[packages/company-dossier/src/core.ts:DossierResult]()。
- `collectWebsite` 不会"throw"：首页抓取失败时，把错误写入 `result.error` 后立即返回；`sitemap.xml` 缺失则记录为 'not found or inaccessible.' 资料来源：[packages/company-dossier/src/collectors/website.ts:collectWebsite]()。
- `renderPeople` 会用启发式规则识别"看起来像个人邮箱"（如 `^[a-z]+([._-][a-z]+)?@/i`），并明确标注为"未经验证" 资料来源：[packages/company-dossier/src/core.ts:renderPeople]()。
- 渲染时遇到无数据，会使用统一占位符 `GAP`（`_Gap: no public data found — requires manual research._`） 资料来源：[packages/company-dossier/src/core.ts:GAP]()。

## 4. 类型、配置与公共 API

`BuildOptions` 暴露给库使用者的关键配置项如下（精简）：

- `sections?: SectionId[]` — 限制只生成九段中的一部分；
- `progress?: ProgressCallback` — 接收状态文本的回调；
- `maxPages?: number` — 内部页面抓取上限（默认 25）；
- `skipSocialProbe?: boolean` — 跳过对社交平台耗时的 HEAD 探测 资料来源：[packages/company-dossier/src/core.ts:BuildOptions]()。

`SectionId` 联合类型与 `SECTIONS` 常量数组共同定义九段顺序：`overview`、`people`、`hiring`、`money`、`locations`、`tech`、`news`、`relationships`、`risk` 资料来源：[packages/company-dossier/src/core.ts:SECTIONS]()。库的对外 API 至少包括 `buildDossier`、`writeDossier`，以及若干独立采集器（如 `collectWebsite`、`collectDns`、`collectWayback`、`extractTechStack`、`collectSearch`） 资料来源：[packages/company-dossier/README.md:Library usage]()。

MCP 侧通过 `registerTools` 注册唯一工具 `build_dossier`，输入形如 `{ "target": "acme.com", "sections": ["overview", "tech", "risk"] }`，与 CLI/`buildDossier` 共享同一份实现 资料来源：[packages/company-dossier/src/mcp-server.ts:registerTools]()。

## See Also

- 顶层 README：项目目标、四种使用方式与仓库结构 [README.md](https://github.com/ever-just/company-dossier/blob/main/README.md)
- 包级 README：CLI 速查、九段说明、库用法与 MCP 集成 [packages/company-dossier/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)
- 集成目录：Claude Agent Skill 与 ChatGPT Apps SDK 接线 [integrations/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md)

---

<a id='page-3'></a>

## Data Collectors and the Nine Dossier Sections

### 相关页面

相关主题：[Core Engine, Module Architecture and Data Flow](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/company-dossier/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)
- [packages/company-dossier/package.json](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/package.json)
- [packages/company-dossier/src/collectors/website.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/collectors/website.ts)
- [packages/company-dossier/src/core.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/core.ts)
- [packages/company-dossier/src/cli.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/cli.ts)
- [packages/company-dossier/src/mcp-server.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts)
- [integrations/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md)
- [integrations/chatgpt/apps-sdk/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/chatgpt/apps-sdk/README.md)
- [README.md](https://github.com/ever-just/company-dossier/blob/main/README.md)
</details>

# 数据采集器与九个档案章节

## 一、定位与职责

`company-dossier` 的核心目标是从**纯公开数据**出发,为任何公司或域名生成结构化、可溯源、带置信度标注的"情报档案"。整个体系分为两层:第一层是**数据采集器(collectors)**,负责从网站、Wayback Machine、DNS、技术指纹、USASpending.gov 等公开来源抓取原始信号;第二层是**章节渲染器(renderers)**,在 `packages/company-dossier/src/core.ts` 中将采集结果编排为九份标准化的 Markdown 章节,并附带 `dossier.json`。资料来源:[packages/company-dossier/README.md]()

包对外暴露了若干可独立调用的采集函数,包括 `collectWebsite`、`collectDns`、`collectWayback`、`extractTechStack`、`collectSearch`,它们都可以脱离主流程单独使用。资料来源:[packages/company-dossier/README.md:118-119]()

## 二、数据采集器

采集器集中在 `src/collectors/`,遵循统一的契约:接收输入参数与进度回调(`progress`),返回一个带有 `error` 字段的结果对象——失败时**绝不抛异常**,而是把错误写入 `error` 以便后续章节如实标记为"缺口"(Gap)。

| 采集器 | 输入 | 主要产物 | 故障语义 |
|:--|:--|:--|:--|
| `collectWebsite` | 基础 URL + `maxPages` | 首页元信息、Schema.org JSON-LD、社交链接、邮箱、电话、sitemap 链接、内部页面 | 失败时 `error` 字段记录,仍可被后续章节读取 |
| `collectWayback` | 域名 | 首末次抓取时间、年度抓取次数、已删除页面快照 | 网络阻塞或 Archive 不可达时降级为"缺口" |
| `collectDns` | 域名 | MX/NS/TXT、SPF、DMARC 记录 | 解析失败时整段章节标记为 Gap |
| `extractTechStack` | 已抓取的 HTML 与 DNS | CMS、分析、像素、CDN、框架、邮件栈 | 同上 |
| `collectSearch` | 公司名或域名 | 公开搜索补全信息(仅在仅提供公司名时启用) | 失败时不影响其它章节 |

资料来源:[packages/company-dossier/src/collectors/website.ts:18-50]()

`maxPages` 默认 25,由 CLI 的 `--max-pages` 与库 API 的 `BuildOptions.maxPages` 共同控制,用于在广度与速度之间取得平衡。资料来源:[packages/company-dossier/src/core.ts]()

## 三、九个章节的对应关系

`SECTIONS` 数组定义了九份固定章节,所有采集结果在此汇聚,每个章节对应一个 `render*` 函数,逐个拼装成最终 Markdown。资料来源:[packages/company-dossier/src/core.ts]()

```mermaid
flowchart LR
  A[Target<br/>域名 / 公司名] --> B[collectWebsite]
  A --> C[collectDns]
  A --> D[collectWayback]
  A --> E[extractTechStack]
  A --> F[collectSearch]
  B & C & D & E & F --> G[core.ts<br/>编排与渲染]
  G --> H1[1. 总览与身份]
  G --> H2[2. 人员与组织架构]
  G --> H3[3. 招聘雷达]
  G --> H4[4. 资金轨迹]
  G --> H5[5. 地址与联系方式]
  G --> H6[6. 技术指纹]
  G --> H7[7. 新闻与时间线]
  G --> H8[8. 关系网络]
  G --> H9[9. 风险标记]
  H1 & H2 & H3 & H4 & H5 & H6 & H7 & H8 & H9 --> I[dossier.json<br/>+ <Company> DOSSIER/]
```

章节中文名称与采集器映射:

1. **总览与身份**:公司名(优先 schema.org `name`,其次 `<title>`,最后域名)、描述、关键词、Schema.org JSON-LD。资料来源:[packages/company-dossier/src/core.ts:renderOverview]()
2. **人员与组织架构**:由 `collectWebsite` 提取的 `allEmails` 派生,按"姓名模式"启发式筛选个人邮箱,领导层与组织图公开来源不足时统一写为 Gap。资料来源:[packages/company-dossier/src/core.ts:renderPeople]()
3. **招聘雷达**:扫描 `pages` 中 URL 匹配 `career|job|hiring|join|work` 的内部页面。资料来源:[packages/company-dossier/src/core.ts:renderHiring]()
4. **资金轨迹**:USASpending.gov 联邦合同与义务金额。
5. **地址与联系方式**:`allPhones` 与结构化地址。
6. **技术指纹**:`extractTechStack` + `collectDns`,整合 CMS、CDN、像素、SPF/DMARC。资料来源:[packages/company-dossier/src/core.ts:renderTech]()
7. **新闻与时间线**:基于 `wb.firstCapture`、`wb.lastCapture` 推算"已归档年数"和年度抓取表。资料来源:[packages/company-dossier/src/core.ts:renderNews]()
8. **关系网络**:`socialLinks` 配合 `--no-social-probe` 选项,默认会 HEAD 探测社交平台可达性。
9. **风险标记**:由 SPF/DMARC 缺失等低置信度技术信号自动生成,**不是法律或财务建议**。资料来源:[packages/company-dossier/README.md]()

## 四、配置与裁剪

`buildDossier(target, options)` 与 CLI `company-dossier <target> [options]` 共享同一份 `BuildOptions`,核心字段包括 `sections`(章节子集)、`progress`(进度回调)、`maxPages`(最大内部页数)、`skipSocialProbe`(跳过慢速社交探测)。资料来源:[packages/company-dossier/src/core.ts]()

CLI 还额外提供 `--json`(把 `dossier.json` 打印到 stdout,便于管道)、`--out <dir>`(输出目录)、`--quiet`(抑制进度)。当用户只提供公司名而非域名时,流程会先经 `collectSearch` 反查域名,再走主链路。资料来源:[packages/company-dossier/src/cli.ts]()

MCP 服务器(`company-dossier-mcp`、`company-dossier-mcp-http`)通过 `mcp-server.ts` 中的 `registerTools` 复用同一份采集+渲染管线,只暴露一个 `build_dossier` 工具,ChatGPT Apps SDK、Claude 连接器等都可以远程调用,最终产物仍是相同的九章节 Markdown 与 JSON。资料来源:[packages/company-dossier/src/mcp-server.ts](),[integrations/chatgpt/apps-sdk/README.md]()

## 五、常见失败模式

- **网络阻塞/Archive 不可达**:`collectWayback` 写入 `error`,章节以"Wayback Machine data unavailable"开头并把新闻部分标记为 Gap,不会伪造数据。资料来源:[packages/company-dossier/src/core.ts:renderNews]()
- **慢速社交探测**:在 CI 场景下使用 `--no-social-probe` 避免被 HEAD 探测拖慢,默认行为保留探测。资料来源:[packages/company-dossier/src/cli.ts]()
- **章节裁剪**:通过 `--sections overview,tech,risk` 只生成目标章节,节省时间,适合快速技术盘点。

---

## 另请参阅

- [Methodology Overview](https://github.com/ever-just/company-dossier/blob/main/methodology/OVERVIEW.md) — 七阶段流水线的完整方法论
- [MCP Server & Remote HTTP](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts) — `build_dossier` 工具定义
- [Integrations README](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md) — Claude Agent Skill 与 ChatGPT Apps SDK 配置
- [VS Code Extension](https://github.com/ever-just/company-dossier-vscode) — `@dossier /research` 编辑器内调用

---

<a id='page-4'></a>

## MCP Server Deployment and AI Assistant Integrations

### 相关页面

相关主题：[Core Engine, Module Architecture and Data Flow](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/company-dossier/src/mcp-server.ts](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/src/mcp-server.ts)
- [packages/company-dossier/package.json](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/package.json)
- [packages/company-dossier/deploy/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/deploy/README.md)
- [packages/company-dossier/README.md](https://github.com/ever-just/company-dossier/blob/main/packages/company-dossier/README.md)
- [integrations/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/README.md)
- [integrations/chatgpt/apps-sdk/README.md](https://github.com/ever-just/company-dossier/blob/main/integrations/chatgpt/apps-sdk/README.md)
- [README.md](https://github.com/ever-just/company-dossier/blob/main/README.md)
</details>

# MCP Server Deployment and AI Assistant Integrations

## 概述

`company-dossier` 是一个面向公开数据的情报收集工具，能够为任意公司或域名生成结构化的九段式情报档案。该项目的核心交付形态不止 CLI 和库函数，还包含一套 **Model Context Protocol (MCP) 服务器** 以及针对主流 AI 助手的集成资产，使 ChatGPT、Claude 等代理能够直接调用该工具生成情报档案。

MCP 服务器由 `packages/company-dossier/src/mcp-server.ts` 中的 `registerTools(server)` 函数统一注册唯一的工具 `build_dossier`，避免 stdio 与 HTTP 两种传输方式下的重复定义。该工具的输入 schema 采用 `zod` 校验，接受 `target`（域名或公司名）以及可选的 `sections` 数组。

资料来源：[packages/company-dossier/src/mcp-server.ts:1-30]()

---

## MCP 服务器架构与二进制分发

`packages/company-dossier/package.json` 中声明了三个可执行入口，覆盖不同的运行形态：

| 二进制名 | 入口文件 | 用途 |
|:--|:--|:--|
| `company-dossier` | `dist/cli.js` | 本地命令行调用 |
| `company-dossier-mcp` | `dist/mcp.js` | stdio 传输的 MCP 服务器 |
| `company-dossier-mcp-http` | `dist/mcp-http.js` | Streamable HTTP 传输的远程 MCP 服务器 |

`tsup` 负责将 TypeScript 源码编译为 ESM 包，并通过 `files` 白名单（`dist`、`README.md`）控制 npm 发布内容，确保部署相关的 `Dockerfile`、`render.yaml`、`fly.toml` 不会随包发布，但仍可在仓库内直接用于云端部署。

资料来源：[packages/company-dossier/package.json:1-70]()

---

## 远程部署：Docker、Render、Fly

`packages/company-dossier/deploy/README.md` 描述了远程 HTTP MCP 服务器的端点契约：

- `POST /mcp`：处理 initialize 和工具调用，初始化时返回 `Mcp-Session-Id` 响应头
- `GET /mcp`：服务器主动推送的 SSE 流
- `DELETE /mcp`：销毁会话
- `GET /health`：健康检查，返回 `200 {"status":"ok"}`

服务器监听端口由环境变量 `process.env.PORT || 8787` 控制。仓库提供三种部署方式：

1. **Render Blueprint**：通过 `render.yaml` 一键创建名为 `company-dossier-mcp` 的 Docker Web 服务，并自动配置 `/health` 健康检查
2. **Fly.io**：使用 `fly.toml` 部署
3. **Docker**：直接基于 `Dockerfile` 构建容器

所有部署文件仅保留在 monorepo 的 `packages/company-dossier/` 目录下，npm 包内不携带这些部署资产，从而保持包体积精简且职责清晰。

```mermaid
graph LR
    A[AI 助手<br/>ChatGPT / Claude] -->|HTTPS / stdio| B[MCP Server<br/>company-dossier-mcp]
    B --> C[build_dossier 工具]
    C --> D[Website Crawl]
    C --> E[DNS Recon]
    C --> F[Wayback Machine]
    C --> G[USASpending.gov]
    C --> H[Tech Fingerprint]
    B -->|Markdown + JSON| A
```

资料来源：[packages/company-dossier/deploy/README.md:1-50]() · [packages/company-dossier/package.json:18-23]()

---

## AI 助手集成资产

`integrations/README.md` 列出针对不同 AI 平台的集成资产，确保代理能够在不具备 MCP 客户端能力时仍可调用 `company-dossier`：

| 资产 | 类型 | 功能 |
|:--|:--|:--|
| `claude-skill/company-dossier/SKILL.md` | Claude Agent Skill | 告知 Claude 何时及如何构建九段式档案，优先调用 MCP/CLI 工具，回退至手动网页采集 |
| `claude-skill/company-dossier/reference/sections.md` | Skill 参考 | Claude 组装档案时按段读取的指引 |
| `claude-skill/company-dossier.zip` | 上传产物 | 已压缩的 Skill 文件夹，便于分发 |
| `chatgpt/gpt/instructions.md` | Custom GPT 规范 | 基于浏览器的 Custom GPT 配置 |
| `chatgpt/apps-sdk/README.md` | App 接线文档 | 基于 MCP 的 ChatGPT App 与 `company-dossier-mcp` 的对接说明 |
| `chatgpt/apps-sdk/manifest.example.json` | 示例 manifest | 连接器 manifest 的起始模板 |

`integrations/chatgpt/apps-sdk/README.md` 进一步说明：ChatGPT App 通过 MCP over HTTPS（Streamable HTTP）连接远程服务器，自动发现 `build_dossier` 工具。托管端点示例为 `https://mcp.companydossier.lol`，认证模型默认为 **no-auth**，因为该工具仅使用公开数据，无需用户凭证；若未来引入账户或计费，可切换至 OAuth 2.1。

资料来源：[integrations/README.md:1-60]() · [integrations/chatgpt/apps-sdk/README.md:1-40]()

---

## 工具契约与 CLI 一致性

`build_dossier` 工具与 CLI 入口共享同一核心函数，保证三种调用方式产出相同的九段式档案。`packages/company-dossier/README.md` 列出九段内容：身份概览、人员与组织架构、招聘雷达、资金线索、地理位置、技术指纹、新闻时间线、关系网络、风险信号。

CLI 选项 `--sections <list>` 与 MCP 输入 `sections` 数组均接受相同的章节标识符集合；CLI 通过 `--json` 直接输出结构化 JSON，MCP 则始终返回结构化结果并由调用方决定如何渲染。

## See Also

- [Company Dossier 主仓库 README](https://github.com/ever-just/company-dossier/blob/main/README.md)
- [Methodology 总览（methodology/OVERVIEW.md）](https://github.com/ever-just/company-dossier/blob/main/methodology/OVERVIEW.md)
- [Claude Skill 资产说明](https://github.com/ever-just/company-dossier/blob/main/integrations/claude-skill/company-dossier/SKILL.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：ever-just/company-dossier

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/ever-just/company-dossier | host_targets=mcp_host, claude, chatgpt

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/ever-just/company-dossier | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/ever-just/company-dossier | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/ever-just/company-dossier | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/ever-just/company-dossier | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/ever-just/company-dossier | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/ever-just/company-dossier | release_recency=unknown

<!-- canonical_name: ever-just/company-dossier; human_manual_source: deepwiki_human_wiki -->