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 统一 KeyBase 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/apiAPI 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, start1, spaceTrue, dot_belowTrue): 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, dstNone): 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(encodingutf-8) result number_markdown(text) dst_path.write_text(result, encodingutf-8) print(fdone: {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 开始传start0就行。另外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 种方法」看起来有点重复。可以在脚本里加一个判断如果标题开头已经是数字加空格就跳过编号或者把原数字去掉。这个改动让模型帮你写一句话的事。工具是死的流程是活的把重复劳动交给脚本把判断留给自己这才是自动化真正的价值。