mellos-mapping

Mellos Mapping

English | 简体中文

一张实时、原生于终端的自底向上开发地图，适用于 Claude Code、ChatGPT 桌面版 Codex 模式和 Codex CLI。

Claude 构建系统时，对话旁边的分屏会显示系统的分层依赖关系图：底部是原始层，只能向下指向的依赖边，表示设计内容的幽灵节点，正在构建内容上的旋转指示器，以及表示已构建并通过验证内容的纯绿色节点。

真实会话：左侧是 Claude Code，右侧是地图面板。L0 已通过验证，L1 刚刚亮起，上方所有内容仍是幽灵节点。

原因

大多数进度报告都是任务列表——一种自上而下的视角。Mellos 地图则反向生长：上层节点只能建立在下方节点之上，这张图让开发规范清晰可见：

• 幽灵设计会在任何代码出现之前呈现。 Claude 会先将整个预期结构声明为虚线幽灵节点；设计还只是一张图时，你就可以否决不合理的设计。
• 旋转指示器标示 Claude 当前关注的位置。 一眼就能看出“它现在在做什么，以及基于什么进行？”
• 完成意味着通过验证。 只有具备证据（测试运行通过），节点才会变为纯绿色。如果后续工作破坏了基础，节点就会变红——旋转的上层楼面之下出现裂缝的基础，是最诚实的状态报告。
• 地图是账本，而不是裁判。 工具只会拒绝结构损坏（边向上指、秩重复）。工作流遵循 Claude 的规范，在捆绑的技能中定义；违规会变得可见，绝不会被悄悄阻止。

安装

克隆与你的宿主对应的分支，然后运行一条命令。无需构建。

分支	适用对象	克隆后运行的命令
main	共享源码 / 任一宿主	node install.mjs chatgpt-app 或 node install.mjs claude
claude	Claude Code	node install.mjs
chatgpt-app	ChatGPT 桌面版，Codex 模式	node install.mjs
需要在 18.x 系列中使用 Node.js 18.17+，或使用 Node.js 20.3+，并确保相应的宿主 CLI 位于 PATH 中。支持的平台包括 Windows 10+、macOS 13.0+，以及使用 glibc 2.28+ 的 Linux；每个平台均支持 x64 或 arm64。操作系统还必须满足所选 Node.js 版本的要求。发布包附带原生锁定绑定；无需本地编译。安装程序会检查
发布包完整性和全部八个 MCP 工具，将运行时保留在克隆目录之外，
并配置宿主。安装后请开始新的对话。
参见发布和分支说明。

也可以通过 Claude Code 的市场安装：

在任意 Claude Code 对话中输入两行：

/plugin marketplace add GuangminJu/mellos-mapping
/plugin install mellos-mapping@mellos-mapping

或者在终端中输入一行：

claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping

需要在 PATH 中使用相同的 Node.js 和平台版本（使用原生 Claude Code 时，请单独安装 Node）。无需构建步骤：dist/ 已提交，因此克隆后即可运行 — dist/server.mjs（MCP 服务）、dist/watch.mjs（面板）、 dist/mmap.mjs（mmap 开关）、dist/hook-session-start.mjs（由 hooks/hooks.json 注册的 SessionStart 钩子），以及 dist/store-paths.mjs（存储的路径词汇表，纯 Node 面板启动器会导入它，而非重复声明文件名）。

**omp（Oh My Pi）**读取的插件布局与 Claude Code 版本附带的相同 — 同一市场目录、.mcp.json、技能和斜杠命令 — 因此一个 发布版本即可服务于两个宿主：

omp plugin marketplace add GuangminJu/mellos-mapping
omp plugin install mellos-mapping@mellos-mapping

此安装跟随 main，发布时会更新版本号。若要固定版本，请添加该版本的检出副本 — GitHub Release 中的 Claude Code 版本 ZIP，或检出发布标签的克隆：

omp plugin marketplace add "<checkout or extracted release directory>"
omp plugin install mellos-mapping@mellos-mapping

omp 不会读取 hooks/hooks.json，因此会话说明段落通过插件的 omp 宿主适配器提供（在 package.json#omp.extensions 中声明）：它使用与 Claude 钩子相同的存储、策略文本和 mmap 垫片安装方式。面板也是同一个位于会话旁边的终端分屏。请将其作为插件安装：omp plugin link 和 npm 包都不是插件，使用其中任一方式都会导致工具缺失。参见 omp 安装和限制。

pi不会读取上述布局：它加载扩展，而且按设计不自带 MCP。因此，插件通过 MCP 与自身通信 — 在 package.json#pi.extensions 中声明的扩展（dist/pi-extension.mjs）会在会话目录中启动同一个 dist/server.mjs，使八个 mmap_* 工具与原有的八个完全相同，名称也相同；并使用与 Claude 钩子打印的相同存储和相同策略文本，生成会话说明段落：

pi install npm:mellos-mapping

添加 -l 可将其安装到当前项目，而不是所有项目，然后开始新的会话：pi 会在会话开始时发现软件包。软件包中的 skills/ 和 commands/ 也会随之安装 — 使用相同的地图规范，并提供相同的斜杠命令 /mmap。参见pi 安装和行为。

