企业官网建设流程全解析

在 MoAI-ADK 中，@MX 标签与Navigator 导航器是 AI 开发挽具（harness）里的"活代码地图"系统：把设计决策、代码符号、SPEC 规格钉进代码和文档，形成可双向链接的关系图，让 AI 代理从任意一端都能瞬间抵达另一端，无需反复重读整个代码库。本文带你用 3 步掌握它。

为什么 AI 需要"活代码地图"

AI 代理理解代码的成本就是上下文（Token）。提示词会被遗忘，但刻在代码里的注释会随代码留存——下一个代理第一次读到代码，就能立即把握意图与约束。

MoAI-ADK 用三层机制解决这个问题：

三层聚合成同一张图，代理修改任何一方时都能立即拉起另一方的上下文。

第一步：@MX 标签——把上下文钉进代码

5 种标签类型

@MX:标签是内联源码注释（支持 16 种语言的注释语法），由internal/mx/tag.go定义：

最小写法示例（完整规则见 mx-tags.md）：

// @MX:ANCHOR:auth-id: 8 处调用，禁止随意改动签名 // @MX:REASON: 外部 OAuth 网关依赖该契约 // @MX:SPEC:SPEC-AUTH-001 func ParseBearer(h string) string { ... }

其中@MX:SPEC子行是关键——它把代码位置直接连接到 SPEC ID，构成"代码 → 设计"方向的第一根链接。

一键扫描：/moai mx 命令

在 Claude Code 中直接输入斜杠命令即可批量打标签，详见 moai-mx.md：

> /moai mx --all # 扫描整个代码库（16 种语言） > /moai mx --dry # 预览，不修改文件 > /moai mx --priority P1 # 只标注高 fan_in 函数

扫描器按 P1–P5 优先级自动找出高 fan-in 函数、危险区域、缺失的 docstring 等，标签描述遵循项目的language.yaml配置（默认英文，韩语项目可设code_comments: ko）。

扫描结果写入侧车索引.moai/state/mx-index.json，并在会话开始/结束、文件编辑后自动验证——源码实现在internal/mx/包中，内部机制可参考 mx-scanner-internals.md。

第二步：Navigator 绑定令牌——设计文档与代码互相指向

Navigator 引入两个新的编写用令牌（navigator.md）：

双向链接长什么样

设计文档tech.md中：

决策 @NAV:DEC-AUTH-STRATEGY: OAuth2 over client-credentials。 头部解析器（see @NAV:SYM:pkg.ParseHeader）提取 Bearer 令牌。

代码auth/auth.go中：

// @NAV:DEC-AUTH-STRATEGY: 实现 OAuth2 client-credentials 流。 // @NAV:SYM:auth.ParseBearer 从 Authorization 头提取 Bearer 令牌。 func ParseBearer(h string) string { ... }

两份文件各自写完后，图里就出现了 3 个节点（决策 + 2 个符号）和它们之间的边：从设计文档到代码、从代码到设计依据，都可以自由移动。这就是"双向链接"的实体形态。

第三步：合成图谱与反向查询

汇聚成一张图

navigator-sync步骤把三组令牌族合并为单一产物.moai/project/navigator/nav-graph.json，包含decision | spec | symbol三类节点与dec-edge | spec-edge | sym-edge三类边（navigator_sync.go）。两个关键性质：

• 字节稳定：同一 git HEAD 上跑两次产出字节相同，审计与可复现性建立在它上面
• fail-open：错误的令牌只留下诊断警告（写入.moai/logs/navigator-sync.log），不中断构建

@MX:SPEC的关联由internal/navigator/sync/mx_bridge.go消费 MX 扫描器输出完成——只读取、不重扫、不改写internal/mx/。

用 moai graph 回答"反向问题"

grep答不了"改这个包会波及哪里"，但图谱可以（graph.md）：

$ moai graph build # 先汇总所有关系到 edges.jsonl $ moai graph query --blast internal/config # 从这里改起会波及多远？ $ moai graph query --callers SPEC-FOO-001 # 谁依赖这个 SPEC？ $ moai graph query --fanin --limit 20 # 被用得最多的包？ $ moai graph query --specs-no-code # 哪些 SPEC 没连上代码？

--blast沿反向边做广度遍历，@MX:SPEC边双向传播——改一个包时，它能顺藤摸瓜告诉你哪些设计规格被波及。此外moai graph check按层度量图谱落后代码多远（fresh / stale / absent），每次生成物都带 provenance 块声明自己描述的是哪棵树、哪个提交，过期判断永远基于内容哈希而非时间戳。

上手清单 🚀

1. 打标签：/moai mx --all给遗留代码库装上"路标"
2. 写令牌：在设计文档补@NAV:DEC-<id>，在代码注释补@NAV:SYM:<symbol>
3. 建图谱：moai graph build→moai graph query --blast <包>，把"波及半径"变成一行命令
4. 守新鲜度：提交前跑moai graph check，避免地图过期误导代理

总结

MoAI-ADK 的 @MX 标签 + Navigator 组合，本质是把"散落在注释里的意图"升级成可寻址、可查询、可审计的关系图：注解层让意图钉在代码旁，令牌层让设计与代码互指，图谱层让反向提问一行作答。对新手来说，记住一句话就够——提示词会被遗忘，钉进代码的链接会一直生效。

延伸阅读：

• 标签协议与生命周期：mx-tags.md
• 扫描器内部（rotRisk 评分、LSP fan-in 引擎）：mx-scanner-internals.md
• 架构文档生成：moai-codemaps.md
• 扫描器源码：internal/mx/，导航器源码：internal/navigator/