DomainAtlas

English | 中文

English

DomainAtlas maintains a dynamically updated business map of your project as it evolves through AI-assisted development. Its core purpose is to help you understand the project's business domains and capabilities. An append-only change ledger supports the map with evidence and a traceable history of changes.

Build an initial map with domainatlas build --input <file> after the DomainAtlas skill analyzes business responsibilities using a ready codebase-memory index, source and documentation. A business domain is the first level; capabilities can nest beneath it, up to five levels in total. Each branch stops where its business meaning is complete. Missing analysis input stops the build; automatic path/symbol inference is disabled. Completed Codex or Cursor tasks then extend the map incrementally. Initialization alone does not build a map; baseline construction does not replay Git history.

Installation (recommended)

Requires Node.js 22+ and Git. Install the published npm package; the CLI and built Web UI are included.

npm install -g domainatlas
domainatlas --help
domainatlas -v

Upgrade the published CLI and refresh already-installed host hooks (Codex and/or Cursor) in one step:

domainatlas upgrade
domainatlas upgrade --dry-run

upgrade does not initialize the current project and does not install hooks for hosts that were never configured. A source checkout skips the npm download and only refreshes hooks to that build.

The current CLI and global hook workflow target macOS/Linux; native Windows has not been verified.

Quick start

1. Install host hooks once (Codex, Cursor, or both):

domainatlas init -g --codex
domainatlas init -g --cursor

Review and trust the hooks in Codex /hooks or Cursor Settings → Hooks. User-level Cursor hooks do not run in Cloud Agents.

2. Initialize each project you want to map:

cd /path/to/your/git-project
domainatlas init

Continue working in the connected host. Initialized projects record completed turns automatically without a prompt prefix or skill invocation. If you initialize midway through a turn, recording starts with the next turn. Uninitialized projects and non-Git directories are skipped without creating files.

3. Build the existing project baseline and open your business map:

Use the DomainAtlas skill to prepare the input file. Every domain and capability in a new input needs a one-sentence summary, a plain-text description, and file evidence.

domainatlas build --input /absolute/path/to/baseline.json
domainatlas ui

Open http://127.0.0.1:4310 and select your project. Read the map's summaries, drill into each node's description, and inspect its evidence and related changes. Use domainatlas list to inspect the auxiliary ledger; Git determines whether records are pending or committed.

Global hook setup preserves other hooks and backs up the original configuration. It does not initialize the current project. Installed hook commands call a short launcher (~/.codex/domainatlas-hook or ~/.cursor/domainatlas-hook) that pins Node and the CLI, so Cursor/Codex do not need nvm on PATH. Use domainatlas init -g --codex --dry-run to preview installation, domainatlas init -g --codex --uninstall to remove its global entries, and domainatlas init --help for options. -g also accepts --global. When the workspace directory is not itself an initialized project, for example a folder holding several repositories, recording falls back to the initialized projects registered under that directory; a project the turn did not change stays untouched.

The DomainAtlas skill supports natural-language requests to build a business map; automatic recording is independent of skill invocation.

Use natural language with an AI tool

Install the DomainAtlas CLI, then install the bundled skill into your AI tool’s skills directory and reload the tool’s skills. Run the following prompts in the target project's workspace. The AI tool needs access to the project's files and permission to run local commands. In Codex, you can also prefix a request with $domainatlas; in other tools, use their skill-loading mechanism. Automatic turn recording uses host hooks (init -g --codex or init -g --cursor); loading the skill does not enable those hooks.

Initialize and build a business map with meaningful names:

Initialize DomainAtlas for this project, then analyze its source and documentation to build and save a business map. Name domains and capabilities by their business responsibilities; give every node a one-sentence summary and a detailed business description supported by file evidence. Flag uncertain conclusions. When finished, briefly tell me what was built.

The AI analyzes the business meaning and imports a baseline with build --input. The CLI itself does not call a language model. For the remaining examples, initialize the target project first; opening the shared workbench does not require initialization.

Preview a quick structural map:

Use DomainAtlas to preview a business map from up to 100 tracked source files in this project. Do not save the baseline. Tell me how many domains and capabilities were found and whether coverage is limited.