安装后的第一个会话会询问你一个问题 — 地图应以多积极的方式打开 — 并将答案记录下来，供你今后打开的每个项目使用。从此以后，钩子会自动将其带入每个新会话；无需逐个项目设置。参见 设置：选择地图的打开时机。 mmap 终端命令（窗格的打开／关闭切换开关）会在 Windows 上自行安装：同一个钩子会在会话启动时检查 shim 是否缺失或指向旧版本的安装，然后将 mmap.cmd（cmd、PowerShell）和 mmap（git-bash）写入 %LOCALAPPDATA%\mellos-mapping\bin，将该目录追加到你的用户 PATH，并通过助手告知你。PATH 更改只会影响新进程——运行中的 Windows Terminal 新标签页仍会继承旧环境，因此在首次运行 mmap 前，请完全退出终端应用并重新打开。PATH 编辑保留了安装程序的保证：如果该条目已存在，则不会进行任何操作；如果 PATH 存在 setx 会破坏的情况（%VARIABLE% 引用被展平、长度超过限制而遭截断），则会直接拒绝修改。

PATH 修改被拒绝并非无路可走：此时会将同样的两个 shim 写入 %LOCALAPPDATA%\Microsoft\WindowsApps（或 ~/.local/bin）——这个目录已列在你的 PATH 中——因此无需更改 PATH，在新终端中即可运行 mmap。PATH 较长的机器恰好最容易遇到这种情况，也最需要这种处理方式。此命令以要打开的页面作为参数（mmap omp-host-support）；如果窗格已打开，则会将其关闭。

其背后的安装步骤仍然是独立命令，适用于钩子未涵盖的情况——例如 --uninstall，或 shim 仍保留但你已移除 PATH 条目，需要重新添加：

node "<plugin dir>/scripts/install-mmap-command.mjs" [--uninstall]

（--json 会将安装结果作为一行 JSON 输出，而不是普通文本——钩子本身调用此命令时使用的就是这种模式。）npm i -g mellos-mapping 也能通过 bin 提供相同的 mmap，无需 shim。

更新

claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping

需要分两步，因为 plugin update 会与本地缓存的 marketplace 克隆进行比较——第一个命令才会实际拉取此仓库。重启 Claude Code 以应用更新。版本发布通过在 main 上提升版本号完成。（在应用内，/plugin 会打开相同的管理界面。）

omp 更新也分为两步：

omp plugin marketplace update mellos-mapping && omp plugin upgrade mellos-mapping@mellos-mapping

先关闭窗格（在窗格中按 q）：监视器从插件副本运行，而在 Windows 上，已打开的文件无法重命名移走，因此在窗格打开时尝试升级可能会失败并报 EPERM，导致插件缓存变空——可通过 omp plugin install mellos-mapping@mellos-mapping --force 修复。接下来：第一个命令刷新目录，第二个命令从目录重新安装。除非 marketplace.autoUpdate 为 off，否则 omp 也会在启动时刷新超过一天未更新的目录条目；在默认的 notify 模式下，此项检查只会将发现写入调试日志，因此 marketplace update 才是让更新显示出来的步骤。upgrade 不会比较版本：它会强制重新安装目录中指定的内容，因此版本发布以提升版本号标识，而非受其限制。之后重启 omp，并重新打开仍显示旧版包的窗格（在窗格中按 q，然后再次运行 mmap_open）。

pi 会直接更新其安装的包，中间无需 marketplace：

pi update npm:mellos-mapping

这是 npm 来源；git 来源会由 pi 自己的更新机制与设置中指定的 ref 保持一致，而带版本号的规格（npm:[email protected]）则会固定版本并跳过更新。之后重启会话：会话拥有它启动的地图服务进程，因此仍在运行的会话会继续使用启动时的副本，直到会话结束。

从 0.19 升级

0.20 将存储目录从 .claude/ 移到了 .mellos/——映射属于这个工具，而非某个客户端。服务和监视器会在启动时各自执行一次迁移，并在迁移时恰好向 stderr 输出一行信息 （mellos-mapping: moved the legacy .claude map store to .mellos/ — commit the move.）：

0.19 及更早版本	0.20 及更高版本
.claude/mellos-mapping.json	.mellos/map.json
.claude/mellos-mapping.pages/	.mellos/pages/
.claude/mellos-mapping.config.json	.mellos/config.json

不会合并或覆盖任何内容：如果项目已经有 .mellos/ 存储（映射、页面或配置），就会保持原样，无论旧目录中还有什么内容。如果你将映射保存在 git 中，请提交这次迁移—— git add -A .claude .mellos 会将其记录为重命名，而不是一堆删除项加未跟踪文件。

这次迁移是这两个进程唯一会访问 .claude/ 的时候。之后，工具只会写入 .mellos/，绝不会写入启动时解析出的项目目录之外。

ChatGPT App · Codex 模式

