企业官网建设流程全解析

1. 长文档标题编号失控的真实场景

你手里有一份 3000 行的 Markdown 技术文档，可能是项目 README、课程笔记、接口手册，也可能是从多个来源拼起来的规范文档。打开大纲视图一看，##和###混着用，有的章节有编号有的没有，中间插了一节之后后面全乱。手动改？改到第 80 行就已经不知道当前是第几级了。

这个场景的核心痛点不是「不会写 Markdown」，而是批量修缮：文档已经存在，结构已经乱了，你需要一套可重复执行、可验证的编号方案。VSCode 本身不负责标题编号，它只负责渲染和编辑，所以真正干活的是插件加配置的组合。

我试过纯手工编号、纯 Python 脚本、以及插件加脚本混合三种路线。纯手工在超过 50 个标题后必然出错；纯脚本灵活但每次都要改路径；插件加脚本的组合最稳，日常用插件一键编号，遇到插件处理不了的边界情况再用脚本兜底。

这篇文章聚焦三件事：VSCode 里装什么插件、settings.json怎么写配置骨架、以及编号完成后怎么验证层级连续性和正确性。适合需要批量修缮长文档的开发者，尤其是那些文档要交付给团队或发布到文档站的场景。

顺带说一句，如果你在写文档时需要调用大模型来辅助生成或校对内容，TaoToken 的模型对话入口可以直接在浏览器里用，不用额外装客户端，地址在文末 CTA 部分会给。

2. TaoToken 前置：API Key 与接入文档准备

在进入 VSCode 配置之前，先把模型调用这条链路打通。原因很简单：长文档修缮过程中，你可能需要让模型帮你检查标题层级是否合理、或者批量生成缺失的章节说明。这时候有一个稳定的 API 入口会省很多事。

TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base URL 使用。你需要先拿到 API Key，操作路径是：登录后进入控制台，在 API Keys 页面创建一个新的 Key。创建时建议按用途命名，比如vscode-md-fix，方便后续排查是哪个环境在用。

拿到 Key 之后，接入文档里有完整的请求示例，包括 chat completions 的 endpoint 格式、鉴权 header 写法、以及常见模型的 model name 列表。如果你用的是 Claude Code 这类编码 Agent，TaoToken 也提供了对应的 Anthropic 兼容入口，配置方式和标准 API 略有不同，具体看文档里的 ClaudeCodeAnthropic 章节。

这里要提醒一点：API Key 不要硬编码在 Markdown 文件或脚本里然后提交到 Git。建议放在环境变量或者 VSCode 的settings.json里通过${env:VAR_NAME}引用。后面第 3 节的配置骨架里会给出这种写法。

控制台地址和 API Keys 页面都可以从官网导航进入，官网入口在文末。先把 Key 准备好，后面配置插件时如果要用到模型辅助校验，直接填进去就行。

3. 可复制的 settings.json 配置骨架与插件组合

这一节是全文的技术核心。先明确插件组合：Markdown All in One负责标题编号和快捷键，Markdown Preview Enhanced负责预览时显示编号效果，Paste Image负责图片转存（长文档通常图文混排，图片路径乱了也会影响编号后的可读性）。

3.1 插件安装与快捷键设定

在 VSCode 扩展面板搜索并安装上述三个插件。安装完成后，Markdown All in One 默认的标题编号快捷键是Shift+Alt+M，但这个快捷键在部分键盘布局下会和输入法冲突。建议在keybindings.json里改成Ctrl+Alt+N：

[ { "key": "ctrl+alt+n", "command": "markdown.extension.numbering", "when": "editorLangId == markdown" } ]

when条件很重要，不加的话在非 Markdown 文件里按这个键也会触发，容易误操作。

3.2 settings.json 配置骨架

下面这份配置可以直接复制到你的 VSCodesettings.json里。我把它分成三段：Markdown 编辑行为、编号相关、以及模型调用占位。

