VS Code 文档仓库专用 Markdown 写作助手：doc-assistant 扩展的完整实现解析-北京尧图网络

文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载本指南深入剖析 vscode-docs 仓库中内置的VS Code Doc AI Assistant.vscode/extensions/doc-assistant扩展它如何为feature(id)特性标记、FeatureStatusfrontmatter 与{% data variables.group.name %}可复用变量提供补全、悬停、诊断与快速修复如何通过语言模型工具Language Model Tools驱动 release notes 的自动生成以及如何本地开发、编译与测试该扩展。阅读本文后你将掌握这套文档即数据的写作辅助机制背后的完整工作原理与可复用的实现范式。扩展概览与定位doc-assistant是一个内嵌于 vscode-docs 仓库的 VS Code 扩展Extension Development 模式它服务于两类核心任务Markdown 写作辅助在编辑 Markdown 时提供特性 ID、可复用变量的补全Completions、悬停详情Hover、未知引用诊断Diagnostics与拼写快速修复Quick Fixes。语言模型工具向 Copilot Chat 等语言模型注册getCurrentMilestone与getReleaseFeatures两个工具用于自动获取当前 VS Code 里程碑名称和当前版本的功能列表支撑 release notes 的编写与生成。扩展的声明信息位于 .vscode/extensions/doc-assistant/package.json名称为vscode-doc-assistant发布者为ms-vscode版本0.0.1要求 VS Code^1.95.0通过onLanguage:markdown激活主入口为./dist/extension.jswebpack 打包产物。Markdown 写作辅助功能详解扩展的写作辅助能力全部围绕两类注册表数据源展开特性注册表build/feature-lifecycle.json提供feature(id)标记与FeatureStatusfrontmatter 的补全与校验变量注册表data/variables目录下的.yml/.yaml文件提供{% data variables.group.name %}指令的补全与校验。这两个数据源正是写作辅助的知识库补全候选、悬停内容、未知引用诊断都基于它们生成。特性引用feature(id)标记与FeatureStatusfrontmatterfeature(id)是仓库文档中标注特性生命周期状态的专用标记例如feature(typescript-5-8)。写作辅助支持在两种场景下补全特性 ID正文中的feature(id)标记Markdown 文件 YAML frontmatter 中的FeatureStatus:字段。补全触发与解析逻辑实现在 .vscode/extensions/doc-assistant/src/markdown/providers.ts 的completionContext函数中它通过正则识别输入前缀/\{%\s*data\svariables\.([^%}]*)$/命中时提供变量补全/feature\(([^)]*)$/命中时提供特性补全若当前位于 frontmatter 区域文件首行为---且尚未闭合/^\s*FeatureStatus:\s*([^\s#]*)$/命中时同样提供特性补全。引用解析的完整语法在 .vscode/extensions/doc-assistant/src/markdown/references.ts 的findDocumentationReferences中定义支持三种引用类型ReferenceKind类型语法说明featurefeature(id)正文中的特性生命周期标记featureStatusfrontmatter 中FeatureStatus: id文档级特性状态声明variable{% data variables.group.name %}可复用变量指令解析器会跳过代码围栏或~~~块内的内容避免误报同时会检测不完整的引用——行尾缺少闭合)的feature(...或缺少%}的{% data ...分别记为incomplete-feature与incomplete-variable。可复用变量{% data variables.group.name %}指令变量体系的设计说明位于 data/variables/README.md可复用变量是网站构建时会被替换的短文本存放在data/variables目录下的.yml/.yaml文件中。变量路径由命名空间固定为variables 相对路径目录文件名去扩展名点号分隔 YAML 键拼接而成。例如文件data/variables/product.yml中的键prodname_vscode对应变量路径variables.product.prodname_vscode。实际变量示例见 data/variables/product.yml其中定义了VS Code、Visual Studio Code、Settings Sync、GitHub Copilot、Codespaces等产品名变量。在 Markdown 正文或字符串型 YAML frontmatter 中通过以下指令引用{% data variables.product.prodname_vscode %}变量文件的解析采用零依赖的自研解析器见 .vscode/extensions/doc-assistant/src/markdown/registry.ts 的parseVariableFile仅支持 YAML 的子集注释#与空行每行一个扁平的key: value条目不支持缩进嵌套映射与块序列- item任何缩进行都会抛出Indented mappings are not supported.错误所有值一律作为字面文本替换不做布尔/数字/null 类型强转需要保留首尾空白或包含#/:字符时用引号包裹双引号支持\、\\、\n、\t转义单引号支持转义单引号不支持YAML 锚点name、别名*name与流式集合{...}/[...]并会拒绝包含这些语法或冒号的值。悬停详情展示生命周期状态与变量解析值悬停Hover支持在任意引用上展示上下文信息实现在DocumentationHoverProvider特性引用feature(id)或FeatureStatus显示生命周期状态Experimental/Preview、ID若注册表中有trackingUrl则附带Open tracking issue链接变量引用显示其解析后的值代码块形式以及定义所在文件与行号如Defined in data/variables/product.yml:5。诊断未知引用与不完整语法诊断Diagnostics仅对已发布文档目录生效即docs、api、remote、release-notes、blogs下的 Markdown 文件见 references.ts 的publishedFolders集合与isPublishedDocument判断补全与悬停则对仓库内任意 Markdown 文件可用。诊断类型与严重级别如下诊断 code消息示例严重级别unknown-variableUnknown reusable variable variables.foo.bar.Errorunknown-featureUnknown feature lifecycle ID foo.Warningincomplete-featureFeature lifecycle marker is missing a closing parenthesis.Warningincomplete-variableReusable variable directive is missing a closing %}.Warningregistry-errorUnable to load documentation registries: ...Error诊断的触发时机覆盖完整编辑生命周期打开文档、编辑文档、关闭文档都会触发重新校验注册表变更onDidChange时也会重新校验同一工作区文件夹下的全部打开的文档。校验逻辑通过validationVersions版本号映射做并发去重——只有最新一次校验结果才会写入诊断集合避免过期结果覆盖新内容。快速修复拼写纠错与闭合符补全DocumentationCodeActionProvider提供两类 Quick Fix不完整语法修复对incomplete-feature在光标处插入)对incomplete-variable插入%}标记为 preferred未知引用替换对unknown-feature/unknown-variable基于Levenshtein 编辑距离对全部候选键排序距离阈值取max(2, 查询长度 × 0.35)最多给出 3 个候选rankCandidates函数最近的一个标记为 preferred每个候选生成一个Replace with ...动作。例如误写feature(typescript-58)时编辑器会诊断未知 ID 并建议替换为最接近的typescript-5-8。注册表加载与热更新机制DocumentationRegistryregistry.ts负责加载、缓存与监控两份注册表是整个辅助功能的底层支撑。特性注册表格式feature-lifecycle.json特性注册表从build/feature-lifecycle.json读取要求严格的 JSON 结构{ $schema: https://..., // 可选 features: { typescript-5-8: { // ID 必须匹配 ^[a-z0-9](?:-[a-z0-9])*$ label: TypeScript 5.8, state: preview, // 仅允许 experimental 或 preview trackingUrl: https://... // 可选必须是 https 链接 } } }loadFeatures会严格校验顶层仅允许$schema与features两个键每个特性 ID 必须是小写字母数字与连字符label必须是非空字符串state仅允许experimental/previewtrackingUrl若提供必须是有效 https URL。任一条件不满足都会抛出带文件路径的明确错误。变量注册表加载与命名冲突检测loadVariables使用data/variables/**/*.{yml,yaml}模式查找变量文件按路径排序后逐个解析文件相对data/variables的路径目录去扩展名的文件名转换为点号分隔的 group 前缀最终变量路径为variables.group.key重复键在同一文件内、以及同一变量路径在不同文件中重复定义都会抛出Duplicate reusable variable错误避免歧义注册表快照RegistrySnapshot以 workspace folder 为 key 做 Promise 缓存getSnapshot并发请求共享同一次加载。文件监听与失效注册表目录通过FileSystemWatcher监控两个模式build/feature-lifecycle.json与data/variables/**/*.{yml,yaml}。任何onDidChange/onDidCreate/onDidDelete事件都会触发invalidate——清除缓存并通过onDidChange事件通知所有打开文档重新校验。工作区文件夹的增删也会动态注册/注销监听器。若注册表缺失或无效扩展会在VS Code Doc Writer输出通道vscode.window.createOutputChannel(VS Code Doc Writer, { log: true })记录错误日志并在所有已打开的已发布 Markdown 文件首行位置注入registry-error诊断同一错误仅上报一次reportedErrors去重避免刷屏。语言模型工具驱动 release notes 生成扩展的另一半职责是为语言模型提供数据工具注册逻辑见 .vscode/extensions/doc-assistant/src/extension.tscontext.subscriptions.push(vscode.lm.registerTool(GetReleaseFeatures.ID, new GetReleaseFeatures(logger))); context.subscriptions.push(vscode.lm.registerTool(GetCurrentMilestoneName.ID, new GetCurrentMilestoneName(logger)));两个工具在 package.json 的contributes.languageModelTools中声明均设置canBeReferencedInPrompt: true即语言模型可以在对话中自行决定调用它们工具名工具引用名功能输入参数getCurrentMilestonegetCurrentMilestone获取 VS Code 仓库当前里程碑名称如April 2024无getReleaseFeaturesgetReleaseFeatures获取当前用户在当前发布版本中负责的所有特性返回含 title、body、number、labels、comments 与关联 issue 的列表milestoneName字符串工具实现使用vscode/prompt-tsx以 TSX 组件方式渲染结果。以GetCurrentMilestoneNamegetCurrentMilestone.tsx为例其invoke方法调用queries.ts中的 GraphQL 查询获取里程碑名成功时返回{milestoneName: April 2024}的 JSON 结果失败时返回{error: No milestone specified}GetReleaseFeaturesgetReleaseIssues.tsx则基于milestoneName参数调用getReleaseFeatures(milestoneName)拉取 issue 列表。二者都会将查询结果写入输出通道的 debug 日志如getReleaseFeatures会记录每条 issue 的 URL便于排查。工具实现依赖 GitHub RESToctokit/rest与 GraphQLapollo-boost/apollo-link-context客户端查询逻辑集中在 .vscode/extensions/doc-assistant/src/tools/queries.ts 与 utils.ts 中。Release Notes 目录诊断除写作辅助外扩展还内建了 release notes 目录校验registerReleaseNoteTocDiagnosticsreleaseNoteTocDiagnostics.ts对匹配/release-notes\/v1_\d\.md$/i的 Markdown 文件调用构建脚本build/release-note-toc中导出的validateReleaseNoteToc验证目录结构将问题以source: Release note ToC的错误诊断展示在对应行号位置。这保证了每期 release notes 的目录与章节编号一致、无遗漏或重复。本地开发与调试README 提供了标准的 VS Code 扩展开发流程在扩展文件夹内执行在 VS Code 中以文件夹方式打开.vscode/extensions/doc-assistant运行npm install安装依赖按F5编译扩展并启动 Extension Development Host即可在开发宿主中调试写作辅助功能。在扩展目录下可运行以下检查命令npm run compile # webpack 打包ts-loader 编译 src npm run lint # eslint 静态检查 src 下的 ts/tsx 文件带缓存 npm test # vscode-test 集成测试相关 npm 脚本定义在 package.json 的scripts字段compile为webpackpackage为生产模式打包--mode production --devtool hidden-source-mappretest先编译测试再编译扩展test通过vscode-test启动测试宿主。构建配置见 webpack.config.js 与 tsconfig.json、tsconfig.test.json。单元/集成测试位于 .vscode/extensions/doc-assistant/src/test/markdown.test.ts覆盖引用解析、变量解析、候选排序等核心逻辑测试类型依赖vscode/test-cli、vscode/test-electron与types/mocha。仓库内build/feature-lifecycle.json与data/variables下的.yml文件即为扩展运行时的真实数据源可直接在开发宿主中体验补全与诊断效果。设计要点与可复用启示从源码可以提炼出这套文档写作辅助设计的三条核心原则对其他文档仓库同样有借鉴价值文档即数据将特性生命周期、产品名等易变信息集中为注册表文件JSON/YAML编辑器能力补全、悬停、诊断全部数据驱动新增特性或产品只需改数据文件无需改扩展代码严格的数据契约注册表加载阶段即做强校验ID 正则、状态枚举、URL 协议、重复键检测把错误暴露在加载期而非写作期配合输出通道日志与registry-error诊断让数据问题第一时间可见贴近编辑体验补全只在工作区文件夹内生效、诊断只面向已发布目录、代码围栏内容一律跳过配合 Levenshtein 拼写纠错与一键补闭合符把辅助能力精准嵌入真实写作流程同时借助文件监听实现注册表热更新无需重启扩展。此外getCurrentMilestone与getReleaseFeatures展示了 VS Code 1.95 Language Model Tools API 的典型用法在package.json中声明工具契约名称、描述、输入 Schema、canBeReferencedInPrompt在扩展激活时用vscode.lm.registerTool注册实现工具内部用vscode/prompt-tsx渲染结构化结果最终让 Copilot Chat 能自主调用外部数据源完成 release notes 撰写——这是文档工程与 AI Agent 结合的一个具体落地案例。赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐VS Code终极Markdown扩展提升写作效率的完整指南 VS Code终极Markdown扩展提升写作效率的完整指南想要在VS Code中高效写作Markdown文档吗VS Code Markdown AVS Code写作助手Grammarly插件完整使用手册VS Code写作助手Grammarly插件完整使用手册 Grammarly for VS Code是专为开发者设计的智能语法检查工具将专业的写作辅助功能无OpenCode VS Code扩展AI编程助手的完整实战指南OpenCode VS Code扩展AI编程助手的完整实战指南 OpenCode VS Code扩展作为新一代AI编程助手工具通过深度集成智能终端能力为开人工智能AI 应用AI Agent代码智能体CLI开发者工具上一篇IDM激活脚本终极指南永久免费解锁下载加速神器下一篇dxwrapper终极指南5步解决Windows老游戏兼容性问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

VS Code 文档仓库专用 Markdown 写作助手：doc-assistant 扩展的完整实现解析

相关推荐

Wand-Enhancer：新手 3 分钟本地解锁 Wand 专业版全部功能的手把手指南

openclaw从零部署：安装、大模型接入与常见问题排查

TikTokDownloader 完整教程：3 步采集 TikTok 账号全量作品链接（实战）

更多资讯

基于编辑距离的VB文本相似行比对工具实现

LM358运放打造纯硬件呼吸灯：从原理到调试的完整指南

LM358呼吸灯电路从入门到精通：三角波振荡器原理与调试指南

教育站群文件上传下载：分布式存储与负载均衡实战

Git实战：理解工作流，搞定提交、分支合并与SSH认证排坑

TensorFlow+CNN预测股票：从K线特征到滚动回测实战

今日更新

基于sEMG与IMU的手语手势识别：从数据采集到实时部署避坑指南

装配车间MES落地指南：SimpleMES工单流转、BOM与齐套检查实战

AI获客怎样减少重复线索？意客AI的原文复用与版本筛选

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？