wandering1
511fd30cc6
用户裁定：文档只写现状，历史流水一律删掉，过程查 git log。 - 43 篇「变更记录 / 修订记录」整节删除：继电保护规划 12.6 KB、产品 需求 11.8 KB、项目部署环境 5.5 KB、BSD Socket 指南 5.3 KB、架构 总览 5.0 KB、实机测试实施指南 3.8 KB 等 - 23 篇别处仍有指向：只留节名 + 一行「本文件不再记流水账，过程查 git log」，节号与锚点不位移（doc-links 不因此断链） - 5 篇整表保留（被当唯一证据 / 活台账引用）：看门狗设计说明、配置 文件设计说明、RAM预算台账、内容页架构、本地工具路径环境变量方案 - 规范同步：文档规范 §5.1 改新裁定；测试文档模板规范删示例节与 登记句；测试开发标准流程 / UI 两篇 / 实机测试实施指南 / 四篇单测 说明 / 并行任务工作树方案 / 编号规范 的「登记变更记录」改「写进 正文」 - 技能同步：stale-doc-count-sweep / ui-verify / id-family 三个 SKILL 正文不再要求追加流水行（顺带消掉 SKILL.md:121「产品需求 §12」 失效引用） - 修 5 处悬空指针：采样有效性校验目录锚点、BSD 指南「文末变更 记录」、docs/README 过期描述、网络自愈架构两处指向面 72 篇文档净减 600 余行；check_doc_links --all --sections-strict 可判 定比例 61% → 78%、失效引用 0；静态门禁 passed=50 failed=0；gitlint 10 条历史提交信息 0 failed。 未提交他人在飞改动：.dsh/skills/keil-build/*（%SystemDrive% 守卫）。
2.7 KiB
2.7 KiB
check-yaml — YAML 必须能被解析
一句话：只保证 YAML 语法能解析。它不校验 schema，也就挡不住"键名写错导致配置静默失效"。
- 配置：官方
pre-commit-hooksv5.0.0，无额外参数。触发面 = YAML 文件：
1. 它在查什么
- 语法可解析性：缩进一致性、制表符、锚点/别名引用是否存在、重复键等解析层错误。
2. 为什么要它
.pre-commit-config.yaml一旦语法坏掉，整套门禁直接不跑：仓库看起来一切正常，其实 39 个检查全部关着。CI 工作流文件同理（远端不动作、本地也不报错）。- 这是所有静默失效里最坏的一种，值得一条零成本门禁。
3. 触发面 / 看不见什么
- 只跑改动过的 YAML；其它文件里内嵌的 YAML（Markdown 代码块、README 示例）不校验。
- 完全不校验"字段是否符合使用方的预期"。
4. 报错怎么读
check yaml...........................................(no files to check)Skipped
check yaml...............................................................Failed
.pre-commit-config.yaml:88:3: mapping values are not allowed here
Skipped只说明本次没改 YAML，不代表 YAML 是好的。
5. 好处
- 把"门禁整体失效"的概率压到最低；报错定位精确到行列。
6. 限制与盲区（请当正文读）
- 键名写错它不管。本仓有现成教训：pre-commit 4.x 已移除
always: true，实测对local钩子里的这个键只告警Unexpected key(s)然后忽略 —— 配置"看起来生效、其实没生效"， 而check-yaml全绿。所以规则变成：想让某个钩子总是跑，必须让files:覆盖到所有触发面 （已写进AGENTS.md提交门禁一节，并在本目录多篇文档里复述为"触发面"一节）。 - 不校验语义：
args少写一个参数、entry指向一个不存在或不可执行的命令，都不报 （那要等到钩子真正跑起来才炸）。 - 不校验 CI 表达式（
${{ ... }}内容原样当字符串）。 - 多文档 YAML、锚点深合并能过解析但可能与本意相反，它不看。
7. 豁免与基线
- 无基线、无豁免（改到 YAML 就跑）。
8. 改这个门禁本身 / 改配置的正确验证方式
- 改完
.pre-commit-config.yaml，验收不是"过了check-yaml"，而是实跑：& '.venv\Scripts\python.exe' -m pre_commit run --all-files，然后确认目标钩子出现在输出里 且状态是Passed而不是Skipped（Skipped=files:没覆盖到，等于没挂）。 - 新增
repo: local钩子时，language: system+ 相对路径入口是最容易写错的两处。