用Trae开发Excel转Markdown工具：从需求到打包全流程

1. 为什么要在一个 AI 编程工具上做“Excel 转 Markdown”

1.1 一个反复出现的小麻烦

我平时写技术文档、维护个人知识库、帮团队整理发布内容,最常遇到的一个操作就是：把 Excel 里的表格挪到 Markdown 编辑器里用。

这个动作听起来简单，实际做起来相当烦人。Excel 本身没有“导出为 Markdown”的选项，网上虽然有在线转换工具，但表格一长、列数一多，格式就出问题，而把数据传到第三方网站上，数据安全和隐私也是个隐患。更别提有些内部数据压根不应该出现在在线服务上。

我想要的其实是一个很朴素的能力：拷贝 Excel 表格，粘贴到一个工具里，拿到符合 Markdown 语法的表格，然后直接粘到文档中用。整个过程应该在本地完成，不经过任何外部服务器，几秒钟结束，没有多余的注册和网页等待。这个需求我惦记了很久，一直懒得专门写代码。

后来我开始认真用 Trae，画风就变了。

1.2 为什么是 Trae 而不是 Visual Studio Code 加插件

Trae 是一款免费的 AI 编程工具，核心卖点是你用自然语言描述需求，它帮你生成、修改、运行代码。它不像纯聊天机器人那样停留在“输出代码片段”的层面，而是内置了完整的项目工作区，可以读文件、改文件、执行终端命令、装依赖库，完整体现了“你说需求，它写代码”的闭环。

对比一下：早期我用 VS Code 写类似的小工具，要自己建项目、装 Python 环境、处理依赖、调试语法错误，一套流程下来少说一小时。用 Trae 的话，大多数代码工作被 AI 直接承接了，我做的更多是“提需求”和“验收结果”，效率不在一个维度上。

我当时给这个系列起了个名字叫“言出法随”，意思是：你像对搭档说话一样把自己的意图说出来，靠谱的代码就出现了。听起来有点玄学，但因为它是免费的，并且确实能用，我就开始了第一个实战项目——Excel 复制内容转 Markdown。

1.3 项目目标与功能范围

在开始之前，我先把需求边界想清楚：

• 核心功能：从 Excel 复制内容后，将其转换为 Markdown 表格，再复制回剪贴板。
• 使用方式：最好是图形界面，或者系统托盘小工具，不应该要求用户打开命令行。
• 运行环境：Windows 为主，能打包成独立 exe 最好。
• 不做什么：不打算做完整的 Excel 文件解析，不做复杂格式转换，不做在线同步。

这些边界对和 AI 对话很重要。AI 在没有约束的时候容易把范围越做越大，你只想要一个开瓶器，它可能连整个厨房都给你包了。提前定义需求和非目标，能让整个开发过程更快。

2. 跟 Trae 对话：第一版脚本的完整诞生过程

2.1 环境准备与第一印象

Trae 的安装没什么可多说的，官网下载对应系统的版本，安装完打开就是一个类似 VS Code 的界面。有一点体验很好：它默认帮我配好了 Python 和 Node 相关的开发环境检测，不需要我先去装一堆插件。

我当时的新建项目步骤是这样的：

1. 打开 Trae，选择“新建项目”，选择 Python 作为基础语言。
2. 项目目录建好后，在 Trae 的对话窗口里开始描述需求。
3. 直接说“帮我写一个 Python 脚本，读取剪贴板中的 Excel 表格内容，转换为 Markdown 表格”。

Trae 很快就生成了一版代码。它不是那种简单的一句代码，而是带注释、带函数拆分的完整脚本。

2.2 第一条提示词，我是怎么写的

很多人和 AI 编程工具配合的第一道坎，是不会提需求。提得含糊，拿到的代码就含糊。我第一条提示词是这样的：

