⚡

技术文档质量检查工具Skill tech-writing-lint

技术文档质量检查工具是一款自动化文档风格与质量检查系统，专为技术写作团队设计。该工具集成了Vale、Alex.js、write-good等多款专业检查工具，能够自动检查文档的语法风格、术语一致性、包容性语言和可读性指标。支持谷歌、微软等主流风格指南，可自定义检查规则和术语词汇表，帮助团队统一文档标准，提升技术文档的专业性和可读性。关键词：技术文档检查、文档质量、风格指南、术语管理、可读性分析、包容性语言、自动化检查、Vale、Alex.js、write-good。

DevOps 0 次安装 0 次浏览 更新于 2/26/2026

name: tech-writing-lint description: 自动化技术文档风格与质量检查。使用Vale检查文档风格，检查包容性语言，强制执行风格指南，并分析可读性指标。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-007 metadata: author: babysitter-sdk version: “1.0.0”

技术文档检查技能

自动化技术文档风格与质量检查。

功能

  • 使用自定义风格规则进行Vale检查
  • 提供write-good建议以提高清晰度
  • 使用Alex.js检查包容性语言
  • 使用Proselint检查风格违规
  • 可读性评分（Flesch-Kincaid, Gunning Fog）
  • 术语一致性检查
  • 微软/谷歌风格指南合规性检查
  • 自定义词汇/术语管理

使用方法

在以下情况调用此技能：

  • 强制执行写作风格标准
  • 检查文档质量
  • 验证术语一致性
  • 分析内容可读性
  • 确保使用包容性语言

输入参数

参数 类型 是否必需 描述
inputPath string 是 文档文件或目录的路径
action string 是 检查类型：lint, readability, terminology, inclusive
styleGuide string 否 应用的风格指南（google, microsoft, custom）
configPath string 否 Vale或自定义配置的路径
glossaryPath string 否 术语词汇表的路径
minReadability number 否 最低可读性分数（0-100）

输入示例

{
  "inputPath": "./docs",
  "action": "lint",
  "styleGuide": "google",
  "configPath": ".vale.ini",
  "minReadability": 60
}

输出结构

检查输出

{
  "files": 25,
  "errors": 8,
  "warnings": 34,
  "suggestions": 56,
  "issues": [
    {
      "file": "docs/api/authentication.md",
      "line": 42,
      "column": 15,
      "rule": "Google.Passive",
      "message": "通常，使用主动语态而不是被动语态。",
      "severity": "warning",
      "context": "令牌由服务器验证。"
    }
  ],
  "readabilityScores": {
    "fleschKincaid": 62.5,
    "gunningFog": 10.2,
    "avgSentenceLength": 18.3,
    "avgWordLength": 5.1
  }
}

术语报告

{
  "inconsistencies": [
    {
      "term": "backend",
      "variants": ["back-end", "back end", "Backend"],
      "preferred": "backend",
      "occurrences": [
        { "file": "docs/arch.md", "line": 15, "found": "back-end" },
        { "file": "docs/guide.md", "line": 42, "found": "Backend" }
      ]
    }
  ],
  "undefined": [
    {
      "term": "microservice",
      "occurrences": 12,
      "suggestion": "添加到词汇表并定义"
    }
  ]
}

Vale配置

.vale.ini

StylesPath = .vale/styles

MinAlertLevel = suggestion

Packages = Google, Microsoft, write-good, alex

[*.md]
BasedOnStyles = Vale, Google, write-good

# 自定义规则
Google.Passive = warning
Google.We = suggestion
Google.Will = warning
Google.Wordiness = warning

write-good.Passive = warning
write-good.Weasel = warning
write-good.TooWordy = suggestion

# 禁用特定规则
Vale.Spelling = NO

[*.mdx]
BasedOnStyles = Vale, Google

[CHANGELOG.md]
BasedOnStyles = Vale

自定义Vale规则

