1. 为什么 Markdown 标题编号总在返工：Cursor 里跑 Python 脚本的真实场景
写技术博客的人大概率都遇到过这个场景：一篇 Markdown 文档写到一半，突然想在第三章前面插一节新内容。插进去容易，但后面所有## 3.x、### 3.x.x的编号全得手动往后挪一位。文档越长，这种连锁修改越让人崩溃。更麻烦的是，很多人在写作阶段根本不确定最终会有几个一级标题，只能先写## 环境准备、## 配置说明这种不带编号的裸标题，等全文写完再统一补编号——而这一步如果靠手工，几十个标题改下来眼睛都花了。
我自己的做法是把这件事交给脚本。核心思路很简单：Markdown 的标题有明确的语法特征，就是以#开头、后面跟空格和文字，层级由#的数量决定。只要按行扫描，维护一个各级计数器的数组，遇到标题就递增对应层级、重置更深层级，然后把编号拼回标题前面就行。这个逻辑用 Python 写不到一百行，但真正让它变得好用，是把它放进 Cursor 里，用对话的方式生成、调试、批量跑。
这里有个容易被忽略的点：脚本本身不难，难的是「让 AI 稳定地帮你改脚本」。如果你在 Cursor 里直接让模型生成代码，它每次给的实现风格可能都不一样，改到第三轮你自己都记不清哪个版本是对的。我的经验是配一个统一的模型接入层，把 Key 和 Base URL 固定下来，这样无论换哪个模型、哪个工具，调用方式都一致，调试脚本时不会因为接入问题分心。TaoToken 在这里扮演的就是这个统一入口的角色——一个 Key 走通对话和代码补全，省去在多个平台之间来回切换的麻烦。
这篇文章面向的是经常写 Markdown 长文、又不想被编号折磨的人。你不需要精通 Python，只要能看懂基本的缩进和函数调用，跟着下面的步骤就能复现。整个流程分四块：先把 Cursor 的模型接入配好，再写编号脚本，然后做单文件和批量两种模式的验证，最后处理几个常见的报错。每一步都有可复制的配置和命令，跑完你就能得到一个能反复用的自动化编号工具。
2. 在 Cursor 里接入 TaoToken 统一 Key：Base URL 与模型配置实操
Cursor 的模型配置入口在设置里，但很多人第一次找会绕路。打开 Cursor，点右上角齿轮图标进入 Settings，左侧选 Models 标签页。这里能看到 OpenAI API Key、Base URL 等字段。关键操作是：把 Base URL 改成 TaoToken 的 API 地址，Key 填你在控制台生成的令牌，然后在模型列表里手动添加你要用的模型 ID。
先说地址。API 端点是https://taotoken.net/api，注意这个地址不带任何查询参数，直接填在 Base URL 输入框里。如果你用的是 OpenAI 兼容模式，Cursor 会自动在这个地址后面拼接/v1/chat/completions这类路径，所以不要自己手动加/v1，否则会变成双份路径导致 404。Key 的获取在控制台页面，登录后进 API Keys 菜单，点创建新密钥，复制那串以sk-开头的字符串。这个 Key 只显示一次，建议当场存进密码管理器。
模型 ID 这块要留意。Cursor 的模型列表里默认有一堆官方模型名，但你走的是自定义 Base URL，需要手动 Add model，填入 TaoToken 支持的模型标识。比如你想用 Claude 系列做代码生成，就填对应的模型 ID；想用 GPT 系列做对话调试，就填另一个。填完之后在聊天框上方的模型下拉里选中它，才算真正生效。
配置片段可以这样记：Base URL 填https://taotoken.net/api，API Key 填sk-开头的令牌，Model 填你选定的模型 ID。这三件套缺一不可，而且顺序上建议先填 Key 再填 Base URL，因为有些版本的 Cursor 会在你改 Base URL 时触发一次连接测试，Key 没填会直接报鉴权失败，容易误判成地址写错了。
配好之后做个最小验证：在 Cursor 聊天框里输入「用 Python 写一个读取文件并打印行数的函数」，看它能不能正常返回代码。如果能返回且没有报错，说明接入通了。这一步别跳过，因为后面写编号脚本时会频繁让模型改代码，接入不稳会浪费大量时间在排查网络问题上。
另外提一句，Cursor 的 Settings 里有个「Verify」按钮，点它会发一个测试请求。如果返回 401，八成是 Key 复制时带了空格或者漏了字符；如果返回连接超时，检查 Base URL 是不是多写了斜杠或者用了 http 而不是 https。这些细节在下一节的排错部分会展开。
3. 可复制的 Python 编号脚本与 Cursor 配置片段
脚本的核心逻辑分三步：解析、计数、重写。解析阶段逐行读取 Markdown，用正则匹配^(#{1,6})\s+(.*)$提取层级和标题文字。计数阶段维护一个长度为 6 的数组counters，遇到层级 n 的标题时，counters[n-1] += 1，并把counters[n:]全部清零——这一步是保证编号连续的关键，比如从## 2.3跳到### 2.3.1再回到## 2.4时，三级计数器要归零。重写阶段把编号拼成1.2.3的形式，根据配置决定编号和标题之间加不加空格、二级以下加不加点号。
下面是可以直接复制运行的完整脚本。我把它放在项目根目录的md_numbering.py里，用python md_numbering.py input.md就能跑。
import re import sys import os from pathlib import Path HEADING_RE = re.compile(r'^(#{1,6})\s+(.*)$') def number_markdown(text, start=1, space=True, dot_below=True): lines = text.splitlines() counters = [0] * 6 counters[0] = start - 1 out = [] for line in lines: m = HEADING_RE.match(line) if not m: out.append(line) continue level = len(m.group(1)) title = m.group(2).strip() counters[level - 1] += 1 for i in range(level, 6): counters[i] = 0 parts = [str(counters[i]) for i in range(level)] if level >= 2 and dot_below: num = '.'.join(parts) + '.' else: num = '.'.join(parts) sep = ' ' if space else '' out.append(f"{'#' * level} {num}{sep}{title}") return '\n'.join(out) def process_file(src, dst=None): src_path = Path(src) if dst is None: dst_path = src_path.with_name(src_path.stem + '-numbered' + src_path.suffix) else: dst_path = Path(dst) text = src_path.read_text(encoding='utf-8') result = number_markdown(text) dst_path.write_text(result, encoding='utf-8') print(f"done: {src_path} -> {dst_path}") def process_dir(folder): folder_path = Path(folder) for md in folder_path.glob('*.md'): if md.stem.endswith('-numbered'): continue process_file(md) if __name__ == '__main__': if len(sys.argv) < 2: print("usage: python md_numbering.py <file_or_dir>") sys.exit(1) target = sys.argv[1] if os.path.isdir(target): process_dir(target) else: process_file(target)在 Cursor 里用的时候，你可以直接把这段代码贴进聊天框，然后说「帮我把二级标题的点号改成可选参数」。模型会基于这段代码改，而不是从零生成，这样风格和变量名都保持一致。这就是为什么前面要先把接入配稳——改代码时模型需要理解上下文，接入不稳会导致它读不到你贴的代码。
配置片段方面，如果你用 Cursor 的.cursorrules文件来固定项目规范，可以加一段：
{ "model": "your-model-id", "baseUrl": "https://taotoken.net/api", "rules": [ "Python 脚本统一用 pathlib 处理路径", "Markdown 标题正则固定为 ^(#{1,6})\\s+(.*)$", "输出文件统一加 -numbered 后缀" ] }这个文件放在项目根目录，Cursor 每次对话都会读取，相当于给模型一个固定的工作约束。注意baseUrl这里写的是 API 地址，Key 不要写进这个文件，Key 放在 Cursor 的 Settings 里更安全。
脚本里有个细节值得说：counters[0] = start - 1这行是为了支持自定义起始序号。如果你希望第一个一级标题从 0 开始，传start=0就行。另外process_dir里跳过了已经带-numbered后缀的文件，防止重复处理时把编号叠加两层。这个坑我踩过——第一次批量跑完没检查，第二次又跑了一遍，结果标题变成了1.1.1这种。
4. 验证请求与运行结果：编号前后标题层级对比
跑脚本之前，先准备一个测试用的 Markdown 文件，内容故意写得层级跳跃一点，这样才能验证计数器归零逻辑对不对。比如：
# 项目说明 ## 环境准备 ### 安装依赖 ### 配置变量 ## 快速开始 # 进阶用法 ## 自定义参数 ### 参数详解保存为test.md，然后在终端执行python md_numbering.py test.md。跑完之后同目录会出现test-numbered.md，打开对比：
# 1. 项目说明 ## 1.1 环境准备 ### 1.1.1 安装依赖 ### 1.1.2 配置变量 ## 1.2 快速开始 # 2. 进阶用法 ## 2.1 自定义参数 ### 2.1.1 参数详解重点看两处：一是## 1.2 快速开始之后跳到# 2. 进阶用法，一级计数器从 1 变 2，二级计数器归零，所以下一个二级标题是2.1而不是1.3；二是### 1.1.2之后回到## 1.2，三级计数器归零，所以没有出现1.2.1这种残留。这两处对了，说明计数逻辑没问题。
批量模式验证：新建一个文件夹，放三四个.md文件进去，执行python md_numbering.py ./docs。脚本会遍历文件夹下所有.md，逐个生成-numbered版本。跑完用ls docs/*-numbered.md确认文件都生成了。如果某个文件没生成，检查它是不是已经在文件名里带了-numbered，或者是不是编码不是 UTF-8 导致读取失败。
在 Cursor 里验证的方式更直观：把test.md和test-numbered.md并排打开，用 Cursor 的 diff 功能对比。如果编号有错位，直接在聊天框里说「1.2 后面的三级标题编号不对，应该是 1.2.1 但现在是 1.1.3」，模型会定位到计数器归零那几行帮你改。这种交互式调试比自己在终端反复跑快得多。
还有一个验证动作是检查边界情况：文档里如果有代码块，代码块内部以#开头的行会不会被误判成标题？比如 Python 注释# 这是注释。当前脚本的正则是^(#{1,6})\s+，要求#后面必须跟空格，而 Python 注释通常是# 注释也带空格，所以会被误伤。解决办法是在解析时跳过代码块区域，用一个in_code标志位，遇到 ``` 就翻转。这个改进可以让模型帮你加，改完再跑一遍测试文件确认代码块没被动。
5. 常见报错排查：401、local proxy failed 与 reading choices 对照
接入和运行过程中最容易撞上三类报错，我按实际遇到的频率排一下。
第一类是 401 Unauthorized。这个基本都出在 Key 上。表现是 Cursor 聊天框返回「Authentication failed」或者终端里 curl 测试返回{"error":{"message":"invalid api key"}}。排查顺序：先确认 Key 有没有复制完整，sk-后面那串字符一个都不能少；再确认 Key 有没有过期或被禁用，去控制台看状态；最后确认 Base URL 有没有写错，如果地址写成了别的域名，请求根本到不了鉴权环节，但有些客户端会统一报 401，容易误导。我试过把 Key 末尾的空格带进去，折腾了十分钟才发现。
第二类是 local proxy failed。这个报错通常出现在 Cursor 的网络设置里。Cursor 默认可能走系统代理，如果你的环境里配了代理但代理没启动，就会报这个。解决方式是在 Cursor Settings 里找到 Network 相关选项，把代理模式改成「No proxy」或者「System proxy」试一下。注意这里说的是客户端自身的网络配置，不是让你去搭什么通道，只是把 Cursor 的代理开关关掉让它直连。如果关掉后能通，说明之前是代理配置和实际网络环境不匹配。
第三类是 reading choices 相关的报错，完整信息可能是error reading choices: unexpected end of JSON input或者no choices in response。这个一般不是鉴权问题，而是模型返回的响应格式和客户端预期不一致。常见原因有两个：一是模型 ID 填错了，请求发到了一个不存在的模型，服务端返回了错误结构；二是请求体里的参数不兼容，比如某些模型不支持temperature或max_tokens的某些取值。排查方法是把模型 ID 换成确认可用的，然后在 Cursor 里发一个最简单的「你好」测试，如果简单请求能通，说明是参数问题，逐步加回参数定位。
还有一类是 OAuth 相关的提示，比如让你重新登录或者 token 刷新失败。这个在 Cursor 里通常和账号登录态有关，跟 API Key 是两套体系。如果你用的是 API Key 模式，忽略 OAuth 提示即可；如果 Cursor 强制走 OAuth 登录，检查一下是不是账号掉线了，重新登录一次。
排错时有个通用技巧：在终端用 curl 直接打 API，绕过 Cursor 的封装，这样能快速区分是接入问题还是客户端问题。命令大概是这样：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"你的模型ID","messages":[{"role":"user","content":"hi"}]}'如果 curl 能返回正常 JSON，说明 Key 和地址都没问题，报错出在 Cursor 的配置上；如果 curl 也报错，那就是 Key 或地址本身的问题。这个二分法能省很多时间。
6. 把编号脚本变成日常工具：接入文档与 Coding Plan 的选择
脚本跑通之后，下一步是让它变成你写作流程的一部分。我的做法是在项目根目录放一个Makefile或者run.sh，写完文档执行一条命令就自动编号。比如：
#!/bin/bash python md_numbering.py ./posts配合 Cursor 的终端，写完直接按快捷键跑，不用切窗口。如果你经常处理多个项目，可以把脚本装成全局命令，用pip install -e .配合entry_points注册一个mdnum命令，这样在任何目录都能调用。
关于模型接入的长期使用，如果你只是偶尔写写文档、调调脚本，按量付费的 API Key 模式就够了，用多少算多少。但如果你每天都在 Cursor 里做代码生成、让模型帮你改脚本、跑批量任务，那可以考虑 Coding Plan 这类包月方案，成本更可控。具体选哪种，去控制台看一下用量统计再决定，别一上来就买大的。
接入文档在https://taotoken.net/doc，里面有各语言的调用示例和参数说明，遇到不确定的字段可以去查。API Keys 管理在https://taotoken.net/api-keys，创建和吊销都在这里。如果你想让模型直接对话调试脚本，用模型对话页面https://taotoken.net/chat更快，不用每次都开 Cursor。
最后说个实用技巧：编号脚本处理中文标题时，如果标题里本身带了数字，比如「3 种方法」，编号后会变成「1.1 3 种方法」，看起来有点重复。可以在脚本里加一个判断，如果标题开头已经是数字加空格，就跳过编号或者把原数字去掉。这个改动让模型帮你写，一句话的事。工具是死的，流程是活的，把重复劳动交给脚本，把判断留给自己，这才是自动化真正的价值。