code复制你的角色是 Python 桌面开发专家。请帮我写一个 Windows 桌面小工具：
1. 用户从 Excel 复制一段表格内容后，运行这个工具；
2. 工具读取 Windows 剪贴板中的文本；
3. 如果能识别出表格结构（多行多列，列之间用制表符分隔），就转换成 Markdown 表格；
4. 转换结果自动写回剪贴板，并在界面提示成功；
5. 如果剪贴板中没有内容或不是表格结构，给出清晰提示。
技术选型不限，但平台要 Windows，尽量少依赖第三方库。

你会发现我在这段提示词里做了几件事：

• 给了角色定义，告诉 AI 它应该以什么身份来写代码。
• 列出了完整的用户使用流程，而不是只描述功能。
• 明确指定了数据来源是剪贴板，以及数据的特征（制表符分隔）。
• 要求结果自动回填剪贴板，并提示用户。
• 限定了技术平台和依赖程度。

这些约束条件会让 AI 的输出质量明显提高，因为它的可选范围被收窄了，生成的东西更贴近实际使用。

2.3 Trae 生成的第一版代码及分析

第一版代码出来之后，我仔细看了一遍。整体结构是：

• 用 pyperclip 库读取和写入剪贴板。
• 把文本按换行符拆成行，每行按制表符拆成列。
• 生成 Markdown 表格格式的字符串。
• 写回剪贴板。

核心代码如下（后来我手动整理过的版本）：

python复制import pyperclip

def excel_to_markdown(text):
    lines = [line.rstrip('\r') for line in text.splitlines() if line.strip()]
    if not lines:
        return ""
    
    rows = [line.split('\t') for line in lines]
    max_cols = max(len(row) for row in rows)
    
    md_lines = []
    for idx, row in enumerate(rows):
        row = row + [''] * (max_cols - len(row))
        md_lines.append('| ' + ' | '.join(row) + ' |')
        if idx == 0:
            md_lines.append('|' + '---|' * max_cols)
    
    return '\n'.join(md_lines)

if __name__ == '__main__':
    raw = pyperclip.paste()
    if raw.strip():
        result = excel_to_markdown(raw)
        pyperclip.copy(result)
        print("转换成功，结果已复制到剪贴板。")
    else:
        print("剪贴板为空。")

代码逻辑算清晰，但它当时真的能直接用吗？不能。因为有几个问题它完全没考虑到位。这就是为什么“AI 生成完代码，代码不等于工具”的原因。接下来我花了不少时间在“打磨”而不是“生成”上，这也是我想在系列里持续记录的核心。

3. 剪贴板里藏着的 Excel 表格：数据格式与解析逻辑

3.1 从 Excel 复制出来的数据到底是什么

这一步是整个项目最关键的认知，我甚至觉得，如果不懂这一点，用任何工具都很难做出好用的转换器。

当你在 Excel 里选中一个区域，按下 Ctrl+C，你以为剪贴板里只有“一张表格”，其实剪贴板里同时存在好几种格式的数据。常见的包括：

对于我们这种“只要内容结构”的工具来说，最稳定可靠的是纯文本格式。它简单到没有任何额外信息，不会因为编辑器不同而丢失内容，而且解析起来几乎不可能出错。这也是我在提示词里特意提“制表符分隔”的原因。

3.2 为什么 HTML 格式看起来更“完整”却是坑

Trae 第一版代码只处理了纯文本，我在测试过程中产生过一个想法：既然剪贴板里有 HTML 格式的表格，直接解析 HTML 不是更好吗？那样还能保留更多样式信息。

于是我让 Trae 写了一个尝试读取剪贴板 HTML 格式的版本。结果遇到了三层问题：

第一层，Windows 剪贴板的 HTML 格式不是标准 HTML 文件，是一段带特殊头（比如 StartFragment、EndFragment 标记）的片段，需要额外处理才能拿到真正的 <table> 标签内容。

第二层，Excel 生成的 HTML 表格非常啰嗦，经常包含内联样式、Excel 特有的 mso- 前缀属性，还有可能把合并单元格表达为 rowspan、colspan，解析工作量成倍增加。

