技能介绍

解决的问题

技术文档在多人协作、长期迭代中常出现风格不一致、术语混乱与语法疏漏：同一份API文档可能同时存在「参数」与「参数值」的表述差异，英文示例时态前后不一，甚至代码块外的注释文本不符合团队风格指南。传统文本检查器无法识别Markdown、AsciiDoc等标记格式的结构化内容，容易将code block内的代码注释、inline code片段误判为散文错误，而人工校对耗时且依赖经验，难以覆盖多格式文档的一致性需求。

核心能力与工作流程

该技能基于Vale实现标记感知的散文检查，核心能力包括：

支持Markdown、AsciiDoc、reStructuredText、HTML四种技术文档常用格式，自动识别标记结构并排除非散文区域
内置规则集与自定义风格指南兼容，可检查风格合规性（如句子长度、被动语态使用）、语法正确性与术语一致性
输出结构化报告，标注问题位置、类型与修改建议

关键步骤：接收目标文档路径→按格式解析标记结构→过滤代码块、表格等非散文内容→逐句匹配风格规则→生成包含行号、规则名称与建议的报告→开发者根据报告手动修正或接入CI流程批量处理。

适用边界与注意点

规则集需匹配文档场景：默认规则可能不适用于特定技术栈（如后端API文档需补充接口术语规则，前端文档需适配组件命名规范），需按需配置.vale.ini或规则包
依赖文档语法规范性：若标记格式存在语法错误（如未闭合的```html标签），解析精度会下降，可能遗漏部分检查项
不处理内容逻辑：仅检查语言表达层面，无法发现参数描述与实际功能不符、接口调用示例错误等逻辑问题
多语言混合文档需对应语言规则：中英混合的技术文档需配置中文规则集，否则中文内容的检查准确性会降低