这是 ChatGPT 桌面应用（也称 Codex App）中的 Codex 模式。 从源分支运行以下命令；在 chatgpt-app 上，请省略主机参数。该命令会配置桌面技能、市场和 8 个 MCP 工具。

node install.mjs chatgpt-app

开始新的对话。桌面技能默认使用 web-terminal： mmap_open {surface: "web-terminal", page: "<slug>"} 会启动本地服务， 然后 AI 会在当前对话的右侧浏览器面板中打开其 URL。 mmap 终端会自动启动，并带有自己的字号选择器； 无需手动粘贴或使用 Computer Use。图形 SVG、原生终端和 Markdown 仍可使用。对于较旧的 MCP 架构，运行 node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>。 排队的面板请求并不能证明用户看得到面板。 请参阅桌面端安装与限制。

对于 Windows Terminal 中的 Codex CLI（而非桌面集成终端），运行 node <plugin root>/scripts/open-pane.mjs <project dir>——它会拆分 承载会话的终端窗口，并让键盘焦点保持在对话上。 如果无法识别或聚焦该窗口，命令会报告失败，而不会在其他位置打开。 --window 可明确选择单独的窗口。添加 --page <slug> 可在特定页面上打开；如果面板已打开，再次使用 --page 运行会将属于此控制台的面板切换到指定页面。在另一个会话或单独窗口中打开的映射不算此拆分面板。面板会自动跟随正在编写的页面——也就是 Agent 当前正在操作的映射；按 f 可切换此行为（手动切换页面也会将其关闭），或使用 --no-follow 启动。在其他环境中，从项目目录的第二个终端（或任意终端拆分窗口）运行 node <plugin root>/dist/watch.mjs。两者接受相同的标志——请参阅 面板标志。

桌面 Markdown 映射

用户选择文档界面时，技能会使用 mmap_open {surface: "markdown", page: "<slug>"}，并在当前对话旁边打开返回的文件。 文档内嵌彩色 SVG 依赖关系映射，以及模块详情、证据和子页面链接。它无需 Web 服务、 浏览器渲染进程、Mermaid 支持或额外的运行时依赖。

成功的 MCP 映射写入会重新生成 .mellos/previews/ 中已启用的预览； JSON 仍是事实来源。图像节点是静态的。文件可见性和查看器自动刷新由桌面宿主负责。请参阅 桌面映射指南，了解重新生成、 缓存行为和限制。

可选的交互式 Web 查看器

还可以使用交互式 Web 查看器，通过 mmap_open {surface: "web", page: "<slug>"} 或 node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug> 启动。 在宿主的右侧浏览器面板中打开它返回的 URL。它支持实时更新、 平移/缩放、悬停和固定详情、搜索、依赖项高亮、 筛选、分组概览、子映射和主题。使用 node "<plugin root>/dist/web.mjs" "<project directory>" --stop 停止。 Markdown/SVG 和终端工作流仍然可用；所有界面共享相同的映射数据。请参阅Web 查看器详情。

任何 MCP 客户端

该服务发布在 npm 上，因此任何 MCP 客户端（Cursor、Windsurf、Zed、 Gemini CLI 等）都可以通过标准的 stdio 配置项运行它：

npx -y mellos-mapping

映射文件会保存到客户端会话的工作目录 （.mellos/map.json）。在同一个项目中打开实时面板：

npx -y -p mellos-mapping mellos-mapping-watch

服务按以下顺序选择项目目录：MELLOS_MAPPING_CWD （显式覆盖项，适用于从固定目录启动服务的客户端），然后是 CLAUDE_PROJECT_DIR（Claude Code 为插件 MCP 服务设置的变量），最后是服务进程自身的工作目录。当客户端在工作项目以外的位置启动服务时，请设置 MELLOS_MAPPING_CWD。

技能/规范层仅适用于 Claude Code + Codex；其他客户端可使用这八个 mmap_* 工具和面板，并自行提供提示词。

使用方法

1. 让 Claude 构建一些并非轻而易举的内容。捆绑的技能会让 Claude 声明幽灵设计，并在工作过程中保持映射更新。
2. 面板会自动打开。每次写入都会告诉 Claude 是否有人在看（请参阅谁在观看）；如果没人看，Claude 就会通过 mmap_open 打开面板或切换其目标——你无需记住这件事。你可以在任何终端中使用 mmap 自行打开或关闭它，也可以在对话中使用 /mellos-mapping:mmap（Windows 上使用 Windows Terminal 分屏，tmux 内使用 tmux 分屏，Pebrel 内使用 Pebrel 分屏，或者打印一条命令供你在第二个终端中运行）。在 Windows 上，无论打开了多少个窗口，面板都会在托管你当前会话的终端窗口中打开；添加 --window 可将映射放到独立窗口中。如果字体缺少框线字符，建议使用 --ascii。
3. 查看节点从底部开始亮起。如果图示让你担忧，就中断操作——这正是它的用途。

