vibe-coding-cn/metadata/debug/standard-kb-migration-health.DEBUG.md

Debug Record

Bug

• 标题：标准知识库迁移后仓库健康度排查
• 症状：迁移后本地校验通过，但需要确认远端 CI、链接、子模块、旧路径和目录结构是否真实一致。
• 首次发现位置 / 时间：2026-05-02，迁移提交 628a3bc 与根目录降噪提交 5caada8 之后。

Environment

• 仓库 / 模块：tukuaiai/vibe-coding-cn
• 当前分支：develop
• 当前 HEAD：5caada8 chore: move ai citation pack under metadata
• GitHub 默认分支：develop
• 远端分支：develop、master；未发现 main。
• 关键配置：.github/workflows/ci.yml 当前监听 main。

Reproduction

1. 在 develop 执行本地仓库校验。
2. 查询 GitHub Actions 最近运行记录。
3. 查询仓库默认分支与远端分支。
4. 对照 .github/workflows/ci.yml 的触发条件。

Observations

• O1：make lint 通过。
• O2：本地 Markdown 相对链接检查通过，范围为排除 .history/、.github/wiki/、tools/external/、tools/chat-vault/、scripts/backups/gz/ 后的 263 个 Markdown 文件。
• O3：git diff --check 通过。
• O4：git submodule status --recursive 正常返回 .tmux、Skill_Seekers-development、claude-official-skills、tmux 及嵌套 configs_repo。
• O5：find . -xtype l -print 未发现断软链接。
• O6：旧路径扫描只命中 CHANGELOG.md 与 metadata/redirects.yml，属于迁移记录和重定向映射，不是活跃引用。
• O7：GitHub 默认分支是 develop。
• O8：远端存在 develop 与 master，没有 main。
• O9：.github/workflows/ci.yml 只监听 push.branches: [ main ] 和 pull_request.branches: [ main ]。
• O10：最近 develop 相关远端检查只有 Labeler，没有 CI。
• O11：历史 CI 最近记录来自 2026-02 的 main push，且 markdown-lint 失败；这不是当前 develop 迁移提交的验证结果。
• O12：修复 CI 触发分支后，develop 的 push / PR 均触发了 CI。
• O13：CI 的 link-checker 成功，markdown-lint 失败，失败原因是 Node.js 16 解析最新版 markdownlint-cli 依赖 string-width 中的正则 /v flag 报 SyntaxError: Invalid regular expression flags。

Hypotheses

H1: 迁移导致 Markdown 链接断裂

• Supports：大规模从 assets/documents/ 移动到 docs/，容易留下旧相对路径。
• Conflicts：本地链接检查通过；旧路径扫描没有发现活跃旧路径引用。
• Test：运行本地 Markdown 相对链接检查。
• Verdict：rejected。

H2: 迁移导致 submodule 或软链接断裂

• Supports：assets/repos/ 拆分到 tools/external/，同时 Skills 中存在跨目录软链接。
• Conflicts：git submodule status --recursive 正常；find . -xtype l -print 无输出。
• Test：运行 submodule 状态检查与断软链接扫描。
• Verdict：rejected。

H3: 远端 CI 没有覆盖当前默认分支

• Supports：GitHub 默认分支是 develop，远端没有 main，但 CI 只监听 main；最近 develop 只跑了 Labeler。
• Conflicts：无。
• Test：查询 gh repo view --json defaultBranchRef、git ls-remote --heads origin master main develop、gh run list --workflow CI、.github/workflows/ci.yml。
• Verdict：confirmed。

H4: CI Node 版本过旧导致 markdownlint 运行时崩溃

• Supports：CI 日志显示 Node 16 环境下 string-width/index.js 的 /v 正则 flag 语法错误；本地 Node 环境运行 make lint 通过。
• Conflicts：无。
• Test：修复 CI 触发后查看失败日志。
• Verdict：confirmed。

Experiments

E1

• Hypothesis：H1 迁移导致 Markdown 链接断裂。
• Change：无生产改动，只运行链接检查脚本。
• Expected：如存在断链，输出缺失目标。
• Result：OK local links checked: 263 files。
• Verdict：rejected。
• Revert：无需。

E2

• Hypothesis：H2 迁移导致 submodule 或软链接断裂。
• Change：无生产改动，只运行状态检查。
• Expected：如存在问题，git submodule status 出现异常或 find . -xtype l 输出断链。
• Result：submodule 正常；断软链接无输出。
• Verdict：rejected。
• Revert：无需。

E3

• Hypothesis：H3 远端 CI 没有覆盖当前默认分支。
• Change：无生产改动，只查询远端和 workflow。
• Expected：如果成立，默认分支与 CI 触发分支不一致。
• Result：默认分支为 develop，远端无 main，CI 只监听 main。
• Verdict：confirmed。
• Revert：无需。

E4

• Hypothesis：H4 CI Node 版本过旧导致 markdownlint 运行时崩溃。
• Change：查看 GitHub Actions 失败日志。
• Expected：如果成立，失败发生在工具启动阶段，而不是 Markdown 规则输出阶段。
• Result：markdown-lint job 在解析依赖时抛出 SyntaxError: Invalid regular expression flags；link-checker job 成功。
• Verdict：confirmed。
• Revert：无需。

Root Cause

• 当前迁移后的本地结构健康，但远端质量门禁存在两层问题：
  1. 仓库默认分支是 develop，仍保留 master，不存在 main，而 CI workflow 原先只监听 main，导致当前默认开发流不会触发 markdown-lint 和 link-checker。
  2. CI 使用 Node.js 16 安装最新版 markdownlint-cli，其依赖已使用 Node 16 不支持的正则 /v flag，导致 markdown-lint 在工具启动阶段崩溃。

Fix

• 已把 .github/workflows/ci.yml 触发分支改为当前真实分支策略：
  • push.branches: [ develop, master ]
  • pull_request.branches: [ develop, master ]
• 已同步更新 AGENTS.md 中 CI 触发规则，避免 Agent 继续相信 main 是主线。
• 已给 CI 增加 workflow_dispatch，方便手动验证迁移大改。
• 已把 CI Node.js 从 16 升级到 22，并同步 README / AGENTS 的 Node.js 环境要求。

Regression Evidence

• 本地测试：make lint 通过。
• 本地链接：263 个 Markdown 文件相对链接检查通过。
• Git 检查：git diff --check 通过。
• 子模块检查：git submodule status --recursive 正常。
• 远端检查：develop 最新提交只有 Labeler，没有 CI；CI 分支触发条件与默认分支不一致。
• 修复后本地复测：make lint、本地 Markdown 相对链接检查、git diff --check、断软链接检查、submodule 状态检查均通过。
• 修复后远端验证：93d0341 触发的 push CI 成功，PR CI 成功，Labeler 成功；markdown-lint 不再因 Node 16 崩溃。