文档链接巡检

零第三方依赖的 Python 命令行工具，用于发现文档中移动或删除文件后留下的失效相对链接。支持普通内联链接和图片链接，保留原始行号，提供 JSON 报告，适合本地文档验收和 CI。

功能与适用场景

查看检查规则与边界，了解具体统计口径及限制。所有工具离线运行，运行时仅使用 Python 标准库；审计不会修改输入文件。报告输出选项可能覆盖指定报告文件。

环境要求

Python 3.10 或更新版本，支持 Windows、Linux 和 macOS。当前验收环境为 Windows；其他平台兼容性尚未实际验证。

获取与安装

git clone https://www.gitlink.org.cn/ZHENAN/markdown-local-link-checker.git
cd markdown-local-link-checker
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS 激活命令为 source .venv/bin/activate。安装会用到 setuptools 构建依赖；不安装也可以直接运行下面的 Python 命令。

快速开始

python linkcheck.py examples/sample.md

安装后可使用 markdown-linkcheck --help；直接运行 python linkcheck.py --help 也可查看全部参数。示例文件保存在 examples。

输出和退出码

主要报告字段：files_checked、links_checked、missing_count、links、errors。

退出码：0：全部有效；1：缺失链接或读取失败；2：参数错误。发现问题或差异的示例返回非零状态属于正常业务结果，不等同于程序崩溃。详细语义及限制见行为说明。

项目结构

markdown-local-link-checker/
├── linkcheck.py        # 核心实现与 CLI 入口
├── tests/            # unittest 自动化测试
├── examples/         # 可直接运行的最小示例
├── docs/behavior.md  # 规则、报告及已知限制
├── pyproject.toml    # 安装元数据和命令入口
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── .gitignore
└── LICENSE

项目保持单模块结构，便于阅读和维护；测试、样例和说明分别存储。

开发与验证

python -B -m unittest discover -s tests -v

测试使用临时文件验证真实行为。重复文件项目的符号链接测试在 Windows 权限不足时跳过。贡献时请提供可复现输入和预期结果，详见贡献指南。

常见问题

如果 Windows 应用控制策略拦截安装生成的命令启动器，可使用 python -m linkcheck --help，或在仓库目录使用 python linkcheck.py --help。无需修改系统安全策略。安装时下载构建依赖失败，可先直接运行脚本，运行本身不需要第三方依赖。

数据与限制

报告可能包含输入原值或本地路径，公开分享前请检查敏感信息。工具采用内存报告，适合日常中小规模数据；大文件或大目录请评估资源开销。当前版本为 0.1.0，未承诺完整格式解析或业务规则判断。

许可证

采用 MIT 许可证。版本记录见 CHANGELOG.md。