Open the business map:

Open the DomainAtlas workbench so I can select this project and browse its business domains, capabilities, and supporting evidence.

Inspect recorded changes:

Use DomainAtlas to summarize this project's recorded business changes. Show each change's original request, affected capabilities, and whether its record has been committed to Git. Only report information supported by the records.

Record a completed task when automatic recording is not enabled:

Use DomainAtlas to record the business change completed in this task. First check for an existing record to avoid duplication. Include the original request, actual changed files, and verified test results; leave unknown results unspecified.

Correct an existing record:

Use DomainAtlas to correct record change_ID: its affected scope should be “refund review,” not “all order management.” Verify the supporting evidence and append a correction that references the original record.

Replace change_ID and the example business names with real values. Once host hooks are installed and trusted and the project is initialized, continue normal development without a DomainAtlas prompt prefix; completed turns are recorded automatically.

Check the CLI version:

Check the DomainAtlas CLI version.

Upgrade DomainAtlas and already-installed hosts:

Upgrade DomainAtlas to the latest published version and refresh all already-installed host hooks.

Business map and supporting capabilities

• Business map: explore domains and nested capabilities in a read-only local Web UI. Cards show short summaries; details show business descriptions, evidence and related changes.
• Incremental updates: completed Codex or Cursor tasks supply change evidence. Turn-start Git snapshots and turn-end file versions identify incremental changes; duplicate completion events create one record.
• Code graph evidence: prefer the locally installed codebase-memory-mcp structured index without reading the full source tree. Requires codebase-memory-mcp 0.11.0 or newer; older builds answer with the pre-0.11 response format, and recording stops with an explicit version message instead of degrading silently. When unavailable, inspect changed paths only and emit low-confidence domain and capability nodes.
• Supporting change ledger: preserve immutable records, original requirements, feedback attribution, and evidence in .domainatlas/.
• Git traceability: derive the first commit containing each record and expose its actual author and committer. stage-records previews matching records and stages their facts with --write only when the full recorded before/after versions match HEAD and the index.

Business descriptions and evidence review

A new build --input manifest requires summary and description on every domain and capability. Describe each node by its business meaning: a broad responsibility explains its purpose and boundary; a scenario explains who triggers it and the outcome; a flow explains branches and state changes; a rule explains conditions and exceptions. Depth does not assign a fixed type. The description is plain text and may use paragraphs. Each node keeps its own tracked-file evidence; see the bundled skill for the input shape.

When a project opens or refreshes, the workbench compares evidence files in the latest baseline with their saved Git hashes, including uncommitted working-tree changes. Review needed means at least one file changed or was deleted; cannot verify means the evidence has no reliable file mapping or a file cannot be checked. An unchanged file proves only that its content still matches the baseline, not that the business description is correct. Review affected logic before rebuilding a complete baseline; a new import does not automatically rewrite old facts. Older nodes without descriptions remain readable and show a prompt to fill them in.

build --input replaces the whole projected baseline; it has no one-domain update option. A JSON file containing only one domain is useful with --dry-run for a preview, but writing it to an existing multi-domain project would hide the other baseline domains. To publish a revised module through the CLI, prepare and validate a complete manifest of all intended domains and capabilities; every imported node needs its own description and evidence. Never edit an older immutable baseline in place or fill unaffected nodes with invented text. --replace additionally archives incremental nodes and is only for an explicitly intended full-map rebuild.

Baseline files are local facts until Git tracks them. A target project's .gitignore may ignore .domainatlas/; check the target's tracking status and report it separately from the successful local write. Neither building nor opening the UI commits or pushes facts.

Web UI

Start the shared workbench from any directory:

domainatlas ui

Open http://127.0.0.1:4310, select a project, then view its business map and change history. Use domainatlas ui --port 4311 to change the port. New init calls register projects in the user-level directory. For older projects, run domainatlas ui --scan /path/to/projects once.

The UI uses React 19, TypeScript, Vite 7, Tailwind CSS 4 and Lucide; the local API uses Fastify 5.

