# @dogfood-lab/atlas 中文文档

规范地址：https://npmcn.com/package/%40dogfood-lab/atlas/

版本：1\.26\.0
npm 元数据更新时间：2026-10-01T08:29:28.359Z
中文译文更新时间：2026-11-12T16:13:30.089Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dogfood-lab/atlas
原文对照：https://npmcn.com/package/%40dogfood-lab/atlas/?lang=original
项目主页：https://github.com/dogfood-lab/testing-os
源码仓库：https://github.com/dogfood-lab/testing-os

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.9 MB，90 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：5 个
- 首次发布：2026-09-23T02:12:15.365Z
- 最新版本发布：2026-10-01T08:29:28.029Z
- 近 30 天下载量：2760（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

读取一个寄存器并写出说明它如何工作的页面:检查CI中的地图,通过MCP回答它的代理,并说在运行前会打破一个工作流程的内容.

## 安装

```sh
npm install @dogfood-lab/atlas
```

也可以使用：`pnpm add @dogfood-lab/atlas`、`yarn add @dogfood-lab/atlas`、`bun add @dogfood-lab/atlas`

## README

# @dogfood-lab/地图集

![An isometric blueprint on a dark drafting sheet: a door on the left where work enters, conveyors and rollers carrying it through a machine, and shelves of boxes on the right where it is kept.](https://raw.githubusercontent.com/dogfood-lab/testing-os/main/assets/atlas-hero.webp)

阿特拉斯读了一个git寄存器,写了一页,上面写着它是如何工作的: 是什么进来的,什么运行的,在哪里着陆的,谁读的,什么打破的,在哪里开始阅读的. 页面上的任何内容都不是一个人写的. 它来源于工作流程,清单,导入,写作和读取代码,和git历史,每当寄存器改变时都会被再生成.

该页面是针对任何需要了解他们没有写的寄存器的:新投稿人、审查人、操作员或模型.

## 使用

```bash
npx --yes @dogfood-lab/atlas init
npx --yes @dogfood-lab/atlas map
npx --yes @dogfood-lab/atlas check [--strict]
npx --yes @dogfood-lab/atlas explain <path-or-part> [--ref <ref>]
npx --yes @dogfood-lab/atlas gaps [path-or-part] [--ref <ref>]
npx --yes @dogfood-lab/atlas mcp
```

`init` 拟议 `atlas/boundaries.yaml`:寄存器中被命名的部分和拥有它们的花纹. 提案没有留下任何跟踪文件:每个项目的一个部分(工作空间成员,或载有清单的目录, `.csproj` 财务报告和审定财务报表 `go.mod` 包括)和每个目录项目留下的部分。 如果提案错误, 请编辑名称和名词 。 一个人可以添加的一行是 `summary`。 。 。 . `init` 还添加 `atlas/**` 改为现有 `.vscodeignore`, (中文(简体) ), `atlas/` 改为现有 `.npmignore` 当一切迹象全无的时候 `files` 列表,以及 `atlas/` 改为 `.prettierignore` 当它被使用的时候,你应当说它所增加的.

`check` 当承诺的地图不再匹配树时失败 。 当你打算改变后,就跑 `map` 并且执行重生成 `atlas/` 文件带有更改;从不手工编辑页面,从不修改代码以满足地图.

`map` 在下面写出四个文件 `atlas/`数字 :

| 文件 | 这是什么 |
| --- | --- |
| `README.md` | 该页. GitHub 当有人打开文件夹时会制作它 . |
| `page.json` | 网站和工具与数据相同. |
| `structure.json` | 每一个跟踪文件在部分,导入边缘在部件之间,门,起落地及其读者(每个作家和读者如何找到它: `ast`, (中文(简体) ), `config`, (中文(简体) ), `text` 或者说 `weak`),以及门运行在文件内部的呼叫顺序. 对于测试:每个工作流程的测试运行(运行者,到达的脚本和目标,以及它是否收集覆盖或写出JUnit结果),测试到达每个部分的运行者,测试文件没有运行工作流程而一个运行者的配置被删除,每个测试文件被写入框架,一个测试运行或拼写每个代码文件的名称,以及失败路径. 字节决定论. |
| `statistics.json` | 在过去的180天里有什么变化. |

每个文件都记录Atlas版本的制作情况(`engine`),而页面上的日期行名是:"从阿特拉斯公司的承诺中"

`check` 将已承诺的映射与工作树进行比较,当一个部分获得或失去依赖性,一个文件更改了部分,一个新文件属于没有部分,一个命名的部分没有匹配,或者一个文件属于两个部分时失败. 在测试工作中运行它,所以地图随代码而移动. 无寄存器 `atlas/` 目录是一个通知并退出 0,所以采用 Atlas reddens nothing.

`check` 也打印通知:留下退出代码的事实. 二是关于一个工作流程. `ATLAS_DOOR_TOOLCHAIN`: 工作将一个步骤所运行的工具不接受的节点版本标出, 从针头和工具的读取 `engines` 在步骤目录的锁文件("部署站点标出节点20并运行Astro building;astro 7.3.3需要Node QQ22.12.0并拒绝开始"). `ATLAS_DOOR_LOCKFILE_PLATFORM`: 任务运行 `npm ci` 在锁文件没有本地约束的平台上,在另一个系统中写上锁的标记。 第三个, `ATLAS_MAP_ENGINE_OLDER`,说承诺的地图 是用比运行的更老的阿特拉斯制作的。 每个名字,它读的行 和做什么 `check --strict` 当有通知时退出 1 。 门检查只读承诺的文件,从不预测跑道;他们无法判断的(没有设置步骤,只有跑道可以知道版本,是自行托管的还是集装箱跑道的,是他们无法读取的锁)被说成是没有判断的,从不是一种发现.

`gaps` 对寄存器、部件、目录或文件来说

-   线人所运行的,和所运行的跑道;
-   哪些部件和文件测试到达,以及如何:测试导入文件、运行文件、测试其中的跑者,或者在字符串图集中拼写它的名字;
-   编码漏洞,(在先在CI中起航或行驶的门道上,然后是扇入道、变化道和故障道),5个加上其余的数;
-   除了它们之外,测试文件没有工作流程运行,覆盖CI不收集,安装的命令没有运行.

事实第一。 在他们后面的每一个建议都标出它的规则(G1到G6在测试 -os's `docs/atlas-test-gaps.spec.md`),引发它的事实及其暗示的来源:房子标准首先,然后是舰队做什么,然后是外部文献. Reach不是测试练习文件的证明,所以阿特拉斯说"没有测试导入或运行这个",从来没有"未经测试". 它读到承诺的地图,或与 `--ref <ref>` 复制方的地图已经保存了, 从来没有地图, 写什么, 没有网络呼叫; `--json` 打印与字段相同的答案。 每项规则在发运前被扣入79个仓库的精密栏杆`docs/atlas-test-gaps.fleet-check.md` 在测试中.

`explain` 说一个文件,一个目录或一个部分在系统中,对于一个即将编辑它的人或在编码会话中的代理人:它的一部份,运行它或经过它的一部份的门,它的一部份进口和谁进口,它在哪里写,谁读,它内部的工作顺序,它用什么来改变. 鉴于代码写作或读取的地方,它也表示谁写作,谁读取. 它阅读了承诺的地图,再也不会看到地图,所以它立刻回答,并命名承诺的答案. `--json` 打印机器的相同事实。 鉴于工作流程文件,它会打印出门:什么触发它,每一个工作都有它的跑步,环境和被绑定的版本,它的步骤和它们运行的程序,它发送什么,它到达什么,它要求的许可,以及它上的任何发现.

与 `--ref <ref>`, (中文(简体) ), `explain` 财务报告和审定财务报表 `gaps` 从地图上解答复制人已经持有的回执, 例如 `origin/main`:文件在该裁判处被读取,没有取出任何内容,最后一行说哪个裁判回答,还有离结账有多远. 当检出时没有地图, 且其获取的上游保存着一个, 信件名称将首先引用 。 在不是一个 git 存储器但持有的目录中 `atlas/`,既回答又说"一棵出口树:历史和新鲜度没有检查".

## 对于代理人: `atlas mcp`

`atlas mcp` 让代理人在会话中,在“示范背景协议”上询问已承诺的地图问题。 特工的委托人开始和他谈话 它回答客户端提供的第一个根的 git 寄存器, 或者它开始于目录中 。 克劳德代码:

```bash
npm i -g @dogfood-lab/atlas
claude mcp add --scope user atlas -- atlas mcp
```

任何其他客户端 启动相同的命令, `atlas` 与论据 `mcp`在 Windows 上,一个全局 npm 命令是 `.cmd` 文件,客户端不能直接启动,所以要给客户端 `cmd /c atlas mcp`,或 `node` 和包裹 `cli.js` 财务报告和审定财务报表 `mcp`。 。 。 .

| 工具 | 它的答案是什么 |
| --- | --- |
| `atlas_overview` | 寄存器:其部件,每扇有触发器的门,其运行和发送以及所到达的多远,其工作的运行时间和任何发现,主流,以及从何处开始阅读. |
| `atlas_explain` | 一个文件、 目录或部分, 如 `atlas explain` 回答,包括谁写,谁读的地方。 一个工作流程文件被解答为它的门. |
| `atlas_reach` | 给定文件的改变会达到什么: 运行它们或穿过它们部分的门, 以及导入它们或读取它们写的东西的文件和部件, 生产和测试. |
| `atlas_changes` | 在一个承诺中承诺的地图与它所回答的地图之间的结构变化是:部件之间的导入(第一个新周期)、门、地方、部件的作者和读者,以及没有部分的新文件. |
| `atlas_check_change` | 在它被承诺之前,有什么变化:到达已更改文件的测试,运行它们的门,在获得或丢失的部分之间导入,文件没有部分,地图是否必须重新生成. 每一个更改的代码文件都写着测试是如何到达它的, 或者说没有测试, 以及它现在的故障路径。 它只读过修改过的文件 。 修改后的表单,工作流程,边界文件或配置引擎所读取的,或被删除的文件,得到"需要完全更新"代替. 当一个工作流程,一个 `package-lock.json` 或一个 `package.json` 在被更改的文件中,它还给出了他们所接触的门上的发现,从树上读出:一推前的那一刻. |
| `atlas_test_gaps` | 没有达到什么测试,什么应该,如 `atlas gaps` 答案是:事实按一个基础分组,然后将建议分开,每个建议都有其规则,触发事实及其来源. |
| `atlas_refresh` | 在背景中再次将检查结果映射到仓库外的缓存中。 后来的答案在新地图完成后使用,并再次调用它来报告进展. |

每个答案都从它的来由开始:地图的承诺,制作它的阿特拉斯版本,以及它的名字在地图后更改的任何文件. 每个工具,但是 `atlas_refresh` 带 `ref`,一个复制人已经持有:然后答案来自该复制人所在的地图,文件被读取,而出处则取出该复制人的名称,其承诺以及它离验收有多远(`atlas_check_change` 只有在退票时 才能拿到地图 当取回的上游持有不同的地图并进行验收时,出处会说出,并列出要询问的应答人的名字;阿特拉斯从不自行交换。 在不是一个 git 存储器但持有的目录中 `atlas/`,只读出地图回答并说出"一棵出口树:历史和新鲜度没有检查"的工具. 每一个事实都有其依据(`parsed`, (中文(简体) ), `declared`, (中文(简体) ), `text`, (中文(简体) ), `weak`, (中文(简体) ), `history`, (中文(简体) ), `unresolved` 或者说 `outside`每个答案都列出了阿特拉斯无法看到的问题。 答案为 JSON 最多 8 KB, 或 64 KB 与 `full: true`首先,最重要的一点。 切合的列表是这样说的,切取的列表带了其余的光标,在答案的顶端,在一个太大,无法显示整体的条目内. `part` 将条目保留在一个部分 `kind` 保持一种事实。 失败是指CLI所打印的相同字段的工具出错:代码,一句,什么变化和做什么.

侧车只读. Git 运行时只读取命令, 带有可选锁并关闭文件系统监视器, 所以一个问题从不写入 `.git`. 网络上没有任何东西,内部也没有模型:每个句子都出自地图. `atlas_refresh` 只写到它的缓存上, `%LOCALAPPDATA%/atlas` 视窗和其他 `$XDG_CACHE_HOME/atlas` 或者说 `~/.cache/atlas`,并拒绝存储器内的缓存。 服务器会讲MCP修订版 2026-07-28,以及2025-11-25和2025-06-18通过 `initialize`是一个局部过程;容器不运行.

## 内容

-   **门.** 每一工作流程 `.github/workflows/`: 它的触发器, 文件其步骤运行( 跟着 `npm run`, (中文(简体) ), `pnpm` 财务报告和审定财务报表 `yarn` 脚本通过根和工作空间脚本,构建输出回条目一个捆绑器名,再到它的tsconfig源头,以及一个将字面命令文本交给 shell 的助手)以及他们只检查的文件(林特斯,类型检查器),它在这里或克隆另一个寄存器,它发送什么,发布什么(npm, PyPI, bunchers.io, RubyGems, 容器图像, VS 代码市场, Open VSX, Hugging Face Hub, a Zenodo record),发布或部署;发布一个将一个构件上传到“将 X 构建到 MSI 和 NSIS 安装器并上传到发布”的释放,以及 `softprops/action-gh-release` 在发布事件上传到该发布时,不创建; a `git add` 不是写作, 和一个舞台上的地方 没有作家的名字 是人写的。 每个命令,都有一个明证`bin` 内 `package.json`, (中文(简体) ), `[project.scripts]` 内 `pyproject.toml`, (中文(简体) ), `[[bin]]` 财务报告和审定财务报表 `src/main.rs` 内 `Cargo.toml`),一个 Tauri 箱子的盒子作为桌面应用程序的人安装,每个货物示例作为命令的人运行 `cargo run --example`,以及 `run/main_scene` 内 `project.godot` 作为游戏,作为他们自己的门;bin nothing ship is "a command(或桌面应用) built (或桌面应用) built build from..., that nothing ship". 交给任何工具的跟踪文件是运行(当工具没有规则时被检查), `astro build` 财务报告和审定财务报表 `vite build` 运行网站, 一个工作门在一个活动 保持发送到该活动。 容器、轮子或二进制构建运行它开始的内容; 推动分支审查不是对寄存器的承诺; 包项仅在一个门出版时才是一个已公布的门; 工作空间成员按名称或通过一个 `for` a. 超过一个目录;是它本身的软件包门;在其步骤中遵循当地可重复使用的工作流程或复合动作; `turbo run`, (中文(简体) ), `next build`,以及 `pnpm <tool>` 没有读取这样的脚本。 每一个导出的文件在加载时启动一个程序的软件包是其条目,而不是库;私人成员的bin是一个捆绑到其已建路径的软件包中的命令. `cargo test`, (中文(简体) ), `run` 财务报告和审定财务报表 `bench` 执行和 `build`, (中文(简体) ), `check`, (中文(简体) ), `clippy` 财务报告和审定财务报表 `fmt` 检查,并使用 Cargo 的软件包选择, 但不包括一个二进制后级上传或软件包( “ buildings src/main. rs ”) ; 每个货物子命令, 但是 `fmt` 运行箱子的构建脚本; `cargo run --example` 执行示例; `cargo tauri` 在箱子之后运行 `beforeBuildCommand`· ; `godot --script`,GUT和gdUnit4 执行,以及跑者发现的测试 `DirAccess` 在运行的时间, `gdlint` 财务报告和审定财务报表 `gdformat` 检查,一个Godot导出是一个发送。 运出 `action.yml` (a) 工作空间外的已出版或已工作清单的箱是门; `dotnet`, (中文(简体) ), `python -m unittest discover` 财务报告和审定财务报表 `npm run` 参数是读取的; 一份私人清单没有发表任何内容。 每个工作的运行时间被记录:跑者标签和他们指的是的平台(一个自托管或集装箱跑者未解决),按名称排列的环境,版本 `actions/setup-node` 财务报告和审定财务报表 `actions/setup-python` pin,读取一个名称所在的版本文件,每个命令都运行在目录中。 跟踪 `package-lock.json` 改为: `engines` 工具中,一个步骤运行,哪个原生绑住锁.
-   **零部件和进口.** JavaScript, TypeScript, TSX, Python, Rust 和 GDScript, 用树标解析; 导入以同样的规则解决了运行时间用途( 设置工具源根和 Python 依赖性, 包括导入名称) , 包括工作空间包导出( )`package.json` `workspaces` 财务报告和审定财务报表 `pnpm-workspace.yaml`无 `node_modules`,因此在干净的克隆上,安装后和建造后,地图是相同的. 每个文件被读取为 git 存储它( CRLF 为 LF 除非 `.gitattributes` 语法拒绝的文件在它拒绝的构造重写后再次解析。 当生锈者把它建成时 生锈的进口跟随了模块树, `use` 结束 `crate`, (中文(简体) ), `self`, (中文(简体) ), `super` 财务报告和审定财务报表 `path =` 依赖关系; GDScript 解析 `res://` 从项目根起 `preload`, (中文(简体) ), `extends`一个场景 `[ext_resource]` 线条, `class_name` 和自动装载。 Astro前题, `file:` 自我依赖, `pathToFileURL` 进口, `sys.path` 插入、命名空间包和懒惰进口表格解析.
-   **落地地和读者.** 代码写入和读取的被跟踪的路径,在调用表达式中找到,然后通过加入和帮助者;一个被写入的文件名称在该文件上着陆,而不是其目录;原始的GitHub URL和引用的路径在文件中没有被解析,标记为被文本所发现,从没有被Markdown Prose中提及的路径. 从命令运行的目录所构建的路径,主目录,临时目录,返回一个的帮助者,一个环境变量或呼叫者通过的一个参数在外被计数;一个写到寄存器不计数,从不放置,并且门名它("写到输出/,没有跟踪"),即使被git忽略;Markdown链接和包装列表不是读者;导入,站点建设和测试都是. 一个命名有轨迹路径的配置文件是它的读取器;一个靴子陷阱(只有当文件缺席时)是无人的;一个在工作目录下拼写有轨迹位置的书写,如上所言. 主卫士身后写作的文字只记入管理文件的门; a `for-of` 超过字面值时按元素读取。 锈 `fs` 写作和阅读被跟踪 `Path` 加入并 `CARGO_MANIFEST_DIR`,通过一个结构的字段到设置它的字段,并通过一个参数到传递它的呼叫; Tauri's `app_data_dir()` 是主目录; `tauri_build::build()` 写入 `gen/schemas/`; GDS脚本 `FileAccess`, (中文(简体) ), `ResourceSaver` 财务报告和审定财务报表 `DirAccess` 打开 `res://` 降落在这里,和 `user://` 是玩家的数据目录,分开计算.
-   **历史.** 档案一并变化,一楼倒地,当历史薄薄后再倒地,页上写出信心.

## 它看不到的东西

在运行时间所建的路径被计算,而不是命名. 未解析的导入按其原因计算,同样,输入寄存器外的路径,写到未跟踪文件,并写到呼叫者所在位置,按其去处说: 命令运行的目录或主目录,其下写有目录,临时目录,或呼叫者所通过路径(然后说写有跟踪位置); 声称没有任何写作或导入文件被解析者所无法读取的文件所限定; 包脚本的 glob随着任务外壳和CI所遗留的测试文件被列出; HTTP 上的链接和未运行的部署文件被命名,并写入玩家的数据目录(`user://`)被计算为相隔. 页面以地图无法看到该寄存器的列表结尾,因此读者知道图片的边缘. 无法判断的门检查是这样说的,没有发现:没有设置步骤的工作,只有跑步者才能知道钉子(pin)`lts/*`, (中文(简体) ), `latest`,一个表达式),一个自托管或容器跑取器,一个它不能读取的锁文件. pnpm和纱线锁文件不读.

## 错误

每个失败都打印出一个形状:代码,一句,什么变化,做什么,以及退出代码. 出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出 没有出站线的通知形状相同.

```text
ATLAS_OVERLAP  A file belongs to more than one boundary.
  what changed:   shared/util.js: alpha, shared
  what to do:     narrow one boundary's globs, then atlas map
exit 1
```

## 私人储存库

`templates/atlas-refresh.yml` 是一个工作流程,可以绘制一个私人存储器在自己的CI内部,并输入该页面。 没有东西离开仓库.

整个私人舰队以集装箱形式运行 具有持续的内存: `ghcr.io/dogfood-lab/atlas` 绘制其目录 `fleet.yml`,保持每一个渲染及其历史 `/data` ,并为机队列表、每一页和代理索引(`/llms.txt`在港口上。 同一图像运行在挂载在 `/repo`。运行命令在仓库中运行 `docker/README.md`。 。 。 .

## 测试的一部分

阿特拉斯系统是一套 [狗食-工具/测试-os](https://github.com/dogfood-lab/testing-os)。页面的规格及其背后的推理是: `docs/atlas-page.spec.md` 在这里。 许可证:麻省理工学院.

## 常见问题

### @dogfood-lab/atlas 是什么？

读取一个寄存器并写出说明它如何工作的页面:检查CI中的地图,通过MCP回答它的代理,并说在运行前会打破一个工作流程的内容\.

### 如何安装 @dogfood-lab/atlas？

在项目目录运行 npm install @dogfood-lab/atlas，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 atlas、atlas-fleet，可以用 npx atlas 直接运行。

### @dogfood-lab/atlas 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dogfood-lab\_\_atlas 是否存在。

### @dogfood-lab/atlas 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dogfood-lab/atlas 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dogfood-lab/atlas 可以商用吗？

@dogfood-lab/atlas 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dogfood-lab/atlas 的下载量有多少？

根据 npm 官方下载统计，@dogfood-lab/atlas 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,760 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dogfood-lab/atlas 还在维护吗？

最新版本 1\.26\.0 发布于 2026/10/01（1 个月前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。