{ "markdown.extension.toc.levels": "2..6", "markdown.extension.toc.omittedFromToc": {}, "markdown.extension.toc.updateOnSave": false, "markdown.extension.list.indentationSize": "adaptive", "markdown.extension.orderedList.autoRenumber": true, "markdown.extension.orderedList.marker": "one", "markdown.extension.preview.autoShowPreviewToSide": false, "markdown.extension.numbering.enabled": true, "markdown.extension.numbering.separator": ".", "markdown.extension.numbering.startAt": 1, "markdown.extension.numbering.includeLevel1": true, "markdown.extension.numbering.skipExisting": false, "markdown.preview.breaks": true, "markdown.preview.typographer": false, "[markdown]": { "editor.wordWrap": "on", "editor.quickSuggestions": { "other": true, "comments": false, "strings": false }, "editor.defaultFormatter": "yzhang.markdown-all-in-one" }, "taotoken.apiBase": "https://taotoken.net/api", "taotoken.apiKey": "${env:TAOTOKEN_API_KEY}", "taotoken.model": "claude-sonnet-4-20250514" }

逐项说明几个关键配置。markdown.extension.numbering.separator控制编号分隔符，默认是.，如果你想要1-1-1这种风格就改成-。markdown.extension.numbering.includeLevel1决定是否给一级标题也加编号，技术文档通常需要，所以设为true。markdown.extension.numbering.skipExisting设为false表示已有编号会被重新计算，这在修缮场景下是必须的，否则旧编号会残留导致层级错乱。

markdown.extension.toc.updateOnSave设为false是有意为之。长文档保存频率高，每次保存都更新目录会拖慢编辑器响应，建议手动触发目录更新。

最后三行是 TaoToken 的配置占位。apiKey用${env:TAOTOKEN_API_KEY}引用环境变量，这样配置文件可以安全地提交到团队仓库。环境变量的设置方式：Windows 用setx TAOTOKEN_API_KEY "你的key"，macOS/Linux 在~/.zshrc或~/.bashrc里加export TAOTOKEN_API_KEY="你的key"。

3.3 编号规则与层级对照

Markdown All in One 的编号逻辑是：按标题在文档中出现的顺序，逐级递增。下面这张表帮你理解不同标题组合下的编号结果：

注意第三行的情况：如果文档没有一级标题，插件默认从二级开始编号，结果会是1、2而不是0.1、0.2。这个行为在includeLevel1为true时也成立，因为插件把最高级标题当作编号起点。

4. 验证请求与成功结果

配置写完之后，必须验证两件事：编号是否连续、层级是否正确。这里给出一套可复现的验证流程。

4.1 一键编号操作步骤

打开你的 Markdown 文件，按Ctrl+Alt+N（或你自定义的快捷键）。插件会扫描全文所有#开头的行，按层级重新编号。编号完成后，打开大纲视图（Ctrl+Shift+O），检查标题列表。

一个典型的成功结果如下：

# 1 项目概述 ## 1.1 背景 ## 1.2 目标 ### 1.2.1 功能目标 ### 1.2.2 性能目标 # 2 架构设计 ## 2.1 模块划分 ## 2.2 数据流

如果出现1.2.1后面直接跳到1.3，说明中间有标题被漏掉了，或者层级判断出错。这时候用下一节的排查方法定位。

4.2 用脚本验证编号连续性

插件编号完成后，建议用一段 Python 脚本做二次校验。这段脚本读取 Markdown 文件，提取所有标题，检查编号是否连续、层级是否合法：

import re def validate_numbering(file_path): with open(file_path, 'r', encoding='utf-8') as f: lines = f.readlines() pattern = r'^(#+)\s+([\d.]+)\s+(.+)$' stack = [] errors = [] for i, line in enumerate(lines, 1): m = re.match(pattern, line.strip()) if not m: continue level = len(m.group(1)) number = m.group(2) parts = [int(x) for x in number.split('.')] if len(parts) != level: errors.append(f"行 {i}: 编号 {number} 层级与标题级别 {level} 不匹配") continue while len(stack) < level: stack.append(0) stack = stack[:level] stack[level-1] += 1 expected = '.'.join(str(x) for x in stack) if number != expected: errors.append(f"行 {i}: 期望 {expected}，实际 {number}") if errors: print("发现编号问题：") for e in errors: print(" ", e) else: print("编号验证通过，所有标题连续且层级正确。") validate_numbering(r'./your-doc.md')