The UI supports Chinese and English. On first use, browser regions CN, TW, HK and MO default to Chinese; other regions default to English. A Chinese browser language without a region also defaults to Chinese. The language selector remembers your choice. AI-generated business content follows the conversation language; switching the UI language does not translate stored facts.

Change ledger commands

The host integration boundary can ingest a completed task event:

domainatlas ingest --host cursor --request "Add refunds" --summary "Added refund review" --changed-file src/billing/refund.ts --test-command "pnpm test" --test-status passed

ingest-codex remains an alias for ingest --host codex. Corrections never overwrite an earlier record:

domainatlas ingest --kind correction --supersedes change_ID --request "Correct the affected scope" --summary "Added omitted capabilities" --changed-file src/billing/refund.ts

Inspect records with their Git-derived lifecycle:

domainatlas list

Preview records that match the currently staged code, then stage their fact files:

domainatlas stage-records
domainatlas stage-records --write

Check the installed version, inspect hook health, repair broken host installs, or upgrade the published package:

domainatlas -v
domainatlas status
domainatlas doctor
domainatlas upgrade
domainatlas upgrade --dry-run

--version and version are aliases for -v. status reports the CLI, Codex/Cursor hook launchers, and the current Git project. doctor rewrites already-installed host hooks and leftover launchers; it does not install a host that was never configured or initialize a project. upgrade also refreshes installed hosts after downloading a newer npm package. All three use CODEX_HOME / CURSOR_HOME (or ~/.codex / ~/.cursor) unless you pass --codex-home / --cursor-home.

From source (contributors)

Use this option when developing DomainAtlas. Requires Node.js 22+ and the pnpm version pinned in package.json (currently 11.13.0).

git clone https://github.com/chanshawoh/domain-atlas.git
cd domain-atlas
pnpm install --frozen-lockfile
pnpm build
pnpm domainatlas --help
pnpm domainatlas -v

To use this build on another project, run node /absolute/path/to/domain-atlas/dist/src/cli.js <command> from that project's Git root. Build before enabling hooks, and keep the checkout at a stable path because installed hooks reference the CLI by absolute path. domainatlas upgrade from a source CLI skips the npm download and only refreshes already-installed host hooks to this build.

Run checks in the tool repository:

pnpm test
# Optional: requires an installed codebase-memory-mcp 0.11.0 or newer
pnpm test:graph

For frontend development, start the API with node /absolute/path/to/domain-atlas/dist/src/cli.js ui from any directory, then run pnpm dev:web in a second terminal in the tool repository. Vite proxies /api to port 4310. This repository includes .codex/hooks.json; its hooks also require review and trust in Codex /hooks.

Maintainer release

The release script follows ImageForge MCP's check-first workflow:

bash script/release.sh
bash script/release.sh --publish

The first command builds, tests, audits production dependencies and installs a temporary npm tarball to verify the CLI and Web UI. Only --publish publishes that exact tarball to npm, after checking main, a clean checkout, remote synchronization, authentication and version availability. It never bumps versions, commits, pushes Git, or creates tags.

Deliberate MVP boundary

The hook protocol, stdin CLI, Git pre-commit behavior, and real graph-provider ingest are tested in isolated repositories. Hook trust and activation remain environment-specific. File versions describe changes observed during a turn; they do not prove authorship when multiple actors edit the same worktree. Multi-turn combined diffs and partial staging are conservatively left unmatched. MCP transport, database projections, and Web write operations remain future work.

中文

DomainAtlas 随 AI 辅助开发过程动态更新项目业务图，帮助你理解项目的业务领域和业务能力。业务图是核心能力；仅追加的变更账本是辅助能力，为业务图提供变更证据和可追溯的演进历史。

先配置 codebase-memory 并确认目标项目索引就绪，使用 DomainAtlas skill 分析业务语义，再通过 domainatlas build --input <文件> 导入初始业务图。业务域是第一层，下级能力可按实际业务逐层嵌套，总深度最多五层；各分支不必达到相同深度。缺少分析输入时停止构建，已禁用路径和代码符号自动推断。后续 Codex 或 Cursor 任务持续增量更新业务图。初始化本身不构建业务图；初始基线不回放 Git 历史。