第三层，即使用 HTML 解析成功，那些样式信息对 Markdown 来说毫无意义，Markdown 表格根本不支持合并单元格和颜色背景。拿着屠龙刀，发现根本没有龙。

最终我决定放弃 HTML 解析路径，专注纯文本。这个决策后来被验证是正确的。现实中的 Excel 表格转换需求，绝大多数只需要表格的“骨架”，而不是它的“皮肤”。

3.3 三行制表符分隔代码的可靠性

有人会质疑：纯文本方式处理不了合并单元格？没错，确实处理不了。但换个角度想，Markdown 本身也不支持合并单元格，所以这个“缺陷”根本不影响目标输出。

还有人担心：如果 Excel 单元格里的内容本身就包含制表符呢？这种情况很少见，Excel 在复制时通常会把内容里的制表符转换成普通空格（具体取决于 Excel 版本），如果真的遇到，我们可以约定用其他方式处理，或者干脆认为这是输入数据的边界情况。

反而应该担心的是另外两件事：一是从网页或者 PDF 复制的表格，分隔符可能不是制表符，而是多个空格。二是单元格文本里带竖线符号 |。这两个问题，我在下一轮边界处理中逐一解决了。

4. 从“能转”到“转得好”：三轮边界处理

4.1 第一轮：竖线字符必须转义

Markdown 表格的列分隔符是竖线。如果 Excel 单元格里本身就有竖线，比如某个备注列里写着“接口A|接口B”，直接转换出来的 Markdown 表格就会列数错乱，整行数据都会歪掉。

解决办法是在拼接表格前，把单元格里的英文竖线 | 替换为 \|。其实还可以考虑替换为全角竖线 ｜，很多排版场景下视觉上更自然，但为了严格遵守 Markdown 语法标准，我最终采用了 \| 的方式。

对应代码加一行就好：

python复制safe_cell = cell.replace('|', '\\|')

这一行代码，是表格转换器真正能用于生产环境的分水岭。没有它，只要遇到一次竖线内容，工具看起来就像坏了。

4.2 第二轮：空单元格与换行内容

在 Excel 表格中，空单元格是非常常见的。转换时如果单元格为空，直接不写任何内容，Markdown 表格中仍能正常对齐。这一点第一版就处理好了，通过 row + [''] * (max_cols - len(row)) 补齐了每行长度，保证表格右侧不会缺列。

真正容易出问题的是单元格里有换行。Excel 单元格支持自动换行和手动换行（Alt+Enter），复制出来之后换行符会变成 \n，但这个 \n 会让 Markdown 表格的第二行多出一个真实换行，直接破坏表格结构。

处理办法是把单元格内的换行符号再转换成 <br> 或空格。在 Markdown 表格中，<br> 是合法的换行方式，而且视觉效果还不错。代码调整如下：

python复制cell = cell.replace('\n', '<br>').replace('\r', '')

这里要注意顺序，\r\n 要先处理掉回车符，再统一处理换行符。Excel 在不同平台上复制的换行符不一样，Windows 下往往是 \r\n，而 Mac 上可能只有 \r。稳妥的做法是把 \r 去掉，然后把 \n 转成 <br>。

4.3 第三轮：从控制台脚本到可用的小工具

第一版的脚本是命令行运行的。虽然“能用”，但对我这种日常使用场景来说，打开命令行太劝退了。我还是希望有一个简单的图形入口，哪怕只是一个窗口加一个“转换”按钮。

于是我在 Trae 对话里加了一个需求：把这个脚本包成 tkinter 图形界面，界面尽量简单，有一个大输入框可以直接粘贴文本，有一个“转换为 Markdown”的按钮，转换完成后结果显示在下方并自动复制到剪贴板，同时显示状态提示。

Trae 在保留已有函数的基础上，用 tkinter 生成了新版界面。整个窗口长这样的结构：

