onboardmap

onboardmap

加入一个代码库，主要是解决“地理位置”问题：程序从哪里启动，测试在哪里，如何只运行其中一个测试，以及某个领域应该找谁咨询？onboardmap 根据你已有的信息绘制这张地图。你提供仓库的文件路径、你认为是入口点的路径、是否要记录的测试运行命令，以及一组路径前缀和对应的所有者（个人或团队）。onboardmap 会返回地图：按区域分组的文件、实际存在的入口点、你指定但不存在的入口点、所有测试文件、所有无人负责的文件，以及各项统计。它从不打开仓库；地图只基于你提供的信息生成。

文件所属的区域是其路径的第一个部分，因此 src/ 下的所有内容都属于 src 区域；位于顶层、路径中没有斜杠的文件，则属于名为 (root) 的区域。区域按升序排列；每个区域会报告其中的文件数量、测试文件数量、该区域内的入口点（顺序与指定顺序一致），以及该区域文件的不同所有者（同样按升序排列）。

文件符合以下任一条件，即计为测试文件。其基本文件名（最后一个斜杠之后的部分）包含 .test. 或 .spec.，例如 parser.test.ts。或者，其目录路径的某一部分恰好是 test、tests、__tests__ 或 spec，例如 tests/helpers/setup.ts。仅仅以字母 t-e-s-t 开头的名称，例如 testfoo.ts，或名为 testing 的文件夹，都不符合这两条规则，因此不算测试文件。

所有权通过前缀匹配，并采用最长匹配规则。如果文件与前缀相同、前缀以斜杠结尾且文件以该前缀开头，或者文件以该前缀加斜杠开头，则该前缀拥有此文件。因此，src 拥有 src/app.ts，但不拥有 srcfoo/app.ts。当多个前缀都匹配时，以较长的前缀为准；这样，较宽泛的所有者可以覆盖整个目录树，而较窄的前缀则可以将某个子树划分给其他人。没有任何前缀匹配的文件会列为无人负责。

你指定的入口点如果不在文件列表中，并不算错误——为新成员绘制地图时，正是了解文档中记载的起点并不存在的好时机。已找到的入口点会按你指定的顺序列出；未找到的入口点会另行按指定顺序报告。统计中的入口点数量只计算已找到的入口点。测试命令会原样返回，包括空字符串；如果未提供，则报告为 null。

格式错误的输入——文件列表缺失、为空或不是数组，文件路径不是字符串或为空，入口点列表无效，测试命令不是字符串，或者所有者映射中有空键、空值或非字符串值——会触发验证错误，并指出出错的路径，不会返回部分结果。两个文件路径相同则会报错并指出重复路径。未知的额外字段会被忽略。

CLI

npx @reneturcios/onboardmap map --input args.json
npx @reneturcios/onboardmap --version

args.json 包含完整的参数对象：

{
  "files": [
    "README.md",
    "src/index.ts",
    "src/parser.ts",
    "src/parser.test.ts",
    "tests/helpers/setup.ts",
    "docs/guide.md"
  ],
  "entry_points": ["src/index.ts", "src/main.ts"],
  "test_command": "npm test",
  "owners": {
    "src": "alice",
    "docs": "bob"
  }
}

地图将以 JSON 格式打印：

{
  "areas": [
    {
      "area": "(root)",
      "files": 1,
      "tests": 0,
      "entry_points": [],
      "owners": []
    },
    {
      "area": "docs",
      "files": 1,
      "tests": 0,
      "entry_points": [],
      "owners": ["bob"]
    },
    {
      "area": "src",
      "files": 3,
      "tests": 1,
      "entry_points": ["src/index.ts"],
      "owners": ["alice"]
    },
    {
      "area": "tests",
      "files": 1,
      "tests": 1,
      "entry_points": [],
      "owners": []
    }
  ],
  "entry_points": ["src/index.ts"],
  "missing_entry_points": ["src/main.ts"],
  "test_files": ["src/parser.test.ts", "tests/helpers/setup.ts"],
  "unowned_files": ["README.md", "tests/helpers/setup.ts"],
  "test_command": "npm test",
  "counts": {
    "files": 6,
    "test_files": 2,
    "areas": 4,
    "entry_points": 1,
    "unowned": 2
  }
}

退出代码：成功时为 0；运行时错误（包括输入文件不可读或无效，以及输入无效）时为 1；用法错误时为 2。

MCP 服务

npx -y @reneturcios/onboardmap mcp

MCP 客户端配置：

{
  "mcpServers": {
    "onboardmap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/onboardmap", "mcp"]
    }
  }
}

工具

• build_onboard_map — 根据调用方提供的仓库信息构建新手导览图：按区域分组的文件、入口点、测试所在位置，以及各项内容的负责人。

  • files（字符串数组，必填，至少 1 个条目）— 仓库文件路径，相对于仓库，顺序由调用方提供
  • entry_points（字符串数组，可选）— 调用方指定为入口点的路径；未提供表示没有入口点
  • test_command（字符串，可选）— 运行测试套件的命令，会原样显示在导览图中
  • owners（对象，可选）— 从路径前缀映射到负责人姓名；未提供表示没有负责人

  返回 {areas, entry_points, missing_entry_points, test_files, unowned_files, test_command, counts}， 其中 areas 包含每个区域对应的 {area, files, tests, entry_points, owners}，而 counts 为 {files, test_files, areas, entry_points, unowned}。

Docker

docker run -i ghcr.io/cloudcorprecords/onboardmap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/onboardmap map --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios