vibe-coding-cn/DEBUG.md

Debug Record

Bug

• 标题：minimal README 重构后的文档一致性调试
• 症状：用户要求开始 debug，但未提供具体报错或失败现象；需要确认最近一次 README.md 预备知识扩展是否引入可复现问题。
• 首次发现位置 / 时间：minimal 分支，2026-09-01；目标提交 21f6273。

Environment

• 仓库 / 模块：/home/lenovo/.projects/vibe-coding-cn-minimal / README.md 与 explain.md
• 运行环境：WSL Ubuntu；Git 分支 minimal
• 依赖 / 版本：markdownlint-cli@0.48.0，通过 npx --yes 临时运行
• 配置差异：当前极简分支没有 Makefile、测试脚本或 CI 文件，使用仓库主分支的 lint 配置进行文档检查。

Reproduction

1. 在 minimal 分支读取当前 README.md、explain.md 和最近提交。
2. 运行 npx --yes markdownlint-cli@0.48.0 --config /home/lenovo/.projects/vibe-coding-cn/.github/lint_config.json README.md。
3. 检查 README.md 的本地链接、折叠标签、手工锚点、禁用句式和 $$ 数学块配对。
4. 运行 git diff --check，确认当前工作树不存在空白错误。

Observations

• O1：最近提交为 21f6273 docs: enrich category theory preliminaries；执行调试前工作树干净，远端 origin/minimal 已同步。
• O2：Markdown lint 命令退出码为 0，没有输出诊断信息。
• O3：README.md 中的本地链接目标 explain.md 存在；当前文档只发现该本地文档链接和一个完整仓库外部链接。
• O4：没有发现 <details>、<summary>、手工 <a id>、点击展开/收起 或“不是……而是……”结构；$$ 行共 22 个，数量为偶数。
• O5：git diff --check 退出码为 0，当前变更没有空白错误。

Hypotheses

H1: README 的近期扩展应先通过静态结构层的确定性验证（ROOT HYPOTHESIS）

• Supports：本次变更新增了较长的类比段落、代码块和数学块，结构风险集中在新增区域。
• Conflicts：当前没有具体渲染或 CI 报错，缺陷尚未被观察到。
• Test：运行固定版本 Markdown lint、git diff --check，并统计 $$ 分隔符数量，确认结构是否完整。

H2：README.md 到 explain.md 的本地跳转失效

• Supports：最近把 explain.md 的详细内容纳入预备知识，同时保留了附录链接。
• Conflicts：工作树中存在 explain.md，README 链接目标为同级路径。
• Test：解析 README 链接并检查本地目标文件存在。

H3：此前清理过的折叠标签、手工锚点或禁用句式重新进入 README

• Supports：当前分支历史上曾使用过这些结构，新增内容可能带回旧模式。
• Conflicts：本次新增内容按纯 Markdown 线性结构编写。
• Test：扫描 <details>、<summary>、<a id>、折叠提示和“不是……而是……”模式。

Experiments

E1

• Hypothesis: H1
• Change: 无；仅运行固定版本 lint、空白检查和数学分隔符统计。
• Expected: 若结构有效，所有检查退出码为 0，数学分隔符数量为偶数。
• Result: Markdown lint 退出码 0；git diff --check 退出码 0；$$ 数量为 22。
• Verdict: confirmed
• Revert: 无需回滚；实验未修改仓库文件。

E2

• Hypothesis: H2
• Change: 无；检查 explain.md 是否存在并列出 README 中的 Markdown 链接。
• Expected: explain.md 存在，README 的本地链接目标可解析。
• Result: 输出 local-link: explain.md exists；链接目标为 explain.md，检查退出码 0。
• Verdict: rejected
• Revert: 无需回滚；实验未修改仓库文件。

E3

• Hypothesis: H3
• Change: 无；扫描折叠标签、手工锚点、折叠提示和禁用句式。
• Expected: 扫描无匹配结果。
• Result: 所有扫描均无输出。
• Verdict: rejected
• Revert: 无需回滚；实验未修改仓库文件。

