文档: 重写 README 的"无人值守"章节 + 防止文档漂移的测试
一、README 的"无人值守"章节已经过时: 写着"每 5 分钟的会话看门狗 + 每天 05:30 一轮", 而实际早改成了 1 分钟 + 每 N 小时一轮, 还多了一套独立的挂机攒模块任务。 重写成两套自动化分开说(打关卡的刷取循环 / 只攒模块不发车), 并链上 docs/WATCH.md —— 否则那份手册写了也没人找得到。 引用的脚本和参数都逐项核对过存在: install_unattended.ps1(-EveryHours)、 install_convert_task.ps1(-EveryHours/-Uninstall)、convert_modules.py、 modules_status.py、docs/WATCH.md。 二、新增 tests/test_doc_refs.py: 机械检查文档里形如 scripts/xxx、docs/xxx.md 的 引用是否真实存在, 并确认 README 指向 WATCH.md、手册里提到四个计划任务名。 这条测试也验证过能失败: 把 README 里的 convert_modules.py 改成不存在的名字, 它准确报出 "README.md -> scripts/convert_modules_RENAMED.py"。 第一版把 ~/lc_mcp/modules/convert.log 这类**运行期产物**也算进去了(在用户主目录 下, 本来就不该在仓库里), 造成误报 —— 已收紧到只认 scripts/ 与 docs/。 文档漂移是最难发现的一类问题: README 说"跑 install_xxx.ps1"而脚本早改名了, 读到的人直接卡住, 而代码测试全绿。 全套 289/289 通过。
This commit is contained in:
@@ -0,0 +1,54 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""文档里引用的脚本/文件必须真实存在。
|
||||
|
||||
文档漂移是最难发现的一类问题: README 说"跑 install_xxx.ps1",而那个脚本早改名了 ——
|
||||
读到的人会直接卡住, 而代码测试全绿。这个仓库的 README 就曾经写着
|
||||
"每 5 分钟的会话看门狗 + 每天 05:30 一轮", 而实际早改成了 1 分钟 + 每 N 小时一轮。
|
||||
|
||||
这里只做机械检查: 文档中形如 scripts/xxx 或 docs/xxx.md 的路径必须存在。
|
||||
判断"描述是否过时"做不到, 但"引用的东西还在不在"是能查的。
|
||||
"""
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
DOCS = ['README.md', 'docs/WATCH.md']
|
||||
# 只认仓库内的 scripts/ 与 docs/ 路径。
|
||||
# 不要收 lc_mcp/ —— 文档里的 ~/lc_mcp/modules/convert.log 之类是**运行期产物**,
|
||||
# 在用户主目录下, 本来就不该出现在仓库里(第一版这么写导致误报)。
|
||||
PATH_RE = re.compile(r'\b((?:scripts|docs)/[A-Za-z0-9_./-]+\.\w+)\b')
|
||||
|
||||
|
||||
class DocReferenceTest(unittest.TestCase):
|
||||
|
||||
def refs(self, path):
|
||||
text = (ROOT / path).read_text(encoding='utf-8')
|
||||
return sorted(set(PATH_RE.findall(text)))
|
||||
|
||||
def test_docs_exist(self):
|
||||
for d in DOCS:
|
||||
self.assertTrue((ROOT / d).exists(), '%s 不见了' % d)
|
||||
|
||||
def test_referenced_files_exist(self):
|
||||
missing = []
|
||||
for d in DOCS:
|
||||
for ref in self.refs(d):
|
||||
if not (ROOT / ref).exists():
|
||||
missing.append('%s -> %s' % (d, ref))
|
||||
self.assertFalse(missing,
|
||||
'文档引用了不存在的文件:\n ' + '\n '.join(missing))
|
||||
|
||||
def test_readme_points_at_the_watch_guide(self):
|
||||
"""值守手册必须能从入口找到, 否则写了等于没写。"""
|
||||
text = (ROOT / 'README.md').read_text(encoding='utf-8')
|
||||
self.assertIn('docs/WATCH.md', text)
|
||||
|
||||
def test_watch_guide_mentions_both_tasks(self):
|
||||
text = (ROOT / 'docs/WATCH.md').read_text(encoding='utf-8')
|
||||
for name in ('LcMCPConvertModules', 'LcKeepDisplay', 'LcMCPServer', 'LcMCPDailyCycle'):
|
||||
self.assertIn(name, text, '值守手册没提到 %s' % name)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user