核心用法
solo-audit 是一款面向知识库（KB）的自动化质量巡检工具，通过多维度扫描定位文档系统的结构性缺陷。用户可通过可选参数指定聚焦领域（如 tags、frontmatter、links），或执行全面审计。工具基于预设的 YAML frontmatter 规范，验证 type、status、title、tags 等必填字段的完整性与合法性，同时枚举文档间的交叉引用关系，识别孤立文件。
显著优点
1. 多维度质量覆盖：整合 frontmatter 校验、链接存活检测、标签一致性分析、孤儿文件识别及机会文档质量评估，形成闭环诊断体系。
2. 智能标签治理：自动发现近似重复标签（如 "ai" vs "AI"）和单次使用标签，显著降低知识检索的噪音。
3. 机会文档专项审计：针对商业机会类文档（type: opportunity）设置额外质量关卡，包括 opportunity_score 缺失、evidence_sources 为零、长期滞留草稿状态等风险指标。
4. 结构化输出：生成标准化 Markdown 报告，含统计概览、问题明细、修复建议，便于团队协作与迭代追踪。
潜在局限
- 静态分析边界：依赖正则与文件系统遍历，无法解析动态生成的链接或运行时依赖。
- 链接检测 fallback：若未配置
scripts/check_links.py，退化为基于 Grep 的简单文件存在性校验，可能误报或漏报相对路径复杂场景。 - 语义理解缺失：标签相似度判断基于字符串匹配，无法理解同义词或领域特定缩写。
- 无修复自动化：仅生成诊断报告，需人工介入执行批量修正。
适合人群
- 技术文档工程师维护大型 markdown 知识库
- 产品经理治理机会线索库（opportunity database）
- 开源社区维护者确保贡献文档规范一致
- 研究团队管理方法论与实验记录的知识图谱
常规风险
| 风险类型 | 描述 | 缓解建议 |
|---------|------|---------|
| 误删风险 | 孤儿文件判定可能遗漏外部引用（如 URL 直链） | 人工复核删除操作 |
| 隐私泄露 | 审计报告可能暴露内部文件路径结构 | 限制报告分发范围 |
| 性能瓶颈 | 超大型仓库全量扫描可能耗时较长 | 分目录增量审计 |