Root Cause

• 当前没有确认的产品或文档缺陷。调试请求未提供具体失败样本，现有可复现实验也没有失败；最近一次 README 扩展在已执行的静态门禁范围内保持通过。

Fix

• 没有生产修复。保留本调试记录作为本轮审计证据；若后续出现具体 GitHub 渲染、链接或 CI 报错，应以该报错建立新的 RED 实验，不沿用本次“未发现失败”的结论。

Regression Evidence

• 回归证据契约：Optional
• 契约文件：本轮未创建；没有确认的 bugfix 或 regression test。
• 测试：固定版本 Markdown lint、git diff --check、本地链接存在性、禁用结构扫描、数学分隔符配对。
• 结果：全部退出码为 0；没有新增生产修复需要回归证明。
• 备注：当前结论限定在 WSL 本地静态检查；GitHub 网页端实际渲染未在本轮复现。

Failed Nodes

• 无。

First Invalid Node

• 无；未发现失败节点。

Upstream Lineage

• 用户的 debug 请求 → 目标提交 21f6273 → README 结构与链接检查。

Downstream Blast Radius

• 无；本轮实验未修改 README 或 explain 内容。

Lowest Common Refinement Ancestor

• README.md 文档一致性静态检查。

Repair Boundary

• 无需修复；如出现新报错，仅修改导致该报错的最小文档范围。

Frozen Nodes

• README.md、explain.md 当前内容；本轮实验只读。

Invalidated Nodes

• 无。

Reverification Required

• 若后续修改 README、explain 或收到 GitHub/CI 具体错误，必须重新运行 lint、链接检查和对应的最小复现；本轮结论不能覆盖后续变更。

Follow-up Validation: README 深度优化

• 基线：c92eaed chore: record minimal README debug audit。
• 变更范围：仅 README.md；补充工程态射契约、形式边界、T_H / V_\Gamma 记号和生成域术语边界，清除公式中的零宽字符。
• 静态结果：固定版本 markdownlint-cli@0.48.0 检查 README.md、explain.md、DEBUG.md 通过。
• 结构结果：git diff --check 通过；代码围栏 28 个且配对；数学块分隔符 22 个且配对。
• 约束结果：未发现折叠标签、手工锚点或禁用的“不是……而是……”句式。
• 链接结果：README.md 的本地入口 explain.md 存在。
• 结论：当前深度优化没有引入可复现的文档结构缺陷；GitHub 网页端渲染仍属于本轮未直接复现的外部环境项。

Follow-up Validation: 工程范畴边界优化

• 基线：f5906e4 docs: formalize engineering category model。
• 变更范围：仅 README.md；修正“六个核心词”的数量口径，补充工程范畴记号 $\mathcal{E}_{H,\Gamma}$、生成/执行/契约满足三层表，以及独立验证的可执行判据。
• 静态结果：固定版本 markdownlint-cli@0.48.0 检查 README.md、explain.md、DEBUG.md 通过。
• 结构结果：git diff --check 通过；代码围栏 28 个且配对；数学块 28 个且配对。
• 约束结果：零宽字符、折叠标签、手工锚点和禁用的“不是……而是……”句式均无匹配。
• 链接结果：README.md 的本地入口 explain.md 存在。
• 结论：本轮边界优化未引入可复现的文档结构或链接缺陷；当前剩余未知项仍是 GitHub 网页端实际数学渲染效果。

Follow-up Validation: 验证语义严谨化

• 基线：864c8d8 docs: tighten category model semantics。
• 变更范围：仅 README.md；补充来源独立性谓词 \mathsf{Ind} 与验证标记定义，限定部分映射的复合成功域，区分契约满足关系与工程层级，并同步文章结构说明、结论路径和记号表。
• 静态结果：固定版本 markdownlint-cli@0.48.0 检查 README.md、explain.md、DEBUG.md 通过。
• 结构结果：git diff --check 通过；代码围栏 28 个且配对；数学块分隔符 30 个且配对。
• 约束结果：未发现折叠标签、手工锚点、禁用的“不是……而是……”句式或零宽字符。
• 链接结果：README.md 的本地入口 explain.md 存在。
• 结论：验证独立性、偏映射适用域和章节口径已获得文档内明确表达；剩余未知项仍是 GitHub 网页端实际数学渲染效果。