运行结果如果是「编号验证通过」，说明插件编号正确。如果有报错，报错信息会直接告诉你哪一行的编号和期望值不一致，方便手动修正。

4.3 用模型辅助检查语义层级

编号正确不代表层级合理。比如「安装步骤」被放在「架构设计」下面，编号是连续的，但语义上不对。这时候可以用 TaoToken 的模型对话入口，把大纲贴进去让模型判断层级是否合理。模型对话地址在文末 CTA 部分，直接浏览器打开就能用，不需要额外配置。

5. 本篇常见错排查

5.1 编号后标题重复出现序号

现象：执行编号后，标题变成# 1 1 项目概述，多了一层序号。

原因：文档里已经有旧编号，而skipExisting被设成了true，插件在旧编号前面又加了一层。

解决：把markdown.extension.numbering.skipExisting改为false，重新执行编号。如果旧编号格式不统一（有的用1.有的用1、），先用正则批量清理：

import re content = re.sub(r'^(#+)\s+[\d.]+\s+', r'\1 ', content, flags=re.MULTILINE)

这段代码把所有标题行里已有的编号去掉，只保留#和标题文字，然后再用插件重新编号。

5.2 代码块内的#被误编号

现象：Python 代码块里的注释# 这是注释被插件当成了标题，加了编号。

原因：Markdown All in One 的编号逻辑默认不区分代码块，它按行扫描#开头的内容。

解决：在settings.json里确认markdown.extension.numbering.enabled为true的同时，检查代码块是否用了正确的围栏语法。必须用三个反引号加语言标识：

# 这是代码块内的注释，不会被编号 def foo(): pass

如果代码块用了缩进式（四个空格）而不是围栏式，插件可能识别不到边界。统一改成围栏式即可。

5.3 编号后目录链接失效

现象：文档开头的 TOC 链接点击后跳转不到对应标题。

原因：TOC 里的锚点是根据标题文字生成的，编号后标题文字变了，锚点没更新。

解决：把markdown.extension.toc.updateOnSave临时设为true，保存一次让 TOC 重新生成，然后再设回false。或者手动执行命令面板里的Markdown All in One: Create Table of Contents。

5.4 多级序号在预览中不显示

现象：编辑区有编号，但预览区看不到。

原因：预览用的渲染器不解析编号，编号只是纯文本。

解决：编号本身就是文本，预览区应该能看到。如果看不到，检查是不是用了 Markdown Preview Enhanced 的自定义 CSS 把标题文字隐藏了。在预览区右键选择「Open in Browser」用浏览器打开，对比一下显示效果。

5.5 API 调用返回 401

现象：用 TaoToken API 做模型辅助校验时返回 401 Unauthorized。

原因：API Key 没设置、设置错了、或者环境变量没生效。

解决：先在终端里echo $TAOTOKEN_API_KEY（Windows 用echo %TAOTOKEN_API_KEY%）确认环境变量有值。如果没有，重新设置并重启 VSCode。如果环境变量有值但仍报 401，去控制台的 API Keys 页面确认 Key 是否被禁用或删除。接入文档里有完整的鉴权 header 示例，对照检查Authorization: Bearer <key>的格式是否正确。

6. 接入与排障入口

编号验证通过之后，如果你想把模型调用集成到文档工作流里，比如自动生成章节摘要、检查术语一致性，可以从 API Keys 页面创建一个专用 Key，然后参考接入文档里的请求示例写脚本。API Keys 入口和接入文档都在官网导航里，官网地址是https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。

如果你更习惯在浏览器里直接和模型对话来辅助校对文档，模型对话入口更适合你，不用写代码，贴进去就能问。长期做编码和 Agent 开发的，可以看 Coding Plan 页面，里面有按量计费和包月方案的对比。

排障方面，编号问题优先查settings.json里的skipExisting和includeLevel1两个开关；API 问题优先查环境变量和 Key 状态。这两类问题覆盖了 90% 以上的报错场景。