理解 TRAE 的 Agent + IDE 思路：用一个 Markdown 检查器拆解完整交付

本文参考 TRAE 官方介绍中的 Agent + IDE 工作方式，以一个实际完成的 Markdown 检查器说明需求、实现、验收和交付如何衔接。工具开发、运行验证及截图由 AI 助手代为完成，验证环境为本地浏览器；文中不包含 TRAE 客户端实测结论，配图均为工具本身的真实运行画面。

技术文章写到最后，最容易漏掉的往往是小问题：图片地址还是自己电脑上的路径，正文留着一句「这里待补充」，标题层级从二级直接跳到了四级。

这些错误不难修改，却很容易在多次编辑之后被忽略。于是，这次把选题落到一个很具体的工具上：粘贴 Markdown，点击检查，得到带行号、原因和修改建议的问题清单。

这个项目也适合用来讨论 AI 开发中的一个问题：代码生成以后，到底还需要做什么，才能说任务完成了？

按照 TRAE 官方介绍，新版支持通过 Agent 模式统筹任务，并切换到 IDE 模式进行精细修改与调试。这种分工给我的启发是，把「推进实现」和「核对实现」放进同一条开发流程。

下面就从需求开始，把这个 Markdown 检查器完整拆开。

一、先定义什么叫完成

如果只给 AI 一句「帮我做一个 Markdown 检查器」，它可以很快生成一个输入框、一个按钮和一组提示卡片。

但页面长什么样，只解决了问题的一部分。真正决定这个工具有没有用的，是检查规则是否符合写作场景。

例如，代码示例里经常会出现 TODO，它是否应该触发提醒？图片路径以斜杠开头，就一定是本机文件吗？正文没有一级标题，是否算错误？

第一版最终确定了这些规则：

功能	处理方式
标题层级	提醒 H2 到 H4 这样的向下跳级；允许返回上级，不强制正文必须以 H1 开始
图片路径	提醒空地址、file 协议和常见的本机绝对路径；支持解析有定义的引用式图片
正文待办	检查正文中的 TODO 和「待补充」，忽略代码块、行内代码和 HTML 注释
内容统计	分别统计中文字符和英文单词，明确排除代码、图片替代文本和链接地址
结果处理	显示行号与修改建议，支持定位原文、查看和复制报告

没有加入自动改稿。技术文章里的错误示例可能是作者故意保留的，检查器应当提供线索，让作者确认后再修改。

没有加入登录、数据库和云端存储。这个任务的核心是检查一段文本，第一版没有必要为此扩展出一套账号系统。

有了这些边界，给 Agent 的任务描述就可以写得更具体。下面这段提示词可用于复现同类项目，它是工作流建议，并非 TRAE 对话记录：

text 复制代码

请开发一个本地 Markdown 发布前检查工具。

使用 Vite + TypeScript，并选用成熟的 Markdown 解析库。
稿件只在浏览器内处理，不上传、不持久化保存。

需要检查标题跳级、空图片地址、常见本机图片路径，
以及正文中的 TODO 和「待补充」。
代码块和行内代码中的待办标记应被忽略。

结果包含源码行号、原因和修改建议，支持复制报告。
不要自动修改原文，不要执行 Markdown 中的 HTML。

请依次交付：需求拆解、检查逻辑、交互页面、测试与构建结果。
最后提供可打开的产物，并说明尚未覆盖的情况。

提示词里的重点，是给出可以核对的行为。之后无论由 Agent 继续实现，还是回到 IDE 检查代码，都有同一套判断标准。

二、检查规则与页面分开实现

项目使用 TypeScript 编写，Vite 负责开发和构建，mdast-util-from-markdown 负责解析 Markdown。

核心结构如下：

text 复制代码

src/
  checker.ts       # 解析、规则检查、报告格式化
  main.ts          # 输入、结果展示、定位和复制
  samples.ts       # 问题示例与修订示例
  cases.ts         # 22 个规则验收场景
  validation.ts    # 在浏览器中运行验收场景
  style.css        # 页面样式

tests/
  checker.test.ts  # 规则、调用隔离和报告测试