安装（推荐）

需要 Node.js 22+ 和 Git。直接安装已发布的 npm 包，其中已包含 CLI 和构建好的 Web UI。

npm install -g domainatlas
domainatlas --help
domainatlas -v

一键升级已发布的 CLI，并刷新已经安装的宿主钩子（Codex 和/或 Cursor）：

domainatlas upgrade
domainatlas upgrade --dry-run

upgrade 不会初始化当前项目，也不会给从未配置过的宿主安装钩子。从源码运行时会跳过 npm 下载，只把钩子刷新到当前构建。

当前 CLI 和全局钩子流程面向 macOS/Linux，尚未验证 Windows 原生环境。

快速开始

1. 一次性安装宿主钩子（Codex、Cursor，或两者）：

domainatlas init -g --codex
domainatlas init -g --cursor

在 Codex /hooks 或 Cursor Settings → Hooks 中审核并信任钩子。用户级 Cursor 钩子不会在 Cloud Agent 中运行。

2. 初始化每个需要构建业务图的项目：

cd /path/to/your/git-project
domainatlas init

接着正常使用已接入的宿主。已初始化项目会自动记录已完成的轮次，无需提示词前缀或调用技能。如果在一轮任务中途初始化，从下一轮开始记录。未初始化的项目和非 Git 目录会被跳过，不会创建文件。

3. 构建已有项目的业务基线并打开业务图：

先用 DomainAtlas 技能准备输入文件。新导入的每个业务域与能力节点都要有一句话 summary、纯文本 description 和文件证据。

domainatlas build --input /absolute/path/to/baseline.json
domainatlas ui

打开 http://127.0.0.1:4310，选择项目后浏览业务领域和能力，并查看关联变更及证据。使用 domainatlas list 查看辅助账本，由 Git 判断记录处于待提交还是已提交状态。

全局钩子安装会保留其他钩子并备份原配置，不会初始化当前项目。写入的钩子命令调用短启动器（~/.codex/domainatlas-hook 或 ~/.cursor/domainatlas-hook），由启动器钉死 Node 和 CLI，因此 Cursor/Codex 不需要 PATH 里有 nvm。使用 domainatlas init -g --codex --dry-run 预览安装，使用 domainatlas init -g --codex --uninstall 移除其全局配置项，使用 domainatlas init --help 查看选项。-g 也可写为 --global。当工作区目录本身不是已初始化的项目时（例如一个存放多个仓库的外层目录），记录会回退到登记在该目录之下、已初始化的项目；本轮没有改动的项目不会产生记录。

DomainAtlas 技能支持通过自然语言请求构建业务图；自动记录独立于技能调用。

在 AI 工具中用自然语言使用

安装 DomainAtlas CLI 后，将包内技能复制到 AI 工具的 skills 目录，并让工具重新加载技能。在需要分析的目标项目工作区中发送下面的提示词，AI 工具需能读取项目文件并执行本地命令。Codex 中也可在请求前加 $domainatlas，其他工具按各自方式加载技能。当前自动轮次记录通过宿主 hooks 接入（init -g --codex 或 init -g --cursor），仅加载技能不会启用这些钩子。

首次初始化并构建有业务含义的业务图：

为当前项目初始化 DomainAtlas，然后分析源码和项目文档，构建并保存业务图。按实际业务职责命名业务领域和能力，为每个节点写一句话摘要及有文件证据支撑的业务详述，标明不确定的结论。完成后简短告诉我构建了什么。

AI 负责分析业务语义，再通过 build --input 导入基线，CLI 本身不调用大模型。下面涉及项目数据的示例需先初始化目标项目；仅打开统一工作台无需初始化。

快速预览结构，不保存业务图：

用 DomainAtlas 预览当前项目的业务图，最多分析 100 个已跟踪源码文件，不保存基线。告诉我发现了多少个业务领域和能力，以及分析范围是否有限。

打开业务图浏览：

打开 DomainAtlas 工作台，让我选择当前项目，查看业务领域、业务能力和支撑证据。

查询已经记录的业务变化：