# .vale/styles/Custom/Terminology.yml
extends: substitution
message: "使用'%s'而不是'%s'。"
level: error
ignorecase: true
swap:
  back-end: backend
  front-end: frontend
  e-mail: email
  log-in: login
  set-up: setup
  on-premise: on-premises
  blacklist: blocklist
  whitelist: allowlist
  master: main
  slave: replica

风格指南规则

# .vale/styles/Custom/ActiveVoice.yml
extends: existence
message: "避免被动语态：'%s'"
level: warning
tokens:
  - 'is being'
  - 'was being'
  - 'has been'
  - 'have been'
  - 'had been'
  - 'will be'
  - 'is done'
  - 'was done'
  - 'are done'
  - 'were done'

Alex.js集成

alex配置

{
  "allow": [
    "execute"
  ],
  "profanitySureness": 2,
  "noBinary": true
}

包容性语言检查

<!-- 之前 -->
用户自己必须配置白名单。
点击主开关以启用。

<!-- 之后 -->
用户必须配置允许列表。
点击主开关以启用。

可读性分析

指标解释

指标 范围 解释
Flesch-Kincaid 0-100 分数越高越容易（文档理想值为60-70）
Gunning Fog 0-20 分数越低越容易（理想值为8-12）
SMOG指数 0-20 所需教育年限
Coleman-Liau 0-20 年级水平

可读性报告

{
  "file": "docs/quickstart.md",
  "metrics": {
    "fleschKincaid": 65.2,
    "gunningFog": 9.8,
    "smog": 10.1,
    "colemanLiau": 11.2,
    "automatedReadability": 10.5
  },
  "statistics": {
    "sentences": 45,
    "words": 823,
    "syllables": 1247,
    "complexWords": 89,
    "avgSentenceLength": 18.3,
    "avgWordLength": 4.8
  },
  "suggestions": [
    "拆分长句（3个句子超过30个单词）",
    "简化复杂词汇：'implementation' -> 'setup'",
    "减少第3-5段中的术语密度"
  ]
}

术语词汇表

glossary.yml

terms:
  - term: API
    definition: 应用程序编程接口
    usage: 始终使用大写API，而不是Api或api

  - term: backend
    definition: 服务器端应用程序代码
    usage: 一个单词，小写（不是back-end或back end）

  - term: SDK
    definition: 软件开发工具包
    usage: 始终使用大写SDK
    expansion_first_use: true

  - term: OAuth
    definition: 开放授权标准
    usage: 大写O，小写auth

prohibited:
  - term: simple
    reason: 主观；对一个人简单可能对另一个人不简单

  - term: easy
    reason: 主观；使用具体指导而不是模糊描述

  - term: just
    reason: 最小化；暗示任务微不足道

  - term: obviously
    reason: 可能让读者感到不足

工作流程

  1. 加载配置 - 解析Vale和自定义配置
  2. 扫描文件 - 查找所有文档文件
  3. 运行检查工具 - 应用Vale, alex, write-good
  4. 分析可读性 - 计算指标
  5. 检查术语 - 根据词汇表验证
  6. 生成报告 - 输出发现和建议

依赖项

{
  "devDependencies": {
    "vale": "^3.0.0",
    "alex": "^11.0.0",
    "write-good": "^1.0.0",
    "textstat": "^0.7.0",
    "proselint": "^0.13.0"
  }
}

CLI命令

# 安装Vale包
vale sync

# 检查文档
vale docs/

# 检查包容性语言
npx alex docs/

# write-good分析
npx write-good docs/**/*.md

# 生成可读性报告
node scripts/readability.js docs/

风格指南比较

规则 Google Microsoft Vale默认
被动语态 警告 警告 建议
将来时 警告 关闭 关闭
第一人称 建议 关闭 关闭
缩略词 允许 不鼓励 关闭
牛津逗号 必需 必需 关闭

应用的最佳实践

  • 使用主动语态
  • 保持句子在25个单词以内
  • 每个段落一个主要思想
  • 首次使用缩写时定义
  • 使用一致的术语
  • 尽可能避免术语
  • 为全球受众写作

参考资料

目标流程

  • style-guide-enforcement.js
  • docs-testing.js
  • docs-audit.js
  • terminology-management.js