最重要的接口是 checkMarkdown(source)：传入原文，返回问题列表和统计结果，不直接操作页面。

每条问题包含以下信息：

ts 复制代码

type Issue = {
  rule: "heading-level" | "image-path" | "todo-marker";
  severity: "warning" | "info";
  line: number;
  column: number;
  offset: number;
  message: string;
  suggestion: string;
};

line 用来告诉作者问题在哪一行，offset 用于定位输入框中的原文位置。页面只负责展示结果，不重新计算规则。

这个拆分也让验收更直接：如果检查结果不对，可以先拿一段固定文本调用检查函数；如果函数结果正确、页面显示不对，再排查交互和状态更新。

三、为什么没有对全文直接搜索 TODO

下面是项目中的综合验收样例：

markdown 复制代码

## 用 AI 做一个小工具

文章写完以后，再花一点时间检查发布细节。

#### 第一步：检查输入

这里待补充操作说明。

![工具界面](file:///Users/demo/Desktop/preview.png)

```ts
// TODO: 这是文章中的代码示例，不应被当成正文待办
const message = "待补充";
```

最后核对图片、标题层级，以及正文里的遗留标记。

这段文本中，真正需要提醒的地方有三处：

第 5 行：标题从 H2 跳到了 H4。
第 7 行：正文仍然包含「待补充」。
第 9 行：图片地址指向本机文件。

代码块里的 TODO 和「待补充」应当保留，不产生正文待办提醒。

如果直接对全文使用正则搜索，代码示例也会被算进去。因此，工具先把 Markdown 解析成语法树，再按节点类型处理：标题节点检查层级，图片节点检查地址，文本节点检查待办。

代码块与行内代码属于独立的节点类型，不会进入正文待办分支。

行号也需要沿用源码位置。若先删除代码块，再对剩余文本逐行计数，报告中的行号就可能与原文对不上。当前实现保留节点的源码起点，并在文本节点内部计算标记位置。

实际页面输出与预期一致：三项提醒分别位于第 5、7、9 行，代码示例中的两处标记没有触发提醒。

图 1：本地浏览器运行截图。左侧为输入原文，右侧按源码顺序列出问题。

这张图比「支持 Markdown 检查」更能解释工具的价值：它展示了检查什么、忽略什么，以及结果能否回到原文。

四、几个需要明确的边界

图片检查很容易被做得过于武断。

file:///Users/demo/Desktop/preview.png 显然不能直接作为公开文章的图片地址，但 /assets/image.png 可能是网站正常使用的路径，不能仅凭开头的斜杠就判错。

目前实现识别 file 协议、Windows 盘符路径，以及 /Users/、/home/ 等常见本机目录。相对路径不一概判错，远程 HTTPS 地址也不会被标记为本机路径。

引用式图片需要多走一步：先找到图片引用，再根据引用名查找定义，检查定义中的目标地址。代码为此单独建立了定义映射，并按 Markdown 的引用规则处理大小写和重复定义。

但这里没有做图片连通性测试。因此，报告没有问题，只表示没有触发本轮路径规则，不代表远程图片一定能打开。

另一处边界是字数。

页面分别显示中文字符数和英文单词数，统计基于 Markdown 文本节点，包含标题及链接显示文字，排除代码、图片替代文本和链接地址。这是一种明确、可重复的口径，但并不保证与掘金编辑器的统计完全一致。

最后是输入内容的展示。原文放在文本框中，动态提示通过 textContent 写入页面，不把稿件当作 HTML 渲染。浏览器验证中输入了包含 <script> 的文本，没有弹出执行对话框，页面仍正常工作。这验证了该样例的处理行为，并不等于完成了全面的安全审计。

五、24 个测试通过之后，构建仍然出过问题

规则测试覆盖了标题跳级、代码块忽略、源码行号、图片地址、引用式图片和文本统计等 22 个场景。

此外，还有两项独立测试：连续检查不同输入时结果是否互相影响，以及生成的报告是否包含正确行号、建议和统计说明。

Node 测试实际输出为：

text 复制代码

tests 24
pass 24
fail 0

不过，第一次生产构建并没有跟着通过。样式文件里有一条多余的导入：

css 复制代码

@import url('data:text/css,');

构建工具尝试处理该导入时，报出了：

text 复制代码

ENOENT: no such file or directory, open 'data:text/css,'

删除这条没有实际用途的导入后，再次运行 npm run build，TypeScript 检查与 Vite 生产构建通过。

这个问题很小，却说明了一件事：规则单元测试只覆盖了检查逻辑，不能代替样式处理和打包验证。完成交付需要逐层验证，而不能在看到「24 个测试通过」时就结束任务。

浏览器验收页随后调用同一套检查函数，运行了其中的 22 个规则场景，结果为 22/22 通过。

图 2：验收页在加载时实际运行检查函数，并比较规则、行号及统计结果。截图不是手工填写的通过清单。

页面交互也做了单独核对：点击第 7 行能选中对应原文；修改稿件后旧结果会被清除，并提示重新检查；清空后统计归零；复制报告后，回读文本在统一换行符后与报告一致。

这些动作没有包含在前面的 24 项 Node 测试数量里。

六、修订之后，再验证一次结果

修订样例做了三个调整：把 H4 改成 H3，补上原本缺失的操作说明，移除尚未准备好的本机截图引用。

代码示例中的 TODO 和「待补充」仍然保留，因为它们属于文章内容。

再次运行检查，提醒数从 3 降到 0。

图 3：修订后的页面。本轮规则没有发现问题，仍保留发布前人工预览的提示。

这里没有声称工具已经解决所有写作问题。第一版仍有明确限制：

不验证远程图片是否可访问，也不判断防盗链问题。
不全面支持 MDX、模板语法和嵌入式 HTML 图片。
不检查错别字、技术内容正确性或文章结构是否合理。
不自动保存稿件，刷新或关闭页面会丢失当前输入。
没有大文档性能基准，也没有人工检查与工具检查的耗时对照。

因此，这次可以给出的结论是：工具完成了已定义规则与交互的验证，能够帮助作者发现一组具体问题。是否提高了整体写作效率，还需要更多实际使用记录，不能从单次演示直接换算成百分比。

七、把这个过程放回 Agent + IDE 工作流

回看这次实现，适合交给 Agent 推进的任务包括：拆解需求、生成项目骨架、实现独立规则、补充测试、整理运行说明，以及执行构建。

需要认真检查的地方则很具体：代码块是否会误报，图片路径的判断是否过宽，源码行号是否正确，页面状态是否对应当前输入，最终产物是否真的能打开。

这也说明 IDE 中的代码检查并不一定发生在整个项目做完之后。每完成一个可验证阶段，就可以查看修改、核对规则，再把明确的问题交回 Agent 处理。

一次有效的反馈最好包含四件事：复现输入、实际现象、预期行为，以及需要重新运行的验证。相比「再优化一下」，这样的反馈更容易收敛到具体修改。

这与 TRAE 官方描述的 Agent 推进和 IDE 精细处理思路相契合；至于 TRAE 在真实账号环境中的响应速度、上下文衔接和稳定性，仍需独立实测，本文不作推断。

最终交付的项目包含源码、测试、构建脚本和两个自包含 HTML 页面，检查器与验收页都内嵌了必要脚本和样式。本次通过本地 HTTP 服务验证了这两个成品；测试工具限制了 file:// 访问，因此未覆盖直接双击文件的打开方式。开发者需要修改源码时，可以运行：

bash 复制代码

npm ci
npm test
npm run build
npm run standalone

这次验证于 2026 年 10 月 20 日完成，开发环境为 macOS arm64、Node.js 25.9.0，生产构建使用 Vite 7.3.7。

一个小工具的交付可以很轻，但应当能回答几个问题：它解决什么，规则如何实现，结果怎样验证，还有哪些限制。

对 AI 辅助开发而言，把这些问题回答清楚，比只展示一张生成后的页面更有参考价值。下一次再让 Agent 开始一个项目时，也可以从一句「请先定义验收标准」开始。