Follow-up Validation: 对偶与契约层次优化

• 基线：46abd06 docs: formalize verification semantics。
• 变更范围：仅 README.md；补充对偶范畴的对象/同态集合定义，明确对偶不推出逆态射，区分任务级契约 \Gamma 与单步契约 $\Gamma_f$。
• 静态结果：固定版本 markdownlint-cli@0.48.0 检查 README.md、explain.md、DEBUG.md 通过。
• 结构结果：git diff --check 通过；代码围栏 28 个且配对；数学块分隔符 32 个且配对。
• 约束结果：未发现折叠标签、手工锚点、禁用的“不是……而是……”句式或零宽字符。
• 链接结果：README.md 的本地入口 explain.md 存在。
• 结论：对偶的形式含义、逆向工作的适用边界和任务/步骤契约层次已明确；剩余未知项仍是 GitHub 网页端实际数学渲染效果。

Follow-up Debug: GitHub 数学宏兼容性

• RED：GitHub 页面显示 The following macros are not allowed: operatorname，相关数学块降级为原始文本。
• 根因：README.md 的公式和行内公式使用了 GitHub 渲染器拒绝的 \operatorname 宏。
• 修复：将 Ob、Hom、Pre、Post、Fail、Verified、Ind 的运算符排版统一为 \mathrm{...}；未改变公式的数学关系。
• 验证：operatorname 匹配数为 0；32 个数学分隔符和 28 个代码围栏均成对；固定版本 Markdown lint、调试记录校验和差异检查通过。
• 回归：README.md 保留本地入口 explain.md，折叠标签、手工锚点和零宽字符扫描均无匹配。
• 结论：源码层已移除截图中触发 GitHub 降级的宏；待 GitHub 页面重新渲染后确认视觉结果。

Follow-up Debug: GitHub 行内公式分隔符

• RED：GitHub HTML 只将行内公式起始分隔符前有空格的内容转换为 math-renderer；紧跟中文标点的公式仍保留为原始文本。
• 根因：README.md 使用了中文逗号加美元符号、中文顿号加美元符号等无空格起始形式，触发 GitHub 行内数学解析边界。
• 修复：为所有行内公式起始分隔符补充前置空格，连续变量统一使用带空格的分隔形式。
• 验证：未发现中文字符或中文标点直接连接美元符号的位置；所有行内公式起始分隔符前均为空格；固定版本 Markdown lint、调试记录校验和差异检查通过。
• 结论：本地源码已满足 GitHub 行内数学解析的边界条件；推送后继续检查 GitHub 页面是否为每个公式生成 math-renderer。

Follow-up Debug: 复合下标行内公式

• RED：推送后的 GitHub HTML 仍有 2 个行内公式未生成 math-renderer，原文中的下标被解析成 HTML 强调标记。
• 根因：复合下标公式 \mathcal{E}_{H,\Gamma} 放在行内美元分隔符中，触发 Markdown 下划线解析冲突。
• 修复：将该记号移入独立数学块，保留 \mathcal{E}_{H,\Gamma} 的原始数学表达。
• 本地验证：数学分隔符 34 个且配对；行内公式 93 组；未发现不满足 GitHub 起始边界的行内公式；Markdown lint、调试记录校验和差异检查通过。
• 结论：当前待推送改动已消除已知的 2 个复杂行内公式解析冲突。

Follow-up Validation: 远端 GitHub HTML 烟测

• 基线：提交 af9f655。
• 结果：源码行内公式 93 组，GitHub 页面 math-renderer 节点 93 个，operatorname 错误字符串 0 个。
• 结论：已知宏、中文标点起始边界和复合下标冲突均已消除；GitHub HTML 已为每组行内公式生成渲染节点。