ef3df73166
清洗管线重构为严格三层架构：
- tango_analyser.py（底层：单词分析）
- task_processor.py（中层：文件 I/O、桶管理）
- workflow.py（顶层：状态机、任务推进）
- 移除旧的 batch_processor.py
新增配置文件系统：
- config.py：TOML 配置，相对路径相对配置文件目录解析
- 查找优先级 --config > cwd > 项目根 > ~ > 默认值
- count=None 语义为处理到文件末尾
项目目录整理：
- 根脚本归档到 scripts/analysis 与 scripts/legacy
- 文档归档到 docs/{design,history,analysis}
- 临时报告移到 reports/（已 gitignore）
文档质量：
- 新增 .markdownlint.json 与 scripts/mdlint.cmd
- 修复全部 14 个 md 文件的 markdownlint 警告
测试：74 passed（8 cleaner + 31 workflow + 6 tango + 15 validator + 14 config）
198 lines
5.0 KiB
Markdown
198 lines
5.0 KiB
Markdown
# Markdown Linting 完成总结
|
||
|
||
## ✅ 所有警告已修复
|
||
|
||
**验证结果**：0 个 markdownlint 错误
|
||
|
||
---
|
||
|
||
## 🔧 建立的自动化机制
|
||
|
||
### 1. 配置文件 `.markdownlint.json`
|
||
|
||
项目根目录的配置文件，VSCode markdownlint 扩展和 CLI 工具共享：
|
||
|
||
```json
|
||
{
|
||
"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
|
||
"default": true,
|
||
"MD013": false,
|
||
"MD033": false,
|
||
"MD041": false,
|
||
"MD060": { "style": "compact" }
|
||
}
|
||
```
|
||
|
||
**规则说明**：
|
||
- `MD013: false` — 关闭行长度限制（中文排版需要更大灵活性）
|
||
- `MD033: false` — 允许 HTML 标签（某些文档需要）
|
||
- `MD041: false` — 不强制首行为 h1（README 可能有徽章等）
|
||
- `MD060: { "style": "compact" }` — 表格管道符只需左右各一个空格（解决 CJK 字符宽度对齐问题）
|
||
|
||
### 2. 检查脚本 `scripts/mdlint.cmd`
|
||
|
||
一键检查所有 markdown 文件：
|
||
|
||
```batch
|
||
@echo off
|
||
REM 使用方法：
|
||
REM scripts\mdlint.cmd 检查所有 md 文件
|
||
REM scripts\mdlint.cmd --fix 自动修复机械问题
|
||
W:
|
||
cd \python\japanese
|
||
npx -y markdownlint-cli %* "**/*.md"
|
||
```
|
||
|
||
**使用示例**：
|
||
|
||
```bash
|
||
# 检查所有 markdown 文件
|
||
scripts\mdlint.cmd
|
||
|
||
# 自动修复（空行、表格间距等）
|
||
scripts\mdlint.cmd --fix
|
||
|
||
# 输出 JSON 格式（便于集成）
|
||
scripts\mdlint.cmd --json -o report.json
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 修复统计
|
||
|
||
### 自动修复的问题（markdownlint-cli --fix）
|
||
|
||
- **MD022**（25+ 处）— 标题前后缺少空行
|
||
- **MD031**（15+ 处）— 代码块前后缺少空行
|
||
- **MD032**（30+ 处）— 列表前后缺少空行
|
||
- **MD058**（2 处）— 表格前后缺少空行
|
||
- **MD060**（50+ 处）— 表格列对齐（改为 compact 样式）
|
||
|
||
### 手动修复的问题
|
||
|
||
- **MD040**（19 处）— 代码块缺少语言标识
|
||
- 目录树/格式说明 → `text`
|
||
- 状态机图 → `text`
|
||
- 编号列表 → `text`
|
||
- **MD036**（5 处）— 加粗文本作为标题
|
||
- WORKFLOW.md 中的 `**3.1 ...**` → `#### 3.1 ...`
|
||
|
||
---
|
||
|
||
## 📝 修复的文件清单
|
||
|
||
### 根目录（2 个）
|
||
- ✅ `README.md`
|
||
- ✅ `README_cleaner.md`
|
||
|
||
### docs/（9 个）
|
||
- ✅ `docs/README.md`
|
||
- ✅ `docs/design/CONFIG_FILE_DESIGN.md`
|
||
- ✅ `docs/design/WORKFLOW.md`
|
||
- ✅ `docs/history/CLEANUP_SUMMARY.md`
|
||
- ✅ `docs/history/CONFIG_INTEGRATION_COMPLETE.md`
|
||
- ✅ `docs/history/CONFIG_SIMPLIFICATION.md`
|
||
- ✅ `docs/history/FINAL_CLEANUP_SUMMARY.md`
|
||
- ✅ `docs/history/MARKDOWN_LINTING_FIX.md`
|
||
- ✅ `docs/history/REFACTOR_SUMMARY.md`
|
||
- ✅ `docs/analysis/REVIEW_ANALYSIS.md`
|
||
|
||
### scripts/（2 个）
|
||
- ✅ `scripts/analysis/README.md`
|
||
- ✅ `scripts/legacy/README.md`
|
||
|
||
### tests/（1 个）
|
||
- ✅ `tests/data/rules.md`
|
||
|
||
**总计**：14 个文件全部修复 ✅
|
||
|
||
---
|
||
|
||
## 🎯 核心修复原则
|
||
|
||
### 1. 表格处理（MD060）
|
||
|
||
**问题**：CJK 字符在等宽字体中占 2 个字符宽度，但 markdownlint 按 1 个字符计算，导致 `aligned` 样式永远无法满足。
|
||
|
||
**解决方案**：
|
||
- 配置文件设置 `"MD060": { "style": "compact" }`
|
||
- `compact` 样式只要求管道符左右各一个空格：`| 列 | 列 |`
|
||
- 自动修复工具能正确处理 CJK 表格
|
||
|
||
### 2. 代码块语言（MD040）
|
||
|
||
**原则**：根据内容选择合适的语言标识
|
||
- `bash` — Shell 命令
|
||
- `python` — Python 代码
|
||
- `toml` — TOML 配置
|
||
- `text` — 纯文本/目录树/格式说明/编号列表
|
||
|
||
### 3. 空行规范（MD022/MD031/MD032/MD058）
|
||
|
||
**原则**：所有块级元素（标题、列表、代码块、表格）前后都要空行
|
||
- 提高可读性
|
||
- 避免解析歧义
|
||
- 自动修复工具能正确处理
|
||
|
||
### 4. 标题语法（MD036）
|
||
|
||
**原则**：独立成行的加粗文本应该使用标题语法
|
||
- `**文本**` → `#### 文本`（根据层级选择）
|
||
- 保持文档大纲结构清晰
|
||
|
||
---
|
||
|
||
## 🔄 持续集成建议
|
||
|
||
### CI/CD 集成
|
||
|
||
在 CI 流程中添加 markdown 检查：
|
||
|
||
```yaml
|
||
# .github/workflows/lint.yml
|
||
name: Lint
|
||
on: [push, pull_request]
|
||
jobs:
|
||
markdown:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
- uses: actions/setup-node@v3
|
||
- run: npx markdownlint-cli "**/*.md"
|
||
```
|
||
|
||
### Pre-commit Hook
|
||
|
||
在 `.git/hooks/pre-commit` 中添加：
|
||
|
||
```bash
|
||
#!/bin/sh
|
||
npx markdownlint-cli "**/*.md" || {
|
||
echo "Markdown lint failed. Run 'scripts/mdlint.cmd --fix' to auto-fix."
|
||
exit 1
|
||
}
|
||
```
|
||
|
||
### VSCode 设置
|
||
|
||
团队成员安装扩展后，项目的 `.markdownlint.json` 会自动生效，无需额外配置。
|
||
|
||
---
|
||
|
||
## 📖 参考资源
|
||
|
||
- [markdownlint 规则文档](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
|
||
- [markdownlint-cli 文档](https://github.com/igorshubovych/markdownlint-cli)
|
||
- [配置文件 Schema](https://github.com/DavidAnson/markdownlint/blob/main/schema/markdownlint-config-schema.json)
|
||
|
||
---
|
||
|
||
## ✨ 完成状态
|
||
|
||
✅ **所有 markdown 文件（14 个）无警告**
|
||
✅ **配置文件已建立**（`.markdownlint.json`）
|
||
✅ **检查脚本已建立**（`scripts/mdlint.cmd`）
|
||
✅ **规则文档已记录**（本文件）
|
||
|
||
项目现在有了可重复、可维护的 markdown 质量保证机制。
|