用 DomainAtlas 汇总当前项目已记录的业务变更，说明每项变更的原始需求、影响的业务能力，以及记录是否已提交到 Git。只报告记录中有证据的信息。

未启用自动记录时，记录已完成的任务：

用 DomainAtlas 记录本次任务已完成的业务变化。先检查是否已有记录，避免重复；记录原始需求、实际修改的文件和已验证的测试结果，未知结果不要补写。

更正已有记录：

用 DomainAtlas 更正记录 change_ID：影响范围应为“退款审核”，不是“整个订单管理”。请核对支撑证据，追加一条引用原记录的更正。

将 change_ID 和示例业务名称替换为真实内容。已安装并信任宿主 hooks、且项目已初始化时，后续正常提出开发需求即可，完成的轮次会自动记录，无需每次加 DomainAtlas 前缀。

查看 CLI 版本：

查看 DomainAtlas CLI 的版本号。

升级 DomainAtlas 并刷新已安装宿主：

将 DomainAtlas 升级到最新已发布版本，并刷新所有已经安装的宿主钩子。

业务图与配套能力

• **项目业务图：**在只读本地 Web UI 中逐层浏览业务域和能力；卡片展示摘要，详情展示业务说明、证据和关联变更。
• **增量更新：**已完成的 Codex 或 Cursor 任务提供变更证据，通过轮次开始时的 Git 快照和结束时的文件版本识别增量变更；重复的完成事件只生成一条记录。
• **代码图谱证据：**优先使用本地 codebase-memory-mcp 结构化索引，无需读取完整源码树；要求 codebase-memory-mcp 0.11.0 或更新版本，更早的版本返回 0.11 之前的响应格式，记录会明确提示版本过旧并停止，而不是静默降级；不可用时仅检查变更路径，生成低置信度的业务领域和能力节点。
• **辅助变更账本：**在 .domainatlas/ 中保留不可变记录、原始需求、反馈归属和证据。
• **Git 追溯：**推导首次包含各条记录的提交，展示实际作者和提交者。stage-records 预览匹配记录，只有完整的变更前后版本与 HEAD 和暂存区一致时，才通过 --write 暂存其事实文件。

业务说明与证据复核

新 build --input 输入要求每个业务域和能力节点都有 summary 与 description。描述按节点的业务含义组织：职责节点说明目标和边界，场景说明参与者、触发条件和结果，流程说明分支与状态变化，规则说明判断条件和例外；不能只按层号套固定模板。详述是可分段的纯文本。每个节点都要有自己的已跟踪文件证据；输入格式见包内技能。

打开项目或点击刷新时，工作台会将最新基线的证据文件与保存的 Git 哈希比较，未提交的工作区修改也会触发提醒。“需复核”表示文件已变化或删除；“无法核验”表示缺少可靠文件映射，或文件无法检查。文件未变化只证明内容与基线一致，不代表业务说明一定正确。应先核实受影响逻辑，再重新分析并导入完整基线；导入不会自动改写旧事实。旧节点没有业务说明时仍能读取，并提示待补充。

build --input 会替换整份基线的展示结果，目前没有“只更新一个业务域”的 CLI 参数。只有一个业务域的 JSON 可用 --dry-run 预览；若直接写入已有多业务域的项目，其他基线业务域会从当前地图消失。要通过 CLI 正式更新一个模块，须准备并校验包含所有目标业务域和能力的完整输入，每个导入节点都要有自己的说明和证据。不要就地修改旧的不可变基线，也不要为未分析的节点编造占位描述。--replace 还会归档增量节点，仅适用于明确要重建整张图的情况。

基线写入本地不等于进入 Git。目标项目的 .gitignore 可能忽略 .domainatlas/；应单独核对并报告跟踪状态。构建或打开工作台都不会自动提交、推送事实。

Web UI

在任意目录启动统一项目工作台：

domainatlas ui

打开 http://127.0.0.1:4310，从全部项目列表进入业务图和历史变更。使用 domainatlas ui --port 4311 修改端口。新版本 init 会登记项目；旧版项目可通过 domainatlas ui --scan /项目父目录 一次性发现。