在 Linux 和 macOS 上，mmap_open 和 mmap 会自动使用 tmux。启动器会定位继承的 TMUX/TMUX_PANE；如果工具进程丢失了这些变量，则会在默认 tmux 服务器上查找唯一附加的会话。默认情况下会在右侧分屏，并保留输入焦点；--window 会创建一个新的 tmux 窗口。重复打开时，会复用绑定到该源窗格或会话窗口的监视器。

如果有多个附加会话，或使用了自定义 tmux 套接字，请在 MCP 服务的环境中设置以下变量（更改后重启服务）：

变量	含义
MELLOS_MAPPING_TMUX_TARGET	显式指定 tmux 会话或窗格，例如 work:2.1 或 %7
MELLOS_MAPPING_TMUX_SOCKET	套接字的绝对路径，例如 /tmp/my-tmux/socket

在 Pebrel 内，mmap_open 和 mmap 会通过 Pebrel 的运行时 CLI（PEBREL_CLI）拆分托管对话的窗格。启动器会根据进程树确认该窗格所在的窗口，将输入焦点还给对话，并在新窗格的 shell（PowerShell、 cmd 或 POSIX shell）中输入监视器命令；该命令会随映射一起退出，从而关闭窗格。 --window 会打开一个新的 Pebrel 窗口。在 tmux 内，则由 tmux 负责分屏。 有歧义的会话、已分离的会话以及缺少 tmux 时，都会显示具体错误和完整引用的监视器命令，其中包含项目和请求的页面，可粘贴到任意可见终端中。地图写入仍然可用；打开失败后，助手只会在环境发生变化或你提出要求时重试。

该窗格支持鼠标操作（xterm SGR 任意事件跟踪——htop 和 tmux 使用的同一协议）：

输入	操作
悬停在节点上	突显其连线；在地图下方预览其详情
点击节点	固定节点——鼠标移开后详情仍会显示
点击空白处 / Esc	取消固定；若没有固定节点，按 Esc 可退出下钻
滚轮 / + -	缩放，以焦点节点为锚点（见下方的缩放阶梯）
左键拖动	地图超出窗格大小时，抓取并平移
Shift+滚轮	垂直滚动
滚轮倾斜（水平）	水平平移
hjkl / 方向键	微调视图
Tab / Shift+Tab / 1-9 / 点击标签页	切换页面（并行地图）
在标签页行上滚动 / 点击 ‹ ›	浏览溢出的标签页栏，但不切换页面
f	切换自动跟随（见页面）
x，或点击活动标签页上的 ×	请求删除屏幕上的页面；在窗口期内再次按下后，其文件会被删除（见页面）
双击 ⊞ 节点	下钻到其子地图（子页面）
Backspace / Esc	退出上一次下钻
拖动 ⋯ 分隔线	调整详情面板大小——向上拖动可完整阅读较长的设计说明
0	重置平移和缩放
q / Ctrl+C	退出窗格

其他所有按键都会被有意忽略：窗格无法识别的转义序列（功能键、Home/End、PgUp/PgDn、Insert/Delete、带修饰键的方向键）会被整体接收并忽略，而不会将其负载字节读作快捷键。

缩放会先缩放图像，只在缩放阶梯的两端切换显示模式，因此每个级别仍会显示有意义的数据：

detail+ ← detail ← 100% ← 85% ← 70% ← 55% ← overview

• 放大超过 100% — detail 会在方框内展开证据和设计说明的前三行；detail+ 会将其扩展为阅读卡片（最多显示十二行说明）；
• 85–55% — 收紧留白并按比例截断标签，方框仍保持为方框；
• 低于 55% — 标签将失去意义，因此地图会进行聚合：每个已声明的分组（区域内带标签的子系统）都会变成一个方框，命名为 foundation subsystem 1/2，其状态根据成员推导；连线会汇总到各分组，未分组的节点则保持不变。就像真实地图一样，缩小时显示的是省份名称，而非匿名点。（没有分组的地图会退回到纯符号星图，并显示各区域的计数。） 页脚始终会标明当前级别。

地图下方、提示行上方设有固定高度的详情面板：包含可拖动的分隔线、按状态着色的标题栏、焦点节点的证据、两个方向的连线（uses → … · used by ← …，每个相邻节点都带有自己的状态符号）以及自动换行的设计说明。没有焦点时，则显示地图的仪表盘。高度固定——详情不会浮在地图上方，布局也不会跳动。

Glyphs

地图的每个绘制位置都使用同一个状态符号，包括窗格中的方框、标签栏和详细信息面板，以及其他任何读取同一存储的客户端：

Unicode	ASCII	含义
·	.	计划中 — 已声明，尚未开始
⠿	*	进行中，静止状态 — 可动画显示的方框会改为轮播盲文帧（⠋⠙⠹…），ASCII 模式下则会循环显示四条横线
■	#	已完成，有证据
□	o	已完成，未记录证据 — 声明相同，但背后没有佐证
✗	X	已退化：之前已完成，现在已损坏
⊞	+	徽章：此节点链接到子地图；双击可进入

图片下方的图例会列出四种状态；只有实际包含 □ 已完成，无证据 的地图才会将其加入图例 — 四种状态构成完整的词汇表，而这种状态表示此处此刻违反了一条规则。文档图表类型会用节点类型符号替换状态图例。

