panli ef3df73166 refactor: 三层架构重构 + 配置文件 + 项目目录整理

清洗管线重构为严格三层架构：
- 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）

2026-08-19 19:40:02 +08:00

5.0 KiB

Raw Blame History

Markdown Linting 完成总结

✅ 所有警告已修复

验证结果：0 个 markdownlint 错误

🔧 建立的自动化机制

1. 配置文件 `.markdownlint.json`

项目根目录的配置文件，VSCode markdownlint 扩展和 CLI 工具共享：

{
  "$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 文件：

@echo off
REM 使用方法：
REM   scripts\mdlint.cmd          检查所有 md 文件
REM   scripts\mdlint.cmd --fix    自动修复机械问题
W:
cd \python\japanese
npx -y markdownlint-cli %* "**/*.md"

使用示例：

# 检查所有 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 检查：

# .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 中添加：

#!/bin/sh
npx markdownlint-cli "**/*.md" || {
  echo "Markdown lint failed. Run 'scripts/mdlint.cmd --fix' to auto-fix."
  exit 1
}

VSCode 设置

团队成员安装扩展后，项目的 .markdownlint.json 会自动生效，无需额外配置。

📖 参考资源

✨ 完成状态

✅ 所有 markdown 文件（14 个）无警告
✅ 配置文件已建立（.markdownlint.json）
✅ 检查脚本已建立（scripts/mdlint.cmd）
✅ 规则文档已记录（本文件）

项目现在有了可重复、可维护的 markdown 质量保证机制。

5.0 KiB Raw Blame History Unescape Escape