AITM 不只是读取源文件 — 它会构建一个结构化、可查询的模型，描述代码实际做了什么，让 AI 不再猜测，而是去核查。

AITM 如何理解项目

Behavioral Contracts

代码库中每一个有意义的功能都可以被记录为一份 Behavioral Contract：一份机器可读的规格，包含 ID、所属模块、一行行为描述、涉及的确切文件、危险区域警告和置信度分数。Contracts 按项目存储在本地 SQLite 数据库中，AI 会在改动任何一行代码之前通过 GraphQL 查询它们。这是虚构文件路径和臆造方法大幅减少的最主要原因 — AI 会核查 Contract，而不是猜测。

Contracts 也不会过时：每次合并之后，Docs 步骤会自动重新扫描变更，并更新受其影响的所有 Contract。

危险区域（Danger zones）

每份 Contract 都可以带有一个危险区域 — 用通俗语言写成的警告，说明改动该代码的影响范围（例如“调用此函数之前务必先检查跳过标志”）。AI 会事先读取危险区域，因此在开始编辑之前就知道不能破坏什么，而不是等测试失败之后。

知识图谱

在一个 GraphQL 端点背后，有十个相互关联的、关于项目的事实来源：

• 变量树（BL.* 业务逻辑代码、UI.* 界面代码）
• Behavioral Contracts
• DOM 元素映射
• Hint Dictionary
• 文档索引
• 代码地图 — imports/exports、高耦合的“god nodes”以及模块社区
• 测试地图 — UI 元素到 Playwright 定位器
• 截图
• Bugs
• 将以上所有内容联系在一起的跨模块边

一次查询即可同时从这十个来源提取相关上下文，而不是让 AI 在整个仓库中盲目地 grep。

项目引导（Onboarding）

首次导入项目时，AITM 会在任何 AI 接触它之前运行一次确定性的静态预扫描：语言和技术栈检测、完整的代码地图、通过 data-aitm 属性提取 DOM、变量回填以及文档指针。之后，AITM 才会可选地运行 AI 阶段 — 架构发现、挖掘 git 历史以获取模块耦合关系，以及按模块的深度分析。简而言之：导入一个仓库，AITM 会在第一个 Task 运行之前就完成映射。

DOM 映射 + Dev Panel

应用中的真实 UI 元素都带有 data-aitm 属性，每个属性携带触发和被触发的效果边，以及标明其在屏幕上位置的像素矩形映射。该映射为可靠的、自愈的 E2E 测试选择器提供了依据，取代了脆弱的 CSS 定位器。

Dev Panel 的作用

Dev Panel 是一个自包含的、可注入的 JS 工具栏（aitm-dev-panel.js），任何由 AITM 管理的项目在开发期间都可以加载它。它是一个浮动、可停靠的工具栏，会用徽章覆盖运行中应用里每个带 data-aitm 标记的元素：悬停提示显示元素的代码、标签、动作和处理函数；实时事件计数器持续运行；一个小型 Chat/Brainstorm 框允许直接从运行中的应用向 AITM 实例发送消息；另外还有字体大小控制以及 AITM 自身的在线/离线状态指示器。该面板会实时跟踪真实的用户交互（click/change/input/mount/unmount），并每 2 秒将其推送给 AITM — AITM 就是这样让其 UI 映射保持最新的。

面板有四个标签页：Elements（点击过或固定的元素，包含其变量代码、Contracts、文件和危险区域警告；Overlay、Pin / One Pin 和 Clear Pins 按钮）、Records（已记录的 UI 元素）、Errors（捕获的 JavaScript 和控制台错误，可在 AITM 中转换为 Bug Task）和 Settings。其完整文档可在 AITM 中通过页眉菜单打开：Help → AITM Dev Panel。

如果 AITM 与本网站运行在不同的机器上，请在配置中设置 AitmServer:PublicBaseUrl（例如 http://192.168.1.50:3333）— 即浏览器加载 aitm-dev-panel.js 的地址。留空则表示 http://<page host>:<Port>。AITM 地址之后也可以在面板的 Settings 标签页中更改。

Guide & Flow — 元素的业务逻辑流程

在 Dev Panel 中元素所在的行，可以打开其详情，包含 Graph、Guide & Flow 和 App Flow 标签页。Guide & Flow 以通俗的步骤自上而下地解释所选元素 — 先是 UI 元素本身，然后是描述其行为的业务 Contracts（每个都列出所涉及的变量）。Copy as Markdown 会将整个解释复制到剪贴板，可直接粘贴到 Task 提示词中。更多内容见 Contract Explorer 与 App Flow。

按项目启用和禁用

它只是添加到项目共享 HTML 外壳中的一个条件性 <script> 标签，仅在非 Production 环境下显示，并带有 data-project="<your-project-id>" 属性，使面板自动指向正确的项目。

Blazor Server (.NET 8+)

在 App.razor 中注入 IWebHostEnvironment，并用 IsProduction() 保护该 script 标签：

@inject IWebHostEnvironment env

@if (!env.IsProduction())
{
    <script src="http://localhost:3333/aitm-dev-panel.js" data-project="your-project-id"></script>
}

ASP.NET Core Razor Pages

模式相同 — @inject IWebHostEnvironment env 加上同样的 IsProduction() 保护 — 放在共享的 _Layout.cshtml 中，使用与上面相同的代码块。

Node / Express / TypeScript

在渲染 HTML 外壳的模板中用 process.env.NODE_ENV 进行保护：

{process.env.NODE_ENV !== 'production' &&
  '<script src="http://localhost:3333/aitm-dev-panel.js" data-project="your-project-id"></script>'}

如需禁用，请删除该条件 script 标签，或者直接在 Production 环境中运行应用 — 该保护会自动将其隐藏，无需改动标签。