窗格标志

窗格启动器（scripts/open-pane.mjs <project dir>）和监视器（dist/watch.mjs）接受相同的监视器标志；启动器会原样转发这些标志，并拒绝任何不认识的标志，而不会将其丢弃。

标志	效果
--page <slug>	打开时显示此页面；如果此控制台的窗格已在运行，则改为切换到该页面，而不再打开另一个窗格
--ascii	使用纯 ASCII 字符集，适用于不支持制表符绘制符号的字体
--no-color	不使用 ANSI 颜色
--no-mouse	不报告鼠标事件，适用于终端复用器需要独占鼠标的情况
--no-follow	启动时关闭自动跟随
--interval <ms>	轮询间隔；默认为 250，最低为 50

仅启动器支持：--window 会打开专用的 "mellos-mapping" 窗口，而不是拆分会话窗口；--force 会为此项目再打开一个窗格，即使已经有窗格在运行。仅监视器支持：--file <path> 用于指定默认页面的状态文件（启动器会根据项目目录推导该文件）。

窗格的归属通过内部监视器标志 --owner <token> 和查看器报告中的可选 owner 字段传递。启动器会根据源控制台进程及其创建时间推导令牌；手动启动的监视器可以省略该令牌。向已绑定的查看器发送聚焦和退出请求时会使用其 PID，因此同一项目的其他窗口无法接收这些请求。不带参数的 mmap 仅切换绑定到当前控制台的窗格；mmap --window 则切换单独的项目窗口。

mmap 命令

在任意终端中输入 mmap，即可切换地图面板：打开当前所在项目的地图面板，或关闭已经打开的面板。

输入	功能
mmap	当前项目没有监视器 → 打开面板；已有监视器 → 关闭面板
mmap <page-slug>	在指定页面打开，或将已打开的面板切换到该页面 — 不会关闭面板
mmap --window	在专用的 "mellos-mapping" 窗口中打开，而不是在当前窗口中分屏
mmap --force	即使已有面板在运行，也再打开一个面板

项目的查找方式与 git 查找根目录相同：从当前目录开始向上查找，直到找到包含 .mellos/ 存储目录的最近目录。在尚无地图的项目中运行也没问题 — 面板会显示待机画面，并持续提示这一状态，直到首次调用 mmap_declare。

关闭操作通过存储目录完成，而不是发送信号：mmap 会在地图旁写入一次性请求，面板会在下次轮询时（默认每隔 250 ms）读取并退出，精确恢复终端原状 — 鼠标报告关闭，光标可见。处于待机画面的面板也会以同样的方式关闭。请求会在读取时删除；如果面板意外退出，残留请求会在下次启动时清除，因此过时的请求绝不会关闭新面板。

上面所有监视器标志在这里也都适用，并会原样传递；未知标志会导致用法错误，绝不会被悄悄忽略。除非你安装了 npm 包，否则需要安装一次 mmap。在 Claude Code 对话中，/mellos-mapping:mmap 会打开同一个面板。

页面

一个项目可以并排保留多张地图 — 一项工作 = 一个页面。Claude 通过向任意 mmap_* 工具传入 page 来指定页面；只要存在第二个页面，面板就会显示标签栏。活动标签会以其地图的汇总状态颜色加粗显示。每个页面都会记住自己的平移位置、缩放比例和固定节点。

默认情况下，面板会跟随正在编写的页面 — 即 Agent 当前正在操作的地图，因此，声明和更新会自动将观众带到相应页面。按 f 可切换此行为；手动切换页面会关闭跟随，使用 --no-follow 启动时也会关闭跟随。关闭跟随后，后台页面的变更会让其标签亮起状态颜色，而不会切换当前视图。显式指定的 --page 优先于跟随设置；如果请求的页面尚不存在，面板会在该页面出现时立即显示它。

删除页面。 一项工作结束后，其页面不必继续保留。在面板中按 x — 或者鼠标悬停时活动标签上的 × — 会发起删除请求：页脚会显示 press x again to delete <page>，在三秒内再次按键即可删除该页面的文件。切换页面、按 Esc 或等待一段时间都会取消请求。× 只会出现在活动标签上，因此点击非活动标签会先切换到该页面，并在下一帧显示其 ×。通过工具调用删除时，使用 mmap_remove {pages: ["slug", …]}，并在该调用的地图编辑完成后执行。无论哪种方式，文件都会被永久删除 — 地图是普通 JSON，因此提交它们是唯一的撤销方式。

状态保存在项目根目录下由工具管理的 .mellos/ 目录中：

