doclint-checker 0.1.2

文档规范检查工具

doclint-project/ ├── .github/ │ └── workflows/ │ └── doclint-pr.yml # [阶段 3] CI 流程配置 ├── src/ │ ├── init.py │ ├── main.py # [阶段 1] CLI 入口 │ ├── config.py # [阶段 2] 配置管理 │ ├── engine.py # [阶段 2] 检测引擎 │ ├── rules/ │ │ ├── base # [阶段 1] 规则基类 │ │ ├── static # [阶段 1] 规则匹配检测项 │ │ | └── punctuation.py # [阶段 1] 规则 1：成对标点 │ │ ├── llm # [阶段 1] LLM检测项 │ │ └── typo.py # [阶段 1] 规则 2：LLM 错别字 │ └── utils.py ├── tests/ │ └── test.md # [阶段 4] 测试文件 ├── .stylecheckrrc.yaml # [阶段 3] 配置文件 ├── requirements.txt └── README.md

PR 门禁集成 (CI/CD)

• 执行策略:

  • 增量检查: 只检查 PR 中 git diff 涉及的文件及受影响章节。
  • 异步执行: CI 任务启动后，立即返回 "Pending" 状态，检测完成后通过 Commit Status API 更新状态。

• 门禁规则:

  • Error 级别问题：阻断合并。
  • Warning 级别问题：仅评论提示，不阻断。

• 评论反馈:

  • 将 SARIF 结果解析为 PR Review Comment，直接标注在具体的代码行上。

• Docker 化: 提供 doclint:latest 镜像，内置 Node 环境和规则，方便 CI 直接拉取运行。

扩展新规则流程

1. 创建规则类 doclint/rules/basic/new_rule.py

class NewRule(BaseRule): rule_id = "new-rule" severity = "warning" def check(self, file_path, content): # 实现检查逻辑 pass

2. 注册到引擎 doclint/engine.py

RULE_REGISTRY = { "paired-punctuation": PairedPunctuationRule, "llm-chinese-typo": LLMTypoRule, "new-rule": NewRule # 新增 }

3. 配置启用 .stylecheckrrc.yaml

rules: new-rule: enable: true severity: "warning"

4. 运行检查

python doclint/main.py tests/test.md

在代码仓 PR 流程中实现非阻塞式的 doclint 集成

核心在于两点：

• CLI 工具行为：无论检测到多少错误，CLI 的退出码（Exit Code）必须始终为 0（成功）。
• CI 工作流设计：GitHub Action 的任务状态显示为“成功”（绿色），但通过脚本将检测结果解析为 PR 评论。 以下是基于之前架构（config.py, engine.py, main.py）的完整 CI 集成方案。

环节	阻塞式 (Blocking)	非阻塞式 (Non-Blocking)
CLI 退出码	有错误返回 1，无错误返回 0	始终返回 0 (无论有无错误)
CI 任务状态	有错误显示 ❌ (Failed)	始终显示 ✅ (Success)
合并权限	错误时禁止合并	允许合并，仅通过评论提示
反馈方式	状态检查 (Status Check)	PR 评论 (Comment)

在其他代码仓的 PR 流程中复用当前的 doclint CLI 工具并保持非阻塞调用

要在其他代码仓的 PR 流程中复用当前的 doclint CLI 工具并保持非阻塞调用，最佳实践是将工具发布为 PyPI 包，并在目标仓库的 CI 中通过 pip install 安装调用。 方案对比

方案	优点	缺点	适用场景
PyPI 包	标准分发，版本管理方便	需要维护 PyPI 发布流程	公开/私有包分发
GitHub Action	使用最简单，一行 uses	需要维护 Action 仓库	团队内部标准化
Submodule	代码可见，可定制	版本更新麻烦	紧密耦合的内部项目
复制脚本	最简单直接	难以同步更新	一次性使用

方案一：发布为 PyPI 包（推荐）

这是最标准的 Python 分发给方式，其他项目只需 pip install 即可使用。

1. 打包 doclint 工具

在项目根目录创建 pyproject.toml：

# pyproject.toml
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "doclint-checker"
version = "0.1.0"
description = "文档规范检查工具"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "Your Team", email = "[e-mail]"}
]
dependencies = [
    "pyyaml>=6.0",
    "openai>=1.0.0"  # 如果启用 LLM 规则
]

[project.scripts]
doclint = "doclint.main:main"

[tool.setuptools.packages.find]
where = ["."]
include = ["doclint*"]

实现其他代码仓灵活选择检测规则配置的方案

创建独立的配置包，其他仓库继承 其他仓库只需在根目录放置自己的 .stylecheckrrc.yaml

# 目标仓库/.stylecheckrrc.yaml
version: 1.0

# 继承共享配置
extends: "package:doclint-config-base/.stylecheckrrc.yaml"

# 本地覆盖
rules:
  llm-chinese-typo:
    enable: false  # 本地关闭 LLM

GitCode 上的代码仓完全可以复用同样的方法

GitCode 上的代码仓完全可以复用同样的方法，但需要根据 GitCode 的 CI/CD 平台特性做少量适配。核心逻辑（CLI 工具、配置系统、规则引擎）无需修改，只需调整 CI 工作流配置 和 评论 API 调用方式。 GitCode 支持多种 CI 配置方式，推荐使用 GitLab CI 兼容格式（.gitcode-ci.yml）。

• 1. 创建 CI 配置文件 在项目根目录创建 .gitcode-ci.yml
• 2. 编写GitCode MR 评论脚本 由于 GitCode 的 API 与 GitHub 不同，需要编写独立的评论脚本。 创建评论脚本 (.gitcode/post_comment.py)

适配项	GitHub	GitCode	工作量
CLI 工具	✅ 无需修改	✅ 无需修改	0
配置文件	✅ 无需修改	✅ 无需修改	0
CI 工作流	.github/workflows/*.yml	.gitcode-ci.yml	⭐⭐
评论脚本	GitHub API	GitCode API	⭐⭐
密钥管理	GitHub Secrets	GitCode 变量	⭐