python复制import tkinter as tk
from tkinter import ttk, messagebox

def convert_from_textbox():
    raw = input_text.get('1.0', tk.END).strip()
    if not raw:
        messagebox.showwarning("提示", "请先粘贴内容")
        return
    md = excel_to_markdown(raw)
    output_text.delete('1.0', tk.END)
    output_text.insert(tk.END, md)
    pyperclip.copy(md)
    status.set("转换成功，已复制到剪贴板")

我后来测试下来，窗口模式最顺手的使用路径是：先在 Excel 里复制，然后到这个窗口里 Ctrl+V，点按钮，切回文档里按 Ctrl+V。整个过程 5 秒不到，比在线转换工具快得多，还不用离开编辑器。

这里我要特别说一句：如果你只是自己用，到这个版本已经可以满意了。千万别急着加“自动监听剪贴板”“开机自启动”“系统托盘图标”这类花哨功能，每加一个，故障点就多一个。工具能用，比工具好看更重要。

4.4 最终代码的完整形态

经过三轮迭代以后，最终版本大概是这样子，命令入口和 GUI 入口都保留：

python复制import sys
import pyperclip
import tkinter as tk
from tkinter import messagebox

def excel_to_markdown(text):
    if not text.strip():
        return ""
    lines = [line.rstrip('\r') for line in text.splitlines() if line.strip()]
    if not lines:
        return ""
    rows = [line.split('\t') for line in lines]
    max_cols = max(len(row) for row in rows)
    md_lines = []
    for idx, row in enumerate(rows):
        row = row + [''] * (max_cols - len(row))
        row = [cell.replace('|', '\\|').replace('\n', '<br>').replace('\r', '') for cell in row]
        md_lines.append('| ' + ' | '.join(row) + ' |')
        if idx == 0:
            md_lines.append('|' + '---|' * max_cols)
    return '\n'.join(md_lines)

def util_command_line():
    raw = pyperclip.paste()
    if raw.strip():
        pyperclip.copy(excel_to_markdown(raw))
        print("转换完成。")
    else:
        print("剪贴板为空。")

def util_gui():
    root = tk.Tk()
    root.title("Excel 转 Markdown")
    root.geometry("560x600")
    
    label1 = tk.Label(root, text="从 Excel 复制内容后粘贴到这里：")
    label1.pack(pady=8)
    
    input_text = tk.Text(root, height=10, font=("Microsoft YaHei", 10))
    input_text.pack(fill=tk.BOTH, padx=12, expand=True)
    
    output_text = tk.Text(root, height=12, font=("Microsoft YaHei", 10))
    output_text.pack(fill=tk.BOTH, padx=12, pady=8, expand=True)
    
    status = tk.StringVar(value="等待输入...")
    status_label = tk.Label(root, textvariable=status, fg="#666")
    status_label.pack(pady=4)
    
    def do_convert():
        raw = input_text.get('1.0', tk.END).strip()
        if not raw:
            messagebox.showwarning("提示", "粘贴内容为空")
            return
        result = excel_to_markdown(raw)
        output_text.delete('1.0', tk.END)
        output_text.insert(tk.END, result)
        pyperclip.copy(result)
        status.set(f"转换成功，共 {len(result)} 个字符，已复制到剪贴板")
    
    btn = tk.Button(root, text="转换为 Markdown", command=do_convert, 
                    height=2, bg="#3178F6", fg="white")
    btn.pack(pady=10)
    
    root.mainloop()

if __name__ == '__main__':
    if len(sys.argv) > 1 and sys.argv[1] == "--cli":
        util_command_line()
    else:
        util_gui()

这段代码本身并不复杂，但对一个日常工具来说足够可靠了。写这篇记录的时候我又重新检查了一遍，几个关键点处理得都比较干净：竖线转义、换行处理、空单元格补齐、命令行与 GUI 双入口。

5. 打包和日常使用：从脚本到“成品小工具”

5.1 打包成 Windows 可执行文件