路径	内容
.mellos/map.json	默认页面——可选；如果项目的工作都在具名页面上进行，则不会有此文件
.mellos/pages/<slug>.json	每个具名页面对应一个文件
.mellos/config.json	项目的映射策略（参见设置）
.mellos/focus	启动器向运行中的窗格发出的单次“显示此页面”请求；窗格会在一个轮询周期内读取并删除该请求
.mellos/quit	mmap 切换命令发出的单次“关闭自身”请求；以相同方式读取并删除
.mellos/viewers/<pid>.json	每个运行中的窗格对应一份报告，记录其显示的页面以及是否启用了自动跟随；运行期间每秒刷新一次（参见谁在查看）
<any of the above>.<pid>.<random>.tmp	正在进行的保存；完成后会重命名并覆盖目标文件，或被移除。若文件残留，表示写入失败（且已报告），甚至无法完成清理
.mellos/.write-lock	用于操作系统项目锁的永久常规文件；请勿纳入版本控制，也不要在正常运行期间删除、重命名或替换

地图文件是纯 JSON，如果你希望在 Git 中保留地图历史记录，可以安全地提交。请勿将 focus、quit、viewers/ 和 .write-lock 纳入 Git。前三者用于传递运行时消息；锁文件必须始终保留，即使没有进程持有其锁。

直白地说并发机制。 每次保存都是原子的——先写入同级的私有临时文件，再将其重命名并覆盖目标文件——因此轮询存储的读取方看到的要么是上一份完整地图，要么是新地图，不会看到写入中断的内容。每个图写入方（MCP、HTTP 查看器、监视器）都使用同一个非阻塞操作系统独占锁来锁定项目。锁使用独立的固定文件，与被替换的地图文件分开；操作完成或进程退出后，即使操作系统释放了锁，该文件也会保留。发生锁竞争时会返回可重试的 BUSY。

该锁会串行执行每项操作的读取、修改和保存。若要保护基于较早读取结果计算出的编辑，请传入 expectedRevision：系统会在锁内进行比较，版本过期时返回 CONFLICT。如果不传，后续写入仍可能覆盖同一字段或 context 这样的整个值。页面可将无关工作分开；但在同一页面上协作仍需使用带版本校验的编辑。底层的 saveMapFile、手动编辑以及较早启动且仍在运行的进程不遵循此约定。升级前，请停止该项目的所有旧版 MCP、查看器和监视器进程；旧版锁目录需要一次性迁移。边界说明和升级步骤请参见持久化地图 API 指南和项目锁定。

图表类型

默认类型 dev 是上述持续更新的进度记录。相同的分层 DAG 机制也可绘制文档图表：在 mmap_declare 中传入 kind，页面便会以中性样式渲染——使用纯色实线边框的方框，不显示幽灵、旋转加载图标或进度计数。

类型	阅读方式	额外效果
architecture	分层组件（也可表示模块依赖和调用图）	边上标注协议
dataflow	将流水线阶段作为层，来源位于底部	边上标注数据
behavior-tree	叶节点（操作）位于底部，根节点位于顶部（也可表示思维导图、WBS）	节点类型 selector、sequence、parallel、decorator、condition、action 会渲染为字形
sequence	经典的调用/返回图：时间自上而下流动，参与者显示为泳道标题；每次调用和每次返回都是执行方泳道中的一个事件	lanes 表示参与者；边上标注消息

节点类型和边标签也适用于 dev 地图。状态机有意不在支持范围内：状态转换会形成循环，而此处的边只能向下指向。

子映射

节点可以通过 submap: <page-slug> 链接到子页面——面板会为其标上 ⊞；双击可进入子映射，按 Backspace 可返回上一级。页面构成的映射之映射：无需新增存储，也无需引入新的不变量。 节点是否值得拥有子映射，由 AI 自行判断——大多数节点都不需要。

子映射是内部细节，而非同级页面：被其他页面进入的页面不会占据标签页。两项改进可避免标签栏消失——页面自己的节点若以自身命名，不会隐藏任何页面；链接循环会保留其标签页，除非循环外的页面进入其中，因为循环中没有可供返回的外部页面。进入子映射后，标签栏会变为面包屑导航——⌫ parent map ▸ node，点击它（或按 Backspace）即可返回上一级。隐藏的子映射在后台发生变化时，页脚会显示提示。

MCP 工具

从 mmap_read 开始，继续处理现有页面；开启新对话不代表开启新的工作。使用稳定 ID、筛选读取和经过修订检查的写入。持久化映射 API 指南介绍了完整的 CRUD、原子混合批次、上下文检查点、源哈希和工作树边界。

工具	用途
mmap_declare	扩展映射：标题（null 表示移除）、图表类型、层级带、泳道、组（子系统）、节点——包含 status、evidence、detail、kind、group、lane、submap——以及可选带标签的边（批次要么全部应用，要么全部不应用）
mmap_update	记录进度并修订：状态（planned → in-progress → done，并附加证据；regressed）、重新标记节点、将节点移至另一个带（layer）、加入或离开组或泳道、设置节点类型或 submap；重命名并重新排序层级带（layers）、重新标记组（groups）和泳道（lanes）；null 可清除任何允许清除的字段
mmap_remove	修订：移除边、节点、组、泳道、空的层级带；以及通过 pages 移除整个页面、文件和所有内容（永久操作；在本次调用的映射编辑应用后执行）
mmap_view	将当前映射以内嵌文本形式呈现（可选 zoom，-4…2），末尾附上 pages: 行，列出项目中的每个页面以及当前查看的页面
mmap_read	结构化页面发现、精确 ID、筛选和分页读取、上下文及源变更
mmap_batch	带修订检查的单页混合创建／更新／移除事务
mmap_setup	获取／设置项目的映射策略——何时打开映射
mmap_open	在屏幕上显示映射：打开窗格，或将已打开的窗格切换到指定 page（设置 window: true 可使用专用窗口）。它会返回之后窗格是否确实报告已打开，而不只是命令是否运行；并且绝不会关闭窗格

