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 = "team@example.com"}
]
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 变量 | ⭐ |

