Markdown 标签管理器（md-tag-plugin）

一个面向昇腾文档工程的 VSCode 扩展，为 Markdown 文档提供芯片标签管理、位置标签引用、保存校验与冗余定制点统计等能力。支持公仓 / 私仓 / 黄区分支多场景构建。

发布者：CANN-PUB
许可证：MIT
最低 VSCode 版本：1.85.0

功能特性

1. 芯片标签

通过 HTML 注释形式在 Markdown 中插入配对的芯片标签，用于标注某段内容适用的 NPU 产品型号：

<!-- npu="950,A3" id4 -->
被标注的内容
<!-- end id4 -->

一键插入 / 移除 / 编辑标签属性
自动生成唯一 id（id1、id2 …）
支持多 NPU 型号组合（逗号分隔）
标签前后跳转导航
悬停提示标签属性信息

2. 位置标签（源引用）

在公仓或黄区分支中，可将当前 Markdown 文件位置标记为源引用，并在私仓对应的 _res.md（cust）文件中维护翻译定制点。提供：

引用插入与跳转
引用装饰高亮（边框 / 下划线可选）
保存时自动同步引用
引用预览增强

3. 保存校验

保存 .md 文件时自动执行以下校验（仅提示，不阻断保存）：

规则	说明
规则 1	`npu` 属性值必须位于 `configs/npu_type.json` 可选范围内
规则 2	开始标签与结束标签必须配对，且开始标签在结束标签之前
规则 3	标签嵌套不得交叉（如 `id4 开 → id5 开 → id4 关 → id5 关` 报错）
规则 4	同一 id 在开始/结束标签中不得重复出现
规则 5	标签格式必须符合规范（空格位缺失等）

其中规则 1~5 对所有 .md 文件生效；@ref 引用校验与 npu 子集嵌套校验仅在 canInsertSourceReference() 仓内运行。

4. 冗余定制点统计

在资源管理器文件夹右键菜单中提供「冗余定制点统计」，扫描私仓 / 黄区分支下 Markdown 文件中的冗余注释对并输出统计结果。

命令与快捷键

命令	快捷键（Win/Linux）	快捷键（Mac）	说明
`mdTag.insertTag`	`Ctrl+Shift+T`	`Cmd+Shift+T`	插入芯片标签
`mdTag.removeTag`	`Ctrl+Shift+R`	`Cmd+Shift+R`	移除标签
`mdTag.editTagAttributes`	`Ctrl+Shift+E`	`Cmd+Shift+E`	编辑芯片标签属性
`mdTag.navigateToNextTag`	`Ctrl+Alt+N`	`Cmd+Alt+N`	跳转到下一个标签
`mdTag.navigateToPreviousTag`	`Ctrl+Alt+P`	`Cmd+Alt+P`	跳转到上一个标签
`mdTag.insertSourceReference`	`Ctrl+Shift+I`	`Cmd+Shift+I`	插入位置标签
`mdTag.manageSourceFolders`	—	—	管理源文件夹
`mdTag.statRedundantComments`	—	—	冗余定制点统计（资源管理器右键）

上下文菜单会根据光标位置、仓库类型动态显示可用项。

配置项

在 VSCode 设置中搜索 mdTag 进行配置：

配置项	类型	默认值	说明
`mdTag.commentIdPrefix`	string	`id`	注释 ID 前缀
`mdTag.enableTagNavigation`	boolean	`true`	启用标签导航
`mdTag.sourceFolders`	array	`[]`	源文件夹配置（含 id、displayName、path、filePattern、watchForChanges）
`mdTag.autoScanRepository`	boolean	`true`	自动扫描整个仓库的 Markdown 文件
`mdTag.scanIgnorePatterns`	array	`[]`	扫描时额外忽略的目录名（默认已忽略 `node_modules`、`.git` 等）
`mdTag.syncOnSave`	boolean	`true`	保存时自动同步引用
`mdTag.showReferencePreview`	boolean	`true`	显示引用预览
`mdTag.referenceDecorationStyle`	enum	`border`	引用装饰样式，可选 `border` / `underline`

仓库类型与构建

插件区分三种仓库场景，由 RepositoryManager 自动探测：

私仓（PRIVATE）：可使用注释对、冗余统计等完整能力
黄区分支（YELLOW_BRANCH）：可插入位置标签
公仓：可插入位置标签（位置标签功能仅在公仓与黄区分支中可用）

构建时通过 scripts/build.js 生成 out/build-config.json 控制构建类型，configs/npu_type.json 中的 NPU 型号白名单会随构建类型自适应（公仓构建仅包含 publicRepo 列表）。

开发与构建

环境准备

npm install

编译与调试

# 编译 TypeScript
npm run compile

# 监听模式
npm run watch

# 代码检查
npm run lint

# 单元测试
npm test

# VSCode 扩展测试
npm run test:vscode

在 VSCode 中按 F5 启动扩展调试宿主，可选择 Launch Private Hub / Launch Public Hub / Launch Yellow Branch Hub 配置进入对应场景。

打包 VSIX

# 公仓构建并打包
npm run package:public

# 私仓构建并打包
npm run package:private

产物为 md-tag-public.vsix 或 md-tag-private.vsix。

项目结构

md-tag/
├── configs/
│   └── npu_type.json          # NPU 型号白名单配置
├── docs/
│   └── superpowers/            # 设计文档与实现计划
│       ├── plans/
│       └── specs/
├── images/                     # 扩展图标
├── resources/icons/            # UI 图标资源
├── scripts/
│   └── build.js                # 公/私仓构建脚本
├── src/
│   ├── extension.ts            # 扩展入口与保存校验集成
│   ├── BuildConfig.ts          # 构建类型运行时读取
│   ├── managers/               # 仓库与编辑保护管理器
│   ├── models/                 # 数据模型与类型定义
│   ├── providers/              # 标签、注释、导航、引用等功能提供者
│   └── utils/                  # 解析器、校验器、装饰、配置等工具
├── .vscode/launch.json         # 调试配置
├── package.json                # 扩展清单
└── tsconfig.json

核心模块说明

模块	职责
`TagParser`	解析芯片标签 start/end 标记，提供 `parseTagMarkers` / `parseTagLikeComments`
`ChipTagValidator`	承载保存校验 5 条规则
`NpuNestingValidator`	npu 子集嵌套校验（子标签 npu ⊆ 祖先 npu 交集）
`ReferenceValidator`	`@ref` 位置引用合法性校验
`NpuTypeConfigManager`	NPU 型号白名单管理（按构建类型自适应）
`RepositoryManager`	仓库类型探测与场景判定
`SourceReferenceProvider`	位置标签插入 / 跳转 / 移除
`EditProtectionManager`	编辑保护机制
`RedundantCommentCleaner`	冗余定制点扫描与统计

Markdown标签管理器

CANN-PUB