批次按层级带 → 组 → 泳道 → 节点更新的顺序应用；在单个节点更新中，layer 会先移动节点，再处理其他字段，因此可以在同一项中将节点移至新层级带并加入组。

边界会拒绝以下内容，确保记录簿不会记下并非本意的内容：

• 未知键，并指出具体键名——拼错的 evidance 会导致错误，而不是被静默丢弃；此规则适用于每一层嵌套；
• 文本字段中的控制字符——存入标签的 ESC 序列会让映射在每个打开它的人的终端中重绘。detail 是例外：换行符和制表符是书写备注所需的字符，其他字符（ESC、BEL、孤立的 CR）仍会被拒绝。文件加载和库保存遵循相同的控制字符规则，同时保留旧文件中的多行证据。对于由库调用者直接构造的映射，终端渲染也会对控制字符进行中和；
• 可选字段中的空字符串——清除字段应使用 null，不能用空白值，因为它会显示成一个无法与真实内容区分的方框；
• submap 指向调用本身所操作页面的节点——这相当于没有底部的链接，而不是父级链接；
• 针对调用本身所操作页面的页面删除请求，或针对项目中不存在的 slug 的删除请求——一次调用不能编辑自己正在删除的映射；而与任何页面都不匹配的名称通常是拼写错误，而非竞争条件；拒绝信息会列出实际存在的页面。

未成功写入时会返回 save failed, nothing changed (retry)：原文件保持完整，只需重新调用即可恢复。

谁在观看

一张没有显示在屏幕上的地图只是一个文件，而不是地图——过去系统中的任何东西都无法分辨两者。助手会声明一个设计，在构建节点时将它们点亮，并把所有内容都报告到一个你从未打开过面板的存储区。

现在，每个面板运行时都会发布一份简短报告——.mellos/viewers/，每个面板一个文件，每秒刷新一次——每次写入和查看都会以这些报告的内容为准：

这一行	含义
pane: CLOSED	没有人在看这张地图；助手会用 mmap_open 打开一个面板，而不是让你来打开
pane: running on this page	有一个正在运行的进程报告了此页面；它的终端可能处于隐藏状态
pane: open on <other>, auto-follow on	面板会跟随上次写入的页面，因此会自动切换到此处
pane: open on <other>, auto-follow OFF	你手动固定了该页面：更改确实存在，但没有显示在你的屏幕上。助手会被告知要说明这一点，而不是移动你的视图

这些报告也会回答 mmap 和启动器的“是否已有面板打开？”这一问题。过去要回答这个问题，需要扫描仅限 Windows 的进程，而且无法得知屏幕上显示的是哪个页面。如果某个面板停止刷新报告，报告会在 5 秒后被忽略，并在 1 分钟后删除，因此被终止的面板无法继续声称有人在看。

心跳信号不能证明屏幕上可见。显式打开 tmux 也会选中现有观看器的窗口，在其他面板被放大时将其显示出来，并在报告可见之前验证已连接会话的活动窗口。在没有 TMUX 的 shell 中聚焦该观看器时，会复用其原始所有者。

设置：选择地图打开的时机

地图绘制应该多积极，取决于个人习惯，而不是仓库的属性——因此，在安装后的第一个会话中，会为你选择一次：

• always — 为每个结构化任务绘制地图：工作流、设计、架构、技术依赖项。助手会主动打开面板；你记录的回答就是长期有效的许可，因此它不会再询问。
• complex — 与上述相同，但仅适用于中等或复杂任务：涉及多个模块、新子系统，或大约需要 1 小时及以上的工作。
• on-request — 仅在你明确提出要求时绘制地图。如果项目中没有地图，插件就完全不发声——目的就是不产生任何干扰。

答案会写入 <your home>/.mellos/config.json，并通过插件的 SessionStart hook 传递到每个会话。该 hook 会读取答案，并在你输入任何内容之前将相应指令交给助手。此后无需再为任何项目单独设置。

某个项目仍然可以使用不同的设置：mmap_setup {policy, scope: "project"} 会将策略记录在该项目的 .mellos/config.json 中，项目策略优先于用户策略。无论你想更改哪种范围的设置，/mmap setup 都会重新询问。该策略会引导助手，但绝不会阻止工具；无论使用哪种策略，明确请求绘制地图始终有效。

没有 hook 的宿主（Codex CLI、纯 MCP 客户端）会以另一种方式询问：只要任一范围都没有策略，每个 mmap_declare 的回复都会附带一条提示，告诉助手询问你。你只要在任何地方回答一次，这条提示就会在所有项目中永久停止出现。