UI 使用 React 19、TypeScript、Vite 7、Tailwind CSS 4 和 Lucide；本地 API 使用 Fastify 5。

界面支持中文和英文。首次使用时，根据浏览器地区，CN、TW、HK、MO 默认中文，其他地区默认英文；未指定地区的中文浏览器语言也默认中文。可通过语言选择器切换并记住选择。AI 生成的业务内容跟随会话语言，切换界面语言不会翻译已有事实。

变更账本命令

宿主集成入口可以接收已完成的任务事件：

domainatlas ingest --host cursor --request "新增退款功能" --summary "已新增退款审核" --changed-file src/billing/refund.ts --test-command "pnpm test" --test-status passed

ingest-codex 仍是 ingest --host codex 的别名。更正记录不会覆盖此前的记录：

domainatlas ingest --kind correction --supersedes change_ID --request "更正影响范围" --summary "补充遗漏的业务能力" --changed-file src/billing/refund.ts

查看记录及其由 Git 推导的生命周期：

domainatlas list

预览与当前暂存代码匹配的记录，再暂存其事实文件：

domainatlas stage-records
domainatlas stage-records --write

查看已安装版本、检查钩子健康、修复异常宿主安装，或升级已发布的包：

domainatlas -v
domainatlas status
domainatlas doctor
domainatlas upgrade
domainatlas upgrade --dry-run

--version 和 version 是 -v 的别名。status 报告 CLI、Codex/Cursor 钩子启动器，以及当前 Git 项目。doctor 重写已经安装的宿主钩子和残留启动器，不会给从未配置过的宿主装钩子，也不会初始化项目。upgrade 在下载更新的 npm 包后也会刷新已安装宿主。三者都使用 CODEX_HOME / CURSOR_HOME（未设置时为 ~/.codex / ~/.cursor），也可用 --codex-home / --cursor-home 覆盖。

源码安装（开发者）

开发 DomainAtlas 本身时使用此方式。需要 Node.js 22+ 和 package.json 固定的 pnpm 版本（当前为 11.13.0）。

git clone https://github.com/chanshawoh/domain-atlas.git
cd domain-atlas
pnpm install --frozen-lockfile
pnpm build
pnpm domainatlas --help
pnpm domainatlas -v

要将此构建用于其他项目，请在目标项目的 Git 根目录运行 node /absolute/path/to/domain-atlas/dist/src/cli.js <command>。启用钩子前先构建，并保持源码目录路径稳定，因为已安装的钩子通过绝对路径引用 CLI。从源码运行 domainatlas upgrade 会跳过 npm 下载，只把已安装宿主钩子刷新到当前构建。

在工具仓库中运行检查：

pnpm test
# 可选：需要已安装 codebase-memory-mcp 0.11.0 或更新版本
pnpm test:graph

前端开发时，在任意目录执行 node /absolute/path/to/domain-atlas/dist/src/cli.js ui 启动 API，再在工具仓库的另一个终端执行 pnpm dev:web。Vite 将 /api 代理到端口 4310。本仓库包含 .codex/hooks.json，其钩子同样需要在 Codex /hooks 中审核并信任。

维护者发布流程

发布脚本沿用 ImageForge MCP 先检查再发布的流程：

bash script/release.sh
bash script/release.sh --publish

第一条命令会构建、测试、审计生产依赖，并安装临时 npm tarball 以验证 CLI 和 Web UI。只有 --publish 才会将该 tarball 发布到 npm，发布前会检查当前分支是否为 main、工作区是否干净、是否与远端同步、认证状态及版本是否可用。脚本不会自动升级版本、创建提交、推送 Git 或创建标签。

MVP 的明确边界

hook 协议、stdin CLI、Git pre-commit 行为以及真实代码图提供方的数据接入均已在隔离仓库中测试。hook 的信任和启用仍取决于具体环境。文件版本描述的是一轮任务中观察到的变更；当多个参与方编辑同一工作区时，它们不能证明作者归属。跨多轮的合并差异和部分暂存采取保守策略，不予匹配。MCP 传输、数据库投影和 Web 写入操作仍属于后续工作。