项目定位与目标

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

资料来源：README.md:7-13

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

核心架构与交付形态

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

资料来源：README.md:17-23

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

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

资料来源：README.md:36-43

快速开始

CLI 安装与运行

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

npx company-dossier acme.com

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

资料来源：packages/company-dossier/README.md:21-27

常用选项包括：

# 指定输出目录并静默运行
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

CLI 帮助文档通过 packages/company-dossier/src/cli.ts:5-30 暴露完整选项列表，包含 --out、--json、--sections、--max-pages、--no-social-probe、--quiet 等开关。

作为库使用

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

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

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

MCP 服务器集成

company-dossier 内置一个符合 Model Context Protocol 标准的 MCP 服务器，通过 stdio 暴露单一工具 build_dossier，允许 ChatGPT、Claude 等 AI Agent 直接调用：

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

工具输入参数示例：

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

资料来源：packages/company-dossier/README.md:81-94

工具注册逻辑由 packages/company-dossier/src/mcp-server.ts:13-37 集中实现，使用 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

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

数据采集流水线

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 的执行流程为：抓取首页 → 抓取 sitemap.xml → 解析内链 → 按 maxPages（默认 25）抓取内部页面，提取标题、描述、邮箱、电话、社交链接、schema.org JSON-LD 等。任一采集器失败都不会抛出异常，而是将错误记录在 result.error 中，最终汇总为档案中的"缺口"。

常见配置与失败模式

资料来源：packages/company-dossier/src/cli.ts:18-25

典型失败模式包括：网络受限的源（如被 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

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. 模块化架构

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

模块间通过纯函数 + 显式接口解耦：采集器只返回数据对象（如 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 图展示端到端的数据流。

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
• 包级 README：CLI 速查、九段说明、库用法与 MCP 集成 packages/company-dossier/README.md
• 集成目录：Claude Agent Skill 与 ChatGPT Apps SDK 接线 integrations/README.md

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

一、定位与职责

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)。

资料来源: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

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 只生成目标章节,节省时间,适合快速技术盘点。

概述

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

Pitfall Log / 踩坑日志

项目：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