工具强制执行的结构不变量：各层按 rank 构成全序（整数范围为 0..99，0 表示底层，每张地图内唯一）；每个节点恰好属于一层；边严格向下——因此图在构造时就保证无环；节点不能依赖同层的兄弟节点（如果 A 需要兄弟节点 B，那么 B 实际上应是更低层的概念，或者 A 和 B 应合并为一个节点）；一个组会将同一层级内的节点聚在一起；节点 ID 和组 ID 共用一个命名空间——一个 ID 只能命名节点或组，不能同时命名两者，因为它们都会渲染为方框，一个 ID 必须只对应一个方框。

开发

请参阅贡献指南和项目结构、分支与恢复指南。

npm ci
npm run verify

开发请使用 Node.js 22.12+。verify 会运行 typecheck、test、build（打包 dist/ 并生成带类型声明的 lib/）、check:package、check:codex 和 check:release。这些检查 npm 入口、Codex 包和两个可安装版本，包括它们的 MCP 握手。

仓库本身自底向上分层，每一层都有对应的规范：

层	代码	规范	职责
0 领域	src/domain/	ops.test.ts	映射值、结构不变量、纯操作
1 格式	src/store/format.ts	store.test.ts	状态文件格式：经重放验证的解析、序列化——不涉及 I/O
1 存储	src/store/store.ts	store.test.ts、atomic-save.test.ts	Node 上的原子状态文件持久化
1 语义	src/semantics/	semantics.test.ts	与媒介无关的视图语义：缩放阶梯、组聚合、页面集规则、序列翻转、共享的字形词汇
2 应用	src/server/apply.ts	apply.test.ts	工具输入 → 事务性操作序列
3 服务	src/server/server.ts	server.test.ts、save-failure.test.ts	通过 stdio 提供的八个 MCP 工具
4 渲染	src/render/	render.test.ts、routing.test.ts	ASCII 渲染器及其线路路由
4 面板	src/watch/	watch.test.ts、pane-state.test.ts、input.test.ts	轮询面板：页面集、输入解析、面板与界面元素
— 启动器	scripts/	open-pane.test.mjs、codex-register.test.mjs	纯 Node 入口
— 打包	package.json	tests/lockfile.test.ts、browser-safe.test.ts	发布内容及其目标对象

dist/ 有意提交到仓库：插件安装会克隆此仓库且不会运行任何内容，因此入口以打包形式发布。CI 会将已提交的 dist/ 与全新构建的结果进行比较，因此如果修改源代码后忘记重新构建，检查就会失败。

库

较低层也可作为库使用（npm run build 会生成带类型声明的 lib/；npm 会将其打包）。子路径导出与源代码对应：

子路径	内容	浏览器安全
mellos-mapping/domain/types	映射值、ID、等级、状态、错误	是
mellos-mapping/domain/ops	对映射执行的纯操作	是
mellos-mapping/format	状态文件解析 / 序列化、页面 ID	是
mellos-mapping/semantics	缩放阶梯、组聚合、焦点与页面集规则、共享的字形词汇	是
mellos-mapping/render	终端渲染器	采用相同方式进行限制（因为它是纯函数），但其输出是字符单元格——适用于终端宿主
mellos-mapping/store	文件系统持久化、原子保存、焦点文件、策略	仅限 Node
mellos-mapping/server	打包后的 MCP 服务入口——用于启动的目标，而非供导入的模块	仅限 Node

浏览器安全意味着整个导入闭包中不包含任何 Node 内置模块，并通过测试加以检查，因此图形客户端（Web 面板、编辑器视图）可以解析状态文件，并复用终端面板所用的完全相同的聚合、缩放和字形语义。

可选的 GitHub Star 提醒

通过 npm/npx 安装后，满足以下条件时，可能会显示一条可关闭的小提醒：已过去至少 7 天，且已在 3 个不同的 UTC 日期成功查看地图。Web 查看器会以内嵌方式显示提醒，不会抢占焦点；原生交互式终端则仅会在成功完成查看会话并退出后显示提醒。提醒绝不会加入 MCP 回复、AI 提示词、安装日志、CI 或管道输出中。插件版和源码检出版本不受影响。

每位用户仅会收到一次提醒，不受项目、版本和安装方式影响。Star 按钮会在系统默认浏览器中打开 GitHub，并保留现有的登录会话。如果启动失败，提醒会保持打开，并提供复制地址选项。关闭提醒、点击其 Star 链接，或直接结束会话后，提醒都不会再次出现。若要在提醒出现前将其禁用，请在查看器/MCP 进程的环境中设置 MELLOS_MAPPING_NO_STAR=1。仅首次使用时间、最后一个 UTC 日期、封顶后的日期计数和一次性标记会存储在 ~/.mellos/support/star-reminder.json 中；不会上传任何内容，只有用户点击链接时才会访问 GitHub。设置不可读取或存储忙碌时，会静默跳过提醒。

社区

本项目参与并支持 LINUX DO 社区。

许可证

MIT