Python 脚本要给别人用，或者想在别人的电脑上免装环境运行，最好打包成 exe。这一步我也让 Trae 处理了，并在它的提示下用了 PyInstaller。

打包过程简单，在终端执行：

bash复制pip install pyinstaller
pyinstaller -F -w excel_to_markdown.py

解释一下参数：

• -F：打包成单个 exe 文件。
• -w：不显示命令行窗口，只显示 GUI 窗口。

打包完成后，dist 目录下会出现一个 excel_to_markdown.exe，把它丢到桌面或固定到任务栏，用的时候点开就行。实测下来 exe 体积大约 8MB 左右，启动很快，不依赖目标机器上有 Python 环境。

需要提醒一句：如果你开启了 Windows Defender 或第三方杀毒软件，PyInstaller 打包出来的文件偶尔会被误报，这是知名开发工具的通病，不是病毒。遇到这种情况可以添加信任目录，或者换用不同的打包参数（比如不使用 -F 而是打包成目录形式）来降低误报率。

5.2 我的日常使用流

工具做出来不是终点，好用才是目标。我现在最顺手的用法有两种：

一种是写文章时，Excel 表格需要进入 Markdown 文档。直接在 Excel 复制，打开工具粘贴，点转换，回文档粘贴。两步操作，五秒内搞定。

另一种是写周报。我们团队周报是 Markdown 格式，里面有一个项目进度表，我平时维护的是 Excel 版本。每周写完进度，复制，转换，粘贴，格式永远一致，不再担心手工排版错位。

另外一个进阶用法：如果你经常需要从 Excel 转 Markdown，可以配合一个全局快捷键工具（比如 PowerToys Run 的自定义命令），让 exe 通过快捷键唤起，会更快。

5.3 关于 Trae 的几条实战心得

经过这个项目，我对 Trae 这类 AI 编程工具有了几个比较实际的认知：

第一，提示词的质量直接决定代码质量。不是“帮我写个工具”就能得到好工具，而是要说清楚使用场景、平台、输入输出方式、约束条件。你描述得越接近真实用户的操作路径，AI 产出的代码越接近能直接用的成品。

第二，AI 生成代码之后，一定要自己读代码、改代码、跑测试。这不是信任问题，而是工程质量问题。AI 第一次生成的代码大概率能覆盖主流程，但边界情况——竖线转义、换行符处理、空指针——需要在真实使用中暴露和修复。

第三，Trae 的迭代模式特别适合小工具开发。第一版出来了，你拿它做几个真实测试，发现问题后直接说“这个单元格里的竖线导致格式乱了，帮我修复”，Trae 能精准定位修改位置。这种“对话式调试”体验，比传统改代码快很多。

第四，免费工具的可用性已经超出我的预期。过去写脚本、调试环境、打包分发，每一步都可能卡住。Trae 把这些步骤的摩擦降到了很低，让一个普通用户也能完成从灵感到工具的闭环。当然，免费策略能持续多久不好说，我打算在系列文章里继续记录它的能力和限制，方便后来的人参考。

写在最后的一点个人体会

说实话，做一个 Excel 转 Markdown 的小工具，技术含量并不高。如果自己从零手写，半小时内也能完成。但这个项目的价值不在于代码本身，而在于让我体验到了“和 AI 说人话就能产出可用工具”的工作方式。它把开发的门槛从一个需要系统学习的过程，变成了一个表达需求、验证结果、逐步修正的自然过程。

言出法随，重点不在“法”（代码），而在“言”（需求表达）。你越清楚自己真正想要什么，越能把它拆成一句话里的明确条件，AI 就越能给你想要的东西。这也是我接下来在这个系列中想持续探讨的主题。

第二个项目我计划做一个小小的 PDF 工具，把扫描版合同里密密麻麻的页面按关键字段批量提取，做成表格导入 Notion。这个需求更复杂，也会遇到更多边界情况，到时候继续把这个过程完整记录下来。